Mercurial > emacs
changeset 84184:631a352c8899
Move to ../doc/emacs/, misc/
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:39:11 +0000 |
| parents | dc68eaa1d194 |
| children | 69e710c3b51f |
| files | man/org.texi |
| diffstat | 1 files changed, 0 insertions(+), 7931 deletions(-) [+] |
line wrap: on
line diff
--- a/man/org.texi Thu Sep 06 04:39:06 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,7931 +0,0 @@ -\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