3 @setfilename ../../info/org
4 @settitle Org Mode Manual
7 @set DATE December 2007
11 * Org Mode: (org). Outline-based notes management and organizer
14 @c Version and Contact Info
15 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}
16 @set AUTHOR Carsten Dominik
17 @set MAINTAINER Carsten Dominik
18 @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
19 @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,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, 2007 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 * Tags:: Tagging headlines and matching sets of tags
84 * Properties and columns:: Storing information about an entry
85 * Dates and times:: Making items useful for planning
86 * Remember:: Quickly adding nodes to the outline tree
87 * Agenda views:: Collecting information into views
88 * Embedded LaTeX:: LaTeX fragments and formulas
89 * Exporting:: Sharing and publishing of notes
90 * Publishing:: Create a web site of linked Org-mode files
91 * Miscellaneous:: All the rest which did not fit elsewhere
92 * Extensions and Hacking:: It is possible to write add-on code
93 * History and Acknowledgments:: How Org-mode came into being
94 * Index:: The fast road to specific information
95 * Key Index:: Key bindings and where they are described
98 --- The Detailed Node Listing ---
102 * Summary:: Brief summary of what Org-mode does
103 * Installation:: How to install a downloaded version of Org-mode
104 * Activation:: How to activate Org-mode for certain buffers.
105 * Feedback:: Bug reports, ideas, patches etc.
106 * Conventions:: Type-setting conventions in the manual
110 * Outlines:: Org-mode is based on outline-mode
111 * Headlines:: How to typeset org-tree headlines
112 * Visibility cycling:: Show and hide, much simplified
113 * Motion:: Jumping to other headlines
114 * Structure editing:: Changing sequence and level of headlines
115 * Archiving:: Move done task trees to a different place
116 * Sparse trees:: Matches embedded in context
117 * Plain lists:: Additional structure within an entry
118 * Drawers:: Tucking stuff away
119 * orgstruct-mode:: Structure editing outside Org-mode
123 * ARCHIVE tag:: Marking a tree as inactive
124 * Moving subtrees:: Moving a tree to an archive file
128 * Built-in table editor:: Simple tables
129 * Narrow columns:: Stop wasting space in tables
130 * Column groups:: Grouping to trigger vertical lines
131 * orgtbl-mode:: The table editor as minor mode
132 * The spreadsheet:: The table editor has spreadsheet capabilities.
136 * References:: How to refer to another field or range
137 * Formula syntax for Calc:: Using Calc to compute stuff
138 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
139 * Field formulas:: Formulas valid for a single field
140 * Column formulas:: Formulas valid for an entire column
141 * Editing and debugging formulas:: Fixing formulas
142 * Updating the table:: Recomputing all dependent fields
143 * Advanced features:: Field names, parameters and automatic recalc
147 * Link format:: How links in Org-mode are formatted
148 * Internal links:: Links to other places in the current file
149 * External links:: URL-like links to the world
150 * Handling links:: Creating, inserting and following
151 * Using links outside Org-mode:: Linking from my C source code?
152 * Link abbreviations:: Shortcuts for writing complex links
153 * Search options:: Linking to a specific location
154 * Custom searches:: When the default search is not enough
158 * Radio targets:: Make targets trigger links in plain text.
162 * TODO basics:: Marking and displaying TODO entries
163 * TODO extensions:: Workflow and assignments
164 * Progress logging:: Dates and notes for progress
165 * Priorities:: Some things are more important than others
166 * Breaking down tasks:: Splitting a task into manageable pieces
167 * Checkboxes:: Tick-off lists
169 Extended use of TODO keywords
171 * Workflow states:: From TODO to DONE in steps
172 * TODO types:: I do this, Fred the rest
173 * Multiple sets in one file:: Mixing it all, and still finding your way
174 * Fast access to TODO states:: Single letter selection of a state
175 * Per file keywords:: Different files, different requirements
176 * Faces for TODO keywords:: Highlighting states
180 * Closing items:: When was this entry marked DONE?
181 * Tracking TODO state changes:: When did the status change?
185 * Tag inheritance:: Tags use the tree structure of the outline
186 * Setting tags:: How to assign tags to a headline
187 * Tag searches:: Searching for combinations of tags
189 Properties and Columns
191 * Property syntax:: How properties are spelled out
192 * Special properties:: Access to other Org-mode features
193 * Property searches:: Matching property values
194 * Property inheritance:: Passing values down the tree
195 * Column view:: Tabular viewing and editing
196 * Property API:: Properties for Lisp programmers
200 * Defining columns:: The COLUMNS format property
201 * Using column view:: How to create and use column view
202 * Capturing Column View:: A dynamic block for column view
206 * Scope of column definitions:: Where defined, where valid?
207 * Column attributes:: Appearance and content of a column
211 * Time stamps:: Assigning a time to a tree entry
212 * Creating timestamps:: Commands which insert timestamps
213 * Deadlines and scheduling:: Planning your work
214 * Clocking work time::
218 * The date/time prompt:: How org-mode helps you entering date and time
219 * Custom time format:: Making dates look differently
221 Deadlines and Scheduling
223 * Inserting deadline/schedule:: Planning items
224 * Repeated tasks:: Items that show up again and again
228 * Setting up remember:: Some code for .emacs to get things going
229 * Remember templates:: Define the outline of different note types
230 * Storing notes:: Directly get the note to where it belongs
231 * Refiling notes:: Moving a note or task to a project
235 * Agenda files:: Files being searched for agenda information
236 * Agenda dispatcher:: Keyboard access to agenda views
237 * Built-in agenda views:: What is available out of the box?
238 * Presentation and sorting:: How agenda items are prepared for display
239 * Agenda commands:: Remote editing of org trees
240 * Custom agenda views:: Defining special searches and views
242 The built-in agenda views
244 * Weekly/Daily agenda:: The calendar page with current tasks
245 * Global TODO list:: All unfinished action items
246 * Matching tags and properties:: Structured information with fine-tuned search
247 * Timeline:: Time-sorted view for single file
248 * Stuck projects:: Find projects you need to review
250 Presentation and sorting
252 * Categories:: Not all tasks are equal
253 * Time-of-day specifications:: How the agenda knows the time
254 * Sorting of agenda items:: The order of things
258 * Storing searches:: Type once, use often
259 * Block agenda:: All the stuff you need in a single buffer
260 * Setting Options:: Changing the rules
261 * Exporting Agenda Views:: Writing agendas to files.
262 * Extracting Agenda Information for other programs::
266 * Math symbols:: TeX macros for symbols and Greek letters
267 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
268 * LaTeX fragments:: Complex formulas made easy
269 * Processing LaTeX fragments:: Previewing LaTeX processing
270 * CDLaTeX mode:: Speed up entering of formulas
274 * ASCII export:: Exporting to plain ASCII
275 * HTML export:: Exporting to HTML
276 * LaTeX export:: Exporting to LaTeX
277 * XOXO export:: Exporting to XOXO
278 * iCalendar export:: Exporting in iCalendar format
279 * Text interpretation:: How the exporter looks at the file
283 * HTML Export commands:: How to invoke LaTeX export
284 * Quoting HTML tags:: Using direct HTML in Org-mode
285 * Links:: Transformation of links for HTML
286 * Images:: How to include images
287 * CSS support:: Changing the appearence of the output
291 * LaTeX export commands:: How to invoke LaTeX export
292 * Quoting LaTeX code:: Incorporating literal LaTeX code
293 * Sectioning structure::
295 Text interpretation by the exporter
297 * Comment lines:: Some lines will not be exported
298 * Initial text:: Text before the first headline
299 * Footnotes:: Numbers like [1]
300 * Quoted examples:: Inserting quoted chnuks of text
301 * Enhancing text:: Subscripts, symbols and more
302 * Export options:: How to influence the export settings
306 * Configuration:: Defining projects
307 * Sample configuration:: Example projects
308 * Triggering publication:: Publication commands
312 * Project alist:: The central configuration variable
313 * Sources and destinations:: From here to there
314 * Selecting files:: What files are part of the project?
315 * Publishing action:: Setting the function doing the publishing
316 * Publishing options:: Tweaking HTML export
317 * Publishing links:: Which links keep working after publishing?
318 * Project page index:: Publishing a list of project files
322 * Simple example:: One-component publishing
323 * Complex example:: A multi-component publishing example
327 * Completion:: M-TAB knows what you need
328 * Customization:: Adapting Org-mode to your taste
329 * In-buffer settings:: Overview of the #+KEYWORDS
330 * The very busy C-c C-c key:: When in doubt, press C-c C-c
331 * Clean view:: Getting rid of leading stars in the outline
332 * TTY keys:: Using Org-mode on a tty
333 * Interaction:: Other Emacs packages
334 * Bugs:: Things which do not work perfectly
336 Interaction with other packages
338 * Cooperation:: Packages Org-mode cooperates with
339 * Conflicts:: Packages that lead to conflicts
341 Extensions, Hooks and Hacking
343 * Extensions:: Existing 3rd-part extensions
344 * Adding hyperlink types:: New custom link types
345 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
346 * Dynamic blocks:: Automatically filled blocks
347 * Special agenda views:: Customized views
348 * Using the property API:: Writing programs that use entry properties
350 Tables and Lists in arbitrary syntax
352 * Radio tables:: Sending and receiving
353 * A LaTeX example:: Step by step, almost a tutorial
354 * Translator functions:: Copy and modify
355 * Radio lists:: Doing the same for lists.
360 @node Introduction, Document structure, Top, Top
361 @chapter Introduction
365 * Summary:: Brief summary of what Org-mode does
366 * Installation:: How to install a downloaded version of Org-mode
367 * Activation:: How to activate Org-mode for certain buffers.
368 * Feedback:: Bug reports, ideas, patches etc.
369 * Conventions:: Type-setting conventions in the manual
372 @node Summary, Installation, Introduction, Introduction
376 Org-mode is a mode for keeping notes, maintaining TODO lists, and doing
377 project planning with a fast and effective plain-text system.
379 Org-mode develops organizational tasks around NOTES files that contain
380 lists or information about projects as plain text. Org-mode is
381 implemented on top of outline-mode, which makes it possible to keep the
382 content of large files well structured. Visibility cycling and
383 structure editing help to work with the tree. Tables are easily created
384 with a built-in table editor. Org-mode supports TODO items, deadlines,
385 time stamps, and scheduling. It dynamically compiles entries into an
386 agenda that utilizes and smoothly integrates much of the Emacs calendar
387 and diary. Plain text URL-like links connect to websites, emails,
388 Usenet messages, BBDB entries, and any files related to the projects.
389 For printing and sharing of notes, an Org-mode file can be exported as a
390 structured ASCII file, as HTML, or (todo and agenda items only) as an
391 iCalendar file. It can also serve as a publishing tool for a set of
394 An important design aspect that distinguishes Org-mode from for example
395 Planner/Muse is that it encourages to store every piece of information
396 only once. In Planner, you have project pages, day pages and possibly
397 other files, duplicating some information such as tasks. In Org-mode,
398 you only have notes files. In your notes you mark entries as tasks,
399 label them with tags and timestamps. All necessary lists like a
400 schedule for the day, the agenda for a meeting, tasks lists selected by
401 tags etc are created dynamically when you need them.
403 Org-mode keeps simple things simple. When first fired up, it should
404 feel like a straightforward, easy to use outliner. Complexity is not
405 imposed, but a large amount of functionality is available when you need
406 it. Org-mode is a toolbox and can be used in different ways, for
410 @r{@bullet{} outline extension with visibility cycling and structure editing}
411 @r{@bullet{} ASCII system and table editor for taking structured notes}
412 @r{@bullet{} ASCII table editor with spreadsheet-like capabilities}
413 @r{@bullet{} TODO list editor}
414 @r{@bullet{} full agenda and planner with deadlines and work scheduling}
415 @r{@bullet{} environment to implement David Allen's GTD system}
416 @r{@bullet{} a basic database application}
417 @r{@bullet{} simple hypertext system, with HTML and LaTeX export}
418 @r{@bullet{} publishing tool to create a set of interlinked webpages}
421 Org-mode's automatic, context sensitive table editor with spreadsheet
422 capabilities can be integrated into any major mode by activating the
423 minor Orgtbl-mode. Using a translation step, it can be used to maintain
424 tables in arbitrary file types, for example in La@TeX{}. The structure
425 editing and list creation capabilities can be used outside Org-mode with
426 the minor Orgstruct-mode.
429 There is a website for Org-mode which provides links to the newest
430 version of Org-mode, as well as additional information, frequently asked
431 questions (FAQ), links to tutorials etc. This page is located at
432 @uref{http://orgmode.org}.
437 @node Installation, Activation, Summary, Introduction
438 @section Installation
442 @b{Important:} @i{If Org-mode is part of the Emacs distribution or an
443 XEmacs package, please skip this section and go directly to
446 If you have downloaded Org-mode from the Web, you must take the
447 following steps to install it: Go into the Org-mode distribution
448 directory and edit the top section of the file @file{Makefile}. You
449 must set the name of the Emacs binary (likely either @file{emacs} or
450 @file{xemacs}), and the paths to the directories where local Lisp and
451 Info files are kept. If you don't have access to the system-wide
452 directories, create your own two directories for these files, enter them
453 into the Makefile, and make sure Emacs finds the Lisp files by adding
454 the following line to @file{.emacs}:
457 (setq load-path (cons "~/path/to/lispdir" load-path))
460 @b{XEmacs users now need to install the file @file{noutline.el} from
461 the @file{xemacs} subdirectory of the Org-mode distribution. Use the
465 @b{make install-noutline}
468 @noindent Now byte-compile and install the Lisp files with the shell
476 @noindent If you want to install the info documentation, use this command:
482 @noindent Then add to @file{.emacs}:
485 ;; This line only if org-mode is not part of the X/Emacs distribution.
486 (require 'org-install)
489 @node Activation, Feedback, Installation, Introduction
493 @cindex global keybindings
494 @cindex keybindings, global
497 @b{Important:} @i{If you use copy-and-paste to copy lisp code from the
498 PDF documentation as viewed by Acrobat reader to your .emacs file, the
499 single quote character comes out incorrectly and the code will not work.
500 You need to fix the single quotes by hand, or copy from Info
504 Add the following lines to your @file{.emacs} file. The last two lines
505 define @emph{global} keys for the commands @command{org-store-link} and
506 @command{org-agenda} - please choose suitable keys yourself.
509 ;; The following lines are always needed. Choose your own keys.
510 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
511 (global-set-key "\C-cl" 'org-store-link)
512 (global-set-key "\C-ca" 'org-agenda)
515 Furthermore, you must activate @code{font-lock-mode} in org-mode
516 buffers, because significant functionality depends on font-locking being
517 active. You can do this with either one of the following two lines
518 (XEmacs user must use the second option):
520 (global-font-lock-mode 1) ; for all buffers
521 (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
524 @cindex org-mode, turning on
525 With this setup, all files with extension @samp{.org} will be put
526 into Org-mode. As an alternative, make the first line of a file look
530 MY PROJECTS -*- mode: org; -*-
533 @noindent which will select Org-mode for this buffer no matter what
534 the file's name is. See also the variable
535 @code{org-insert-mode-line-in-empty-file}.
537 @node Feedback, Conventions, Activation, Introduction
544 If you find problems with Org-mode, or if you have questions, remarks,
545 or ideas about it, please contact the maintainer @value{MAINTAINER} at
546 @value{MAINTAINEREMAIL}.
548 For bug reports, please provide as much information as possible,
549 including the version information of Emacs (@kbd{C-h v emacs-version
550 @key{RET}}) and Org-mode (@kbd{C-h v org-version @key{RET}}), as well as
551 the Org-mode related setup in @file{.emacs}. If an error occurs, a
552 backtrace can be very useful (see below on how to create one). Often a
553 small example file helps, along with clear information about:
556 @item What exactly did you do?
557 @item What did you expect to happen?
558 @item What happened instead?
560 @noindent Thank you for helping to improve this mode.
562 @subsubheading How to create a useful backtrace
564 @cindex backtrace of an error
565 If working with Org-mode produces an error with a message you don't
566 understand, you may have hit a bug. The best way to report this is by
567 providing, in addition to what was mentioned above, a @emph{Backtrace}.
568 This is information from the built-in debugger about where and how the
569 error occurred. Here is how to produce a useful backtrace:
573 Start a fresh Emacs or XEmacs, and make sure that it will load the
574 original Lisp code in @file{org.el} instead of the compiled version in
575 @file{org.elc}. The backtrace contains much more information if it is
576 produced with uncompiled code. To do this, either rename @file{org.elc}
577 to something else before starting Emacs, or ask Emacs explicitly to load
578 @file{org.el} by using the command line
580 emacs -l /path/to/org.el
583 Go to the @code{Options} menu and select @code{Enter Debugger on Error}
584 (XEmacs has this option in the @code{Troubleshooting} sub-menu).
586 Do whatever you have to do to hit the error. Don't forget to
587 document the steps you take.
589 When you hit the error, a @file{*Backtrace*} buffer will appear on the
590 screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
591 attach it to your bug report.
594 @node Conventions, , Feedback, Introduction
595 @section Typesetting conventions used in this manual
597 Org-mode has 3 types of keywords that are being used. TODO keywords,
598 tags, and property names. For this manual we are using the following
604 TODO keyword are written with all capitals, even if they are
608 User-defined Tags are written in lowercase, built-in tags with special
612 User-defined properties are capitalized in all examples, while
613 built-in properties with special meaning are all-caps.
616 @node Document structure, Tables, Introduction, Top
617 @chapter Document Structure
618 @cindex document structure
619 @cindex structure of document
621 Org-mode is based on outline mode and provides flexible commands to
622 edit the structure of the document.
625 * Outlines:: Org-mode is based on outline-mode
626 * Headlines:: How to typeset org-tree headlines
627 * Visibility cycling:: Show and hide, much simplified
628 * Motion:: Jumping to other headlines
629 * Structure editing:: Changing sequence and level of headlines
630 * Archiving:: Move done task trees to a different place
631 * Sparse trees:: Matches embedded in context
632 * Plain lists:: Additional structure within an entry
633 * Drawers:: Tucking stuff away
634 * orgstruct-mode:: Structure editing outside Org-mode
637 @node Outlines, Headlines, Document structure, Document structure
642 Org-mode is implemented on top of outline-mode. Outlines allow a
643 document to be organized in a hierarchical structure, which (at least
644 for me) is the best representation of notes and thoughts. An overview
645 of this structure is achieved by folding (hiding) large parts of the
646 document to show only the general document structure and the parts
647 currently being worked on. Org-mode greatly simplifies the use of
648 outlines by compressing the entire show/hide functionality into a single
649 command @command{org-cycle}, which is bound to the @key{TAB} key.
651 @node Headlines, Visibility cycling, Outlines, Document structure
656 Headlines define the structure of an outline tree. The headlines in
657 Org-mode start with one or more stars, on the left margin@footnote{See
658 the variable @code{org-special-ctrl-a/e} to configure special behavior
659 of @kbd{C-a} and @kbd{C-e} in headlines.}. For example:
669 * Another top level headline
672 @noindent Some people find the many stars too noisy and would prefer an
673 outline that has whitespace followed by a single star as headline
674 starters. @ref{Clean view} describes a setup to realize this.
676 An empty line after the end of a subtree is considered part of it and
677 will be hidden when the subtree is folded. However, if you leave at
678 least two empty lines, one empty line will remain visible after folding
679 the subtree, in order to structure the collapsed view. See the
680 variable @code{org-cycle-separator-lines} to modify this behavior.
682 @node Visibility cycling, Motion, Headlines, Document structure
683 @section Visibility cycling
684 @cindex cycling, visibility
685 @cindex visibility cycling
686 @cindex trees, visibility
687 @cindex show hidden text
690 Outlines make it possible to hide parts of the text in the buffer.
691 Org-mode uses just two commands, bound to @key{TAB} and
692 @kbd{S-@key{TAB}} to change the visibility in the buffer.
694 @cindex subtree visibility states
695 @cindex subtree cycling
696 @cindex folded, subtree visibility state
697 @cindex children, subtree visibility state
698 @cindex subtree, subtree visibility state
702 @emph{Subtree cycling}: Rotate current subtree among the states
705 ,-> FOLDED -> CHILDREN -> SUBTREE --.
706 '-----------------------------------'
709 The cursor must be on a headline for this to work@footnote{see, however,
710 the option @code{org-cycle-emulate-tab}.}. When the cursor is at the
711 beginning of the buffer and the first line is not a headline, then
712 @key{TAB} actually runs global cycling (see below)@footnote{see the
713 option @code{org-cycle-global-at-bob}.}. Also when called with a prefix
714 argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
716 @cindex global visibility states
717 @cindex global cycling
718 @cindex overview, global visibility state
719 @cindex contents, global visibility state
720 @cindex show all, global visibility state
724 @emph{Global cycling}: Rotate the entire buffer among the states
727 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
728 '--------------------------------------'
731 When @kbd{S-@key{TAB}} is called with a numerical prefix N, the CONTENTS
732 view up to headlines of level N will be shown.
733 Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.
735 @cindex show all, command
741 Reveal context around point, showing the current entry, the following
742 heading and the hierarchy above. Useful for working near a location
743 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda
744 command (@pxref{Agenda commands}). With prefix arg show, on each
745 level, all sibling headings.
748 Show the current subtree in an indirect buffer@footnote{The indirect
751 (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual})
754 (see the Emacs manual for more information about indirect buffers)
756 will contain the entire buffer, but will be narrowed to the current
757 tree. Editing the indirect buffer will also change the original buffer,
758 but without affecting visibility in that buffer.}. With numerical
759 prefix ARG, go up to this level and then take that tree. If ARG is
760 negative, go up that many levels. With @kbd{C-u} prefix, do not remove
761 the previously used indirect buffer.
764 When Emacs first visits an Org-mode file, the global state is set to
765 OVERVIEW, i.e. only the top level headlines are visible. This can be
766 configured through the variable @code{org-startup-folded}, or on a
767 per-file basis by adding one of the following lines anywhere in the
776 @node Motion, Structure editing, Visibility cycling, Document structure
778 @cindex motion, between headlines
779 @cindex jumping, to headlines
780 @cindex headline navigation
781 The following commands jump to other headlines in the buffer.
792 Next heading same level.
795 Previous heading same level.
798 Backward to higher level heading.
801 Jump to a different place without changing the current outline
802 visibility. Shows the document structure in a temporary buffer, where
803 you can use the following keys to find your destination:
805 @key{TAB} @r{Cycle visibility.}
806 @key{down} / @key{up} @r{Next/previous visible headline.}
807 n / p @r{Next/previous visible headline.}
808 f / b @r{Next/previous headline same level.}
810 0-9 @r{Digit argument.}
811 @key{RET} @r{Select this location.}
815 @node Structure editing, Archiving, Motion, Document structure
816 @section Structure editing
817 @cindex structure editing
818 @cindex headline, promotion and demotion
819 @cindex promotion, of subtrees
820 @cindex demotion, of subtrees
821 @cindex subtree, cut and paste
822 @cindex pasting, of subtrees
823 @cindex cutting, of subtrees
824 @cindex copying, of subtrees
825 @cindex subtrees, cut and paste
830 Insert new heading with same level as current. If the cursor is in a
831 plain list item, a new item is created (@pxref{Plain lists}). To force
832 creation of a new headline, use a prefix arg, or first press @key{RET}
833 to get to the beginning of the next line. When this command is used in
834 the middle of a line, the line is split and the rest of the line becomes
835 the new headline. If the command is used at the beginning of a
836 headline, the new headline is created before the current line. If at
837 the beginning of any other line, the content of that line is made the
838 new heading. If the command is used at the end of a folded subtree
839 (i.e. behind the ellipses at the end of a headline), then a headline
840 like the current one will be inserted after the end of the subtree.
843 Insert a new heading after the current subtree, same level as the
844 current headline. This command works from anywhere in the entry.
845 @kindex M-S-@key{RET}
847 Insert new TODO entry with same level as current heading.
850 Promote current heading by one level.
851 @kindex M-@key{right}
853 Demote current heading by one level.
854 @kindex M-S-@key{left}
856 Promote the current subtree by one level.
857 @kindex M-S-@key{right}
858 @item M-S-@key{right}
859 Demote the current subtree by one level.
862 Move subtree up (swap with previous subtree of same
864 @kindex M-S-@key{down}
866 Move subtree down (swap with next subtree of same level).
871 Kill subtree, i.e. remove it from buffer but save in kill ring.
872 With prefix arg, kill N sequential subtrees.
875 Copy subtree to kill ring. With prefix arg, copy N sequential subtrees.
878 Yank subtree from kill ring. This does modify the level of the subtree to
879 make sure the tree fits in nicely at the yank position. The yank
880 level can also be specified with a prefix arg, or by yanking after a
881 headline marker like @samp{****}.
884 Refile entry to a different location. @xref{Refiling notes}.
887 Sort same-level entries. When there is an active region, all entries in
888 the region will be sorted. Otherwise the children of the current
889 headline are sorted. The command prompts for the sorting method, which
890 can be alphabetically, numerically, by time (using the first time stamp
891 in each entry), by priority, and each of these in reverse order. You
892 can also supply your own function to extract the sorting key. With a
893 @kbd{C-u} prefix, sorting will be case-sensitive. With two @kbd{C-u
894 C-u} prefixes, duplicate entries will also be removed.
897 @cindex region, active
898 @cindex active region
899 @cindex transient-mark-mode
900 When there is an active region (transient-mark-mode), promotion and
901 demotion work on all headlines in the region. To select a region of
902 headlines, it is best to place both point and mark at the beginning of a
903 line, mark at the beginning of the first headline, and point at the line
904 just after the last headline to change. Note that when the cursor is
905 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
908 @node Archiving, Sparse trees, Structure editing, Document structure
912 When a project represented by a (sub)tree is finished, you may want
913 to move the tree out of the way and to stop it from contributing to the
914 agenda. Org-mode knows two ways of archiving. You can mark a tree with
915 the ARCHIVE tag, or you can move an entire (sub)tree to a different
919 * ARCHIVE tag:: Marking a tree as inactive
920 * Moving subtrees:: Moving a tree to an archive file
923 @node ARCHIVE tag, Moving subtrees, Archiving, Archiving
924 @subsection The ARCHIVE tag
925 @cindex internal archiving
927 A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
928 its location in the outline tree, but behaves in the following way:
931 It does not open when you attempt to do so with a visibility cycling
932 command (@pxref{Visibility cycling}). You can force cycling archived
933 subtrees with @kbd{C-@key{TAB}}, or by setting the option
934 @code{org-cycle-open-archived-trees}. Also normal outline commands like
935 @code{show-all} will open archived subtrees.
937 During sparse tree construction (@pxref{Sparse trees}), matches in
938 archived subtrees are not exposed, unless you configure the option
939 @code{org-sparse-tree-open-archived-trees}.
941 During agenda view construction (@pxref{Agenda views}), the content of
942 archived trees is ignored unless you configure the option
943 @code{org-agenda-skip-archived-trees}.
945 Archived trees are not exported (@pxref{Exporting}), only the headline
946 is. Configure the details using the variable
947 @code{org-export-with-archived-trees}.
950 The following commands help managing the ARCHIVE tag:
955 Toggle the ARCHIVE tag for the current headline. When the tag is set,
956 the headline changes to a shadowish face, and the subtree below it is
958 @kindex C-u C-c C-x C-a
959 @item C-u C-c C-x C-a
960 Check if any direct children of the current headline should be archived.
961 To do this, each subtree is checked for open TODO entries. If none are
962 found, the command offers to set the ARCHIVE tag for the child. If the
963 cursor is @emph{not} on a headline when this command is invoked, the
964 level 1 trees will be checked.
967 Cycle a tree even if it is tagged with ARCHIVE.
970 @node Moving subtrees, , ARCHIVE tag, Archiving
971 @subsection Moving subtrees
972 @cindex external archiving
974 Once an entire project is finished, you may want to move it to a
975 different location, either in the current file, or even in a different
976 file, the archive file.
981 Archive the subtree starting at the cursor position to the location
982 given by @code{org-archive-location}. Context information that could be
983 lost like the file name, the category, inherited tags, and the todo
984 state will be store as properties in the entry.
985 @kindex C-u C-c C-x C-s
986 @item C-u C-c C-x C-s
987 Check if any direct children of the current headline could be moved to
988 the archive. To do this, each subtree is checked for open TODO entries.
989 If none are found, the command offers to move it to the archive
990 location. If the cursor is @emph{not} on a headline when this command
991 is invoked, the level 1 trees will be checked.
994 @cindex archive locations
995 The default archive location is a file in the same directory as the
996 current file, with the name derived by appending @file{_archive} to the
997 current file name. For information and examples on how to change this,
998 see the documentation string of the variable
999 @code{org-archive-location}. There is also an in-buffer option for
1000 setting this variable, for example@footnote{For backward compatibility,
1001 the following also works: If there are several such lines in a file,
1002 each specifies the archive location for the text below it. The first
1003 such line also applies to any text before its definition. However,
1004 using this method is @emph{strongly} deprecated as it is incompatible
1005 with the outline structure of the document. The correct method for
1006 setting multiple archive locations in a buffer is using a property.}:
1009 #+ARCHIVE: %s_done::
1013 If you would like to have a special ARCHIVE location for a single entry
1014 or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
1015 location as the value (@pxref{Properties and columns}).
1017 @node Sparse trees, Plain lists, Archiving, Document structure
1018 @section Sparse trees
1019 @cindex sparse trees
1020 @cindex trees, sparse
1021 @cindex folding, sparse trees
1022 @cindex occur, command
1024 An important feature of Org-mode is the ability to construct
1025 @emph{sparse trees} for selected information in an outline tree. A
1026 sparse tree means that the entire document is folded as much as
1027 possible, but the selected information is made visible along with the
1028 headline structure above it@footnote{See also the variables
1029 @code{org-show-hierarchy-above}, @code{org-show-following-heading}, and
1030 @code{org-show-siblings} for detailed control on how much context is
1031 shown around each match.}. Just try it out and you will see immediately
1034 Org-mode contains several commands creating such trees, all these
1035 commands can be accessed through a dispatcher:
1040 This prompts for an extra key to select a sparse-tree creating command.
1043 Occur. Prompts for a regexp and shows a sparse tree with all matches.
1044 If the match is in a headline, the headline is made visible. If the
1045 match is in the body of an entry, headline and body are made visible.
1046 In order to provide minimal context, also the full hierarchy of
1047 headlines above the match is shown, as well as the headline following
1048 the match. Each match is also highlighted; the highlights disappear
1049 when the buffer is changed by an editing command, or by pressing
1050 @kbd{C-c C-c}. When called with a @kbd{C-u} prefix argument, previous
1051 highlights are kept, so several calls to this command can be stacked.
1054 For frequently used sparse trees of specific search strings, you can
1055 use the variable @code{org-agenda-custom-commands} to define fast
1056 keyboard access to specific sparse trees. These commands will then be
1057 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
1061 (setq org-agenda-custom-commands
1062 '(("f" occur-tree "FIXME")))
1065 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
1066 a sparse tree matching the string @samp{FIXME}.
1068 The other sparse tree commands select headings based on TODO keywords,
1069 tags, or properties and will be discussed later in this manual.
1072 @cindex printing sparse trees
1073 @cindex visible text, printing
1074 To print a sparse tree, you can use the Emacs command
1075 @code{ps-print-buffer-with-faces} which does not print invisible parts
1076 of the document @footnote{This does not work under XEmacs, because
1077 XEmacs uses selective display for outlining, not text properties.}.
1078 Or you can use the command @kbd{C-c C-e v} to export only the visible
1079 part of the document and print the resulting file.
1081 @node Plain lists, Drawers, Sparse trees, Document structure
1082 @section Plain lists
1084 @cindex lists, plain
1085 @cindex lists, ordered
1086 @cindex ordered lists
1088 Within an entry of the outline tree, hand-formatted lists can provide
1089 additional structure. They also provide a way to create lists of
1090 checkboxes (@pxref{Checkboxes}). Org-mode supports editing such lists,
1091 and the HTML exporter (@pxref{Exporting}) does parse and format them.
1093 Org-mode knows ordered and unordered lists. Unordered list items start
1094 with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a
1095 bullet, lines must be indented or they will be seen as top-level
1096 headlines. Also, when you are hiding leading stars to get a clean
1097 outline view, plain list items starting with a star are visually
1098 indistinguishable from true headlines. In short: even though @samp{*}
1099 is supported, it may be better not to use it for plain list items.} as
1100 bullets. Ordered list items start with @samp{1.} or @samp{1)}. Items
1101 belonging to the same list must have the same indentation on the first
1102 line. In particular, if an ordered list reaches number @samp{10.}, then
1103 the 2--digit numbers must be written left-aligned with the other numbers
1104 in the list. Indentation also determines the end of a list item. It
1105 ends before the next line that is indented like the bullet/number, or
1106 less. Empty lines are part of the previous item, so you can have
1107 several paragraphs in one item. If you would like an empty line to
1108 terminate all currently open plain lists, configure the variable
1109 @code{org-empty-line-terminates-plain-lists}. Here is an example:
1113 ** Lord of the Rings
1114 My favorite scenes are (in this order)
1115 1. The attack of the Rohirrim
1116 2. Eowyns fight with the witch king
1117 + this was already my favorite scene in the book
1118 + I really like Miranda Otto.
1119 3. Peter Jackson being shot by Legolas
1121 He makes a really funny face when it happens.
1122 But in the end, not individual scenes matter but the film as a whole.
1126 Org-mode supports these lists by tuning filling and wrapping commands to
1127 deal with them correctly@footnote{Org-mode only changes the filling
1128 settings for Emacs. For XEmacs, you should use Kyle E. Jones'
1129 @file{filladapt.el}. To turn this on, put into @file{.emacs}:
1130 @code{(require 'filladapt)}}.
1132 The following commands act on items when the cursor is in the first line
1133 of an item (the line with the bullet or number).
1138 Items can be folded just like headline levels if you set the variable
1139 @code{org-cycle-include-plain-lists}. The level of an item is then
1140 given by the indentation of the bullet/number. Items are always
1141 subordinate to real headlines, however; the hierarchies remain
1142 completely separated.
1144 If @code{org-cycle-include-plain-lists} has not been set, @key{TAB}
1145 fixes the indentation of the curent line in a heuristic way.
1148 Insert new item at current level. With prefix arg, force a new heading
1149 (@pxref{Structure editing}). If this command is used in the middle of a
1150 line, the line is @emph{split} and the rest of the line becomes the new
1151 item. If this command is executed in the @emph{whitespace before a bullet or
1152 number}, the new item is created @emph{before} the current item. If the
1153 command is executed in the white space before the text that is part of
1154 an item but does not contain the bullet, a bullet is added to the
1156 @kindex M-S-@key{RET}
1158 Insert a new item with a checkbox (@pxref{Checkboxes}).
1160 @kindex S-@key{down}
1163 Jump to the previous/next item in the current list.
1164 @kindex M-S-@key{up}
1165 @kindex M-S-@key{down}
1167 @itemx M-S-@key{down}
1168 Move the item including subitems up/down (swap with previous/next item
1169 of same indentation). If the list is ordered, renumbering is
1171 @kindex M-S-@key{left}
1172 @kindex M-S-@key{right}
1173 @item M-S-@key{left}
1174 @itemx M-S-@key{right}
1175 Decrease/increase the indentation of the item, including subitems.
1176 Initially, the item tree is selected based on current indentation.
1177 When these commands are executed several times in direct succession,
1178 the initially selected region is used, even if the new indentation
1179 would imply a different hierarchy. To use the new hierarchy, break
1180 the command chain with a cursor motion or so.
1183 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1184 state of the checkbox. If not, make this command makes sure that all
1185 the items on this list level use the same bullet. Furthermore, if this
1186 is an ordered list, make sure the numbering is ok.
1189 Cycle the entire list level through the different itemize/enumerate
1190 bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}).
1191 With prefix arg, select the nth bullet from this list.
1194 @node Drawers, orgstruct-mode, Plain lists, Document structure
1197 @cindex visibility cycling, drawers
1199 Sometimes you want to keep information associated with an entry, but you
1200 normally don't want to see it. For this, Org-mode has @emph{drawers}.
1201 Drawers need to be configured with the variable
1202 @code{org-drawers}@footnote{You can define drawers on a per-file basis
1203 with a line like @code{#+DRAWERS: HIDDEN PROPPERTIES STATE}}, and
1207 ** This is a headline
1208 Still outside the drawer
1210 This is inside the drawer.
1215 Visibility cycling (@pxref{Visibility cycling}) on the headline will
1216 hide and show the entry, but keep the drawer collapsed to a single line.
1217 In order to look inside the drawer, you need to move the cursor to the
1218 drawer line and press @key{TAB} there. Org-mode uses a drawer for
1219 storing properties (@pxref{Properties and columns}).
1221 @node orgstruct-mode, , Drawers, Document structure
1222 @section The Orgstruct minor mode
1223 @cindex orgstruct-mode
1224 @cindex minor mode for structure editing
1226 If you like the intuitive way the Org-mode structure editing and list
1227 formatting works, you might want to use these commands in other modes
1228 like text-mode or mail-mode as well. The minor mode Orgstruct-mode
1229 makes this possible. You can always toggle the mode with @kbd{M-x
1230 orgstruct-mode}. To turn it on by default, for example in mail mode,
1234 (add-hook 'mail-mode-hook 'turn-on-orgstruct)
1237 When this mode is active and the cursor is on a line that looks to
1238 Org-mode like a headline of the first line of a list item, most
1239 structure editing commands will work, even if the same keys normally
1240 have different functionality in the major mode you are using. If the
1241 cursor is not in one of those special lines, Orgstruct-mode lurks
1242 silently in the shadow.
1244 @node Tables, Hyperlinks, Document structure, Top
1247 @cindex editing tables
1249 Org-mode has a very fast and intuitive table editor built-in.
1250 Spreadsheet-like calculations are supported in connection with the
1251 Emacs @file{calc} package.
1254 * Built-in table editor:: Simple tables
1255 * Narrow columns:: Stop wasting space in tables
1256 * Column groups:: Grouping to trigger vertical lines
1257 * orgtbl-mode:: The table editor as minor mode
1258 * The spreadsheet:: The table editor has spreadsheet capabilities.
1261 @node Built-in table editor, Narrow columns, Tables, Tables
1262 @section The built-in table editor
1263 @cindex table editor, built-in
1265 Org-mode makes it easy to format tables in plain ASCII. Any line with
1266 @samp{|} as the first non-whitespace character is considered part of a
1267 table. @samp{|} is also the column separator. A table might look like
1271 | Name | Phone | Age |
1272 |-------+-------+-----|
1273 | Peter | 1234 | 17 |
1274 | Anna | 4321 | 25 |
1277 A table is re-aligned automatically each time you press @key{TAB} or
1278 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
1279 the next field (@key{RET} to the next row) and creates new table rows
1280 at the end of the table or before horizontal lines. The indentation
1281 of the table is set by the first line. Any line starting with
1282 @samp{|-} is considered as a horizontal separator line and will be
1283 expanded on the next re-align to span the whole table width. So, to
1284 create the above table, you would only type
1291 @noindent and then press @key{TAB} to align the table and start filling in
1294 When typing text into a field, Org-mode treats @key{DEL},
1295 @key{Backspace}, and all character keys in a special way, so that
1296 inserting and deleting avoids shifting other fields. Also, when
1297 typing @emph{immediately after the cursor was moved into a new field
1298 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
1299 field is automatically made blank. If this behavior is too
1300 unpredictable for you, configure the variables
1301 @code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
1304 @tsubheading{Creation and conversion}
1307 Convert the active region to table. If every line contains at least one
1308 TAB character, the function assumes that the material is tab separated.
1309 If every line contains a comma, comma-separated values (CSV) are assumed.
1310 If not, lines are split at whitespace into fields. You can use a prefix
1311 argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
1312 C-u} forces TAB, and a numeric argument N indicates that at least N
1313 consequtive spaces, or alternatively a TAB will be the separator.
1315 If there is no active region, this command creates an empty Org-mode
1316 table. But it's easier just to start typing, like
1317 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
1319 @tsubheading{Re-aligning and field motion}
1322 Re-align the table without moving the cursor.
1326 Re-align the table, move to the next field. Creates a new row if
1331 Re-align, move to previous field.
1335 Re-align the table and move down to next row. Creates a new row if
1336 necessary. At the beginning or end of a line, @key{RET} still does
1337 NEWLINE, so it can be used to split a table.
1339 @tsubheading{Column and row editing}
1340 @kindex M-@key{left}
1341 @kindex M-@key{right}
1343 @itemx M-@key{right}
1344 Move the current column left/right.
1346 @kindex M-S-@key{left}
1347 @item M-S-@key{left}
1348 Kill the current column.
1350 @kindex M-S-@key{right}
1351 @item M-S-@key{right}
1352 Insert a new column to the left of the cursor position.
1355 @kindex M-@key{down}
1358 Move the current row up/down.
1360 @kindex M-S-@key{up}
1362 Kill the current row or horizontal line.
1364 @kindex M-S-@key{down}
1365 @item M-S-@key{down}
1366 Insert a new row above (with arg: below) the current row.
1370 Insert a horizontal line below current row. With prefix arg, the line
1371 is created above the current line.
1375 Sort the table lines in the region. The position of point indicates the
1376 column to be used for sorting, and the range of lines is the range
1377 between the nearest horizontal separator lines, or the entire table. If
1378 point is before the first column, you will be prompted for the sorting
1379 column. If there is an active region, the mark specifies the first line
1380 and the sorting column, while point should be in the last line to be
1381 included into the sorting. The command prompts for the sorting type
1382 (alphabetically, numerically, or by time). When called with a prefix
1383 argument, alphabetic sorting will be case-sensitive.
1385 @tsubheading{Regions}
1388 Copy a rectangular region from a table to a special clipboard. Point
1389 and mark determine edge fields of the rectangle. The process ignores
1390 horizontal separator lines.
1394 Copy a rectangular region from a table to a special clipboard, and
1395 blank all fields in the rectangle. So this is the ``cut'' operation.
1399 Paste a rectangular region into a table.
1400 The upper right corner ends up in the current field. All involved fields
1401 will be overwritten. If the rectangle does not fit into the present table,
1402 the table is enlarged as needed. The process ignores horizontal separator
1407 Wrap several fields in a column like a paragraph. If there is an active
1408 region, and both point and mark are in the same column, the text in the
1409 column is wrapped to minimum width for the given number of lines. A
1410 prefix ARG may be used to change the number of desired lines. If there
1411 is no region, the current field is split at the cursor position and the
1412 text fragment to the right of the cursor is prepended to the field one
1413 line down. If there is no region, but you specify a prefix ARG, the
1414 current field is made blank, and the content is appended to the field
1417 @tsubheading{Calculations}
1418 @cindex formula, in tables
1419 @cindex calculations, in tables
1420 @cindex region, active
1421 @cindex active region
1422 @cindex transient-mark-mode
1425 Sum the numbers in the current column, or in the rectangle defined by
1426 the active region. The result is shown in the echo area and can
1427 be inserted with @kbd{C-y}.
1431 When current field is empty, copy from first non-empty field above.
1432 When not empty, copy current field down to next row and move cursor
1433 along with it. Depending on the variable
1434 @code{org-table-copy-increment}, integer field values will be
1435 incremented during copy. This key is also used by CUA-mode
1436 (@pxref{Cooperation}).
1438 @tsubheading{Miscellaneous}
1441 Edit the current field in a separate window. This is useful for fields
1442 that are not fully visible (@pxref{Narrow columns}). When called with a
1443 @kbd{C-u} prefix, just make the full field visible, so that it can be
1446 @kindex C-c @key{TAB}
1448 This is an alias for @kbd{C-u C-c `} to make the current field fully
1451 @item M-x org-table-import
1452 Import a file as a table. The table should be TAB- or whitespace
1453 separated. Useful, for example, to import a spreadsheet table or data
1454 from a database, because these programs generally can write
1455 TAB-separated text files. This command works by inserting the file into
1456 the buffer and then converting the region to a table. Any prefix
1457 argument is passed on to the converter, which uses it to determine the
1460 Tables can also be imported by pasting tabular text into the org-mode
1461 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
1462 @kbd{C-c |} command (see above under @i{Creation and conversion}.
1464 @item M-x org-table-export
1465 Export the table as a TAB-separated file. Useful for data exchange with,
1466 for example, spreadsheet or database programs.
1469 If you don't like the automatic table editor because it gets in your
1470 way on lines which you would like to start with @samp{|}, you can turn
1474 (setq org-enable-table-editor nil)
1477 @noindent Then the only table command that still works is
1478 @kbd{C-c C-c} to do a manual re-align.
1480 @node Narrow columns, Column groups, Built-in table editor, Tables
1481 @section Narrow columns
1482 @cindex narrow columns in tables
1484 The width of columns is automatically determined by the table editor.
1485 Sometimes a single field or a few fields need to carry more text,
1486 leading to inconveniently wide columns. To limit@footnote{This feature
1487 does not work on XEmacs.} the width of a column, one field anywhere in
1488 the column may contain just the string @samp{<N>} where @samp{N} is an
1489 integer specifying the width of the column in characters. The next
1490 re-align will then set the width of this column to no more than this
1495 |---+------------------------------| |---+--------|
1497 | 1 | one | | 1 | one |
1498 | 2 | two | ----\ | 2 | two |
1499 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1500 | 4 | four | | 4 | four |
1501 |---+------------------------------| |---+--------|
1506 Fields that are wider become clipped and end in the string @samp{=>}.
1507 Note that the full text is still in the buffer, it is only invisible.
1508 To see the full text, hold the mouse over the field - a tool-tip window
1509 will show the full content. To edit such a field, use the command
1510 @kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will
1511 open a new window with the full field. Edit it and finish with @kbd{C-c
1514 When visiting a file containing a table with narrowed columns, the
1515 necessary character hiding has not yet happened, and the table needs to
1516 be aligned before it looks nice. Setting the option
1517 @code{org-startup-align-all-tables} will realign all tables in a file
1518 upon visiting, but also slow down startup. You can also set this option
1519 on a per-file basis with:
1526 @node Column groups, orgtbl-mode, Narrow columns, Tables
1527 @section Column groups
1528 @cindex grouping columns in tables
1530 When Org-mode exports tables, it does so by default without vertical
1531 lines because that is visually more satisfying in general. Occasionally
1532 however, vertical lines can be useful to structure a table into groups
1533 of columns, much like horizontal lines can do for groups of rows. In
1534 order to specify column groups, you can use a special row where the
1535 first field contains only @samp{/}. The further fields can either
1536 contain @samp{<} to indicate that this column should start a group,
1537 @samp{>} to indicate the end of a column, or @samp{<>} to make a column
1538 a group of its own. Boundaries between colum groups will upon export be
1539 marked with vertical lines. Here is an example:
1542 | | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1543 |---+----+-----+-----+-----+---------+------------|
1544 | / | <> | < | | > | < | > |
1545 | # | 1 | 1 | 1 | 1 | 1 | 1 |
1546 | # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
1547 | # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
1548 |---+----+-----+-----+-----+---------+------------|
1549 #+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))
1552 It is also sufficient to just insert the colum group starters after
1553 every vertical line you'd like to have:
1556 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
1557 |----+-----+-----+-----+---------+------------|
1561 @node orgtbl-mode, The spreadsheet, Column groups, Tables
1562 @section The Orgtbl minor mode
1564 @cindex minor mode for tables
1566 If you like the intuitive way the Org-mode table editor works, you
1567 might also want to use it in other modes like text-mode or mail-mode.
1568 The minor mode Orgtbl-mode makes this possible. You can always toggle
1569 the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for
1570 example in mail mode, use
1573 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1576 Furthermore, with some special setup, it is possible to maintain tables
1577 in arbitrary syntax with Orgtbl-mode. For example, it is possible to
1578 construct La@TeX{} tables with the underlying ease and power of
1579 Orgtbl-mode, including spreadsheet capabilities. For details, see
1580 @ref{Tables in arbitrary syntax}.
1582 @node The spreadsheet, , orgtbl-mode, Tables
1583 @section The spreadsheet
1584 @cindex calculations, in tables
1585 @cindex spreadsheet capabilities
1586 @cindex @file{calc} package
1588 The table editor makes use of the Emacs @file{calc} package to implement
1589 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1590 derive fields from other fields. While fully featured, Org-mode's
1591 implementation is not identical to other spreadsheets. For example,
1592 Org-mode knows the concept of a @emph{column formula} that will be
1593 applied to all non-header fields in a column without having to copy the
1594 formula to each relevant field.
1597 * References:: How to refer to another field or range
1598 * Formula syntax for Calc:: Using Calc to compute stuff
1599 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
1600 * Field formulas:: Formulas valid for a single field
1601 * Column formulas:: Formulas valid for an entire column
1602 * Editing and debugging formulas:: Fixing formulas
1603 * Updating the table:: Recomputing all dependent fields
1604 * Advanced features:: Field names, parameters and automatic recalc
1607 @node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
1608 @subsection References
1611 To compute fields in the table from other fields, formulas must
1612 reference other fields or ranges. In Org-mode, fields can be referenced
1613 by name, by absolute coordinates, and by relative coordinates. To find
1614 out what the coordinates of a field are, press @kbd{C-c ?} in that
1615 field, or press @kbd{C-c @}} to toggle the display of a grid.
1617 @subsubheading Field references
1618 @cindex field references
1619 @cindex references, to fields
1621 Formulas can reference the value of another field in two ways. Like in
1622 any other spreadsheet, you may reference fields with a letter/number
1623 combination like @code{B3}, meaning the 2nd field in the 3rd row.
1624 @c Such references are always fixed to that field, they don't change
1625 @c when you copy and paste a formula to a different field. So
1626 @c Org-mode's @code{B3} behaves like @code{$B$3} in other spreadsheets.
1629 Org-mode also uses another, more general operator that looks like this:
1635 Column references can be absolute like @samp{1}, @samp{2},...@samp{N},
1636 or relative to the current column like @samp{+1} or @samp{-2}.
1638 The row specification only counts data lines and ignores horizontal
1639 separator lines (hlines). You can use absolute row numbers
1640 @samp{1}...@samp{N}, and row numbers relative to the current row like
1641 @samp{+3} or @samp{-1}. Or specify the row relative to one of the
1642 hlines: @samp{I} refers to the first hline@footnote{Note that only
1643 hlines are counted that @emph{separate} table lines. If the table
1644 starts with a hline above the header, it does not count.}, @samp{II} to
1645 the second etc. @samp{-I} refers to the first such line above the
1646 current line, @samp{+I} to the first such line below the current line.
1647 You can also write @samp{III+2} which is the second data line after the
1648 third hline in the table. Relative row numbers like @samp{-3} will not
1649 cross hlines if the current line is too close to the hline. Instead,
1650 the value directly at the hline is used.
1652 @samp{0} refers to the current row and column. Also, if you omit
1653 either the column or the row part of the reference, the current
1654 row/column is implied.
1656 Org-mode's references with @emph{unsigned} numbers are fixed references
1657 in the sense that if you use the same reference in the formula for two
1658 different fields, the same field will be referenced each time.
1659 Org-mode's references with @emph{signed} numbers are floating
1660 references because the same reference operator can reference different
1661 fields depending on the field being calculated by the formula.
1663 Here are a few examples:
1666 @@2$3 @r{2nd row, 3rd column}
1667 C2 @r{same as previous}
1668 $5 @r{column 5 in the current row}
1669 E& @r{same as previous}
1670 @@2 @r{current column, row 2}
1671 @@-1$-3 @r{the field one row up, three columns to the left}
1672 @@-I$2 @r{field just under hline above current row, column 2}
1675 @subsubheading Range references
1676 @cindex range references
1677 @cindex references, to ranges
1679 You may reference a rectangular range of fields by specifying two field
1680 references connected by two dots @samp{..}. If both fields are in the
1681 current row, you may simply use @samp{$2..$7}, but if at least one field
1682 is in a different row, you need to use the general @code{@@row$column}
1683 format at least for the first field (i.e the reference must start with
1684 @samp{@@} in order to be interpreted correctly). Examples:
1687 $1..$3 @r{First three fields in the current row.}
1688 $P..$Q @r{Range, using column names (see under Advanced)}
1689 @@2$1..@@4$3 @r{6 fields between these two fields.}
1690 A2..C4 @r{Same as above.}
1691 @@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row}
1694 @noindent Range references return a vector of values that can be fed
1695 into Calc vector functions. Empty fields in ranges are normally
1696 suppressed, so that the vector contains only the non-empty fields (but
1697 see the @samp{E} mode switch below). If there are no non-empty fields,
1698 @samp{[0]} is returned to avoid syntax errors in formulas.
1700 @subsubheading Named references
1701 @cindex named references
1702 @cindex references, named
1703 @cindex name, of column or field
1704 @cindex constants, in calculations
1706 @samp{$name} is interpreted as the name of a column, parameter or
1707 constant. Constants are defined globally through the variable
1708 @code{org-table-formula-constants}, and locally (for the file) through a
1712 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
1716 Also properties (@pxref{Properties and columns}) can be used as
1717 constants in table formulas: For a property @samp{:XYZ:} use the name
1718 @samp{$PROP_XYZ}, and the property will be searched in the current
1719 outline entry and in the hierarchy above it. If you have the
1720 @file{constants.el} package, it will also be used to resolve constants,
1721 including natural constants like @samp{$h} for Planck's constant, and
1722 units like @samp{$km} for kilometers@footnote{@file{Constant.el} can
1723 supply the values of constants in two different unit systems, @code{SI}
1724 and @code{cgs}. Which one is used depends on the value of the variable
1725 @code{constants-unit-system}. You can use the @code{#+STARTUP} options
1726 @code{constSI} and @code{constcgs} to set this value for the current
1727 buffer.}. Column names and parameters can be specified in special table
1728 lines. These are described below, see @ref{Advanced features}. All
1729 names must start with a letter, and further consist of letters and
1732 @node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet
1733 @subsection Formula syntax for Calc
1734 @cindex formula syntax, Calc
1735 @cindex syntax, of formulas
1737 A formula can be any algebraic expression understood by the Emacs
1738 @file{Calc} package. @b{Note that @file{calc} has the
1739 non-standard convention that @samp{/} has lower precedence than
1740 @samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before
1741 evaluation by @code{calc-eval} (@pxref{Calling Calc from
1742 Your Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU
1743 Emacs Calc Manual}),
1744 @c FIXME: The link to the calc manual in HTML does not work.
1745 variable substitution takes place according to the rules described above.
1746 @cindex vectors, in table calculations
1747 The range vectors can be directly fed into the calc vector functions
1748 like @samp{vmean} and @samp{vsum}.
1750 @cindex format specifier
1751 @cindex mode, for @file{calc}
1752 A formula can contain an optional mode string after a semicolon. This
1753 string consists of flags to influence Calc and other modes during
1754 execution. By default, Org-mode uses the standard calc modes (precision
1755 12, angular units degrees, fraction and symbolic modes off. The display
1756 format, however, has been changed to @code{(float 5)} to keep tables
1757 compact. The default settings can be configured using the variable
1758 @code{org-calc-default-modes}.
1761 p20 @r{switch the internal precision to 20 digits}
1762 n3 s3 e2 f4 @r{normal, scientific, engineering, or fixed display format}
1763 D R @r{angle modes: degrees, radians}
1764 F S @r{fraction and symbolic modes}
1765 N @r{interpret all fields as numbers, use 0 for non-numbers}
1766 T @r{force text interpretation}
1767 E @r{keep empty fields in ranges}
1771 In addition, you may provide a @code{printf} format specifier to
1772 reformat the final result. A few examples:
1775 $1+$2 @r{Sum of first and second field}
1776 $1+$2;%.2f @r{Same, format result to two decimals}
1777 exp($2)+exp($1) @r{Math functions can be used}
1778 $0;%.1f @r{Reformat current cell to 1 decimal}
1779 ($3-32)*5/9 @r{Degrees F -> C conversion}
1780 $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
1781 tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
1782 sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
1783 vmean($2..$7) @r{Compute column range mean, using vector function}
1784 vmean($2..$7);EN @r{Same, but treat empty fields as 0}
1785 taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree}
1788 Calc also contains a complete set of logical operations. For example
1791 if($1<20,teen,string("")) @r{``teen'' if age $1 less than 20, else empty}
1794 @node Formula syntax for Lisp, Field formulas, Formula syntax for Calc, The spreadsheet
1795 @subsection Emacs Lisp forms as formulas
1796 @cindex Lisp forms, as table formulas
1798 It is also possible to write a formula in Emacs Lisp; this can be useful
1799 for string manipulation and control structures, if the Calc's
1800 functionality is not enough. If a formula starts with a single quote
1801 followed by an opening parenthesis, then it is evaluated as a lisp form.
1802 The evaluation should return either a string or a number. Just as with
1803 @file{calc} formulas, you can specify modes and a printf format after a
1804 semicolon. With Emacs Lisp forms, you need to be concious about the way
1805 field references are interpolated into the form. By default, a
1806 reference will be interpolated as a Lisp string (in double quotes)
1807 containing the field. If you provide the @samp{N} mode switch, all
1808 referenced elements will be numbers (non-number fields will be zero) and
1809 interpolated as Lisp numbers, without quotes. If you provide the
1810 @samp{L} flag, all fields will be interpolated literally, without quotes.
1811 I.e., if you want a reference to be interpreted as a string by the Lisp
1812 form, enclode the reference operator itself in double quotes, like
1813 @code{"$3"}. Ranges are inserted as space-separated fields, so you can
1814 embed them in list or vector syntax. A few examples, note how the
1815 @samp{N} mode is used when we do computations in lisp.
1818 @r{Swap the first two characters of the content of column 1}
1819 '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
1820 @r{Add columns 1 and 2, equivalent to the Calc's @code{$1+$2}}
1822 @r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}}
1823 '(apply '+ '($1..$4));N
1826 @node Field formulas, Column formulas, Formula syntax for Lisp, The spreadsheet
1827 @subsection Field formulas
1828 @cindex field formula
1829 @cindex formula, for individual table field
1831 To assign a formula to a particular field, type it directly into the
1832 field, preceded by @samp{:=}, for example @samp{:=$1+$2}. When you
1833 press @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in
1834 the field, the formula will be stored as the formula for this field,
1835 evaluated, and the current field replaced with the result.
1837 Formulas are stored in a special line starting with @samp{#+TBLFM:}
1838 directly below the table. If you typed the equation in the 4th field of
1839 the 3rd data line in the table, the formula will look like
1840 @samp{@@3$4=$1+$2}. When inserting/deleting/swapping column and rows
1841 with the appropriate commands, @i{absolute references} (but not relative
1842 ones) in stored formulas are modified in order to still reference the
1843 same field. Of cause this is not true if you edit the table structure
1844 with normal editing commands - then you must fix the equations yourself.
1846 Instead of typing an equation into the field, you may also use the
1852 Install a new formula for the current field. The command prompts for a
1853 formula, with default taken from the @samp{#+TBLFM:} line, applies
1854 it to the current field and stores it.
1857 @node Column formulas, Editing and debugging formulas, Field formulas, The spreadsheet
1858 @subsection Column formulas
1859 @cindex column formula
1860 @cindex formula, for table column
1862 Often in a table, the same formula should be used for all fields in a
1863 particular column. Instead of having to copy the formula to all fields
1864 in that column, org-mode allows to assign a single formula to an entire
1865 column. If the table contains horizontal separator hlines, everything
1866 before the first such line is considered part of the table @emph{header}
1867 and will not be modified by column formulas.
1869 To assign a formula to a column, type it directly into any field in the
1870 column, preceded by an equal sign, like @samp{=$1+$2}. When you press
1871 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the
1872 field, the formula will be stored as the formula for the current column,
1873 evaluated and the current field replaced with the result. If the field
1874 contains only @samp{=}, the previously stored formula for this column is
1875 used. For each column, Org-mode will only remember the most recently
1876 used formula. In the @samp{TBLFM:} line, column formulas will look like
1879 Instead of typing an equation into the field, you may also use the
1885 Install a new formula for the current column and replace current field
1886 with the result of the formula. The command prompts for a formula, with
1887 default taken from the @samp{#+TBLFM} line, applies it to the current
1888 field and stores it. With a numerical prefix (e.g. @kbd{C-5 C-c =})
1889 will apply it to that many consecutive fields in the current column.
1893 @node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet
1894 @subsection Editing and Debugging formulas
1895 @cindex formula editing
1896 @cindex editing, of table formulas
1898 You can edit individual formulas in the minibuffer or directly in the
1899 field. Org-mode can also prepare a special buffer with all active
1900 formulas of a table. When offering a formula for editing, Org-mode
1901 converts references to the standard format (like @code{B3} or @code{D&})
1902 if possible. If you prefer to only work with the internal format (like
1903 @code{@@3$2} or @code{$4}), configure the variable
1904 @code{org-table-use-standard-references}.
1911 Edit the formula associated with the current column/field in the
1912 minibuffer. See @ref{Column formulas} and @ref{Field formulas}.
1913 @kindex C-u C-u C-c =
1915 Re-insert the active formula (either a
1916 field formula, or a column formula) into the current field, so that you
1917 can edit it directly in the field. The advantage over editing in the
1918 minibuffer is that you can use the command @kbd{C-c ?}.
1921 While editing a formula in a table field, highlight the field(s)
1922 referenced by the reference at the cursor position in the formula.
1925 Toggle the display of row and column numbers for a table, using
1926 overlays. These are updated each time the table is aligned, you can
1927 force it with @kbd{C-c C-c}.
1930 Toggle the formula debugger on and off. See below.
1933 Edit all formulas for the current table in a special buffer, where the
1934 formulas will be displayed one per line. If the current field has an
1935 active formula, the cursor in the formula editor will mark it.
1936 While inside the special buffer, Org-mode will automatically highlight
1937 any field or range reference at the cursor position. You may edit,
1938 remove and add formulas, and use the following commands:
1944 Exit the formula editor and store the modified formulas. With @kbd{C-u}
1945 prefix, also apply the new formulas to the entire table.
1948 Exit the formula editor without installing changes.
1951 Toggle all references in the formula editor between standard (like
1952 @code{B3}) and internal (like @code{@@3$2}).
1955 Pretty-print or indent lisp formula at point. When in a line containing
1956 a lisp formula, format the formula according to Emacs Lisp rules.
1957 Another @key{TAB} collapses the formula back again. In the open
1958 formula, @key{TAB} re-indents just like in Emacs-lisp-mode.
1961 Complete Lisp symbols, just like in Emacs-lisp-mode.
1963 @kindex S-@key{down}
1964 @kindex S-@key{left}
1965 @kindex S-@key{right}
1966 @item S-@key{up}/@key{down}/@key{left}/@key{right}
1967 Shift the reference at point. For example, if the reference is
1968 @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
1969 This also works for relative references, and for hline references.
1970 @kindex M-S-@key{up}
1971 @kindex M-S-@key{down}
1972 @item M-S-@key{up}/@key{down}
1973 Move the test line for column formulas in the Org-mode buffer up and
1976 @kindex M-@key{down}
1977 @item M-@key{up}/@key{down}
1978 Scroll the window displaying the table.
1981 Turn the coordinate grid in the table on and off.
1985 Making a table field blank does not remove the formula associated with
1986 the field, because that is stored in a different line (the @samp{TBLFM}
1987 line) - during the next recalculation the field will be filled again.
1988 To remove a formula from a field, you have to give an empty reply when
1989 prompted for the formula, or to edit the @samp{#+TBLFM} line.
1992 You may edit the @samp{#+TBLFM} directly and re-apply the changed
1993 equations with @kbd{C-c C-c} in that line, or with the normal
1994 recalculation commands in the table.
1996 @subsubheading Debugging formulas
1997 @cindex formula debugging
1998 @cindex debugging, of table formulas
1999 When the evaluation of a formula leads to an error, the field content
2000 becomes the string @samp{#ERROR}. If you would like see what is going
2001 on during variable substitution and calculation in order to find a bug,
2002 turn on formula debugging in the @code{Tbl} menu and repeat the
2003 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
2004 field. Detailed information will be displayed.
2006 @node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet
2007 @subsection Updating the Table
2008 @cindex recomputing table fields
2009 @cindex updating, table
2011 Recalculation of a table is normally not automatic, but needs to be
2012 triggered by a command. See @ref{Advanced features} for a way to make
2013 recalculation at least semi-automatically.
2015 In order to recalculate a line of a table or the entire table, use the
2021 Recalculate the current row by first applying the stored column formulas
2022 from left to right, and all field formulas in the current row.
2028 Recompute the entire table, line by line. Any lines before the first
2029 hline are left alone, assuming that these are part of the table header.
2031 @kindex C-u C-u C-c *
2032 @kindex C-u C-u C-c C-c
2034 @itemx C-u C-u C-c C-c
2035 Iterate the table by recomputing it until no further changes occur.
2036 This may be necessary if some computed fields use the value of other
2037 fields that are computed @i{later} in the calculation sequence.
2040 @node Advanced features, , Updating the table, The spreadsheet
2041 @subsection Advanced features
2043 If you want the recalculation of fields to happen automatically, or if
2044 you want to be able to assign @i{names} to fields and columns, you need
2045 to reserve the first column of the table for special marking characters.
2049 Rotate the calculation mark in first column through the states @samp{},
2050 @samp{#}, @samp{*}, @samp{!}, @samp{$}. The meaning of these characters
2051 is discussed below. When there is an active region, change all marks in
2055 Here is an example of a table that collects exam results of students and
2056 makes use of these features:
2060 |---+---------+--------+--------+--------+-------+------|
2061 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
2062 |---+---------+--------+--------+--------+-------+------|
2063 | ! | | P1 | P2 | P3 | Tot | |
2064 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
2065 | ^ | | m1 | m2 | m3 | mt | |
2066 |---+---------+--------+--------+--------+-------+------|
2067 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
2068 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
2069 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
2070 |---+---------+--------+--------+--------+-------+------|
2071 | | Average | | | | 29.7 | |
2072 | ^ | | | | | at | |
2073 | $ | max=50 | | | | | |
2074 |---+---------+--------+--------+--------+-------+------|
2075 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
2079 @noindent @b{Important}: Please note that for these special tables,
2080 recalculating the table with @kbd{C-u C-c *} will only affect rows that
2081 are marked @samp{#} or @samp{*}, and fields that have a formula assigned
2082 to the field itself. The column formulas are not applied in rows with
2085 @cindex marking characters, tables
2086 The marking characters have the following meaning:
2089 The fields in this line define names for the columns, so that you may
2090 refer to a column as @samp{$Tot} instead of @samp{$6}.
2092 This row defines names for the fields @emph{above} the row. With such
2093 a definition, any formula in the table may use @samp{$m1} to refer to
2094 the value @samp{10}. Also, if you assign a formula to a names field, it
2095 will be stored as @samp{$name=...}.
2097 Similar to @samp{^}, but defines names for the fields in the row
2100 Fields in this row can define @emph{parameters} for formulas. For
2101 example, if a field in a @samp{$} row contains @samp{max=50}, then
2102 formulas in this table can refer to the value 50 using @samp{$max}.
2103 Parameters work exactly like constants, only that they can be defined on
2106 Fields in this row are automatically recalculated when pressing
2107 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
2108 is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
2109 lines will be left alone by this command.
2111 Selects this line for global recalculation with @kbd{C-u C-c *}, but
2112 not for automatic recalculation. Use this when automatic
2113 recalculation slows down editing too much.
2115 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
2116 All lines that should be recalculated should be marked with @samp{#}
2119 Do not export this line. Useful for lines that contain the narrowing
2123 Finally, just to whet your appetite on what can be done with the
2124 fantastic @file{calc} package, here is a table that computes the Taylor
2125 series of degree @code{n} at location @code{x} for a couple of functions
2126 (homework: try that with Excel :-)
2130 |---+-------------+---+-----+--------------------------------------|
2131 | | Func | n | x | Result |
2132 |---+-------------+---+-----+--------------------------------------|
2133 | # | exp(x) | 1 | x | 1 + x |
2134 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
2135 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
2136 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
2137 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
2138 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
2139 |---+-------------+---+-----+--------------------------------------|
2140 #+TBLFM: $5=taylor($2,$4,$3);n3
2144 @node Hyperlinks, TODO items, Tables, Top
2148 Just like HTML, Org-mode provides links inside a file, and external
2149 links to other files, Usenet articles, emails, and much more.
2152 * Link format:: How links in Org-mode are formatted
2153 * Internal links:: Links to other places in the current file
2154 * External links:: URL-like links to the world
2155 * Handling links:: Creating, inserting and following
2156 * Using links outside Org-mode:: Linking from my C source code?
2157 * Link abbreviations:: Shortcuts for writing complex links
2158 * Search options:: Linking to a specific location
2159 * Custom searches:: When the default search is not enough
2162 @node Link format, Internal links, Hyperlinks, Hyperlinks
2163 @section Link format
2165 @cindex format, of links
2167 Org-mode will recognize plain URL-like links and activate them as
2168 clickable links. The general link format, however, looks like this:
2171 [[link][description]] @r{or alternatively} [[link]]
2174 Once a link in the buffer is complete (all brackets present), Org-mode
2175 will change the display so that @samp{description} is displayed instead
2176 of @samp{[[link][description]]} and @samp{link} is displayed instead of
2177 @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
2178 which by default is an underlined face. You can directly edit the
2179 visible part of a link. Note that this can be either the @samp{link}
2180 part (if there is no description) or the @samp{description} part. To
2181 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
2184 If you place the cursor at the beginning or just behind the end of the
2185 displayed text and press @key{BACKSPACE}, you will remove the
2186 (invisible) bracket at that location. This makes the link incomplete
2187 and the internals are again displayed as plain text. Inserting the
2188 missing bracket hides the link internals again. To show the
2189 internal structure of all links, use the menu entry
2190 @code{Org->Hyperlinks->Literal links}.
2192 @node Internal links, External links, Link format, Hyperlinks
2193 @section Internal links
2194 @cindex internal links
2195 @cindex links, internal
2196 @cindex targets, for links
2198 If the link does not look like a URL, it is considered to be internal in
2199 the current file. Links such as @samp{[[My Target]]} or @samp{[[My
2200 Target][Find my target]]} lead to a text search in the current file.
2201 The link can be followed with @kbd{C-c C-o} when the cursor is on the
2202 link, or with a mouse click (@pxref{Handling links}). The preferred
2203 match for such a link is a dedicated target: the same string in double
2204 angular brackets. Targets may be located anywhere; sometimes it is
2205 convenient to put them into a comment line. For example
2211 @noindent In HTML export (@pxref{HTML export}), such targets will become
2212 named anchors for direct access through @samp{http} links@footnote{Note
2213 that text before the first headline is usually not exported, so the
2214 first such target should be after the first headline.}.
2216 If no dedicated target exists, Org-mode will search for the words in the
2217 link. In the above example the search would be for @samp{my target}.
2218 Links starting with a star like @samp{*My Target} restrict the search to
2219 headlines. When searching, Org-mode will first try an exact match, but
2220 then move on to more and more lenient searches. For example, the link
2221 @samp{[[*My Targets]]} will find any of the following:
2225 ** TODO my targets are bright
2226 ** my 20 targets are
2229 To insert a link targeting a headline, in-buffer completion can be used.
2230 Just type a star followed by a few optional letters into the buffer and
2231 press @kbd{M-@key{TAB}}. All headlines in the current buffer will be
2232 offered as completions. @xref{Handling links}, for more commands
2235 Following a link pushes a mark onto Org-mode's own mark ring. You can
2236 return to the previous position with @kbd{C-c &}. Using this command
2237 several times in direct succession goes back to positions recorded
2241 * Radio targets:: Make targets trigger links in plain text.
2244 @node Radio targets, , Internal links, Internal links
2245 @subsection Radio targets
2246 @cindex radio targets
2247 @cindex targets, radio
2248 @cindex links, radio targets
2250 Org-mode can automatically turn any occurrences of certain target names
2251 in normal text into a link. So without explicitly creating a link, the
2252 text connects to the target radioing its position. Radio targets are
2253 enclosed by triple angular brackets. For example, a target @samp{<<<My
2254 Target>>>} causes each occurrence of @samp{my target} in normal text to
2255 become activated as a link. The Org-mode file is scanned automatically
2256 for radio targets only when the file is first loaded into Emacs. To
2257 update the target list during editing, press @kbd{C-c C-c} with the
2258 cursor on or at a target.
2260 @node External links, Handling links, Internal links, Hyperlinks
2261 @section External links
2262 @cindex links, external
2263 @cindex external links
2264 @cindex links, external
2271 @cindex WANDERLUST links
2273 @cindex USENET links
2278 Org-mode supports links to files, websites, Usenet and email messages,
2279 and BBDB database entries. External links are URL-like locators. They
2280 start with a short identifying string followed by a colon. There can be
2281 no space after the colon. The following list shows examples for each
2285 http://www.astro.uva.nl/~dominik @r{on the web}
2286 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
2287 file:papers/last.pdf @r{file, relative path}
2288 news:comp.emacs @r{Usenet link}
2289 mailto:adent@@galaxy.net @r{Mail link}
2290 vm:folder @r{VM folder link}
2291 vm:folder#id @r{VM message link}
2292 vm://myself@@some.where.org/folder#id @r{VM on remote machine}
2293 wl:folder @r{WANDERLUST folder link}
2294 wl:folder#id @r{WANDERLUST message link}
2295 mhe:folder @r{MH-E folder link}
2296 mhe:folder#id @r{MH-E message link}
2297 rmail:folder @r{RMAIL folder link}
2298 rmail:folder#id @r{RMAIL message link}
2299 gnus:group @r{GNUS group link}
2300 gnus:group#id @r{GNUS article link}
2301 bbdb:Richard Stallman @r{BBDB link}
2302 shell:ls *.org @r{A shell command}
2303 elisp:(find-file-other-frame "Elisp.org") @r{An elisp form to evaluate}
2306 A link should be enclosed in double brackets and may contain a
2307 descriptive text to be displayed instead of the url (@pxref{Link
2308 format}), for example:
2311 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
2315 If the description is a file name or URL that points to an image, HTML
2316 export (@pxref{HTML export}) will inline the image as a clickable
2317 button. If there is no description at all and the link points to an
2319 that image will be inlined into the exported HTML file.
2321 @cindex angular brackets, around links
2322 @cindex plain text external links
2323 Org-mode also finds external links in the normal text and activates them
2324 as links. If spaces must be part of the link (for example in
2325 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
2326 about the end of the link, enclose them in angular brackets.
2328 @node Handling links, Using links outside Org-mode, External links, Hyperlinks
2329 @section Handling links
2330 @cindex links, handling
2332 Org-mode provides methods to create a link in the correct syntax, to
2333 insert it into an org-mode file, and to follow the link.
2337 @cindex storing links
2339 Store a link to the current location. This is a @emph{global} command
2340 which can be used in any buffer to create a link. The link will be
2341 stored for later insertion into an Org-mode buffer (see below). For
2342 Org-mode files, if there is a @samp{<<target>>} at the cursor, the link
2343 points to the target. Otherwise it points to the current headline. For
2344 VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will
2345 indicate the current article/entry. For W3 and W3M buffers, the link
2346 goes to the current URL. For any other files, the link will point to
2347 the file, with a search string (@pxref{Search options}) pointing to the
2348 contents of the current line. If there is an active region, the
2349 selected words will form the basis of the search string. If the
2350 automatically created link is not working correctly or accurately
2351 enough, you can write custom functions to select the search string and
2352 to do the search for particular file types - see @ref{Custom searches}.
2353 The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}.
2356 @cindex link completion
2357 @cindex completion, of links
2358 @cindex inserting links
2360 Insert a link. This prompts for a link to be inserted into the buffer.
2361 You can just type a link, using text for an internal link, or one of the
2362 link type prefixes mentioned in the examples above. All links stored
2363 during the current session are part of the history for this prompt, so
2364 you can access them with @key{up} and @key{down} (or @kbd{M-p/n}).
2365 Completion, on the other hand, will help you to insert valid link
2366 prefixes like @samp{http:} or @samp{ftp:}, including the prefixes
2367 defined through link abbreviations (@pxref{Link abbreviations}). The
2368 link will be inserted into the buffer@footnote{After insertion of a
2369 stored link, the link will be removed from the list of stored links. To
2370 keep it in the list later use, use a triple @kbd{C-u} prefix to @kbd{C-c
2371 C-l}, or configure the option
2372 @code{org-keep-stored-link-after-insertion}.}, along with a descriptive
2373 text. If some text was selected when this command is called, the
2374 selected text becomes the default description.@* Note that you don't
2375 have to use this command to insert a link. Links in Org-mode are plain
2376 text, and you can type or paste them straight into the buffer. By using
2377 this command, the links are automatically enclosed in double brackets,
2378 and you will be asked for the optional descriptive text.
2380 @c If the link is a @samp{file:} link and
2381 @c the linked file is located in the same directory as the current file or
2382 @c a subdirectory of it, the path of the file will be inserted relative to
2383 @c the current directory.
2386 @cindex file name completion
2387 @cindex completion, of file names
2389 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
2390 a file will be inserted and you may use file name completion to select
2391 the name of the file. The path to the file is inserted relative to the
2392 directory of the current org file, if the linked file is in the current
2393 directory or in a subdirectory of it, or if the path is written relative
2394 to the current directory using @samp{../}. Otherwise an absolute path
2395 is used, if possible with @samp{~/} for your home directory. You can
2396 force an absolute path with two @kbd{C-u} prefixes.
2398 @item C-c C-l @r{(with cursor on existing link)}
2399 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
2400 link and description parts of the link.
2402 @cindex following links
2405 Open link at point. This will launch a web browser for URLs (using
2406 @command{browse-url-at-point}), run vm/mh-e/wanderlust/rmail/gnus/bbdb
2407 for the corresponding links, and execute the command in a shell link.
2408 When the cursor is on an internal link, this commands runs the
2409 corresponding search. When the cursor is on a TAG list in a headline,
2410 it creates the corresponding TAGS view. If the cursor is on a time
2411 stamp, it compiles the agenda for that date. Furthermore, it will visit
2412 text and remote files in @samp{file:} links with Emacs and select a
2413 suitable application for local non-text files. Classification of files
2414 is based on file extension only. See option @code{org-file-apps}. If
2415 you want to override the default application and visit the file with
2416 Emacs, use a @kbd{C-u} prefix.
2422 On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
2423 would. Under Emacs 22, also @kbd{mouse-1} will follow a link.
2427 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
2428 internal links to be displayed in another window@footnote{See the
2429 variable @code{org-display-internal-link-with-indirect-buffer}}.
2434 Push the current position onto the mark ring, to be able to return
2435 easily. Commands following an internal link do this automatically.
2437 @cindex links, returning to
2440 Jump back to a recorded position. A position is recorded by the
2441 commands following internal links, and by @kbd{C-c %}. Using this
2442 command several times in direct succession moves through a ring of
2443 previously recorded positions.
2447 @cindex links, finding next/previous
2450 Move forward/backward to the next link in the buffer. At the limit of
2451 the buffer, the search fails once, and then wraps around. The key
2452 bindings for this are really too long, you might want to bind this also
2453 to @kbd{C-n} and @kbd{C-p}
2455 (add-hook 'org-load-hook
2457 (define-key 'org-mode-map "\C-n" 'org-next-link)
2458 (define-key 'org-mode-map "\C-p" 'org-previous-link)))
2462 @node Using links outside Org-mode, Link abbreviations, Handling links, Hyperlinks
2463 @section Using links outside Org-mode
2465 You can insert and follow links that have Org-mode syntax not only in
2466 Org-mode, but in any Emacs buffer. For this, you should create two
2467 global commands, like this (please select suitable global keys
2471 (global-set-key "\C-c L" 'org-insert-link-global)
2472 (global-set-key "\C-c o" 'org-open-at-point-global)
2475 @node Link abbreviations, Search options, Using links outside Org-mode, Hyperlinks
2476 @section Link abbreviations
2477 @cindex link abbreviations
2478 @cindex abbreviation, links
2480 Long URLs can be cumbersome to type, and often many similar links are
2481 needed in a document. For this you can use link abbreviations. An
2482 abbreviated link looks like this
2485 [[linkword:tag][description]]
2489 where the tag is optional. Such abbreviations are resolved according to
2490 the information in the variable @code{org-link-abbrev-alist} that
2491 relates the linkwords to replacement text. Here is an example:
2495 (setq org-link-abbrev-alist
2496 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
2497 ("google" . "http://www.google.com/search?q=")
2498 ("ads" . "http://adsabs.harvard.edu/cgi-bin/
2499 nph-abs_connect?author=%s&db_key=AST")))
2503 If the replacement text contains the string @samp{%s}, it will be
2504 replaced with the tag. Otherwise the tag will be appended to the string
2505 in order to create the link. You may also specify a function that will
2506 be called with the tag as the only argument to create the link.
2508 With the above setting, you could link to a specific bug with
2509 @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
2510 @code{[[google:OrgMode]]} and find out what the Org-mode author is
2511 doing besides Emacs hacking with @code{[[ads:Dominik,C]]}.
2513 If you need special abbreviations just for a single Org-mode buffer, you
2514 can define them in the file with
2517 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
2518 #+LINK: google http://www.google.com/search?q=%s
2522 In-buffer completion @pxref{Completion} can be used after @samp{[} to
2523 complete link abbreviations.
2525 @node Search options, Custom searches, Link abbreviations, Hyperlinks
2526 @section Search options in file links
2527 @cindex search option in file links
2528 @cindex file links, searching
2530 File links can contain additional information to make Emacs jump to a
2531 particular location in the file when following a link. This can be a
2532 line number or a search option after a double@footnote{For backward
2533 compatibility, line numbers can also follow a single colon.} colon. For
2534 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
2535 links}) to a file, it encodes the words in the current line as a search
2536 string that can be used to find this line back later when following the
2537 link with @kbd{C-c C-o}.
2539 Here is the syntax of the different ways to attach a search to a file
2540 link, together with an explanation:
2543 [[file:~/code/main.c::255]]
2544 [[file:~/xx.org::My Target]]
2545 [[file:~/xx.org::*My Target]]
2546 [[file:~/xx.org::/regexp/]]
2553 Search for a link target @samp{<<My Target>>}, or do a text search for
2554 @samp{my target}, similar to the search in internal links, see
2555 @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
2556 link will become an HTML reference to the corresponding named anchor in
2559 In an Org-mode file, restrict search to headlines.
2561 Do a regular expression search for @code{regexp}. This uses the Emacs
2562 command @code{occur} to list all matches in a separate window. If the
2563 target file is in Org-mode, @code{org-occur} is used to create a
2564 sparse tree with the matches.
2565 @c If the target file is a directory,
2566 @c @code{grep} will be used to search all files in the directory.
2569 As a degenerate case, a file link with an empty file name can be used
2570 to search the current file. For example, @code{[[file:::find me]]} does
2571 a search for @samp{find me} in the current file, just as
2572 @samp{[[find me]]} would.
2574 @node Custom searches, , Search options, Hyperlinks
2575 @section Custom Searches
2576 @cindex custom search strings
2577 @cindex search strings, custom
2579 The default mechanism for creating search strings and for doing the
2580 actual search related to a file link may not work correctly in all
2581 cases. For example, BibTeX database files have many entries like
2582 @samp{year="1993"} which would not result in good search strings,
2583 because the only unique identification for a BibTeX entry is the
2586 If you come across such a problem, you can write custom functions to set
2587 the right search string for a particular file type, and to do the search
2588 for the string in the file. Using @code{add-hook}, these functions need
2589 to be added to the hook variables
2590 @code{org-create-file-search-functions} and
2591 @code{org-execute-file-search-functions}. See the docstring for these
2592 variables for more information. Org-mode actually uses this mechanism
2593 for Bib@TeX{} database files, and you can use the corresponding code as
2594 an implementation example. Search for @samp{BibTeX links} in the source
2599 @node TODO items, Tags, Hyperlinks, Top
2603 Org-mode does not maintain TODO lists as a separate document. TODO
2604 items are an integral part of the notes file, because TODO items
2605 usually come up while taking notes! With Org-mode, you simply mark
2606 any entry in a tree as being a TODO item. In this way, the
2607 information is not duplicated, and the entire context from which the
2608 item emerged is always present when you check.
2610 Of course, this technique causes TODO items to be scattered throughout
2611 your file. Org-mode provides methods to give you an overview over all
2612 things you have to do.
2615 * TODO basics:: Marking and displaying TODO entries
2616 * TODO extensions:: Workflow and assignments
2617 * Progress logging:: Dates and notes for progress
2618 * Priorities:: Some things are more important than others
2619 * Breaking down tasks:: Splitting a task into manageable pieces
2620 * Checkboxes:: Tick-off lists
2623 @node TODO basics, TODO extensions, TODO items, TODO items
2624 @section Basic TODO functionality
2626 Any headline can become a TODO item by starting it with the word TODO,
2630 *** TODO Write letter to Sam Fortune
2634 The most important commands to work with TODO entries are:
2638 @cindex cycling, of TODO states
2640 Rotate the TODO state of the current item among
2643 ,-> (unmarked) -> TODO -> DONE --.
2644 '--------------------------------'
2647 The same rotation can also be done ``remotely'' from the timeline and
2648 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
2652 Select a specific keyword using completion of (if it has been set up)
2653 the fast selection interface.
2655 @kindex S-@key{right}
2656 @kindex S-@key{left}
2659 Select the following/preceding TODO state, similar to cycling. Mostly
2660 useful if more than two TODO states are possible (@pxref{TODO
2664 Use the fast tag interface to quickly and directly select a specific
2665 TODO state. For this you need to assign keys to TODO state, like this:
2667 #+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d)
2669 @noindent See @ref{Per file keywords} and @ref{Setting tags} for more
2673 @cindex sparse tree, for TODO
2676 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds
2677 the entire buffer, but shows all TODO items and the headings hierarchy
2678 above them. With prefix arg, search for a specific TODO. You will be
2679 prompted for the keyword, and you can also give a list of keywords like
2680 @code{kwd1|kwd2|...}. With numerical prefix N, show the tree for the
2681 Nth keyword in the variable @code{org-todo-keywords}. With two prefix
2682 args, find all TODO and DONE entries.
2685 Show the global TODO list. This collects the TODO items from all
2686 agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in
2687 @code{agenda-mode}, so there are commands to examine and manipulate
2688 the TODO entries directly from that buffer (@pxref{Agenda commands}).
2689 @xref{Global TODO list}, for more information.
2690 @kindex S-M-@key{RET}
2692 Insert a new TODO entry below the current one.
2695 @node TODO extensions, Progress logging, TODO basics, TODO items
2696 @section Extended use of TODO keywords
2697 @cindex extended TODO keywords
2699 The default implementation of TODO entries is just two states: TODO and
2700 DONE. You can use the TODO feature for more complicated things by
2701 configuring the variable @code{org-todo-keywords}. With special setup,
2702 the TODO keyword system can work differently in different files.
2704 Note that @i{tags} are another way to classify headlines in general and
2705 TODO items in particular (@pxref{Tags}).
2708 * Workflow states:: From TODO to DONE in steps
2709 * TODO types:: I do this, Fred the rest
2710 * Multiple sets in one file:: Mixing it all, and still finding your way
2711 * Fast access to TODO states:: Single letter selection of a state
2712 * Per file keywords:: Different files, different requirements
2713 * Faces for TODO keywords:: Highlighting states
2716 @node Workflow states, TODO types, TODO extensions, TODO extensions
2717 @subsection TODO keywords as workflow states
2718 @cindex TODO workflow
2719 @cindex workflow states as TODO keywords
2721 You can use TODO keywords to indicate different @emph{sequential} states
2722 in the process of working on an item, for example@footnote{Changing
2723 this variable only becomes effective after restarting Org-mode in a
2727 (setq org-todo-keywords
2728 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
2731 The vertical bar separates the TODO keywords (states that @emph{need
2732 action}) from the DONE states (which need @emph{no further action}. If
2733 you don't provide the separator bar, the last state is used as the DONE
2735 @cindex completion, of TODO keywords
2736 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
2737 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may
2738 also use a prefix argument to quickly select a specific state. For
2739 example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
2740 If you define many keywords, you can use in-buffer completion (see
2741 @ref{Completion}) to insert these words into the buffer. Changing a
2742 todo state can be logged with a timestamp, see @ref{Tracking TODO state
2743 changes} for more information.
2745 @node TODO types, Multiple sets in one file, Workflow states, TODO extensions
2746 @subsection TODO keywords as types
2748 @cindex names as TODO keywords
2749 @cindex types as TODO keywords
2751 The second possibility is to use TODO keywords to indicate different
2752 @emph{types} of action items. For example, you might want to indicate
2753 that items are for ``work'' or ``home''. Or, when you work with several
2754 people on a single project, you might want to assign action items
2755 directly to persons, by using their names as TODO keywords. This would
2756 be set up like this:
2759 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
2762 In this case, different keywords do not indicate a sequence, but rather
2763 different types. So the normal work flow would be to assign a task to a
2764 person, and later to mark it DONE. Org-mode supports this style by
2765 adapting the workings of the command @kbd{C-c C-t}@footnote{This is also
2766 true for the @kbd{t} command in the timeline and agenda buffers.}. When
2767 used several times in succession, it will still cycle through all names,
2768 in order to first select the right type for a task. But when you return
2769 to the item after some time and execute @kbd{C-c C-t} again, it will
2770 switch from any name directly to DONE. Use prefix arguments or
2771 completion to quickly select a specific name. You can also review the
2772 items of a specific TODO type in a sparse tree by using a numeric prefix
2773 to @kbd{C-c C-v}. For example, to see all things Lucy has to do, you
2774 would use @kbd{C-3 C-c C-v}. To collect Lucy's items from all agenda
2775 files into a single buffer, you would use the prefix arg as well when
2776 creating the global todo list: @kbd{C-3 C-c t}.
2778 @node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions
2779 @subsection Multiple keyword sets in one file
2780 @cindex todo keyword sets
2782 Sometimes you may want to use different sets of TODO keywords in
2783 parallel. For example, you may want to have the basic
2784 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
2785 separate state indicating that an item has been canceled (so it is not
2786 DONE, but also does not require action). Your setup would then look
2790 (setq org-todo-keywords
2791 '((sequence "TODO" "|" "DONE")
2792 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
2793 (sequence "|" "CANCELED")))
2796 The keywords should all be different, this helps Org-mode to keep track
2797 of which subsequence should be used for a given entry. In this setup,
2798 @kbd{C-c C-t} only operates within a subsequence, so it switches from
2799 @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
2800 (nothing) to @code{REPORT}. Therefore you need a mechanism to initially
2801 select the correct sequence. Besides the obvious ways like typing a
2802 keyword or using completion, you may also apply the following commands:
2805 @kindex C-S-@key{right}
2806 @kindex C-S-@key{left}
2807 @item C-S-@key{right}
2808 @itemx C-S-@key{left}
2809 These keys jump from one TODO subset to the next. In the above example,
2810 @kbd{C-S-@key{right}} would jump from @code{TODO} or @code{DONE} to
2811 @code{REPORT}, and any of the words in the second row to @code{CANCELED}.
2812 @kindex S-@key{right}
2813 @kindex S-@key{left}
2816 @kbd{S-@key{<left>}} and @kbd{S-@key{<right>}} and walk through
2817 @emph{all} keywords from all sets, so for example @kbd{S-@key{<right>}}
2818 would switch from @code{DONE} to @code{REPORT} in the example above.
2821 @node Fast access to TODO states, Per file keywords, Multiple sets in one file, TODO extensions
2822 @subsection Fast access to TODO states
2824 If you would like to quickly change an entry to an arbitrary TODO state
2825 instead of cycling through the states, you can set up keys for
2826 single-letter access to the states. This is done by adding the section
2827 key after each keyword, in parenthesis. For example:
2830 (setq org-todo-keywords
2831 '((sequence "TODO(t)" "|" "DONE(d)")
2832 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
2833 (sequence "|" "CANCELED(c)")))
2836 If you then press @code{C-u C-c C-t} followed by the selection key, the
2837 entry will be switched to this state. @key{SPC} can be used to remove
2838 any TODO keyword from an entry. Should you like this way of selecting
2839 TODO states a lot, you might want to set the variable
2840 @code{org-use-fast-todo-selection} to @code{t} and make this behavior
2841 the default. Check also the variable
2842 @code{org-fast-tag-selection-include-todo}, it allows to change the TODO
2843 state through the tags interface (@pxref{Setting tags}).
2845 @node Per file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions
2846 @subsection Setting up keywords for individual files
2847 @cindex keyword options
2848 @cindex per file keywords
2850 It can be very useful to use different aspects of the TODO mechanism in
2851 different files. For file-local settings, you need to add special lines
2852 to the file which set the keywords and interpretation for that file
2853 only. For example, to set one of the two examples discussed above, you
2854 need one of the following lines, starting in column zero anywhere in the
2858 #+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED
2862 #+TYP_TODO: Fred Sara Lucy Mike | DONE
2865 A setup for using several sets in parallel would be:
2868 #+SEQ_TODO: TODO | DONE
2869 #+SEQ_TODO: REPORT BUG KNOWNCAUSE | FIXED
2870 #+SEQ_TODO: | CANCELED
2873 @cindex completion, of option keywords
2875 @noindent To make sure you are using the correct keyword, type
2876 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
2878 @cindex DONE, final TODO keyword
2879 Remember that the keywords after the vertical bar (or the last keyword
2880 if no bar is there) must always mean that the item is DONE (although you
2881 may use a different word). After changing one of these lines, use
2882 @kbd{C-c C-c} with the cursor still in the line to make the changes
2883 known to Org-mode@footnote{Org-mode parses these lines only when
2884 Org-mode is activated after visiting a file. @kbd{C-c C-c} with the
2885 cursor in a line starting with @samp{#+} is simply restarting Org-mode
2886 for the current buffer.}.
2888 @node Faces for TODO keywords, , Per file keywords, TODO extensions
2889 @subsection Faces for TODO keywords
2890 @cindex faces, for TODO keywords
2892 Org-mode highlights TODO keywords with special faces: @code{org-todo}
2893 for keywords indicating that an item still has to be acted upon, and
2894 @code{org-done} for keywords indicating that an item is finished. If
2895 you are using more than 2 different states, you might want to use
2896 special faces for some of them. This can be done using the variable
2897 @code{org-todo-keyword-faces}. For example:
2900 (setq org-todo-keyword-faces
2901 '(("TODO" . org-warning)
2902 ("DEFERRED" . shadow)
2903 ("CANCELED" . (:foreground "blue" :weight bold))))
2907 @node Progress logging, Priorities, TODO extensions, TODO items
2908 @section Progress Logging
2909 @cindex progress logging
2910 @cindex logging, of progress
2912 Org-mode can automatically record a time stamp and even a note when you
2913 mark a TODO item as DONE, or even each time you change the state of
2917 * Closing items:: When was this entry marked DONE?
2918 * Tracking TODO state changes:: When did the status change?
2921 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging
2922 @subsection Closing items
2924 If you want to keep track of @emph{when} a certain TODO item was
2925 finished, turn on logging with@footnote{The corresponding in-buffer
2926 setting is: @code{#+STARTUP: logdone}. You may also set this for the
2927 scope of a subtree by adding a @code{LOGGING} property with one or more
2928 of the logging keywords in the value.}
2931 (setq org-log-done t)
2935 Then each time you turn a TODO entry into DONE using either @kbd{C-c
2936 C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
2937 @samp{CLOSED: [timestamp]} will be inserted just after the headline. If
2938 you turn the entry back into a TODO item through further state cycling,
2939 that line will be removed again. In the timeline (@pxref{Timeline}) and
2940 in the agenda (@pxref{Weekly/Daily agenda}), you can then use the
2941 @kbd{l} key to display the TODO items closed on each day, giving you an
2942 overview of what has been done on a day. If you want to record a note
2943 along with the timestamp, use@footnote{The corresponding in-buffer
2944 setting is: @code{#+STARTUP: lognotedone}}
2947 (setq org-log-done '(done))
2950 @node Tracking TODO state changes, , Closing items, Progress logging
2951 @subsection Tracking TODO state changes
2953 When TODO keywords are used as workflow states (@pxref{Workflow
2954 states}), you might want to keep track of when a state change occurred
2955 and record a note about this change. With the setting@footnote{The
2956 corresponding in-buffer setting is: @code{#+STARTUP: lognotestate}.}
2959 (setq org-log-done '(state))
2963 each state change will prompt you for a note that will be attached to
2964 the current headline. If you press @kbd{C-c C-c} without typing
2965 anything into the note buffer, only the time of the state change will be
2966 noted. Very likely you do not want this verbose tracking all the time,
2967 so it is probably better to configure this behavior with in-buffer
2968 options. For example, if you are tracking purchases, put these into a
2969 separate file that contains:
2972 #+SEQ_TODO: TODO(t) ORDERED(o) INVOICE(i) PAYED(p) | RECEIVED(r)
2973 #+STARTUP: lognotestate
2976 If you only need to take a note for some of the states, mark those
2977 states with an additional @samp{@@}, like this:
2980 #+SEQ_TODO: TODO(t) ORDERED(o@@) INVOICE(i@@) PAYED(p) | RECEIVED(r)
2981 #+STARTUP: lognotestate
2984 @node Priorities, Breaking down tasks, Progress logging, TODO items
2988 If you use Org-mode extensively to organize your work, you may end up
2989 with a number of TODO entries so large that you'd like to prioritize
2990 them. This can be done by placing a @emph{priority cookie} into the
2994 *** TODO [#A] Write letter to Sam Fortune
2998 With its standard setup, Org-mode supports priorities @samp{A},
2999 @samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry
3000 without a cookie is treated as priority @samp{B}. Priorities make a
3001 difference only in the agenda (@pxref{Weekly/Daily agenda}).
3006 Set the priority of the current headline. The command prompts for a
3007 priority character @samp{A}, @samp{B} or @samp{C}. When you press
3008 @key{SPC} instead, the priority cookie is removed from the headline.
3009 The priorities can also be changed ``remotely'' from the timeline and
3010 agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
3013 @kindex S-@key{down}
3016 Increase/decrease priority of current headline@footnote{See also the
3017 option @code{org-priority-start-cycle-with-default'}.}. Note that these
3018 keys are also used to modify time stamps (@pxref{Creating timestamps}).
3019 Furthermore, these keys are also used by CUA-mode (@pxref{Conflicts}).
3022 You can change the range of allowed priorities by setting the variables
3023 @code{org-highest-priority}, @code{org-lowest-priority}, and
3024 @code{org-default-priority}. For an individual buffer, you may set
3025 these values (highest, lowest, default) like this (please make sure that
3026 the highest priority is earlier in the alphabet than the lowest
3033 @node Breaking down tasks, Checkboxes, Priorities, TODO items
3034 @section Breaking tasks down into subtasks
3035 @cindex tasks, breaking down
3037 It is often advisable to break down large tasks into smaller, manageable
3038 subtasks. You can do this by creating an outline tree below a TODO
3039 item, with detailed subtasks on the tree@footnote{To keep subtasks out
3040 of the global TODO list, see the
3041 @code{org-agenda-todo-list-sublevels}.}. Another possibility is the use
3042 of checkboxes to identify (a hierarchy of) a large number of subtasks
3043 (@pxref{Checkboxes}).
3046 @node Checkboxes, , Breaking down tasks, TODO items
3050 Every item in a plain list (@pxref{Plain lists}) can be made a checkbox
3051 by starting it with the string @samp{[ ]}. This feature is similar to
3052 TODO items (@pxref{TODO items}), but more lightweight. Checkboxes are
3053 not included into the global TODO list, so they are often great to split
3054 a task into a number of simple steps. Or you can use them in a shopping
3055 list. To toggle a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's
3056 @file{org-mouse.el}. Here is an example of a checkbox list.
3059 * TODO Organize party [3/6]
3065 - [ ] think about what music to play
3066 - [X] talk to the neighbors
3069 @cindex statistics, for checkboxes
3070 @cindex checkbox statistics
3071 The @samp{[3/6]} and @samp{[1/3]} in the first and second line are
3072 cookies indicating how many checkboxes are present in this entry, and
3073 how many of them have been checked off. This can give you an idea on
3074 how many checkboxes remain, even without opening a folded entry. The
3075 cookies can be placed into a headline or into (the first line of) a
3076 plain list item. Each cookie covers all checkboxes structurally below
3077 that headline/item. You have to insert the cookie yourself by typing
3078 either @samp{[/]} or @samp{[%]}. In the first case you get an @samp{n
3079 out of m} result, in the second case you get information about the
3080 percentage of checkboxes checked (in the above example, this would be
3081 @samp{[50%]} and @samp{[33%], respectively}).
3083 @noindent The following commands work with checkboxes:
3088 Toggle checkbox at point. With prefix argument, set it to @samp{[-]},
3089 which is considered to be an intermediate state.
3092 Toggle checkbox at point.
3095 If there is an active region, toggle the first checkbox in the region
3096 and set all remaining boxes to the same status as the first. If you
3097 want to toggle all boxes in the region independently, use a prefix
3100 If the cursor is in a headline, toggle checkboxes in the region between
3101 this headline and the next (so @emph{not} the entire subtree).
3103 If there is no active region, just toggle the checkbox at point.
3105 @kindex M-S-@key{RET}
3107 Insert a new item with a checkbox.
3108 This works only if the cursor is already in a plain list item
3109 (@pxref{Plain lists}).
3112 Update the checkbox statistics in the current outline entry. When
3113 called with a @kbd{C-u} prefix, update the entire file. Checkbox
3114 statistic cookies are updated automatically if you toggle checkboxes
3115 with @kbd{C-c C-c} and make new ones with @kbd{M-S-@key{RET}}. If you
3116 delete boxes or add/change them by hand, use this command to get things
3117 back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}.
3121 @node Tags, Properties and columns, TODO items, Top
3124 @cindex headline tagging
3125 @cindex matching, tags
3126 @cindex sparse tree, tag based
3128 If you wish to implement a system of labels and contexts for
3129 cross-correlating information, an excellent way is to assign @i{tags} to
3130 headlines. Org-mode has extensive support for using tags.
3132 Every headline can contain a list of tags, at the end of the headline.
3133 Tags are normal words containing letters, numbers, @samp{_}, and
3134 @samp{@@}. Tags must be preceded and followed by a single colon; like
3135 @samp{:WORK:}. Several tags can be specified like @samp{:work:URGENT:}.
3138 * Tag inheritance:: Tags use the tree structure of the outline
3139 * Setting tags:: How to assign tags to a headline
3140 * Tag searches:: Searching for combinations of tags
3143 @node Tag inheritance, Setting tags, Tags, Tags
3144 @section Tag inheritance
3145 @cindex tag inheritance
3146 @cindex inheritance, of tags
3147 @cindex sublevels, inclusion into tags match
3149 @i{Tags} make use of the hierarchical structure of outline trees. If a
3150 heading has a certain tag, all subheadings will inherit the tag as
3151 well. For example, in the list
3154 * Meeting with the French group :work:
3155 ** Summary by Frank :boss:notes:
3156 *** TODO Prepare slides for him :action:
3160 the final heading will have the tags @samp{:work:}, @samp{:boss:},
3161 @samp{:notes:}, and @samp{:action:}. When executing tag searches and
3162 Org-mode finds that a certain headline matches the search criterion, it
3163 will not check any sublevel headline, assuming that these likely also
3164 match, and that the list of matches can become very long. This may
3165 not be what you want, however, and you can influence inheritance and
3166 searching using the variables @code{org-use-tag-inheritance} and
3167 @code{org-tags-match-list-sublevels}.
3169 @node Setting tags, Tag searches, Tag inheritance, Tags
3170 @section Setting tags
3171 @cindex setting tags
3172 @cindex tags, setting
3175 Tags can simply be typed into the buffer at the end of a headline.
3176 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
3177 also a special command for inserting tags:
3182 @cindex completion, of tags
3183 Enter new tags for the current headline. Org-mode will either offer
3184 completion or a special single-key interface for setting tags, see
3185 below. After pressing @key{RET}, the tags will be inserted and aligned
3186 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
3187 tags in the current buffer will be aligned to that column, just to make
3188 things look nice. TAGS are automatically realigned after promotion,
3189 demotion, and TODO state changes (@pxref{TODO basics}).
3192 Org will support tag insertion based on a @emph{list of tags}. By
3193 default this list is constructed dynamically, containing all tags
3194 currently used in the buffer. You may also globally specify a hard list
3195 of tags with the variable @code{org-tag-alist}. Finally you can set
3196 the default tags for a given file with lines like
3199 #+TAGS: @@work @@home @@tennisclub
3200 #+TAGS: laptop car pc sailboat
3203 If you have globally defined your preferred set of tags using the
3204 variable @code{org-tag-alist}, but would like to use a dynamic tag list
3205 in a specific file: Just add an empty TAGS option line to that file:
3211 The default support method for entering tags is minibuffer completion.
3212 However, Org-mode also implements a much better method: @emph{fast tag
3213 selection}. This method allows to select and deselect tags with a
3214 single key per tag. To function efficiently, you should assign unique
3215 keys to most tags. This can be done globally with
3218 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
3221 @noindent or on a per-file basis with
3224 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
3228 You can also group together tags that are mutually exclusive. With
3229 curly braces@footnote{In @code{org-mode-alist} use
3230 @code{'(:startgroup)} and @code{'(:endgroup)}, respectively. Several
3231 groups are allowed.}
3234 #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)
3237 @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
3238 and @samp{@@tennisclub} should be selected.
3240 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
3241 these lines to activate any changes.
3243 If at least one tag has a selection key, pressing @kbd{C-c C-c} will
3244 automatically present you with a special interface, listing inherited
3245 tags, the tags of the current headline, and a list of all legal tags
3246 with corresponding keys@footnote{Keys will automatically be assigned to
3247 tags which have no configured keys.}. In this interface, you can use
3252 Pressing keys assigned to tags will add or remove them from the list of
3253 tags in the current line. Selecting a tag in a group of mutually
3254 exclusive tags will turn off any other tags from that group.
3257 Enter a tag in the minibuffer, even if the tag is not in the predefined
3258 list. You will be able to complete on all tags present in the buffer.
3261 Clear all tags for this line.
3264 Accept the modified set.
3266 Abort without installing changes.
3268 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
3270 Turn off groups of mutually exclusive tags. Use this to (as an
3271 exception) assign several tags from such a group.
3273 Toggle auto-exit after the next change (see below).
3274 If you are using expert mode, the first @kbd{C-c} will display the
3279 This method lets you assign tags to a headline with very few keys. With
3280 the above setup, you could clear the current tags and set @samp{@@home},
3281 @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
3282 C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to
3283 @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
3284 alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
3285 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
3286 @key{RET} @key{RET}}.
3288 If you find that most of the time, you need only a single keypress to
3289 modify your list of tags, set the variable
3290 @code{org-fast-tag-selection-single-key}. Then you no longer have to
3291 press @key{RET} to exit fast tag selection - it will immediately exit
3292 after the first change. If you then occasionally need more keys, press
3293 @kbd{C-c} to turn off auto-exit for the current tag selection process
3294 (in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c
3295 C-c}). If you set the variable to the value @code{expert}, the special
3296 window is not even shown for single-key tag selection, it comes up only
3297 when you press an extra @kbd{C-c}.
3299 @node Tag searches, , Setting tags, Tags
3300 @section Tag searches
3301 @cindex tag searches
3302 @cindex searching for tags
3304 Once a tags system has been set up, it can be used to collect related
3305 information into special lists.
3312 Create a sparse tree with all headlines matching a tags search. With a
3313 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
3316 Create a global list of tag matches from all agenda files.
3317 @xref{Matching tags and properties}.
3320 Create a global list of tag matches from all agenda files, but check
3321 only TODO items and force checking subitems (see variable
3322 @code{org-tags-match-list-sublevels}).
3325 @cindex Boolean logic, for tag searches
3326 A @i{tags} search string can use Boolean operators @samp{&} for AND and
3327 @samp{|} for OR. @samp{&} binds more strongly than @samp{|}.
3328 Parenthesis are currently not implemented. A tag may also be preceded
3329 by @samp{-}, to select against it, and @samp{+} is syntactic sugar for
3330 positive selection. The AND operator @samp{&} is optional when @samp{+}
3331 or @samp{-} is present. Examples:
3335 Select headlines tagged @samp{:work:}, but discard those also tagged
3338 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
3339 @item work|laptop&night
3340 Like before, but require the @samp{:laptop:} lines to be tagged also
3344 @cindex TODO keyword matching, with tags search
3345 If you are using multi-state TODO keywords (@pxref{TODO extensions}), it
3346 can be useful to also match on the TODO keyword. This can be done by
3347 adding a condition after a slash to a tags match. The syntax is similar
3348 to the tag matches, but should be applied with consideration: For
3349 example, a positive selection on several TODO keywords can not
3350 meaningfully be combined with boolean AND. However, @emph{negative
3351 selection} combined with AND can be meaningful. To make sure that only
3352 lines are checked that actually have any TODO keyword, use @kbd{C-c a
3353 M}, or equivalently start the todo part after the slash with @samp{!}.
3358 Select @samp{:work:}-tagged TODO lines with the specific TODO
3359 keyword @samp{WAITING}.
3360 @item work/!-WAITING-NEXT
3361 Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
3363 @item work/+WAITING|+NEXT
3364 Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
3368 @cindex regular expressions, with tags search
3369 Any element of the tag/todo match can be a regular expression - in this
3370 case it must be enclosed in curly braces. For example,
3371 @samp{work+@{^boss.*@}} matches headlines that contain the tag
3372 @samp{work} and any tag @i{starting} with @samp{boss}.
3374 @cindex level, require for tags/property match
3375 @cindex category, require for tags/property match
3376 You can also require a headline to be of a certain level or category, by
3377 writing instead of any TAG an expression like @samp{LEVEL=3} or
3378 @samp{CATEGORY="work"}, respectively. For example, a search
3379 @samp{+LEVEL=3+boss/-DONE} lists all level three headlines that have the
3380 tag @samp{boss} and are @emph{not} marked with the todo keyword DONE.
3382 @node Properties and columns, Dates and times, Tags, Top
3383 @chapter Properties and Columns
3386 Properties are a set of key-value pairs associated with an entry. There
3387 are two main applications for properties in Org-mode. First, properties
3388 are like tags, but with a value. For example, in a file where you
3389 document bugs and plan releases of a piece of software, instead of using
3390 tags like @code{:release_1:}, @code{:release_2:}, it can be more
3391 efficient to use a property @code{Release} with a value @code{1.0} or
3392 @code{2.0}. Second, you can use properties to implement (very basic)
3393 database capabilities in an Org-mode buffer, for example to create a
3394 list of Music CD's you own. You can edit and view properties
3395 conveniently in column view (@pxref{Column view}).
3398 * Property syntax:: How properties are spelled out
3399 * Special properties:: Access to other Org-mode features
3400 * Property searches:: Matching property values
3401 * Property inheritance:: Passing values down the tree
3402 * Column view:: Tabular viewing and editing
3403 * Property API:: Properties for Lisp programmers
3406 @node Property syntax, Special properties, Properties and columns, Properties and columns
3407 @section Property Syntax
3408 @cindex property syntax
3409 @cindex drawer, for properties
3411 Properties are key-value pairs. They need to be inserted into a special
3412 drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property
3413 is specified on a single line, with the key (surrounded by colons)
3414 first, and the value after it. Here is an example:
3419 *** Goldberg Variations
3421 :Title: Goldberg Variations
3422 :Composer: J.S. Bach
3424 :Publisher: Deutsche Grammphon
3429 You may define the allowed values for a particular property @samp{Xyz}
3430 by setting a property @samp{Xyz_ALL}. This special property is
3431 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
3432 the entire tree. When allowed values are defined, setting the
3433 corresponding property becomes easier and is less prone to typing
3434 errors. For the example with the CD collection, we can predefine
3435 publishers and the number of disks in a box like this:
3440 :NDisks_ALL: 1 2 3 4
3441 :Publisher_ALL: "Deutsche Grammophon" Phillips EMI
3445 If you want to set properties that can be inherited by any entry in a
3446 file, use a line like
3449 #+PROPERTY: NDisks_ALL 1 2 3 4
3452 Property values set with the global variable
3453 @code{org-global-properties} can be inherited by all entries in all
3457 The following commands help to work with properties:
3462 After an initial colon in a line, complete property keys. All keys used
3463 in the current file will be offered as possible completions.
3466 Set a property. This prompts for a property name and a value. If
3467 necessary, the property drawer is created as well.
3468 @item M-x org-insert-property-drawer
3469 Insert a property drawer into the current entry. The drawer will be
3470 inserted early in the entry, but after the lines with planning
3471 information like deadlines.
3474 With the cursor in a property drawer, this executes property commands.
3476 Set a property in the current entry. Both the property and the value
3477 can be inserted using completion.
3478 @kindex S-@key{right}
3479 @kindex S-@key{left}
3480 @item S-@key{left}/@key{right}
3481 Switch property at point to the next/previous allowed value.
3483 Remove a property from the current entry.
3485 Globally remove a property, from all entries in the current file.
3487 Compute the property at point, using the operator and scope from the
3488 nearest column format definition.
3491 @node Special properties, Property searches, Property syntax, Properties and columns
3492 @section Special Properties
3493 @cindex properties, special
3495 Special properties provide alternative access method to Org-mode
3496 features discussed in the previous chapters, like the TODO state or the
3497 priority of an entry. This interface exists so that you can include
3498 these states into columns view (@pxref{Column view}), or to use them in
3499 queries. The following property names are special and should not be
3500 used as keys in the properties drawer:
3503 TODO @r{The TODO keyword of the entry.}
3504 TAGS @r{The tags defined directly in the headline.}
3505 ALLTAGS @r{All tags, including inherited ones.}
3506 PRIORITY @r{The priority of the entry, a string with a single letter.}
3507 DEADLINE @r{The deadline time string, without the angular brackets.}
3508 SCHEDULED @r{The scheduling time stamp, without the angular brackets.}
3511 @node Property searches, Property inheritance, Special properties, Properties and columns
3512 @section Property searches
3513 @cindex properties, searching
3514 @cindex properties, inheritance
3515 @cindex searching, of properties
3516 @cindex inheritance, of properties
3518 To create sparse trees and special lists with selection based on
3519 properties, the same commands are used as for tag searches (@pxref{Tag
3520 searches}), and the same logic applies. For example, a search string
3523 +work-boss+PRIORITY="A"+Coffee="unlimited"+With=@{Sarah\|Denny@}
3527 finds entries tagged @samp{:work:} but not @samp{:boss:}, which
3528 also have a priority value @samp{A}, a @samp{:Coffee:} property with the
3529 value @samp{unlimited}, and a @samp{:With:} property that is matched by
3530 the regular expression @samp{Sarah\|Denny}.
3532 You can configure Org-mode to use property inheritance during a search,
3533 see @ref{Property inheritance} for details.
3535 There is also a special command for creating sparse trees based on a
3541 Create a sparse tree based on the value of a property. This first
3542 prompts for the name of a property, and then for a value. A sparse tree
3543 is created with all entries that define this property with the given
3544 value. If you enclose the value into curly braces, it is interpreted as
3545 a regular expression and matched against the property values.
3548 @node Property inheritance, Column view, Property searches, Properties and columns
3549 @section Property Inheritance
3551 The outline structure of Org-mode documents lends itself for an
3552 inheritance model of properties: If the parent in a tree has a certain
3553 property, the children can inherit this property. Org-mode does not
3554 turn this on by default, because it can slow down property searches
3555 significantly and is often not needed. However, if you find inheritance
3556 useful, you can turn it on by setting the variable
3557 @code{org-use-property-inheritance}. It may be set to @code{t}, to make
3558 all properties inherited from the parent, or to a list of properties
3559 that should be inherited.
3561 Org-mode has a few properties for which inheritance is hard-coded, at
3562 least for the special applications for which they are used:
3566 The column property defines the format of column view (@pxref{Column
3567 view}). It is inherited in the sense that the level where a
3568 @code{COLUMNS} property is defined is used as the starting point for a
3569 column view table, independently of the location in the subtree from
3570 where columns view is turned on.
3572 For agenda view, a category set through a @code{CATEGORY} property
3573 applies to the entire subtree.
3575 For archiving, the @code{ARCHIVE} property may define the archive
3576 location for the entire subtree (@pxref{Moving subtrees}).
3579 @node Column view, Property API, Property inheritance, Properties and columns
3580 @section Column View
3582 A great way to view and edit properties in an outline tree is
3583 @emph{column view}. In column view, each outline item is turned into a
3584 table row. Columns in this table provide access to properties of the
3585 entries. Org-mode implements columns by overlaying a tabular structure
3586 over the headline of each item. While the headlines have been turned
3587 into a table row, you can still change the visibility of the outline
3588 tree. For example, you get a compact table by switching to CONTENTS
3589 view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
3590 is active), but you can still open, read, and edit the entry below each
3591 headline. Or, you can switch to column view after executing a sparse
3592 tree command and in this way get a table only for the selected items.
3593 Column view also works in agenda buffers (@pxref{Agenda views}) where
3594 queries have collected selected items, possibly from a number of files.
3597 * Defining columns:: The COLUMNS format property
3598 * Using column view:: How to create and use column view
3599 * Capturing Column View:: A dynamic block for column view
3602 @node Defining columns, Using column view, Column view, Column view
3603 @subsection Defining Columns
3604 @cindex column view, for properties
3605 @cindex properties, column view
3607 Setting up a column view first requires defining the columns. This is
3608 done by defining a column format line.
3611 * Scope of column definitions:: Where defined, where valid?
3612 * Column attributes:: Appearance and content of a column
3615 @node Scope of column definitions, Column attributes, Defining columns, Defining columns
3616 @subsubsection Scope of column definitions
3618 To define a column format for an entire file, use a line like
3621 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3624 To specify a format that only applies to a specific tree, add a COLUMNS
3625 property to the top node of that tree, for example
3627 ** Top node for columns view
3629 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
3633 If a @code{COLUMNS} property is present in an entry, it defines columns
3634 for the entry itself, and for the entire subtree below it. Since the
3635 column definition is part of the hierarchical structure of the document,
3636 you can define columns on level 1 that are general enough for all
3637 sublevels, and more specific columns further down, when you edit a
3638 deeper part of the tree.
3640 @node Column attributes, , Scope of column definitions, Defining columns
3641 @subsubsection Column attributes
3642 A column definition sets the attributes of a column. The general
3643 definition looks like this:
3646 %[width]property[(title)][@{summary-type@}]
3650 Except for the percent sign and the property name, all items are
3651 optional. The individual parts have the following meaning:
3654 width @r{An integer specifying the width of the column in characters.}
3655 @r{If omitted, the width will be determined automatically.}
3656 property @r{The property that should be edited in this column.}
3657 (title) @r{The header text for the column. If omitted, the}
3658 @r{property name is used.}
3659 @{summary-type@} @r{The summary type. If specified, the column values for}
3660 @r{parent nodes are computed from the children.}
3661 @r{Supported summary types are:}
3662 @{+@} @r{Sum numbers in this column.}
3663 @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.}
3664 @{$@} @r{Currency, short for @samp{+;%.2f}.}
3665 @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.}
3666 @{X@} @r{Checkbox status, [X] if all children are [X].}
3670 Here is an example for a complete columns definition, along with allowed
3674 :COLUMNS: %20ITEM %9Approved(Approved?)@{X@} %Owner %11Status %10Time_Spent@{:@}
3675 :Owner_ALL: Tammy Mark Karl Lisa Don
3676 :Status_ALL: "In progress" "Not started yet" "Finished" ""
3677 :Approved_ALL: "[ ]" "[X]"
3680 The first column, @samp{%25ITEM}, means the first 25 characters of the
3681 item itself, i.e. of the headline. You probably always should start the
3682 column definition with the ITEM specifier. The other specifiers create
3683 columns @samp{Owner} with a list of names as allowed values, for
3684 @samp{Status} with four different possible values, and for a checkbox
3685 field @samp{Approved}. When no width is given after the @samp{%}
3686 character, the column will be exactly as wide as it needs to be in order
3687 to fully display all values. The @samp{Approved} column does have a
3688 modified title (@samp{Approved?}, with a question mark). Summaries will
3689 be created for the @samp{Time_Spent} column by adding time duration
3690 expressions like HH:MM, and for the @samp{Approved} column, by providing
3691 an @samp{[X]} status if all children have been checked.
3693 @node Using column view, Capturing Column View, Defining columns, Column view
3694 @subsection Using Column View
3697 @tsubheading{Turning column view on and off}
3700 Create the column view for the local environment. This command searches
3701 the hierarchy, up from point, for a @code{COLUMNS} property that defines
3702 a format. When one is found, the column view table is established for
3703 the entire tree, starting from the entry that contains the @code{COLUMNS}
3704 property. If none is found, the format is taken from the @code{#+COLUMNS}
3705 line or from the variable @code{org-columns-default-format}, and column
3706 view is established for the current entry and its subtree.
3710 @tsubheading{Editing values}
3711 @item @key{left} @key{right} @key{up} @key{down}
3712 Move through the column view from field to field.
3713 @kindex S-@key{left}
3714 @kindex S-@key{right}
3715 @item S-@key{left}/@key{right}
3716 Switch to the next/previous allowed value of the field. For this, you
3717 have to have specified allowed values for a property.
3721 Same as @kbd{S-@key{left}/@key{right}}
3724 Edit the property at point. For the special properties, this will
3725 invoke the same interface that you normally use to change that
3726 property. For example, when editing a TAGS property, the tag completion
3727 or fast selection interface will pop up.
3730 When there is a checkbox at point, toggle it.
3733 View the full value of this property. This is useful if the width of
3734 the column is smaller than that of the value.
3737 Edit the list of allowed values for this property. If the list is found
3738 in the hierarchy, the modified values is stored there. If no list is
3739 found, the new value is stored in the first entry that is part of the
3740 current column view.
3741 @tsubheading{Modifying the table structure}
3745 Make the column narrower/wider by one character.
3746 @kindex S-M-@key{right}
3747 @item S-M-@key{right}
3748 Insert a new column, to the right of the current column.
3749 @kindex S-M-@key{left}
3750 @item S-M-@key{left}
3751 Delete the current column.
3754 @node Capturing Column View, , Using column view, Column view
3755 @subsection Capturing Column View
3757 Since column view is just an overlay over a buffer, it cannot be
3758 exported or printed directly. If you want to capture a column view, use
3759 the dynamic block (@pxref{Dynamic blocks}). The frame of this block
3764 #+BEGIN: columnview :hlines 1 :id "label"
3769 @noindent This dynamic block has the following parameters:
3773 This is most important parameter. Column view is a feature that is
3774 often localized to a certain (sub)tree, and the capture block might be
3775 in a different location in the file. To identify the tree whose view to
3776 capture, you can use 3 values:
3778 local @r{use the tree in which the capture block is located}
3779 global @r{make a global view, including all headings in the file}
3780 "label" @r{call column view in the tree that has and @code{:ID:}}
3781 @r{property with the value @i{label}}
3784 When @code{t}, insert a hline after every line. When a number N, insert
3785 a hline before each headline with level @code{<= N}.
3787 When set to @code{t}, enforce column groups to get vertical lines.
3791 The following commands insert or update the dynamic block:
3796 Insert a dynamic block capturing a column view. You will be prompted
3797 for the scope or id of the view.
3802 Update dynamical block at point. The cursor needs to be in the
3803 @code{#+BEGIN} line of the dynamic block.
3804 @kindex C-u C-c C-x C-u
3805 @item C-u C-c C-x C-u
3806 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
3807 you have several clocktable blocks in a buffer.
3810 @node Property API, , Column view, Properties and columns
3811 @section The Property API
3812 @cindex properties, API
3813 @cindex API, for properties
3815 There is a full API for accessing and changing properties. This API can
3816 be used by Emacs Lisp programs to work with properties and to implement
3817 features based on them. For more information see @ref{Using the
3820 @node Dates and times, Remember, Properties and columns, Top
3821 @chapter Dates and Times
3827 Items can be labeled with a date and/or a time to make them useful for
3828 project planning. The specially formatted string carrying the date and
3829 time information is called a @emph{timestamp} in Org-mode. This may be
3830 a little confusing because timestamp is often used as indicating when
3831 something was created or last changed. However, in Org-mode this term
3832 is used in a much wider sense.
3835 * Time stamps:: Assigning a time to a tree entry
3836 * Creating timestamps:: Commands which insert timestamps
3837 * Deadlines and scheduling:: Planning your work
3838 * Clocking work time::
3842 @node Time stamps, Creating timestamps, Dates and times, Dates and times
3843 @section Time stamps, deadlines and scheduling
3845 @cindex ranges, time
3850 A time stamp is a specification of a date (possibly with time or a range
3851 of times) in a special format, either @samp{<2003-09-16 Tue>} or
3852 @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue
3853 12:00-12:30>}@footnote{This is the standard ISO date/time format. If
3854 you cannot get used to these, see @ref{Custom time format}}. A time
3855 stamp can appear anywhere in the headline or body of an org-tree entry.
3856 Its presence causes entries to be shown on specific dates in the agenda
3857 (@pxref{Weekly/Daily agenda}). We distinguish:
3860 @item Plain time stamp; Event; Appointment
3862 A simple time stamp just assigns a date/time to an item. This is just
3863 like writing down an appointment or event in a paper agenda. In the
3864 timeline and agenda displays, the headline of an entry associated with a
3865 plain time stamp will be shown exactly on that date.
3868 * Meet Peter at the movies <2006-11-01 Wed 19:15>
3869 * Discussion on climate change <2006-11-02 Thu 20:00-22:00>
3872 @item Time stamp with repeater interval
3873 @cindex timestamp, with repeater interval
3874 A time stamp may contain a @emph{repeater interval}, indicating that it
3875 applies not only on the given date, but again and again after a certain
3876 interval of N days (d), weeks (w), months(m), or years(y). The
3877 following will show up in the agenda every Wednesday:
3880 * Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
3883 @item Diary-style sexp entries
3884 For more complex date specifications, Org-mode supports using the
3885 special sexp diary entries implemented in the Emacs calendar/diary
3886 package. For example
3889 * The nerd meeting on every 2nd Thursday of the month
3890 <%%(diary-float t 4 2)>
3893 @item Time/Date range
3896 Two time stamps connected by @samp{--} denote a range. The headline
3897 will be shown on the first and last day of the range, and on any dates
3898 that are displayed and fall in the range. Here is an example:
3901 ** Meeting in Amsterdam
3902 <2004-08-23 Mon>--<2004-08-26 Thu>
3905 @item Inactive time stamp
3906 @cindex timestamp, inactive
3907 @cindex inactive timestamp
3908 Just like a plain time stamp, but with square brackets instead of
3909 angular ones. These time stamps are inactive in the sense that they do
3910 @emph{not} trigger an entry to show up in the agenda.
3913 * Gillian comes late for the fifth time [2006-11-01 Wed]
3918 @node Creating timestamps, Deadlines and scheduling, Time stamps, Dates and times
3919 @section Creating timestamps
3920 @cindex creating timestamps
3921 @cindex timestamps, creating
3923 For Org-mode to recognize time stamps, they need to be in the specific
3924 format. All commands listed below produce time stamps in the correct
3930 Prompt for a date and insert a corresponding time stamp. When the
3931 cursor is at a previously used time stamp, it is updated to NOW. When
3932 this command is used twice in succession, a time range is inserted.
3936 Like @kbd{C-c .}, but use the alternative format which contains date
3937 and time. The default time can be rounded to multiples of 5 minutes,
3938 see the option @code{org-time-stamp-rounding-minutes}.
3942 Like @kbd{C-c .}, but insert an inactive time stamp that will not cause
3947 Insert a time stamp corresponding to the cursor date in the Calendar.
3951 Access the Emacs calendar for the current date. If there is a
3952 timestamp in the current line, goto the corresponding date
3957 Access the agenda for the date given by the time stamp or -range at
3958 point (@pxref{Weekly/Daily agenda}).
3960 @kindex S-@key{left}
3961 @kindex S-@key{right}
3963 @itemx S-@key{right}
3964 Change date at cursor by one day. These key bindings conflict with
3965 CUA-mode (@pxref{Conflicts}).
3968 @kindex S-@key{down}
3971 Change the item under the cursor in a timestamp. The cursor can be on a
3972 year, month, day, hour or minute. Note that if the cursor is in a
3973 headline and not at a time stamp, these same keys modify the priority of
3974 an item. (@pxref{Priorities}). The key bindings also conflict with
3975 CUA-mode (@pxref{Conflicts}).
3978 @cindex evaluate time range
3980 Evaluate a time range by computing the difference between start and
3981 end. With prefix arg, insert result after the time range (in a table:
3982 into the following column).
3987 * The date/time prompt:: How org-mode helps you entering date and time
3988 * Custom time format:: Making dates look differently
3991 @node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps
3992 @subsection The date/time prompt
3993 @cindex date, reading in minibuffer
3994 @cindex time, reading in minibuffer
3996 When Org-mode prompts for a date/time, the default is shown as an ISO
3997 date, and the prompt therefore seems to ask for an ISO date. But it
3998 will in fact accept any string containing some date and/or time
3999 information, and it is really smart about interpreting your input. You
4000 can, for example, use @kbd{C-y} to paste a (possibly multi-line) string
4001 copied from an email message. Org-mode will find whatever information
4002 is in there and derive anything you have not specified from the
4003 @emph{default date and time}. The default is usually the current date
4004 and time, but when modifying an existing time stamp, or when entering
4005 the second stamp of a range, it is taken from the stamp in the buffer.
4006 When filling in information, Org-mode assumes that most of the time you
4007 will want to enter a date in the future: If you omit the month/year and
4008 the given day/month is @i{before} today, it will assume that you mean a
4009 future date@footnote{See the variable
4010 @code{org-read-date-prefer-future}.}.
4012 For example, lets assume that today is @b{June 13, 2006}. Here is how
4013 various inputs will be interpreted, the items filled in by Org-mode are
4017 3-2-5 --> 2003-02-05
4018 14 --> @b{2006}-@b{06}-14
4019 12 --> @b{2006}-@b{07}-12
4020 Fri --> nearest Friday (defaultdate or later)
4021 sep 15 --> @b{2006}-11-15
4022 feb 15 --> @b{2007}-02-15
4023 sep 12 9 --> 2009-09-12
4024 12:45 --> @b{2006}-@b{06}-@b{13} 12:45
4025 22 sept 0:34 --> @b{2006}-09-22 0:34
4028 Furthermore you can specify a relative date by giving, as the
4029 @emph{first} thing in the input: a plus/minus sign, a number and a
4030 letter [dwmy] to indicate change in days weeks, months, years. With a
4031 single plus or minus, the date is always relative to today. With a
4032 double plus or minus, it is relative to the default date. If instead of
4033 a single letter, you use the abbreviation of day name, the date will be
4034 the nth such day. E.g.
4037 +4d --> four days from today
4038 +4 --> same as above
4039 +2w --> two weeks from today
4040 ++5 --> five days from default date
4041 +2tue --> second tuesday from now.
4044 The function understands English month and weekday abbreviations. If
4045 you want to use unabbreviated names and/or other languages, configure
4046 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
4048 @cindex calendar, for selecting date
4049 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
4050 you don't need/want the calendar, configure the variable
4051 @code{org-popup-calendar-for-date-prompt}.}. When you exit the date
4052 prompt, either by clicking on a date in the calendar, or by pressing
4053 @key{RET}, the date selected in the calendar will be combined with the
4054 information entered at the prompt. You can control the calendar fully
4055 from the minibuffer:
4060 @kindex S-@key{right}
4061 @kindex S-@key{left}
4062 @kindex S-@key{down}
4064 @kindex M-S-@key{right}
4065 @kindex M-S-@key{left}
4068 > / < @r{Scroll calendar forward/backward by one month.}
4069 mouse-1 @r{Select date by clicking on it.}
4070 S-@key{right}/@key{left} @r{One day forward/backward.}
4071 S-@key{down}/@key{up} @r{One week forward/backward.}
4072 M-S-@key{right}/@key{left} @r{One month forward/backward.}
4073 @key{RET} @r{Choose date in calendar.}
4076 The actions of the date/time prompt may seem complex, but I asure you
4077 they will grow on you. To help you understand what is going on, the
4078 current interpretation of your input will be displayed live in the
4079 minibuffer@footnote{If you find this distracting, turn the display of
4080 with @code{org-read-date-display-live}.}.
4082 @node Custom time format, , The date/time prompt, Creating timestamps
4083 @subsection Custom time format
4084 @cindex custom date/time format
4085 @cindex time format, custom
4086 @cindex date format, custom
4088 Org-mode uses the standard ISO notation for dates and times as it is
4089 defined in ISO 8601. If you cannot get used to this and require another
4090 representation of date and time to keep you happy, you can get it by
4091 customizing the variables @code{org-display-custom-times} and
4092 @code{org-time-stamp-custom-formats}.
4097 Toggle the display of custom formats for dates and times.
4101 Org-mode needs the default format for scanning, so the custom date/time
4102 format does not @emph{replace} the default format - instead it is put
4103 @emph{over} the default format using text properties. This has the
4104 following consequences:
4107 You cannot place the cursor onto a time stamp anymore, only before or
4110 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
4111 each component of a time stamp. If the cursor is at the beginning of
4112 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
4113 just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the
4114 time will be changed by one minute.
4116 If the time stamp contains a range of clock times or a repeater, these
4117 will not be overlayed, but remain in the buffer as they were.
4119 When you delete a time stamp character-by-character, it will only
4120 disappear from the buffer after @emph{all} (invisible) characters
4121 belonging to the ISO timestamp have been removed.
4123 If the custom time stamp format is longer than the default and you are
4124 using dates in tables, table alignment will be messed up. If the custom
4125 format is shorter, things do work as expected.
4129 @node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and times
4130 @section Deadlines and Scheduling
4132 A time stamp may be preceded by special keywords to facilitate planning
4137 @cindex DEADLINE keyword
4138 The task (most likely a TODO item) is supposed to be finished on that
4139 date, and it will be listed then. In addition, the compilation for
4140 @emph{today} will carry a warning about the approaching or missed
4141 deadline, starting @code{org-deadline-warning-days} before the due date,
4142 and continuing until the entry is marked DONE. An example:
4145 *** TODO write article about the Earth for the Guide
4146 The editor in charge is [[bbdb:Ford Prefect]]
4147 DEADLINE: <2004-02-29 Sun>
4150 You can specify a different lead time for warnings for a specific
4151 deadlines using the following syntax. Here is an example with a warning
4152 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}.
4155 @cindex SCHEDULED keyword
4156 You are planning to start working on that task on the given date. The
4157 headline will be listed under the given date@footnote{It will still be
4158 listed on that date after it has been marked DONE. If you don't like
4159 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
4160 addition, a reminder that the scheduled date has passed will be present
4161 in the compilation for @emph{today}, until the entry is marked DONE.
4162 I.e., the task will automatically be forwarded until completed.
4165 *** TODO Call Trillian for a date on New Years Eve.
4166 SCHEDULED: <2004-12-25 Sat>
4170 @b{Important:} Scheduling an item in Org-mode should @i{not} be
4171 understood like @i{Scheduling a meeting}. Setting a date for a meeting
4172 is just a simple appointment, you should mark this entry with a simple
4173 plain time stamp, to get this item shown on the date where it applies.
4174 This is a frequent mis-understanding from Org-users. In Org-mode,
4175 @i{Scheduling} means setting a date when you want to start working on an
4180 * Inserting deadline/schedule:: Planning items
4181 * Repeated tasks:: Items that show up again and again
4184 @node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling
4185 @subsection Inserting deadline/schedule
4187 The following commands allow to quickly insert a deadline or to schedule
4194 Insert @samp{DEADLINE} keyword along with a stamp. The insertion will
4195 happen in the line directly following the headline. When called with a
4196 prefix arg, an existing deadline will be removed from the entry.
4197 @c FIXME Any CLOSED timestamp will be removed.????????
4200 @cindex sparse tree, for deadlines
4202 Create a sparse tree with all deadlines that are either past-due, or
4203 which will become due within @code{org-deadline-warning-days}.
4204 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
4205 prefix, check that many days. For example, @kbd{C-1 C-c / d} shows
4206 all deadlines due tomorrow.
4210 Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will
4211 happen in the line directly following the headline. Any CLOSED
4212 timestamp will be removed. When called with a prefix argument, remove
4213 the scheduling date from the entry.
4216 @node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling
4217 @subsection Repeated Tasks
4219 Some tasks need to be repeated again and again, and Org-mode therefore
4220 allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for
4223 ** TODO Pay the rent
4224 DEADLINE: <2005-10-01 Sat +1m>
4227 Deadlines and scheduled items produce entries in the agenda when they
4228 are over-due, so it is important to be able to mark such an entry as
4229 completed once you have done so. When you mark a DEADLINE or a SCHEDULE
4230 with the todo keyword DONE, it will no longer produce entries in the
4231 agenda. The problem with this is, however, that then also the
4232 @emph{next} instance of the repeated entry will not be active. Org-mode
4233 deals with this in the following way: When you try to mark such an entry
4234 DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating
4235 time stamp by the repeater interval, and immediately set the entry state
4236 back to TODO. In the example above, setting the state to DONE would
4237 actually switch the date like this:
4240 ** TODO Pay the rent
4241 DEADLINE: <2005-11-01 Tue +1m>
4244 You will also be prompted for a note@footnote{You can change this using
4245 the option @code{org-log-repeat}, or the @code{#+STARTUP} options
4246 @code{logrepeat} and @code{nologrepeat}.} that will be put under the
4247 DEADLINE line to keep a record that you actually acted on the previous
4248 instance of this deadline.
4250 As a consequence of shifting the base date, this entry will no longer be
4251 visible in the agenda when checking past dates, but all future instances
4254 You may have both scheduling and deadline information for a specific
4255 task - just make sure that the repeater intervals on both are the same.
4257 @node Clocking work time, , Deadlines and scheduling, Dates and times
4258 @section Clocking work time
4260 Org-mode allows you to clock the time you spent on specific tasks in a
4261 project. When you start working on an item, you can start the clock.
4262 When you stop working on that task, or when you mark the task done, the
4263 clock is stopped and the corresponding time interval is recorded. It
4264 also computes the total time spent on each subtree of a project.
4269 Start the clock on the current item (clock-in). This inserts the CLOCK
4270 keyword together with a timestamp. If this is not the first clocking of
4271 this item, the multiple CLOCK lines will be wrapped into a
4272 @code{:CLOCK:} drawer (see also the variable
4273 @code{org-clock-into-drawer}.
4276 Stop the clock (clock-out). The inserts another timestamp at the same
4277 location where the clock was last started. It also directly computes
4278 the resulting time in inserts it after the time range as @samp{=>
4279 HH:MM}. See the variable @code{org-log-done} for the possibility to
4280 record an additional note together with the clock-out time
4281 stamp@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
4285 Recompute the time interval after changing one of the time stamps. This
4286 is only necessary if you edit the time stamps directly. If you change
4287 them with @kbd{S-@key{cursor}} keys, the update is automatic.
4290 Changing the TODO state of an item to DONE automatically stops the clock
4291 if it is running in this same item.
4294 Cancel the current clock. This is useful if a clock was started by
4295 mistake, or if you ended up working on something else.
4298 Jump to the entry that contains the currently running clock, an another
4302 Display time summaries for each subtree in the current buffer. This
4303 puts overlays at the end of each headline, showing the total time
4304 recorded under that heading, including the time of any subheadings. You
4305 can use visibility cycling to study the tree, but the overlays disappear
4306 when you change the buffer (see variable
4307 @code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}.
4310 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
4311 report as an org-mode table into the current file. When the cursor is
4312 at an existing clock table, just update it. When called with a prefix
4313 argument, jump to the first clock report in the current document and
4316 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
4321 If such a block already exists at point, its content is replaced by the
4322 new table. The @samp{BEGIN} line can specify options:
4324 :maxlevel @r{Maximum level depth to which times are listed in the table.}
4325 :emphasize @r{When @code{t}, emphasize level one and level two items}
4326 :scope @r{The scope to consider. This can be any of the following:}
4327 nil @r{the current buffer or narrowed region}
4328 file @r{the full current buffer}
4329 subtree @r{the subtree where the clocktable is located}
4330 treeN @r{the surrounding level N tree, for example @code{tree3}}
4331 tree @r{the surrounding level 1 tree}
4332 agenda @r{all agenda files}
4333 ("file"..) @r{scan these files}
4334 :block @r{The time block to consider. This block is specified relative}
4335 @r{to the current time and may be any of these keywords:}
4336 @r{@code{today}, @code{yesterday}, @code{thisweek}, @code{lastweek},}
4337 @r{@code{thismonth}, @code{lastmonth}, @code{thisyear}, or @code{lastyear}}.
4338 :tstart @r{A time string specifying when to start considering times}
4339 :tend @r{A time string specifying when to stop considering times}
4341 So to get a clock summary of the current level 1 tree, for the current
4342 day, you could write
4344 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1
4348 and to use a specific time range you could write@footnote{Note that all
4349 parameters must be specified in a single line - the line is broken here
4350 only to fit it onto the manual.}
4352 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
4353 :tend "<2006-08-10 Thu 12:00>"
4361 Update dynamical block at point. The cursor needs to be in the
4362 @code{#+BEGIN} line of the dynamic block.
4363 @kindex C-u C-c C-x C-u
4364 @item C-u C-c C-x C-u
4365 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
4366 you have several clocktable blocks in a buffer.
4369 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
4370 the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been
4371 worked on or closed during a day.
4373 @node Remember, Agenda views, Dates and times, Top
4375 @cindex @file{remember.el}
4377 The @i{Remember} package by John Wiegley lets you store quick notes with
4378 little interruption of your work flow. See
4379 @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more
4380 information. It is an excellent way to add new notes and tasks to
4381 Org-mode files. Org-mode significantly expands the possibilities of
4382 @i{remember}: You may define templates for different note types, and
4383 associate target files and headlines with specific templates. It also
4384 allows you to select the location where a note should be stored
4385 interactively, on the fly.
4388 * Setting up remember:: Some code for .emacs to get things going
4389 * Remember templates:: Define the outline of different note types
4390 * Storing notes:: Directly get the note to where it belongs
4391 * Refiling notes:: Moving a note or task to a project
4394 @node Setting up remember, Remember templates, Remember, Remember
4395 @section Setting up remember
4397 The following customization will tell @i{remember} to use org files as
4398 target, and to create annotations compatible with Org-mode links.
4401 (org-remember-insinuate)
4402 (setq org-directory "~/path/to/my/orgfiles/")
4403 (setq org-default-notes-file (concat org-directory "/notes.org"))
4404 (define-key global-map "\C-cr" 'org-remember)
4407 The last line binds the command @code{org-remember} to a global
4408 key@footnote{Please select your own key, @kbd{C-c r} is only a
4409 suggestion.}. @code{org-remember} basically just calls @code{remember},
4410 but it makes a few things easier: If there is an active region, it will
4411 automatically copy the region into the remember buffer. It also allows
4412 to jump to the buffer and location where remember notes are being
4413 stored: Just call @code{org-remember} with a prefix argument.
4415 @node Remember templates, Storing notes, Setting up remember, Remember
4416 @section Remember templates
4417 @cindex templates, for remember
4419 In combination with Org-mode, you can use templates to generate
4420 different types of @i{remember} notes. For example, if you would like
4421 to use one template to create general TODO entries, another one for
4422 journal entries, and a third one for collecting random ideas, you could
4426 (setq org-remember-templates
4427 '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks")
4428 ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")
4429 ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
4432 @noindent In these entries, the first string is just a name, and the
4433 character specifies how to select the template. It is useful if the
4434 character is also the first letter of the name. The next string
4435 specifies the template. Two more (optional) strings give the file in
4436 which, and the headline under which the new note should be stored. The
4437 file (if not present or @code{nil}) defaults to
4438 @code{org-default-notes-file}, the heading to
4439 @code{org-remember-default-headline}.
4441 When you call @kbd{M-x remember} (or @kbd{M-x org-remember}) to remember
4442 something, org will prompt for a key to select the template (if you have
4443 more than one template) and then prepare the buffer like
4446 [[file:link to where you called remember]]
4450 During expansion of the template, special @kbd{%}-escapes allow dynamic
4451 insertion of content:
4453 %^@{prompt@} @r{prompt the user for a string and replace this sequence with it.}
4454 %t @r{time stamp, date only}
4455 %T @r{time stamp with date and time}
4456 %u, %U @r{like the above, but inactive time stamps}
4457 %^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}}
4458 @r{You may define a prompt like @code{%^@{Birthday@}t}}
4459 %n @r{user name (taken from @code{user-full-name})}
4460 %a @r{annotation, normally the link created with @code{org-store-link}}
4461 %A @r{like @code{%a}, but prompt for the description part}
4462 %i @r{initial content, the region when remember is called with C-u.}
4463 @r{The entire text will be indented like @code{%i} itself.}
4464 %c @r{Content of the clipboard, or current kill ring head.}
4465 %^g @r{prompt for tags, with completion on tags in target file.}
4466 %^G @r{prompt for tags, with completion all tags in all agenda files.}
4467 %:keyword @r{specific information for certain link types, see below}
4468 %[pathname] @r{insert the contents of the file given by @code{pathname}}
4469 %(sexp) @r{evaluate elisp @code{(sexp)} and replace with the result}
4473 For specific link types, the following keywords will be
4474 defined@footnote{If you define your own link types (@pxref{Adding
4475 hyperlink types}), any property you store with
4476 @code{org-store-link-props} can be accessed in remember templates in a
4480 Link type | Available keywords
4481 -------------------+----------------------------------------------
4482 bbdb | %:name %:company
4483 vm, wl, mh, rmail | %:type %:subject %:message-id
4484 | %:from %:fromname %:fromaddress
4485 | %:to %:toname %:toaddress
4486 | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}}
4487 gnus | %:group, @r{for messages also all email fields}
4489 info | %:file %:node
4494 To place the cursor after template expansion use:
4497 %? @r{After completing the template, position cursor here.}
4501 If you change you mind about which template to use, call
4502 @code{org-remember} in the remember buffer. You may then select a new
4503 template that will be filled with the previous context information.
4505 @node Storing notes, Refiling notes, Remember templates, Remember
4506 @section Storing notes
4508 When you are finished preparing a note with @i{remember}, you have to press
4509 @kbd{C-c C-c} to file the note away. The handler will store the note in
4510 the file and under the headline specified in the template, or it will
4511 use the default file and headlines. The window configuration will be
4512 restored, and you are back in the working context before the call to
4513 @code{remember}. To re-use the location found during the last call to
4514 @code{remember}, exit the remember buffer with @kbd{C-u C-u C-c C-c},
4515 i.e. specify a double prefix argument to @kbd{C-c C-c}.
4517 If you want to store the note directly to a different place, use
4518 @kbd{C-u C-c C-c} instead to exit remember@footnote{Configure the
4519 variable @code{org-remember-store-without-prompt} to make this behavior
4520 the default.}. The handler will then first prompt for a target file -
4521 if you press @key{RET}, the value specified for the template is used.
4522 Then the command offers the headings tree of the selected file, with the
4523 cursor position at the default headline (if you had specified one in the
4524 template). You can either immediately press @key{RET} to get the note
4525 placed there. Or you can use the following keys to find a different
4528 @key{TAB} @r{Cycle visibility.}
4529 @key{down} / @key{up} @r{Next/previous visible headline.}
4530 n / p @r{Next/previous visible headline.}
4531 f / b @r{Next/previous headline same level.}
4533 @c 0-9 @r{Digit argument.}
4536 Pressing @key{RET} or @key{left} or @key{right}
4537 then leads to the following result.
4539 @multitable @columnfractions 0.2 0.15 0.65
4540 @item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}
4541 @item on headline @tab @key{RET} @tab as sublevel of the heading at cursor, first or last
4542 @item @tab @tab depending on @code{org-reverse-note-order}.
4543 @item @tab @key{left}/@key{right} @tab as same level, before/after current heading
4544 @item buffer-start @tab @key{RET} @tab as level 2 heading at end of file or level 1 at beginning
4545 @item @tab @tab depending on @code{org-reverse-note-order}.
4546 @item not on headline @tab @key{RET}
4547 @tab at cursor position, level taken from context.
4550 Before inserting the text into a tree, the function ensures that the
4551 text has a headline, i.e. a first line that starts with a @samp{*}. If
4552 not, a headline is constructed from the current date and some additional
4553 data. If you have indented the text of the note below the headline, the
4554 indentation will be adapted if inserting the note into the tree requires
4555 demotion from level 1.
4557 @node Refiling notes, , Storing notes, Remember
4558 @section Refiling notes
4559 @cindex refiling notes
4561 Remember is usually used to quickly capture notes and tasks into one or
4562 a few capture lists. When reviewing the captured data, you may want to
4563 refile some of the entries into a different list, for example into a
4564 project. Cutting, finding the right location and then pasting the note
4565 is cumbersome. To simplify this process, you can use the following
4571 Refile the entry at point. This command offers possible locations for
4572 refiling the entry and lets you select one with completion. The item is
4573 filed below the target heading as a subitem. Depending on
4574 @code{org-reverse-note-order}, it will be either the first of last
4575 subitem, and you can toggle the value of this variable for the duration
4576 of the command by using a @kbd{C-u} prefix.@* By default, all level 1
4577 headlines in the current buffer are considered to be targets, but you
4578 can have more complex definitions across a number of files. See the
4579 variable @code{org-refile-targets} for details. The list of targets is
4580 compiled upon first use, you can update it by using a double prefix
4581 argument (@kbd{C-u C-u}) to this command.
4584 @node Agenda views, Embedded LaTeX, Remember, Top
4585 @chapter Agenda Views
4586 @cindex agenda views
4588 Due to the way Org-mode works, TODO items, time-stamped items, and
4589 tagged headlines can be scattered throughout a file or even a number of
4590 files. To get an overview over open action items, or over events that
4591 are important for a particular date, this information must be collected,
4592 sorted and displayed in an organized way.
4594 Org-mode can select items based on various criteria, and display them
4595 in a separate buffer. Six different view types are provided:
4599 an @emph{agenda} that is like a calendar and shows information
4602 a @emph{TODO list} that covers all unfinished
4605 a @emph{tags view}, showings headlines based on
4606 the tags associated with them,
4608 a @emph{timeline view} that shows all events in a single Org-mode file,
4609 in time-sorted view,
4611 a @emph{stuck projects view} showing projects that currently don't move
4614 @emph{custom views} that are special tag/keyword searches and
4615 combinations of different views.
4619 The extracted information is displayed in a special @emph{agenda
4620 buffer}. This buffer is read-only, but provides commands to visit the
4621 corresponding locations in the original Org-mode files, and even to
4622 edit these files remotely.
4624 Two variables control how the agenda buffer is displayed and whether the
4625 window configuration is restored when the agenda exits:
4626 @code{org-agenda-window-setup} and
4627 @code{org-agenda-restore-windows-after-quit}.
4630 * Agenda files:: Files being searched for agenda information
4631 * Agenda dispatcher:: Keyboard access to agenda views
4632 * Built-in agenda views:: What is available out of the box?
4633 * Presentation and sorting:: How agenda items are prepared for display
4634 * Agenda commands:: Remote editing of org trees
4635 * Custom agenda views:: Defining special searches and views
4638 @node Agenda files, Agenda dispatcher, Agenda views, Agenda views
4639 @section Agenda files
4640 @cindex agenda files
4641 @cindex files for agenda
4643 The information to be shown is collected from all @emph{agenda files},
4644 the files listed in the variable @code{org-agenda-files}@footnote{If the
4645 value of that variable is not a list, but a single file name, then the
4646 list of agenda files will be maintained in that external file.}. If a
4647 directory is part of this list, all files with the extension @file{.org}
4648 in this directory will be part of the list.
4650 Thus even if you only work with a single Org-mode file, this file should
4651 be put into that list@footnote{When using the dispatcher, pressing
4652 @kbd{<} before selecting a command will actually limit the command to
4653 the current file, and ignore @code{org-agenda-files} until the next
4654 dispatcher command.}. You can customize @code{org-agenda-files}, but
4655 the easiest way to maintain it is through the following commands
4657 @cindex files, adding to agenda list
4661 Add current file to the list of agenda files. The file is added to
4662 the front of the list. If it was already in the list, it is moved to
4663 the front. With prefix arg, file is added/moved to the end.
4666 Remove current file from the list of agenda files.
4671 Cycle through agenda file list, visiting one file after the other.
4675 The Org menu contains the current list of files and can be used
4676 to visit any of them.
4678 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views
4679 @section The agenda dispatcher
4680 @cindex agenda dispatcher
4681 @cindex dispatching agenda commands
4682 The views are created through a dispatcher that should be bound to a
4683 global key, for example @kbd{C-c a} (@pxref{Installation}). In the
4684 following we will assume that @kbd{C-c a} is indeed how the dispatcher
4685 is accessed and list keyboard access to commands accordingly. After
4686 pressing @kbd{C-c a}, an additional letter is required to execute a
4687 command. The dispatcher offers the following default commands:
4690 Create the calendar-like agenda (@pxref{Weekly/Daily agenda}).
4692 Create a list of all TODO items (@pxref{Global TODO list}).
4694 Create a list of headlines matching a TAGS expression (@pxref{Matching
4695 tags and properties}).
4697 Create the timeline view for the current buffer (@pxref{Timeline}).
4699 Create a list of stuck projects (@pxref{Stuck projects}).
4701 Search for a regular expression in all agenda files and additionally in
4702 the files listed in @code{org-agenda-multi-occur-extra-files}. This
4703 uses the Emacs command @code{multi-occur}. A prefix argument can be
4704 used to specify the number of context lines for each match, default is
4707 Restrict an agenda command to the current buffer@footnote{For backward
4708 compatibility, you can also press @kbd{1} to restrict to the current
4709 buffer.}. After pressing @kbd{<}, you still need to press the character
4710 selecting the command.
4712 If there is an active region, restrict the following agenda command to
4713 the region. Otherwise, restrict it to the current subtree@footnote{For
4714 backward compatibility, you can also press @kbd{0} to restrict to the
4715 current buffer.}. After pressing @kbd{< <}, you still need to press the
4716 character selecting the command.
4719 You can also define custom commands that will be accessible through the
4720 dispatcher, just like the default commands. This includes the
4721 possibility to create extended agenda buffers that contain several
4722 blocks together, for example the weekly agenda, the global TODO list and
4723 a number of special tags matches. @xref{Custom agenda views}.
4725 @node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views
4726 @section The built-in agenda views
4728 In this section we describe the built-in views.
4731 * Weekly/Daily agenda:: The calendar page with current tasks
4732 * Global TODO list:: All unfinished action items
4733 * Matching tags and properties:: Structured information with fine-tuned search
4734 * Timeline:: Time-sorted view for single file
4735 * Stuck projects:: Find projects you need to review
4738 @node Weekly/Daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
4739 @subsection The weekly/daily agenda
4741 @cindex weekly agenda
4742 @cindex daily agenda
4744 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
4745 paper agenda, showing all the tasks for the current week or day.
4748 @cindex org-agenda, command
4751 Compile an agenda for the current week from a list of org files. The
4752 agenda shows the entries for each day. With a numeric
4753 prefix@footnote{For backward compatibility, the universal prefix
4754 @kbd{C-u} causes all TODO entries to be listed before the agenda. This
4755 feature is deprecated, use the dedicated TODO list, or a block agenda
4756 instead.} (like @kbd{C-u 2 1 C-c a a}) you may set the number of days
4757 to be displayed (see also the variable @code{org-agenda-ndays})
4760 Remote editing from the agenda buffer means, for example, that you can
4761 change the dates of deadlines and appointments from the agenda buffer.
4762 The commands available in the Agenda buffer are listed in @ref{Agenda
4765 @subsubheading Calendar/Diary integration
4766 @cindex calendar integration
4767 @cindex diary integration
4769 Emacs contains the calendar and diary by Edward M. Reingold. The
4770 calendar displays a three-month calendar with holidays from different
4771 countries and cultures. The diary allows you to keep track of
4772 anniversaries, lunar phases, sunrise/set, recurrent appointments
4773 (weekly, monthly) and more. In this way, it is quite complementary to
4774 Org-mode. It can be very useful to combine output from Org-mode with
4777 In order to include entries from the Emacs diary into Org-mode's
4778 agenda, you only need to customize the variable
4781 (setq org-agenda-include-diary t)
4784 @noindent After that, everything will happen automatically. All diary
4785 entries including holidays, anniversaries etc will be included in the
4786 agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and
4787 @key{RET} can be used from the agenda buffer to jump to the diary
4788 file in order to edit existing diary entries. The @kbd{i} command to
4789 insert new entries for the current date works in the agenda buffer, as
4790 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
4791 Sunrise/Sunset times, show lunar phases and to convert to other
4792 calendars, respectively. @kbd{c} can be used to switch back and forth
4793 between calendar and agenda.
4795 If you are using the diary only for sexp entries and holidays, it is
4796 faster to not use the above setting, but instead to copy or even move
4797 the entries into an Org-mode file. Org-mode evaluates diary-style sexp
4798 entries, and does it faster because there is no overhead for first
4799 creating the diary display. Note that the sexp entries must start at
4800 the left margin, no white space is allowed before them. For example,
4801 the following segment of an Org-mode file will be processed and entries
4802 will be made in the agenda:
4805 * Birthdays and similar stuff
4807 %%(org-calendar-holiday) ; special function for holiday names
4809 %%(diary-anniversary 14 5 1956) Arthur Dent is %d years old
4810 %%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old
4813 @subsubheading Appointment reminders
4814 @cindex @file{appt.el}
4815 @cindex appointment reminders
4817 Org can interact with Emacs appointments notification facility.
4819 To add all the appointments of your agenda files, use the command
4820 @code{org-agenda-to-appt}. This commands also lets you filter through
4821 the list of your appointments and add only those belonging to a specific
4822 category or matching a regular expression. See the docstring for
4825 @node Global TODO list, Matching tags and properties, Weekly/Daily agenda, Built-in agenda views
4826 @subsection The global TODO list
4827 @cindex global TODO list
4828 @cindex TODO list, global
4830 The global TODO list contains all unfinished TODO items, formatted and
4831 collected into a single place.
4836 Show the global TODO list. This collects the TODO items from all
4837 agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in
4838 @code{agenda-mode}, so there are commands to examine and manipulate
4839 the TODO entries directly from that buffer (@pxref{Agenda commands}).
4842 @cindex TODO keyword matching
4843 Like the above, but allows selection of a specific TODO keyword. You
4844 can also do this by specifying a prefix argument to @kbd{C-c a t}. With
4845 a @kbd{C-u} prefix you are prompted for a keyword, and you may also
4846 specify several keywords by separating them with @samp{|} as boolean OR
4847 operator. With a numeric prefix, the Nth keyword in
4848 @code{org-todo-keywords} is selected.
4850 The @kbd{r} key in the agenda buffer regenerates it, and you can give
4851 a prefix argument to this command to change the selected TODO keyword,
4852 for example @kbd{3 r}. If you often need a search for a specific
4853 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
4854 Matching specific TODO keywords can also be done as part of a tags
4855 search (@pxref{Tag searches}).
4858 Remote editing of TODO items means that you can change the state of a
4859 TODO entry with a single key press. The commands available in the
4860 TODO list are described in @ref{Agenda commands}.
4862 @cindex sublevels, inclusion into todo list
4863 Normally the global todo list simply shows all headlines with TODO
4864 keywords. This list can become very long. There are two ways to keep
4868 Some people view a TODO item that has been @emph{scheduled} for
4869 execution (@pxref{Time stamps}) as no longer @emph{open}. Configure the
4870 variable @code{org-agenda-todo-ignore-scheduled} to exclude scheduled
4871 items from the global TODO list.
4873 TODO items may have sublevels to break up the task into subtasks. In
4874 such cases it may be enough to list only the highest level TODO headline
4875 and omit the sublevels from the global list. Configure the variable
4876 @code{org-agenda-todo-list-sublevels} to get this behavior.
4879 @node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views
4880 @subsection Matching Tags and Properties
4881 @cindex matching, of tags
4882 @cindex matching, of properties
4885 If headlines in the agenda files are marked with @emph{tags}
4886 (@pxref{Tags}), you can select headlines based on the tags that apply
4887 to them and collect them into an agenda buffer.
4892 Produce a list of all headlines that match a given set of tags. The
4893 command prompts for a selection criterion, which is a boolean logic
4894 expression with tags, like @samp{+work+urgent-withboss} or
4895 @samp{work|home} (@pxref{Tags}). If you often need a specific search,
4896 define a custom command for it (@pxref{Agenda dispatcher}).
4899 Like @kbd{C-c a m}, but only select headlines that are also TODO items
4900 and force checking subitems (see variable
4901 @code{org-tags-match-list-sublevels}). Matching specific todo keywords
4902 together with a tags match is also possible, see @ref{Tag searches}.
4905 The commands available in the tags list are described in @ref{Agenda
4908 @node Timeline, Stuck projects, Matching tags and properties, Built-in agenda views
4909 @subsection Timeline for a single file
4910 @cindex timeline, single file
4911 @cindex time-sorted view
4913 The timeline summarizes all time-stamped items from a single Org-mode
4914 file in a @emph{time-sorted view}. The main purpose of this command is
4915 to give an overview over events in a project.
4920 Show a time-sorted view of the org file, with all time-stamped items.
4921 When called with a @kbd{C-u} prefix, all unfinished TODO entries
4922 (scheduled or not) are also listed under the current date.
4926 The commands available in the timeline buffer are listed in
4927 @ref{Agenda commands}.
4930 @node Stuck projects, , Timeline, Built-in agenda views
4931 @subsection Stuck projects
4933 If you are following a system like David Allen's GTD to organize your
4934 work, one of the ``duties'' you have is a regular review to make sure
4935 that all projects move along. A @emph{stuck} project is a project that
4936 has no defined next actions, so it will never show up in the TODO lists
4937 Org-mode produces. During the review, you need to identify such
4938 projects and define next actions for them.
4943 List projects that are stuck.
4946 Customize the variable @code{org-stuck-projects} to define what a stuck
4947 project is and how to find it.
4950 You almost certainly will have to configure this view before it will
4951 work for you. The built-in default assumes that all your projects are
4952 level-2 headlines, and that a project is not stuck if it has at least
4953 one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
4955 Lets assume that you, in your own way of using Org-mode, identify
4956 projects with a tag PROJECT, and that you use a todo keyword MAYBE to
4957 indicate a project that should not be considered yet. Lets further
4958 assume that the todo keyword DONE marks finished projects, and that NEXT
4959 and TODO indicate next actions. The tag @@SHOP indicates shopping and
4960 is a next action even without the NEXT tag. Finally, if the project
4961 contains the special word IGNORE anywhere, it should not be listed
4962 either. In this case you would start by identifying eligible projects
4963 with a tags/todo match @samp{+PROJECT/-MAYBE-DONE}, and then check for
4964 TODO, NEXT, @@SHOP, and IGNORE in the subtree to identify projects that
4965 are not stuck. The correct customization for this is
4968 (setq org-stuck-projects
4969 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
4974 @node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views
4975 @section Presentation and sorting
4976 @cindex presentation, of agenda items
4978 Before displaying items in an agenda view, Org-mode visually prepares
4979 the items and sorts them. Each item occupies a single line. The line
4980 starts with a @emph{prefix} that contains the @emph{category}
4981 (@pxref{Categories}) of the item and other important information. You can
4982 customize the prefix using the option @code{org-agenda-prefix-format}.
4983 The prefix is followed by a cleaned-up version of the outline headline
4984 associated with the item.
4987 * Categories:: Not all tasks are equal
4988 * Time-of-day specifications:: How the agenda knows the time
4989 * Sorting of agenda items:: The order of things
4992 @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
4993 @subsection Categories
4996 The category is a broad label assigned to each agenda item. By default,
4997 the category is simply derived from the file name, but you can also
4998 specify it with a special line in the buffer, like this@footnote{For
4999 backward compatibility, the following also works: If there are several
5000 such lines in a file, each specifies the category for the text below it.
5001 The first category also applies to any text before the first CATEGORY
5002 line. However, using this method is @emph{strongly} deprecated as it is
5003 incompatible with the outline structure of the document. The correct
5004 method for setting multiple categories in a buffer is using a
5012 If you would like to have a special CATEGORY for a single entry or a
5013 (sub)tree, give the entry a @code{:CATEGORY:} property with the location
5014 as the value (@pxref{Properties and columns}).
5017 The display in the agenda buffer looks best if the category is not
5018 longer than 10 characters.
5020 @node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
5021 @subsection Time-of-Day Specifications
5022 @cindex time-of-day specification
5024 Org-mode checks each agenda item for a time-of-day specification. The
5025 time can be part of the time stamp that triggered inclusion into the
5026 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
5027 ranges can be specified with two time stamps, like
5029 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
5031 In the headline of the entry itself, a time(range) may also appear as
5032 plain text (like @samp{12:45} or a @samp{8:30-1pm}. If the agenda
5033 integrates the Emacs diary (@pxref{Weekly/Daily agenda}), time
5034 specifications in diary entries are recognized as well.
5036 For agenda display, Org-mode extracts the time and displays it in a
5037 standard 24 hour format as part of the prefix. The example times in
5038 the previous paragraphs would end up in the agenda like this:
5041 8:30-13:00 Arthur Dent lies in front of the bulldozer
5042 12:45...... Ford Prefect arrives and takes Arthur to the pub
5043 19:00...... The Vogon reads his poem
5044 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
5048 If the agenda is in single-day mode, or for the display of today, the
5049 timed entries are embedded in a time grid, like
5052 8:00...... ------------------
5053 8:30-13:00 Arthur Dent lies in front of the bulldozer
5054 10:00...... ------------------
5055 12:00...... ------------------
5056 12:45...... Ford Prefect arrives and takes Arthur to the pub
5057 14:00...... ------------------
5058 16:00...... ------------------
5059 18:00...... ------------------
5060 19:00...... The Vogon reads his poem
5061 20:00...... ------------------
5062 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
5065 The time grid can be turned on and off with the variable
5066 @code{org-agenda-use-time-grid}, and can be configured with
5067 @code{org-agenda-time-grid}.
5069 @node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting
5070 @subsection Sorting of agenda items
5071 @cindex sorting, of agenda items
5072 @cindex priorities, of agenda items
5073 Before being inserted into a view, the items are sorted. How this is
5074 done depends on the type of view.
5077 For the daily/weekly agenda, the items for each day are sorted. The
5078 default order is to first collect all items containing an explicit
5079 time-of-day specification. These entries will be shown at the beginning
5080 of the list, as a @emph{schedule} for the day. After that, items remain
5081 grouped in categories, in the sequence given by @code{org-agenda-files}.
5082 Within each category, items are sorted by priority (@pxref{Priorities}),
5083 which is composed of the base priority (2000 for priority @samp{A}, 1000
5084 for @samp{B}, and 0 for @samp{C}), plus additional increments for
5085 overdue scheduled or deadline items.
5087 For the TODO list, items remain in the order of categories, but within
5088 each category, sorting takes place according to priority
5089 (@pxref{Priorities}).
5091 For tags matches, items are not sorted at all, but just appear in the
5092 sequence in which they are found in the agenda files.
5095 Sorting can be customized using the variable
5096 @code{org-agenda-sorting-strategy}.
5099 @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda views
5100 @section Commands in the agenda buffer
5101 @cindex commands, in agenda buffer
5103 Entries in the agenda buffer are linked back to the org file or diary
5104 file where they originate. You are not allowed to edit the agenda
5105 buffer itself, but commands are provided to show and jump to the
5106 original entry location, and to edit the org-files ``remotely'' from
5107 the agenda buffer. In this way, all information is stored only once,
5108 removing the risk that your agenda and note files may diverge.
5110 Some commands can be executed with mouse clicks on agenda lines. For
5111 the other commands, the cursor needs to be in the desired line.
5114 @tsubheading{Motion}
5115 @cindex motion commands in agenda
5118 Next line (same as @key{up} and @kbd{C-p}).
5121 Previous line (same as @key{down} and @kbd{C-n}).
5122 @tsubheading{View/GoTo org file}
5127 Display the original location of the item in another window.
5131 Display original location and recenter that window.
5139 Go to the original location of the item in another window. Under Emacs
5140 22, @kbd{mouse-1} will also works for this.
5144 Go to the original location of the item and delete other windows.
5148 Toggle Follow mode. In Follow mode, as you move the cursor through
5149 the agenda buffer, the other window always shows the corresponding
5150 location in the org file. The initial setting for this mode in new
5151 agenda buffers can be set with the variable
5152 @code{org-agenda-start-with-follow-mode}.
5156 Display the entire subtree of the current item in an indirect buffer.
5157 With numerical prefix ARG, go up to this level and then take that tree.
5158 If ARG is negative, go up that many levels. With @kbd{C-u} prefix, do
5159 not remove the previously used indirect buffer.
5163 Toggle Logbook mode. In Logbook mode, entries that where marked DONE while
5164 logging was on (variable @code{org-log-done}) are shown in the agenda,
5165 as are entries that have been clocked on that day.
5167 @tsubheading{Change display}
5168 @cindex display changing, in agenda
5171 Delete other windows.
5178 Switch to day/week/month/year view. When switching to day or week view,
5179 this setting becomes the default for subseqent agenda commands. Since
5180 month and year views are slow to create, the do not become the default.
5184 Toggle the inclusion of diary entries. See @ref{Weekly/Daily agenda}.
5188 Toggle the time grid on and off. See also the variables
5189 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
5193 Recreate the agenda buffer, for example to reflect the changes
5194 after modification of the time stamps of items with S-@key{left} and
5195 S-@key{right}. When the buffer is the global todo list, a prefix
5196 argument is interpreted to create a selective list for a specific TODO
5203 Save all Org-mode buffers in the current Emacs session.
5207 Display the following @code{org-agenda-ndays} days. For example, if
5208 the display covers a week, switch to the following week. With prefix
5209 arg, go forward that many times @code{org-agenda-ndays} days.
5213 Display the previous dates.
5219 @tsubheading{Remote editing}
5220 @cindex remote editing, from agenda
5225 @cindex undoing remote-editing events
5226 @cindex remote editing, undo
5229 Undo a change due to a remote editing command. The change is undone
5230 both in the agenda buffer and in the remote buffer.
5234 Change the TODO state of the item, both in the agenda and in the
5239 Delete the current agenda item along with the entire subtree belonging
5240 to it in the original Org-mode file. If the text to be deleted remotely
5241 is longer than one line, the kill needs to be confirmed by the user. See
5242 variable @code{org-agenda-confirm-kill}.
5246 Archive the subtree corresponding to the current headline.
5250 Show all tags associated with the current item. Because of
5251 inheritance, this may be more than the tags listed in the line itself.
5255 Set tags for the current headline. If there is an active region in the
5256 agenda, change a tag for all headings in the region.
5260 Toggle the ARCHIVE tag for the current headline.
5264 Set the priority for the current item. Org-mode prompts for the
5265 priority character. If you reply with @key{SPC}, the priority cookie
5266 is removed from the entry.
5270 Display weighted priority of current item.
5276 Increase the priority of the current item. The priority is changed in
5277 the original buffer, but the agenda is not resorted. Use the @kbd{r}
5281 @kindex S-@key{down}
5284 Decrease the priority of the current item.
5292 Set a deadline for this item.
5294 @kindex S-@key{right}
5296 Change the time stamp associated with the current line by one day into
5297 the future. With prefix argument, change it by that many days. For
5298 example, @kbd{3 6 5 S-@key{right}} will change it by a year. The
5299 stamp is changed in the original org file, but the change is not
5300 directly reflected in the agenda buffer. Use the
5301 @kbd{r} key to update the buffer.
5303 @kindex S-@key{left}
5305 Change the time stamp associated with the current line by one day
5310 Change the time stamp associated with the current line to today.
5311 The key @kbd{>} has been chosen, because it is the same as @kbd{S-.}
5316 Start the clock on the current item. If a clock is running already, it
5321 Stop the previously started clock.
5325 Cancel the currently running clock.
5329 Jump to the running clock in another window.
5331 @tsubheading{Calendar commands}
5332 @cindex calendar commands, from agenda
5335 Open the Emacs calendar and move to the date at the agenda cursor.
5338 When in the calendar, compute and show the Org-mode agenda for the
5341 @cindex diary entries, creating from agenda
5344 Insert a new entry into the diary. Prompts for the type of entry
5345 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a new
5346 entry in the diary, just as @kbd{i d} etc. would do in the calendar.
5347 The date is taken from the cursor position.
5351 Show the phases of the moon for the three months around current date.
5355 Show sunrise and sunset times. The geographical location must be set
5356 with calendar variables, see documentation of the Emacs calendar.
5360 Convert the date at cursor into many other cultural and historic
5365 Show holidays for three month around the cursor date.
5367 @c FIXME: This should be a different key.
5370 Export a single iCalendar file containing entries from all agenda files.
5372 @tsubheading{Exporting to a file}
5375 @cindex exporting agenda views
5376 @cindex agenda views, exporting
5377 Write the agenda view to a file. Depending on the extension of the
5378 selected file name, the view will be exported as HTML (extension
5379 @file{.html} or @file{.htm}), Postscript (extension @file{.ps}), or
5380 plain text (any other extension). Use the variable
5381 @code{org-agenda-exporter-settings} to set options for @file{ps-print}
5382 and for @file{htmlize} to be used during export.
5384 @tsubheading{Quit and Exit}
5387 Quit agenda, remove the agenda buffer.
5390 @cindex agenda files, removing buffers
5392 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
5393 for the compilation of the agenda. Buffers created by the user to
5394 visit org files will not be removed.
5398 @node Custom agenda views, , Agenda commands, Agenda views
5399 @section Custom agenda views
5400 @cindex custom agenda views
5401 @cindex agenda views, custom
5403 Custom agenda commands serve two purposes: to store and quickly access
5404 frequently used TODO and tags searches, and to create special composite
5405 agenda buffers. Custom agenda commands will be accessible through the
5406 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
5409 * Storing searches:: Type once, use often
5410 * Block agenda:: All the stuff you need in a single buffer
5411 * Setting Options:: Changing the rules
5412 * Exporting Agenda Views:: Writing agendas to files.
5413 * Extracting Agenda Information for other programs::
5416 @node Storing searches, Block agenda, Custom agenda views, Custom agenda views
5417 @subsection Storing searches
5419 The first application of custom searches is the definition of keyboard
5420 shortcuts for frequently used searches, either creating an agenda
5421 buffer, or a sparse tree (the latter covering of course only the current
5424 Custom commands are configured in the variable
5425 @code{org-agenda-custom-commands}. You can customize this variable, for
5426 example by pressing @kbd{C-c a C}. You can also directly set it with
5427 Emacs Lisp in @file{.emacs}. The following example contains all valid
5432 (setq org-agenda-custom-commands
5433 '(("w" todo "WAITING")
5434 ("W" todo-tree "WAITING")
5435 ("u" tags "+BOSS-URGENT")
5436 ("v" tags-todo "+BOSS-URGENT")
5437 ("U" tags-tree "+BOSS-URGENT")
5438 ("f" occur-tree "\\<FIXME\\>")
5439 ("h" . "HOME+Name tags searches") ; description for "h" prefix
5440 ("hl" tags "+HOME+Lisa")
5441 ("hp" tags "+HOME+Peter")
5442 ("hk" tags "+HOME+Kim")))
5447 The initial string in each entry defines the keys you have to press
5448 after the dispatcher command @kbd{C-c a} in order to access the command.
5449 Usually this will be just a single character, but if you have many
5450 similar commands, you can also define two-letter combinations where the
5451 first character is the same in several combinations and serves as a
5452 prefix key@footnote{You can provide a description for a prefix key by
5453 inserting a cons cell with the prefix and the description.}. The second
5454 parameter is the search type, followed by the string or regular
5455 expression to be used for the matching. The example above will
5460 as a global search for TODO entries with @samp{WAITING} as the TODO
5463 as the same search, but only in the current buffer and displaying the
5464 results as a sparse tree
5466 as a global tags search for headlines marked @samp{:BOSS:} but not
5469 as the same search as @kbd{C-c a u}, but limiting the search to
5470 headlines that are also TODO items
5472 as the same search as @kbd{C-c a u}, but only in the current buffer and
5473 displaying the result as a sparse tree
5475 to create a sparse tree (again: current buffer only) with all entries
5476 containing the word @samp{FIXME}
5478 as a prefix command for a HOME tags search where you have to press an
5479 additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,
5480 Peter, or Kim) as additional tag to match.
5483 @node Block agenda, Setting Options, Storing searches, Custom agenda views
5484 @subsection Block agenda
5485 @cindex block agenda
5486 @cindex agenda, with block views
5488 Another possibility is the construction of agenda views that comprise
5489 the results of @emph{several} commands, each of which creates a block in
5490 the agenda buffer. The available commands include @code{agenda} for the
5491 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
5492 for the global todo list (as constructed with @kbd{C-c a t}), and the
5493 matching commands discussed above: @code{todo}, @code{tags}, and
5494 @code{tags-todo}. Here are two examples:
5498 (setq org-agenda-custom-commands
5499 '(("h" "Agenda and Home-related tasks"
5503 ("o" "Agenda and Office-related tasks"
5511 This will define @kbd{C-c a h} to create a multi-block view for stuff
5512 you need to attend to at home. The resulting agenda buffer will contain
5513 your agenda for the current week, all TODO items that carry the tag
5514 @samp{HOME}, and also all lines tagged with @samp{GARDEN}. Finally the
5515 command @kbd{C-c a o} provides a similar view for office tasks.
5518 @node Setting Options, Exporting Agenda Views, Block agenda, Custom agenda views
5519 @subsection Setting Options for custom commands
5520 @cindex options, for custom agenda views
5522 Org-mode contains a number of variables regulating agenda construction
5523 and display. The global variables define the behavior for all agenda
5524 commands, including the custom commands. However, if you want to change
5525 some settings just for a single custom view, you can do so. Setting
5526 options requires inserting a list of variable names and values at the
5527 right spot in @code{org-agenda-custom-commands}. For example:
5531 (setq org-agenda-custom-commands
5532 '(("w" todo "WAITING"
5533 ((org-agenda-sorting-strategy '(priority-down))
5534 (org-agenda-prefix-format " Mixed: ")))
5535 ("U" tags-tree "+BOSS-URGENT"
5536 ((org-show-following-heading nil)
5537 (org-show-hierarchy-above nil)))))
5542 Now the @kbd{C-c a w} command will sort the collected entries only by
5543 priority, and the prefix format is modified to just say @samp{ Mixed:}
5544 instead of giving the category of the entry. The sparse tags tree of
5545 @kbd{C-c a U} will now turn out ultra-compact, because neither the
5546 headline hierarchy above the match, nor the headline following the match
5549 For command sets creating a block agenda,
5550 @code{org-agenda-custom-commands} has two separate spots for setting
5551 options. You can add options that should be valid for just a single
5552 command in the set, and options that should be valid for all commands in
5553 the set. The former are just added to the command entry, the latter
5554 must come after the list of command entries. Going back to the block
5555 agenda example (@pxref{Block agenda}), let's change the sorting strategy
5556 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
5557 the results for GARDEN tags query in the opposite order,
5558 @code{priority-up}. This would look like this:
5562 (setq org-agenda-custom-commands
5563 '(("h" "Agenda and Home-related tasks"
5567 ((org-agenda-sorting-strategy '(priority-up)))))
5568 ((org-agenda-sorting-strategy '(priority-down))))
5569 ("o" "Agenda and Office-related tasks"
5576 As you see, the values and parenthesis setting is a little complex.
5577 When in doubt, use the customize interface to set this variable - it
5578 fully supports its structure. Just one caveat: When setting options in
5579 this interface, the @emph{values} are just lisp expressions. So if the
5580 value is a string, you need to add the double quotes around the value
5584 @node Exporting Agenda Views, Extracting Agenda Information for other programs, Setting Options, Custom agenda views
5585 @subsection Exporting Agenda Views
5586 @cindex agenda views, exporting
5588 If you are away from your computer, it can be very useful to have a
5589 printed version of some agenda views to carry around. Org-mode can
5590 export custom agenda views as plain text, HTML@footnote{You need to
5591 install Hrvoje Niksic' @file{htmlize.el}.} and postscript. If you want
5592 to do this only occasionally, use the command
5597 @cindex exporting agenda views
5598 @cindex agenda views, exporting
5599 Write the agenda view to a file. Depending on the extension of the
5600 selected file name, the view will be exported as HTML (extension
5601 @file{.html} or @file{.htm}), Postscript (extension @file{.ps}), or
5602 plain text (any other extension). Use the variable
5603 @code{org-agenda-exporter-settings} to set options for @file{ps-print}
5604 and for @file{htmlize} to be used during export, for example
5606 (setq org-agenda-exporter-settings
5607 '((ps-number-of-columns 2)
5608 (ps-landscape-mode t)
5609 (htmlize-output-type 'css)))
5613 If you need to export certain agenda views frequently, you can associate
5614 any custom agenda command with a list of output file names
5615 @footnote{If you want to store standard views like the weekly agenda
5616 or the global TODO list as well, you need to define custom commands for
5617 them in order to be able to specify filenames.}. Here is an example
5618 that first does define custom commands for the agenda and the global
5619 todo list, together with a number of files to which to export them.
5620 Then we define two block agenda commands and specify filenames for them
5621 as well. File names can be relative to the current working directory,
5626 (setq org-agenda-custom-commands
5627 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
5628 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
5629 ("h" "Agenda and Home-related tasks"
5634 ("~/views/home.html"))
5635 ("o" "Agenda and Office-related tasks"
5640 ("~/views/office.ps"))))
5644 The extension of the file name determines the type of export. If it is
5645 @file{.html}, Org-mode will use the @file{htmlize.el} package to convert
5646 the buffer to HTML and save it to this file name. If the extension is
5647 @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
5648 postscript output. Any other extension produces a plain ASCII file.
5650 The export files are @emph{not} created when you use one of those
5651 commands interactively. Instead, there is a special command to produce
5652 @emph{all} specified files in one step:
5657 Export all agenda views that have export filenames associated with
5661 You can use the options section of the custom agenda commands to also
5662 set options for the export commands. For example:
5665 (setq org-agenda-custom-commands
5667 ((ps-number-of-columns 2)
5668 (ps-landscape-mode t)
5669 (org-agenda-prefix-format " [ ] ")
5670 (org-agenda-with-colors nil)
5671 (org-agenda-remove-tags t))
5676 This command sets two options for the postscript exporter, to make it
5677 print in two columns in landscape format - the resulting page can be cut
5678 in two and then used in a paper agenda. The remaining settings modify
5679 the agenda prefix to omit category and scheduling information, and
5680 instead include a checkbox to check off items. We also remove the tags
5681 to make the lines compact, and we don't want to use colors for the
5682 black-and-white printer. Settings specified in
5683 @code{org-agenda-exporter-settings} will also apply, but the settings
5684 in @code{org-agenda-custom-commands} take precedence.
5687 From the command line you may also use
5689 emacs -f org-batch-store-agenda-views -kill
5692 or, if you need to modify some parameters
5694 emacs -eval '(org-batch-store-agenda-views \
5695 org-agenda-ndays 30 \
5696 org-agenda-start-day "2007-11-01" \
5697 org-agenda-include-diary nil \
5698 org-agenda-files (quote ("~/org/project.org")))' \
5702 which will create the agenda views restricted to the file
5703 @file{~/org/project.org}, without diary entries and with 30 days
5706 @node Extracting Agenda Information for other programs, , Exporting Agenda Views, Custom agenda views
5707 @subsection Extracting Agenda Information for other programs
5708 @cindex agenda, pipe
5709 @cindex Scripts, for agenda processing
5711 Org-mode provides commands to access agenda information for the command
5712 line in emacs batch mode. This extracted information can be sent
5713 directly to a printer, or it can be read by a program that does further
5714 processing of the data. The first of these commands is the function
5715 @code{org-batch-agenda}, that produces an agenda view and sends it as
5716 ASCII text to STDOUT. The command takes a single string as parameter.
5717 If the string has length 1, it is used as a key to one of the commands
5718 you have configured in @code{org-agenda-custom-commands}, basically any
5719 key you can use after @kbd{C-c a}. For example, to directly print the
5720 current TODO list, you could use
5723 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
5726 If the parameter is a string with 2 or more characters, it is used as a
5727 tags/todo match string. For example, to print your local shopping list
5728 (all items with the tag @samp{shop}, but excluding the tag
5729 @samp{NewYork}), you could use
5732 emacs -batch -l ~/.emacs \
5733 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
5737 You may also modify parameters on the fly like this:
5740 emacs -batch -l ~/.emacs \
5741 -eval '(org-batch-agenda "a" \
5742 org-agenda-ndays 30 \
5743 org-agenda-include-diary nil \
5744 org-agenda-files (quote ("~/org/project.org")))' \
5749 which will produce a 30 day agenda, fully restricted to the Org file
5750 @file{~/org/projects.org}, not even including the diary.
5752 If you want to process the agenda data in more sophisticated ways, you
5753 can use the command @code{org-batch-agenda-csv} to get a comma-separated
5754 list of values for each agenda item. Each line in the output will
5755 contain a number of fields separated by commas. The fields in a line
5759 category @r{The category of the item}
5760 head @r{The headline, without TODO kwd, TAGS and PRIORITY}
5761 type @r{The type of the agenda entry, can be}
5762 todo @r{selected in TODO match}
5763 tagsmatch @r{selected in tags match}
5764 diary @r{imported from diary}
5765 deadline @r{a deadline}
5766 scheduled @r{scheduled}
5767 timestamp @r{appointment, selected by timestamp}
5768 closed @r{entry was closed on date}
5769 upcoming-deadline @r{warning about nearing deadline}
5770 past-scheduled @r{forwarded scheduled item}
5771 block @r{entry has date block including date}
5772 todo @r{The todo keyword, if any}
5773 tags @r{All tags including inherited ones, separated by colons}
5774 date @r{The relevant date, like 2007-2-14}
5775 time @r{The time, like 15:00-16:50}
5776 extra @r{String with extra planning info}
5777 priority-l @r{The priority letter if any was given}
5778 priority-n @r{The computed numerical priority}
5782 Time and date will only be given if a timestamp (or deadline/scheduled)
5783 lead to the selection of the item.
5785 A CSV list like this is very easy to use in a post processing script.
5786 For example, here is a Perl program that gets the TODO list from
5787 Emacs/org-mode and prints all the items, preceded by a checkbox:
5793 # define the Emacs command to run
5794 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
5796 # run it and capture the output
5797 $agenda = qx@{$cmd 2>/dev/null@};
5799 # loop over all lines
5800 foreach $line (split(/\n/,$agenda)) @{
5802 # get the individual values
5803 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
5804 $priority_l,$priority_n) = split(/,/,$line);
5806 # proccess and print
5807 print "[ ] $head\n";
5812 @node Embedded LaTeX, Exporting, Agenda views, Top
5813 @chapter Embedded LaTeX
5814 @cindex @TeX{} interpretation
5815 @cindex La@TeX{} interpretation
5817 Plain ASCII is normally sufficient for almost all note taking. One
5818 exception, however, are scientific notes which need to be able to
5819 contain mathematical symbols and the occasional formula.
5820 La@TeX{}@footnote{La@TeX{} is a macro system based on Donald E. Knuth's
5821 @TeX{} system. Many of the features described here as ``La@TeX{}'' are
5822 really from @TeX{}, but for simplicity I am blurring this distinction.}
5823 is widely used to typeset scientific documents. Org-mode supports
5824 embedding La@TeX{} code into its files, because many academics are used
5825 to read La@TeX{} source code, and because it can be readily processed
5826 into images for HTML production.
5828 It is not necessary to mark La@TeX{} macros and code in any special way.
5829 If you observe a few conventions, Org-mode knows how to find it and what
5833 * Math symbols:: TeX macros for symbols and Greek letters
5834 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
5835 * LaTeX fragments:: Complex formulas made easy
5836 * Processing LaTeX fragments:: Previewing LaTeX processing
5837 * CDLaTeX mode:: Speed up entering of formulas
5840 @node Math symbols, Subscripts and Superscripts, Embedded LaTeX, Embedded LaTeX
5841 @section Math symbols
5842 @cindex math symbols
5845 You can use La@TeX{} macros to insert special symbols like @samp{\alpha}
5846 to indicate the Greek letter, or @samp{\to} to indicate an arrow.
5847 Completion for these macros is available, just type @samp{\} and maybe a
5848 few letters, and press @kbd{M-@key{TAB}} to see possible completions.
5849 Unlike La@TeX{} code, Org-mode allows these macros to be present
5850 without surrounding math delimiters, for example:
5853 Angles are written as Greek letters \alpha, \beta and \gamma.
5856 During HTML export (@pxref{HTML export}), these symbols are translated
5857 into the proper syntax for HTML, for the above examples this is
5858 @samp{α} and @samp{→}, respectively.
5860 @node Subscripts and Superscripts, LaTeX fragments, Math symbols, Embedded LaTeX
5861 @section Subscripts and Superscripts
5865 Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super-
5866 and subscripts. Again, these can be used without embedding them in
5867 math-mode delimiters. To increase the readability of ASCII text, it is
5868 not necessary (but OK) to surround multi-character sub- and superscripts
5869 with curly braces. For example
5872 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
5873 the sun is R_@{sun@} = 6.96 x 10^8 m.
5876 To avoid interpretation as raised or lowered text, you can quote
5877 @samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}.
5879 During HTML export (@pxref{HTML export}), subscript and superscripts
5880 are surrounded with @code{<sub>} and @code{<sup>} tags, respectively.
5882 @node LaTeX fragments, Processing LaTeX fragments, Subscripts and Superscripts, Embedded LaTeX
5883 @section LaTeX fragments
5884 @cindex LaTeX fragments
5886 With symbols, sub- and superscripts, HTML is pretty much at its end when
5887 it comes to representing mathematical formulas@footnote{Yes, there is
5888 MathML, but that is not yet fully supported by many browsers, and there
5889 is no decent converter for turning La@TeX{} or ASCII representations of
5890 formulas into MathML. So for the time being, converting formulas into
5891 images seems the way to go.}. More complex expressions need a dedicated
5892 formula processor. To this end, Org-mode can contain arbitrary La@TeX{}
5893 fragments. It provides commands to preview the typeset result of these
5894 fragments, and upon export to HTML, all fragments will be converted to
5895 images and inlined into the HTML document@footnote{The La@TeX{} export
5896 will not use images for displaying La@TeX{} fragments but include these
5897 fragments directly into the La@TeX{} code.}. For this to work you
5898 need to be on a system with a working La@TeX{} installation. You also
5899 need the @file{dvipng} program, available at
5900 @url{http://sourceforge.net/projects/dvipng/}. The La@TeX{} header that
5901 will be used when processing a fragment can be configured with the
5902 variable @code{org-format-latex-header}.
5904 La@TeX{} fragments don't need any special marking at all. The following
5905 snippets will be identified as La@TeX{} source code:
5908 Environments of any kind. The only requirement is that the
5909 @code{\begin} statement appears on a new line, preceded by only
5912 Text within the usual La@TeX{} math delimiters. To avoid conflicts with
5913 currency specifications, single @samp{$} characters are only recognized
5914 as math delimiters if the enclosed text contains at most two line breaks,
5915 is directly attached to the @samp{$} characters with no whitespace in
5916 between, and if the closing @samp{$} is followed by whitespace or
5917 punctuation. For the other delimiters, there is no such restriction, so
5918 when in doubt, use @samp{\(...\)} as inline math delimiters.
5921 @noindent For example:
5924 \begin@{equation@} % arbitrary environments,
5925 x=\sqrt@{b@} % even tables, figures
5926 \end@{equation@} % etc
5928 If $a^2=b$ and \( b=2 \), then the solution must be
5929 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
5933 If you need any of the delimiter ASCII sequences for other purposes, you
5934 can configure the option @code{org-format-latex-options} to deselect the
5935 ones you do not wish to have interpreted by the La@TeX{} converter.
5937 @node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
5938 @section Processing LaTeX fragments
5939 @cindex LaTeX fragments, preview
5941 La@TeX{} fragments can be processed to produce a preview images of the
5942 typeset expressions:
5947 Produce a preview image of the La@TeX{} fragment at point and overlay it
5948 over the source code. If there is no fragment at point, process all
5949 fragments in the current entry (between two headlines). When called
5950 with a prefix argument, process the entire subtree. When called with
5951 two prefix arguments, or when the cursor is before the first headline,
5952 process the entire buffer.
5955 Remove the overlay preview images.
5958 During HTML export (@pxref{HTML export}), all La@TeX{} fragments are
5959 converted into images and inlined into the document if the following
5963 (setq org-export-with-LaTeX-fragments t)
5966 @node CDLaTeX mode, , Processing LaTeX fragments, Embedded LaTeX
5967 @section Using CDLaTeX to enter math
5970 CDLaTeX-mode is a minor mode that is normally used in combination with a
5971 major La@TeX{} mode like AUCTeX in order to speed-up insertion of
5972 environments and math templates. Inside Org-mode, you can make use of
5973 some of the features of cdlatex-mode. You need to install
5974 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
5975 AUCTeX) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
5976 Don't turn cdlatex-mode itself under Org-mode, but use the light
5977 version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it
5978 on for the current buffer with @code{M-x org-cdlatex-mode}, or for all
5982 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
5985 When this mode is enabled, the following features are present (for more
5986 details see the documentation of cdlatex-mode):
5990 Environment templates can be inserted with @kbd{C-c @{}.
5993 The @key{TAB} key will do template expansion if the cursor is inside a
5994 La@TeX{} fragment@footnote{Org-mode has a method to test if the cursor is
5995 inside such a fragment, see the documentation of the function
5996 @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
5997 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
5998 correctly inside the first brace. Another @key{TAB} will get you into
5999 the second brace. Even outside fragments, @key{TAB} will expand
6000 environment abbreviations at the beginning of a line. For example, if
6001 you write @samp{equ} at the beginning of a line and press @key{TAB},
6002 this abbreviation will be expanded to an @code{equation} environment.
6003 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
6007 Pressing @kbd{_} and @kbd{^} inside a La@TeX{} fragment will insert these
6008 characters together with a pair of braces. If you use @key{TAB} to move
6009 out of the braces, and if the braces surround only a single character or
6010 macro, they are removed again (depending on the variable
6011 @code{cdlatex-simplify-sub-super-scripts}).
6014 Pressing the backquote @kbd{`} followed by a character inserts math
6015 macros, also outside La@TeX{} fragments. If you wait more than 1.5 seconds
6016 after the backquote, a help window will pop up.
6019 Pressing the normal quote @kbd{'} followed by another character modifies
6020 the symbol before point with an accent or a font. If you wait more than
6021 1.5 seconds after the backquote, a help window will pop up. Character
6022 modification will work only inside La@TeX{} fragments, outside the quote
6026 @node Exporting, Publishing, Embedded LaTeX, Top
6030 Org-mode documents can be exported into a variety of other formats. For
6031 printing and sharing of notes, ASCII export produces a readable and
6032 simple version of an Org-mode file. HTML export allows you to publish a
6033 notes file on the web, while the XOXO format provides a solid base for
6034 exchange with a broad range of other applications. La@TeX{} export lets
6035 you use Org-mode and its structured editing functions to easily create
6036 La@TeX{} files. To incorporate entries with associated times like
6037 deadlines or appointments into a desktop calendar program like iCal,
6038 Org-mode can also produce extracts in the iCalendar format. Currently
6039 Org-mode only supports export, not import of these different formats.
6041 When exporting, Org-mode uses special conventions to enrich the output
6042 produced. @xref{Text interpretation}, for more details.
6047 Dispatcher for export and publishing commands. Displays a help-window
6048 listing the additional key(s) needed to launch an export or publishing
6053 * ASCII export:: Exporting to plain ASCII
6054 * HTML export:: Exporting to HTML
6055 * LaTeX export:: Exporting to LaTeX
6056 * XOXO export:: Exporting to XOXO
6057 * iCalendar export:: Exporting in iCalendar format
6058 * Text interpretation:: How the exporter looks at the file
6061 @node ASCII export, HTML export, Exporting, Exporting
6062 @section ASCII export
6063 @cindex ASCII export
6065 ASCII export produces a simple and very readable version of an Org-mode
6068 @cindex region, active
6069 @cindex active region
6070 @cindex transient-mark-mode
6074 Export as ASCII file. For an org file @file{myfile.org}, the ASCII file
6075 will be @file{myfile.txt}. The file will be overwritten without
6076 warning. If there is an active region, only the region will be
6077 exported. If the selected region is a single tree, the tree head will
6078 become the document title. If the tree head entry has or inherits an
6079 EXPORT_FILE_NAME property, that name will be used for the export.
6082 Export only the visible part of the document.
6085 @cindex headline levels, for exporting
6086 In the exported version, the first 3 outline levels will become
6087 headlines, defining a general document structure. Additional levels
6088 will be exported as itemized lists. If you want that transition to occur
6089 at a different level, specify it with a prefix argument. For example,
6096 creates only top level headlines and does the rest as items. When
6097 headlines are converted to items, the indentation of the text following
6098 the headline is changed to fit nicely under the item. This is done with
6099 the assumption that the first bodyline indicates the base indentation of
6100 the body text. Any indentation larger than this is adjusted to preserve
6101 the layout relative to the first line. Should there be lines with less
6102 indentation than the first, these are left alone.
6104 @node HTML export, LaTeX export, ASCII export, Exporting
6105 @section HTML export
6108 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
6109 HTML formatting, in ways similar to John Grubers @emph{markdown}
6110 language, but with additional support for tables.
6113 * HTML Export commands:: How to invoke LaTeX export
6114 * Quoting HTML tags:: Using direct HTML in Org-mode
6115 * Links:: Transformation of links for HTML
6116 * Images:: How to include images
6117 * CSS support:: Changing the appearence of the output
6120 @node HTML Export commands, Quoting HTML tags, HTML export, HTML export
6121 @subsection HTML export commands
6123 @cindex region, active
6124 @cindex active region
6125 @cindex transient-mark-mode
6129 Export as HTML file @file{myfile.html}. For an org file
6130 @file{myfile.org}, the ASCII file will be @file{myfile.html}. The file
6131 will be overwritten without warning. If there is an active region, only
6132 the region will be exported. If the selected region is a single tree,
6133 the tree head will become the document title. If the tree head entry
6134 has or inherits an EXPORT_FILE_NAME property, that name will be used for
6138 Export as HTML file and immediately open it with a browser.
6141 Export to a temporary buffer, do not create a file.
6144 Export the active region to a temporary buffer. With prefix arg, do not
6145 produce file header and foot, but just the plain HTML section for the
6146 region. This is good for cut-and-paste operations.
6155 Export only the visible part of the document.
6156 @item M-x org-export-region-as-html
6157 Convert the region to HTML under the assumption that it was org-mode
6158 syntax before. This is a global command that can be invoked in any
6160 @item M-x org-replace-region-by-HTML
6161 Replace the active region (assumed to be in Org-mode syntax) by HTML
6165 @cindex headline levels, for exporting
6166 In the exported version, the first 3 outline levels will become
6167 headlines, defining a general document structure. Additional levels
6168 will be exported as itemized lists. If you want that transition to occur
6169 at a different level, specify it with a prefix argument. For example,
6176 creates two levels of headings and does the rest as items.
6178 @node Quoting HTML tags, Links, HTML Export commands, HTML export
6179 @subsection Quoting HTML tags
6181 Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
6182 @samp{>} in HTML export. If you want to include simple HTML tags
6183 which should be interpreted as such, mark them with @samp{@@} as in
6184 @samp{@@<b>bold text@@</b>}. Note that this really works only for
6185 simple tags. For more extensive HTML that should be copied verbatim to
6186 the exported file use either
6189 #+HTML: Literal HTML code for export
6196 All lines between these markers are exported literally
6201 @node Links, Images, Quoting HTML tags, HTML export
6204 @cindex links, in HTML export
6205 @cindex internal links, in HTML export
6206 @cindex external links, in HTML export
6207 Internal links (@pxref{Internal links}) will continue to work in HTML
6208 files only if they match a dedicated @samp{<<target>>}. Automatic links
6209 created by radio targets (@pxref{Radio targets}) will also work in the
6210 HTML file. Links to external files will still work if the HTML file is
6211 in the same directory as the Org-mode file. Links to other @file{.org}
6212 files will be translated into HTML links under the assumption that an
6213 HTML version also exists of the linked file. For information related to
6214 linking files while publishing them to a publishing directory see
6215 @ref{Publishing links}.
6217 @node Images, CSS support, Links, HTML export
6220 @cindex images, inline in HTML
6221 @cindex inlining images in HTML
6222 HTML export can inline images given as links in the Org-mode file, and
6223 it can make an image the clickable part of a link. By
6224 default@footnote{but see the variable
6225 @code{org-export-html-inline-images}}, images are inlined if a link does
6226 not have a description. So @samp{[[file:myimg.jpg]]} will be inlined,
6227 while @samp{[[file:myimg.jpg][the image]]} will just produce a link
6228 @samp{the image} that points to the image. If the description part
6229 itself is a @code{file:} link or a @code{http:} URL pointing to an
6230 image, this image will be inlined and activated so that clicking on the
6231 image will activate the link. For example, to include a thumbnail that
6232 will link to a high resolution version of the image, you could use:
6235 [[file:highres.jpg][file:thumb.jpg]]
6239 and you could use @code{http} addresses just as well.
6241 @node CSS support, , Images, HTML export
6242 @subsection CSS support
6244 You can also give style information for the exported file. The HTML
6245 exporter assigns the following CSS classes to appropriate parts of the
6246 document - your style specifications may change these:
6248 .todo @r{TODO keywords}
6249 .done @r{the DONE keyword}
6250 .timestamp @r{time stamp}
6251 .timestamp-kwd @r{keyword associated with a time stamp, like SCHEDULED}
6252 .tag @r{tag in a headline}
6253 .target @r{target for links}
6256 The default style specification can be configured through the option
6257 @code{org-export-html-style}. If you want to use a file-local style,
6258 you may use file variables, best wrapped into a COMMENT section at the
6259 end of the outline tree. For example@footnote{Under Emacs 21, the
6260 continuation lines for a variable value should have no @samp{#} at the
6261 start of the line.}:
6264 * COMMENT html style specifications
6267 # org-export-html-style: " <style type=\"text/css\">
6268 # p @{font-weight: normal; color: gray; @}
6269 # h1 @{color: black; @}
6274 Remember to execute @kbd{M-x normal-mode} after changing this to make
6275 the new style visible to Emacs. This command restarts org-mode for the
6276 current buffer and forces Emacs to re-evaluate the local variables
6277 section in the buffer.
6279 @c FIXME: More about header and footer styles
6280 @c FIXME: Talk about links and targets.
6282 @node LaTeX export, XOXO export, HTML export, Exporting
6283 @section LaTeX export
6284 @cindex LaTeX export
6286 Org-mode contains a La@TeX{} exporter written by Bastien Guerry.
6289 * LaTeX export commands:: How to invoke LaTeX export
6290 * Quoting LaTeX code:: Incorporating literal LaTeX code
6291 * Sectioning structure::
6294 @node LaTeX export commands, Quoting LaTeX code, LaTeX export, LaTeX export
6295 @subsection LaTeX export commands
6300 Export as La@TeX{} file @file{myfile.tex}.
6303 Export to a temporary buffer, do not create a file.
6308 Export only the visible part of the document.
6309 @item M-x org-export-region-as-latex
6310 Convert the region to La@TeX{} under the assumption that it was org-mode
6311 syntax before. This is a global command that can be invoked in any
6313 @item M-x org-replace-region-by-latex
6314 Replace the active region (assumed to be in Org-mode syntax) by La@TeX{}
6318 @cindex headline levels, for exporting
6319 In the exported version, the first 3 outline levels will become
6320 headlines, defining a general document structure. Additional levels
6321 will be exported as description lists. The exporter can ignore them or
6322 convert them to a custom string depending on
6323 @code{org-latex-low-levels}.
6325 If you want that transition to occur at a different level, specify it
6326 with a prefix argument. For example,
6333 creates two levels of headings and does the rest as items.
6335 @node Quoting LaTeX code, Sectioning structure, LaTeX export commands, LaTeX export
6336 @subsection Quoting LaTeX code
6338 Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly
6339 inserted into the La@TeX{} file. Forthermore, you can add special code
6340 that should only be present in La@TeX{} export with the following
6344 #+LaTeX: Literal LaTeX code for export
6351 All lines between these markers are exported literally
6357 @node Sectioning structure, , Quoting LaTeX code, LaTeX export
6358 @subsection Sectioning structure
6360 @cindex LaTeX sectioning structure
6362 By default, the La@TeX{} output uses the class @code{article}.
6364 You can change this globally by setting a different value for
6365 @code{org-export-latex-default-class} or locally by adding an option
6366 like @code{#+LaTeX_CLASS: myclass} in your file. The class should be
6367 listed in @code{org-export-latex-classes}, where you can also define the
6368 sectioning structure for each class.
6371 @node XOXO export, iCalendar export, LaTeX export, Exporting
6372 @section XOXO export
6375 Org-mode contains an exporter that produces XOXO-style output.
6376 Currently, this exporter only handles the general outline structure and
6377 does not interpret any additional Org-mode features.
6382 Export as XOXO file @file{myfile.html}.
6385 Export only the visible part of the document.
6388 @node iCalendar export, Text interpretation, XOXO export, Exporting
6389 @section iCalendar export
6390 @cindex iCalendar export
6392 Some people like to use Org-mode for keeping track of projects, but
6393 still prefer a standard calendar application for anniversaries and
6394 appointments. In this case it can be useful to have deadlines and
6395 other time-stamped items in Org-mode files show up in the calendar
6396 application. Org-mode can export calendar information in the standard
6397 iCalendar format. If you also want to have TODO entries included in the
6398 export, configure the variable @code{org-icalendar-include-todo}.
6403 Create iCalendar entries for the current file and store them in the same
6404 directory, using a file extension @file{.ics}.
6407 Like @kbd{C-c C-e i}, but do this for all files in
6408 @code{org-agenda-files}. For each of these files, a separate iCalendar
6409 file will be written.
6412 Create a single large iCalendar file from all files in
6413 @code{org-agenda-files} and write it to the file given by
6414 @code{org-combined-agenda-icalendar-file}.
6417 The export will honor SUMMARY, DESCRIPTION and LOCATION properties if
6418 the selected entries have them. If not, the summary will be derived
6419 from the headline, and the description from the body (limited to
6420 @code{org-icalendar-include-body} characters).
6422 How this calendar is best read and updated, depends on the application
6423 you are using. The FAQ covers this issue.
6426 @node Text interpretation, , iCalendar export, Exporting
6427 @section Text interpretation by the exporter
6429 The exporter backends interpret additional structure in the Org-mode file
6430 in order to produce better output.
6433 * Comment lines:: Some lines will not be exported
6434 * Initial text:: Text before the first headline
6435 * Footnotes:: Numbers like [1]
6436 * Quoted examples:: Inserting quoted chnuks of text
6437 * Enhancing text:: Subscripts, symbols and more
6438 * Export options:: How to influence the export settings
6441 @node Comment lines, Initial text, Text interpretation, Text interpretation
6442 @subsection Comment lines
6443 @cindex comment lines
6444 @cindex exporting, not
6446 Lines starting with @samp{#} in column zero are treated as comments
6447 and will never be exported. Also entire subtrees starting with the
6448 word @samp{COMMENT} will never be exported.
6453 Toggle the COMMENT keyword at the beginning of an entry.
6456 @node Initial text, Footnotes, Comment lines, Text interpretation
6457 @subsection Text before the first headline
6459 Org-mode normally ignores any text before the first headline when
6460 exporting, leaving this region for internal links to speed up navigation
6461 etc. However, in publishing-oriented files, you might want to have some
6462 text before the first headline, like a small introduction, special HTML
6463 code with a navigation bar, etc. You can ask to have this part of the
6464 file exported as well by setting the variable
6465 @code{org-export-skip-text-before-1st-heading} to @code{nil}. On a
6466 per-file basis, you can get the same effect with
6472 The text before the first headline will be fully processed
6473 (@pxref{Enhancing text}), and the first non-comment line becomes the
6474 title of the exported document. If you need to include literal HTML,
6475 use the special constructs described in @ref{Quoting HTML tags}. The
6476 table of contents is normally inserted directly before the first
6477 headline of the file. If you would like to get it to a different
6478 location, insert the string @code{[TABLE-OF-CONTENTS]} on a line by
6479 itself at the desired location.
6481 Finally, if you want to use the space before the first headline for
6482 internal purposes, but @emph{still} want to place something before the
6483 first headline when exporting the file, you can use the @code{#+TEXT}
6488 #+TEXT: This text will go before the *first* headline.
6489 #+TEXT: We place the table of contents here:
6490 #+TEXT: [TABLE-OF-CONTENTS]
6491 #+TEXT: This goes between the table of contents and the first headline
6494 @node Footnotes, Quoted examples, Initial text, Text interpretation
6495 @subsection Footnotes
6497 @cindex @file{footnote.el}
6499 Numbers in square brackets are treated as footnotes, so that you can use
6500 the Emacs package @file{footnote.el} to create footnotes. For example:
6503 The org-mode homepage[1] clearly needs help from
6504 a good web designer.
6506 [1] The link is: http://orgmode.org
6511 Note that the @file{footnote} package uses @kbd{C-c !} to invoke its
6512 commands. This binding conflicts with the org-mode command for
6513 inserting inactive time stamps. You could use the variable
6514 @code{footnote-prefix} to switch footnotes commands to another key. Or,
6515 if you are too used to this binding, you could use
6516 @code{org-replace-disputed-keys} and @code{org-disputed-keys} to change
6517 the settings in Org-mode.
6519 @node Quoted examples, Enhancing text, Footnotes, Text interpretation
6520 @subsection Quoted examples
6521 @cindex quoted examples
6522 @cindex examples, quoted
6523 @cindex text, fixed width
6524 @cindex fixed width text
6526 When writing technical documents, you often need to insert examples that
6527 are not further interpreted by Org-mode. For historical reasons, there
6528 are several ways to do this:
6532 If a headline starts with the word @samp{QUOTE}, the text below the
6533 headline will be typeset as fixed-width, to allow quoting of computer
6536 Lines starting with @samp{:} are also typeset in fixed-width font.
6540 Toggle fixed-width for entry (QUOTE) or region, see below.
6543 Finally, text between
6549 will also be exported in this way.
6553 @node Enhancing text, Export options, Quoted examples, Text interpretation
6554 @subsection Enhancing text for export
6555 @cindex enhancing text
6558 Some of the export backends of Org-mode allow for sophisticated text
6559 formatting, this is true in particular for the HTML and La@TeX{}
6560 backends. Org-mode has a number of typing conventions that allow to
6561 produce a richly formatted output.
6565 @cindex hand-formatted lists
6566 @cindex lists, hand-formatted
6568 Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.}
6569 or @samp{2)} as enumerator will be recognized and transformed if the
6570 backend supports lists. See @xref{Plain lists}.
6572 @cindex underlined text
6575 @cindex verbatim text
6577 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
6578 and @code{~verbatim~}, and, if you must, @samp{+strikethrough+}. Text
6579 in the code and verbatim string is not processed for org-mode specific
6580 syntax, it is exported verbatim.
6582 @cindex horizontal rules, in exported files
6584 A line consisting of only dashes, and at least 5 of them, will be
6585 exported as a horizontal line (@samp{<hr/>} in HTML).
6587 @cindex LaTeX fragments, export
6588 @cindex TeX macros, export
6590 Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML
6591 entities or images (@pxref{Embedded LaTeX}).
6593 @cindex tables, export
6595 Tables are transformed into native tables under the exporter, if the
6596 export backend supports this. Data fields before the first horizontal
6597 separator line will be formatted as table header fields.
6601 If a headline starts with the word @samp{QUOTE}, the text below the
6602 headline will be typeset as fixed-width, to allow quoting of computer
6603 codes etc. Lines starting with @samp{:} are also typeset in fixed-width
6608 Toggle fixed-width for entry (QUOTE) or region, see below.
6610 Finally, text between
6616 will also be exported in this way.
6618 @cindex linebreak, forced
6620 A double backslash @emph{at the end of a line} enforces a line break at
6623 @cindex HTML entities, LaTeX entities
6625 Strings like @code{\alpha} will be exported as @code{α}, in the
6626 HTML output. These strings are exported as @code{$\alpha$} in the
6627 La@TeX{} output. Similarly, @code{\nbsp} will become @code{ } in
6628 HTML and in La@TeX{}. This applies for a long list of entities, see
6629 the variable @code{org-html-entities} for the complete list.
6633 If these conversions conflict with your habits of typing ASCII text,
6634 they can all be turned off with corresponding variables. See the
6635 customization group @code{org-export-general}, and the following section
6636 which explains how to set export options with special lines in a
6640 @node Export options, , Enhancing text, Text interpretation
6641 @subsection Export options
6642 @cindex options, for export
6644 @cindex completion, of option keywords
6645 The exporter recognizes special lines in the buffer which provide
6646 additional information. These lines may be put anywhere in the file.
6647 The whole set of lines can be inserted into the buffer with @kbd{C-c
6648 C-e t}. For individual lines, a good way to make sure the keyword is
6649 correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
6650 (@pxref{Completion}).
6655 Insert template with export options, see example below.
6659 #+TITLE: the title to be shown (default is the buffer name)
6660 #+AUTHOR: the author (default taken from @code{user-full-name})
6661 #+DATE: A date, fixed, of a format string for @code{format-time-string}
6662 #+EMAIL: his/her email address (default from @code{user-mail-address})
6663 #+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language})
6664 #+TEXT: Some descriptive text to be inserted at the beginning.
6665 #+TEXT: Several lines may be given.
6666 #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
6670 The OPTIONS line is a compact form to specify export settings. Here
6672 @cindex headline levels
6673 @cindex section-numbers
6674 @cindex table of contents
6675 @cindex linebreak preservation
6676 @cindex quoted HTML tags
6677 @cindex fixed-width sections
6679 @cindex @TeX{}-like syntax for sub- and superscripts
6681 @cindex special strings
6682 @cindex emphasized text
6683 @cindex @TeX{} macros
6684 @cindex La@TeX{} fragments
6685 @cindex author info, in export
6686 @cindex time info, in export
6688 H: @r{set the number of headline levels for export}
6689 num: @r{turn on/off section-numbers}
6690 toc: @r{turn on/off table of contents, or set level limit (integer)}
6691 \n: @r{turn on/off linebreak-preservation}
6692 @@: @r{turn on/off quoted HTML tags}
6693 :: @r{turn on/off fixed-width sections}
6694 |: @r{turn on/off tables}
6695 ^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If}
6696 @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but}
6697 @r{the simple @code{a_b} will be left as it is.}
6698 -: @r{turn on/off conversion of special strings.}
6699 f: @r{turn on/off foototes like this[1].}
6700 *: @r{turn on/off emphasized text (bold, italic, underlined)}
6701 TeX: @r{turn on/off simple @TeX{} macros in plain text}
6702 LaTeX: @r{turn on/off La@TeX{} fragments}
6703 skip: @r{turn on/off skipping the text before the first heading}
6704 author: @r{turn on/off inclusion of author name/email into exported file}
6705 timestamp: @r{turn on/off inclusion creation time into exported file}
6706 d: @r{turn on/off inclusion of drawers}
6709 These options take effect in both the HTML and La@TeX{} export, except
6710 for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and
6711 @code{nil} for the La@TeX{} export.
6713 @node Publishing, Miscellaneous, Exporting, Top
6717 Org-mode includes@footnote{@file{org-publish.el} is not distributed with
6718 Emacs 21, if you are still using Emacs 21, you need you need to download
6719 this file separately.} a publishing management system that allows you to
6720 configure automatic HTML conversion of @emph{projects} composed of
6721 interlinked org files. This system is called @emph{org-publish}. You can
6722 also configure org-publish to automatically upload your exported HTML
6723 pages and related attachments, such as images and source code files, to
6724 a web server. Org-publish turns org-mode into a web-site authoring tool.
6726 You can also use Org-publish to convert files into La@TeX{}, or even
6727 combine HTML and La@TeX{} conversion so that files are available in both
6728 formats on the server@footnote{Since La@TeX{} files on a server are not
6729 that helpful, you surely want to perform further conversion on them --
6730 e.g. convert them to @code{PDF} format.}.
6732 Org-publish has been contributed to Org-mode by David O'Toole.
6735 * Configuration:: Defining projects
6736 * Sample configuration:: Example projects
6737 * Triggering publication:: Publication commands
6740 @node Configuration, Sample configuration, Publishing, Publishing
6741 @section Configuration
6743 Publishing needs significant configuration to specify files, destination
6744 and many other properties of a project.
6747 * Project alist:: The central configuration variable
6748 * Sources and destinations:: From here to there
6749 * Selecting files:: What files are part of the project?
6750 * Publishing action:: Setting the function doing the publishing
6751 * Publishing options:: Tweaking HTML export
6752 * Publishing links:: Which links keep working after publishing?
6753 * Project page index:: Publishing a list of project files
6756 @node Project alist, Sources and destinations, Configuration, Configuration
6757 @subsection The variable @code{org-publish-project-alist}
6758 @cindex org-publish-project-alist
6759 @cindex projects, for publishing
6761 Org-publish is configured almost entirely through setting the value of
6762 one variable, called @code{org-publish-project-alist}.
6763 Each element of the list configures one project, and may be in one of
6764 the two following forms:
6767 ("project-name" :property value :property value ...)
6771 ("project-name" :components ("project-name" "project-name" ...))
6775 In both cases, projects are configured by specifying property values.
6776 A project defines the set of files that will be published, as well as
6777 the publishing configuration to use when publishing those files. When
6778 a project takes the second form listed above, the individual members
6779 of the ``components'' property are taken to be components of the
6780 project, which group together files requiring different publishing
6781 options. When you publish such a ``meta-project'' all the components
6784 @node Sources and destinations, Selecting files, Project alist, Configuration
6785 @subsection Sources and destinations for files
6786 @cindex directories, for publishing
6788 Most properties are optional, but some should always be set. In
6789 particular, org-publish needs to know where to look for source files,
6790 and where to put published files.
6792 @multitable @columnfractions 0.3 0.7
6793 @item @code{:base-directory}
6794 @tab Directory containing publishing source files
6795 @item @code{:publishing-directory}
6796 @tab Directory (possibly remote) where output files will be published.
6797 @item @code{:preparation-function}
6798 @tab Function called before starting publishing process, for example to
6799 run @code{make} for updating files to be published.
6803 @node Selecting files, Publishing action, Sources and destinations, Configuration
6804 @subsection Selecting files
6805 @cindex files, selecting for publishing
6807 By default, all files with extension @file{.org} in the base directory
6808 are considered part of the project. This can be modified by setting the
6810 @multitable @columnfractions 0.25 0.75
6811 @item @code{:base-extension}
6812 @tab Extension (without the dot!) of source files. This actually is a
6815 @item @code{:exclude}
6816 @tab Regular expression to match file names that should not be
6817 published, even though they have been selected on the basis of their
6820 @item @code{:include}
6821 @tab List of files to be included regardless of @code{:base-extension}
6822 and @code{:exclude}.
6825 @node Publishing action, Publishing options, Selecting files, Configuration
6826 @subsection Publishing Action
6827 @cindex action, for publishing
6829 Publishing means that a file is copied to the destination directory and
6830 possibly transformed in the process. The default transformation is to
6831 export Org-mode files as HTML files, and this is done by the function
6832 @code{org-publish-org-to-html} which calls the HTML exporter
6833 (@pxref{HTML export}). But you also can publish your files in La@TeX{} by
6834 using the function @code{org-publish-org-to-latex} instead. Other files
6835 like images only need to be copied to the publishing destination. For
6836 non-Org-mode files, you need to specify the publishing function.
6839 @multitable @columnfractions 0.3 0.7
6840 @item @code{:publishing-function}
6841 @tab Function executing the publication of a file. This may also be a
6842 list of functions, which will all be called in turn.
6845 The function must accept two arguments: a property list containing at
6846 least a @code{:publishing-directory} property, and the name of the file
6847 to be published. It should take the specified file, make the necessary
6848 transformation (if any) and place the result into the destination folder.
6849 You can write your own publishing function, but @code{org-publish}
6850 provides one for attachments (files that only need to be copied):
6851 @code{org-publish-attachment}.
6853 @node Publishing options, Publishing links, Publishing action, Configuration
6854 @subsection Options for the HTML/LaTeX exporters
6855 @cindex options, for publishing
6857 The property list can be used to set many export options for the HTML
6858 and La@TeX{} exporters. In most cases, these properties correspond to user
6859 variables in Org-mode. The table below lists these properties along
6860 with the variable they belong to. See the documentation string for the
6861 respective variable for details.
6863 @multitable @columnfractions 0.3 0.7
6864 @item @code{:language} @tab @code{org-export-default-language}
6865 @item @code{:headline-levels} @tab @code{org-export-headline-levels}
6866 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
6867 @item @code{:table-of-contents} @tab @code{org-export-with-toc}
6868 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
6869 @item @code{:emphasize} @tab @code{org-export-with-emphasize}
6870 @item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts}
6871 @item @code{:special-strings} @tab @code{org-export-with-special-strings}
6872 @item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}
6873 @item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}
6874 @item @code{:fixed-width} @tab @code{org-export-with-fixed-width}
6875 @item @code{:timestamps} .@tab @code{org-export-with-timestamps}
6876 @item @code{:tags} .@tab @code{org-export-with-tags}
6877 @item @code{:tables} @tab @code{org-export-with-tables}
6878 @item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line}
6879 @item @code{:style} @tab @code{org-export-html-style}
6880 @item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html}
6881 @item @code{:inline-images} @tab @code{org-export-html-inline-images}
6882 @item @code{:expand-quoted-html} @tab @code{org-export-html-expand}
6883 @item @code{:timestamp} @tab @code{org-export-html-with-timestamp}
6884 @item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
6885 @item @code{:preamble} @tab @code{org-export-html-preamble}
6886 @item @code{:postamble} @tab @code{org-export-html-postamble}
6887 @item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble}
6888 @item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble}
6889 @item @code{:author} @tab @code{user-full-name}
6890 @item @code{:email} @tab @code{user-mail-address}
6893 If you use several email addresses, separate them by a semi-column.
6895 Most of the @code{org-export-with-*} variables have the same effect in
6896 both HTML and La@TeX{} exporters, except for @code{:TeX-macros} and
6897 @code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the
6900 When a property is given a value in @code{org-publish-project-alist},
6901 its setting overrides the value of the corresponding user variable (if
6902 any) during publishing. Options set within a file (@pxref{Export
6903 options}), however, override everything.
6905 @node Publishing links, Project page index, Publishing options, Configuration
6906 @subsection Links between published files
6907 @cindex links, publishing
6909 To create a link from one Org-mode file to another, you would use
6910 something like @samp{[[file:foo.org][The foo]]} or simply
6911 @samp{file:foo.org.} (@pxref{Hyperlinks}). Upon publishing this link
6912 becomes a link to @file{foo.html}. In this way, you can interlink the
6913 pages of your "org web" project and the links will work as expected when
6914 you publish them to HTML.
6916 You may also link to related files, such as images. Provided you are
6917 careful with relative pathnames, and provided you have also configured
6918 @code{org-publish} to upload the related files, these links will work
6919 too. @ref{Complex example} for an example of this usage.
6921 Sometime an Org-mode file to be published may contain links that are
6922 only valid in your production environment, but not in the publishing
6923 location. In this case, use the property
6925 @multitable @columnfractions 0.4 0.6
6926 @item @code{:link-validation-function}
6927 @tab Function to validate links
6931 to define a function for checking link validity. This function must
6932 accept two arguments, the file name and a directory relative to which
6933 the file name is interpreted in the production environment. If this
6934 function returns @code{nil}, then the HTML generator will only insert a
6935 description into the HTML file, but no link. One option for this
6936 function is @code{org-publish-validate-link} which checks if the given
6937 file is part of any project in @code{org-publish-project-alist}.
6939 @node Project page index, , Publishing links, Configuration
6940 @subsection Project page index
6941 @cindex index, of published pages
6943 The following properties may be used to control publishing of an
6944 index of files or summary page for a given project.
6946 @multitable @columnfractions 0.25 0.75
6947 @item @code{:auto-index}
6948 @tab When non-nil, publish an index during org-publish-current-project or
6951 @item @code{:index-filename}
6952 @tab Filename for output of index. Defaults to @file{index.org} (which
6953 becomes @file{index.html}).
6955 @item @code{:index-title}
6956 @tab Title of index page. Defaults to name of file.
6958 @item @code{:index-function}
6959 @tab Plugin function to use for generation of index.
6960 Defaults to @code{org-publish-org-index}, which generates a plain list
6961 of links to all files in the project.
6964 @node Sample configuration, Triggering publication, Configuration, Publishing
6965 @section Sample configuration
6967 Below we provide two example configurations. The first one is a simple
6968 project publishing only a set of Org-mode files. The second example is
6969 more complex, with a multi-component project.
6972 * Simple example:: One-component publishing
6973 * Complex example:: A multi-component publishing example
6976 @node Simple example, Complex example, Sample configuration, Sample configuration
6977 @subsection Example: simple publishing configuration
6979 This example publishes a set of Org-mode files to the @file{public_html}
6980 directory on the local machine.
6983 (setq org-publish-project-alist
6985 :base-directory "~/org/"
6986 :publishing-directory "~/public_html"
6987 :section-numbers nil
6988 :table-of-contents nil
6989 :style "<link rel=stylesheet
6990 href=\"../other/mystyle.css\"
6991 type=\"text/css\">")))
6994 @node Complex example, , Simple example, Sample configuration
6995 @subsection Example: complex publishing configuration
6997 This more complicated example publishes an entire website, including
6998 org files converted to HTML, image files, emacs lisp source code, and
6999 stylesheets. The publishing-directory is remote and private files are
7002 To ensure that links are preserved, care should be taken to replicate
7003 your directory structure on the web server, and to use relative file
7004 paths. For example, if your org files are kept in @file{~/org} and your
7005 publishable images in @file{~/images}, you'd link to an image with
7008 file:../images/myimage.png
7011 On the web server, the relative path to the image should be the
7012 same. You can accomplish this by setting up an "images" folder in the
7013 right place on the webserver, and publishing images to it.
7016 (setq org-publish-project-alist
7018 :base-directory "~/org/"
7019 :base-extension "org"
7020 :publishing-directory "/ssh:user@@host:~/html/notebook/"
7021 :publishing-function org-publish-org-to-html
7022 :exclude "PrivatePage.org" ;; regexp
7024 :section-numbers nil
7025 :table-of-contents nil
7026 :style "<link rel=stylesheet
7027 href=\"../other/mystyle.css\" type=\"text/css\">"
7029 :auto-postamble nil)
7032 :base-directory "~/images/"
7033 :base-extension "jpg\\|gif\\|png"
7034 :publishing-directory "/ssh:user@@host:~/html/images/"
7035 :publishing-function org-publish-attachment)
7038 :base-directory "~/other/"
7039 :base-extension "css\\|el"
7040 :publishing-directory "/ssh:user@@host:~/html/other/"
7041 :publishing-function org-publish-attachment)
7042 ("website" :components ("orgfiles" "images" "other"))))
7045 @node Triggering publication, , Sample configuration, Publishing
7046 @section Triggering publication
7048 Once org-publish is properly configured, you can publish with the
7049 following functions:
7053 Prompt for a specific project and publish all files that belong to it.
7055 Publish the project containing the current file.
7057 Publish only the current file.
7059 Publish all projects.
7062 Org uses timestamps to track when a file has changed. The above
7063 functions normally only publish changed files. You can override this and
7064 force publishing of all files by giving a prefix argument.
7066 @node Miscellaneous, Extensions and Hacking, Publishing, Top
7067 @chapter Miscellaneous
7070 * Completion:: M-TAB knows what you need
7071 * Customization:: Adapting Org-mode to your taste
7072 * In-buffer settings:: Overview of the #+KEYWORDS
7073 * The very busy C-c C-c key:: When in doubt, press C-c C-c
7074 * Clean view:: Getting rid of leading stars in the outline
7075 * TTY keys:: Using Org-mode on a tty
7076 * Interaction:: Other Emacs packages
7077 * Bugs:: Things which do not work perfectly
7080 @node Completion, Customization, Miscellaneous, Miscellaneous
7082 @cindex completion, of @TeX{} symbols
7083 @cindex completion, of TODO keywords
7084 @cindex completion, of dictionary words
7085 @cindex completion, of option keywords
7086 @cindex completion, of tags
7087 @cindex completion, of property keys
7088 @cindex completion, of link abbreviations
7089 @cindex @TeX{} symbol completion
7090 @cindex TODO keywords completion
7091 @cindex dictionary word completion
7092 @cindex option keyword completion
7093 @cindex tag completion
7094 @cindex link abbreviations, completion of
7096 Org-mode supports in-buffer completion. This type of completion does
7097 not make use of the minibuffer. You simply type a few letters into
7098 the buffer and use the key to complete text right there.
7103 Complete word at point
7106 At the beginning of a headline, complete TODO keywords.
7108 After @samp{\}, complete @TeX{} symbols supported by the exporter.
7110 After @samp{*}, complete headlines in the current buffer so that they
7111 can be used in search links like @samp{[[*find this headline]]}.
7113 After @samp{:} in a headline, complete tags. The list of tags is taken
7114 from the variable @code{org-tag-alist} (possibly set through the
7115 @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
7116 dynamically from all tags used in the current buffer.
7118 After @samp{:} and not in a headline, complete property keys. The list
7119 of keys is constructed dynamically from all keys used in the current
7122 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
7124 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
7125 @samp{OPTIONS} which set file-specific options for Org-mode. When the
7126 option keyword is already complete, pressing @kbd{M-@key{TAB}} again
7127 will insert example settings for this keyword.
7129 In the line after @samp{#+STARTUP: }, complete startup keywords,
7130 i.e. valid keys for this line.
7132 Elsewhere, complete dictionary words using ispell.
7136 @node Customization, In-buffer settings, Completion, Miscellaneous
7137 @section Customization
7138 @cindex customization
7139 @cindex options, for customization
7140 @cindex variables, for customization
7142 There are more than 180 variables that can be used to customize
7143 Org-mode. For the sake of compactness of the manual, I am not
7144 describing the variables here. A structured overview of customization
7145 variables is available with @kbd{M-x org-customize}. Or select
7146 @code{Browse Org Group} from the @code{Org->Customization} menu. Many
7147 settings can also be activated on a per-file basis, by putting special
7148 lines into the buffer (@pxref{In-buffer settings}).
7150 @node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
7151 @section Summary of in-buffer settings
7152 @cindex in-buffer settings
7153 @cindex special keywords
7155 Org-mode uses special lines in the buffer to define settings on a
7156 per-file basis. These lines start with a @samp{#+} followed by a
7157 keyword, a colon, and then individual words defining a setting. Several
7158 setting words can be in the same line, but you can also have multiple
7159 lines for the keyword. While these settings are described throughout
7160 the manual, here is a summary. After changing any of those lines in the
7161 buffer, press @kbd{C-c C-c} with the cursor still in the line to
7162 activate the changes immediately. Otherwise they become effective only
7163 when the file is visited again in a new Emacs session.
7166 @item #+ARCHIVE: %s_done::
7167 This line sets the archive location for the agenda file. It applies for
7168 all subsequent lines until the next @samp{#+ARCHIVE} line, or the end
7169 of the file. The first such line also applies to any entries before it.
7170 The corresponding variable is @code{org-archive-location}.
7172 This line sets the category for the agenda file. The category applies
7173 for all subsequent lines until the next @samp{#+CATEGORY} line, or the
7174 end of the file. The first such line also applies to any entries before it.
7175 @item #+COLUMNS: %25ITEM .....
7176 Set the default format for columns view. This format applies when
7177 columns view is invoked in location where no COLUMNS property applies.
7178 @item #+CONSTANTS: name1=value1 ...
7179 Set file-local values for constants to be used in table formulas. This
7180 line set the local variable @code{org-table-formula-constants-local}.
7181 The global version of this variable is
7182 @code{org-table-formula-constants}.
7183 @item #+DRAWERS: NAME1 .....
7184 Set the file-local set of drawers. The corresponding global variable is
7186 @item #+LINK: linkword replace
7187 These lines (several are allowed) specify link abbreviations.
7188 @xref{Link abbreviations}. The corresponding variable is
7189 @code{org-link-abbrev-alist}.
7190 @item #+PRIORITIES: highest lowest default
7191 This line sets the limits and the default for the priorities. All three
7192 must be either letters A-Z or numbers 0-9. The highest priority must
7193 have a lower ASCII number that the lowest priority.
7194 @item #+PROPERTY: Property_Name Value
7195 This line sets a default inheritance value for entries in the current
7196 buffer, most useful for specifying the allowed values of a property.
7198 This line sets options to be used at startup of Org-mode, when an
7199 Org-mode file is being visited. The first set of options deals with the
7200 initial visibility of the outline tree. The corresponding variable for
7201 global default settings is @code{org-startup-folded}, with a default
7202 value @code{t}, which means @code{overview}.
7203 @cindex @code{overview}, STARTUP keyword
7204 @cindex @code{content}, STARTUP keyword
7205 @cindex @code{showall}, STARTUP keyword
7207 overview @r{top-level headlines only}
7208 content @r{all headlines}
7209 showall @r{no folding at all, show everything}
7211 Then there are options for aligning tables upon visiting a file. This
7212 is useful in files containing narrowed table columns. The corresponding
7213 variable is @code{org-startup-align-all-tables}, with a default value
7215 @cindex @code{align}, STARTUP keyword
7216 @cindex @code{noalign}, STARTUP keyword
7218 align @r{align all tables}
7219 noalign @r{don't align tables on startup}
7221 Logging TODO state changes and clock intervals (variables
7222 @code{org-log-done} and @code{org-log-repeat}) can be configured using
7224 @cindex @code{logdone}, STARTUP keyword
7225 @cindex @code{nologging}, STARTUP keyword
7226 @cindex @code{lognotedone}, STARTUP keyword
7227 @cindex @code{lognoteclock-out}, STARTUP keyword
7228 @cindex @code{lognotestate}, STARTUP keyword
7229 @cindex @code{logrepeat}, STARTUP keyword
7230 @cindex @code{nologrepeat}, STARTUP keyword
7232 logging @r{record a timestamp when an item is marked DONE}
7233 nologging @r{don't record when items are marked DONE}
7234 lognotedone @r{record timestamp and a note when DONE}
7235 lognotestate @r{record timestamp and a note when TODO state changes}
7236 logrepeat @r{record a note when re-instating a repeating item}
7237 nologrepeat @r{do not record when re-instating repeating item}
7238 lognoteclock-out @r{record timestamp and a note when clocking out}
7240 Here are the options for hiding leading stars in outline headings. The
7241 corresponding variables are @code{org-hide-leading-stars} and
7242 @code{org-odd-levels-only}, both with a default setting @code{nil}
7243 (meaning @code{showstars} and @code{oddeven}).
7244 @cindex @code{hidestars}, STARTUP keyword
7245 @cindex @code{showstars}, STARTUP keyword
7246 @cindex @code{odd}, STARTUP keyword
7247 @cindex @code{even}, STARTUP keyword
7249 hidestars @r{make all but one of the stars starting a headline invisible.}
7250 showstars @r{show all stars starting a headline}
7251 odd @r{allow only odd outline levels (1,3,...)}
7252 oddeven @r{allow all outline levels}
7254 To turn on custom format overlays over time stamps (variables
7255 @code{org-put-time-stamp-overlays} and
7256 @code{org-time-stamp-overlay-formats}), use
7257 @cindex @code{customtime}, STARTUP keyword
7259 customtime @r{overlay custom time format}
7261 The following options influence the table spreadsheet (variable
7262 @code{constants-unit-system}).
7263 @cindex @code{constcgs}, STARTUP keyword
7264 @cindex @code{constSI}, STARTUP keyword
7266 constcgs @r{@file{constants.el} should use the c-g-s unit system}
7267 constSI @r{@file{constants.el} should use the SI unit system}
7269 @item #+TAGS: TAG1(c1) TAG2(c2)
7270 These lines (several such lines are allowed) specify the legal tags in
7271 this file, and (potentially) the corresponding @emph{fast tag selection}
7272 keys. The corresponding variable is @code{org-tag-alist}.
7274 This line contains the formulas for the table directly above the line.
7275 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS, #+DATE:
7276 These lines provide settings for exporting files. For more details see
7277 @ref{Export options}.
7278 @item #+SEQ_TODO: #+TYP_TODO:
7279 These lines set the TODO keywords and their interpretation in the
7280 current file. The corresponding variables are @code{org-todo-keywords}
7281 and @code{org-todo-interpretation}.
7284 @node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
7285 @section The very busy C-c C-c key
7287 @cindex C-c C-c, overview
7289 The key @kbd{C-c C-c} has many purposes in org-mode, which are all
7290 mentioned scattered throughout this manual. One specific function of
7291 this key is to add @emph{tags} to a headline (@pxref{Tags}). In many
7292 other circumstances it means something like @emph{Hey Org-mode, look
7293 here and update according to what you see here}. Here is a summary of
7294 what this means in different contexts.
7298 If there are highlights in the buffer from the creation of a sparse
7299 tree, or from clock display, remove these highlights.
7301 If the cursor is in one of the special @code{#+KEYWORD} lines, this
7302 triggers scanning the buffer for these lines and updating the
7305 If the cursor is inside a table, realign the table. This command
7306 works even if the automatic table editor has been turned off.
7308 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
7311 If the cursor is inside a table created by the @file{table.el} package,
7312 activate that table.
7314 If the current buffer is a remember buffer, close the note and file it.
7315 With a prefix argument, file it, without further interaction, to the
7318 If the cursor is on a @code{<<<target>>>}, update radio targets and
7319 corresponding links in this buffer.
7321 If the cursor is in a property line or at the start or end of a property
7322 drawer, offer property commands.
7324 If the cursor is in a plain list item with a checkbox, toggle the status
7327 If the cursor is on a numbered item in a plain list, renumber the
7330 If the cursor is on the @code{#+BEGIN} line of a dynamical block, the
7334 @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
7335 @section A cleaner outline view
7336 @cindex hiding leading stars
7337 @cindex clean outline view
7339 Some people find it noisy and distracting that the Org-mode headlines
7340 are starting with a potentially large number of stars. For example
7341 the tree from @ref{Headlines}:
7344 * Top level headline
7350 * Another top level headline
7354 Unfortunately this is deeply ingrained into the code of Org-mode and
7355 cannot be easily changed. You can, however, modify the display in such
7356 a way that all leading stars become invisible and the outline more easy
7357 to read. To do this, customize the variable
7358 @code{org-hide-leading-stars} like this:
7361 (setq org-hide-leading-stars t)
7365 or change this on a per-file basis with one of the lines (anywhere in
7369 #+STARTUP: showstars
7370 #+STARTUP: hidestars
7374 Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate
7377 With stars hidden, the tree becomes:
7380 * Top level headline
7386 * Another top level headline
7390 Note that the leading stars are not truly replaced by whitespace, they
7391 are only fontified with the face @code{org-hide} that uses the
7392 background color as font color. If you are not using either white or
7393 black background, you may have to customize this face to get the wanted
7394 effect. Another possibility is to set this font such that the extra
7395 stars are @i{almost} invisible, for example using the color
7396 @code{grey90} on a white background.
7398 Things become cleaner still if you skip all the even levels and use only
7399 odd levels 1, 3, 5..., effectively adding two stars to go from one
7400 outline level to the next:
7403 * Top level headline
7409 * Another top level headline
7413 In order to make the structure editing and export commands handle this
7414 convention correctly, use
7417 (setq org-odd-levels-only t)
7421 or set this on a per-file basis with one of the following lines (don't
7422 forget to press @kbd{C-c C-c} with the cursor in the startup line to
7423 activate changes immediately).
7430 You can convert an Org-mode file from single-star-per-level to the
7431 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
7432 RET} in that file. The reverse operation is @kbd{M-x
7433 org-convert-to-oddeven-levels}.
7435 @node TTY keys, Interaction, Clean view, Miscellaneous
7436 @section Using org-mode on a tty
7437 @cindex tty keybindings
7439 Org-mode uses a number of keys that are not accessible on a tty. This
7440 applies to most special keys like cursor keys, @key{TAB} and
7441 @key{RET}, when these are combined with modifier keys like @key{Meta}
7442 and/or @key{Shift}. Org-mode uses these bindings because it needs to
7443 provide keys for a large number of commands, and because these keys
7444 appeared particularly easy to remember. In order to still be able to
7445 access the core functionality of Org-mode on a tty, alternative
7446 bindings are provided. Here is a complete list of these bindings,
7447 which are obviously more cumbersome to use. Note that sometimes a
7448 work-around can be better. For example changing a time stamp is
7449 really only fun with @kbd{S-@key{cursor}} keys. On a tty you would
7450 rather use @kbd{C-c .} to re-insert the timestamp.
7452 @multitable @columnfractions 0.15 0.2 0.2
7453 @item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2}
7454 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab
7455 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}}
7456 @item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab
7457 @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{@key{Esc} @key{right}}
7458 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab
7459 @item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{@key{Esc} @key{up}}
7460 @item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab
7461 @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{@key{Esc} @key{down}}
7462 @item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab
7463 @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab
7464 @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{@key{Esc} @key{RET}}
7465 @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab
7466 @item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab
7467 @item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab
7468 @item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab
7469 @item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab
7470 @item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab
7471 @item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab
7474 @node Interaction, Bugs, TTY keys, Miscellaneous
7475 @section Interaction with other packages
7476 @cindex packages, interaction with other
7477 Org-mode lives in the world of GNU Emacs and interacts in various ways
7478 with other code out there.
7481 * Cooperation:: Packages Org-mode cooperates with
7482 * Conflicts:: Packages that lead to conflicts
7485 @node Cooperation, Conflicts, Interaction, Interaction
7486 @subsection Packages that Org-mode cooperates with
7489 @cindex @file{calc.el}
7490 @item @file{calc.el} by Dave Gillespie
7491 Org-mode uses the calc package for implementing spreadsheet
7492 functionality in its tables (@pxref{The spreadsheet}). Org-mode
7493 checks for the availability of calc by looking for the function
7494 @code{calc-eval} which should be autoloaded in your setup if calc has
7495 been installed properly. As of Emacs 22, calc is part of the Emacs
7496 distribution. Another possibility for interaction between the two
7497 packages is using calc for embedded calculations. @xref{Embedded Mode,
7498 , Embedded Mode, calc, GNU Emacs Calc Manual}.
7499 @cindex @file{constants.el}
7500 @item @file{constants.el} by Carsten Dominik
7501 In a table formula (@pxref{The spreadsheet}), it is possible to use
7502 names for natural constants or units. Instead of defining your own
7503 constants in the variable @code{org-table-formula-constants}, install
7504 the @file{constants} package which defines a large number of constants
7505 and units, and lets you use unit prefixes like @samp{M} for
7506 @samp{Mega} etc. You will need version 2.0 of this package, available
7507 at @url{http://www.astro.uva.nl/~dominik/Tools}. Org-mode checks for
7508 the function @code{constants-get}, which has to be autoloaded in your
7509 setup. See the installation instructions in the file
7510 @file{constants.el}.
7511 @item @file{cdlatex.el} by Carsten Dominik
7512 @cindex @file{cdlatex.el}
7513 Org-mode can make use of the cdlatex package to efficiently enter
7514 La@TeX{} fragments into Org-mode files. See @ref{CDLaTeX mode}.
7515 @item @file{remember.el} by John Wiegley
7516 @cindex @file{remember.el}
7517 Org mode cooperates with remember, see @ref{Remember}.
7518 @file{Remember.el} is not part of Emacs, find it on the web.
7519 @cindex @file{table.el}
7520 @item @file{table.el} by Takaaki Ota
7522 @cindex table editor, @file{table.el}
7523 @cindex @file{table.el}
7525 Complex ASCII tables with automatic line wrapping, column- and
7526 row-spanning, and alignment can be created using the Emacs table
7527 package by Takaaki Ota (@uref{http://sourceforge.net/projects/table},
7528 and also part of Emacs 22).
7529 When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-mode
7530 will call @command{table-recognize-table} and move the cursor into the
7531 table. Inside a table, the keymap of Org-mode is inactive. In order
7532 to execute Org-mode-related commands, leave the table.
7537 Recognize @file{table.el} table. Works when the cursor is in a
7542 Insert a table.el table. If there is already a table at point, this
7543 command converts it between the table.el format and the Org-mode
7544 format. See the documentation string of the command
7545 @code{org-convert-table} for the restrictions under which this is
7548 @file{table.el} is part of Emacs 22.
7549 @cindex @file{footnote.el}
7550 @item @file{footnote.el} by Steven L. Baur
7551 Org-mode recognizes numerical footnotes as provided by this package
7552 (@pxref{Footnotes}).
7555 @node Conflicts, , Cooperation, Interaction
7556 @subsection Packages that lead to conflicts with Org-mode
7560 @cindex @file{allout.el}
7561 @item @file{allout.el} by Ken Manheimer
7562 Startup of Org-mode may fail with the error message
7563 @code{(wrong-type-argument keymapp nil)} when there is an outdated
7564 version @file{allout.el} on the load path, for example the version
7565 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem will
7566 disappear. If for some reason you cannot do this, make sure that org.el
7567 is loaded @emph{before} @file{allout.el}, for example by putting
7568 @code{(require 'org)} early enough into your @file{.emacs} file.
7570 @cindex @file{CUA.el}
7571 @item @file{CUA.el} by Kim. F. Storm
7572 Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys used by
7573 CUA-mode (as well as pc-select-mode and s-region-mode) to select and
7574 extend the region. If you want to use one of these packages along with
7575 Org-mode, configure the variable @code{org-replace-disputed-keys}. When
7576 set, Org-mode will move the following keybindings in Org-mode files, and
7577 in the agenda buffer (but not during date selection).
7580 S-UP -> M-p S-DOWN -> M-n
7581 S-LEFT -> M-- S-RIGHT -> M-+
7584 Yes, these are unfortunately more difficult to remember. If you want
7585 to have other replacement keys, look at the variable
7586 @code{org-disputed-keys}.
7587 @item @file{windmove.el} by Hovav Shacham
7588 @cindex @file{windmove.el}
7589 Also this package uses the @kbd{S-<cursor>} keys, so everything written
7590 in the paragraph above about CUA mode also applies here.
7592 @cindex @file{footnote.el}
7593 @item @file{footnote.el} by Steven L. Baur
7594 Org-mode supports the syntax of the footnote package, but only the
7595 numerical footnote markers. Also, the default key for footnote
7596 commands, @kbd{C-c !} is already used by Org-mode. You could use the
7597 variable @code{footnote-prefix} to switch footnotes commands to another
7598 key. Or, you could use @code{org-replace-disputed-keys} and
7599 @code{org-disputed-keys} to change the settings in Org-mode.
7604 @node Bugs, , Interaction, Miscellaneous
7608 Here is a list of things that should work differently, but which I
7609 have found too hard to fix.
7613 If a table field starts with a link, and if the corresponding table
7614 column is narrowed (@pxref{Narrow columns}) to a width too small to
7615 display the link, the field would look entirely empty even though it is
7616 not. To prevent this, Org-mode throws an error. The work-around is to
7617 make the column wide enough to fit the link, or to add some text (at
7618 least 2 characters) before the link in the same field.
7620 Narrowing table columns does not work on XEmacs, because the
7621 @code{format} function does not transport text properties.
7623 Text in an entry protected with the @samp{QUOTE} keyword should not
7626 When the application called by @kbd{C-c C-o} to open a file link fails
7627 (for example because the application does not exist or refuses to open
7628 the file), it does so silently. No error message is displayed.
7630 Recalculating a table line applies the formulas from left to right.
7631 If a formula uses @emph{calculated} fields further down the row,
7632 multiple recalculation may be needed to get all fields consistent. You
7633 may use the command @code{org-table-iterate} (@kbd{C-u C-c *}) to
7634 recalculate until convergence.
7636 A single letter cannot be made bold, for example @samp{*a*}.
7638 The exporters work well, but could be made more efficient.
7642 @node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top
7643 @appendix Extensions, Hooks and Hacking
7645 This appendix lists extensions for Org-mode written by other authors.
7646 It also covers some aspects where users can extend the functionality of
7650 * Extensions:: Existing 3rd-part extensions
7651 * Adding hyperlink types:: New custom link types
7652 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
7653 * Dynamic blocks:: Automatically filled blocks
7654 * Special agenda views:: Customized views
7655 * Using the property API:: Writing programs that use entry properties
7658 @node Extensions, Adding hyperlink types, Extensions and Hacking, Extensions and Hacking
7659 @section Third-party extensions for Org-mode
7660 @cindex extension, third-party
7662 The following extensions for Org-mode have been written by other people:
7665 @cindex @file{org-publish.el}
7666 @item @file{org-publish.el} by David O'Toole
7667 This package provides facilities for publishing related sets of Org-mode
7668 files together with linked files like images as webpages. It is
7669 highly configurable and can be used for other publishing purposes as
7670 well. As of Org-mode version 4.30, @file{org-publish.el} is part of the
7671 Org-mode distribution. It is not yet part of Emacs, however, a delay
7672 caused by the preparations for the 22.1 release. In the mean time,
7673 @file{org-publish.el} can be downloaded from David's site:
7674 @url{http://dto.freeshell.org/e/org-publish.el}.
7675 @cindex @file{org-mouse.el}
7676 @item @file{org-mouse.el} by Piotr Zielinski
7677 This package implements extended mouse functionality for Org-mode. It
7678 allows you to cycle visibility and to edit the document structure with
7679 the mouse. Best of all, it provides a context-sensitive menu on
7680 @key{mouse-3} that changes depending on the context of a mouse-click.
7681 As of Org-mode version 4.53, @file{org-mouse.el} is part of the
7682 Org-mode distribution. It is not yet part of Emacs, however, a delay
7683 caused by the preparations for the 22.1 release. In the mean time,
7684 @file{org-mouse.el} can be downloaded from Piotr's site:
7685 @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}.
7686 @cindex @file{org-blog.el}
7687 @item @file{org-blog.el} by David O'Toole
7688 A blogging plug-in for @file{org-publish.el}.@*
7689 @url{http://dto.freeshell.org/notebook/OrgMode.html}.
7690 @cindex @file{blorg.el}
7691 @item @file{blorg.el} by Bastien Guerry
7692 Publish Org-mode files as
7693 blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}.
7694 @cindex @file{org2rem.el}
7695 @item @file{org2rem.el} by Bastien Guerry
7696 Translates Org-mode files into something readable by
7697 Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}.
7698 @item @file{org-toc.el} by Bastien Guerry
7699 Produces a simple table of contents of an Org-mode file, for easy
7700 navigation. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}.
7701 @item @file{org-registry.el} by Bastien Guerry
7702 Find which Org-file link to a certain document.
7703 @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}.
7708 @node Adding hyperlink types, Tables in arbitrary syntax, Extensions, Extensions and Hacking
7709 @section Adding hyperlink types
7710 @cindex hyperlinks, adding new types
7712 Org-mode has a large number of hyperlink types built-in
7713 (@pxref{Hyperlinks}). If you would like to add new link types, it
7714 provides an interface for doing so. Lets look at an example file
7715 @file{org-man.el} that will add support for creating links like
7716 @samp{[[man:printf][The printf manpage]]} to show unix manual pages inside
7720 ;;; org-man.el - Support for links to manpages in Org-mode
7724 (org-add-link-type "man" 'org-man-open)
7725 (add-hook 'org-store-link-functions 'org-man-store-link)
7727 (defcustom org-man-command 'man
7728 "The Emacs command to be used to display a man page."
7730 :type '(choice (const man) (const woman)))
7732 (defun org-man-open (path)
7733 "Visit the manpage on PATH.
7734 PATH should be a topic that can be thrown at the man command."
7735 (funcall org-man-command path))
7737 (defun org-man-store-link ()
7738 "Store a link to a manpage."
7739 (when (memq major-mode '(Man-mode woman-mode))
7740 ;; This is a man page, we do make this link
7741 (let* ((page (org-man-get-page-name))
7742 (link (concat "man:" page))
7743 (description (format "Manpage for %s" page)))
7744 (org-store-link-props
7747 :description description))))
7749 (defun org-man-get-page-name ()
7750 "Extract the page name from the buffer name."
7751 ;; This works for both `Man-mode' and `woman-mode'.
7752 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
7753 (match-string 1 (buffer-name))
7754 (error "Cannot create link to this man page")))
7758 ;;; org-man.el ends here
7762 You would activate this new link type in @file{.emacs} with
7769 Lets go through the file and see what it does.
7772 It does @code{(require 'org)} to make sure that @file{org.el} has been
7775 The next line calls @code{org-add-link-type} to define a new link type
7776 with prefix @samp{man}. The call also contains the name of a function
7777 that will be called to follow such a link.
7779 The next line adds a function to @code{org-store-link-functions}, in
7780 order to allow the command @kbd{C-c l} to record a useful link in a
7781 buffer displaying a man page.
7784 The rest of the file defines the necessary variables and functions.
7785 First there is a customization variable that determines which emacs
7786 command should be used to display manpages. There are two options,
7787 @code{man} and @code{woman}. Then the function to follow a link is
7788 defined. It gets the link path as an argument - in this case the link
7789 path is just a topic for the manual command. The function calls the
7790 value of @code{org-man-command} to display the man page.
7792 Finally the function @code{org-man-store-link} is defined. When you try
7793 to store a link with @kbd{C-c l}, also this function will be called to
7794 try to make a link. The function must first decide if it is supposed to
7795 create the link for this buffer type, we do this by checking the value
7796 of the variable @code{major-mode}. If not, the function must exit and
7797 retunr the value @code{nil}. If yes, the link is created by getting the
7798 manual tpoic from the buffer name and prefixing it with the string
7799 @samp{man:}. Then it must call the command @code{org-store-link-props}
7800 and set the @code{:type} and @code{:link} properties. Optionally you
7801 can also set the @code{:description} property to provide a default for
7802 the link description when the link is later inserted into tan Org-mode
7803 buffer with @kbd{C-c C-l}.
7805 @node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Extensions and Hacking
7806 @section Tables and Lists in arbitrary syntax
7807 @cindex tables, in other modes
7808 @cindex lists, in other modes
7811 Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a
7812 frequent feature request has been to make it work with native tables in
7813 specific languages, for example La@TeX{}. However, this is extremely
7814 hard to do in a general way, would lead to a customization nightmare,
7815 and would take away much of the simplicity of the Orgtbl-mode table
7819 This appendix describes a different approach. We keep the Orgtbl-mode
7820 table in its native format (the @i{source table}), and use a custom
7821 function to @i{translate} the table to the correct syntax, and to
7822 @i{install} it in the right location (the @i{target table}). This puts
7823 the burden of writing conversion functions on the user, but it allows
7824 for a very flexible system.
7826 Bastien added the ability to do the same with lists. You can use Org's
7827 facilities to edit and structure lists by turning @code{orgstruct-mode}
7828 on, then locally exporting such lists in another format (HTML, La@TeX{}
7833 * Radio tables:: Sending and receiving
7834 * A LaTeX example:: Step by step, almost a tutorial
7835 * Translator functions:: Copy and modify
7836 * Radio lists:: Doing the same for lists.
7839 @node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax
7840 @subsection Radio tables
7841 @cindex radio tables
7843 To define the location of the target table, you first need to create two
7844 lines that are comments in the current mode, but contain magic words for
7845 Orgtbl-mode to find. Orgtbl-mode will insert the translated table
7846 between these lines, replacing whatever was there before. For example:
7849 /* BEGIN RECEIVE ORGTBL table_name */
7850 /* END RECEIVE ORGTBL table_name */
7854 Just above the source table, we put a special line that tells
7855 Orgtbl-mode how to translate this table and where to install it. For
7858 #+ORGTBL: SEND table_name translation_function arguments....
7862 @code{table_name} is the reference name for the table that is also used
7863 in the receiver lines. @code{translation_function} is the Lisp function
7864 that does the translation. Furthermore, the line can contain a list of
7865 arguments (alternating key and value) at the end. The arguments will be
7866 passed as a property list to the translation function for
7867 interpretation. A few standard parameters are already recognized and
7868 acted upon before the translation function is called:
7872 Skip the first N lines of the table. Hlines do count!
7873 @item :skipcols (n1 n2 ...)
7874 List of columns that should be skipped. If the table has a column with
7875 calculation marks, that column is automatically discarded as well.
7876 Please note that the translator function sees the table @emph{after} the
7877 removal of these columns, the function never knows that there have been
7882 The one problem remaining is how to keep the source table in the buffer
7883 without disturbing the normal workings of the file, for example during
7884 compilation of a C file or processing of a La@TeX{} file. There are a
7885 number of different solutions:
7889 The table could be placed in a block comment if that is supported by the
7890 language. For example, in C-mode you could wrap the table between
7891 @samp{/*} and @samp{*/} lines.
7893 Sometimes it is possible to put the table after some kind of @i{END}
7894 statement, for example @samp{\bye} in TeX and @samp{\end@{document@}}
7897 You can just comment the table line by line whenever you want to process
7898 the file, and uncomment it whenever you need to edit the table. This
7899 only sounds tedious - the command @kbd{M-x orgtbl-toggle-comment} does
7900 make this comment-toggling very easy, in particular if you bind it to a
7904 @node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax
7905 @subsection A LaTeX example of radio tables
7906 @cindex LaTeX, and orgtbl-mode
7908 The best way to wrap the source table in La@TeX{} is to use the
7909 @code{comment} environment provided by @file{comment.sty}. It has to be
7910 activated by placing @code{\usepackage@{comment@}} into the document
7911 header. Orgtbl-mode can insert a radio table skeleton@footnote{By
7912 default this works only for La@TeX{}, HTML, and TeXInfo. Configure the
7913 variable @code{orgtbl-radio-tables} to install templates for other
7914 modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will
7915 be prompted for a table name, lets say we use @samp{salesfigures}. You
7916 will then get the following template:
7919 % BEGIN RECEIVE ORGTBL salesfigures
7920 % END RECEIVE ORGTBL salesfigures
7922 #+ORGTBL: SEND salesfigures orgtbl-to-latex
7928 The @code{#+ORGTBL: SEND} line tells orgtbl-mode to use the function
7929 @code{orgtbl-to-latex} to convert the table into La@TeX{} and to put it
7930 into the receiver location with name @code{salesfigures}. You may now
7931 fill in the table, feel free to use the spreadsheet features@footnote{If
7932 the @samp{#+TBLFM} line contains an odd number of dollar characters,
7933 this may cause problems with font-lock in latex-mode. As shown in the
7934 example you can fix this by adding an extra line inside the
7935 @code{comment} environment that is used to balance the dollar
7936 expressions. If you are using AUCTeX with the font-latex library, a
7937 much better solution is to add the @code{comment} environment to the
7938 variable @code{LaTeX-verbatim-environments}.}:
7941 % BEGIN RECEIVE ORGTBL salesfigures
7942 % END RECEIVE ORGTBL salesfigures
7944 #+ORGTBL: SEND salesfigures orgtbl-to-latex
7945 | Month | Days | Nr sold | per day |
7946 |-------+------+---------+---------|
7947 | Jan | 23 | 55 | 2.4 |
7948 | Feb | 21 | 16 | 0.8 |
7949 | March | 22 | 278 | 12.6 |
7950 #+TBLFM: $4=$3/$2;%.1f
7951 % $ (optional extra dollar to keep font-lock happy, see footnote)
7956 When you are done, press @kbd{C-c C-c} in the table to get the converted
7957 table inserted between the two marker lines.
7959 Now lets assume you want to make the table header by hand, because you
7960 want to control how columns are aligned etc. In this case we make sure
7961 that the table translator does skip the first 2 lines of the source
7962 table, and tell the command to work as a @i{splice}, i.e. to not produce
7963 header and footer commands of the target table:
7966 \begin@{tabular@}@{lrrr@}
7967 Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
7968 % BEGIN RECEIVE ORGTBL salesfigures
7969 % END RECEIVE ORGTBL salesfigures
7973 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
7974 | Month | Days | Nr sold | per day |
7975 |-------+------+---------+---------|
7976 | Jan | 23 | 55 | 2.4 |
7977 | Feb | 21 | 16 | 0.8 |
7978 | March | 22 | 278 | 12.6 |
7979 #+TBLFM: $4=$3/$2;%.1f
7983 The La@TeX{} translator function @code{orgtbl-to-latex} is already part of
7984 Orgtbl-mode. It uses a @code{tabular} environment to typeset the table
7985 and marks horizontal lines with @code{\hline}. Furthermore, it
7986 interprets the following parameters:
7990 When set to t, return only table body lines, don't wrap them into a
7991 tabular environment. Default is nil.
7994 A format to be used to wrap each field, should contain @code{%s} for the
7995 original field value. For example, to wrap each field value in dollars,
7996 you could use @code{:fmt "$%s$"}. This may also be a property list with
7997 column numbers and formats. for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
8000 Use this format to print numbers with exponentials. The format should
8001 have @code{%s} twice for inserting mantissa and exponent, for example
8002 @code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This
8003 may also be a property list with column numbers and formats, for example
8004 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
8005 @code{efmt} has been applied to a value, @code{fmt} will also be
8009 @node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax
8010 @subsection Translator functions
8011 @cindex HTML, and orgtbl-mode
8012 @cindex translator function
8014 Orgtbl-mode has several translator functions built-in:
8015 @code{orgtbl-to-latex}, @code{orgtbl-to-html}, and
8016 @code{orgtbl-to-texinfo}. Except for @code{orgtbl-to-html}@footnote{The
8017 HTML translator uses the same code that produces tables during HTML
8018 export.}, these all use a generic translator, @code{orgtbl-to-generic}.
8019 For example, @code{orgtbl-to-latex} itself is a very short function that
8020 computes the column definitions for the @code{tabular} environment,
8021 defines a few field and line separators and then hands over to the
8022 generic translator. Here is the entire code:
8026 (defun orgtbl-to-latex (table params)
8027 "Convert the orgtbl-mode TABLE to LaTeX."
8028 (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
8029 org-table-last-alignment ""))
8032 :tstart (concat "\\begin@{tabular@}@{" alignment "@}")
8033 :tend "\\end@{tabular@}"
8034 :lstart "" :lend " \\\\" :sep " & "
8035 :efmt "%s\\,(%s)" :hline "\\hline")))
8036 (orgtbl-to-generic table (org-combine-plists params2 params))))
8040 As you can see, the properties passed into the function (variable
8041 @var{PARAMS}) are combined with the ones newly defined in the function
8042 (variable @var{PARAMS2}). The ones passed into the function (i.e. the
8043 ones set by the @samp{ORGTBL SEND} line) take precedence. So if you
8044 would like to use the La@TeX{} translator, but wanted the line endings to
8045 be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
8046 overrule the default with
8049 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
8052 For a new language, you can either write your own converter function in
8053 analogy with the La@TeX{} translator, or you can use the generic function
8054 directly. For example, if you have a language where a table is started
8055 with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are
8056 started with @samp{!BL!}, ended with @samp{!EL!} and where the field
8057 separator is a TAB, you could call the generic translator like this (on
8061 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
8062 :lstart "!BL! " :lend " !EL!" :sep "\t"
8066 Please check the documentation string of the function
8067 @code{orgtbl-to-generic} for a full list of parameters understood by
8068 that function and remember that you can pass each of them into
8069 @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
8070 using the generic function.
8072 Of course you can also write a completely new function doing complicated
8073 things the generic translator cannot do. A translator function takes
8074 two arguments. The first argument is the table, a list of lines, each
8075 line either the symbol @code{hline} or a list of fields. The second
8076 argument is the property list containing all parameters specified in the
8077 @samp{#+ORGTBL: SEND} line. The function must return a single string
8078 containing the formatted table. If you write a generally useful
8079 translator, please post it on @code{emacs-orgmode@@gnu.org} so that
8080 others can benefit from your work.
8082 @node Radio lists, , Translator functions, Tables in arbitrary syntax
8083 @subsection Radio lists
8085 @cindex org-list-insert-radio-list
8087 Sending and receiving radio lists works exactly the same way than
8088 sending and receiving radio tables (@pxref{Radio tables}) @footnote{You
8089 need to load the @code{org-export-latex.el} package to use radio lists
8090 since the relevant code is there for now.}. As for radio tables, you
8091 can insert radio lists templates in HTML, La@TeX{} and TeXInfo modes by
8092 calling @code{org-list-insert-radio-list}.
8094 Here are the differences with radio tables:
8098 Use @code{ORGLST} instead of @code{ORGTBL}.
8100 The available translation functions for radio lists don't take
8103 `C-c C-c' will work when pressed on the first item of the list.
8106 Here is a La@TeX{} example. Let's say that you have this in your
8110 % BEGIN RECEIVE ORGLST to-buy
8111 % END RECEIVE ORGLST to-buy
8113 #+ORGLIST: SEND to-buy orgtbl-to-latex
8122 Pressing `C-c C-c' on @code{a new house} and will insert the converted
8123 La@TeX{} list between the two marker lines.
8125 @node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Extensions and Hacking
8126 @section Dynamic blocks
8127 @cindex dynamic blocks
8129 Org-mode documents can contain @emph{dynamic blocks}. These are
8130 specially marked regions that are updated by some user-written function.
8131 A good example for such a block is the clock table inserted by the
8132 command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
8134 Dynamic block are enclosed by a BEGIN-END structure that assigns a name
8135 to the block and can also specify parameters for the function producing
8136 the content of the block.
8139 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
8144 Dynamic blocks are updated with the following commands
8149 Update dynamic block at point.
8150 @kindex C-u C-c C-x C-u
8151 @item C-u C-c C-x C-u
8152 Update all dynamic blocks in the current file.
8155 Updating a dynamic block means to remove all the text between BEGIN and
8156 END, parse the BEGIN line for parameters and then call the specific
8157 writer function for this block to insert the new content. For a block
8158 with name @code{myblock}, the writer function is
8159 @code{org-dblock-write:myblock} with as only parameter a property list
8160 with the parameters given in the begin line. Here is a trivial example
8161 of a block that keeps track of when the block update function was last
8165 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
8171 The corresponding block writer function could look like this:
8174 (defun org-dblock-write:block-update-time (params)
8175 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
8176 (insert "Last block update at: "
8177 (format-time-string fmt (current-time)))))
8180 If you want to make sure that all dynamic blocks are always up-to-date,
8181 you could add the function @code{org-update-all-dblocks} to a hook, for
8182 example @code{before-save-hook}. @code{org-update-all-dblocks} is
8183 written in a way that is does nothing in buffers that are not in Org-mode.
8185 @node Special agenda views, Using the property API, Dynamic blocks, Extensions and Hacking
8186 @section Special Agenda Views
8187 @cindex agenda views, user-defined
8189 Org-mode provides a special hook that can be used to narrow down the
8190 selection made by any of the agenda views. You may specify a function
8191 that is used at each match to verify if the match should indeed be part
8192 of the agenda view, and if not, how much should be skipped.
8194 Let's say you want to produce a list of projects that contain a WAITING
8195 tag anywhere in the project tree. Let's further assume that you have
8196 marked all tree headings that define a project with the todo keyword
8197 PROJECT. In this case you would run a todo search for the keyword
8198 PROJECT, but skip the match unless there is a WAITING tag anywhere in
8199 the subtree belonging to the project line.
8201 To achieve this, you must write a function that searches the subtree for
8202 the tag. If the tag is found, the function must return @code{nil} to
8203 indicate that this match should not be skipped. If there is no such
8204 tag, return the location of the end of the subtree, to indicate that
8205 search should continue from there.
8208 (defun my-skip-unless-waiting ()
8209 "Skip trees that are not waiting"
8210 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
8211 (if (re-search-forward ":WAITING:" subtree-end t)
8212 nil ; tag found, do not skip
8213 subtree-end))) ; tag not found, continue after end of subtree
8216 Now you may use this function in an agenda custom command, for example
8220 (org-add-agenda-custom-command
8221 '("b" todo "PROJECT"
8222 ((org-agenda-skip-function 'my-org-waiting-projects)
8223 (org-agenda-overriding-header "Projects waiting for something: "))))
8226 Note that this also binds @code{org-agenda-overriding-header} to get a
8227 meaningful header in the agenda view.
8229 You may also put a Lisp form into @code{org-agenda-skip-function}. In
8230 particular, you may use the functions @code{org-agenda-skip-entry-if}
8231 and @code{org-agenda-skip-subtree-if} in this form, for example:
8234 @item '(org-agenda-skip-entry-if 'scheduled)
8235 Skip current entry if it has been scheduled.
8236 @item '(org-agenda-skip-entry-if 'notscheduled)
8237 Skip current entry if it has not been scheduled.
8238 @item '(org-agenda-skip-entry-if 'deadline)
8239 Skip current entry if it has a deadline.
8240 @item '(org-agenda-skip-entry-if 'scheduled 'deadline)
8241 Skip current entry if it has a deadline, or if it is scheduled.
8242 @item '(org-agenda-skip-entry 'regexp "regular expression")
8243 Skip current entry if the regular expression matches in the entry.
8244 @item '(org-agenda-skip-entry 'notregexp "regular expression")
8245 Skip current entry unless the regular expression matches.
8246 @item '(org-agenda-skip-subtree-if 'regexp "regular expression")
8247 Same as above, but check and skip the entire subtree.
8250 Therefore we could also have written the search for WAITING projects
8251 like this, even without defining a special function:
8254 (org-add-agenda-custom-command
8255 '("b" todo "PROJECT"
8256 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
8257 'regexp ":WAITING:"))
8258 (org-agenda-overriding-header "Projects waiting for something: "))))
8262 @node Using the property API, , Special agenda views, Extensions and Hacking
8263 @section Using the property API
8264 @cindex API, for properties
8265 @cindex properties, API
8267 Here is a description of the functions that can be used to work with
8270 @defun org-entry-properties &optional pom which
8271 Get all properties of the entry at point-or-marker POM.
8272 This includes the TODO keyword, the tags, time strings for deadline,
8273 scheduled, and clocking, and any additional properties defined in the
8274 entry. The return value is an alist, keys may occur multiple times
8275 if the property key was used several times.
8276 POM may also be nil, in which case the current entry is used.
8277 If WHICH is nil or `all', get all properties. If WHICH is
8278 `special' or `standard', only get that subclass.
8280 @defun org-entry-get pom property &optional inherit
8281 Get value of PROPERTY for entry at point-or-marker POM.
8282 If INHERIT is non-nil and the entry does not have the property,
8283 then also check higher levels of the hierarchy. This function ignores
8284 the value of @code{org-use-property-inheritance} and requires the
8285 explicit INHERIT flag.
8288 @defun org-entry-delete pom property
8289 Delete the property PROPERTY from entry at point-or-marker POM.
8292 @defun org-entry-put pom property value
8293 Set PROPERTY to VALUE for entry at point-or-marker POM.
8296 @defun org-buffer-property-keys &optional include-specials
8297 Get all property keys in the current buffer.
8300 @defun org-insert-property-drawer
8301 Insert a property drawer at point.
8304 @node History and Acknowledgments, Index, Extensions and Hacking, Top
8305 @appendix History and Acknowledgments
8306 @cindex acknowledgments
8310 Org-mode was borne in 2003, out of frustration over the user interface
8311 of the Emacs outline-mode. I was trying to organize my notes and
8312 projects, and using Emacs seemed to be the natural way to go. However,
8313 having to remember eleven different commands with two or three keys per
8314 command, only to hide and unhide parts of the outline tree, that seemed
8315 entirely unacceptable to me. Also, when using outlines to take notes, I
8316 constantly want to restructure the tree, organizing it parallel to my
8317 thoughts and plans. @emph{Visibility cycling} and @emph{structure
8318 editing} were originally implemented in the package
8319 @file{outline-magic.el}, but quickly moved to the more general
8320 @file{org.el}. As this environment became comfortable for project
8321 planning, the next step was adding @emph{TODO entries}, basic @emph{time
8322 stamps}, and @emph{table support}. These areas highlight the two main
8323 goals that Org-mode still has today: To create a new, outline-based,
8324 plain text mode with innovative and intuitive editing features, and to
8325 incorporate project planning functionality directly into a notes file.
8327 Since the first release, literally thousands of emails to me or on
8328 @code{emacs-orgmode@@gnu.org} have provided a constant stream of bug
8329 reports, feedback, new ideas, and sometimes patches and add-on code.
8330 Many thanks to everyone who has helped to improve this package. I am
8331 trying to keep here a list of the people who had significant influence
8332 in shaping one or more aspects of Org-mode. The list may not be
8333 complete, if I have forgotten someone, please accept my apologies and
8339 @i{Russel Adams} came up with the idea for drawers.
8341 @i{Thomas Baumann} contributed the code for links to the MH-E email
8344 @i{Alex Bochannek} provided a patch for rounding time stamps.
8346 @i{Charles Cave}'s suggestion sparked the implementation of templates
8349 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
8352 @i{Gregory Chernov} patched support for lisp forms into table
8353 calculations and improved XEmacs compatibility, in particular by porting
8354 @file{nouline.el} to XEmacs.
8356 @i{Sacha Chua} suggested to copy some linking code from Planner.
8358 @i{Eddward DeVilla} proposed and tested checkbox statistics. He also
8359 came up with the idea of properties, and that there should be an API for
8362 @i{Kees Dullemond} used to edit projects lists directly in HTML and so
8363 inspired some of the early development, including HTML export. He also
8364 asked for a way to narrow wide table columns.
8366 @i{Christian Egli} converted the documentation into TeXInfo format,
8367 patched CSS formatting into the HTML exporter, and inspired the agenda.
8369 @i{David Emery} provided a patch for custom CSS support in exported
8372 @i{Nic Ferrier} contributed mailcap and XOXO support.
8374 @i{John Foerch} figured out how to make incremental search show context
8375 around a match in a hidden outline tree.
8377 @i{Niels Giesen} had the idea to automatically archive DONE trees.
8379 @i{Bastien Guerry} wrote the La@TeX{} exporter and has been prolific
8380 with patches, ideas, and bug reports.
8382 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
8384 @i{Scott Jaderholm} proposed footnotes, control over whitespace between
8385 folded entries, and column view for properties.
8387 @i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also
8388 provided frequent feedback and some patches.
8390 @i{Jason F. McBrayer} suggested agenda export to CSV format.
8392 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file
8395 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
8398 @i{Rick Moynihan} proposed to allow multiple TODO sequences in a file.
8400 @i{Todd Neal} provided patches for links to Info files and elisp forms.
8402 @i{Tim O'Callaghan} suggested in-file links, search options for general
8403 file links, and TAGS.
8405 @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
8408 @i{Oliver Oppitz} suggested multi-state TODO items.
8410 @i{Scott Otterson} sparked the introduction of descriptive text for
8411 links, among other things.
8413 @i{Pete Phillips} helped during the development of the TAGS feature, and
8414 provided frequent feedback.
8416 @i{T.V. Raman} reported bugs and suggested improvements.
8418 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
8421 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
8423 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
8424 conflict with @file{allout.el}.
8426 @i{Jason Riedy} sent a patch to fix a bug with export of TODO keywords.
8428 @i{Philip Rooke} created the Org-mode reference card and provided lots
8431 @i{Christian Schlauer} proposed angular brackets around links, among
8434 Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s
8435 @file{organizer-mode.el}.
8437 @i{Daniel Sinder} came up with the idea of internal archiving by locking
8440 @i{Dale Smith} proposed link abbreviations.
8442 @i{Adam Spiers} asked for global linking commands and inspired the link
8443 extension system. support mairix.
8445 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
8446 chapter about publishing.
8448 @i{J@"urgen Vollmer} contributed code generating the table of contents
8451 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
8454 @i{David Wainberg} suggested archiving, and improvements to the linking
8457 @i{John Wiegley} wrote @file{emacs-wiki.el} and @file{planner.el}. The
8458 development of Org-mode was fully independent, and both systems are
8459 really different beasts in their basic ideas and implementation details.
8460 I later looked at John's code, however, and learned from his
8461 implementation of (i) links where the link itself is hidden and only a
8462 description is shown, and (ii) popping up a calendar to select a date.
8463 John has also contributed a number of great ideas directly to Org-mode.
8465 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
8468 @i{Roland Winkler} requested additional keybindings to make Org-mode
8471 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
8472 and contributed various ideas and code snippets.
8476 @node Index, Key Index, History and Acknowledgments, Top
8481 @node Key Index, , Index, Top
8482 @unnumbered Key Index
8489 arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac