3 @setfilename ../info/org
4 @settitle Org Mode Manual
11 * Org Mode: (org). outline-based notes management and organizer
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@@science.uva.nl}
19 @set MAINTAINERCONTACT @uref{mailto:dominik@@science.uva.nl,contact the maintainer}
25 @c Subheadings inside a table.
26 @macro tsubheading{text}
36 This manual is for Org-mode (version @value{VERSION}).
38 Copyright @copyright{} 2004, 2005, 2006 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 * 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
96 --- The Detailed Node Listing ---
100 * Summary:: Brief summary of what Org-mode does
101 * Installation:: How to install Org-mode
102 * Feedback:: Bug reports, ideas, patches etc.
106 * Outlines:: Org-mode is based on outline-mode
107 * Headlines:: How to typeset org-tree headlines
108 * Visibility cycling:: Show and hide, much simplified
109 * Motion:: Jumping to other headlines
110 * Structure editing:: Changing sequence and level of headlines
111 * Archiving:: Move done task trees to a different place
112 * Sparse trees:: Matches embedded in context
113 * Plain lists:: Editing hand-formatted lists
114 * Checkboxes:: Easily checking off things.
118 * ARCHIVE tag:: Marking a tree as inactive
119 * Moving subtrees:: Moving a tree to an archive file
123 * Built-in table editor:: Simple tables
124 * Narrow columns:: Stop wasting space in tables
125 * Table calculations:: Compute a field from other fields
126 * orgtbl-mode:: The table editor as minor mode
127 * table.el:: Complex tables
129 Calculations in tables
131 * Formula syntax:: How to write a formula
132 * Lisp formulas:: An alternative way to write formulas
133 * Column formulas:: Formulas valid for all fields in a column
134 * Advanced features:: Field names, parameters and automatic recalc
135 * Named-field formulas:: Formulas valid in single fields
136 * Editing/debugging formulas:: Changing a stored formula
137 * Appetizer:: Taste the power of calc
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 * Search options:: Linking to a specific location
146 * Custom searches:: When the default search is not enough
147 * Remember:: Org-trees store quick notes
151 * Radio targets:: Make targets trigger links in plain text.
152 * CamelCase links:: Activating CamelCase words as links
156 * TODO basics:: Marking and displaying TODO entries
157 * TODO extensions:: Workflow and assignments
158 * Priorities:: Some things are more important than others
160 Extended use of TODO keywords
162 * Workflow states:: From TODO to DONE in steps
163 * TODO types:: I do this, Fred the rest
164 * Per file keywords:: Different files, different requirements
168 * Time stamps:: Assigning a time to a tree entry
169 * Creating timestamps:: Commands which insert timestamps
170 * Progress logging:: Documenting when what work was done.
174 * Closing items:: When was this entry marked DONE?
175 * Clocking work time:: When exactly did you work on this item?
179 * Tag inheritance:: Tags use the tree structure of the outline
180 * Setting tags:: How to assign tags to a headline
181 * Tag searches:: Searching for combinations of tags
185 * Agenda files:: Files being searched for agenda information
186 * Agenda dispatcher:: Keyboard access to agenda views
187 * Weekly/Daily agenda:: The calendar page with current tasks
188 * Global TODO list:: All unfinished action items
189 * Matching headline tags:: Structured information with fine-tuned search
190 * Timeline:: Time-sorted view for single file
191 * Agenda commands:: Remote editing of org trees
193 The weekly/daily agenda
195 * Categories:: Not all tasks are equal
196 * Time-of-day specifications:: How the agenda knows the time
197 * Calendar/Diary integration:: Integrating Anniversaries and more
198 * Sorting of agenda items:: The order of things
202 * Math symbols:: TeX macros for symbols and Greek letters
203 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
204 * LaTeX fragments:: Complex formulas made easy
205 * Processing LaTeX fragments:: Previewing LaTeX processing
206 * CDLaTeX mode:: Speed up entering of formulas
210 * ASCII export:: Exporting to plain ASCII
211 * HTML export:: Exporting to HTML
212 * XOXO export:: Exporting to XOXO
213 * iCalendar export:: Exporting in iCalendar format
214 * Text interpretation:: How the exporter looks at the file
216 Text interpretation by the exporter
218 * Comment lines:: Some lines will not be exported
219 * Enhancing text:: Subscripts, symbols and more
220 * Export options:: How to influence the export settings
224 * Configuration:: Defining projects
225 * Sample configuration:: Example projects
226 * Triggering publication:: Publication commands
230 * Project alist:: The central configuration variable
231 * Sources and destinations:: From here to there
232 * Selecting files:: What files are part of the project?
233 * Publishing action:: Setting the function doing the publishing
234 * Publishing options:: Tweaking HTML export
235 * Publishing links:: Which links keep working after publishing?
236 * Project page index:: Publishing a list of project files
240 * Simple example:: One-component publishing
241 * Complex example:: A multi-component publishing example
245 * Completion:: M-TAB knows what you need
246 * Customization:: Adapting Org-mode to your taste
247 * In-buffer settings:: Overview of the #+KEYWORDS
248 * The very busy C-c C-c key:: When in doubt, press C-c C-c
249 * Clean view:: Getting rid of leading stars in the outline
250 * TTY keys:: Using Org-mode on a tty
251 * Interaction:: Other Emacs packages
252 * Bugs:: Things which do not work perfectly
254 Interaction with other packages
256 * Cooperation:: Packages Org-mode cooperates with
257 * Conflicts:: Packages that lead to conflicts
259 Extensions, Hooks and Hacking
261 * Extensions:: Existing 3rd-part extensions
262 * Dynamic blocks:: Automatically filled blocks
267 @node Introduction, Document structure, Top, Top
268 @chapter Introduction
272 * Summary:: Brief summary of what Org-mode does
273 * Installation:: How to install Org-mode
274 * Feedback:: Bug reports, ideas, patches etc.
277 @node Summary, Installation, Introduction, Introduction
281 Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
282 project planning with a fast and effective plain-text system.
284 Org-mode develops organizational tasks around NOTES files that contain
285 information about projects as plain text. Org-mode is implemented on
286 top of outline-mode, which makes it possible to keep the content of
287 large files well structured. Visibility cycling and structure editing
288 help to work with the tree. Tables are easily created with a built-in
289 table editor. Org-mode supports ToDo items, deadlines, time stamps,
290 and scheduling. It dynamically compiles entries into an agenda that
291 utilizes and smoothly integrates much of the Emacs calendar and diary.
292 Plain text URL-like links connect to websites, emails, Usenet
293 messages, BBDB entries, and any files related to the projects. For
294 printing and sharing of notes, an Org-mode file can be exported as a
295 structured ASCII file, as HTML, or (todo and agenda items only) as an
296 iCalendar file. It can also serve as a publishing tool for a set of
299 Org-mode keeps simple things simple. When first fired up, it should
300 feel like a straightforward, easy to use outliner. Complexity is not
301 imposed, but a large amount of functionality is available when you need
302 it. Org-mode can be used on different levels and in different ways, for
306 @r{@bullet{} as an outline extension with visibility cycling and structure editing}
307 @r{@bullet{} as an ASCII system and table editor for taking structured notes}
308 @r{@bullet{} as an ASCII table editor with spreadsheet-like capabilities}
309 @r{@bullet{} as a TODO list editor}
310 @r{@bullet{} as a full agenda and planner with deadlines and work scheduling}
311 @r{@bullet{} as a simple hypertext system, with HTML export}
312 @r{@bullet{} as a publishing tool to create a set of interlinked webpages}
315 The Org-mode table editor can be integrated into any major mode by
316 activating the minor Orgtbl-mode.
319 There is a website for Org-mode which provides links to the newest
320 version of Org-mode, as well as additional information, frequently asked
321 questions (FAQ), links to tutorials etc. This page is located at
322 @uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
326 @node Installation, Feedback, Summary, Introduction
327 @section Installation and Activation
330 @cindex global keybindings
331 @cindex keybindings, global
333 If Org-mode is part of the Emacs distribution or an XEmacs package,
334 you only need to copy the following lines to your @file{.emacs} file.
335 The last two lines define @emph{global} keys for the commands
336 @command{org-store-link} and @command{org-agenda} - please
337 choose suitable keys yourself.
340 ;; The following lines are always needed. Choose your own keys.
341 (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
342 (define-key global-map "\C-cl" 'org-store-link)
343 (define-key global-map "\C-ca" 'org-agenda)
346 Furthermore, you must activate @code{font-lock-mode} in org-mode
347 buffers, because significant functionality depends on font-locking being
348 active. You can do this with either one of the following two lines:
350 (global-font-lock-mode 1) ; for all buffers
351 (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
354 If you have downloaded Org-mode from the Web, you must take additional
355 action: Byte-compile @file{org.el} and @file{org-publish.el} and put
356 them together with @file{org-install.el} on your load path. Then add to
360 ;; This line only if org-mode is not part of the X/Emacs distribution.
361 (require 'org-install)
364 If you use Org-mode with XEmacs, you also need to install the file
365 @file{noutline.el} from the @file{xemacs} subdirectory of the Org-mode
368 @cindex org-mode, turning on
369 With this setup, all files with extension @samp{.org} will be put into
370 Org-mode. As an alternative, make the first line of a file look like
374 MY PROJECTS -*- mode: org; -*-
377 @noindent which will select Org-mode for this buffer no matter what
378 the file's name is. See also the variable
379 @code{org-insert-mode-line-in-empty-file}.
381 @node Feedback, , Installation, Introduction
388 If you find problems with Org-mode, or if you have questions, remarks,
389 or ideas about it, please contact the maintainer @value{MAINTAINER} at
390 @value{MAINTAINEREMAIL}.
392 For bug reports, please provide as much information as possible,
393 including the version information of Emacs (@kbd{C-h v emacs-version
394 @key{RET}}) and Org-mode (@kbd{C-h v org-version @key{RET}}), as well as
395 the Org-mode related setup in @file{.emacs}. If an error occurs, a
396 traceback can be very useful. Often a small example file helps, along
397 with clear information about:
400 @item What exactly did you do?
401 @item What did you expect to happen?
402 @item What happened instead?
404 @noindent Thank you for helping to improve this mode.
406 @node Document structure, Tables, Introduction, Top
407 @chapter Document Structure
408 @cindex document structure
409 @cindex structure of document
411 Org-mode is based on outline mode and provides flexible commands to
412 edit the structure of the document.
415 * Outlines:: Org-mode is based on outline-mode
416 * Headlines:: How to typeset org-tree headlines
417 * Visibility cycling:: Show and hide, much simplified
418 * Motion:: Jumping to other headlines
419 * Structure editing:: Changing sequence and level of headlines
420 * Archiving:: Move done task trees to a different place
421 * Sparse trees:: Matches embedded in context
422 * Plain lists:: Editing hand-formatted lists
423 * Checkboxes:: Easily checking off things.
426 @node Outlines, Headlines, Document structure, Document structure
431 Org-mode is implemented on top of outline-mode. Outlines allow to
432 organize a document in a hierarchical structure, which (at least for
433 me) is the best representation of notes and thoughts. Overview over
434 this structure is achieved by folding (hiding) large parts of the
435 document to show only the general document structure and the parts
436 currently being worked on. Org-mode greatly simplifies the use of
437 outlines by compressing the entire show/hide functionality into a
438 single command @command{org-cycle}, which is bound to the @key{TAB}
441 @node Headlines, Visibility cycling, Outlines, Document structure
446 Headlines define the structure of an outline tree. The headlines in
447 Org-mode start with one or more stars, on the left margin. For
457 * Another top level headline
460 @noindent Some people find the many stars too noisy and would prefer an
461 outline that has whitespace followed by a single star as headline
462 starters. @ref{Clean view} describes a setup to realize this.
464 @node Visibility cycling, Motion, Headlines, Document structure
465 @section Visibility cycling
466 @cindex cycling, visibility
467 @cindex visibility cycling
468 @cindex trees, visibility
469 @cindex show hidden text
472 Outlines make it possible to hide parts of the text in the buffer.
473 Org-mode uses just two commands, bound to @key{TAB} and
474 @kbd{S-@key{TAB}} to change the visibility in the buffer.
476 @cindex subtree visibility states
477 @cindex subtree cycling
478 @cindex folded, subtree visibility state
479 @cindex children, subtree visibility state
480 @cindex subtree, subtree visibility state
484 @emph{Subtree cycling}: Rotate current subtree between the states
487 ,-> FOLDED -> CHILDREN -> SUBTREE --.
488 '-----------------------------------'
491 The cursor must be on a headline for this to work@footnote{see, however,
492 the option @code{org-cycle-emulate-tab}.}. When the cursor is at the
493 beginning of the buffer and the first line is not a headline, then
494 @key{TAB} actually runs global cycling (see below)@footnote{see the
495 option @code{org-cycle-global-at-bob}.}. Also when called with a prefix
496 argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
498 @cindex global visibility states
499 @cindex global cycling
500 @cindex overview, global visibility state
501 @cindex contents, global visibility state
502 @cindex show all, global visibility state
506 @emph{Global cycling}: Rotate the entire buffer between the states
509 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
510 '--------------------------------------'
513 Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.
515 @cindex show all, command
521 When Emacs first visits an Org-mode file, the global state is set to
522 OVERVIEW, i.e. only the top level headlines are visible. This can be
523 configured through the variable @code{org-startup-folded}, or on a
524 per-file basis by adding one of the following lines anywhere in the
533 @node Motion, Structure editing, Visibility cycling, Document structure
535 @cindex motion, between headlines
536 @cindex jumping, to headlines
537 @cindex headline navigation
538 The following commands jump to other headlines in the buffer.
549 Next heading same level.
552 Previous heading same level.
555 Backward to higher level heading.
558 Jump to a different place without changing the current outline
559 visibility. Shows the document structure in a temporary buffer, where
560 you can use visibility cycling (@key{TAB}) to find your destination.
561 After pressing @key{RET}, the cursor moves to the selected location in
562 the original buffer, and the headings hierarchy above it is made
566 @node Structure editing, Archiving, Motion, Document structure
567 @section Structure editing
568 @cindex structure editing
569 @cindex headline, promotion and demotion
570 @cindex promotion, of subtrees
571 @cindex demotion, of subtrees
572 @cindex subtree, cut and paste
573 @cindex pasting, of subtrees
574 @cindex cutting, of subtrees
575 @cindex copying, of subtrees
576 @cindex subtrees, cut and paste
581 Insert new heading with same level as current. If the cursor is in a
582 plain list item, a new item is created (@pxref{Plain lists}). To force
583 creation of a new headline, use a prefix arg, or first press @key{RET}
584 to get to the beginning of the next line. When this command is used in
585 the middle of a line, the line is split and the rest of the line becomes
586 the new headline. If the command is used at the beginning of a
587 headline, the new headline is created before the current line. If at
588 the beginning of any other line, the content of that line is made the
590 @kindex M-S-@key{RET}
592 Insert new TODO entry with same level as current heading.
595 Promote current heading by one level.
596 @kindex M-@key{right}
598 Demote current heading by one level.
599 @kindex M-S-@key{left}
601 Promote the current subtree by one level.
602 @kindex M-S-@key{right}
603 @item M-S-@key{right}
604 Demote the current subtree by one level.
607 Move subtree up (swap with previous subtree of same
609 @kindex M-S-@key{down}
611 Move subtree down (swap with next subtree of same level).
616 Kill subtree, i.e. remove it from buffer but save in kill ring.
619 Copy subtree to kill ring.
622 Yank subtree from kill ring. This does modify the level of the subtree to
623 make sure the tree fits in nicely at the yank position. The yank
624 level can also be specified with a prefix arg, or by yanking after a
625 headline marker like @samp{****}.
628 @cindex region, active
629 @cindex active region
630 @cindex transient-mark-mode
631 When there is an active region (transient-mark-mode), promotion and
632 demotion work on all headlines in the region. To select a region of
633 headlines, it is best to place both point and mark at the beginning of a
634 line, mark at the beginning of the first headline, and point at the line
635 just after the last headline to change. Note that when the cursor is
636 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
639 @node Archiving, Sparse trees, Structure editing, Document structure
643 When a project represented by a (sub)tree is finished, you may want
644 to move the tree out of the way and to stop it from contributing to the
645 agenda. Org-mode knows two ways of archiving. You can mark a tree with
646 the ARCHIVE tag, or you can move an entire (sub)tree to a different
650 * ARCHIVE tag:: Marking a tree as inactive
651 * Moving subtrees:: Moving a tree to an archive file
654 @node ARCHIVE tag, Moving subtrees, Archiving, Archiving
655 @subsection The ARCHIVE tag
656 @cindex internal archiving
658 A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
659 its location in the outline tree, but behaves in the following way:
662 It does not open when you attempt to do so with a visibility cycling
663 command (@pxref{Visibility cycling}). You can still open it with a
664 normal outline command like @code{show-all}. Or you can modify the
665 option @code{org-cycle-open-archived-trees}.
667 During sparse tree construction (@pxref{Sparse trees}), matches in
668 archived subtrees are not exposed, unless you configure the option
669 @code{org-sparse-tree-open-archived-trees}.
671 During agenda view construction (@pxref{Agenda views}), the content of
672 archived trees is ignored unless you configure the option
673 @code{org-agenda-skip-archived-trees}.
675 Archived trees are not exported (@pxref{Exporting}), only the headline
676 is. Configure the details using the variable
677 @code{org-export-with-archived-trees}.
680 The following commands allow to set or clear the ARCHIVE tag:
685 Toggle the ARCHIVE tag for the current headline. When the tag is set,
686 the headline changes to a shadowish face, and the subtree below it is
688 @kindex C-u C-c C-x C-a
689 @item C-u C-c C-x C-a
690 Check if any direct children of the current headline should be archived.
691 To do this, each subtree is checked for open TODO entries. If none are
692 found, the command offers to set the ARCHIVE tag for the child. If the
693 cursor is @emph{not} on a headline when this command is invoked, the
694 level 1 trees will be checked.
697 @node Moving subtrees, , ARCHIVE tag, Archiving
698 @subsection Moving subtrees
699 @cindex external archiving
701 Once an entire project is finished, you may want to move it to a
702 different location, either in the current file, or even in a different
703 file, the archive file.
708 Archive the subtree starting at the cursor position to the location
709 given by @code{org-archive-location}.
712 Check if any direct children of the current headline could be moved to
713 the archive. To do this, each subtree is checked for open TODO entries.
714 If none are found, the command offers to move it to the archive
715 location. If the cursor is @emph{not} on a headline when this command
716 is invoked, the level 1 trees will be checked.
719 @cindex archive locations
720 The default archive location is a file in the same directory as the
721 current file, with the name derived by appending @file{_archive} to the
722 current file name. For information and examples on how to change this,
723 see the documentation string of the variable
724 @code{org-archive-location}.
726 @node Sparse trees, Plain lists, Archiving, Document structure
727 @section Sparse trees
729 @cindex trees, sparse
730 @cindex folding, sparse trees
731 @cindex occur, command
733 An important feature of Org-mode is the ability to construct
734 @emph{sparse trees} for selected information in an outline tree. A
735 sparse tree means that the entire document is folded as much as
736 possible, but the selected information is made visible along with the
737 headline structure above it@footnote{See also the variables
738 @code{org-show-hierarchy-above} and
739 @code{org-show-following-heading}.}. Just try it out and you will see
740 immediately how it works.
742 Org-mode contains several commands creating such trees. The most
743 basic one is @command{org-occur}:
748 Occur. Prompts for a regexp and shows a sparse tree with all matches.
749 If the match is in a headline, the headline is made visible. If the
750 match is in the body of an entry, headline and body are made visible.
751 In order to provide minimal context, also the full hierarchy of
752 headlines above the match is shown, as well as the headline following
753 the match. Each match is also highlighted; the highlights disappear
754 when the buffer is changed with an editing command.
757 For frequently used sparse trees of specific search strings, you can
758 use the variable @code{org-agenda-custom-commands} to define fast
759 keyboard access to specific sparse trees. These commands will then be
760 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
764 (setq org-agenda-custom-commands
765 '(("f" occur-tree "FIXME")))
768 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
769 a sparse tree matching the string @samp{FIXME}.
771 Other commands use sparse trees as well. For example @kbd{C-c
772 C-v} creates a sparse TODO tree (@pxref{TODO basics}).
775 @cindex printing sparse trees
776 @cindex visible text, printing
777 To print a sparse tree, you can use the Emacs command
778 @code{ps-print-buffer-with-faces} which does not print invisible parts
779 of the document @footnote{This does not work under XEmacs, because
780 XEmacs uses selective display for outlining, not text properties.}.
781 Or you can use the command @kbd{C-c C-x v} to export only the visible
782 part of the document and print the resulting file.
785 @node Plain lists, Checkboxes, Sparse trees, Document structure
789 @cindex lists, ordered
790 @cindex ordered lists
792 Headlines define both the structure of the Org-mode file, and also lists
793 (for example, TODO items (@pxref{TODO items}) should be created using
794 headline levels). When taking notes, however, the plain text is
795 sometimes easier to read with hand-formatted lists. Org-mode supports
796 editing such lists, and the HTML exporter (@pxref{Exporting}) does
797 parse and format them.
799 Org-mode knows ordered and unordered lists. Unordered list items start
800 with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a
801 bullet, lines must be indented or they will be seen as top-level
802 headlines. Also, when you are hiding leading stars to get a clean
803 outline view, plain list items starting with a star are visually
804 indistinguishable from true headlines. In short: even though @samp{*}
805 is supported, it may be better not to use it for plain list items} as
806 bullets. Ordered list items start with @samp{1.} or @samp{1)}. Items
807 belonging to the same list must have the same indentation on the first
808 line. In particular, if an ordered list reaches number @samp{10.}, then
809 the 2--digit numbers must be written left-aligned with the other numbers
810 in the list. Indentation also determines the end of a list item. It
811 ends before the next line that is indented like the bullet/number, or
817 My favorite scenes are (in this order)
818 1. Eowyns fight with the witch king
819 + this was already my favorite scene in the book
820 + I really like Miranda Otto.
821 2. The attack of the Rohirrim
822 3. Peter Jackson being shot by Legolas
824 He makes a really funny face when it happens.
825 But in the end, not individual scenes matter but the film as a whole.
829 Org-mode supports these lists by tuning filling and wrapping commands
830 to deal with them correctly.
832 The following commands act on items when the cursor is in the first line
833 of an item (the line with the bullet or number).
838 Items can be folded just like headline levels if you set the variable
839 @code{org-cycle-include-plain-lists}. The level of an item is then
840 given by the indentation of the bullet/number. Items are always
841 subordinate to real headlines, however; the hierarchies remain
842 completely separated.
845 Insert new item at current level. With prefix arg, force a new heading
846 (@pxref{Structure editing}). If this command is used in the middle of a
847 line, the line is @emph{split} and the rest of the line becomes the new
848 item. If this command is executed in the @emph{whitespace before a bullet or
849 number}, the new item is created @emph{before} the current item. If the
850 command is executed in the white space before the text that is part of
851 an item but does not contain the bullet, a bullet is added to the
853 @kindex M-S-@key{RET}
855 Insert a new item with a checkbox (@pxref{Checkboxes}).
860 Jump to the previous/next item in the current list.
862 @kindex M-S-@key{down}
864 @itemx M-S-@key{down}
865 Move the item including subitems up/down (swap with previous/next item
866 of same indentation). If the list is ordered, renumbering is
868 @kindex M-S-@key{left}
869 @kindex M-S-@key{right}
871 @itemx M-S-@key{right}
872 Decrease/increase the indentation of the item, including subitems.
873 Initially, the item tree is selected based on current indentation.
874 When these commands are executed several times in direct succession,
875 the initially selected region is used, even if the new indentation
876 would imply a different hierarchy. To use the new hierarchy, break
877 the command chain with a cursor motion or so.
880 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
881 state of the checkbox. Otherwise, if this is an ordered list, renumber
882 the ordered list at the cursor.
886 @node Checkboxes, , Plain lists, Document structure
890 Every item in a plain list (ordered and unordered) can be made a
891 checkbox by starting it with the string @samp{[ ]}. This feature is
892 similar to TODO items (@pxref{TODO items}), but more lightweight.
893 Checkboxes are not included into the global TODO list, so they are often
894 great to split a task into a number of simple steps. Or you can use
895 them in a shopping list to select the items you need to buy. To toggle
896 a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's
897 @file{org-mouse.el}. Here is an example of a checkbox list.
900 * Avoid stupid mistakes when distributing a new version
901 - [ ] update also Emacs CVS
902 - [X] forget to update index.html on the website
903 - [X] leaving a `(debug)' form in the code
906 @noindent The following commands work with checkboxes:
911 Toggle checkbox at point.
914 Toggle checkbox at point.
917 If there is an active region, toggle the first checkbox in the region
918 and set all remaining boxes to the same status as the first. If you
919 want to toggle all boxes in the region independently, use a prefix
922 If the cursor is in a headline, toggle checkboxes in the region between
923 this headline and the next. This does @emph{not} act on the entire
924 subtree, just the current entry.
926 If no active region, just toggle the checkbox at point.
928 @kindex M-S-@key{RET}
930 Insert a new item with a checkbox.
931 This works only if the cursor is already in a plain list item
932 (@pxref{Plain lists}).
935 @node Tables, Hyperlinks, Document structure, Top
938 @cindex editing tables
940 Org-mode has a very fast and intuitive table editor built-in.
941 Spreadsheet-like calculations are supported in connection with the
942 Emacs @file{calc} package.
945 * Built-in table editor:: Simple tables
946 * Narrow columns:: Stop wasting space in tables
947 * Table calculations:: Compute a field from other fields
948 * orgtbl-mode:: The table editor as minor mode
949 * table.el:: Complex tables
952 @node Built-in table editor, Narrow columns, Tables, Tables
953 @section The built-in table editor
954 @cindex table editor, builtin
956 Org-mode makes it easy to format tables in plain ASCII. Any line with
957 @samp{|} as the first non-white character is considered part of a
958 table. @samp{|} is also the column separator. A table might look
962 | Name | Phone | Age |
963 |-------+-------+-----|
964 | Peter | 1234 | 17 |
968 A table is re-aligned automatically each time you press @key{TAB} or
969 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
970 the next field (@key{RET} to the next row) and creates new table rows
971 at the end of the table or before horizontal lines. The indentation
972 of the table is set by the first line. Any line starting with
973 @samp{|-} is considered as a horizontal separator line and will be
974 expanded on the next re-align to span the whole table width. So, to
975 create the above table, you would only type
982 @noindent and then press @key{TAB} to align the table and start filling in
985 When typing text into a field, Org-mode treats @key{DEL},
986 @key{Backspace}, and all character keys in a special way, so that
987 inserting and deleting avoids shifting other fields. Also, when
988 typing @emph{immediately after the cursor was moved into a new field
989 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
990 field is automatically made blank. If this behavior is too
991 unpredictable for you, configure the variables
992 @code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
995 @tsubheading{Creation and conversion}
998 Convert the active region to table. If every line contains at least one
999 TAB character, the function assumes that the material is tab separated.
1000 If not, lines are split at whitespace into fields. You can use a prefix
1001 argument to indicate the minimum number of consecutive spaces required
1002 to identify a field separator (default: just one).@*
1003 If there is no active region, this command creates an empty Org-mode
1004 table. But it's easier just to start typing, like
1005 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
1007 @tsubheading{Re-aligning and field motion}
1010 Re-align the table without moving the cursor.
1014 Re-align the table, move to the next field. Creates a new row if
1019 Re-align, move to previous field.
1023 Re-align the table and move down to next row. Creates a new row if
1024 necessary. At the beginning or end of a line, @key{RET} still does
1025 NEWLINE, so it can be used to split a table.
1027 @tsubheading{Column and row editing}
1028 @kindex M-@key{left}
1029 @kindex M-@key{right}
1031 @itemx M-@key{right}
1032 Move the current column left/right.
1034 @kindex M-S-@key{left}
1035 @item M-S-@key{left}
1036 Kill the current column.
1038 @kindex M-S-@key{right}
1039 @item M-S-@key{right}
1040 Insert a new column to the left of the cursor position.
1043 @kindex M-@key{down}
1046 Move the current row up/down.
1048 @kindex M-S-@key{up}
1050 Kill the current row or horizontal line.
1052 @kindex M-S-@key{down}
1053 @item M-S-@key{down}
1054 Insert a new row above (with arg: below) the current row.
1058 Insert a horizontal line below current row. With prefix arg, the line
1059 is created above the current line.
1063 Sort the table lines in the region. Point and mark must be in the first
1064 and last line to be included, and must be in the column that should be
1065 used for sorting. The command prompts for numerical versus
1066 alphanumerical sorting.
1068 @tsubheading{Regions}
1071 Copy a rectangular region from a table to a special clipboard. Point
1072 and mark determine edge fields of the rectangle. The process ignores
1073 horizontal separator lines.
1076 Copy a rectangular region from a table to a special clipboard, and
1077 blank all fields in the rectangle. So this is the ``cut'' operation.
1080 Paste a rectangular region into a table.
1081 The upper right corner ends up in the current field. All involved fields
1082 will be overwritten. If the rectangle does not fit into the present table,
1083 the table is enlarged as needed. The process ignores horizontal separator
1087 Wrap several fields in a column like a paragraph. If there is an active
1088 region, and both point and mark are in the same column, the text in the
1089 column is wrapped to minimum width for the given number of lines. A
1090 prefix ARG may be used to change the number of desired lines. If there
1091 is no region, the current field is split at the cursor position and the
1092 text fragment to the right of the cursor is prepended to the field one
1093 line down. If there is no region, but you specify a prefix ARG, the
1094 current field is made blank, and the content is appended to the field
1097 @tsubheading{Calculations}
1098 @cindex formula, in tables
1099 @cindex calculations, in tables
1102 Install a new formula for the current column and replace current field
1103 with the result of the formula.
1107 Install a new formula for the current field, which must be a named
1108 field. Evaluate the formula and replace the field content with the
1113 Edit all formulas associated with the current table in a separate
1118 Recalculate the current row by applying the stored formulas from left
1119 to right. When called with a @kbd{C-u} prefix, recalculate the
1120 entire table, starting with the first non-header line (i.e. below the
1121 first horizontal separator line). For details, see @ref{Table calculations}.
1125 Rotate the calculation mark in first column through the states
1126 @samp{}, @samp{#}, @samp{*}, @samp{!}, @samp{$}. For the meaning of
1127 these marks see @ref{Advanced features}. When there is an active
1128 region, change all marks in the region.
1132 Which table column is the cursor in? Displays number >0 in echo
1135 @cindex region, active
1136 @cindex active region
1137 @cindex transient-mark-mode
1140 Sum the numbers in the current column, or in the rectangle defined by
1141 the active region. The result is shown in the echo area and can
1142 be inserted with @kbd{C-y}.
1146 When current field is empty, copy from first non-empty field above.
1147 When not empty, copy current field down to next row and move cursor
1148 along with it. Depending on the variable
1149 @code{org-table-copy-increment}, integer field values will be
1150 incremented during copy. This key is also used by CUA-mode
1151 (@pxref{Cooperation}).
1153 @tsubheading{Miscellaneous}
1156 Edit the current field in a separate window. This is useful for fields
1157 that are not fully visible (@pxref{Narrow columns}). When called with a
1158 @kbd{C-u} prefix, just make the full field visible, so that it can be
1161 @kindex C-c @key{TAB}
1163 This is an alias for @kbd{C-u C-c `} to make the current field fully
1166 @item M-x org-table-import
1167 Import a file as a table. The table should be TAB- or whitespace
1168 separated. Useful, for example, to import an Excel table or data from a
1169 database, because these programs generally can write TAB-separated text
1170 files. This command works by inserting the file into the buffer and
1171 then converting the region to a table. Any prefix argument is passed on
1172 to the converter, which uses it to determine the separator.
1174 @item M-x org-table-export
1175 Export the table as a TAB-separated file. Useful for data exchange with,
1176 for example, Excel or database programs.
1180 If you don't like the automatic table editor because it gets in your
1181 way on lines which you would like to start with @samp{|}, you can turn
1185 (setq org-enable-table-editor nil)
1188 @noindent Then the only table command that still works is
1189 @kbd{C-c C-c} to do a manual re-align.
1191 @node Narrow columns, Table calculations, Built-in table editor, Tables
1192 @section Narrow columns
1193 @cindex narrow columns in tables
1195 The width of columns is automatically determined by the table editor.
1196 Sometimes a single field or a few fields need to carry more text,
1197 leading to inconveniently wide columns. To limit@footnote{This feature
1198 does not work on XEmacs.} the width of a column, one field anywhere in
1199 the column may contain just the string @samp{<N>} where @samp{N} is an
1200 integer specifying the width of the column in characters. The next
1201 re-align will then set the width of this column to no more than this
1205 |---+------------------------------| |---+--------|
1207 | 1 | one | | 1 | one |
1208 | 2 | two | ----\ | 2 | two |
1209 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1210 | 4 | four | | 4 | four |
1211 |---+------------------------------| |---+--------|
1215 Fields that are wider become clipped and end in the string @samp{=>}.
1216 Note that the full text is still in the buffer, it is only invisible.
1217 To see the full text, hold the mouse over the field - a tooltip window
1218 will show the full content. To edit such a field, use the command
1219 @kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will
1220 open a new window with the full field. Edit it and finish with @kbd{C-c
1223 When visiting a file containing a table with narrowed columns, the
1224 necessary character hiding has not yet happened, and the table needs to
1225 be aligned before it looks nice. Setting the option
1226 @code{org-startup-align-all-tables} will realign all tables in a file
1227 upon visiting, but also slow down startup. You can also set this option
1228 on a per-file basis with:
1235 @node Table calculations, orgtbl-mode, Narrow columns, Tables
1236 @section Calculations in tables
1237 @cindex calculations, in tables
1238 @cindex spreadsheet capabilities
1239 @cindex @file{calc} package
1241 The table editor makes use of the Emacs @file{calc} package to implement
1242 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1243 derive fields from other fields. Org-mode has two levels of complexity
1244 for table calculations. On the basic level, tables do only horizontal
1245 computations, so a field can be computed from other fields @emph{in the
1246 same row}, and Org-mode assumes that there is only one formula for each
1247 column. This is very efficient to work with and enough for many tasks.
1248 On the complex level, columns and individual fields can be named for
1249 easier referencing in formulas, individual named fields can have their
1250 own formula associated with them, and recalculation can be automated.
1253 * Formula syntax:: How to write a formula
1254 * Lisp formulas:: An alternative way to write formulas
1255 * Column formulas:: Formulas valid for all fields in a column
1256 * Advanced features:: Field names, parameters and automatic recalc
1257 * Named-field formulas:: Formulas valid in single fields
1258 * Editing/debugging formulas:: Changing a stored formula
1259 * Appetizer:: Taste the power of calc
1262 @node Formula syntax, Lisp formulas, Table calculations, Table calculations
1263 @subsection Formula syntax
1264 @cindex formula syntax
1265 @cindex syntax, of formulas
1267 A formula can be any algebraic expression understood by the Emacs
1268 @file{calc} package. Note that @file{calc} has the slightly
1269 non-standard convention that @samp{/} has lower precedence than
1270 @samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}. Before
1271 evaluation by @code{calc-eval} (@pxref{Calling Calc from Your
1272 Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU Emacs
1273 Calc Manual}), variable substitution takes place:
1276 $ @r{refers to the current field}
1277 $3 @r{refers to the field in column 3 of the current row}
1278 $3..$7 @r{a vector of the fields in columns 3-7 of current row}
1279 $P1..$P3 @r{vector of column range, using column names}
1280 &2 @r{second data field above the current, in same column}
1281 &5-2 @r{vector from fifth to second field above current}
1282 &III-II @r{vector of fields between 2nd and 3rd hline above}
1283 &III @r{vector of fields between third hline above and current field}
1284 $name @r{a named field, parameter or constant}
1287 @cindex vectors, in table calculations
1288 The range vectors can be directly fed into the calc vector functions
1289 like @samp{vmean} and @samp{vsum}.
1291 @cindex name, of column or field
1292 @cindex constants, in calculations
1293 @samp{$name} is interpreted as the name of a column, parameter or
1294 constant. Constants are defined globally through the variable
1295 @code{org-table-formula-constants}. If you have the
1296 @file{constants.el} package, it will also be used to resolve
1297 constants, including natural constants like @samp{$h} for Planck's
1298 constant, and units like @samp{$km} for kilometers. Column names and
1299 parameters can be specified in special table lines. These are
1300 described below, see @ref{Advanced features}.
1302 @cindex format specifier
1303 @cindex mode, for @file{calc}
1304 A formula can contain an optional mode string after a semicolon. This
1305 string consists of flags to influence calc's modes@footnote{By
1306 default, Org-mode uses the standard calc modes (precision 12, angular
1307 units degrees, fraction and symbolic modes off). The display format,
1308 however, has been changed to @code{(float 5)} to keep tables compact.
1309 The default settings can be configured using the variable
1310 @code{org-calc-default-modes}.} during execution, e.g. @samp{p20} to
1311 switch the internal precision to 20 digits, @samp{n3}, @samp{s3},
1312 @samp{e2} or @samp{f4} to switch to normal, scientific, engineering,
1313 or fixed display format, respectively, and @samp{D}, @samp{R}, @samp{F},
1314 and @samp{S} to turn on degrees, radians, fraction and symbolic modes,
1315 respectively. In addition, you may provide a @code{printf} format
1316 specifier to reformat the final result. A few examples:
1319 $1+$2 @r{Sum of first and second field}
1320 $1+$2;%.2f @r{Same, format result to two decimals}
1321 exp($2)+exp($1) @r{Math functions can be used}
1322 $;%.1f @r{Reformat current cell to 1 decimal}
1323 ($3-32)*5/9 @r{Degrees F -> C conversion}
1324 $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
1325 tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
1326 sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
1327 vmean($2..$7) @r{Compute column range mean, using vector function}
1328 vsum(&III) @r{Sum numbers from 3rd hline above, up to here}
1329 taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree}
1332 @node Lisp formulas, Column formulas, Formula syntax, Table calculations
1333 @subsection Emacs Lisp forms as formulas
1334 @cindex Lisp forms, as table formulas
1336 It is also possible to write a formula in Emacs lisp; this can be useful
1337 for string manipulation and control structures. If a formula starts
1338 with a single quote followed by an opening parenthesis, then it is
1339 evaluated as a lisp form. The evaluation should return either a string
1340 or a number. Just as with @file{calc} formulas, you can provide a
1341 format specifier after a semicolon. A few examples:
1344 @r{swap the first two characters of the content of column 1}
1345 '(concat (substring "$1" 1 2) (substring "$1" 0 1) (substring "$1" 2))
1346 @r{Add columns 1 and 2, equivalent to the calc's @code{$1+$2}}
1350 @node Column formulas, Advanced features, Lisp formulas, Table calculations
1351 @subsection Column formulas
1352 @cindex column formula
1353 @cindex formula, for table column
1355 To apply a formula to a field, type it directly into the field,
1356 preceded by an equal sign, like @samp{=$1+$2}. When you press
1357 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the
1358 field, the formula will be stored as the formula for the current
1359 column, evaluated and the current field replaced with the result. If
1360 the field contains only @samp{=}, the previously stored formula for
1361 this column is used.
1363 For each column, Org-mode will remember the most recently used
1364 formula. The information is stored in a special line starting with
1365 @samp{#+TBLFM} directly below the table. When adding/deleting/moving
1366 columns with the appropriate commands, the stored equations will be
1367 modified accordingly. When a column used in a calculation is removed,
1368 references to this column become invalid and will cause an error upon
1369 applying the equation.
1371 Instead of typing an equation into the field, you may also use the
1372 command @kbd{C-c =}. It prompts for a formula (with default taken
1373 from the @samp{#+TBLFM:} line) and applies it to the current field. A
1374 numerical prefix (e.g. @kbd{C-5 C-c =}) will apply it to that many
1375 consecutive fields in the current column.
1377 @cindex recomputing table fields
1378 To recompute all the fields in a line, use the command @kbd{C-c *}.
1379 It re-applies all stored equations to the current row, from left to
1380 right. With a @kbd{C-u} prefix, this will be done to every line in
1381 the table, so use this command it you want to make sure the entire
1382 table is up-to-date. @kbd{C-u C-c C-c} is another way to update the
1383 entire table. Global updating does not touch the line(s) above the
1384 first horizontal separator line, assuming that this is the table
1387 @node Advanced features, Named-field formulas, Column formulas, Table calculations
1388 @subsection Advanced features
1390 If you want the recalculation of fields to happen automatically,
1391 or if you want to be able to assign a formula to an individual field
1392 (instead of an entire column) you need to reserve the first column of
1393 the table for special marking characters. Here is an example of a
1394 table that collects exam results of students and makes use of these
1399 |---+---------+--------+--------+--------+-------+------|
1400 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1401 |---+---------+--------+--------+--------+-------+------|
1402 | ! | | P1 | P2 | P3 | Tot | |
1403 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
1404 | ^ | | m1 | m2 | m3 | mt | |
1405 |---+---------+--------+--------+--------+-------+------|
1406 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
1407 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
1408 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
1409 |---+---------+--------+--------+--------+-------+------|
1410 | | Average | | | | 29.7 | |
1411 | ^ | | | | | at | |
1412 | $ | max=50 | | | | | |
1413 |---+---------+--------+--------+--------+-------+------|
1414 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(&II);%.1f
1418 @noindent @b{Important}: Please note that for these special tables,
1419 recalculating the table with @kbd{C-u C-c *} will only affect rows
1420 that are marked @samp{#} or @samp{*}, and named fields. The column
1421 formulas are not applied in rows with empty first field.
1423 @cindex marking characters, tables
1424 The marking characters have the following meaning:
1427 The fields in this line define names for the columns, so that you may
1428 refer to a column as @samp{$Tot} instead of @samp{$6}.
1430 This row defines names for the fields @emph{above} the row. With such
1431 a definition, any formula in the table may use @samp{$m1} to refer to
1432 the value @samp{10}. Also, named fields can have their own formula
1433 associated with them.
1435 Similar to @samp{^}, but defines names for the fields in the row
1438 Fields in this row can define @emph{parameters} for formulas. For
1439 example, if a field in a @samp{$} row contains @samp{max=50}, then
1440 formulas in this table can refer to the value 50 using @samp{$max}.
1441 Parameters work exactly like constants, only that they can be defined on
1442 a per-table basis. Changing a parameter and then recalculating the
1443 table can be useful.
1445 Fields in this row are automatically recalculated when pressing
1446 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
1447 is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
1448 lines will be left alone by this command.
1450 Selects this line for global recalculation with @kbd{C-u C-c *}, but
1451 not for automatic recalculation. Use this when automatic
1452 recalculation slows down editing too much.
1454 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
1455 All lines that should be recalculated should be marked with @samp{#}
1459 @node Named-field formulas, Editing/debugging formulas, Advanced features, Table calculations
1460 @subsection Named-field formulas
1461 @cindex named field formula
1462 @cindex formula, for named table field
1464 A named field can have its own formula associated with it. In the
1465 example above, this is used for the @samp{at} field that contains
1466 the average result of the students. To enter a formula for a named
1467 field, just type it into the buffer, preceded by @samp{:=}. Or use
1468 @kbd{C-u C-c =}. This equation will be stored below the table like
1469 @samp{$name=...}. Any recalculation in the table (even if only
1470 requested for the current line) will also update all named field
1473 @node Editing/debugging formulas, Appetizer, Named-field formulas, Table calculations
1474 @subsection Editing and debugging formulas
1475 @cindex formula editing
1476 @cindex editing, of table formulas
1478 To edit a column or field formula, use the commands @kbd{C-c
1479 =} and @kbd{C-u C-c =}, respectively. The currently active expression
1480 is then presented as default in the minibuffer, where it may be edited.
1482 Note that making a table field blank does not remove the formula
1483 associated with the field - during the next recalculation the field
1484 will be filled again. To remove a formula from a field, you have to
1485 give an empty reply when prompted for the formula, or to edit the
1486 @samp{#+TBLFM} line.
1489 You may edit the @samp{#+TBLFM} directly and re-apply
1490 the changed equations with @kbd{C-c C-c} in that line, or with the
1491 normal recalculation commands in the table.
1497 In particular for large tables with many formulas, it is convenient to
1498 use the command @kbd{C-c '} to edit the formulas of the current table
1499 in a separate buffer. That buffer will show the formulas one per
1500 line, and you are free to edit, add and remove formulas. Press
1501 @kbd{C-c ?} on a @samp{$...} expression to get information about its
1502 interpretation. Exiting the buffer with @kbd{C-c C-c} only stores the
1503 modified formulas below the table. Exiting with @kbd{C-u C-c C-c}
1504 also applies them to the entire table. @kbd{C-c C-q} exits without
1505 installing the changes.
1507 When the evaluation of a formula leads to an error, the field content
1508 becomes the string @samp{#ERROR}. If you would like see what is going
1509 on during variable substitution and calculation in order to find a
1510 bug, turn on formula debugging in the menu and repeat the calculation,
1511 for example by pressing @kbd{C-c = @key{RET}} in a field.
1512 Detailed information will be displayed.
1514 @node Appetizer, , Editing/debugging formulas, Table calculations
1515 @subsection Appetizer
1517 Finally, just to whet your appetite on what can be done with the fantastic
1518 @file{calc} package, here is a table that computes the Taylor series
1519 for a couple of functions (homework: try that with Excel :-)
1523 |---+-------------+---+-----+--------------------------------------|
1524 | | Func | n | x | Result |
1525 |---+-------------+---+-----+--------------------------------------|
1526 | # | exp(x) | 1 | x | 1 + x |
1527 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
1528 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
1529 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1530 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
1531 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
1532 |---+-------------+---+-----+--------------------------------------|
1533 #+TBLFM: $5=taylor($2,$4,$3);n3
1537 @node orgtbl-mode, table.el, Table calculations, Tables
1538 @section The Orgtbl minor mode
1540 @cindex minor mode for tables
1542 If you like the intuitive way the Org-mode table editor works, you
1543 might also want to use it in other modes like text-mode or mail-mode.
1544 The minor mode Orgtbl-mode makes this possible. You can always toggle
1545 the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for
1546 example in mail mode, use
1549 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1552 @node table.el, , orgtbl-mode, Tables
1553 @section The @file{table.el} package
1555 @cindex table editor, @file{table.el}
1556 @cindex @file{table.el}
1558 Complex ASCII tables with automatic line wrapping, column- and
1559 row-spanning, and alignment can be created using the Emacs table
1560 package by Takaaki Ota (@uref{http://sourceforge.net/projects/table},
1561 and also part of Emacs 22).
1562 When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-mode
1563 will call @command{table-recognize-table} and move the cursor into the
1564 table. Inside a table, the keymap of Org-mode is inactive. In order
1565 to execute Org-mode-related commands, leave the table.
1570 Recognize @file{table.el} table. Works when the cursor is in a
1575 Insert a table.el table. If there is already a table at point, this
1576 command converts it between the table.el format and the Org-mode
1577 format. See the documentation string of the command
1578 @code{org-convert-table} for the restrictions under which this is
1582 @node Hyperlinks, TODO items, Tables, Top
1586 Just like HTML, Org-mode provides links inside a file, and external
1587 links to other files, Usenet articles, emails, and much more.
1590 * Link format:: How links in Org-mode are formatted
1591 * Internal links:: Links to other places in the current file
1592 * External links:: URL-like links to the world
1593 * Handling links:: Creating, inserting and following
1594 * Search options:: Linking to a specific location
1595 * Custom searches:: When the default search is not enough
1596 * Remember:: Org-trees store quick notes
1599 @node Link format, Internal links, Hyperlinks, Hyperlinks
1600 @section Link format
1602 @cindex format, of links
1604 Org-mode will recognize plain URL-like links and activate them as
1605 clickable links. The general link format, however, looks like this:
1608 [[link][description]] @r{or alternatively} [[link]]
1611 Once a link in the buffer is complete (all brackets present), Org-mode
1612 will change the display so that @samp{description} is displayed instead
1613 of @samp{[[link][description]]} and @samp{link} is displayed instead of
1614 @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
1615 which by default is an underlined face. You can directly edit the
1616 visible part of a link. Note that this can be either the @samp{link}
1617 part (if there is no description) or the @samp{description} part. To
1618 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
1621 If you place the cursor at the beginning or just behind the end of the
1622 displayed text and press @key{BACKSPACE}, you will remove the
1623 (invisible) bracket at that location. This makes the link incomplete
1624 and the internals are again displayed as plain text. Inserting the
1625 missing bracket hides the link internals again. To show the
1626 internal structure of all links, use the menu entry
1627 @code{Org->Hyperlinks->Literal links}.
1629 @node Internal links, External links, Link format, Hyperlinks
1630 @section Internal links
1631 @cindex internal links
1632 @cindex links, internal
1633 @cindex CamelCase links
1635 If the link does not look like a URL, it is considered to be internal in
1636 the current file. Links such as @samp{[[My Target]]} or @samp{[[My
1637 Target][Find my target]]} lead to a text search in the current file.
1638 The link can be followed with @kbd{C-c C-o} when the cursor is on the
1639 link, or with a mouse click (@pxref{Handling links}). The preferred
1640 match for such a link is a dedicated target: the same string in double
1641 angular brackets. Targets may be located anywhere; often it is
1642 convenient to put them into a comment line. For example
1648 @noindent In HTML export (@pxref{HTML export}), such targets will become
1649 named anchors for direct access through @samp{http} links@footnote{Note
1650 that text before the first headline will never be exported, so the first
1651 such target must be after the first headline.}.
1653 If no dedicated target exists, Org-mode will search for the words in the
1654 link. In the above example the search would be for @samp{my target}.
1655 Links starting with a star like @samp{*My Target} restrict the search to
1656 headlines. When searching, Org-mode will first try an exact match, but
1657 then move on to more and more lenient searches. For example, the link
1658 @samp{[[*My Targets]]} will find any of the following:
1662 ** TODO my targets are bright
1663 ** my 20 targets are
1666 To insert a link targeting a headline, in-buffer completion can be used.
1667 Just type a star followed by a few optional letters into the buffer and
1668 press @kbd{M-@key{TAB}}. All headlines in the current buffer will be
1669 offered as completions. @xref{Handling links}, for more commands
1672 Following a link pushes a mark onto Org-mode's own mark ring. You can
1673 return to the previous position with @kbd{C-c &}. Using this command
1674 several times in direct succession goes back to positions recorded
1678 * Radio targets:: Make targets trigger links in plain text.
1679 * CamelCase links:: Activating CamelCase words as links
1682 @node Radio targets, CamelCase links, Internal links, Internal links
1683 @subsection Radio targets
1685 You can configure Org-mode to link any occurrences of certain target
1686 names in normal text. So without explicitly creating a link, the text
1687 connects to the target radioing its position. Radio targets are
1688 enclosed by triple angular brackets. For example, a target
1689 @samp{<<<My Target>>>} causes each occurrence of @samp{my target} in
1690 normal text to become activated as a link. The Org-mode file is
1691 scanned automatically for radio targets only when the file is first
1692 loaded into Emacs. To update the target list during editing, press
1693 @kbd{C-c C-c} with the cursor on or at a target.
1695 @node CamelCase links, , Radio targets, Internal links
1696 @subsection CamelCase words as links
1697 @cindex completion, of CamelCase links
1698 @cindex CamelCase links, completion of
1700 Org-mode also supports CamelCase words as links. This feature is not
1701 turned on by default because of the inconsistencies this system suffers
1702 from. To activate CamelCase words as links, you need to customize
1703 the option @code{org-activate-links}. A CamelCase word then leads to a
1704 text search such that @samp{CamelCaseLink} is equivalent to
1705 @samp{[[camel case link]]}.
1707 @node External links, Handling links, Internal links, Hyperlinks
1708 @section External links
1709 @cindex links, external
1710 @cindex external links
1711 @cindex links, external
1718 @cindex WANDERLUST links
1720 @cindex USENET links
1725 Org-mode supports links to files, websites, Usenet and email messages,
1726 and BBDB database entries. External links are URL-like locators. They
1727 start with a short identifying string followed by a colon. There can be
1728 no space after the colon. The following list shows examples for each
1732 http://www.astro.uva.nl/~dominik @r{on the web}
1733 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
1734 file:papers/last.pdf @r{file, relative path}
1735 news:comp.emacs @r{Usenet link}
1736 mailto:adent@@galaxy.net @r{Mail link}
1737 vm:folder @r{VM folder link}
1738 vm:folder#id @r{VM message link}
1739 vm://myself@@some.where.org/folder#id @r{VM on remote machine}
1740 wl:folder @r{WANDERLUST folder link}
1741 wl:folder#id @r{WANDERLUST message link}
1742 mhe:folder @r{MH-E folder link}
1743 mhe:folder#id @r{MH-E message link}
1744 rmail:folder @r{RMAIL folder link}
1745 rmail:folder#id @r{RMAIL message link}
1746 gnus:group @r{GNUS group link}
1747 gnus:group#id @r{GNUS article link}
1748 bbdb:Richard Stallman @r{BBDB link}
1749 shell:ls *.org @r{A shell command}
1750 elisp:(find-file-other-frame "Elisp.org") @r{An elisp form to evaluate}
1753 A link should be enclosed in double brackets and may contain a
1754 descriptive text to be displayed instead of the url (@pxref{Link
1755 format}), for example:
1758 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
1761 @cindex angular brackets, around links
1762 @cindex plain text external links
1763 Org-mode also finds external links in the normal text and activates them
1764 as links. If spaces must be part of the link (for example in
1765 @samp{bbdb:Richard Stallman}), or you need to remove ambiguities about the end of
1766 the link, enclose them in angular brackets.
1768 @node Handling links, Search options, External links, Hyperlinks
1769 @section Handling links
1771 Org-mode provides methods to create a link in the correct syntax, to
1772 insert it into an org-mode file, and to follow the link.
1776 @cindex storing links
1778 Store a link to the current location. This is a @emph{global} command
1779 which can be used in any buffer to create a link. The link will be
1780 stored for later insertion into an Org-mode buffer (see below). For
1781 Org-mode files, if there is a @samp{<<target>>} at the cursor, the link
1782 points to the target. Otherwise it points to the current headline. For
1783 VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will
1784 indicate the current article/entry. For W3 and W3M buffers, the link
1785 goes to the current URL. For any other files, the link will point to
1786 the file, with a search string (@pxref{Search options}) pointing to the
1787 contents of the current line. If there is an active region, the
1788 selected words will form the basis of the search string. If the
1789 automatically created link is not working correctly or accurately
1790 enough, you can write custom functions to select the search string and
1791 to do the search for particular file types - see @ref{Custom searches}.
1792 The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}.
1795 @cindex link completion
1796 @cindex completion, of links
1797 @cindex inserting links
1799 Insert a link. This prompts for a link to be inserted into the buffer.
1800 You can just type a link, using text for an internal link, or one of the
1801 link type prefixes mentioned in the examples above. Through completion,
1802 all links stored during the current session can be
1803 accessed@footnote{After insertion of a stored link, the link will be
1804 removed from the list of stored links. To keep it in the list later
1805 use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the
1806 option @code{org-keep-stored-link-after-insertion}.}. The link
1807 will be inserted into the buffer, along with a descriptive text. Note
1808 that you don't have to use this command to insert a link. Links in
1809 Org-mode are plain text, and you can type or paste them straight into
1810 the buffer. By using this command, the links are automatically enclosed
1811 in double brackets, and you will be asked for the optional descriptive
1812 text. If the link is a @samp{file:} link and the linked file is located
1813 in the same directory as the current file or a subdirectory of it, the
1814 path of the file will be inserted relative to the current directory.
1817 @cindex file name completion
1818 @cindex completion, of file names
1820 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
1821 a file will be inserted and you may use file name completion to select
1822 the name of the file. The path to the file is inserted relative to the
1823 directory of the current org file, if the linked file is in the current
1824 directory or in a subdirectory of it, or if the path is written relative
1825 to the current directory using @samp{../}. Otherwise an absolute path
1826 is used, if possible with @samp{~/} for your home directory. You can
1827 force an absolute path with two @kbd{C-u} prefixes.
1829 @item C-c C-l @r{with cursor on existing link}
1830 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
1831 link and description parts of the link.
1833 @cindex following links
1836 Open link at point. This will launch a web browser for URLs (using
1837 @command{browse-url-at-point}), run vm/mh-e/wanderlust/rmail/gnus/bbdb
1838 for the corresponding links, and execute the command in a shell link.
1839 When the cursor is on an internal link, this commands runs the
1840 corresponding search. When the cursor is on a TAG list in a headline,
1841 it creates the corresponding TAGS view. If the cursor is on a time
1842 stamp, it compiles the agenda for that date. Furthermore, it will visit
1843 text and remote files in @samp{file:} links with Emacs and select a
1844 suitable application for local non-text files. Classification of files
1845 is based on file extension only. See option @code{org-file-apps}. If
1846 you want to override the default application and visit the file with
1847 Emacs, use a @kbd{C-u} prefix.
1853 On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
1854 would. Under Emacs 22, also @kbd{mouse-1} will follow a link.
1858 Like @kbd{mouse-2}, but force file links to be opened with Emacs.
1863 Push the current position onto the mark ring, to be able to return
1864 easily. Commands following an internal link do this automatically.
1866 @cindex links, returning to
1869 Jump back to a recorded position. A position is recorded by the
1870 commands following internal links, and by @kbd{C-c %}. Using this
1871 command several times in direct succession moves through a ring of
1872 previously recorded positions.
1876 @node Search options, Custom searches, Handling links, Hyperlinks
1877 @section Search options in file links
1878 @cindex search option in file links
1879 @cindex file links, searching
1881 File links can contain additional information to make Emacs jump to a
1882 particular location in the file when following a link. This can be a
1883 line number or a search option after a double@footnote{For backward
1884 compatibility, line numbers can also follow a single colon.} colon. For
1885 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
1886 links}) to a file, it encodes the words in the current line as a search
1887 string that can be used to find this line back later when following the
1888 link with @kbd{C-c C-o}.
1890 Here is the syntax of the different ways to attach a search to a file
1891 link, together with an explanation:
1894 [[file:~/code/main.c::255]]
1895 [[file:~/xx.org::My Target]]
1896 [[file:~/xx.org::*My Target]]
1897 [[file:~/xx.org::/regexp/]]
1904 Search for a link target @samp{<<My Target>>}, or do a text search for
1905 @samp{my target}, similar to the search in internal links, see
1906 @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
1907 link will become an HTML reference to the corresponding named anchor in
1910 In an Org-mode file, restrict search to headlines.
1912 Do a regular expression search for @code{regexp}. This uses the Emacs
1913 command @code{occur} to list all matches in a separate window. If the
1914 target file is in Org-mode, @code{org-occur} is used to create a
1915 sparse tree with the matches.
1916 @c If the target file is a directory,
1917 @c @code{grep} will be used to search all files in the directory.
1920 As a degenerate case, a file link with an empty file name can be used
1921 to search the current file. For example, @code{<file:::find me>} does
1922 a search for @samp{find me} in the current file, just as
1923 @samp{[[find me]]} would.
1925 @node Custom searches, Remember, Search options, Hyperlinks
1926 @section Custom Searches
1927 @cindex custom search strings
1929 The default mechanism for creating search strings and for doing the
1930 actual search related to a file link may not work correctly in all
1931 cases. For example, BibTeX database files have many entries like
1932 @samp{year="1993"} which would not result in good search strings,
1933 because the only unique identification for a BibTeX entry is the
1936 If you come across such a problem, you can write custom functions to set
1937 the right search string for a particular file type, and to do the search
1938 for the string in the file. Using @code{add-hook}, these functions need
1939 to be added to the hook variables
1940 @code{org-create-file-search-functions} and
1941 @code{org-execute-file-search-functions}. See the docstring for these
1942 variables for more information. Org-mode actually uses this mechanism
1943 for Bib@TeX{} database files, and you can use the corresponding code as
1944 an implementation example. Search for @samp{BibTeX links} in the source
1948 @node Remember, , Custom searches, Hyperlinks
1950 @cindex @file{remember.el}
1952 Another way to create org entries with links to other files is through
1953 the @emph{Remember} package by John Wiegley. @emph{Remember} lets you
1954 store quick notes with little interruption of your work flow. See
1955 @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more
1956 information. The notes produced by @emph{Remember} can be stored in
1957 different ways, and Org-mode files are a good target. Org-mode allows
1958 you to file away notes either to a default file, or directly to the correct
1959 location in your Org-mode outline tree. The following customization
1960 will tell @emph{Remember} to use org files as target, and to create
1961 annotations compatible with Org-mode links.
1964 (setq org-directory "~/path/to/my/orgfiles/")
1965 (setq org-default-notes-file "~/.notes")
1966 (setq remember-annotation-functions '(org-remember-annotation))
1967 (setq remember-handler-functions '(org-remember-handler))
1968 (add-hook 'remember-mode-hook 'org-remember-apply-template)
1971 @cindex templates, for remember
1972 In combination with Org-mode, you can use templates to generate
1973 different types of remember notes. For example, if you would like to
1974 use one template to create general TODO entries, and another one for
1975 journal entries, you could use:
1978 (setq org-remember-templates
1979 '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org")
1980 (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")))
1983 @noindent In these entries, the character specifies how to select the
1984 template, the first string specifies the template, and the (optional)
1985 second string specifies a default file (overruling
1986 @code{org-default-notes-file}) as a target for this note.
1988 When you call @kbd{M-x remember} to remember something, org will prompt
1989 for a key to select the template and then prepare the buffer like
1992 <file:link to where you called remember>
1998 * [2006-03-21 Tue 15:37]
2000 <file:link to where you called remember>
2003 @noindent See the variable @code{org-remember-templates} for more details.
2005 When you are finished composing a note with remember, you have to press
2006 @kbd{C-c C-c} to file the note away. The handler first prompts for a
2007 target file - if you press @key{RET}, the value of
2008 @code{org-default-notes-file} is used. Then the command offers the
2009 headings tree of the selected file. You can either immediately press
2010 @key{RET} to get the note appended to the file. Or you can use vertical
2011 cursor motion (@key{up} and @key{down}) and visibility cycling
2012 (@key{TAB}) to find a better place. Pressing @key{RET} or @key{left} or
2013 @key{right} leads to the following result.
2015 @multitable @columnfractions 0.2 0.1 0.7
2016 @item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}
2017 @item buffer-start @tab @key{RET} @tab as level 2 heading at end of file
2018 @item on headline @tab @key{RET} @tab as sublevel of the heading at cursor
2019 @item @tab @key{left} @tab as same level, before current heading
2020 @item @tab @key{right} @tab as same level, after current heading
2021 @item not on headline @tab @key{RET}
2022 @tab at cursor position, level taken from context.
2023 Or use prefix arg to specify level manually.
2026 So a fast way to store the note is to press @kbd{C-c C-c @key{RET}
2027 @key{RET}} to append it to the default file. Even shorter would be
2028 @kbd{C-u C-c C-c}, which does the same without even showing the tree.
2029 But with little extra effort, you can push it directly to the correct
2032 Before inserting the text into a tree, the function ensures that the
2033 text has a headline, i.e. a first line that starts with a @samp{*}.
2034 If not, a headline is constructed from the current date and some
2035 additional data. If the variable @code{org-adapt-indentation} is
2036 non-nil, the entire text is also indented so that it starts in the
2037 same column as the headline (after the asterisks).
2040 @node TODO items, Timestamps, Hyperlinks, Top
2044 Org-mode does not maintain TODO lists as a separate document. TODO
2045 items are an integral part of the notes file, because TODO items
2046 usually come up while taking notes! With Org-mode, you simply mark
2047 any entry in a tree as being a TODO item. In this way, the
2048 information is not duplicated, and the entire context from which the
2049 item emerged is always present when you check.
2051 Of course, this technique causes TODO items to be scattered throughout
2052 your file. Org-mode provides methods to give you an overview over all
2053 things you have to do.
2056 * TODO basics:: Marking and displaying TODO entries
2057 * TODO extensions:: Workflow and assignments
2058 * Priorities:: Some things are more important than others
2061 @node TODO basics, TODO extensions, TODO items, TODO items
2062 @section Basic TODO functionality
2064 Any headline can become a TODO item by starting it with the word TODO,
2068 *** TODO Write letter to Sam Fortune
2072 The most important commands to work with TODO entries are:
2076 @cindex cycling, of TODO states
2078 Rotate the TODO state of the current item between
2081 ,-> (unmarked) -> TODO -> DONE --.
2082 '--------------------------------'
2085 The same rotation can also be done ``remotely'' from the timeline and
2086 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
2087 @kindex S-@key{right}
2088 @kindex S-@key{left}
2091 Select the following/preceding TODO state, similar to cycling. Mostly
2092 useful if more than two TODO states are possible (@pxref{TODO extensions}).
2094 @cindex sparse tree, for TODO
2096 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds
2097 the entire buffer, but shows all TODO items and the headings hierarchy
2098 above them. With prefix arg, show also the DONE entries. With
2099 numerical prefix N, show the tree for the Nth keyword in the variable
2100 @code{org-todo-keywords}.
2103 Show the global TODO list. This collects the TODO items from all
2104 agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in
2105 @code{agenda-mode}, so there are commands to examine and manipulate
2106 the TODO entries directly from that buffer (@pxref{Agenda commands}).
2107 @xref{Global TODO list}, for more information.
2108 @c @item @code{org-agenda-include-all-todo}
2109 @c If you would like to have all your TODO items listed as part of your
2110 @c agenda, customize the variable @code{org-agenda-include-all-todo}.
2114 @node TODO extensions, Priorities, TODO basics, TODO items
2115 @section Extended use of TODO keywords
2116 @cindex extended TODO keywords
2118 The default implementation of TODO entries is just two states: TODO and
2119 DONE. You can, however, use the TODO feature for more complicated
2120 things by configuring the variables @code{org-todo-keywords} and
2121 @code{org-todo-interpretation}. Using special setup, you can even use
2122 TODO keywords in different ways in different org files.
2124 Note that @i{tags} are another way to classify headlines in general and
2125 TODO items in particular (@pxref{Tags}).
2128 * Workflow states:: From TODO to DONE in steps
2129 * TODO types:: I do this, Fred the rest
2130 * Per file keywords:: Different files, different requirements
2133 @node Workflow states, TODO types, TODO extensions, TODO extensions
2134 @subsection TODO keywords as workflow states
2135 @cindex TODO workflow
2136 @cindex workflow states as TODO keywords
2138 You can use TODO keywords to indicate different states in the process
2139 of working on an item, for example:
2142 (setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE")
2143 org-todo-interpretation 'sequence)
2146 @cindex completion, of TODO keywords
2147 Changing these variables only becomes effective in a new Emacs session.
2148 With this setup, the command @kbd{C-c C-t} will cycle an entry from
2149 TODO to FEEDBACK, then to VERIFY, and finally to DONE. You may also
2150 use a prefix argument to quickly select a specific state. For example
2151 @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
2152 If you define many keywords, you can use in-buffer completion (see
2153 @ref{Completion}) to insert these words into the buffer.
2155 @node TODO types, Per file keywords, Workflow states, TODO extensions
2156 @subsection TODO keywords as types
2158 @cindex names as TODO keywords
2159 @cindex types as TODO keywords
2161 The second possibility is to use TODO keywords to indicate different
2162 types of action items. For example, you might want to indicate that
2163 items are for ``work'' or ``home''. If you are into David Allen's
2164 @emph{Getting Things DONE}, you might want to use todo types
2165 @samp{NEXTACTION}, @samp{WAITING}, @samp{MAYBE}. Or, when you work
2166 with several people on a single project, you might want to assign
2167 action items directly to persons, by using their names as TODO
2168 keywords. This would be set up like this:
2171 (setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE")
2172 org-todo-interpretation 'type)
2175 In this case, different keywords do not indicate a sequence, but
2176 rather different types. So it is normally not useful to change from
2177 one type to another. Therefore, in this case the behavior of the
2178 command @kbd{C-c C-t} is changed slightly@footnote{This is also true
2179 for the @kbd{t} command in the timeline and agenda buffers.}. When
2180 used several times in succession, it will still cycle through all
2181 names. But when you return to the item after some time and execute
2182 @kbd{C-c C-t} again, it will switch from each name directly to DONE.
2183 Use prefix arguments or completion to quickly select a specific name.
2184 You can also review the items of a specific TODO type in a sparse tree
2185 by using a numeric prefix to @kbd{C-c C-v}. For example, to see all
2186 things Lucy has to do, you would use @kbd{C-3 C-c C-v}. To collect
2187 Lucy's items from all agenda files into a single buffer, you
2188 would use the prefix arg as well when creating the global todo list:
2191 @node Per file keywords, , TODO types, TODO extensions
2192 @subsection Setting up TODO keywords for individual files
2193 @cindex keyword options
2194 @cindex per file keywords
2196 It can be very useful to use different aspects of the TODO mechanism
2197 in different files, which is not possible with the global settings
2198 described above. For file-local settings, you need to add special
2199 lines to the file which set the keywords and interpretation for that
2200 file only. For example, to set one of the two examples discussed
2201 above, you need one of the following lines, starting in column zero
2202 anywhere in the file:
2205 #+SEQ_TODO: TODO FEEDBACK VERIFY DONE
2206 #+TYP_TODO: Fred Sara Lucy Mike DONE
2209 @cindex Completion, of option keywords
2211 @noindent To make sure you are using the correct keyword, type
2212 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
2214 @cindex DONE, final TODO keyword
2215 Remember that the last keyword must always mean that the item is DONE
2216 (although you may use a different word). Also note that in each file,
2217 only one of the two aspects of TODO keywords can be used. After
2218 changing one of these lines, use @kbd{C-c C-c} with the cursor still
2219 in the line to make the changes known to Org-mode@footnote{Org-mode
2220 parses these lines only when Org-mode is activated after visiting a
2221 file. @kbd{C-c C-c} with the cursor in a line starting with @samp{#+}
2222 is simply restarting Org-mode, making sure that these changes will be
2225 If you want to use very many keywords, for example when working with a
2226 large group of people, you may split the names over several lines:
2229 #+TYP_TODO: Fred Sara Lucy Mike
2230 #+TYP_TODO: Luis George Jules Jessica
2231 #+TYP_TODO: Kim Arnold Peter
2235 @node Priorities, , TODO extensions, TODO items
2239 If you use Org-mode extensively to organize your work, you may end up
2240 with a number of TODO entries so large that you'd like to prioritize
2241 them. This can be done by placing a @emph{priority cookie} into the
2245 *** TODO [#A] Write letter to Sam Fortune
2249 With its standard setup, Org-mode supports priorities @samp{A},
2250 @samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry
2251 without a cookie is treated as priority @samp{B}. Priorities make a
2252 difference only in the agenda (@pxref{Weekly/Daily agenda}).
2257 Set the priority of the current headline. The command prompts for a
2258 priority character @samp{A}, @samp{B} or @samp{C}. When you press
2259 @key{SPC} instead, the priority cookie is removed from the headline.
2260 The priorities can also be changed ``remotely'' from the timeline and
2261 agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
2264 @kindex S-@key{down}
2267 Increase/decrease priority of current headline. Note that these keys
2268 are also used to modify time stamps (@pxref{Creating timestamps}).
2269 Furthermore, these keys are also used by CUA-mode (@pxref{Conflicts}).
2272 @node Timestamps, Tags, TODO items, Top
2275 Items can be labeled with timestamps to make them useful for project
2279 * Time stamps:: Assigning a time to a tree entry
2280 * Creating timestamps:: Commands which insert timestamps
2281 * Progress logging:: Documenting when what work was done.
2285 @node Time stamps, Creating timestamps, Timestamps, Timestamps
2286 @section Time stamps, deadlines and scheduling
2288 @cindex ranges, time
2293 A time stamp is a specification of a date (possibly with time) in a
2294 special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16
2295 Tue 09:39>}. A time stamp can appear anywhere in the headline or body
2296 of an org-tree entry. Its presence allows entries to be shown on specific
2297 dates in the agenda (@pxref{Weekly/Daily agenda}). We distinguish:
2300 @item Plain time stamp
2302 A simple time stamp just assigns a date/time to an item. This is just
2303 like writing down an appointment in a paper agenda, or like writing down
2304 an event in a diary, when you want to take note of when something
2305 happened. In the timeline and agenda displays, the headline of an entry
2306 associated with a plain time stamp will be shown exactly on that date.
2308 @item Time stamp range
2310 Two time stamps connected by @samp{--} denote a time range. The
2311 headline will be shown on the first and last day of the range, and on
2312 any dates that are displayed and fall in the range. Here is an
2316 ** Meeting in Amsterdam
2317 <2004-08-23 Mon>--<2004-08-26 Thu>
2320 @item Time stamp with SCHEDULED keyword
2321 @cindex SCHEDULED keyword
2322 If a time stamp is preceded by the word @samp{SCHEDULED:}, it means you
2323 are planning to start working on that task on the given date. So this is
2324 not about recording an event, but about planning your work. The
2325 headline will be listed under the given date. In addition, a reminder
2326 that the scheduled date has passed will be present in the compilation
2327 for @emph{today}, until the entry is marked DONE. I.e., the task will
2328 automatically be forwarded until completed.
2331 *** TODO Call Trillian for a date on New Years Eve.
2332 SCHEDULED: <2004-12-25 Sat>
2335 @item Time stamp with DEADLINE keyword
2336 @cindex DEADLINE keyword
2337 If a time stamp is preceded by the word @samp{DEADLINE:}, the task
2338 (most likely a TODO item) is supposed to be finished on that date, and
2339 it will be listed then. In addition, the compilation for @emph{today}
2340 will carry a warning about the approaching or missed deadline,
2341 starting @code{org-deadline-warning-days} before the due date, and
2342 continuing until the entry is marked DONE. An example:
2345 *** TODO write article about the Earth for the Guide
2346 The editor in charge is <bbdb:Ford Prefect>
2347 DEADLINE: <2004-02-29 Sun>
2349 @item Time stamp with CLOSED keyword
2350 @cindex CLOSED keyword
2351 When @code{org-log-done} is non-nil, Org-mode will automatically insert
2352 a special time stamp each time a TODO entry is marked done
2353 (@pxref{Progress logging}). This time stamp is enclosed in square
2354 brackets instead of angular brackets.
2356 @item Time range with CLOCK keyword
2357 @cindex CLOCK keyword
2358 When using the clock to time the work that is being done on specific
2359 items, time ranges preceded by the CLOCK keyword are inserted
2360 automatically into the file. The time stamps are enclosed in square
2361 brackets instead of angular brackets. @xref{Clocking work time}.
2364 @node Creating timestamps, Progress logging, Time stamps, Timestamps
2365 @section Creating timestamps
2366 @cindex creating timestamps
2367 @cindex timestamps, creating
2369 For Org-mode to recognize time stamps, they need to be in the specific
2370 format. All commands listed below produce time stamps in the correct
2376 Prompt for a date and insert a corresponding time stamp. When the
2377 cursor is at a previously used time stamp, it is updated to NOW. When
2378 this command is used twice in succession, a time range is inserted.
2382 Like @kbd{C-c .}, but use the alternative format which contains date
2383 and time. The default time can be rounded to multiples of 5 minutes,
2384 see the option @code{org-time-stamp-rounding-minutes}.
2388 Like @kbd{C-c .}, but insert an inactive time stamp not triggering the
2393 Insert a time stamp corresponding to the cursor date in the Calendar.
2397 Access the Emacs calendar for the current date. If there is a
2398 timestamp in the current line, goto the corresponding date
2403 Access the agenda for the date given by the time stamp at point
2404 (@pxref{Weekly/Daily agenda}).
2408 Insert @samp{DEADLINE} keyword along with a stamp. The insertion will
2409 happen in the line directly following the headline.
2410 @c FIXME Any CLOSED timestamp will be removed.????????
2413 @cindex sparse tree, for deadlines
2415 Create a sparse tree with all deadlines that are either past-due, or
2416 which will become due within @code{org-deadline-warning-days}.
2417 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
2418 prefix, check that many days. For example, @kbd{C-1 C-c C-w} shows
2419 all deadlines due tomorrow.
2423 Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will
2424 happen in the line directly following the headline. Any CLOSED
2425 timestamp will be removed.
2427 @kindex S-@key{left}
2428 @kindex S-@key{right}
2430 @itemx S-@key{right}
2431 Change date at cursor by one day. These key bindings conflict with
2432 CUA-mode (@pxref{Conflicts}).
2435 @kindex S-@key{down}
2438 Change the item under the cursor in a timestamp. The cursor can be on
2439 a year, month, day, hour or minute. Note that if the cursor is not at
2440 a time stamp, these same keys modify the priority of an item.
2441 (@pxref{Priorities}). The key bindings also conflict with CUA-mode
2442 (@pxref{Conflicts}).
2446 @cindex evaluate time range
2448 Evaluate a time range by computing the difference between start and
2449 end. With prefix arg, insert result after the time range (in a table:
2450 into the following column).
2453 @cindex date, reading in minibuffer
2454 @cindex time, reading in minibuffer
2455 @cindex calendar, for selecting date
2456 When Org-mode prompts for a date/time, the function reading your input
2457 will replace anything you choose not to specify with the current date
2458 and time. For details, see the documentation string of
2459 @command{org-read-date}. Also, a calender will pop up to allow
2460 selecting a date. The calendar can be fully controlled from the
2461 minibuffer, and a date can be selected with the following commands:
2466 Scroll calendar backwards by one month.
2469 Scroll calendar forwards by one month.
2472 Select date by clicking on it.
2473 @kindex S-@key{right}
2476 @kindex S-@key{left}
2479 @kindex S-@key{down}
2485 @kindex M-S-@key{right}
2486 @item M-S-@key{right}
2488 @kindex M-S-@key{left}
2489 @item M-S-@key{left}
2493 Choose date in calendar (only if nothing typed into minibuffer).
2496 @node Progress logging, , Creating timestamps, Timestamps
2497 @section Progress Logging
2498 @cindex progress logging
2499 @cindex logging, of progress
2501 Org-mode can automatically record a time stamp when you mark a TODO item
2502 as DONE. You can also measure precisely the time you spent on specific
2503 items in a project by starting and stopping a clock when you start and
2504 stop working on an aspect of a project.
2507 * Closing items:: When was this entry marked DONE?
2508 * Clocking work time:: When exactly did you work on this item?
2511 @node Closing items, Clocking work time, Progress logging, Progress logging
2512 @subsection Closing items
2514 If you want to keep track of @emph{when} a certain TODO item was
2515 finished, turn on logging with
2518 (setq org-log-done t)
2522 Then each time you turn a TODO entry into DONE using either @kbd{C-c
2523 C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
2524 @samp{CLOSED: [timestamp]} will be inserted just after the headline.
2525 If you turn the entry back into a TODO item again through further
2526 state cycling, that line will be removed again. In the timeline
2527 (@pxref{Timeline}) and in the agenda (@pxref{Weekly/Daily agenda}),
2528 you can then use the @kbd{l} key to display the TODO items closed on
2529 each day, giving you an overview of what has been done on a day.
2531 @node Clocking work time, , Closing items, Progress logging
2532 @subsection Clocking work time
2534 Org-mode allows you to clock the time you spent on specific tasks in a
2535 project. When you start working on an item, you can start the clock.
2536 When you stop working on that task, or when you mark the task done, the
2537 clock is stopped and the corresponding time interval is recorded. It
2538 also computes the total time spent on each subtree of a project.
2543 Start the clock on the current item (clock-in). This inserts the CLOCK
2544 keyword together with a timestamp.
2547 Stop the clock (clock-out). The inserts another timestamp at the same
2548 location where the clock was last started. It also directly computes
2549 the resulting time in inserts it after the time range as @samp{=>
2553 Changing the TODO state of an item to DONE automatically stops the clock
2554 if it is running in this same item.
2557 Cancel the current clock. This is useful if a clock was started by
2558 mistake, or if you ended up working on something else.
2561 Display time summaries for each subtree in the current buffer. This
2562 puts overlays at the end of each headline, showing the total time
2563 recorded under that heading, including the time of any subheadings. You
2564 can use visibility cycling to study the tree, but the overlays disappear
2565 automatically when the buffer is changed.
2568 Insert a dynamic block containing a clock report as an org-mode table
2569 into the current file.
2571 #+BEGIN: clocktable :maxlevel 2 :emphasize nil
2576 If such a block already exists, its content is replaced by the new
2577 table. The @samp{BEGIN} line can specify options:
2579 :maxlevels @r{Maximum level depth to which times are listed in the table.}
2580 :emphasize @r{When @code{t}, emphasize level one and level two items}
2584 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
2585 the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been
2586 worked on or closed during a day.
2588 @node Tags, Agenda views, Timestamps, Top
2591 @cindex headline tagging
2592 @cindex matching, tags
2593 @cindex sparse tree, tag based
2595 If you wish to implement a system of labels and contexts for
2596 cross-correlating information, an excellent way is to assign @i{tags} to
2597 headlines. Org-mode has extensive support for using tags.
2599 Every headline can contain a list of tags, at the end of the headline.
2600 Tags are normal words containing letters, numbers, @samp{_}, and
2601 @samp{@@}. Tags must be preceded and followed by a single colon; like
2602 @samp{:WORK:}. Several tags can be specified like @samp{:WORK:URGENT:}.
2605 * Tag inheritance:: Tags use the tree structure of the outline
2606 * Setting tags:: How to assign tags to a headline
2607 * Tag searches:: Searching for combinations of tags
2610 @node Tag inheritance, Setting tags, Tags, Tags
2611 @section Tag inheritance
2612 @cindex inheritance, of tags
2614 @i{Tags} make use of the hierarchical structure of outline trees. If a
2615 heading has a certain tag, all subheadings will inherit the tag as
2616 well. For example, in the list
2619 * Meeting with the French group :WORK:
2620 ** Summary by Frank :BOSS:NOTES:
2621 *** TODO Prepare slides for him :ACTION:
2625 the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:},
2626 @samp{:NOTES:}, and @samp{:ACTION:}. When executing tag searches and
2627 Org-mode finds that a certain headline matches the search criterion, it
2628 will not check any sublevel headline, assuming that these likely also
2629 match, and that the list of matches can become very long. This may
2630 not be what you want, however, and you can influence inheritance and
2631 searching using the variables @code{org-use-tag-inheritance} and
2632 @code{org-tags-match-list-sublevels}.
2634 @node Setting tags, Tag searches, Tag inheritance, Tags
2635 @section Setting tags
2636 @cindex setting tags
2639 Tags can simply be typed into the buffer at the end of a headline.
2640 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
2641 also a special command for inserting tags:
2646 @cindex completion, of tags
2647 Enter new tags for the current headline. Org-mode will either offer
2648 completion or a special single-key interface for setting tags, see
2649 below. After pressing @key{RET}, the tags will be inserted and aligned
2650 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
2651 tags in the current buffer will be aligned to that column, just to make
2652 things look nice. TAGS are automatically realigned after promotion,
2653 demotion, and TODO state changes (@pxref{TODO basics}).
2656 Org will support tag insertion based on a @emph{list of tags}. By
2657 default this list is constructed dynamically, containing all tags
2658 currently used in the buffer. You may also globally specify a hard list
2659 of tags with the variable @code{org-tag-alist}. Finally you can set
2660 the allowed tags for a given file with lines like
2663 #+TAGS: @@WORK @@HOME @@TENNISCLUB
2664 #+TAGS: Laptop Car PC Sailboat
2667 The default support method is minibuffer completion. However, Org-mode
2668 also implements a much better method: @emph{fast tag selection}. This
2669 method allows to select and deselect tags with a single key per tag. To
2670 function efficiently, you should assign unique keys to all tags. This
2671 can be done globally with
2674 (setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l)))
2677 @noindent or on a per-file basis with
2680 #+TAGS: @@WORK(w) @@HOME(h) @@TENNISCLUB(t) Laptop(l) PC(p)
2684 You can also group together tags that are mutually exclusive. With
2685 curly braces@footnote{In @code{org-mode-alist} use
2686 @code{'(:startgroup)} and @code{'(:endgroup)}, respectively. Several
2687 groups are allowed.}
2690 #+TAGS: @{ @@WORK(w) @@HOME(h) @@TENNISCLUB(t) @} Laptop(l) PC(p)
2693 @noindent you indicate that at most one of @samp{@@WORK}, @samp{@@HOME},
2694 and @samp{@@SAILBOAT} should be selected.
2696 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
2697 these lines to activate any changes.
2699 If at least one tag has a selection key, pressing @kbd{C-c C-c} will
2700 automatically present you with a special interface, listing inherited
2701 tags, the tags of the current headline, and a list of all legal tags
2702 with corresponding keys@footnote{Keys will automatically assigned to
2703 tags which have no configured keys.}. Pressing keys for the tags will
2704 add or remove them from the list of tags in the current line. Selecting
2705 a tag in a group of mutually exclusive tags will turn off any other tags
2706 from that group. @key{SPC} clears all tags for this line, @kbd{RET}
2707 accepts the modified set, and @kbd{C-g} aborts without installing
2708 changes. This method lets you assign tags to a headline with very few
2709 keys. With the above setup, you could clear the current tags and set
2710 @samp{@@HOME}, @samp{Laptop} and @samp{PC} tags with just the following
2711 keys: @kbd{C-c C-c @key{SPC} h l p @key{RET}}. Switching from
2712 @samp{@@HOME} to @samp{@@WORK} would be done with @kbd{C-c C-c w
2715 What if you have globally defined your preferred set of tags using the
2716 variable @code{org-tag-alist}, but would like to use a dynamic tag list
2717 in a specific file? Just add an empty TAGS option line to that file:
2725 @node Tag searches, , Setting tags, Tags
2726 @section Tag searches
2727 @cindex tag searches
2729 Once a tags system has been set up, it can be used to collect related
2730 information into special lists.
2735 Create a sparse tree with all headlines matching a tags search.
2738 Create a global list of tag matches from all agenda files.
2739 @xref{Matching headline tags}.
2742 Create a global list of tag matches from all agenda files, but check
2743 only TODO items and force checking subitems (see variable
2744 @code{org-tags-match-list-sublevels}).
2747 A @i{tags} search string can use Boolean operators @samp{&} for AND and
2748 @samp{|} for OR. @samp{&} binds more strongly than @samp{|}.
2749 Parenthesis are currently not implemented. A tag may also be preceded
2750 by @samp{-}, to select against it, and @samp{+} is syntactic sugar for
2751 positive selection. The AND operator @samp{&} is optional when @samp{+}
2752 or @samp{-} is present. For example, @samp{+WORK-BOSS} would select all
2753 headlines that are tagged @samp{:WORK:}, but discard those also tagged
2754 @samp{:BOSS:}. The search string @samp{WORK|LAPTOP} selects all lines
2755 tagged @samp{:WORK:} or @samp{:LAPTOP:}. The string
2756 @samp{WORK|LAPTOP&NIGHT} requires that the @samp{:LAPTOP:} lines are
2757 also tagged @samp{NIGHT}.
2759 @node Agenda views, Embedded LaTeX, Tags, Top
2760 @chapter Agenda Views
2761 @cindex agenda views
2763 Due to the way Org-mode works, TODO items, time-stamped items, and
2764 tagged headlines can be scattered throughout a file or even a number of
2765 files. To get an overview over open action items, or over events that
2766 are important for a particular date, this information must be collected,
2767 sorted and displayed in an organized way.
2769 Org-mode can select items based on various criteria, and display them
2770 in a separate buffer. Three different views are provided:
2774 an @emph{agenda} that is like a calendar and shows information
2777 a @emph{TODO list} that covers all unfinished
2780 a @emph{tags view} that shows information based on
2781 the tags associated with headlines in the outline tree.
2785 The extracted information is displayed in a special @emph{agenda
2786 buffer}. This buffer is read-only, but provides commands to visit the
2787 corresponding locations in the original Org-mode files, and even to
2788 edit these files remotely.
2791 * Agenda files:: Files being searched for agenda information
2792 * Agenda dispatcher:: Keyboard access to agenda views
2793 * Weekly/Daily agenda:: The calendar page with current tasks
2794 * Global TODO list:: All unfinished action items
2795 * Matching headline tags:: Structured information with fine-tuned search
2796 * Timeline:: Time-sorted view for single file
2797 * Agenda commands:: Remote editing of org trees
2800 @node Agenda files, Agenda dispatcher, Agenda views, Agenda views
2801 @section Agenda files
2803 The information to be shown is collected from all @emph{agenda files},
2804 the files listed in the variable @code{org-agenda-files}@footnote{If the
2805 value of that variable is not a list, but a single file name, then the
2806 list of agenda files will be maintained in that external file.}. Thus even
2807 if you only work with a single Org-mode file, this file should be put
2808 into that list@footnote{When using the dispatcher pressing @kbd{1}
2809 before selecting a command will actually limit the command to the
2810 current file, and ignore @code{org-agenda-files} until the next
2811 dispatcher command.}. You can customize @code{org-agenda-files}, but
2812 the easiest way to maintain it is through the following commands
2814 @cindex files, adding to agenda list
2818 Add current file to the list of agenda files. The file is added to
2819 the front of the list. If it was already in the list, it is moved to
2820 the front. With prefix arg, file is added/moved to the end.
2823 Remove current file from the list of agenda files.
2826 Cycle through agenda file list, visiting one file after the other.
2830 The Org menu contains the current list of files and can be used
2831 to visit any of them.
2833 @node Agenda dispatcher, Weekly/Daily agenda, Agenda files, Agenda views
2834 @section The agenda dispatcher
2835 @cindex agenda dispatcher
2836 @cindex dispatching agenda commands
2837 @cindex custom agenda commands
2838 @cindex agenda commands, custom
2839 The views are created through a dispatcher that should be bound to a
2840 global key, for example @kbd{C-c a} (@pxref{Installation}). In the
2841 following we will assume that @kbd{C-c a} is indeed how the dispatcher
2842 is accessed and list keyboard access to commands accordingly. After
2843 pressing @kbd{C-c a}, an additional letter is required to execute a
2844 command. The dispatcher offers the following default commands:
2847 Create the calendar-like agenda (@pxref{Weekly/Daily agenda}).
2849 Create a list of all TODO items (@pxref{Global TODO list}).
2851 Create a list of headlines matching a TAGS expression (@pxref{Matching
2855 You can also define custom commands that will be accessible through
2856 the dispatcher, just like the default commands. Custom commands are
2857 global searches for tags and specific TODO keywords, or a variety of
2858 sparse tree creating commands (@pxref{Sparse trees}). As sparse trees
2859 are only defined for a single org-mode file, these latter commands act
2860 on the current buffer instead of the list of agenda files.
2863 Custom commands are configured in the variable
2864 @code{org-agenda-custom-commands}. You can customize this variable,
2865 for example by pressing @kbd{C-c a C}. You can also directly set it
2866 with Emacs Lisp in @file{.emacs}. For example:
2869 (setq org-agenda-custom-commands
2870 '(("w" todo "WAITING")
2871 ("u" tags "+BOSS-URGENT")
2872 ("U" tags-tree "+BOSS-URGENT")
2873 ("f" occur-tree "\\<FIXME\\>")))
2876 @noindent will define @kbd{C-c a w} as a global search for
2877 TODO entries with @samp{WAITING} as the TODO keyword, @kbd{C-c a u} as a
2878 global tags search for headlines marked @samp{:BOSS:} but not
2879 @samp{:URGENT:}, @kbd{C-c a U} to do the same search but only in the
2880 current buffer and display the result as a sparse tree, and @kbd{C-c a
2881 f} to create a sparse tree with all entries containing the word
2882 @samp{FIXME}. For more information, look at the documentation string
2883 of the variable @code{org-agenda-custom-commands}.
2885 @node Weekly/Daily agenda, Global TODO list, Agenda dispatcher, Agenda views
2886 @section The weekly/daily agenda
2889 The purpose of the weekly/daily @emph{agenda} is to act like a page of
2890 a paper agenda, showing all the tasks for the current week or day.
2893 @cindex org-agenda, command
2896 Compile an agenda for the current week from a list of org files. The
2897 agenda shows the entries for each day. With a @kbd{C-u} prefix (or
2898 when the variable @code{org-agenda-include-all-todo} is @code{t}), all
2899 unfinished TODO items (including those without a date) are also listed at
2900 the beginning of the buffer, before the first date.@*
2903 Remote editing from the agenda buffer means, for example, that you can
2904 change the dates of deadlines and appointments from the agenda buffer.
2905 The commands available in the Agenda buffer are listed in @ref{Agenda
2909 * Categories:: Not all tasks are equal
2910 * Time-of-day specifications:: How the agenda knows the time
2911 * Calendar/Diary integration:: Integrating Anniversaries and more
2912 * Sorting of agenda items:: The order of things
2915 @node Categories, Time-of-day specifications, Weekly/Daily agenda, Weekly/Daily agenda
2916 @subsection Categories
2919 In the agenda buffer, each entry is preceded by a @emph{category},
2920 which is derived from the file name. The category can also be set
2921 with a special line anywhere in the buffer, looking like this:
2927 If there are several such lines in a file, each specifies the category
2928 for the text below it (but the first category also applies to any text
2929 before the first CATEGORY line). The display in the agenda buffer looks
2930 best if the category is not longer than 10 characters.
2932 @node Time-of-day specifications, Calendar/Diary integration, Categories, Weekly/Daily agenda
2933 @subsection Time-of-Day Specifications
2935 Org-mode checks each agenda item for a time-of-day specification. The
2936 time can be part of the time stamp that triggered inclusion into the
2937 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
2938 ranges can be specified with two time stamps, like
2940 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
2942 In the headline of the entry itself, a time(range) may also appear as
2943 plain text (like @samp{12:45} or a @samp{8:30-1pm}. If the agenda
2944 integrates the Emacs diary (@pxref{Calendar/Diary integration}), time
2945 specifications in diary entries are recognized as well.
2947 For agenda display, Org-mode extracts the time and displays it in a
2948 standard 24 hour format as part of the prefix. The example times in
2949 the previous paragraphs would end up in the agenda like this:
2952 8:30-13:00 Arthur Dent lies in front of the bulldozer
2953 12:45...... Ford Prefect arrives and takes Arthur to the pub
2954 19:00...... The Vogon reads his poem
2955 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
2958 If the agenda is in single-day mode, or for the display of today, the
2959 timed entries are embedded in a time grid, like
2962 8:00...... ------------------
2963 8:30-13:00 Arthur Dent lies in front of the bulldozer
2964 10:00...... ------------------
2965 12:00...... ------------------
2966 12:45...... Ford Prefect arrives and takes Arthur to the pub
2967 14:00...... ------------------
2968 16:00...... ------------------
2969 18:00...... ------------------
2970 19:00...... The Vogon reads his poem
2971 20:00...... ------------------
2972 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
2975 The time grid can be turned on and off with the variable
2976 @code{org-agenda-use-time-grid}, and can be configured with
2977 @code{org-agenda-time-grid}.
2980 @node Calendar/Diary integration, Sorting of agenda items, Time-of-day specifications, Weekly/Daily agenda
2981 @subsection Calendar/Diary integration
2982 @cindex calendar integration
2983 @cindex diary integration
2985 Emacs contains the calendar and diary by Edward M. Reingold. The
2986 calendar displays a three-month calendar with holidays from different
2987 countries and cultures. The diary allows you to keep track of
2988 anniversaries, lunar phases, sunrise/set, recurrent appointments
2989 (weekly, monthly) and more. In this way, it is quite complementary to
2990 Org-mode. It can be very useful to combine output from Org-mode with
2993 In order to include entries from the Emacs diary into Org-mode's
2994 agenda, you only need to customize the variable
2997 (setq org-agenda-include-diary t)
3000 @noindent After that, everything will happen automatically. All diary
3001 entries including holidays, anniversaries etc will be included in the
3002 agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and
3003 @key{RET} can be used from the agenda buffer to jump to the diary
3004 file in order to edit existing diary entries. The @kbd{i} command to
3005 insert new entries for the current date works in the agenda buffer, as
3006 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
3007 Sunrise/Sunset times, show lunar phases and to convert to other
3008 calendars, respectively. @kbd{c} can be used to switch back and forth
3009 between calendar and agenda.
3011 @node Sorting of agenda items, , Calendar/Diary integration, Weekly/Daily agenda
3012 @subsection Sorting of agenda items
3013 @cindex sorting, of agenda items
3014 @cindex priorities, of agenda items
3015 The entries for each day are sorted. The default order is to first
3016 collect all items containing an explicit time-of-day specification.
3017 These entries will be shown at the beginning of the list, as a
3018 @emph{schedule} for the day. After that, items remain grouped in
3019 categories, in the sequence given by @code{org-agenda-files}. Within
3020 each category, items are sorted by priority (@pxref{Priorities}).
3022 The priority is a numerical quantity composed of the base priority
3023 (2000 for priority @samp{A}, 1000 for @samp{B}, and 0 for @samp{C}),
3024 plus additional increments for overdue scheduled or deadline items.
3026 Sorting can be customized using the variable
3027 @code{org-agenda-sorting-strategy}.
3030 @node Global TODO list, Matching headline tags, Weekly/Daily agenda, Agenda views
3031 @section The global TODO list
3032 @cindex global TODO list
3033 @cindex TODO list, global
3035 The global TODO list contains all unfinished TODO items, formatted and
3036 collected into a single place.
3041 Show the global TODO list. This collects the TODO items from all
3042 agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in
3043 @code{agenda-mode}, so there are commands to examine and manipulate
3044 the TODO entries directly from that buffer (@pxref{Agenda commands}).
3047 Like the above, but allows selection of a specific TODO keyword. You can
3048 also do this by specifying a prefix argument to @kbd{C-c a t}. With a
3049 @kbd{C-u} prefix you are prompted for a keyword. With a numeric
3050 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
3052 The @kbd{r} key in the agenda buffer regenerates it, and you can give
3053 a prefix argument to this command to change the selected TODO keyword,
3054 for example @kbd{3 r}. If you often need a search for a specific
3055 keyword, define a custom command for it (@pxref{Agenda dispatcher}).
3058 Remote editing of TODO items means that you can change the state of a
3059 TODO entry with a single key press. The commands available in the
3060 TODO list are described in @ref{Agenda commands}.
3062 @node Matching headline tags, Timeline, Global TODO list, Agenda views
3063 @section Matching headline tags
3064 @cindex matching, of tags
3067 If headlines in the agenda files are marked with @emph{tags}
3068 (@pxref{Tags}), you can select headlines based on the tags that apply
3069 to them and collect them into an agenda buffer.
3074 Produce a list of all headlines that match a given set of tags. The
3075 command prompts for a selection criterion, which is a boolean logic
3076 expression with tags, like @samp{+WORK+URGENT-WITHBOSS} or
3077 @samp{WORK|HOME} (@pxref{Tags}). If you often need a specific search,
3078 define a custom command for it (@pxref{Agenda dispatcher}).
3081 Like @kbd{C-c a m}, but only select headlines that are also TODO items
3082 and force checking subitems (see variable
3083 @code{org-tags-match-list-sublevels}.
3086 The commands available in the tags list are described in @ref{Agenda
3089 @node Timeline, Agenda commands, Matching headline tags, Agenda views
3090 @section Timeline for a single file
3091 @cindex single file summary
3092 @cindex agenda, for single file
3093 @cindex timeline, single file
3094 @cindex time-sorted view
3096 The timeline is not really an agenda view, because it only summarizes
3097 items from a single Org-mode file. But it also uses the agenda buffer
3098 and provides similar commands, so we discuss it here. The timeline
3099 shows all time-stamped items in a single Org-mode file (or the
3100 selected part of it), in a @emph{time-sorted view}. The main purpose of
3101 this command is to give an overview over events in a project.
3106 Show a time-sorted view of the org file, with all time-stamped items.
3107 When called with a @kbd{C-u} prefix, all unfinished TODO entries
3108 (scheduled or not) are also listed under the current date.
3112 The commands available in the timeline buffer are listed in
3113 @ref{Agenda commands}.
3115 @node Agenda commands, , Timeline, Agenda views
3116 @section Commands in the agenda buffer
3117 @cindex commands, in agenda buffer
3119 Entries in the agenda buffer are linked back to the org file or diary
3120 file where they originate. You are not allowed to edit the agenda
3121 buffer itself, but commands are provided to show and jump to the
3122 original entry location, and to edit the org-files ``remotely'' from
3123 the agenda buffer. In this way, all information is stored only once,
3124 removing the risk that your agenda and note files may diverge.
3126 Some commands can be executed with mouse clicks on agenda lines. For
3127 the other commands, the cursor needs to be in the desired line.
3130 @tsubheading{Motion}
3133 Next line (same as @key{up}).
3136 Previous line (same as @key{down}).
3137 @tsubheading{View/GoTo org file}
3142 Display the original location of the item in another window.
3146 Display original location and recenter that window.
3154 Go to the original location of the item in another window. Under Emacs
3155 22, @kbd{mouse-1} will also works for this.
3159 Go to the original location of the item and delete other windows.
3163 Toggle Follow mode. In Follow mode, as you move the cursor through
3164 the agenda buffer, the other window always shows the corresponding
3165 location in the org file. The initial setting for this mode in new
3166 agenda buffers can be set with the variable
3167 @code{org-agenda-start-with-follow-mode}.
3171 Toggle Logbook mode. In Logbook mode, entries that where marked DONE while
3172 logging was on (variable @code{org-log-done}) are shown in the agenda,
3173 as are entries that have been clocked on that day.
3175 @tsubheading{Change display}
3178 Delete other windows.
3182 Switch to weekly view (7 days displayed together).
3186 Switch to daily view (just one day displayed).
3190 Toggle the inclusion of diary entries. See @ref{Calendar/Diary integration}.
3194 Toggle the time grid on and off. See also the variables
3195 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
3199 Recreate the agenda buffer, for example to reflect the changes
3200 after modification of the time stamps of items with S-@key{left} and
3201 S-@key{right}. When the buffer is the global todo list, a prefix
3202 argument is interpreted to create a selective list for a specific TODO
3207 Save all Org-mode buffers in the current Emacs session.
3211 Display the following @code{org-agenda-ndays} days. For example, if
3212 the display covers a week, switch to the following week. With prefix
3213 arg, go forward that many times @code{org-agenda-ndays} days.
3217 Display the previous dates.
3223 @tsubheading{Remote editing}
3230 Change the TODO state of the item, both in the agenda and in the
3235 Show all tags associated with the current item. Because of
3236 inheritance, this may be more than the tags listed in the line itself.
3240 Set tags for the current headline.
3244 Toggle the ARCHIVE tag for the current headline.
3248 Set the priority for the current item. Org-mode prompts for the
3249 priority character. If you reply with @key{SPC}, the priority cookie
3250 is removed from the entry.
3254 Display weighted priority of current item.
3260 Increase the priority of the current item. The priority is changed in
3261 the original buffer, but the agenda is not resorted. Use the @kbd{r}
3265 @kindex S-@key{down}
3268 Decrease the priority of the current item.
3276 Set a deadline for this item.
3278 @kindex S-@key{right}
3280 Change the time stamp associated with the current line by one day into
3281 the future. With prefix argument, change it by that many days. For
3282 example, @kbd{3 6 5 S-@key{right}} will change it by a year. The
3283 stamp is changed in the original org file, but the change is not
3284 directly reflected in the agenda buffer. Use the
3285 @kbd{r} key to update the buffer.
3287 @kindex S-@key{left}
3289 Change the time stamp associated with the current line by one day
3294 Change the time stamp associated with the current line to today.
3295 The key @kbd{>} has been chosen, because it is the same as @kbd{S-.}
3300 Start the clock on the current item. If a clock is running already, it
3304 Stop the previously started clock.
3307 Cancel the currently running clock.
3309 @tsubheading{Calendar commands}
3312 Open the Emacs calendar and move to the date at the agenda cursor.
3315 When in the calendar, compute and show the Org-mode agenda for the
3318 @cindex diary entries, creating from agenda
3321 Insert a new entry into the diary. Prompts for the type of entry
3322 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a new
3323 entry in the diary, just as @kbd{i d} etc. would do in the calendar.
3324 The date is taken from the cursor position.
3328 Show the phases of the moon for the three months around current date.
3332 Show sunrise and sunset times. The geographical location must be set
3333 with calendar variables, see documentation of the Emacs calendar.
3337 Convert the date at cursor into many other cultural and historic
3342 Show holidays for three month around the cursor date.
3346 Export a single iCalendar file containing entries from all agenda files.
3348 @tsubheading{Quit and Exit}
3351 Quit agenda, remove the agenda buffer.
3354 @cindex agenda files, removing buffers
3356 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
3357 for the compilation of the agenda. Buffers created by the user to
3358 visit org files will not be removed.
3362 @node Embedded LaTeX, Exporting, Agenda views, Top
3363 @chapter Embedded LaTeX
3364 @cindex @TeX{} interpretation
3365 @cindex La@TeX{} interpretation
3367 Plain ASCII is normally sufficient for almost all note taking. One
3368 exception, however, are scientific notes which need to be able to
3369 contain mathematical symbols and the occasional formula.
3370 La@TeX{}@footnote{La@TeX{} is a macro system based on Donald E. Knuth's
3371 @TeX{} system. Many of the features described here as ``La@TeX{}'' are
3372 really from @TeX{}, but for simplicity I am blurring this distinction.}
3373 is widely used to typeset scientific documents. Org-mode supports
3374 embedding La@TeX{} code into its files, because many academics are used
3375 to read La@TeX{} source code, and because it can be readily processed
3376 into images for HTML production.
3378 It is not necessary to mark La@TeX{} macros and code in any special way.
3379 If you observe a few conventions, Org-mode knows how to find it and what
3383 * Math symbols:: TeX macros for symbols and Greek letters
3384 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
3385 * LaTeX fragments:: Complex formulas made easy
3386 * Processing LaTeX fragments:: Previewing LaTeX processing
3387 * CDLaTeX mode:: Speed up entering of formulas
3390 @node Math symbols, Subscripts and Superscripts, Embedded LaTeX, Embedded LaTeX
3391 @section Math symbols
3393 You can use La@TeX{} macros to insert special symbols like @samp{\alpha}
3394 to indicate the Greek letter, or @samp{\to} to indicate an arrow.
3395 Completion for these macros is available, just type @samp{\} and maybe a
3396 few letters, and press @kbd{M-@key{TAB}} to see possible completions.
3397 Unlike La@TeX{} code, Org-mode allows these macros to be present
3398 without surrounding math delimiters, for example:
3401 Angles are written as Greek letters \alpha, \beta and \gamma.
3404 During HTML export (@pxref{HTML export}), these symbols are translated
3405 into the proper syntax for HTML, for the above examples this is
3406 @samp{α} and @samp{→}, respectively.
3408 @node Subscripts and Superscripts, LaTeX fragments, Math symbols, Embedded LaTeX
3409 @section Subscripts and Superscripts
3411 Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super-
3412 and subscripts. Again, these can be used without embedding them in
3413 math-mode delimiters. To increase the readability of ASCII text, it is
3414 not necessary (but OK) to surround multi-character sub- and superscripts
3415 with curly braces. For example
3418 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
3419 the sun is R_@{sun@} = 6.96 x 10^8 m.
3422 To avoid interpretation as raised or lowered text, you can quote
3423 @samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}.
3425 During HTML export (@pxref{HTML export}), subscript and superscripts
3426 are surrounded with @code{<sub>} and @code{<sup>} tags, respectively.
3428 @node LaTeX fragments, Processing LaTeX fragments, Subscripts and Superscripts, Embedded LaTeX
3429 @section LaTeX fragments
3431 With symbols, sub- and superscripts, HTML is pretty much at its end when
3432 it comes to representing mathematical formulas. More complex
3433 expressions need a dedicated formula processor. To this end, Org-mode
3434 can contain arbitrary La@TeX{} fragments. It provides commands to
3435 preview the typeset result of these fragments, and upon export to HTML,
3436 all fragments will be converted to images and inlined into the HTML
3437 document. For this to work you need to be on a system with a working
3438 La@TeX{} installation. You also need the @file{dvipng} program,
3439 available at @url{http://sourceforge.net/projects/dvipng/}.
3441 La@TeX{} fragments don't need any special marking at all. The following
3442 snippets will be identified as LaTeX source code:
3445 Environments of any kind. The only requirement is that the
3446 @code{\begin} statement appears on a new line, preceded by only
3449 Text within the usual La@TeX{} math delimiters. To avoid conflicts with
3450 currency specifications, single @samp{$} characters are only recognized
3451 as math delimiters if the enclosed text contains at most two line breaks,
3452 is directly attached to the @samp{$} characters with no whitespace in
3453 between, and if the closing @samp{$} is followed by whitespace or
3454 punctuation. For the other delimiters, there is no such restriction, so
3455 when in doubt, use @samp{\(...\)} as inline math delimiters.
3458 @noindent For example:
3461 \begin@{equation@} % arbitrary environments,
3462 x=\sqrt@{b@} % even tables, figures
3463 \end@{equation@} % etc
3465 If $a^2=b$ and \( b=2 \), then the solution must be
3466 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
3470 If you need any of the delimiter ASCII sequences for other purposes, you
3471 can configure the option @code{org-format-latex-options} to deselect the
3472 ones you do not wish to have interpreted by the La@TeX{} converter.
3474 @node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
3475 @section Processing LaTeX fragments
3477 La@TeX{} fragments can be processed to produce a preview images of the
3478 typeset expressions:
3483 Produce a preview image of the La@TeX{} fragment at point and overlay it
3484 over the source code. If there is no fragment at point, process all
3485 fragments in the current entry (between two headlines). When called
3486 with a prefix argument, process the entire subtree. When called with
3487 two prefix arguments, or when the cursor is before the first headline,
3488 process the entire buffer.
3491 Remove the overlay preview images.
3494 During HTML export (@pxref{HTML export}), all La@TeX{} fragments are
3495 converted into images and inlined into the document if the following
3499 (setq org-export-with-LaTeX-fragments t)
3502 @node CDLaTeX mode, , Processing LaTeX fragments, Embedded LaTeX
3503 @section Using CDLaTeX to enter math
3505 CDLaTeX-mode is a minor mode that is normally used in combination with a
3506 major LaTeX mode like AUCTeX in order to speed-up insertion of
3507 environments and math templates. Inside Org-mode, you can make use of
3508 some of the features of cdlatex-mode. You need to install
3509 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
3510 AUCTeX) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
3511 Don't turn cdlatex-mode itself under Org-mode, but use the light
3512 version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it
3513 on for the current buffer with @code{M-x org-cdlatex-mode}, or for all
3517 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
3520 When this mode is enabled, the following features are present (for more
3521 details see the documentation of cdlatex-mode):
3525 Environment templates can be inserted with @kbd{C-c @{}.
3528 The @key{TAB} key will do template expansion if the cursor is inside a
3529 LaTeX fragment@footnote{Org-mode has a method to test if the cursor is
3530 inside such a fragment, see the documentation of the function
3531 @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
3532 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
3533 correctly inside the first brace. Another @key{TAB} will get you into
3534 the second brace. Even outside fragments, @key{TAB} will expand
3535 environment abbreviations at the beginning of a line. For example, if
3536 you write @samp{equ} at the beginning of a line and press @key{TAB},
3537 this abbreviation will be expanded to an @code{equation} environment.
3538 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
3542 Pressing @kbd{_} and @kbd{^} inside a LaTeX fragment will insert these
3543 characters together with a pair of braces. If you use @key{TAB} to move
3544 out of the braces, and if the braces surround only a single character or
3545 macro, they are removed again (depending on the variable
3546 @code{cdlatex-simplify-sub-super-scripts}).
3549 Pressing the backquote @kbd{`} followed by a character inserts math
3550 macros, also outside LaTeX fragments. If you wait more than 1.5 seconds
3551 after the backquote, a help window will pop up.
3554 Pressing the normal quote @kbd{'} followed by another character modifies
3555 the symbol before point with an accent or a font. If you wait more than
3556 1.5 seconds after the backquote, a help window will pop up. Character
3557 modification will work only inside La@TeX{} fragments, outside the quote
3561 @node Exporting, Publishing, Embedded LaTeX, Top
3565 Org-mode documents can be exported into a variety of other formats. For
3566 printing and sharing of notes, ASCII export produces a readable and
3567 simple version of an Org-mode file. HTML export allows you to publish a
3568 notes file on the web, while the XOXO format provides a solid base for
3569 exchange with a broad range of other applications. To incorporate
3570 entries with associated times like deadlines or appointments into a
3571 desktop calendar program like iCal, Org-mode can also produce extracts
3572 in the iCalendar format. Currently Org-mode only supports export, not
3573 import of these different formats.
3575 When exporting, Org-mode uses special conventions to enrich the output
3576 produced. @xref{Text interpretation}, for more details.
3579 * ASCII export:: Exporting to plain ASCII
3580 * HTML export:: Exporting to HTML
3581 * XOXO export:: Exporting to XOXO
3582 * iCalendar export:: Exporting in iCalendar format
3583 * Text interpretation:: How the exporter looks at the file
3586 @node ASCII export, HTML export, Exporting, Exporting
3587 @section ASCII export
3588 @cindex ASCII export
3590 ASCII export produces a simple and very readable version of an Org-mode
3593 @cindex region, active
3594 @cindex active region
3595 @cindex transient-mark-mode
3599 Export as ASCII file. If there is an active region, only the region
3600 will be exported. For an org file @file{myfile.org}, the ASCII file
3601 will be @file{myfile.txt}. The file will be overwritten without
3605 Export only the visible part of the document.
3608 @cindex headline levels, for exporting
3609 In the exported version, the first 3 outline levels will become
3610 headlines, defining a general document structure. Additional levels
3611 will be exported as itemized lists. If you want that transition to occur
3612 at a different level, specify it with a prefix argument. For example,
3619 creates only top level headlines and does the rest as items. When
3620 headlines are converted to items, the indentation of the text following
3621 the headline is changed to fit nicely under the item. This is done with
3622 the assumption that the first bodyline indicates the base indentation of
3623 the body text. Any indentation larger than this is adjusted to preserve
3624 the layout relative to the first line. Should there be lines with less
3625 indentation than the first, these are left alone.
3627 @node HTML export, XOXO export, ASCII export, Exporting
3628 @section HTML export
3631 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
3632 HTML formatting, in ways similar to John Grubers @emph{markdown}
3633 language, but with additional support for tables.
3635 @cindex region, active
3636 @cindex active region
3637 @cindex transient-mark-mode
3641 Export as HTML file @file{myfile.html}.
3644 Export as HTML file and open it with a browser.
3649 Export only the visible part of the document.
3652 @cindex headline levels, for exporting
3653 In the exported version, the first 3 outline levels will become
3654 headlines, defining a general document structure. Additional levels
3655 will be exported as itemized lists. If you want that transition to occur
3656 at a different level, specify it with a prefix argument. For example,
3663 creates two levels of headings and does the rest as items.
3665 If you want to include HTML tags which should be interpreted as such,
3666 mark them with @samp{@@} as in @samp{@@<b>bold text@@</b>}.
3667 Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
3668 @samp{>} in HTML export.
3670 @cindex links, in HTML export
3671 @cindex internal links, in HTML export
3672 @cindex external links, in HTML export
3673 Internal links (@pxref{Internal links}) will continue to work in HTML
3674 files only if they match a dedicated @samp{<<target>>}. Automatic links
3675 created by radio targets (@pxref{Radio targets}) will also work in the
3676 HTML file. Links to external files will still work if the HTML file is
3677 in the same directory as the Org-mode file. Links to other @file{.org}
3678 files will be translated into HTML links under the assumption that an
3679 HTML version also exists of the linked file. For information related to
3680 linking files while publishing them to a publishing directory see
3681 @ref{Publishing links}.
3683 You can also give style information for the exported file. The HTML
3684 exporter assigns the following CSS classes to appropriate parts of the
3685 document - your style specifications may change these:
3687 .todo @r{TODO keywords}
3688 .done @r{the DONE keyword}
3689 .timestamp @r{time stamp}
3690 .timestamp-kwd @r{keyword associated with a time stamp, like SCHEDULED}
3691 .tag @r{tag in a headline}
3692 .target @r{target for links}
3695 The default style specification can be configured through the option
3696 @code{org-export-html-style}. If you want to use a file-local style,
3697 you may use file variables, best wrapped into a COMMENT section at the
3698 end of the outline tree. For example:
3701 * COMMENT HTML style specifications
3704 # org-export-html-style: " <style type=\"text/css\">
3705 # p @{font-weight: normal; color: gray; @}
3706 # h1 @{color: black; @}
3711 Remember to execute @kbd{M-x normal-mode} after changing this to make
3712 the new style visible to Emacs. This command restarts org-mode for the
3713 current buffer and forces Emacs to re-evaluate the local variables
3714 section in the buffer.
3716 @c FIXME: More about header and footer styles
3717 @c FIXME: Talk about links and targets.
3719 @node XOXO export, iCalendar export, HTML export, Exporting
3720 @section XOXO export
3723 Org-mode contains an exporter that produces XOXO-style output.
3724 Currently, this exporter only handles the general outline structure and
3725 does not interpret any additional Org-mode features.
3730 Export as XOXO file @file{myfile.html}.
3733 Export only the visible part of the document.
3736 @node iCalendar export, Text interpretation, XOXO export, Exporting
3737 @section iCalendar export
3738 @cindex iCalendar export
3740 Some people like to use Org-mode for keeping track of projects, but
3741 still prefer a standard calendar application for anniversaries and
3742 appointments. In this case it can be useful to have deadlines and
3743 other time-stamped items in Org-mode files show up in the calendar
3744 application. Org-mode can export calendar information in the standard
3750 Create iCalendar entries for the current file and store them in the same
3751 directory, using a file extension @file{.ics}.
3754 Like @kbd{C-c C-x i}, but do this for all files in
3755 @code{org-agenda-files}. For each of these files, a separate iCalendar
3756 file will be written.
3759 Create a single large iCalendar file from all files in
3760 @code{org-agenda-files} and write it to the file given by
3761 @code{org-combined-agenda-icalendar-file}.
3764 How this calendar is best read and updated, depends on the application
3765 you are using. For example, when using iCal under Apple MacOS X, you
3766 could create a new calendar @samp{OrgMode} (the default name for the
3767 calendar created by @kbd{C-c C-x c}, see the variables
3768 @code{org-icalendar-combined-name} and
3769 @code{org-combined-agenda-icalendar-file}). Then set Org-mode to
3770 overwrite the corresponding file
3771 @file{~/Library/Calendars/OrgMode.ics}. You may even use AppleScript
3772 to make iCal re-read the calendar files each time a new version of
3773 @file{OrgMode.ics} is produced. Here is the setup needed for this:
3775 @cindex applescript, for calendar update
3777 (setq org-combined-agenda-icalendar-file
3778 "~/Library/Calendars/OrgMode.ics")
3779 (add-hook 'org-after-save-iCalendar-file-hook
3782 "osascript -e 'tell application \"iCal\" to reload calendars'")))
3785 @node Text interpretation, , iCalendar export, Exporting
3786 @section Text interpretation by the exporter
3788 The exporter backends interpret additional structure in the Org-mode file
3789 in order to produce better output.
3792 * Comment lines:: Some lines will not be exported
3793 * Enhancing text:: Subscripts, symbols and more
3794 * Export options:: How to influence the export settings
3797 @node Comment lines, Enhancing text, Text interpretation, Text interpretation
3798 @subsection Comment lines
3799 @cindex comment lines
3800 @cindex exporting, not
3802 Lines starting with @samp{#} in column zero are treated as comments
3803 and will never be exported. Also entire subtrees starting with the
3804 word @samp{COMMENT} will never be exported. Finally, any text before
3805 the first headline will not be exported either.
3810 Toggle the COMMENT keyword at the beginning of an entry.
3813 @node Enhancing text, Export options, Comment lines, Text interpretation
3814 @subsection Enhancing text for export
3815 @cindex enhancing text
3818 Some of the export backends of Org-mode allow for sophisticated text
3819 formatting, this is true in particular for the HTML backend. Org-mode
3820 has a number of typing conventions that allow to produce a richly
3825 @cindex hand-formatted lists
3826 @cindex lists, hand-formatted
3828 Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.}
3829 or @samp{2)} as enumerator will be recognized and transformed if the
3830 backend supports lists. See @xref{Plain lists}.
3832 @cindex underlined text
3836 You can make words @b{*bold*}, @i{/italic/}, _underlined_,
3837 @code{=code=}, and @samp{+strikethrough+}.
3839 @cindex LaTeX fragments, export
3840 @cindex TeX macros, export
3842 Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML
3843 entities or images (@pxref{Embedded LaTeX}).
3845 @cindex tables, export
3847 Tables are transformed into native tables under the exporter, if the
3848 export backend supports this. Data fields before the first horizontal
3849 separator line will be formatted as table header fields.
3853 If a headline starts with the word @samp{QUOTE}, the text below the
3854 headline will be typeset as fixed-width, to allow quoting of computer
3855 codes etc. Lines starting with @samp{:} are also typeset in
3860 Toggle fixed-width for entry (QUOTE) or region, see below.
3863 @cindex linebreak, forced
3865 A double backslash @emph{at the end of a line} enforces a line break at
3869 If these conversions conflict with your habits of typing ASCII text,
3870 they can all be turned off with corresponding variables (see the
3871 customization group @code{org-export-general}, and the following section
3872 which explains how to set export options with special lines in a
3876 @node Export options, , Enhancing text, Text interpretation
3877 @subsection Export options
3878 @cindex options, for export
3880 @cindex completion, of option keywords
3881 The exporter recognizes special lines in the buffer which provide
3882 additional information. These lines may be put anywhere in the file.
3883 The whole set of lines can be inserted into the buffer with @kbd{C-c
3884 C-x t}. For individual lines, a good way to make sure the keyword is
3885 correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
3886 (@pxref{Completion}).
3891 Insert template with export options, see example below.
3895 #+TITLE: the title to be shown (default is the buffer name)
3896 #+AUTHOR: the author (default taken from @code{user-full-name})
3897 #+EMAIL: his/her email address (default from @code{user-mail-address})
3898 #+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language})
3899 #+TEXT: Some descriptive text to be inserted at the beginning.
3900 #+TEXT: Several lines may be given.
3901 #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t *:nil TeX:t LaTeX:t
3905 The OPTIONS line is a compact form to specify export settings. Here
3907 @cindex headline levels
3908 @cindex section-numbers
3909 @cindex table of contents
3910 @cindex linebreak preservation
3911 @cindex quoted HTML tags
3912 @cindex fixed-width sections
3914 @cindex @TeX{}-like syntax for sub- and superscripts
3915 @cindex emphasized text
3916 @cindex @TeX{} macros
3917 @cindex La@TeX{} fragments
3919 H: @r{set the number of headline levels for export}
3920 num: @r{turn on/off section-numbers}
3921 toc: @r{turn on/off table of contents}
3922 \n: @r{turn on/off linebreak-preservation}
3923 @@: @r{turn on/off quoted HTML tags}
3924 :: @r{turn on/off fixed-width sections}
3925 |: @r{turn on/off tables}
3926 ^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts.}
3927 *: @r{turn on/off emphasized text (bold, italic, underlined)}
3928 TeX: @r{turn on/off simple @TeX{} macros in plain text}
3929 LaTeX: @r{turn on/off La@TeX{} fragments}
3932 @node Publishing, Miscellaneous, Exporting, Top
3936 Org-mode includes@footnote{@file{org-publish.el} is not yet part of
3937 emacs, so if you are using @file{org.el} as it comes with Emacs, you
3938 need to download this file separately. Also make sure org.el is at
3939 least version 4.27.} a publishing management system
3940 that allows you to configure automatic HTML conversion of
3941 @emph{projects} composed of interlinked org files. This system is
3942 called @emph{org-publish}. You can also configure org-publish to
3943 automatically upload your exported HTML pages and related attachments,
3944 such as images and source code files, to a web server. Org-publish turns
3945 org-mode into a web-site authoring tool.
3947 Org-publish has been contributed to Org-mode by David O'Toole.
3950 * Configuration:: Defining projects
3951 * Sample configuration:: Example projects
3952 * Triggering publication:: Publication commands
3955 @node Configuration, Sample configuration, Publishing, Publishing
3956 @section Configuration
3958 Publishing needs significant configuration to specify files, destination
3959 and many other properties of a project.
3962 * Project alist:: The central configuration variable
3963 * Sources and destinations:: From here to there
3964 * Selecting files:: What files are part of the project?
3965 * Publishing action:: Setting the function doing the publishing
3966 * Publishing options:: Tweaking HTML export
3967 * Publishing links:: Which links keep working after publishing?
3968 * Project page index:: Publishing a list of project files
3971 @node Project alist, Sources and destinations, Configuration, Configuration
3972 @subsection The variable @code{org-publish-project-alist}
3973 @cindex org-publish-project-alist
3974 @cindex projects, for publishing
3976 Org-publish is configured almost entirely through setting the value of
3977 one variable, called @code{org-publish-project-alist}.
3978 Each element of the list configures one project, and may be in one of
3979 the two following forms:
3982 ("project-name" :property value :property value ...)
3986 ("project-name" :components ("project-name" "project-name" ...))
3990 In both cases, projects are configured by specifying property values.
3991 A project defines the set of files that will be published, as well as
3992 the publishing configuration to use when publishing those files. When
3993 a project takes the second form listed above, the individual members
3994 of the ``components'' property are taken to be components of the
3995 project, which group together files requiring different publishing
3996 options. When you publish such a ``meta-project'' all the components
3999 @node Sources and destinations, Selecting files, Project alist, Configuration
4000 @subsection Sources and destinations for files
4001 @cindex directories, for publishing
4003 Most properties are optional, but some should always be set. In
4004 particular, org-publish needs to know where to look for source files,
4005 and where to put published files.
4007 @multitable @columnfractions 0.3 0.7
4008 @item @code{:base-directory}
4009 @tab Directory containing publishing source files
4010 @item @code{:publishing-directory}
4011 @tab Directory (possibly remote) where output files will be published.
4015 @node Selecting files, Publishing action, Sources and destinations, Configuration
4016 @subsection Selecting files
4017 @cindex files, selecting for publishing
4019 By default, all files with extension @file{.org} in the base directory
4020 are considered part of the project. This can be modified by setting the
4022 @multitable @columnfractions 0.25 0.75
4023 @item @code{:base-extension}
4024 @tab Extension (without the dot!) of source files. This actually is a
4027 @item @code{:exclude}
4028 @tab Regular expression to match file names that should not be
4029 published, even though they have been selected on the basis of their
4032 @item @code{:include}
4033 @tab List of files to be included regardless of @code{:base-extension}
4034 and @code{:exclude}.
4037 @node Publishing action, Publishing options, Selecting files, Configuration
4038 @subsection Publishing Action
4039 @cindex action, for publishing
4041 Publishing means that a file is copied to the destination directory and
4042 possibly transformed in the process. The default transformation is to
4043 export Org-mode files as HTML files, and this is done by the function
4044 @code{org-publish-org-to-html} which calls the HTML exporter
4045 (@pxref{HTML export}). Other files like images only need to be copied
4046 to the publishing destination. For non-Org-mode files, you need to
4047 specify the publishing function.
4049 @multitable @columnfractions 0.3 0.7
4050 @item @code{:publishing-function}
4051 @tab Function executing the publication of a file.
4054 The function must accept two arguments: a property list containing at
4055 least a @code{:publishing-directory} property, and the name of the file
4056 to be published. It should take the specified file, make the necessary
4057 transformation (if any) and place the result into the destination folder.
4058 You can write your own publishing function, but @code{org-publish}
4059 provides one for attachments (files that only need to be copied):
4060 @code{org-publish-attachment}.
4062 @node Publishing options, Publishing links, Publishing action, Configuration
4063 @subsection Options for the HTML exporter
4064 @cindex options, for publishing
4066 The property list can be used to set many export options for the HTML
4067 exporter. In most cases, these properties correspond to user variables
4068 in Org-mode. The table below lists these properties along with the
4069 variable they belong to. See the documentation string for the
4070 respective variable for details.
4072 @multitable @columnfractions 0.3 0.7
4073 @item @code{:language} @tab @code{org-export-default-language}
4074 @item @code{:headline-levels} @tab @code{org-export-headline-levels}
4075 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
4076 @item @code{:table-of-contents} @tab @code{org-export-with-toc}
4077 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
4078 @item @code{:emphasize} @tab @code{org-export-with-emphasize}
4079 @item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts}
4080 @item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}
4081 @item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}
4082 @item @code{:fixed-width} @tab @code{org-export-with-fixed-width}
4083 @item @code{:timestamps} .@tab @code{org-export-with-timestamps}
4084 @item @code{:tags} .@tab @code{org-export-with-tags}
4085 @item @code{:tables} @tab @code{org-export-with-tables}
4086 @item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line}
4087 @item @code{:style} @tab @code{org-export-html-style}
4088 @item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html}
4089 @item @code{:inline-images} @tab @code{org-export-html-inline-images}
4090 @item @code{:expand-quoted-html} @tab @code{org-export-html-expand}
4091 @item @code{:timestamp} @tab @code{org-export-html-with-timestamp}
4092 @item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
4093 @item @code{:preamble} @tab @code{org-export-html-preamble}
4094 @item @code{:postamble} @tab @code{org-export-html-postamble}
4095 @item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble}
4096 @item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble}
4097 @item @code{:author} @tab @code{user-full-name}
4098 @item @code{:email} @tab @code{user-mail-address}
4101 When a property is given a value in org-publish-project-alist, its
4102 setting overrides the value of the corresponding user variable (if any)
4103 during publishing. options set within a file (@pxref{Export
4104 options}), however, override everything.
4106 @node Publishing links, Project page index, Publishing options, Configuration
4107 @subsection Links between published files
4108 @cindex links, publishing
4110 To create a link from one Org-mode file to another, you would use
4111 something like @samp{[[file:foo.org][The foo]]} or simply
4112 @samp{file:foo.org.} (@pxref{Hyperlinks}). Upon publishing this link
4113 becomes a link to @file{foo.html}. In this way, you can interlink the
4114 pages of your "org web" project and the links will work as expected when
4115 you publish them to HTML.
4117 You may also link to related files, such as images. Provided you are
4118 careful with relative pathnames, and provided you have also configured
4119 org-publish to upload the related files, these links will work
4120 too. @ref{Complex example} for an example of this usage.
4122 Sometime an Org-mode file to be published may contain links that are
4123 only valid in your production environment, but not in the publishing
4124 location. In this case, use the property
4126 @multitable @columnfractions 0.4 0.6
4127 @item @code{:link-validation-function}
4128 @tab Function to validate links
4132 to define a function for checking link validity. This function must
4133 accept two arguments, the file name and a directory relative to which
4134 the file name is interpreted in the production environment. If this
4135 function returns @code{nil}, then the HTML generator will only insert a
4136 description into the HTML file, but no link. One option for this
4137 function is @code{org-publish-validate-link} which checks if the given
4138 file is part of any project in @code{org-publish-project-alist}.
4140 @node Project page index, , Publishing links, Configuration
4141 @subsection Project page index
4142 @cindex index, of published pages
4144 The following properties may be used to control publishing of an
4145 index of files or summary page for a given project.
4147 @multitable @columnfractions 0.25 0.75
4148 @item @code{:auto-index}
4149 @tab When non-nil, publish an index during org-publish-current-project or
4152 @item @code{:index-filename}
4153 @tab Filename for output of index. Defaults to @file{index.org} (which
4154 becomes @file{index.html}).
4156 @item @code{:index-title}
4157 @tab Title of index page. Defaults to name of file.
4159 @item @code{:index-function}
4160 @tab Plugin function to use for generation of index.
4161 Defaults to @code{org-publish-org-index}, which generates a plain list
4162 of links to all files in the project.
4165 @node Sample configuration, Triggering publication, Configuration, Publishing
4166 @section Sample configuration
4168 Below we provide two example configurations. The first one is a simple
4169 project publishing only a set of Org-mode files. The second example is
4170 more complex, with a multi-component project.
4173 * Simple example:: One-component publishing
4174 * Complex example:: A multi-component publishing example
4177 @node Simple example, Complex example, Sample configuration, Sample configuration
4178 @subsection Example: simple publishing configuration
4180 This example publishes a set of Org-mode files to the @file{public_html}
4181 directory on the local machine.
4184 (setq org-publish-project-alist
4186 :base-directory "~/org/"
4187 :publishing-directory "~/public_html"
4188 :section-numbers nil
4189 :table-of-contents nil
4190 :style "<link rel=stylesheet
4191 href=\"../other/mystyle.css\"
4192 type=\"text/css\">")))
4195 @node Complex example, , Simple example, Sample configuration
4196 @subsection Example: complex publishing configuration
4198 This more complicated example publishes an entire website, including
4199 org files converted to HTML, image files, emacs lisp source code, and
4200 stylesheets. The publishing-directory is remote and private files are
4203 To ensure that links are preserved, care should be taken to replicate
4204 your directory structure on the web server, and to use relative file
4205 paths. For example, if your org files are kept in @file{~/org} and your
4206 publishable images in @file{~/images}, you'd link to an image with
4209 file:../images/myimage.png
4212 On the web server, the relative path to the image should be the
4213 same. You can accomplish this by setting up an "images" folder in the
4214 right place on the webserver, and publishing images to it.
4217 (setq org-publish-project-alist
4219 :base-directory "~/org/"
4220 :base-extension "org"
4221 :publishing-directory "/ssh:user@@host:~/html/notebook/"
4222 :publishing-function org-publish-org-to-html
4223 :exclude "PrivatePage.org" ;; regexp
4225 :section-numbers nil
4226 :table-of-contents nil
4227 :style "<link rel=stylesheet
4228 href=\"../other/mystyle.css\" type=\"text/css\">"
4230 :auto-postamble nil)
4233 :base-directory "~/images/"
4234 :base-extension "jpg\\|gif\\|png"
4235 :publishing-directory "/ssh:user@@host:~/html/images/"
4236 :publishing-function org-publish-attachment)
4239 :base-directory "~/other/"
4240 :base-extension "css\\|el"
4241 :publishing-directory "/ssh:user@@host:~/html/other/"
4242 :publishing-function org-publish-attachment)
4243 ("website" :components ("orgfiles" "images" "other"))))
4246 @node Triggering publication, , Sample configuration, Publishing
4247 @section Triggering publication
4249 Once org-publish is properly configured, you can publish with the
4250 following functions:
4254 Prompts for a specific project to publish.
4256 Publishes the project the current file is part of.
4258 Publishes only the current file.
4260 Publish all projects.
4263 Org uses timestamps to track when a file has changed. The above
4264 functions normally only publish changed files. You can override this and
4265 force publishing of all files by giving a prefix argument.
4267 @node Miscellaneous, Extensions and Hacking, Publishing, Top
4268 @chapter Miscellaneous
4271 * Completion:: M-TAB knows what you need
4272 * Customization:: Adapting Org-mode to your taste
4273 * In-buffer settings:: Overview of the #+KEYWORDS
4274 * The very busy C-c C-c key:: When in doubt, press C-c C-c
4275 * Clean view:: Getting rid of leading stars in the outline
4276 * TTY keys:: Using Org-mode on a tty
4277 * Interaction:: Other Emacs packages
4278 * Bugs:: Things which do not work perfectly
4281 @node Completion, Customization, Miscellaneous, Miscellaneous
4283 @cindex completion, of @TeX{} symbols
4284 @cindex completion, of TODO keywords
4285 @cindex completion, of dictionary words
4286 @cindex completion, of option keywords
4287 @cindex completion, of CamelCase links
4288 @cindex completion, of tags
4289 @cindex @TeX{} symbol completion
4290 @cindex TODO keywords completion
4291 @cindex dictionary word completion
4292 @cindex option keyword completion
4293 @cindex CamelCase link completion
4294 @cindex tag completion
4296 Org-mode supports in-buffer completion. This type of completion does
4297 not make use of the minibuffer. You simply type a few letters into
4298 the buffer and use the key to complete text right there.
4303 Complete word at point
4306 At the beginning of a headline, complete TODO keywords.
4308 After @samp{\}, complete @TeX{} symbols supported by the exporter.
4310 After @samp{*}, complete CamelCase versions of all headlines in the
4313 After @samp{:}, complete tags used elsewhere in the buffer.
4315 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
4316 @samp{OPTIONS} which set file-specific options for Org-mode. When the
4317 option keyword is already complete, pressing @kbd{M-@key{TAB}} again
4318 will insert example settings for this keyword.
4320 Elsewhere, complete dictionary words using ispell.
4324 @node Customization, In-buffer settings, Completion, Miscellaneous
4325 @section Customization
4326 @cindex customization
4327 @cindex options, for customization
4328 @cindex variables, for customization
4330 There are more than 100 variables that can be used to customize
4331 Org-mode. For the sake of compactness of the manual, we are not
4332 describing the variables here. A structured overview of customization
4333 variables is available with @kbd{M-x org-customize}. Or select
4334 @code{Browse Org Group} from the @code{Org->Customization} menu. Many
4335 settings can also be activated on a per-file basis, by putting special
4336 lines into the buffer (@pxref{In-buffer settings}).
4338 @node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
4339 @section Summary of in-buffer settings
4340 @cindex in-buffer settings
4341 @cindex special keywords
4343 Org-mode uses special lines in the buffer to define settings on a
4344 per-file basis. These lines start with a @samp{#+} followed by a
4345 keyword, a colon, and then individual words defining a setting. Several
4346 setting words can be in the same line, but you can also have multiple
4347 lines for the keyword. While these settings are described throughout
4348 the manual, here is a summary. After changing any of those lines in the
4349 buffer, press @kbd{C-c C-c} with the cursor still in the line to
4350 activate the changes immediately. Otherwise they become effective only
4351 when the file is visited again in a new Emacs session.
4355 This line sets options to be used at startup of org-mode, when an
4356 Org-mode file is being visited. The first set of options deals with the
4357 initial visibility of the outline tree. The corresponding variable for
4358 global default settings is @code{org-startup-folded}, with a default
4359 value @code{t}, which means @code{overview}.
4361 overview @r{top-level headlines only}
4362 content @r{all headlines}
4363 showall @r{no folding at all, show everything}
4365 Then there are options for aligning tables upon visiting a file. This
4366 is useful in files containing narrowed table columns. The corresponding
4367 variable is @code{org-startup-align-all-tables}, with a default value
4370 align @r{align all tables}
4371 noalign @r{don't align tables on startup}
4373 Logging when a TODO item is marked DONE (variable @code{org-log-done})
4374 can be configured using these options.
4376 logging @r{record a timestamp when an item is marked DONE}
4377 nologging @r{don't record when items are marked DONE}
4379 Here are the options for hiding leading stars in outline headings. The
4380 corresponding variables are @code{org-hide-leading-stars} and
4381 @code{org-odd-levels-only}, both with a default setting @code{nil}
4382 (meaning @code{showstars} and @code{oddeven}).
4384 hidestars @r{make all but one of the stars starting a headline invisible.}
4385 showstars @r{show all stars starting a headline}
4386 odd @r{allow only odd outline levels (1,3,...)}
4387 oddeven @r{allow all outline levels}
4389 @item #+SEQ_TODO: #+TYP_TODO:
4390 These lines set the TODO keywords and their interpretation in the
4391 current file. The corresponding variables are @code{org-todo-keywords}
4392 and @code{org-todo-interpretation}.
4393 @item #+TAGS: TAG1(c1) TAG2(c2)
4394 These lines (several such lines are allowed) specify the legal tags in
4395 this file, and (potentially) the corresponding @emph{fast tag selection}
4396 keys. The corresponding variable is @code{org-tag-alist}.
4398 This line sets the category for the agenda file. The category applies
4399 for all subsequent lines until the next @samp{#+CATEGORY} line, or the
4402 This line contains the formulas for the table directly above the line.
4403 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:
4404 These lines provide settings for exporting files. For more details see
4405 @ref{Export options}.
4408 @node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
4409 @section The very busy C-c C-c key
4412 The key @kbd{C-c C-c} has many purposes in org-mode, which are all
4413 mentioned scattered throughout this manual. One specific function of
4414 this key is to add @emph{tags} to a headline (@pxref{Tags}). In many
4415 other circumstances it means something like @emph{Hey Org-mode, look
4416 here and update according to what you see here}. Here is a summary of
4417 what this means in different contexts.
4421 If there are highlights in the buffer from the creation of a sparse
4422 tree, or from clock display, remove these highlights.
4424 If the cursor is in one of the special @code{#+KEYWORD} lines, this
4425 triggers scanning the buffer for these lines and updating the
4428 If the cursor is inside a table, realign the table. This command
4429 works even if the automatic table editor has been turned off.
4431 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
4434 If the cursor is inside a table created by the @file{table.el} package,
4435 activate that table.
4437 If the current buffer is a remember buffer, close note and file it.
4438 with a prefix argument, file it without further interaction to the default
4441 If the cursor is on a @code{<<<target>>>}, update radio targets and
4442 corresponding links in this buffer.
4444 If the cursor is in a plain list item with a checkbox, toggle the status
4447 If the cursor is on a numbered item in a plain list, renumber the
4451 @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
4452 @section A cleaner outline view
4453 @cindex hiding leading stars
4454 @cindex clean outline view
4456 Some people find it noisy and distracting that the Org-mode headlines
4457 are starting with a potentially large number of stars. For example
4458 the tree from @ref{Headlines}:
4461 * Top level headline
4467 * Another top level headline
4471 Unfortunately this is deeply ingrained into the code of Org-mode and
4472 cannot be easily changed. You can, however, modify the display in such
4473 a way that all leading stars become invisible and the outline more easy
4474 to read. To do this, customize the variable
4475 @code{org-hide-leading-stars} like this:
4478 (setq org-hide-leading-stars t)
4482 or change this on a per-file basis with one of the lines (anywhere in
4486 #+STARTUP: showstars
4487 #+STARTUP: hidestars
4491 Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate
4494 With stars hidden, the tree becomes:
4497 * Top level headline
4503 * Another top level headline
4507 Note that the leading stars are not truly replaced by whitespace, they
4508 are only fontified with the face @code{org-hide} that uses the
4509 background color as font color. If are are not using either white or
4510 black background, you may have to customize this face to get the wanted
4511 effect. Another possibility is to set this font such that the extra
4512 stars are @i{almost} invisible, for example using the color
4513 @code{grey90} on a white background.
4515 Things become cleaner still if you skip all the even levels and use only
4516 odd levels 1, 3, 5..., effectively adding two stars to go from one
4517 outline level to the next:
4520 * Top level headline
4526 * Another top level headline
4530 In order to make the structure editing and export commands handle this
4531 convention correctly, use
4534 (setq org-odd-levels-only t)
4538 or set this on a per-file basis with one of the following lines (don't
4539 forget to press @kbd{C-c C-c} with the cursor in the startup line to
4540 activate changes immediately).
4547 You can convert an Org-mode file from single-star-per-level to the
4548 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
4549 RET} in that file. The reverse operation is @kbd{M-x
4550 org-convert-to-oddeven-levels}.
4552 @node TTY keys, Interaction, Clean view, Miscellaneous
4553 @section Using org-mode on a tty
4554 @cindex tty keybindings
4556 Org-mode uses a number of keys that are not accessible on a tty. This
4557 applies to most special keys like cursor keys, @key{TAB} and
4558 @key{RET}, when these are combined with modifier keys like @key{Meta}
4559 and/or @key{Shift}. Org-mode uses these bindings because it needs to
4560 provide keys for a large number of commands, and because these keys
4561 appeared particularly easy to remember. In order to still be able to
4562 access the core functionality of Org-mode on a tty, alternative
4563 bindings are provided. Here is a complete list of these bindings,
4564 which are obviously more cumbersome to use. Note that sometimes a
4565 work-around can be better. For example changing a time stamp is
4566 really only fun with @kbd{S-@key{cursor}} keys. On a tty you would
4567 rather use @kbd{C-c .} to re-insert the timestamp.
4569 @multitable @columnfractions 0.15 0.2 0.2
4570 @item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2}
4571 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab
4572 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}}
4573 @item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab
4574 @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{@key{Esc} @key{right}}
4575 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab
4576 @item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{@key{Esc} @key{up}}
4577 @item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab
4578 @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{@key{Esc} @key{down}}
4579 @item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab
4580 @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab
4581 @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{@key{Esc} @key{RET}}
4582 @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab
4583 @item @kbd{S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab
4584 @item @kbd{S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab
4585 @item @kbd{S-@key{up}} @tab @kbd{C-c C-x @key{up}} @tab
4586 @item @kbd{S-@key{down}} @tab @kbd{C-c C-x @key{down}} @tab
4589 @node Interaction, Bugs, TTY keys, Miscellaneous
4590 @section Interaction with other packages
4591 @cindex packages, interaction with other
4592 Org-mode lives in the world of GNU Emacs and interacts in various ways
4593 with other code out there.
4596 * Cooperation:: Packages Org-mode cooperates with
4597 * Conflicts:: Packages that lead to conflicts
4601 @node Cooperation, Conflicts, Interaction, Interaction
4602 @subsection Packages that Org-mode cooperates with
4605 @cindex @file{calc.el}
4606 @item @file{calc.el} by Dave Gillespie
4607 Org-mode uses the calc package for implementing spreadsheet
4608 functionality in its tables (@pxref{Table calculations}). Org-modes
4609 checks for the availability of calc by looking for the function
4610 @code{calc-eval} which should be autoloaded in your setup if calc has
4611 been installed properly. As of Emacs 22, calc is part of the Emacs
4612 distribution. Another possibility for interaction between the two
4613 packages is using calc for embedded calculations. @xref{Embedded Mode,
4614 , Embedded Mode, calc, GNU Emacs Calc Manual}.
4615 @cindex @file{constants.el}
4616 @item @file{constants.el} by Carsten Dominik
4617 In a table formula (@pxref{Table calculations}), it is possible to use
4618 names for natural constants or units. Instead of defining your own
4619 constants in the variable @code{org-table-formula-constants}, install
4620 the @file{constants} package which defines a large number of constants
4621 and units, and lets you use unit prefixes like @samp{M} for
4622 @samp{Mega} etc. You will need version 2.0 of this package, available
4623 at @url{http://www.astro.uva.nl/~dominik/Tools}. Org-mode checks for
4624 the function @code{constants-get}, which has to be autoloaded in your
4625 setup. See the installation instructions in the file
4626 @file{constants.el}.
4627 @item @file{cdlatex.el} by Carsten Dominik
4628 @cindex @file{cdlatex.el}
4629 Org-mode can make use of the cdlatex package to efficiently enter
4630 La@TeX{} fragments into Org-mode files.
4631 @file{cdlatex.el} is not part of Emacs, find it on the web.
4632 @item @file{remember.el} by John Wiegley
4633 @cindex @file{remember.el}
4634 Org mode cooperates with remember, see @ref{Remember}.
4635 @file{Remember.el} is not part of Emacs, find it on the web.
4636 @cindex @file{table.el}
4637 @item @file{table.el} by Takaaki Ota
4638 Org mode cooperates with table.el, see @ref{table.el}. @file{table.el}
4639 is part of Emacs 22.
4642 @node Conflicts, , Cooperation, Interaction
4643 @subsection Packages that lead to conflicts with Org-mode
4647 @cindex @file{allout.el}
4648 @item @file{allout.el} by Ken Manheimer
4649 Startup of Org-mode may fail with the error message
4650 @code{(wrong-type-argument keymapp nil)} when there is an outdated
4651 version @file{allout.el} on the load path, for example the version
4652 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem will
4653 disappear. If for some reason you cannot do this, make sure that org.el
4654 is loaded @emph{before} @file{allout.el}, for example by putting
4655 @code{(require 'org)} early enough into your @file{.emacs} file.
4657 @cindex @file{CUA.el}
4658 @item @file{CUA.el} by Kim. F. Storm
4659 Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys
4660 used by CUA-mode (as well as pc-select-mode and s-region-mode) to
4661 select and extend the region. If you want to use one of these
4662 packages along with Org-mode, configure the variable
4663 @code{org-CUA-compatible}. When set, Org-mode will move the following
4664 keybindings in org-mode files, and in the agenda buffer (but not
4665 during date selection).
4668 S-UP -> M-p S-DOWN -> M-n
4669 S-LEFT -> M-- S-RIGHT -> M-+
4673 Yes, these are unfortunately more difficult to remember. If you want
4674 to have other replacement keys, look at the variable
4675 @code{org-disputed-keys}.
4676 @item @file{windmove.el} by Hovav Shacham
4677 @cindex @file{windmove.el}
4678 Also this package uses the @kbd{S-<cursor>} keys, so everything written
4679 in the paragraph above about CUA mode also applies here.
4683 @node Bugs, , Interaction, Miscellaneous
4687 Here is a list of things that should work differently, but which I
4688 have found too hard to fix.
4692 If a table field starts with a link, and if the corresponding table
4693 column is narrowed (@pxref{Narrow columns}) to a width too small to
4694 display the link, the field would look entirely empty even though it is
4695 not. To prevent this, Org-mode throws an error. The work-around is to
4696 make the column wide enough to fit the link, or to add some text (at
4697 least 2 characters) before the link in the same field.
4699 Narrowing table columns does not work on XEmacs, because the
4700 @code{format} function does not transport text properties.
4702 Text in an entry protected with the @samp{QUOTE} keyword should not
4705 When the application called by @kbd{C-c C-o} to open a file link fails
4706 (for example because the application does not exist or refuses to open
4707 the file), it does so silently. No error message is displayed.
4709 The remote-editing commands in the agenda buffer cannot be undone with
4710 @code{undo} called from within the agenda buffer. But you can go to
4711 the corresponding buffer (using @key{TAB} or @key{RET} and execute
4714 Recalculating a table line applies the formulas from left to right.
4715 If a formula uses @emph{calculated} fields further down the row,
4716 multiple recalculation may be needed to get all fields consistent.
4718 A single letter cannot be made bold, for example @samp{*a*}.
4720 The exporters work well, but could be made more efficient.
4724 @node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top
4725 @appendix Extensions, Hooks and Hacking
4727 This appendix lists extensions for Org-mode written by other authors.
4728 It also covers some aspects where users can easily extend the
4729 functionality of Org-mode.
4732 * Extensions:: Existing 3rd-part extensions
4733 * Dynamic blocks:: Automatically filled blocks
4736 @node Extensions, Dynamic blocks, Extensions and Hacking, Extensions and Hacking
4737 @section Third-party extensions for Org-mode
4739 The following extensions for Org-mode have been written by other people:
4742 @cindex @file{org-mouse.el}
4743 @item @file{org-mouse.el} by Piotr Zielinski
4744 This package implements extended mouse functionality for Org-mode. It
4745 allows you to cycle visibility and to edit the document structure with
4746 the mouse. Best of all, it provides a context-sensitive menu on
4747 @key{mouse-3} that changes depending on the context of a mouse-click.
4748 @file{org-mouse.el} is freely available at @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}.
4749 @cindex @file{org-publish.el}
4750 @item @file{org-publish.el} by David O'Toole
4751 This package provides facilities for publishing related sets of Org-mode
4752 files together with linked files like images as a webpages. It is
4753 highly configurable and can be used for other publishing purposes as
4754 well. As of Org-mode version 4.30, @file{org-publish.el} is part of the
4755 Org-mode distribution. It is not yet part of Emacs, however, a delay
4756 caused by the preparations for the 22.1 release. In the mean time,
4757 @file{org-publish.el} can be downloaded from David's site:
4758 @url{http://dto.freeshell.org/e/org-publish.el}.
4759 @cindex @file{org-blog.el}
4760 @item @file{org-blog.el} by David O'Toole
4761 A blogging plug-in for @file{org-publish.el}.
4762 @url{http://dto.freeshell.org/notebook/OrgMode.html}.
4763 @cindex @file{org-blogging.el}
4764 @item @file{org-blogging.el} by Bastien Guerry
4765 Publish Org-mode files as
4766 blogs. @url{http://www.cognition.ens.fr/~guerry/org-blogging.html}.
4769 @node Dynamic blocks, , Extensions, Extensions and Hacking
4770 @section Dynamic blocks
4772 Org-mode documents can contain @emph{dynamic blocks}. These are
4773 specially marked regions that are updates by some user-written
4774 function. A good example for such a block is the clock table inserted
4775 by the command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
4777 Dynamic block are enclosed by a BEGIN-END structure that assigns a name
4778 to the block and can also specify parameters for the function producing
4779 the content of the block.
4782 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 .....
4787 Dynamic blocks are updated with the following commands
4792 Update dynamic block at point.
4793 @kindex C-u C-c C-x C-u
4794 @item C-u C-c C-x C-u
4795 Update all dynamic blocks in the current file.
4798 Updating a dynamic block means to remove all the text between BEGIN and
4799 END, parse the BEGIN line for parameters and then call the specific
4800 writer function for this block to insert the new content. For a block
4801 with name @code{myblock}, the writer function is
4802 @code{org-dblock-write:myblock} with as only parameter a property list
4803 with the parameters given in the begin line. Here is a trivial example
4804 of a block that keeps track of when the block update function was last
4808 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
4814 The corresponding block writer function could look like this:
4817 (defun org-dblock-write:date-and-time (params)
4818 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
4819 (insert "Last block update at: "
4820 (format-time-string fmt (current-time)))))
4823 If you want to make sure that all dynamic blocks are always up-to-date,
4824 you could add the function @code{org-update-all-dblocks} to a hook, for
4825 example @code{before-save-hook}. @code{org-update-all-dblocks} is
4826 written in a way that is does nothing in buffers that are not in Org-mode.
4829 @node History and Acknowledgments, Index, Extensions and Hacking, Top
4830 @appendix History and Acknowledgments
4831 @cindex acknowledgments
4835 The beginnings of Org-mode go back to 2003. It was borne out of
4836 frustration over the user interface of the emacs outline-mode. All I
4837 wanted was to make working with an outline tree possible without having
4838 to remember more than 10 commands just for hiding and unhiding parts of
4839 the outline tree, and to allow to restructure a tree easily. Visibility
4840 cycling and structure editing were originally implemented in the package
4841 @file{outline-magic.el}, but quickly moved to the more general
4842 @file{org.el}. TODO entries, basic time stamps, and table support were
4843 added next, and highlight the two main goals that Org-mode still has
4844 today: To create a new, outline-based, plain text mode with innovative
4845 and intuitive editing features, and to incorporate project planning
4846 functionality directly into a notes file.
4848 Since the first release, hundreds of emails to me or on
4849 @code{emacs-orgmode@@gnu.org} have provided a constant stream of bug
4850 reports, feedback, new ideas, and sometimes even patches and add-on
4851 code. Many thanks to everyone who has helped to improve this package.
4852 I am trying to keep here a list of the people who had significant
4853 influence in shaping one or more aspects of Org-mode. The list may not
4854 be complete, if I have forgotten someone, please accept my apologies and
4859 @i{Thomas Baumann} contributed the code for links to the MH-E email
4862 @i{Alex Bochannek} provided a patch for rounding time stamps.
4864 @i{Charles Cave}'s suggestion sparked the implementation of templates
4867 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
4870 @i{Gregory Chernov} patched support for lisp forms into table
4871 calculations and improved XEmacs compatibility, in particular by porting
4872 @file{nouline.el} to XEmacs.
4874 @i{Sacha Chua} suggested to copy some linking code from Planner.
4876 @i{Kees Dullemond} inspired the use of narrowed tabled columns.
4878 @i{Christian Egli} converted the documentation into TeXInfo format,
4879 patched CSS formatting into the HTML exporter, and inspired the agenda.
4881 @i{Nic Ferrier} contributed mailcap and XOXO support.
4883 @i{Niels Giessen} had the idea to automatically archive DONE trees.
4885 @i{Bastien Guerry} provoded extensive feedback.
4887 @i{Kai Grossjohann} pointed out key-binding conflicts caused by
4890 @i{Leon Liu} asked for embedded LaTeX and tested it.
4892 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
4895 @i{Todd Neal} provided patches for links to Info files and elisp forms.
4897 @i{Tim O'Callaghan} suggested in-file links, search options for general
4898 file links, and TAGS.
4900 @i{Oliver Oppitz} suggested multi-state TODO items.
4902 @i{Scott Otterson} sparked the introduction of descriptive text for
4903 links, among other things.
4905 @i{Pete Phillips} helped the development of the TAGS feature.
4907 @i{T.V. Raman} reported bugs and suggested improvements.
4909 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
4912 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
4914 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
4915 conflict with @file{allout.el}.
4917 @i{Philip Rooke} created the Org-mode reference card and provided lots
4920 @i{Christian Schlauer} proposed angular brackets around links, among
4923 Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s
4924 @file{organizer-mode.el}.
4926 @i{Daniel Sinder} came up with the idea of internal archiving by locking
4929 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
4930 chapter about publishing.
4932 @i{J@"urgen Vollmer} contributed code generating the table of contents
4935 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
4938 @i{David Wainberg} suggested archiving, and improvements to the linking
4941 @i{John Wiegley} wrote @file{emacs-wiki.el} and @file{planner.el}. The
4942 development of Org-mode was fully independent, and both systems are
4943 really different beasts in their basic ideas and implementation details.
4944 I later looked at John's code, however, and learned from his
4945 implementation of (i) links where the link itself is hidden and only a
4946 description is shown, and (ii) popping up a calendar to select a date.
4948 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
4951 @i{Roland Winkler} requested additional keybindings to make Org-mode
4954 @i{Piotr Zielinski} wrote @file{org-mouse.el} and showed how to follow
4959 @node Index, Key Index, History and Acknowledgments, Top
4964 @node Key Index, , Index, Top
4972 arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac