Mercurial > emacs
changeset 84308:c2eb0b4307ea
Move here from ../../man
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 05:01:28 +0000 |
| parents | bc3b4a05f57f |
| children | 537ecf6520b8 |
| files | doc/misc/org.texi |
| diffstat | 1 files changed, 7931 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/org.texi Thu Sep 06 05:01:28 2007 +0000 @@ -0,0 +1,7931 @@ +\input texinfo +@c %**start of header +@setfilename ../info/org +@settitle Org Mode Manual + +@set VERSION 5.07 +@set DATE August 2007 + +@dircategory Emacs +@direntry +* Org Mode: (org). Outline-based notes management and organizer +@end direntry + +@c Version and Contact Info +@set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage} +@set AUTHOR Carsten Dominik +@set MAINTAINER Carsten Dominik +@set MAINTAINEREMAIL @email{dominik at science dot uva dot nl} +@set MAINTAINERCONTACT @uref{mailto:dominik at science dot uva dot nl,contact the maintainer} +@c %**end of header +@finalout + +@c Macro definitions + +@c Subheadings inside a table. +@macro tsubheading{text} +@ifinfo +@subsubheading \text\ +@end ifinfo +@ifnotinfo +@item @b{\text\} +@end ifnotinfo +@end macro + +@copying +This manual is for Org-mode (version @value{VERSION}). + +Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License.'' + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' +@end quotation +@end copying + +@titlepage +@title Org Mode Manual + +@subtitle Release @value{VERSION} +@author by Carsten Dominik + +@c The following two commands start the copyright page. +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@c Output the table of contents at the beginning. +@contents + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Org Mode Manual + +@insertcopying +@end ifnottex + +@menu +* Introduction:: Getting started +* Document structure:: A tree works like your brain +* Tables:: Pure magic for quick formatting +* Hyperlinks:: Notes in context +* TODO items:: Every tree branch can be a TODO item +* Tags:: Tagging headlines and matching sets of tags +* Properties and columns:: +* Timestamps:: Assign date and time to items +* Agenda views:: Collecting information into views +* Embedded LaTeX:: LaTeX fragments and formulas +* Exporting:: Sharing and publishing of notes +* Publishing:: Create a web site of linked Org-mode files +* Miscellaneous:: All the rest which did not fit elsewhere +* Extensions and Hacking:: It is possible to write add-on code +* History and Acknowledgments:: How Org-mode came into being +* Index:: The fast road to specific information +* Key Index:: Key bindings and where they are described + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Summary:: Brief summary of what Org-mode does +* Installation:: How to install a downloaded version of Org-mode +* Activation:: How to activate Org-mode for certain buffers. +* Feedback:: Bug reports, ideas, patches etc. + +Document Structure + +* Outlines:: Org-mode is based on outline-mode +* Headlines:: How to typeset org-tree headlines +* Visibility cycling:: Show and hide, much simplified +* Motion:: Jumping to other headlines +* Structure editing:: Changing sequence and level of headlines +* Archiving:: Move done task trees to a different place +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Drawers:: Tucking stuff away +* orgstruct-mode:: Structure editing outside Org-mode + +Archiving + +* ARCHIVE tag:: Marking a tree as inactive +* Moving subtrees:: Moving a tree to an archive file + +Tables + +* Built-in table editor:: Simple tables +* Narrow columns:: Stop wasting space in tables +* Column groups:: Grouping to trigger vertical lines +* orgtbl-mode:: The table editor as minor mode +* The spreadsheet:: The table editor has spreadsheet capabilities. + +The spreadsheet + +* References:: How to refer to another field or range +* Formula syntax for Calc:: Using Calc to compute stuff +* Formula syntax for Lisp:: Writing formulas in Emacs Lisp +* Field formulas:: Formulas valid for a single field +* Column formulas:: Formulas valid for an entire column +* Editing and debugging formulas:: Fixing formulas +* Updating the table:: Recomputing all dependent fields +* Advanced features:: Field names, parameters and automatic recalc + +Hyperlinks + +* Link format:: How links in Org-mode are formatted +* Internal links:: Links to other places in the current file +* External links:: URL-like links to the world +* Handling links:: Creating, inserting and following +* Using links outside Org-mode:: Linking from my C source code? +* Link abbreviations:: Shortcuts for writing complex links +* Search options:: Linking to a specific location +* Custom searches:: When the default search is not enough +* Remember:: Org-trees store quick notes + +Internal links + +* Radio targets:: Make targets trigger links in plain text. + +Remember + +* Setting up remember:: Some code for .emacs to get things going +* Remember templates:: Define the outline of different note types +* Storing notes:: Directly get the note to where it belongs + +TODO items + +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists + +Extended use of TODO keywords + +* Workflow states:: From TODO to DONE in steps +* TODO types:: I do this, Fred the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Per file keywords:: Different files, different requirements + +Tags + +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags + +Properties and Columns + +* Property syntax:: How properties are spelled out +* Special properties:: Access to other Org-mode features +* Property searches:: Matching property values +* Column view:: Tabular viewing and editing +* Property API:: Properties for Lisp programmers + +Column View + +* Defining columns:: The COLUMNS format property +* Using column view:: How to create and use column view + +Defining Columns + +* Scope of column definitions:: Where defined, where valid? +* Column attributes:: Appearance and content of a column + +Timestamps + +* Time stamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Progress logging:: Documenting when what work was done. + +Creating timestamps + +* The date/time prompt:: How org-mode helps you entering date and time +* Custom time format:: Making dates look differently + +Deadlines and Scheduling + +* Inserting deadline/schedule:: Planning items +* Repeated tasks:: Items that show up again and again + +Progress Logging + +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Clocking work time:: When exactly did you work on this item? + +Agenda Views + +* Agenda files:: Files being searched for agenda information +* Agenda dispatcher:: Keyboard access to agenda views +* Built-in agenda views:: What is available out of the box? +* Presentation and sorting:: How agenda items are prepared for display +* Agenda commands:: Remote editing of org trees +* Custom agenda views:: Defining special searches and views + +The built-in agenda views + +* Weekly/Daily agenda:: The calendar page with current tasks +* Global TODO list:: All unfinished action items +* Matching tags and properties:: Structured information with fine-tuned search +* Timeline:: Time-sorted view for single file +* Stuck projects:: Find projects you need to review + +Presentation and sorting + +* Categories:: Not all tasks are equal +* Time-of-day specifications:: How the agenda knows the time +* Sorting of agenda items:: The order of things + +Custom agenda views + +* Storing searches:: Type once, use often +* Block agenda:: All the stuff you need in a single buffer +* Setting Options:: Changing the rules +* Exporting Agenda Views:: Writing agendas to files. +* Extracting Agenda Information for other programs:: + +Embedded LaTeX + +* Math symbols:: TeX macros for symbols and Greek letters +* Subscripts and Superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Processing LaTeX fragments:: Previewing LaTeX processing +* CDLaTeX mode:: Speed up entering of formulas + +Exporting + +* ASCII export:: Exporting to plain ASCII +* HTML export:: Exporting to HTML +* LaTeX export:: Exporting to LaTeX +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format +* Text interpretation:: How the exporter looks at the file + +HTML export + +* HTML Export commands:: How to invoke LaTeX export +* Quoting HTML tags:: Using direct HTML in Org-mode +* Links:: Transformation of links for HTML +* Images:: How to include images +* CSS support:: Changing the appearence of the output + +LaTeX export + +* LaTeX export commands:: How to invoke LaTeX export +* Quoting LaTeX code:: Incorporating literal LaTeX code + +Text interpretation by the exporter + +* Comment lines:: Some lines will not be exported +* Initial text:: Text before the first headline +* Footnotes:: Numbers like [1] +* Enhancing text:: Subscripts, symbols and more +* Export options:: How to influence the export settings + +Publishing + +* Configuration:: Defining projects +* Sample configuration:: Example projects +* Triggering publication:: Publication commands + +Configuration + +* Project alist:: The central configuration variable +* Sources and destinations:: From here to there +* Selecting files:: What files are part of the project? +* Publishing action:: Setting the function doing the publishing +* Publishing options:: Tweaking HTML export +* Publishing links:: Which links keep working after publishing? +* Project page index:: Publishing a list of project files + +Sample configuration + +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example + +Miscellaneous + +* Completion:: M-TAB knows what you need +* Customization:: Adapting Org-mode to your taste +* In-buffer settings:: Overview of the #+KEYWORDS +* The very busy C-c C-c key:: When in doubt, press C-c C-c +* Clean view:: Getting rid of leading stars in the outline +* TTY keys:: Using Org-mode on a tty +* Interaction:: Other Emacs packages +* Bugs:: Things which do not work perfectly + +Interaction with other packages + +* Cooperation:: Packages Org-mode cooperates with +* Conflicts:: Packages that lead to conflicts + +Extensions, Hooks and Hacking + +* Extensions:: Existing 3rd-part extensions +* Adding hyperlink types:: New custom link types +* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs +* Dynamic blocks:: Automatically filled blocks +* Special agenda views:: Customized views +* Using the property API:: Writing programs that use entry properties + +Tables in arbitrary syntax + +* Radio tables:: Sending and receiving +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify + +@end detailmenu +@end menu + +@node Introduction, Document structure, Top, Top +@chapter Introduction +@cindex introduction + +@menu +* Summary:: Brief summary of what Org-mode does +* Installation:: How to install a downloaded version of Org-mode +* Activation:: How to activate Org-mode for certain buffers. +* Feedback:: Bug reports, ideas, patches etc. +@end menu + +@node Summary, Installation, Introduction, Introduction +@section Summary +@cindex summary + +Org-mode is a mode for keeping notes, maintaining TODO lists, and doing +project planning with a fast and effective plain-text system. + +Org-mode develops organizational tasks around NOTES files that contain +lists or information about projects as plain text. Org-mode is +implemented on top of outline-mode, which makes it possible to keep the +content of large files well structured. Visibility cycling and +structure editing help to work with the tree. Tables are easily created +with a built-in table editor. Org-mode supports TODO items, deadlines, +time stamps, and scheduling. It dynamically compiles entries into an +agenda that utilizes and smoothly integrates much of the Emacs calendar +and diary. Plain text URL-like links connect to websites, emails, +Usenet messages, BBDB entries, and any files related to the projects. +For printing and sharing of notes, an Org-mode file can be exported as a +structured ASCII file, as HTML, or (todo and agenda items only) as an +iCalendar file. It can also serve as a publishing tool for a set of +linked webpages. + +An important design aspect that distinguishes Org-mode from for example +Planner/Muse is that it encourages to store every piece of information +only once. In Planner, you have project pages, day pages and possibly +other files, duplicating some information such as tasks. In Org-mode, +you only have notes files. In your notes you mark entries as tasks, +label them with tags and timestamps. All necessary lists like a +schedule for the day, the agenda for a meeting, tasks lists selected by +tags etc are created dynamically when you need them. + +Org-mode keeps simple things simple. When first fired up, it should +feel like a straightforward, easy to use outliner. Complexity is not +imposed, but a large amount of functionality is available when you need +it. Org-mode is a toolbox and can be used in different ways, for +example as: + +@example +@r{@bullet{} outline extension with visibility cycling and structure editing} +@r{@bullet{} ASCII system and table editor for taking structured notes} +@r{@bullet{} ASCII table editor with spreadsheet-like capabilities} +@r{@bullet{} TODO list editor} +@r{@bullet{} full agenda and planner with deadlines and work scheduling} +@r{@bullet{} environment to implement David Allen's GTD system} +@r{@bullet{} a basic database application} +@r{@bullet{} simple hypertext system, with HTML export} +@r{@bullet{} publishing tool to create a set of interlinked webpages} +@end example + +Org-mode's automatic, context sensitive table editor with spreadsheet +capabilities can be integrated into any major mode by activating the +minor Orgtbl-mode. Using a translation step, it can be used to maintain +tables in arbitrary file types, for example in La@TeX{}. The structure +editing and list creation capabilities can be used outside Org-mode with +the minor Orgstruct-mode. + +@cindex FAQ +There is a website for Org-mode which provides links to the newest +version of Org-mode, as well as additional information, frequently asked +questions (FAQ), links to tutorials etc. This page is located at +@uref{http://www.astro.uva.nl/~dominik/Tools/org/}. + +@page + + +@node Installation, Activation, Summary, Introduction +@section Installation +@cindex installation +@cindex XEmacs + +@b{Important:} @i{If Org-mode is part of the Emacs distribution or an +XEmacs package, please skip this section and go directly to +@ref{Activation}.} + +If you have downloaded Org-mode from the Web, you must take the +following steps to install it: Go into the Org-mode distribution +directory and edit the top section of the file @file{Makefile}. You +must set the name of the Emacs binary (likely either @file{emacs} or +@file{xemacs}), and the paths to the directories where local Lisp and +Info files are kept. If you don't have access to the system-wide +directories, create your own two directories for these files, enter them +into the Makefile, and make sure Emacs finds the Lisp files by adding +the following line to @file{.emacs}: + +@example +(setq load-path (cons "~/path/to/lispdir" load-path)) +@end example + +@b{XEmacs users now need to install the file @file{noutline.el} from +the @file{xemacs} subdirectory of the Org-mode distribution. Use the +command:} + +@example +@b{make install-noutline} +@end example + +@noindent Now byte-compile and install the Lisp files with the shell +commands: + +@example +make +make install +@end example + +@noindent If you want to install the info documentation, use this command: + +@example +make install-info +@end example + +@noindent Then add to @file{.emacs}: + +@lisp +;; This line only if org-mode is not part of the X/Emacs distribution. +(require 'org-install) +@end lisp + +@node Activation, Feedback, Installation, Introduction +@section Activation +@cindex activation +@cindex autoload +@cindex global keybindings +@cindex keybindings, global + +@iftex +@b{Important:} @i{If you use copy-and-paste to copy lisp code from the +PDF documentation as viewed by Acrobat reader to your .emacs file, the +single quote character comes out incorrectly and the code will not work. +You need to fix the single quotes by hand, or copy from Info +documentation.} +@end iftex + +Add the following lines to your @file{.emacs} file. The last two lines +define @emph{global} keys for the commands @command{org-store-link} and +@command{org-agenda} - please choose suitable keys yourself. + +@lisp +;; The following lines are always needed. Choose your own keys. +(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) +(global-set-key "\C-cl" 'org-store-link) +(global-set-key "\C-ca" 'org-agenda) +@end lisp + +Furthermore, you must activate @code{font-lock-mode} in org-mode +buffers, because significant functionality depends on font-locking being +active. You can do this with either one of the following two lines +(XEmacs user must use the second option): +@lisp +(global-font-lock-mode 1) ; for all buffers +(add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only +@end lisp + +@cindex org-mode, turning on +With this setup, all files with extension @samp{.org} will be put +into Org-mode. As an alternative, make the first line of a file look +like this: + +@example +MY PROJECTS -*- mode: org; -*- +@end example + +@noindent which will select Org-mode for this buffer no matter what +the file's name is. See also the variable +@code{org-insert-mode-line-in-empty-file}. + +@node Feedback, , Activation, Introduction +@section Feedback +@cindex feedback +@cindex bug reports +@cindex maintainer +@cindex author + +If you find problems with Org-mode, or if you have questions, remarks, +or ideas about it, please contact the maintainer @value{MAINTAINER} at +@value{MAINTAINEREMAIL}. + +For bug reports, please provide as much information as possible, +including the version information of Emacs (@kbd{C-h v emacs-version +@key{RET}}) and Org-mode (@kbd{C-h v org-version @key{RET}}), as well as +the Org-mode related setup in @file{.emacs}. If an error occurs, a +backtrace can be very useful (see below on how to create one). Often a +small example file helps, along with clear information about: + +@enumerate +@item What exactly did you do? +@item What did you expect to happen? +@item What happened instead? +@end enumerate +@noindent Thank you for helping to improve this mode. + +@subsubheading How to create a useful backtrace + +@cindex backtrace of an error +If working with Org-mode produces an error with a message you don't +understand, you may have hit a bug. The best way to report this is by +providing, in addition to what was mentioned above, a @emph{Backtrace}. +This is information from the built-in debugger about where and how the +error occurred. Here is how to produce a useful backtrace: + +@enumerate +@item +Start a fresh Emacs or XEmacs, and make sure that it will load the +original Lisp code in @file{org.el} instead of the compiled version in +@file{org.elc}. The backtrace contains much more information if it is +produced with uncompiled code. To do this, either rename @file{org.elc} +to something else before starting Emacs, or ask Emacs explicitly to load +@file{org.el} by using the command line +@example +emacs -l /path/to/org.el +@end example +@item +Go to the @code{Options} menu and select @code{Enter Debugger on Error} +(XEmacs has this option in the @code{Troubleshooting} sub-menu). +@item +Do whatever you have to do to hit the error. Don't forget to +document the steps you take. +@item +When you hit the error, a @file{*Backtrace*} buffer will appear on the +screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and +attach it to your bug report. +@end enumerate + +@node Document structure, Tables, Introduction, Top +@chapter Document Structure +@cindex document structure +@cindex structure of document + +Org-mode is based on outline mode and provides flexible commands to +edit the structure of the document. + +@menu +* Outlines:: Org-mode is based on outline-mode +* Headlines:: How to typeset org-tree headlines +* Visibility cycling:: Show and hide, much simplified +* Motion:: Jumping to other headlines +* Structure editing:: Changing sequence and level of headlines +* Archiving:: Move done task trees to a different place +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Drawers:: Tucking stuff away +* orgstruct-mode:: Structure editing outside Org-mode +@end menu + +@node Outlines, Headlines, Document structure, Document structure +@section Outlines +@cindex outlines +@cindex outline-mode + +Org-mode is implemented on top of outline-mode. Outlines allow a +document to be organized in a hierarchical structure, which (at least +for me) is the best representation of notes and thoughts. An overview +of this structure is achieved by folding (hiding) large parts of the +document to show only the general document structure and the parts +currently being worked on. Org-mode greatly simplifies the use of +outlines by compressing the entire show/hide functionality into a single +command @command{org-cycle}, which is bound to the @key{TAB} key. + +@node Headlines, Visibility cycling, Outlines, Document structure +@section Headlines +@cindex headlines +@cindex outline tree + +Headlines define the structure of an outline tree. The headlines in +Org-mode start with one or more stars, on the left margin@footnote{See +the variable @code{org-special-ctrl-a/e} to configure special behavior +of @kbd{C-a} and @kbd{C-e} in headlines.}. For example: + +@example +* Top level headline +** Second level +*** 3rd level + some text +*** 3rd level + more text + +* Another top level headline +@end example + +@noindent Some people find the many stars too noisy and would prefer an +outline that has whitespace followed by a single star as headline +starters. @ref{Clean view} describes a setup to realize this. + +An empty line after the end of a subtree is considered part of it and +will be hidden when the subtree is folded. However, if you leave at +least two empty lines, one empty line will remain visible after folding +the subtree, in order to structure the collapsed view. See the +variable @code{org-cycle-separator-lines} to modify this behavior. + +@node Visibility cycling, Motion, Headlines, Document structure +@section Visibility cycling +@cindex cycling, visibility +@cindex visibility cycling +@cindex trees, visibility +@cindex show hidden text +@cindex hide text + +Outlines make it possible to hide parts of the text in the buffer. +Org-mode uses just two commands, bound to @key{TAB} and +@kbd{S-@key{TAB}} to change the visibility in the buffer. + +@cindex subtree visibility states +@cindex subtree cycling +@cindex folded, subtree visibility state +@cindex children, subtree visibility state +@cindex subtree, subtree visibility state +@table @kbd +@kindex @key{TAB} +@item @key{TAB} +@emph{Subtree cycling}: Rotate current subtree among the states + +@example +,-> FOLDED -> CHILDREN -> SUBTREE --. +'-----------------------------------' +@end example + +The cursor must be on a headline for this to work@footnote{see, however, +the option @code{org-cycle-emulate-tab}.}. When the cursor is at the +beginning of the buffer and the first line is not a headline, then +@key{TAB} actually runs global cycling (see below)@footnote{see the +option @code{org-cycle-global-at-bob}.}. Also when called with a prefix +argument (@kbd{C-u @key{TAB}}), global cycling is invoked. + +@cindex global visibility states +@cindex global cycling +@cindex overview, global visibility state +@cindex contents, global visibility state +@cindex show all, global visibility state +@kindex S-@key{TAB} +@item S-@key{TAB} +@itemx C-u @key{TAB} +@emph{Global cycling}: Rotate the entire buffer among the states + +@example +,-> OVERVIEW -> CONTENTS -> SHOW ALL --. +'--------------------------------------' +@end example + +When @kbd{S-@key{TAB}} is called with a numerical prefix N, the CONTENTS +view up to headlines of level N will be shown. +Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field. + +@cindex show all, command +@kindex C-c C-a +@item C-c C-a +Show all. +@kindex C-c C-r +@item C-c C-r +Reveal context around point, showing the current entry, the following +heading and the hierarchy above. Useful for working near a location +exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda +command (@pxref{Agenda commands}). With prefix arg show, on each +level, all sibling headings. +@kindex C-c C-x b +@item C-c C-x b +Show the current subtree in an indirect buffer@footnote{The indirect +buffer +@ifinfo +(@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) +@end ifinfo +@ifnotinfo +(see the Emacs manual for more information about indirect buffers) +@end ifnotinfo +will contain the entire buffer, but will be narrowed to the current +tree. Editing the indirect buffer will also change the original buffer, +but without affecting visibility in that buffer.}. With numerical +prefix ARG, go up to this level and then take that tree. If ARG is +negative, go up that many levels. With @kbd{C-u} prefix, do not remove +the previously used indirect buffer. +@end table + +When Emacs first visits an Org-mode file, the global state is set to +OVERVIEW, i.e. only the top level headlines are visible. This can be +configured through the variable @code{org-startup-folded}, or on a +per-file basis by adding one of the following lines anywhere in the +buffer: + +@example +#+STARTUP: overview +#+STARTUP: content +#+STARTUP: showall +@end example + +@node Motion, Structure editing, Visibility cycling, Document structure +@section Motion +@cindex motion, between headlines +@cindex jumping, to headlines +@cindex headline navigation +The following commands jump to other headlines in the buffer. + +@table @kbd +@kindex C-c C-n +@item C-c C-n +Next heading. +@kindex C-c C-p +@item C-c C-p +Previous heading. +@kindex C-c C-f +@item C-c C-f +Next heading same level. +@kindex C-c C-b +@item C-c C-b +Previous heading same level. +@kindex C-c C-u +@item C-c C-u +Backward to higher level heading. +@kindex C-c C-j +@item C-c C-j +Jump to a different place without changing the current outline +visibility. Shows the document structure in a temporary buffer, where +you can use the following keys to find your destination: +@example +@key{TAB} @r{Cycle visibility.} +@key{down} / @key{up} @r{Next/previous visible headline.} +n / p @r{Next/previous visible headline.} +f / b @r{Next/previous headline same level.} +u @r{One level up.} +0-9 @r{Digit argument.} +@key{RET} @r{Select this location.} +@end example +@end table + +@node Structure editing, Archiving, Motion, Document structure +@section Structure editing +@cindex structure editing +@cindex headline, promotion and demotion +@cindex promotion, of subtrees +@cindex demotion, of subtrees +@cindex subtree, cut and paste +@cindex pasting, of subtrees +@cindex cutting, of subtrees +@cindex copying, of subtrees +@cindex subtrees, cut and paste + +@table @kbd +@kindex M-@key{RET} +@item M-@key{RET} +Insert new heading with same level as current. If the cursor is in a +plain list item, a new item is created (@pxref{Plain lists}). To force +creation of a new headline, use a prefix arg, or first press @key{RET} +to get to the beginning of the next line. When this command is used in +the middle of a line, the line is split and the rest of the line becomes +the new headline. If the command is used at the beginning of a +headline, the new headline is created before the current line. If at +the beginning of any other line, the content of that line is made the +new heading. If the command is used at the end of a folded subtree +(i.e. behind the ellipses at the end of a headline), then a headline +like the current one will be inserted after the end of the subtree. +@kindex M-S-@key{RET} +@item M-S-@key{RET} +Insert new TODO entry with same level as current heading. +@kindex M-@key{left} +@item M-@key{left} +Promote current heading by one level. +@kindex M-@key{right} +@item M-@key{right} +Demote current heading by one level. +@kindex M-S-@key{left} +@item M-S-@key{left} +Promote the current subtree by one level. +@kindex M-S-@key{right} +@item M-S-@key{right} +Demote the current subtree by one level. +@kindex M-S-@key{up} +@item M-S-@key{up} +Move subtree up (swap with previous subtree of same +level). +@kindex M-S-@key{down} +@item M-S-@key{down} +Move subtree down (swap with next subtree of same level). +@kindex C-c C-x C-w +@kindex C-c C-x C-k +@item C-c C-x C-w +@itemx C-c C-x C-k +Kill subtree, i.e. remove it from buffer but save in kill ring. +@kindex C-c C-x M-w +@item C-c C-x M-w +Copy subtree to kill ring. +@kindex C-c C-x C-y +@item C-c C-x C-y +Yank subtree from kill ring. This does modify the level of the subtree to +make sure the tree fits in nicely at the yank position. The yank +level can also be specified with a prefix arg, or by yanking after a +headline marker like @samp{****}. +@kindex C-c ^ +@item C-c ^ +Sort same-level entries. When there is an active region, all entries in +the region will be sorted. Otherwise the children of the current +headline are sorted. The command prompts for the sorting method, which +can be alphabetically, numerically, by time (using the first time stamp +in each entry), by priority, and each of these in reverse order. With a +@kbd{C-u} prefix, sorting will be case-sensitive. With two @kbd{C-u +C-u} prefixes, duplicate entries will also be removed. +@end table + +@cindex region, active +@cindex active region +@cindex transient-mark-mode +When there is an active region (transient-mark-mode), promotion and +demotion work on all headlines in the region. To select a region of +headlines, it is best to place both point and mark at the beginning of a +line, mark at the beginning of the first headline, and point at the line +just after the last headline to change. Note that when the cursor is +inside a table (@pxref{Tables}), the Meta-Cursor keys have different +functionality. + +@node Archiving, Sparse trees, Structure editing, Document structure +@section Archiving +@cindex archiving + +When a project represented by a (sub)tree is finished, you may want +to move the tree out of the way and to stop it from contributing to the +agenda. Org-mode knows two ways of archiving. You can mark a tree with +the ARCHIVE tag, or you can move an entire (sub)tree to a different +location. + +@menu +* ARCHIVE tag:: Marking a tree as inactive +* Moving subtrees:: Moving a tree to an archive file +@end menu + +@node ARCHIVE tag, Moving subtrees, Archiving, Archiving +@subsection The ARCHIVE tag +@cindex internal archiving + +A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at +its location in the outline tree, but behaves in the following way: +@itemize @minus +@item +It does not open when you attempt to do so with a visibility cycling +command (@pxref{Visibility cycling}). You can force cycling archived +subtrees with @kbd{C-@key{TAB}}, or by setting the option +@code{org-cycle-open-archived-trees}. Also normal outline commands like +@code{show-all} will open archived subtrees. +@item +During sparse tree construction (@pxref{Sparse trees}), matches in +archived subtrees are not exposed, unless you configure the option +@code{org-sparse-tree-open-archived-trees}. +@item +During agenda view construction (@pxref{Agenda views}), the content of +archived trees is ignored unless you configure the option +@code{org-agenda-skip-archived-trees}. +@item +Archived trees are not exported (@pxref{Exporting}), only the headline +is. Configure the details using the variable +@code{org-export-with-archived-trees}. +@end itemize + +The following commands help managing the ARCHIVE tag: + +@table @kbd +@kindex C-c C-x C-a +@item C-c C-x C-a +Toggle the ARCHIVE tag for the current headline. When the tag is set, +the headline changes to a shadowish face, and the subtree below it is +hidden. +@kindex C-u C-c C-x C-a +@item C-u C-c C-x C-a +Check if any direct children of the current headline should be archived. +To do this, each subtree is checked for open TODO entries. If none are +found, the command offers to set the ARCHIVE tag for the child. If the +cursor is @emph{not} on a headline when this command is invoked, the +level 1 trees will be checked. +@kindex C-@kbd{TAB} +@item C-@kbd{TAB} +Cycle a tree even if it is tagged with ARCHIVE. +@end table + +@node Moving subtrees, , ARCHIVE tag, Archiving +@subsection Moving subtrees +@cindex external archiving + +Once an entire project is finished, you may want to move it to a +different location, either in the current file, or even in a different +file, the archive file. + +@table @kbd +@kindex C-c C-x C-s +@item C-c C-x C-s +Archive the subtree starting at the cursor position to the location +given by @code{org-archive-location}. Context information that could be +lost like the file name, the category, inherited tags, and the todo +state will be store as properties in the entry. +@kindex C-u C-c C-x C-s +@item C-u C-c C-x C-s +Check if any direct children of the current headline could be moved to +the archive. To do this, each subtree is checked for open TODO entries. +If none are found, the command offers to move it to the archive +location. If the cursor is @emph{not} on a headline when this command +is invoked, the level 1 trees will be checked. +@end table + +@cindex archive locations +The default archive location is a file in the same directory as the +current file, with the name derived by appending @file{_archive} to the +current file name. For information and examples on how to change this, +see the documentation string of the variable +@code{org-archive-location}. There is also an in-buffer option for +setting this variable, for example + +@example +#+ARCHIVE: %s_done:: +@end example + +@noindent +You may have several such lines in the buffer, they will then be valid +for the entries following the line (the first will also apply to any +text before it). + +@node Sparse trees, Plain lists, Archiving, Document structure +@section Sparse trees +@cindex sparse trees +@cindex trees, sparse +@cindex folding, sparse trees +@cindex occur, command + +An important feature of Org-mode is the ability to construct +@emph{sparse trees} for selected information in an outline tree. A +sparse tree means that the entire document is folded as much as +possible, but the selected information is made visible along with the +headline structure above it@footnote{See also the variables +@code{org-show-hierarchy-above}, @code{org-show-following-heading}, and +@code{org-show-siblings} for detailed control on how much context is +shown around each match.}. Just try it out and you will see immediately +how it works. + +Org-mode contains several commands creating such trees. The most +basic one is @command{org-occur}: + +@table @kbd +@kindex C-c / +@item C-c / +Occur. Prompts for a regexp and shows a sparse tree with all matches. +If the match is in a headline, the headline is made visible. If the +match is in the body of an entry, headline and body are made visible. +In order to provide minimal context, also the full hierarchy of +headlines above the match is shown, as well as the headline following +the match. Each match is also highlighted; the highlights disappear +when the buffer is changed by an editing command, or by pressing +@kbd{C-c C-c}. When called with a @kbd{C-u} prefix argument, previous +highlights are kept, so several calls to this command can be stacked. +@end table +@noindent +For frequently used sparse trees of specific search strings, you can +use the variable @code{org-agenda-custom-commands} to define fast +keyboard access to specific sparse trees. These commands will then be +accessible through the agenda dispatcher (@pxref{Agenda dispatcher}). +For example: + +@lisp +(setq org-agenda-custom-commands + '(("f" occur-tree "FIXME"))) +@end lisp + +@noindent will define the key @kbd{C-c a f} as a shortcut for creating +a sparse tree matching the string @samp{FIXME}. + +Other commands use sparse trees as well. For example @kbd{C-c +C-v} creates a sparse TODO tree (@pxref{TODO basics}). + +@kindex C-c C-e v +@cindex printing sparse trees +@cindex visible text, printing +To print a sparse tree, you can use the Emacs command +@code{ps-print-buffer-with-faces} which does not print invisible parts +of the document @footnote{This does not work under XEmacs, because +XEmacs uses selective display for outlining, not text properties.}. +Or you can use the command @kbd{C-c C-e v} to export only the visible +part of the document and print the resulting file. + +@node Plain lists, Drawers, Sparse trees, Document structure +@section Plain lists +@cindex plain lists +@cindex lists, plain +@cindex lists, ordered +@cindex ordered lists + +Within an entry of the outline tree, hand-formatted lists can provide +additional structure. They also provide a way to create lists of +checkboxes (@pxref{Checkboxes}). Org-mode supports editing such lists, +and the HTML exporter (@pxref{Exporting}) does parse and format them. + +Org-mode knows ordered and unordered lists. Unordered list items start +with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a +bullet, lines must be indented or they will be seen as top-level +headlines. Also, when you are hiding leading stars to get a clean +outline view, plain list items starting with a star are visually +indistinguishable from true headlines. In short: even though @samp{*} +is supported, it may be better not to use it for plain list items.} as +bullets. Ordered list items start with @samp{1.} or @samp{1)}. Items +belonging to the same list must have the same indentation on the first +line. In particular, if an ordered list reaches number @samp{10.}, then +the 2--digit numbers must be written left-aligned with the other numbers +in the list. Indentation also determines the end of a list item. It +ends before the next line that is indented like the bullet/number, or +less. Empty lines are part of the previous item, so you can have +several paragraphs in one item. If you would like an empty line to +terminate all currently open plain lists, configure the variable +@code{org-empty-line-terminates-plain-lists}. Here is an example: + +@example +@group +** Lord of the Rings + My favorite scenes are (in this order) + 1. The attack of the Rohirrim + 2. Eowyns fight with the witch king + + this was already my favorite scene in the book + + I really like Miranda Otto. + 3. Peter Jackson being shot by Legolas + - on DVD only + He makes a really funny face when it happens. + But in the end, not individual scenes matter but the film as a whole. +@end group +@end example + +Org-mode supports these lists by tuning filling and wrapping commands to +deal with them correctly@footnote{Org-mode only changes the filling +settings for Emacs. For XEmacs, you should use Kyle E. Jones' +@file{filladapt.el}. To turn this on, put into @file{.emacs}: +@code{(require 'filladapt)}}. + +The following commands act on items when the cursor is in the first line +of an item (the line with the bullet or number). + +@table @kbd +@kindex @key{TAB} +@item @key{TAB} +Items can be folded just like headline levels if you set the variable +@code{org-cycle-include-plain-lists}. The level of an item is then +given by the indentation of the bullet/number. Items are always +subordinate to real headlines, however; the hierarchies remain +completely separated. + +If @code{org-cycle-include-plain-lists} has not been set, @key{TAB} +fixes the indentation of the curent line in a heuristic way. +@kindex M-@key{RET} +@item M-@key{RET} +Insert new item at current level. With prefix arg, force a new heading +(@pxref{Structure editing}). If this command is used in the middle of a +line, the line is @emph{split} and the rest of the line becomes the new +item. If this command is executed in the @emph{whitespace before a bullet or +number}, the new item is created @emph{before} the current item. If the +command is executed in the white space before the text that is part of +an item but does not contain the bullet, a bullet is added to the +current line. +@kindex M-S-@key{RET} +@item M-S-@key{RET} +Insert a new item with a checkbox (@pxref{Checkboxes}). +@kindex S-@key{up} +@kindex S-@key{down} +@item S-@key{up} +@itemx S-@key{down} +Jump to the previous/next item in the current list. +@kindex M-S-@key{up} +@kindex M-S-@key{down} +@item M-S-@key{up} +@itemx M-S-@key{down} +Move the item including subitems up/down (swap with previous/next item +of same indentation). If the list is ordered, renumbering is +automatic. +@kindex M-S-@key{left} +@kindex M-S-@key{right} +@item M-S-@key{left} +@itemx M-S-@key{right} +Decrease/increase the indentation of the item, including subitems. +Initially, the item tree is selected based on current indentation. +When these commands are executed several times in direct succession, +the initially selected region is used, even if the new indentation +would imply a different hierarchy. To use the new hierarchy, break +the command chain with a cursor motion or so. +@kindex C-c C-c +@item C-c C-c +If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the +state of the checkbox. If not, make this command makes sure that all +the items on this list level use the same bullet. Furthermore, if this +is an ordered list, make sure the numbering is ok. +@kindex C-c - +@item C-c - +Cycle the entire list level through the different itemize/enumerate +bullets (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). +With prefix arg, select the nth bullet from this list. +@end table + +@node Drawers, orgstruct-mode, Plain lists, Document structure +@section Drawers +@cindex drawers +@cindex visibility cycling, drawers + +Sometimes you want to keep information associated with an entry, but you +normally don't want to see it. For this, Org-mode has @emph{drawers}. +Drawers need to be configured with the variable @code{org-drawers}, and +look like this: + +@example +** This is a headline + Still outside the drawer + :DRAWERNAME: + This is inside the drawer. + :END: + After the drawer. +@end example + +Visibility cycling (@pxref{Visibility cycling}) on the headline will +hide and show the entry, but keep the drawer collapsed to a single line. +In order to look inside the drawer, you need to move the cursor to the +drawer line and press @key{TAB} there. Org-mode uses a drawer for +storing properties (@pxref{Properties and columns}). + +@node orgstruct-mode, , Drawers, Document structure +@section The Orgstruct minor mode +@cindex orgstruct-mode +@cindex minor mode for structure editing + +If you like the intuitive way the Org-mode structure editing and list +formatting works, you might want to use these commands in other modes +like text-mode or mail-mode as well. The minor mode Orgstruct-mode +makes this possible. You can always toggle the mode with @kbd{M-x +orgstruct-mode}. To turn it on by default, for example in mail mode, +use + +@lisp +(add-hook 'mail-mode-hook 'turn-on-orgstruct) +@end lisp + +When this mode is active and the cursor is on a line that looks to +Org-mode like a headline of the first line of a list item, most +structure editing commands will work, even if the same keys normally +have different functionality in the major mode you are using. If the +cursor is not in one of those special lines, Orgstruct-mode lurks +silently in the shadow. + +@node Tables, Hyperlinks, Document structure, Top +@chapter Tables +@cindex tables +@cindex editing tables + +Org-mode has a very fast and intuitive table editor built-in. +Spreadsheet-like calculations are supported in connection with the +Emacs @file{calc} package. + +@menu +* Built-in table editor:: Simple tables +* Narrow columns:: Stop wasting space in tables +* Column groups:: Grouping to trigger vertical lines +* orgtbl-mode:: The table editor as minor mode +* The spreadsheet:: The table editor has spreadsheet capabilities. +@end menu + +@node Built-in table editor, Narrow columns, Tables, Tables +@section The built-in table editor +@cindex table editor, built-in + +Org-mode makes it easy to format tables in plain ASCII. Any line with +@samp{|} as the first non-whitespace character is considered part of a +table. @samp{|} is also the column separator. A table might look like +this: + +@example +| Name | Phone | Age | +|-------+-------+-----| +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +@end example + +A table is re-aligned automatically each time you press @key{TAB} or +@key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to +the next field (@key{RET} to the next row) and creates new table rows +at the end of the table or before horizontal lines. The indentation +of the table is set by the first line. Any line starting with +@samp{|-} is considered as a horizontal separator line and will be +expanded on the next re-align to span the whole table width. So, to +create the above table, you would only type + +@example +|Name|Phone|Age| +|- +@end example + +@noindent and then press @key{TAB} to align the table and start filling in +fields. + +When typing text into a field, Org-mode treats @key{DEL}, +@key{Backspace}, and all character keys in a special way, so that +inserting and deleting avoids shifting other fields. Also, when +typing @emph{immediately after the cursor was moved into a new field +with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the +field is automatically made blank. If this behavior is too +unpredictable for you, configure the variables +@code{org-enable-table-editor} and @code{org-table-auto-blank-field}. + +@table @kbd +@tsubheading{Creation and conversion} +@kindex C-c | +@item C-c | +Convert the active region to table. If every line contains at least one +TAB character, the function assumes that the material is tab separated. +If not, lines are split at whitespace into fields. You can use a prefix +argument to indicate the minimum number of consecutive spaces required +to identify a field separator (default: just one).@* +If there is no active region, this command creates an empty Org-mode +table. But it's easier just to start typing, like +@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}. + +@tsubheading{Re-aligning and field motion} +@kindex C-c C-c +@item C-c C-c +Re-align the table without moving the cursor. +@c +@kindex @key{TAB} +@item @key{TAB} +Re-align the table, move to the next field. Creates a new row if +necessary. +@c +@kindex S-@key{TAB} +@item S-@key{TAB} +Re-align, move to previous field. +@c +@kindex @key{RET} +@item @key{RET} +Re-align the table and move down to next row. Creates a new row if +necessary. At the beginning or end of a line, @key{RET} still does +NEWLINE, so it can be used to split a table. + +@tsubheading{Column and row editing} +@kindex M-@key{left} +@kindex M-@key{right} +@item M-@key{left} +@itemx M-@key{right} +Move the current column left/right. +@c +@kindex M-S-@key{left} +@item M-S-@key{left} +Kill the current column. +@c +@kindex M-S-@key{right} +@item M-S-@key{right} +Insert a new column to the left of the cursor position. +@c +@kindex M-@key{up} +@kindex M-@key{down} +@item M-@key{up} +@itemx M-@key{down} +Move the current row up/down. +@c +@kindex M-S-@key{up} +@item M-S-@key{up} +Kill the current row or horizontal line. +@c +@kindex M-S-@key{down} +@item M-S-@key{down} +Insert a new row above (with arg: below) the current row. +@c +@kindex C-c - +@item C-c - +Insert a horizontal line below current row. With prefix arg, the line +is created above the current line. +@c +@kindex C-c ^ +@item C-c ^ +Sort the table lines in the region. The position of point indicates the +column to be used for sorting, and the range of lines is the range +between the nearest horizontal separator lines, or the entire table. If +point is before the first column, you will be prompted for the sorting +column. If there is an active region, the mark specifies the first line +and the sorting column, while point should be in the last line to be +included into the sorting. The command prompts for the sorting type +(alphabetically, numerically, or by time). When called with a prefix +argument, alphabetic sorting will be case-sensitive. + +@tsubheading{Regions} +@kindex C-c C-x M-w +@item C-c C-x M-w +Copy a rectangular region from a table to a special clipboard. Point +and mark determine edge fields of the rectangle. The process ignores +horizontal separator lines. +@c +@kindex C-c C-x C-w +@item C-c C-x C-w +Copy a rectangular region from a table to a special clipboard, and +blank all fields in the rectangle. So this is the ``cut'' operation. +@c +@kindex C-c C-x C-y +@item C-c C-x C-y +Paste a rectangular region into a table. +The upper right corner ends up in the current field. All involved fields +will be overwritten. If the rectangle does not fit into the present table, +the table is enlarged as needed. The process ignores horizontal separator +lines. +@c +@kindex C-c C-q +@item C-c C-q +Wrap several fields in a column like a paragraph. If there is an active +region, and both point and mark are in the same column, the text in the +column is wrapped to minimum width for the given number of lines. A +prefix ARG may be used to change the number of desired lines. If there +is no region, the current field is split at the cursor position and the +text fragment to the right of the cursor is prepended to the field one +line down. If there is no region, but you specify a prefix ARG, the +current field is made blank, and the content is appended to the field +above. + +@tsubheading{Calculations} +@cindex formula, in tables +@cindex calculations, in tables +@cindex region, active +@cindex active region +@cindex transient-mark-mode +@kindex C-c + +@item C-c + +Sum the numbers in the current column, or in the rectangle defined by +the active region. The result is shown in the echo area and can +be inserted with @kbd{C-y}. +@c +@kindex S-@key{RET} +@item S-@key{RET} +When current field is empty, copy from first non-empty field above. +When not empty, copy current field down to next row and move cursor +along with it. Depending on the variable +@code{org-table-copy-increment}, integer field values will be +incremented during copy. This key is also used by CUA-mode +(@pxref{Cooperation}). + +@tsubheading{Miscellaneous} +@kindex C-c ` +@item C-c ` +Edit the current field in a separate window. This is useful for fields +that are not fully visible (@pxref{Narrow columns}). When called with a +@kbd{C-u} prefix, just make the full field visible, so that it can be +edited in place. +@c +@kindex C-c @key{TAB} +@item C-c @key{TAB} +This is an alias for @kbd{C-u C-c `} to make the current field fully +visible. +@c +@item M-x org-table-import +Import a file as a table. The table should be TAB- or whitespace +separated. Useful, for example, to import an Excel table or data from a +database, because these programs generally can write TAB-separated text +files. This command works by inserting the file into the buffer and +then converting the region to a table. Any prefix argument is passed on +to the converter, which uses it to determine the separator. +@item C-c | +Tables can also be imported by pasting tabular text into the org-mode +buffer, selecting the pasted text with @kbd{C-x C-x} and then using the +@kbd{C-c |} command (see above under @i{Creation and conversion}. +@c +@item M-x org-table-export +Export the table as a TAB-separated file. Useful for data exchange with, +for example, Excel or database programs. +@end table + +If you don't like the automatic table editor because it gets in your +way on lines which you would like to start with @samp{|}, you can turn +it off with + +@lisp +(setq org-enable-table-editor nil) +@end lisp + +@noindent Then the only table command that still works is +@kbd{C-c C-c} to do a manual re-align. + +@node Narrow columns, Column groups, Built-in table editor, Tables +@section Narrow columns +@cindex narrow columns in tables + +The width of columns is automatically determined by the table editor. +Sometimes a single field or a few fields need to carry more text, +leading to inconveniently wide columns. To limit@footnote{This feature +does not work on XEmacs.} the width of a column, one field anywhere in +the column may contain just the string @samp{<N>} where @samp{N} is an +integer specifying the width of the column in characters. The next +re-align will then set the width of this column to no more than this +value. + +@example +@group +|---+------------------------------| |---+--------| +| | | | | <6> | +| 1 | one | | 1 | one | +| 2 | two | ----\ | 2 | two | +| 3 | This is a long chunk of text | ----/ | 3 | This=> | +| 4 | four | | 4 | four | +|---+------------------------------| |---+--------| +@end group +@end example + +@noindent +Fields that are wider become clipped and end in the string @samp{=>}. +Note that the full text is still in the buffer, it is only invisible. +To see the full text, hold the mouse over the field - a tool-tip window +will show the full content. To edit such a field, use the command +@kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will +open a new window with the full field. Edit it and finish with @kbd{C-c +C-c}. + +When visiting a file containing a table with narrowed columns, the +necessary character hiding has not yet happened, and the table needs to +be aligned before it looks nice. Setting the option +@code{org-startup-align-all-tables} will realign all tables in a file +upon visiting, but also slow down startup. You can also set this option +on a per-file basis with: + +@example +#+STARTUP: align +#+STARTUP: noalign +@end example + +@node Column groups, orgtbl-mode, Narrow columns, Tables +@section Column groups +@cindex grouping columns in tables + +When Org-mode exports tables, it does so by default without vertical +lines because that is visually more satisfying in general. Occasionally +however, vertical lines can be useful to structure a table into groups +of columns, much like horizontal lines can do for groups of rows. In +order to specify column groups, you can use a special row where the +first field contains only @samp{/}. The further fields can either +contain @samp{<} to indicate that this column should start a group, +@samp{>} to indicate the end of a column, or @samp{<>} to make a column +a group of its own. Boundaries between colum groups will upon export be +marked with vertical lines. Here is an example: + +@example +| | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | +|---+----+-----+-----+-----+---------+------------| +| / | <> | < | | > | < | > | +| # | 1 | 1 | 1 | 1 | 1 | 1 | +| # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 | +| # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 | +|---+----+-----+-----+-----+---------+------------| +#+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2)) +@end example + +It is also sufficient to just insert the colum group starters after +every vertical line you'd like to have: + +@example +| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | +|----+-----+-----+-----+---------+------------| +| / | < | | | < | | +@end example + +@node orgtbl-mode, The spreadsheet, Column groups, Tables +@section The Orgtbl minor mode +@cindex orgtbl-mode +@cindex minor mode for tables + +If you like the intuitive way the Org-mode table editor works, you +might also want to use it in other modes like text-mode or mail-mode. +The minor mode Orgtbl-mode makes this possible. You can always toggle +the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for +example in mail mode, use + +@lisp +(add-hook 'mail-mode-hook 'turn-on-orgtbl) +@end lisp + +Furthermore, with some special setup, it is possible to maintain tables +in arbitrary syntax with Orgtbl-mode. For example, it is possible to +construct La@TeX{} tables with the underlying ease and power of +Orgtbl-mode, including spreadsheet capabilities. For details, see +@ref{Tables in arbitrary syntax}. + +@node The spreadsheet, , orgtbl-mode, Tables +@section The spreadsheet +@cindex calculations, in tables +@cindex spreadsheet capabilities +@cindex @file{calc} package + +The table editor makes use of the Emacs @file{calc} package to implement +spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to +derive fields from other fields. While fully featured, Org-mode's +implementation is not identical to other spreadsheets. For example, +Org-mode knows the concept of a @emph{column formula} that will be +applied to all non-header fields in a column without having to copy the +formula to each relevant field. + +@menu +* References:: How to refer to another field or range +* Formula syntax for Calc:: Using Calc to compute stuff +* Formula syntax for Lisp:: Writing formulas in Emacs Lisp +* Field formulas:: Formulas valid for a single field +* Column formulas:: Formulas valid for an entire column +* Editing and debugging formulas:: Fixing formulas +* Updating the table:: Recomputing all dependent fields +* Advanced features:: Field names, parameters and automatic recalc +@end menu + +@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet +@subsection References +@cindex references + +To compute fields in the table from other fields, formulas must +reference other fields or ranges. In Org-mode, fields can be referenced +by name, by absolute coordinates, and by relative coordinates. To find +out what the coordinates of a field are, press @kbd{C-c ?} in that +field, or press @kbd{C-c @}} to toggle the display of a grid. + +@subsubheading Field references +@cindex field references +@cindex references, to fields + +Formulas can reference the value of another field in two ways. Like in +any other spreadsheet, you may reference fields with a letter/number +combination like @code{B3}, meaning the 2nd field in the 3rd row. +@c Such references are always fixed to that field, they don't change +@c when you copy and paste a formula to a different field. So +@c Org-mode's @code{B3} behaves like @code{$B$3} in other spreadsheets. + +@noindent +Org-mode also uses another, more general operator that looks like this: +@example +@@row$column +@end example + +@noindent +Column references can be absolute like @samp{1}, @samp{2},...@samp{N}, +or relative to the current column like @samp{+1} or @samp{-2}. + +The row specification only counts data lines and ignores horizontal +separator lines (hlines). You can use absolute row numbers +@samp{1}...@samp{N}, and row numbers relative to the current row like +@samp{+3} or @samp{-1}. Or specify the row relative to one of the +hlines: @samp{I} refers to the first hline, @samp{II} to the second etc. +@samp{-I} refers to the first such line above the current line, +@samp{+I} to the first such line below the current line. You can also +write @samp{III+2} which is the second data line after the third hline +in the table. Relative row numbers like @samp{-3} will not cross hlines +if the current line is too close to the hline. Instead, the value +directly at the hline is used. + +@samp{0} refers to the current row and column. Also, if you omit +either the column or the row part of the reference, the current +row/column is implied. + +Org-mode's references with @emph{unsigned} numbers are fixed references +in the sense that if you use the same reference in the formula for two +different fields, the same field will be referenced each time. +Org-mode's references with @emph{signed} numbers are floating +references because the same reference operator can reference different +fields depending on the field being calculated by the formula. + +Here are a few examples: + +@example +@@2$3 @r{2nd row, 3rd column} +C2 @r{same as previous} +$5 @r{column 5 in the current row} +E& @r{same as previous} +@@2 @r{current column, row 2} +@@-1$-3 @r{the field one row up, three columns to the left} +@@-I$2 @r{field just under hline above current row, column 2} +@end example + +@subsubheading Range references +@cindex range references +@cindex references, to ranges + +You may reference a rectangular range of fields by specifying two field +references connected by two dots @samp{..}. If both fields are in the +current row, you may simply use @samp{$2..$7}, but if at least one field +is in a different row, you need to use the general @code{@@row$column} +format at least for the first field (i.e the reference must start with +@samp{@@} in order to be interpreted correctly). Examples: + +@example +$1..$3 @r{First three fields in the current row.} +$P..$Q @r{Range, using column names (see under Advanced)} +@@2$1..@@4$3 @r{6 fields between these two fields.} +A2..C4 @r{Same as above.} +@@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row} +@end example + +@noindent Range references return a vector of values that can be fed +into Calc vector functions. Empty fields in ranges are normally +suppressed, so that the vector contains only the non-empty fields (but +see the @samp{E} mode switch below). If there are no non-empty fields, +@samp{[0]} is returned to avoid syntax errors in formulas. + +@subsubheading Named references +@cindex named references +@cindex references, named +@cindex name, of column or field +@cindex constants, in calculations + +@samp{$name} is interpreted as the name of a column, parameter or +constant. Constants are defined globally through the variable +@code{org-table-formula-constants}, and locally (for the file) through a +line like + +@example +#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 +@end example + +@noindent +Also properties (@pxref{Properties and columns}) can be used as +constants in table formulas: For a property @samp{:XYZ:} use the name +@samp{$PROP_XYZ}, and the property will be searched in the current +outline entry and in the hierarchy above it. If you have the +@file{constants.el} package, it will also be used to resolve constants, +including natural constants like @samp{$h} for Planck's constant, and +units like @samp{$km} for kilometers@footnote{@file{Constant.el} can +supply the values of constants in two different unit systems, @code{SI} +and @code{cgs}. Which one is used depends on the value of the variable +@code{constants-unit-system}. You can use the @code{#+STARTUP} options +@code{constSI} and @code{constcgs} to set this value for the current +buffer.}. Column names and parameters can be specified in special table +lines. These are described below, see @ref{Advanced features}. All +names must start with a letter, and further consist of letters and +numbers. + +@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet +@subsection Formula syntax for Calc +@cindex formula syntax, Calc +@cindex syntax, of formulas + +A formula can be any algebraic expression understood by the Emacs +@file{Calc} package. @b{Note that @file{calc} has the +non-standard convention that @samp{/} has lower precedence than +@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before +evaluation by @code{calc-eval} (@pxref{Calling Calc from +Your Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU +Emacs Calc Manual}), +@c FIXME: The link to the calc manual in HTML does not work. +variable substitution takes place according to the rules described above. +@cindex vectors, in table calculations +The range vectors can be directly fed into the calc vector functions +like @samp{vmean} and @samp{vsum}. + +@cindex format specifier +@cindex mode, for @file{calc} +A formula can contain an optional mode string after a semicolon. This +string consists of flags to influence Calc and other modes during +execution. By default, Org-mode uses the standard calc modes (precision +12, angular units degrees, fraction and symbolic modes off. The display +format, however, has been changed to @code{(float 5)} to keep tables +compact. The default settings can be configured using the variable +@code{org-calc-default-modes}. + +@example +p20 @r{switch the internal precision to 20 digits} +n3 s3 e2 f4 @r{normal, scientific, engineering, or fixed display format} +D R @r{angle modes: degrees, radians} +F S @r{fraction and symbolic modes} +N @r{interpret all fields as numbers, use 0 for non-numbers} +T @r{force text interpretation} +E @r{keep empty fields in ranges} +@end example + +@noindent +In addition, you may provide a @code{printf} format specifier to +reformat the final result. A few examples: + +@example +$1+$2 @r{Sum of first and second field} +$1+$2;%.2f @r{Same, format result to two decimals} +exp($2)+exp($1) @r{Math functions can be used} +$0;%.1f @r{Reformat current cell to 1 decimal} +($3-32)*5/9 @r{Degrees F -> C conversion} +$c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}} +tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1} +sin($1);Dp3%.1e @r{Same, but use printf specifier for display} +vmean($2..$7) @r{Compute column range mean, using vector function} +vmean($2..$7);EN @r{Same, but treat empty fields as 0} +taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree} +@end example + +Calc also contains a complete set of logical operations. For example + +@example +if($1<20,teen,string("")) @r{``teen'' if age $1 less than 20, else empty} +@end example + +@node Formula syntax for Lisp, Field formulas, Formula syntax for Calc, The spreadsheet +@subsection Emacs Lisp forms as formulas +@cindex Lisp forms, as table formulas + +It is also possible to write a formula in Emacs Lisp; this can be useful +for string manipulation and control structures, if the Calc's +functionality is not enough. If a formula starts with a single quote +followed by an opening parenthesis, then it is evaluated as a lisp form. +The evaluation should return either a string or a number. Just as with +@file{calc} formulas, you can specify modes and a printf format after a +semicolon. With Emacs Lisp forms, you need to be concious about the way +field references are interpolated into the form. By default, a +reference will be interpolated as a Lisp string (in double quotes) +containing the field. If you provide the @samp{N} mode switch, all +referenced elements will be numbers (non-number fields will be zero) and +interpolated as Lisp numbers, without quotes. If you provide the +@samp{L} flag, all fields will be interpolated literally, without quotes. +I.e., if you want a reference to be interpreted as a string by the Lisp +form, enclode the reference operator itself in double quotes, like +@code{"$3"}. Ranges are inserted as space-separated fields, so you can +embed them in list or vector syntax. A few examples, note how the +@samp{N} mode is used when we do computations in lisp. + +@example +@r{Swap the first two characters of the content of column 1} + '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) +@r{Add columns 1 and 2, equivalent to the Calc's @code{$1+$2}} + '(+ $1 $2);N +@r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}} + '(apply '+ '($1..$4));N +@end example + +@node Field formulas, Column formulas, Formula syntax for Lisp, The spreadsheet +@subsection Field formulas +@cindex field formula +@cindex formula, for individual table field + +To assign a formula to a particular field, type it directly into the +field, preceded by @samp{:=}, for example @samp{:=$1+$2}. When you +press @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in +the field, the formula will be stored as the formula for this field, +evaluated, and the current field replaced with the result. + +Formulas are stored in a special line starting with @samp{#+TBLFM:} +directly below the table. If you typed the equation in the 4th field of +the 3rd data line in the table, the formula will look like +@samp{@@3$4=$1+$2}. When inserting/deleting/swapping column and rows +with the appropriate commands, @i{absolute references} (but not relative +ones) in stored formulas are modified in order to still reference the +same field. Of cause this is not true if you edit the table structure +with normal editing commands - then you must fix the equations yourself. + +Instead of typing an equation into the field, you may also use the +following command + +@table @kbd +@kindex C-u C-c = +@item C-u C-c = +Install a new formula for the current field. The command prompts for a +formula, with default taken from the @samp{#+TBLFM:} line, applies +it to the current field and stores it. +@end table + +@node Column formulas, Editing and debugging formulas, Field formulas, The spreadsheet +@subsection Column formulas +@cindex column formula +@cindex formula, for table column + +Often in a table, the same formula should be used for all fields in a +particular column. Instead of having to copy the formula to all fields +in that column, org-mode allows to assign a single formula to an entire +column. If the table contains horizontal separator hlines, everything +before the first such line is considered part of the table @emph{header} +and will not be modified by column formulas. + +To assign a formula to a column, type it directly into any field in the +column, preceded by an equal sign, like @samp{=$1+$2}. When you press +@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the +field, the formula will be stored as the formula for the current column, +evaluated and the current field replaced with the result. If the field +contains only @samp{=}, the previously stored formula for this column is +used. For each column, Org-mode will only remember the most recently +used formula. In the @samp{TBLFM:} line, column formulas will look like +@samp{$4=$1+$2}. + +Instead of typing an equation into the field, you may also use the +following command: + +@table @kbd +@kindex C-c = +@item C-c = +Install a new formula for the current column and replace current field +with the result of the formula. The command prompts for a formula, with +default taken from the @samp{#+TBLFM} line, applies it to the current +field and stores it. With a numerical prefix (e.g. @kbd{C-5 C-c =}) +will apply it to that many consecutive fields in the current column. +@end table + + +@node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet +@subsection Editing and Debugging formulas +@cindex formula editing +@cindex editing, of table formulas + +You can edit individual formulas in the minibuffer or directly in the +field. Org-mode can also prepare a special buffer with all active +formulas of a table. When offering a formula for editing, Org-mode +converts references to the standard format (like @code{B3} or @code{D&}) +if possible. If you prefer to only work with the internal format (like +@code{@@3$2} or @code{$4}), configure the variable +@code{org-table-use-standard-references}. + +@table @kbd +@kindex C-c = +@kindex C-u C-c = +@item C-c = +@itemx C-u C-c = +Edit the formula associated with the current column/field in the +minibuffer. See @ref{Column formulas} and @ref{Field formulas}. +@kindex C-u C-u C-c = +@item C-u C-u C-c = +Re-insert the active formula (either a +field formula, or a column formula) into the current field, so that you +can edit it directly in the field. The advantage over editing in the +minibuffer is that you can use the command @kbd{C-c ?}. +@kindex C-c ? +@item C-c ? +While editing a formula in a table field, highlight the field(s) +referenced by the reference at the cursor position in the formula. +@kindex C-c @} +@item C-c @} +Toggle the display of row and column numbers for a table, using +overlays. These are updated each time the table is aligned, you can +force it with @kbd{C-c C-c}. +@kindex C-c @{ +@item C-c @{ +Toggle the formula debugger on and off. See below. +@kindex C-c ' +@item C-c ' +Edit all formulas for the current table in a special buffer, where the +formulas will be displayed one per line. If the current field has an +active formula, the cursor in the formula editor will mark it. +While inside the special buffer, Org-mode will automatically highlight +any field or range reference at the cursor position. You may edit, +remove and add formulas, and use the following commands: +@table @kbd +@kindex C-c C-c +@kindex C-x C-s +@item C-c C-c +@itemx C-x C-s +Exit the formula editor and store the modified formulas. With @kbd{C-u} +prefix, also apply the new formulas to the entire table. +@kindex C-c C-q +@item C-c C-q +Exit the formula editor without installing changes. +@kindex C-c C-r +@item C-c C-r +Toggle all references in the formula editor between standard (like +@code{B3}) and internal (like @code{@@3$2}). +@kindex @key{TAB} +@item @key{TAB} +Pretty-print or indent lisp formula at point. When in a line containing +a lisp formula, format the formula according to Emacs Lisp rules. +Another @key{TAB} collapses the formula back again. In the open +formula, @key{TAB} re-indents just like in Emacs-lisp-mode. +@kindex M-@key{TAB} +@item M-@key{TAB} +Complete Lisp symbols, just like in Emacs-lisp-mode. +@kindex S-@key{up} +@kindex S-@key{down} +@kindex S-@key{left} +@kindex S-@key{right} +@item S-@key{up}/@key{down}/@key{left}/@key{right} +Shift the reference at point. For example, if the reference is +@code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}. +This also works for relative references, and for hline references. +@kindex M-S-@key{up} +@kindex M-S-@key{down} +@item M-S-@key{up}/@key{down} +Move the test line for column formulas in the Org-mode buffer up and +down. +@kindex M-@key{up} +@kindex M-@key{down} +@item M-@key{up}/@key{down} +Scroll the window displaying the table. +@kindex C-c @} +@item C-c @} +Turn the coordinate grid in the table on and off. +@end table +@end table + +Making a table field blank does not remove the formula associated with +the field, because that is stored in a different line (the @samp{TBLFM} +line) - during the next recalculation the field will be filled again. +To remove a formula from a field, you have to give an empty reply when +prompted for the formula, or to edit the @samp{#+TBLFM} line. + +@kindex C-c C-c +You may edit the @samp{#+TBLFM} directly and re-apply the changed +equations with @kbd{C-c C-c} in that line, or with the normal +recalculation commands in the table. + +@subsubheading Debugging formulas +@cindex formula debugging +@cindex debugging, of table formulas +When the evaluation of a formula leads to an error, the field content +becomes the string @samp{#ERROR}. If you would like see what is going +on during variable substitution and calculation in order to find a bug, +turn on formula debugging in the @code{Tbl} menu and repeat the +calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a +field. Detailed information will be displayed. + +@node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet +@subsection Updating the Table +@cindex recomputing table fields +@cindex updating, table + +Recalculation of a table is normally not automatic, but needs to be +triggered by a command. See @ref{Advanced features} for a way to make +recalculation at least semi-automatically. + +In order to recalculate a line of a table or the entire table, use the +following commands: + +@table @kbd +@kindex C-c * +@item C-c * +Recalculate the current row by first applying the stored column formulas +from left to right, and all field formulas in the current row. +@c +@kindex C-u C-c * +@item C-u C-c * +@kindex C-u C-c C-c +@itemx C-u C-c C-c +Recompute the entire table, line by line. Any lines before the first +hline are left alone, assuming that these are part of the table header. +@c +@kindex C-u C-u C-c * +@kindex C-u C-u C-c C-c +@item C-u C-u C-c * +@itemx C-u C-u C-c C-c +Iterate the table by recomputing it until no further changes occur. +This may be necessary if some computed fields use the value of other +fields that are computed @i{later} in the calculation sequence. +@end table + +@node Advanced features, , Updating the table, The spreadsheet +@subsection Advanced features + +If you want the recalculation of fields to happen automatically, or if +you want to be able to assign @i{names} to fields and columns, you need +to reserve the first column of the table for special marking characters. +@table @kbd +@kindex C-# +@item C-# +Rotate the calculation mark in first column through the states @samp{}, +@samp{#}, @samp{*}, @samp{!}, @samp{$}. The meaning of these characters +is discussed below. When there is an active region, change all marks in +the region. +@end table + +Here is an example of a table that collects exam results of students and +makes use of these features: + +@example +@group +|---+---------+--------+--------+--------+-------+------| +| | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note | +|---+---------+--------+--------+--------+-------+------| +| ! | | P1 | P2 | P3 | Tot | | +| # | Maximum | 10 | 15 | 25 | 50 | 10.0 | +| ^ | | m1 | m2 | m3 | mt | | +|---+---------+--------+--------+--------+-------+------| +| # | Peter | 10 | 8 | 23 | 41 | 8.2 | +| # | Sara | 6 | 14 | 19 | 39 | 7.8 | +| # | Sam | 2 | 4 | 3 | 9 | 1.8 | +|---+---------+--------+--------+--------+-------+------| +| | Average | | | | 29.7 | | +| ^ | | | | | at | | +| $ | max=50 | | | | | | +|---+---------+--------+--------+--------+-------+------| +#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f +@end group +@end example + +@noindent @b{Important}: Please note that for these special tables, +recalculating the table with @kbd{C-u C-c *} will only affect rows that +are marked @samp{#} or @samp{*}, and fields that have a formula assigned +to the field itself. The column formulas are not applied in rows with +empty first field. + +@cindex marking characters, tables +The marking characters have the following meaning: +@table @samp +@item ! +The fields in this line define names for the columns, so that you may +refer to a column as @samp{$Tot} instead of @samp{$6}. +@item ^ +This row defines names for the fields @emph{above} the row. With such +a definition, any formula in the table may use @samp{$m1} to refer to +the value @samp{10}. Also, if you assign a formula to a names field, it +will be stored as @samp{$name=...}. +@item _ +Similar to @samp{^}, but defines names for the fields in the row +@emph{below}. +@item $ +Fields in this row can define @emph{parameters} for formulas. For +example, if a field in a @samp{$} row contains @samp{max=50}, then +formulas in this table can refer to the value 50 using @samp{$max}. +Parameters work exactly like constants, only that they can be defined on +a per-table basis. +@item # +Fields in this row are automatically recalculated when pressing +@key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row +is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked +lines will be left alone by this command. +@item * +Selects this line for global recalculation with @kbd{C-u C-c *}, but +not for automatic recalculation. Use this when automatic +recalculation slows down editing too much. +@item +Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}. +All lines that should be recalculated should be marked with @samp{#} +or @samp{*}. +@item / +Do not export this line. Useful for lines that contain the narrowing +@samp{<N>} markers. +@end table + +Finally, just to whet your appetite on what can be done with the +fantastic @file{calc} package, here is a table that computes the Taylor +series of degree @code{n} at location @code{x} for a couple of functions +(homework: try that with Excel :-) + +@example +@group +|---+-------------+---+-----+--------------------------------------| +| | Func | n | x | Result | +|---+-------------+---+-----+--------------------------------------| +| # | exp(x) | 1 | x | 1 + x | +| # | exp(x) | 2 | x | 1 + x + x^2 / 2 | +| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 | +| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 | +| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 | +| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 | +|---+-------------+---+-----+--------------------------------------| +#+TBLFM: $5=taylor($2,$4,$3);n3 +@end group +@end example + +@node Hyperlinks, TODO items, Tables, Top +@chapter Hyperlinks +@cindex hyperlinks + +Just like HTML, Org-mode provides links inside a file, and external +links to other files, Usenet articles, emails, and much more. + +@menu +* Link format:: How links in Org-mode are formatted +* Internal links:: Links to other places in the current file +* External links:: URL-like links to the world +* Handling links:: Creating, inserting and following +* Using links outside Org-mode:: Linking from my C source code? +* Link abbreviations:: Shortcuts for writing complex links +* Search options:: Linking to a specific location +* Custom searches:: When the default search is not enough +* Remember:: Org-trees store quick notes +@end menu + +@node Link format, Internal links, Hyperlinks, Hyperlinks +@section Link format +@cindex link format +@cindex format, of links + +Org-mode will recognize plain URL-like links and activate them as +clickable links. The general link format, however, looks like this: + +@example +[[link][description]] @r{or alternatively} [[link]] +@end example + +Once a link in the buffer is complete (all brackets present), Org-mode +will change the display so that @samp{description} is displayed instead +of @samp{[[link][description]]} and @samp{link} is displayed instead of +@samp{[[link]]}. Links will be highlighted in the face @code{org-link}, +which by default is an underlined face. You can directly edit the +visible part of a link. Note that this can be either the @samp{link} +part (if there is no description) or the @samp{description} part. To +edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the +cursor on the link. + +If you place the cursor at the beginning or just behind the end of the +displayed text and press @key{BACKSPACE}, you will remove the +(invisible) bracket at that location. This makes the link incomplete +and the internals are again displayed as plain text. Inserting the +missing bracket hides the link internals again. To show the +internal structure of all links, use the menu entry +@code{Org->Hyperlinks->Literal links}. + +@node Internal links, External links, Link format, Hyperlinks +@section Internal links +@cindex internal links +@cindex links, internal +@cindex targets, for links + +If the link does not look like a URL, it is considered to be internal in +the current file. Links such as @samp{[[My Target]]} or @samp{[[My +Target][Find my target]]} lead to a text search in the current file. +The link can be followed with @kbd{C-c C-o} when the cursor is on the +link, or with a mouse click (@pxref{Handling links}). The preferred +match for such a link is a dedicated target: the same string in double +angular brackets. Targets may be located anywhere; sometimes it is +convenient to put them into a comment line. For example + +@example +# <<My Target>> +@end example + +@noindent In HTML export (@pxref{HTML export}), such targets will become +named anchors for direct access through @samp{http} links@footnote{Note +that text before the first headline is usually not exported, so the +first such target should be after the first headline.}. + +If no dedicated target exists, Org-mode will search for the words in the +link. In the above example the search would be for @samp{my target}. +Links starting with a star like @samp{*My Target} restrict the search to +headlines. When searching, Org-mode will first try an exact match, but +then move on to more and more lenient searches. For example, the link +@samp{[[*My Targets]]} will find any of the following: + +@example +** My targets +** TODO my targets are bright +** my 20 targets are +@end example + +To insert a link targeting a headline, in-buffer completion can be used. +Just type a star followed by a few optional letters into the buffer and +press @kbd{M-@key{TAB}}. All headlines in the current buffer will be +offered as completions. @xref{Handling links}, for more commands +creating links. + +Following a link pushes a mark onto Org-mode's own mark ring. You can +return to the previous position with @kbd{C-c &}. Using this command +several times in direct succession goes back to positions recorded +earlier. + +@menu +* Radio targets:: Make targets trigger links in plain text. +@end menu + +@node Radio targets, , Internal links, Internal links +@subsection Radio targets +@cindex radio targets +@cindex targets, radio +@cindex links, radio targets + +Org-mode can automatically turn any occurrences of certain target names +in normal text into a link. So without explicitly creating a link, the +text connects to the target radioing its position. Radio targets are +enclosed by triple angular brackets. For example, a target @samp{<<<My +Target>>>} causes each occurrence of @samp{my target} in normal text to +become activated as a link. The Org-mode file is scanned automatically +for radio targets only when the file is first loaded into Emacs. To +update the target list during editing, press @kbd{C-c C-c} with the +cursor on or at a target. + +@node External links, Handling links, Internal links, Hyperlinks +@section External links +@cindex links, external +@cindex external links +@cindex links, external +@cindex GNUS links +@cindex BBDB links +@cindex URL links +@cindex file links +@cindex VM links +@cindex RMAIL links +@cindex WANDERLUST links +@cindex MH-E links +@cindex USENET links +@cindex SHELL links +@cindex Info links +@cindex elisp links + +Org-mode supports links to files, websites, Usenet and email messages, +and BBDB database entries. External links are URL-like locators. They +start with a short identifying string followed by a colon. There can be +no space after the colon. The following list shows examples for each +link type. + +@example +http://www.astro.uva.nl/~dominik @r{on the web} +file:/home/dominik/images/jupiter.jpg @r{file, absolute path} +file:papers/last.pdf @r{file, relative path} +news:comp.emacs @r{Usenet link} +mailto:adent@@galaxy.net @r{Mail link} +vm:folder @r{VM folder link} +vm:folder#id @r{VM message link} +vm://myself@@some.where.org/folder#id @r{VM on remote machine} +wl:folder @r{WANDERLUST folder link} +wl:folder#id @r{WANDERLUST message link} +mhe:folder @r{MH-E folder link} +mhe:folder#id @r{MH-E message link} +rmail:folder @r{RMAIL folder link} +rmail:folder#id @r{RMAIL message link} +gnus:group @r{GNUS group link} +gnus:group#id @r{GNUS article link} +bbdb:Richard Stallman @r{BBDB link} +shell:ls *.org @r{A shell command} +elisp:(find-file-other-frame "Elisp.org") @r{An elisp form to evaluate} +@end example + +A link should be enclosed in double brackets and may contain a +descriptive text to be displayed instead of the url (@pxref{Link +format}), for example: + +@example +[[http://www.gnu.org/software/emacs/][GNU Emacs]] +@end example + +@noindent +If the description is a file name or URL that points to an image, HTML +export (@pxref{HTML export}) will inline the image as a clickable +button. If there is no description at all and the link points to an +image, +that image will be inlined into the exported HTML file. + +@cindex angular brackets, around links +@cindex plain text external links +Org-mode also finds external links in the normal text and activates them +as links. If spaces must be part of the link (for example in +@samp{bbdb:Richard Stallman}), or if you need to remove ambiguities +about the end of the link, enclose them in angular brackets. + +@node Handling links, Using links outside Org-mode, External links, Hyperlinks +@section Handling links +@cindex links, handling + +Org-mode provides methods to create a link in the correct syntax, to +insert it into an org-mode file, and to follow the link. + +@table @kbd +@kindex C-c l +@cindex storing links +@item C-c l +Store a link to the current location. This is a @emph{global} command +which can be used in any buffer to create a link. The link will be +stored for later insertion into an Org-mode buffer (see below). For +Org-mode files, if there is a @samp{<<target>>} at the cursor, the link +points to the target. Otherwise it points to the current headline. For +VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will +indicate the current article/entry. For W3 and W3M buffers, the link +goes to the current URL. For any other files, the link will point to +the file, with a search string (@pxref{Search options}) pointing to the +contents of the current line. If there is an active region, the +selected words will form the basis of the search string. If the +automatically created link is not working correctly or accurately +enough, you can write custom functions to select the search string and +to do the search for particular file types - see @ref{Custom searches}. +The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}. +@c +@kindex C-c C-l +@cindex link completion +@cindex completion, of links +@cindex inserting links +@item C-c C-l +Insert a link. This prompts for a link to be inserted into the buffer. +You can just type a link, using text for an internal link, or one of the +link type prefixes mentioned in the examples above. All links stored +during the current session are part of the history for this prompt, so +you can access them with @key{up} and @key{down}. Completion, on the +other hand, will help you to insert valid link prefixes like +@samp{http:} or @samp{ftp:}, including the prefixes defined through link +abbreviations (@pxref{Link abbreviations}). The link will be inserted +into the buffer@footnote{After insertion of a stored link, the link will +be removed from the list of stored links. To keep it in the list later +use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the +option @code{org-keep-stored-link-after-insertion}.}, along with a +descriptive text. If some text was selected when this command is +called, the selected text becomes the default description.@* Note that +you don't have to use this command to insert a link. Links in Org-mode +are plain text, and you can type or paste them straight into the buffer. +By using this command, the links are automatically enclosed in double +brackets, and you will be asked for the optional descriptive text. +@c +@c If the link is a @samp{file:} link and +@c the linked file is located in the same directory as the current file or +@c a subdirectory of it, the path of the file will be inserted relative to +@c the current directory. +@c +@kindex C-u C-c C-l +@cindex file name completion +@cindex completion, of file names +@item C-u C-c C-l +When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to +a file will be inserted and you may use file name completion to select +the name of the file. The path to the file is inserted relative to the +directory of the current org file, if the linked file is in the current +directory or in a subdirectory of it, or if the path is written relative +to the current directory using @samp{../}. Otherwise an absolute path +is used, if possible with @samp{~/} for your home directory. You can +force an absolute path with two @kbd{C-u} prefixes. +@c +@item C-c C-l @r{(with cursor on existing link)} +When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the +link and description parts of the link. +@c +@cindex following links +@kindex C-c C-o +@item C-c C-o +Open link at point. This will launch a web browser for URLs (using +@command{browse-url-at-point}), run vm/mh-e/wanderlust/rmail/gnus/bbdb +for the corresponding links, and execute the command in a shell link. +When the cursor is on an internal link, this commands runs the +corresponding search. When the cursor is on a TAG list in a headline, +it creates the corresponding TAGS view. If the cursor is on a time +stamp, it compiles the agenda for that date. Furthermore, it will visit +text and remote files in @samp{file:} links with Emacs and select a +suitable application for local non-text files. Classification of files +is based on file extension only. See option @code{org-file-apps}. If +you want to override the default application and visit the file with +Emacs, use a @kbd{C-u} prefix. +@c +@kindex mouse-2 +@kindex mouse-1 +@item mouse-2 +@itemx mouse-1 +On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o} +would. Under Emacs 22, also @kbd{mouse-1} will follow a link. +@c +@kindex mouse-3 +@item mouse-3 +Like @kbd{mouse-2}, but force file links to be opened with Emacs, and +internal links to be displayed in another window@footnote{See the +variable @code{org-display-internal-link-with-indirect-buffer}}. +@c +@cindex mark ring +@kindex C-c % +@item C-c % +Push the current position onto the mark ring, to be able to return +easily. Commands following an internal link do this automatically. +@c +@cindex links, returning to +@kindex C-c & +@item C-c & +Jump back to a recorded position. A position is recorded by the +commands following internal links, and by @kbd{C-c %}. Using this +command several times in direct succession moves through a ring of +previously recorded positions. +@c +@kindex C-c C-x C-n +@kindex C-c C-x C-p +@cindex links, finding next/previous +@item C-c C-x C-n +@itemx C-c C-x C-p +Move forward/backward to the next link in the buffer. At the limit of +the buffer, the search fails once, and then wraps around. The key +bindings for this are really too long, you might want to bind this also +to @kbd{C-n} and @kbd{C-p} +@lisp +(add-hook 'org-load-hook + (lambda () + (define-key 'org-mode-map "\C-n" 'org-next-link) + (define-key 'org-mode-map "\C-p" 'org-previous-link))) +@end lisp +@end table + +@node Using links outside Org-mode, Link abbreviations, Handling links, Hyperlinks +@section Using links outside Org-mode + +You can insert and follow links that have Org-mode syntax not only in +Org-mode, but in any Emacs buffer. For this, you should create two +global commands, like this (please select suitable global keys +yourself): + +@lisp +(global-set-key "\C-c L" 'org-insert-link-global) +(global-set-key "\C-c o" 'org-open-at-point-global) +@end lisp + +@node Link abbreviations, Search options, Using links outside Org-mode, Hyperlinks +@section Link abbreviations +@cindex link abbreviations +@cindex abbreviation, links + +Long URLs can be cumbersome to type, and often many similar links are +needed in a document. For this you can use link abbreviations. An +abbreviated link looks like this + +@example +[[linkword:tag][description]] +@end example + +@noindent +where the tag is optional. Such abbreviations are resolved according to +the information in the variable @code{org-link-abbrev-alist} that +relates the linkwords to replacement text. Here is an example: + +@lisp +@group +(setq org-link-abbrev-alist + '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") + ("google" . "http://www.google.com/search?q=") + ("ads" . "http://adsabs.harvard.edu/cgi-bin/ + nph-abs_connect?author=%s&db_key=AST"))) +@end group +@end lisp + +If the replacement text contains the string @samp{%s}, it will be +replaced with the tag. Otherwise the tag will be appended to the string +in order to create the link. You may also specify a function that will +be called with the tag as the only argument to create the link. + +With the above setting, you could link to a specific bug with +@code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with +@code{[[google:OrgMode]]} and find out what the Org-mode author is +doing besides Emacs hacking with @code{[[ads:Dominik,C]]}. + +If you need special abbreviations just for a single Org-mode buffer, you +can define them in the file with + +@example +#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id= +#+LINK: google http://www.google.com/search?q=%s +@end example + +@noindent +In-buffer completion @pxref{Completion} can be used after @samp{[} to +complete link abbreviations. + +@node Search options, Custom searches, Link abbreviations, Hyperlinks +@section Search options in file links +@cindex search option in file links +@cindex file links, searching + +File links can contain additional information to make Emacs jump to a +particular location in the file when following a link. This can be a +line number or a search option after a double@footnote{For backward +compatibility, line numbers can also follow a single colon.} colon. For +example, when the command @kbd{C-c l} creates a link (@pxref{Handling +links}) to a file, it encodes the words in the current line as a search +string that can be used to find this line back later when following the +link with @kbd{C-c C-o}. + +Here is the syntax of the different ways to attach a search to a file +link, together with an explanation: + +@example +[[file:~/code/main.c::255]] +[[file:~/xx.org::My Target]] +[[file:~/xx.org::*My Target]] +[[file:~/xx.org::/regexp/]] +@end example + +@table @code +@item 255 +Jump to line 255. +@item My Target +Search for a link target @samp{<<My Target>>}, or do a text search for +@samp{my target}, similar to the search in internal links, see +@ref{Internal links}. In HTML export (@pxref{HTML export}), such a file +link will become an HTML reference to the corresponding named anchor in +the linked file. +@item *My Target +In an Org-mode file, restrict search to headlines. +@item /regexp/ +Do a regular expression search for @code{regexp}. This uses the Emacs +command @code{occur} to list all matches in a separate window. If the +target file is in Org-mode, @code{org-occur} is used to create a +sparse tree with the matches. +@c If the target file is a directory, +@c @code{grep} will be used to search all files in the directory. +@end table + +As a degenerate case, a file link with an empty file name can be used +to search the current file. For example, @code{[[file:::find me]]} does +a search for @samp{find me} in the current file, just as +@samp{[[find me]]} would. + +@node Custom searches, Remember, Search options, Hyperlinks +@section Custom Searches +@cindex custom search strings +@cindex search strings, custom + +The default mechanism for creating search strings and for doing the +actual search related to a file link may not work correctly in all +cases. For example, BibTeX database files have many entries like +@samp{year="1993"} which would not result in good search strings, +because the only unique identification for a BibTeX entry is the +citation key. + +If you come across such a problem, you can write custom functions to set +the right search string for a particular file type, and to do the search +for the string in the file. Using @code{add-hook}, these functions need +to be added to the hook variables +@code{org-create-file-search-functions} and +@code{org-execute-file-search-functions}. See the docstring for these +variables for more information. Org-mode actually uses this mechanism +for Bib@TeX{} database files, and you can use the corresponding code as +an implementation example. Search for @samp{BibTeX links} in the source +file. + + +@node Remember, , Custom searches, Hyperlinks +@section Remember +@cindex @file{remember.el} + +Another way to create org entries with links to other files is through +the @i{remember} package by John Wiegley. @i{Remember} lets you store +quick notes with little interruption of your work flow. See +@uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more +information. The notes produced by @i{Remember} can be stored in +different ways, and Org-mode files are a good target. Org-mode +significantly expands the possibilities of @i{remember}: You may define +templates for different note types, and to associate target files and +headlines with specific templates. It also allows you to select the +location where a note should be stored interactively, on the fly. + +@menu +* Setting up remember:: Some code for .emacs to get things going +* Remember templates:: Define the outline of different note types +* Storing notes:: Directly get the note to where it belongs +@end menu + +@node Setting up remember, Remember templates, Remember, Remember +@subsection Setting up remember + +The following customization will tell @i{remember} to use org files as +target, and to create annotations compatible with Org-mode links. + +@example +(setq org-directory "~/path/to/my/orgfiles/") +(setq org-default-notes-file "~/.notes") +(setq remember-annotation-functions '(org-remember-annotation)) +(setq remember-handler-functions '(org-remember-handler)) +(add-hook 'remember-mode-hook 'org-remember-apply-template) +@end example + +@node Remember templates, Storing notes, Setting up remember, Remember +@subsection Remember templates +@cindex templates, for remember + +In combination with Org-mode, you can use templates to generate +different types of @i{remember} notes. For example, if you would like +to use one template to create general TODO entries, another one for +journal entries, and a third one for collecting random ideas, you could +use: + +@example +(setq org-remember-templates + '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org") + (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") + (?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) +@end example + +@noindent In these entries, the character specifies how to select the +template. The first string specifies the template. Two more (optional) +strings give the file in which, and the headline under which the new +note should be stored. The file defaults (if not present or @code{nil}) +to @code{org-default-notes-file}, the heading to +@code{org-remember-default-headline}. Both defaults help to get to the +storing location quickly, but you can change the location interactively +while storing the note. + +When you call @kbd{M-x remember} (or @kbd{M-x org-remember}) to remember +something, org will prompt for a key to select the template (if you have +more than one template) and then prepare the buffer like +@example +* TODO + [[file:link to where you called remember]] +@end example + +@noindent or + +@example +* [2006-03-21 Tue 15:37] + + [[file:link to where you called remember]] +@end example + +@noindent +During expansion of the template, special @kbd{%}-escapes allow dynamic +insertion of content: +@example +%^@{prompt@} @r{prompt the user for a string and replace this sequence with it.} +%t @r{time stamp, date only} +%T @r{time stamp with date and time} +%u, %U @r{like the above, but inactive time stamps} +%^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}} + @r{You may define a prompt like @code{%^@{Birthday@}t}} +%n @r{user name (taken from @code{user-full-name})} +%a @r{annotation, normally the link created with @code{org-store-link}} +%i @r{initial content, the region when remember is called with C-u.} + @r{The entire text will be indented like @code{%i} itself.} +%^g @r{prompt for tags, with completion on tags in target file.} +%^G @r{prompt for tags, with completion all tags in all agenda files.} +%:keyword @r{specific information for certain link types, see below} +@end example + +@noindent +For specific link types, the following keywords will be defined: + +@example +Link type | Available keywords +-------------------+---------------------------------------------- +bbdb | %:name %:company +vm, wl, mh, rmail | %:type %:subject %:message-id + | %:from %:fromname %:fromaddress + | %:to %:toname %:toaddress + | %: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}.}} +gnus | %:group, @r{for messages also all email fields} +w3, w3m | %:url +info | %:file %:node +calendar | %:date" +@end example + +@noindent +To place the cursor after template expansion use: + +@example +%? @r{After completing the template, position cursor here.} +@end example + +@noindent +If you change you mind about which template to use, call +@code{org-remember} in the remember buffer. You may then select a new +template that will be filled with the previous context information. + +@node Storing notes, , Remember templates, Remember +@subsection Storing notes + +When you are finished preparing a note with @i{remember}, you have to press +@kbd{C-c C-c} to file the note away. The handler first prompts for a +target file - if you press @key{RET}, the value specified for the +template is used. Then the command offers the headings tree of the +selected file, with the cursor position at the default headline (if you +had specified one in the template). You can either immediately press +@key{RET} to get the note placed there. Or you can use the following +keys to find a better location: +@example +@key{TAB} @r{Cycle visibility.} +@key{down} / @key{up} @r{Next/previous visible headline.} +n / p @r{Next/previous visible headline.} +f / b @r{Next/previous headline same level.} +u @r{One level up.} +@c 0-9 @r{Digit argument.} +@end example +@noindent +Pressing @key{RET} or @key{left} or @key{right} +then leads to the following result. + +@multitable @columnfractions 0.2 0.15 0.65 +@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted} +@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file +@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor +@item @tab @key{left}/@key{right} @tab as same level, before/after current heading +@item not on headline @tab @key{RET} + @tab at cursor position, level taken from context. +@end multitable + +So a fast way to store the note to its default location is to press +@kbd{C-c C-c @key{RET} @key{RET}}. Even shorter would be @kbd{C-u C-c +C-c}, which does the same without even asking for a file or showing the +tree. + +Before inserting the text into a tree, the function ensures that the +text has a headline, i.e. a first line that starts with a @samp{*}. +If not, a headline is constructed from the current date and some +additional data. If the variable @code{org-adapt-indentation} is +non-nil, the entire text is also indented so that it starts in the +same column as the headline (after the asterisks). + + +@node TODO items, Tags, Hyperlinks, Top +@chapter TODO items +@cindex TODO items + +Org-mode does not maintain TODO lists as a separate document. TODO +items are an integral part of the notes file, because TODO items +usually come up while taking notes! With Org-mode, you simply mark +any entry in a tree as being a TODO item. In this way, the +information is not duplicated, and the entire context from which the +item emerged is always present when you check. + +Of course, this technique causes TODO items to be scattered throughout +your file. Org-mode provides methods to give you an overview over all +things you have to do. + +@menu +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists +@end menu + +@node TODO basics, TODO extensions, TODO items, TODO items +@section Basic TODO functionality + +Any headline can become a TODO item by starting it with the word TODO, +for example: + +@example +*** TODO Write letter to Sam Fortune +@end example + +@noindent +The most important commands to work with TODO entries are: + +@table @kbd +@kindex C-c C-t +@cindex cycling, of TODO states +@item C-c C-t +Rotate the TODO state of the current item among + +@example +,-> (unmarked) -> TODO -> DONE --. +'--------------------------------' +@end example + +The same rotation can also be done ``remotely'' from the timeline and +agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). +@kindex S-@key{right} +@kindex S-@key{left} +@item S-@key{right} +@itemx S-@key{left} +Select the following/preceding TODO state, similar to cycling. Mostly +useful if more than two TODO states are possible (@pxref{TODO +extensions}). +@kindex C-c C-c +@item C-c C-c +Use the fast tag interface to quickly and directly select a specific +TODO state. For this you need to assign keys to TODO state, like this: +@example +#+SEQ_TODO: TODO(t) STARTED(s) WAITING(w) | DONE(d) +@end example +@noindent See @ref{Per file keywords} and @ref{Setting tags} for more +information. +@kindex C-c C-v +@cindex sparse tree, for TODO +@item C-c C-v +View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds +the entire buffer, but shows all TODO items and the headings hierarchy +above them. With prefix arg, search for a specific TODO. You will be +prompted for the keyword, and you can also give a list of keywords like +@code{kwd1|kwd2|...}. With numerical prefix N, show the tree for the +Nth keyword in the variable @code{org-todo-keywords}. With two prefix +args, find all TODO and DONE entries. +@kindex C-c a t +@item C-c a t +Show the global TODO list. This collects the TODO items from all +agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in +@code{agenda-mode}, so there are commands to examine and manipulate +the TODO entries directly from that buffer (@pxref{Agenda commands}). +@xref{Global TODO list}, for more information. +@kindex S-M-@key{RET} +@item S-M-@key{RET} +Insert a new TODO entry below the current one. +@end table + +@node TODO extensions, Priorities, TODO basics, TODO items +@section Extended use of TODO keywords +@cindex extended TODO keywords + +The default implementation of TODO entries is just two states: TODO and +DONE. You can use the TODO feature for more complicated things by +configuring the variable @code{org-todo-keywords}. With special setup, +the TODO keyword system can work differently in different files. + +Note that @i{tags} are another way to classify headlines in general and +TODO items in particular (@pxref{Tags}). + +@menu +* Workflow states:: From TODO to DONE in steps +* TODO types:: I do this, Fred the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Per file keywords:: Different files, different requirements +@end menu + +@node Workflow states, TODO types, TODO extensions, TODO extensions +@subsection TODO keywords as workflow states +@cindex TODO workflow +@cindex workflow states as TODO keywords + +You can use TODO keywords to indicate different @emph{sequential} states +in the process of working on an item, for example@footnote{Changing +this variable only becomes effective after restarting Org-mode in a +buffer.}: + +@lisp +(setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) +@end lisp + +The vertical bar separates the TODO keywords (states that @emph{need +action}) from the DONE states (which need @emph{no further action}. If +you don't provide the separator bar, the last state is used as the DONE +state. +@cindex completion, of TODO keywords +With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO +to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may +also use a prefix argument to quickly select a specific state. For +example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY. +If you define many keywords, you can use in-buffer completion (see +@ref{Completion}) to insert these words into the buffer. Changing a +todo state can be logged with a timestamp, see @ref{Tracking TODO state +changes} for more information. + +@node TODO types, Multiple sets in one file, Workflow states, TODO extensions +@subsection TODO keywords as types +@cindex TODO types +@cindex names as TODO keywords +@cindex types as TODO keywords + +The second possibility is to use TODO keywords to indicate different +@emph{types} of action items. For example, you might want to indicate +that items are for ``work'' or ``home''. Or, when you work with several +people on a single project, you might want to assign action items +directly to persons, by using their names as TODO keywords. This would +be set up like this: + +@lisp +(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE"))) +@end lisp + +In this case, different keywords do not indicate a sequence, but rather +different types. So the normal work flow would be to assign a task to a +person, and later to mark it DONE. Org-mode supports this style by +adapting the workings of the command @kbd{C-c C-t}@footnote{This is also +true for the @kbd{t} command in the timeline and agenda buffers.}. When +used several times in succession, it will still cycle through all names, +in order to first select the right type for a task. But when you return +to the item after some time and execute @kbd{C-c C-t} again, it will +switch from any name directly to DONE. Use prefix arguments or +completion to quickly select a specific name. You can also review the +items of a specific TODO type in a sparse tree by using a numeric prefix +to @kbd{C-c C-v}. For example, to see all things Lucy has to do, you +would use @kbd{C-3 C-c C-v}. To collect Lucy's items from all agenda +files into a single buffer, you would use the prefix arg as well when +creating the global todo list: @kbd{C-3 C-c t}. + +@node Multiple sets in one file, Per file keywords, TODO types, TODO extensions +@subsection Multiple keyword sets in one file +@cindex todo keyword sets + +Sometimes you may want to use different sets of TODO keywords in +parallel. For example, you may want to have the basic +@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a +separate state indicating that an item has been canceled (so it is not +DONE, but also does not require action). Your setup would then look +like this: + +@lisp +(setq org-todo-keywords + '((sequence "TODO" "|" "DONE") + (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") + (sequence "|" "CANCELED"))) +@end lisp + +The keywords should all be different, this helps Org-mode to keep track +of which subsequence should be used for a given entry. In this setup, +@kbd{C-c C-t} only operates within a subsequence, so it switches from +@code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to +(nothing) to @code{REPORT}. Therefore you need a mechanism to initially +select the correct sequence. Besides the obvious ways like typing a +keyword or using completion, you may also apply the following commands: + +@table @kbd +@kindex C-S-@key{right} +@kindex C-S-@key{left} +@item C-S-@key{right} +@itemx C-S-@key{left} +These keys jump from one TODO subset to the next. In the above example, +@kbd{C-S-@key{right}} would jump from @code{TODO} or @code{DONE} to +@code{REPORT}, and any of the words in the second row to @code{CANCELED}. +@kindex S-@key{right} +@kindex S-@key{left} +@item S-@key{right} +@itemx S-@key{left} +@kbd{S-@key{<left>}} and @kbd{S-@key{<right>}} and walk through +@emph{all} keywords from all sets, so for example @kbd{S-@key{<right>}} +would switch from @code{DONE} to @code{REPORT} in the example above. +@end table + +@node Per file keywords, , Multiple sets in one file, TODO extensions +@subsection Setting up keywords for individual files +@cindex keyword options +@cindex per file keywords + +It can be very useful to use different aspects of the TODO mechanism in +different files. For file-local settings, you need to add special lines +to the file which set the keywords and interpretation for that file +only. For example, to set one of the two examples discussed above, you +need one of the following lines, starting in column zero anywhere in the +file: + +@example +#+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED +@end example +or +@example +#+TYP_TODO: Fred Sara Lucy Mike | DONE +@end example + +A setup for using several sets in parallel would be: + +@example +#+SEQ_TODO: TODO | DONE +#+SEQ_TODO: REPORT BUG KNOWNCAUSE | FIXED +#+SEQ_TODO: | CANCELED +@end example + +@cindex completion, of option keywords +@kindex M-@key{TAB} +@noindent To make sure you are using the correct keyword, type +@samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion. + +@cindex DONE, final TODO keyword +Remember that the keywords after the vertical bar (or the last keyword +if no bar is there) must always mean that the item is DONE (although you +may use a different word). After changing one of these lines, use +@kbd{C-c C-c} with the cursor still in the line to make the changes +known to Org-mode@footnote{Org-mode parses these lines only when +Org-mode is activated after visiting a file. @kbd{C-c C-c} with the +cursor in a line starting with @samp{#+} is simply restarting Org-mode +for the current buffer.}. + +@node Priorities, Breaking down tasks, TODO extensions, TODO items +@section Priorities +@cindex priorities + +If you use Org-mode extensively to organize your work, you may end up +with a number of TODO entries so large that you'd like to prioritize +them. This can be done by placing a @emph{priority cookie} into the +headline, like this + +@example +*** TODO [#A] Write letter to Sam Fortune +@end example + +@noindent +With its standard setup, Org-mode supports priorities @samp{A}, +@samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry +without a cookie is treated as priority @samp{B}. Priorities make a +difference only in the agenda (@pxref{Weekly/Daily agenda}). + +@table @kbd +@kindex @kbd{C-c ,} +@item @kbd{C-c ,} +Set the priority of the current headline. The command prompts for a +priority character @samp{A}, @samp{B} or @samp{C}. When you press +@key{SPC} instead, the priority cookie is removed from the headline. +The priorities can also be changed ``remotely'' from the timeline and +agenda buffer with the @kbd{,} command (@pxref{Agenda commands}). +@c +@kindex S-@key{up} +@kindex S-@key{down} +@item S-@key{up} +@itemx S-@key{down} +Increase/decrease priority of current headline. Note that these keys +are also used to modify time stamps (@pxref{Creating timestamps}). +Furthermore, these keys are also used by CUA-mode (@pxref{Conflicts}). +@end table + +You can change the range of allowed priorities by setting the variables +@code{org-highest-priority}, @code{org-lowest-priority}, and +@code{org-default-priority}. For an individual buffer, you may set +these values (highest, lowest, default) like this (please make sure that +the highest priority is earlier in the alphabet than the lowest +priority): + +@example +#+PRIORITIES: A C B +@end example + +@node Breaking down tasks, Checkboxes, Priorities, TODO items +@section Breaking tasks down into subtasks +@cindex tasks, breaking down + +It is often advisable to break down large tasks into smaller, manageable +subtasks. You can do this by creating an outline tree below a TODO +item, with detailed subtasks on the tree@footnote{To keep subtasks out +of the global TODO list, see the +@code{org-agenda-todo-list-sublevels}.}. Another possibility is the use +of checkboxes to identify (a hierarchy of) a large number of subtasks +(@pxref{Checkboxes}). + + +@node Checkboxes, , Breaking down tasks, TODO items +@section Checkboxes +@cindex checkboxes + +Every item in a plain list (@pxref{Plain lists}) can be made a checkbox +by starting it with the string @samp{[ ]}. This feature is similar to +TODO items (@pxref{TODO items}), but more lightweight. Checkboxes are +not included into the global TODO list, so they are often great to split +a task into a number of simple steps. Or you can use them in a shopping +list. To toggle a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's +@file{org-mouse.el}. Here is an example of a checkbox list. + +@example +* TODO Organize party [3/6] + - call people [1/3] + - [ ] Peter + - [X] Sarah + - [ ] Sam + - [X] order food + - [ ] think about what music to play + - [X] talk to the neighbors +@end example + +@cindex statistics, for checkboxes +@cindex checkbox statistics +The @samp{[3/6]} and @samp{[1/3]} in the first and second line are +cookies indicating how many checkboxes are present in this entry, and +how many of them have been checked off. This can give you an idea on +how many checkboxes remain, even without opening a folded entry. The +cookies can be placed into a headline or into (the first line of) a +plain list item. Each cookie covers all checkboxes structurally below +that headline/item. You have to insert the cookie yourself by typing +either @samp{[/]} or @samp{[%]}. In the first case you get an @samp{n +out of m} result, in the second case you get information about the +percentage of checkboxes checked (in the above example, this would be +@samp{[50%]} and @samp{[33%], respectively}). + +@noindent The following commands work with checkboxes: + +@table @kbd +@kindex C-c C-c +@item C-c C-c +Toggle checkbox at point. With prefix argument, set it to @samp{[-]}, +which is considered to be an intermediate state. +@kindex C-c C-x C-b +@item C-c C-x C-b +Toggle checkbox at point. +@itemize @minus +@item +If there is an active region, toggle the first checkbox in the region +and set all remaining boxes to the same status as the first. If you +want to toggle all boxes in the region independently, use a prefix +argument. +@item +If the cursor is in a headline, toggle checkboxes in the region between +this headline and the next (so @emph{not} the entire subtree). +@item +If there is no active region, just toggle the checkbox at point. +@end itemize +@kindex M-S-@key{RET} +@item M-S-@key{RET} +Insert a new item with a checkbox. +This works only if the cursor is already in a plain list item +(@pxref{Plain lists}). +@kindex C-c # +@item C-c # +Update the checkbox statistics in the current outline entry. When +called with a @kbd{C-u} prefix, update the entire file. Checkbox +statistic cookies are updated automatically if you toggle checkboxes +with @kbd{C-c C-c} and make new ones with @kbd{M-S-@key{RET}}. If you +delete boxes or add/change them by hand, use this command to get things +back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}. +@end table + + +@node Tags, Properties and columns, TODO items, Top +@chapter Tags +@cindex tags +@cindex headline tagging +@cindex matching, tags +@cindex sparse tree, tag based + +If you wish to implement a system of labels and contexts for +cross-correlating information, an excellent way is to assign @i{tags} to +headlines. Org-mode has extensive support for using tags. + +Every headline can contain a list of tags, at the end of the headline. +Tags are normal words containing letters, numbers, @samp{_}, and +@samp{@@}. Tags must be preceded and followed by a single colon; like +@samp{:WORK:}. Several tags can be specified like @samp{:WORK:URGENT:}. + +@menu +* Tag inheritance:: Tags use the tree structure of the outline +* Setting tags:: How to assign tags to a headline +* Tag searches:: Searching for combinations of tags +@end menu + +@node Tag inheritance, Setting tags, Tags, Tags +@section Tag inheritance +@cindex inheritance, of tags +@cindex sublevels, inclusion into tags match + +@i{Tags} make use of the hierarchical structure of outline trees. If a +heading has a certain tag, all subheadings will inherit the tag as +well. For example, in the list + +@example +* Meeting with the French group :WORK: +** Summary by Frank :BOSS:NOTES: +*** TODO Prepare slides for him :ACTION: +@end example + +@noindent +the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:}, +@samp{:NOTES:}, and @samp{:ACTION:}. When executing tag searches and +Org-mode finds that a certain headline matches the search criterion, it +will not check any sublevel headline, assuming that these likely also +match, and that the list of matches can become very long. This may +not be what you want, however, and you can influence inheritance and +searching using the variables @code{org-use-tag-inheritance} and +@code{org-tags-match-list-sublevels}. + +@node Setting tags, Tag searches, Tag inheritance, Tags +@section Setting tags +@cindex setting tags +@cindex tags, setting + +@kindex M-@key{TAB} +Tags can simply be typed into the buffer at the end of a headline. +After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is +also a special command for inserting tags: + +@table @kbd +@kindex C-c C-c +@item C-c C-c +@cindex completion, of tags +Enter new tags for the current headline. Org-mode will either offer +completion or a special single-key interface for setting tags, see +below. After pressing @key{RET}, the tags will be inserted and aligned +to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all +tags in the current buffer will be aligned to that column, just to make +things look nice. TAGS are automatically realigned after promotion, +demotion, and TODO state changes (@pxref{TODO basics}). +@end table + +Org will support tag insertion based on a @emph{list of tags}. By +default this list is constructed dynamically, containing all tags +currently used in the buffer. You may also globally specify a hard list +of tags with the variable @code{org-tag-alist}. Finally you can set +the default tags for a given file with lines like + +@example +#+TAGS: @@WORK @@HOME @@TENNISCLUB +#+TAGS: Laptop Car PC Sailboat +@end example + +If you have globally defined your preferred set of tags using the +variable @code{org-tag-alist}, but would like to use a dynamic tag list +in a specific file: Just add an empty TAGS option line to that file: + +@example +#+TAGS: +@end example + +The default support method for entering tags is minibuffer completion. +However, Org-mode also implements a much better method: @emph{fast tag +selection}. This method allows to select and deselect tags with a +single key per tag. To function efficiently, you should assign unique +keys to most tags. This can be done globally with + +@lisp +(setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l))) +@end lisp + +@noindent or on a per-file basis with + +@example +#+TAGS: @@WORK(w) @@HOME(h) @@TENNISCLUB(t) Laptop(l) PC(p) +@end example + +@noindent +You can also group together tags that are mutually exclusive. With +curly braces@footnote{In @code{org-mode-alist} use +@code{'(:startgroup)} and @code{'(:endgroup)}, respectively. Several +groups are allowed.} + +@example +#+TAGS: @{ @@WORK(w) @@HOME(h) @@TENNISCLUB(t) @} Laptop(l) PC(p) +@end example + +@noindent you indicate that at most one of @samp{@@WORK}, @samp{@@HOME}, +and @samp{@@TENNISCLUB} should be selected. + +@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of +these lines to activate any changes. + +If at least one tag has a selection key, pressing @kbd{C-c C-c} will +automatically present you with a special interface, listing inherited +tags, the tags of the current headline, and a list of all legal tags +with corresponding keys@footnote{Keys will automatically be assigned to +tags which have no configured keys.}. In this interface, you can use +the following keys: + +@table @kbd +@item a-z... +Pressing keys assigned to tags will add or remove them from the list of +tags in the current line. Selecting a tag in a group of mutually +exclusive tags will turn off any other tags from that group. +@kindex @key{TAB} +@item @key{TAB} +Enter a tag in the minibuffer, even if the tag is not in the predefined +list. You will be able to complete on all tags present in the buffer. +@kindex @key{SPC} +@item @key{SPC} +Clear all tags for this line. +@kindex @key{RET} +@item @key{RET} +Accept the modified set. +@item C-g +Abort without installing changes. +@item q +If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}. +@item ! +Turn off groups of mutually exclusive tags. Use this to (as an +exception) assign several tags from such a group. +@item C-c +Toggle auto-exit after the next change (see below). +If you are using expert mode, the first @kbd{C-c} will display the +selection window. +@end table + +@noindent +This method lets you assign tags to a headline with very few keys. With +the above setup, you could clear the current tags and set @samp{@@HOME}, +@samp{Laptop} and @samp{PC} tags with just the following keys: @kbd{C-c +C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@HOME} to +@samp{@@WORK} would be done with @kbd{C-c C-c w @key{RET}} or +alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag +@samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h +@key{RET} @key{RET}}. + +If you find that most of the time, you need only a single keypress to +modify your list of tags, set the variable +@code{org-fast-tag-selection-single-key}. Then you no longer have to +press @key{RET} to exit fast tag selection - it will immediately exit +after the first change. If you then occasionally need more keys, press +@kbd{C-c} to turn off auto-exit for the current tag selection process +(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c +C-c}). If you set the variable to the value @code{expert}, the special +window is not even shown for single-key tag selection, it comes up only +when you press an extra @kbd{C-c}. + +@node Tag searches, , Setting tags, Tags +@section Tag searches +@cindex tag searches +@cindex searching for tags + +Once a tags system has been set up, it can be used to collect related +information into special lists. + +@table @kbd +@kindex C-c \ +@item C-c \ +Create a sparse tree with all headlines matching a tags search. With a +@kbd{C-u} prefix argument, ignore headlines that are not a TODO line. +@kindex C-c a m +@item C-c a m +Create a global list of tag matches from all agenda files. +@xref{Matching tags and properties}. +@kindex C-c a M +@item C-c a M +Create a global list of tag matches from all agenda files, but check +only TODO items and force checking subitems (see variable +@code{org-tags-match-list-sublevels}). +@end table + +@cindex Boolean logic, for tag searches +A @i{tags} search string can use Boolean operators @samp{&} for AND and +@samp{|} for OR. @samp{&} binds more strongly than @samp{|}. +Parenthesis are currently not implemented. A tag may also be preceded +by @samp{-}, to select against it, and @samp{+} is syntactic sugar for +positive selection. The AND operator @samp{&} is optional when @samp{+} +or @samp{-} is present. Examples: + +@table @samp +@item +WORK-BOSS +Select headlines tagged @samp{:WORK:}, but discard those also tagged +@samp{:BOSS:}. +@item WORK|LAPTOP +Selects lines tagged @samp{:WORK:} or @samp{:LAPTOP:}. +@item WORK|LAPTOP&NIGHT +Like before, but require the @samp{:LAPTOP:} lines to be tagged also +@samp{NIGHT}. +@end table + +@cindex TODO keyword matching, with tags search +If you are using multi-state TODO keywords (@pxref{TODO extensions}), it +can be useful to also match on the TODO keyword. This can be done by +adding a condition after a slash to a tags match. The syntax is similar +to the tag matches, but should be applied with consideration: For +example, a positive selection on several TODO keywords can not +meaningfully be combined with boolean AND. However, @emph{negative +selection} combined with AND can be meaningful. To make sure that only +lines are checked that actually have any TODO keyword, use @kbd{C-c a +M}, or equivalently start the todo part after the slash with @samp{!}. +Examples: + +@table @samp +@item WORK/WAITING +Select @samp{:WORK:}-tagged TODO lines with the specific TODO +keyword @samp{WAITING}. +@item WORK/!-WAITING-NEXT +Select @samp{:WORK:}-tagged TODO lines that are neither @samp{WAITING} +nor @samp{NEXT} +@item WORK/+WAITING|+NEXT +Select @samp{:WORK:}-tagged TODO lines that are either @samp{WAITING} or +@samp{NEXT}. +@end table + +@cindex regular expressions, with tags search +Any element of the tag/todo match can be a regular expression - in this +case it must be enclosed in curly braces. For example, +@samp{WORK+@{^BOSS.*@}} matches headlines that contain the tag +@samp{WORK} and any tag @i{starting} with @samp{BOSS}. + +@cindex level, require for tags match +You can also require a headline to be of a certain level, by writing +instead of any TAG an expression like @samp{LEVEL=3}. For example, a +search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that +have the tag BOSS and are @emph{not} marked with the todo keyword DONE. + +@node Properties and columns, Timestamps, Tags, Top +@chapter Properties and Columns +@cindex properties + +Properties are a set of key-value pairs associated with an entry. There +are two main applications for properties in Org-mode. First, properties +are like tags, but with a value. For example, in a file where you +document bugs and plan releases of a piece of software, instead of using +tags like @code{:release_1:}, @code{:release_2:}, it can be more +efficient to use a property @code{RELEASE} with a value @code{1.0} or +@code{2.0}. Second, you can use properties to implement (very basic) +database capabilities in an Org-mode buffer, for example to create a +list of Music CD's you own. You can edit and view properties +conveniently in column view (@pxref{Column view}). + +@menu +* Property syntax:: How properties are spelled out +* Special properties:: Access to other Org-mode features +* Property searches:: Matching property values +* Column view:: Tabular viewing and editing +* Property API:: Properties for Lisp programmers +@end menu + +@node Property syntax, Special properties, Properties and columns, Properties and columns +@section Property Syntax +@cindex property syntax +@cindex drawer, for properties + +Properties are key-value pairs. They need to be inserted into a special +drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property +is specified on a single line, with the key (surrounded by colons) +first, and the value after it. Here is an example: + +@example +* CD collection +** Classic +*** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Artist: Glen Gould + :Publisher: Deutsche Grammphon + :NDisks: 1 + :END: +@end example + +You may define the allowed values for a particular property @samp{XYZ} +by setting a property @samp{XYZ_ALL}. This special property is +@emph{inherited}, so if you set it in a level 1 entry, it will apply to +the entire tree. When allowed values are defined, setting the +corresponding property becomes easier and is less prone to typing +errors. For the example with the CD collection, we can predefine +publishers and the number of disks in a box like this: + +@example +* CD collection + :PROPERTIES: + :NDisks_ALL: 1 2 3 4 + :Publisher_ALL: "Deutsche Grammophon" Phillips EMI + :END: +@end example + +If you want to set properties that can be inherited by any entry in a +file, use a line like + +@example +#+PROPERTY: NDisks_ALL 1 2 3 4 +@end example + +Property values set with the global variable +@code{org-global-properties} can be inherited by all entries in all +Org-mode files. + +@noindent +The following commands help to work with properties: + +@table @kbd +@kindex M-@key{TAB} +@item M-@key{TAB} +After an initial colon in a line, complete property keys. All keys used +in the current file will be offered as possible completions. +@item M-x org-insert-property-drawer +Insert a property drawer into the current entry. The drawer will be +inserted early in the entry, but after the lines with planning +information like deadlines. +@kindex C-c C-c +@item C-c C-c +With the cursor in a property drawer, this executes property commands. +@item C-c C-c s +Set a property in the current entry. Both the property and the value +can be inserted using completion. +@kindex S-@key{right} +@kindex S-@key{left} +@item S-@key{left}/@key{right} +Switch property at point to the next/previous allowed value. +@item C-c C-c d +Remove a property from the current entry. +@item C-c C-c D +Globally remove a property, from all entries in the current file. +@end table + +@node Special properties, Property searches, Property syntax, Properties and columns +@section Special Properties +@cindex properties, special + +Special properties provide alternative access method to Org-mode +features discussed in the previous chapters, like the TODO state or the +priority of an entry. This interface exists so that you can include +these states into columns view (@pxref{Column view}). The following +property names are special and should not be used as keys in the +properties drawer: + +@example +TODO @r{The TODO keyword of the entry.} +TAGS @r{The tags defined directly in the headline.} +ALLTAGS @r{All tags, including inherited ones.} +PRIORITY @r{The priority of the entry, a string with a single letter.} +DEADLINE @r{The deadline time string, without the angular brackets.} +SCHEDULED @r{The scheduling time stamp, without the angular brackets.} +@end example + +@node Property searches, Column view, Special properties, Properties and columns +@section Property searches +@cindex properties, searching + +To create sparse trees and special lists with selection based on +properties, the same commands are used as for tag searches (@pxref{Tag +searches}), and the same logic applies. For example, a search string + +@example ++WORK-BOSS+PRIORITY="A"+coffee="unlimited"+with=@{Sarah\|Denny@} +@end example + +@noindent +finds entries tagged @samp{:WORK:} but not @samp{:BOSS:}, which +also have a priority value @samp{A}, a @samp{:coffee:} property with the +value @samp{unlimited}, and a @samp{:with:} property that is matched by +the regular expression @samp{Sarah\|Denny}. + +@node Column view, Property API, Property searches, Properties and columns +@section Column View + +A great way to view and edit properties in an outline tree is +@emph{column view}. In column view, each outline item is turned into a +table row. Columns in this table provide access to properties of the +entries. Org-mode implements columns by overlaying a tabular structure +over the headline of each item. While the headlines have been turned +into a table row, you can still change the visibility of the outline +tree. For example, you get a compact table by switching to CONTENTS +view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view +is active), but you can still open, read, and edit the entry below each +headline. Or, you can switch to column view after executing a sparse +tree command and in this way get a table only for the selected items. +Column view also works in agenda buffers (@pxref{Agenda views}) where +queries have collected selected items, possibly from a number of files. + +@menu +* Defining columns:: The COLUMNS format property +* Using column view:: How to create and use column view +@end menu + +@node Defining columns, Using column view, Column view, Column view +@subsection Defining Columns +@cindex column view, for properties +@cindex properties, column view + +Setting up a column view first requires defining the columns. This is +done by defining a column format line. + +@menu +* Scope of column definitions:: Where defined, where valid? +* Column attributes:: Appearance and content of a column +@end menu + +@node Scope of column definitions, Column attributes, Defining columns, Defining columns +@subsubsection Scope of column definitions + +To define a column format for an entire file, use a line like + +@example +#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO +@end example + +To specify a format that only applies to a specific tree, add a COLUMNS +property to the top node of that tree, for example +@example +** Top node for columns view + :PROPERTIES: + :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO + :END: +@end example + +If a @code{COLUMNS} property is present in an entry, it defines columns +for the entry itself, and for the entire subtree below it. Since the +column definition is part of the hierarchical structure of the document, +you can define columns on level 1 that are general enough for all +sublevels, and more specific columns further down, when you edit a +deeper part of the tree. + +@node Column attributes, , Scope of column definitions, Defining columns +@subsubsection Column attributes +A column definition sets the attributes of a column. The general +definition looks like this: + +@example + %[width]property[(title)][@{summary-type@}] +@end example + +@noindent +Except for the percent sign and the property name, all items are +optional. The individual parts have the following meaning: + +@example +width @r{An integer specifying the width of the column in characters.} + @r{If omitted, the width will be determined automatically.} +property @r{The property that should be edited in this column.} +(title) @r{The header text for the column. If omitted, the} + @r{property name is used.} +@{summary-type@} @r{The summary type. If specified, the column values for} + @r{parent nodes are computed from the children.} + @r{Supported summary types are:} + @{+@} @r{Sum numbers in this column.} + @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.} + @{X@} @r{Checkbox status, [X] if all children are [X].} +@end example + +@noindent +Here is an example for a complete columns definition, along with allowed +values. + +@example +:COLUMNS: %20ITEM %9Approved(Approved?)@{X@} %Owner %11Status %10Time_Spent@{:@} +:Owner_ALL: Tammy Mark Karl Lisa Don +:Status_ALL: "In progress" "Not started yet" "Finished" "" +:Approved_ALL: "[ ]" "[X]" +@end example + +The first column, @samp{%25ITEM}, means the first 25 characters of the +item itself, i.e. of the headline. You probably always should start the +column definition with the ITEM specifier. The other specifiers create +columns @samp{Owner} with a list of names as allowed values, for +@samp{Status} with four different possible values, and for a checkbox +field @samp{Approved}. When no width is given after the @samp{%} +character, the column will be exactly as wide as it needs to be in order +to fully display all values. The @samp{Approved} column does have a +modified title (@samp{Approved?}, with a question mark). Summaries will +be created for the @samp{Time_Spent} column by adding time duration +expressions like HH:MM, and for the @samp{Approved} column, by providing +an @samp{[X]} status if all children have been checked. + +@node Using column view, , Defining columns, Column view +@subsection Using Column View + +@table @kbd +@tsubheading{Turning column view on and off} +@kindex C-c C-x C-c +@item C-c C-x C-c +Create the column view for the local environment. This command searches +the hierarchy, up from point, for a @code{COLUMNS} property that defines +a format. When one is found, the column view table is established for +the entire tree, starting from the entry that contains the @code{COLUMNS} +property. If none is found, the format is taken from the @code{#+COLUMNS} +line or from the variable @code{org-columns-default-format}, and column +view is established for the current entry and its subtree. +@kindex q +@item q +Exit column view. +@tsubheading{Editing values} +@item @key{left} @key{right} @key{up} @key{down} +Move through the column view from field to field. +@kindex S-@key{left} +@kindex S-@key{right} +@item S-@key{left}/@key{right} +Switch to the next/previous allowed value of the field. For this, you +have to have specified allowed values for a property. +@kindex n +@kindex p +@itemx n / p +Same as @kbd{S-@key{left}/@key{right}} +@kindex e +@item e +Edit the property at point. For the special properties, this will +invoke the same interface that you normally use to change that +property. For example, when editing a TAGS property, the tag completion +or fast selection interface will pop up. +@kindex v +@item v +View the full value of this property. This is useful if the width of +the column is smaller than that of the value. +@kindex a +@item a +Edit the list of allowed values for this property. If the list is found +in the hierarchy, the modified values is stored there. If no list is +found, the new value is stored in the first entry that is part of the +current column view. +@tsubheading{Modifying the table structure} +@kindex < +@kindex > +@item < / > +Make the column narrower/wider by one character. +@kindex S-M-@key{right} +@item S-M-@key{right} +Insert a new column, to the right of the current column. +@kindex S-M-@key{left} +@item S-M-@key{left} +Delete the current column. +@end table + +@node Property API, , Column view, Properties and columns +@section The Property API +@cindex properties, API +@cindex API, for properties + +There is a full API for accessing and changing properties. This API can +be used by Emacs Lisp programs to work with properties and to implement +features based on them. For more information see @ref{Using the +property API}. + +@node Timestamps, Agenda views, Properties and columns, Top +@chapter Timestamps +@cindex time stamps +@cindex date stamps + +Items can be labeled with timestamps to make them useful for project +planning. + +@menu +* Time stamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Progress logging:: Documenting when what work was done. +@end menu + + +@node Time stamps, Creating timestamps, Timestamps, Timestamps +@section Time stamps, deadlines and scheduling +@cindex time stamps +@cindex ranges, time +@cindex date stamps +@cindex deadlines +@cindex scheduling + +A time stamp is a specification of a date (possibly with time or a range +of times) in a special format, either @samp{<2003-09-16 Tue>} or +@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue +12:00-12:30>}@footnote{This is the standard ISO date/time format. If +you cannot get used to these, see @ref{Custom time format}}. A time +stamp can appear anywhere in the headline or body of an org-tree entry. +Its presence causes entries to be shown on specific dates in the agenda +(@pxref{Weekly/Daily agenda}). We distinguish: + +@table @var +@item Plain time stamp +@cindex timestamp +A simple time stamp just assigns a date/time to an item. This is just +like writing down an appointment in a paper agenda, or like writing down +an event in a diary, when you want to take note of when something +happened. In the timeline and agenda displays, the headline of an entry +associated with a plain time stamp will be shown exactly on that date. + +@example +* Meet Peter at the movies <2006-11-01 Wed 19:15> +* Discussion on climate change <2006-11-02 Thu 20:00-22:00> +@end example + +@item Time stamp with repeater interval +@cindex timestamp, with repeater interval +A time stamp may contain a @emph{repeater interval}, indicating that it +applies not only on the given date, but again and again after a certain +interval of N days (d), weeks (w), months(m), or years(y). The +following will show up in the agenda every Wednesday: + +@example +* Pick up Sam at school <2007-05-16 Wed 12:30 +1w> +@end example + +@item Diary-style sexp entries +For more complex date specifications, Org-mode supports using the +special sexp diary entries implemented in the Emacs calendar/diary +package. For example + +@example +* The nerd meeting on every 2nd Thursday of the month + <%%(diary-float t 4 2)> +@end example + +@item Time/Date range +@cindex timerange +@cindex date range +Two time stamps connected by @samp{--} denote a range. The headline +will be shown on the first and last day of the range, and on any dates +that are displayed and fall in the range. Here is an example: + +@example +** Meeting in Amsterdam + <2004-08-23 Mon>--<2004-08-26 Thu> +@end example + +@item Inactive time stamp +@cindex timestamp, inactive +@cindex inactive timestamp +Just like a plain time stamp, but with square brackets instead of +angular ones. These time stamps are inactive in the sense that they do +@emph{not} trigger an entry to show up in the agenda. + +@example +* Gillian comes late for the fifth time [2006-11-01 Wed] +@end example + +@end table + +@node Creating timestamps, Deadlines and scheduling, Time stamps, Timestamps +@section Creating timestamps +@cindex creating timestamps +@cindex timestamps, creating + +For Org-mode to recognize time stamps, they need to be in the specific +format. All commands listed below produce time stamps in the correct +format. + +@table @kbd +@kindex C-c . +@item C-c . +Prompt for a date and insert a corresponding time stamp. When the +cursor is at a previously used time stamp, it is updated to NOW. When +this command is used twice in succession, a time range is inserted. +@c +@kindex C-u C-c . +@item C-u C-c . +Like @kbd{C-c .}, but use the alternative format which contains date +and time. The default time can be rounded to multiples of 5 minutes, +see the option @code{org-time-stamp-rounding-minutes}. +@c +@kindex C-c ! +@item C-c ! +Like @kbd{C-c .}, but insert an inactive time stamp that will not cause +an agenda entry. +@c +@kindex C-c < +@item C-c < +Insert a time stamp corresponding to the cursor date in the Calendar. +@c +@kindex C-c > +@item C-c > +Access the Emacs calendar for the current date. If there is a +timestamp in the current line, goto the corresponding date +instead. +@c +@kindex C-c C-o +@item C-c C-o +Access the agenda for the date given by the time stamp or -range at +point (@pxref{Weekly/Daily agenda}). +@c +@kindex S-@key{left} +@kindex S-@key{right} +@item S-@key{left} +@itemx S-@key{right} +Change date at cursor by one day. These key bindings conflict with +CUA-mode (@pxref{Conflicts}). +@c +@kindex S-@key{up} +@kindex S-@key{down} +@item S-@key{up} +@itemx S-@key{down} +Change the item under the cursor in a timestamp. The cursor can be on a +year, month, day, hour or minute. Note that if the cursor is in a +headline and not at a time stamp, these same keys modify the priority of +an item. (@pxref{Priorities}). The key bindings also conflict with +CUA-mode (@pxref{Conflicts}). +@c +@kindex C-c C-y +@cindex evaluate time range +@item C-c C-y +Evaluate a time range by computing the difference between start and +end. With prefix arg, insert result after the time range (in a table: +into the following column). +@end table + + +@menu +* The date/time prompt:: How org-mode helps you entering date and time +* Custom time format:: Making dates look differently +@end menu + +@node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps +@subsection The date/time prompt +@cindex date, reading in minibuffer +@cindex time, reading in minibuffer + +When Org-mode prompts for a date/time, the prompt suggests to enter an +ISO date. But it will in fact accept any string containing some date +and/or time information. You can, for example, use @kbd{C-y} to paste a +(possibly multi-line) string copied from an email message. Org-mode +will find whatever information is in there and will replace anything not +specified with the current date and time. For example: + +@example + 3-2-5 --> 2003-02-05 + feb 15 --> currentyear-02-15 + sep 12 9 --> 2009-09-12 + 12:45 --> today 12:45 + 22 sept 0:34 --> currentyear-09-22 0:34 + 12 --> currentyear-currentmonth-12 + Fri --> nearest Friday (today or later) + +4 --> 4 days from now (if +N is the only thing given) +@end example + +The function understands English month and weekday abbreviations. If +you want to use unabbreviated names and/or other languages, configure +the variables @code{parse-time-months} and @code{parse-time-weekdays}. + +@cindex calendar, for selecting date +Parallel to the minibuffer prompt, a calendar is popped up@footnote{If +you don't need/want the calendar, configure the variable +@code{org-popup-calendar-for-date-prompt}.}. When you exit the date +prompt, either by clicking on a date in the calendar, or by pressing +@key{RET}, the date selected in the calendar will be combined with the +information entered at the prompt. You can control the calendar fully +from the minibuffer: + +@table @kbd +@kindex < +@item < +Scroll calendar backwards by one month. +@kindex > +@item > +Scroll calendar forwards by one month. +@kindex mouse-1 +@item mouse-1 +Select date by clicking on it. +@kindex S-@key{right} +@item S-@key{right} +One day forward. +@kindex S-@key{left} +@item S-@key{left} +One day back. +@kindex S-@key{down} +@item S-@key{down} +One week forward. +@kindex S-@key{up} +@item S-@key{up} +One week back. +@kindex M-S-@key{right} +@item M-S-@key{right} +One month forward. +@kindex M-S-@key{left} +@item M-S-@key{left} +One month back. +@kindex @key{RET} +@item @key{RET} +Choose date in calendar (only if nothing was typed into minibuffer). +@end table + +@node Custom time format, , The date/time prompt, Creating timestamps +@subsection Custom time format +@cindex custom date/time format +@cindex time format, custom +@cindex date format, custom + +Org-mode uses the standard ISO notation for dates and times as it is +defined in ISO 8601. If you cannot get used to this and require another +representation of date and time to keep you happy, you can get it by +customizing the variables @code{org-display-custom-times} and +@code{org-time-stamp-custom-formats}. + +@table @kbd +@kindex C-c C-x C-t +@item C-c C-x C-t +Toggle the display of custom formats for dates and times. +@end table + +@noindent +Org-mode needs the default format for scanning, so the custom date/time +format does not @emph{replace} the default format - instead it is put +@emph{over} the default format using text properties. This has the +following consequences: +@itemize @bullet +@item +You cannot place the cursor onto a time stamp anymore, only before or +after. +@item +The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust +each component of a time stamp. If the cursor is at the beginning of +the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day, +just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the +time will be changed by one minute. +@item +If the time stamp contains a range of clock times or a repeater, these +will not be overlayed, but remain in the buffer as they were. +@item +When you delete a time stamp character-by-character, it will only +disappear from the buffer after @emph{all} (invisible) characters +belonging to the ISO timestamp have been removed. +@item +If the custom time stamp format is longer than the default and you are +using dates in tables, table alignment will be messed up. If the custom +format is shorter, things do work as expected. +@end itemize + + +@node Deadlines and scheduling, Progress logging, Creating timestamps, Timestamps +@section Deadlines and Scheduling + +A time stamp may be preceded by special keywords to facilitate planning +of work: + +@table @var +@item DEADLINE +@cindex DEADLINE keyword +The task (most likely a TODO item) is supposed to be finished on that +date, and it will be listed then. In addition, the compilation for +@emph{today} will carry a warning about the approaching or missed +deadline, starting @code{org-deadline-warning-days} before the due date, +and continuing until the entry is marked DONE. An example: + +@example +*** TODO write article about the Earth for the Guide + The editor in charge is [[bbdb:Ford Prefect]] + DEADLINE: <2004-02-29 Sun> +@end example + +You can specify a different lead time for warnings for a specific +deadlines using the following syntax. Here is an example with a warning +period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. + +@item SCHEDULED +@cindex SCHEDULED keyword +You are planning to start working on that task on the given date. The +headline will be listed under the given date@footnote{It will still be +listed on that date after it has been marked DONE. If you don't like +this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In +addition, a reminder that the scheduled date has passed will be present +in the compilation for @emph{today}, until the entry is marked DONE. +I.e., the task will automatically be forwarded until completed. + +@example +*** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> +@end example +@end table + +@menu +* Inserting deadline/schedule:: Planning items +* Repeated tasks:: Items that show up again and again +@end menu + +@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling +@subsection Inserting deadline/schedule + +The following commands allow to quickly insert a deadline or to schedule +an item: + +@table @kbd +@c +@kindex C-c C-d +@item C-c C-d +Insert @samp{DEADLINE} keyword along with a stamp. The insertion will +happen in the line directly following the headline. +@c FIXME Any CLOSED timestamp will be removed.???????? +@c +@kindex C-c C-w +@cindex sparse tree, for deadlines +@item C-c C-w +Create a sparse tree with all deadlines that are either past-due, or +which will become due within @code{org-deadline-warning-days}. +With @kbd{C-u} prefix, show all deadlines in the file. With a numeric +prefix, check that many days. For example, @kbd{C-1 C-c C-w} shows +all deadlines due tomorrow. +@c +@kindex C-c C-s +@item C-c C-s +Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will +happen in the line directly following the headline. Any CLOSED +timestamp will be removed. +@end table + +@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling +@subsection Repeated Tasks + +Some tasks need to be repeated again and again, and Org-mode therefore +allows to use a repeater in a DEADLINE or SCHEDULED time stamp, for +example: +@example +** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> +@end example + +Deadlines and scheduled items produce entries in the agenda when they +are over-due, so it is important to be able to mark such an entry as +completed once you have done so. When you mark a DEADLINE or a SCHEDULE +with the todo keyword DONE, it will no longer produce entries in the +agenda. The problem with this is, however, that then also the +@emph{next} instance of the repeated entry will not be active. Org-mode +deals with this in the following way: When you try to mark such an entry +DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating +time stamp by the repeater interval, and immediately set the entry state +back to TODO. In the example above, setting the state to DONE would +actually switch the date like this: + +@example +** TODO Pay the rent + DEADLINE: <2005-11-01 Tue +1m> +@end example + +You will also be prompted for a note that will be put under the DEADLINE +line to keep a record that you actually acted on the previous instance +of this deadline. + +As a consequence of shifting the base date, this entry will no longer be +visible in the agenda when checking past dates, but all future instances +will be visible. + +You may have both scheduling and deadline information for a specific +task - just make sure that the repeater intervals on both are the same. + +@node Progress logging, , Deadlines and scheduling, Timestamps +@section Progress Logging +@cindex progress logging +@cindex logging, of progress + +Org-mode can automatically record a time stamp when you mark a TODO item +as DONE, or even each time when you change the state of a TODO item. +You can also measure precisely the time you spent on specific items in a +project by starting and stopping a clock when you start and stop working +on an aspect of a project. + +@menu +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Clocking work time:: When exactly did you work on this item? +@end menu + +@node Closing items, Tracking TODO state changes, Progress logging, Progress logging +@subsection Closing items + +If you want to keep track of @emph{when} a certain TODO item was +finished, turn on logging with@footnote{The corresponding in-buffer +setting is: @code{#+STARTUP: logdone}} + +@lisp +(setq org-log-done t) +@end lisp + +@noindent +Then each time you turn a TODO entry into DONE using either @kbd{C-c +C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line +@samp{CLOSED: [timestamp]} will be inserted just after the headline. If +you turn the entry back into a TODO item through further state cycling, +that line will be removed again. In the timeline (@pxref{Timeline}) and +in the agenda (@pxref{Weekly/Daily agenda}), you can then use the +@kbd{l} key to display the TODO items closed on each day, giving you an +overview of what has been done on a day. If you want to record a note +along with the timestamp, use@footnote{The corresponding in-buffer +setting is: @code{#+STARTUP: lognotedone}} + +@lisp +(setq org-log-done '(done)) +@end lisp + +@node Tracking TODO state changes, Clocking work time, Closing items, Progress logging +@subsection Tracking TODO state changes + +When TODO keywords are used as workflow states (@pxref{Workflow +states}), you might want to keep track of when a state change occurred, +and you may even want to attach notes to that state change. With the +setting + +@lisp +(setq org-log-done '(state)) +@end lisp + +@noindent +each state change will prompt you for a note that will be attached to +the current headline. Very likely you do not want this verbose tracking +all the time, so it is probably better to configure this behavior with +in-buffer options. For example, if you are tracking purchases, put +these into a separate file that starts with: + +@example +#+SEQ_TODO: TODO ORDERED INVOICE PAYED RECEIVED SENT +#+STARTUP: lognotestate +@end example + + +@node Clocking work time, , Tracking TODO state changes, Progress logging +@subsection Clocking work time + +Org-mode allows you to clock the time you spent on specific tasks in a +project. When you start working on an item, you can start the clock. +When you stop working on that task, or when you mark the task done, the +clock is stopped and the corresponding time interval is recorded. It +also computes the total time spent on each subtree of a project. + +@table @kbd +@kindex C-c C-x C-i +@item C-c C-x C-i +Start the clock on the current item (clock-in). This inserts the CLOCK +keyword together with a timestamp. +@kindex C-c C-x C-o +@item C-c C-x C-o +Stop the clock (clock-out). The inserts another timestamp at the same +location where the clock was last started. It also directly computes +the resulting time in inserts it after the time range as @samp{=> +HH:MM}. See the variable @code{org-log-done} for the possibility to +record an additional note together with the clock-out time +stamp@footnote{The corresponding in-buffer setting is: @code{#+STARTUP: +lognoteclock-out}}. +@kindex C-c C-y +@item C-c C-y +Recompute the time interval after changing one of the time stamps. This +is only necessary if you edit the time stamps directly. If you change +them with @kbd{S-@key{cursor}} keys, the update is automatic. +@kindex C-c C-t +@item C-c C-t +Changing the TODO state of an item to DONE automatically stops the clock +if it is running in this same item. +@kindex C-c C-x C-x +@item C-c C-x C-x +Cancel the current clock. This is useful if a clock was started by +mistake, or if you ended up working on something else. +@kindex C-c C-x C-d +@item C-c C-x C-d +Display time summaries for each subtree in the current buffer. This +puts overlays at the end of each headline, showing the total time +recorded under that heading, including the time of any subheadings. You +can use visibility cycling to study the tree, but the overlays disappear +when you change the buffer (see variable +@code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}. +@kindex C-c C-x C-r +@item C-c C-x C-r +Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock +report as an org-mode table into the current file. +@example +#+BEGIN: clocktable :maxlevel 2 :emphasize nil + +#+END: clocktable +@end example +@noindent +If such a block already exists, its content is replaced by the new +table. The @samp{BEGIN} line can specify options: +@example +:maxlevels @r{Maximum level depth to which times are listed in the table.} +:emphasize @r{When @code{t}, emphasize level one and level two items} +:block @r{The time block to consider. This block is specified relative} + @r{to the current time and may be any of these keywords:} + @r{@code{today}, @code{yesterday}, @code{thisweek}, @code{lastweek},} + @r{@code{thismonth}, @code{lastmonth}, @code{thisyear}, or @code{lastyear}}. +:tstart @r{A time string specifying when to start considering times} +:tend @r{A time string specifying when to stop considering times} +@end example +So to get a clock summary for the current day, you could write +@example +#+BEGIN: clocktable :maxlevel 2 :block today + +#+END: clocktable +@end example +and to use a specific time range you could write@footnote{Note that all +parameters must be specified in a single line - the line is broken here +only to fit it onto the manual.} +@example +#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" + :tend "<2006-08-10 Thu 12:00>" + +#+END: clocktable +@end example +@kindex C-u C-c C-x C-u +@item C-u C-c C-x C-u +Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if +you have several clocktable blocks in a buffer. +@end table + +The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in +the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been +worked on or closed during a day. + +@node Agenda views, Embedded LaTeX, Timestamps, Top +@chapter Agenda Views +@cindex agenda views + +Due to the way Org-mode works, TODO items, time-stamped items, and +tagged headlines can be scattered throughout a file or even a number of +files. To get an overview over open action items, or over events that +are important for a particular date, this information must be collected, +sorted and displayed in an organized way. + +Org-mode can select items based on various criteria, and display them +in a separate buffer. Six different view types are provided: + +@itemize @bullet +@item +an @emph{agenda} that is like a calendar and shows information +for specific dates, +@item +a @emph{TODO list} that covers all unfinished +action items, +@item +a @emph{tags view}, showings headlines based on +the tags associated with them, +@item +a @emph{timeline view} that shows all events in a single Org-mode file, +in time-sorted view, +@item +a @emph{stuck projects view} showing projects that currently don't move +along, and +@item +@emph{custom views} that are special tag/keyword searches and +combinations of different views. +@end itemize + +@noindent +The extracted information is displayed in a special @emph{agenda +buffer}. This buffer is read-only, but provides commands to visit the +corresponding locations in the original Org-mode files, and even to +edit these files remotely. + +Two variables control how the agenda buffer is displayed and whether the +window configuration is restored when the agenda exits: +@code{org-agenda-window-setup} and +@code{org-agenda-restore-windows-after-quit}. + +@menu +* Agenda files:: Files being searched for agenda information +* Agenda dispatcher:: Keyboard access to agenda views +* Built-in agenda views:: What is available out of the box? +* Presentation and sorting:: How agenda items are prepared for display +* Agenda commands:: Remote editing of org trees +* Custom agenda views:: Defining special searches and views +@end menu + +@node Agenda files, Agenda dispatcher, Agenda views, Agenda views +@section Agenda files +@cindex agenda files +@cindex files for agenda + +The information to be shown is collected from all @emph{agenda files}, +the files listed in the variable @code{org-agenda-files}@footnote{If the +value of that variable is not a list, but a single file name, then the +list of agenda files will be maintained in that external file.}. Thus even +if you only work with a single Org-mode file, this file should be put +into that list@footnote{When using the dispatcher, pressing @kbd{1} +before selecting a command will actually limit the command to the +current file, and ignore @code{org-agenda-files} until the next +dispatcher command.}. You can customize @code{org-agenda-files}, but +the easiest way to maintain it is through the following commands + +@cindex files, adding to agenda list +@table @kbd +@kindex C-c [ +@item C-c [ +Add current file to the list of agenda files. The file is added to +the front of the list. If it was already in the list, it is moved to +the front. With prefix arg, file is added/moved to the end. +@kindex C-c ] +@item C-c ] +Remove current file from the list of agenda files. +@kindex C-, +@kindex C-' +@item C-, +@itemx C-' +Cycle through agenda file list, visiting one file after the other. +@end table + +@noindent +The Org menu contains the current list of files and can be used +to visit any of them. + +@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views +@section The agenda dispatcher +@cindex agenda dispatcher +@cindex dispatching agenda commands +The views are created through a dispatcher that should be bound to a +global key, for example @kbd{C-c a} (@pxref{Installation}). In the +following we will assume that @kbd{C-c a} is indeed how the dispatcher +is accessed and list keyboard access to commands accordingly. After +pressing @kbd{C-c a}, an additional letter is required to execute a +command. The dispatcher offers the following default commands: +@table @kbd +@item a +Create the calendar-like agenda (@pxref{Weekly/Daily agenda}). +@item t @r{/} T +Create a list of all TODO items (@pxref{Global TODO list}). +@item m @r{/} M +Create a list of headlines matching a TAGS expression (@pxref{Matching +tags and properties}). +@item L +Create the timeline view for the current buffer (@pxref{Timeline}). +@item # @r{/} ! +Create a list of stuck projects (@pxref{Stuck projects}). +@item 1 +Restrict an agenda command to the current buffer. After pressing +@kbd{1}, you still need to press the character selecting the command. +@item 0 +If there is an active region, restrict the following agenda command to +the region. Otherwise, restrict it to the current subtree. After +pressing @kbd{0}, you still need to press the character selecting the +command. +@end table + +You can also define custom commands that will be accessible through the +dispatcher, just like the default commands. This includes the +possibility to create extended agenda buffers that contain several +blocks together, for example the weekly agenda, the global TODO list and +a number of special tags matches. @xref{Custom agenda views}. + +@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views +@section The built-in agenda views + +In this section we describe the built-in views. + +@menu +* Weekly/Daily agenda:: The calendar page with current tasks +* Global TODO list:: All unfinished action items +* Matching tags and properties:: Structured information with fine-tuned search +* Timeline:: Time-sorted view for single file +* Stuck projects:: Find projects you need to review +@end menu + +@node Weekly/Daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views +@subsection The weekly/daily agenda +@cindex agenda +@cindex weekly agenda +@cindex daily agenda + +The purpose of the weekly/daily @emph{agenda} is to act like a page of a +paper agenda, showing all the tasks for the current week or day. + +@table @kbd +@cindex org-agenda, command +@kindex C-c a a +@item C-c a a +Compile an agenda for the current week from a list of org files. The +agenda shows the entries for each day. With a @kbd{C-u} prefix (or +when the variable @code{org-agenda-include-all-todo} is @code{t}), all +unfinished TODO items (including those without a date) are also listed at +the beginning of the buffer, before the first date.@* +@end table + +Remote editing from the agenda buffer means, for example, that you can +change the dates of deadlines and appointments from the agenda buffer. +The commands available in the Agenda buffer are listed in @ref{Agenda +commands}. + +@subsubheading Calendar/Diary integration +@cindex calendar integration +@cindex diary integration + +Emacs contains the calendar and diary by Edward M. Reingold. The +calendar displays a three-month calendar with holidays from different +countries and cultures. The diary allows you to keep track of +anniversaries, lunar phases, sunrise/set, recurrent appointments +(weekly, monthly) and more. In this way, it is quite complementary to +Org-mode. It can be very useful to combine output from Org-mode with +the diary. + +In order to include entries from the Emacs diary into Org-mode's +agenda, you only need to customize the variable + +@lisp +(setq org-agenda-include-diary t) +@end lisp + +@noindent After that, everything will happen automatically. All diary +entries including holidays, anniversaries etc will be included in the +agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and +@key{RET} can be used from the agenda buffer to jump to the diary +file in order to edit existing diary entries. The @kbd{i} command to +insert new entries for the current date works in the agenda buffer, as +well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display +Sunrise/Sunset times, show lunar phases and to convert to other +calendars, respectively. @kbd{c} can be used to switch back and forth +between calendar and agenda. + +If you are using the diary only for sexp entries and holidays, it is +faster to not use the above setting, but instead to copy or even move +the entries into an Org-mode file. Org-mode evaluates diary-style sexp +entries, and does it faster because there is no overhead for first +creating the diary display. Note that the sexp entries must start at +the left margin, no white space is allowed before them. For example, +the following segment of an Org-mode file will be processed and entries +will be made in the agenda: + +@example +* Birthdays and similar stuff +#+CATEGORY: Holiday +%%(org-calendar-holiday) ; special function for holiday names +#+CATEGORY: Ann +%%(diary-anniversary 14 5 1956) Arthur Dent is %d years old +%%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old +@end example + +@node Global TODO list, Matching tags and properties, Weekly/Daily agenda, Built-in agenda views +@subsection The global TODO list +@cindex global TODO list +@cindex TODO list, global + +The global TODO list contains all unfinished TODO items, formatted and +collected into a single place. + +@table @kbd +@kindex C-c a t +@item C-c a t +Show the global TODO list. This collects the TODO items from all +agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in +@code{agenda-mode}, so there are commands to examine and manipulate +the TODO entries directly from that buffer (@pxref{Agenda commands}). +@kindex C-c a T +@item C-c a T +@cindex TODO keyword matching +Like the above, but allows selection of a specific TODO keyword. You +can also do this by specifying a prefix argument to @kbd{C-c a t}. With +a @kbd{C-u} prefix you are prompted for a keyword, and you may also +specify several keywords by separating them with @samp{|} as boolean OR +operator. With a numeric prefix, the Nth keyword in +@code{org-todo-keywords} is selected. +@kindex r +The @kbd{r} key in the agenda buffer regenerates it, and you can give +a prefix argument to this command to change the selected TODO keyword, +for example @kbd{3 r}. If you often need a search for a specific +keyword, define a custom command for it (@pxref{Agenda dispatcher}).@* +Matching specific TODO keywords can also be done as part of a tags +search (@pxref{Tag searches}). +@end table + +Remote editing of TODO items means that you can change the state of a +TODO entry with a single key press. The commands available in the +TODO list are described in @ref{Agenda commands}. + +@cindex sublevels, inclusion into todo list +Normally the global todo list simply shows all headlines with TODO +keywords. This list can become very long. There are two ways to keep +it more compact: +@itemize @minus +@item +Some people view a TODO item that has been @emph{scheduled} for +execution (@pxref{Time stamps}) as no longer @emph{open}. Configure the +variable @code{org-agenda-todo-ignore-scheduled} to exclude scheduled +items from the global TODO list. +@item +TODO items may have sublevels to break up the task into subtasks. In +such cases it may be enough to list only the highest level TODO headline +and omit the sublevels from the global list. Configure the variable +@code{org-agenda-todo-list-sublevels} to get this behavior. +@end itemize + +@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views +@subsection Matching Tags and Properties +@cindex matching, of tags +@cindex matching, of properties +@cindex tags view + +If headlines in the agenda files are marked with @emph{tags} +(@pxref{Tags}), you can select headlines based on the tags that apply +to them and collect them into an agenda buffer. + +@table @kbd +@kindex C-c a m +@item C-c a m +Produce a list of all headlines that match a given set of tags. The +command prompts for a selection criterion, which is a boolean logic +expression with tags, like @samp{+WORK+URGENT-WITHBOSS} or +@samp{WORK|HOME} (@pxref{Tags}). If you often need a specific search, +define a custom command for it (@pxref{Agenda dispatcher}). +@kindex C-c a M +@item C-c a M +Like @kbd{C-c a m}, but only select headlines that are also TODO items +and force checking subitems (see variable +@code{org-tags-match-list-sublevels}). Matching specific todo keywords +together with a tags match is also possible, see @ref{Tag searches}. +@end table + +The commands available in the tags list are described in @ref{Agenda +commands}. + +@node Timeline, Stuck projects, Matching tags and properties, Built-in agenda views +@subsection Timeline for a single file +@cindex timeline, single file +@cindex time-sorted view + +The timeline summarizes all time-stamped items from a single Org-mode +file in a @emph{time-sorted view}. The main purpose of this command is +to give an overview over events in a project. + +@table @kbd +@kindex C-c a L +@item C-c a L +Show a time-sorted view of the org file, with all time-stamped items. +When called with a @kbd{C-u} prefix, all unfinished TODO entries +(scheduled or not) are also listed under the current date. +@end table + +@noindent +The commands available in the timeline buffer are listed in +@ref{Agenda commands}. + + +@node Stuck projects, , Timeline, Built-in agenda views +@subsection Stuck projects + +If you are following a system like David Allen's GTD to organize your +work, one of the ``duties'' you have is a regular review to make sure +that all projects move along. A @emph{stuck} project is a project that +has no defined next actions, so it will never show up in the TODO lists +Org-mode produces. During the review, you need to identify such +projects and define next actions for them. + +@table @kbd +@kindex C-c a # +@item C-c a # +List projects that are stuck. +@kindex C-c a ! +@item C-c a ! +Customize the variable @code{org-stuck-projects} to define what a stuck +project is and how to find it. +@end table + +You almost certainly will have to configure this view before it will +work for you. The built-in default assumes that all your projects are +level-2 headlines, and that a project is not stuck if it has at least +one entry marked with a todo keyword TODO or NEXT or NEXTACTION. + +Lets assume that you, in your own way of using Org-mode, identify +projects with a tag PROJECT, and that you use a todo keyword MAYBE to +indicate a project that should not be considered yet. Lets further +assume that the todo keyword DONE marks finished projects, and that NEXT +and TODO indicate next actions. The tag @@SHOP indicates shopping and +is a next action even without the NEXT tag. Finally, if the project +contains the special word IGNORE anywhere, it should not be listed +either. In this case you would start by identifying eligible projects +with a tags/todo match @samp{+PROJECT/-MAYBE-DONE}, and then check for +TODO, NEXT, @@SHOP, and IGNORE in the subtree to identify projects that +are not stuck. The correct customization for this is + +@lisp +(setq org-stuck-projects + '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP") + "\\<IGNORE\\>")) +@end lisp + + +@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views +@section Presentation and sorting +@cindex presentation, of agenda items + +Before displaying items in an agenda view, Org-mode visually prepares +the items and sorts them. Each item occupies a single line. The line +starts with a @emph{prefix} that contains the @emph{category} +(@pxref{Categories}) of the item and other important information. You can +customize the prefix using the option @code{org-agenda-prefix-format}. +The prefix is followed by a cleaned-up version of the outline headline +associated with the item. + +@menu +* Categories:: Not all tasks are equal +* Time-of-day specifications:: How the agenda knows the time +* Sorting of agenda items:: The order of things +@end menu + +@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting +@subsection Categories + +@cindex category +The category is a broad label assigned to each agenda item. By default, +the category is simply derived from the file name, but you can also +specify it with a special line in the buffer, like this: + +@example +#+CATEGORY: Thesis +@end example + +If there are several such lines in a file, each specifies the category +for the text below it (but the first category also applies to any text +before the first CATEGORY line). The display in the agenda buffer looks +best if the category is not longer than 10 characters. + +@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting +@subsection Time-of-Day Specifications +@cindex time-of-day specification + +Org-mode checks each agenda item for a time-of-day specification. The +time can be part of the time stamp that triggered inclusion into the +agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time +ranges can be specified with two time stamps, like +@c +@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}. + +In the headline of the entry itself, a time(range) may also appear as +plain text (like @samp{12:45} or a @samp{8:30-1pm}. If the agenda +integrates the Emacs diary (@pxref{Weekly/Daily agenda}), time +specifications in diary entries are recognized as well. + +For agenda display, Org-mode extracts the time and displays it in a +standard 24 hour format as part of the prefix. The example times in +the previous paragraphs would end up in the agenda like this: + +@example + 8:30-13:00 Arthur Dent lies in front of the bulldozer + 12:45...... Ford Prefect arrives and takes Arthur to the pub + 19:00...... The Vogon reads his poem + 20:30-22:15 Marwin escorts the Hitchhikers to the bridge +@end example + +@cindex time grid +If the agenda is in single-day mode, or for the display of today, the +timed entries are embedded in a time grid, like + +@example + 8:00...... ------------------ + 8:30-13:00 Arthur Dent lies in front of the bulldozer + 10:00...... ------------------ + 12:00...... ------------------ + 12:45...... Ford Prefect arrives and takes Arthur to the pub + 14:00...... ------------------ + 16:00...... ------------------ + 18:00...... ------------------ + 19:00...... The Vogon reads his poem + 20:00...... ------------------ + 20:30-22:15 Marwin escorts the Hitchhikers to the bridge +@end example + +The time grid can be turned on and off with the variable +@code{org-agenda-use-time-grid}, and can be configured with +@code{org-agenda-time-grid}. + +@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting +@subsection Sorting of agenda items +@cindex sorting, of agenda items +@cindex priorities, of agenda items +Before being inserted into a view, the items are sorted. How this is +done depends on the type of view. +@itemize @bullet +@item +For the daily/weekly agenda, the items for each day are sorted. The +default order is to first collect all items containing an explicit +time-of-day specification. These entries will be shown at the beginning +of the list, as a @emph{schedule} for the day. After that, items remain +grouped in categories, in the sequence given by @code{org-agenda-files}. +Within each category, items are sorted by priority (@pxref{Priorities}), +which is composed of the base priority (2000 for priority @samp{A}, 1000 +for @samp{B}, and 0 for @samp{C}), plus additional increments for +overdue scheduled or deadline items. +@item +For the TODO list, items remain in the order of categories, but within +each category, sorting takes place according to priority +(@pxref{Priorities}). +@item +For tags matches, items are not sorted at all, but just appear in the +sequence in which they are found in the agenda files. +@end itemize + +Sorting can be customized using the variable +@code{org-agenda-sorting-strategy}. + + +@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda views +@section Commands in the agenda buffer +@cindex commands, in agenda buffer + +Entries in the agenda buffer are linked back to the org file or diary +file where they originate. You are not allowed to edit the agenda +buffer itself, but commands are provided to show and jump to the +original entry location, and to edit the org-files ``remotely'' from +the agenda buffer. In this way, all information is stored only once, +removing the risk that your agenda and note files may diverge. + +Some commands can be executed with mouse clicks on agenda lines. For +the other commands, the cursor needs to be in the desired line. + +@table @kbd +@tsubheading{Motion} +@cindex motion commands in agenda +@kindex n +@item n +Next line (same as @key{up}). +@kindex p +@item p +Previous line (same as @key{down}). +@tsubheading{View/GoTo org file} +@kindex mouse-3 +@kindex @key{SPC} +@item mouse-3 +@itemx @key{SPC} +Display the original location of the item in another window. +@c +@kindex L +@item L +Display original location and recenter that window. +@c +@kindex mouse-2 +@kindex mouse-1 +@kindex @key{TAB} +@item mouse-2 +@itemx mouse-1 +@itemx @key{TAB} +Go to the original location of the item in another window. Under Emacs +22, @kbd{mouse-1} will also works for this. +@c +@kindex @key{RET} +@itemx @key{RET} +Go to the original location of the item and delete other windows. +@c +@kindex f +@item f +Toggle Follow mode. In Follow mode, as you move the cursor through +the agenda buffer, the other window always shows the corresponding +location in the org file. The initial setting for this mode in new +agenda buffers can be set with the variable +@code{org-agenda-start-with-follow-mode}. +@c +@kindex b +@item b +Display the entire subtree of the current item in an indirect buffer. +With numerical prefix ARG, go up to this level and then take that tree. +If ARG is negative, go up that many levels. With @kbd{C-u} prefix, do +not remove the previously used indirect buffer. +@c +@kindex l +@item l +Toggle Logbook mode. In Logbook mode, entries that where marked DONE while +logging was on (variable @code{org-log-done}) are shown in the agenda, +as are entries that have been clocked on that day. + +@tsubheading{Change display} +@cindex display changing, in agenda +@kindex o +@item o +Delete other windows. +@c +@kindex d +@kindex w +@kindex m +@kindex y +@item d w m y +Switch to day/week/month/year view. When switching to day or week view, +this setting becomes the default for subseqent agenda commands. Since +month and year views are slow to create, the do not become the default. +@c +@kindex D +@item D +Toggle the inclusion of diary entries. See @ref{Weekly/Daily agenda}. +@c +@kindex g +@item g +Toggle the time grid on and off. See also the variables +@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}. +@c +@kindex r +@item r +Recreate the agenda buffer, for example to reflect the changes +after modification of the time stamps of items with S-@key{left} and +S-@key{right}. When the buffer is the global todo list, a prefix +argument is interpreted to create a selective list for a specific TODO +keyword. +@c +@kindex s +@item s +Save all Org-mode buffers in the current Emacs session. +@c +@kindex @key{right} +@item @key{right} +Display the following @code{org-agenda-ndays} days. For example, if +the display covers a week, switch to the following week. With prefix +arg, go forward that many times @code{org-agenda-ndays} days. +@c +@kindex @key{left} +@item @key{left} +Display the previous dates. +@c +@kindex . +@item . +Goto today. + +@tsubheading{Remote editing} +@cindex remote editing, from agenda + +@item 0-9 +Digit argument. +@c +@cindex undoing remote-editing events +@cindex remote editing, undo +@kindex C-_ +@item C-_ +Undo a change due to a remote editing command. The change is undone +both in the agenda buffer and in the remote buffer. +@c +@kindex t +@item t +Change the TODO state of the item, both in the agenda and in the +original org file. +@c +@kindex C-k +@item C-k +Delete the current agenda item along with the entire subtree belonging +to it in the original Org-mode file. If the text to be deleted remotely +is longer than one line, the kill needs to be confirmed by the user. See +variable @code{org-agenda-confirm-kill}. +@c +@kindex $ +@item $ +Archive the subtree corresponding to the current headline. +@c +@kindex T +@item T +Show all tags associated with the current item. Because of +inheritance, this may be more than the tags listed in the line itself. +@c +@kindex : +@item : +Set tags for the current headline. +@c +@kindex a +@item a +Toggle the ARCHIVE tag for the current headline. +@c +@kindex , +@item , +Set the priority for the current item. Org-mode prompts for the +priority character. If you reply with @key{SPC}, the priority cookie +is removed from the entry. +@c +@kindex P +@item P +Display weighted priority of current item. +@c +@kindex + +@kindex S-@key{up} +@item + +@itemx S-@key{up} +Increase the priority of the current item. The priority is changed in +the original buffer, but the agenda is not resorted. Use the @kbd{r} +key for this. +@c +@kindex - +@kindex S-@key{down} +@item - +@itemx S-@key{down} +Decrease the priority of the current item. +@c +@kindex C-c C-s +@item C-c C-s +Schedule this item +@c +@kindex C-c C-d +@item C-c C-d +Set a deadline for this item. +@c +@kindex S-@key{right} +@item S-@key{right} +Change the time stamp associated with the current line by one day into +the future. With prefix argument, change it by that many days. For +example, @kbd{3 6 5 S-@key{right}} will change it by a year. The +stamp is changed in the original org file, but the change is not +directly reflected in the agenda buffer. Use the +@kbd{r} key to update the buffer. +@c +@kindex S-@key{left} +@item S-@key{left} +Change the time stamp associated with the current line by one day +into the past. +@c +@kindex > +@item > +Change the time stamp associated with the current line to today. +The key @kbd{>} has been chosen, because it is the same as @kbd{S-.} +on my keyboard. +@c +@kindex I +@item I +Start the clock on the current item. If a clock is running already, it +is stopped first. +@c +@kindex O +@item O +Stop the previously started clock. +@c +@kindex X +@item X +Cancel the currently running clock. + +@tsubheading{Calendar commands} +@cindex calendar commands, from agenda +@kindex c +@item c +Open the Emacs calendar and move to the date at the agenda cursor. +@c +@item c +When in the calendar, compute and show the Org-mode agenda for the +date at the cursor. +@c +@cindex diary entries, creating from agenda +@kindex i +@item i +Insert a new entry into the diary. Prompts for the type of entry +(day, weekly, monthly, yearly, anniversary, cyclic) and creates a new +entry in the diary, just as @kbd{i d} etc. would do in the calendar. +The date is taken from the cursor position. +@c +@kindex M +@item M +Show the phases of the moon for the three months around current date. +@c +@kindex S +@item S +Show sunrise and sunset times. The geographical location must be set +with calendar variables, see documentation of the Emacs calendar. +@c +@kindex C +@item C +Convert the date at cursor into many other cultural and historic +calendars. +@c +@kindex H +@item H +Show holidays for three month around the cursor date. +@c +@c FIXME: This should be a different key. +@kindex C-c C-x C-c +@item C-c C-x C-c +Export a single iCalendar file containing entries from all agenda files. + +@tsubheading{Exporting to a file} +@kindex C-x C-w +@item C-x C-w +@cindex exporting agenda views +@cindex agenda views, exporting +Write the agenda view to a file. Depending on the extension of the +selected file name, the view will be exported as HTML (extension +@file{.html} or @file{.htm}), Postscript (extension @file{.ps}), or +plain text (any other extension). Use the variable +@code{org-agenda-exporter-settings} to set options for @file{ps-print} +and for @file{htmlize} to be used during export. + +@tsubheading{Quit and Exit} +@kindex q +@item q +Quit agenda, remove the agenda buffer. +@c +@kindex x +@cindex agenda files, removing buffers +@item x +Exit agenda, remove the agenda buffer and all buffers loaded by Emacs +for the compilation of the agenda. Buffers created by the user to +visit org files will not be removed. +@end table + + +@node Custom agenda views, , Agenda commands, Agenda views +@section Custom agenda views +@cindex custom agenda views +@cindex agenda views, custom + +Custom agenda commands serve two purposes: to store and quickly access +frequently used TODO and tags searches, and to create special composite +agenda buffers. Custom agenda commands will be accessible through the +dispatcher (@pxref{Agenda dispatcher}), just like the default commands. + +@menu +* Storing searches:: Type once, use often +* Block agenda:: All the stuff you need in a single buffer +* Setting Options:: Changing the rules +* Exporting Agenda Views:: Writing agendas to files. +* Extracting Agenda Information for other programs:: +@end menu + +@node Storing searches, Block agenda, Custom agenda views, Custom agenda views +@subsection Storing searches + +The first application of custom searches is the definition of keyboard +shortcuts for frequently used searches, either creating an agenda +buffer, or a sparse tree (the latter covering of course only the current +buffer). +@kindex C-c a C +Custom commands are configured in the variable +@code{org-agenda-custom-commands}. You can customize this variable, for +example by pressing @kbd{C-c a C}. You can also directly set it with +Emacs Lisp in @file{.emacs}. The following example contains all valid +search types: + +@lisp +@group +(setq org-agenda-custom-commands + '(("w" todo "WAITING") + ("W" todo-tree "WAITING") + ("u" tags "+BOSS-URGENT") + ("v" tags-todo "+BOSS-URGENT") + ("U" tags-tree "+BOSS-URGENT") + ("f" occur-tree "\\<FIXME\\>"))) +@end group +@end lisp + +@noindent +The initial single-character string in each entry defines the character +you have to press after the dispatcher command @kbd{C-c a} in order to +access the command. The second parameter is the search type, followed +by the string or regular expression to be used for the matching. The +example above will therefore define: + +@table @kbd +@item C-c a w +as a global search for TODO entries with @samp{WAITING} as the TODO +keyword +@item C-c a W +as the same search, but only in the current buffer and displaying the +results as a sparse tree +@item C-c a u +as a global tags search for headlines marked @samp{:BOSS:} but not +@samp{:URGENT:} +@item C-c a v +as the same search as @kbd{C-c a u}, but limiting the search to +headlines that are also TODO items +@item C-c a U +as the same search as @kbd{C-c a u}, but only in the current buffer and +displaying the result as a sparse tree +@item C-c a f +to create a sparse tree (again: current buffer only) with all entries +containing the word @samp{FIXME}. +@end table + +@node Block agenda, Setting Options, Storing searches, Custom agenda views +@subsection Block agenda +@cindex block agenda +@cindex agenda, with block views + +Another possibility is the construction of agenda views that comprise +the results of @emph{several} commands, each of which creates a block in +the agenda buffer. The available commands include @code{agenda} for the +daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo} +for the global todo list (as constructed with @kbd{C-c a t}), and the +matching commands discussed above: @code{todo}, @code{tags}, and +@code{tags-todo}. Here are two examples: + +@lisp +@group +(setq org-agenda-custom-commands + '(("h" "Agenda and Home-related tasks" + ((agenda) + (tags-todo "HOME") + (tags "GARDEN"))) + ("o" "Agenda and Office-related tasks" + ((agenda) + (tags-todo "WORK") + (tags "OFFICE"))))) +@end group +@end lisp + +@noindent +This will define @kbd{C-c a h} to create a multi-block view for stuff +you need to attend to at home. The resulting agenda buffer will contain +your agenda for the current week, all TODO items that carry the tag +@samp{HOME}, and also all lines tagged with @samp{GARDEN}. Finally the +command @kbd{C-c a o} provides a similar view for office tasks. + + +@node Setting Options, Exporting Agenda Views, Block agenda, Custom agenda views +@subsection Setting Options for custom commands +@cindex options, for custom agenda views + +Org-mode contains a number of variables regulating agenda construction +and display. The global variables define the behavior for all agenda +commands, including the custom commands. However, if you want to change +some settings just for a single custom view, you can do so. Setting +options requires inserting a list of variable names and values at the +right spot in @code{org-agenda-custom-commands}. For example: + +@lisp +@group +(setq org-agenda-custom-commands + '(("w" todo "WAITING" + ((org-agenda-sorting-strategy '(priority-down)) + (org-agenda-prefix-format " Mixed: "))) + ("U" tags-tree "+BOSS-URGENT" + ((org-show-following-heading nil) + (org-show-hierarchy-above nil))))) +@end group +@end lisp + +@noindent +Now the @kbd{C-c a w} command will sort the collected entries only by +priority, and the prefix format is modified to just say @samp{ Mixed:} +instead of giving the category of the entry. The sparse tags tree of +@kbd{C-c a U} will now turn out ultra-compact, because neither the +headline hierarchy above the match, nor the headline following the match +will be shown. + +For command sets creating a block agenda, +@code{org-agenda-custom-commands} has two separate spots for setting +options. You can add options that should be valid for just a single +command in the set, and options that should be valid for all commands in +the set. The former are just added to the command entry, the latter +must come after the list of command entries. Going back to the block +agenda example (@pxref{Block agenda}), let's change the sorting strategy +for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort +the results for GARDEN tags query in the opposite order, +@code{priority-up}. This would look like this: + +@lisp +@group +(setq org-agenda-custom-commands + '(("h" "Agenda and Home-related tasks" + ((agenda) + (tags-todo "HOME") + (tags "GARDEN" + ((org-agenda-sorting-strategy '(priority-up))))) + ((org-agenda-sorting-strategy '(priority-down)))) + ("o" "Agenda and Office-related tasks" + ((agenda) + (tags-todo "WORK") + (tags "OFFICE"))))) +@end group +@end lisp + +As you see, the values and parenthesis setting is a little complex. +When in doubt, use the customize interface to set this variable - it +fully supports its structure. Just one caveat: When setting options in +this interface, the @emph{values} are just lisp expressions. So if the +value is a string, you need to add the double quotes around the value +yourself. + + +@node Exporting Agenda Views, Extracting Agenda Information for other programs, Setting Options, Custom agenda views +@subsection Exporting Agenda Views +@cindex agenda views, exporting + +If you are away from your computer, it can be very useful to have a +printed version of some agenda views to carry around. Org-mode can +export custom agenda views as plain text, HTML@footnote{You need to +install Hrvoje Niksic' @file{htmlize.el}.} and postscript. If you want +to do this only occasionally, use the command + +@table @kbd +@kindex C-x C-w +@item C-x C-w +@cindex exporting agenda views +@cindex agenda views, exporting +Write the agenda view to a file. Depending on the extension of the +selected file name, the view will be exported as HTML (extension +@file{.html} or @file{.htm}), Postscript (extension @file{.ps}), or +plain text (any other extension). Use the variable +@code{org-agenda-exporter-settings} to set options for @file{ps-print} +and for @file{htmlize} to be used during export, for example +@lisp +(setq org-agenda-exporter-settings + '((ps-number-of-columns 2) + (ps-landscape-mode t) + (htmlize-output-type 'css))) +@end lisp +@end table + +If you need to export certain agenda views frequently, you can associate +any custom agenda command with a list of output file names +@footnote{If you want to store standard views like the weekly agenda +or the global TODO list as well, you need to define custom commands for +them in order to be able to specify filenames.}. Here is an example +that first does define custom commands for the agenda and the global +todo list, together with a number of files to which to export them. +Then we define two block agenda commands and specify filenames for them +as well. File names can be relative to the current working directory, +or absolute. + +@lisp +@group +(setq org-agenda-custom-commands + '(("X" agenda "" nil ("agenda.html" "agenda.ps")) + ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps")) + ("h" "Agenda and Home-related tasks" + ((agenda) + (tags-todo "HOME") + (tags "GARDEN")) + nil + ("~/views/home.html")) + ("o" "Agenda and Office-related tasks" + ((agenda) + (tags-todo "WORK") + (tags "OFFICE")) + nil + ("~/views/office.ps")))) +@end group +@end lisp + +The extension of the file name determines the type of export. If it is +@file{.html}, Org-mode will use the @file{htmlize.el} package to convert +the buffer to HTML and save it to this file name. If the extension is +@file{.ps}, @code{ps-print-buffer-with-faces} is used to produce +postscript output. Any other extension produces a plain ASCII file. + +The export files are @emph{not} created when you use one of those +commands interactively. Instead, there is a special command to produce +@emph{all} specified files in one step: + +@table @kbd +@kindex C-c a e +@item C-c a e +Export all agenda views that have export filenames associated with +them. +@end table + +You can use the options section of the custom agenda commands to also +set options for the export commands. For example: + +@lisp +(setq org-agenda-custom-commands + '(("X" agenda "" + ((ps-number-of-columns 2) + (ps-landscape-mode t) + (org-agenda-prefix-format " [ ] ") + (org-agenda-with-colors nil) + (org-agenda-remove-tags t)) + ("theagenda.ps")))) +@end lisp + +@noindent +This command sets two options for the postscript exporter, to make it +print in two columns in landscape format - the resulting page can be cut +in two and then used in a paper agenda. The remaining settings modify +the agenda prefix to omit category and scheduling information, and +instead include a checkbox to check off items. We also remove the tags +to make the lines compact, and we don't want to use colors for the +black-and-white printer. Settings specified in +@code{org-agenda-exporter-settings} will also apply, but the settings +in @code{org-agenda-custom-commands} take precedence. + +@noindent +From the command line you may also use +@example +emacs -f org-batch-store-agenda-views -kill +@end example +@noindent +or, if you need to modify some parameters +@example +emacs -eval '(org-batch-store-agenda-views \ + org-agenda-ndays 30 \ + org-agenda-include-diary nil \ + org-agenda-files (quote ("~/org/project.org")))' \ + -kill +@end example +@noindent +which will create the agenda views restricted to the file +@file{~/org/project.org}, without diary entries and with 30 days +extent. + +@node Extracting Agenda Information for other programs, , Exporting Agenda Views, Custom agenda views +@subsection Extracting Agenda Information for other programs +@cindex agenda, pipe +@cindex Scripts, for agenda processing + +Org-mode provides commands to access agenda information for the command +line in emacs batch mode. This extracted information can be sent +directly to a printer, or it can be read by a program that does further +processing of the data. The first of these commands is the function +@code{org-batch-agenda}, that produces an agenda view and sends it as +ASCII text to STDOUT. The command takes a single string as parameter. +If the string has length 1, it is used as a key to one of the commands +you have configured in @code{org-agenda-custom-commands}, basically any +key you can use after @kbd{C-c a}. For example, to directly print the +current TODO list, you could use + +@example +emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr +@end example + +If the parameter is a string with 2 or more characters, it is used as a +tags/todo match string. For example, to print your local shopping list +(all items with the tag @samp{shop}, but excluding the tag +@samp{NewYork}), you could use + +@example +emacs -batch -l ~/.emacs \ + -eval '(org-batch-agenda "+shop-NewYork")' | lpr +@end example + +@noindent +You may also modify parameters on the fly like this: + +@example +emacs -batch -l ~/.emacs \ + -eval '(org-batch-agenda "a" \ + org-agenda-ndays 30 \ + org-agenda-include-diary nil \ + org-agenda-files (quote ("~/org/project.org")))' \ + | lpr +@end example + +@noindent +which will produce a 30 day agenda, fully restricted to the Org file +@file{~/org/projects.org}, not even including the diary. + +If you want to process the agenda data in more sophisticated ways, you +can use the command @code{org-batch-agenda-csv} to get a comma-separated +list of values for each agenda item. Each line in the output will +contain a number of fields separated by commas. The fields in a line +are: + +@example +category @r{The category of the item} +head @r{The headline, without TODO kwd, TAGS and PRIORITY} +type @r{The type of the agenda entry, can be} + todo @r{selected in TODO match} + tagsmatch @r{selected in tags match} + diary @r{imported from diary} + deadline @r{a deadline} + scheduled @r{scheduled} + timestamp @r{appointment, selected by timestamp} + closed @r{entry was closed on date} + upcoming-deadline @r{warning about nearing deadline} + past-scheduled @r{forwarded scheduled item} + block @r{entry has date block including date} +todo @r{The todo keyword, if any} +tags @r{All tags including inherited ones, separated by colons} +date @r{The relevant date, like 2007-2-14} +time @r{The time, like 15:00-16:50} +extra @r{String with extra planning info} +priority-l @r{The priority letter if any was given} +priority-n @r{The computed numerical priority} +@end example + +@noindent +Time and date will only be given if a timestamp (or deadline/scheduled) +lead to the selection of the item. + +A CSV list like this is very easy to use in a post processing script. +For example, here is a Perl program that gets the TODO list from +Emacs/org-mode and prints all the items, preceded by a checkbox: + +@example +@group +#!/usr/bin/perl + +# define the Emacs command to run +$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; + +# run it and capture the output +$agenda = qx@{$cmd 2>/dev/null@}; + +# loop over all lines +foreach $line (split(/\n/,$agenda)) @{ + + # get the individual values + ($category,$head,$type,$todo,$tags,$date,$time,$extra, + $priority_l,$priority_n) = split(/,/,$line); + + # proccess and print + print "[ ] $head\n"; +@} +@end group +@end example + +@node Embedded LaTeX, Exporting, Agenda views, Top +@chapter Embedded LaTeX +@cindex @TeX{} interpretation +@cindex La@TeX{} interpretation + +Plain ASCII is normally sufficient for almost all note taking. One +exception, however, are scientific notes which need to be able to +contain mathematical symbols and the occasional formula. +La@TeX{}@footnote{La@TeX{} is a macro system based on Donald E. Knuth's +@TeX{} system. Many of the features described here as ``La@TeX{}'' are +really from @TeX{}, but for simplicity I am blurring this distinction.} +is widely used to typeset scientific documents. Org-mode supports +embedding La@TeX{} code into its files, because many academics are used +to read La@TeX{} source code, and because it can be readily processed +into images for HTML production. + +It is not necessary to mark La@TeX{} macros and code in any special way. +If you observe a few conventions, Org-mode knows how to find it and what +to do with it. + +@menu +* Math symbols:: TeX macros for symbols and Greek letters +* Subscripts and Superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Processing LaTeX fragments:: Previewing LaTeX processing +* CDLaTeX mode:: Speed up entering of formulas +@end menu + +@node Math symbols, Subscripts and Superscripts, Embedded LaTeX, Embedded LaTeX +@section Math symbols +@cindex math symbols +@cindex TeX macros + +You can use La@TeX{} macros to insert special symbols like @samp{\alpha} +to indicate the Greek letter, or @samp{\to} to indicate an arrow. +Completion for these macros is available, just type @samp{\} and maybe a +few letters, and press @kbd{M-@key{TAB}} to see possible completions. +Unlike La@TeX{} code, Org-mode allows these macros to be present +without surrounding math delimiters, for example: + +@example +Angles are written as Greek letters \alpha, \beta and \gamma. +@end example + +During HTML export (@pxref{HTML export}), these symbols are translated +into the proper syntax for HTML, for the above examples this is +@samp{α} and @samp{→}, respectively. + +@node Subscripts and Superscripts, LaTeX fragments, Math symbols, Embedded LaTeX +@section Subscripts and Superscripts +@cindex subscript +@cindex superscript + +Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super- +and subscripts. Again, these can be used without embedding them in +math-mode delimiters. To increase the readability of ASCII text, it is +not necessary (but OK) to surround multi-character sub- and superscripts +with curly braces. For example + +@example +The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of +the sun is R_@{sun@} = 6.96 x 10^8 m. +@end example + +To avoid interpretation as raised or lowered text, you can quote +@samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}. + +During HTML export (@pxref{HTML export}), subscript and superscripts +are surrounded with @code{<sub>} and @code{<sup>} tags, respectively. + +@node LaTeX fragments, Processing LaTeX fragments, Subscripts and Superscripts, Embedded LaTeX +@section LaTeX fragments +@cindex LaTeX fragments + +With symbols, sub- and superscripts, HTML is pretty much at its end when +it comes to representing mathematical formulas@footnote{Yes, there is +MathML, but that is not yet fully supported by many browsers, and there +is no decent converter for turning La@TeX{} or ASCII representations of +formulas into MathML. So for the time being, converting formulas into +images seems the way to go.}. More complex expressions need a dedicated +formula processor. To this end, Org-mode can contain arbitrary La@TeX{} +fragments. It provides commands to preview the typeset result of these +fragments, and upon export to HTML, all fragments will be converted to +images and inlined into the HTML document@footnote{The La@TeX{} export +will not use images for displaying La@TeX{} fragments but include these +fragments directly into the La@TeX{} code.}. For this to work you +need to be on a system with a working La@TeX{} installation. You also +need the @file{dvipng} program, available at +@url{http://sourceforge.net/projects/dvipng/}. The La@TeX{} header that +will be used when processing a fragment can be configured with the +variable @code{org-format-latex-header}. + +La@TeX{} fragments don't need any special marking at all. The following +snippets will be identified as La@TeX{} source code: +@itemize @bullet +@item +Environments of any kind. The only requirement is that the +@code{\begin} statement appears on a new line, preceded by only +whitespace. +@item +Text within the usual La@TeX{} math delimiters. To avoid conflicts with +currency specifications, single @samp{$} characters are only recognized +as math delimiters if the enclosed text contains at most two line breaks, +is directly attached to the @samp{$} characters with no whitespace in +between, and if the closing @samp{$} is followed by whitespace or +punctuation. For the other delimiters, there is no such restriction, so +when in doubt, use @samp{\(...\)} as inline math delimiters. +@end itemize + +@noindent For example: + +@example +\begin@{equation@} % arbitrary environments, +x=\sqrt@{b@} % even tables, figures +\end@{equation@} % etc + +If $a^2=b$ and \( b=2 \), then the solution must be +either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. +@end example + +@noindent +If you need any of the delimiter ASCII sequences for other purposes, you +can configure the option @code{org-format-latex-options} to deselect the +ones you do not wish to have interpreted by the La@TeX{} converter. + +@node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX +@section Processing LaTeX fragments +@cindex LaTeX fragments, preview + +La@TeX{} fragments can be processed to produce a preview images of the +typeset expressions: + +@table @kbd +@kindex C-c C-x C-l +@item C-c C-x C-l +Produce a preview image of the La@TeX{} fragment at point and overlay it +over the source code. If there is no fragment at point, process all +fragments in the current entry (between two headlines). When called +with a prefix argument, process the entire subtree. When called with +two prefix arguments, or when the cursor is before the first headline, +process the entire buffer. +@kindex C-c C-c +@item C-c C-c +Remove the overlay preview images. +@end table + +During HTML export (@pxref{HTML export}), all La@TeX{} fragments are +converted into images and inlined into the document if the following +setting is active: + +@lisp +(setq org-export-with-LaTeX-fragments t) +@end lisp + +@node CDLaTeX mode, , Processing LaTeX fragments, Embedded LaTeX +@section Using CDLaTeX to enter math +@cindex CDLaTeX + +CDLaTeX-mode is a minor mode that is normally used in combination with a +major La@TeX{} mode like AUCTeX in order to speed-up insertion of +environments and math templates. Inside Org-mode, you can make use of +some of the features of cdlatex-mode. You need to install +@file{cdlatex.el} and @file{texmathp.el} (the latter comes also with +AUCTeX) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. +Don't turn cdlatex-mode itself under Org-mode, but use the light +version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it +on for the current buffer with @code{M-x org-cdlatex-mode}, or for all +Org-mode files with + +@lisp +(add-hook 'org-mode-hook 'turn-on-org-cdlatex) +@end lisp + +When this mode is enabled, the following features are present (for more +details see the documentation of cdlatex-mode): +@itemize @bullet +@kindex C-c @{ +@item +Environment templates can be inserted with @kbd{C-c @{}. +@item +@kindex @key{TAB} +The @key{TAB} key will do template expansion if the cursor is inside a +La@TeX{} fragment@footnote{Org-mode has a method to test if the cursor is +inside such a fragment, see the documentation of the function +@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will +expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor +correctly inside the first brace. Another @key{TAB} will get you into +the second brace. Even outside fragments, @key{TAB} will expand +environment abbreviations at the beginning of a line. For example, if +you write @samp{equ} at the beginning of a line and press @key{TAB}, +this abbreviation will be expanded to an @code{equation} environment. +To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}. +@item +@kindex _ +@kindex ^ +Pressing @kbd{_} and @kbd{^} inside a La@TeX{} fragment will insert these +characters together with a pair of braces. If you use @key{TAB} to move +out of the braces, and if the braces surround only a single character or +macro, they are removed again (depending on the variable +@code{cdlatex-simplify-sub-super-scripts}). +@item +@kindex ` +Pressing the backquote @kbd{`} followed by a character inserts math +macros, also outside La@TeX{} fragments. If you wait more than 1.5 seconds +after the backquote, a help window will pop up. +@item +@kindex ' +Pressing the normal quote @kbd{'} followed by another character modifies +the symbol before point with an accent or a font. If you wait more than +1.5 seconds after the backquote, a help window will pop up. Character +modification will work only inside La@TeX{} fragments, outside the quote +is normal. +@end itemize + +@node Exporting, Publishing, Embedded LaTeX, Top +@chapter Exporting +@cindex exporting + +Org-mode documents can be exported into a variety of other formats. For +printing and sharing of notes, ASCII export produces a readable and +simple version of an Org-mode file. HTML export allows you to publish a +notes file on the web, while the XOXO format provides a solid base for +exchange with a broad range of other applications. La@TeX{} export lets +you use Org-mode and its structured editing functions to easily create +La@TeX{} files. To incorporate entries with associated times like +deadlines or appointments into a desktop calendar program like iCal, +Org-mode can also produce extracts in the iCalendar format. Currently +Org-mode only supports export, not import of these different formats. + +When exporting, Org-mode uses special conventions to enrich the output +produced. @xref{Text interpretation}, for more details. + +@table @kbd +@kindex C-c C-e +@item C-c C-e +Dispatcher for export and publishing commands. Displays a help-window +listing the additional key(s) needed to launch an export or publishing +command. +@end table + +@menu +* ASCII export:: Exporting to plain ASCII +* HTML export:: Exporting to HTML +* LaTeX export:: Exporting to LaTeX +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format +* Text interpretation:: How the exporter looks at the file +@end menu + +@node ASCII export, HTML export, Exporting, Exporting +@section ASCII export +@cindex ASCII export + +ASCII export produces a simple and very readable version of an Org-mode +file. + +@cindex region, active +@cindex active region +@cindex transient-mark-mode +@table @kbd +@kindex C-c C-e a +@item C-c C-e a +Export as ASCII file. For an org file @file{myfile.org}, the ASCII file +will be @file{myfile.txt}. The file will be overwritten without +warning. If there is an active region, only the region will be +exported. If the selected region is a single tree, the tree head will +become the document title. If the tree head entry has or inherits an +EXPORT_FILE_NAME property, that name will be used for the export. +@kindex C-c C-e v a +@item C-c C-e v a +Export only the visible part of the document. +@end table + +@cindex headline levels, for exporting +In the exported version, the first 3 outline levels will become +headlines, defining a general document structure. Additional levels +will be exported as itemized lists. If you want that transition to occur +at a different level, specify it with a prefix argument. For example, + +@example +@kbd{C-1 C-c C-e a} +@end example + +@noindent +creates only top level headlines and does the rest as items. When +headlines are converted to items, the indentation of the text following +the headline is changed to fit nicely under the item. This is done with +the assumption that the first bodyline indicates the base indentation of +the body text. Any indentation larger than this is adjusted to preserve +the layout relative to the first line. Should there be lines with less +indentation than the first, these are left alone. + +@node HTML export, LaTeX export, ASCII export, Exporting +@section HTML export +@cindex HTML export + +Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive +HTML formatting, in ways similar to John Grubers @emph{markdown} +language, but with additional support for tables. + +@menu +* HTML Export commands:: How to invoke LaTeX export +* Quoting HTML tags:: Using direct HTML in Org-mode +* Links:: Transformation of links for HTML +* Images:: How to include images +* CSS support:: Changing the appearence of the output +@end menu + +@node HTML Export commands, Quoting HTML tags, HTML export, HTML export +@subsection HTML export commands + +@cindex region, active +@cindex active region +@cindex transient-mark-mode +@table @kbd +@kindex C-c C-e h +@item C-c C-e h +Export as HTML file @file{myfile.html}. For an org file +@file{myfile.org}, the ASCII file will be @file{myfile.html}. The file +will be overwritten without warning. If there is an active region, only +the region will be exported. If the selected region is a single tree, +the tree head will become the document title. If the tree head entry +has or inherits an EXPORT_FILE_NAME property, that name will be used for +the export. +@kindex C-c C-e b +@item C-c C-e b +Export as HTML file and immediately open it with a browser. +@kindex C-c C-e H +@item C-c C-e H +Export to a temporary buffer, do not create a file. +@kindex C-c C-e R +@item C-c C-e H +Export the active region to a temporary buffer. With prefix arg, do not +produce file header and foot, but just the plain HTML section for the +region. This is good for cut-and-paste operations. +@kindex C-c C-e v h +@kindex C-c C-e v b +@kindex C-c C-e v H +@kindex C-c C-e v R +@item C-c C-e v h +@item C-c C-e v b +@item C-c C-e v H +@item C-c C-e v R +Export only the visible part of the document. +@item M-x org-export-region-as-html +Convert the region to HTML under the assumption that it was org-mode +syntax before. This is a global command that can be invoked in any +buffer. +@item M-x org-replace-region-by-HTML +Replace the active region (assumed to be in Org-mode syntax) by HTML +code. +@end table + +@cindex headline levels, for exporting +In the exported version, the first 3 outline levels will become +headlines, defining a general document structure. Additional levels +will be exported as itemized lists. If you want that transition to occur +at a different level, specify it with a prefix argument. For example, + +@example +@kbd{C-2 C-c C-e b} +@end example + +@noindent +creates two levels of headings and does the rest as items. + +@node Quoting HTML tags, Links, HTML Export commands, HTML export +@subsection Quoting HTML tags + +Plain @samp{<} and @samp{>} are always transformed to @samp{<} and +@samp{>} in HTML export. If you want to include simple HTML tags +which should be interpreted as such, mark them with @samp{@@} as in +@samp{@@<b>bold text@@</b>}. Note that this really works only for +simple tags. For more extensive HTML that should be copied verbatim to +the exported file use either + +@example +#+HTML: Literal HTML code for export +@end example + +@noindent or + +@example +#+BEGIN_HTML +All lines between these markers are exported literally +#+END_HTML +@end example + + +@node Links, Images, Quoting HTML tags, HTML export +@subsection Links + +@cindex links, in HTML export +@cindex internal links, in HTML export +@cindex external links, in HTML export +Internal links (@pxref{Internal links}) will continue to work in HTML +files only if they match a dedicated @samp{<<target>>}. Automatic links +created by radio targets (@pxref{Radio targets}) will also work in the +HTML file. Links to external files will still work if the HTML file is +in the same directory as the Org-mode file. Links to other @file{.org} +files will be translated into HTML links under the assumption that an +HTML version also exists of the linked file. For information related to +linking files while publishing them to a publishing directory see +@ref{Publishing links}. + +@node Images, CSS support, Links, HTML export +@subsection Images + +@cindex images, inline in HTML +@cindex inlining images in HTML +HTML export can inline images given as links in the Org-mode file, and +it can make an image the clickable part of a link. By +default@footnote{but see the variable +@code{org-export-html-inline-images}}, images are inlined if a link does +not have a description. So @samp{[[file:myimg.jpg]]} will be inlined, +while @samp{[[file:myimg.jpg][the image]]} will just produce a link +@samp{the image} that points to the image. If the description part +itself is a @code{file:} link or a @code{http:} URL pointing to an +image, this image will be inlined and activated so that clicking on the +image will activate the link. For example, to include a thumbnail that +will link to a high resolution version of the image, you could use: + +@example +[[file:highres.jpg][file:thumb.jpg]] +@end example + +@noindent +and you could use @code{http} addresses just as well. + +@node CSS support, , Images, HTML export +@subsection CSS support + +You can also give style information for the exported file. The HTML +exporter assigns the following CSS classes to appropriate parts of the +document - your style specifications may change these: +@example +.todo @r{TODO keywords} +.done @r{the DONE keyword} +.timestamp @r{time stamp} +.timestamp-kwd @r{keyword associated with a time stamp, like SCHEDULED} +.tag @r{tag in a headline} +.target @r{target for links} +@end example + +The default style specification can be configured through the option +@code{org-export-html-style}. If you want to use a file-local style, +you may use file variables, best wrapped into a COMMENT section at the +end of the outline tree. For example@footnote{Under Emacs 21, the +continuation lines for a variable value should have no @samp{#} at the +start of the line.}: + +@example +* COMMENT html style specifications + +# Local Variables: +# org-export-html-style: " <style type=\"text/css\"> +# p @{font-weight: normal; color: gray; @} +# h1 @{color: black; @} +# </style>" +# End: +@end example + +Remember to execute @kbd{M-x normal-mode} after changing this to make +the new style visible to Emacs. This command restarts org-mode for the +current buffer and forces Emacs to re-evaluate the local variables +section in the buffer. + +@c FIXME: More about header and footer styles +@c FIXME: Talk about links and targets. + +@node LaTeX export, XOXO export, HTML export, Exporting +@section LaTeX export +@cindex LaTeX export + +Org-mode contains a La@TeX{} exporter written by Bastien Guerry. + +@menu +* LaTeX export commands:: How to invoke LaTeX export +* Quoting LaTeX code:: Incorporating literal LaTeX code +@end menu + +@node LaTeX export commands, Quoting LaTeX code, LaTeX export, LaTeX export +@subsection LaTeX export commands + +@table @kbd +@kindex C-c C-e l +@item C-c C-e l +Export as La@TeX{} file @file{myfile.tex}. +@kindex C-c C-e L +@item C-c C-e L +Export to a temporary buffer, do not create a file. +@kindex C-c C-e v l +@kindex C-c C-e v L +@item C-c C-e v l +@item C-c C-e v L +Export only the visible part of the document. +@item M-x org-export-region-as-latex +Convert the region to La@TeX{} under the assumption that it was org-mode +syntax before. This is a global command that can be invoked in any +buffer. +@item M-x org-replace-region-by-latex +Replace the active region (assumed to be in Org-mode syntax) by La@TeX{} +code. +@end table + +@cindex headline levels, for exporting +In the exported version, the first 3 outline levels will become +headlines, defining a general document structure. Additional levels +will be exported as description lists. The exporter can ignore them or +convert them to a custom string depending on +@code{org-latex-low-levels}. + +If you want that transition to occur at a different level, specify it +with a prefix argument. For example, + +@example +@kbd{C-2 C-c C-e l} +@end example + +@noindent +creates two levels of headings and does the rest as items. + +@node Quoting LaTeX code, , LaTeX export commands, LaTeX export +@subsection Quoting LaTeX code + +Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly +inserted into the La@TeX{} file. Forthermore, you can add special code +that should only be present in La@TeX{} export with the following +constructs: + +@example +#+LaTeX: Literal LaTeX code for export +@end example + +@noindent or + +@example +#+BEGIN_LaTeX +All lines between these markers are exported literally +#+END_LaTeX +@end example +@node XOXO export, iCalendar export, LaTeX export, Exporting +@section XOXO export +@cindex XOXO export + +Org-mode contains an exporter that produces XOXO-style output. +Currently, this exporter only handles the general outline structure and +does not interpret any additional Org-mode features. + +@table @kbd +@kindex C-c C-e x +@item C-c C-e x +Export as XOXO file @file{myfile.html}. +@kindex C-c C-e v +@item C-c C-e v x +Export only the visible part of the document. +@end table + +@node iCalendar export, Text interpretation, XOXO export, Exporting +@section iCalendar export +@cindex iCalendar export + +Some people like to use Org-mode for keeping track of projects, but +still prefer a standard calendar application for anniversaries and +appointments. In this case it can be useful to have deadlines and +other time-stamped items in Org-mode files show up in the calendar +application. Org-mode can export calendar information in the standard +iCalendar format. If you also want to have TODO entries included in the +export, configure the variable @code{org-icalendar-include-todo}. + +@table @kbd +@kindex C-c C-e i +@item C-c C-e i +Create iCalendar entries for the current file and store them in the same +directory, using a file extension @file{.ics}. +@kindex C-c C-e I +@item C-c C-e I +Like @kbd{C-c C-e i}, but do this for all files in +@code{org-agenda-files}. For each of these files, a separate iCalendar +file will be written. +@kindex C-c C-e c +@item C-c C-e c +Create a single large iCalendar file from all files in +@code{org-agenda-files} and write it to the file given by +@code{org-combined-agenda-icalendar-file}. +@end table + +How this calendar is best read and updated, depends on the application +you are using. The FAQ covers this issue. + + +@node Text interpretation, , iCalendar export, Exporting +@section Text interpretation by the exporter + +The exporter backends interpret additional structure in the Org-mode file +in order to produce better output. + +@menu +* Comment lines:: Some lines will not be exported +* Initial text:: Text before the first headline +* Footnotes:: Numbers like [1] +* Enhancing text:: Subscripts, symbols and more +* Export options:: How to influence the export settings +@end menu + +@node Comment lines, Initial text, Text interpretation, Text interpretation +@subsection Comment lines +@cindex comment lines +@cindex exporting, not + +Lines starting with @samp{#} in column zero are treated as comments +and will never be exported. Also entire subtrees starting with the +word @samp{COMMENT} will never be exported. + +@table @kbd +@kindex C-c ; +@item C-c ; +Toggle the COMMENT keyword at the beginning of an entry. +@end table + +@node Initial text, Footnotes, Comment lines, Text interpretation +@subsection Text before the first headline + +Org-mode normally ignores any text before the first headline when +exporting, leaving this region for internal links to speed up navigation +etc. However, in publishing-oriented files, you might want to have some +text before the first headline, like a small introduction, special HTML +code with a navigation bar, etc. You can ask to have this part of the +file exported as well by setting the variable +@code{org-export-skip-text-before-1st-heading} to @code{nil}. On a +per-file basis, you can get the same effect with + +@example +#+OPTIONS: skip:nil +@end example + +The text before the first headline will be fully processed +(@pxref{Enhancing text}), and the first non-comment line becomes the +title of the exported document. If you need to include literal HTML, +use the special constructs described in @ref{Quoting HTML tags}. The +table of contents is normally inserted directly before the first +headline of the file. If you would like to get it to a different +location, insert the string @code{[TABLE-OF-CONTENTS]} on a line by +itself at the desired location. + +Finally, if you want to use the space before the first headline for +internal purposes, but @emph{still} want to place something before the +first headline when exporting the file, you can use the @code{#+TEXT} +construct: + +@example +#+OPTIONS: skip:t +#+TEXT: This text will go before the *first* headline. +#+TEXT: We place the table of contents here: +#+TEXT: [TABLE-OF-CONTENTS] +#+TEXT: This goes between the table of contents and the first headline +@end example + +@node Footnotes, Enhancing text, Initial text, Text interpretation +@subsection Footnotes +@cindex footnotes +@cindex @file{footnote.el} + +Numbers in square brackets are treated as footnotes, so that you can use +the Emacs package @file{footnote.el} to create footnotes. For example: + +@example +The org-mode homepage[1] clearly needs help from +a good web designer. + +[1] The link is: http://www.astro.uva.nl/~dominik/Tools/org +@end example + +@noindent +@kindex C-c ! +Note that the @file{footnote} package uses @kbd{C-c !} to invoke its +commands. This binding conflicts with the org-mode command for +inserting inactive time stamps. You could use the variable +@code{footnote-prefix} to switch footnotes commands to another key. Or, +if you are too used to this binding, you could use +@code{org-replace-disputed-keys} and @code{org-disputed-keys} to change +the settings in Org-mode. + +@node Enhancing text, Export options, Footnotes, Text interpretation +@subsection Enhancing text for export +@cindex enhancing text +@cindex richer text + +Some of the export backends of Org-mode allow for sophisticated text +formatting, this is true in particular for the HTML and La@TeX{} +backends. Org-mode has a number of typing conventions that allow to +produce a richly formatted output. + +@itemize @bullet + +@cindex hand-formatted lists +@cindex lists, hand-formatted +@item +Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.} +or @samp{2)} as enumerator will be recognized and transformed if the +backend supports lists. See @xref{Plain lists}. + +@cindex underlined text +@cindex bold text +@cindex italic text +@item +You can make words @b{*bold*}, @i{/italic/}, _underlined_, +@code{=code=}, and even @samp{+strikethrough+}@footnote{but remember +that strikethrough is typographically evil and should @i{never} be +used.}. + +@cindex horizontal rules, in exported files +@item +A line consisting of only dashes, and at least 5 of them, will be +exported as a horizontal line (@samp{<hr/>} in HTML). + +@cindex LaTeX fragments, export +@cindex TeX macros, export +@item +Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML +entities or images (@pxref{Embedded LaTeX}). + +@cindex tables, export +@item +Tables are transformed into native tables under the exporter, if the +export backend supports this. Data fields before the first horizontal +separator line will be formatted as table header fields. + +@cindex fixed width +@item +If a headline starts with the word @samp{QUOTE}, the text below the +headline will be typeset as fixed-width, to allow quoting of computer +codes etc. Lines starting with @samp{:} are also typeset in fixed-width +font. +@table @kbd +@kindex C-c : +@item C-c : +Toggle fixed-width for entry (QUOTE) or region, see below. +@end table + +@cindex linebreak, forced +@item +A double backslash @emph{at the end of a line} enforces a line break at +this position. +@end itemize + +If these conversions conflict with your habits of typing ASCII text, +they can all be turned off with corresponding variables. See the +customization group @code{org-export-general}, and the following section +which explains how to set export options with special lines in a +buffer. + + +@node Export options, , Enhancing text, Text interpretation +@subsection Export options +@cindex options, for export + +@cindex completion, of option keywords +The exporter recognizes special lines in the buffer which provide +additional information. These lines may be put anywhere in the file. +The whole set of lines can be inserted into the buffer with @kbd{C-c +C-e t}. For individual lines, a good way to make sure the keyword is +correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion +(@pxref{Completion}). + +@table @kbd +@kindex C-c C-e t +@item C-c C-e t +Insert template with export options, see example below. +@end table + +@example +#+TITLE: the title to be shown (default is the buffer name) +#+AUTHOR: the author (default taken from @code{user-full-name}) +#+EMAIL: his/her email address (default from @code{user-mail-address}) +#+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language}) +#+TEXT: Some descriptive text to be inserted at the beginning. +#+TEXT: Several lines may be given. +#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... +@end example + +@noindent +The OPTIONS line is a compact form to specify export settings. Here +you can: +@cindex headline levels +@cindex section-numbers +@cindex table of contents +@cindex linebreak preservation +@cindex quoted HTML tags +@cindex fixed-width sections +@cindex tables +@cindex @TeX{}-like syntax for sub- and superscripts +@cindex footnotes +@cindex emphasized text +@cindex @TeX{} macros +@cindex La@TeX{} fragments +@cindex author info, in export +@cindex time info, in export +@example +H: @r{set the number of headline levels for export} +num: @r{turn on/off section-numbers} +toc: @r{turn on/off table of contents, or set level limit (integer)} +\n: @r{turn on/off linebreak-preservation} +@@: @r{turn on/off quoted HTML tags} +:: @r{turn on/off fixed-width sections} +|: @r{turn on/off tables} +^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If} + @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but} + @r{the simple @code{a_b} will be left as it is.} +f: @r{turn on/off foototes like this[1].} +*: @r{turn on/off emphasized text (bold, italic, underlined)} +TeX: @r{turn on/off simple @TeX{} macros in plain text} +LaTeX: @r{turn on/off La@TeX{} fragments} +skip: @r{turn on/off skipping the text before the first heading} +author: @r{turn on/off inclusion of author name/email into exported file} +timestamp: @r{turn on/off inclusion creation time into exported file} +@end example + +These options take effect in both the HTML and La@TeX{} export, except +for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and +@code{nil} for the La@TeX{} export. + +@node Publishing, Miscellaneous, Exporting, Top +@chapter Publishing +@cindex publishing + +Org-mode includes@footnote{@file{org-publish.el} is not distributed with +Emacs 21, if you are still using Emacs 21, you need you need to download +this file separately.} a publishing management system that allows you to +configure automatic HTML conversion of @emph{projects} composed of +interlinked org files. This system is called @emph{org-publish}. You can +also configure org-publish to automatically upload your exported HTML +pages and related attachments, such as images and source code files, to +a web server. Org-publish turns org-mode into a web-site authoring tool. + +You can also use Org-publish to convert files into La@TeX{}, or even +combine HTML and La@TeX{} conversion so that files are available in both +formats on the server@footnote{Since La@TeX{} files on a server are not +that helpful, you surely want to perform further conversion on them -- +e.g. convert them to @code{PDF} format.}. + +Org-publish has been contributed to Org-mode by David O'Toole. + +@menu +* Configuration:: Defining projects +* Sample configuration:: Example projects +* Triggering publication:: Publication commands +@end menu + +@node Configuration, Sample configuration, Publishing, Publishing +@section Configuration + +Publishing needs significant configuration to specify files, destination +and many other properties of a project. + +@menu +* Project alist:: The central configuration variable +* Sources and destinations:: From here to there +* Selecting files:: What files are part of the project? +* Publishing action:: Setting the function doing the publishing +* Publishing options:: Tweaking HTML export +* Publishing links:: Which links keep working after publishing? +* Project page index:: Publishing a list of project files +@end menu + +@node Project alist, Sources and destinations, Configuration, Configuration +@subsection The variable @code{org-publish-project-alist} +@cindex org-publish-project-alist +@cindex projects, for publishing + +Org-publish is configured almost entirely through setting the value of +one variable, called @code{org-publish-project-alist}. +Each element of the list configures one project, and may be in one of +the two following forms: + +@lisp +("project-name" :property value :property value ...) + +@r{or} + +("project-name" :components ("project-name" "project-name" ...)) + +@end lisp + +In both cases, projects are configured by specifying property values. +A project defines the set of files that will be published, as well as +the publishing configuration to use when publishing those files. When +a project takes the second form listed above, the individual members +of the ``components'' property are taken to be components of the +project, which group together files requiring different publishing +options. When you publish such a ``meta-project'' all the components +will also publish. + +@node Sources and destinations, Selecting files, Project alist, Configuration +@subsection Sources and destinations for files +@cindex directories, for publishing + +Most properties are optional, but some should always be set. In +particular, org-publish needs to know where to look for source files, +and where to put published files. + +@multitable @columnfractions 0.3 0.7 +@item @code{:base-directory} +@tab Directory containing publishing source files +@item @code{:publishing-directory} +@tab Directory (possibly remote) where output files will be published. +@item @code{:preparation-function} +@tab Function called before starting publishing process, for example to +run @code{make} for updating files to be published. +@end multitable +@noindent + +@node Selecting files, Publishing action, Sources and destinations, Configuration +@subsection Selecting files +@cindex files, selecting for publishing + +By default, all files with extension @file{.org} in the base directory +are considered part of the project. This can be modified by setting the +properties +@multitable @columnfractions 0.25 0.75 +@item @code{:base-extension} +@tab Extension (without the dot!) of source files. This actually is a +regular expression. + +@item @code{:exclude} +@tab Regular expression to match file names that should not be +published, even though they have been selected on the basis of their +extension. + +@item @code{:include} +@tab List of files to be included regardless of @code{:base-extension} +and @code{:exclude}. +@end multitable + +@node Publishing action, Publishing options, Selecting files, Configuration +@subsection Publishing Action +@cindex action, for publishing + +Publishing means that a file is copied to the destination directory and +possibly transformed in the process. The default transformation is to +export Org-mode files as HTML files, and this is done by the function +@code{org-publish-org-to-html} which calls the HTML exporter +(@pxref{HTML export}). But you also can publish your files in La@TeX{} by +using the function @code{org-publish-org-to-latex} instead. Other files +like images only need to be copied to the publishing destination. For +non-Org-mode files, you need to specify the publishing function. + + +@multitable @columnfractions 0.3 0.7 +@item @code{:publishing-function} +@tab Function executing the publication of a file. This may also be a +list of functions, which will all be called in turn. +@end multitable + +The function must accept two arguments: a property list containing at +least a @code{:publishing-directory} property, and the name of the file +to be published. It should take the specified file, make the necessary +transformation (if any) and place the result into the destination folder. +You can write your own publishing function, but @code{org-publish} +provides one for attachments (files that only need to be copied): +@code{org-publish-attachment}. + +@node Publishing options, Publishing links, Publishing action, Configuration +@subsection Options for the HTML/LaTeX exporters +@cindex options, for publishing + +The property list can be used to set many export options for the HTML +and La@TeX{} exporters. In most cases, these properties correspond to user +variables in Org-mode. The table below lists these properties along +with the variable they belong to. See the documentation string for the +respective variable for details. + +@multitable @columnfractions 0.3 0.7 +@item @code{:language} @tab @code{org-export-default-language} +@item @code{:headline-levels} @tab @code{org-export-headline-levels} +@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} +@item @code{:table-of-contents} @tab @code{org-export-with-toc} +@item @code{:archived-trees} @tab @code{org-export-with-archived-trees} +@item @code{:emphasize} @tab @code{org-export-with-emphasize} +@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} +@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} +@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} +@item @code{:fixed-width} @tab @code{org-export-with-fixed-width} +@item @code{:timestamps} .@tab @code{org-export-with-timestamps} +@item @code{:tags} .@tab @code{org-export-with-tags} +@item @code{:tables} @tab @code{org-export-with-tables} +@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line} +@item @code{:style} @tab @code{org-export-html-style} +@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html} +@item @code{:inline-images} @tab @code{org-export-html-inline-images} +@item @code{:expand-quoted-html} @tab @code{org-export-html-expand} +@item @code{:timestamp} @tab @code{org-export-html-with-timestamp} +@item @code{:publishing-directory} @tab @code{org-export-publishing-directory} +@item @code{:preamble} @tab @code{org-export-html-preamble} +@item @code{:postamble} @tab @code{org-export-html-postamble} +@item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble} +@item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble} +@item @code{:author} @tab @code{user-full-name} +@item @code{:email} @tab @code{user-mail-address} +@end multitable + +Most of the @code{org-export-with-*} variables have the same effect in +both HTML and La@TeX{} exporters, except for @code{:TeX-macros} and +@code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the +La@TeX{} export. + +When a property is given a value in org-publish-project-alist, its +setting overrides the value of the corresponding user variable (if any) +during publishing. Options set within a file (@pxref{Export +options}), however, override everything. + +@node Publishing links, Project page index, Publishing options, Configuration +@subsection Links between published files +@cindex links, publishing + +To create a link from one Org-mode file to another, you would use +something like @samp{[[file:foo.org][The foo]]} or simply +@samp{file:foo.org.} (@pxref{Hyperlinks}). Upon publishing this link +becomes a link to @file{foo.html}. In this way, you can interlink the +pages of your "org web" project and the links will work as expected when +you publish them to HTML. + +You may also link to related files, such as images. Provided you are +careful with relative pathnames, and provided you have also configured +org-publish to upload the related files, these links will work +too. @ref{Complex example} for an example of this usage. + +Sometime an Org-mode file to be published may contain links that are +only valid in your production environment, but not in the publishing +location. In this case, use the property + +@multitable @columnfractions 0.4 0.6 +@item @code{:link-validation-function} +@tab Function to validate links +@end multitable + +@noindent +to define a function for checking link validity. This function must +accept two arguments, the file name and a directory relative to which +the file name is interpreted in the production environment. If this +function returns @code{nil}, then the HTML generator will only insert a +description into the HTML file, but no link. One option for this +function is @code{org-publish-validate-link} which checks if the given +file is part of any project in @code{org-publish-project-alist}. + +@node Project page index, , Publishing links, Configuration +@subsection Project page index +@cindex index, of published pages + +The following properties may be used to control publishing of an +index of files or summary page for a given project. + +@multitable @columnfractions 0.25 0.75 +@item @code{:auto-index} +@tab When non-nil, publish an index during org-publish-current-project or +org-publish-all. + +@item @code{:index-filename} +@tab Filename for output of index. Defaults to @file{index.org} (which +becomes @file{index.html}). + +@item @code{:index-title} +@tab Title of index page. Defaults to name of file. + +@item @code{:index-function} +@tab Plugin function to use for generation of index. +Defaults to @code{org-publish-org-index}, which generates a plain list +of links to all files in the project. +@end multitable + +@node Sample configuration, Triggering publication, Configuration, Publishing +@section Sample configuration + +Below we provide two example configurations. The first one is a simple +project publishing only a set of Org-mode files. The second example is +more complex, with a multi-component project. + +@menu +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example +@end menu + +@node Simple example, Complex example, Sample configuration, Sample configuration +@subsection Example: simple publishing configuration + +This example publishes a set of Org-mode files to the @file{public_html} +directory on the local machine. + +@lisp +(setq org-publish-project-alist + '(("org" + :base-directory "~/org/" + :publishing-directory "~/public_html" + :section-numbers nil + :table-of-contents nil + :style "<link rel=stylesheet + href=\"../other/mystyle.css\" + type=\"text/css\">"))) +@end lisp + +@node Complex example, , Simple example, Sample configuration +@subsection Example: complex publishing configuration + +This more complicated example publishes an entire website, including +org files converted to HTML, image files, emacs lisp source code, and +stylesheets. The publishing-directory is remote and private files are +excluded. + +To ensure that links are preserved, care should be taken to replicate +your directory structure on the web server, and to use relative file +paths. For example, if your org files are kept in @file{~/org} and your +publishable images in @file{~/images}, you'd link to an image with +@c +@example +file:../images/myimage.png +@end example +@c +On the web server, the relative path to the image should be the +same. You can accomplish this by setting up an "images" folder in the +right place on the webserver, and publishing images to it. + +@lisp +(setq org-publish-project-alist + '(("orgfiles" + :base-directory "~/org/" + :base-extension "org" + :publishing-directory "/ssh:user@@host:~/html/notebook/" + :publishing-function org-publish-org-to-html + :exclude "PrivatePage.org" ;; regexp + :headline-levels 3 + :section-numbers nil + :table-of-contents nil + :style "<link rel=stylesheet + href=\"../other/mystyle.css\" type=\"text/css\">" + :auto-preamble t + :auto-postamble nil) + + ("images" + :base-directory "~/images/" + :base-extension "jpg\\|gif\\|png" + :publishing-directory "/ssh:user@@host:~/html/images/" + :publishing-function org-publish-attachment) + + ("other" + :base-directory "~/other/" + :base-extension "css\\|el" + :publishing-directory "/ssh:user@@host:~/html/other/" + :publishing-function org-publish-attachment) + ("website" :components ("orgfiles" "images" "other")))) +@end lisp + +@node Triggering publication, , Sample configuration, Publishing +@section Triggering publication + +Once org-publish is properly configured, you can publish with the +following functions: + +@table @kbd +@item C-c C-e C +Prompt for a specific project and publish all files that belong to it. +@item C-c C-e P +Publish the project containing the current file. +@item C-c C-e F +Publish only the current file. +@item C-c C-e A +Publish all projects. +@end table + +Org uses timestamps to track when a file has changed. The above +functions normally only publish changed files. You can override this and +force publishing of all files by giving a prefix argument. + +@node Miscellaneous, Extensions and Hacking, Publishing, Top +@chapter Miscellaneous + +@menu +* Completion:: M-TAB knows what you need +* Customization:: Adapting Org-mode to your taste +* In-buffer settings:: Overview of the #+KEYWORDS +* The very busy C-c C-c key:: When in doubt, press C-c C-c +* Clean view:: Getting rid of leading stars in the outline +* TTY keys:: Using Org-mode on a tty +* Interaction:: Other Emacs packages +* Bugs:: Things which do not work perfectly +@end menu + +@node Completion, Customization, Miscellaneous, Miscellaneous +@section Completion +@cindex completion, of @TeX{} symbols +@cindex completion, of TODO keywords +@cindex completion, of dictionary words +@cindex completion, of option keywords +@cindex completion, of tags +@cindex completion, of property keys +@cindex completion, of link abbreviations +@cindex @TeX{} symbol completion +@cindex TODO keywords completion +@cindex dictionary word completion +@cindex option keyword completion +@cindex tag completion +@cindex link abbreviations, completion of + +Org-mode supports in-buffer completion. This type of completion does +not make use of the minibuffer. You simply type a few letters into +the buffer and use the key to complete text right there. + +@table @kbd +@kindex M-@key{TAB} +@item M-@key{TAB} +Complete word at point +@itemize @bullet +@item +At the beginning of a headline, complete TODO keywords. +@item +After @samp{\}, complete @TeX{} symbols supported by the exporter. +@item +After @samp{*}, complete headlines in the current buffer so that they +can be used in search links like @samp{[[*find this headline]]}. +@item +After @samp{:} in a headline, complete tags. The list of tags is taken +from the variable @code{org-tag-alist} (possibly set through the +@samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created +dynamically from all tags used in the current buffer. +@item +After @samp{:} and not in a headline, complete property keys. The list +of keys is constructed dynamically from all keys used in the current +buffer. +@item +After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}). +@item +After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or +@samp{OPTIONS} which set file-specific options for Org-mode. When the +option keyword is already complete, pressing @kbd{M-@key{TAB}} again +will insert example settings for this keyword. +@item +In the line after @samp{#+STARTUP: }, complete startup keywords, +i.e. valid keys for this line. +@item +Elsewhere, complete dictionary words using ispell. +@end itemize +@end table + +@node Customization, In-buffer settings, Completion, Miscellaneous +@section Customization +@cindex customization +@cindex options, for customization +@cindex variables, for customization + +There are more than 180 variables that can be used to customize +Org-mode. For the sake of compactness of the manual, I am not +describing the variables here. A structured overview of customization +variables is available with @kbd{M-x org-customize}. Or select +@code{Browse Org Group} from the @code{Org->Customization} menu. Many +settings can also be activated on a per-file basis, by putting special +lines into the buffer (@pxref{In-buffer settings}). + +@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous +@section Summary of in-buffer settings +@cindex in-buffer settings +@cindex special keywords + +Org-mode uses special lines in the buffer to define settings on a +per-file basis. These lines start with a @samp{#+} followed by a +keyword, a colon, and then individual words defining a setting. Several +setting words can be in the same line, but you can also have multiple +lines for the keyword. While these settings are described throughout +the manual, here is a summary. After changing any of those lines in the +buffer, press @kbd{C-c C-c} with the cursor still in the line to +activate the changes immediately. Otherwise they become effective only +when the file is visited again in a new Emacs session. + +@table @kbd +@item #+ARCHIVE: %s_done:: +This line sets the archive location for the agenda file. It applies for +all subsequent lines until the next @samp{#+ARCHIVE} line, or the end +of the file. The first such line also applies to any entries before it. +The corresponding variable is @code{org-archive-location}. +@item #+CATEGORY: +This line sets the category for the agenda file. The category applies +for all subsequent lines until the next @samp{#+CATEGORY} line, or the +end of the file. The first such line also applies to any entries before it. +@item #+COLUMNS: %25ITEM ..... +Set the default format for columns view. This format applies when +columns view is invoked in location where no COLUMNS property applies. +@item #+CONSTANTS: name1=value1 ... +Set file-local values for constants to be used in table formulas. This +line set the local variable @code{org-table-formula-constants-local}. +The global version of theis variable is +@code{org-table-formula-constants}. +corresponding +@item #+LINK: linkword replace +These lines (several are allowed) specify link abbreviations. +@xref{Link abbreviations}. The corresponding variable is +@code{org-link-abbrev-alist}. +@item #+PRIORITIES: highest lowest default +This line sets the limits and the default for the priorities. All three +must be either letters A-Z or numbers 0-9. The highest priority must +have a lower ASCII number that the lowest priority. +@item #+PROPERTY: Property_Name Value +This line sets a default inheritance value for entries in the current +buffer, most useful for specifying the allowed values of a property. +@item #+STARTUP: +This line sets options to be used at startup of Org-mode, when an +Org-mode file is being visited. The first set of options deals with the +initial visibility of the outline tree. The corresponding variable for +global default settings is @code{org-startup-folded}, with a default +value @code{t}, which means @code{overview}. +@cindex @code{overview}, STARTUP keyword +@cindex @code{content}, STARTUP keyword +@cindex @code{showall}, STARTUP keyword +@example +overview @r{top-level headlines only} +content @r{all headlines} +showall @r{no folding at all, show everything} +@end example +Then there are options for aligning tables upon visiting a file. This +is useful in files containing narrowed table columns. The corresponding +variable is @code{org-startup-align-all-tables}, with a default value +@code{nil}. +@cindex @code{align}, STARTUP keyword +@cindex @code{noalign}, STARTUP keyword +@example +align @r{align all tables} +noalign @r{don't align tables on startup} +@end example +Logging TODO state changes and clock intervals (variable +@code{org-log-done}) can be configured using these options. +@cindex @code{logdone}, STARTUP keyword +@cindex @code{nologging}, STARTUP keyword +@cindex @code{lognotedone}, STARTUP keyword +@cindex @code{lognoteclock-out}, STARTUP keyword +@cindex @code{lognotestate}, STARTUP keyword +@cindex @code{logrepeat}, STARTUP keyword +@cindex @code{nologrepeat}, STARTUP keyword +@example +logging @r{record a timestamp when an item is marked DONE} +nologging @r{don't record when items are marked DONE} +lognotedone @r{record timestamp and a note when DONE} +lognotestate @r{record timestamp and a note when TODO state changes} +logrepeat @r{record a note when re-instating a repeating item} +nologrepeat @r{do not record when re-instating repeating item} +lognoteclock-out @r{record timestamp and a note when clocking out} +@end example +Here are the options for hiding leading stars in outline headings. The +corresponding variables are @code{org-hide-leading-stars} and +@code{org-odd-levels-only}, both with a default setting @code{nil} +(meaning @code{showstars} and @code{oddeven}). +@cindex @code{hidestars}, STARTUP keyword +@cindex @code{showstars}, STARTUP keyword +@cindex @code{odd}, STARTUP keyword +@cindex @code{even}, STARTUP keyword +@example +hidestars @r{make all but one of the stars starting a headline invisible.} +showstars @r{show all stars starting a headline} +odd @r{allow only odd outline levels (1,3,...)} +oddeven @r{allow all outline levels} +@end example +To turn on custom format overlays over time stamps (variables +@code{org-put-time-stamp-overlays} and +@code{org-time-stamp-overlay-formats}), use +@cindex @code{customtime}, STARTUP keyword +@example +customtime @r{overlay custom time format} +@end example +The following options influence the table spreadsheet (variable +@code{constants-unit-system}). +@cindex @code{constcgs}, STARTUP keyword +@cindex @code{constSI}, STARTUP keyword +@example +constcgs @r{@file{constants.el} should use the c-g-s unit system} +constSI @r{@file{constants.el} should use the SI unit system} +@end example +@item #+TAGS: TAG1(c1) TAG2(c2) +These lines (several such lines are allowed) specify the legal tags in +this file, and (potentially) the corresponding @emph{fast tag selection} +keys. The corresponding variable is @code{org-tag-alist}. +@item #+TBLFM: +This line contains the formulas for the table directly above the line. +@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS: +These lines provide settings for exporting files. For more details see +@ref{Export options}. +@item #+SEQ_TODO: #+TYP_TODO: +These lines set the TODO keywords and their interpretation in the +current file. The corresponding variables are @code{org-todo-keywords} +and @code{org-todo-interpretation}. +@end table + +@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous +@section The very busy C-c C-c key +@kindex C-c C-c +@cindex C-c C-c, overview + +The key @kbd{C-c C-c} has many purposes in org-mode, which are all +mentioned scattered throughout this manual. One specific function of +this key is to add @emph{tags} to a headline (@pxref{Tags}). In many +other circumstances it means something like @emph{Hey Org-mode, look +here and update according to what you see here}. Here is a summary of +what this means in different contexts. + +@itemize @minus +@item +If there are highlights in the buffer from the creation of a sparse +tree, or from clock display, remove these highlights. +@item +If the cursor is in one of the special @code{#+KEYWORD} lines, this +triggers scanning the buffer for these lines and updating the +information. +@item +If the cursor is inside a table, realign the table. This command +works even if the automatic table editor has been turned off. +@item +If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to +the entire table. +@item +If the cursor is inside a table created by the @file{table.el} package, +activate that table. +@item +If the current buffer is a remember buffer, close the note and file it. +With a prefix argument, file it, without further interaction, to the +default location. +@item +If the cursor is on a @code{<<<target>>>}, update radio targets and +corresponding links in this buffer. +@item +If the cursor is in a property line or at the start or end of a property +drawer, offer property commands. +@item +If the cursor is in a plain list item with a checkbox, toggle the status +of the checkbox. +@item +If the cursor is on a numbered item in a plain list, renumber the +ordered list. +@end itemize + +@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous +@section A cleaner outline view +@cindex hiding leading stars +@cindex clean outline view + +Some people find it noisy and distracting that the Org-mode headlines +are starting with a potentially large number of stars. For example +the tree from @ref{Headlines}: + +@example +* Top level headline +** Second level +*** 3rd level + some text +*** 3rd level + more text +* Another top level headline +@end example + +@noindent +Unfortunately this is deeply ingrained into the code of Org-mode and +cannot be easily changed. You can, however, modify the display in such +a way that all leading stars become invisible and the outline more easy +to read. To do this, customize the variable +@code{org-hide-leading-stars} like this: + +@lisp +(setq org-hide-leading-stars t) +@end lisp + +@noindent +or change this on a per-file basis with one of the lines (anywhere in +the buffer) + +@example +#+STARTUP: showstars +#+STARTUP: hidestars +@end example + +@noindent +Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate +the modifications. + +With stars hidden, the tree becomes: + +@example +* Top level headline + * Second level + * 3rd level + some text + * 3rd level + more text +* Another top level headline +@end example + +@noindent +Note that the leading stars are not truly replaced by whitespace, they +are only fontified with the face @code{org-hide} that uses the +background color as font color. If you are not using either white or +black background, you may have to customize this face to get the wanted +effect. Another possibility is to set this font such that the extra +stars are @i{almost} invisible, for example using the color +@code{grey90} on a white background. + +Things become cleaner still if you skip all the even levels and use only +odd levels 1, 3, 5..., effectively adding two stars to go from one +outline level to the next: + +@example +* Top level headline + * Second level + * 3rd level + some text + * 3rd level + more text +* Another top level headline +@end example + +@noindent +In order to make the structure editing and export commands handle this +convention correctly, use + +@lisp +(setq org-odd-levels-only t) +@end lisp + +@noindent +or set this on a per-file basis with one of the following lines (don't +forget to press @kbd{C-c C-c} with the cursor in the startup line to +activate changes immediately). + +@example +#+STARTUP: odd +#+STARTUP: oddeven +@end example + +You can convert an Org-mode file from single-star-per-level to the +double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels +RET} in that file. The reverse operation is @kbd{M-x +org-convert-to-oddeven-levels}. + +@node TTY keys, Interaction, Clean view, Miscellaneous +@section Using org-mode on a tty +@cindex tty keybindings + +Org-mode uses a number of keys that are not accessible on a tty. This +applies to most special keys like cursor keys, @key{TAB} and +@key{RET}, when these are combined with modifier keys like @key{Meta} +and/or @key{Shift}. Org-mode uses these bindings because it needs to +provide keys for a large number of commands, and because these keys +appeared particularly easy to remember. In order to still be able to +access the core functionality of Org-mode on a tty, alternative +bindings are provided. Here is a complete list of these bindings, +which are obviously more cumbersome to use. Note that sometimes a +work-around can be better. For example changing a time stamp is +really only fun with @kbd{S-@key{cursor}} keys. On a tty you would +rather use @kbd{C-c .} to re-insert the timestamp. + +@multitable @columnfractions 0.15 0.2 0.2 +@item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2} +@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab +@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}} +@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab +@item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{@key{Esc} @key{right}} +@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab +@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{@key{Esc} @key{up}} +@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab +@item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{@key{Esc} @key{down}} +@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab +@item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab +@item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{@key{Esc} @key{RET}} +@item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab +@item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab +@item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab +@item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab +@item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab +@item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab +@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab +@end multitable + +@node Interaction, Bugs, TTY keys, Miscellaneous +@section Interaction with other packages +@cindex packages, interaction with other +Org-mode lives in the world of GNU Emacs and interacts in various ways +with other code out there. + +@menu +* Cooperation:: Packages Org-mode cooperates with +* Conflicts:: Packages that lead to conflicts +@end menu + +@node Cooperation, Conflicts, Interaction, Interaction +@subsection Packages that Org-mode cooperates with + +@table @asis +@cindex @file{calc.el} +@item @file{calc.el} by Dave Gillespie +Org-mode uses the calc package for implementing spreadsheet +functionality in its tables (@pxref{The spreadsheet}). Org-mode +checks for the availability of calc by looking for the function +@code{calc-eval} which should be autoloaded in your setup if calc has +been installed properly. As of Emacs 22, calc is part of the Emacs +distribution. Another possibility for interaction between the two +packages is using calc for embedded calculations. @xref{Embedded Mode, +, Embedded Mode, calc, GNU Emacs Calc Manual}. +@cindex @file{constants.el} +@item @file{constants.el} by Carsten Dominik +In a table formula (@pxref{The spreadsheet}), it is possible to use +names for natural constants or units. Instead of defining your own +constants in the variable @code{org-table-formula-constants}, install +the @file{constants} package which defines a large number of constants +and units, and lets you use unit prefixes like @samp{M} for +@samp{Mega} etc. You will need version 2.0 of this package, available +at @url{http://www.astro.uva.nl/~dominik/Tools}. Org-mode checks for +the function @code{constants-get}, which has to be autoloaded in your +setup. See the installation instructions in the file +@file{constants.el}. +@item @file{cdlatex.el} by Carsten Dominik +@cindex @file{cdlatex.el} +Org-mode can make use of the cdlatex package to efficiently enter +La@TeX{} fragments into Org-mode files. See @ref{CDLaTeX mode}. +@item @file{remember.el} by John Wiegley +@cindex @file{remember.el} +Org mode cooperates with remember, see @ref{Remember}. +@file{Remember.el} is not part of Emacs, find it on the web. +@cindex @file{table.el} +@item @file{table.el} by Takaaki Ota +@kindex C-c C-c +@cindex table editor, @file{table.el} +@cindex @file{table.el} + +Complex ASCII tables with automatic line wrapping, column- and +row-spanning, and alignment can be created using the Emacs table +package by Takaaki Ota (@uref{http://sourceforge.net/projects/table}, +and also part of Emacs 22). +When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-mode +will call @command{table-recognize-table} and move the cursor into the +table. Inside a table, the keymap of Org-mode is inactive. In order +to execute Org-mode-related commands, leave the table. + +@table @kbd +@kindex C-c C-c +@item C-c C-c +Recognize @file{table.el} table. Works when the cursor is in a +table.el table. +@c +@kindex C-c ~ +@item C-c ~ +Insert a table.el table. If there is already a table at point, this +command converts it between the table.el format and the Org-mode +format. See the documentation string of the command +@code{org-convert-table} for the restrictions under which this is +possible. +@end table +@file{table.el} is part of Emacs 22. +@cindex @file{footnote.el} +@item @file{footnote.el} by Steven L. Baur +Org-mode recognizes numerical footnotes as provided by this package +(@pxref{Footnotes}). +@end table + +@node Conflicts, , Cooperation, Interaction +@subsection Packages that lead to conflicts with Org-mode + +@table @asis + +@cindex @file{allout.el} +@item @file{allout.el} by Ken Manheimer +Startup of Org-mode may fail with the error message +@code{(wrong-type-argument keymapp nil)} when there is an outdated +version @file{allout.el} on the load path, for example the version +distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem will +disappear. If for some reason you cannot do this, make sure that org.el +is loaded @emph{before} @file{allout.el}, for example by putting +@code{(require 'org)} early enough into your @file{.emacs} file. + +@cindex @file{CUA.el} +@item @file{CUA.el} by Kim. F. Storm +Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys +used by CUA-mode (as well as pc-select-mode and s-region-mode) to +select and extend the region. If you want to use one of these +packages along with Org-mode, configure the variable +@code{org-CUA-compatible}. When set, Org-mode will move the following +keybindings in Org-mode files, and in the agenda buffer (but not +during date selection). + +@example +S-UP -> M-p S-DOWN -> M-n +S-LEFT -> M-- S-RIGHT -> M-+ +@end example + +Yes, these are unfortunately more difficult to remember. If you want +to have other replacement keys, look at the variable +@code{org-disputed-keys}. +@item @file{windmove.el} by Hovav Shacham +@cindex @file{windmove.el} +Also this package uses the @kbd{S-<cursor>} keys, so everything written +in the paragraph above about CUA mode also applies here. + +@cindex @file{footnote.el} +@item @file{footnote.el} by Steven L. Baur +Org-mode supports the syntax of the footnote package, but only the +numerical footnote markers. Also, the default key for footnote +commands, @kbd{C-c !} is already used by Org-mode. You could use the +variable @code{footnote-prefix} to switch footnotes commands to another +key. Or, you could use @code{org-replace-disputed-keys} and +@code{org-disputed-keys} to change the settings in Org-mode. + +@end table + + +@node Bugs, , Interaction, Miscellaneous +@section Bugs +@cindex bugs + +Here is a list of things that should work differently, but which I +have found too hard to fix. + +@itemize @bullet +@item +If a table field starts with a link, and if the corresponding table +column is narrowed (@pxref{Narrow columns}) to a width too small to +display the link, the field would look entirely empty even though it is +not. To prevent this, Org-mode throws an error. The work-around is to +make the column wide enough to fit the link, or to add some text (at +least 2 characters) before the link in the same field. +@item +Narrowing table columns does not work on XEmacs, because the +@code{format} function does not transport text properties. +@item +Text in an entry protected with the @samp{QUOTE} keyword should not +autowrap. +@item +When the application called by @kbd{C-c C-o} to open a file link fails +(for example because the application does not exist or refuses to open +the file), it does so silently. No error message is displayed. +@item +Recalculating a table line applies the formulas from left to right. +If a formula uses @emph{calculated} fields further down the row, +multiple recalculation may be needed to get all fields consistent. You +may use the command @code{org-table-iterate} (@kbd{C-u C-c *}) to +recalculate until convergence. +@item +A single letter cannot be made bold, for example @samp{*a*}. +@item +The exporters work well, but could be made more efficient. +@end itemize + + +@node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top +@appendix Extensions, Hooks and Hacking + +This appendix lists extensions for Org-mode written by other authors. +It also covers some aspects where users can extend the functionality of +Org-mode. + +@menu +* Extensions:: Existing 3rd-part extensions +* Adding hyperlink types:: New custom link types +* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs +* Dynamic blocks:: Automatically filled blocks +* Special agenda views:: Customized views +* Using the property API:: Writing programs that use entry properties +@end menu + +@node Extensions, Adding hyperlink types, Extensions and Hacking, Extensions and Hacking +@section Third-party extensions for Org-mode +@cindex extension, third-party + +The following extensions for Org-mode have been written by other people: + +@table @asis +@cindex @file{org-publish.el} +@item @file{org-publish.el} by David O'Toole +This package provides facilities for publishing related sets of Org-mode +files together with linked files like images as webpages. It is +highly configurable and can be used for other publishing purposes as +well. As of Org-mode version 4.30, @file{org-publish.el} is part of the +Org-mode distribution. It is not yet part of Emacs, however, a delay +caused by the preparations for the 22.1 release. In the mean time, +@file{org-publish.el} can be downloaded from David's site: +@url{http://dto.freeshell.org/e/org-publish.el}. +@cindex @file{org-mouse.el} +@item @file{org-mouse.el} by Piotr Zielinski +This package implements extended mouse functionality for Org-mode. It +allows you to cycle visibility and to edit the document structure with +the mouse. Best of all, it provides a context-sensitive menu on +@key{mouse-3} that changes depending on the context of a mouse-click. +As of Org-mode version 4.53, @file{org-mouse.el} is part of the +Org-mode distribution. It is not yet part of Emacs, however, a delay +caused by the preparations for the 22.1 release. In the mean time, +@file{org-mouse.el} can be downloaded from Piotr's site: +@url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}. +@cindex @file{org-blog.el} +@item @file{org-blog.el} by David O'Toole +A blogging plug-in for @file{org-publish.el}.@* +@url{http://dto.freeshell.org/notebook/OrgMode.html}. +@cindex @file{blorg.el} +@item @file{blorg.el} by Bastien Guerry +Publish Org-mode files as +blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}. +@cindex @file{org2rem.el} +@item @file{org2rem.el} by Bastien Guerry +Translates Org-mode files into something readable by +Remind. @url{http://www.cognition.ens.fr/~guerry/u/org2rem.el}. +@end table + +@page + +@node Adding hyperlink types, Tables in arbitrary syntax, Extensions, Extensions and Hacking +@section Adding hyperlink types +@cindex hyperlinks, adding new types + +Org-mode has a large number of hyperlink types built-in +(@pxref{Hyperlinks}). If you would like to add new link types, it +provides an interface for doing so. Lets look at an example file +@file{org-man.el} that will add support for creating links like +@samp{[[man:printf][The printf manpage]]} to show unix manual pages inside +emacs: + +@lisp +;;; org-man.el - Support for links to manpages in Org-mode + +(require 'org) + +(org-add-link-type "man" 'org-man-open) +(add-hook 'org-store-link-functions 'org-man-store-link) + +(defcustom org-man-command 'man + "The Emacs command to be used to display a man page." + :group 'org-link + :type '(choice (const man) (const woman))) + +(defun org-man-open (path) + "Visit the manpage on PATH. +PATH should be a topic that can be thrown at the man command." + (funcall org-man-command path)) + +(defun org-man-store-link () + "Store a link to a manpage." + (when (memq major-mode '(Man-mode woman-mode)) + ;; This is a man page, we do make this link + (let* ((page (org-man-get-page-name)) + (link (concat "man:" page)) + (description (format "Manpage for %s" page))) + (org-store-link-props + :type "man" + :link link + :description description)))) + +(defun org-man-get-page-name () + "Extract the page name from the buffer name." + ;; This works for both `Man-mode' and `woman-mode'. + (if (string-match " \\(\\S-+\\)\\*" (buffer-name)) + (match-string 1 (buffer-name)) + (error "Cannot create link to this man page"))) + +(provide 'org-man) + +;;; org-man.el ends here +@end lisp + +@noindent +You would activate this new link type in @file{.emacs} with + +@lisp +(require 'org-man) +@end lisp + +@noindent +Lets go through the file and see what it does. +@enumerate +@item +It does @code{(require 'org)} to make sure that @file{org.el} has been +loaded. +@item +The next line calls @code{org-add-link-type} to define a new link type +with prefix @samp{man}. The call also contains the name of a function +that will be called to follow such a link. +@item +The next line adds a function to @code{org-store-link-functions}, in +order to allow the command @kbd{C-c l} to record a useful link in a +buffer displaying a man page. +@end enumerate + +The rest of the file defines the necessary variables and functions. +First there is a customization variable that determines which emacs +command should be used to display manpages. There are two options, +@code{man} and @code{woman}. Then the function to follow a link is +defined. It gets the link path as an argument - in this case the link +path is just a topic for the manual command. The function calls the +value of @code{org-man-command} to display the man page. + +Finally the function @code{org-man-store-link} is defined. When you try +to store a link with @kbd{C-c l}, also this function will be called to +try to make a link. The function must first decide if it is supposed to +create the link for this buffer type, we do this by checking the value +of the variable @code{major-mode}. If not, the function must exit and +retunr the value @code{nil}. If yes, the link is created by getting the +manual tpoic from the buffer name and prefixing it with the string +@samp{man:}. Then it must call the command @code{org-store-link-props} +and set the @code{:type} and @code{:link} properties. Optionally you +can also set the @code{:description} property to provide a default for +the link description when the link is later inserted into tan Org-mode +buffer with @kbd{C-c C-l}. + +@node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Extensions and Hacking +@section Tables in arbitrary syntax +@cindex tables, in other modes +@cindex orgtbl-mode + +Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a +frequent feature request has been to make it work with native tables in +specific languages, for example La@TeX{}. However, this is extremely hard +to do in a general way, would lead to a customization nightmare, and +would take away much of the simplicity of the Orgtbl-mode table editor. + +This appendix describes a different approach. We keep the Orgtbl-mode +table in its native format (the @i{source table}), and use a custom +function to @i{translate} the table to the correct syntax, and to +@i{install} it in the right location (the @i{target table}). This puts +the burden of writing conversion functions on the user, but it allows +for a very flexible system. + +@menu +* Radio tables:: Sending and receiving +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify +@end menu + +@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax +@subsection Radio tables +@cindex radio tables + +To define the location of the target table, you first need to create two +lines that are comments in the current mode, but contain magic words for +Orgtbl-mode to find. Orgtbl-mode will insert the translated table +between these lines, replacing whatever was there before. For example: + +@example +/* BEGIN RECEIVE ORGTBL table_name */ +/* END RECEIVE ORGTBL table_name */ +@end example + +@noindent +Just above the source table, we put a special line that tells +Orgtbl-mode how to translate this table and where to install it. For +example: +@example +#+ORGTBL: SEND table_name translation_function arguments.... +@end example + +@noindent +@code{table_name} is the reference name for the table that is also used +in the receiver lines. @code{translation_function} is the Lisp function +that does the translation. Furthermore, the line can contain a list of +arguments (alternating key and value) at the end. The arguments will be +passed as a property list to the translation function for +interpretation. A few standard parameters are already recognized and +acted upon before the translation function is called: + +@table @code +@item :skip N +Skip the first N lines of the table. Hlines do count! +@item :skipcols (n1 n2 ...) +List of columns that should be skipped. If the table has a column with +calculation marks, that column is automatically discarded as well. +Please note that the translator function sees the table @emph{after} the +removal of these columns, the function never knows that there have been +additional columns. +@end table + +@noindent +The one problem remaining is how to keep the source table in the buffer +without disturbing the normal workings of the file, for example during +compilation of a C file or processing of a La@TeX{} file. There are a +number of different solutions: + +@itemize @bullet +@item +The table could be placed in a block comment if that is supported by the +language. For example, in C-mode you could wrap the table between +@samp{/*} and @samp{*/} lines. +@item +Sometimes it is possible to put the table after some kind of @i{END} +statement, for example @samp{\bye} in TeX and @samp{\end@{document@}} +in La@TeX{}. +@item +You can just comment the table line by line whenever you want to process +the file, and uncomment it whenever you need to edit the table. This +only sounds tedious - the command @kbd{M-x orgtbl-toggle-comment} does +make this comment-toggling very easy, in particular if you bind it to a +key. +@end itemize + +@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax +@subsection A LaTeX example +@cindex LaTeX, and orgtbl-mode + +The best way to wrap the source table in La@TeX{} is to use the +@code{comment} environment provided by @file{comment.sty}. It has to be +activated by placing @code{\usepackage@{comment@}} into the document +header. Orgtbl-mode can insert a radio table skeleton@footnote{By +default this works only for La@TeX{}, HTML, and TeXInfo. Configure the +variable @code{orgtbl-radio-tables} to install templates for other +modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will +be prompted for a table name, lets say we use @samp{salesfigures}. You +will then get the following template: + +@example +% BEGIN RECEIVE ORGTBL salesfigures +% END RECEIVE ORGTBL salesfigures +\begin@{comment@} +#+ORGTBL: SEND salesfigures orgtbl-to-latex +| | | +\end@{comment@} +@end example + +@noindent +The @code{#+ORGTBL: SEND} line tells orgtbl-mode to use the function +@code{orgtbl-to-latex} to convert the table into La@TeX{} and to put it +into the receiver location with name @code{salesfigures}. You may now +fill in the table, feel free to use the spreadsheet features@footnote{If +the @samp{#+TBLFM} line contains an odd number of dollar characters, +this may cause problems with font-lock in latex-mode. As shown in the +example you can fix this by adding an extra line inside the +@code{comment} environment that is used to balance the dollar +expressions. If you are using AUCTeX with the font-latex library, a +much better solution is to add the @code{comment} environment to the +variable @code{LaTeX-verbatim-environments}.}: + +@example +% BEGIN RECEIVE ORGTBL salesfigures +% END RECEIVE ORGTBL salesfigures +\begin@{comment@} +#+ORGTBL: SEND salesfigures orgtbl-to-latex +| Month | Days | Nr sold | per day | +|-------+------+---------+---------| +| Jan | 23 | 55 | 2.4 | +| Feb | 21 | 16 | 0.8 | +| March | 22 | 278 | 12.6 | +#+TBLFM: $4=$3/$2;%.1f +% $ (optional extra dollar to keep font-lock happy, see footnote) +\end@{comment@} +@end example + +@noindent +When you are done, press @kbd{C-c C-c} in the table to get the converted +table inserted between the two marker lines. + +Now lets assume you want to make the table header by hand, because you +want to control how columns are aligned etc. In this case we make sure +that the table translator does skip the first 2 lines of the source +table, and tell the command to work as a @i{splice}, i.e. to not produce +header and footer commands of the target table: + +@example +\begin@{tabular@}@{lrrr@} +Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\ +% BEGIN RECEIVE ORGTBL salesfigures +% END RECEIVE ORGTBL salesfigures +\end@{tabular@} +% +\begin@{comment@} +#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2 +| Month | Days | Nr sold | per day | +|-------+------+---------+---------| +| Jan | 23 | 55 | 2.4 | +| Feb | 21 | 16 | 0.8 | +| March | 22 | 278 | 12.6 | +#+TBLFM: $4=$3/$2;%.1f +\end@{comment@} +@end example + +The La@TeX{} translator function @code{orgtbl-to-latex} is already part of +Orgtbl-mode. It uses a @code{tabular} environment to typeset the table +and marks horizontal lines with @code{\hline}. Furthermore, it +interprets the following parameters: + +@table @code +@item :splice nil/t +When set to t, return only table body lines, don't wrap them into a +tabular environment. Default is nil. + +@item :fmt fmt +A format to be used to wrap each field, should contain @code{%s} for the +original field value. For example, to wrap each field value in dollars, +you could use @code{:fmt "$%s$"}. This may also be a property list with +column numbers and formats. for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}. + +@item :efmt efmt +Use this format to print numbers with exponentials. The format should +have @code{%s} twice for inserting mantissa and exponent, for example +@code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This +may also be a property list with column numbers and formats, for example +@code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After +@code{efmt} has been applied to a value, @code{fmt} will also be +applied. +@end table + +@node Translator functions, , A LaTeX example, Tables in arbitrary syntax +@subsection Translator functions +@cindex HTML, and orgtbl-mode +@cindex translator function + +Orgtbl-mode has several translator functions built-in: +@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and +@code{orgtbl-to-texinfo}. Except for @code{orgtbl-to-html}@footnote{The +HTML translator uses the same code that produces tables during HTML +export.}, these all use a generic translator, @code{orgtbl-to-generic}. +For example, @code{orgtbl-to-latex} itself is a very short function that +computes the column definitions for the @code{tabular} environment, +defines a few field and line separators and then hands over to the +generic translator. Here is the entire code: + +@lisp +@group +(defun orgtbl-to-latex (table params) + "Convert the orgtbl-mode TABLE to LaTeX." + (let* ((alignment (mapconcat (lambda (x) (if x "r" "l")) + org-table-last-alignment "")) + (params2 + (list + :tstart (concat "\\begin@{tabular@}@{" alignment "@}") + :tend "\\end@{tabular@}" + :lstart "" :lend " \\\\" :sep " & " + :efmt "%s\\,(%s)" :hline "\\hline"))) + (orgtbl-to-generic table (org-combine-plists params2 params)))) +@end group +@end lisp + +As you can see, the properties passed into the function (variable +@var{PARAMS}) are combined with the ones newly defined in the function +(variable @var{PARAMS2}). The ones passed into the function (i.e. the +ones set by the @samp{ORGTBL SEND} line) take precedence. So if you +would like to use the La@TeX{} translator, but wanted the line endings to +be @samp{\\[2mm]} instead of the default @samp{\\}, you could just +overrule the default with + +@example +#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]" +@end example + +For a new language, you can either write your own converter function in +analogy with the La@TeX{} translator, or you can use the generic function +directly. For example, if you have a language where a table is started +with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are +started with @samp{!BL!}, ended with @samp{!EL!} and where the field +separator is a TAB, you could call the generic translator like this (on +a single line!): + +@example +#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!" + :lstart "!BL! " :lend " !EL!" :sep "\t" +@end example + +@noindent +Please check the documentation string of the function +@code{orgtbl-to-generic} for a full list of parameters understood by +that function and remember that you can pass each of them into +@code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function +using the generic function. + +Of course you can also write a completely new function doing complicated +things the generic translator cannot do. A translator function takes +two arguments. The first argument is the table, a list of lines, each +line either the symbol @code{hline} or a list of fields. The second +argument is the property list containing all parameters specified in the +@samp{#+ORGTBL: SEND} line. The function must return a single string +containing the formatted table. If you write a generally useful +translator, please post it on @code{emacs-orgmode@@gnu.org} so that +others can benefit from your work. + +@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Extensions and Hacking +@section Dynamic blocks +@cindex dynamic blocks + +Org-mode documents can contain @emph{dynamic blocks}. These are +specially marked regions that are updated by some user-written function. +A good example for such a block is the clock table inserted by the +command @kbd{C-c C-x C-r} (@pxref{Clocking work time}). + +Dynamic block are enclosed by a BEGIN-END structure that assigns a name +to the block and can also specify parameters for the function producing +the content of the block. + +@example +#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... + +#+END: +@end example + +Dynamic blocks are updated with the following commands + +@table @kbd +@kindex C-c C-x C-u +@item C-c C-x C-u +Update dynamic block at point. +@kindex C-u C-c C-x C-u +@item C-u C-c C-x C-u +Update all dynamic blocks in the current file. +@end table + +Updating a dynamic block means to remove all the text between BEGIN and +END, parse the BEGIN line for parameters and then call the specific +writer function for this block to insert the new content. For a block +with name @code{myblock}, the writer function is +@code{org-dblock-write:myblock} with as only parameter a property list +with the parameters given in the begin line. Here is a trivial example +of a block that keeps track of when the block update function was last +run: + +@example +#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" + +#+END: +@end example + +@noindent +The corresponding block writer function could look like this: + +@lisp +(defun org-dblock-write:block-update-time (params) + (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) + (insert "Last block update at: " + (format-time-string fmt (current-time))))) +@end lisp + +If you want to make sure that all dynamic blocks are always up-to-date, +you could add the function @code{org-update-all-dblocks} to a hook, for +example @code{before-save-hook}. @code{org-update-all-dblocks} is +written in a way that is does nothing in buffers that are not in Org-mode. + +@node Special agenda views, Using the property API, Dynamic blocks, Extensions and Hacking +@section Special Agenda Views +@cindex agenda views, user-defined + +Org-mode provides a special hook that can be used to narrow down the +selection made by any of the agenda views. You may specify a function +that is used at each match to verify if the match should indeed be part +of the agenda view, and if not, how much should be skipped. + +Let's say you want to produce a list of projects that contain a WAITING +tag anywhere in the project tree. Let's further assume that you have +marked all tree headings that define a project with the todo keyword +PROJECT. In this case you would run a todo search for the keyword +PROJECT, but skip the match unless there is a WAITING tag anywhere in +the subtree belonging to the project line. + +To achieve this, you must write a function that searches the subtree for +the tag. If the tag is found, the function must return @code{nil} to +indicate that this match should not be skipped. If there is no such +tag, return the location of the end of the subtree, to indicate that +search should continue from there. + +@lisp +(defun my-skip-unless-waiting () + "Skip trees that are not waiting" + (let ((subtree-end (save-excursion (org-end-of-subtree t)))) + (if (re-search-forward ":WAITING:" subtree-end t) + nil ; tag found, do not skip + subtree-end))) ; tag not found, continue after end of subtree +@end lisp + +Now you may use this function in an agenda custom command, for example +like this: + +@lisp +(org-add-agenda-custom-command + '("b" todo "PROJECT" + ((org-agenda-skip-function 'my-org-waiting-projects) + (org-agenda-overriding-header "Projects waiting for something: ")))) +@end lisp + +Note that this also binds @code{org-agenda-overriding-header} to get a +meaningful header in the agenda view. + +You may also put a Lisp form into @code{org-agenda-skip-function}. In +particular, you may use the functions @code{org-agenda-skip-entry-if} +and @code{org-agenda-skip-subtree-if} in this form, for example: + +@table @code +@item '(org-agenda-skip-entry-if 'scheduled) +Skip current entry if it has been scheduled. +@item '(org-agenda-skip-entry-if 'notscheduled) +Skip current entry if it has not been scheduled. +@item '(org-agenda-skip-entry-if 'deadline) +Skip current entry if it has a deadline. +@item '(org-agenda-skip-entry-if 'scheduled 'deadline) +Skip current entry if it has a deadline, or if it is scheduled. +@item '(org-agenda-skip-entry 'regexp "regular expression") +Skip current entry if the regular expression contained in the variable +@code{org-agenda-skip-regexp} matches in the entry. +@item '(org-agenda-skip-subtree-if 'regexp "regular expression") +Same as above, but check and skip the entire subtree. +@end table + +Therefore we could also have written the search for WAITING projects +like this, even without defining a special function: + +@lisp +(org-add-agenda-custom-command + '("b" todo "PROJECT" + ((org-agenda-skip-function '(org-agenda-skip-subtree-if + 'regexp ":WAITING:")) + (org-agenda-overriding-header "Projects waiting for something: ")))) +@end lisp + + +@node Using the property API, , Special agenda views, Extensions and Hacking +@section Using the property API +@cindex API, for properties +@cindex properties, API + +Here is a description of the functions that can be used to work with +properties. + +@defun org-entry-properties &optional pom which +Get all properties of the entry at point-or-marker POM. +This includes the TODO keyword, the tags, time strings for deadline, +scheduled, and clocking, and any additional properties defined in the +entry. The return value is an alist, keys may occur multiple times +if the property key was used several times. +POM may also be nil, in which case the current entry is used. +If WHICH is nil or `all', get all properties. If WHICH is +`special' or `standard', only get that subclass. +@end defun +@defun org-entry-get pom property &optional inherit +Get value of PROPERTY for entry at point-or-marker POM. +If INHERIT is non-nil and the entry does not have the property, +then also check higher levels of the hierarchy. +@end defun + +@defun org-entry-delete pom property +Delete the property PROPERTY from entry at point-or-marker POM. +@end defun + +@defun org-entry-put pom property value +Set PROPERTY to VALUE for entry at point-or-marker POM. +@end defun + +@defun org-buffer-property-keys &optional include-specials +Get all property keys in the current buffer. +@end defun + +@defun org-insert-property-drawer +Insert a property drawer at point. +@end defun + +@node History and Acknowledgments, Index, Extensions and Hacking, Top +@appendix History and Acknowledgments +@cindex acknowledgments +@cindex history +@cindex thanks + +Org-mode was borne in 2003, out of frustration over the user interface +of the Emacs outline-mode. I was trying to organize my notes and +projects, and using Emacs seemed to be the natural way to go. However, +having to remember eleven different commands with two or three keys per +command, only to hide and unhide parts of the outline tree, that seemed +entirely unacceptable to me. Also, when using outlines to take notes, I +constantly want to restructure the tree, organizing it parallel to my +thoughts and plans. @emph{Visibility cycling} and @emph{structure +editing} were originally implemented in the package +@file{outline-magic.el}, but quickly moved to the more general +@file{org.el}. As this environment became comfortable for project +planning, the next step was adding @emph{TODO entries}, basic @emph{time +stamps}, and @emph{table support}. These areas highlight the two main +goals that Org-mode still has today: To create a new, outline-based, +plain text mode with innovative and intuitive editing features, and to +incorporate project planning functionality directly into a notes file. + +Since the first release, literally thousands of emails to me or on +@code{emacs-orgmode@@gnu.org} have provided a constant stream of bug +reports, feedback, new ideas, and sometimes patches and add-on code. +Many thanks to everyone who has helped to improve this package. I am +trying to keep here a list of the people who had significant influence +in shaping one or more aspects of Org-mode. The list may not be +complete, if I have forgotten someone, please accept my apologies and +let me know. + +@itemize @bullet + +@item +@i{Russel Adams} came up with the idea for drawers. +@item +@i{Thomas Baumann} contributed the code for links to the MH-E email +system. +@item +@i{Alex Bochannek} provided a patch for rounding time stamps. +@item +@i{Charles Cave}'s suggestion sparked the implementation of templates +for Remember. +@item +@i{Pavel Chalmoviansky} influenced the agenda treatment of items with +specified time. +@item +@i{Gregory Chernov} patched support for lisp forms into table +calculations and improved XEmacs compatibility, in particular by porting +@file{nouline.el} to XEmacs. +@item +@i{Sacha Chua} suggested to copy some linking code from Planner. +@item +@i{Eddward DeVilla} proposed and tested checkbox statistics. He also +came up with the idea of properties, and that there should be an API for +them. +@item +@i{Kees Dullemond} used to edit projects lists directly in HTML and so +inspired some of the early development, including HTML export. He also +asked for a way to narrow wide table columns. +@item +@i{Christian Egli} converted the documentation into TeXInfo format, +patched CSS formatting into the HTML exporter, and inspired the agenda. +@item +@i{David Emery} provided a patch for custom CSS support in exported +HTML agendas. +@item +@i{Nic Ferrier} contributed mailcap and XOXO support. +@item +@i{John Foerch} figured out how to make incremental search show context +around a match in a hidden outline tree. +@item +@i{Niels Giessen} had the idea to automatically archive DONE trees. +@item +@i{Bastien Guerry} wrote the La@TeX{} exporter and has been prolific +with patches, ideas, and bug reports. +to Org-mode. +@item +@i{Kai Grossjohann} pointed out key-binding conflicts with other packages. +@item +@i{Scott Jaderholm} proposed footnotes, control over whitespace between +folded entries, and column view for properties. +@item +@i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also +provided frequent feedback and some patches. +@item +@i{Jason F. McBrayer} suggested agenda export to CSV format. +@item +@i{Dmitri Minaev} sent a patch to set priority limits on a per-file +basis. +@item +@i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler +happy. +@item +@i{Rick Moynihan} proposed to allow multiple TODO sequences in a file. +@item +@i{Todd Neal} provided patches for links to Info files and elisp forms. +@item +@i{Tim O'Callaghan} suggested in-file links, search options for general +file links, and TAGS. +@item +@i{Takeshi Okano} translated the manual and David O'Toole's tutorial +into Japanese. +@item +@i{Oliver Oppitz} suggested multi-state TODO items. +@item +@i{Scott Otterson} sparked the introduction of descriptive text for +links, among other things. +@item +@i{Pete Phillips} helped during the development of the TAGS feature, and +provided frequent feedback. +@item +@i{T.V. Raman} reported bugs and suggested improvements. +@item +@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality +control. +@item +@i{Kevin Rogers} contributed code to access VM files on remote hosts. +@item +@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a +conflict with @file{allout.el}. +@item +@i{Jason Riedy} sent a patch to fix a bug with export of TODO keywords. +@item +@i{Philip Rooke} created the Org-mode reference card and provided lots +of feedback. +@item +@i{Christian Schlauer} proposed angular brackets around links, among +other things. +@item +Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s +@file{organizer-mode.el}. +@item +@i{Daniel Sinder} came up with the idea of internal archiving by locking +subtrees. +@item +@i{Dale Smith} proposed link abbreviations. +@item +@i{Adam Spiers} asked for global linking commands and inspired the link +extension system. support mairix. +@item +@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual +chapter about publishing. +@item +@i{J@"urgen Vollmer} contributed code generating the table of contents +in HTML output. +@item +@i{Chris Wallace} provided a patch implementing the @samp{QUOTE} +keyword. +@item +@i{David Wainberg} suggested archiving, and improvements to the linking +system. +@item +@i{John Wiegley} wrote @file{emacs-wiki.el} and @file{planner.el}. The +development of Org-mode was fully independent, and both systems are +really different beasts in their basic ideas and implementation details. +I later looked at John's code, however, and learned from his +implementation of (i) links where the link itself is hidden and only a +description is shown, and (ii) popping up a calendar to select a date. +John has also contributed a number of great ideas directly to Org-mode. +@item +@i{Carsten Wimmer} suggested some changes and helped fix a bug in +linking to GNUS. +@item +@i{Roland Winkler} requested additional keybindings to make Org-mode +work on a tty. +@item +@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks +and contributed various ideas and code snippets. +@end itemize + + +@node Index, Key Index, History and Acknowledgments, Top +@unnumbered Index + +@printindex cp + +@node Key Index, , Index, Top +@unnumbered Key Index + +@printindex ky + +@bye + +@ignore + arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac +@end ignore