4 @setfilename ../info/org
5 @settitle Org Mode Manual
12 * Org Mode: (org). Outline-based notes management and organizer
15 @c Version and Contact Info
16 @set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}
17 @set MAINTAINER Carsten Dominik
18 @set MAINTAINEREMAIL @email{dominik@@science.uva.nl}
19 @set MAINTAINERCONTACT @uref{mailto:dominik@@science.uva.nl,contact the maintainer}
25 @c Subheadings inside a table. Need a difference between info and the rest.
26 @macro tsubheading{text}
36 This manual is for Org-mode (version @value{VERSION}).
38 Copyright @copyright{} 2004, 2005 Free Software Foundation
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
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.''
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.
63 @vskip 0pt plus 1filll
67 @c Output the table of contents at the beginning.
71 @node Top, Introduction, (dir), (dir)
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 * Timeline and Agenda:: Use time-stamped items to produce an agenda
85 * Exporting:: Sharing and publishing of notes
86 * Miscellaneous:: All the rest which did not fit elsewhere
87 * Index:: The fast road to specific information
88 * Key Index:: Key bindings and where they are described
91 --- The Detailed Node Listing ---
95 * Summary:: Brief summary of what Org-mode does
96 * Installation and Activation:: How to install Org-mode
97 * Feedback:: Bug reportes, ideas, patches etc.
101 * Outlines:: Org-mode is based on outline-mode
102 * Headlines:: How to typeset org-tree headlines
103 * Visibility cycling:: Show ad hide, much simplified
104 * Motion:: Jumping to other headlines
105 * Structure editing:: Changing sequence and level of headlines
106 * Archiving:: Move done task trees to a different place
107 * Sparse trees:: Matches embedded in context
111 * Built-in table editor:: Simple tables
112 * table.el:: Complex tables
113 * orgtbl-mode:: The table editor as minor mode
117 * Links:: URL-like links to the world
118 * Remember:: Org-trees store quick notes
122 * TODO basics:: Marking and displaying TODO entries
123 * TODO extensions:: Workflow and assignments
124 * Priorities:: Some things are more important than others
126 Extended use of TODO keywords
128 * Workflow states:: From TODO to DONE in steps
129 * TODO types:: I do this, Fred the rest
130 * Per file keywords:: Different files, different requirements
134 * Time stamps:: Assigning a time to a tree entry
135 * Creating timestamps:: Commands which insert timestamps
139 * Timeline:: Time-sorted view for single file
140 * Agenda:: Your weekly planner
141 * Agenda commands:: Remote editing of org trees
142 * Calendar/Diary integration:: Integrating Anniversaries and more
144 Calendar/Diary integration
146 * Diary to agenda:: Agenda incorporates the diary
147 * Agenda to diary:: Diary incorporates the agenda
151 * Export commands:: Commands which export and display
152 * HTML formatting:: Interpretation of the buffer content
153 * Export options:: How to influence exports
154 * Comment lines:: Lines which will not be exported
158 * Completion:: M-TAB knows what you need
159 * Customization:: Adapting Org-mode to your taste
160 * FAQ:: Frequently asked questions
161 * Interaction:: Other Emacs packages
162 * Bugs:: Things which do not work perfectly
163 * Acknowledgments:: These people provided feedback and more
168 @node Introduction, Document Structure, Top, Top
169 @chapter Introduction
173 * Summary:: Brief summary of what Org-mode does
174 * Installation and Activation:: How to install Org-mode
175 * Feedback:: Bug reportes, ideas, patches etc.
178 @node Summary, Installation and Activation, Introduction, Introduction
182 Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
183 project planning with a fast and effective plain-text system.
185 Org-mode develops organizational tasks around NOTES files that contain
186 information about projects as plain text. Org-mode is implemented on
187 top of outline-mode, which makes it possible to keep the content of
188 large files well structured. Visibility cycling and structure editing
189 help to work with the tree. Tables are easily created with a built-in
190 table editor. Org-mode supports ToDo items, deadlines, time stamps,
191 and scheduling. It dynamically compiles entries into an agenda that
192 utilizes and smoothly integrates much of the Emacs calendar and diary.
193 Plain text URL-like links connect to websites, emails, usenet
194 messages, BBDB entries, and any files related to the projects. For
195 printing and sharing of notes, an Org-mode file can be exported as a
196 structured ASCII file, or as HTML.
198 Org-mode keeps simple things simple. Not every outline branch needs
199 to be an action item, not every action item needs to have priority or
200 scheduling information associated with it. Org-mode can be used on
201 different levels and in different ways, for example
204 @r{@bullet{} as an outline extension with visibility cycling and structure editing}
205 @r{@bullet{} as an ASCII system and table editor to take structured notes}
206 @r{@bullet{} as a simple hypertext system, with HTML export}
207 @r{@bullet{} as a TODO list editor}
208 @r{@bullet{} as a full agenda and planner with deadlines and work scheduling}
211 The Org-mode table editor can be integrated into any major mode by
212 activating the minor Orgtbl-mode.
214 There is a website for Org-mode which provides links to the newest
215 version of Org-mode, as well as additional information, screen shots
216 and example files. This page is located at
217 @uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
221 @node Installation and Activation, Feedback, Summary, Introduction
222 @section Installation and Activation
225 @cindex global keybindings
226 @cindex keybindings, global
228 If Org-mode is part of the Emacs distribution or an XEmacs package,
229 you only need to copy the following lines to your @file{.emacs} file.
230 The last two lines define @emph{global} keys for the commands
231 @command{org-store-link} and @command{org-agenda} - please choose
232 suitable keys yourself.
235 ;; The following lines are always needed. Choose your own keys.
236 (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
237 (define-key global-map "\C-cl" 'org-store-link)
238 (define-key global-map "\C-ca" 'org-agenda)
241 If you have downloaded Org-mode from the Web, you must byte-compile
242 @file{org.el} and put it on your load path. In addition to the Emacs
243 Lisp lines above, you also need to add the following lines to
247 ;; These lines only if org-mode is not part of the X/Emacs distribution.
248 (autoload 'org-mode "org" "Org mode" t)
249 (autoload 'org-diary "org" "Diary entries from Org mode")
250 (autoload 'org-agenda "org" "Multi-file agenda from Org mode" t)
251 (autoload 'org-store-link "org" "Store a link to the current location" t)
252 (autoload 'orgtbl-mode "org" "Org tables as a minor mode" t)
253 (autoload 'turn-on-orgtbl "org" "Org tables as a minor mode")
256 @cindex org-mode, turning on
257 With this setup, all files with extension @samp{.org} will be put into
258 Org-mode. As an alternative, make the first line of a file look like
262 MY PROJECTS -*- mode: org; -*-
265 @noindent which will select Org-mode for this buffer no matter what
266 the file's name is. See also the variable
267 @code{org-insert-mode-line-in-empty-file'}.
269 @node Feedback, , Installation and Activation, Introduction
276 If you find problems with Org-mode, or if you have questions, remarks,
277 or ideas about it, please contact the maintainer Carsten Dominik at
278 @value{MAINTAINEREMAIL}.
280 For bug reports, please provide as much information as possible,
281 including the version information of Emacs (@kbd{C-h v emacs-version
282 @key{RET}}) and Org-mode (@kbd{M-x org-version}), as well as the
283 Org-mode related setup in @file{.emacs}. If an error occurs, a
284 traceback can be very useful. Often a small example file helps, along
285 with clear information about:
287 @item What exactly did you do?
288 @item What did you expect to happen?
289 @item What happened instead?
291 @noindent Thanks for helping to improve this mode.
293 @node Document Structure, Tables, Introduction, Top
294 @chapter Document Structure
295 @cindex document structure
296 @cindex structure of document
298 Org-mode is based on outline mode and provides flexible commands to
299 edit the structure of the document.
302 * Outlines:: Org-mode is based on outline-mode
303 * Headlines:: How to typeset org-tree headlines
304 * Visibility cycling:: Show ad hide, much simplified
305 * Motion:: Jumping to other headlines
306 * Structure editing:: Changing sequence and level of headlines
307 * Archiving:: Move done task trees to a different place
308 * Sparse trees:: Matches embedded in context
311 @node Outlines, Headlines, Document Structure, Document Structure
316 Org-mode is implemented on top of outline-mode. Outlines allow to
317 organize a document in a hierarchical structure, which (at least for
318 me) is the best representation of notes and thoughts. Overview over
319 this structure is achieved by folding (hiding) large parts of the
320 document to show only the general document structure and the parts
321 currently being worked on. Org-mode greatly simplifies the use of
322 outlines by compressing the entire show/hide functionality into a
323 single command @command{org-cycle}, which is bound to the @key{TAB}
326 @node Headlines, Visibility cycling, Outlines, Document Structure
331 Headlines define the structure of an outline tree. The Headlines in
332 Org-mode start with one or more stars, for example
341 * Another top level headline
344 @node Visibility cycling, Motion, Headlines, Document Structure
345 @section Visibility cycling
346 @cindex visibility cycling
347 @cindex trees, visibility
349 Outlines make it possible to hide parts of the text in the buffer.
350 Org-mode uses a single command bound to the @key{TAB} key to change
351 the visibility in the buffer.
353 @cindex subtree visibility states
354 @cindex folded, subtree visibility state
355 @cindex children, subtree visibility state
356 @cindex subtree, subtree visibility state
360 Rotate current subtree between the states
362 ,-> FOLDED -> CHILDREN -> SUBTREE --.
363 '-----------------------------------'
365 At the beginning of the buffer (or when called with @kbd{C-u}), this does
366 the same as the command @kbd{S-@key{TAB}} below.
368 @cindex global visibility states
369 @cindex overview, global visibility state
370 @cindex contents, global visibility state
371 @cindex show all, global visibility state
374 Rotate the entire buffer between the states
376 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
377 '--------------------------------------'
379 Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.
381 @cindex show all, command
387 When Emacs firsts visits a Org-mode file, the global state is set to
388 OVERVIEW, i.e. only the top level headlines are visible. This can be
389 configured through the variable @code{org-startup-folded}, or on a
390 per-file basis by adding one of the following lines anywhere in the
399 @node Motion, Structure editing, Visibility cycling, Document Structure
401 @cindex motion, between headlines
402 @cindex jumping, to headlines
403 The following commands jump to other headlines in the buffer.
414 Next heading same level.
417 Previous heading same level.
420 Backward to higher level heading.
423 Jump to a different place without changing the current outline
424 visibility. Shows the document structure in a temporary buffer, where
425 you can use visibility cycling (@key{TAB}) to find your destination.
426 After pressing @key{RET}, the cursor moves to the selected location in
427 the original buffer, and the headings hierarchy above it is made
431 @node Structure editing, Archiving, Motion, Document Structure
432 @section Structure editing
433 @cindex structure editing
434 @cindex headline, promotion and demotion
435 @cindex promotion, of subtrees
436 @cindex demotion, of subtrees
437 @cindex subtree, cut and paste
438 @cindex pasting, subtrees
439 @cindex cutting, subtrees
440 @cindex copying, subtrees
445 Insert new heading with same level as current
446 @kindex M-S-@key{RET}
448 Insert new TODO entry with same level as current heading.
451 Promote current heading by one level
452 @kindex M-@key{right}
454 Demote current heading by one level
455 @kindex M-S-@key{left}
457 Promote the current subtree by one level
458 @kindex M-S-@key{right}
459 @item M-S-@key{right}
460 Demote the current subtree by one level
463 Move subtree up (swap with previous subtree of same level)
464 @kindex M-S-@key{down}
466 Move subtree down (swap with next subtree of same level)
469 Kill subtree, i.e. remove it from buffer but save in kill ring.
472 Copy subtree to kill ring.
475 Yank subtree from kill ring. This does modify the level of the subtree to
476 make sure the tree fits in nicely at the yank position. The yank
477 level can also be specified with a prefix arg, or by yanking after a
478 headline marker like @samp{****}.
481 @cindex region, active
482 @cindex active region
483 @cindex transient-mark-mode
484 When there is an active region (transient-mark-mode), promotion and
485 demotion work on all headlines in the region. To select a region of
486 headlines, it is best to place both point and mark at the beginning of a
487 line, mark at the beginning of the first headline, and point at the line
488 just after the last headline to change. Note that when the cursor is
489 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
492 @node Archiving, Sparse trees, Structure editing, Document Structure
496 When an project represented by a (sub)tree is finished, you may want
497 to move the tree to an Archive place, either in the same file under a
498 special top-level heading, or even to a different file.
502 Archive the subtree starting at the cursor position to the location
503 given by @code{org-archive-location}.
506 @cindex archive locations
507 The default archive is a file in the same directory as the current
508 file, with the name derived by appending @file{_archive} to the
509 current file name. For information and examples on how to change
510 this, see the documentation string of the variable
511 @code{org-archive-location}. If you are also using the Org-mode
512 agenda, archiving to a different file is a good way to keep archived
513 trees from contributing agenda items.
515 @node Sparse trees, , Archiving, Document Structure
516 @section Sparse trees
518 @cindex trees, sparse
519 @cindex folding, sparse trees
520 @cindex occur, command
522 An important feature of Org-mode is the ability to construct
523 @emph{sparse trees} for selected information in an outline tree. A
524 sparse tree means that the entire document is folded as much as
525 possible, but the selected information is made visible along with the
526 headline structure above it@footnote{See also the variable
527 @code{org-show-following-heading}}. Just try it out and you will see
528 immediately how it works.
530 Org-mode contains several commands creating such trees. The most
531 basic one is @command{org-occur}:
536 Occur. Prompts for a regexp and shows a sparse tree with all matches.
537 If the match is in a headline, the headline is made visible. If the
538 match is in the body of an entry, headline and body are made visible.
539 In order to provide minimal context, also the full hierarchy of
540 headlines above the match is shown, as well as the headline following
544 Other commands are using this feature as well. For example @kbd{C-c
545 C-v} creates a sparse TODO tree (@pxref{TODO basics}).
548 @cindex printing sparse trees
549 @cindex visible text, printing
550 To print a sparse tree, you can use the Emacs command
551 @code{ps-print-buffer-with-faces} which does not print invisible parts
552 of the document @footnote{this does not work under XEmacs, because
553 XEmacs uses selective display for outlining, not text properties}.
554 Or you can use the command @kbd{C-c C-x v} to copy the visible part of
555 the document to another file (extension @file{.txt}) which then can be
556 printed in any desired way.
558 @node Tables, Hyperlinks, Document Structure, Top
562 For taking notes, tables are an essential tool because they allow
563 immediate and clear structuring of data. Org-mode has a very fast and
564 intuitive table editor built-in. More complex tables can be created
565 with the Emacs table.el package.
568 * Built-in table editor:: Simple tables
569 * table.el:: Complex tables
570 * orgtbl-mode:: The table editor as minor mode
573 @node Built-in table editor, table.el, Tables, Tables
574 @section The built-in table editor
575 @cindex table editor, builtin
577 Org-mode makes it easy to format tables in plain ASCII. Any line with
578 @samp{|} as the first non-white character is considered part of a
579 table. @samp{|} is also the column separator. A table might look
583 | Name | Phone | Age |
584 |-------+-------+-----|
585 | Peter | 1234 | 17 |
589 A table is re-aligned automatically each time you press @key{TAB} or
590 @key{RET} inside the table. @key{TAB} also moves to the next field
591 (@key{RET} to the next row) and creates new table rows at the end of the
592 table or before horizontal lines. The indentation of the table is set
593 by the first line. Any line starting with @samp{|-} is considered as a
594 horizontal separator line and will be expanded on the next re-align to
595 span the whole table width. So, to create the above table, you would
603 @noindent and then press @key{TAB} to align the table and start filling in
607 @tsubheading{Creation and conversion}
610 Recognize @file{table.el} table. Works when the cursor is in a
615 Convert region to table. Works when the cursor is not in an existing
616 table, and when there is a region defined. If every line contains at
617 least one TAB character, the function assumes that the material is tab
618 separated. If not, lines are split at whitespace into fields. You
619 can use a prefix argument to indicate how many consecutive spaces are
620 at least required to indicate a field separator (default: just one).
622 @item M-x org-table-create
623 Creates an empty Org-mode table. However, it is much easier to just
624 start typing, like @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}
626 @tsubheading{Re-aligning and field motion}
629 Re-align the table without moving the cursor.
633 Re-align the table, move to the next field. Creates a new row if
638 Move to previous field.
642 Re-align the table and move down to next row. Creates a new row if
643 necessary. At the beginning or end of a line, @key{RET} still does
644 NEWLINE, so it can be used to split a table.
646 @tsubheading{Column and row editing}
648 @kindex M-@key{right}
651 Move the current column left/right
653 @kindex M-S-@key{left}
655 Kill the current column.
657 @kindex M-S-@key{right}
658 @item M-S-@key{right}
659 Insert a new column to the left of the cursor position.
665 Move the current row up/down
669 Kill the current row or horizontal line.
671 @kindex M-S-@key{down}
673 Insert a new row above (with arg: below) the current row.
677 Insert a horizontal line below current row. With prefix arg, line is
678 created above the current line.
680 @tsubheading{Regions}
683 Copy an rectangular region from a table to a special clipboard. Point
684 and mark determine edge fields of the rectangle. The process ignores
685 horizontal separator lines.
688 Copy an rectangular region from a table to a special clipboard, and
689 blank all fields in the rectangle.
692 Paste a rectangular region into a table.
693 The upper right corner ends up in the current field. All involved fields
694 will be overwritten. If the rectangle does not fit into the present table,
695 the table is enlarged as needed. The process ignores horizontal separator
699 Wrap several fields in a column like a paragraph. If there is an active
700 region, and both point and mark are in the same column, the text in the
701 column is wrapped to minimum width for the given number of lines. A
702 prefix ARG may be used to change the number of desired lines. If there
703 is no region, the current field is split at the cursor position and the
704 text fragment to the right of the cursor is prepended to the field one
705 line down. If there is no region, but you specify a prefix ARG, the
706 current field gets blank, and the content is appended to the field
709 @tsubheading{Calculations}
712 Which table column is the cursor in? Displays number >0 in echo
715 @cindex region, active
716 @cindex active region
717 @cindex transient-mark-mode
720 Sum the numbers in the current column, or in the rectangle defined by
721 the active region. The result is displayed in the echo area and can
722 be inserted with @kbd{C-y}.
726 When current field is empty, copy from first non-empty field above.
727 When not empty, copy current field down to next row and move cursor
728 along with it. Depending on the variable
729 @code{org-table-copy-increment}, integer field values will be
730 incremented during copy. This key is also used by CUA-mode
731 (@pxref{Interaction}).
733 @cindex formula, in tables
734 @cindex calculations, in tables
737 Replace current field with the result of a formula. Requires the
738 Emacs calc package. The formula can access the current field with
739 @samp{$}, and the other fields in the current row
740 with @samp{$1}, @samp{$2},... For details see the documentation of the
741 command @command{org-table-eval-formula}.
743 @tsubheading{Miscellaneous}
746 Toggle the visibility of vertical lines in tables. The lines are
747 still there, only made invisible with a text property. Any @samp{|}
748 added by hand will become invisible on the next align.
749 Typographically it is good style to have no vertical lines in tables.
751 @item M-x org-table-import
752 Import a file as a table. The table should be TAB- or whitespace
753 separated. Useful for example to import an Excel table or data from a
754 database, because these programs generally can write TAB-separated text
755 files. This command works by inserting the file into the buffer and
756 then converting the region to a table. Any prefix argument is passed on
757 to the converter, which uses it to determine the separator.
759 @item M-x org-table-export
760 Export the table as a TAB-separated file. Useful for data exchange with
761 for example Excel or database programs.
765 If you don't like the automatic table editor because it gets into your
766 way in lines which you would like to start with @samp{|}, you can turn
769 (setq org-enable-table-editor nil)
771 @noindent The only table command which then still works is
772 @kbd{C-c C-c} to do a manual re-align.
774 @node table.el, orgtbl-mode, Built-in table editor, Tables
775 @section The @file{table.el} package
777 @cindex table editor, table.el
778 @cindex @file{table.el}
780 More complex ASCII tables (with automatic line wrapping, column- and
781 row-spanning, and alignment) can be created using the Emacs table
782 package by Takaaki Ota (@uref{http://sourceforge.net/projects/table}).
783 When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-mode
784 will call @command{table-recognize-table} and move the cursor into the
785 table. Inside a table, the keymap of Org-mode is inactive. In order
786 to execute org-related commands, leave the table.
791 Insert a table.el table. If there is already a table at point, this
792 command converts it between the table.el format and the Org-mode
793 format. See the documentation string of the command
794 @code{org-convert-table} for the restrictions under which this is
798 @node orgtbl-mode, , table.el, Tables
799 @section The Orgtbl minor mode
801 @cindex Minor mode for tables
803 If you like the intuitive way the Org-mode table editor works, you
804 might want to use it also in other modes like text-mode or mail-mode.
805 The minor mode Orgtbl-mode makes this possible. You can always toggle
806 the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for
807 example in mail mode, use
809 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
812 @node Hyperlinks, TODO items, Tables, Top
816 Just like HMTL, Org-mode provides links to other files, usenet
817 articles, emails and much more.
820 * Links:: URL-like links to the world
821 * Remember:: Org-trees store quick notes
824 @node Links, Remember, Hyperlinks, Hyperlinks
831 @cindex WANDERLUST links
835 Org-mode supports links to files, websites, usenet and email messages;
836 and BBDB database entries. Links are just plain-text URL-like
837 locators, optionally enclosed by angular brackets. The following list
838 shows examples for each link type.
841 <http://www.astro.uva.nl/~dominik> @r{on the web}
842 <file:/home/dominik/images/jupiter.jpg> @r{file, absolute path}
843 <file:papers/last.pdf> @r{file, relative path}
844 <file:~/code/main.c:255> @r{file, with line number}
845 <news:comp.emacs> @r{Usenet link}
846 <mailto:adent@@galaxy.net> @r{Mail link}
847 <vm:folder> @r{VM folder link}
848 <vm:folder#id> @r{VM message link}
849 <vm://myself@@some.where.org/folder#id> @r{VM on remote machine}
850 <wl:folder> @r{WANDERLUST folder link}
851 <wl:folder#id> @r{WANDERLUST message link}
852 <rmail:folder> @r{RMAIL folder link}
853 <rmail:folder#id> @r{RMAIL message link}
854 <gnus:group> @r{GNUS group link}
855 <gnus:group#id> @r{GNUS article link}
856 <bbdb:Richard Stallman> @r{BBDB link}
857 <shell:ls *.org>@footnote{Note that @samp{<} and @samp{>} cannot be part of a link, and therefore of a shell command. If you need redirection, use @@@{ and @@@} instead.} @r{A shell command}
860 A link may contain space characters and is terminated by @samp{>} or by
861 the end of a line. In tables, the end of a table field also terminates
862 a link. Angle brackets around a link are not required, but are
863 recommended to avoid problems with punctuation and other text following
864 the link. See also the variable @code{org-allow-space-in-links}.
866 @cindex storing links
870 Store a link to the current location. This is a @emph{global} command
871 which can be used in any buffer to create a link. The link will be
872 stored for later insertion into an Org-mode buffer (see below). For VM,
873 RMAIL, WANDERLUST, GNUS and BBDB buffers, the link will point to the
874 current article/entry. For W3 and W3M buffer, the link goes to the
875 current URL. For any other files, the link will just point to the file.
876 The key binding @kbd{C-c l} is only a suggestion - see
877 @ref{Installation and Activation}.
881 Insert a link. This prompts for a link to be inserted into the
882 buffer. You can just type a link, using one of the link type prefixes
883 mentioned in the examples above. Through completion, all links stored
884 during the current session can be accessed. When called with prefix
885 arg, you can use file name completion to enter a file link. The link
886 will be formatted as given in the variable @code{org-link-format} and
887 inserted into the buffer. Note that you don't have to use this
888 command to insert a link. Links in Org-mode are plain text, and you
889 can type or paste them straight into the buffer.
891 @cindex inserting links
894 Open link at point. This will launch a web browser for URLs (using
895 @command{browse-url-at-point}), run vm/gnus/bbdb for the corresponding
896 links, execute the command in a shell link, visit text files with
897 Emacs and select a suitable application for non-text files.
898 Classification of files is based on file extension only. See option
899 @code{org-file-apps}. If there is no link at point, the current
900 subtree will be searched for one. If you want to override the default
901 application and visit the file with Emacs, use a @kbd{C-u} prefix.
902 If the cursor is on a time stamp, compiles the agenda for that date.
904 @strong{IMPORTANT}: Be careful not to use any dangerous commands in a
909 On links, @kbd{mouse-2} will open the link just like @kbd{C-c C-o} would.
913 Like @kbd{mouse-2}, but force file links to be opened with Emacs.
916 @node Remember, , Links, Hyperlinks
918 @cindex @file{remember.el}
920 Another way to create org entries with links to other files is through
921 the @emph{Remember} package by John Wiegley. @emph{Remember} lets you
922 store quick notes with little interruption of your work flow. See
923 @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more
924 information. The notes produced by @emph{Remember} can be stored in
925 different ways, and Org-mode files are a good target.
926 Org-mode allows to file away notes either to a default file, or
927 directly to the correct location in your Org-mode outline tree. The
928 following customization will tell @emph{Remember} to use org files as
929 target, and to create annotations compatible with Org-mode links.
931 @c FIXME: The autoload will not be necessary when Org-mode is part of Emacs
933 (autoload 'org-remember-annotation "org")
934 (autoload 'org-remember-handler "org")
935 (setq org-directory "~/path/to/my/orgfiles/")
936 (setq org-default-notes-file "~/.notes")
937 (setq remember-annotation-functions '(org-remember-annotation))
938 (setq remember-handler-functions '(org-remember-handler))
941 When you compose a note with remember, you have to press @kbd{C-c C-c}
942 to exit remember-mode and to file away the note. The handler first
943 prompts for a target file - if you press @key{RET}, the value of
944 @code{org-default-notes-file} is used. Then the command offers the
945 headings tree of the selected file. You can either immediately press
946 @key{RET} to get the note appended to the file. Or you can use
947 vertical cursor motion (@key{up} and @key{down}) and visibility
948 cycling (@key{TAB}) to find a better place. Pressing @key{RET} or
949 @key{left} or @key{right} leads to the following result.
951 @multitable @columnfractions 0.2 0.1 0.7
952 @item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}
953 @item buffer-start @tab @key{RET} @tab as level 2 heading at end of file
954 @item on headline @tab @key{RET} @tab as sublevel of the heading at cursor
955 @item @tab @key{left} @tab as same level, before current heading
956 @item @tab @key{right} @tab as same level, after current heading
957 @item not on headline @tab @key{RET}
958 @tab at cursor position, level taken from context.
959 Or use prefix arg to specify level manually.
962 So a fast way to store the note is to press @kbd{C-c C-c @key{RET}
963 @key{RET}} to append it to the default file. Even shorter would be
964 @kbd{C-u C-c C-c}, which does the same without even showing the tree.
965 But with little extra effort, you can push it directly to the correct
968 Before inserting the text into a tree, the function ensures that the
969 text has a headline, i.e. a first line that starts with a @samp{*}.
970 If not, a headline is constructed from the current date and some
971 additional data. If the variable @code{org-adapt-indentation} is
972 non-@code{nil}, the entire text is also indented so that it starts in
973 the same column as the headline (after the asterisks).
975 @node TODO items, Timestamps, Hyperlinks, Top
979 Org-mode does not maintain TODO lists as a separate document. TODO
980 items are an integral part of the notes file, because TODO items
981 usually come up while taking notes! With Org-mode, you simply mark
982 any entry in a tree as being a TODO item. In this way, the
983 information is not duplicated, and the entire context from which the
984 item emerged is always present when you check.
986 Of course, this technique causes TODO items to be scattered throughout
987 your file. Org-mode provides methods to give you an overview over all
988 things you have to do.
991 * TODO basics:: Marking and displaying TODO entries
992 * TODO extensions:: Workflow and assignments
993 * Priorities:: Some things are more important than others
996 @node TODO basics, TODO extensions, TODO items, TODO items
997 @section Basic TODO functionality
999 Any headline can become a TODO item by starting it with the word TODO,
1003 *** TODO Write letter to Sam Fortune
1007 The most important commands to work with TODO entries are:
1012 Rotate the TODO state of the current item between
1014 ,-> (unmarked) -> TODO -> DONE --.
1015 '--------------------------------'
1017 The same rotation can also be done ``remotely'' from the timeline and
1018 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
1020 @cindex sparse tree, for TODO
1022 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds
1023 the entire buffer, but shows all TODO items and the headings hierarchy
1024 above them. With prefix arg, show also the DONE entries.
1026 A @kbd{C-u} argument to the @code{org-agenda command} (@pxref{Agenda})
1027 collects all unfinished TODO items into a single place.
1030 @node TODO extensions, Priorities, TODO basics, TODO items
1031 @section Extended use of TODO keywords
1032 @cindex extended TODO keywords
1034 The default implementation of TODO entries is just two states: TODO
1035 and DONE. You can, however, use the TODO feature for more
1036 complicated things by configuring the variables
1037 @code{org-todo-keywords} and @code{org-todo-interpretation}. Using
1038 special setup, you can even use TODO keywords in different ways in
1039 different org files.
1042 * Workflow states:: From TODO to DONE in steps
1043 * TODO types:: I do this, Fred the rest
1044 * Per file keywords:: Different files, different requirements
1047 @node Workflow states, TODO types, TODO extensions, TODO extensions
1048 @subsection TODO keywords as workflow states
1049 @cindex TODO workflow
1050 @cindex workflow states as TODO keywords
1052 You can use TODO keywords to indicate different states in the process
1053 of working on an item, for example
1056 (setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE")
1057 org-todo-interpretation 'sequence)
1060 With this setup, the command @kbd{C-c C-t} will cycle an entry from
1061 TODO to FEEDBACK, then to VERIFY, and finally too DONE. You may also
1062 use a prefix argument to quickly select a specific state. For example
1063 @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
1064 If you define many keywords, you can use in-buffer completion (see
1065 @ref{Completion}) to insert these words into the buffer.
1067 @node TODO types, Per file keywords, Workflow states, TODO extensions
1068 @subsection TODO keywords as types
1070 @cindex names as TODO keywords
1071 @cindex types as TODO keywords
1073 The second possibility is to use TODO keywords to indicate different
1074 types of action items. For example, you might want to indicate that
1075 items are for ``work'' or ``home''. Or, when you work with several
1076 people on a single project, you might want to assign action items
1077 directly to persons, by using their names as TODO keywords. This
1078 would be set up like this:
1081 (setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE")
1082 org-todo-interpretation 'type)
1085 In this case, different keywords do not indicate a sequence, but
1086 rather different types. So it is normally not useful to change from
1087 one type to another. Therefore, in this case the the behavior of the
1088 command @kbd{C-c C-t} is changed slightly@footnote{This is also true
1089 for the @kbd{t} command in the timeline and agenda buffers}. When
1090 used several times in succession, it will still cycle through all
1091 names. But when when you return to the item after some time and
1092 execute @kbd{C-c C-t} again, it will switch from each name directly to
1093 DONE. Use prefix arguments or completion to quickly select a specific
1096 @node Per file keywords, , TODO types, TODO extensions
1097 @subsection Setting up TODO keywords for individual files
1098 @cindex keyword options
1099 @cindex per file keywords
1101 It can be very useful to use different aspects of the TODO mechanism
1102 in different files, which is not possible with the global settings
1103 described above. For file-local settings, you need to add special
1104 lines to the file which set the keywords and interpretation for that
1105 file only. For example, to set one of the two examples discussed
1106 above, you need one of the following lines, starting in column zero
1107 anywhere in the file:
1110 #+SEQ_TODO: TODO FEEDBACK VERIFY DONE
1111 #+TYP_TODO: Fred Sara Lucy Mike DONE
1114 @cindex Completing option keywords
1116 @noindent To make sure you are using the correct keyword, type
1117 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
1119 @cindex DONE, final TODO keyword
1120 Remember that the last keyword must always mean that the item is DONE
1121 (you may use a different word, though). Also note that in each file,
1122 only one of the two aspects of TODO keywords can be used. After
1123 changing one of these lines, use @kbd{C-c C-c} with the cursor still
1124 in the line to make the changes known to Org-mode@footnote{Org-mode
1125 parses these lines only when Org-mode is activated after visiting a
1126 file. @kbd{C-c C-c} with the cursor in a line starting with @samp{#-}
1127 is simply restarting Org-mode, making sure that these changes will be
1130 If you want to use very many keywords, for example when working with a
1131 large group of people, you may split the names over several lines:
1134 #+TYP_TODO: Fred Sara Lucy Mike
1135 #+TYP_TODO: Luis George Jules Jessica
1136 #+TYP_TODO: Kim Arnold Peter
1140 @node Priorities, , TODO extensions, TODO items
1144 If you use Org-mode extensively to organize your work, you may end up
1145 with a number of TODO entries so large that you'd like to prioritize
1146 them. This can be done by placing a @emph{priority cookie} into the
1150 *** TODO [#A] Write letter to Sam Fortune
1154 With its standard setup, Org-mode supports priorities @samp{A},
1155 @samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry
1156 without a cookie is treated as priority @samp{B}. Priorities make a
1157 difference only in the agenda (@pxref{Agenda}).
1162 Set the priority of the current item. The command prompts for a
1163 priority character @samp{A}, @samp{B} or @samp{C}. When you press
1164 @key{SPC} instead, the priority cookie is removed from the headline.
1165 The priorities can also be changed ``remotely'' from the timeline and
1166 agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
1169 @kindex S-@key{down}
1172 Increase/decrease priority of current item. Note that these keys are
1173 also used to modify time stamps (@pxref{Creating timestamps}).
1174 Furthermore, these keys is also used by CUA-mode
1175 (@pxref{Interaction}).
1180 @node Timestamps, Timeline and Agenda, TODO items, Top
1183 Items can be labeled with timestamps to make them useful for project
1187 * Time stamps:: Assigning a time to a tree entry
1188 * Creating timestamps:: Commands which insert timestamps
1192 @node Time stamps, Creating timestamps, Timestamps, Timestamps
1193 @section Time stamps, deadlines and scheduling
1198 A time stamp is a specification of a date (possibly with time) in a
1199 special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16
1200 Tue 09:39>}. A time stamp can appear anywhere in the headline or body
1201 of an org-tree entry. Its presence allows to show entries on specific
1202 dates in the agenda (@pxref{Agenda}). We distinguish:
1207 A simple time stamp just assigns a date/time to an item. In the
1208 timeline and agenda displays, the headline of the entry will be shown
1209 exactly on that date.
1213 Two time stamps connected by @samp{--} denote a time range. The
1214 headline will be shown on the first and last day of the range, and on
1215 any dates that are displayed and fall in the range. Here is an
1219 ** Meeting in Amsterdam
1220 <2004-08-23 Mon>--<2004-08-26 Thu>
1225 If a time stamp is preceded by the word @samp{DEADLINE:}, the task
1226 (most likely a TODO item) is supposed to be finished on that date, and
1227 it will be listed then. In addition, the compilation for the
1228 @emph{current day} will carry a warning about the approaching or
1229 missed deadline, starting @code{org-deadline-warning-days} before the
1230 due date, and continuing until the entry is marked DONE. An example:
1233 *** TODO write article about the Earth for the Guide
1234 The editor in charge is bbdb:Ford Prefect
1235 DEADLINE: <2004-02-29 Sun>
1240 If a time stamp is preceded by the word @samp{SCHEDULED:}, it means
1241 you are planning to start working on that task on the given date. The
1242 headline will be listed under the given date. In addition, a reminder
1243 that the scheduled date has passed will be present in the compilation
1244 for the @emph{current day}, until the entry is marked DONE. I.e., the
1245 task will automatically be forwarded.
1248 @node Creating timestamps, , Time stamps, Timestamps
1249 @section Creating timestamps
1250 @cindex creating timestamps
1252 For Org-mode to recognize time stamps, they need to be in the specific
1253 format. All commands listed below produce time stamps in the correct
1259 Prompt for a date and insert a corresponding time stamp. When the
1260 cursor is at a previously used time stamp, it is updated to NOW. When
1261 this command is used twice in succession, a time range is inserted.
1265 Like @kbd{C-c .}, but use the alternative format which contains date
1270 Insert a time stamp corresponding to the cursor date in the Calendar.
1274 Access the Emacs calendar for the current date. If there is a
1275 timestamp in the current line, goto the corresponding date
1280 Access the agenda for the date given by the time stamp at point
1285 Insert @samp{DEADLINE} keyword along with a stamp.
1287 @cindex sparse tree, for deadlines
1289 Create a sparse tree with all deadlines that are either past-due, or
1290 which will become due within @code{org-deadline-warning-days}.
1291 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
1292 prefix, check that many days. For example, @kbd{C-1 C-c C-w} shows
1293 all deadlines due tomorrow.
1297 Insert @samp{SCHEDULED} keyword along with a stamp.
1299 @kindex S-@key{left}
1300 @kindex S-@key{right}
1302 @itemx S-@key{right}
1303 Change date at cursor by one day. These key bindings conflict with
1304 CUA-mode (@pxref{Interaction}).
1307 @kindex S-@key{down}
1310 Change the item under the cursor in a timestamp. The cursor can be on
1311 a year, month, day, hour or minute. Note that if the cursor is not at
1312 a time stamp, these same keys modify the priority of an item.
1313 (@pxref{Priorities}). These key bindings conflict with CUA-mode
1314 (@pxref{Interaction}).
1318 @cindex evaluate time range
1320 Evaluate a time range by computing the difference between start and
1321 end. With prefix arg, insert result after the time range (in a table:
1322 into the following column).
1325 @cindex date, reading in minibuffer
1326 @cindex time, reading in minibuffer
1327 @cindex calendar, for selecting date
1328 When org prompts for a date/time, the function reading your input will
1329 replace anything you choose not to specify with the current date and
1330 time. For details, see the documentation string of
1331 @command{org-read-date}. Also, a calender will pop up to allow
1332 selecting a date. The calendar can be fully controlled from the
1333 minibuffer, and a date can be selected with the following commands:
1338 Scroll calendar backwards by one month.
1341 Scroll calendar forwards by one month.
1344 Select date by clicking on it.
1345 @kindex S-@key{right}
1348 @kindex S-@key{left}
1351 @kindex S-@key{down}
1357 @kindex M-S-@key{right}
1358 @item M-S-@key{right}
1360 @kindex M-S-@key{left}
1361 @item M-S-@key{left}
1365 Choose date in calendar (only if nothing typed into minibuffer).
1368 @node Timeline and Agenda, Exporting, Timestamps, Top
1369 @chapter Timeline and Agenda
1372 We have already described three commands to filter important
1373 information in an org file into a sparse tree (@pxref{Sparse trees}):
1375 @cindex sparse trees
1378 The TODO tree, (@kbd{C-c C-v}), see @ref{TODO items}.
1380 The occur tree @kbd{C-c /}, see @ref{TODO items}.
1382 Checking upcoming deadlines with @kbd{C-c C-w}, see @ref{Creating
1387 Instead of using the sparse trees, Org-mode can also collect and
1388 time-sort the important items into a separate buffer, which we call
1389 the @emph{timeline} of the org file. It can also collect information
1390 from a @emph{list of files} and in this way provide an @emph{agenda}
1391 which covers all of your current projects, action items and
1395 * Timeline:: Time-sorted view for single file
1396 * Agenda:: Your weekly planner
1397 * Agenda commands:: Remote editing of org trees
1398 * Calendar/Diary integration:: Integrating Anniversaries and more
1401 @node Timeline, Agenda, Timeline and Agenda, Timeline and Agenda
1402 @section Timeline for a single file
1403 @cindex single file summary
1404 @cindex agenda, for single file
1405 @cindex timeline, single file
1406 @cindex time-sorted view
1408 The timeline shows all time-stamped items in a single Org-mode file,
1409 in @emph{time-sorted view}. The main purpose of this command is to
1410 give an overview over events in a project.
1415 Show a time-sorted view of the org file, with all time-stamped items
1416 of today or later. When called with a @kbd{C-u} prefix, past dates
1417 will be included as well. When called with two @kbd{C-u C-u}
1418 prefixes, all unfinished TODO entries (scheduled or not) are also
1419 listed under the current date.
1423 The timeline is shown in a temporary buffer @file{*Org Agenda*}. The
1424 commands available in the Agenda buffer are listed in @ref{Agenda
1427 @node Agenda, Agenda commands, Timeline, Timeline and Agenda
1431 An agenda can be compiled from one or more org files. The main
1432 purpose of this command is to act like a paper agenda, showing you all
1433 the tasks for the current day or week.
1435 The Org-mode files to be processed in order to generate the agenda are
1436 listed in the variable @code{org-agenda-files}. You can customize
1437 this variable, but the easiest way to maintain it is through the
1440 @cindex files, adding to agenda list
1444 Add current file to the list of agenda files
1447 Remove current file from the list of agenda files.
1450 The Org menu contains the list of all files and can be used to quickly
1453 The global command @command{org-agenda} compiles the agenda from all
1457 @cindex org-agenda, command
1460 Compile an agenda for the current week from a list of org files. The
1461 agenda shows the entries for each day. With a @kbd{C-u} prefix (or
1462 when the variable @code{org-agenda-include-all-todo} is @code{t}), all
1463 unfinished TODO items (also those without a date) are also listed at
1464 the beginning of the buffer, before the first date.@*
1465 The key binding @kbd{C-c a} is only a suggestion - see
1466 @ref{Installation and Activation}.
1469 The commands available in the Agenda buffer are listed in
1470 @ref{Agenda commands}.
1472 @subsection Categories
1475 In the agenda buffer, each entry is preceded by a @emph{category},
1476 which is derived from the file name. The category can also be set
1477 with a special line anywhere in the buffer, looking like this:
1482 After changing this line, press @kbd{C-c C-c} with the cursor still in
1483 the line, to make the changes known to org-mode. Otherwise, the
1484 change will only be active the next time you visit this file with
1487 The display in the agenda buffer looks best if the category is not
1488 longer than 10 characters.
1490 @subsection Time Specifications
1492 Org-mode checks each agenda item for a time specification. The time
1493 can be part of the time stamp that triggered inclusion into the agenda,
1494 for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time ranges can
1495 be specified with two time stamps, like
1497 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
1499 In the headline of the entry itself, a time(range) may also appear as
1500 plain text (like @samp{12:45} or a @samp{8:30-1pm}. If the agenda
1501 integrates the Emacs diary (@pxref{Calendar/Diary integration}), time
1502 specifications in diary entries are recognized as well.
1504 For agenda display, Org-mode extracts the time and displays it in a
1505 standard 24 hour format as part of the prefix. The example times in
1506 the previous paragraphs would end up in the agenda like this:
1509 8:30-13:00 Arthur Dent lies in front of the bulldozer
1510 12:45...... Ford Prefect arrives and takes Arthur to the pub
1511 19:00...... The Vogon reads his poem
1512 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
1515 If the agenda is in single-day mode, or for the display of today, the
1516 timed entries are embedded in a time grid, like
1519 8:00...... ------------------
1520 8:30-13:00 Arthur Dent lies in front of the bulldozer
1521 10:00...... ------------------
1522 12:00...... ------------------
1523 12:45...... Ford Prefect arrives and takes Arthur to the pub
1524 14:00...... ------------------
1525 16:00...... ------------------
1526 18:00...... ------------------
1527 19:00...... The Vogon reads his poem
1528 20:00...... ------------------
1529 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
1532 The time grid can be turned on and off with the variable
1533 @code{org-agenda-use-time-grid}, and can be configured with
1534 @code{org-agenda-time-grid}.
1537 @subsection Sorting of agenda items
1538 @cindex sorting, of agenda items
1539 @cindex priorities, of agenda items
1540 The entries for each day are sorted. The default order is to first
1541 collect all items containing an explicit time-of-day specification.
1542 These entries will be shown at the beginning of the list, as a
1543 @emph{schedule} for the day. After that, items remain grouped in
1544 categories, in the sequence given by @code{org-agenda-files}. Within
1545 each category, items are sorted by priority (@pxref{Priorities}).
1547 The priority is a numerical quantity composed of the base priority
1548 (2000 for priority @samp{A}, 1000 for @samp{B}, and 0 for @samp{C}),
1549 plus additional increments for overdue scheduled or deadline items.
1551 Sorting can be customized using the variable
1552 @code{org-agenda-sorting-strategy}.
1554 @node Agenda commands, Calendar/Diary integration, Agenda, Timeline and Agenda
1555 @section Commands in the agenda buffer
1557 Entries in the agenda buffer are linked back to the org file or diary
1558 file where they originate. You are not allowed to edit the agenda
1559 buffer itself, but commands are provided to show and jump to the
1560 original entry location, and to edit the org-files ``remotely'' from
1561 the agenda buffer. In this way, all information is stored only once,
1562 and you don't risk that your agenda and note files diverge.
1564 Some commands can be executed with mouse clicks on agenda lines. For
1565 the other commands, the cursor needs to be in the desired line. Most
1566 commands are available for both timelines and the agenda. The
1567 exceptions are marked.
1570 @tsubheading{Motion}
1573 Next line (same as @key{up}).
1576 Previous line (same as @key{down}).
1577 @tsubheading{View/GoTo org file}
1582 Display the original location of the item in another window.
1586 Display original location and recenter that window.
1592 Go to the original location of the item in another window.
1596 Go to the original location of the item and delete other windows.
1600 Toggle follow mode. In follow mode, as you move the cursor through
1601 the agenda buffer, the other window always shows the corresponding
1602 location in the org file.
1604 @tsubheading{Change display}
1607 Delete other windows.
1611 Toggle between weekly and daily view.
1615 Toggle the inclusion of diary entries. See @ref{Calendar/Diary integration}.
1619 Toggle the time grid on and off. See also the variables
1620 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
1624 Recreate the agenda buffer, for example to reflect the changes
1625 after modification of the time stamps of items with S-@key{left} and
1630 Display the following @code{org-agenda-ndays} days. For example, if
1631 the display covers a week, switch to the following week. With prefix
1632 arg, go forward that many times @code{org-agenda-ndays} days. Not
1633 available in timelines.
1637 Display the previous dates. Not available in timelines.
1643 @tsubheading{Remote editing}
1650 Change the TODO state of the item, both in the agenda and in the
1655 Set the priority for the current item. Org-mode prompts for the
1656 priority character. If you reply with @key{SPC}, the priority cookie
1657 is removed from the entry.
1661 Display weighted priority of current item.
1667 Increase the priority of the current item. The priority is changed in
1668 the original buffer, but the agenda is not resorted. Use the @kbd{r}
1672 @kindex S-@key{down}
1675 Decrease the priority of the current item.
1677 @kindex S-@key{right}
1679 Change the time stamp associated with the current line by one day into
1680 the future. With prefix argument, change it by that many days. For
1681 example, @kbd{3 6 5 S-@key{right}} will change it by a year. The
1682 stamp is changed in the original org file, but the change is not
1683 directly reflected in the agenda buffer. Use the
1684 @kbd{r} key to update the buffer.
1686 @kindex S-@key{left}
1688 Change the time stamp associated with the current line by one day
1693 Change the time stamp associated with the current line to today.
1694 The key @kbd{>} has been chosen, because it is the same as @kbd{S-.}
1697 @cindex diary entries, creating from agenda
1700 Insert a new entry into the diary. Prompts for the type of entry
1701 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a new
1702 entry in the diary, just like @kbd{i d} etc. would do in the calendar.
1703 The date is taken from the cursor position.
1705 @tsubheading{Calendar commands}
1708 Open the Emacs calendar and move to the date at the agenda cursor.
1711 When in the calendar, compute and show the Org-mode agenda for the
1716 Show the phases of the moon for three month around current date.
1720 Show sunrise and sunset times. The geographical location must be set
1721 with calendar variables, see documentation of the Emacs calendar.
1725 Convert the date at cursor into many other cultural and historic
1730 Show holidays for three month around the cursor date.
1732 @tsubheading{Quit and Exit}
1735 Quit Agenda, remove the agenda buffer.
1738 @cindex agenda files, removing buffers
1740 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
1741 for the compilation of the agenda. Buffers created by the user to
1742 visit org files will not be removed.
1746 @node Calendar/Diary integration, , Agenda commands, Timeline and Agenda
1747 @section Calendar/Diary integration
1748 @cindex calendar integration
1749 @cindex diary integration
1751 Emacs contains the calendar and diary by Edward M. Reingold. The
1752 calendar displays a three-month calendar with holidays from different
1753 countries and cultures. The diary allows to keep track of
1754 anniversaries, lunar phases, sunrise/set, recurrent appointments
1755 (weekly, monthly) and more. In this way, it is quite complementary to
1756 Org-mode. It can be very useful to combine output from Org-mode with
1759 The interaction between Org-mode and diary works both ways: You can
1760 list entries from the diary in the Org-mode agenda, from which many
1761 calendar and diary commands are directly accessible. Or you can
1762 display entries from the org agenda in the Emacs diary.
1765 * Diary to agenda:: Agenda incorporates the diary
1766 * Agenda to diary:: Diary incorporates the agenda
1769 @node Diary to agenda, Agenda to diary, Calendar/Diary integration, Calendar/Diary integration
1770 @subsection Including the diary into the agenda
1771 @cindex diary to agenda
1773 In order to include entries from the Emacs diary into Org-mode's
1774 agenda, you only need to customize the variable
1777 (setq org-agenda-include-diary t)
1781 @noindent After that, everything will happen automatically. All diary
1782 entries including holidays, anniversaries etc will be included in the
1783 agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and
1784 @key{RET} can be used from the agenda buffer to jump to the diary
1785 file, in order to edit existing diary entries. Also the @kbd{i}
1786 command to insert new entries for the current date works in the agenda
1787 buffer, as well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to
1788 display Sunrise/Sunset times, show lunar phases and to convert to
1789 other calendars, respectively. @kbd{c} can be used to switch back and
1790 forth between calendar and agenda.
1792 @node Agenda to diary, , Diary to agenda, Calendar/Diary integration
1793 @subsection Including the agenda into the diary
1795 If you prefer to use the Emacs diary as your main instrument and if
1796 you wish to include the Org-mode agenda into it, the following steps
1797 are necessary: Autoload the function @command{org-diary} as shown
1798 above under @ref{Installation and Activation}. You also need to use
1799 @emph{fancy diary display} by setting in @file{.emacs}:
1802 (add-hook 'diary-display-hook 'fancy-diary-display)
1805 Then include the following line into your @file{~/diary} file, in
1806 order to get the entries from all files listed in the variable
1807 @code{org-agenda-files}:
1813 You may also select specific files with
1816 &%%(org-diary) ~/path/to/some/org-file.org
1817 &%%(org-diary) ~/path/to/another/org-file.org
1820 If you now launch the calendar and press @kbd{d} to display a diary,
1821 the headlines of entries containing a timestamp, date range, schedule,
1822 or deadline referring to the selected date will be listed. Just like
1823 in Org-mode's agenda view, the diary for @emph{today} contains
1824 additional entries for overdue deadlines and scheduled items. See
1825 also the documentation of the @command{org-diary} function.
1827 @node Exporting, Miscellaneous, Timeline and Agenda, Top
1834 @cindex headline levels, for exporting
1835 For printing and sharing of notes, an Org-mode document can be
1836 exported as an ASCII file, or as HTML. In the exported version, the
1837 first 3 outline levels will become headlines, defining a general
1838 document structure. Additional levels will be exported as itemize
1839 lists. If you want that transition to occur at a different level,
1840 specify it with a prefix argument. For example,
1843 @kbd{M-1 M-x org-export-as-html}
1846 creates only top level headlines and does the rest as items.
1849 * Export commands:: Commands which export and display
1850 * HTML formatting:: Interpretation of the buffer content
1851 * Export options:: How to influence exports
1852 * Comment lines:: Lines which will not be exported
1855 @node Export commands, HTML formatting, Exporting, Exporting
1856 @section Export commands
1858 @cindex region, active
1859 @cindex active region
1860 @cindex transient-mark-mode
1864 Export as ASCII file. If there is an active region, only the region
1865 will be exported. For an org file @file{myfile.org}, the ASCII file
1866 will be @file{myfile.txt}. The file will be overwritten without
1870 Export as HTML file @file{myfile.html}.
1873 Export as HTML file and open it with a browser.
1876 Insert template with export options, see below.
1879 Toggle fixed-width for line or region, see below.
1882 @node HTML formatting, Export options, Export commands, Exporting
1883 @section HTML formatting
1885 Not all text is transferred literally to the exported HTML file. The
1886 exporter implements the following interpretation:
1889 @cindex underlined text
1893 You can make words @b{*bold*}, @i{/italic/}, and _underlined_
1895 @cindex @TeX{} interpretation
1897 Simple @TeX{}-like math constructs are interpreted:
1901 @samp{10^22} and @samp{J_n} are super- and subscripts. You can quote
1902 @samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}
1904 @samp{\alpha} indicates a Greek letter, @samp{\to} an arrow. You can
1905 use completion for these macros, just type @samp{\} and maybe a few
1906 letters, and press @kbd{M-@key{TAB}} to see possible completions.
1909 @cindex tables, export to HTML
1911 Tables are transformed into HTML tables. Data fields before the first
1912 horizontal separator line will be formatted as table header fields.
1916 Lines starting with @samp{:} are typeset in a fixed-width font, to
1917 allow quoting of computer code etc.
1921 If you want to include HTML tags which should be interpreted as such,
1922 mark them with a @samp{@@} like in @samp{@@<b>bold text@@</b>}.
1923 Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
1924 @samp{>} in HTML export.
1927 If these conversions conflict with your habits of typing ASCII text,
1928 they can all be turned off with corresponding variables.
1930 @node Export options, Comment lines, HTML formatting, Exporting
1931 @section Export options
1932 @cindex options, for export
1934 The exporter recognizes special lines in the buffer which provide
1935 additional information. These lines may be put anywhere in the file.
1936 The whole set of lines can be inserted into the buffer with @kbd{C-c
1937 C-x t}. For individual lines, a good way to make sure the keyword is
1938 correct it to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
1939 (@pxref{Completion}).
1942 #+TITLE: the title to be shown (default is the buffer name)
1943 #+AUTHOR: the author (default taken from @code{user-full-name})
1944 #+EMAIL: his/her email address (default from @code{user-mail-address})
1945 #+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language})
1946 #+TEXT: Some descriptive text to be inserted at the beginning.
1947 #+TEXT: Several lines may be given.
1948 #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t *:nil TeX:t
1951 The OPTIONS line is a compact form to specify export settings. Here
1953 @cindex headline levels
1954 @cindex section-numbers
1955 @cindex table of contents
1956 @cindex linebreak-preservation
1957 @cindex quoted html tags
1958 @cindex fixed-width sections
1960 @cindex @TeX{}-like syntax for sub- and superscripts
1961 @cindex emphasized text
1962 @cindex @TeX{} macros
1964 H: @r{set the number of headline levels for export}
1965 num: @r{turn on/off section-numbers}
1966 toc: @r{turn on/off table of contents}
1967 \n: @r{turn on/off linebreak-preservation}
1968 @@: @r{turn on/off quoted html tags}
1969 :: @r{turn on/off fixed-width sections}
1970 |: @r{turn on/off tables}
1971 ^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts.}
1972 *: @r{turn on/off emphasized text (bold, italic, underlined)}
1973 TeX: @r{turn on/off @TeX{} macros}
1976 @node Comment lines, , Export options, Exporting
1977 @section Comment lines
1978 @cindex comment lines
1979 @cindex exporting, not
1981 Lines starting with @samp{#} in column zero are treated as comments
1982 and will never be exported. Also entire subtrees starting with the
1983 word @samp{COMMENT} will never be exported. Finally, any text before
1984 the first headline will not be exported either.
1989 Toggle the COMMENT keyword at the beginning of an entry.
1992 @node Miscellaneous, Index, Exporting, Top
1993 @chapter Miscellaneous
1996 * Completion:: M-TAB knows what you need
1997 * Customization:: Adapting Org-mode to your taste
1998 * FAQ:: Frequently asked questions
1999 * Interaction:: Other Emacs packages
2000 * Bugs:: Things which do not work perfectly
2001 * Acknowledgments:: These people provided feedback and more
2004 @node Completion, Customization, Miscellaneous, Miscellaneous
2006 @cindex complete @TeX{} symbols
2007 @cindex complete TODO keywords
2008 @cindex complete dictionary words
2009 @cindex complete option keywords
2011 Org-mode supports in-buffer completion. This type of completion does
2012 not make use of the minibuffer. You simply type a few letters into
2013 the buffer and use the key to complete text right there.
2018 Complete word at point
2021 At the beginning of a headline, complete TODO keywords.
2023 After @samp{\}, complete @TeX{} symbols supported by the exporter.
2025 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
2026 @samp{OPTIONS} which set file-specific options for Org-mode. When the
2027 option keyword is already complete, pressing @kbd{M-@key{TAB}} again
2028 will insert example settings for this keyword.
2030 Elsewhere, complete dictionary words using ispell.
2034 @node Customization, FAQ, Completion, Miscellaneous
2035 @section Customization
2036 @cindex customization
2037 @cindex options, for customization
2038 @cindex variables, for customization
2040 There is a large number of variables which can be used to customize
2041 Org-mode. For the sake of compactness of the manual, we are not
2042 describing the variables here. For an overview of customization
2043 variables, use @kbd{M-x org-customize}. Or select @code{Browse Org
2044 Group} from the @code{Org->Customization} menu.
2046 @node FAQ, Interaction, Customization, Miscellaneous
2047 @section Frequently asked questions
2050 @item @b{Org-mode seems to be useful default mode for the various
2051 @file{README} files I have scattered through my directories. How do I
2052 turn it on for all @file{README} files?}
2054 (add-to-list 'auto-mode-alist '("README$" . org-mode))
2057 @item @b{I would like to have two windows on the same Org-mode
2058 file, but with different outline visibility. Is that possible?}@*
2059 @cindex @code{make-indirect-buffer}
2060 @cindex indirect buffers
2061 In GNU Emacs, you may use @emph{indirect buffers} which do exactly
2062 this. See the documentation on the command
2063 @code{make-indirect-buffer}. In XEmacs, this is currently not
2064 possible because of the different outline implementation.
2066 @item @b{Is there an easy way to insert links to web locations?}@*
2067 @cindex URL, paste into buffer
2068 Sure, just paste them into the buffer. A plain-text URL-like string
2069 is directly interpreted as a link.
2071 @item @b{When I export my TODO list, every TODO item becomes a
2072 separate section. How do I enforce these items to be exported as an
2074 If you plan to use ASCII or HTML export, make sure things you want to
2075 be exported as item lists are level 4 at least, even if that does mean
2076 there is a level jump. For example
2079 * Todays top priorities
2080 **** TODO write a letter to xyz
2081 **** TODO Finish the paper
2082 **** Pick up kids at the school
2085 Alternatively, if you need a specific value for the heading/item
2086 transition in a particular file, use the @samp{+OPTIONS} line to
2087 configure the @samp{H} switch.
2093 @item @b{I would like to export only a subtree of my file to HTML. How?}@*
2094 @cindex exporting a subtree
2095 If you want to export a subtree, mark the subtree as region and then
2096 export. Marking can be done with @kbd{C-c @@ C-x C-x}, for example.
2098 @item @b{Org-mode takes over the S-cursor keys. I also want to use
2099 CUA-mode, is there a way to fix this conflict?}@*
2100 Yes, see @ref{Interaction}
2102 @item @b{Is there an easy way to insert an empty table template with a
2103 default number of rows and columns?}@*
2104 @cindex table, empty template
2105 To insert an empty table template, just type @samp{|-} and use
2106 @key{TAB}. The default size can be changed with the variable
2107 @code{org-table-default-size}. However, just starting to type the
2108 first line is usually much easier.
2110 @item @b{When I am in the last column of a table and just above a
2111 horizontal line in the table, pressing TAB creates a new table line
2112 @i{before} the horizontal line. How can I quickly move to the line
2113 @i{below} the horizontal line instead?}@*
2114 Press @key{down} (to get on the separator line) and then @key{TAB}.
2116 @item @b{How can I change the indentation of an entire table without
2117 fixing every line by hand?}@*
2118 @cindex indentation, of tables
2119 The indentation of a table is set by the first line. So just fix the
2120 indentation of the first line and realign with @key{TAB}.
2125 @node Interaction, Bugs, FAQ, Miscellaneous
2126 @section Interaction with other packages
2127 @cindex packages, interaction with other
2128 @cindex @file{planner.el}
2129 @cindex @file{remember.el}
2130 @cindex @file{table.el}
2131 @file{Org.el} can cooperate with the following packages:
2134 @cindex @file{remember.el}
2135 @item @file{remember.el} by John Wiegley
2136 Org mode cooperates with remember, see @ref{Remember}.
2137 @cindex @file{plannner.el}
2138 @item @file{planner.el} by John Wiegley
2139 Planner is another tool to plan work and keep track of tasks. Planner
2140 uses a multi-file approach with project pages and day pages. Is based
2141 on Emacs-Wiki. It can be useful to display the agenda entries
2142 resulting from org files in day-pages of the planner. This can be
2143 done through the diary of the calendar: Integrate org files into the
2144 diary as described above, and then turn on the diary support of
2146 @cindex @file{table.el}
2147 @item @file{table.el} by Takaaki Ota
2148 Org mode cooperates with table.el, see @ref{table.el}.
2149 @cindex @file{CUA.el}
2150 @item @file{CUA.el} by Kim. F. Storm
2151 Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys
2152 used by CUA-mode (as well as pc-select-mode and s-region-mode) to
2153 select and extend the region. If you want to use one of these
2154 packages along with Org-mode, configure the variable
2155 @code{org-CUA-compatible}. When set, Org-mode will move the folowing
2156 keybindings in org-mode files, and in the agenda buffer (but not
2157 during date selection).
2159 S-UP -> M-p S-DOWN -> M-n
2160 S-LEFT -> M-- S-RIGHT -> M-+
2163 Yes, these are unfortunately more difficult to remember. If you want
2164 to have other replacement keys, look at the variable
2165 @code{org-disputed-keys}.
2169 @node Bugs, Acknowledgments, Interaction, Miscellaneous
2173 Here is a list of things which should work differently, but which I
2174 have found too hard to fix.
2178 If you call @code{fill-paragraph} (bound to @kbd{M-q}) in a table, the
2179 filling is correctly disabled. However, if some text directly
2180 (without an empty line in between) preceeds or follws a table, calling
2181 @code{fill-paragraph} in that text will also fill the table like
2182 normal text. Also, @code{fill-region} does bypass the
2183 @code{fill-paragraph} code and will fill tables like normal text.
2185 When the application called by @kbd{C-c C-o} to open a file link fails
2186 (for example because the application does not exits or refuses to open
2187 the file), it does so silently. No error message is displayed.
2189 Under XEmacs, if Org-mode entries are included into the diary, it is
2190 not possible to jump back from the diary to the org file. Apparently,
2191 the text properties are lost when the fancy-diary-display is used.
2192 However, from Org-mode's timeline and agenda buffers (created with
2193 @kbd{C-c C-r} and @kbd{C-c a}), things do work correctly.
2195 Linux should also have a default viewer application, using mailcap.
2196 Maybe we can use GNUS or VM mime code? Or dired's guessing commands?
2197 Any hints (or even patches) are appreciated.
2199 When you write @samp{x = a /b/ c}, b will be exported in italics.
2201 The exporters work well, but could be made more efficient.
2206 @node Acknowledgments, , Bugs, Miscellaneous
2207 @section Acknowledgments
2208 @cindex acknowledgments
2210 Org-mode was written by Carsten Dominik, who still maintains it at the
2211 Org-mode homepage @uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
2212 The following people have helped the development along with ideas,
2213 suggestions and patches.
2217 Matthias Rempe (Oelde) provided ideas and suggestions, a patch
2218 introducing Windows NT/2000 support, and quality control.
2220 Kevin Rogers contributed code to access VM files on remote hosts.
2222 Juergen Vollmer contributed code generating the table of contents
2223 in HTML output, and other export improvements.
2225 Christian Egli converted the documentation into TeXInfo format. He
2226 also showed me his plans for a multifile summary for Org-mode. Some of
2227 his ideas have found their way into the agenda.
2229 Philip Rooke created the Org-mode reference card. He also helped with
2230 beta testing and contributed a number of very useful ideas.
2232 Christian Schlauer proposed angular brackets around links, and some
2235 David Wainberg suggested to implement an archiving mechanism.
2237 Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
2238 @file{organizer-mode.el}.
2240 Scheduling TODO items was inspired by John Wiegley's @file{planner.el}.
2242 Sacha Chua, the current maintainer of Planner, offered linking code
2243 from Planner. I made use of the offer for links to RMAIL and Wanderlust.
2245 Oliver Oppitz sent several useful suggestions.
2247 Carsten Wimmer suggested some changes and helped fix a bug in linking
2250 Pavel Chalmoviansky reported bugs and suggested improvements related
2251 to the agenda treatment of items with specified time.
2253 Stefan Monnier provided a patch with lots of little fixes to keep the
2254 Emacs-Lisp compiler happy.
2256 Kai Grossjohann pointed out that a number of key bindings in Org-mode
2257 conflict with other packages.
2260 @node Index, Key Index, Miscellaneous, Top
2265 @node Key Index, , Index, Top
2274 arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac