diff options
| author | Luke Shumaker <LukeShu@sbcglobal.net> | 2011-04-13 23:20:15 -0400 |
|---|---|---|
| committer | Luke Shumaker <LukeShu@sbcglobal.net> | 2011-04-13 23:20:15 -0400 |
| commit | f7464fdd2e33e5dc6c159a4adc8f53902e6d4511 (patch) | |
| tree | b1d65db982af54cc2088de3228174c4ea710c2f4 /.emacs.d/org-7.4/doc | |
Initial commit of Luke Shumaker's "dot-files".
Diffstat (limited to '.emacs.d/org-7.4/doc')
| -rw-r--r-- | .emacs.d/org-7.4/doc/.nosearch | 1 | ||||
| -rw-r--r-- | .emacs.d/org-7.4/doc/dir | 18 | ||||
| -rw-r--r-- | .emacs.d/org-7.4/doc/org | 16592 | ||||
| -rw-r--r-- | .emacs.d/org-7.4/doc/org.pdf | bin | 0 -> 1482828 bytes | |||
| -rw-r--r-- | .emacs.d/org-7.4/doc/org.texi | 14774 | ||||
| -rw-r--r-- | .emacs.d/org-7.4/doc/orgcard.pdf | bin | 0 -> 83342 bytes | |||
| -rw-r--r-- | .emacs.d/org-7.4/doc/orgcard.tex | 686 | ||||
| -rw-r--r-- | .emacs.d/org-7.4/doc/orgcard_letter.pdf | bin | 0 -> 83320 bytes | |||
| -rw-r--r-- | .emacs.d/org-7.4/doc/orgguide.pdf | bin | 0 -> 283532 bytes | |||
| -rw-r--r-- | .emacs.d/org-7.4/doc/orgguide.texi | 2699 | ||||
| -rw-r--r-- | .emacs.d/org-7.4/doc/pdflayout.sty | 47 |
11 files changed, 34817 insertions, 0 deletions
diff --git a/.emacs.d/org-7.4/doc/.nosearch b/.emacs.d/org-7.4/doc/.nosearch new file mode 100644 index 0000000..50a914b --- /dev/null +++ b/.emacs.d/org-7.4/doc/.nosearch @@ -0,0 +1 @@ +No search diff --git a/.emacs.d/org-7.4/doc/dir b/.emacs.d/org-7.4/doc/dir new file mode 100644 index 0000000..9610c40 --- /dev/null +++ b/.emacs.d/org-7.4/doc/dir @@ -0,0 +1,18 @@ +This is the file .../info/dir, which contains the +topmost node of the Info hierarchy, called (dir)Top. +The first time you invoke Info you start off looking at this node. + +File: dir, Node: Top This is the top of the INFO tree + + This (the Directory node) gives a menu of major topics. + Typing "q" exits, "?" lists all Info commands, "d" returns here, + "h" gives a primer for first-timers, + "mEmacs<Return>" visits the Emacs manual, etc. + + In Emacs, you can click mouse button 2 on a menu item or cross reference + to select it. + +* Menu: + +Emacs +* Org Mode: (org). Outline-based notes management and organizer diff --git a/.emacs.d/org-7.4/doc/org b/.emacs.d/org-7.4/doc/org new file mode 100644 index 0000000..7712859 --- /dev/null +++ b/.emacs.d/org-7.4/doc/org @@ -0,0 +1,16592 @@ +This is org, produced by makeinfo version 4.8 from org.texi. + + This manual is for Org version 7.4. + + Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 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 the freedom to copy and + modify this GNU manual. Buying copies from the FSF supports it in + developing GNU and promoting software freedom." + + This document is part of a collection distributed under the GNU + Free Documentation License. If you want to distribute this + document separately from the collection, you can do so by adding a + copy of the license to the document, as described in section 6 of + the license. + +INFO-DIR-SECTION Emacs +START-INFO-DIR-ENTRY +* Org Mode: (org). Outline-based notes management and organizer +END-INFO-DIR-ENTRY + + +File: org, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +Org Mode Manual +*************** + +This manual is for Org version 7.4. + + Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software +Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 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 the freedom to copy and + modify this GNU manual. Buying copies from the FSF supports it in + developing GNU and promoting software freedom." + + This document is part of a collection distributed under the GNU + Free Documentation License. If you want to distribute this + document separately from the collection, you can do so by adding a + copy of the license to the document, as described in section 6 of + the license. + +* 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:: Storing information about an entry +* Dates and Times:: Making items useful for planning +* Capture - Refile - Archive:: The ins and outs for projects +* Agenda Views:: Collecting information into views +* Markup:: Prepare text for rich export +* Exporting:: Sharing and publishing of notes +* Publishing:: Create a web site of linked Org files +* Working With Source Code:: Export, evaluate, and tangle code blocks +* Miscellaneous:: All the rest which did not fit elsewhere +* Hacking:: How to hack your way around +* MobileOrg:: Viewing and capture on a mobile device +* History and Acknowledgments:: How Org came into being +* Main Index:: An index of Org's concepts and features +* Key Index:: Key bindings and where they are described +* Command and Function Index:: Command names and some internal functions +* Variable Index:: Variables mentioned in the manual + + --- The Detailed Node Listing --- + +Introduction + +* Summary:: Brief summary of what Org does +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. +* Conventions:: Type-setting conventions in the manual + +Document structure + +* Outlines:: Org 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 +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Drawers:: Tucking stuff away +* Blocks:: Folding blocks +* Footnotes:: How footnotes are defined in Org's syntax +* Orgstruct mode:: Structure editing outside Org + +Tables + +* Built-in table editor:: Simple tables +* Column width and alignment:: Overrule the automatic settings +* Column groups:: Grouping to trigger vertical lines +* Orgtbl mode:: The table editor as minor mode +* The spreadsheet:: The table editor has spreadsheet capabilities +* Org-Plot:: Plotting from org tables + +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 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:: 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 + +Internal links + +* Radio targets:: Make targets trigger links in plain text + +TODO items + +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* Progress logging:: Dates and notes for progress +* 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 does the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Fast access to TODO states:: Single letter selection of a state +* Per-file keywords:: Different files, different requirements +* Faces for TODO keywords:: Highlighting states +* TODO dependencies:: When one task needs to wait for others + +Progress logging + +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Tracking your habits:: How consistent have you been? + +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 +* Property inheritance:: Passing values down the tree +* 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 +* Capturing column view:: A dynamic block for column view + +Defining columns + +* Scope of column definitions:: Where defined, where valid? +* Column attributes:: Appearance and content of a column + +Dates and times + +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task +* Effort estimates:: Planning work effort in advance +* Relative timer:: Notes with a running timer +* Countdown timer:: Starting a countdown timer for a task + +Creating timestamps + +* The date/time prompt:: How Org-mode helps you entering date and time +* Custom time format:: Making dates look different + +Deadlines and scheduling + +* Inserting deadline/schedule:: Planning items +* Repeated tasks:: Items that show up again and again + +Clocking work time + +* Clocking commands:: Starting and stopping a clock +* The clock table:: Detailed reports +* Resolving idle time:: Resolving time when you've been idle + +Capture - Refile - Archive + +* Capture:: Capturing new stuff +* Attachments:: Add files to tasks +* RSS Feeds:: Getting input from RSS feeds +* Protocols:: External (e.g. Browser) access to Emacs and Org +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects + +Capture + +* Setting up capture:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types + +Capture templates + +* Template elements:: What is needed for a complete template entry +* Template expansion:: Filling in information about time and context + +Archiving + +* Moving subtrees:: Moving a tree to an archive file +* Internal archiving:: Switch off a tree but keep it in the file + +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 +* Exporting Agenda Views:: Writing a view to a file +* Agenda column view:: Using column view for collected entries + +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 +* Search view:: Find entries by searching for text +* 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 + +Markup for rich export + +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Index entries:: Making an index +* Macro replacement:: Use macros to create complex output +* Embedded LaTeX:: LaTeX can be freely used inside Org documents + +Structural markup elements + +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Initial text:: Text before the first heading? +* Lists:: Lists +* Paragraphs:: Paragraphs +* Footnote markup:: Footnotes +* Emphasis and monospace:: Bold, italic, etc. +* Horizontal rules:: Make a line +* Comment lines:: What will *not* be exported + +Embedded LaTeX + +* Special symbols:: Greek letters and other symbols +* Subscripts and superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Previewing LaTeX fragments:: What will this snippet look like? +* CDLaTeX mode:: Speed up entering of formulas + +Exporting + +* Selective export:: Using tags to select and exclude trees +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to LaTeX, and processing to PDF +* DocBook export:: Exporting to DocBook +* TaskJuggler export:: Exporting to TaskJuggler +* Freemind export:: Exporting to Freemind mind maps +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format + +HTML export + +* HTML Export commands:: How to invoke HTML export +* Quoting HTML tags:: Using direct HTML in Org-mode +* Links in HTML export:: How links will be interpreted and formatted +* Tables in HTML export:: How to modify the formatting of tables +* Images in HTML export:: How to insert figures into HTML output +* Math formatting in HTML export:: Beautiful math also on the web +* Text areas in HTML export:: An alternative way to show an example +* CSS support:: Changing the appearance of the output +* JavaScript support:: Info and Folding in a web browser + +LaTeX and PDF export + +* LaTeX/PDF export commands:: Which key invokes which commands +* Header and sectioning:: Setting up the export file structure +* Quoting LaTeX code:: Incorporating literal LaTeX code +* Tables in LaTeX export:: Options for exporting tables to LaTeX +* Images in LaTeX export:: How to insert figures into LaTeX output +* Beamer class export:: Turning the file into a presentation + +DocBook export + +* DocBook export commands:: How to invoke DocBook export +* Quoting DocBook code:: Incorporating DocBook code in Org files +* Recursive sections:: Recursive sections in DocBook +* Tables in DocBook export:: Tables are exported as HTML tables +* Images in DocBook export:: How to insert figures into DocBook output +* Special characters:: How to handle special characters + +Publishing + +* Configuration:: Defining projects +* Uploading files:: How to get files up on the server +* 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? +* Sitemap:: Generating a list of all pages +* Generating an index:: An index that reaches across pages + +Sample configuration + +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example + +Working with source code + +* Structure of code blocks:: Code block syntax described +* Editing source code:: Language major-mode editing +* Exporting code blocks:: Export contents and/or results +* Extracting source code:: Create pure source code files +* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Library of Babel:: Use and contribute to a library of useful code blocks +* Languages:: List of supported code block languages +* Header arguments:: Configure code block functionality +* Results of evaluation:: How evaluation results are handled +* Noweb reference syntax:: Literate programming in Org-mode +* Key bindings and useful functions:: Work quickly with code blocks +* Batch execution:: Call functions from the command line + +Header arguments + +* Using header arguments:: Different ways to set header arguments +* Specific header arguments:: List of header arguments + +Using header arguments + +* System-wide header arguments:: Set global default values +* Language-specific header arguments:: Set default values by language +* Buffer-wide header arguments:: Set default values for a specific buffer +* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Code block specific header arguments:: The most common way to set values +* Header arguments in function calls:: The most specific level + +Specific header arguments + +* var:: Pass arguments to code blocks +* results:: Specify the type of results and how they will + be collected and handled +* file:: Specify a path for file output +* dir:: Specify the default (possibly remote) + directory for code block execution +* exports:: Export code and/or results +* tangle:: Toggle tangling and specify file name +* comments:: Toggle insertion of comments in tangled + code files +* no-expand:: Turn off variable assignment and noweb + expansion during tangling +* session:: Preserve the state of code evaluation +* noweb:: Toggle expansion of noweb references +* cache:: Avoid re-evaluating unchanged code blocks +* hlines:: Handle horizontal lines in tables +* colnames:: Handle column names in tables +* rownames:: Handle row names in tables +* shebang:: Make tangled files executable +* eval:: Limit evaluation of specific code blocks + +Miscellaneous + +* Completion:: M-TAB knows what you need +* Easy Templates:: Quick insertion of structural elements +* Speed keys:: Electric commands at the beginning of a headline +* Code evaluation security:: Org mode files evaluate inline code +* Customization:: Adapting Org 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 on a tty +* Interaction:: Other Emacs packages + +Interaction with other packages + +* Cooperation:: Packages Org cooperates with +* Conflicts:: Packages that lead to conflicts + +Hacking + +* Hooks:: Who to reach into Org's internals +* Add-on packages:: Available extensions +* Adding hyperlink types:: New custom link types +* Context-sensitive commands:: How to add functionality to such commands +* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs +* Dynamic blocks:: Automatically filled blocks +* Special agenda views:: Customized views +* Extracting agenda information:: Postprocessing of agenda information +* Using the property API:: Writing programs that use entry properties +* Using the mapping API:: Mapping over all or selected entries + +Tables and lists in arbitrary syntax + +* Radio tables:: Sending and receiving radio tables +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify +* Radio lists:: Doing the same for lists + +MobileOrg + +* Setting up the staging area:: Where to interact with the mobile device +* Pushing to MobileOrg:: Uploading Org files and agendas +* Pulling from MobileOrg:: Integrating captured and flagged items + + +File: org, Node: Introduction, Next: Document Structure, Prev: Top, Up: Top + +1 Introduction +************** + +* Menu: + +* Summary:: Brief summary of what Org does +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. +* Conventions:: Type-setting conventions in the manual + + +File: org, Node: Summary, Next: Installation, Prev: Introduction, Up: Introduction + +1.1 Summary +=========== + +Org is a mode for keeping notes, maintaining TODO lists, and doing +project planning with a fast and effective plain-text system. + + Org develops organizational tasks around NOTES files that contain +lists or information about projects as plain text. Org 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 supports TODO items, deadlines, timestamps, 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 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 web pages. + + As a project planning environment, Org works by adding metadata to +outline nodes. Based on this data, specific entries can be extracted +in queries and create dynamic agenda views. + + Org mode contains the Org Babel environment which allows you to work +with embedded source code blocks in a file, to facilitate code +evaluation, documentation, and tangling. + + Org'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 LaTeX. The structure +editing and list creation capabilities can be used outside Org with the +minor Orgstruct mode. + + Org 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 is a toolbox and can be used in different ways and for +different ends, for example: + + * an outline extension with visibility cycling and structure editing + * an ASCII system and table editor for taking structured notes + * a TODO list editor + * a full agenda and planner with deadlines and work scheduling + * an environment in which to implement David Allen's GTD system + * a simple hypertext system, with HTML and LaTeX export + * a publishing tool to create a set of interlinked webpages + * an environment for literate programming + + There is a website for Org which provides links to the newest +version of Org, as well as additional information, frequently asked +questions (FAQ), links to tutorials, etc. This page is located at +`http://orgmode.org'. + + +File: org, Node: Installation, Next: Activation, Prev: Summary, Up: Introduction + +1.2 Installation +================ + +Important: If you are using a version of Org that is part of the Emacs +distribution or an XEmacs package, please skip this section and go +directly to *Note Activation::. + + If you have downloaded Org from the Web, either as a distribution +`.zip' or `.tar' file, or as a Git archive, you must take the following +steps to install it: go into the unpacked Org distribution directory +and edit the top section of the file `Makefile'. You must set the name +of the Emacs binary (likely either `emacs' or `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, you can simply run +Org directly from the distribution directory by adding the `lisp' +subdirectory to the Emacs load path. To do this, add the following +line to `.emacs': + + (setq load-path (cons "~/path/to/orgdir/lisp" load-path)) + +If you plan to use code from the `contrib' subdirectory, do a similar +step for this directory: + + (setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) + +Now byte-compile the Lisp files with the shell command: + + make + +If you are running Org from the distribution directory, this is all. +If you want to install Org into the system directories, use (as +administrator) + + make install + + Installing Info files is system dependent, because of differences in +the `install-info' program. In Debian it copies the info files into the +correct directory and modifies the info directory file. In many other +systems, the files need to be copied to the correct directory +separately, and `install-info' then only modifies the directory file. +Check your system documentation to find out which of the following +commands you need: + + make install-info + make install-info-debian + + Then add the following line to `.emacs'. It is needed so that Emacs +can autoload functions that are located in files not immediately loaded +when Org-mode starts. + (require 'org-install) + + Do not forget to activate Org as described in the following section. + + +File: org, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction + +1.3 Activation +============== + +Add the following lines to your `.emacs' file. The last three lines +define _global_ keys for the commands `org-store-link', `org-agenda', +and `org-iswitchb'--please choose suitable keys yourself. + + ;; 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) + (global-set-key "\C-cb" 'org-iswitchb) + + Furthermore, you must activate `font-lock-mode' in Org buffers, +because significant functionality depends on font-locking being active. +You can do this with either one of the following two lines (XEmacs +users must use the second option): + (global-font-lock-mode 1) ; for all buffers + (add-hook 'org-mode-hook 'turn-on-font-lock) ; Org buffers only + + With this setup, all files with extension `.org' will be put into +Org-mode. As an alternative, make the first line of a file look like +this: + + MY PROJECTS -*- mode: org; -*- + +which will select Org-mode for this buffer no matter what the file's +name is. See also the variable `org-insert-mode-line-in-empty-file'. + + Many commands in Org work on the region if the region is active. To +make use of this, you need to have `transient-mark-mode' +(`zmacs-regions' in XEmacs) turned on. In Emacs 23 this is the default, +in Emacs 22 you need to do this yourself with + (transient-mark-mode 1) + If you do not like `transient-mark-mode', you can create an active +region by using the mouse to select a region, or pressing `C-<SPC>' +twice before moving the cursor. + + +File: org, Node: Feedback, Next: Conventions, Prev: Activation, Up: Introduction + +1.4 Feedback +============ + +If you find problems with Org, or if you have questions, remarks, or +ideas about it, please mail to the Org mailing list +<emacs-orgmode@gnu.org>. If you are not a member of the mailing list, +your mail will be passed to the list after a moderator has approved +it(1). + + For bug reports, please first try to reproduce the bug with the +latest version of Org available--if you are running an outdated +version, it is quite possible that the bug has been fixed already. If +the bug persists, prepare a report and provide as much information as +possible, including the version information of Emacs (`M-x +emacs-version <RET>') and Org (`M-x org-version <RET>'), as well as the +Org related setup in `.emacs'. The easiest way to do this is to use +the command + M-x org-submit-bug-report + which will put all this information into an Emacs mail buffer so +that you only need to add your description. If you re not sending the +Email from within Emacs, please copy and paste the content into your +Email program. + + 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: + + 1. What exactly did you do? + + 2. What did you expect to happen? + + 3. What happened instead? + Thank you for helping to improve this program. + +How to create a useful backtrace +................................ + +If working with Org 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 _backtrace_. +This is information from the built-in debugger about where and how the +error occurred. Here is how to produce a useful backtrace: + + 1. Reload uncompiled versions of all Org-mode Lisp files. The + backtrace contains much more information if it is produced with + uncompiled code. To do this, use + C-u M-x org-reload RET + or select `Org -> Refresh/Reload -> Reload Org uncompiled' from the + menu. + + 2. Go to the `Options' menu and select `Enter Debugger on Error' + (XEmacs has this option in the `Troubleshooting' sub-menu). + + 3. Do whatever you have to do to hit the error. Don't forget to + document the steps you take. + + 4. When you hit the error, a `*Backtrace*' buffer will appear on the + screen. Save this buffer to a file (for example using `C-x C-w') + and attach it to your bug report. + + ---------- Footnotes ---------- + + (1) Please consider subscribing to the mailing list, in order to +minimize the work the mailing list moderators have to do. + + +File: org, Node: Conventions, Prev: Feedback, Up: Introduction + +1.5 Typesetting conventions used in this manual +=============================================== + +Org uses three types of keywords: TODO keywords, tags, and property +names. In this manual we use the following conventions: + +`TODO' +`WAITING' + TODO keywords are written with all capitals, even if they are + user-defined. + +`boss' +`ARCHIVE' + User-defined tags are written in lowercase; built-in tags with + special meaning are written with all capitals. + +`Release' +`PRIORITY' + User-defined properties are capitalized; built-in properties with + special meaning are written with all capitals. + + The manual lists both the keys and the corresponding commands for +accessing functionality. Org mode often uses the same key for +different functions, depending on context. The command that is bound +to such keys has a generic name, like `org-metaright'. In the manual +we will, wherever possible, give the function that is internally called +by the generic command. For example, in the chapter on document +structure, `M-<right>' will be listed to call `org-do-demote', while in +the chapter on tables, it will be listed to call +org-table-move-column-right. + + If you prefer, you can compile the manual without the command names +by unsetting the flag `cmdnames' in `org.texi'. + + +File: org, Node: Document Structure, Next: Tables, Prev: Introduction, Up: Top + +2 Document structure +******************** + +Org is based on Outline mode and provides flexible commands to edit the +structure of the document. + +* Menu: + +* Outlines:: Org 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 +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Drawers:: Tucking stuff away +* Blocks:: Folding blocks +* Footnotes:: How footnotes are defined in Org's syntax +* Orgstruct mode:: Structure editing outside Org + + +File: org, Node: Outlines, Next: Headlines, Prev: Document Structure, Up: Document Structure + +2.1 Outlines +============ + +Org 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 greatly simplifies the use of outlines by +compressing the entire show/hide functionality into a single command, +`org-cycle', which is bound to the <TAB> key. + + +File: org, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document Structure + +2.2 Headlines +============= + +Headlines define the structure of an outline tree. The headlines in Org +start with one or more stars, on the left margin(1). For example: + + * Top level headline + ** Second level + *** 3rd level + some text + *** 3rd level + more text + + * Another top level headline + +Some people find the many stars too noisy and would prefer an outline +that has whitespace followed by a single star as headline starters. +*Note 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 `org-cycle-separator-lines' to modify this behavior. + + ---------- Footnotes ---------- + + (1) See the variables `org-special-ctrl-a/e', `org-special-ctrl-k', +and `org-ctrl-k-protect-subtree' to configure special behavior of `C-a', +`C-e', and `C-k' in headlines. + + +File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document Structure + +2.3 Visibility cycling +====================== + +Outlines make it possible to hide parts of the text in the buffer. Org +uses just two commands, bound to <TAB> and `S-<TAB>' to change the +visibility in the buffer. + +`<TAB>' (`org-cycle') + _Subtree cycling_: Rotate current subtree among the states + + ,-> FOLDED -> CHILDREN -> SUBTREE --. + '-----------------------------------' + + The cursor must be on a headline for this to work(1). When the + cursor is at the beginning of the buffer and the first line is not + a headline, then <TAB> actually runs global cycling (see + below)(2). Also when called with a prefix argument (`C-u <TAB>'), + global cycling is invoked. + +`S-<TAB>' (`org-global-cycle') +C-u <TAB> + _Global cycling_: Rotate the entire buffer among the states + + ,-> OVERVIEW -> CONTENTS -> SHOW ALL --. + '--------------------------------------' + + When `S-<TAB>' is called with a numeric prefix argument N, the + CONTENTS view up to headlines of level N will be shown. Note that + inside tables, `S-<TAB>' jumps to the previous field. + +`C-u C-u C-u <TAB>' (`show-all') + Show all, including drawers. + +`C-c C-r' (`org-reveal') + Reveal context around point, showing the current entry, the + following heading and the hierarchy above. Useful for working + near a location that has been exposed by a sparse tree command + (*note Sparse trees::) or an agenda command (*note Agenda + commands::). With a prefix argument show, on each level, all + sibling headings. With double prefix arg, also show the entire + subtree of the parent. + +`C-c C-k' (`show-branches') + Expose all the headings of the subtree, CONTENT view for just one + subtree. + +`C-c C-x b' (`org-tree-to-indirect-buffer') + Show the current subtree in an indirect buffer(3). With a numeric + prefix argument N, go up to level N and then take that tree. If N + is negative then go up that many levels. With a `C-u' prefix, do + not remove the previously used indirect buffer. + + When Emacs first visits an Org file, the global state is set to +OVERVIEW, i.e. only the top level headlines are visible. This can be +configured through the variable `org-startup-folded', or on a per-file +basis by adding one of the following lines anywhere in the buffer: + + #+STARTUP: overview + #+STARTUP: content + #+STARTUP: showall + #+STARTUP: showeverything + +Furthermore, any entries with a `VISIBILITY' property (*note Properties +and Columns::) will get their visibility adapted accordingly. Allowed +values for this property are `folded', `children', `content', and `all'. +`C-u C-u <TAB>' (`org-set-startup-visibility') + Switch back to the startup visibility of the buffer, i.e. whatever + is requested by startup options and `VISIBILITY' properties in + individual entries. + + ---------- Footnotes ---------- + + (1) see, however, the option `org-cycle-emulate-tab'. + + (2) see the option `org-cycle-global-at-bob'. + + (3) The indirect buffer (*note Indirect Buffers: (emacs)Indirect +Buffers.) 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. + + +File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document Structure + +2.4 Motion +========== + +The following commands jump to other headlines in the buffer. + +`C-c C-n' (`outline-next-visible-heading') + Next heading. + +`C-c C-p' (`outline-previous-visible-heading') + Previous heading. + +`C-c C-f' (`org-forward-same-level') + Next heading same level. + +`C-c C-b' (`org-backward-same-level') + Previous heading same level. + +`C-c C-u' (`outline-up-heading') + Backward to higher level heading. + +`C-c C-j' (`org-goto') + 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: + <TAB> Cycle visibility. + <down> / <up> Next/previous visible headline. + <RET> Select this location. + / Do a Sparse-tree search + The following keys work if you turn off `org-goto-auto-isearch' + n / p Next/previous visible headline. + f / b Next/previous headline same level. + u One level up. + 0-9 Digit argument. + q Quit + See also the variable `org-goto-interface'. + + +File: org, Node: Structure editing, Next: Sparse trees, Prev: Motion, Up: Document Structure + +2.5 Structure editing +===================== + +`M-<RET>' (`org-insert-heading') + Insert new heading with same level as current. If the cursor is + in a plain list item, a new item is created (*note Plain lists::). + To force creation of a new headline, use a prefix argument, or + first press <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(1). 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. + +`C-<RET>' (`org-insert-heading-respect-content') + Just like `M-<RET>', except when adding a new heading below the + current heading, the new heading is placed after the body instead + of before it. This command works from anywhere in the entry. + +`M-S-<RET>' (`org-insert-todo-heading') + Insert new TODO entry with same level as current heading. See + also the variable `org-treat-insert-todo-heading-as-state-change'. + +`C-S-<RET>' (`org-insert-todo-heading-respect-content') + Insert new TODO entry with same level as current heading. Like + `C-<RET>', the new headline will be inserted after the current + subtree. + +`<TAB>' (`org-cycle') + In a new entry with no text yet, the first <TAB> demotes the entry + to become a child of the previous one. The next <TAB> makes it a + parent, and so on, all the way to top level. Yet another <TAB>, + and you are back to the initial level. + +`M-<left>' (`org-do-promote') + Promote current heading by one level. + +`M-<right>' (`org-do-demote') + Demote current heading by one level. + +`M-S-<left>' (`org-promote-subtree') + Promote the current subtree by one level. + +`M-S-<right>' (`org-demote-subtree') + Demote the current subtree by one level. + +`M-S-<up>' (`org-move-subtree-up') + Move subtree up (swap with previous subtree of same level). + +`M-S-<down>' (`org-move-subtree-down') + Move subtree down (swap with next subtree of same level). + +`C-c C-x C-w' (`org-cut-subtree') + Kill subtree, i.e. remove it from buffer but save in kill ring. + With a numeric prefix argument N, kill N sequential subtrees. + +`C-c C-x M-w' (`org-copy-subtree') + Copy subtree to kill ring. With a numeric prefix argument N, copy + the N sequential subtrees. + +`C-c C-x C-y' (`org-paste-subtree') + 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 numeric prefix + argument, or by yanking after a headline marker like `****'. + +`C-y' (`org-yank') + Depending on the variables `org-yank-adjusted-subtrees' and + `org-yank-folded-subtrees', Org's internal `yank' command will + paste subtrees folded and in a clever way, using the same command + as `C-c C-x C-y'. With the default settings, no level adjustment + will take place, but the yanked tree will be folded unless doing + so would swallow text previously visible. Any prefix argument to + this command will force a normal `yank' to be executed, with the + prefix passed along. A good way to force a normal yank is `C-u + C-y'. If you use `yank-pop' after a yank, it will yank previous + kill items plainly, without adjustment and folding. + +`C-c C-x c' (`org-clone-subtree-with-time-shift') + Clone a subtree by making a number of sibling copies of it. You + will be prompted for the number of copies to make, and you can + also specify if any timestamps in the entry should be shifted. + This can be useful, for example, to create a number of tasks + related to a series of lectures to prepare. For more details, see + the docstring of the command `org-clone-subtree-with-time-shift'. + +`C-c C-w' (`org-refile') + Refile entry or region to a different location. *Note Refiling + notes::. + +`C-c ^' (`org-sort-entries-or-items') + 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 + (first timestamp with active preferred, creation time, scheduled + time, deadline time), by priority, by TODO keyword (in the + sequence the keywords have been defined in the setup) or by the + value of a property. Reverse sorting is possible as well. You + can also supply your own function to extract the sorting key. + With a `C-u' prefix, sorting will be case-sensitive. With two + `C-u C-u' prefixes, duplicate entries will also be removed. + +`C-x n s' (`org-narrow-to-subtree') + Narrow buffer to current subtree. + +`C-x n w' (`widen') + Widen buffer to remove narrowing. + +`C-c *' (`org-toggle-heading') + Turn a normal line or plain list item into a headline (so that it + becomes a subheading at its location). Also turn a headline into + a normal line by removing the stars. If there is an active + region, turn all lines in the region into headlines. If the first + line in the region was an item, turn only the item lines into + headlines. Finally, if the first line is a headline, remove the + stars from all headlines in the region. + + 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 (*note Tables::), the Meta-Cursor keys have different +functionality. + + ---------- Footnotes ---------- + + (1) If you do not want the line to be split, customize the variable +`org-M-RET-may-split-line'. + + +File: org, Node: Sparse trees, Next: Plain lists, Prev: Structure editing, Up: Document Structure + +2.6 Sparse trees +================ + +An important feature of Org-mode is the ability to construct _sparse +trees_ for selected information in an outline tree, so that the entire +document is folded as much as possible, but the selected information is +made visible along with the headline structure above it(1). Just try +it out and you will see immediately how it works. + + Org-mode contains several commands creating such trees, all these +commands can be accessed through a dispatcher: + +`C-c /' (`org-sparse-tree') + This prompts for an extra key to select a sparse-tree creating + command. + +`C-c / r' (`org-occur') + 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(2), or by pressing `C-c C-c'. When called + with a `C-u' prefix argument, previous highlights are kept, so + several calls to this command can be stacked. + +For frequently used sparse trees of specific search strings, you can +use the variable `org-agenda-custom-commands' to define fast keyboard +access to specific sparse trees. These commands will then be +accessible through the agenda dispatcher (*note Agenda dispatcher::). +For example: + + (setq org-agenda-custom-commands + '(("f" occur-tree "FIXME"))) + +will define the key `C-c a f' as a shortcut for creating a sparse tree +matching the string `FIXME'. + + The other sparse tree commands select headings based on TODO +keywords, tags, or properties and will be discussed later in this +manual. + + To print a sparse tree, you can use the Emacs command +`ps-print-buffer-with-faces' which does not print invisible parts of +the document (3). Or you can use the command `C-c C-e v' to export +only the visible part of the document and print the resulting file. + + ---------- Footnotes ---------- + + (1) See also the variables `org-show-hierarchy-above', +`org-show-following-heading', `org-show-siblings', and +`org-show-entry-below' for detailed control on how much context is +shown around each match. + + (2) This depends on the option `org-remove-highlights-with-change' + + (3) This does not work under XEmacs, because XEmacs uses selective +display for outlining, not text properties. + + +File: org, Node: Plain lists, Next: Drawers, Prev: Sparse trees, Up: Document Structure + +2.7 Plain 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 (*note Checkboxes::). Org supports editing such lists, and +every exporter (*note Exporting::) can parse and format them. + + Org knows ordered lists, unordered lists, and description lists. + * _Unordered_ list items start with `-', `+', or `*'(1) as bullets. + + * _Ordered_ list items start with a numeral followed by either a + period or a right parenthesis(2), such as `1.' or `1)'. If you + want a list to start with a different value (e.g. 20), start the + text of the item with `[@20]'(3). Those constructs can be used in + any item of the list in order to enforce a particular numbering. + + * _Description_ list items are unordered list items, and contain the + separator ` :: ' to separate the description _term_ from the + description. + + Items belonging to the same list must have the same indentation on +the first line. In particular, if an ordered list reaches number +`10.', then the 2-digit numbers must be written left-aligned with the +other numbers in the list. + + Two methods(4) are provided to terminate lists. A list ends before +the next line that is indented like the bullet/number or less, or it +ends before two blank lines(5). In both cases, all levels of the list +are closed(6). For finer control, you can end lists with any pattern +set in `org-list-end-regexp'. Here is an example: + + ** Lord of the Rings + My favorite scenes are (in this order) + 1. The attack of the Rohirrim + 2. Eowyn's 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 + He makes a really funny face when it happens. + - on DVD only + But in the end, no individual scenes matter but the film as a whole. + Important actors in this film are: + - Elijah Wood :: He plays Frodo + - Sean Austin :: He plays Sam, Frodo's friend. I still remember + him very well from his role as Mikey Walsh in The Goonies. + + Org supports these lists by tuning filling and wrapping commands to +deal with them correctly(7), and by exporting them properly (*note +Exporting::). Since indentation is what governs the structure of these +lists, many structural constructs like `#+BEGIN_...' blocks can be +indented to signal that they should be considered as a list item. + + If you find that using a different bullet for a sub-list (than that +used for the current list-level) improves readability, customize the +variable `org-list-demote-modify-bullet'. + + The following commands act on items when the cursor is in the first +line of an item (the line with the bullet or number). Some of them +imply the application of automatic rules to keep list structure intact. +If some of these actions get in your way, configure +`org-list-automatic-rules' to disable them individually. + +`<TAB>' (`org-cycle') + Items can be folded just like headline levels. Normally this + works only if the cursor is on a plain list item. For more + details, see the variable `org-cycle-include-plain-lists'. If + this variable is set to `integrate', plain list items will be + treated like low-level headlines. 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. + +`M-<RET>' (`org-insert-heading') + Insert new item at current level. With a prefix argument, force a + new heading (*note Structure editing::). If this command is used + in the middle of a line, the line is _split_ and the rest of the + line becomes the new item(8). If this command is executed _before + an item's body_, the new item is created _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. + + As a new item cannot be inserted in a structural construct (like + an example or source code block) within a list, Org will instead + insert it right before the structure, or return an error. + +M-S-<RET> + Insert a new item with a checkbox (*note Checkboxes::). + +`<TAB>' (`org-cycle') + In a new item with no text yet, the first <TAB> demotes the item to + become a child of the previous one. Subsequent <TAB>s move the + item to meaningful levels in the list and eventually get it back + to its initial position. + +S-<up> +S-<down> + Jump to the previous/next item in the current list, but only if + `org-support-shift-select' is off. If not, you can still use + paragraph jumping commands like `C-<up>' and `C-<down>' to quite + similar effect. + +M-S-<up> +M-S-<down> + Move the item including subitems up/down (swap with previous/next + item of same indentation). If the list is ordered, renumbering is + automatic. + +M-<left> +M-<right> + Decrease/increase the indentation of an item, leaving children + alone. + +M-S-<left> +M-S-<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. + + As a special case, using this command on the very first item of a + list will move the whole list. This behavior can be disabled by + configuring `org-list-automatic-rules'. The global indentation of + a list has no influence on the text _after_ the list. + +C-c C-c + If there is a checkbox (*note Checkboxes::) in the item line, + toggle the state of the checkbox. Also, makes sure that all the + items on this list level use the same bullet and that the + numbering of list items (if applicable) is correct. + +C-c - + Cycle the entire list level through the different + itemize/enumerate bullets (`-', `+', `*', `1.', `1)') or a subset + of them, depending on `org-plain-list-ordered-item-terminator', + the type of list, and its position(9). With a numeric prefix + argument N, select the Nth bullet from this list. If there is an + active region when calling this, all lines will be converted to + list items. If the first line already was a list item, any item + markers will be removed from the list. Finally, even without an + active region, a normal line will be converted into a list item. + +C-c * + Turn a plain list item into a headline (so that it becomes a + subheading at its location). *Note Structure editing::, for a + detailed explanation. + +S-<left>/<right> + This command also cycles bullet styles when the cursor in on the + bullet or anywhere in an item line, details depending on + `org-support-shift-select'. + +C-c ^ + Sort the plain list. You will be prompted for the sorting method: + numerically, alphabetically, by time, or by custom function. + + ---------- Footnotes ---------- + + (1) When using `*' 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 `*' is supported, it may be better to not use it for plain +list items. + + (2) You can filter out any of them by configuring +`org-plain-list-ordered-item-terminator'. + + (3) If there's a checkbox in the item, the cookie must be put +_before_ the checkbox. + + (4) To disable either of them, configure `org-list-ending-method'. + + (5) See also `org-empty-line-terminates-plain-lists'. + + (6) So you cannot have a sublist, some text and then another sublist +while still in the same top-level list item. This used to be possible, +but it was only supported in the HTML exporter and difficult to manage +with automatic indentation. + + (7) Org only changes the filling settings for Emacs. For XEmacs, +you should use Kyle E. Jones' `filladapt.el'. To turn this on, put +into `.emacs': `(require 'filladapt)' + + (8) If you do not want the line to be split, customize the variable +`org-M-RET-may-split-line'. + + (9) See `bullet' rule in `org-list-automatic-rules' for more +information. + + +File: org, Node: Drawers, Next: Blocks, Prev: Plain lists, Up: Document Structure + +2.8 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 _drawers_. +Drawers need to be configured with the variable `org-drawers'(1). +Drawers look like this: + + ** This is a headline + Still outside the drawer + :DRAWERNAME: + This is inside the drawer. + :END: + After the drawer. + + Visibility cycling (*note 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 <TAB> there. Org-mode uses the +`PROPERTIES' drawer for storing properties (*note Properties and +Columns::), and you can also arrange for state change notes (*note +Tracking TODO state changes::) and clock times (*note Clocking work +time::) to be stored in a drawer `LOGBOOK'. If you want to store a +quick note in the LOGBOOK drawer, in a similar way to state changes, use + +`C-c C-z' + Add a time-stamped note to the LOGBOOK drawer. + + ---------- Footnotes ---------- + + (1) You can define drawers on a per-file basis with a line like +`#+DRAWERS: HIDDEN PROPERTIES STATE' + + +File: org, Node: Blocks, Next: Footnotes, Prev: Drawers, Up: Document Structure + +2.9 Blocks +========== + +Org-mode uses begin...end blocks for various purposes from including +source code examples (*note Literal examples::) to capturing time +logging information (*note Clocking work time::). These blocks can be +folded and unfolded by pressing TAB in the begin line. You can also +get all blocks folded at startup by configuring the variable +`org-hide-block-startup' or on a per-file basis by using + + #+STARTUP: hideblocks + #+STARTUP: nohideblocks + + +File: org, Node: Footnotes, Next: Orgstruct mode, Prev: Blocks, Up: Document Structure + +2.10 Footnotes +============== + +Org-mode supports the creation of footnotes. In contrast to the +`footnote.el' package, Org-mode's footnotes are designed for work on a +larger document, not only for one-off documents like emails. The basic +syntax is similar to the one used by `footnote.el', i.e. a footnote is +defined in a paragraph that is started by a footnote marker in square +brackets in column 0, no indentation allowed. If you need a paragraph +break inside a footnote, use the LaTeX idiom `\par'. The footnote +reference is simply the marker in square brackets, inside text. For +example: + + The Org homepage[fn:1] now looks a lot better than it used to. + ... + [fn:1] The link is: http://orgmode.org + + Org-mode extends the number-based syntax to _named_ footnotes and +optional inline definition. Using plain numbers as markers (as +`footnote.el' does) is supported for backward compatibility, but not +encouraged because of possible conflicts with LaTeX snippets (*note +Embedded LaTeX::). Here are the valid references: + +`[1]' + A plain numeric footnote marker. Compatible with `footnote.el', + but not recommended because something like `[1]' could easily be + part of a code snippet. + +`[fn:name]' + A named footnote reference, where `name' is a unique label word, + or, for simplicity of automatic creation, a number. + +`[fn:: This is the inline definition of this footnote]' + A LaTeX-like anonymous footnote where the definition is given + directly at the reference point. + +`[fn:name: a definition]' + An inline definition of a footnote, which also specifies a name + for the note. Since Org allows multiple references to the same + note, you can then use `[fn:name]' to create additional references. + + Footnote labels can be created automatically, or you can create +names yourself. This is handled by the variable +`org-footnote-auto-label' and its corresponding `#+STARTUP' keywords. +See the docstring of that variable for details. + +The following command handles footnotes: + +`C-c C-x f' + The footnote action command. + + When the cursor is on a footnote reference, jump to the + definition. When it is at a definition, jump to the (first) + reference. + + Otherwise, create a new footnote. Depending on the variable + `org-footnote-define-inline'(1), the definition will be placed + right into the text as part of the reference, or separately into + the location determined by the variable `org-footnote-section'. + + When this command is called with a prefix argument, a menu of + additional options is offered: + s Sort the footnote definitions by reference sequence. During editing, + Org makes no effort to sort footnote definitions into a particular + sequence. If you want them sorted, use this command, which will + also move entries according to `org-footnote-section'. Automatic + sorting after each insertion/deletion can be configured using the + variable `org-footnote-auto-adjust'. + r Renumber the simple `fn:N' footnotes. Automatic renumbering + after each insertion/deletion can be configured using the variable + `org-footnote-auto-adjust'. + S Short for first `r', then `s' action. + n Normalize the footnotes by collecting all definitions (including + inline definitions) into a special section, and then numbering them + in sequence. The references will then also be numbers. This is + meant to be the final step before finishing a document (e.g. sending + off an email). The exporters do this automatically, and so could + something like `message-send-hook'. + d Delete the footnote at point, and all definitions of and references + to it. + Depending on the variable `org-footnote-auto-adjust'(2), + renumbering and sorting footnotes can be automatic after each + insertion or deletion. + +`C-c C-c' + If the cursor is on a footnote reference, jump to the definition. + If it is a the definition, jump back to the reference. When + called at a footnote location with a prefix argument, offer the + same menu as `C-c C-x f'. + +`C-c C-o or mouse-1/2' + Footnote labels are also links to the corresponding + definition/reference, and you can use the usual commands to follow + these links. + + ---------- Footnotes ---------- + + (1) The corresponding in-buffer setting is: `#+STARTUP: fninline' or +`#+STARTUP: nofninline' + + (2) the corresponding in-buffer options are `fnadjust' and +`nofnadjust'. + + +File: org, Node: Orgstruct mode, Prev: Footnotes, Up: Document Structure + +2.11 The Orgstruct minor mode +============================= + +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. Toggle the mode with `M-x orgstruct-mode', or +turn it on by default, for example in Mail mode, with one of: + + (add-hook 'mail-mode-hook 'turn-on-orgstruct) + (add-hook 'mail-mode-hook 'turn-on-orgstruct++) + + When this mode is active and the cursor is on a line that looks to +Org like a headline or 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 shadows. When you use `orgstruct++-mode', Org will also export +indentation and autofill settings into that mode, and detect item +context after the first line of an item. + + +File: org, Node: Tables, Next: Hyperlinks, Prev: Document Structure, Up: Top + +3 Tables +******** + +Org comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported using the Emacs `calc' package (*note Calc: +(Calc)Top.). + +* Menu: + +* Built-in table editor:: Simple tables +* Column width and alignment:: Overrule the automatic settings +* Column groups:: Grouping to trigger vertical lines +* Orgtbl mode:: The table editor as minor mode +* The spreadsheet:: The table editor has spreadsheet capabilities +* Org-Plot:: Plotting from org tables + + +File: org, Node: Built-in table editor, Next: Column width and alignment, Prev: Tables, Up: Tables + +3.1 The built-in table editor +============================= + +Org makes it easy to format tables in plain ASCII. Any line with `|' +as the first non-whitespace character is considered part of a table. +`|' is also the column separator. A table might look like this: + + | Name | Phone | Age | + |-------+-------+-----| + | Peter | 1234 | 17 | + | Anna | 4321 | 25 | + + A table is re-aligned automatically each time you press <TAB> or +<RET> or `C-c C-c' inside the table. <TAB> also moves to the next +field (<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 `|-' 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 + + |Name|Phone|Age| + |- + +and then press <TAB> to align the table and start filling in fields. +Even faster would be to type `|Name|Phone|Age' followed by `C-c <RET>'. + + When typing text into a field, Org treats <DEL>, <Backspace>, and +all character keys in a special way, so that inserting and deleting +avoids shifting other fields. Also, when typing _immediately after the +cursor was moved into a new field with `<TAB>', `S-<TAB>' or `<RET>'_, +the field is automatically made blank. If this behavior is too +unpredictable for you, configure the variables +`org-enable-table-editor' and `org-table-auto-blank-field'. + +Creation and conversion +....................... + +`C-c | (`org-table-create-or-convert-from-region')' + 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 every line contains a comma, comma-separated + values (CSV) are assumed. If not, lines are split at whitespace + into fields. You can use a prefix argument to force a specific + separator: `C-u' forces CSV, `C-u C-u' forces TAB, and a numeric + argument N indicates that at least N consecutive spaces, or + alternatively a TAB will be the separator. + If there is no active region, this command creates an empty Org + table. But it's easier just to start typing, like + `|Name|Phone|Age <RET> |- <TAB>'. + +Re-aligning and field motion +............................ + +`C-c C-c (`org-table-align')' + Re-align the table without moving the cursor. + +`<TAB> (`org-table-next-field')' + Re-align the table, move to the next field. Creates a new row if + necessary. + +`S-<TAB> (`org-table-previous-field')' + Re-align, move to previous field. + +`<RET> (`org-table-next-row')' + Re-align the table and move down to next row. Creates a new row if + necessary. At the beginning or end of a line, <RET> still does + NEWLINE, so it can be used to split a table. + +`M-a (`org-table-beginning-of-field')' + Move to beginning of the current table field, or on to the + previous field. + +`M-e (`org-table-end-of-field')' + Move to end of the current table field, or on to the next field. + +Column and row editing +...................... + +`M-<left> (`org-table-move-column-left')' +`M-<right> (`org-table-move-column-right')' + Move the current column left/right. + +`M-S-<left> (`org-table-delete-column')' + Kill the current column. + +`M-S-<right> (`org-table-insert-column')' + Insert a new column to the left of the cursor position. + +`M-<up> (`org-table-move-row-up')' +`M-<down> (`org-table-move-row-down')' + Move the current row up/down. + +`M-S-<up> (`org-table-kill-row')' + Kill the current row or horizontal line. + +`M-S-<down> (`org-table-insert-row')' + Insert a new row above the current row. With a prefix argument, + the line is created below the current one. + +`C-c - (`org-table-insert-hline')' + Insert a horizontal line below current row. With a prefix + argument, the line is created above the current line. + +`C-c <RET> (`org-table-hline-and-move')' + Insert a horizontal line below current row, and move the cursor + into the row below that line. + +`C-c ^ (`org-table-sort-lines')' + 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. + +Regions +....... + +`C-c C-x M-w (`org-table-copy-region')' + Copy a rectangular region from a table to a special clipboard. + Point and mark determine edge fields of the rectangle. If there + is no active region, copy just the current field. The process + ignores horizontal separator lines. + +`C-c C-x C-w (`org-table-cut-region')' + 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-c C-x C-y (`org-table-paste-rectangle')' + Paste a rectangular region into a table. The upper left 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. + +`M-<RET> (`org-table-wrap-region')' + Split the current field at the cursor position and move the rest + to the line below. 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 numeric prefix + argument may be used to change the number of desired lines. If + there is no region, but you specify a prefix argument, the current + field is made blank, and the content is appended to the field + above. + +Calculations +............ + +`C-c + (`org-table-sum')' + 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 `C-y'. + +`S-<RET> (`org-table-copy-down')' + 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 + `org-table-copy-increment', integer field values will be + incremented during copy. Integers that are too large will not be + incremented. Also, a `0' prefix argument temporarily disables the + increment. This key is also used by shift-selection and related + modes (*note Conflicts::). + +Miscellaneous +............. + +`C-c ` (`org-table-edit-field')' + Edit the current field in a separate window. This is useful for + fields that are not fully visible (*note Column width and + alignment::). When called with a `C-u' prefix, just make the full + field visible, so that it can be edited in place. + +`M-x org-table-import' + Import a file as a table. The table should be TAB or whitespace + separated. Use, for example, to import a spreadsheet 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. + +`C-c | (`org-table-create-or-convert-from-region')' + Tables can also be imported by pasting tabular text into the Org + buffer, selecting the pasted text with `C-x C-x' and then using the + `C-c |' command (see above under Creation and conversion). + +`M-x org-table-export' + Export the table, by default as a TAB-separated file. Use for data + exchange with, for example, spreadsheet or database programs. The + format used to export the file can be configured in the variable + `org-table-export-default-format'. You may also use properties + `TABLE_EXPORT_FILE' and `TABLE_EXPORT_FORMAT' to specify the file + name and the format for table export in a subtree. Org supports + quite general formats for exported tables. The exporter format is + the same as the format used by Orgtbl radio tables, see *Note + Translator functions::, for a detailed description. + + If you don't like the automatic table editor because it gets in your +way on lines which you would like to start with `|', you can turn it +off with + + (setq org-enable-table-editor nil) + +Then the only table command that still works is `C-c C-c' to do a +manual re-align. + + +File: org, Node: Column width and alignment, Next: Column groups, Prev: Built-in table editor, Up: Tables + +3.2 Column width and alignment +============================== + +The width of columns is automatically determined by the table editor. +And also the alignment of a column is determined automatically from the +fraction of number-like versus non-number fields in the column. + + Sometimes a single field or a few fields need to carry more text, +leading to inconveniently wide columns. Or maybe you want to make a +table with several columns having a fixed width, regardless of content. +To set(1) the width of a column, one field anywhere in the column may +contain just the string `<N>' where `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 this value. + + |---+------------------------------| |---+--------| + | | | | | <6> | + | 1 | one | | 1 | one | + | 2 | two | ----\ | 2 | two | + | 3 | This is a long chunk of text | ----/ | 3 | This=> | + | 4 | four | | 4 | four | + |---+------------------------------| |---+--------| + +Fields that are wider become clipped and end in the string `=>'. Note +that the full text is still in the buffer but is hidden. 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 `C-c `' (that +is `C-c' followed by the backquote). This will open a new window with +the full field. Edit it and finish with `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 +`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: + + #+STARTUP: align + #+STARTUP: noalign + + If you would like to overrule the automatic alignment of number-rich +columns to the right and of string-rich column to the left, you can use +`<r>', `c'(2) or `<l>' in a similar fashion. You may also combine +alignment and field width like this: `<l10>'. + + Lines which only contain these formatting cookies will be removed +automatically when exporting the document. + + ---------- Footnotes ---------- + + (1) This feature does not work on XEmacs. + + (2) Centering does not work inside Emacs, but it does have an effect +when exporting to HTML. + + +File: org, Node: Column groups, Next: Orgtbl mode, Prev: Column width and alignment, Up: Tables + +3.3 Column groups +================= + +When Org 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 `/'. The further fields can either contain +`<' to indicate that this column should start a group, `>' to indicate +the end of a column, or `<>' to make a column a group of its own. +Boundaries between column groups will upon export be marked with +vertical lines. Here is an 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: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1))) + + It is also sufficient to just insert the column group starters after +every vertical line you would like to have: + + | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | + |----+-----+-----+-----+---------+------------| + | / | < | | | < | | + + +File: org, Node: Orgtbl mode, Next: The spreadsheet, Prev: Column groups, Up: Tables + +3.4 The Orgtbl minor mode +========================= + +If you like the intuitive way the Org 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 `M-x orgtbl-mode'. To turn it on by default, for example in +mail mode, use + + (add-hook 'mail-mode-hook 'turn-on-orgtbl) + + Furthermore, with some special setup, it is possible to maintain +tables in arbitrary syntax with Orgtbl mode. For example, it is +possible to construct LaTeX tables with the underlying ease and power of +Orgtbl mode, including spreadsheet capabilities. For details, see +*Note Tables in arbitrary syntax::. + + +File: org, Node: The spreadsheet, Next: Org-Plot, Prev: Orgtbl mode, Up: Tables + +3.5 The spreadsheet +=================== + +The table editor makes use of the Emacs `calc' package to implement +spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to +derive fields from other fields. While fully featured, Org's +implementation is not identical to other spreadsheets. For example, +Org knows the concept of a _column formula_ that will be applied to all +non-header fields in a column without having to copy the formula to +each relevant field. There is also a formula debugger, and a formula +editor with features for highlighting fields in the table corresponding +to the references at the point in the formula, moving these references +by arrow keys + +* 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 + + +File: org, Node: References, Next: Formula syntax for Calc, Prev: The spreadsheet, Up: The spreadsheet + +3.5.1 References +---------------- + +To compute fields in the table from other fields, formulas must +reference other fields or ranges. In Org, fields can be referenced by +name, by absolute coordinates, and by relative coordinates. To find +out what the coordinates of a field are, press `C-c ?' in that field, +or press `C-c }' to toggle the display of a grid. + +Field references +................ + +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 `B3', meaning the 2nd field in the 3rd row. + +Org also uses another, more general operator that looks like this: + @ROW$COLUMN + +Column references can be absolute like `1', `2',...`N', or relative to +the current column like `+1' or `-2'. + + The row specification only counts data lines and ignores horizontal +separator lines (hlines). You can use absolute row numbers `1'...`N', +and row numbers relative to the current row like `+3' or `-1'. Or +specify the row relative to one of the hlines: `I' refers to the first +hline(1), `II' to the second, etc. `-I' refers to the first such line +above the current line, `+I' to the first such line below the current +line. You can also write `III+2' which is the second data line after +the third hline in the table. + + `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's references with _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's +references with _signed_ numbers are floating references because the +same reference operator can reference different fields depending on the +field being calculated by the formula. + + As a special case, references like `$LR5' and `$LR12' can be used to +refer in a stable way to the 5th and 12th field in the last row of the +table. + + Here are a few examples: + + @2$3 2nd row, 3rd column + C2 same as previous + $5 column 5 in the current row + E& same as previous + @2 current column, row 2 + @-1$-3 the field one row up, three columns to the left + @-I$2 field just under hline above current row, column 2 + +Range references +................ + +You may reference a rectangular range of fields by specifying two field +references connected by two dots `..'. If both fields are in the +current row, you may simply use `$2..$7', but if at least one field is +in a different row, you need to use the general `@row$column' format at +least for the first field (i.e the reference must start with `@' in +order to be interpreted correctly). Examples: + + $1..$3 First three fields in the current row. + $P..$Q Range, using column names (see under Advanced) + @2$1..@4$3 6 fields between these two fields. + A2..C4 Same as above. + @-1$-2..@-1 3 numbers from the column to the left, 2 up to current row + +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 `E' +mode switch below). If there are no non-empty fields, `[0]' is +returned to avoid syntax errors in formulas. + +Field coordinates in formulas +............................. + +For Calc formulas and Lisp formulas `@#' and `$#' can be used to get +the row or column number of the field where the formula result goes. +The traditional Lisp formula equivalents are `org-table-current-dline' +and `org-table-current-column'. Examples: + + if(@# % 2, $#, string("")) column number on odd lines only + $3 = remote(FOO, @@#$2) copy column 2 from table FOO into + column 3 of the current table + +For the second example, table FOO must have at least as many rows as +the current table. Inefficient(2) for large number of rows. + +Named references +................ + +`$name' is interpreted as the name of a column, parameter or constant. +Constants are defined globally through the variable +`org-table-formula-constants', and locally (for the file) through a +line like + + #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 + +Also properties (*note Properties and Columns::) can be used as +constants in table formulas: for a property `:Xyz:' use the name +`$PROP_Xyz', and the property will be searched in the current outline +entry and in the hierarchy above it. If you have the `constants.el' +package, it will also be used to resolve constants, including natural +constants like `$h' for Planck's constant, and units like `$km' for +kilometers(3). Column names and parameters can be specified in special +table lines. These are described below, see *Note Advanced features::. +All names must start with a letter, and further consist of letters and +numbers. + +Remote references +................. + +You may also reference constants, fields and ranges from a different +table, either in the current file or even in a different file. The +syntax is + + remote(NAME-OR-ID,REF) + +where NAME can be the name of a table in the current file as set by a +`#+TBLNAME: NAME' line before the table. It can also be the ID of an +entry, even in a different file, and the reference then refers to the +first table in that entry. REF is an absolute field or range reference +as described above for example `@3$3' or `$somename', valid in the +referenced table. + + ---------- Footnotes ---------- + + (1) Note that only hlines are counted that _separate_ table lines. +If the table starts with a hline above the header, it does not count. + + (2) The computation time scales as O(N^2) because table FOO is +parsed for each field to be copied. + + (3) `constants.el' can supply the values of constants in two +different unit systems, `SI' and `cgs'. Which one is used depends on +the value of the variable `constants-unit-system'. You can use the +`#+STARTUP' options `constSI' and `constcgs' to set this value for the +current buffer. + + +File: org, Node: Formula syntax for Calc, Next: Formula syntax for Lisp, Prev: References, Up: The spreadsheet + +3.5.2 Formula syntax for Calc +----------------------------- + +A formula can be any algebraic expression understood by the Emacs +`Calc' package. Note that `calc' has the non-standard convention that +`/' has lower precedence than `*', so that `a/b*c' is interpreted as +`a/(b*c)'. Before evaluation by `calc-eval' (*note calc-eval: +(Calc)Calling Calc from Your Programs.), variable substitution takes +place according to the rules described above. The range vectors can be +directly fed into the Calc vector functions like `vmean' and `vsum'. + + 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 uses the standard Calc modes (precision 12, +angular units degrees, fraction and symbolic modes off). The display +format, however, has been changed to `(float 8)' to keep tables +compact. The default settings can be configured using the variable +`org-calc-default-modes'. + + p20 set the internal Calc calculation precision to 20 digits + n3 s3 e2 f4 Normal, scientific, engineering, or fixed + format of the result of Calc passed back to Org. + Calc formatting is unlimited in precision as + long as the Calc calculation precision is greater. + D R angle modes: degrees, radians + F S fraction and symbolic modes + N interpret all fields as numbers, use 0 for non-numbers + T force text interpretation + E keep empty fields in ranges + L literal + +Unless you use large integer numbers or high-precision-calculation and +-display for floating point numbers you may alternatively provide a +`printf' format specifier to reformat the Calc result after it has been +passed back to Org instead of letting Calc already do the formatting(1). +A few examples: + + $1+$2 Sum of first and second field + $1+$2;%.2f Same, format result to two decimals + exp($2)+exp($1) Math functions can be used + $0;%.1f Reformat current cell to 1 decimal + ($3-32)*5/9 Degrees F -> C conversion + $c/$1/$cm Hz -> cm conversion, using `constants.el' + tan($1);Dp3s1 Compute in degrees, precision 3, display SCI 1 + sin($1);Dp3%.1e Same, but use printf specifier for display + vmean($2..$7) Compute column range mean, using vector function + vmean($2..$7);EN Same, but treat empty fields as 0 + taylor($3,x=7,2) Taylor series of $3, at x=7, second degree + + Calc also contains a complete set of logical operations. For example + + if($1<20,teen,string("")) "teen" if age $1 less than 20, else empty + + ---------- Footnotes ---------- + + (1) The `printf' reformatting is limited in precision because the +value passed to it is converted into an `integer' or `double'. The +`integer' is limited in size by truncating the signed value to 32 bits. +The `double' is limited in precision to 64 bits overall which leaves +approximately 16 significant decimal digits. + + +File: org, Node: Formula syntax for Lisp, Next: Field formulas, Prev: Formula syntax for Calc, Up: The spreadsheet + +3.5.3 Emacs Lisp forms as formulas +---------------------------------- + +It is also possible to write a formula in Emacs Lisp; this can be +useful for string manipulation and control structures, if 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 `calc' formulas, you can specify modes and a printf format +after a semicolon. With Emacs Lisp forms, you need to be conscious +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 `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 `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, enclose the reference operator itself in +double-quotes, like `"$3"'. Ranges are inserted as space-separated +fields, so you can +embed them in list or vector syntax. Here are a +few examples--note how the `N' mode is used when we do computations in +Lisp: + + Swap the first two characters of the content of column 1 + '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) + Add columns 1 and 2, equivalent to Calc's `$1+$2' + '(+ $1 $2);N + Compute the sum of columns 1-4, like Calc's `vsum($1..$4)' + '(apply '+ '($1..$4));N + + +File: org, Node: Field formulas, Next: Column formulas, Prev: Formula syntax for Lisp, Up: The spreadsheet + +3.5.4 Field formulas +-------------------- + +To assign a formula to a particular field, type it directly into the +field, preceded by `:=', for example `:=$1+$2'. When you press <TAB> +or <RET> or `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 `#+TBLFM:' +directly below the table. If you type the equation in the 4th field of +the 3rd data line in the table, the formula will look like +`@3$4=$1+$2'. When inserting/deleting/swapping column and rows with +the appropriate commands, absolute references (but not relative ones) +in stored formulas are modified in order to still reference the same +field. Of course this is not true if you edit the table structure with +normal editing commands--then you must fix the equations yourself. The +left-hand side of a formula may also be a named field (*note Advanced +features::), or a last-row reference like `$LR3'. + + Instead of typing an equation into the field, you may also use the +following command + +`C-u C-c = (`org-table-eval-formula')' + Install a new formula for the current field. The command prompts + for a formula with default taken from the `#+TBLFM:' line, applies + it to the current field, and stores it. + + +File: org, Node: Column formulas, Next: Editing and debugging formulas, Prev: Field formulas, Up: The spreadsheet + +3.5.5 Column formulas +--------------------- + +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 allows you 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 _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 `=$1+$2'. When you press +<TAB> or <RET> or `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 `=', the previously stored formula for this column is used. For +each column, Org will only remember the most recently used formula. In +the `#+TBLFM:' line, column formulas will look like `$4=$1+$2'. The +left-hand side of a column formula cannot currently be the name of +column, it must be the numeric column reference. + + Instead of typing an equation into the field, you may also use the +following command: + +`C-c = (`org-table-eval-formula')' + 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 `#+TBLFM' line, applies it to + the current field and stores it. With a numeric prefix + argument(e.g. `C-5 C-c =') the command will apply it to that many + consecutive fields in the current column. + + +File: org, Node: Editing and debugging formulas, Next: Updating the table, Prev: Column formulas, Up: The spreadsheet + +3.5.6 Editing and debugging formulas +------------------------------------ + +You can edit individual formulas in the minibuffer or directly in the +field. Org can also prepare a special buffer with all active formulas +of a table. When offering a formula for editing, Org converts +references to the standard format (like `B3' or `D&') if possible. If +you prefer to only work with the internal format (like `@3$2' or `$4'), +configure the variable `org-table-use-standard-references'. + +`C-c = or C-u C-c = (`org-table-eval-formula')' + Edit the formula associated with the current column/field in the + minibuffer. See *Note Column formulas::, and *Note Field + formulas::. + +`C-u C-u C-c = (`org-table-eval-formula')' + 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 `C-c ?'. + +`C-c ? (`org-table-field-info')' + While editing a formula in a table field, highlight the field(s) + referenced by the reference at the cursor position in the formula. + +`C-c }' + Toggle the display of row and column numbers for a table, using + overlays (`org-table-toggle-coordinate-overlays'). These are + updated each time the table is aligned; you can force it with `C-c + C-c'. + +`C-c {' + Toggle the formula debugger on and off + (`org-table-toggle-formula-debugger'). See below. + +`C-c ' (`org-table-edit-formulas')' + 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 will automatically + highlight any field or range reference at the cursor position. + You may edit, remove and add formulas, and use the following + commands: + `C-c C-c or C-x C-s (`org-table-fedit-finish')' + Exit the formula editor and store the modified formulas. + With `C-u' prefix, also apply the new formulas to the entire + table. + + `C-c C-q (`org-table-fedit-abort')' + Exit the formula editor without installing changes. + + `C-c C-r (`org-table-fedit-toggle-ref-type')' + Toggle all references in the formula editor between standard + (like `B3') and internal (like `@3$2'). + + `<TAB> (`org-table-fedit-lisp-indent')' + 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 <TAB> collapses the formula back + again. In the open formula, <TAB> re-indents just like in + Emacs Lisp mode. + + `M-<TAB> (`lisp-complete-symbol')' + Complete Lisp symbols, just like in Emacs Lisp mode. + + `S-<up>/<down>/<left>/<right>' + Shift the reference at point. For example, if the reference + is `B3' and you press `S-<right>', it will become `C3'. This + also works for relative references and for hline references. + + `M-S-<up> (`org-table-fedit-line-up')' + `M-S-<down> (`org-table-fedit-line-down')' + Move the test line for column formulas in the Org buffer up + and down. + + `M-<up> (`org-table-fedit-scroll-down')' + `M-<down> (`org-table-fedit-scroll-up')' + Scroll the window displaying the table. + + `C-c }' + Turn the coordinate grid in the table on and off. + + Making a table field blank does not remove the formula associated +with the field, because that is stored in a different line (the +`#+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 `#+TBLFM' line. + + You may edit the `#+TBLFM' directly and re-apply the changed +equations with `C-c C-c' in that line or with the normal recalculation +commands in the table. + +Debugging formulas +.................. + +When the evaluation of a formula leads to an error, the field content +becomes the string `#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 `Tbl' menu and repeat the calculation, +for example by pressing `C-u C-u C-c = <RET>' in a field. Detailed +information will be displayed. + + +File: org, Node: Updating the table, Next: Advanced features, Prev: Editing and debugging formulas, Up: The spreadsheet + +3.5.7 Updating the table +------------------------ + +Recalculation of a table is normally not automatic, but needs to be +triggered by a command. See *Note Advanced features::, for a way to +make recalculation at least semi-automatic. + + In order to recalculate a line of a table or the entire table, use +the following commands: + +`C-c * (`org-table-recalculate')' + Recalculate the current row by first applying the stored column + formulas from left to right, and all field formulas in the current + row. + +`C-u C-c *' +`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-u C-u C-c * or C-u C-u C-c C-c (`org-table-iterate')' + 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 later in the calculation sequence. + +`M-x org-table-recalculate-buffer-tables' + Recompute all tables in the current buffer. + +`M-x org-table-iterate-buffer-tables' + Iterate all tables in the current buffer, in order to converge + table-to-table dependencies. + + +File: org, Node: Advanced features, Prev: Updating the table, Up: The spreadsheet + +3.5.8 Advanced features +----------------------- + +If you want the recalculation of fields to happen automatically, or if +you want to be able to assign names to fields and columns, you need to +reserve the first column of the table for special marking characters. +`C-# (`org-table-rotate-recalc-marks')' + Rotate the calculation mark in first column through the states ` ', + `#', `*', `!', `$'. When there is an active region, change all + marks in the region. + + Here is an example of a table that collects exam results of students +and makes use of these features: + + |---+---------+--------+--------+--------+-------+------| + | | 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 | + | # | 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 + +Important: please note that for these special tables, recalculating the +table with `C-u C-c *' will only affect rows that are marked `#' or +`*', and fields that have a formula assigned to the field itself. The +column formulas are not applied in rows with empty first field. + + The marking characters have the following meaning: +`!' + The fields in this line define names for the columns, so that you + may refer to a column as `$Tot' instead of `$6'. + +`^' + This row defines names for the fields _above_ the row. With such + a definition, any formula in the table may use `$m1' to refer to + the value `10'. Also, if you assign a formula to a names field, it + will be stored as `$name=...'. + +`_' + Similar to `^', but defines names for the fields in the row + _below_. + +`$' + Fields in this row can define _parameters_ for formulas. For + example, if a field in a `$' row contains `max=50', then formulas + in this table can refer to the value 50 using `$max'. Parameters + work exactly like constants, only that they can be defined on a + per-table basis. + +`#' + Fields in this row are automatically recalculated when pressing + <TAB> or <RET> or `S-<TAB>' in this row. Also, this row is + selected for a global recalculation with `C-u C-c *'. Unmarked + lines will be left alone by this command. + +`*' + Selects this line for global recalculation with `C-u C-c *', but + not for automatic recalculation. Use this when automatic + recalculation slows down editing too much. + +`' + Unmarked lines are exempt from recalculation with `C-u C-c *'. + All lines that should be recalculated should be marked with `#' or + `*'. + +`/' + Do not export this line. Useful for lines that contain the + narrowing `<N>' markers or column group markers. + + Finally, just to whet your appetite for what can be done with the +fantastic `calc.el' package, here is a table that computes the Taylor +series of degree `n' at location `x' for a couple of functions. + + |---+-------------+---+-----+--------------------------------------| + | | 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 + + +File: org, Node: Org-Plot, Prev: The spreadsheet, Up: Tables + +3.6 Org-Plot +============ + +Org-Plot can produce 2D and 3D graphs of information stored in org +tables using `Gnuplot' `http://www.gnuplot.info/' and `gnuplot-mode' +`http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html'. To see +this in action, ensure that you have both Gnuplot and Gnuplot mode +installed on your system, then call `org-plot/gnuplot' on the following +table. + + #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]" + | Sede | Max cites | H-index | + |-----------+-----------+---------| + | Chile | 257.72 | 21.39 | + | Leeds | 165.77 | 19.68 | + | Sao Paolo | 71.00 | 11.50 | + | Stockholm | 134.19 | 14.33 | + | Morelia | 257.56 | 17.67 | + + Notice that Org Plot is smart enough to apply the table's headers as +labels. Further control over the labels, type, content, and appearance +of plots can be exercised through the `#+PLOT:' lines preceding a +table. See below for a complete list of Org-plot options. For more +information and examples see the Org-plot tutorial at +`http://orgmode.org/worg/org-tutorials/org-plot.php'. + +Plot Options +............ + +`set' + Specify any `gnuplot' option to be set when graphing. + +`title' + Specify the title of the plot. + +`ind' + Specify which column of the table to use as the `x' axis. + +`deps' + Specify the columns to graph as a Lisp style list, surrounded by + parentheses and separated by spaces for example `dep:(3 4)' to + graph the third and fourth columns (defaults to graphing all other + columns aside from the `ind' column). + +`type' + Specify whether the plot will be `2d', `3d', or `grid'. + +`with' + Specify a `with' option to be inserted for every col being plotted + (e.g. `lines', `points', `boxes', `impulses', etc...). Defaults + to `lines'. + +`file' + If you want to plot to a file, specify + `"PATH/TO/DESIRED/OUTPUT-FILE"'. + +`labels' + List of labels to be used for the `deps' (defaults to the column + headers if they exist). + +`line' + Specify an entire line to be inserted in the Gnuplot script. + +`map' + When plotting `3d' or `grid' types, set this to `t' to graph a + flat mapping rather than a `3d' slope. + +`timefmt' + Specify format of Org-mode timestamps as they will be parsed by + Gnuplot. Defaults to `%Y-%m-%d-%H:%M:%S'. + +`script' + If you want total control, you can specify a script file (place + the file name between double-quotes) which will be used to plot. + Before plotting, every instance of `$datafile' in the specified + script will be replaced with the path to the generated data file. + Note: even if you set this option, you may still want to specify + the plot type, as that can impact the content of the data file. + + +File: org, Node: Hyperlinks, Next: TODO Items, Prev: Tables, Up: Top + +4 Hyperlinks +************ + +Like HTML, Org provides links inside a file, external links to other +files, Usenet articles, emails, and much more. + +* Menu: + +* Link format:: How links in Org 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:: 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 + + +File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks + +4.1 Link format +=============== + +Org will recognize plain URL-like links and activate them as clickable +links. The general link format, however, looks like this: + + [[link][description]] or alternatively [[link]] + +Once a link in the buffer is complete (all brackets present), Org will +change the display so that `description' is displayed instead of +`[[link][description]]' and `link' is displayed instead of `[[link]]'. +Links will be highlighted in the face `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 `link' part (if there is no +description) or the `description' part. To edit also the invisible +`link' part, use `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 <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 `Org->Hyperlinks->Literal +links'. + + +File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks + +4.2 Internal links +================== + +If the link does not look like a URL, it is considered to be internal +in the current file. The most important case is a link like +`[[#my-custom-id]]' which will link to the entry with the `CUSTOM_ID' +property `my-custom-id'. Such custom IDs are very good for HTML export +(*note HTML export::) where they produce pretty section links. You are +responsible yourself to make sure these custom IDs are unique in a file. + + Links such as `[[My Target]]' or `[[My Target][Find my target]]' +lead to a text search in the current file. + + The link can be followed with `C-c C-o' when the cursor is on the +link, or with a mouse click (*note Handling links::). Links to custom +IDs will point to the corresponding headline. The preferred match for +a text 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 + + # <<My Target>> + +In HTML export (*note HTML export::), such targets will become named +anchors for direct access through `http' links(1). + + If no dedicated target exists, Org will search for a headline that +is exactly the link text but may also include a TODO keyword and +tags(2). In non-Org files, the search will look for the words in the +link text. In the above example the search would be for `my target'. + + Following a link pushes a mark onto Org's own mark ring. You can +return to the previous position with `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 + + ---------- Footnotes ---------- + + (1) Note that text before the first headline is usually not +exported, so the first such target should be after the first headline, +or in the line directly before the first headline. + + (2) 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 `M-<TAB>'. All headlines in the current buffer will +be offered as completions. + + +File: org, Node: Radio targets, Prev: Internal links, Up: Internal links + +4.2.1 Radio targets +------------------- + +Org 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 `<<<My +Target>>>' causes each occurrence of `my target' in normal text to +become activated as a link. The Org file is scanned automatically for +radio targets only when the file is first loaded into Emacs. To update +the target list during editing, press `C-c C-c' with the cursor on or +at a target. + + +File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks + +4.3 External links +================== + +Org supports links to files, websites, Usenet and email messages, BBDB +database entries and links to both IRC conversations and their logs. +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. + + http://www.astro.uva.nl/~dominik on the web + doi:10.1000/182 DOI for an electronic resource + file:/home/dominik/images/jupiter.jpg file, absolute path + /home/dominik/images/jupiter.jpg same as above + file:papers/last.pdf file, relative path + ./papers/last.pdf same as above + file:/myself@some.where:papers/last.pdf file, path on remote machine + /myself@some.where:papers/last.pdf same as above + file:sometextfile::NNN file with line number to jump to + file:projects.org another Org file + file:projects.org::some words text search in Org file + file:projects.org::*task title heading search in Org file + docview:papers/last.pdf::NNN open file in doc-view mode at page NNN + id:B7423F4D-2E8A-471B-8810-C40F074717E9 Link to heading by ID + news:comp.emacs Usenet link + mailto:adent@galaxy.net Mail link + vm:folder VM folder link + vm:folder#id VM message link + vm://myself@some.where.org/folder#id VM on remote machine + wl:folder WANDERLUST folder link + wl:folder#id WANDERLUST message link + mhe:folder MH-E folder link + mhe:folder#id MH-E message link + rmail:folder RMAIL folder link + rmail:folder#id RMAIL message link + gnus:group Gnus group link + gnus:group#id Gnus article link + bbdb:R.*Stallman BBDB link (with regexp) + irc:/irc.com/#emacs/bob IRC link + info:org:External%20links Info node link (with encoded space) + shell:ls *.org A shell command + elisp:org-agenda Interactive Elisp command + elisp:(find-file-other-frame "Elisp.org") Elisp form to evaluate + + A link should be enclosed in double brackets and may contain a +descriptive text to be displayed instead of the URL (*note Link +format::), for example: + + [[http://www.gnu.org/software/emacs/][GNU Emacs]] + +If the description is a file name or URL that points to an image, HTML +export (*note 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. + + Org also finds external links in the normal text and activates them +as links. If spaces must be part of the link (for example in +`bbdb:Richard Stallman'), or if you need to remove ambiguities about +the end of the link, enclose them in square brackets. + + +File: org, Node: Handling links, Next: Using links outside Org, Prev: External links, Up: Hyperlinks + +4.4 Handling links +================== + +Org provides methods to create a link in the correct syntax, to insert +it into an Org file, and to follow the link. + +`C-c l (`org-store-link')' + Store a link to the current location. This is a _global_ command + (you must create the key binding yourself) which can be used in + any buffer to create a link. The link will be stored for later + insertion into an Org buffer (see below). What kind of link will + be created depends on the current buffer: + + Org-mode buffers + For Org files, if there is a `<<target>>' at the cursor, the link + points to the target. Otherwise it points to the current + headline, which will also be the description. + + If the headline has a `CUSTOM_ID' property, a link to this custom + ID will be stored. In addition or alternatively (depending on the + value of `org-link-to-org-use-id'), a globally unique `ID' + property will be created and/or used to construct a link. So + using this command in Org buffers will potentially create two + links: a human-readable from the custom ID, and one that is + globally unique and works even if the entry is moved from file to + file. Later, when inserting the link, you need to decide which one + to use. + + Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus + Pretty much all Emacs mail clients are supported. The link will + point to the current article, or, in some GNUS buffers, to the + group. The description is constructed from the author and the + subject. + + Web browsers: W3 and W3M + Here the link will be the current URL, with the page title as + description. + + Contacts: BBDB + Links created in a BBDB buffer will point to the current entry. + + Chat: IRC + For IRC links, if you set the variable `org-irc-link-to-logs' to + `t', a `file:/' style link to the relevant point in the logs for + the current conversation is created. Otherwise an `irc:/' style + link to the user/channel/server under the point will be stored. + + Other files + For any other files, the link will point to the file, with a + search string (*note 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 *Note Custom + searches::. The key binding `C-c l' is only a suggestion--see + *Note Installation::. + + Agenda view + When the cursor is in an agenda view, the created link points to + the entry referenced by the current line. + +`C-c C-l (`org-insert-link')' + Insert a link(1). 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. The link will be inserted into the buffer(2), along with a + descriptive text. If some text was selected when this command is + called, the selected text becomes the default description. + + Inserting stored links + All links stored during the current session are part of the + history for this prompt, so you can access them with <up> and + <down> (or `M-p/n'). + + Completion support + Completion with <TAB> will help you to insert valid link prefixes + like `http:' or `ftp:', including the prefixes defined through + link abbreviations (*note Link abbreviations::). If you press + <RET> after inserting only the PREFIX, Org will offer specific + completion support for some link types(3) For example, if you + type `file <RET>', file name completion (alternative access: `C-u + C-c C-l', see below) will be offered, and after `bbdb <RET>' you + can complete contact names. + +`C-u C-c C-l' + When `C-c C-l' is called with a `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 sub-directory of it, or + if the path is written relative to the current directory using + `../'. Otherwise an absolute path is used, if possible with `~/' + for your home directory. You can force an absolute path with two + `C-u' prefixes. + +`C-c C-l (with cursor on existing link)' + When the cursor is on an existing link, `C-c C-l' allows you to + edit the link and description parts of the link. + +`C-c C-o (`org-open-at-point')' + Open link at point. This will launch a web browser for URLs (using + `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 command 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 timestamp, it compiles the agenda for that date. + Furthermore, it will visit text and remote files in `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 `org-file-apps'. If you want to override the default + application and visit the file with Emacs, use a `C-u' prefix. If + you want to avoid opening in Emacs, use a `C-u C-u' prefix. + If the cursor is on a headline, but not on a link, offer all links + in the headline and entry text. + +`<RET>' + When `org-return-follows-link' is set, `<RET>' will also follow + the link at point. + +`mouse-2' +`mouse-1' + On links, `mouse-2' will open the link just as `C-c C-o' would. + Under Emacs 22 and later, `mouse-1' will also follow a link. + +`mouse-3' + Like `mouse-2', but force file links to be opened with Emacs, and + internal links to be displayed in another window(4). + +`C-c C-x C-v (`org-toggle-inline-images')' + Toggle the inline display of linked images. Normally this will + only inline images that have no description part in the link, i.e. + images that will also be inlined during export. When called with + a prefix argument, also display images that do have a link + description. You can ask for inline images to be displayed at + startup by configuring the variable + `org-startup-with-inline-images'(5). + +`C-c % (`org-mark-ring-push')' + Push the current position onto the mark ring, to be able to return + easily. Commands following an internal link do this automatically. + +`C-c & (`org-mark-ring-goto')' + Jump back to a recorded position. A position is recorded by the + commands following internal links, and by `C-c %'. Using this + command several times in direct succession moves through a ring of + previously recorded positions. + +`C-c C-x C-n (`org-next-link')' +`C-c C-x C-p (`org-previous-link')' + 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 `C-n' and `C-p' + (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))) + + ---------- Footnotes ---------- + + (1) Note that you don't have to use this command to insert a link. +Links in Org 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. + + (2) 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 `C-u' prefix argument to `C-c C-l', or configure the option +`org-keep-stored-link-after-insertion'. + + (3) This works by calling a special function +`org-PREFIX-complete-link'. + + (4) See the variable `org-display-internal-link-with-indirect-buffer' + + (5) with corresponding `#+STARTUP' keywords `inlineimages' and +`inlineimages' + + +File: org, Node: Using links outside Org, Next: Link abbreviations, Prev: Handling links, Up: Hyperlinks + +4.5 Using links outside Org +=========================== + +You can insert and follow links that have Org syntax not only in Org, +but in any Emacs buffer. For this, you should create two global +commands, like this (please select suitable global keys yourself): + + (global-set-key "\C-c L" 'org-insert-link-global) + (global-set-key "\C-c o" 'org-open-at-point-global) + + +File: org, Node: Link abbreviations, Next: Search options, Prev: Using links outside Org, Up: Hyperlinks + +4.6 Link abbreviations +====================== + +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 + + [[linkword:tag][description]] + +where the tag is optional. The linkword must be a word, starting with +a letter, followed by letters, numbers, `-', and `_'. Abbreviations +are resolved according to the information in the variable +`org-link-abbrev-alist' that relates the linkwords to replacement text. +Here is an example: + + (setq org-link-abbrev-alist + '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") + ("google" . "http://www.google.com/search?q=") + ("gmap" . "http://maps.google.com/maps?q=%s") + ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1") + ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST"))) + + If the replacement text contains the string `%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 +`[[bugzilla:129]]', search the web for `OrgMode' with +`[[google:OrgMode]]', show the map location of the Free Software +Foundation `[[gmap:51 Franklin Street, Boston]]' or of Carsten office +`[[omap:Science Park 904, Amsterdam, The Netherlands]]' and find out +what the Org author is doing besides Emacs hacking with +`[[ads:Dominik,C]]'. + + If you need special abbreviations just for a single Org buffer, you +can define them in the file with + + #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id= + #+LINK: google http://www.google.com/search?q=%s + +In-buffer completion (*note Completion::) can be used after `[' to +complete link abbreviations. You may also define a function +`org-PREFIX-complete-link' that implements special (e.g. completion) +support for inserting such a link with `C-c C-l'. Such a function +should not accept any arguments, and return the full link with prefix. + + +File: org, Node: Search options, Next: Custom searches, Prev: Link abbreviations, Up: Hyperlinks + +4.7 Search options in file links +================================ + +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(1) colon. For example, +when the command `C-c l' creates a link (*note 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 +`C-c C-o'. + + Here is the syntax of the different ways to attach a search to a file +link, together with an explanation: + + [[file:~/code/main.c::255]] + [[file:~/xx.org::My Target]] + [[file:~/xx.org::*My Target]] + [[file:~/xx.org::#my-custom-id]] + [[file:~/xx.org::/regexp/]] + +`255' + Jump to line 255. + +`My Target' + Search for a link target `<<My Target>>', or do a text search for + `my target', similar to the search in internal links, see *Note + Internal links::. In HTML export (*note HTML export::), such a + file link will become an HTML reference to the corresponding named + anchor in the linked file. + +`*My Target' + In an Org file, restrict search to headlines. + +`#my-custom-id' + Link to a heading with a `CUSTOM_ID' property + +`/regexp/' + Do a regular expression search for `regexp'. This uses the Emacs + command `occur' to list all matches in a separate window. If the + target file is in Org-mode, `org-occur' is used to create a sparse + tree with the matches. + + As a degenerate case, a file link with an empty file name can be used +to search the current file. For example, `[[file:::find me]]' does a +search for `find me' in the current file, just as `[[find me]]' would. + + ---------- Footnotes ---------- + + (1) For backward compatibility, line numbers can also follow a +single colon. + + +File: org, Node: Custom searches, Prev: Search options, Up: Hyperlinks + +4.8 Custom Searches +=================== + +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 +`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 `add-hook', these functions +need to be added to the hook variables +`org-create-file-search-functions' and +`org-execute-file-search-functions'. See the docstring for these +variables for more information. Org actually uses this mechanism for +BibTeX database files, and you can use the corresponding code as an +implementation example. See the file `org-bibtex.el'. + + +File: org, Node: TODO Items, Next: Tags, Prev: Hyperlinks, Up: Top + +5 TODO items +************ + +Org-mode does not maintain TODO lists as separate documents(1). +Instead, TODO items are an integral part of the notes file, because +TODO items usually come up while taking notes! With Org mode, simply +mark any entry in a tree as being a TODO item. In this way, +information is not duplicated, and the entire context from which the +TODO item emerged is always present. + + Of course, this technique for managing TODO items scatters them +throughout your notes file. Org-mode compensates for this by providing +methods to give you an overview of all the things that you have to do. + +* Menu: + +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* Progress logging:: Dates and notes for progress +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists + + ---------- Footnotes ---------- + + (1) Of course, you can make a document that contains only long lists +of TODO items, but this is not required. + + +File: org, Node: TODO basics, Next: TODO extensions, Prev: TODO Items, Up: TODO Items + +5.1 Basic TODO functionality +============================ + +Any headline becomes a TODO item when it starts with the word `TODO', +for example: + + *** TODO Write letter to Sam Fortune + +The most important commands to work with TODO entries are: + +`C-c C-t (`org-todo')' + Rotate the TODO state of the current item among + + ,-> (unmarked) -> TODO -> DONE --. + '--------------------------------' + + The same rotation can also be done "remotely" from the timeline and + agenda buffers with the `t' command key (*note Agenda commands::). + +`C-u C-c C-t' + Select a specific keyword using completion or (if it has been set + up) the fast selection interface. For the latter, you need to + assign keys to TODO states, see *Note Per-file keywords::, and + *Note Setting tags::, for more information. + +`S-<right> / S-<left>' + Select the following/preceding TODO state, similar to cycling. + Useful mostly if more than two TODO states are possible (*note + TODO extensions::). See also *Note Conflicts::, for a discussion + of the interaction with `shift-selection-mode'. See also the + variable `org-treat-S-cursor-todo-selection-as-state-change'. + +`C-c / t (`org-show-todo-key')' + View TODO items in a _sparse tree_ (*note Sparse trees::). Folds + the entire buffer, but shows all TODO items (with not-DONE state) + and the headings hierarchy above them. With a prefix argument (or + by using `C-c / T'), search for a specific TODO. You will be + prompted for the keyword, and you can also give a list of keywords + like `KWD1|KWD2|...' to list entries that match any one of these + keywords. With numeric prefix argument N, show the tree for the + Nth keyword in the variable `org-todo-keywords'. With two prefix + arguments, find all TODO states, both un-done and done. + +`C-c a t (`org-todo-list')' + Show the global TODO list. Collects the TODO items (with not-DONE + states) from all agenda files (*note Agenda Views::) into a single + buffer. The new buffer will be in `agenda-mode', which provides + commands to examine and manipulate the TODO entries from the new + buffer (*note Agenda commands::). *Note Global TODO list::, for + more information. + +`S-M-<RET> (`org-insert-todo-heading')' + Insert a new TODO entry below the current one. + +Changing a TODO state can also trigger tag changes. See the docstring +of the option `org-todo-state-tags-triggers' for details. + + +File: org, Node: TODO extensions, Next: Progress logging, Prev: TODO basics, Up: TODO Items + +5.2 Extended use of TODO keywords +================================= + +By default, marked TODO entries have one of only two states: TODO and +DONE. Org-mode allows you to classify TODO items in more complex ways +with _TODO keywords_ (stored in `org-todo-keywords'). With special +setup, the TODO keyword system can work differently in different files. + + Note that tags are another way to classify headlines in general and +TODO items in particular (*note Tags::). + +* Menu: + +* Workflow states:: From TODO to DONE in steps +* TODO types:: I do this, Fred does the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Fast access to TODO states:: Single letter selection of a state +* Per-file keywords:: Different files, different requirements +* Faces for TODO keywords:: Highlighting states +* TODO dependencies:: When one task needs to wait for others + + +File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, Up: TODO extensions + +5.2.1 TODO keywords as workflow states +-------------------------------------- + +You can use TODO keywords to indicate different _sequential_ states in +the process of working on an item, for example(1): + + (setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) + + The vertical bar separates the TODO keywords (states that _need +action_) from the DONE states (which need _no further action_). If you +don't provide the separator bar, the last state is used as the DONE +state. With this setup, the command `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 numeric prefix argument to quickly select a specific +state. For example `C-3 C-c C-t' will change the state immediately to +VERIFY. Or you can use `S-<left>' to go backward through the sequence. +If you define many keywords, you can use in-buffer completion (*note +Completion::) or even a special one-key selection scheme (*note Fast +access to TODO states::) to insert these words into the buffer. +Changing a TODO state can be logged with a timestamp, see *Note +Tracking TODO state changes::, for more information. + + ---------- Footnotes ---------- + + (1) Changing this variable only becomes effective after restarting +Org-mode in a buffer. + + +File: org, Node: TODO types, Next: Multiple sets in one file, Prev: Workflow states, Up: TODO extensions + +5.2.2 TODO keywords as types +---------------------------- + +The second possibility is to use TODO keywords to indicate different +_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: + + (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE"))) + + 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 `C-c C-t'(1). 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 `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 `C-c / +t'. For example, to see all things Lucy has to do, you would use `C-3 +C-c / t'. To collect Lucy's items from all agenda files into a single +buffer, you would use the numeric prefix argument as well when creating +the global TODO list: `C-3 C-c a t'. + + ---------- Footnotes ---------- + + (1) This is also true for the `t' command in the timeline and agenda +buffers. + + +File: org, Node: Multiple sets in one file, Next: Fast access to TODO states, Prev: TODO types, Up: TODO extensions + +5.2.3 Multiple keyword sets in one file +--------------------------------------- + +Sometimes you may want to use different sets of TODO keywords in +parallel. For example, you may want to have the basic `TODO'/`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: + + (setq org-todo-keywords + '((sequence "TODO" "|" "DONE") + (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") + (sequence "|" "CANCELED"))) + + 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, `C-c C-t' only operates within a subsequence, so it switches from +`DONE' to (nothing) to `TODO', and from `FIXED' to (nothing) to +`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: + +`C-u C-u C-c C-t' +`C-S-<right>' +`C-S-<left>' + These keys jump from one TODO subset to the next. In the above + example, `C-u C-u C-c C-t' or `C-S-<right>' would jump from `TODO' + or `DONE' to `REPORT', and any of the words in the second row to + `CANCELED'. Note that the `C-S-' key binding conflict with + `shift-selection-mode' (*note Conflicts::). + +`S-<right>' +`S-<left>' + `S-<<left>>' and `S-<<right>>' and walk through _all_ keywords + from all sets, so for example `S-<<right>>' would switch from + `DONE' to `REPORT' in the example above. See also *Note + Conflicts::, for a discussion of the interaction with + `shift-selection-mode'. + + +File: org, Node: Fast access to TODO states, Next: Per-file keywords, Prev: Multiple sets in one file, Up: TODO extensions + +5.2.4 Fast access to TODO states +-------------------------------- + +If you would like to quickly change an entry to an arbitrary TODO state +instead of cycling through the states, you can set up keys for +single-letter access to the states. This is done by adding the section +key after each keyword, in parentheses. For example: + + (setq org-todo-keywords + '((sequence "TODO(t)" "|" "DONE(d)") + (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") + (sequence "|" "CANCELED(c)"))) + + If you then press `C-c C-t' followed by the selection key, the entry +will be switched to this state. <SPC> can be used to remove any TODO +keyword from an entry.(1) + + ---------- Footnotes ---------- + + (1) Check also the variable `org-fast-tag-selection-include-todo', +it allows you to change the TODO state through the tags interface +(*note Setting tags::), in case you like to mingle the two concepts. +Note that this means you need to come up with unique keys across both +sets of keywords. + + +File: org, Node: Per-file keywords, Next: Faces for TODO keywords, Prev: Fast access to TODO states, Up: TODO extensions + +5.2.5 Setting up keywords for individual files +---------------------------------------------- + +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: + + #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED + (you may also write `#+SEQ_TODO' to be explicit about the +interpretation, but it means the same as `#+TODO'), or + #+TYP_TODO: Fred Sara Lucy Mike | DONE + + A setup for using several sets in parallel would be: + + #+TODO: TODO | DONE + #+TODO: REPORT BUG KNOWNCAUSE | FIXED + #+TODO: | CANCELED + +To make sure you are using the correct keyword, type `#+' into the +buffer and then use `M-<TAB>' completion. + + 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 `C-c C-c' with the cursor still in the line to make the +changes known to Org-mode(1). + + ---------- Footnotes ---------- + + (1) Org-mode parses these lines only when Org-mode is activated +after visiting a file. `C-c C-c' with the cursor in a line starting +with `#+' is simply restarting Org-mode for the current buffer. + + +File: org, Node: Faces for TODO keywords, Next: TODO dependencies, Prev: Per-file keywords, Up: TODO extensions + +5.2.6 Faces for TODO keywords +----------------------------- + +Org-mode highlights TODO keywords with special faces: `org-todo' for +keywords indicating that an item still has to be acted upon, and +`org-done' for keywords indicating that an item is finished. If you +are using more than 2 different states, you might want to use special +faces for some of them. This can be done using the variable +`org-todo-keyword-faces'. For example: + + (setq org-todo-keyword-faces + '(("TODO" . org-warning) ("STARTED" . "yellow") + ("CANCELED" . (:foreground "blue" :weight bold)))) + + While using a list with face properties as shown for CANCELED +_should_ work, this does not aways seem to be the case. If necessary, +define a special face and use that. A string is interpreted as a +color. The variable `org-faces-easy-properties' determines if that +color is interpreted as a foreground or a background color. + + +File: org, Node: TODO dependencies, Prev: Faces for TODO keywords, Up: TODO extensions + +5.2.7 TODO dependencies +----------------------- + +The structure of Org files (hierarchy and lists) makes it easy to +define TODO dependencies. Usually, a parent TODO task should not be +marked DONE until all subtasks (defined as children tasks) are marked +as DONE. And sometimes there is a logical sequence to a number of +(sub)tasks, so that one task cannot be acted upon before all siblings +above it are done. If you customize the variable +`org-enforce-todo-dependencies', Org will block entries from changing +state to DONE while they have children that are not DONE. Furthermore, +if an entry has a property `ORDERED', each of its children will be +blocked until all earlier siblings are marked DONE. Here is an example: + + * TODO Blocked until (two) is done + ** DONE one + ** TODO two + + * Parent + :PROPERTIES: + :ORDERED: t + :END: + ** TODO a + ** TODO b, needs to wait for (a) + ** TODO c, needs to wait for (a) and (b) + +`C-c C-x o (`org-toggle-ordered-property')' + Toggle the `ORDERED' property of the current entry. A property is + used for this behavior because this should be local to the current + entry, not inherited like a tag. However, if you would like to + track the value of this property with a tag for better visibility, + customize the variable `org-track-ordered-property-with-tag'. + +`C-u C-u C-u C-c C-t' + Change TODO state, circumventing any state blocking. + + If you set the variable `org-agenda-dim-blocked-tasks', TODO entries +that cannot be closed because of such dependencies will be shown in a +dimmed font or even made invisible in agenda views (*note Agenda +Views::). + + You can also block changes of TODO states by looking at checkboxes +(*note Checkboxes::). If you set the variable +`org-enforce-todo-checkbox-dependencies', an entry that has unchecked +checkboxes will be blocked from switching to DONE. + + If you need more complex dependency structures, for example +dependencies between entries in different trees or files, check out the +contributed module `org-depend.el'. + + +File: org, Node: Progress logging, Next: Priorities, Prev: TODO extensions, Up: TODO Items + +5.3 Progress logging +==================== + +Org-mode can automatically record a timestamp and possibly a note when +you mark a TODO item as DONE, or even each time you change the state of +a TODO item. This system is highly configurable, settings can be on a +per-keyword basis and can be localized to a file or even a subtree. For +information on how to clock working time for a task, see *Note Clocking +work time::. + +* Menu: + +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Tracking your habits:: How consistent have you been? + + +File: org, Node: Closing items, Next: Tracking TODO state changes, Prev: Progress logging, Up: Progress logging + +5.3.1 Closing items +------------------- + +The most basic logging is to keep track of _when_ a certain TODO item +was finished. This is achieved with(1) + + (setq org-log-done 'time) + +Then each time you turn an entry from a TODO (not-done) state into any +of the DONE states, a line `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. If you +want to record a note along with the timestamp, use(2) + + (setq org-log-done 'note) + +You will then be prompted for a note, and that note will be stored below +the entry with a `Closing Note' heading. + + In the timeline (*note Timeline::) and in the agenda (*note +Weekly/daily agenda::), you can then use the `l' key to display the +TODO items with a `CLOSED' timestamp on each day, giving you an +overview of what has been done. + + ---------- Footnotes ---------- + + (1) The corresponding in-buffer setting is: `#+STARTUP: logdone' + + (2) The corresponding in-buffer setting is: `#+STARTUP: lognotedone' + + +File: org, Node: Tracking TODO state changes, Next: Tracking your habits, Prev: Closing items, Up: Progress logging + +5.3.2 Tracking TODO state changes +--------------------------------- + +When TODO keywords are used as workflow states (*note Workflow +states::), you might want to keep track of when a state change occurred +and maybe take a note about this change. You can either record just a +timestamp, or a time-stamped note for a change. These records will be +inserted after the headline as an itemized list, newest first(1). When +taking a lot of notes, you might want to get the notes out of the way +into a drawer (*note Drawers::). Customize the variable +`org-log-into-drawer' to get this behavior--the recommended drawer for +this is called `LOGBOOK'. You can also overrule the setting of this +variable for a subtree by setting a `LOG_INTO_DRAWER' property. + + Since it is normally too much to record a note for every state, +Org-mode expects configuration on a per-keyword basis for this. This +is achieved by adding special markers `!' (for a timestamp) and `@' +(for a note) in parentheses after each keyword. For example, with the +setting + + (setq org-todo-keywords + '((sequence "TODO(t)" "WAIT(w@/!)" "|" "DONE(d!)" "CANCELED(c@)"))) + +you not only define global TODO keywords and fast access keys, but also +request that a time is recorded when the entry is set to DONE(2), and +that a note is recorded when switching to WAIT or CANCELED. The +setting for WAIT is even more special: the `!' after the slash means +that in addition to the note taken when entering the state, a timestamp +should be recorded when leaving the WAIT state, if and only if the +target state does not configure logging for entering it. So it has no +effect when switching from WAIT to DONE, because DONE is configured to +record a timestamp only. But when switching from WAIT back to TODO, +the `/!' in the WAIT setting now triggers a timestamp even though TODO +has no logging configured. + + You can use the exact same syntax for setting logging preferences +local to a buffer: + #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@) + + In order to define logging settings that are local to a subtree or a +single item, define a LOGGING property in this entry. Any non-empty +LOGGING property resets all logging settings to nil. You may then turn +on logging for this specific tree using STARTUP keywords like +`lognotedone' or `logrepeat', as well as adding state specific settings +like `TODO(!)'. For example + + * TODO Log each state with only a time + :PROPERTIES: + :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!) + :END: + * TODO Only log when switching to WAIT, and when repeating + :PROPERTIES: + :LOGGING: WAIT(@) logrepeat + :END: + * TODO No logging at all + :PROPERTIES: + :LOGGING: nil + :END: + + ---------- Footnotes ---------- + + (1) See the variable `org-log-states-order-reversed' + + (2) It is possible that Org-mode will record two timestamps when you +are using both `org-log-done' and state change logging. However, it +will never prompt for two notes--if you have configured both, the state +change recording note will take precedence and cancel the `Closing +Note'. + + +File: org, Node: Tracking your habits, Prev: Tracking TODO state changes, Up: Progress logging + +5.3.3 Tracking your habits +-------------------------- + +Org has the ability to track the consistency of a special category of +TODOs, called "habits". A habit has the following properties: + + 1. You have enabled the `habits' module by customizing the variable + `org-modules'. + + 2. The habit is a TODO, with a TODO keyword representing an open + state. + + 3. The property `STYLE' is set to the value `habit'. + + 4. The TODO has a scheduled date, usually with a `.+' style repeat + interval. A `++' style may be appropriate for habits with time + constraints, e.g., must be done on weekends, or a `+' style for an + unusual habit that can have a backlog, e.g., weekly reports. + + 5. The TODO may also have minimum and maximum ranges specified by + using the syntax `.+2d/3d', which says that you want to do the + task at least every three days, but at most every two days. + + 6. You must also have state logging for the `DONE' state enabled, in + order for historical data to be represented in the consistency + graph. If it's not enabled it's not an error, but the consistency + graphs will be largely meaningless. + + To give you an idea of what the above rules look like in action, +here's an actual habit with some history: + + ** TODO Shave + SCHEDULED: <2009-10-17 Sat .+2d/4d> + - State "DONE" from "TODO" [2009-10-15 Thu] + - State "DONE" from "TODO" [2009-10-12 Mon] + - State "DONE" from "TODO" [2009-10-10 Sat] + - State "DONE" from "TODO" [2009-10-04 Sun] + - State "DONE" from "TODO" [2009-10-02 Fri] + - State "DONE" from "TODO" [2009-09-29 Tue] + - State "DONE" from "TODO" [2009-09-25 Fri] + - State "DONE" from "TODO" [2009-09-19 Sat] + - State "DONE" from "TODO" [2009-09-16 Wed] + - State "DONE" from "TODO" [2009-09-12 Sat] + :PROPERTIES: + :STYLE: habit + :LAST_REPEAT: [2009-10-19 Mon 00:36] + :END: + + What this habit says is: I want to shave at most every 2 days (given +by the `SCHEDULED' date and repeat interval) and at least every 4 days. +If today is the 15th, then the habit first appears in the agenda on +Oct 17, after the minimum of 2 days has elapsed, and will appear +overdue on Oct 19, after four days have elapsed. + + What's really useful about habits is that they are displayed along +with a consistency graph, to show how consistent you've been at getting +that task done in the past. This graph shows every day that the task +was done over the past three weeks, with colors for each day. The +colors used are: + +`Blue' + If the task wasn't to be done yet on that day. + +`Green' + If the task could have been done on that day. + +`Yellow' + If the task was going to be overdue the next day. + +`Red' + If the task was overdue on that day. + + In addition to coloring each day, the day is also marked with an +asterisk if the task was actually done that day, and an exclamation +mark to show where the current day falls in the graph. + + There are several configuration variables that can be used to change +the way habits are displayed in the agenda. + +`org-habit-graph-column' + The buffer column at which the consistency graph should be drawn. + This will overwrite any text in that column, so it's a good idea + to keep your habits' titles brief and to the point. + +`org-habit-preceding-days' + The amount of history, in days before today, to appear in + consistency graphs. + +`org-habit-following-days' + The number of days after today that will appear in consistency + graphs. + +`org-habit-show-habits-only-for-today' + If non-nil, only show habits in today's agenda view. This is set + to true by default. + + Lastly, pressing `K' in the agenda buffer will cause habits to +temporarily be disabled and they won't appear at all. Press `K' again +to bring them back. They are also subject to tag filtering, if you +have habits which should only be done in certain contexts, for example. + + +File: org, Node: Priorities, Next: Breaking down tasks, Prev: Progress logging, Up: TODO Items + +5.4 Priorities +============== + +If you use Org-mode extensively, you may end up with enough TODO items +that it starts to make sense to prioritize them. Prioritizing can be +done by placing a _priority cookie_ into the headline of a TODO item, +like this + + *** TODO [#A] Write letter to Sam Fortune + +By default, Org-mode supports three priorities: `A', `B', and `C'. `A' +is the highest priority. An entry without a cookie is treated just +like priority `B'. Priorities make a difference only for sorting in +the agenda (*note Weekly/daily agenda::); outside the agenda, they have +no inherent meaning to Org-mode. The cookies can be highlighted with +special faces by customizing the variable `org-priority-faces'. + + Priorities can be attached to any outline node; they do not need to +be TODO items. + +`C-c ,' + Set the priority of the current headline (`org-priority'). The + command prompts for a priority character `A', `B' or `C'. When + you press <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 `,' command (*note Agenda + commands::). + +`S-<up> (`org-priority-up')' +`S-<down> (`org-priority-down')' + Increase/decrease priority of current headline(1). Note that + these keys are also used to modify timestamps (*note Creating + timestamps::). See also *Note Conflicts::, for a discussion of + the interaction with `shift-selection-mode'. + + You can change the range of allowed priorities by setting the +variables `org-highest-priority', `org-lowest-priority', and +`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): + + #+PRIORITIES: A C B + + ---------- Footnotes ---------- + + (1) See also the option `org-priority-start-cycle-with-default'. + + +File: org, Node: Breaking down tasks, Next: Checkboxes, Prev: Priorities, Up: TODO Items + +5.5 Breaking tasks down into subtasks +===================================== + +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(1). To keep the overview over +the fraction of subtasks that are already completed, insert either +`[/]' or `[%]' anywhere in the headline. These cookies will be updated +each time the TODO status of a child changes, or when pressing `C-c +C-c' on the cookie. For example: + + * Organize Party [33%] + ** TODO Call people [1/2] + *** TODO Peter + *** DONE Sarah + ** TODO Buy food + ** DONE Talk to neighbor + + If a heading has both checkboxes and TODO children below it, the +meaning of the statistics cookie become ambiguous. Set the property +`COOKIE_DATA' to either `checkbox' or `todo' to resolve this issue. + + If you would like to have the statistics cookie count any TODO +entries in the subtree (not just direct children), configure the +variable `org-hierarchical-todo-statistics'. To do this for a single +subtree, include the word `recursive' into the value of the +`COOKIE_DATA' property. + + * Parent capturing statistics [2/20] + :PROPERTIES: + :COOKIE_DATA: todo recursive + :END: + + If you would like a TODO entry to automatically change to DONE when +all children are done, you can use the following setup: + + (defun org-summary-todo (n-done n-not-done) + "Switch entry to DONE when all subentries are done, to TODO otherwise." + (let (org-log-done org-log-states) ; turn off logging + (org-todo (if (= n-not-done 0) "DONE" "TODO")))) + + (add-hook 'org-after-todo-statistics-hook 'org-summary-todo) + + Another possibility is the use of checkboxes to identify (a +hierarchy of) a large number of subtasks (*note Checkboxes::). + + ---------- Footnotes ---------- + + (1) To keep subtasks out of the global TODO list, see the +`org-agenda-todo-list-sublevels'. + + +File: org, Node: Checkboxes, Prev: Breaking down tasks, Up: TODO Items + +5.6 Checkboxes +============== + +Every item in a plain list(1) (*note Plain lists::) can be made into a +checkbox by starting it with the string `[ ]'. This feature is similar +to TODO items (*note TODO Items::), but is 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 `C-c C-c', or +use the mouse (thanks to Piotr Zielinski's `org-mouse.el'). + + Here is an example of a checkbox list. + + * TODO Organize party [2/4] + - [-] call people [1/3] + - [ ] Peter + - [X] Sarah + - [ ] Sam + - [X] order food + - [ ] think about what music to play + - [X] talk to the neighbors + + Checkboxes work hierarchically, so if a checkbox item has children +that are checkboxes, toggling one of the children checkboxes will make +the parent checkbox reflect if none, some, or all of the children are +checked. + + The `[2/4]' and `[1/3]' in the first and second line are cookies +indicating how many checkboxes present in this entry have been checked +off, and the total number of checkboxes present. 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 checkboxes of direct +children structurally below the headline/item on which the cookie +appears(2). You have to insert the cookie yourself by typing either +`[/]' or `[%]'. With `[/]' you get an `n out of m' result, as in the +examples above. With `[%]' you get information about the percentage of +checkboxes checked (in the above example, this would be `[50%]' and +`[33%]', respectively). In a headline, a cookie can count either +checkboxes below the heading or TODO states of children, and it will +display whatever was changed last. Set the property `COOKIE_DATA' to +either `checkbox' or `todo' to resolve this issue. + + If the current outline node has an `ORDERED' property, checkboxes +must be checked off in sequence, and an error will be thrown if you try +to check off a box while there are unchecked boxes above it. + +The following commands work with checkboxes: + +`C-c C-c (`org-toggle-checkbox')' + Toggle checkbox status or (with prefix arg) checkbox presence at + point. With double prefix argument, set it to `[-]', which is + considered to be an intermediate state. + +`C-c C-x C-b (`org-toggle-checkbox')' + Toggle checkbox status or (with prefix arg) checkbox presence at + point. With double prefix argument, set it to `[-]', which is + considered to be an intermediate state. + - 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. With a prefix arg, add or remove the checkbox for + all items in the region. + + - If the cursor is in a headline, toggle checkboxes in the + region between this headline and the next (so _not_ the + entire subtree). + + - If there is no active region, just toggle the checkbox at + point. + +`M-S-<RET> (`org-insert-todo-heading')' + Insert a new item with a checkbox. This works only if the cursor + is already in a plain list item (*note Plain lists::). + +`C-c C-x o (`org-toggle-ordered-property')' + Toggle the `ORDERED' property of the entry, to toggle if + checkboxes must be checked off in sequence. A property is used + for this behavior because this should be local to the current + entry, not inherited like a tag. However, if you would like to + track the value of this property with a tag for better visibility, + customize the variable `org-track-ordered-property-with-tag'. + +`C-c # (`org-update-statistics-cookies')' + Update the statistics cookie in the current outline entry. When + called with a `C-u' prefix, update the entire file. Checkbox + statistic cookies are updated automatically if you toggle + checkboxes with `C-c C-c' and make new ones with `M-S-<RET>'. + TODO statistics cookies update when changing TODO states. If you + delete boxes/entries or add/change them by hand, use this command + to get things back into sync. Or simply toggle any entry twice + (checkboxes with `C-c C-c'). + + ---------- Footnotes ---------- + + (1) With the exception of description lists. But you can allow it by +modifying `org-list-automatic-rules' accordingly. + + (2) Set the variable `org-hierarchical-checkbox-statistics' if you +want such cookies to represent the all checkboxes below the cookie, not +just the direct children. + + +File: org, Node: Tags, Next: Properties and Columns, Prev: TODO Items, Up: Top + +6 Tags +****** + +An excellent way to implement labels and contexts for cross-correlating +information is to assign tags to headlines. Org-mode has extensive +support for tags. + + Every headline can contain a list of tags; they occur at the end of +the headline. Tags are normal words containing letters, numbers, `_', +and `@'. Tags must be preceded and followed by a single colon, e.g., +`:work:'. Several tags can be specified, as in `:work:urgent:'. Tags +will by default be in bold face with the same color as the headline. +You may specify special faces for specific tags using the variable +`org-tag-faces', in much the same way as you can for TODO keywords +(*note Faces for TODO keywords::). + +* 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 + + +File: org, Node: Tag inheritance, Next: Setting tags, Prev: Tags, Up: Tags + +6.1 Tag inheritance +=================== + +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 + + * Meeting with the French group :work: + ** Summary by Frank :boss:notes: + *** TODO Prepare slides for him :action: + +the final heading will have the tags `:work:', `:boss:', `:notes:', and +`:action:' even though the final heading is not explicitly marked with +those tags. You can also set tags that all entries in a file should +inherit just as if these tags were defined in a hypothetical level zero +that surrounds the entire file. Use a line like this(1): + + #+FILETAGS: :Peter:Boss:Secret: + +To limit tag inheritance to specific tags, or to turn it off entirely, +use the variables `org-use-tag-inheritance' and +`org-tags-exclude-from-inheritance'. + + When a headline matches during a tags search while tag inheritance +is turned on, all the sublevels in the same tree will (for a simple +match form) match as well(2). The list of matches may then become very +long. If you only want to see the first tags match in a subtree, +configure the variable `org-tags-match-list-sublevels' (not +recommended). + + ---------- Footnotes ---------- + + (1) As with all these in-buffer settings, pressing `C-c C-c' +activates any changes in the line. + + (2) This is only true if the search does not involve more complex +tests including properties (*note Property searches::). + + +File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags + +6.2 Setting tags +================ + +Tags can simply be typed into the buffer at the end of a headline. +After a colon, `M-<TAB>' offers completion on tags. There is also a +special command for inserting tags: + +`C-c C-q (`org-set-tags-command')' + 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 <RET>, the tags will be inserted + and aligned to `org-tags-column'. When called with a `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 (*note + TODO basics::). + +`C-c C-c (`org-set-tags-command')' + When the cursor is in a headline, this does the same as `C-c C-q'. + + Org will support tag insertion based on a _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 `org-tag-alist'. Finally you can set the +default tags for a given file with lines like + + #+TAGS: @work @home @tennisclub + #+TAGS: laptop car pc sailboat + + If you have globally defined your preferred set of tags using the +variable `org-tag-alist', but would like to use a dynamic tag list in a +specific file, add an empty TAGS option line to that file: + + #+TAGS: + + If you have a preferred set of tags that you would like to use in +every file, in addition to those defined on a per-file basis by TAGS +option lines, then you may specify a list of tags with the variable +`org-tag-persistent-alist'. You may turn this off on a per-file basis +by adding a STARTUP option line to that file: + + #+STARTUP: noptag + + By default Org-mode uses the standard minibuffer completion +facilities for entering tags. However, it also implements another, +quicker, tag selection method called _fast tag selection_. This allows +you to select and deselect tags with just a single key press. For this +to work well you should assign unique letters to most of your commonly +used tags. You can do this globally by configuring the variable +`org-tag-alist' in your `.emacs' file. For example, you may find the +need to tag many items in different files with `:@home:'. In this case +you can set something like: + + (setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l))) + +If the tag is only relevant to the file you are working on, then you +can instead set the TAGS option line as: + + #+TAGS: @work(w) @home(h) @tennisclub(t) laptop(l) pc(p) + +The tags interface will show the available tags in a splash window. If +you want to start a new line after a specific tag, insert `\n' into the +tag list + + #+TAGS: @work(w) @home(h) @tennisclub(t) \n laptop(l) pc(p) + +or write them in two lines: + + #+TAGS: @work(w) @home(h) @tennisclub(t) + #+TAGS: laptop(l) pc(p) + +You can also group together tags that are mutually exclusive by using +braces, as in: + + #+TAGS: { @work(w) @home(h) @tennisclub(t) } laptop(l) pc(p) + +you indicate that at most one of `@work', `@home', and `@tennisclub' +should be selected. Multiple such groups are allowed. + +Don't forget to press `C-c C-c' with the cursor in one of these lines +to activate any changes. + +To set these mutually exclusive groups in the variable `org-tags-alist', +you must use the dummy tags `:startgroup' and `:endgroup' instead of +the braces. Similarly, you can use `:newline' to indicate a line +break. The previous example would be set globally by the following +configuration: + + (setq org-tag-alist '((:startgroup . nil) + ("@work" . ?w) ("@home" . ?h) + ("@tennisclub" . ?t) + (:endgroup . nil) + ("laptop" . ?l) ("pc" . ?p))) + + If at least one tag has a selection key then pressing `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 valid tags +with corresponding keys(1). In this interface, you can use the +following keys: + +`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. + +`<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. + +`<SPC>' + Clear all tags for this line. + +`<RET>' + Accept the modified set. + +`C-g' + Abort without installing changes. + +`q' + If `q' is not assigned to a tag, it aborts like `C-g'. + +`!' + Turn off groups of mutually exclusive tags. Use this to (as an + exception) assign several tags from such a group. + +`C-c' + Toggle auto-exit after the next change (see below). If you are + using expert mode, the first `C-c' will display the selection + window. + +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 `@home', +`laptop' and `pc' tags with just the following keys: `C-c C-c <SPC> h l +p <RET>'. Switching from `@home' to `@work' would be done with `C-c +C-c w <RET>' or alternatively with `C-c C-c C-c w'. Adding the +non-predefined tag `Sarah' could be done with `C-c C-c <TAB> S a r a h +<RET> <RET>'. + + If you find that most of the time you need only a single key press to +modify your list of tags, set the variable +`org-fast-tag-selection-single-key'. Then you no longer have to press +<RET> to exit fast tag selection--it will immediately exit after the +first change. If you then occasionally need more keys, press `C-c' to +turn off auto-exit for the current tag selection process (in effect: +start selection with `C-c C-c C-c' instead of `C-c C-c'). If you set +the variable to the value `expert', the special window is not even +shown for single-key tag selection, it comes up only when you press an +extra `C-c'. + + ---------- Footnotes ---------- + + (1) Keys will automatically be assigned to tags which have no +configured keys. + + +File: org, Node: Tag searches, Prev: Setting tags, Up: Tags + +6.3 Tag searches +================ + +Once a system of tags has been set up, it can be used to collect related +information into special lists. + +`C-c / m or C-c ,org-match-sparse-tree (`')' + Create a sparse tree with all headlines matching a tags search. + With a `C-u' prefix argument, ignore headlines that are not a TODO + line. + +`C-c a m (`org-tags-view')' + Create a global list of tag matches from all agenda files. *Note + Matching tags and properties::. + +`C-c a M (`org-tags-view')' + Create a global list of tag matches from all agenda files, but + check only TODO items and force checking subitems (see variable + `org-tags-match-list-sublevels'). + + These commands all prompt for a match string which allows basic +Boolean logic like `+boss+urgent-project1', to find entries with tags +`boss' and `urgent', but not `project1', or `Kathy|Sally' to find +entries which are tagged, like `Kathy' or `Sally'. The full syntax of +the search string is rich and allows also matching against TODO +keywords, entry levels and properties. For a complete description with +many examples, see *Note Matching tags and properties::. + + +File: org, Node: Properties and Columns, Next: Dates and Times, Prev: Tags, Up: Top + +7 Properties and columns +************************ + +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. Second, you can use properties to +implement (very basic) database capabilities in an Org buffer. For an +example of the first application, imagine maintaining a file where you +document bugs and plan releases for a piece of software. Instead of +using tags like `:release_1:', `:release_2:', one can use a property, +say `:Release:', that in different subtrees has different values, such +as `1.0' or `2.0'. For an example of the second application of +properties, imagine keeping track of your music CDs, where properties +could be things such as the album, artist, date of release, number of +tracks, and so on. + + Properties can be conveniently edited and viewed in column view +(*note Column view::). + +* Menu: + +* Property syntax:: How properties are spelled out +* Special properties:: Access to other Org-mode features +* Property searches:: Matching property values +* Property inheritance:: Passing values down the tree +* Column view:: Tabular viewing and editing +* Property API:: Properties for Lisp programmers + + +File: org, Node: Property syntax, Next: Special properties, Prev: Properties and Columns, Up: Properties and Columns + +7.1 Property syntax +=================== + +Properties are key-value pairs. They need to be inserted into a special +drawer (*note Drawers::) with the name `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: + + * CD collection + ** Classic + *** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Artist: Glen Gould + :Publisher: Deutsche Grammophon + :NDisks: 1 + :END: + + You may define the allowed values for a particular property `:Xyz:' +by setting a property `:Xyz_ALL:'. This special property is +_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: + + * CD collection + :PROPERTIES: + :NDisks_ALL: 1 2 3 4 + :Publisher_ALL: "Deutsche Grammophon" Philips EMI + :END: + + If you want to set properties that can be inherited by any entry in a +file, use a line like + #+PROPERTY: NDisks_ALL 1 2 3 4 + + Property values set with the global variable `org-global-properties' +can be inherited by all entries in all Org files. + +The following commands help to work with properties: + +`M-<TAB> (`org-complete')' + After an initial colon in a line, complete property keys. All + keys used in the current file will be offered as possible + completions. + +`C-c C-x p (`org-set-property')' + Set a property. This prompts for a property name and a value. If + necessary, the property drawer is created as well. + +`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. + +`C-c C-c (`org-property-action')' + With the cursor in a property drawer, this executes property + commands. + +`C-c C-c s (`org-set-property')' + Set a property in the current entry. Both the property and the + value can be inserted using completion. + +`S-<right> (`org-property-next-allowed-value')' +`S-<left> (`org-property-previous-allowed-value')' + Switch property at point to the next/previous allowed value. + +`C-c C-c d (`org-delete-property')' + Remove a property from the current entry. + +`C-c C-c D (`org-delete-property-globally')' + Globally remove a property, from all entries in the current file. + +`C-c C-c c (`org-compute-property-at-point')' + Compute the property at point, using the operator and scope from + the nearest column format definition. + + +File: org, Node: Special properties, Next: Property searches, Prev: Property syntax, Up: Properties and Columns + +7.2 Special properties +====================== + +Special properties provide an alternative access method to Org-mode +features, like the TODO state or the priority of an entry, discussed in +the previous chapters. This interface exists so that you can include +these states in a column view (*note Column view::), or to use them in +queries. The following property names are special and should not be +used as keys in the properties drawer: + + TODO The TODO keyword of the entry. + TAGS The tags defined directly in the headline. + ALLTAGS All tags, including inherited ones. + CATEGORY The category of an entry. + PRIORITY The priority of the entry, a string with a single letter. + DEADLINE The deadline time string, without the angular brackets. + SCHEDULED The scheduling timestamp, without the angular brackets. + CLOSED When was this entry closed? + TIMESTAMP The first keyword-less timestamp in the entry. + TIMESTAMP_IA The first inactive timestamp in the entry. + CLOCKSUM The sum of CLOCK intervals in the subtree. `org-clock-sum' + must be run first to compute the values. + BLOCKED "t" if task is currently blocked by children or siblings + ITEM The content of the entry. + + +File: org, Node: Property searches, Next: Property inheritance, Prev: Special properties, Up: Properties and Columns + +7.3 Property searches +===================== + +To create sparse trees and special lists with selection based on +properties, the same commands are used as for tag searches (*note Tag +searches::). +`C-c / m or C-c ,org-match-sparse-tree (`')' + Create a sparse tree with all matching entries. With a `C-u' + prefix argument, ignore headlines that are not a TODO line. + +`C-c a m (`org-tags-view')' + Create a global list of tag/property matches from all agenda + files. *Note Matching tags and properties::. + +`C-c a M (`org-tags-view')' + Create a global list of tag matches from all agenda files, but + check only TODO items and force checking of subitems (see variable + `org-tags-match-list-sublevels'). + + The syntax for the search string is described in *Note Matching tags +and properties::. + + There is also a special command for creating sparse trees based on a +single property: + +`C-c / p' + Create a sparse tree based on the value of a property. This first + prompts for the name of a property, and then for a value. A + sparse tree is created with all entries that define this property + with the given value. If you enclose the value in curly braces, + it is interpreted as a regular expression and matched against the + property values. + + +File: org, Node: Property inheritance, Next: Column view, Prev: Property searches, Up: Properties and Columns + +7.4 Property Inheritance +======================== + +The outline structure of Org-mode documents lends itself to an +inheritance model of properties: if the parent in a tree has a certain +property, the children can inherit this property. Org-mode does not +turn this on by default, because it can slow down property searches +significantly and is often not needed. However, if you find inheritance +useful, you can turn it on by setting the variable +`org-use-property-inheritance'. It may be set to `t' to make all +properties inherited from the parent, to a list of properties that +should be inherited, or to a regular expression that matches inherited +properties. If a property has the value `nil', this is interpreted as +an explicit undefine of the property, so that inheritance search will +stop at this value and return `nil'. + + Org-mode has a few properties for which inheritance is hard-coded, at +least for the special applications for which they are used: + +`COLUMNS' + The `:COLUMNS:' property defines the format of column view (*note + Column view::). It is inherited in the sense that the level where + a `:COLUMNS:' property is defined is used as the starting point + for a column view table, independently of the location in the + subtree from where columns view is turned on. + +`CATEGORY' + For agenda view, a category set through a `:CATEGORY:' property + applies to the entire subtree. + +`ARCHIVE' + For archiving, the `:ARCHIVE:' property may define the archive + location for the entire subtree (*note Moving subtrees::). + +`LOGGING' + The LOGGING property may define logging settings for an entry or a + subtree (*note Tracking TODO state changes::). + + +File: org, Node: Column view, Next: Property API, Prev: Property inheritance, Up: Properties and Columns + +7.5 Column view +=============== + +A great way to view and edit properties in an outline tree is _column +view_. In column view, each outline node 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 +(`S-<TAB> S-<TAB>', or simply `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 (*note 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 +* Capturing column view:: A dynamic block for column view + + +File: org, Node: Defining columns, Next: Using column view, Prev: Column view, Up: Column view + +7.5.1 Defining columns +---------------------- + +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 + + +File: org, Node: Scope of column definitions, Next: Column attributes, Prev: Defining columns, Up: Defining columns + +7.5.1.1 Scope of column definitions +................................... + +To define a column format for an entire file, use a line like + + #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO + + To specify a format that only applies to a specific tree, add a +`:COLUMNS:' property to the top node of that tree, for example: + + ** Top node for columns view + :PROPERTIES: + :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO + :END: + + If a `: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. + + +File: org, Node: Column attributes, Prev: Scope of column definitions, Up: Defining columns + +7.5.1.2 Column attributes +......................... + +A column definition sets the attributes of a column. The general +definition looks like this: + + %[WIDTH]PROPERTY[(TITLE)][{SUMMARY-TYPE}] + +Except for the percent sign and the property name, all items are +optional. The individual parts have the following meaning: + + WIDTH An integer specifying the width of the column in characters. + If omitted, the width will be determined automatically. + PROPERTY The property that should be edited in this column. + Special properties representing meta data are allowed here + as well (*note Special properties::) + TITLE The header text for the column. If omitted, the property + name is used. + {SUMMARY-TYPE} The summary type. If specified, the column values for + parent nodes are computed from the children. + Supported summary types are: + {+} Sum numbers in this column. + {+;%.1f} Like `+', but format result with `%.1f'. + {$} Currency, short for `+;%.2f'. + {:} Sum times, HH:MM, plain numbers are hours. + {X} Checkbox status, `[X]' if all children are `[X]'. + {X/} Checkbox status, `[n/m]'. + {X%} Checkbox status, `[n%]'. + {min} Smallest number in column. + {max} Largest number. + {mean} Arithmetic mean of numbers. + {:min} Smallest time value in column. + {:max} Largest time value. + {:mean} Arithmetic mean of time values. + {@min} Minimum age (in days/hours/mins/seconds). + {@max} Maximum age (in days/hours/mins/seconds). + {@mean} Arithmetic mean of ages (in days/hours/mins/seconds). + {est+} Add low-high estimates. + +Be aware that you can only have one summary type for any property you +include. Subsequent columns referencing the same property will all +display the same summary information. + + The `est+' summary type requires further explanation. It is used for +combining estimates, expressed as low-high ranges. For example, instead +of estimating a particular task will take 5 days, you might estimate it +as 5-6 days if you're fairly confident you know how much work is +required, or 1-10 days if you don't really know what needs to be done. +Both ranges average at 5.5 days, but the first represents a more +predictable delivery. + + When combining a set of such estimates, simply adding the lows and +highs produces an unrealistically wide result. Instead, `est+' adds the +statistical mean and variance of the sub-tasks, generating a final +estimate from the sum. For example, suppose you had ten tasks, each of +which was estimated at 0.5 to 2 days of work. Straight addition +produces an estimate of 5 to 20 days, representing what to expect if +everything goes either extremely well or extremely poorly. In contrast, +`est+' estimates the full job more realistically, at 10-15 days. + + Here is an example for a complete columns definition, along with +allowed values. + + :COLUMNS: %25ITEM %9Approved(Approved?){X} %Owner %11Status \(1) + %10Time_Estimate{:} %CLOCKSUM + :Owner_ALL: Tammy Mark Karl Lisa Don + :Status_ALL: "In progress" "Not started yet" "Finished" "" + :Approved_ALL: "[ ]" "[X]" + +The first column, `%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 `Owner' with a list of names as allowed values, for +`Status' with four different possible values, and for a checkbox field +`Approved'. When no width is given after the `%' character, the column +will be exactly as wide as it needs to be in order to fully display all +values. The `Approved' column does have a modified title (`Approved?', +with a question mark). Summaries will be created for the +`Time_Estimate' column by adding time duration expressions like HH:MM, +and for the `Approved' column, by providing an `[X]' status if all +children have been checked. The `CLOCKSUM' column is special, it lists +the sum of CLOCK intervals in the subtree. + + ---------- Footnotes ---------- + + (1) Please note that the COLUMNS definition must be on a single +line--it is wrapped here only because of formatting constraints. + + +File: org, Node: Using column view, Next: Capturing column view, Prev: Defining columns, Up: Column view + +7.5.2 Using column view +----------------------- + +Turning column view on and off +.............................. + +`C-c C-x C-c (`org-columns')' + Turn on column view. If the cursor is before the first headline + in the file, column view is turned on for the entire file, using + the `#+COLUMNS' definition. If the cursor is somewhere inside the + outline, this command searches the hierarchy, up from point, for a + `:COLUMNS:' property that defines a format. When one is found, + the column view table is established for the tree starting at the + entry that contains the `:COLUMNS:' property. If no such property + is found, the format is taken from the `#+COLUMNS' line or from + the variable `org-columns-default-format', and column view is + established for the current entry and its subtree. + +`r (`org-columns-redo')' + Recreate the column view, to include recent changes made in the + buffer. + +`g (`org-columns-redo')' + Same as `r'. + +`q (`org-columns-quit')' + Exit column view. + +Editing values +.............. + +`<left> <right> <up> <down>' + Move through the column view from field to field. + +`S-<left>/<right>' + Switch to the next/previous allowed value of the field. For this, + you have to have specified allowed values for a property. + +`1..9,0' + Directly select the Nth allowed value, `0' selects the 10th value. + +`n (`org-columns-next-allowed-value')' +`p (`org-columns-previous-allowed-value')' + Same as `S-<left>/<right>' + +`e (`org-columns-edit-value')' + 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. + +`C-c C-c (`org-columns-set-tags-or-toggle')' + When there is a checkbox at point, toggle it. + +`v (`org-columns-show-value')' + View the full value of this property. This is useful if the width + of the column is smaller than that of the value. + +`a (`org-columns-edit-allowed')' + 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. + +Modifying the table structure +............................. + +`< (`org-columns-narrow')' +`> (`org-columns-widen')' + Make the column narrower/wider by one character. + +`S-M-<right> (`org-columns-new')' + Insert a new column, to the left of the current column. + +`S-M-<left> (`org-columns-delete')' + Delete the current column. + + +File: org, Node: Capturing column view, Prev: Using column view, Up: Column view + +7.5.3 Capturing column view +--------------------------- + +Since column view is just an overlay over a buffer, it cannot be +exported or printed directly. If you want to capture a column view, use +a `columnview' dynamic block (*note Dynamic blocks::). The frame of +this block looks like this: + + * The column view + #+BEGIN: columnview :hlines 1 :id "label" + + #+END: + +This dynamic block has the following parameters: + +`:id' + This is the most important parameter. Column view is a feature + that is often localized to a certain (sub)tree, and the capture + block might be at a different location in the file. To identify + the tree whose view to capture, you can use 4 values: + local use the tree in which the capture block is located + global make a global view, including all headings in the file + "file:PATH-TO-FILE" + run column view at the top of this file + "ID" call column view in the tree that has an `:ID:' + property with the value label. You can use + `M-x org-id-copy' to create a globally unique ID for + the current entry and copy it to the kill-ring. + +`:hlines' + When `t', insert an hline after every line. When a number N, + insert an hline before each headline with level `<= N'. + +`:vlines' + When set to `t', force column groups to get vertical lines. + +`:maxlevel' + When set to a number, don't capture entries below this level. + +`:skip-empty-rows' + When set to `t', skip rows where the only non-empty specifier of + the column view is `ITEM'. + + +The following commands insert or update the dynamic block: + +`C-c C-x i (`org-insert-columns-dblock')' + Insert a dynamic block capturing a column view. You will be + prompted for the scope or ID of the view. + +`C-c C-c or C-c C-x C-u (`org-dblock-update')' + Update dynamic block at point. The cursor needs to be in the + `#+BEGIN' line of the dynamic block. + +`C-u C-c C-x C-u (`org-update-all-dblocks')' + Update all dynamic blocks (*note Dynamic blocks::). This is + useful if you have several clock table blocks, column-capturing + blocks or other dynamic blocks in a buffer. + + You can add formulas to the column view table and you may add +plotting instructions in front of the table--these will survive an +update of the block. If there is a `#+TBLFM:' after the table, the +table will actually be recalculated automatically after an update. + + An alternative way to capture and process property values into a +table is provided by Eric Schulte's `org-collector.el' which is a +contributed package(1). It provides a general API to collect +properties from entries in a certain scope, and arbitrary Lisp +expressions to process these values before inserting them into a table +or a dynamic block. + + ---------- Footnotes ---------- + + (1) Contributed packages are not part of Emacs, but are distributed +with the main distribution of Org (visit `http://orgmode.org'). + + +File: org, Node: Property API, Prev: Column view, Up: Properties and Columns + +7.6 The Property API +==================== + +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 *Note Using the +property API::. + + +File: org, Node: Dates and Times, Next: Capture - Refile - Archive, Prev: Properties and Columns, Up: Top + +8 Dates and times +***************** + +To assist project planning, TODO items can be labeled with a date and/or +a time. The specially formatted string carrying the date and time +information is called a _timestamp_ in Org-mode. This may be a little +confusing because timestamp is often used as indicating when something +was created or last changed. However, in Org-mode this term is used in +a much wider sense. + +* Menu: + +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task +* Effort estimates:: Planning work effort in advance +* Relative timer:: Notes with a running timer +* Countdown timer:: Starting a countdown timer for a task + + +File: org, Node: Timestamps, Next: Creating timestamps, Prev: Dates and Times, Up: Dates and Times + +8.1 Timestamps, deadlines, and scheduling +========================================= + +A timestamp is a specification of a date (possibly with a time or a +range of times) in a special format, either `<2003-09-16 Tue>' or +`<2003-09-16 Tue 09:39>' or `<2003-09-16 Tue 12:00-12:30>'(1). A +timestamp 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 (*note Weekly/daily agenda::). We distinguish: + +PLAIN TIMESTAMP; EVENT; APPOINTMENT + A simple timestamp just assigns a date/time to an item. This is + just like writing down an appointment or event in a paper agenda. + In the timeline and agenda displays, the headline of an entry + associated with a plain timestamp will be shown exactly on that + date. + + * Meet Peter at the movies <2006-11-01 Wed 19:15> + * Discussion on climate change <2006-11-02 Thu 20:00-22:00> + +TIMESTAMP WITH REPEATER INTERVAL + A timestamp may contain a _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: + + * Pick up Sam at school <2007-05-16 Wed 12:30 +1w> + +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 + + * The nerd meeting on every 2nd Thursday of the month + <%%(diary-float t 4 2)> + +TIME/DATE RANGE + Two timestamps connected by `--' 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: + + ** Meeting in Amsterdam + <2004-08-23 Mon>--<2004-08-26 Thu> + +INACTIVE TIMESTAMP + Just like a plain timestamp, but with square brackets instead of + angular ones. These timestamps are inactive in the sense that + they do _not_ trigger an entry to show up in the agenda. + + * Gillian comes late for the fifth time [2006-11-01 Wed] + + + ---------- Footnotes ---------- + + (1) This is inspired by the standard ISO 8601 date/time format. To +use an alternative format, see *Note Custom time format::. + + +File: org, Node: Creating timestamps, Next: Deadlines and scheduling, Prev: Timestamps, Up: Dates and Times + +8.2 Creating timestamps +======================= + +For Org-mode to recognize timestamps, they need to be in the specific +format. All commands listed below produce timestamps in the correct +format. + +`C-c . (`org-time-stamp')' + Prompt for a date and insert a corresponding timestamp. When the + cursor is at an existing timestamp in the buffer, the command is + used to modify this timestamp instead of inserting a new one. + When this command is used twice in succession, a time range is + inserted. + +`C-c ! (`org-time-stamp-inactive')' + Like `C-c .', but insert an inactive timestamp that will not cause + an agenda entry. + +`C-u C-c .' +`C-u C-c !' + Like `C-c .' and `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 + `org-time-stamp-rounding-minutes'. + +`C-c < (`org-date-from-calendar')' + Insert a timestamp corresponding to the cursor date in the + Calendar. + +`C-c > (`org-goto-calendar')' + Access the Emacs calendar for the current date. If there is a + timestamp in the current line, go to the corresponding date + instead. + +`C-c C-o (`org-open-at-point')' + Access the agenda for the date given by the timestamp or -range at + point (*note Weekly/daily agenda::). + +`S-<left> (`org-timestamp-down-day')' +`S-<right> (`org-timestamp-up-day')' + Change date at cursor by one day. These key bindings conflict with + shift-selection and related modes (*note Conflicts::). + +`S-<up> (`org-timestamp-up')' +`S-<down> (`org-timestamp-down-down')' + Change the item under the cursor in a timestamp. The cursor can + be on a year, month, day, hour or minute. When the timestamp + contains a time range like `15:30-16:30', modifying the first time + will also shift the second, shifting the time block with constant + length. To change the length, modify the second time. Note that + if the cursor is in a headline and not at a timestamp, these same + keys modify the priority of an item. (*note Priorities::). The + key bindings also conflict with shift-selection and related modes + (*note Conflicts::). + +`C-c C-y (`org-evaluate-time-range')' + Evaluate a time range by computing the difference between start + and end. With a prefix argument, insert result after the time + range (in a table: into the following column). + +* Menu: + +* The date/time prompt:: How Org-mode helps you entering date and time +* Custom time format:: Making dates look different + + +File: org, Node: The date/time prompt, Next: Custom time format, Prev: Creating timestamps, Up: Creating timestamps + +8.2.1 The date/time prompt +-------------------------- + +When Org-mode prompts for a date/time, the default is shown in default +date/time format, and the prompt therefore seems to ask for a specific +format. But it will in fact accept any string containing some date +and/or time information, and it is really smart about interpreting your +input. You can, for example, use `C-y' to paste a (possibly +multi-line) string copied from an email message. Org-mode will find +whatever information is in there and derive anything you have not +specified from the _default date and time_. The default is usually the +current date and time, but when modifying an existing timestamp, or +when entering the second stamp of a range, it is taken from the stamp +in the buffer. When filling in information, Org-mode assumes that most +of the time you will want to enter a date in the future: if you omit +the month/year and the given day/month is before today, it will assume +that you mean a future date(1). If the date has been automatically +shifted into the future, the time prompt will show this with `(=>F).' + + For example, let's assume that today is June 13, 2006. Here is how +various inputs will be interpreted, the items filled in by Org-mode are +in bold. + + 3-2-5 --> 2003-02-05 + 2/5/3 --> 2003-02-05 + 14 --> 2006-06-14 + 12 --> 2006-07-12 + 2/5 --> 2007-02-05 + Fri --> nearest Friday (default date or later) + sep 15 --> 2006-09-15 + feb 15 --> 2007-02-15 + sep 12 9 --> 2009-09-12 + 12:45 --> 2006-06-13 12:45 + 22 sept 0:34 --> 2006-09-22 0:34 + w4 --> ISO week for of the current year 2006 + 2012 w4 fri --> Friday of ISO week 4 in 2012 + 2012-w04-5 --> Same as above + + Furthermore you can specify a relative date by giving, as the +_first_ thing in the input: a plus/minus sign, a number and a letter +([dwmy]) to indicate change in days, weeks, months, or years. With a +single plus or minus, the date is always relative to today. With a +double plus or minus, it is relative to the default date. If instead of +a single letter, you use the abbreviation of day name, the date will be +the Nth such day. E.g. + + +0 --> today + . --> today + +4d --> four days from today + +4 --> same as above + +2w --> two weeks from today + ++5 --> five days from default date + +2tue --> second Tuesday from now. + + The function understands English month and weekday abbreviations. If +you want to use unabbreviated names and/or other languages, configure +the variables `parse-time-months' and `parse-time-weekdays'. + + You can specify a time range by giving start and end times or by +giving a start time and a duration (in HH:MM format). Use `-' or `-{}-' +as the separator in the former case and use '+' as the separator in the +latter case. E.g. + + 11am-1:15pm --> 11:00-13:15 + 11am--1:15pm --> same as above + 11am+2:15 --> same as above + + Parallel to the minibuffer prompt, a calendar is popped up(2). When +you exit the date prompt, either by clicking on a date in the calendar, +or by pressing <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: + + <RET> Choose date at cursor in calendar. + mouse-1 Select date by clicking on it. + S-<right>/<left> One day forward/backward. + S-<down>/<up> One week forward/backward. + M-S-<right>/<left> One month forward/backward. + > / < Scroll calendar forward/backward by one month. + M-v / C-v Scroll calendar forward/backward by 3 months. + + The actions of the date/time prompt may seem complex, but I assure +you they will grow on you, and you will start getting annoyed by pretty +much any other way of entering a date/time out there. To help you +understand what is going on, the current interpretation of your input +will be displayed live in the minibuffer(3). + + ---------- Footnotes ---------- + + (1) See the variable `org-read-date-prefer-future'. You may set +that variable to the symbol `time' to even make a time before now shift +the date to tomorrow. + + (2) If you don't need/want the calendar, configure the variable +`org-popup-calendar-for-date-prompt'. + + (3) If you find this distracting, turn the display of with +`org-read-date-display-live'. + + +File: org, Node: Custom time format, Prev: The date/time prompt, Up: Creating timestamps + +8.2.2 Custom time format +------------------------ + +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 `org-display-custom-times' and +`org-time-stamp-custom-formats'. + +`C-c C-x C-t (`org-toggle-time-stamp-overlays')' + Toggle the display of custom formats for dates and times. + +Org-mode needs the default format for scanning, so the custom date/time +format does not _replace_ the default format--instead it is put _over_ +the default format using text properties. This has the following +consequences: + * You cannot place the cursor onto a timestamp anymore, only before + or after. + + * The `S-<up>/<down>' keys can no longer be used to adjust each + component of a timestamp. If the cursor is at the beginning of + the stamp, `S-<up>/<down>' will change the stamp by one day, just + like `S-<left>/<right>'. At the end of the stamp, the time will + be changed by one minute. + + * If the timestamp contains a range of clock times or a repeater, + these will not be overlaid, but remain in the buffer as they were. + + * When you delete a timestamp character-by-character, it will only + disappear from the buffer after _all_ (invisible) characters + belonging to the ISO timestamp have been removed. + + * If the custom timestamp 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. + + +File: org, Node: Deadlines and scheduling, Next: Clocking work time, Prev: Creating timestamps, Up: Dates and Times + +8.3 Deadlines and scheduling +============================ + +A timestamp may be preceded by special keywords to facilitate planning: + +DEADLINE + Meaning: the task (most likely a TODO item, though not + necessarily) is supposed to be finished on that date. + + On the deadline date, the task will be listed in the agenda. In + addition, the agenda for _today_ will carry a warning about the + approaching or missed deadline, starting + `org-deadline-warning-days' before the due date, and continuing + until the entry is marked DONE. An example: + + *** TODO write article about the Earth for the Guide + The editor in charge is [[bbdb:Ford Prefect]] + DEADLINE: <2004-02-29 Sun> + + 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 `DEADLINE: <2004-02-29 Sun -5d>'. + +SCHEDULED + Meaning: you are planning to start working on that task on the + given date. + + The headline will be listed under the given date(1). In addition, + a reminder that the scheduled date has passed will be present in + the compilation for _today_, until the entry is marked DONE, i.e. + the task will automatically be forwarded until completed. + + *** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> + + Important: Scheduling an item in Org-mode should not be understood + in the same way that we understand scheduling a meeting. Setting + a date for a meeting is just a simple appointment, you should mark + this entry with a simple plain timestamp, to get this item shown + on the date where it applies. This is a frequent misunderstanding + by Org users. In Org-mode, scheduling means setting a date when + you want to start working on an action item. + + You may use timestamps with repeaters in scheduling and deadline +entries. Org-mode will issue early and late warnings based on the +assumption that the timestamp represents the nearest instance of the +repeater. However, the use of diary sexp entries like `<%%(diary-float +t 42)>' in scheduling and deadline timestamps is limited. Org-mode +does not know enough about the internals of each sexp function to issue +early and late warnings. However, it will show the item on each day +where the sexp entry matches. + +* Menu: + +* Inserting deadline/schedule:: Planning items +* Repeated tasks:: Items that show up again and again + + ---------- Footnotes ---------- + + (1) It will still be listed on that date after it has been marked +DONE. If you don't like this, set the variable +`org-agenda-skip-scheduled-if-done'. + + +File: org, Node: Inserting deadline/schedule, Next: Repeated tasks, Prev: Deadlines and scheduling, Up: Deadlines and scheduling + +8.3.1 Inserting deadlines or schedules +-------------------------------------- + +The following commands allow you to quickly insert a deadline or to +schedule an item: + +`C-c C-d (`org-deadline')' + Insert `DEADLINE' keyword along with a stamp. The insertion will + happen in the line directly following the headline. When called + with a prefix arg, an existing deadline will be removed from the + entry. Depending on the variable `org-log-redeadline'(1), a note + will be taken when changing an existing deadline. + +`C-c C-s (`org-schedule')' + Insert `SCHEDULED' keyword along with a stamp. The insertion will + happen in the line directly following the headline. Any CLOSED + timestamp will be removed. When called with a prefix argument, + remove the scheduling date from the entry. Depending on the + variable `org-log-reschedule'(2), a note will be taken when + changing an existing scheduling time. + +`C-c C-x C-k (`org-mark-entry-for-agenda-action')' + Mark the current entry for agenda action. After you have marked + the entry like this, you can open the agenda or the calendar to + find an appropriate date. With the cursor on the selected date, + press `k s' or `k d' to schedule the marked item. + +`C-c / d (`org-check-deadlines')' + Create a sparse tree with all deadlines that are either past-due, + or which will become due within `org-deadline-warning-days'. With + `C-u' prefix, show all deadlines in the file. With a numeric + prefix, check that many days. For example, `C-1 C-c / d' shows + all deadlines due tomorrow. + +`C-c / b (`org-check-before-date')' + Sparse tree for deadlines and scheduled items before a given date. + +`C-c / a (`org-check-after-date')' + Sparse tree for deadlines and scheduled items after a given date. + + ---------- Footnotes ---------- + + (1) with corresponding `#+STARTUP' keywords `logredeadline', +`lognoteredeadline', and `nologredeadline' + + (2) with corresponding `#+STARTUP' keywords `logredeadline', +`lognoteredeadline', and `nologredeadline' + + +File: org, Node: Repeated tasks, Prev: Inserting deadline/schedule, Up: Deadlines and scheduling + +8.3.2 Repeated tasks +-------------------- + +Some tasks need to be repeated again and again. Org-mode helps to +organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, +or plain timestamp. In the following example + ** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> + the `+1m' is a repeater; the intended interpretation is that the task +has a deadline on <2005-10-01> and repeats itself every (one) month +starting from that time. If you need both a repeater and a special +warning period in a deadline entry, the repeater should come first and +the warning period last: `DEADLINE: <2005-10-01 Sat +1m -3d>'. + + 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 +_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 `C-c C-t'), it will shift the base date of the +repeating timestamp by the repeater interval, and immediately set the +entry state back to TODO(1). In the example above, setting the state +to DONE would actually switch the date like this: + + ** TODO Pay the rent + DEADLINE: <2005-11-01 Tue +1m> + + A timestamp(2) will be added under the deadline, 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. + + With the `+1m' cookie, the date shift will always be exactly one +month. So if you have not paid the rent for three months, marking this +entry DONE will still keep it as an overdue deadline. Depending on the +task, this may not be the best way to handle it. For example, if you +forgot to call your father for 3 weeks, it does not make sense to call +him 3 times in a single day to make up for it. Finally, there are tasks +like changing batteries which should always repeat a certain time after +the last time you did it. For these tasks, Org-mode has special +repeaters `++' and `.+'. For example: + + ** TODO Call Father + DEADLINE: <2008-02-10 Sun ++1w> + Marking this DONE will shift the date by at least one week, + but also by as many weeks as it takes to get this date into + the future. However, it stays on a Sunday, even if you called + and marked it done on Saturday. + ** TODO Check the batteries in the smoke detectors + DEADLINE: <2005-11-01 Tue .+1m> + Marking this DONE will shift the date to one month after + today. + + You may have both scheduling and deadline information for a specific +task--just make sure that the repeater intervals on both are the same. + + An alternative to using a repeater is to create a number of copies +of a task subtree, with dates shifted in each copy. The command `C-c +C-x c' was created for this purpose, it is described in *Note Structure +editing::. + + ---------- Footnotes ---------- + + (1) In fact, the target state is taken from, in this sequence, the +`REPEAT_TO_STATE' property or the variable `org-todo-repeat-to-state'. +If neither of these is specified, the target state defaults to the +first state of the TODO state sequence. + + (2) You can change this using the option `org-log-repeat', or the +`#+STARTUP' options `logrepeat', `lognoterepeat', and `nologrepeat'. +With `lognoterepeat', you will also be prompted for a note. + + +File: org, Node: Clocking work time, Next: Effort estimates, Prev: Deadlines and scheduling, Up: Dates and Times + +8.4 Clocking work time +====================== + +Org-mode allows you to clock the time you spend 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. And it +remembers a history or tasks recently clocked, to that you can jump +quickly between a number of tasks absorbing your time. + + To save the clock history across Emacs sessions, use + (setq org-clock-persist 'history) + (org-clock-persistence-insinuate) + When you clock into a new task after resuming Emacs, the incomplete +clock(1) will be found (*note Resolving idle time::) and you will be +prompted about what to do with it. + +* Menu: + +* Clocking commands:: Starting and stopping a clock +* The clock table:: Detailed reports +* Resolving idle time:: Resolving time when you've been idle + + ---------- Footnotes ---------- + + (1) To resume the clock under the assumption that you have worked on +this task while outside Emacs, use `(setq org-clock-persist t)'. + + +File: org, Node: Clocking commands, Next: The clock table, Prev: Clocking work time, Up: Clocking work time + +8.4.1 Clocking commands +----------------------- + +`C-c C-x C-i (`org-clock-in')' + Start the clock on the current item (clock-in). This inserts the + CLOCK keyword together with a timestamp. If this is not the first + clocking of this item, the multiple CLOCK lines will be wrapped + into a `:LOGBOOK:' drawer (see also the variable + `org-clock-into-drawer'). When called with a `C-u' prefix + argument, select the task from a list of recently clocked tasks. + With two `C-u C-u' prefixes, clock into the task at point and mark + it as the default task. The default task will always be available + when selecting a clocking task, with letter `d'. + While the clock is running, the current clocking time is shown in + the mode line, along with the title of the task. The clock time + shown will be all time ever clocked for this task and its + children. If the task has an effort estimate (*note Effort + estimates::), the mode line displays the current clocking time + against it(1) If the task is a repeating one (*note Repeated + tasks::), only the time since the last reset of the task (2) will + be shown. More control over what time is shown can be exercised + with the `CLOCK_MODELINE_TOTAL' property. It may have the values + `current' to show only the current clocking instance, `today' to + show all time clocked on this tasks today (see also the variable + `org-extend-today-until'), `all' to include all time, or `auto' + which is the default(3). + Clicking with `mouse-1' onto the mode line entry will pop up a + menu with clocking options. + +`C-c C-x C-o (`org-clock-out')' + Stop the clock (clock-out). This 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 + `=> HH:MM'. See the variable `org-log-note-clock-out' for the + possibility to record an additional note together with the + clock-out timestamp(4). + +`C-c C-x C-e (`org-clock-modify-effort-estimate')' + Update the effort estimate for the current clock task. + +`C-c C-c or C-c C-y (`org-evaluate-time-range')' + Recompute the time interval after changing one of the timestamps. + This is only necessary if you edit the timestamps directly. If + you change them with `S-<cursor>' keys, the update is automatic. + +`C-c C-t (`org-todo')' + Changing the TODO state of an item to DONE automatically stops the + clock if it is running in this same item. + +`C-c C-x C-x (`org-clock-cancel')' + Cancel the current clock. This is useful if a clock was started by + mistake, or if you ended up working on something else. + +`C-c C-x C-j (`org-clock-goto')' + Jump to the headline of the currently clocked in task. With a + `C-u' prefix arg, select the target task from a list of recently + clocked tasks. + +`C-c C-x C-d (`org-clock-display')' + 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 + `org-remove-highlights-with-change') or press `C-c C-c'. + + The `l' key may be used in the timeline (*note Timeline::) and in +the agenda (*note Weekly/daily agenda::) to show which tasks have been +worked on or closed during a day. + + ---------- Footnotes ---------- + + (1) To add an effort estimate "on the fly", hook a function doing +this to `org-clock-in-prepare-hook'. + + (2) as recorded by the `LAST_REPEAT' property + + (3) See also the variable `org-clock-modeline-total'. + + (4) The corresponding in-buffer setting is: `#+STARTUP: +lognoteclock-out' + + +File: org, Node: The clock table, Next: Resolving idle time, Prev: Clocking commands, Up: Clocking work time + +8.4.2 The clock table +--------------------- + +Org mode can produce quite complex reports based on the time clocking +information. Such a report is called a _clock table_, because it is +formatted as one or several Org tables. + +`C-c C-x C-r (`org-clock-report')' + Insert a dynamic block (*note Dynamic blocks::) containing a clock + report as an Org-mode table into the current file. When the + cursor is at an existing clock table, just update it. When called + with a prefix argument, jump to the first clock report in the + current document and update it. + +`C-c C-c or C-c C-x C-u (`org-dblock-update')' + Update dynamic block at point. The cursor needs to be in the + `#+BEGIN' line of the dynamic block. + +`C-u C-c C-x C-u' + Update all dynamic blocks (*note Dynamic blocks::). This is + useful if you have several clock table blocks in a buffer. + +`S-<left>' +`S-<right> (`org-clocktable-try-shift')' + Shift the current `:block' interval and update the table. The + cursor needs to be in the `#+BEGIN: clocktable' line for this + command. If `:block' is `today', it will be shifted to `today-1' + etc. + + Here is an example of the frame for a clock table as it is inserted +into the buffer with the `C-c C-x C-r' command: + + #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file + #+END: clocktable + The `BEGIN' line and specify a number of options to define the scope, +structure, and formatting of the report. Defaults for all these +options can be configured in the variable `org-clocktable-defaults'. + +First there are options that determine which clock entries are to be +selected: + :maxlevel Maximum level depth to which times are listed in the table. + Clocks at deeper levels will be summed into the upper level. + :scope The scope to consider. This can be any of the following: + nil the current buffer or narrowed region + file the full current buffer + subtree the subtree where the clocktable is located + treeN the surrounding level N tree, for example `tree3' + tree the surrounding level 1 tree + agenda all agenda files + ("file"..) scan these files + file-with-archives current file and its archives + agenda-with-archives all agenda files, including archives + :block The time block to consider. This block is specified either + absolute, or relative to the current time and may be any of + these formats: + 2007-12-31 New year eve 2007 + 2007-12 December 2007 + 2007-W50 ISO-week 50 in 2007 + 2007-Q2 2nd quarter in 2007 + 2007 the year 2007 + today, yesterday, today-N a relative day + thisweek, lastweek, thisweek-N a relative week + thismonth, lastmonth, thismonth-N a relative month + thisyear, lastyear, thisyear-N a relative year + Use `S-<left>/<right>' keys to shift the time interval. + :tstart A time string specifying when to start considering times. + :tend A time string specifying when to stop considering times. + :step `week' or `day', to split the table into chunks. + To use this, `:block' or `:tstart', `:tend' are needed. + :stepskip0 Do not show steps that have zero time. + :fileskip0 Do not show table sections from files which did not contribute. + :tags A tags match to select entries that should contribute. + + Then there are options which determine the formatting of the table. +There options are interpreted by the function +`org-clocktable-write-default', but you can specify your own function +using the `:formatter' parameter. + :emphasize When `t', emphasize level one and level two items. + :link Link the item headlines in the table to their origins. + :narrow An integer to limit the width of the headline column in + the org table. If you write it like `50!', then the + headline will also be shortened in export. + :indent Indent each headline field according to its level. + :tcolumns Number of columns to be used for times. If this is smaller + than `:maxlevel', lower levels will be lumped into one column. + :level Should a level number column be included? + :compact Abbreviation for `:level nil :indent t :narrow 40! :tcolumns 1' + All are overwritten except if there is an explicit `:narrow' + :timestamp A timestamp for the entry, when available. Look for SCHEDULED, + DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order. + :formula Content of a `#+TBLFM' line to be added and evaluated. + As a special case, `:formula %' adds a column with % time. + If you do not specify a formula here, any existing formula + below the clock table will survive updates and be evaluated. + :formatter A function to format clock data and insert it into the buffer. + To get a clock summary of the current level 1 tree, for the current +day, you could write + #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t + #+END: clocktable + and to use a specific time range you could write(1) + #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" + :tend "<2006-08-10 Thu 12:00>" + #+END: clocktable + A summary of the current subtree with % times would be + #+BEGIN: clocktable :scope subtree :link t :formula % + #+END: clocktable + A horizontally compact representation of everything clocked during +last week would be + #+BEGIN: clocktable :scope agenda :block lastweek :compact t + #+END: clocktable + + ---------- Footnotes ---------- + + (1) Note that all parameters must be specified in a single line--the +line is broken here only to fit it into the manual. + + +File: org, Node: Resolving idle time, Prev: The clock table, Up: Clocking work time + +8.4.3 Resolving idle time +------------------------- + +If you clock in on a work item, and then walk away from your +computer--perhaps to take a phone call--you often need to "resolve" the +time you were away by either subtracting it from the current clock, or +applying it to another one. + + By customizing the variable `org-clock-idle-time' to some integer, +such as 10 or 15, Emacs can alert you when you get back to your +computer after being idle for that many minutes(1), and ask what you +want to do with the idle time. There will be a question waiting for +you when you get back, indicating how much idle time has passed +(constantly updated with the current amount), as well as a set of +choices to correct the discrepancy: + +`k' + To keep some or all of the minutes and stay clocked in, press `k'. + Org will ask how many of the minutes to keep. Press <RET> to + keep them all, effectively changing nothing, or enter a number to + keep that many minutes. + +`K' + If you use the shift key and press `K', it will keep however many + minutes you request and then immediately clock out of that task. + If you keep all of the minutes, this is the same as just clocking + out of the current task. + +`s' + To keep none of the minutes, use `s' to subtract all the away time + from the clock, and then check back in from the moment you + returned. + +`S' + To keep none of the minutes and just clock out at the start of the + away time, use the shift key and press `S'. Remember that using + shift will always leave you clocked out, no matter which option + you choose. + +`C' + To cancel the clock altogether, use `C'. Note that if instead of + canceling you subtract the away time, and the resulting clock + amount is less than a minute, the clock will still be canceled + rather than clutter up the log with an empty entry. + + What if you subtracted those away minutes from the current clock, +and now want to apply them to a new clock? Simply clock in to any task +immediately after the subtraction. Org will notice that you have +subtracted time "on the books", so to speak, and will ask if you want +to apply those minutes to the next task you clock in on. + + There is one other instance when this clock resolution magic occurs. +Say you were clocked in and hacking away, and suddenly your cat chased +a mouse who scared a hamster that crashed into your UPS's power button! +You suddenly lose all your buffers, but thanks to auto-save you still +have your recent Org mode changes, including your last clock in. + + If you restart Emacs and clock into any task, Org will notice that +you have a dangling clock which was never clocked out from your last +session. Using that clock's starting time as the beginning of the +unaccounted-for period, Org will ask how you want to resolve that time. +The logic and behavior is identical to dealing with away time due to +idleness; it's just happening due to a recovery event rather than a set +amount of idle time. + + You can also check all the files visited by your Org agenda for +dangling clocks at any time using `M-x org-resolve-clocks'. + + ---------- Footnotes ---------- + + (1) On computers using Mac OS X, idleness is based on actual user +idleness, not just Emacs' idle time. For X11, you can install a +utility program `x11idle.c', available in the UTILITIES directory of +the Org git distribution, to get the same general treatment of +idleness. On other systems, idle time refers to Emacs idle time only. + + +File: org, Node: Effort estimates, Next: Relative timer, Prev: Clocking work time, Up: Dates and Times + +8.5 Effort estimates +==================== + +If you want to plan your work in a very detailed way, or if you need to +produce offers with quotations of the estimated work effort, you may +want to assign effort estimates to entries. If you are also clocking +your work, you may later want to compare the planned effort with the +actual working time, a great way to improve planning estimates. Effort +estimates are stored in a special property `Effort'(1). You can set +the effort for an entry with the following commands: + +`C-c C-x e (`org-set-effort')' + Set the effort estimate for the current entry. With a numeric + prefix argument, set it to the Nth allowed value (see below). + This command is also accessible from the agenda with the `e' key. + +`C-c C-x C-e (`org-clock-modify-effort-estimate')' + Modify the effort estimate of the item currently being clocked. + + Clearly the best way to work with effort estimates is through column +view (*note Column view::). You should start by setting up discrete +values for effort estimates, and a `COLUMNS' format that displays these +values together with clock sums (if you want to clock your time). For +a specific buffer you can use + + #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 8:00 + #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort){:} %CLOCKSUM + +or, even better, you can set up these values globally by customizing the +variables `org-global-properties' and `org-columns-default-format'. In +particular if you want to use this setup also in the agenda, a global +setup may be advised. + + The way to assign estimates to individual items is then to switch to +column mode, and to use `S-<right>' and `S-<left>' to change the value. +The values you enter will immediately be summed up in the hierarchy. +In the column next to it, any clocked time will be displayed. + + If you switch to column view in the daily/weekly agenda, the effort +column will summarize the estimated work effort for each day(2), and +you can use this to find space in your schedule. To get an overview of +the entire part of the day that is committed, you can set the option +`org-agenda-columns-add-appointments-to-effort-sum'. The appointments +on a day that take place over a specified time interval will then also +be added to the load estimate of the day. + + Effort estimates can be used in secondary agenda filtering that is +triggered with the `/' key in the agenda (*note Agenda commands::). If +you have these estimates defined consistently, two or three key presses +will narrow down the list to stuff that fits into an available time +slot. + + ---------- Footnotes ---------- + + (1) You may change the property being used with the variable +`org-effort-property'. + + (2) Please note the pitfalls of summing hierarchical data in a flat +list (*note Agenda column view::). + + +File: org, Node: Relative timer, Next: Countdown timer, Prev: Effort estimates, Up: Dates and Times + +8.6 Taking notes with a relative timer +====================================== + +When taking notes during, for example, a meeting or a video viewing, it +can be useful to have access to times relative to a starting time. Org +provides such a relative timer and make it easy to create timed notes. + +`C-c C-x . (`org-timer')' + Insert a relative time into the buffer. The first time you use + this, the timer will be started. When called with a prefix + argument, the timer is restarted. + +`C-c C-x - (`org-timer-item')' + Insert a description list item with the current relative time. + With a prefix argument, first reset the timer to 0. + +`M-<RET> (`org-insert-heading')' + Once the timer list is started, you can also use `M-<RET>' to + insert new timer items. + +`C-c C-x ,' + Pause the timer, or continue it if it is already paused + (`org-timer-pause-or-continue'). + +`C-u C-c C-x ,' + Stop the timer. After this, you can only start a new timer, not + continue the old one. This command also removes the timer from + the mode line. + +`C-c C-x 0 (`org-timer-start')' + Reset the timer without inserting anything into the buffer. By + default, the timer is reset to 0. When called with a `C-u' + prefix, reset the timer to specific starting offset. The user is + prompted for the offset, with a default taken from a timer string + at point, if any, So this can be used to restart taking notes + after a break in the process. When called with a double prefix + argument `C-u C-u', change all timer strings in the active region + by a certain amount. This can be used to fix timer strings if the + timer was not started at exactly the right moment. + + +File: org, Node: Countdown timer, Prev: Relative timer, Up: Dates and Times + +8.7 Countdown timer +=================== + +Calling `org-timer-set-timer' from an Org-mode buffer runs a countdown +timer. Use <;> from agenda buffers, <C-c C-x ;> everwhere else. + + `org-timer-set-timer' prompts the user for a duration and displays a +countdown timer in the modeline. `org-timer-default-timer' sets the +default countdown value. Giving a prefix numeric argument overrides +this default value. + + +File: org, Node: Capture - Refile - Archive, Next: Agenda Views, Prev: Dates and Times, Up: Top + +9 Capture - Refile - Archive +**************************** + +An important part of any organization system is the ability to quickly +capture new ideas and tasks, and to associate reference material with +them. Org does this using a process called capture. It also can store +files related to a task (attachments) in a special directory. Once in +the system, tasks and projects need to be moved around. Moving +completed project trees to an archive file keeps the system compact and +fast. + +* Menu: + +* Capture:: Capturing new stuff +* Attachments:: Add files to tasks +* RSS Feeds:: Getting input from RSS feeds +* Protocols:: External (e.g. Browser) access to Emacs and Org +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects + + +File: org, Node: Capture, Next: Attachments, Prev: Capture - Refile - Archive, Up: Capture - Refile - Archive + +9.1 Capture +=========== + +Org's method for capturing new items is heavily inspired by John Wiegley +excellent remember package. Up to version 6.36 Org used a special setup +for `remember.el'. `org-remember.el' is still part of Org-mode for +backward compatibility with existing setups. You can find the +documentation for org-remember at `http://orgmode.org/org-remember.pdf'. + + The new capturing setup described here is preferred and should be +used by new users. To convert your `org-remember-templates', run the +command + M-x org-capture-import-remember-templates <RET> + and then customize the new variable with `M-x customize-variable +org-capture-templates', check the result, and save the customization. +You can then use both remember and capture until you are familiar with +the new mechanism. + + Capture lets you quickly store notes with little interruption of +your work flow. The basic process of capturing is very similar to +remember, but Org does enhance it with templates and more. + +* Menu: + +* Setting up capture:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types + + +File: org, Node: Setting up capture, Next: Using capture, Prev: Capture, Up: Capture + +9.1.1 Setting up capture +------------------------ + +The following customization sets a default target file for notes, and +defines a global key(1) for capturing new material. + + (setq org-default-notes-file (concat org-directory "/notes.org")) + (define-key global-map "\C-cc" 'org-capture) + + ---------- Footnotes ---------- + + (1) Please select your own key, `C-c c' is only a suggestion. + + +File: org, Node: Using capture, Next: Capture templates, Prev: Setting up capture, Up: Capture + +9.1.2 Using capture +------------------- + +`C-c c (`org-capture')' + Call the command `org-capture'. Note that this keybinding is + global and not active by default - you need to install it. If you + have templates defined *note Capture templates::, it will offer + these templates for selection or use a new Org outline node as the + default template. It will insert the template into the target + file and switch to an indirect buffer narrowed to this new node. + You may then insert the information you want. + +`C-c C-c (`org-capture-finalize')' + Once you have finished entering information into the capture + buffer, `C-c C-c' will return you to the window configuration + before the capture process, so that you can resume your work + without further distraction. When called with a prefix arg, + finalize and then jump to the captured item. + +`C-c C-w (`org-capture-refile')' + Finalize the capture process by refiling (*note Refiling notes::) + the note to a different place. Please realize that this is a + normal refiling command that will be executed--so the cursor + position at the moment you run this command is important. If you + have inserted a tree with a parent and children, first move the + cursor back to the parent. Any prefix argument given to this + command will be passed on to the `org-refile' command. + +`C-c C-k (`org-capture-kill')' + Abort the capture process and return to the previous state. + + + You can also call `org-capture' in a special way from the agenda, +using the `k c' key combination. With this access, any timestamps +inserted by the selected capture template will default to the cursor +date in the agenda, rather than to the current date. + + To find the locations of the last stored capture, use `org-capture' +with prefix commands: + +`C-u C-c c' + Visit the target location of a cpature template. You get to + select the template in the usual way. + +`C-u C-u C-c c' + Visit the last stored capture item in its buffer. + + +File: org, Node: Capture templates, Prev: Using capture, Up: Capture + +9.1.3 Capture templates +----------------------- + +You can use templates for different types of capture items, and for +different target locations. The easiest way to create such templates is +through the customize interface. + +`C-c c C' + Customize the variable `org-capture-templates'. + + Before we give the formal description of template definitions, let's +look at an example. Say you would like to use one template to create +general TODO entries, and you want to put these entries under the +heading `Tasks' in your file `~/org/gtd.org'. Also, a date tree in the +file `journal.org' should capture journal entries. A possible +configuration would look like: + + (setq org-capture-templates + '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") + "* TODO %?\n %i\n %a") + ("j" "Journal" entry (file+datetree "~/org/journal.org") + "* %?\nEntered on %U\n %i\n %a"))) + +If you then press `C-c c t', Org will prepare the template for you like +this: + * TODO + [[file:LINK TO WHERE YOU INITIATED CAPTURE]] + +During expansion of the template, `%a' has been replaced by a link to +the location from where you called the capture command. This can be +extremely useful for deriving tasks from emails, for example. You fill +in the task definition, press `C-c C-c' and Org returns you to the same +place where you started the capture process. + +* Menu: + +* Template elements:: What is needed for a complete template entry +* Template expansion:: Filling in information about time and context + + +File: org, Node: Template elements, Next: Template expansion, Prev: Capture templates, Up: Capture templates + +9.1.3.1 Template elements +......................... + +Now lets look at the elements of a template definition. Each entry in +`org-capture-templates' is a list with the following items: + +KEYS + The keys that will select the template, as a string, characters + only, for example `"a"' for a template to be selected with a + single key, or `"bt"' for selection with two keys. When using + several keys, keys using the same prefix key must be sequential in + the list and preceded by a 2-element entry explaining the prefix + key, for example + ("b" "Templates for marking stuff to buy") + If you do not define a template for the `C' key, this key will be + used to open the customize buffer for this complex variable. + +DESCRIPTION + A short string describing the template, which will be shown during + selection. + +TYPE + The type of entry, a symbol. Valid values are: + `entry' + An Org-mode node, with a headline. Will be filed as the child + of the target entry or as a top-level entry. The target file + should be an Org-mode file. + + `item' + A plain list item, placed in the first plain list at the + target location. Again the target file should be an Org file. + + `checkitem' + A checkbox item. This only differs from the plain list item + by the default template. + + `table-line' + a new line in the first table at the target location. Where + exactly the line will be inserted depends on the properties + `:prepend' and `:table-line-pos' (see below). + + `plain' + Text to be inserted as it is. + +TARGET + Specification of where the captured item should be placed. In + Org-mode files, targets usually define a node. Entries will + become children of this node. Other types will be added to the + table or list in the body of this node. Most target + specifications contain a file name. If that file name is the + empty string, it defaults to `org-default-notes-file'. + + Valid values are: + `(file "path/to/file")' + Text will be placed at the beginning or end of that file. + + `(id "id of existing org entry")' + Filing as child of this entry, or in the body of the entry. + + `(file+headline "path/to/file" "node headline")' + Fast configuration if the target heading is unique in the + file. + + `(file+olp "path/to/file" "Level 1 heading" "Level 2" ...)' + For non-unique headings, the full path is safer. + + `(file+regexp "path/to/file" "regexp to find location")' + Use a regular expression to position the cursor. + + `(file+datetree "path/to/file")' + Will create a heading in a date tree for today's date. + + `(file+datetree+prompt "path/to/file")' + Will create a heading in a date tree, but will prompt for the + date. + + `(file+function "path/to/file" function-finding-location)' + A function to find the right location in the file. + + `(clock)' + File to the entry that is currently being clocked. + + `(function function-finding-location)' + Most general way, write your own function to find both file + and location. + +TEMPLATE + The template for creating the capture item. If you leave this + empty, an appropriate default template will be used. Otherwise + this is a string with escape codes, which will be replaced + depending on time and context of the capture call. The string + with escapes may be loaded from a template file, using the special + syntax `(file "path/to/template")'. See below for more details. + +PROPERTIES + The rest of the entry is a property list of additional options. + Recognized properties are: + `:prepend' + Normally new captured information will be appended at the + target location (last child, last table line, last list + item...). Setting this property will change that. + + `:immediate-finish' + When set, do not offer to edit the information, just file it + away immediately. This makes sense if the template only needs + information that can be added automatically. + + `:empty-lines' + Set this to the number of lines to insert before and after + the new item. Default 0, only common other value is 1. + + `:clock-in' + Start the clock in this item. + + `:clock-resume' + If starting the capture interrupted a clock, restart that + clock when finished with the capture. + + `:unnarrowed' + Do not narrow the target buffer, simply show the full buffer. + Default is to narrow it so that you only see the new + material. + + `:kill-buffer' + If the target file was not yet visited when capture was + invoked, kill the buffer again after capture is completed. + + +File: org, Node: Template expansion, Prev: Template elements, Up: Capture templates + +9.1.3.2 Template expansion +.......................... + +In the template itself, special `%'-escapes(1) allow dynamic insertion +of content: + + %^{PROMPT} prompt the user for a string and replace this sequence with it. + You may specify a default value and a completion table with + %^{prompt|default|completion2|completion3...} + The arrow keys access a prompt-specific history. + %a annotation, normally the link created with `org-store-link' + %A like `%a', but prompt for the description part + %i initial content, the region when capture is called while the + region is active. + The entire text will be indented like `%i' itself. + %t timestamp, date only + %T timestamp with date and time + %u, %U like the above, but inactive timestamps + %^t like `%t', but prompt for date. Similarly `%^T', `%^u', `%^U' + You may define a prompt like `%^{Birthday}t' + %n user name (taken from `user-full-name') + %c Current kill ring head. + %x Content of the X clipboard. + %^C Interactive selection of which kill or clip to use. + %^L Like `%^C', but insert as link. + %k title of the currently clocked task + %K link to the currently clocked task + %^g prompt for tags, with completion on tags in target file. + %^G prompt for tags, with completion all tags in all agenda files. + %^{PROP}p Prompt the user for a value for property PROP + %:keyword specific information for certain link types, see below + %[FILE] insert the contents of the file given by FILE + %(SEXP) evaluate Elisp SEXP and replace with the result + +For specific link types, the following keywords will be defined(2): + + Link type | Available keywords + -------------------+---------------------------------------------- + bbdb | %:name %:company + irc | %:server %:port %:nick + vm, wl, mh, mew, rmail | %:type %:subject %:message-id + | %:from %:fromname %:fromaddress + | %:to %:toname %:toaddress + | %:date (message date header field) + | %:date-timestamp (date as active timestamp) + | %:date-timestamp-inactive (date as inactive timestamp) + | %:fromto (either "to NAME" or "from NAME")(3) + gnus | %:group, for messages also all email fields + w3, w3m | %:url + info | %:file %:node + calendar | %:date + +To place the cursor after template expansion use: + + %? After completing the template, position cursor here. + + ---------- Footnotes ---------- + + (1) If you need one of these sequences literally, escape the `%' +with a backslash. + + (2) If you define your own link types (*note Adding hyperlink +types::), any property you store with `org-store-link-props' can be +accessed in capture templates in a similar way. + + (3) This will always be the other, not the user. See the variable +`org-from-is-user-regexp'. + + +File: org, Node: Attachments, Next: RSS Feeds, Prev: Capture, Up: Capture - Refile - Archive + +9.2 Attachments +=============== + +It is often useful to associate reference material with an outline +node/task. Small chunks of plain text can simply be stored in the +subtree of a project. Hyperlinks (*note Hyperlinks::) can establish +associations with files that live elsewhere on your computer or in the +cloud, like emails or source code files belonging to a project. +Another method is attachments, which are files located in a directory +belonging to an outline node. Org uses directories named by the unique +ID of each entry. These directories are located in the `data' +directory which lives in the same directory where your Org file +lives(1). If you initialize this directory with `git init', Org will +automatically commit changes when it sees them. The attachment system +has been contributed to Org by John Wiegley. + + In cases where it seems better to do so, you can also attach a +directory of your choice to an entry. You can also make children +inherit the attachment directory from a parent, so that an entire +subtree uses the same attached directory. + +The following commands deal with attachments: + +`C-c C-a (`org-attach')' + The dispatcher for commands related to the attachment system. + After these keys, a list of commands is displayed and you must + press an additional key to select a command: + + `a (`org-attach-attach')' + Select a file and move it into the task's attachment + directory. The file will be copied, moved, or linked, + depending on `org-attach-method'. Note that hard links are + not supported on all systems. + + `c/m/l' + Attach a file using the copy/move/link method. Note that + hard links are not supported on all systems. + + `n (`org-attach-new')' + Create a new attachment as an Emacs buffer. + + `z (`org-attach-sync')' + Synchronize the current task with its attachment directory, + in case you added attachments yourself. + + `p (`org-attach-open')' + Open current task's attachment. If there is more than one, + prompt for a file name first. Opening will follow the rules + set by `org-file-apps'. For more details, see the + information on following hyperlinks (*note Handling links::). + + `O (`org-attach-open-in-emacs')' + Also open the attachment, but force opening the file in Emacs. + + `f (`org-attach-reveal')' + Open the current task's attachment directory. + + `F (`org-attach-reveal-in-emacs')' + Also open the directory, but force using `dired' in Emacs. + + `d (`org-attach-delete-one')' + Select and delete a single attachment. + + `D (`org-attach-delete-all')' + Delete all of a task's attachments. A safer way is to open + the directory in `dired' and delete from there. + + `s (`org-attach-set-directory')' + Set a specific directory as the entry's attachment directory. + This works by putting the directory path into the + `ATTACH_DIR' property. + + `i (`org-attach-set-inherit')' + Set the `ATTACH_DIR_INHERIT' property, so that children will + use the same directory for attachments as the parent does. + + ---------- Footnotes ---------- + + (1) If you move entries or Org files from one directory to another, +you may want to configure `org-attach-directory' to contain an absolute +path. + + +File: org, Node: RSS Feeds, Next: Protocols, Prev: Attachments, Up: Capture - Refile - Archive + +9.3 RSS feeds +============= + +Org can add and change entries based on information found in RSS feeds +and Atom feeds. You could use this to make a task out of each new +podcast in a podcast feed. Or you could use a phone-based +note-creating service on the web to import tasks into Org. To access +feeds, configure the variable `org-feed-alist'. The docstring of this +variable has detailed information. Here is just an example: + + (setq org-feed-alist + '(("Slashdot" + "http://rss.slashdot.org/Slashdot/slashdot" + "~/txt/org/feeds.org" "Slashdot Entries"))) + +will configure that new items from the feed provided by +`rss.slashdot.org' will result in new entries in the file +`~/org/feeds.org' under the heading `Slashdot Entries', whenever the +following command is used: + +`C-c C-x g (`org-feed-update-all')' + +`C-c C-x g' + Collect items from the feeds configured in `org-feed-alist' and + act upon them. + +`C-c C-x G (`org-feed-goto-inbox')' + Prompt for a feed name and go to the inbox configured for this + feed. + + Under the same headline, Org will create a drawer `FEEDSTATUS' in +which it will store information about the status of items in the feed, +to avoid adding the same item several times. You should add +`FEEDSTATUS' to the list of drawers in that file: + + #+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS + + For more information, including how to read atom feeds, see +`org-feed.el' and the docstring of `org-feed-alist'. + + +File: org, Node: Protocols, Next: Refiling notes, Prev: RSS Feeds, Up: Capture - Refile - Archive + +9.4 Protocols for external access +================================= + +You can set up Org for handling protocol calls from outside +applications that are passed to Emacs through the `emacsserver'. For +example, you can configure bookmarks in your web browser to send a link +to the current page to Org and create a note from it using capture +(*note Capture::). Or you could create a bookmark that will tell Emacs +to open the local source file of a remote website you are looking at +with the browser. See +`http://orgmode.org/worg/org-contrib/org-protocol.php' for detailed +documentation and setup instructions. + + +File: org, Node: Refiling notes, Next: Archiving, Prev: Protocols, Up: Capture - Refile - Archive + +9.5 Refiling notes +================== + +When reviewing the captured data, you may want to refile some of the +entries into a different list, for example into a project. Cutting, +finding the right location, and then pasting the note is cumbersome. +To simplify this process, you can use the following special command: + +`C-c C-w (`org-refile')' + Refile the entry or region at point. This command offers possible + locations for refiling the entry and lets you select one with + completion. The item (or all items in the region) is filed below + the target heading as a subitem. Depending on + `org-reverse-note-order', it will be either the first or last + subitem. + By default, all level 1 headlines in the current buffer are + considered to be targets, but you can have more complex + definitions across a number of files. See the variable + `org-refile-targets' for details. If you would like to select a + location via a file-path-like completion along the outline path, + see the variables `org-refile-use-outline-path' and + `org-outline-path-complete-in-steps'. If you would like to be + able to create new nodes as new parents for refiling on the fly, + check the variable `org-refile-allow-creating-parent-nodes'. When + the variable `org-log-refile'(1) is set, a time stamp or a note + will be recorded when an entry has been refiled. + +`C-u C-c C-w' + Use the refile interface to jump to a heading. + +`C-u C-u C-c C-w (`org-refile-goto-last-stored')' + Jump to the location where `org-refile' last moved a tree to. + +`C-2 C-c C-w' + Refile as the child of the item currently being clocked. + +`C-0 C-c C-w or C-u C-u C-u C-c C-w' + +`C-0 C-c C-w or C-u C-u C-u C-c C-w (`org-refile-cache-clear')' + Clear the target cache. Caching of refile targets can be turned + on by setting `org-refile-use-cache'. To make the command see new + possible targets, you have to clear the cache with this command. + + ---------- Footnotes ---------- + + (1) with corresponding `#+STARTUP' keywords `logrefile', +`lognoterefile', and `nologrefile' + + +File: org, Node: Archiving, Prev: Refiling notes, Up: Capture - Refile - Archive + +9.6 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. Archiving is important to keep your working files compact and +global searches like the construction of agenda views fast. + +`C-c C-x C-a (`org-archive-subtree-default')' + Archive the current entry using the command specified in the + variable `org-archive-default-command'. + +* Menu: + +* Moving subtrees:: Moving a tree to an archive file +* Internal archiving:: Switch off a tree but keep it in the file + + +File: org, Node: Moving subtrees, Next: Internal archiving, Prev: Archiving, Up: Archiving + +9.6.1 Moving a tree to the archive file +--------------------------------------- + +The most common archiving action is to move a project tree to another +file, the archive file. + +`C-c C-x C-s or short C-c $ (`org-archive-subtree')' + Archive the subtree starting at the cursor position to the location + given by `org-archive-location'. + +`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 _not_ on a headline + when this command is invoked, the level 1 trees will be checked. + + The default archive location is a file in the same directory as the +current file, with the name derived by appending `_archive' to the +current file name. For information and examples on how to change this, +see the documentation string of the variable `org-archive-location'. +There is also an in-buffer option for setting this variable, for +example(1): + + #+ARCHIVE: %s_done:: + +If you would like to have a special ARCHIVE location for a single entry +or a (sub)tree, give the entry an `:ARCHIVE:' property with the +location as the value (*note Properties and Columns::). + + When a subtree is moved, it receives a number of special properties +that record context information like the file from where the entry +came, its outline path the archiving time etc. Configure the variable +`org-archive-save-context-info' to adjust the amount of information +added. + + ---------- Footnotes ---------- + + (1) For backward compatibility, the following also works: If there +are several such lines in a file, each specifies the archive location +for the text below it. The first such line also applies to any text +before its definition. However, using this method is _strongly_ +deprecated as it is incompatible with the outline structure of the +document. The correct method for setting multiple archive locations in +a buffer is using properties. + + +File: org, Node: Internal archiving, Prev: Moving subtrees, Up: Archiving + +9.6.2 Internal archiving +------------------------ + +If you want to just switch off (for agenda views) certain subtrees +without moving them to a different file, you can use the `ARCHIVE tag'. + + A headline that is marked with the ARCHIVE tag (*note Tags::) stays +at its location in the outline tree, but behaves in the following way: + - It does not open when you attempt to do so with a visibility + cycling command (*note Visibility cycling::). You can force + cycling archived subtrees with `C-<TAB>', or by setting the option + `org-cycle-open-archived-trees'. Also normal outline commands like + `show-all' will open archived subtrees. + + - During sparse tree construction (*note Sparse trees::), matches in + archived subtrees are not exposed, unless you configure the option + `org-sparse-tree-open-archived-trees'. + + - During agenda view construction (*note Agenda Views::), the + content of archived trees is ignored unless you configure the + option `org-agenda-skip-archived-trees', in which case these trees + will always be included. In the agenda you can press `v a' to get + archives temporarily included. + + - Archived trees are not exported (*note Exporting::), only the + headline is. Configure the details using the variable + `org-export-with-archived-trees'. + + - Archived trees are excluded from column view unless the variable + `org-columns-skip-archived-trees' is configured to `nil'. + + The following commands help manage the ARCHIVE tag: + +`C-c C-x a (`org-toggle-archive-tag')' + Toggle the ARCHIVE tag for the current headline. When the tag is + set, the headline changes to a shadowed face, and the subtree + below it is hidden. + +`C-u C-c C-x 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 _not_ on a headline when this + command is invoked, the level 1 trees will be checked. + +`C-TAB (`org-force-cycle-archived')' + Cycle a tree even if it is tagged with ARCHIVE. + +`C-c C-x A (`org-archive-to-archive-sibling')' + Move the current entry to the _Archive Sibling_. This is a + sibling of the entry with the heading `Archive' and the tag + `ARCHIVE'. The entry becomes a child of that sibling and in this + way retains a lot of its original context, including inherited + tags and approximate position in the outline. + + +File: org, Node: Agenda Views, Next: Markup, Prev: Capture - Refile - Archive, Up: Top + +10 Agenda views +*************** + +Due to the way Org 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 of open action items, or of events that are +important for a particular date, this information must be collected, +sorted and displayed in an organized way. + + Org can select items based on various criteria and display them in a +separate buffer. Seven different view types are provided: + + * an _agenda_ that is like a calendar and shows information for + specific dates, + + * a _TODO list_ that covers all unfinished action items, + + * a _match view_, showings headlines based on the tags, properties, + and TODO state associated with them, + + * a _timeline view_ that shows all events in a single Org file, in + time-sorted view, + + * a _text search view_ that shows all entries from multiple files + that contain specified keywords, + + * a _stuck projects view_ showing projects that currently don't move + along, and + + * _custom views_ that are special searches and combinations of + different views. + +The extracted information is displayed in a special _agenda buffer_. +This buffer is read-only, but provides commands to visit the +corresponding locations in the original Org 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: +`org-agenda-window-setup' and `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 +* Exporting Agenda Views:: Writing a view to a file +* Agenda column view:: Using column view for collected entries + + +File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda Views, Up: Agenda Views + +10.1 Agenda files +================= + +The information to be shown is normally collected from all _agenda +files_, the files listed in the variable `org-agenda-files'(1). If a +directory is part of this list, all files with the extension `.org' in +this directory will be part of the list. + + Thus, even if you only work with a single Org file, that file should +be put into the list(2). You can customize `org-agenda-files', but the +easiest way to maintain it is through the following commands + +`C-c [ (`org-agenda-to-front')' + 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 a prefix argument, file is added/moved to the + end. + +`C-c ] (`org-remove-file')' + Remove current file from the list of agenda files. + +`C-' (`org-cycle-agenda-files')' +`C-,' + Cycle through agenda file list, visiting one file after the other. + +`M-x org-iswitchb' + Command to use an `iswitchb'-like interface to switch to and + between Org buffers. + +The Org menu contains the current list of files and can be used to +visit any of them. + + If you would like to focus the agenda temporarily on a file not in +this list, or on just one file in the list, or even on only a subtree +in a file, then this can be done in different ways. For a single +agenda command, you may press `<' once or several times in the +dispatcher (*note Agenda dispatcher::). To restrict the agenda scope +for an extended period, use the following commands: + +`C-c C-x < (`org-agenda-set-restriction-lock')' + Permanently restrict the agenda to the current subtree. When with + a prefix argument, or with the cursor before the first headline in + a file, the agenda scope is set to the entire file. This + restriction remains in effect until removed with `C-c C-x >', or + by typing either `<' or `>' in the agenda dispatcher. If there is + a window displaying an agenda view, the new restriction takes + effect immediately. + +`C-c C-x > (`org-agenda-remove-restriction-lock')' + Remove the permanent restriction created by `C-c C-x <'. + +When working with `speedbar.el', you can use the following commands in +the Speedbar frame: +`< in the speedbar frame (`org-speedbar-set-agenda-restriction')' + Permanently restrict the agenda to the item--either an Org file or + a subtree in such a file--at the cursor in the Speedbar frame. If + there is a window displaying an agenda view, the new restriction + takes effect immediately. + +`> in the speedbar frame (`org-agenda-remove-restriction-lock')' + Lift the restriction. + + ---------- Footnotes ---------- + + (1) 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. + + (2) When using the dispatcher, pressing `<' before selecting a +command will actually limit the command to the current file, and ignore +`org-agenda-files' until the next dispatcher command. + + +File: org, Node: Agenda dispatcher, Next: Built-in agenda views, Prev: Agenda files, Up: Agenda Views + +10.2 The agenda dispatcher +========================== + +The views are created through a dispatcher, which should be bound to a +global key--for example `C-c a' (*note Installation::). In the +following we will assume that `C-c a' is indeed how the dispatcher is +accessed and list keyboard access to commands accordingly. After +pressing `C-c a', an additional letter is required to execute a +command. The dispatcher offers the following default commands: +`a' + Create the calendar-like agenda (*note Weekly/daily agenda::). + +`t / T' + Create a list of all TODO items (*note Global TODO list::). + +`m / M' + Create a list of headlines matching a TAGS expression (*note + Matching tags and properties::). + +`L' + Create the timeline view for the current buffer (*note Timeline::). + +`s' + Create a list of entries selected by a boolean expression of + keywords and/or regular expressions that must or must not occur in + the entry. + +`/' + Search for a regular expression in all agenda files and + additionally in the files listed in + `org-agenda-text-search-extra-files'. This uses the Emacs command + `multi-occur'. A prefix argument can be used to specify the + number of context lines for each match, default is 1. + +`# / !' + Create a list of stuck projects (*note Stuck projects::). + +`<' + Restrict an agenda command to the current buffer(1). After + pressing `<', you still need to press the character selecting the + command. + +`< <' + If there is an active region, restrict the following agenda + command to the region. Otherwise, restrict it to the current + subtree(2). After pressing `< <', you still need to press the + character selecting the command. + + 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. *Note Custom agenda views::. + + ---------- Footnotes ---------- + + (1) For backward compatibility, you can also press `1' to restrict +to the current buffer. + + (2) For backward compatibility, you can also press `0' to restrict +to the current region/subtree. + + +File: org, Node: Built-in agenda views, Next: Presentation and sorting, Prev: Agenda dispatcher, Up: Agenda Views + +10.3 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 +* Search view:: Find entries by searching for text +* Stuck projects:: Find projects you need to review + + +File: org, Node: Weekly/daily agenda, Next: Global TODO list, Prev: Built-in agenda views, Up: Built-in agenda views + +10.3.1 The weekly/daily agenda +------------------------------ + +The purpose of the weekly/daily _agenda_ is to act like a page of a +paper agenda, showing all the tasks for the current week or day. + +`C-c a a (`org-agenda-list')' + Compile an agenda for the current week from a list of Org files. + The agenda shows the entries for each day. With a numeric + prefix(1) (like `C-u 2 1 C-c a a') you may set the number of days + to be displayed. + + The default number of days displayed in the agenda is set by the +variable `org-agenda-span' (or the obsolete `org-agenda-ndays'). This +variable can be set to any number of days you want to see by default in +the agenda, or to a span name, such a `day', `week', `month' or `year'. + + 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 +*Note Agenda commands::. + +Calendar/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. It can be very useful to combine output from Org with the diary. + + In order to include entries from the Emacs diary into Org-mode's +agenda, you only need to customize the variable + + (setq org-agenda-include-diary t) + +After that, everything will happen automatically. All diary entries +including holidays, anniversaries, etc., will be included in the agenda +buffer created by Org-mode. <SPC>, <TAB>, and <RET> can be used from +the agenda buffer to jump to the diary file in order to edit existing +diary entries. The `i' command to insert new entries for the current +date works in the agenda buffer, as well as the commands `S', `M', and +`C' to display Sunrise/Sunset times, show lunar phases and to convert +to other calendars, respectively. `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 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 whitespace is allowed before them. For example, +the following segment of an Org file will be processed and entries will +be made in the agenda: + + * Birthdays and similar stuff + #+CATEGORY: Holiday + %%(org-calendar-holiday) ; special function for holiday names + #+CATEGORY: Ann + %%(diary-anniversary 5 14 1956)(2) Arthur Dent is %d years old + %%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old + +Anniversaries from BBDB +....................... + +If you are using the Big Brothers Database to store your contacts, you +will very likely prefer to store anniversaries in BBDB rather than in a +separate Org or diary file. Org supports this and will show BBDB +anniversaries as part of the agenda. All you need to do is to add the +following to one your your agenda files: + + * Anniversaries + :PROPERTIES: + :CATEGORY: Anniv + :END: + %%(org-bbdb-anniversaries) + + You can then go ahead and define anniversaries for a BBDB record. +Basically, you need to press `C-o anniversary <RET>' with the cursor in +a BBDB record and then add the date in the format `YYYY-MM-DD', +followed by a space and the class of the anniversary (`birthday' or +`wedding', or a format string). If you omit the class, it will default +to `birthday'. Here are a few examples, the header for the file +`org-bbdb.el' contains more detailed information. + + 1973-06-22 + 1955-08-02 wedding + 2008-04-14 %s released version 6.01 of org-mode, %d years ago + + After a change to BBDB, or for the first agenda display during an +Emacs session, the agenda display will suffer a short delay as Org +updates its hash with anniversaries. However, from then on things will +be very fast--much faster in fact than a long list of +`%%(diary-anniversary)' entries in an Org or Diary file. + +Appointment reminders +..................... + +Org can interact with Emacs appointments notification facility. To add +all the appointments of your agenda files, use the command +`org-agenda-to-appt'. This command also lets you filter through the +list of your appointments and add only those belonging to a specific +category or matching a regular expression. See the docstring for +details. + + ---------- Footnotes ---------- + + (1) For backward compatibility, the universal prefix `C-u' causes +all TODO entries to be listed before the agenda. This feature is +deprecated, use the dedicated TODO list, or a block agenda instead +(*note Block agenda::). + + (2) Note that the order of the arguments (month, day, year) depends +on the setting of `calendar-date-style'. + + +File: org, Node: Global TODO list, Next: Matching tags and properties, Prev: Weekly/daily agenda, Up: Built-in agenda views + +10.3.2 The global TODO list +--------------------------- + +The global TODO list contains all unfinished TODO items formatted and +collected into a single place. + +`C-c a t (`org-todo-list')' + Show the global TODO list. This collects the TODO items from all + agenda files (*note Agenda Views::) into a single buffer. By + default, this lists items with a state the is not a DONE state. + The buffer is in `agenda-mode', so there are commands to examine + and manipulate the TODO entries directly from that buffer (*note + Agenda commands::). + +`C-c a T (`org-todo-list')' + Like the above, but allows selection of a specific TODO keyword. + You can also do this by specifying a prefix argument to `C-c a t'. + You are prompted for a keyword, and you may also specify several + keywords by separating them with `|' as the boolean OR operator. + With a numeric prefix, the Nth keyword in `org-todo-keywords' is + selected. The `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 `3 r'. If you often need a + search for a specific keyword, define a custom command for it + (*note Agenda dispatcher::). + Matching specific TODO keywords can also be done as part of a tags + search (*note Tag searches::). + + 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 *Note Agenda commands::. + + 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: + - Some people view a TODO item that has been _scheduled_ for + execution or have a _deadline_ (*note Timestamps::) as no longer + _open_. Configure the variables + `org-agenda-todo-ignore-scheduled', + `org-agenda-todo-ignore-deadlines', + `org-agenda-todo-ignore-timestamp' and/or + `org-agenda-todo-ignore-with-date' to exclude such items from the + global TODO list. + + - 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 `org-agenda-todo-list-sublevels' to get this behavior. + + +File: org, Node: Matching tags and properties, Next: Timeline, Prev: Global TODO list, Up: Built-in agenda views + +10.3.3 Matching tags and properties +----------------------------------- + +If headlines in the agenda files are marked with _tags_ (*note Tags::), +or have properties (*note Properties and Columns::), you can select +headlines based on this metadata and collect them into an agenda +buffer. The match syntax described here also applies when creating +sparse trees with `C-c / m'. + +`C-c a m (`org-tags-view')' + 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 `+work+urgent-withboss' or + `work|home' (*note Tags::). If you often need a specific search, + define a custom command for it (*note Agenda dispatcher::). + +`C-c a M (`org-tags-view')' + Like `C-c a m', but only select headlines that are also TODO items + in a not-DONE state and force checking subitems (see variable + `org-tags-match-list-sublevels'). To exclude scheduled/deadline + items, see the variable + `org-agenda-tags-todo-honor-ignore-options'. Matching specific + TODO keywords together with a tags match is also possible, see + *Note Tag searches::. + + The commands available in the tags list are described in *Note +Agenda commands::. + +Match syntax +............ + +A search string can use Boolean operators `&' for AND and `|' for OR. +`&' binds more strongly than `|'. Parentheses are currently not +implemented. Each element in the search is either a tag, a regular +expression matching tags, or an expression like `PROPERTY OPERATOR +VALUE' with a comparison operator, accessing a property value. Each +element may be preceded by `-', to select against it, and `+' is +syntactic sugar for positive selection. The AND operator `&' is +optional when `+' or `-' is present. Here are some examples, using +only tags. + +`+work-boss' + Select headlines tagged `:work:', but discard those also tagged + `:boss:'. + +`work|laptop' + Selects lines tagged `:work:' or `:laptop:'. + +`work|laptop+night' + Like before, but require the `:laptop:' lines to be tagged also + `:night:'. + + Instead of a tag, you may also specify a regular expression enclosed +in curly braces. For example, `work+{^boss.*}' matches headlines that +contain the tag `:work:' and any tag starting with `boss'. + + You may also test for properties (*note Properties and Columns::) at +the same time as matching tags. The properties may be real properties, +or special properties that represent other metadata (*note Special +properties::). For example, the "property" `TODO' represents the TODO +keyword of the entry. Or, the "property" `LEVEL' represents the level +of an entry. So a search `+LEVEL=3+boss-TODO="DONE"' lists all level +three headlines that have the tag `boss' and are _not_ marked with the +TODO keyword DONE. In buffers with `org-odd-levels-only' set, `LEVEL' +does not count the number of stars, but `LEVEL=2' will correspond to 3 +stars etc. + + Here are more examples: +`work+TODO="WAITING"' + Select `:work:'-tagged TODO lines with the specific TODO keyword + `WAITING'. + +`work+TODO="WAITING"|home+TODO="WAITING"' + Waiting tasks both at work and at home. + + When matching properties, a number of different operators can be +used to test the value of a property. Here is a complex example: + + +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \ + +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>" + +The type of comparison will depend on how the comparison value is +written: + - If the comparison value is a plain number, a numerical comparison + is done, and the allowed operators are `<', `=', `>', `<=', `>=', + and `<>'. + + - If the comparison value is enclosed in double-quotes, a string + comparison is done, and the same operators are allowed. + + - If the comparison value is enclosed in double-quotes _and_ angular + brackets (like `DEADLINE<="<2008-12-24 18:30>"'), both values are + assumed to be date/time specifications in the standard Org way, + and the comparison will be done accordingly. Special values that + will be recognized are `"<now>"' for now (including time), and + `"<today>"', and `"<tomorrow>"' for these days at 0:00 hours, i.e. + without a time specification. Also strings like `"<+5d>"' or + `"<-2m>"' with units `d', `w', `m', and `y' for day, week, month, + and year, respectively, can be used. + + - If the comparison value is enclosed in curly braces, a regexp + match is performed, with `=' meaning that the regexp matches the + property value, and `<>' meaning that it does not match. + + So the search string in the example finds entries tagged `:work:' but +not `:boss:', which also have a priority value `A', a `:Coffee:' +property with the value `unlimited', an `Effort' property that is +numerically smaller than 2, a `:With:' property that is matched by the +regular expression `Sarah\|Denny', and that are scheduled on or after +October 11, 2008. + + Accessing TODO, LEVEL, and CATEGORY during a search is fast. +Accessing any other properties will slow down the search. However, +once you have paid the price by accessing one property, testing +additional properties is cheap again. + + You can configure Org-mode to use property inheritance during a +search, but beware that this can slow down searches considerably. See +*Note Property inheritance::, for details. + + For backward compatibility, and also for typing speed, there is also +a different way to test TODO states in a search. For this, terminate +the tags/property part of the search string (which may include several +terms connected with `|') with a `/' and then specify a Boolean +expression just for TODO keywords. The syntax is then similar to that +for tags, but should be applied with care: for example, a positive +selection on several TODO keywords cannot meaningfully be combined with +boolean AND. However, _negative selection_ combined with AND can be +meaningful. To make sure that only lines are checked that actually +have any TODO keyword (resulting in a speed-up), use `C-c a M', or +equivalently start the TODO part after the slash with `!'. Using `C-c +a M' or `/!' will not match TODO keywords in a DONE state. Examples: + +`work/WAITING' + Same as `work+TODO="WAITING"' + +`work/!-WAITING-NEXT' + Select `:work:'-tagged TODO lines that are neither `WAITING' nor + `NEXT' + +`work/!+WAITING|+NEXT' + Select `:work:'-tagged TODO lines that are either `WAITING' or + `NEXT'. + + +File: org, Node: Timeline, Next: Search view, Prev: Matching tags and properties, Up: Built-in agenda views + +10.3.4 Timeline for a single file +--------------------------------- + +The timeline summarizes all time-stamped items from a single Org-mode +file in a _time-sorted view_. The main purpose of this command is to +give an overview over events in a project. + +`C-c a L (`org-timeline')' + Show a time-sorted view of the Org file, with all time-stamped + items. When called with a `C-u' prefix, all unfinished TODO + entries (scheduled or not) are also listed under the current date. + +The commands available in the timeline buffer are listed in *Note +Agenda commands::. + + +File: org, Node: Search view, Next: Stuck projects, Prev: Timeline, Up: Built-in agenda views + +10.3.5 Search view +------------------ + +This agenda view is a general text search facility for Org-mode entries. +It is particularly useful to find notes. + +`C-c a s (`org-search-view')' + This is a special search that lets you select entries by matching + a substring or specific words using a boolean logic. + For example, the search string `computer equipment' will find entries +that contain `computer equipment' as a substring. If the two words are +separated by more space or a line break, the search will still match. +Search view can also search for specific keywords in the entry, using +Boolean logic. The search string `+computer +wifi -ethernet +-{8\.11[bg]}' will search for note entries that contain the keywords +`computer' and `wifi', but not the keyword `ethernet', and which are +also not matched by the regular expression `8\.11[bg]', meaning to +exclude both 8.11b and 8.11g. The first `+' is necessary to turn on +word search, other `+' characters are optional. For more details, see +the docstring of the command `org-search-view'. + + Note that in addition to the agenda files, this command will also +search the files listed in `org-agenda-text-search-extra-files'. + + +File: org, Node: Stuck projects, Prev: Search view, Up: Built-in agenda views + +10.3.6 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 _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. + +`C-c a # (`org-agenda-list-stuck-projects')' + List projects that are stuck. + +`C-c a !' + Customize the variable `org-stuck-projects' to define what a stuck + project is and how to find it. + + 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. + + Let's 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. Let's 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(1) `+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 + + (setq org-stuck-projects + '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@SHOP") + "\\<IGNORE\\>")) + + Note that if a project is identified as non-stuck, the subtree of +this entry will still be searched for stuck projects. + + ---------- Footnotes ---------- + + (1) *Note Tag searches::. + + +File: org, Node: Presentation and sorting, Next: Agenda commands, Prev: Built-in agenda views, Up: Agenda Views + +10.4 Presentation and sorting +============================= + +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 _prefix_ that contains the _category_ (*note +Categories::) of the item and other important information. You can +customize the prefix using the option `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 + + +File: org, Node: Categories, Next: Time-of-day specifications, Prev: Presentation and sorting, Up: Presentation and sorting + +10.4.1 Categories +----------------- + +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(1): + + #+CATEGORY: Thesis + +If you would like to have a special CATEGORY for a single entry or a +(sub)tree, give the entry a `:CATEGORY:' property with the special +category you want to apply as the value. + +The display in the agenda buffer looks best if the category is not +longer than 10 characters. + +You can set up icons for category by customizing the +`org-agenda-category-icon-alist' variable. + + ---------- Footnotes ---------- + + (1) For backward compatibility, the following also works: if there +are several such lines in a file, each specifies the category for the +text below it. The first category also applies to any text before the +first CATEGORY line. However, using this method is _strongly_ +deprecated as it is incompatible with the outline structure of the +document. The correct method for setting multiple categories in a +buffer is using a property. + + +File: org, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and sorting + +10.4.2 Time-of-day specifications +--------------------------------- + +Org-mode checks each agenda item for a time-of-day specification. The +time can be part of the timestamp that triggered inclusion into the +agenda, for example as in `<2005-05-10 Tue 19:00>'. Time ranges can be +specified with two timestamps, like +`<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 `12:45' or a `8:30-1pm'). If the agenda integrates +the Emacs diary (*note 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: + + 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 Marvin escorts the Hitchhikers to the bridge + + If the agenda is in single-day mode, or for the display of today, the +timed entries are embedded in a time grid, like + + 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 Marvin escorts the Hitchhikers to the bridge + + The time grid can be turned on and off with the variable +`org-agenda-use-time-grid', and can be configured with +`org-agenda-time-grid'. + + +File: org, Node: Sorting of agenda items, Prev: Time-of-day specifications, Up: Presentation and sorting + +10.4.3 Sorting of agenda items +------------------------------ + +Before being inserted into a view, the items are sorted. How this is +done depends on the type of view. + * 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 _schedule_ for the day. After + that, items remain grouped in categories, in the sequence given by + `org-agenda-files'. Within each category, items are sorted by + priority (*note Priorities::), which is composed of the base + priority (2000 for priority `A', 1000 for `B', and 0 for `C'), + plus additional increments for overdue scheduled or deadline items. + + * For the TODO list, items remain in the order of categories, but + within each category, sorting takes place according to priority + (*note Priorities::). The priority used for sorting derives from + the priority cookie, with additions depending on how close an item + is to its due or scheduled date. + + * For tags matches, items are not sorted at all, but just appear in + the sequence in which they are found in the agenda files. + + Sorting can be customized using the variable +`org-agenda-sorting-strategy', and may also include criteria based on +the estimated effort of an entry (*note Effort estimates::). + + +File: org, Node: Agenda commands, Next: Custom agenda views, Prev: Presentation and sorting, Up: Agenda Views + +10.5 Commands in the 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. + +Motion +...... + +`n (`org-agenda-next-line')' + Next line (same as <up> and `C-p'). + +`p (`org-agenda-previous-line')' + Previous line (same as <down> and `C-n'). + +View/Go to Org file +................... + +`<SPC> or mouse-3 (`org-agenda-show-and-scroll-up')' + Display the original location of the item in another window. With + prefix arg, make sure that the entire entry is made visible in the + outline, not only the heading. + +`L (`org-agenda-recenter')' + Display original location and recenter that window. + +`<TAB> or mouse-2 (`org-agenda-goto')' + Go to the original location of the item in another window. + +`<RET> (`org-agenda-switch-to')' + Go to the original location of the item and delete other windows. + +`F (`org-agenda-follow-mode')' + 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 + `org-agenda-start-with-follow-mode'. + +`C-c C-x b (`org-agenda-tree-to-indirect-buffer')' + Display the entire subtree of the current item in an indirect + buffer. With a numeric prefix argument N, go up to level N and + then take that tree. If N is negative, go up that many levels. + With a `C-u' prefix, do not remove the previously used indirect + buffer. + +`C-c C-o (`org-agenda-open-link')' + Follow a link in the entry. This will offer a selection of any + links in the text belonging to the referenced Org node. If there + is only one link, it will be followed without a selection prompt. + +Change display +.............. + +`o' + Delete other windows. + +`v d or short d (`org-aganda-day-view')' +`v w or short w (`org-aganda-day-view')' +`v m (`org-agenda-month-view')' +`v y (`org-agenda-month-year')' + Switch to day/week/month/year view. When switching to day or week + view, this setting becomes the default for subsequent agenda + commands. Since month and year views are slow to create, they do + not become the default. A numeric prefix argument may be used to + jump directly to a specific day of the year, ISO week, month, or + year, respectively. For example, `32 d' jumps to February 1st, `9 + w' to ISO week number 9. When setting day, week, or month view, a + year may be encoded in the prefix argument as well. For example, + `200712 w' will jump to week 12 in 2007. If such a year + specification has only one or two digits, it will be mapped to the + interval 1938-2037. + +`f (`org-agenda-later')' + Go forward in time to display the following + `org-agenda-current-span' days. For example, if the display + covers a week, switch to the following week. With prefix arg, go + forward that many times `org-agenda-current-span' days. + +`b (`org-agenda-earlier')' + Go backward in time to display earlier dates. + +`. (`org-agenda-goto-today')' + Go to today. + +`j (`org-agenda-goto-date')' + Prompt for a date and go there. + +`J (`org-agenda-clock-goto')' + Go to the currently clocked-in task in the agenda buffer. + +`D (`org-agenda-toggle-diary')' + Toggle the inclusion of diary entries. See *Note Weekly/daily + agenda::. + +`v l or short l (`org-agenda-log-mode')' + Toggle Logbook mode. In Logbook mode, entries that were marked + DONE while logging was on (variable `org-log-done') are shown in + the agenda, as are entries that have been clocked on that day. + You can configure the entry types that should be included in log + mode using the variable `org-agenda-log-mode-items'. When called + with a `C-u' prefix, show all possible logbook entries, including + state changes. When called with two prefix args `C-u C-u', show + only logging information, nothing else. `v L' is equivalent to + `C-u v l'. + +`v [ or short [ (`org-agenda-manipulate-query-add')' + Include inactive timestamps into the current view. Only for + weekly/daily agenda and timeline views. + +`v a (`org-agenda-archives-mode')' +`v A (`org-agenda-archives-mode 'files')' + Toggle Archives mode. In Archives mode, trees that are marked + `ARCHIVED' are also scanned when producing the agenda. When you + use the capital `A', even all archive files are included. To exit + archives mode, press `v a' again. + +`v R or short R (`org-agenda-clockreport-mode')' + Toggle Clockreport mode. In Clockreport mode, the daily/weekly + agenda will always show a table with the clocked times for the + timespan and file scope covered by the current agenda view. The + initial setting for this mode in new agenda buffers can be set + with the variable `org-agenda-start-with-clockreport-mode'. By + using a prefix argument when toggling this mode (i.e. `C-u R'), + the clock table will not show contributions from entries that are + hidden by agenda filtering(1). + +`v E or short E (`org-agenda-entry-text-mode')' + Toggle entry text mode. In entry text mode, a number of lines + from the Org outline node referenced by an agenda line will be + displayed below the line. The maximum number of lines is given by + the variable `org-agenda-entry-text-maxlines'. Calling this + command with a numeric prefix argument will temporarily modify + that number to the prefix value. + +`G (`org-agenda-toggle-time-grid')' + Toggle the time grid on and off. See also the variables + `org-agenda-use-time-grid' and `org-agenda-time-grid'. + +`r (`org-agenda-rodo')' + Recreate the agenda buffer, for example to reflect the changes + after modification of the timestamps of items with `S-<left>' and + `S-<right>'. When the buffer is the global TODO list, a prefix + argument is interpreted to create a selective list for a specific + TODO keyword. + +`g (`org-agenda-rodo')' + Same as `r'. + +`C-x C-s or short s (`org-save-all-org-buffers')' + Save all Org buffers in the current Emacs session, and also the + locations of IDs. + +`C-c C-x C-c (`org-agenda-columns')' + Invoke column view (*note Column view::) in the agenda buffer. + The column view format is taken from the entry at point, or (if + there is no entry at point), from the first entry in the agenda + view. So whatever the format for that entry would be in the + original buffer (taken from a property, from a `#+COLUMNS' line, + or from the default variable `org-columns-default-format'), will + be used in the agenda. + +`C-c C-x > (`org-agenda-remove-restriction-lock')' + Remove the restriction lock on the agenda, if it is currently + restricted to a file or subtree (*note Agenda files::). + +Secondary filtering and query editing +..................................... + +`/ (`org-agenda-filter-by-tag')' + Filter the current agenda view with respect to a tag and/or effort + estimates. The difference between this and a custom agenda + command is that filtering is very fast, so that you can switch + quickly between different filters without having to recreate the + agenda.(2) + + You will be prompted for a tag selection letter; <SPC> will mean + any tag at all. Pressing <TAB> at that prompt will offer use + completion to select a tag (including any tags that do not have a + selection character). The command then hides all entries that do + not contain or inherit this tag. When called with prefix arg, + remove the entries that _do_ have the tag. A second `/' at the + prompt will turn off the filter and unhide any hidden entries. If + the first key you press is either `+' or `-', the previous filter + will be narrowed by requiring or forbidding the selected + additional tag. Instead of pressing `+' or `-' after `/', you can + also immediately use the `\' command. + + In order to filter for effort estimates, you should set up allowed + efforts globally, for example + (setq org-global-properties + '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) + You can then filter for an effort by first typing an operator, one + of `<', `>', and `=', and then the one-digit index of an effort + estimate in your array of allowed values, where `0' means the 10th + value. The filter will then restrict to entries with effort + smaller-or-equal, equal, or larger-or-equal than the selected + value. If the digits 0-9 are not used as fast access keys to + tags, you can also simply press the index digit directly without + an operator. In this case, `<' will be assumed. For application + of the operator, entries without a defined effort will be treated + according to the value of `org-sort-agenda-noeffort-is-high'. To + filter for tasks without effort definition, press `?' as the + operator. + + Org also supports automatic, context-aware tag filtering. If the + variable `org-agenda-auto-exclude-function' is set to a + user-defined function, that function can decide which tags should + be excluded from the agenda automatically. Once this is set, the + `/' command then accepts `RET' as a sub-option key and runs the + auto exclusion logic. For example, let's say you use a `Net' tag + to identify tasks which need network access, an `Errand' tag for + errands in town, and a `Call' tag for making phone calls. You + could auto-exclude these tags based on the availability of the + Internet, and outside of business hours, with something like this: + + (defun org-my-auto-exclude-function (tag) + (and (cond + ((string= tag "Net") + (/= 0 (call-process "/sbin/ping" nil nil nil + "-c1" "-q" "-t1" "mail.gnu.org"))) + ((or (string= tag "Errand") (string= tag "Call")) + (let ((hour (nth 2 (decode-time)))) + (or (< hour 8) (> hour 21))))) + (concat "-" tag))) + + (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function) + +`,org-agenda-filter-by-tag-refine (`')' + Narrow the current agenda filter by an additional condition. When + called with prefix arg, remove the entries that _do_ have the tag, + or that do match the effort criterion. You can achieve the same + effect by pressing `+' or `-' as the first key after the `/' + command. + +`[ ] { }' + + in search view + add new search words (`[' and `]') or new regular expressions + (`{' and `}') to the query string. The opening bracket/brace + will add a positive search term prefixed by `+', indicating + that this search term must occur/match in the entry. The + closing bracket/brace will add a negative search term which + must not occur/match in the entry for it to be selected. + +Remote editing +.............. + +`0-9' + Digit argument. + +`C-_ (`org-agenda-undo')' + Undo a change due to a remote editing command. The change is + undone both in the agenda buffer and in the remote buffer. + +`t (`org-agenda-todo')' + Change the TODO state of the item, both in the agenda and in the + original org file. + +`C-S-<right> (`org-agenda-todo-nextset')' + +`C-S-<left> (`org-agenda-todo-previousset')' + Switch to the next/previous set of TODO keywords. + +`C-k (`org-agenda-kill')' + Delete the current agenda item along with the entire subtree + belonging to it in the original Org file. If the text to be + deleted remotely is longer than one line, the kill needs to be + confirmed by the user. See variable `org-agenda-confirm-kill'. + +`C-c C-w (`org-agenda-refile')' + Refile the entry at point. + +`C-c C-x C-a or short a (`org-agenda-archive-default-with-confirmation')' + Archive the subtree corresponding to the entry at point using the + default archiving command set in `org-archive-default-command'. + When using the `a' key, confirmation will be required. + +`C-c C-x a (`org-agenda-toggle-archive-tag')' + Toggle the ARCHIVE tag for the current headline. + +`C-c C-x A (`org-agenda-archive-to-archive-sibling')' + Move the subtree corresponding to the current entry to its _archive + sibling_. + +`C-c C-x C-s or short $ (`org-agenda-archive')' + Archive the subtree corresponding to the current headline. This + means the entry will be moved to the configured archive location, + most likely a different file. + +`T (`org-agenda-show-tags')' + Show all tags associated with the current item. This is useful if + you have turned off `org-agenda-show-inherited-tags', but still + want to see all tags of a headline occasionally. + +`: (`org-agenda-set-tags')' + Set tags for the current headline. If there is an active region + in the agenda, change a tag for all headings in the region. + +`,' + Set the priority for the current item (`org-agenda-priority'). + Org-mode prompts for the priority character. If you reply with + <SPC>, the priority cookie is removed from the entry. + +`P (`org-agenda-show-priority')' + Display weighted priority of current item. + +`+ or S-<up> (`org-agenda-priority-up')' + Increase the priority of the current item. The priority is + changed in the original buffer, but the agenda is not resorted. + Use the `r' key for this. + +`- or S-<down> (`org-agenda-priority-down')' + Decrease the priority of the current item. + +`z or C-c C-z (`org-agenda-add-note')' + Add a note to the entry. This note will be recorded, and then + filed to the same location where state change notes are put. + Depending on `org-log-into-drawer', this may be inside a drawer. + +`C-c C-a (`org-attach')' + Dispatcher for all command related to attachments. + +`C-c C-s (`org-agenda-schedule')' + Schedule this item. With prefix arg remove the scheduling + timestamp + +`C-c C-d (`org-agenda-deadline')' + Set a deadline for this item. With prefix arg remove the deadline. + +`k (`org-agenda-action')' + Agenda actions, to set dates for selected items to the cursor date. + This command also works in the calendar! The command prompts for + an additional key: + m Mark the entry at point for action. You can also make entries + in Org files with `C-c C-x C-k'. + d Set the deadline of the marked entry to the date at point. + s Schedule the marked entry at the date at point. + r Call `org-capture' with the cursor date as default date. + Press `r' afterward to refresh the agenda and see the effect of the + command. + +`S-<right> (`org-agenda-do-date-later')' + Change the timestamp associated with the current line by one day + into the future. With a numeric prefix argument, change it by + that many days. For example, `3 6 5 S-<right>' will change it by + a year. With a `C-u' prefix, change the time by one hour. If you + immediately repeat the command, it will continue to change hours + even without the prefix arg. With a double `C-u C-u' prefix, do + the same for changing minutes. The stamp is changed in the + original Org file, but the change is not directly reflected in the + agenda buffer. Use `r' or `g' to update the buffer. + +`S-<left> (`org-agenda-do-date-earlier')' + Change the timestamp associated with the current line by one day + into the past. + +`> (`org-agenda-date-prompt')' + Change the timestamp associated with the current line. The key + `>' has been chosen, because it is the same as `S-.' on my + keyboard. + +`I (`org-agenda-clock-in')' + Start the clock on the current item. If a clock is running + already, it is stopped first. + +`O (`org-agenda-clock-out')' + Stop the previously started clock. + +`X (`org-agenda-clock-cancel')' + Cancel the currently running clock. + +`J (`org-agenda-clock-goto')' + Jump to the running clock in another window. + +Bulk remote editing selected entries +.................................... + +`m (`org-agenda-bulk-mark')' + Mark the entry at point for bulk action. With prefix arg, mark + that many successive entries. + +`u (`org-agenda-bulk-unmark')' + Unmark entry for bulk action. + +`U (`org-agenda-bulk-remove-all-marks')' + Unmark all marked entries for bulk action. + +`B (`org-agenda-bulk-action')' + Bulk action: act on all marked entries in the agenda. This will + prompt for another key to select the action to be applied. The + prefix arg to `B' will be passed through to the `s' and `d' + commands, to bulk-remove these special timestamps. + r Prompt for a single refile target and move all entries. The entries + will no longer be in the agenda; refresh (`g') to bring them back. + $ Archive all selected entries. + A Archive entries by moving them to their respective archive siblings. + t Change TODO state. This prompts for a single TODO keyword and + changes the state of all selected entries, bypassing blocking and + suppressing logging notes (but not time stamps). + + Add a tag to all selected entries. + - Remove a tag from all selected entries. + s Schedule all items to a new date. To shift existing schedule dates + by a fixed number of days, use something starting with double plus + at the prompt, for example `++8d' or `++2w'. + S Reschedule randomly by N days. N will be prompted for. With prefix + arg (`C-u B S'), scatter only accross weekdays. + d Set deadline to a specific date. + +Calendar commands +................. + +`c (`org-agenda-goto-calendar')' + Open the Emacs calendar and move to the date at the agenda cursor. + +`c (`org-calendar-goto-agenda')' + When in the calendar, compute and show the Org-mode agenda for the + date at the cursor. + +`i (`org-agenda-diary-entry')' + Insert a new entry into the diary, using the date at the cursor + and (for block entries) the date at the mark. This will add to + the Emacs diary file(3), in a way similar to the `i' command in + the calendar. The diary file will pop up in another window, where + you can add the entry. + + If you configure `org-agenda-diary-file' to point to an Org-mode + file, Org will create entries (in org-mode syntax) in that file + instead. Most entries will be stored in a date-based outline tree + that will later make it easy to archive appointments from previous + months/years. The tree will be built under an entry with a + `DATE_TREE' property, or else with years as top-level entries. + Emacs will prompt you for the entry text--if you specify it, the + entry will be created in `org-agenda-diary-file' without further + interaction. If you directly press <RET> at the prompt without + typing text, the target file will be shown in another window for + you to finish the entry there. See also the `k r' command. + +`M (`org-agenda-phases-of-moon')' + Show the phases of the moon for the three months around current + date. + +`S (`org-agenda-sunrise-sunset')' + Show sunrise and sunset times. The geographical location must be + set with calendar variables, see the documentation for the Emacs + calendar. + +`C (`org-agenda-convert-date')' + Convert the date at cursor into many other cultural and historic + calendars. + +`H (`org-agenda-holidays')' + Show holidays for three months around the cursor date. + +`M-x org-export-icalendar-combine-agenda-files' + Export a single iCalendar file containing entries from all agenda + files. This is a globally available command, and also available + in the agenda menu. + +Exporting to a file +................... + +`C-x C-w (`org-write-agenda')' + Write the agenda view to a file. Depending on the extension of + the selected file name, the view will be exported as HTML + (extension `.html' or `.htm'), Postscript (extension `.ps'), PDF + (extension `.pdf'), and plain text (any other extension). When + called with a `C-u' prefix argument, immediately open the newly + created file. Use the variable `org-agenda-exporter-settings' to + set options for `ps-print' and for `htmlize' to be used during + export. + +Quit and Exit +............. + +`q (`org-agenda-quit')' + Quit agenda, remove the agenda buffer. + +`x (`org-agenda-exit')' + 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. + + ---------- Footnotes ---------- + + (1) Only tags filtering will be respected here, effort filtering is +ignored. + + (2) Custom commands can preset a filter by binding the variable +`org-agenda-filter-preset' as an option. This filter will then be +applied to the view and persist as a basic filter through refreshes and +more secondary filtering. The filter is a global property of the +entire agenda view--in a block agenda, you should only set this in the +global options section, not in the section of an individual block. + + (3) This file is parsed for the agenda when +`org-agenda-include-diary' is set. + + +File: org, Node: Custom agenda views, Next: Exporting Agenda Views, Prev: Agenda commands, Up: Agenda Views + +10.6 Custom agenda views +======================== + +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 (*note 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 + + +File: org, Node: Storing searches, Next: Block agenda, Prev: Custom agenda views, Up: Custom agenda views + +10.6.1 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). Custom commands are configured in the variable +`org-agenda-custom-commands'. You can customize this variable, for +example by pressing `C-c a C'. You can also directly set it with Emacs +Lisp in `.emacs'. The following example contains all valid search +types: + + (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\\>") + ("h" . "HOME+Name tags searches") ; description for "h" prefix + ("hl" tags "+home+Lisa") + ("hp" tags "+home+Peter") + ("hk" tags "+home+Kim"))) + +The initial string in each entry defines the keys you have to press +after the dispatcher command `C-c a' in order to access the command. +Usually this will be just a single character, but if you have many +similar commands, you can also define two-letter combinations where the +first character is the same in several combinations and serves as a +prefix key(1). 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: + +`C-c a w' + as a global search for TODO entries with `WAITING' as the TODO + keyword + +`C-c a W' + as the same search, but only in the current buffer and displaying + the results as a sparse tree + +`C-c a u' + as a global tags search for headlines marked `:boss:' but not + `:urgent:' + +`C-c a v' + as the same search as `C-c a u', but limiting the search to + headlines that are also TODO items + +`C-c a U' + as the same search as `C-c a u', but only in the current buffer and + displaying the result as a sparse tree + +`C-c a f' + to create a sparse tree (again: current buffer only) with all + entries containing the word `FIXME' + +`C-c a h' + as a prefix command for a HOME tags search where you have to press + an additional key (`l', `p' or `k') to select a name (Lisa, Peter, + or Kim) as additional tag to match. + + ---------- Footnotes ---------- + + (1) You can provide a description for a prefix key by inserting a +cons cell with the prefix and the description. + + +File: org, Node: Block agenda, Next: Setting Options, Prev: Storing searches, Up: Custom agenda views + +10.6.2 Block agenda +------------------- + +Another possibility is the construction of agenda views that comprise +the results of _several_ commands, each of which creates a block in the +agenda buffer. The available commands include `agenda' for the daily +or weekly agenda (as created with `C-c a a'), `alltodo' for the global +TODO list (as constructed with `C-c a t'), and the matching commands +discussed above: `todo', `tags', and `tags-todo'. Here are two +examples: + + (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"))))) + +This will define `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 +`home', and also all lines tagged with `garden'. Finally the command +`C-c a o' provides a similar view for office tasks. + + +File: org, Node: Setting Options, Prev: Block agenda, Up: Custom agenda views + +10.6.3 Setting options for custom commands +------------------------------------------ + +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 `org-agenda-custom-commands'. For example: + + (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))) + ("N" search "" + ((org-agenda-files '("~org/notes.org")) + (org-agenda-text-search-extra-files nil))))) + +Now the `C-c a w' command will sort the collected entries only by +priority, and the prefix format is modified to just say ` Mixed: ' +instead of giving the category of the entry. The sparse tags tree of +`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. The command `C-c a N' will do a text search limited to only a +single file. + + For command sets creating a block agenda, +`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 (*note Block agenda::), let's change the sorting strategy +for the `C-c a h' commands to `priority-down', but let's sort the +results for GARDEN tags query in the opposite order, `priority-up'. +This would look like this: + + (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"))))) + + As you see, the values and parentheses 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 _values_ are just Lisp expressions. So if the +value is a string, you need to add the double-quotes around the value +yourself. + + +File: org, Node: Exporting Agenda Views, Next: Agenda column view, Prev: Custom agenda views, Up: Agenda Views + +10.7 Exporting Agenda Views +=========================== + +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(1), Postscript, PDF(2), +and iCalendar files. If you want to do this only occasionally, use the +command + +`C-x C-w (`org-write-agenda')' + Write the agenda view to a file. Depending on the extension of + the selected file name, the view will be exported as HTML + (extension `.html' or `.htm'), Postscript (extension `.ps'), + iCalendar (extension `.ics'), or plain text (any other extension). + Use the variable `org-agenda-exporter-settings' to set options + for `ps-print' and for `htmlize' to be used during export, for + example + + (setq org-agenda-exporter-settings + '((ps-number-of-columns 2) + (ps-landscape-mode t) + (org-agenda-add-entry-text-maxlines 5) + (htmlize-output-type 'css))) + + If you need to export certain agenda views frequently, you can +associate any custom agenda command with a list of output file names +(3). Here is an example that first defines 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 file names for them as well. File names can be relative to the +current working directory, or absolute. + + (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" "~/calendars/office.ics")))) + + The extension of the file name determines the type of export. If it +is `.html', Org-mode will use the `htmlize.el' package to convert the +buffer to HTML and save it to this file name. If the extension is +`.ps', `ps-print-buffer-with-faces' is used to produce Postscript +output. If the extension is `.ics', iCalendar export is run export +over all files that were used to construct the agenda, and limit the +export to entries listed in the agenda. Any other extension produces a +plain ASCII file. + + The export files are _not_ created when you use one of those +commands interactively because this might use too much overhead. +Instead, there is a special command to produce _all_ specified files in +one step: + +`C-c a e (`org-store-agenda-views')' + Export all agenda views that have export file names associated with + them. + + You can use the options section of the custom agenda commands to also +set options for the export commands. For example: + + (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")))) + +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 +`org-agenda-exporter-settings' will also apply, but the settings in +`org-agenda-custom-commands' take precedence. + +From the command line you may also use + emacs -f org-batch-store-agenda-views -kill + or, if you need to modify some parameters(4) + emacs -eval '(org-batch-store-agenda-views \ + org-agenda-span month \ + org-agenda-start-day "2007-11-01" \ + org-agenda-include-diary nil \ + org-agenda-files (quote ("~/org/project.org")))' \ + -kill + which will create the agenda views restricted to the file +`~/org/project.org', without diary entries and with a 30-day extent. + + You can also extract agenda information in a way that allows further +processing by other programs. See *Note Extracting agenda +information::, for more information. + + ---------- Footnotes ---------- + + (1) You need to install Hrvoje Niksic's `htmlize.el'. + + (2) To create PDF output, the ghostscript `ps2pdf' utility must be +installed on the system. Selecting a PDF file with also create the +postscript file. + + (3) 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 file names. + + (4) Quoting depends on the system you use, please check the FAQ for +examples. + + +File: org, Node: Agenda column view, Prev: Exporting Agenda Views, Up: Agenda Views + +10.8 Using column view in the agenda +==================================== + +Column view (*note Column view::) is normally used to view and edit +properties embedded in the hierarchical structure of an Org file. It +can be quite useful to use column view also from the agenda, where +entries are collected by certain criteria. + +`C-c C-x C-c (`org-agenda-columns')' + Turn on column view in the agenda. + + To understand how to use this properly, it is important to realize +that the entries in the agenda are no longer in their proper outline +environment. This causes the following issues: + + 1. Org needs to make a decision which `COLUMNS' format to use. Since + the entries in the agenda are collected from different files, and + different files may have different `COLUMNS' formats, this is a + non-trivial problem. Org first checks if the variable + `org-overriding-columns-format' is currently set, and if so, takes + the format from there. Otherwise it takes the format associated + with the first item in the agenda, or, if that item does not have + a specific format (defined in a property, or in its file), it uses + `org-columns-default-format'. + + 2. If any of the columns has a summary type defined (*note Column + attributes::), turning on column view in the agenda will visit all + relevant agenda files and make sure that the computations of this + property are up to date. This is also true for the special + `CLOCKSUM' property. Org will then sum the values displayed in + the agenda. In the daily/weekly agenda, the sums will cover a + single day; in all other views they cover the entire block. It is + vital to realize that the agenda may show the same entry _twice_ + (for example as scheduled and as a deadline), and it may show two + entries from the same hierarchy (for example a _parent_ and its + _child_). In these cases, the summation in the agenda will lead + to incorrect results because some values will count double. + + 3. When the column view in the agenda shows the `CLOCKSUM', that is + always the entire clocked time for this item. So even in the + daily/weekly agenda, the clocksum listed in column view may + originate from times outside the current view. This has the + advantage that you can compare these values with a column listing + the planned total effort for a task--one of the major applications + for column view in the agenda. If you want information about + clocked time in the displayed period use clock table mode (press + `R' in the agenda). + + +File: org, Node: Markup, Next: Exporting, Prev: Agenda Views, Up: Top + +11 Markup for rich export +************************* + +When exporting Org-mode documents, the exporter tries to reflect the +structure of the document as accurately as possible in the backend. +Since export targets like HTML, LaTeX, or DocBook allow much richer +formatting, Org-mode has rules on how to prepare text for rich export. +This section summarizes the markup rules used in an Org-mode buffer. + +* Menu: + +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Index entries:: Making an index +* Macro replacement:: Use macros to create complex output +* Embedded LaTeX:: LaTeX can be freely used inside Org documents + + +File: org, Node: Structural markup elements, Next: Images and tables, Prev: Markup, Up: Markup + +11.1 Structural markup elements +=============================== + +* Menu: + +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Initial text:: Text before the first heading? +* Lists:: Lists +* Paragraphs:: Paragraphs +* Footnote markup:: Footnotes +* Emphasis and monospace:: Bold, italic, etc. +* Horizontal rules:: Make a line +* Comment lines:: What will *not* be exported + + +File: org, Node: Document title, Next: Headings and sections, Prev: Structural markup elements, Up: Structural markup elements + +Document title +-------------- + +The title of the exported document is taken from the special line + + #+TITLE: This is the title of the document + +If this line does not exist, the title is derived from the first +non-empty, non-comment line in the buffer. If no such line exists, or +if you have turned off exporting of the text before the first headline +(see below), the title will be the file name without extension. + + If you are exporting only a subtree by marking is as the region, the +heading of the subtree will become the title of the document. If the +subtree has a property `EXPORT_TITLE', that will take precedence. + + +File: org, Node: Headings and sections, Next: Table of contents, Prev: Document title, Up: Structural markup elements + +Headings and sections +--------------------- + +The outline structure of the document as described in *Note Document +Structure::, forms the basis for defining sections of the exported +document. However, since the outline structure is also used for (for +example) lists of tasks, only the first three outline levels will be +used as headings. Deeper levels will become itemized lists. You can +change the location of this switch globally by setting the variable +`org-export-headline-levels', or on a per-file basis with a line + + #+OPTIONS: H:4 + + +File: org, Node: Table of contents, Next: Initial text, Prev: Headings and sections, Up: Structural markup elements + +Table of contents +----------------- + +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 `[TABLE-OF-CONTENTS]' on a line by itself +at the desired location. The depth of the table of contents is by +default the same as the number of headline levels, but you can choose a +smaller number, or turn off the table of contents entirely, by +configuring the variable `org-export-with-toc', or on a per-file basis +with a line like + + #+OPTIONS: toc:2 (only to two levels in TOC) + #+OPTIONS: toc:nil (no TOC at all) + + +File: org, Node: Initial text, Next: Lists, Prev: Table of contents, Up: Structural markup elements + +Text before the first headline +------------------------------ + +Org-mode normally exports the text before the first headline, and even +uses the first line as the document title. The text will be fully +marked up. If you need to include literal HTML, LaTeX, or DocBook +code, use the special constructs described below in the sections for +the individual exporters. + + Some people like to use the space before the first headline for +setup and internal links and therefore would like to control the +exported text before the first headline in a different way. You can do +so by setting the variable `org-export-skip-text-before-1st-heading' to +`t'. On a per-file basis, you can get the same effect with `#+OPTIONS: +skip:t'. + +If you still want to have some text before the first headline, use the +`#+TEXT' construct: + + #+OPTIONS: skip:t + #+TEXT: This text will go before the *first* headline. + #+TEXT: [TABLE-OF-CONTENTS] + #+TEXT: This goes between the table of contents and the first headline + + +File: org, Node: Lists, Next: Paragraphs, Prev: Initial text, Up: Structural markup elements + +Lists +----- + +Plain lists as described in *Note Plain lists::, are translated to the +backend's syntax for such lists. Most backends support unordered, +ordered, and description lists. + + +File: org, Node: Paragraphs, Next: Footnote markup, Prev: Lists, Up: Structural markup elements + +Paragraphs, line breaks, and quoting +------------------------------------ + +Paragraphs are separated by at least one empty line. If you need to +enforce a line break within a paragraph, use `\\' at the end of a line. + + To keep the line breaks in a region, but otherwise use normal +formatting, you can use this construct, which can also be used to +format poetry. + + #+BEGIN_VERSE + Great clouds overhead + Tiny black birds rise and fall + Snow covers Emacs + + -- AlexSchroeder + #+END_VERSE + + When quoting a passage from another document, it is customary to +format this as a paragraph that is indented on both the left and the +right margin. You can include quotations in Org-mode documents like +this: + + #+BEGIN_QUOTE + Everything should be made as simple as possible, + but not any simpler -- Albert Einstein + #+END_QUOTE + + If you would like to center some text, do it like this: + #+BEGIN_CENTER + Everything should be made as simple as possible, \\ + but not any simpler + #+END_CENTER + + +File: org, Node: Footnote markup, Next: Emphasis and monospace, Prev: Paragraphs, Up: Structural markup elements + +Footnote markup +--------------- + +Footnotes defined in the way described in *Note Footnotes::, will be +exported by all backends. Org allows multiple references to the same +note, and different backends support this to varying degrees. + + +File: org, Node: Emphasis and monospace, Next: Horizontal rules, Prev: Footnote markup, Up: Structural markup elements + +Emphasis and monospace +---------------------- + +You can make words *bold*, /italic/, _underlined_, `=code=' and +`~verbatim~', and, if you must, `+strike-through+'. Text in the code +and verbatim string is not processed for Org-mode specific syntax; it +is exported verbatim. + + +File: org, Node: Horizontal rules, Next: Comment lines, Prev: Emphasis and monospace, Up: Structural markup elements + +Horizontal rules +---------------- + +A line consisting of only dashes, and at least 5 of them, will be +exported as a horizontal line (`<hr/>' in HTML). + + +File: org, Node: Comment lines, Prev: Horizontal rules, Up: Structural markup elements + +Comment lines +------------- + +Lines starting with `#' in column zero are treated as comments and will +never be exported. If you want an indented line to be treated as a +comment, start it with `#+ '. Also entire subtrees starting with the +word `COMMENT' will never be exported. Finally, regions surrounded by +`#+BEGIN_COMMENT' ... `#+END_COMMENT' will not be exported. + +`C-c ;' + Toggle the COMMENT keyword at the beginning of an entry. + + +File: org, Node: Images and tables, Next: Literal examples, Prev: Structural markup elements, Up: Markup + +11.2 Images and Tables +====================== + +Both the native Org-mode tables (*note Tables::) and tables formatted +with the `table.el' package will be exported properly. For Org-mode +tables, the lines before the first horizontal separator line will +become table header lines. You can use the following lines somewhere +before the table to assign a caption and a label for cross references, +and in the text you can refer to the object with `\ref{tab:basic-data}': + + #+CAPTION: This is the caption for the next table (or link) + #+LABEL: tbl:basic-data + | ... | ...| + |-----|----| + + Some backends (HTML, LaTeX, and DocBook) allow you to directly +include images into the exported document. Org does this, if a link to +an image files does not have a description part, for example +`[[./img/a.jpg]]'. If you wish to define a caption for the image and +maybe a label for internal cross references, make sure that the link is +on a line by itself and precede it with `#+CAPTION' and `#+LABEL' as +follows: + + #+CAPTION: This is the caption for the next figure link (or table) + #+LABEL: fig:SED-HR4049 + [[./img/a.jpg]] + + You may also define additional attributes for the figure. As this is +backend-specific, see the sections about the individual backends for +more information. + + *Note the discussion of image links: Handling links. + + +File: org, Node: Literal examples, Next: Include files, Prev: Images and tables, Up: Markup + +11.3 Literal examples +===================== + +You can include literal examples that should not be subjected to +markup. Such examples will be typeset in monospace, so this is well +suited for source code and similar examples. + + #+BEGIN_EXAMPLE + Some example from a text file. + #+END_EXAMPLE + + Note that such blocks may be indented in order to align nicely with +indented text and in particular with plain list structure (*note Plain +lists::). For simplicity when using small examples, you can also start +the example lines with a colon followed by a space. There may also be +additional whitespace before the colon: + + Here is an example + : Some example from a text file. + + If the example is source code from a programming language, or any +other text that can be marked up by font-lock in Emacs, you can ask for +the example to look like the fontified Emacs buffer(1). This is done +with the `src' block, where you also need to specify the name of the +major mode that should be used to fontify the example: + + #+BEGIN_SRC emacs-lisp + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) + #+END_SRC + + Both in `example' and in `src' snippets, you can add a `-n' switch +to the end of the `BEGIN' line, to get the lines of the example +numbered. If you use a `+n' switch, the numbering from the previous +numbered snippet will be continued in the current one. In literal +examples, Org will interpret strings like `(ref:name)' as labels, and +use them as targets for special hyperlinks like `[[(name)]]' (i.e. the +reference name enclosed in single parenthesis). In HTML, hovering the +mouse over such a link will remote-highlight the corresponding code +line, which is kind of cool. + + You can also add a `-r' switch which removes the labels from the +source code(2). With the `-n' switch, links to these references will +be labeled by the line numbers from the code listing, otherwise links +will use the labels with no parentheses. Here is an example: + + #+BEGIN_SRC emacs-lisp -n -r + (save-excursion (ref:sc) + (goto-char (point-min)) (ref:jump) + #+END_SRC + In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]] + jumps to point-min. + + If the syntax for the label format conflicts with the language +syntax, use a `-l' switch to change the format, for example +`#+BEGIN_SRC pascal -n -r -l "((%s))"'. See also the variable +`org-coderef-label-format'. + + HTML export also allows examples to be published as text areas, +*Note Text areas in HTML export::. + +`C-c '' + Edit the source code example at point in its native mode. This + works by switching to a temporary buffer with the source code. + You need to exit by pressing `C-c '' again(3). The edited version + will then replace the old version in the Org buffer. Fixed-width + regions (where each line starts with a colon followed by a space) + will be edited using `artist-mode'(4) to allow creating ASCII + drawings easily. Using this command in an empty line will create + a new fixed-width region. + +`C-c l' + Calling `org-store-link' while editing a source code example in a + temporary buffer created with `C-c '' will prompt for a label. + Make sure that it is unique in the current buffer, and insert it + with the proper formatting like `(ref:label)' at the end of the + current line. Then the label is stored as a link `(label)', for + retrieval with `C-c C-l'. + + ---------- Footnotes ---------- + + (1) This works automatically for the HTML backend (it requires +version 1.34 of the `htmlize.el' package, which is distributed with +Org). Fontified code chunks in LaTeX can be achieved using either the +listings or the minted (http://code.google.com/p/minted) package. To +use listings, turn on the variable `org-export-latex-listings' and +ensure that the listings package is included by the LaTeX header (e.g. +by configuring `org-export-latex-packages-alist'). See the listings +documentation for configuration options, including obtaining colored +output. For minted it is necessary to install the program pygments +(http://pygments.org), in addition to setting +`org-export-latex-minted', ensuring that the minted package is included +by the LaTeX header, and ensuring that the `-shell-escape' option is +passed to `pdflatex' (see `org-latex-to-pdf-process'). See the +documentation of the variables `org-export-latex-listings' and +`org-export-latex-minted' for further details. + + (2) Adding `-k' to `-n -r' will keep the labels in the source code +while using line numbers for the links, which might be useful to +explain those in an org-mode example code. + + (3) Upon exit, lines starting with `*' or `#' will get a comma +prepended, to keep them from being interpreted by Org as outline nodes +or special comments. These commas will be stripped for editing with +`C-c '', and also for export. + + (4) You may select a different-mode with the variable +`org-edit-fixed-width-region-mode'. + + +File: org, Node: Include files, Next: Index entries, Prev: Literal examples, Up: Markup + +11.4 Include files +================== + +During export, you can include the content of another file. For +example, to include your `.emacs' file, you could use: + + #+INCLUDE: "~/.emacs" src emacs-lisp + The optional second and third parameter are the markup (e.g. `quote', +`example', or `src'), and, if the markup is `src', the language for +formatting the contents. The markup is optional; if it is not given, +the text will be assumed to be in Org-mode format and will be processed +normally. The include line will also allow additional keyword +parameters `:prefix1' and `:prefix' to specify prefixes for the first +line and for each following line, `:minlevel' in order to get org-mode +content demoted to a specified level, as well as any options accepted +by the selected markup. For example, to include a file as an item, use + + #+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " " + +`C-c '' + Visit the include file at point. + + +File: org, Node: Index entries, Next: Macro replacement, Prev: Include files, Up: Markup + +11.5 Index entries +================== + +You can specify entries that will be used for generating an index during +publishing. This is done by lines starting with `#+INDEX'. An entry +the contains an exclamation mark will create a sub item. See *Note +Generating an index:: for more information. + + * Curriculum Vitae + #+INDEX: CV + #+INDEX: Application!CV + + +File: org, Node: Macro replacement, Next: Embedded LaTeX, Prev: Index entries, Up: Markup + +11.6 Macro replacement +====================== + +You can define text snippets with + + #+MACRO: name replacement text $1, $2 are arguments + +which can be referenced anywhere in the document (even in code +examples) with `{{{name(arg1,arg2)}}}'. In addition to defined macros, +`{{{title}}}', `{{{author}}}', etc., will reference information set by +the `#+TITLE:', `#+AUTHOR:', and similar lines. Also, +`{{{date(FORMAT)}}}' and `{{{modification-time(FORMAT)}}}' refer to +current date time and to the modification time of the file being +exported, respectively. FORMAT should be a format string understood by +`format-time-string'. + + Macro expansion takes place during export, and some people use it to +construct complex HTML code. + + +File: org, Node: Embedded LaTeX, Prev: Macro replacement, Up: Markup + +11.7 Embedded LaTeX +=================== + +Plain ASCII is normally sufficient for almost all note taking. +Exceptions include scientific notes, which often require mathematical +symbols and the occasional formula. LaTeX(1) is widely used to +typeset scientific documents. Org-mode supports embedding LaTeX code +into its files, because many academics are used to writing and reading +LaTeX source code, and because it can be readily processed to produce +pretty output for a number of export backends. + +* Menu: + +* Special symbols:: Greek letters and other symbols +* Subscripts and superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Previewing LaTeX fragments:: What will this snippet look like? +* CDLaTeX mode:: Speed up entering of formulas + + ---------- Footnotes ---------- + + (1) LaTeX is a macro system based on Donald E. Knuth's TeX system. +Many of the features described here as "LaTeX" are really from TeX, but +for simplicity I am blurring this distinction. + + +File: org, Node: Special symbols, Next: Subscripts and superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX + +11.7.1 Special symbols +---------------------- + +You can use LaTeX macros to insert special symbols like `\alpha' to +indicate the Greek letter, or `\to' to indicate an arrow. Completion +for these macros is available, just type `\' and maybe a few letters, +and press `M-<TAB>' to see possible completions. Unlike LaTeX code, +Org-mode allows these macros to be present without surrounding math +delimiters, for example: + + Angles are written as Greek letters \alpha, \beta and \gamma. + + During export, these symbols will be transformed into the native +format of the exporter backend. Strings like `\alpha' will be exported +as `α' in the HTML output, and as `$\alpha$' in the LaTeX output. +Similarly, `\nbsp' will become ` ' in HTML and `~' in LaTeX. If +you need such a symbol inside a word, terminate it like this: +`\Aacute{}stor'. + + A large number of entities is provided, with names taken from both +HTML and LaTeX; see the variable `org-entities' for the complete list. +`\-' is treated as a shy hyphen, and `--', `---', and `...' are all +converted into special commands creating hyphens of different lengths +or a compact set of dots. + + If you would like to see entities displayed as UTF8 characters, use +the following command(1): + +`C-c C-x \' + Toggle display of entities as UTF-8 characters. This does not + change the buffer content which remains plain ASCII, but it + overlays the UTF-8 character for display purposes only. + + ---------- Footnotes ---------- + + (1) You can turn this on by default by setting the variable +`org-pretty-entities', or on a per-file base with the `#+STARTUP' +option `entitiespretty'. + + +File: org, Node: Subscripts and superscripts, Next: LaTeX fragments, Prev: Special symbols, Up: Embedded LaTeX + +11.7.2 Subscripts and superscripts +---------------------------------- + +Just like in LaTeX, `^' and `_' 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 + + The mass of 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. + + To avoid interpretation as raised or lowered text, you can quote `^' +and `_' with a backslash: `\^' and `\_'. If you write a text where the +underscore is often used in a different context, Org's convention to +always interpret these as subscripts can get in your way. Configure the +variable `org-export-with-sub-superscripts' to globally change this +convention, or use, on a per-file basis: + + #+OPTIONS: ^:{} + +With this setting, `a_b' will not be interpreted as a subscript, but +`a_{b}' will. + +`C-c C-x \' + In addition to showing entities as UTF-8 characters, this command + will also format sub- and superscripts in a WYSIWYM way. + + +File: org, Node: LaTeX fragments, Next: Previewing LaTeX fragments, Prev: Subscripts and superscripts, Up: Embedded LaTeX + +11.7.3 LaTeX fragments +---------------------- + +Going beyond symbols and sub- and superscripts, a full formula language +is needed. Org-mode can contain LaTeX math fragments, and it supports +ways to process these for several export backends. When exporting to +LaTeX, the code is obviously left as it is. When exporting to HTML, +Org invokes the MathJax library (http://www.mathjax.org) (*note Math +formatting in HTML export::) to process and display the math(1). +Finally, it can also process the mathematical expressions into +images(2) that can be displayed in a browser or in DocBook documents. + + LaTeX fragments don't need any special marking at all. The following +snippets will be identified as LaTeX source code: + * Environments of any kind(3). The only requirement is that the + `\begin' statement appears on a new line, preceded by only + whitespace. + + * Text within the usual LaTeX math delimiters. To avoid conflicts + with currency specifications, single `$' characters are only + recognized as math delimiters if the enclosed text contains at + most two line breaks, is directly attached to the `$' characters + with no whitespace in between, and if the closing `$' is followed + by whitespace, punctuation or a dash. For the other delimiters, + there is no such restriction, so when in doubt, use `\(...\)' as + inline math delimiters. + +For 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} \]. + +If you need any of the delimiter ASCII sequences for other purposes, you +can configure the option `org-format-latex-options' to deselect the +ones you do not wish to have interpreted by the LaTeX converter. + + LaTeX processing can be configured with the variable +`org-export-with-LaTeX-fragments'. The default setting is `t' which +means `MathJax' for HTML, and no processing for DocBook, ASCII and +LaTeX backends. You can also set this variable on a per-file basis +using one of these lines: + + #+OPTIONS: LaTeX:t Do the right thing automatically (MathJax) + #+OPTIONS: LaTeX:dvipng Force using dvipng images + #+OPTIONS: LaTeX:nil Do not process LaTeX fragments at all + #+OPTIONS: LaTeX:verbatim Verbatim export, for jsMath or so + + ---------- Footnotes ---------- + + (1) If you plan to use this regularly or on pages with significant +page views, you should install `MathJax' on your own server in order to +limit the load of our server. + + (2) For this to work you need to be on a system with a working LaTeX +installation. You also need the `dvipng' program, available at +`http://sourceforge.net/projects/dvipng/'. The LaTeX header that will +be used when processing a fragment can be configured with the variable +`org-format-latex-header'. + + (3) When `MathJax' is used, only the environment recognized by +`MathJax' will be processed. When `dvipng' is used to create images, +any LaTeX environments will be handled. + + +File: org, Node: Previewing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX + +11.7.4 Previewing LaTeX fragments +--------------------------------- + +If you have `dvipng' installed, LaTeX fragments can be processed to +produce preview images of the typeset expressions: + +`C-c C-x C-l' + Produce a preview image of the LaTeX 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. + +`C-c C-c' + Remove the overlay preview images. + + You can customize the variable `org-format-latex-options' to +influence some aspects of the preview. In particular, the `:scale' (and +for HTML export, `:html-scale') property can be used to adjust the size +of the preview images. + + +File: org, Node: CDLaTeX mode, Prev: Previewing LaTeX fragments, Up: Embedded LaTeX + +11.7.5 Using CDLaTeX to enter math +---------------------------------- + +CDLaTeX mode is a minor mode that is normally used in combination with a +major LaTeX 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 `cdlatex.el' +and `texmathp.el' (the latter comes also with AUCTeX) from +`http://www.astro.uva.nl/~dominik/Tools/cdlatex'. Don't use CDLaTeX +mode itself under Org-mode, but use the light version +`org-cdlatex-mode' that comes as part of Org-mode. Turn it on for the +current buffer with `M-x org-cdlatex-mode', or for all Org files with + + (add-hook 'org-mode-hook 'turn-on-org-cdlatex) + + When this mode is enabled, the following features are present (for +more details see the documentation of CDLaTeX mode): + * Environment templates can be inserted with `C-c {'. + + * The <TAB> key will do template expansion if the cursor is inside a + LaTeX fragment(1). For example, <TAB> will expand `fr' to + `\frac{}{}' and position the cursor correctly inside the first + brace. Another <TAB> will get you into the second brace. Even + outside fragments, <TAB> will expand environment abbreviations at + the beginning of a line. For example, if you write `equ' at the + beginning of a line and press <TAB>, this abbreviation will be + expanded to an `equation' environment. To get a list of all + abbreviations, type `M-x cdlatex-command-help'. + + * Pressing `_' and `^' inside a LaTeX fragment will insert these + characters together with a pair of braces. If you use <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 `cdlatex-simplify-sub-super-scripts'). + + * Pressing the backquote ``' followed by a character inserts math + macros, also outside LaTeX fragments. If you wait more than 1.5 + seconds after the backquote, a help window will pop up. + + * Pressing the single-quote `'' 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 single-quote, a help window + will pop up. Character modification will work only inside LaTeX + fragments; outside the quote is normal. + + ---------- Footnotes ---------- + + (1) Org-mode has a method to test if the cursor is inside such a +fragment, see the documentation of the function +`org-inside-LaTeX-fragment-p'. + + +File: org, Node: Exporting, Next: Publishing, Prev: Markup, Up: Top + +12 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 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. LaTeX export lets +you use Org-mode and its structured editing functions to easily create +LaTeX files. DocBook export makes it possible to convert Org files to +many other formats using DocBook tools. For project management you can +create gantt and resource charts by using TaskJuggler export. 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. + + Org supports export of selected regions when `transient-mark-mode' is +enabled (default in Emacs 23). + +* Menu: + +* Selective export:: Using tags to select and exclude trees +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to LaTeX, and processing to PDF +* DocBook export:: Exporting to DocBook +* TaskJuggler export:: Exporting to TaskJuggler +* Freemind export:: Exporting to Freemind mind maps +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format + + +File: org, Node: Selective export, Next: Export options, Prev: Exporting, Up: Exporting + +12.1 Selective export +===================== + +You may use tags to select the parts of a document that should be +exported, or to exclude parts from export. This behavior is governed +by two variables: `org-export-select-tags' and +`org-export-exclude-tags'. + + Org first checks if any of the _select_ tags is present in the +buffer. If yes, all trees that do not carry one of these tags will be +excluded. If a selected tree is a subtree, the heading hierarchy above +it will also be selected for export, but not the text below those +headings. + +If none of the select tags is found, the whole buffer will be selected +for export. + +Finally, all subtrees that are marked by any of the _exclude_ tags will +be removed from the export buffer. + + +File: org, Node: Export options, Next: The export dispatcher, Prev: Selective export, Up: Exporting + +12.2 Export options +=================== + +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 `C-c C-e +t'. For individual lines, a good way to make sure the keyword is +correct is to type `#+' and then use `M-<TAB>' completion (*note +Completion::). For a summary of other in-buffer settings not +specifically related to export, see *Note In-buffer settings::. In +particular, note that you can place commonly-used (export) options in a +separate file which can be included using `#+SETUPFILE'. + +`C-c C-e t (`org-insert-export-options-template')' + Insert template with export options, see example below. + + #+TITLE: the title to be shown (default is the buffer name) + #+AUTHOR: the author (default taken from `user-full-name') + #+DATE: a date, fixed, or a format string for `format-time-string' + #+EMAIL: his/her email address (default from `user-mail-address') + #+DESCRIPTION: the page description, e.g. for the XHTML meta tag + #+KEYWORDS: the page keywords, e.g. for the XHTML meta tag + #+LANGUAGE: language for HTML, e.g. `en' (`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 ... + #+BIND: lisp-var lisp-val, e.g.: org-export-latex-low-levels itemize + You need to confirm using these, or configure `org-export-allow-BIND' + #+LINK_UP: the ``up'' link of an exported page + #+LINK_HOME: the ``home'' link of an exported page + #+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage{xyz} + #+EXPORT_SELECT_TAGS: Tags that select a tree for export + #+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export + #+XSLT: the XSLT stylesheet used by DocBook exporter to generate FO file + +The OPTIONS line is a compact(1) form to specify export settings. Here +you can: + H: set the number of headline levels for export + num: turn on/off section-numbers + toc: turn on/off table of contents, or set level limit (integer) + \n: turn on/off line-break-preservation (DOES NOT WORK) + @: turn on/off quoted HTML tags + :: turn on/off fixed-width sections + |: turn on/off tables + ^: turn on/off TeX-like syntax for sub- and superscripts. If + you write "^:{}", `a_{b}' will be interpreted, but + the simple `a_b' will be left as it is. + -: turn on/off conversion of special strings. + f: turn on/off footnotes like this[1]. + todo: turn on/off inclusion of TODO keywords into exported text + pri: turn on/off priority cookies + tags: turn on/off inclusion of tags, may also be `not-in-toc' + <: turn on/off inclusion of any time/date stamps like DEADLINES + *: turn on/off emphasized text (bold, italic, underlined) + TeX: turn on/off simple TeX macros in plain text + LaTeX: configure export of LaTeX fragments. Default `auto' + skip: turn on/off skipping the text before the first heading + author: turn on/off inclusion of author name/email into exported file + email: turn on/off inclusion of author email into exported file + creator: turn on/off inclusion of creator info into exported file + timestamp: turn on/off inclusion creation time into exported file + d: turn on/off inclusion of drawers + These options take effect in both the HTML and LaTeX export, except +for `TeX' and `LaTeX', which are respectively `t' and `nil' for the +LaTeX export. The default values for these and many other options are +given by a set of variables. For a list of such variables, the +corresponding OPTIONS keys and also the publishing keys (*note Project +alist::), see the constant `org-export-plist-vars'. + + When exporting only a single subtree by selecting it with `C-c @' +before calling an export command, the subtree can overrule some of the +file's export settings with properties `EXPORT_FILE_NAME', +`EXPORT_TITLE', `EXPORT_TEXT', `EXPORT_AUTHOR', `EXPORT_DATE', and +`EXPORT_OPTIONS'. + + ---------- Footnotes ---------- + + (1) If you want to configure many options this way, you can use +several OPTIONS lines. + + +File: org, Node: The export dispatcher, Next: ASCII/Latin-1/UTF-8 export, Prev: Export options, Up: Exporting + +12.3 The export dispatcher +========================== + +All export commands can be reached using the export dispatcher, which +is a prefix key that prompts for an additional key specifying the +command. Normally the entire file is exported, but if there is an +active region that contains one outline tree, the first heading is used +as document title and the subtrees are exported. + +`C-c C-e (`org-export')' + Dispatcher for export and publishing commands. Displays a + help-window listing the additional key(s) needed to launch an + export or publishing command. The prefix arg is passed through to + the exporter. A double prefix `C-u C-u' causes most commands to + be executed in the background, in a separate Emacs process(1). + +`C-c C-e v (`org-export-visible')' + Like `C-c C-e', but only export the text that is currently visible + (i.e. not hidden by outline visibility). + +`C-u C-u C-c C-e (`org-export')' + Call the exporter, but reverse the setting of + `org-export-run-in-background', i.e. request background processing + if not set, or force processing in the current Emacs process if + set. + + ---------- Footnotes ---------- + + (1) To make this behavior the default, customize the variable +`org-export-run-in-background'. + + +File: org, Node: ASCII/Latin-1/UTF-8 export, Next: HTML export, Prev: The export dispatcher, Up: Exporting + +12.4 ASCII/Latin-1/UTF-8 export +=============================== + +ASCII export produces a simple and very readable version of an Org-mode +file, containing only plain ASCII. Latin-1 and UTF-8 export augment +the file with special characters and symbols available in these +encodings. + +`C-c C-e a (`org-export-as-ascii')' + Export as ASCII file. For an Org file, `myfile.org', the ASCII + file will be `myfile.txt'. The file will be overwritten without + warning. If there is an active region(1), only the region will be + exported. If the selected region is a single tree(2), 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. + +`C-c C-e A (`org-export-as-ascii-to-buffer')' + Export to a temporary buffer. Do not create a file. + +`C-c C-e n (`org-export-as-latin1')' +`C-c C-e N (`org-export-as-latin1-to-buffer')' + Like the above commands, but use Latin-1 encoding. + +`C-c C-e u (`org-export-as-utf8')' +`C-c C-e U (`org-export-as-utf8-to-buffer')' + Like the above commands, but use UTF-8 encoding. + +`C-c C-e v a/n/u' + Export only the visible part of the document. + + 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, + + C-1 C-c C-e a + +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 body line 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. + + Links will be exported in a footnote-like style, with the +descriptive part in the text and the link in a note before the next +heading. See the variable `org-export-ascii-links-to-notes' for +details and other options. + + ---------- Footnotes ---------- + + (1) This requires `transient-mark-mode' be turned on. + + (2) To select the current subtree, use `C-c @'. + + +File: org, Node: HTML export, Next: LaTeX and PDF export, Prev: ASCII/Latin-1/UTF-8 export, Up: Exporting + +12.5 HTML export +================ + +Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive +HTML formatting, in ways similar to John Gruber's _markdown_ language, +but with additional support for tables. + +* Menu: + +* HTML Export commands:: How to invoke HTML export +* Quoting HTML tags:: Using direct HTML in Org-mode +* Links in HTML export:: How links will be interpreted and formatted +* Tables in HTML export:: How to modify the formatting of tables +* Images in HTML export:: How to insert figures into HTML output +* Math formatting in HTML export:: Beautiful math also on the web +* Text areas in HTML export:: An alternative way to show an example +* CSS support:: Changing the appearance of the output +* JavaScript support:: Info and Folding in a web browser + + +File: org, Node: HTML Export commands, Next: Quoting HTML tags, Prev: HTML export, Up: HTML export + +12.5.1 HTML export commands +--------------------------- + +`C-c C-e h (`org-export-as-html')' + Export as HTML file `myfile.html'. For an Org file `myfile.org', + the ASCII file will be `myfile.html'. The file will be overwritten + without warning. If there is an active region(1), only the region + will be exported. If the selected region is a single tree(2), 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. + +`C-c C-e b (`org-export-as-html-and-open')' + Export as HTML file and immediately open it with a browser. + +`C-c C-e H (`org-export-as-html-to-buffer')' + Export to a temporary buffer. Do not create a file. + +`C-c C-e R (`org-export-region-as-html')' + Export the active region to a temporary buffer. With a prefix + argument, do not produce the file header and footer, but just the + plain HTML section for the region. This is good for cut-and-paste + operations. + +`C-c C-e v h/b/H/R' + Export only the visible part of the document. + +`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. + +`M-x org-replace-region-by-HTML' + Replace the active region (assumed to be in Org-mode syntax) by + HTML code. + + 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 numeric prefix argument. +For example, + + C-2 C-c C-e b + +creates two levels of headings and does the rest as items. + + ---------- Footnotes ---------- + + (1) This requires `transient-mark-mode' be turned on. + + (2) To select the current subtree, use `C-c @'. + + +File: org, Node: Quoting HTML tags, Next: Links in HTML export, Prev: HTML Export commands, Up: HTML export + +12.5.2 Quoting HTML tags +------------------------ + +Plain `<' and `>' are always transformed to `<' and `>' in HTML +export. If you want to include simple HTML tags which should be +interpreted as such, mark them with `@' as in `@<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 + + #+HTML: Literal HTML code for export + +or + + #+BEGIN_HTML + All lines between these markers are exported literally + #+END_HTML + + +File: org, Node: Links in HTML export, Next: Tables in HTML export, Prev: Quoting HTML tags, Up: HTML export + +12.5.3 Links in HTML export +--------------------------- + +Internal links (*note Internal links::) will continue to work in HTML. +This includes automatic links created by radio targets (*note Radio +targets::). Links to external files will still work if the target file +is on the same relative path as the published Org file. Links to other +`.org' files will be translated into HTML links under the assumption +that an HTML version also exists of the linked file, at the same +relative path. `id:' links can then be used to jump to specific +entries across files. For information related to linking files while +publishing them to a publishing directory see *Note Publishing links::. + + If you want to specify attributes for links, you can do so using a +special `#+ATTR_HTML' line to define attributes that will be added to +the `<a>' or `<img>' tags. Here is an example that sets `title' and +`style' attributes for a link: + + #+ATTR_HTML: title="The Org-mode homepage" style="color:red;" + [[http://orgmode.org]] + + +File: org, Node: Tables in HTML export, Next: Images in HTML export, Prev: Links in HTML export, Up: HTML export + +12.5.4 Tables +------------- + +Org-mode tables are exported to HTML using the table tag defined in +`org-export-html-table-tag'. The default setting makes tables without +cell borders and frame. If you would like to change this for individual +tables, place something like the following before the table: + + #+CAPTION: This is a table with lines around and between cells + #+ATTR_HTML: border="2" rules="all" frame="all" + + +File: org, Node: Images in HTML export, Next: Math formatting in HTML export, Prev: Tables in HTML export, Up: HTML export + +12.5.5 Images in HTML export +---------------------------- + +HTML export can inline images given as links in the Org file, and it +can make an image the clickable part of a link. By default(1), images +are inlined if a link does not have a description. So +`[[file:myimg.jpg]]' will be inlined, while `[[file:myimg.jpg][the +image]]' will just produce a link `the image' that points to the image. +If the description part itself is a `file:' link or a `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: + + [[file:highres.jpg][file:thumb.jpg]] + + If you need to add attributes to an inlined image, use a +`#+ATTR_HTML'. In the example below we specify the `alt' and `title' +attributes to support text viewers and accessibility, and align it to +the right. + + #+CAPTION: A black cat stalking a spider + #+ATTR_HTML: alt="cat/spider image" title="Action!" align="right" + [[./img/a.jpg]] + +and you could use `http' addresses just as well. + + ---------- Footnotes ---------- + + (1) But see the variable `org-export-html-inline-images'. + + +File: org, Node: Math formatting in HTML export, Next: Text areas in HTML export, Prev: Images in HTML export, Up: HTML export + +12.5.6 Math formatting in HTML export +------------------------------------- + +LaTeX math snippets (*note LaTeX fragments::) can be displayed in two +different ways on HTML pages. The default is to use the MathJax system +(http://www.mathjax.org) which should work out of the box with Org mode +installation because `http://orgmode.org' serves `MathJax' for Org-mode +users for small applications and for testing purposes. If you plan to +use this regularly or on pages with significant page views, you should +install(1) MathJax on your own server in order to limit the load of our +server. To configure `MathJax', use the variable +`org-export-html-mathjax-options' or insert something like the +following into the buffer: + + #+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js" + +See the docstring of the variable `org-export-html-mathjax-options' for +the meaning of the parameters in this line. + + If you prefer, you can also request that LaTeX fragments are +processed into small images that will be inserted into the browser +page. Before the availability of MathJax, this was the default method +for Org files. This method requires that the `dvipng' program is +available on your system. You can still get this processing with + + #+OPTIONS: LaTeX:dvipng + + ---------- Footnotes ---------- + + (1) Installation instructions can be found on the MathJax website, +see `http://www.mathjax.org/resources/docs/?installation.html'. + + +File: org, Node: Text areas in HTML export, Next: CSS support, Prev: Math formatting in HTML export, Up: HTML export + +12.5.7 Text areas in HTML export +-------------------------------- + +An alternative way to publish literal code examples in HTML is to use +text areas, where the example can even be edited before pasting it into +an application. It is triggered by a `-t' switch at an `example' or +`src' block. Using this switch disables any options for syntax and +label highlighting, and line numbering, which may be present. You may +also use `-h' and `-w' switches to specify the height and width of the +text area, which default to the number of lines in the example, and 80, +respectively. For example + + #+BEGIN_EXAMPLE -t -w 40 + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) + #+END_EXAMPLE + + +File: org, Node: CSS support, Next: JavaScript support, Prev: Text areas in HTML export, Up: HTML export + +12.5.8 CSS support +------------------ + +You can also give style information for the exported file. The HTML +exporter assigns the following special CSS classes(1) to appropriate +parts of the document--your style specifications may change these, in +addition to any of the standard classes like for headlines, tables, etc. + p.author author information, including email + p.date publishing date + p.creator creator info, about org-mode version + .title document title + .todo TODO keywords, all not-done states + .done the DONE keywords, all stated the count as done + .WAITING each TODO keyword also uses a class named after itself + .timestamp timestamp + .timestamp-kwd keyword associated with a timestamp, like SCHEDULED + .timestamp-wrapper span around keyword plus timestamp + .tag tag in a headline + ._HOME each tag uses itself as a class, "@" replaced by "_" + .target target for links + .linenr the line number in a code example + .code-highlighted for highlighting referenced code lines + div.outline-N div for outline level N (headline plus text)) + div.outline-text-N extra div for text at outline level N + .section-number-N section number in headlines, different for each level + div.figure how to format an inlined image + pre.src formatted source code + pre.example normal example + p.verse verse paragraph + div.footnotes footnote section headline + p.footnote footnote definition paragraph, containing a footnote + .footref a footnote reference number (always a <sup>) + .footnum footnote number in footnote definition (always <sup>) + + Each exported file contains a compact default style that defines +these classes in a basic way(2). You may overwrite these settings, or +add to them by using the variables `org-export-html-style' (for +Org-wide settings) and `org-export-html-style-extra' (for more +fine-grained settings, like file-local settings). To set the latter +variable individually for each file, you can use + + #+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" /> + +For longer style definitions, you can use several such lines. You +could also directly write a `<style>' `</style>' section in this way, +without referring to an external file. + + In order to add styles to a subtree, use the `:HTML_CONTAINER_CLASS:' +property to assign a class to the tree. In order to specify CSS styles +for a particular headline, you can use the id specified in a +`:CUSTOM_ID:' property. + + ---------- Footnotes ---------- + + (1) If the classes on TODO keywords and tags lead to conflicts, use +the variables `org-export-html-todo-kwd-class-prefix' and +`org-export-html-tag-class-prefix' to make them unique. + + (2) This style is defined in the constant +`org-export-html-style-default', which you should not modify. To turn +inclusion of these defaults off, customize +`org-export-html-style-include-default' + + +File: org, Node: JavaScript support, Prev: CSS support, Up: HTML export + +12.5.9 JavaScript supported display of web pages +------------------------------------------------ + +Sebastian Rose has written a JavaScript program especially designed to +enhance the web viewing experience of HTML files created with Org. This +program allows you to view large files in two different ways. The +first one is an _Info_-like mode where each section is displayed +separately and navigation can be done with the `n' and `p' keys (and +some other keys as well, press `?' for an overview of the available +keys). The second view type is a _folding_ view much like Org provides +inside Emacs. The script is available at +`http://orgmode.org/org-info.js' and you can find the documentation for +it at `http://orgmode.org/worg/code/org-info-js/'. We host the script +at our site, but if you use it a lot, you might not want to be +dependent on `orgmode.org' and prefer to install a local copy on your +own web server. + + To use the script, you need to make sure that the `org-jsinfo.el' +module gets loaded. It should be loaded by default, but you can try +`M-x customize-variable <RET> org-modules <RET>' to convince yourself +that this is indeed the case. All it then takes to make use of the +program is adding a single line to the Org file: + + #+INFOJS_OPT: view:info toc:nil + +If this line is found, the HTML header will automatically contain the +code needed to invoke the script. Using the line above, you can set +the following viewing options: + + path: The path to the script. The default is to grab the script from + `http://orgmode.org/org-info.js', but you might want to have + a local copy and use a path like `../scripts/org-info.js'. + view: Initial view when website is first shown. Possible values are: + info Info-like interface with one section per page. + overview Folding interface, initially showing only top-level. + content Folding interface, starting with all headlines visible. + showall Folding interface, all headlines and text visible. + sdepth: Maximum headline level that will still become an independent + section for info and folding modes. The default is taken from + `org-export-headline-levels' (= the `H' switch in `#+OPTIONS'). + If this is smaller than in `org-export-headline-levels', each + info/folding section can still contain child headlines. + toc: Should the table of contents _initially_ be visible? + Even when `nil', you can always get to the "toc" with `i'. + tdepth: The depth of the table of contents. The defaults are taken from + the variables `org-export-headline-levels' and `org-export-with-toc'. + ftoc: Does the CSS of the page specify a fixed position for the "toc"? + If yes, the toc will never be displayed as a section. + ltoc: Should there be short contents (children) in each section? + Make this `above' if the section should be above initial text. + mouse: Headings are highlighted when the mouse is over them. Should be + `underline' (default) or a background color like `#cccccc'. + buttons: Should view-toggle buttons be everywhere? When `nil' (the + default), only one such button will be present. + You can choose default values for these options by customizing the +variable `org-infojs-options'. If you always want to apply the script +to your pages, configure the variable `org-export-html-use-infojs'. + + +File: org, Node: LaTeX and PDF export, Next: DocBook export, Prev: HTML export, Up: Exporting + +12.6 LaTeX and PDF export +========================= + +Org-mode contains a LaTeX exporter written by Bastien Guerry. With +further processing(1), this backend is also used to produce PDF output. +Since the LaTeX output uses `hyperref' to implement links and cross +references, the PDF output file will be fully linked. + +* Menu: + +* LaTeX/PDF export commands:: Which key invokes which commands +* Header and sectioning:: Setting up the export file structure +* Quoting LaTeX code:: Incorporating literal LaTeX code +* Tables in LaTeX export:: Options for exporting tables to LaTeX +* Images in LaTeX export:: How to insert figures into LaTeX output +* Beamer class export:: Turning the file into a presentation + + ---------- Footnotes ---------- + + (1) The default LaTeX output is designed for processing with pdftex +or latex. It includes packages that are not compatible with xetex and +possibly luatex. See the variables +`org-export-latex-default-packages-alist' and +`org-export-latex-packages-alist'. + + +File: org, Node: LaTeX/PDF export commands, Next: Header and sectioning, Prev: LaTeX and PDF export, Up: LaTeX and PDF export + +12.6.1 LaTeX export commands +---------------------------- + +`C-c C-e l (`org-export-as-latex')' + Export as LaTeX file `myfile.tex'. For an Org file `myfile.org', + the ASCII file will be `myfile.tex'. The file will be overwritten + without warning. If there is an active region(1), only the region + will be exported. If the selected region is a single tree(2), 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. + +`C-c C-e L (`org-export-as-latex-to-buffer')' + Export to a temporary buffer. Do not create a file. + +`C-c C-e v l/L' + Export only the visible part of the document. + +`M-x org-export-region-as-latex' + Convert the region to LaTeX under the assumption that it was + Org-mode syntax before. This is a global command that can be + invoked in any buffer. + +`M-x org-replace-region-by-latex' + Replace the active region (assumed to be in Org-mode syntax) by + LaTeX code. + +`C-c C-e p (`org-export-as-pdf')' + Export as LaTeX and then process to PDF. + +`C-c C-e d (`org-export-as-pdf-and-open')' + Export as LaTeX and then process to PDF, then open the resulting + PDF file. + + 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 `org-latex-low-levels'. + + If you want that transition to occur at a different level, specify it +with a numeric prefix argument. For example, + + C-2 C-c C-e l + +creates two levels of headings and does the rest as items. + + ---------- Footnotes ---------- + + (1) This requires `transient-mark-mode' be turned on. + + (2) To select the current subtree, use `C-c @'. + + +File: org, Node: Header and sectioning, Next: Quoting LaTeX code, Prev: LaTeX/PDF export commands, Up: LaTeX and PDF export + +12.6.2 Header and sectioning structure +-------------------------------------- + +By default, the LaTeX output uses the class `article'. + + You can change this globally by setting a different value for +`org-export-latex-default-class' or locally by adding an option like +`#+LaTeX_CLASS: myclass' in your file, or with a `:LaTeX_CLASS:' +property that applies when exporting a region containing only this +(sub)tree. The class must be listed in `org-export-latex-classes'. +This variable defines a header template for each class(1), and allows +you to define the sectioning structure for each class. You can also +define your own classes there. `#+LaTeX_CLASS_OPTIONS' or a +`LaTeX_CLASS_OPTIONS' property can specify the options for the +`\documentclass' macro. You can also use `#+LATEX_HEADER: +\usepackage{xyz}' to add lines to the header. See the docstring of +`org-export-latex-classes' for more information. + + ---------- Footnotes ---------- + + (1) Into which the values of +`org-export-latex-default-packages-alist' and +`org-export-latex-packages-alist' are spliced. + + +File: org, Node: Quoting LaTeX code, Next: Tables in LaTeX export, Prev: Header and sectioning, Up: LaTeX and PDF export + +12.6.3 Quoting LaTeX code +------------------------- + +Embedded LaTeX as described in *Note Embedded LaTeX::, will be correctly +inserted into the LaTeX file. This includes simple macros like +`\ref{LABEL}' to create a cross reference to a figure. Furthermore, +you can add special code that should only be present in LaTeX export +with the following constructs: + + #+LaTeX: Literal LaTeX code for export + +or + + #+BEGIN_LaTeX + All lines between these markers are exported literally + #+END_LaTeX + + +File: org, Node: Tables in LaTeX export, Next: Images in LaTeX export, Prev: Quoting LaTeX code, Up: LaTeX and PDF export + +12.6.4 Tables in LaTeX export +----------------------------- + +For LaTeX export of a table, you can specify a label and a caption +(*note Images and tables::). You can also use the `ATTR_LaTeX' line to +request a `longtable' environment for the table, so that it may span +several pages, or provide the `multicolumn' keyword that will make the +table span the page in a multicolumn environment (`table*' environment). +Finally, you can set the alignment string: + + #+CAPTION: A long table + #+LABEL: tbl:long + #+ATTR_LaTeX: longtable align=l|lp{3cm}r|l + | ..... | ..... | + | ..... | ..... | + + +File: org, Node: Images in LaTeX export, Next: Beamer class export, Prev: Tables in LaTeX export, Up: LaTeX and PDF export + +12.6.5 Images in LaTeX export +----------------------------- + +Images that are linked to without a description part in the link, like +`[[file:img.jpg]]' or `[[./img.jpg]]' will be inserted into the PDF +output file resulting from LaTeX processing. Org will use an +`\includegraphics' macro to insert the image. If you have specified a +caption and/or a label as described in *Note Images and tables::, the +figure will be wrapped into a `figure' environment and thus become a +floating element. You can use an `#+ATTR_LaTeX:' line to specify the +various options that can be used in the optional argument of the +`\includegraphics' macro. To modify the placement option of the +`figure' environment, add something like `placement=[h!]' to the +Attributes. + + If you would like to let text flow around the image, add the word +`wrap' to the `#+ATTR_LaTeX:' line, which will make the figure occupy +the left half of the page. To fine-tune, the `placement' field will be +the set of additional arguments needed by the `wrapfigure' environment. +Note that if you change the size of the image, you need to use +compatible settings for `\includegraphics' and `wrapfigure'. + + #+CAPTION: The black-body emission of the disk around HR 4049 + #+LABEL: fig:SED-HR4049 + #+ATTR_LaTeX: width=5cm,angle=90 + [[./img/sed-hr4049.pdf]] + + #+ATTR_LaTeX: width=0.38\textwidth wrap placement={r}{0.4\textwidth} + [[./img/hst.png]] + + If you need references to a label created in this way, write +`\ref{fig:SED-HR4049}' just like in LaTeX. + + +File: org, Node: Beamer class export, Prev: Images in LaTeX export, Up: LaTeX and PDF export + +12.6.6 Beamer class export +-------------------------- + +The LaTeX class `beamer' allows production of high quality presentations +using LaTeX and pdf processing. Org-mode has special support for +turning an Org-mode file or tree into a `beamer' presentation. + + When the LaTeX class for the current buffer (as set with +`#+LaTeX_CLASS: beamer') or subtree (set with a `LaTeX_CLASS' property) +is `beamer', a special export mode will turn the file or tree into a +beamer presentation. Any tree with not-too-deep level nesting should +in principle be exportable as a beamer presentation. By default, the +top-level entries (or the first level below the selected subtree +heading) will be turned into frames, and the outline structure below +this level will become itemize lists. You can also configure the +variable `org-beamer-frame-level' to a different level--then the +hierarchy above frames will produce the sectioning structure of the +presentation. + + A template for useful in-buffer settings or properties can be +inserted into the buffer with `M-x org-insert-beamer-options-template'. +Among other things, this will install a column view format which is +very handy for editing special properties used by beamer. + + You can influence the structure of the presentation using the +following properties: + +`BEAMER_env' + The environment that should be used to format this entry. Valid + environments are defined in the constant + `org-beamer-environments-default', and you can define more in + `org-beamer-environments-extra'. If this property is set, the + entry will also get a `:B_environment:' tag to make this visible. + This tag has no semantic meaning, it is only a visual aid. + +`BEAMER_envargs' + The beamer-special arguments that should be used for the + environment, like `[t]' or `[<+->]' of `<2-3>'. If the + `BEAMER_col' property is also set, something like `C[t]' can be + added here as well to set an options argument for the implied + `columns' environment. `c[t]' or `c<2->' will set an options for + the implied `column' environment. + +`BEAMER_col' + The width of a column that should start with this entry. If this + property is set, the entry will also get a `:BMCOL:' property to + make this visible. Also this tag is only a visual aid. When this + is a plain number, it will be interpreted as a fraction of + `\textwidth'. Otherwise it will be assumed that you have + specified the units, like `3cm'. The first such property in a + frame will start a `columns' environment to surround the columns. + This environment is closed when an entry has a `BEAMER_col' + property with value 0 or 1, or automatically at the end of the + frame. + +`BEAMER_extra' + Additional commands that should be inserted after the environment + has been opened. For example, when creating a frame, this can be + used to specify transitions. + + Frames will automatically receive a `fragile' option if they contain +source code that uses the verbatim environment. Special `beamer' +specific code can be inserted using `#+BEAMER:' and +`#+BEGIN_beamer...#+end_beamer' constructs, similar to other export +backends, but with the difference that `#+LaTeX:' stuff will be included +in the presentation as well. + + Outline nodes with `BEAMER_env' property value `note' or `noteNH' +will be formatted as beamer notes, i,e, they will be wrapped into +`\note{...}'. The former will include the heading as part of the note +text, the latter will ignore the heading of that node. To simplify note +generation, it is actually enough to mark the note with a _tag_ (either +`:B_note:' or `:B_noteNH:') instead of creating the `BEAMER_env' +property. + + You can turn on a special minor mode `org-beamer-mode' for editing +support with + + #+STARTUP: beamer + +`C-c C-b (`org-beamer-select-environment')' + In `org-beamer-mode', this key offers fast selection of a beamer + environment or the `BEAMER_col' property. + + Column view provides a great way to set the environment of a node +and other important parameters. Make sure you are using a COLUMN +format that is geared toward this special purpose. The command `M-x +org-insert-beamer-options-template' defines such a format. + + Here is a simple example Org document that is intended for beamer +export. + + #+LaTeX_CLASS: beamer + #+TITLE: Example Presentation + #+AUTHOR: Carsten Dominik + #+LaTeX_CLASS_OPTIONS: [presentation] + #+BEAMER_FRAME_LEVEL: 2 + #+BEAMER_HEADER_EXTRA: \usetheme{Madrid}\usecolortheme{default} + #+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex) + + * This is the first structural section + + ** Frame 1 \\ with a subtitle + *** Thanks to Eric Fraga :BMCOL:B_block: + :PROPERTIES: + :BEAMER_env: block + :BEAMER_envargs: C[t] + :BEAMER_col: 0.5 + :END: + for the first viable beamer setup in Org + *** Thanks to everyone else :BMCOL:B_block: + :PROPERTIES: + :BEAMER_col: 0.5 + :BEAMER_env: block + :BEAMER_envargs: <2-> + :END: + for contributing to the discussion + **** This will be formatted as a beamer note :B_note: + ** Frame 2 \\ where we will not use columns + *** Request :B_block: + Please test this stuff! + :PROPERTIES: + :BEAMER_env: block + :END: + + For more information, see the documentation on Worg. + + +File: org, Node: DocBook export, Next: TaskJuggler export, Prev: LaTeX and PDF export, Up: Exporting + +12.7 DocBook export +=================== + +Org contains a DocBook exporter written by Baoqiu Cui. Once an Org +file is exported to DocBook format, it can be further processed to +produce other formats, including PDF, HTML, man pages, etc., using many +available DocBook tools and stylesheets. + + Currently DocBook exporter only supports DocBook V5.0. + +* Menu: + +* DocBook export commands:: How to invoke DocBook export +* Quoting DocBook code:: Incorporating DocBook code in Org files +* Recursive sections:: Recursive sections in DocBook +* Tables in DocBook export:: Tables are exported as HTML tables +* Images in DocBook export:: How to insert figures into DocBook output +* Special characters:: How to handle special characters + + +File: org, Node: DocBook export commands, Next: Quoting DocBook code, Prev: DocBook export, Up: DocBook export + +12.7.1 DocBook export commands +------------------------------ + +`C-c C-e D (`org-export-as-docbook')' + Export as DocBook file. For an Org file, `myfile.org', the + DocBook XML file will be `myfile.xml'. The file will be + overwritten without warning. If there is an active region(1), + only the region will be exported. If the selected region is a + single tree(2), 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. + +`C-c C-e V (`org-export-as-docbook-pdf-and-open')' + Export as DocBook file, process to PDF, then open the resulting + PDF file. + + Note that, in order to produce PDF output based on exported + DocBook file, you need to have XSLT processor and XSL-FO processor + software installed on your system. Check variables + `org-export-docbook-xslt-proc-command' and + `org-export-docbook-xsl-fo-proc-command'. + + The stylesheet argument `%s' in variable + `org-export-docbook-xslt-proc-command' is replaced by the value of + variable `org-export-docbook-xslt-stylesheet', which needs to be + set by the user. You can also overrule this global setting on a + per-file basis by adding an in-buffer setting `#+XSLT:' to the Org + file. + +`C-c C-e v D' + Export only the visible part of the document. + + ---------- Footnotes ---------- + + (1) This requires `transient-mark-mode' to be turned on + + (2) To select the current subtree, use `C-c @'. + + +File: org, Node: Quoting DocBook code, Next: Recursive sections, Prev: DocBook export commands, Up: DocBook export + +12.7.2 Quoting DocBook code +--------------------------- + +You can quote DocBook code in Org files and copy it verbatim into +exported DocBook file with the following constructs: + + #+DOCBOOK: Literal DocBook code for export + +or + + #+BEGIN_DOCBOOK + All lines between these markers are exported by DocBook exporter + literally. + #+END_DOCBOOK + + For example, you can use the following lines to include a DocBook +warning admonition. As to what this warning says, you should pay +attention to the document context when quoting DocBook code in Org +files. You may make exported DocBook XML files invalid by not quoting +DocBook code correctly. + + #+BEGIN_DOCBOOK + <warning> + <para>You should know what you are doing when quoting DocBook XML code + in your Org file. Invalid DocBook XML may be generated by + DocBook exporter if you are not careful!</para> + </warning> + #+END_DOCBOOK + + +File: org, Node: Recursive sections, Next: Tables in DocBook export, Prev: Quoting DocBook code, Up: DocBook export + +12.7.3 Recursive sections +------------------------- + +DocBook exporter exports Org files as articles using the `article' +element in DocBook. Recursive sections, i.e. `section' elements, are +used in exported articles. Top level headlines in Org files are +exported as top level sections, and lower level headlines are exported +as nested sections. The entire structure of Org files will be exported +completely, no matter how many nested levels of headlines there are. + + Using recursive sections makes it easy to port and reuse exported +DocBook code in other DocBook document types like `book' or `set'. + + +File: org, Node: Tables in DocBook export, Next: Images in DocBook export, Prev: Recursive sections, Up: DocBook export + +12.7.4 Tables in DocBook export +------------------------------- + +Tables in Org files are exported as HTML tables, which have been +supported since DocBook V4.3. + + If a table does not have a caption, an informal table is generated +using the `informaltable' element; otherwise, a formal table will be +generated using the `table' element. + + +File: org, Node: Images in DocBook export, Next: Special characters, Prev: Tables in DocBook export, Up: DocBook export + +12.7.5 Images in DocBook export +------------------------------- + +Images that are linked to without a description part in the link, like +`[[file:img.jpg]]' or `[[./img.jpg]]', will be exported to DocBook +using `mediaobject' elements. Each `mediaobject' element contains an +`imageobject' that wraps an `imagedata' element. If you have specified +a caption for an image as described in *Note Images and tables::, a +`caption' element will be added in `mediaobject'. If a label is also +specified, it will be exported as an `xml:id' attribute of the +`mediaobject' element. + + Image attributes supported by the `imagedata' element, like `align' +or `width', can be specified in two ways: you can either customize +variable `org-export-docbook-default-image-attributes' or use the +`#+ATTR_DOCBOOK:' line. Attributes specified in variable +`org-export-docbook-default-image-attributes' are applied to all inline +images in the Org file to be exported (unless they are overridden by +image attributes specified in `#+ATTR_DOCBOOK:' lines). + + The `#+ATTR_DOCBOOK:' line can be used to specify additional image +attributes or override default image attributes for individual images. +If the same attribute appears in both the `#+ATTR_DOCBOOK:' line and +variable `org-export-docbook-default-image-attributes', the former +takes precedence. Here is an example about how image attributes can be +set: + + #+CAPTION: The logo of Org-mode + #+LABEL: unicorn-svg + #+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%" + [[./img/org-mode-unicorn.svg]] + + By default, DocBook exporter recognizes the following image file +types: `jpeg', `jpg', `png', `gif', and `svg'. You can customize +variable `org-export-docbook-inline-image-extensions' to add more types +to this list as long as DocBook supports them. + + +File: org, Node: Special characters, Prev: Images in DocBook export, Up: DocBook export + +12.7.6 Special characters in DocBook export +------------------------------------------- + +Special characters that are written in TeX-like syntax, such as +`\alpha', `\Gamma', and `\Zeta', are supported by DocBook exporter. +These characters are rewritten to XML entities, like `α', +`Γ', and `Ζ', based on the list saved in variable +`org-entities'. As long as the generated DocBook file includes the +corresponding entities, these special characters are recognized. + + You can customize variable `org-export-docbook-doctype' to include +the entities you need. For example, you can set variable +`org-export-docbook-doctype' to the following value to recognize all +special characters included in XHTML entities: + + "<!DOCTYPE article [ + <!ENTITY % xhtml1-symbol PUBLIC + \"-//W3C//ENTITIES Symbol for HTML//EN//XML\" + \"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\" + > + %xhtml1-symbol; + ]> + " + + +File: org, Node: TaskJuggler export, Next: Freemind export, Prev: DocBook export, Up: Exporting + +12.8 TaskJuggler export +======================= + +TaskJuggler (http://www.taskjuggler.org/) is a project management tool. +It provides an optimizing scheduler that computes your project time +lines and resource assignments based on the project outline and the +constraints that you have provided. + + The TaskJuggler exporter is a bit different from other exporters, +such as the HTML and LaTeX exporters for example, in that it does not +export all the nodes of a document or strictly follow the order of the +nodes in the document. + + Instead the TaskJuggler exporter looks for a tree that defines the +tasks and a optionally tree that defines the resources for this +project. It then creates a TaskJuggler file based on these trees and +the attributes defined in all the nodes. + +12.8.1 TaskJuggler export commands +---------------------------------- + +`C-c C-e j (`org-export-as-taskjuggler')' + Export as TaskJuggler file. + +`C-c C-e J (`org-export-as-taskjuggler-and-open')' + Export as TaskJuggler file and then open the file with + TaskJugglerUI. + +12.8.2 Tasks +------------ + +Create your tasks as you usually do with Org-mode. Assign efforts to +each task using properties (it's easiest to do this in the column +view). You should end up with something similar to the example by Peter +Jones in +`http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org'. +Now mark the top node of your tasks with a tag named +`:taskjuggler_project:' (or whatever you customized +`org-export-taskjuggler-project-tag' to). You are now ready to export +the project plan with `C-c C-e J' which will export the project plan and +open a gantt chart in TaskJugglerUI. + +12.8.3 Resources +---------------- + +Next you can define resources and assign those to work on specific +tasks. You can group your resources hierarchically. Tag the top node of +the resources with `:taskjuggler_resource:' (or whatever you customized +`org-export-taskjuggler-resource-tag' to). You can optionally assign an +identifier (named `resource_id') to the resources (using the standard +Org properties commands, *note Property syntax::) or you can let the +exporter generate identifiers automatically (the exporter picks the +first word of the headline as the identifier as long as it is +unique--see the documentation of `org-taskjuggler-get-unique-id'). +Using that identifier you can then allocate resources to tasks. This is +again done with the `allocate' property on the tasks. Do this in column +view or when on the task type `C-c C-x p allocate <RET> <resource_id> +<RET>'. + + Once the allocations are done you can again export to TaskJuggler +and check in the Resource Allocation Graph which person is working on +what task at what time. + +12.8.4 Export of properties +--------------------------- + +The exporter also takes TODO state information into consideration, i.e. +if a task is marked as done it will have the corresponding attribute in +TaskJuggler (`complete 100'). Also it will export any property on a task +resource or resource node which is known to TaskJuggler, such as +`limits', `vacation', `shift', `booking', `efficiency', `journalentry', +`rate' for resources or `account', `start', `note', `duration', `end', +`journalentry', `milestone', `reference', `responsible', `scheduling', +etc for tasks. + +12.8.5 Dependencies +------------------- + +The exporter will handle dependencies that are defined in the tasks +either with the `ORDERED' attribute (*note TODO dependencies::), with +the `BLOCKER' attribute (see `org-depend.el') or alternatively with a +`depends' attribute. Both the `BLOCKER' and the `depends' attribute can +be either `previous-sibling' or a reference to an identifier (named +`task_id') which is defined for another task in the project. `BLOCKER' +and the `depends' attribute can define multiple dependencies separated +by either space or comma. You can also specify optional attributes on +the dependency by simply appending it. The following examples should +illustrate this: + + * Preparation + :PROPERTIES: + :task_id: preparation + :ORDERED: t + :END: + * Training material + :PROPERTIES: + :task_id: training_material + :ORDERED: t + :END: + ** Markup Guidelines + :PROPERTIES: + :Effort: 2.0 + :END: + ** Workflow Guidelines + :PROPERTIES: + :Effort: 2.0 + :END: + * Presentation + :PROPERTIES: + :Effort: 2.0 + :BLOCKER: training_material { gapduration 1d } preparation + :END: + +12.8.6 Reports +-------------- + +TaskJuggler can produce many kinds of reports (e.g. gantt chart, +resource allocation, etc). The user defines what kind of reports should +be generated for a project in the TaskJuggler file. The exporter will +automatically insert some default reports in the file. These defaults +are defined in `org-export-taskjuggler-default-reports'. They can be +modified using customize along with a number of other options. For a +more complete list, see `M-x customize-group <RET> +org-export-taskjuggler <RET>'. + + For more information and examples see the Org-taskjuggler tutorial at +`http://orgmode.org/worg/org-tutorials/org-taskjuggler.php'. + + +File: org, Node: Freemind export, Next: XOXO export, Prev: TaskJuggler export, Up: Exporting + +12.9 Freemind export +==================== + +The Freemind exporter was written by Lennart Borgman. + +`C-c C-e m (`org-export-as-freemind')' + Export as Freemind mind map `myfile.mm'. + + +File: org, Node: XOXO export, Next: iCalendar export, Prev: Freemind export, Up: Exporting + +12.10 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. + +`C-c C-e x (`org-export-as-xoxo')' + Export as XOXO file `myfile.html'. + +`C-c C-e v x' + Export only the visible part of the document. + + +File: org, Node: iCalendar export, Prev: XOXO export, Up: Exporting + +12.11 iCalendar export +====================== + +Some people 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 show deadlines and +other time-stamped items in Org files 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 `org-icalendar-include-todo'. Plain timestamps +are exported as VEVENT, and TODO items as VTODO. It will also create +events from deadlines that are in non-TODO items. Deadlines and +scheduling dates in TODO items will be used to set the start and due +dates for the TODO entry(1). As categories, it will use the tags +locally defined in the heading, and the file/tree category(2). See the +variable `org-icalendar-alarm-time' for a way to assign alarms to +entries with a time. + + The iCalendar standard requires each entry to have a globally unique +identifier (UID). Org creates these identifiers during export. If you +set the variable `org-icalendar-store-UID', the UID will be stored in +the `:ID:' property of the entry and re-used next time you report this +entry. Since a single entry can give rise to multiple iCalendar +entries (as a timestamp, a deadline, a scheduled item, and as a TODO +item), Org adds prefixes to the UID, depending on what triggered the +inclusion of the entry. In this way the UID remains unique, but a +synchronization program can still figure out from which entry all the +different instances originate. + +`C-c C-e i (`org-export-icalendar-this-file')' + Create iCalendar entries for the current file and store them in + the same directory, using a file extension `.ics'. + +`C-c C-e I (`org-export-icalendar-all-agenda-files')' + Like `C-c C-e i', but do this for all files in `org-agenda-files'. + For each of these files, a separate iCalendar file will be + written. + +`C-c C-e c (`org-export-icalendar-combine-agenda-files')' + Create a single large iCalendar file from all files in + `org-agenda-files' and write it to the file given by + `org-combined-agenda-icalendar-file'. + + The export will honor SUMMARY, DESCRIPTION and LOCATION(3) +properties if the selected entries have them. If not, the summary will +be derived from the headline, and the description from the body +(limited to `org-icalendar-include-body' characters). + + How this calendar is best read and updated, depends on the +application you are using. The FAQ covers this issue. + + ---------- Footnotes ---------- + + (1) See the variables `org-icalendar-use-deadline' and +`org-icalendar-use-scheduled'. + + (2) To add inherited tags or the TODO state, configure the variable +`org-icalendar-categories'. + + (3) The LOCATION property can be inherited from higher in the +hierarchy if you configure `org-use-property-inheritance' accordingly. + + +File: org, Node: Publishing, Next: Working With Source Code, Prev: Exporting, Up: Top + +13 Publishing +************* + +Org includes a publishing management system that allows you to configure +automatic HTML conversion of _projects_ composed of interlinked org +files. You can also configure Org to automatically upload your +exported HTML pages and related attachments, such as images and source +code files, to a web server. + + You can also use Org to convert files into PDF, or even combine HTML +and PDF conversion so that files are available in both formats on the +server. + + Publishing has been contributed to Org by David O'Toole. + +* Menu: + +* Configuration:: Defining projects +* Uploading files:: How to get files up on the server +* Sample configuration:: Example projects +* Triggering publication:: Publication commands + + +File: org, Node: Configuration, Next: Uploading files, Prev: Publishing, Up: Publishing + +13.1 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? +* Sitemap:: Generating a list of all pages +* Generating an index:: An index that reaches across pages + + +File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration + +13.1.1 The variable `org-publish-project-alist' +----------------------------------------------- + +Publishing is configured almost entirely through setting the value of +one variable, called `org-publish-project-alist'. Each element of the +list configures one project, and may be in one of the two following +forms: + + ("project-name" :property value :property value ...) + i.e. a well-formed property list with alternating keys and values + or + ("project-name" :components ("project-name" "project-name" ...)) + + 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 +sub-projects, which group together files requiring different publishing +options. When you publish such a "meta-project", all the components +will also be published, in the sequence given. + + +File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration + +13.1.2 Sources and destinations for files +----------------------------------------- + +Most properties are optional, but some should always be set. In +particular, Org needs to know where to look for source files, and where +to put published files. + +`:base-directory' Directory containing publishing source files +`:publishing-directory'Directory where output files will be published. + You can directly publish to a webserver using a + file name syntax appropriate for the Emacs + `tramp' package. Or you can publish to a local + directory and use external tools to upload your + website (*note Uploading files::). +`:preparation-function'Function or list of functions to be called before + starting the publishing process, for example, to + run `make' for updating files to be published. + The project property list is scoped into this + call as the variable `project-plist'. +`:completion-function' Function or list of functions called after + finishing the publishing process, for example, to + change permissions of the resulting files. The + project property list is scoped into this call as + the variable `project-plist'. + + +File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration + +13.1.3 Selecting files +---------------------- + +By default, all files with extension `.org' in the base directory are +considered part of the project. This can be modified by setting the +properties +`:base-extension' Extension (without the dot!) of source files. This + actually is a regular expression. Set this to the + symbol `any' if you want to get all files in + `:base-directory', even without extension. +`:exclude' Regular expression to match file names that should + not be published, even though they have been selected + on the basis of their extension. +`:include' List of files to be included regardless of + `:base-extension' and `:exclude'. +`:recursive' Non-nil means, check base-directory recursively for + files to publish. + + +File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration + +13.1.4 Publishing action +------------------------ + +Publishing means that a file is copied to the destination directory and +possibly transformed in the process. The default transformation is to +export Org files as HTML files, and this is done by the function +`org-publish-org-to-html' which calls the HTML exporter (*note HTML +export::). But you also can publish your content as PDF files using +`org-publish-org-to-pdf', or as `ascii', `latin1' or `utf8' encoded +files using the corresponding functions. If you want to publish the +Org file itself, but with archived, commented, and tag-excluded trees +removed, use `org-publish-org-to-org' and set the parameters +`:plain-source' and/or `:htmlized-source'. This will produce +`file.org' and `file.org.html' in the publishing directory(1). Other +files like images only need to be copied to the publishing destination; +for this you may use `org-publish-attachment'. For non-Org files, you +always need to specify the publishing function: + +`:publishing-function' Function executing the publication of a file. + This may also be a list of functions, which will + all be called in turn. +`:plain-source' Non-nil means, publish plain source. +`:htmlized-source' Non-nil means, publish htmlized source. + + The function must accept three arguments: a property list containing +at least a `:publishing-directory' property, the name of the file to be +published, and the path to the publishing directory of the output file. +It should take the specified file, make the necessary transformation +(if any) and place the result into the destination folder. + + ---------- Footnotes ---------- + + (1) `file-source.org' and `file-source.org.html' if source and +publishing directories are equal. Note that with this kind of setup, +you need to add `:exclude "-source\\.org"' to the project definition in +`org-publish-project-alist' to prevent the published source files from +being considered as new org files the next time the project is +published. + + +File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration + +13.1.5 Options for the HTML/LaTeX exporters +------------------------------------------- + +The property list can be used to set many export options for the HTML +and LaTeX exporters. In most cases, these properties correspond to user +variables in Org. The table below lists these properties along with +the variable they belong to. See the documentation string for the +respective variable for details. + +`:link-up' `org-export-html-link-up' +`:link-home' `org-export-html-link-home' +`:language' `org-export-default-language' +`:customtime' `org-display-custom-times' +`:headline-levels' `org-export-headline-levels' +`:section-numbers' `org-export-with-section-numbers' +`:section-number-format'`org-export-section-number-format' +`:table-of-contents' `org-export-with-toc' +`:preserve-breaks' `org-export-preserve-breaks' +`:archived-trees' `org-export-with-archived-trees' +`:emphasize' `org-export-with-emphasize' +`:sub-superscript' `org-export-with-sub-superscripts' +`:special-strings' `org-export-with-special-strings' +`:footnotes' `org-export-with-footnotes' +`:drawers' `org-export-with-drawers' +`:tags' `org-export-with-tags' +`:todo-keywords' `org-export-with-todo-keywords' +`:priority' `org-export-with-priority' +`:TeX-macros' `org-export-with-TeX-macros' +`:LaTeX-fragments' `org-export-with-LaTeX-fragments' +`:latex-listings' `org-export-latex-listings' +`:skip-before-1st-heading'`org-export-skip-text-before-1st-heading' +`:fixed-width' `org-export-with-fixed-width' +`:timestamps' `org-export-with-timestamps' +`:author-info' `org-export-author-info' +`:email-info' `org-export-email-info' +`:creator-info' `org-export-creator-info' +`:tables' `org-export-with-tables' +`:table-auto-headline' `org-export-highlight-first-table-line' +`:style-include-default'`org-export-html-style-include-default' +`:style' `org-export-html-style' +`:style-extra' `org-export-html-style-extra' +`:convert-org-links' `org-export-html-link-org-files-as-html' +`:inline-images' `org-export-html-inline-images' +`:html-extension' `org-export-html-extension' +`:xml-declaration' `org-export-html-xml-declaration' +`:html-table-tag' `org-export-html-table-tag' +`:expand-quoted-html' `org-export-html-expand' +`:timestamp' `org-export-html-with-timestamp' +`:publishing-directory' `org-export-publishing-directory' +`:preamble' `org-export-html-preamble' +`:postamble' `org-export-html-postamble' +`:auto-preamble' `org-export-html-auto-preamble' +`:auto-postamble' `org-export-html-auto-postamble' +`:author' `user-full-name' +`:email' `user-mail-address' : `addr;addr;..' +`:select-tags' `org-export-select-tags' +`:exclude-tags' `org-export-exclude-tags' +`:latex-image-options' `org-export-latex-image-default-option' + + Most of the `org-export-with-*' variables have the same effect in +both HTML and LaTeX exporters, except for `:TeX-macros' and +`:LaTeX-fragments', respectively `nil' and `t' in the LaTeX 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 (*note Export options::), +however, override everything. + + +File: org, Node: Publishing links, Next: Sitemap, Prev: Publishing options, Up: Configuration + +13.1.6 Links between published files +------------------------------------ + +To create a link from one Org file to another, you would use something +like `[[file:foo.org][The foo]]' or simply `file:foo.org.' (*note +Hyperlinks::). When published, this link becomes a link to `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. If you +also publish the Org source file and want to link to that, use an +`http:' link instead of a `file:' link, because `file:' links are +converted to link to the corresponding `html' file. + + You may also link to related files, such as images. Provided you are +careful with relative file names, and provided you have also configured +Org to upload the related files, these links will work too. See *Note +Complex example::, for an example of this usage. + + Sometimes an Org 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 + +`:link-validation-function' Function to validate links + +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 `nil', then the HTML generator will only insert a +description into the HTML file, but no link. One option for this +function is `org-publish-validate-link' which checks if the given file +is part of any project in `org-publish-project-alist'. + + +File: org, Node: Sitemap, Next: Generating an index, Prev: Publishing links, Up: Configuration + +13.1.7 Generating a sitemap +--------------------------- + +The following properties may be used to control publishing of a map of +files for a given project. + +`:auto-sitemap' When non-nil, publish a sitemap during + `org-publish-current-project' or + `org-publish-all'. +`:sitemap-filename' Filename for output of sitemap. Defaults to + `sitemap.org' (which becomes `sitemap.html'). +`:sitemap-title' Title of sitemap page. Defaults to name of + file. +`:sitemap-function' Plug-in function to use for generation of the + sitemap. Defaults to + `org-publish-org-sitemap', which generates a + plain list of links to all files in the + project. +`:sitemap-sort-folders' Where folders should appear in the sitemap. + Set this to `first' (default) or `last' to + display folders first or last, respectively. + Any other value will mix files and folders. +`:sitemap-alphabetically' The site map is normally sorted + alphabetically. Set this explicitly to `nil' + to turn off sorting. +`:sitemap-ignore-case' Should sorting be case-sensitive? Default + `nil'. + + +File: org, Node: Generating an index, Prev: Sitemap, Up: Configuration + +13.1.8 Generating an index +-------------------------- + +Org-mode can generate an index across the files of a publishing project. + +`:makeindex' When non-nil, generate in index in the file + `theindex.org' and publish it as `theindex.html'. + + The file will be create when first publishing a project with the +`:makeindex' set. The file only contains a statement `#+include: +"theindex.inc"'. You can then built around this include statement by +adding a title, style information etc. + + +File: org, Node: Uploading files, Next: Sample configuration, Prev: Configuration, Up: Publishing + +13.2 Uploading files +==================== + +For those people already utilizing third party sync tools such as +`rsync' or `unison', it might be preferable not to use the built in +remote publishing facilities of Org-mode which rely heavily on Tramp. +Tramp, while very useful and powerful, tends not to be so efficient for +multiple file transfer and has been known to cause problems under heavy +usage. + + Specialized synchronization utilities offer several advantages. In +addition to timestamp comparison, they also do content and +permissions/attribute checks. For this reason you might prefer to +publish your web to a local directory (possibly even in place with your +Org files) and then use `unison' or `rsync' to do the synchronization +with the remote host. + + Since Unison (for example) can be configured as to which files to +transfer to a certain remote destination, it can greatly simplify the +project publishing definition. Simply keep all files in the correct +location, process your Org files with `org-publish' and let the +synchronization tool do the rest. You do not need, in this scenario, +to include attachments such as `jpg', `css' or `gif' files in the +project definition since the 3rd party tool syncs them. + + Publishing to a local directory is also much faster than to a remote +one, so that you can afford more easily to republish entire projects. +If you set `org-publish-use-timestamps-flag' to `nil', you gain the main +benefit of re-including any changed external files such as source +example files you might include with `#+INCLUDE'. The timestamp +mechanism in Org is not smart enough to detect if included files have +been modified. + + +File: org, Node: Sample configuration, Next: Triggering publication, Prev: Uploading files, Up: Publishing + +13.3 Sample configuration +========================= + +Below we provide two example configurations. The first one is a simple +project publishing only a set of Org 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 + + +File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration + +13.3.1 Example: simple publishing configuration +----------------------------------------------- + +This example publishes a set of Org files to the `public_html' +directory on the local machine. + + (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\"/>"))) + + +File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration + +13.3.2 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 +style sheets. 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 `~/org' and your +publishable images in `~/images', you would link to an image with + file:../images/myimage.png + 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 web server, and publishing images to it. + + (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")))) + + +File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing + +13.4 Triggering publication +=========================== + +Once properly configured, Org can publish with the following commands: + +`C-c C-e X (`org-publish')' + Prompt for a specific project and publish all files that belong to + it. + +`C-c C-e P (`org-publish-current-project')' + Publish the project containing the current file. + +`C-c C-e F (`org-publish-current-file')' + Publish only the current file. + +`C-c C-e E (`org-publish-all')' + Publish every project. + + 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 to any of +the commands above, or by customizing the variable +`org-publish-use-timestamps-flag'. This may be necessary in particular +if files include other files via `#+SETUPFILE:' or `#+INCLUDE:'. + + +File: org, Node: Working With Source Code, Next: Miscellaneous, Prev: Publishing, Up: Top + +14 Working with source code +*************************** + +Source code can be included in Org-mode documents using a `src' block, +e.g. + + #+BEGIN_SRC emacs-lisp + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) + #+END_SRC + + Org-mode provides a number of features for working with live source +code, including editing of code blocks in their native major-mode, +evaluation of code blocks, tangling of code blocks, and exporting code +blocks and their results in several formats. This functionality was +contributed by Eric Schulte and Dan Davison, and was originally named +Org-babel. + + The following sections describe Org-mode's code block handling +facilities. + +* Menu: + +* Structure of code blocks:: Code block syntax described +* Editing source code:: Language major-mode editing +* Exporting code blocks:: Export contents and/or results +* Extracting source code:: Create pure source code files +* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Library of Babel:: Use and contribute to a library of useful code blocks +* Languages:: List of supported code block languages +* Header arguments:: Configure code block functionality +* Results of evaluation:: How evaluation results are handled +* Noweb reference syntax:: Literate programming in Org-mode +* Key bindings and useful functions:: Work quickly with code blocks +* Batch execution:: Call functions from the command line + + +File: org, Node: Structure of code blocks, Next: Editing source code, Prev: Working With Source Code, Up: Working With Source Code + +14.1 Structure of code blocks +============================= + +The structure of code blocks is as follows: + + #+srcname: <name> + #+begin_src <language> <switches> <header arguments> + <body> + #+end_src + + code blocks can also be embedded in text as so called inline code +blocks as + + src_<language>{<body>} + + or + + src_<language>[<header arguments>]{<body>} + +`<name>' + This name is associated with the code block. This is similar to + the `#+tblname' lines that can be used to name tables in Org-mode + files. Referencing the name of a code block makes it possible to + evaluate the block from other places in the file, other files, or + from Org-mode table formulas (see *Note The spreadsheet::). + +`<language>' + The language of the code in the block. + +`<switches>' + Switches controlling exportation of the code block (see switches + discussion in *Note Literal examples::) + +`<header arguments>' + Optional header arguments control many aspects of evaluation, + export and tangling of code blocks. See the *Note Header + arguments:: section. Header arguments can also be set on a + per-buffer or per-subtree basis using properties. + +`<body>' + The source code. + + +File: org, Node: Editing source code, Next: Exporting code blocks, Prev: Structure of code blocks, Up: Working With Source Code + +14.2 Editing source code +======================== + +Use `C-c '' to edit the current code block. This brings up a language +major-mode edit buffer containing the body of the code block. Saving +this buffer will write the new contents back to the Org buffer. Use +`C-c '' again to exit. + + The `org-src-mode' minor mode will be active in the edit buffer. The +following variables can be used to configure the behavior of the edit +buffer. See also the customization group `org-edit-structure' for +further configuration options. + +`org-src-lang-modes' + If an Emacs major-mode named `<lang>-mode' exists, where `<lang>' + is the language named in the header line of the code block, then + the edit buffer will be placed in that major-mode. This variable + can be used to map arbitrary language names to existing major + modes. + +`org-src-window-setup' + Controls the way Emacs windows are rearranged when the edit buffer + is created. + +`org-src-preserve-indentation' + This variable is especially useful for tangling languages such as + Python, in which whitespace indentation in the output is critical. + +`org-src-ask-before-returning-to-edit-buffer' + By default, Org will ask before returning to an open edit buffer. + Set this variable to nil to switch without asking. + + +File: org, Node: Exporting code blocks, Next: Extracting source code, Prev: Editing source code, Up: Working With Source Code + +14.3 Exporting code blocks +========================== + +It is possible to export the _contents_ of code blocks, the _results_ +of code block evaluation, _neither_, or _both_. For most languages, +the default exports the contents of code blocks. However, for some +languages (e.g. `ditaa') the default exports the results of code block +evaluation. For information on exporting code block bodies, see *Note +Literal examples::. + + The `:exports' header argument can be used to specify export +behavior: + +Header arguments: +................. + +`:exports code' + The default in most languages. The body of the code block is + exported, as described in *Note Literal examples::. + +`:exports results' + The code block will be evaluated and the results will be placed in + the Org-mode buffer for export, either updating previous results + of the code block located anywhere in the buffer or, if no + previous results exist, placing the results immediately after the + code block. The body of the code block will not be exported. + +`:exports both' + Both the code block and its results will be exported. + +`:exports none' + Neither the code block nor its results will be exported. + + It is possible to inhibit the evaluation of code blocks during +export. Setting the `org-export-babel-evaluate' variable to `nil' will +ensure that no code blocks are evaluated as part of the export process. +This can be useful in situations where potentially untrusted Org-mode +files are exported in an automated fashion, for example when Org-mode +is used as the markup language for a wiki. + + +File: org, Node: Extracting source code, Next: Evaluating code blocks, Prev: Exporting code blocks, Up: Working With Source Code + +14.4 Extracting source code +=========================== + +Creating pure source code files by extracting code from source blocks is +referred to as "tangling"--a term adopted from the literate programming +community. During "tangling" of code blocks their bodies are expanded +using `org-babel-expand-src-block' which can expand both variable and +"noweb" style references (see *Note Noweb reference syntax::). + +Header arguments +................ + +`:tangle no' + The default. The code block is not included in the tangled output. + +`:tangle yes' + Include the code block in the tangled output. The output file name + is the name of the org file with the extension `.org' replaced by + the extension for the block language. + +`:tangle filename' + Include the code block in the tangled output to file `filename'. + +Functions +......... + +`org-babel-tangle' + Tangle the current file. Bound to `C-c C-v t'. + +`org-babel-tangle-file' + Choose a file to tangle. Bound to `C-c C-v f'. + +Hooks +..... + +`org-babel-post-tangle-hook' + This hook is run from within code files tangled by + `org-babel-tangle'. Example applications could include + post-processing, compilation or evaluation of tangled code files. + + +File: org, Node: Evaluating code blocks, Next: Library of Babel, Prev: Extracting source code, Up: Working With Source Code + +14.5 Evaluating code blocks +=========================== + +Code blocks can be evaluated(1) and the results placed in the Org-mode +buffer. By default, evaluation is only turned on for `emacs-lisp' code +blocks, however support exists for evaluating blocks in many languages. +See *Note Languages:: for a list of supported languages. See *Note +Structure of code blocks:: for information on the syntax used to define +a code block. + + There are a number of ways to evaluate code blocks. The simplest is +to press `C-c C-c' or `C-c C-v e' with the point on a code block(2). +This will call the `org-babel-execute-src-block' function to evaluate +the block and insert its results into the Org-mode buffer. + + It is also possible to evaluate named code blocks from anywhere in an +Org-mode buffer or an Org-mode table. `#+call' (or synonymously +`#+function' or `#+lob') lines can be used to remotely execute code +blocks located in the current Org-mode buffer or in the "Library of +Babel" (see *Note Library of Babel::). These lines use the following +syntax. + + #+call: <name>(<arguments>) <header arguments> + #+function: <name>(<arguments>) <header arguments> + #+lob: <name>(<arguments>) <header arguments> + +`<name>' + The name of the code block to be evaluated. + +`<arguments>' + Arguments specified in this section will be passed to the code + block. + +`<header arguments>' + Header arguments can be placed after the function invocation. See + *Note Header arguments:: for more information on header arguments. + + ---------- Footnotes ---------- + + (1) Whenever code is evaluated there is a potential for that code to +do harm. Org-mode provides a number of safeguards to ensure that it +only evaluates code with explicit confirmation from the user. For +information on these safeguards (and on how to disable them) see *Note +Code evaluation security::. + + (2) The `org-babel-no-eval-on-ctrl-c-ctrl-c' variable can be used to +remove code evaluation from the `C-c C-c' key binding. + + +File: org, Node: Library of Babel, Next: Languages, Prev: Evaluating code blocks, Up: Working With Source Code + +14.6 Library of Babel +===================== + +The "Library of Babel" is a library of code blocks that can be called +from any Org-mode file. The library is housed in an Org-mode file +located in the `contrib' directory of Org-mode. Org-mode users can +deposit functions they believe to be generally useful in the library. + + Code blocks defined in the "Library of Babel" can be called remotely +as if they were in the current Org-mode buffer (see *Note Evaluating +code blocks:: for information on the syntax of remote code block +evaluation). + + Code blocks located in any Org-mode file can be loaded into the +"Library of Babel" with the `org-babel-lob-ingest' function, bound to +`C-c C-v i'. + + +File: org, Node: Languages, Next: Header arguments, Prev: Library of Babel, Up: Working With Source Code + +14.7 Languages +============== + +Code blocks in the following languages are supported. + +Language Identifier Language Identifier +Asymptote asymptote C C +C++ C++ Clojure clojure +CSS css ditaa ditaa +Graphviz dot Emacs Lisp emacs-lisp +gnuplot gnuplot Haskell haskell +LaTeX latex MATLAB matlab +Mscgen mscgen Objective Caml ocaml +Octave octave Oz oz +Perl perl Python python +R R Ruby ruby +Sass sass GNU Screen screen +shell sh SQL sql +SQLite sqlite + + Language-specific documentation is available for some languages. If +available, it can be found at +`http://orgmode.org/worg/org-contrib/babel/languages'. + + The `org-babel-load-languages' controls which languages are enabled +for evaluation (by default only `emacs-lisp' is enabled). This +variable can be set using the customization interface or by adding code +like the following to your emacs configuration. + + The following disables `emacs-lisp' evaluation and enables + evaluation of `R' code blocks. + + (org-babel-do-load-languages + 'org-babel-load-languages + '((emacs-lisp . nil) + (R . t))) + + It is also possible to enable support for a language by loading the +related elisp file with `require'. + + The following adds support for evaluating `clojure' code blocks. + + (require 'ob-clojure) + + +File: org, Node: Header arguments, Next: Results of evaluation, Prev: Languages, Up: Working With Source Code + +14.8 Header arguments +===================== + +Code block functionality can be configured with header arguments. This +section provides an overview of the use of header arguments, and then +describes each header argument in detail. + +* Menu: + +* Using header arguments:: Different ways to set header arguments +* Specific header arguments:: List of header arguments + + +File: org, Node: Using header arguments, Next: Specific header arguments, Prev: Header arguments, Up: Header arguments + +14.8.1 Using header arguments +----------------------------- + +The values of header arguments can be set in six different ways, each +more specific (and having higher priority) than the last. + +* Menu: + +* System-wide header arguments:: Set global default values +* Language-specific header arguments:: Set default values by language +* Buffer-wide header arguments:: Set default values for a specific buffer +* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Code block specific header arguments:: The most common way to set values +* Header arguments in function calls:: The most specific level + + +File: org, Node: System-wide header arguments, Next: Language-specific header arguments, Prev: Using header arguments, Up: Using header arguments + +System-wide header arguments +............................ + +System-wide values of header arguments can be specified by customizing +the `org-babel-default-header-args' variable: + + :session => "none" + :results => "replace" + :exports => "code" + :cache => "no" + :noweb => "no" + + For example, the following example could be used to set the default +value of `:noweb' header arguments to `yes'. This would have the +effect of expanding `:noweb' references by default when evaluating +source code blocks. + + (setq org-babel-default-header-args + (cons '(:noweb . "yes") + (assq-delete-all :noweb org-babel-default-header-args))) + + +File: org, Node: Language-specific header arguments, Next: Buffer-wide header arguments, Prev: System-wide header arguments, Up: Using header arguments + +Language-specific header arguments +.................................. + +Each language can define its own set of default header arguments. See +the language-specific documentation available online at +`http://orgmode.org/worg/org-contrib/babel'. + + +File: org, Node: Buffer-wide header arguments, Next: Header arguments in Org-mode properties, Prev: Language-specific header arguments, Up: Using header arguments + +Buffer-wide header arguments +............................ + +Buffer-wide header arguments may be specified through the use of a +special line placed anywhere in an Org-mode file. The line consists of +the `#+BABEL:' keyword followed by a series of header arguments which +may be specified using the standard header argument syntax. + + For example the following would set `session' to `*R*', and +`results' to `silent' for every code block in the buffer, ensuring that +all execution took place in the same session, and no results would be +inserted into the buffer. + + #+BABEL: :session *R* :results silent + + +File: org, Node: Header arguments in Org-mode properties, Next: Code block specific header arguments, Prev: Buffer-wide header arguments, Up: Using header arguments + +Header arguments in Org-mode properties +....................................... + +Header arguments are also read from Org-mode properties (see *Note +Property syntax::), which can be set on a buffer-wide or per-heading +basis. An example of setting a header argument for all code blocks in a +buffer is + + #+property: tangle yes + + When properties are used to set default header arguments, they are +looked up with inheritance, so the value of the `:cache' header +argument will default to `yes' in all code blocks in the subtree rooted +at the following heading: + + * outline header + :PROPERTIES: + :cache: yes + :END: + + Properties defined in this way override the properties set in +`org-babel-default-header-args'. It is convenient to use the +`org-set-property' function bound to `C-c C-x p' to set properties in +Org-mode documents. + + +File: org, Node: Code block specific header arguments, Next: Header arguments in function calls, Prev: Header arguments in Org-mode properties, Up: Using header arguments + +Code block specific header arguments +.................................... + +The most common way to assign values to header arguments is at the code +block level. This can be done by listing a sequence of header +arguments and their values as part of the `#+begin_src' line. +Properties set in this way override both the values of +`org-babel-default-header-args' and header arguments specified as +properties. In the following example, the `:results' header argument +is set to `silent', meaning the results of execution will not be +inserted in the buffer, and the `:exports' header argument is set to +`code', meaning only the body of the code block will be preserved on +export to HTML or LaTeX. + + #+source: factorial + #+begin_src haskell :results silent :exports code :var n=0 + fac 0 = 1 + fac n = n * fac (n-1) + #+end_src + Similarly, it is possible to set header arguments for inline code +blocks: + + src_haskell[:exports both]{fac 5} + + +File: org, Node: Header arguments in function calls, Prev: Code block specific header arguments, Up: Using header arguments + +Header arguments in function calls +.................................. + +At the most specific level, header arguments for "Library of Babel" or +function call lines can be set as shown below: + + #+call: factorial(n=5) :exports results + + +File: org, Node: Specific header arguments, Prev: Using header arguments, Up: Header arguments + +14.8.2 Specific header arguments +-------------------------------- + +The following header arguments are defined: + +* Menu: + +* var:: Pass arguments to code blocks +* results:: Specify the type of results and how they will + be collected and handled +* file:: Specify a path for file output +* dir:: Specify the default (possibly remote) + directory for code block execution +* exports:: Export code and/or results +* tangle:: Toggle tangling and specify file name +* comments:: Toggle insertion of comments in tangled + code files +* no-expand:: Turn off variable assignment and noweb + expansion during tangling +* session:: Preserve the state of code evaluation +* noweb:: Toggle expansion of noweb references +* cache:: Avoid re-evaluating unchanged code blocks +* hlines:: Handle horizontal lines in tables +* colnames:: Handle column names in tables +* rownames:: Handle row names in tables +* shebang:: Make tangled files executable +* eval:: Limit evaluation of specific code blocks + + +File: org, Node: var, Next: results, Prev: Specific header arguments, Up: Specific header arguments + +14.8.2.1 `:var' +............... + +The `:var' header argument is used to pass arguments to code blocks. +The specifics of how arguments are included in a code block vary by +language; these are addressed in the language-specific documentation. +However, the syntax used to specify arguments is the same across all +languages. The values passed to arguments can be literal values, +values from org-mode tables and literal example blocks, or the results +of other code blocks. + + These values can be indexed in a manner similar to arrays--see the +"indexable variable values" heading below. + + The following syntax is used to pass arguments to code blocks using +the `:var' header argument. + + :var name=assign + + where `assign' can take one of the following forms + + * literal value either a string `"string"' or a number `9'. + + * reference a table name: + + #+tblname: example-table + | 1 | + | 2 | + | 3 | + | 4 | + + #+source: table-length + #+begin_src emacs-lisp :var table=example-table + (length table) + #+end_src + + #+results: table-length + : 4 + + a code block name, as assigned by `#+srcname:', followed by + parentheses: + + #+begin_src emacs-lisp :var length=table-length() + (* 2 length) + #+end_src + + #+results: + : 8 + + In addition, an argument can be passed to the code block referenced + by `:var'. The argument is passed within the parentheses + following the code block name: + + #+source: double + #+begin_src emacs-lisp :var input=8 + (* 2 input) + #+end_src + + #+results: double + : 16 + + #+source: squared + #+begin_src emacs-lisp :var input=double(input=1) + (* input input) + #+end_src + + #+results: squared + : 4 + +Alternate argument syntax +......................... + +It is also possible to specify arguments in a potentially more natural +way using the `#+source:' line of a code block. As in the following +example arguments can be packed inside of parenthesis, separated by +commas, following the source name. + + #+source: double(input=0, x=2) + #+begin_src emacs-lisp + (* 2 (+ input x)) + #+end_src + +Indexable variable values +......................... + +It is possible to reference portions of variable values by "indexing" +into the variables. Indexes are 0 based with negative values counting +back from the end. If an index is separated by `,'s then each +subsequent section will index into the next deepest nesting or +dimension of the value. The following example assigns the last cell of +the first row the table `example-table' to the variable `data': + + #+results: example-table + | 1 | a | + | 2 | b | + | 3 | c | + | 4 | d | + + #+begin_src emacs-lisp :var data=example-table[0,-1] + data + #+end_src + + #+results: + : a + + Ranges of variable values can be referenced using two integers +separated by a `:', in which case the entire inclusive range is +referenced. For example the following assigns the middle three rows of +`example-table' to `data'. + + #+results: example-table + | 1 | a | + | 2 | b | + | 3 | c | + | 4 | d | + | 5 | 3 | + + #+begin_src emacs-lisp :var data=example-table[1:3] + data + #+end_src + + #+results: + | 2 | b | + | 3 | c | + | 4 | d | + + Additionally, an empty index, or the single character `*', are both +interpreted to mean the entire range and as such are equivalent to +`0:-1', as shown in the following example in which the entire first +column is referenced. + + #+results: example-table + | 1 | a | + | 2 | b | + | 3 | c | + | 4 | d | + + #+begin_src emacs-lisp :var data=example-table[,0] + data + #+end_src + + #+results: + | 1 | 2 | 3 | 4 | + + It is possible to index into the results of code blocks as well as +tables. Any number of dimensions can be indexed. Dimensions are +separated from one another by commas, as shown in the following example. + + #+source: 3D + #+begin_src emacs-lisp + '(((1 2 3) (4 5 6) (7 8 9)) + ((10 11 12) (13 14 15) (16 17 18)) + ((19 20 21) (22 23 24) (25 26 27))) + #+end_src + + #+begin_src emacs-lisp :var data=3D[1,,1] + data + #+end_src + + #+results: + | 11 | 14 | 17 | + + +File: org, Node: results, Next: file, Prev: var, Up: Specific header arguments + +14.8.2.2 `:results' +................... + +There are three classes of `:results' header argument. Only one option +per class may be supplied per code block. + + * collection header arguments specify how the results should be + collected from the code block + + * type header arguments specify what type of result the code block + will return--which has implications for how they will be inserted + into the Org-mode buffer + + * handling header arguments specify how the results of evaluating + the code block should be handled. + +Collection +.......... + +The following options are mutually exclusive, and specify how the +results should be collected from the code block. + + * `value' This is the default. The result is the value of the last + statement in the code block. This header argument places the + evaluation in functional mode. Note that in some languages, e.g., + Python, use of this result type requires that a `return' statement + be included in the body of the source code block. E.g., `:results + value'. + + * `output' The result is the collection of everything printed to + STDOUT during the execution of the code block. This header + argument places the evaluation in scripting mode. E.g., `:results + output'. + +Type +.... + +The following options are mutually exclusive and specify what type of +results the code block will return. By default, results are inserted +as either a table or scalar depending on their value. + + * `table', `vector' The results should be interpreted as an Org-mode + table. If a single value is returned, it will be converted into a + table with one row and one column. E.g., `:results value table'. + + * `list' The results should be interpreted as an Org-mode list. If + a single scalar value is returned it will be converted into a list + with only one element. + + * `scalar', `verbatim' The results should be interpreted + literally--they will not be converted into a table. The results + will be inserted into the Org-mode buffer as quoted text. E.g., + `:results value verbatim'. + + * `file' The results will be interpreted as the path to a file, and + will be inserted into the Org-mode buffer as a file link. E.g., + `:results value file'. + + * `raw', `org' The results are interpreted as raw Org-mode code and + are inserted directly into the buffer. If the results look like a + table they will be aligned as such by Org-mode. E.g., `:results + value raw'. + + * `html' Results are assumed to be HTML and will be enclosed in a + `begin_html' block. E.g., `:results value html'. + + * `latex' Results assumed to be LaTeX and are enclosed in a + `begin_latex' block. E.g., `:results value latex'. + + * `code' Result are assumed to be parseable code and are enclosed in + a code block. E.g., `:results value code'. + + * `pp' The result is converted to pretty-printed code and is + enclosed in a code block. This option currently supports Emacs + Lisp, Python, and Ruby. E.g., `:results value pp'. + +Handling +........ + +The following results options indicate what happens with the results +once they are collected. + + * `silent' The results will be echoed in the minibuffer but will not + be inserted into the Org-mode buffer. E.g., `:results output + silent'. + + * `replace' The default value. Any existing results will be + removed, and the new results will be inserted into the Org-mode + buffer in their place. E.g., `:results output replace'. + + * `append' If there are pre-existing results of the code block then + the new results will be appended to the existing results. + Otherwise the new results will be inserted as with `replace'. + + * `prepend' If there are pre-existing results of the code block then + the new results will be prepended to the existing results. + Otherwise the new results will be inserted as with `replace'. + + +File: org, Node: file, Next: dir, Prev: results, Up: Specific header arguments + +14.8.2.3 `:file' +................ + +The header argument `:file' is used to specify a path for file output. +An Org-mode style `file:' link is inserted into the buffer as the result +(see *Note Link format::). Common examples are graphical output from R, +gnuplot, ditaa and LaTeX code blocks. + + Note that for some languages, including R, gnuplot, LaTeX and ditaa, +graphical output is sent to the specified file without the file being +referenced explicitly in the code block. See the documentation for the +individual languages for details. In contrast, general purpose +languages such as Python and Ruby require that the code explicitly +create output corresponding to the path indicated by `:file'. + + +File: org, Node: dir, Next: exports, Prev: file, Up: Specific header arguments + +14.8.2.4 `:dir' and remote execution +.................................... + +While the `:file' header argument can be used to specify the path to the +output file, `:dir' specifies the default directory during code block +execution. If it is absent, then the directory associated with the +current buffer is used. In other words, supplying `:dir path' +temporarily has the same effect as changing the current directory with +`M-x cd path', and then not supplying `:dir'. Under the surface, `:dir' +simply sets the value of the Emacs variable `default-directory'. + + When using `:dir', you should supply a relative path for file output +(e.g. `:file myfile.jpg' or `:file results/myfile.jpg') in which case +that path will be interpreted relative to the default directory. + + In other words, if you want your plot to go into a folder called +`Work' in your home directory, you could use + + #+begin_src R :file myplot.png :dir ~/Work + matplot(matrix(rnorm(100), 10), type="l") + #+end_src + +Remote execution +................ + +A directory on a remote machine can be specified using tramp file +syntax, in which case the code will be evaluated on the remote machine. +An example is + + #+begin_src R :file plot.png :dir /dand@yakuba.princeton.edu: + plot(1:10, main=system("hostname", intern=TRUE)) + #+end_src + + Text results will be returned to the local Org-mode buffer as usual, +and file output will be created on the remote machine with relative +paths interpreted relative to the remote directory. An Org-mode link to +the remote file will be created. + + So, in the above example a plot will be created on the remote +machine, and a link of the following form will be inserted in the org +buffer: + + [[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] + + Most of this functionality follows immediately from the fact that +`:dir' sets the value of the Emacs variable `default-directory', thanks +to tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need +to install tramp separately in order for these features to work +correctly. + +Further points +.............. + + * If `:dir' is used in conjunction with `:session', although it will + determine the starting directory for a new session as expected, no + attempt is currently made to alter the directory associated with + an existing session. + + * `:dir' should typically not be used to create files during export + with `:exports results' or `:exports both'. The reason is that, in + order to retain portability of exported material between machines, + during export links inserted into the buffer will *not* be + expanded against `default directory'. Therefore, if + `default-directory' is altered using `:dir', it is probable that + the file will be created in a location to which the link does not + point. + + +File: org, Node: exports, Next: tangle, Prev: dir, Up: Specific header arguments + +14.8.2.5 `:exports' +................... + +The `:exports' header argument specifies what should be included in HTML +or LaTeX exports of the Org-mode file. + + * `code' The default. The body of code is included into the + exported file. E.g., `:exports code'. + + * `results' The result of evaluating the code is included in the + exported file. E.g., `:exports results'. + + * `both' Both the code and results are included in the exported + file. E.g., `:exports both'. + + * `none' Nothing is included in the exported file. E.g., `:exports + none'. + + +File: org, Node: tangle, Next: comments, Prev: exports, Up: Specific header arguments + +14.8.2.6 `:tangle' +.................. + +The `:tangle' header argument specifies whether or not the code block +should be included in tangled extraction of source code files. + + * `tangle' The code block is exported to a source code file named + after the basename (name w/o extension) of the Org-mode file. + E.g., `:tangle yes'. + + * `no' The default. The code block is not exported to a source code + file. E.g., `:tangle no'. + + * other Any other string passed to the `:tangle' header argument is + interpreted as a file basename to which the block will be + exported. E.g., `:tangle basename'. + + +File: org, Node: comments, Next: no-expand, Prev: tangle, Up: Specific header arguments + +14.8.2.7 `:comments' +.................... + +By default code blocks are tangled to source-code files without any +insertion of comments beyond those which may already exist in the body +of the code block. The `:comments' header argument can be set as +follows to control the insertion of extra comments into the tangled +code file. + + * `no' The default. No extra comments are inserted during tangling. + + * `link' The code block is wrapped in comments which contain + pointers back to the original Org file from which the code was + tangled. + + * `yes' A synonym for "link" to maintain backwards compatibility. + + * `org' Include text from the org-mode file as a comment. + + The text is picked from the leading context of the tangled code + and is limited by the nearest headline or source block as the case + may be. + + * `both' Turns on both the "link" and "org" comment options. + + +File: org, Node: no-expand, Next: session, Prev: comments, Up: Specific header arguments + +14.8.2.8 `:no-expand' +..................... + +By default, code blocks are expanded with `org-babel-expand-src-block' +during tangling. This has the effect of assigning values to variables +specified with `:var' (see *Note var::), and of replacing "noweb" +references (see *Note Noweb reference syntax::) with their targets. The +`:no-expand' header argument can be used to turn off this behavior. + + +File: org, Node: session, Next: noweb, Prev: no-expand, Up: Specific header arguments + +14.8.2.9 `:session' +................... + +The `:session' header argument starts a session for an interpreted +language where state is preserved. + + By default, a session is not started. + + A string passed to the `:session' header argument will give the +session a name. This makes it possible to run concurrent sessions for +each interpreted language. + + +File: org, Node: noweb, Next: cache, Prev: session, Up: Specific header arguments + +14.8.2.10 `:noweb' +.................. + +The `:noweb' header argument controls expansion of "noweb" style (see +*Note Noweb reference syntax::) references in a code block. This header +argument can have one of three values: `yes' `no' or `tangle'. + + * `yes' All "noweb" syntax references in the body of the code block + will be expanded before the block is evaluated, tangled or + exported. + + * `no' The default. No "noweb" syntax specific action is taken on + evaluating code blocks, However, noweb references will still be + expanded during tangling. + + * `tangle' All "noweb" syntax references in the body of the code + block will be expanded before the block is tangled, however + "noweb" references will not be expanded when the block is + evaluated or exported. + +Noweb prefix lines +.................. + +Noweb insertions are now placed behind the line prefix of the +`<<reference>>'. This behavior is illustrated in the following +example. Because the `<<example>>' noweb reference appears behind the +SQL comment syntax, each line of the expanded noweb reference will be +commented. + + This code block: + + -- <<example>> + + expands to: + + -- this is the + -- multi-line body of example + + Note that noweb replacement text that does not contain any newlines +will not be affected by this change, so it is still possible to use +inline noweb references. + + +File: org, Node: cache, Next: hlines, Prev: noweb, Up: Specific header arguments + +14.8.2.11 `:cache' +.................. + +The `:cache' header argument controls the use of in-buffer caching of +the results of evaluating code blocks. It can be used to avoid +re-evaluating unchanged code blocks. This header argument can have one +of two values: `yes' or `no'. + + * `no' The default. No caching takes place, and the code block will + be evaluated every time it is called. + + * `yes' Every time the code block is run a SHA1 hash of the code and + arguments passed to the block will be generated. This hash is + packed into the `#+results:' line and will be checked on subsequent + executions of the code block. If the code block has not changed + since the last time it was evaluated, it will not be re-evaluated. + + +File: org, Node: hlines, Next: colnames, Prev: cache, Up: Specific header arguments + +14.8.2.12 `:hlines' +................... + +Tables are frequently represented with one or more horizontal lines, or +hlines. The `:hlines' argument to a code block accepts the values +`yes' or `no', with a default value of `no'. + + * `no' Strips horizontal lines from the input table. In most + languages this is the desired effect because an `hline' symbol is + interpreted as an unbound variable and raises an error. Setting + `:hlines no' or relying on the default value yields the following + results. + + #+tblname: many-cols + | a | b | c | + |---+---+---| + | d | e | f | + |---+---+---| + | g | h | i | + + #+source: echo-table + #+begin_src python :var tab=many-cols + return tab + #+end_src + + #+results: echo-table + | a | b | c | + | d | e | f | + | g | h | i | + + * `yes' Leaves hlines in the table. Setting `:hlines yes' has this + effect. + + #+tblname: many-cols + | a | b | c | + |---+---+---| + | d | e | f | + |---+---+---| + | g | h | i | + + #+source: echo-table + #+begin_src python :var tab=many-cols :hlines yes + return tab + #+end_src + + #+results: echo-table + | a | b | c | + |---+---+---| + | d | e | f | + |---+---+---| + | g | h | i | + + +File: org, Node: colnames, Next: rownames, Prev: hlines, Up: Specific header arguments + +14.8.2.13 `:colnames' +..................... + +The `:colnames' header argument accepts the values `yes', `no', or +`nil' for unassigned. The default value is `nil'. + + * `nil' If an input table looks like it has column names (because + its second row is an hline), then the column names will be removed + from the table before processing, then reapplied to the results. + + #+tblname: less-cols + | a | + |---| + | b | + | c | + + #+srcname: echo-table-again + #+begin_src python :var tab=less-cols + return [[val + '*' for val in row] for row in tab] + #+end_src + + #+results: echo-table-again + | a | + |----| + | b* | + | c* | + + * `no' No column name pre-processing takes place + + * `yes' Column names are removed and reapplied as with `nil' even if + the table does not "look like" it has column names (i.e. the + second row is not an hline) + + +File: org, Node: rownames, Next: shebang, Prev: colnames, Up: Specific header arguments + +14.8.2.14 `:rownames' +..................... + +The `:rownames' header argument can take on the values `yes' or `no', +with a default value of `no'. + + * `no' No row name pre-processing will take place. + + * `yes' The first column of the table is removed from the table + before processing, and is then reapplied to the results. + + #+tblname: with-rownames + | one | 1 | 2 | 3 | 4 | 5 | + | two | 6 | 7 | 8 | 9 | 10 | + + #+srcname: echo-table-once-again + #+begin_src python :var tab=with-rownames :rownames yes + return [[val + 10 for val in row] for row in tab] + #+end_src + + #+results: echo-table-once-again + | one | 11 | 12 | 13 | 14 | 15 | + | two | 16 | 17 | 18 | 19 | 20 | + + +File: org, Node: shebang, Next: eval, Prev: rownames, Up: Specific header arguments + +14.8.2.15 `:shebang' +.................... + +Setting the `:shebang' header argument to a string value (e.g. +`:shebang "#!/bin/bash"') causes the string to be inserted as the first +line of any tangled file holding the code block, and the file +permissions of the tangled file are set to make it executable. + + +File: org, Node: eval, Prev: shebang, Up: Specific header arguments + +14.8.2.16 `:eval' +................. + +The `:eval' header argument can be used to limit the evaluation of +specific code blocks. `:eval' accepts two arguments "never" and +"query". `:eval never' will ensure that a code block is never +evaluated, this can be useful for protecting against the evaluation of +dangerous code blocks. `:eval query' will require a query for every +execution of a code block regardless of the value of the +`org-confirm-babel-evaluate' variable. + + +File: org, Node: Results of evaluation, Next: Noweb reference syntax, Prev: Header arguments, Up: Working With Source Code + +14.9 Results of evaluation +========================== + +The way in which results are handled depends on whether a session is +invoked, as well as on whether `:results value' or `:results output' is +used. The following table shows the possibilities: + + Non-session Session +`:results value' value of last value of last expression + expression +`:results output' contents of STDOUT concatenation of interpreter + output + + Note: With `:results value', the result in both `:session' and +non-session is returned to Org-mode as a table (a one- or +two-dimensional vector of strings or numbers) when appropriate. + +14.9.1 Non-session +------------------ + +14.9.1.1 `:results value' +......................... + +This is the default. Internally, the value is obtained by wrapping the +code in a function definition in the external language, and evaluating +that function. Therefore, code should be written as if it were the body +of such a function. In particular, note that Python does not +automatically return a value from a function unless a `return' +statement is present, and so a `return' statement will usually be +required in Python. + + This is the only one of the four evaluation contexts in which the +code is automatically wrapped in a function definition. + +14.9.1.2 `:results output' +.......................... + +The code is passed to the interpreter as an external process, and the +contents of the standard output stream are returned as text. (In certain +languages this also contains the error output stream; this is an area +for future work.) + +14.9.2 Session +-------------- + +14.9.2.1 `:results value' +......................... + +The code is passed to the interpreter running as an interactive Emacs +inferior process. The result returned is the result of the last +evaluation performed by the interpreter. (This is obtained in a +language-specific manner: the value of the variable `_' in Python and +Ruby, and the value of `.Last.value' in R). + +14.9.2.2 `:results output' +.......................... + +The code is passed to the interpreter running as an interactive Emacs +inferior process. The result returned is the concatenation of the +sequence of (text) output from the interactive interpreter. Notice that +this is not necessarily the same as what would be sent to `STDOUT' if +the same code were passed to a non-interactive interpreter running as +an external process. For example, compare the following two blocks: + + #+begin_src python :results output + print "hello" + 2 + print "bye" + #+end_src + + #+resname: + : hello + : bye + + In non-session mode, the `2' is not printed and does not appear. + #+begin_src python :results output :session + print "hello" + 2 + print "bye" + #+end_src + + #+resname: + : hello + : 2 + : bye + + But in `:session' mode, the interactive interpreter receives input +`2' and prints out its value, `2'. (Indeed, the other print statements +are unnecessary here). + + +File: org, Node: Noweb reference syntax, Next: Key bindings and useful functions, Prev: Results of evaluation, Up: Working With Source Code + +14.10 Noweb reference syntax +============================ + +The "noweb" (see `http://www.cs.tufts.edu/~nr/noweb/') Literate +Programming system allows named blocks of code to be referenced by +using the familiar Noweb syntax: + + <<code-block-name>> + + When a code block is tangled or evaluated, whether or not "noweb" +references are expanded depends upon the value of the `:noweb' header +argument. If `:noweb yes', then a Noweb reference is expanded before +evaluation. If `:noweb no', the default, then the reference is not +expanded before evaluation. + + Note: the default value, `:noweb no', was chosen to ensure that +correct code is not broken in a language, such as Ruby, where `<<arg>>' +is a syntactically valid construct. If `<<arg>>' is not syntactically +valid in languages that you use, then please consider setting the +default value. + + +File: org, Node: Key bindings and useful functions, Next: Batch execution, Prev: Noweb reference syntax, Up: Working With Source Code + +14.11 Key bindings and useful functions +======================================= + +Many common Org-mode key sequences are re-bound depending on the +context. + + Within a code block, the following key bindings are active: + +`C-c C-c' org-babel-execute-src-block +`C-c C-o' org-babel-open-src-block-result +`C-<up>' org-babel-load-in-session +`M-<down>' org-babel-pop-to-session + + In an Org-mode buffer, the following key bindings are active: + +`C-c C-v a' or `C-c C-v org-babel-sha1-hash +C-a' +`C-c C-v b' or `C-c C-v org-babel-execute-buffer +C-b' +`C-c C-v f' or `C-c C-v org-babel-tangle-file +C-f' +`C-c C-v g' org-babel-goto-named-source-block +`C-c C-v h' org-babel-describe-bindings +`C-c C-v l' or `C-c C-v org-babel-lob-ingest +C-l' +`C-c C-v p' or `C-c C-v org-babel-expand-src-block +C-p' +`C-c C-v s' or `C-c C-v org-babel-execute-subtree +C-s' +`C-c C-v t' or `C-c C-v org-babel-tangle +C-t' +`C-c C-v z' or `C-c C-v org-babel-switch-to-session +C-z' + + +File: org, Node: Batch execution, Prev: Key bindings and useful functions, Up: Working With Source Code + +14.12 Batch execution +===================== + +It is possible to call functions from the command line. This shell +script calls `org-babel-tangle' on every one of its arguments. + + Be sure to adjust the paths to fit your system. + + #!/bin/sh + # -*- mode: shell-script -*- + # + # tangle files with org-mode + # + DIR=`pwd` + FILES="" + ORGINSTALL="~/src/org/lisp/org-install.el" + + # wrap each argument in the code required to call tangle on it + for i in $@; do + FILES="$FILES \"$i\"" + done + + emacs -Q --batch -l $ORGINSTALL \ + --eval "(progn + (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) + (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) + (require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle) + (mapc (lambda (file) + (find-file (expand-file-name file \"$DIR\")) + (org-babel-tangle) + (kill-buffer)) '($FILES)))" 2>&1 |grep tangled + + +File: org, Node: Miscellaneous, Next: Hacking, Prev: Working With Source Code, Up: Top + +15 Miscellaneous +**************** + +* Menu: + +* Completion:: M-TAB knows what you need +* Easy Templates:: Quick insertion of structural elements +* Speed keys:: Electric commands at the beginning of a headline +* Code evaluation security:: Org mode files evaluate inline code +* Customization:: Adapting Org 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 on a tty +* Interaction:: Other Emacs packages + + +File: org, Node: Completion, Next: Easy Templates, Prev: Miscellaneous, Up: Miscellaneous + +15.1 Completion +=============== + +Emacs would not be Emacs without completion, and Org-mode uses it +whenever it makes sense. If you prefer an iswitchb- or ido-like +interface for some of the completion prompts, you can specify your +preference by setting at most one of the variables +`org-completion-use-iswitchb' `org-completion-use-ido'. + + Org 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. + +`M-<TAB>' + Complete word at point + * At the beginning of a headline, complete TODO keywords. + + * After `\', complete TeX symbols supported by the exporter. + + * After `*', complete headlines in the current buffer so that + they can be used in search links like `[[*find this + headline]]'. + + * After `:' in a headline, complete tags. The list of tags is + taken from the variable `org-tag-alist' (possibly set through + the `#+TAGS' in-buffer option, *note Setting tags::), or it + is created dynamically from all tags used in the current + buffer. + + * After `:' and not in a headline, complete property keys. The + list of keys is constructed dynamically from all keys used in + the current buffer. + + * After `[', complete link abbreviations (*note Link + abbreviations::). + + * After `#+', complete the special keywords like `TYP_TODO' or + `OPTIONS' which set file-specific options for Org-mode. When + the option keyword is already complete, pressing `M-<TAB>' + again will insert example settings for this keyword. + + * In the line after `#+STARTUP: ', complete startup keywords, + i.e. valid keys for this line. + + * Elsewhere, complete dictionary words using Ispell. + + +File: org, Node: Easy Templates, Next: Speed keys, Prev: Completion, Up: Miscellaneous + +15.2 Easy Templates +=================== + +Org-mode supports insertion of empty structural elements (like +`#+BEGIN_SRC' and `#+END_SRC' pairs) with just a few key strokes. This +is achieved through a native template expansion mechanism. Note that +Emacs has several other template mechanisms which could be used in a +similar way, for example `yasnippet'. + + To insert a structural element, type a `<', followed by a template +selector and `<TAB>'. Completion takes effect only when the above +keystrokes are typed on a line by itself. + + The following template selectors are currently supported. + +`s' `#+begin_src ... #+end_src' +`e' `#+begin_example ... #+end_example' +`q' `#+begin_quote ... #+end_quote' +`v' `#+begin_verse ... #+end_verse' +`c' `#+begin_center ... #+end_center' +`l' `#+begin_latex ... #+end_latex' +`L' `#+latex:' +`h' `#+begin_html ... #+end_html' +`H' `#+html:' +`a' `#+begin_ascii ... #+end_ascii' +`A' `#+ascii:' +`i' `#+include:' line + + For example, on an empty line, typing "<e" and then pressing TAB, +will expand into a complete EXAMPLE template. + + You can install additional templates by customizing the variable +`org-structure-template-alist'. See the docstring of the variable for +additional details. + + +File: org, Node: Speed keys, Next: Code evaluation security, Prev: Easy Templates, Up: Miscellaneous + +15.3 Speed keys +=============== + +Single keys can be made to execute commands when the cursor is at the +beginning of a headline, i.e. before the first star. Configure the +variable `org-use-speed-commands' to activate this feature. There is a +pre-defined list of commands, and you can add more such commands using +the variable `org-speed-commands-user'. Speed keys do not only speed up +navigation and other commands, but they also provide an alternative way +to execute commands bound to keys that are not or not easily available +on a TTY, or on a small mobile device with a limited keyboard. + + To see which commands are available, activate the feature and press +`?' with the cursor at the beginning of a headline. + + +File: org, Node: Code evaluation security, Next: Customization, Prev: Speed keys, Up: Miscellaneous + +15.4 Code evaluation and security issues +======================================== + +Org provides tools to work with the code snippets, including evaluating +them. + + Running code on your machine always comes with a security risk. +Badly written or malicious code can be executed on purpose or by +accident. Org has default settings which will only evaluate such code +if you give explicit permission to do so, and as a casual user of these +features you should leave these precautions intact. + + For people who regularly work with such code, the confirmation +prompts can become annoying, and you might want to turn them off. This +can be done, but you must be aware of the risks that are involved. + + Code evaluation can happen under the following circumstances: + +Source code blocks + Source code blocks can be evaluated during export, or when + pressing `C-c C-c' in the block. The most important thing to + realize here is that Org mode files which contain code snippets + are, in a certain sense, like executable files. So you should + accept them and load them into Emacs only from trusted + sources--just like you would do with a program you install on your + computer. + + Make sure you know what you are doing before customizing the + variables which take off the default security brakes. + + -- User Option: org-confirm-babel-evaluate + When set to t user is queried before code block evaluation + +Following `shell' and `elisp' links + Org has two link types that can directly evaluate code (*note + External links::). These links can be problematic because the + code to be evaluated is not visible. + + -- User Option: org-confirm-shell-link-function + Function to queries user about shell link execution. + + -- User Option: org-confirm-elisp-link-function + Functions to query user for Emacs Lisp link execution. + +Formulas in tables + Formulas in tables (*note The spreadsheet::) are code that is + evaluated either by the calc interpreter, or by the Emacs Lisp + interpreter. + + +File: org, Node: Customization, Next: In-buffer settings, Prev: Code evaluation security, Up: Miscellaneous + +15.5 Customization +================== + +There are more than 180 variables that can be used to customize Org. +For the sake of compactness of the manual, I am not describing the +variables here. A structured overview of customization variables is +available with `M-x org-customize'. Or select `Browse Org Group' from +the `Org->Customization' menu. Many settings can also be activated on +a per-file basis, by putting special lines into the buffer (*note +In-buffer settings::). + + +File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous + +15.6 Summary of in-buffer settings +================================== + +Org-mode uses special lines in the buffer to define settings on a +per-file basis. These lines start with a `#+' 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 `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. + +`#+ARCHIVE: %s_done::' + This line sets the archive location for the agenda file. It + applies for all subsequent lines until the next `#+ARCHIVE' line, + or the end of the file. The first such line also applies to any + entries before it. The corresponding variable is + `org-archive-location'. + +`#+CATEGORY:' + This line sets the category for the agenda file. The category + applies for all subsequent lines until the next `#+CATEGORY' line, + or the end of the file. The first such line also applies to any + entries before it. + +`#+COLUMNS: %25ITEM .....' + Set the default format for columns view. This format applies when + columns view is invoked in locations where no `COLUMNS' property + applies. + +`#+CONSTANTS: name1=value1 ...' + Set file-local values for constants to be used in table formulas. + This line sets the local variable + `org-table-formula-constants-local'. The global version of this + variable is `org-table-formula-constants'. + +`#+FILETAGS: :tag1:tag2:tag3:' + Set tags that can be inherited by any entry in the file, including + the top-level entries. + +`#+DRAWERS: NAME1 .....' + Set the file-local set of drawers. The corresponding global + variable is `org-drawers'. + +`#+LINK: linkword replace' + These lines (several are allowed) specify link abbreviations. + *Note Link abbreviations::. The corresponding variable is + `org-link-abbrev-alist'. + +`#+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 than the lowest priority. + +`#+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. + +`#+SETUPFILE: file' + This line defines a file that holds more in-buffer setup. + Normally this is entirely ignored. Only when the buffer is parsed + for option-setting lines (i.e. when starting Org-mode for a file, + when pressing `C-c C-c' in a settings line, or when exporting), + then the contents of this file are parsed as if they had been + included in the buffer. In particular, the file can be any other + Org-mode file with internal setup. You can visit the file the + cursor is in the line with `C-c ''. + +`#+STARTUP:' + This line sets options to be used at startup of Org-mode, when an + Org 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 `org-startup-folded', with a default value `t', which + means `overview'. + overview top-level headlines only + content all headlines + showall no folding of any entries + showeverything show even drawer contents + + Dynamic virtual indentation is controlled by the variable + `org-startup-indented'(1) + indent start with `org-indent-mode' turned on + noindent start with `org-indent-mode' turned off + + Then there are options for aligning tables upon visiting a file. + This is useful in files containing narrowed table columns. The + corresponding variable is `org-startup-align-all-tables', with a + default value `nil'. + align align all tables + noalign don't align tables on startup + + When visiting a file, inline images can be automatically + displayed. The corresponding variable is + `org-startup-with-inline-images', with a default value `nil' to + avoid delays when visiting a file. + inlineimages show inline images + noinlineimages don't show inline images on startup + + Logging the closing and reopening of TODO items and clock + intervals can be configured using these options (see variables + `org-log-done', `org-log-note-clock-out' and `org-log-repeat') + logdone record a timestamp when an item is marked DONE + lognotedone record timestamp and a note when DONE + nologdone don't record when items are marked DONE + logrepeat record a time when reinstating a repeating item + lognoterepeat record a note when reinstating a repeating item + nologrepeat do not record when reinstating repeating item + lognoteclock-out record a note when clocking out + nolognoteclock-out don't record a note when clocking out + logreschedule record a timestamp when scheduling time changes + lognotereschedule record a note when scheduling time changes + nologreschedule do not record when a scheduling date changes + logredeadline record a timestamp when deadline changes + lognoteredeadline record a note when deadline changes + nologredeadline do not record when a deadline date changes + logrefile record a timestamp when refiling + lognoterefile record a note when refiling + nologrefile do not record when refiling + Here are the options for hiding leading stars in outline headings, + and for indenting outlines. The corresponding variables are + `org-hide-leading-stars' and `org-odd-levels-only', both with a + default setting `nil' (meaning `showstars' and `oddeven'). + hidestars make all but one of the stars starting a headline invisible. + showstars show all stars starting a headline + indent virtual indentation according to outline level + noindent no virtual indentation according to outline level + odd allow only odd outline levels (1,3,...) + oddeven allow all outline levels + To turn on custom format overlays over timestamps (variables + `org-put-time-stamp-overlays' and + `org-time-stamp-overlay-formats'), use + customtime overlay custom time format + The following options influence the table spreadsheet (variable + `constants-unit-system'). + constcgs `constants.el' should use the c-g-s unit system + constSI `constants.el' should use the SI unit system + To influence footnote settings, use the following keywords. The + corresponding variables are `org-footnote-define-inline', + `org-footnote-auto-label', and `org-footnote-auto-adjust'. + fninline define footnotes inline + fnnoinline define footnotes in separate section + fnlocal define footnotes near first reference, but not inline + fnprompt prompt for footnote labels + fnauto create [fn:1]-like labels automatically (default) + fnconfirm offer automatic label for editing or confirmation + fnplain create [1]-like labels automatically + fnadjust automatically renumber and sort footnotes + nofnadjust do not renumber and sort automatically + To hide blocks on startup, use these keywords. The corresponding + variable is `org-hide-block-startup'. + hideblocks Hide all begin/end blocks on startup + nohideblocks Do not hide blocks on startup + The display of entities as UTF-8 characters is governed by the + variable `org-pretty-entities' and the keywords + entitiespretty Show entities as UTF-8 characters where possible + entitiesplain Leave entities plain + +`#+TAGS: TAG1(c1) TAG2(c2)' + These lines (several such lines are allowed) specify the valid + tags in this file, and (potentially) the corresponding _fast tag + selection_ keys. The corresponding variable is `org-tag-alist'. + +`#+TBLFM:' + This line contains the formulas for the table directly above the + line. + +`#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,' +`#+OPTIONS:, #+BIND:, #+XSLT:,' +`#+DESCRIPTION:, #+KEYWORDS:,' +`#+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,' +`#+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:' + These lines provide settings for exporting files. For more + details see *Note Export options::. + +`#+TODO: #+SEQ_TODO: #+TYP_TODO:' + These lines set the TODO keywords and their interpretation in the + current file. The corresponding variable is `org-todo-keywords'. + + ---------- Footnotes ---------- + + (1) Emacs 23 and Org-mode 6.29 are required + + +File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous + +15.7 The very busy C-c C-c key +============================== + +The key `C-c C-c' has many purposes in Org, which are all mentioned +scattered throughout this manual. One specific function of this key is +to add _tags_ to a headline (*note Tags::). In many other +circumstances it means something like _"Hey Org, look here and update +according to what you see here"_. Here is a summary of what this means +in different contexts. + + - If there are highlights in the buffer from the creation of a sparse + tree, or from clock display, remove these highlights. + + - If the cursor is in one of the special `#+KEYWORD' lines, this + triggers scanning the buffer for these lines and updating the + information. + + - If the cursor is inside a table, realign the table. This command + works even if the automatic table editor has been turned off. + + - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the + entire table. + + - If the current buffer is a capture buffer, close the note and file + it. With a prefix argument, file it, without further interaction, + to the default location. + + - If the cursor is on a `<<<target>>>', update radio targets and + corresponding links in this buffer. + + - If the cursor is in a property line or at the start or end of a + property drawer, offer property commands. + + - If the cursor is at a footnote reference, go to the corresponding + definition, and vice versa. + + - If the cursor is on a statistics cookie, update it. + + - If the cursor is in a plain list item with a checkbox, toggle the + status of the checkbox. + + - If the cursor is on a numbered item in a plain list, renumber the + ordered list. + + - If the cursor is on the `#+BEGIN' line of a dynamic block, the + block is updated. + + +File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous + +15.8 A cleaner outline view +=========================== + +Some people find it noisy and distracting that the Org headlines start +with a potentially large number of stars, and that text below the +headlines is not indented. While this is no problem when writing a +_book-like_ document where the outline headings are really section +headings, in a more _list-oriented_ outline, indented structure is a +lot cleaner: + + * Top level headline | * Top level headline + ** Second level | * Second level + *** 3rd level | * 3rd level + some text | some text + *** 3rd level | * 3rd level + more text | more text + * Another top level headline | * Another top level headline + +If you are using at least Emacs 23.2(1) and version 6.29 of Org, this +kind of view can be achieved dynamically at display time using +`org-indent-mode'. In this minor mode, all lines are prefixed for +display with the necessary amount of space(2). Also headlines are +prefixed with additional stars, so that the amount of indentation +shifts by two(3) spaces per level. All headline stars but the last +one are made invisible using the `org-hide' face(4) - see below under +`2.' for more information on how this works. You can turn on +`org-indent-mode' for all files by customizing the variable +`org-startup-indented', or you can turn it on for individual files using + + #+STARTUP: indent + + If you want a similar effect in an earlier version of Emacs and/or +Org, or if you want the indentation to be hard space characters so that +the plain text file looks as similar as possible to the Emacs display, +Org supports you in the following way: + + 1. _Indentation of text below headlines_ + You may indent text below each headline to make the left boundary + line up with the headline, like + + *** 3rd level + more text, now indented + + Org supports this with paragraph filling, line wrapping, and + structure editing(5), preserving or adapting the indentation as + appropriate. + + 2. _Hiding leading stars_ + You can modify the display in such a way that all leading stars + become invisible. To do this in a global way, configure the + variable `org-hide-leading-stars' or change this on a per-file + basis with + + #+STARTUP: hidestars + #+STARTUP: showstars + + With hidden stars, the tree becomes: + + * Top level headline + * Second level + * 3rd level + ... + + The leading stars are not truly replaced by whitespace, they are + only fontified with the face `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 almost invisible, for example using the color + `grey90' on a white background. + + 3. 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(6). In this way we get the + outline view shown at the beginning of this section. In order to + make the structure editing and export commands handle this + convention correctly, configure the variable + `org-odd-levels-only', or set this on a per-file basis with one of + the following lines: + + #+STARTUP: odd + #+STARTUP: oddeven + + You can convert an Org file from single-star-per-level to the + double-star-per-level convention with `M-x + org-convert-to-odd-levels RET' in that file. The reverse + operation is `M-x org-convert-to-oddeven-levels'. + + ---------- Footnotes ---------- + + (1) Emacs 23.1 can actually crash with `org-indent-mode' + + (2) `org-indent-mode' also sets the `wrap-prefix' property, such +that `visual-line-mode' (or purely setting `word-wrap') wraps long +lines (including headlines) correctly indented. + + (3) See the variable `org-indent-indentation-per-level'. + + (4) Turning on `org-indent-mode' sets `org-hide-leading-stars' to +`t' and `org-adapt-indentation' to `nil'. + + (5) See also the variable `org-adapt-indentation'. + + (6) When you need to specify a level for a property search or refile +targets, `LEVEL=2' will correspond to 3 stars, etc. + + +File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous + +15.9 Using Org on a tty +======================= + +Because Org contains a large number of commands, by default many of +Org's core commands are bound to keys that are generally not accessible +on a tty, such as the cursor keys (<left>, <right>, <up>, <down>), +<TAB> and <RET>, in particular when used together with modifiers like +<Meta> and/or <Shift>. To access these commands on a tty when special +keys are unavailable, the following alternative bindings can be used. +The tty bindings below will likely be more cumbersome; you may find for +some of the bindings below that a customized workaround suits you +better. For example, changing a timestamp is really only fun with +`S-<cursor>' keys, whereas on a tty you would rather use `C-c .' to +re-insert the timestamp. + +Default Alternative 1 Speed Alternative 2 + key +`S-<TAB>' `C-u <TAB>' `C' +`M-<left>' `C-c C-x l' `l' `<Esc> <left>' +`M-S-<left>'`C-c C-x L' `L' +`M-<right>' `C-c C-x r' `r' `<Esc> + <right>' +`M-S-<right>'`C-c C-x R' `R' +`M-<up>' `C-c C-x u' ` ' `<Esc> <up>' +`M-S-<up>' `C-c C-x U' `U' +`M-<down>' `C-c C-x d' ` ' `<Esc> <down>' +`M-S-<down>'`C-c C-x D' `D' +`S-<RET>' `C-c C-x c' ` ' +`M-<RET>' `C-c C-x m' ` ' `<Esc> <RET>' +`M-S-<RET>' `C-c C-x M' ` ' +`S-<left>' `C-c <left>' ` ' +`S-<right>' `C-c <right>' ` ' +`S-<up>' `C-c <up>' ` ' +`S-<down>' `C-c <down>' ` ' +`C-S-<left>'`C-c C-x ` ' + <left>' +`C-S-<right>'`C-c C-x ` ' + <right>' + + +File: org, Node: Interaction, Prev: TTY keys, Up: Miscellaneous + +15.10 Interaction with other packages +===================================== + +Org lives in the world of GNU Emacs and interacts in various ways with +other code out there. + +* Menu: + +* Cooperation:: Packages Org cooperates with +* Conflicts:: Packages that lead to conflicts + + +File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction + +15.10.1 Packages that Org cooperates with +----------------------------------------- + +`calc.el' by Dave Gillespie + Org uses the Calc package for implementing spreadsheet + functionality in its tables (*note The spreadsheet::). Org checks + for the availability of Calc by looking for the function + `calc-eval' which will have been autoloaded during 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. *Note + Embedded Mode: (Calc)Embedded Mode. + +`constants.el' by Carsten Dominik + In a table formula (*note The spreadsheet::), it is possible to use + names for natural constants or units. Instead of defining your own + constants in the variable `org-table-formula-constants', install + the `constants' package which defines a large number of constants + and units, and lets you use unit prefixes like `M' for `Mega', + etc. You will need version 2.0 of this package, available at + `http://www.astro.uva.nl/~dominik/Tools'. Org checks for the + function `constants-get', which has to be autoloaded in your + setup. See the installation instructions in the file + `constants.el'. + +`cdlatex.el' by Carsten Dominik + Org-mode can make use of the CDLaTeX package to efficiently enter + LaTeX fragments into Org files. See *Note CDLaTeX mode::. + +`imenu.el' by Ake Stenhoff and Lars Lindberg + Imenu allows menu access to an index of items in a file. Org-mode + supports Imenu--all you need to do to get the index is the + following: + (add-hook 'org-mode-hook + (lambda () (imenu-add-to-menubar "Imenu"))) + By default the index is two levels deep--you can modify the depth + using the option `org-imenu-depth'. + +`remember.el' by John Wiegley + Org used to use this package for capture, but no longer does. + +`speedbar.el' by Eric M. Ludlam + Speedbar is a package that creates a special frame displaying + files and index items in files. Org-mode supports Speedbar and + allows you to drill into Org files directly from the Speedbar. It + also allows you to restrict the scope of agenda commands to a file + or a subtree by using the command `<' in the Speedbar frame. + +`table.el' by Takaaki Ota + Complex ASCII tables with automatic line wrapping, column- and + row-spanning, and alignment can be created using the Emacs table + package by Takaaki Ota (`http://sourceforge.net/projects/table', + and also part of Emacs 22). Org-mode will recognize these tables + and export them properly. Because of interference with other + Org-mode functionality, you unfortunately cannot edit these tables + directly in the buffer. Instead, you need to use the command `C-c + '' to edit them, similar to source code snippets. + + `C-c ' (`org-edit-special')' + Edit a `table.el' table. Works when the cursor is in a + table.el table. + + `C-c ~ (`org-table-create-with-table.el')' + 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 `org-convert-table' for the restrictions under which + this is possible. + `table.el' is part of Emacs since Emacs 22. + +`footnote.el' by Steven L. Baur + Org-mode recognizes numerical footnotes as provided by this + package. However, Org-mode also has its own footnote support + (*note Footnotes::), which makes using `footnote.el' unnecessary. + + +File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction + +15.10.2 Packages that lead to conflicts with Org-mode +----------------------------------------------------- + + In Emacs 23, `shift-selection-mode' is on by default, meaning that + cursor motions combined with the shift key should start or enlarge + regions. This conflicts with the use of `S-<cursor>' commands in + Org to change timestamps, TODO keywords, priorities, and item + bullet types if the cursor is at such a location. By default, + `S-<cursor>' commands outside special contexts don't do anything, + but you can customize the variable `org-support-shift-select'. + Org-mode then tries to accommodate shift selection by (i) using it + outside of the special contexts where special commands apply, and + by (ii) extending an existing active region even if the cursor + moves across a special context. + +`CUA.el' by Kim. F. Storm + Key bindings in Org conflict with the `S-<cursor>' keys used by + CUA mode (as well as `pc-select-mode' and `s-region-mode') to + select and extend the region. In fact, Emacs 23 has this built-in + in the form of `shift-selection-mode', see previous paragraph. If + you are using Emacs 23, you probably don't want to use another + package for this purpose. However, if you prefer to leave these + keys to a different package while working in Org-mode, configure + the variable `org-replace-disputed-keys'. When set, Org will move + the following key bindings in Org files, and in the agenda buffer + (but not during date selection). + + S-UP -> M-p S-DOWN -> M-n + S-LEFT -> M-- S-RIGHT -> M-+ + C-S-LEFT -> M-S-- C-S-RIGHT -> M-S-+ + + Yes, these are unfortunately more difficult to remember. If you + want to have other replacement keys, look at the variable + `org-disputed-keys'. + +`yasnippet.el' + The way Org-mode binds the TAB key (binding to `[tab]' instead of + `"\t"') overrules YASnippet's access to this key. The following + code fixed this problem: + + (add-hook 'org-mode-hook + (lambda () + (org-set-local 'yas/trigger-key [tab]) + (define-key yas/keymap [tab] 'yas/next-field-group))) + +`windmove.el' by Hovav Shacham + This package also uses the `S-<cursor>' keys, so everything written + in the paragraph above about CUA mode also applies here. If you + want make the windmove function active in locations where Org-mode + does not have special functionality on `S-<cursor>', add this to + your configuration: + + ;; Make windmove work in org-mode: + (add-hook 'org-shiftup-final-hook 'windmove-up) + (add-hook 'org-shiftleft-final-hook 'windmove-left) + (add-hook 'org-shiftdown-final-hook 'windmove-down) + (add-hook 'org-shiftright-final-hook 'windmove-right) + +`viper.el' by Michael Kifer + Viper uses `C-c /' and therefore makes this key not access the + corresponding Org-mode command `org-sparse-tree'. You need to find + another key for this command, or override the key in + `viper-vi-global-user-map' with + + (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree) + + + +File: org, Node: Hacking, Next: MobileOrg, Prev: Miscellaneous, Up: Top + +Appendix A Hacking +****************** + +This appendix covers some aspects where users can extend the +functionality of Org. + +* Menu: + +* Hooks:: Who to reach into Org's internals +* Add-on packages:: Available extensions +* Adding hyperlink types:: New custom link types +* Context-sensitive commands:: How to add functionality to such commands +* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs +* Dynamic blocks:: Automatically filled blocks +* Special agenda views:: Customized views +* Extracting agenda information:: Postprocessing of agenda information +* Using the property API:: Writing programs that use entry properties +* Using the mapping API:: Mapping over all or selected entries + + +File: org, Node: Hooks, Next: Add-on packages, Prev: Hacking, Up: Hacking + +A.1 Hooks +========= + +Org has a large number of hook variables that can be used to add +functionality. This appendix about hacking is going to illustrate the +use of some of them. A complete list of all hooks with documentation is +maintained by the Worg project and can be found at +`http://orgmode.org/worg/org-configs/org-hooks.php'. + + +File: org, Node: Add-on packages, Next: Adding hyperlink types, Prev: Hooks, Up: Hacking + +A.2 Add-on packages +=================== + +A large number of add-on packages have been written by various authors. +These packages are not part of Emacs, but they are distributed as +contributed packages with the separate release available at the +Org-mode home page at `http://orgmode.org'. The list of contributed +packages, along with documentation about each package, is maintained by +the Worg project at `http://orgmode.org/worg/org-contrib/'. + + +File: org, Node: Adding hyperlink types, Next: Context-sensitive commands, Prev: Add-on packages, Up: Hacking + +A.3 Adding hyperlink types +========================== + +Org has a large number of hyperlink types built-in (*note +Hyperlinks::). If you would like to add new link types, Org provides +an interface for doing so. Let's look at an example file, +`org-man.el', that will add support for creating links like +`[[man:printf][The printf manpage]]' to show Unix manual pages inside +Emacs: + + ;;; org-man.el - Support for links to manpages in Org + + (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 + +You would activate this new link type in `.emacs' with + + (require 'org-man) + +Let's go through the file and see what it does. + 1. It does `(require 'org)' to make sure that `org.el' has been + loaded. + + 2. The next line calls `org-add-link-type' to define a new link type + with prefix `man'. The call also contains the name of a function + that will be called to follow such a link. + + 3. The next line adds a function to `org-store-link-functions', in + order to allow the command `C-c l' to record a useful link in a + buffer displaying a man page. + + 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 man pages. There are two options, +`man' and `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 +`org-man-command' to display the man page. + + Finally the function `org-man-store-link' is defined. When you try +to store a link with `C-c l', 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 `major-mode'. If not, the function must exit and +return the value `nil'. If yes, the link is created by getting the +manual topic from the buffer name and prefixing it with the string +`man:'. Then it must call the command `org-store-link-props' and set +the `:type' and `:link' properties. Optionally you can also set the +`:description' property to provide a default for the link description +when the link is later inserted into an Org buffer with `C-c C-l'. + + When it makes sense for your new link type, you may also define a +function `org-PREFIX-complete-link' that implements special (e.g. +completion) support for inserting such a link with `C-c C-l'. Such a +function should not accept any arguments, and return the full link with +prefix. + + +File: org, Node: Context-sensitive commands, Next: Tables in arbitrary syntax, Prev: Adding hyperlink types, Up: Hacking + +A.4 Context-sensitive commands +============================== + +Org has several commands that act differently depending on context. +The most important example it the `C-c C-c' (*note The very busy C-c +C-c key::). Also the `M-cursor' and `M-S-cursor' keys have this +property. + + Add-ons can tap into this functionality by providing a function that +detects special context for that add-on and executes functionality +appropriate for the context. Here is an example from Dan Davison's +`org-R.el' which allows you to evaluate commands based on the `R' +programming language (1). For this package, special contexts are lines +that start with `#+R:' or `#+RR:'. + + (defun org-R-apply-maybe () + "Detect if this is context for org-R and execute R commands." + (if (save-excursion + (beginning-of-line 1) + (looking-at "#\\+RR?:")) + (progn (call-interactively 'org-R-apply) + t) ;; to signal that we took action + nil)) ;; to signal that we did not + + (add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe) + + The function first checks if the cursor is in such a line. If that +is the case, `org-R-apply' is called and the function returns `t' to +signal that action was taken, and `C-c C-c' will stop looking for other +contexts. If the function finds it should do nothing locally, it +returns `nil' so that other, similar functions can have a try. + + ---------- Footnotes ---------- + + (1) `org-R.el' has been replaced by the org-mode functionality +described in *Note Working With Source Code:: and is now obsolete. + + +File: org, Node: Tables in arbitrary syntax, Next: Dynamic blocks, Prev: Context-sensitive commands, Up: Hacking + +A.5 Tables and lists in arbitrary syntax +======================================== + +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 LaTeX. 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 source table), and use a custom +function to translate the table to the correct syntax, and to install +it in the right location (the target table). This puts the burden of +writing conversion functions on the user, but it allows for a very +flexible system. + + Bastien added the ability to do the same with lists, in Orgstruct +mode. You can use Org's facilities to edit and structure lists by +turning `orgstruct-mode' on, then locally exporting such lists in +another format (HTML, LaTeX or Texinfo.) + +* Menu: + +* Radio tables:: Sending and receiving radio tables +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify +* Radio lists:: Doing the same for lists + + +File: org, Node: Radio tables, Next: A LaTeX example, Prev: Tables in arbitrary syntax, Up: Tables in arbitrary syntax + +A.5.1 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: + + /* BEGIN RECEIVE ORGTBL table_name */ + /* END RECEIVE ORGTBL table_name */ + +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: + #+ORGTBL: SEND table_name translation_function arguments.... + +`table_name' is the reference name for the table that is also used in +the receiver lines. `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: + +`:skip N' + Skip the first N lines of the table. Hlines do count as separate + lines for this parameter! + +`: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 + _after_ the removal of these columns, the function never knows + that there have been additional columns. + +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 LaTeX file. There are a +number of different solutions: + + * 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 `/*' and `*/' lines. + + * Sometimes it is possible to put the table after some kind of END + statement, for example `\bye' in TeX and `\end{document}' in LaTeX. + + * 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 `M-x + orgtbl-toggle-comment' makes this comment-toggling very easy, in + particular if you bind it to a key. + + +File: org, Node: A LaTeX example, Next: Translator functions, Prev: Radio tables, Up: Tables in arbitrary syntax + +A.5.2 A LaTeX example of radio tables +------------------------------------- + +The best way to wrap the source table in LaTeX is to use the `comment' +environment provided by `comment.sty'. It has to be activated by +placing `\usepackage{comment}' into the document header. Orgtbl mode +can insert a radio table skeleton(1) with the command `M-x +orgtbl-insert-radio-table'. You will be prompted for a table name, +let's say we use `salesfigures'. You will then get the following +template: + + % BEGIN RECEIVE ORGTBL salesfigures + % END RECEIVE ORGTBL salesfigures + \begin{comment} + #+ORGTBL: SEND salesfigures orgtbl-to-latex + | | | + \end{comment} + +The `#+ORGTBL: SEND' line tells Orgtbl mode to use the function +`orgtbl-to-latex' to convert the table into LaTeX and to put it into +the receiver location with name `salesfigures'. You may now fill in +the table--feel free to use the spreadsheet features(2): + + % 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} + +When you are done, press `C-c C-c' in the table to get the converted +table inserted between the two marker lines. + + Now let's 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 skips the first 2 lines of the source +table, and tell the command to work as a splice, i.e. to not produce +header and footer commands of the target table: + + \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} + + The LaTeX translator function `orgtbl-to-latex' is already part of +Orgtbl mode. It uses a `tabular' environment to typeset the table and +marks horizontal lines with `\hline'. Furthermore, it interprets the +following parameters (see also *note Translator functions::): + +`:splice nil/t' + When set to t, return only table body lines, don't wrap them into a + tabular environment. Default is nil. + +`:fmt fmt' + A format to be used to wrap each field, it should contain `%s' for + the original field value. For example, to wrap each field value + in dollars, you could use `:fmt "$%s$"'. This may also be a + property list with column numbers and formats. for example `:fmt + (2 "$%s$" 4 "%s\\%%")'. A function of one argument can be used in + place of the strings; the function must return a formatted string. + +`:efmt efmt' + Use this format to print numbers with exponentials. The format + should have `%s' twice for inserting mantissa and exponent, for + example `"%s\\times10^{%s}"'. The default is `"%s\\,(%s)"'. This + may also be a property list with column numbers and formats, for + example `:efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")'. + After `efmt' has been applied to a value, `fmt' will also be + applied. Similar to `fmt', functions of two arguments can be + supplied instead of strings. + + ---------- Footnotes ---------- + + (1) By default this works only for LaTeX, HTML, and Texinfo. +Configure the variable `orgtbl-radio-tables' to install templates for +other modes. + + (2) If the `#+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 +`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 `comment' environment to the variable +`LaTeX-verbatim-environments'. + + +File: org, Node: Translator functions, Next: Radio lists, Prev: A LaTeX example, Up: Tables in arbitrary syntax + +A.5.3 Translator functions +-------------------------- + +Orgtbl mode has several translator functions built-in: `orgtbl-to-csv' +(comma-separated values), `orgtbl-to-tsv' (TAB-separated values) +`orgtbl-to-latex', `orgtbl-to-html', and `orgtbl-to-texinfo'. Except +for `orgtbl-to-html'(1), these all use a generic translator, +`orgtbl-to-generic'. For example, `orgtbl-to-latex' itself is a very +short function that computes the column definitions for the `tabular' +environment, defines a few field and line separators and then hands +processing over to the generic translator. Here is the entire code: + + (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)))) + + As you can see, the properties passed into the function (variable +PARAMS) are combined with the ones newly defined in the function +(variable PARAMS2). The ones passed into the function (i.e. the ones +set by the `ORGTBL SEND' line) take precedence. So if you would like +to use the LaTeX translator, but wanted the line endings to be +`\\[2mm]' instead of the default `\\', you could just overrule the +default with + + #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]" + + For a new language, you can either write your own converter function +in analogy with the LaTeX translator, or you can use the generic +function directly. For example, if you have a language where a table +is started with `!BTBL!', ended with `!ETBL!', and where table lines are +started with `!BL!', ended with `!EL!', and where the field separator +is a TAB, you could call the generic translator like this (on a single +line!): + + #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!" + :lstart "!BL! " :lend " !EL!" :sep "\t" + +Please check the documentation string of the function +`orgtbl-to-generic' for a full list of parameters understood by that +function, and remember that you can pass each of them into +`orgtbl-to-latex', `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 `hline' or a list of fields. The +second argument is the property list containing all parameters +specified in the `#+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 <emacs-orgmode@gnu.org> so that +others can benefit from your work. + + ---------- Footnotes ---------- + + (1) The HTML translator uses the same code that produces tables +during HTML export. + + +File: org, Node: Radio lists, Prev: Translator functions, Up: Tables in arbitrary syntax + +A.5.4 Radio lists +----------------- + +Sending and receiving radio lists works exactly the same way as sending +and receiving radio tables (*note Radio tables::). As for radio +tables, you can insert radio list templates in HTML, LaTeX and Texinfo +modes by calling `org-list-insert-radio-list'. + + Here are the differences with radio tables: + + - Orgstruct mode must be active. + + - Use the `ORGLST' keyword instead of `ORGTBL'. + + - The available translation functions for radio lists don't take + parameters. + + - `C-c C-c' will work when pressed on the first item of the list. + + Here is a LaTeX example. Let's say that you have this in your LaTeX +file: + + % BEGIN RECEIVE ORGLST to-buy + % END RECEIVE ORGLST to-buy + \begin{comment} + #+ORGLST: SEND to-buy org-list-to-latex + - a new house + - a new computer + + a new keyboard + + a new mouse + - a new life + \end{comment} + + Pressing `C-c C-c' on `a new house' and will insert the converted +LaTeX list between the two marker lines. + + +File: org, Node: Dynamic blocks, Next: Special agenda views, Prev: Tables in arbitrary syntax, Up: Hacking + +A.6 Dynamic blocks +================== + +Org documents can contain _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 `C-c C-x +C-r' (*note Clocking work time::). + + Dynamic blocks 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. + + #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... + + #+END: + + Dynamic blocks are updated with the following commands + +`C-c C-x C-u (`org-dblock-update')' + Update dynamic block at point. + +`C-u C-c C-x C-u' + Update all dynamic blocks in the current file. + + 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. If you want +to use the original content in the writer function, you can use the +extra parameter `:content'. + + For a block with name `myblock', the writer function is +`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: + + #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" + + #+END: + +The corresponding block writer function could look like this: + + (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))))) + + If you want to make sure that all dynamic blocks are always +up-to-date, you could add the function `org-update-all-dblocks' to a +hook, for example `before-save-hook'. `org-update-all-dblocks' is +written in a way such that it does nothing in buffers that are not in +`org-mode'. + + +File: org, Node: Special agenda views, Next: Extracting agenda information, Prev: Dynamic blocks, Up: Hacking + +A.7 Special agenda views +======================== + +Org provides a special hook that can be used to narrow down the +selection made by these agenda views: `todo', `alltodo', `tags', +`tags-todo', `tags-tree'. 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 `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. + + (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 + + Now you may use this function in an agenda custom command, for +example like this: + + (org-add-agenda-custom-command + '("b" todo "PROJECT" + ((org-agenda-skip-function 'my-skip-unless-waiting) + (org-agenda-overriding-header "Projects waiting for something: ")))) + + Note that this also binds `org-agenda-overriding-header' to get a +meaningful header in the agenda view. + + A general way to create custom searches is to base them on a search +for entries with a certain level limit. If you want to study all +entries with your custom search function, simply do a search for +`LEVEL>0'(1), and then use `org-agenda-skip-function' to select the +entries you really want to have. + + You may also put a Lisp form into `org-agenda-skip-function'. In +particular, you may use the functions `org-agenda-skip-entry-if' and +`org-agenda-skip-subtree-if' in this form, for example: + +`'(org-agenda-skip-entry-if 'scheduled)' + Skip current entry if it has been scheduled. + +`'(org-agenda-skip-entry-if 'notscheduled)' + Skip current entry if it has not been scheduled. + +`'(org-agenda-skip-entry-if 'deadline)' + Skip current entry if it has a deadline. + +`'(org-agenda-skip-entry-if 'scheduled 'deadline)' + Skip current entry if it has a deadline, or if it is scheduled. + +`'(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))' + Skip current entry if the TODO keyword is TODO or WAITING. + +`'(org-agenda-skip-entry-if 'todo 'done)' + Skip current entry if the TODO keyword marks a DONE state. + +`'(org-agenda-skip-entry-if 'timestamp)' + Skip current entry if it has any timestamp, may also be deadline + or scheduled. + +`'(org-agenda-skip-entry 'regexp "regular expression")' + Skip current entry if the regular expression matches in the entry. + +`'(org-agenda-skip-entry 'notregexp "regular expression")' + Skip current entry unless the regular expression matches. + +`'(org-agenda-skip-subtree-if 'regexp "regular expression")' + Same as above, but check and skip the entire subtree. + + Therefore we could also have written the search for WAITING projects +like this, even without defining a special function: + + (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: ")))) + + ---------- Footnotes ---------- + + (1) Note that, when using `org-odd-levels-only', a level number +corresponds to order in the hierarchy, not to the number of stars. + + +File: org, Node: Extracting agenda information, Next: Using the property API, Prev: Special agenda views, Up: Hacking + +A.8 Extracting agenda information +================================= + +Org 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 +`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 `org-agenda-custom-commands', basically any key you +can use after `C-c a'. For example, to directly print the current TODO +list, you could use + + emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr + + 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 `shop', but excluding the tag `NewYork'), +you could use + + emacs -batch -l ~/.emacs \ + -eval '(org-batch-agenda "+shop-NewYork")' | lpr + +You may also modify parameters on the fly like this: + + emacs -batch -l ~/.emacs \ + -eval '(org-batch-agenda "a" \ + org-agenda-span month \ + org-agenda-include-diary nil \ + org-agenda-files (quote ("~/org/project.org")))' \ + | lpr + +which will produce a 30-day agenda, fully restricted to the Org 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 `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: + + category The category of the item + head The headline, without TODO keyword, TAGS and PRIORITY + type The type of the agenda entry, can be + todo selected in TODO match + tagsmatch selected in tags match + diary imported from diary + deadline a deadline + scheduled scheduled + timestamp appointment, selected by timestamp + closed entry was closed on date + upcoming-deadline warning about nearing deadline + past-scheduled forwarded scheduled item + block entry has date block including date + todo The TODO keyword, if any + tags All tags including inherited ones, separated by colons + date The relevant date, like 2007-2-14 + time The time, like 15:00-16:50 + extra String with extra planning info + priority-l The priority letter if any was given + priority-n The computed numerical priority + +Time and date will only be given if a timestamp (or deadline/scheduled) +led 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 and prints all the items, preceded by a checkbox: + + #!/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); + # process and print + print "[ ] $head\n"; + } + + +File: org, Node: Using the property API, Next: Using the mapping API, Prev: Extracting agenda information, Up: Hacking + +A.9 Using the property API +========================== + +Here is a description of the functions that can be used to work with +properties. + + -- Function: 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. + + -- Function: org-entry-get pom property &optional inherit + Get value of PROPERTY for entry at point-or-marker POM. By + default, this only looks at properties defined locally in the + entry. If INHERIT is non-nil and the entry does not have the + property, then also check higher levels of the hierarchy. If + INHERIT is the symbol `selective', use inheritance if and only if + the setting of `org-use-property-inheritance' selects PROPERTY for + inheritance. + + -- Function: org-entry-delete pom property + Delete the property PROPERTY from entry at point-or-marker POM. + + -- Function: org-entry-put pom property value + Set PROPERTY to VALUE for entry at point-or-marker POM. + + -- Function: org-buffer-property-keys &optional include-specials + Get all property keys in the current buffer. + + -- Function: org-insert-property-drawer + Insert a property drawer at point. + + -- Function: org-entry-put-multivalued-property pom property &rest + values + Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a + list of strings. They will be concatenated, with spaces as + separators. + + -- Function: org-entry-get-multivalued-property pom property + Treat the value of the property PROPERTY as a whitespace-separated + list of values and return the values as a list of strings. + + -- Function: org-entry-add-to-multivalued-property pom property value + Treat the value of the property PROPERTY as a whitespace-separated + list of values and make sure that VALUE is in this list. + + -- Function: org-entry-remove-from-multivalued-property pom property + value + Treat the value of the property PROPERTY as a whitespace-separated + list of values and make sure that VALUE is _not_ in this list. + + -- Function: org-entry-member-in-multivalued-property pom property + value + Treat the value of the property PROPERTY as a whitespace-separated + list of values and check if VALUE is in this list. + + -- User Option: org-property-allowed-value-functions + Hook for functions supplying allowed values for a specific + property. The functions must take a single argument, the name of + the property, and return a flat list of allowed values. If `:ETC' + is one of the values, use the values as completion help, but allow + also other values to be entered. The functions must return `nil' + if they are not responsible for this property. + + +File: org, Node: Using the mapping API, Prev: Using the property API, Up: Hacking + +A.10 Using the mapping API +========================== + +Org has sophisticated mapping capabilities to find all entries +satisfying certain criteria. Internally, this functionality is used to +produce agenda views, but there is also an API that can be used to +execute arbitrary functions for each or selected entries. The main +entry point for this API is: + + -- Function: org-map-entries func &optional match scope &rest skip + Call FUNC at each headline selected by MATCH in SCOPE. + + FUNC is a function or a Lisp form. The function will be called + without arguments, with the cursor positioned at the beginning of + the headline. The return values of all calls to the function will + be collected and returned as a list. + + The call to FUNC will be wrapped into a save-excursion form, so + FUNC does not need to preserve point. After evaluation, the + cursor will be moved to the end of the line (presumably of the + headline of the processed entry) and search continues from there. + Under some circumstances, this may not produce the wanted results. + For example, if you have removed (e.g. archived) the current + (sub)tree it could mean that the next entry will be skipped + entirely. In such cases, you can specify the position from where + search should continue by making FUNC set the variable + `org-map-continue-from' to the desired buffer position. + + MATCH is a tags/property/todo match as it is used in the agenda + match view. Only headlines that are matched by this query will be + considered during the iteration. When MATCH is nil or t, all + headlines will be visited by the iteration. + + SCOPE determines the scope of this command. It can be any of: + + nil the current buffer, respecting the restriction if any + tree the subtree started with the entry at point + file the current buffer, without restriction + file-with-archives + the current buffer, and any archives associated with it + agenda all agenda files + agenda-with-archives + all agenda files with any archive files associated with them + (file1 file2 ...) + if this is a list, all files in the list will be scanned + The remaining args are treated as settings for the skipping + facilities of the scanner. The following items can be given here: + + archive skip trees with the archive tag + comment skip trees with the COMMENT keyword + function or Lisp form + will be used as value for `org-agenda-skip-function', + so whenever the function returns t, FUNC + will not be called for that entry and search will + continue from the point where the function leaves it + + The function given to that mapping routine can really do anything +you like. It can use the property API (*note Using the property API::) +to gather more information about the entry, or in order to change +metadata in the entry. Here are a couple of functions that might be +handy: + + -- Function: org-todo &optional arg + Change the TODO state of the entry. See the docstring of the + functions for the many possible values for the argument ARG. + + -- Function: org-priority &optional action + Change the priority of the entry. See the docstring of this + function for the possible values for ACTION. + + -- Function: org-toggle-tag tag &optional onoff + Toggle the tag TAG in the current entry. Setting ONOFF to either + `on' or `off' will not toggle tag, but ensure that it is either on + or off. + + -- Function: org-promote + Promote the current entry. + + -- Function: org-demote + Demote the current entry. + + Here is a simple example that will turn all entries in the current +file with a tag `TOMORROW' into TODO entries with the keyword +`UPCOMING'. Entries in comment trees and in archive trees will be +ignored. + + (org-map-entries + '(org-todo "UPCOMING") + "+TOMORROW" 'file 'archive 'comment) + + The following example counts the number of entries with TODO keyword +`WAITING', in all agenda files. + + (length (org-map-entries t "/+WAITING" 'agenda)) + + +File: org, Node: MobileOrg, Next: History and Acknowledgments, Prev: Hacking, Up: Top + +Appendix B MobileOrg +******************** + +MobileOrg (http://mobileorg.ncogni.to/) is an application for the +iPhone/iPod Touch series of devices, developed by Richard Moreland. +MobileOrg offers offline viewing and capture support for an Org-mode +system rooted on a "real" computer. It does also allow you to record +changes to existing entries. Android users should check out MobileOrg +Android (http://wiki.github.com/matburt/mobileorg-android/) by Matt +Jones. + + This appendix describes the support Org has for creating agenda +views in a format that can be displayed by MobileOrg, and for +integrating notes captured and changes made by MobileOrg into the main +system. + + For changing tags and TODO states in MobileOrg, you should have set +up the customization variables `org-todo-keywords' and `org-tags-alist' +to cover all important tags and TODO keywords, even if individual files +use only part of these. MobileOrg will also offer you states and tags +set up with in-buffer settings, but it will understand the logistics of +TODO state sets (*note Per-file keywords::) and mutually exclusive tags +(*note Setting tags::) only for those set in these variables. + +* Menu: + +* Setting up the staging area:: Where to interact with the mobile device +* Pushing to MobileOrg:: Uploading Org files and agendas +* Pulling from MobileOrg:: Integrating captured and flagged items + + +File: org, Node: Setting up the staging area, Next: Pushing to MobileOrg, Prev: MobileOrg, Up: MobileOrg + +B.1 Setting up the staging area +=============================== + +MobileOrg needs to interact with Emacs through a directory on a server. +If you are using a public server, you should consider to encrypt the +files that are uploaded to the server. This can be done with Org-mode +7.02 and with MobileOrg 1.5 (iPhone version), and you need an `openssl' +installation on your system. To turn on encryption, set a password in +MobileOrg and, on the Emacs side, configure the variable +`org-mobile-use-encryption'(1). + + The easiest way to create that directory is to use a free +Dropbox.com (http://dropbox.com) account(2). When MobileOrg first +connects to your Dropbox, it will create a directory MobileOrg inside +the Dropbox. After the directory has been created, tell Emacs about it: + + (setq org-mobile-directory "~/Dropbox/MobileOrg") + + Org-mode has commands to put files for MobileOrg into that directory, +and to read captured notes from there. + + ---------- Footnotes ---------- + + (1) If you can safely store the password in your Emacs setup, you +might also want to configure `org-mobile-encryption-password'. Please +read the docstring of that variable. Note that encryption will apply +only to the contents of the `.org' files. The file names themselves +will remain visible. + + (2) If you cannot use Dropbox, or if your version of MobileOrg does +not support it, you can use a webdav server. For more information, +check out the documentation of MobileOrg and also this FAQ entry +(http://orgmode.org/worg/org-faq.php#mobileorg_webdav). + + +File: org, Node: Pushing to MobileOrg, Next: Pulling from MobileOrg, Prev: Setting up the staging area, Up: MobileOrg + +B.2 Pushing to MobileOrg +======================== + +This operation copies all files currently listed in `org-mobile-files' +to the directory `org-mobile-directory'. By default this list contains +all agenda files (as listed in `org-agenda-files'), but additional files +can be included by customizing `org-mobiles-files'. File names will be +staged with paths relative to `org-directory', so all files should be +inside this directory. The push operation also creates a special Org +file `agendas.org' with all custom agenda view defined by the user(1). +Finally, Org writes the file `index.org', containing links to all other +files. MobileOrg first reads this file from the server, and then +downloads all agendas and Org files listed in it. To speed up the +download, MobileOrg will only read files whose checksums(2) have +changed. + + ---------- Footnotes ---------- + + (1) While creating the agendas, Org-mode will force ID properties on +all referenced entries, so that these entries can be uniquely identified +if MobileOrg flags them for further action. If you do not want to get +these properties in so many entries, you can set the variable +`org-mobile-force-id-on-agenda-items' to `nil'. Org mode will then +rely on outline paths, in the hope that these will be unique enough. + + (2) stored automatically in the file `checksums.dat' + + +File: org, Node: Pulling from MobileOrg, Prev: Pushing to MobileOrg, Up: MobileOrg + +B.3 Pulling from MobileOrg +========================== + +When MobileOrg synchronizes with the server, it not only pulls the Org +files for viewing. It also appends captured entries and pointers to +flagged and changed entries to the file `mobileorg.org' on the server. +Org has a _pull_ operation that integrates this information into an +inbox file and operates on the pointers to flagged entries. Here is +how it works: + + 1. Org moves all entries found in `mobileorg.org'(1) and appends them + to the file pointed to by the variable + `org-mobile-inbox-for-pull'. Each captured entry and each editing + event will be a top-level entry in the inbox file. + + 2. After moving the entries, Org will attempt to implement the + changes made in MobileOrg. Some changes are applied directly and + without user interaction. Examples are all changes to tags, TODO + state, headline and body text that can be cleanly applied. + Entries that have been flagged for further action will receive a + tag `:FLAGGED:', so that they can be easily found again. When + there is a problem finding an entry or applying the change, the + pointer entry will remain in the inbox and will be marked with an + error message. You need to later resolve these issues by hand. + + 3. Org will then generate an agenda view with all flagged entries. + The user should then go through these entries and do whatever + actions are necessary. If a note has been stored while flagging + an entry in MobileOrg, that note will be displayed in the echo + area when the cursor is on the corresponding agenda line. + `?' + Pressing `?' in that special agenda will display the full + flagging note in another window and also push it onto the + kill ring. So you could use `? z C-y C-c C-c' to store that + flagging note as a normal note in the entry. Pressing `?' + twice in succession will offer to remove the `:FLAGGED:' tag + along with the recorded flagging note (which is stored in a + property). In this way you indicate that the intended + processing for this flagged entry is finished. + + If you are not able to process all flagged entries directly, you can +always return to this agenda view(2) using `C-c a ?'. + + ---------- Footnotes ---------- + + (1) `mobileorg.org' will be empty after this operation. + + (2) Note, however, that there is a subtle difference. The view +created automatically by `M-x org-mobile-pull <RET>' is guaranteed to +search all files that have been addressed by the last pull. This might +include a file that is not currently in your list of agenda files. If +you later use `C-c a ?' to regenerate the view, only the current agenda +files will be searched. + + +File: org, Node: History and Acknowledgments, Next: Main Index, Prev: MobileOrg, Up: Top + +Appendix C History and acknowledgments +************************************** + +Org was born 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 show parts of the outline tree, that seemed entirely +unacceptable to me. Also, when using outlines to take notes, I +constantly wanted to restructure the tree, organizing it parallel to my +thoughts and plans. _Visibility cycling_ and _structure editing_ were +originally implemented in the package `outline-magic.el', but quickly +moved to the more general `org.el'. As this environment became +comfortable for project planning, the next step was adding _TODO +entries_, basic _timestamps_, and _table support_. These areas +highlighted the two main goals that Org still has today: to be 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 to +<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. The list may not be complete, if I +have forgotten someone, please accept my apologies and let me know. + + Before I get to this list, a few special mentions are in order: + +Bastien Guerry + Bastien has written a large number of extensions to Org (most of + them integrated into the core by now), including the LaTeX + exporter and the plain list parser. His support during the early + days, when he basically acted as co-maintainer, was central to the + success of this project. Bastien also invented Worg, helped + establishing the Web presence of Org, and sponsors hosting costs + for the orgmode.org website. + +Eric Schulte and Dan Davison + Eric and Dan are jointly responsible for the Org-babel system, + which turns Org into a multi-language environment for evaluating + code and doing literate programming and reproducible research. + +John Wiegley + John has contributed a number of great ideas and patches directly + to Org, including the attachment system (`org-attach.el'), + integration with Apple Mail (`org-mac-message.el'), hierarchical + dependencies of TODO items, habit tracking (`org-habits.el'), and + encryption (`org-crypt.el'). Also, the capture system is really + an extended copy of his great `remember.el'. + +Sebastian Rose + Without Sebastian, the HTML/XHTML publishing of Org would be the + pitiful work of an ignorant amateur. Sebastian has pushed this + part of Org onto a much higher level. He also wrote + `org-info.js', a Java script for displaying webpages derived from + Org using an Info-like or a folding interface with single-key + navigation. + +OK, now to the full list of contributions! Again, please let me know +what I am missing here! + + * Russel Adams came up with the idea for drawers. + + * Thomas Baumann wrote `org-bbdb.el' and `org-mhe.el'. + + * Christophe Bataillon created the great unicorn logo that we use on + the Org-mode website. + + * Alex Bochannek provided a patch for rounding timestamps. + + * Jan Böcker wrote `org-docview.el'. + + * Brad Bozarth showed how to pull RSS feed data into Org-mode files. + + * Tom Breton wrote `org-choose.el'. + + * Charles Cave's suggestion sparked the implementation of templates + for Remember, which are now templates for capture. + + * Pavel Chalmoviansky influenced the agenda treatment of items with + specified time. + + * Gregory Chernov patched support for Lisp forms into table + calculations and improved XEmacs compatibility, in particular by + porting `nouline.el' to XEmacs. + + * Sacha Chua suggested copying some linking code from Planner. + + * Baoqiu Cui contributed the DocBook exporter. + + * 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. + + * Nick Dokos tracked down several nasty bugs. + + * 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. + + * Thomas S. Dye contributed documentation on Worg and helped + integrating the Org-Babel documentation into the manual. + + * Christian Egli converted the documentation into Texinfo format, + inspired the agenda, patched CSS formatting into the HTML + exporter, and wrote `org-taskjuggler.el'. + + * David Emery provided a patch for custom CSS support in exported + HTML agendas. + + * Nic Ferrier contributed mailcap and XOXO support. + + * Miguel A. Figueroa-Villanueva implemented hierarchical checkboxes. + + * John Foerch figured out how to make incremental search show context + around a match in a hidden outline tree. + + * Raimar Finken wrote `org-git-line.el'. + + * Mikael Fornius works as a mailing list moderator. + + * Austin Frank works as a mailing list moderator. + + * Eric Fraga drove the development of BEAMER export with ideas and + testing. + + * Barry Gidden did proofreading the manual in preparation for the + book publication through Network Theory Ltd. + + * Niels Giesen had the idea to automatically archive DONE trees. + + * Nicolas Goaziou rewrote much of the plain list code. + + * Kai Grossjohann pointed out key-binding conflicts with other + packages. + + * Brian Gough of Network Theory Ltd publishes the Org mode manual as + a book. + + * Bernt Hansen has driven much of the support for auto-repeating + tasks, task state change logging, and the clocktable. His clear + explanations have been critical when we started to adopt the Git + version control system. + + * Manuel Hermenegildo has contributed various ideas, small fixes and + patches. + + * Phil Jackson wrote `org-irc.el'. + + * Scott Jaderholm proposed footnotes, control over whitespace between + folded entries, and column view for properties. + + * Matt Jones wrote MobileOrg Android. + + * Tokuya Kameshima wrote `org-wl.el' and `org-mew.el'. + + * Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He also + provided frequent feedback and some patches. + + * Matt Lundin has proposed last-row references for table formulas + and named invisible anchors. He has also worked a lot on the FAQ. + + * David Maus wrote `org-atom.el', maintains the issues file for Org, + and is a prolific contributor on the mailing list with competent + replies, small fixes and patches. + + * Jason F. McBrayer suggested agenda export to CSV format. + + * Max Mikhanosha came up with the idea of refiling. + + * Dmitri Minaev sent a patch to set priority limits on a per-file + basis. + + * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler + happy. + + * Richard Moreland wrote MobileOrg for the iPhone. + + * Rick Moynihan proposed allowing multiple TODO sequences in a file + and being able to quickly restrict the agenda to a subtree. + + * Todd Neal provided patches for links to Info files and Elisp forms. + + * Greg Newman refreshed the unicorn logo into its current form. + + * Tim O'Callaghan suggested in-file links, search options for general + file links, and TAGS. + + * Osamu Okano wrote `orgcard2ref.pl', a Perl program to create a text + version of the reference card. + + * Takeshi Okano translated the manual and David O'Toole's tutorial + into Japanese. + + * Oliver Oppitz suggested multi-state TODO items. + + * Scott Otterson sparked the introduction of descriptive text for + links, among other things. + + * Pete Phillips helped during the development of the TAGS feature, + and provided frequent feedback. + + * Martin Pohlack provided the code snippet to bundle character + insertion into bundles of 20 for undo. + + * T.V. Raman reported bugs and suggested improvements. + + * Matthias Rempe (Oelde) provided ideas, Windows support, and quality + control. + + * Paul Rivier provided the basic implementation of named footnotes. + He also acted as mailing list moderator for some time. + + * Kevin Rogers contributed code to access VM files on remote hosts. + + * Frank Ruell solved the mystery of the `keymapp nil' bug, a + conflict with `allout.el'. + + * Jason Riedy generalized the send-receive mechanism for Orgtbl + tables with extensive patches. + + * Philip Rooke created the Org reference card, provided lots of + feedback, developed and applied standards to the Org documentation. + + * Christian Schlauer proposed angular brackets around links, among + other things. + + * Paul Sexton wrote `org-ctags.el'. + + * Linking to VM/BBDB/Gnus was first inspired by Tom Shannon's + `organizer-mode.el'. + + * Ilya Shlyakhter proposed the Archive Sibling, line numbering in + literal examples, and remote highlighting for referenced code + lines. + + * Stathis Sideris wrote the `ditaa.jar' ASCII to PNG converter that + is now packaged into Org's `contrib' directory. + + * Daniel Sinder came up with the idea of internal archiving by + locking subtrees. + + * Dale Smith proposed link abbreviations. + + * James TD Smith has contributed a large number of patches for useful + tweaks and features. + + * Adam Spiers asked for global linking commands, inspired the link + extension system, added support for mairix, and proposed the + mapping API. + + * Ulf Stegemann created the table to translate special symbols to + HTML, LaTeX, UTF-8, Latin-1 and ASCII. + + * Andy Stewart contributed code to `org-w3m.el', to copy HTML content + with links transformation to Org syntax. + + * David O'Toole wrote `org-publish.el' and drafted the manual + chapter about publishing. + + * Sebastien Vauban reported many issues with LaTeX and BEAMER export + and enabled source code highlighling in Gnus. + + * Stefan Vollmar organized a video-recorded talk at the + Max-Planck-Institute for Neurology. He also inspired the creation + of a concept index for HTML export. + + * Ju"rgen Vollmer contributed code generating the table of contents + in HTML output. + + * Samuel Wales has provided important feedback and bug reports. + + * Chris Wallace provided a patch implementing the `QUOTE' keyword. + + * David Wainberg suggested archiving, and improvements to the linking + system. + + * Carsten Wimmer suggested some changes and helped fix a bug in + linking to Gnus. + + * Roland Winkler requested additional key bindings to make Org work + on a tty. + + * Piotr Zielinski wrote `org-mouse.el', proposed agenda blocks and + contributed various ideas and code snippets. + + +File: org, Node: Main Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top + +Concept index +************* + + +* Menu: + +* #+ARCHIVE: Moving subtrees. (line 27) +* #+ATTR_DOCBOOK: Images in DocBook export. + (line 30) +* #+ATTR_HTML <1>: Links in HTML export. + (line 21) +* #+ATTR_HTML <2>: Tables in HTML export. + (line 11) +* #+ATTR_HTML: Images in HTML export. + (line 24) +* #+ATTR_LaTeX <1>: Images in LaTeX export. + (line 25) +* #+ATTR_LaTeX: Tables in LaTeX export. + (line 13) +* #+AUTHOR: Export options. (line 19) +* #+BEGIN, clocktable: The clock table. (line 35) +* #+BEGIN, columnview: Capturing column view. + (line 11) +* #+BEGIN:dynamic block: Dynamic blocks. (line 15) +* #+BEGIN_CENTER: Paragraphs. (line 31) +* #+BEGIN_COMMENT: Comment lines. (line 6) +* #+BEGIN_DOCBOOK: Quoting DocBook code. + (line 11) +* #+BEGIN_EXAMPLE: Literal examples. (line 8) +* #+BEGIN_HTML: Quoting HTML tags. (line 12) +* #+BEGIN_LaTeX: Quoting LaTeX code. (line 14) +* #+BEGIN_QUOTE: Paragraphs. (line 26) +* #+BEGIN_SRC: Literal examples. (line 27) +* #+BEGIN_VERSE: Paragraphs. (line 13) +* #+BIND: Export options. (line 19) +* #+CAPTION <1>: Images in HTML export. + (line 24) +* #+CAPTION <2>: Tables in HTML export. + (line 11) +* #+CAPTION <3>: Images in DocBook export. + (line 30) +* #+CAPTION <4>: Images and tables. (line 6) +* #+CAPTION <5>: Images in LaTeX export. + (line 25) +* #+CAPTION: Tables in LaTeX export. + (line 13) +* #+CATEGORY: Categories. (line 6) +* #+COLUMNS: Scope of column definitions. + (line 8) +* #+CONSTANTS: References. (line 99) +* #+DATE: Export options. (line 19) +* #+DESCRIPTION: Export options. (line 19) +* #+DOCBOOK: Quoting DocBook code. + (line 9) +* #+DRAWERS: Drawers. (line 6) +* #+EMAIL: Export options. (line 19) +* #+EXPORT_EXCLUDE_TAGS: Export options. (line 19) +* #+EXPORT_SELECT_TAGS: Export options. (line 19) +* #+FILETAGS: Tag inheritance. (line 20) +* #+HTML: Quoting HTML tags. (line 12) +* #+INCLUDE: Include files. (line 7) +* #+INFOJS_OPT: JavaScript support. (line 26) +* #+KEYWORDS: Export options. (line 19) +* #+LABEL <1>: Images and tables. (line 6) +* #+LABEL <2>: Images in LaTeX export. + (line 25) +* #+LABEL <3>: Tables in LaTeX export. + (line 13) +* #+LABEL: Images in DocBook export. + (line 30) +* #+LANGUAGE: Export options. (line 19) +* #+LaTeX: Quoting LaTeX code. (line 12) +* #+LATEX_CLASS: Header and sectioning. + (line 8) +* #+LATEX_CLASS_OPTIONS: Header and sectioning. + (line 8) +* #+LATEX_HEADER <1>: Export options. (line 19) +* #+LATEX_HEADER: Header and sectioning. + (line 8) +* #+LINK: Link abbreviations. (line 41) +* #+LINK_HOME: Export options. (line 19) +* #+LINK_UP: Export options. (line 19) +* #+MACRO: Macro replacement. (line 6) +* #+OPTIONS <1>: Headings and sections. + (line 14) +* #+OPTIONS: Export options. (line 19) +* #+ORGLST: Radio lists. (line 25) +* #+ORGTBL: Radio tables. (line 15) +* #+ORGTBL, SEND: A LaTeX example. (line 14) +* #+PLOT: Org-Plot. (line 6) +* #+PRIORITIES: Priorities. (line 44) +* #+PROPERTY: Property syntax. (line 37) +* #+SEQ_TODO: Per-file keywords. (line 6) +* #+SETUPFILE: In-buffer settings. (line 61) +* #+STARTUP:: In-buffer settings. (line 74) +* #+STYLE: CSS support. (line 44) +* #+TAGS: Setting tags. (line 29) +* #+TBLFM: Field formulas. (line 12) +* #+TBLNAME: References. (line 120) +* #+TEXT <1>: Initial text. (line 6) +* #+TEXT: Export options. (line 19) +* #+TITLE <1>: Document title. (line 8) +* #+TITLE: Export options. (line 19) +* #+TODO: Per-file keywords. (line 6) +* #+TYP_TODO: Per-file keywords. (line 6) +* #+XSLT: Export options. (line 19) +* abbreviation, links: Link abbreviations. (line 6) +* acknowledgments: History and Acknowledgments. + (line 6) +* action, for publishing: Publishing action. (line 6) +* activation: Activation. (line 6) +* active region <1>: Structure editing. (line 124) +* active region <2>: ASCII/Latin-1/UTF-8 export. + (line 11) +* active region <3>: Built-in table editor. + (line 156) +* active region <4>: HTML Export commands. + (line 6) +* active region <5>: LaTeX/PDF export commands. + (line 6) +* active region: DocBook export commands. + (line 6) +* add-on packages: Add-on packages. (line 6) +* add-ons, context-sensitive commands: Context-sensitive commands. + (line 6) +* agenda: Weekly/daily agenda. (line 6) +* agenda dispatcher: Agenda dispatcher. (line 6) +* agenda files: Agenda files. (line 6) +* agenda files, removing buffers: Agenda commands. (line 486) +* agenda views: Agenda Views. (line 6) +* agenda views, custom: Custom agenda views. (line 6) +* agenda views, exporting <1>: Exporting Agenda Views. + (line 13) +* agenda views, exporting <2>: Agenda commands. (line 473) +* agenda views, exporting: Exporting Agenda Views. + (line 6) +* agenda views, user-defined: Special agenda views. + (line 6) +* agenda, column view: Agenda column view. (line 6) +* agenda, pipe: Extracting agenda information. + (line 6) +* agenda, with block views: Block agenda. (line 6) +* align, STARTUP keyword: In-buffer settings. (line 94) +* alignment in tables: Column width and alignment. + (line 6) +* anniversaries, from BBDB: Weekly/daily agenda. (line 69) +* API, for mapping: Using the mapping API. + (line 6) +* API, for properties <1>: Using the property API. + (line 6) +* API, for properties: Property API. (line 6) +* appointment reminders: Weekly/daily agenda. (line 102) +* appt.el: Weekly/daily agenda. (line 102) +* archive locations: Moving subtrees. (line 20) +* archiving: Archiving. (line 6) +* ASCII export: ASCII/Latin-1/UTF-8 export. + (line 6) +* Atom feeds: RSS Feeds. (line 6) +* attachments: Attachments. (line 6) +* author: Feedback. (line 6) +* author info, in export: Export options. (line 39) +* autoload: Activation. (line 6) +* babel, languages: Languages. (line 6) +* babel, library of: Library of Babel. (line 6) +* backtrace of an error: Feedback. (line 40) +* Baur, Steven L.: Cooperation. (line 74) +* BBDB links: External links. (line 6) +* BBDB, anniversaries: Weekly/daily agenda. (line 69) +* block agenda: Block agenda. (line 6) +* blocking, of checkboxes: Checkboxes. (line 46) +* blocks, folding: Blocks. (line 6) +* bold text, markup rules: Emphasis and monospace. + (line 6) +* Boolean logic, for tag/property searches: Matching tags and properties. + (line 34) +* bug reports: Feedback. (line 6) +* C-c C-c, overview: The very busy C-c C-c key. + (line 6) +* calc package: The spreadsheet. (line 6) +* calc.el: Cooperation. (line 6) +* calculations, in tables <1>: The spreadsheet. (line 6) +* calculations, in tables: Built-in table editor. + (line 156) +* calendar commands, from agenda: Agenda commands. (line 422) +* calendar integration: Weekly/daily agenda. (line 28) +* calendar, for selecting date: The date/time prompt. + (line 70) +* capture <1>: Capture. (line 6) +* capture: Capture - Refile - Archive. + (line 6) +* category: Categories. (line 6) +* category, require for tags/property match: Matching tags and properties. + (line 59) +* CDLaTeX: CDLaTeX mode. (line 6) +* cdlatex.el: Cooperation. (line 29) +* checkbox blocking: Checkboxes. (line 46) +* checkbox statistics: Checkboxes. (line 30) +* checkboxes: Checkboxes. (line 6) +* checkboxes and TODO dependencies: TODO dependencies. (line 44) +* children, subtree visibility state: Visibility cycling. (line 10) +* clean outline view: Clean view. (line 6) +* clocking time: Clocking work time. (line 6) +* clocktable, dynamic block: The clock table. (line 6) +* code block, batch execution: Batch execution. (line 6) +* code block, editing: Editing source code. (line 6) +* code block, evaluating: Evaluating code blocks. + (line 6) +* code block, exporting: Exporting code blocks. + (line 6) +* code block, extracting source code: Extracting source code. + (line 6) +* code block, header arguments: Header arguments. (line 6) +* code block, key bindings: Key bindings and useful functions. + (line 6) +* code block, languages: Languages. (line 6) +* code block, library: Library of Babel. (line 6) +* code block, noweb reference: Noweb reference syntax. + (line 6) +* code block, results of evaluation: Results of evaluation. + (line 6) +* code block, structure: Structure of code blocks. + (line 6) +* code line references, markup rules: Literal examples. (line 6) +* code text, markup rules: Emphasis and monospace. + (line 6) +* column formula: Column formulas. (line 6) +* column view, for properties: Defining columns. (line 6) +* column view, in agenda: Agenda column view. (line 6) +* column, of field coordinates: References. (line 84) +* commands, in agenda buffer: Agenda commands. (line 6) +* comment lines: Comment lines. (line 6) +* completion, of dictionary words: Completion. (line 6) +* completion, of file names: Handling links. (line 89) +* completion, of link abbreviations: Completion. (line 6) +* completion, of links: Handling links. (line 66) +* completion, of option keywords <1>: Export options. (line 6) +* completion, of option keywords <2>: Per-file keywords. (line 24) +* completion, of option keywords: Completion. (line 6) +* completion, of property keys: Completion. (line 6) +* completion, of tags <1>: Completion. (line 6) +* completion, of tags: Setting tags. (line 11) +* completion, of TeX symbols: Completion. (line 6) +* completion, of TODO keywords <1>: Workflow states. (line 15) +* completion, of TODO keywords: Completion. (line 6) +* constants, in calculations: References. (line 99) +* constants.el: Cooperation. (line 17) +* constcgs, STARTUP keyword: In-buffer settings. (line 140) +* constSI, STARTUP keyword: In-buffer settings. (line 140) +* content, STARTUP keyword <1>: Visibility cycling. (line 55) +* content, STARTUP keyword: In-buffer settings. (line 80) +* contents, global visibility state: Visibility cycling. (line 22) +* context-sensitive commands, hooks: Context-sensitive commands. + (line 6) +* coordinates, of field: References. (line 84) +* copying, of subtrees: Structure editing. (line 6) +* Countdown timer: Countdown timer. (line 6) +* creating timestamps: Creating timestamps. (line 6) +* CSS, for HTML export: CSS support. (line 6) +* CUA.el: Conflicts. (line 19) +* Cui, Baoqiu: DocBook export. (line 6) +* custom agenda views: Custom agenda views. (line 6) +* custom date/time format: Custom time format. (line 6) +* custom search strings: Custom searches. (line 6) +* customization: Customization. (line 6) +* customtime, STARTUP keyword: In-buffer settings. (line 137) +* cutting, of subtrees: Structure editing. (line 6) +* cycling, of TODO states: TODO basics. (line 14) +* cycling, visibility: Visibility cycling. (line 6) +* daily agenda: Weekly/daily agenda. (line 6) +* date format, custom: Custom time format. (line 6) +* date range: Timestamps. (line 40) +* date stamp: Dates and Times. (line 6) +* date stamps: Timestamps. (line 6) +* date, reading in minibuffer: The date/time prompt. + (line 6) +* dates: Dates and Times. (line 6) +* Davison, Dan: Working With Source Code. + (line 6) +* DEADLINE keyword: Deadlines and scheduling. + (line 9) +* deadlines: Timestamps. (line 6) +* debugging, of table formulas: Editing and debugging formulas. + (line 98) +* demotion, of subtrees: Structure editing. (line 6) +* dependencies, of TODO states: TODO dependencies. (line 6) +* diary entries, creating from agenda: Agenda commands. (line 427) +* diary integration: Weekly/daily agenda. (line 28) +* dictionary word completion: Completion. (line 6) +* directories, for publishing: Sources and destinations. + (line 6) +* dispatcher, for export commands: The export dispatcher. + (line 6) +* dispatching agenda commands: Agenda dispatcher. (line 6) +* display changing, in agenda: Agenda commands. (line 64) +* DocBook export: DocBook export. (line 6) +* DocBook recursive sections: Recursive sections. (line 6) +* document structure: Document Structure. (line 6) +* document title, markup rules: Document title. (line 6) +* Dominik, Carsten: Cooperation. (line 29) +* DONE, final TODO keyword: Per-file keywords. (line 27) +* drawer, for properties: Property syntax. (line 6) +* drawer, for state change recording: Tracking TODO state changes. + (line 6) +* drawers: Drawers. (line 6) +* dvipng: Math formatting in HTML export. + (line 6) +* dynamic blocks: Dynamic blocks. (line 6) +* dynamic indentation: Clean view. (line 6) +* editing tables: Tables. (line 6) +* editing, of table formulas: Editing and debugging formulas. + (line 6) +* effort estimates: Effort estimates. (line 6) +* effort filtering, in agenda: Agenda commands. (line 179) +* Elisp links: External links. (line 6) +* emacsserver: Protocols. (line 6) +* emphasized text: Export options. (line 39) +* entitiesplain, STARTUP keyword: In-buffer settings. (line 160) +* entitiespretty, STARTUP keyword: In-buffer settings. (line 160) +* evaluate time range: Creating timestamps. (line 59) +* even, STARTUP keyword: In-buffer settings. (line 128) +* export, selective by tags: Selective export. (line 6) +* exporting: Exporting. (line 6) +* exporting agenda views <1>: Exporting Agenda Views. + (line 13) +* exporting agenda views: Agenda commands. (line 473) +* exporting, not: Comment lines. (line 6) +* extended TODO keywords: TODO extensions. (line 6) +* external archiving: Moving subtrees. (line 6) +* external links: External links. (line 6) +* external links, in HTML export: Links in HTML export. + (line 6) +* faces, for TODO keywords: Faces for TODO keywords. + (line 6) +* FAQ: Summary. (line 53) +* feedback: Feedback. (line 6) +* field coordinates: References. (line 84) +* field formula: Field formulas. (line 6) +* field references: References. (line 15) +* file links: External links. (line 6) +* file links, searching: Search options. (line 6) +* file name completion: Handling links. (line 89) +* files for agenda: Agenda files. (line 6) +* files, adding to agenda list: Agenda files. (line 15) +* files, selecting for publishing: Selecting files. (line 6) +* filtering, by tag and effort, in agenda: Agenda commands. (line 179) +* fixed-width sections: Export options. (line 39) +* fnadjust, STARTUP keyword: In-buffer settings. (line 145) +* fnauto, STARTUP keyword: In-buffer settings. (line 145) +* fnconfirm, STARTUP keyword: In-buffer settings. (line 145) +* fninline, STARTUP keyword: In-buffer settings. (line 145) +* fnlocal, STARTUP keyword: In-buffer settings. (line 145) +* fnplain, STARTUP keyword: In-buffer settings. (line 145) +* fnprompt, STARTUP keyword: In-buffer settings. (line 145) +* folded, subtree visibility state: Visibility cycling. (line 10) +* folding, sparse trees: Sparse trees. (line 6) +* following links: Handling links. (line 101) +* footnote.el <1>: Footnote markup. (line 6) +* footnote.el: Cooperation. (line 74) +* footnotes <1>: Footnotes. (line 6) +* footnotes: Export options. (line 39) +* footnotes, markup rules: Footnote markup. (line 6) +* format specifier: Formula syntax for Calc. + (line 14) +* format, of links: Link format. (line 6) +* formatting source code, markup rules: Literal examples. (line 23) +* formula debugging: Editing and debugging formulas. + (line 98) +* formula editing: Editing and debugging formulas. + (line 6) +* formula syntax, Calc: Formula syntax for Calc. + (line 6) +* formula, for individual table field: Field formulas. (line 6) +* formula, for table column: Column formulas. (line 6) +* formula, in tables: Built-in table editor. + (line 156) +* Freemind export: Freemind export. (line 6) +* Gillespie, Dave: Cooperation. (line 6) +* global cycling: Visibility cycling. (line 22) +* global key bindings: Activation. (line 6) +* global TODO list: Global TODO list. (line 6) +* global visibility states: Visibility cycling. (line 22) +* Gnus links: External links. (line 6) +* graph, in tables: Org-Plot. (line 6) +* grouping columns in tables: Column groups. (line 6) +* Guerry, Bastien: LaTeX and PDF export. + (line 6) +* habits: Tracking your habits. + (line 6) +* hacking: Hacking. (line 6) +* header, for LaTeX files: Header and sectioning. + (line 6) +* headings and sections, markup rules: Headings and sections. + (line 6) +* headline levels: Export options. (line 39) +* headline levels, for exporting <1>: LaTeX/PDF export commands. + (line 37) +* headline levels, for exporting <2>: HTML Export commands. + (line 39) +* headline levels, for exporting: ASCII/Latin-1/UTF-8 export. + (line 34) +* headline navigation: Motion. (line 6) +* headline tagging: Tags. (line 6) +* headline, promotion and demotion: Structure editing. (line 6) +* headlines: Headlines. (line 6) +* hide text: Visibility cycling. (line 6) +* hideblocks, STARTUP keyword <1>: In-buffer settings. (line 156) +* hideblocks, STARTUP keyword: Blocks. (line 13) +* hidestars, STARTUP keyword: In-buffer settings. (line 128) +* hiding leading stars: Clean view. (line 6) +* history: History and Acknowledgments. + (line 6) +* hooks: Hooks. (line 6) +* horizontal rules, markup rules: Horizontal rules. (line 6) +* HTML entities: Special symbols. (line 6) +* HTML export: HTML export. (line 6) +* HTML export, CSS: CSS support. (line 6) +* HTML, and Orgtbl mode: Translator functions. + (line 6) +* hyperlinks: Hyperlinks. (line 6) +* hyperlinks, adding new types: Adding hyperlink types. + (line 6) +* iCalendar export: iCalendar export. (line 6) +* idle, resolve, dangling: Resolving idle time. (line 6) +* images, inline in DocBook: Images in DocBook export. + (line 6) +* images, inline in HTML: Images in HTML export. + (line 6) +* images, inline in LaTeX: Images in LaTeX export. + (line 6) +* images, inlining: Handling links. (line 134) +* imenu.el: Cooperation. (line 33) +* in-buffer settings: In-buffer settings. (line 6) +* inactive timestamp: Timestamps. (line 49) +* include files, markup rules: Include files. (line 6) +* indent, STARTUP keyword: In-buffer settings. (line 86) +* index entries, for publishing: Index entries. (line 6) +* index, in a publishing project: Generating an index. (line 6) +* Info links: External links. (line 6) +* inheritance, of properties: Property inheritance. + (line 6) +* inheritance, of tags: Tag inheritance. (line 6) +* inlined images, markup rules: Images and tables. (line 18) +* inlineimages, STARTUP keyword <1>: In-buffer settings. (line 101) +* inlineimages, STARTUP keyword: Handling links. (line 134) +* inlining images: Handling links. (line 134) +* inlining images in DocBook: Images in DocBook export. + (line 6) +* inlining images in HTML: Images in HTML export. + (line 6) +* inlining images in LaTeX: Images in LaTeX export. + (line 6) +* inserting links: Handling links. (line 66) +* insertion, of templates: Easy Templates. (line 6) +* installation: Installation. (line 6) +* internal links: Internal links. (line 6) +* internal links, in HTML export: Links in HTML export. + (line 6) +* introduction: Introduction. (line 6) +* iPhone: MobileOrg. (line 6) +* IRC links: External links. (line 6) +* italic text, markup rules: Emphasis and monospace. + (line 6) +* jumping, to headlines: Motion. (line 6) +* key bindings, global: Activation. (line 6) +* keyword options: Per-file keywords. (line 6) +* LaTeX class: Header and sectioning. + (line 6) +* LaTeX entities: Special symbols. (line 6) +* LaTeX export: LaTeX and PDF export. + (line 6) +* LaTeX fragments <1>: Export options. (line 39) +* LaTeX fragments: LaTeX fragments. (line 6) +* LaTeX fragments, markup rules: Special symbols. (line 6) +* LaTeX fragments, preview: Previewing LaTeX fragments. + (line 6) +* LaTeX header: Header and sectioning. + (line 6) +* LaTeX interpretation: Embedded LaTeX. (line 6) +* LaTeX sectioning structure: Header and sectioning. + (line 6) +* LaTeX, and Orgtbl mode: A LaTeX example. (line 6) +* Latin-1 export: ASCII/Latin-1/UTF-8 export. + (line 6) +* level, require for tags/property match: Matching tags and properties. + (line 59) +* line-break preservation: Export options. (line 39) +* link abbreviations: Link abbreviations. (line 6) +* link abbreviations, completion of: Completion. (line 6) +* link completion: Handling links. (line 66) +* link format: Link format. (line 6) +* links, external: External links. (line 6) +* links, finding next/previous: Handling links. (line 154) +* links, handling: Handling links. (line 6) +* links, in HTML export: Links in HTML export. + (line 6) +* links, internal: Internal links. (line 6) +* links, publishing: Publishing links. (line 6) +* links, radio targets: Radio targets. (line 6) +* links, returning to: Handling links. (line 147) +* Lisp forms, as table formulas: Formula syntax for Lisp. + (line 6) +* lists, in other modes: Tables in arbitrary syntax. + (line 6) +* lists, markup rules: Lists. (line 6) +* lists, ordered: Plain lists. (line 6) +* lists, plain: Plain lists. (line 6) +* literal examples, markup rules: Literal examples. (line 6) +* logdone, STARTUP keyword: In-buffer settings. (line 107) +* logging, of progress: Progress logging. (line 6) +* lognoteclock-out, STARTUP keyword: In-buffer settings. (line 107) +* lognotedone, STARTUP keyword: In-buffer settings. (line 107) +* lognoteredeadline, STARTUP keyword: In-buffer settings. (line 107) +* lognoterefile, STARTUP keyword: In-buffer settings. (line 107) +* lognoterepeat, STARTUP keyword: In-buffer settings. (line 107) +* lognotereschedule, STARTUP keyword: In-buffer settings. (line 107) +* logredeadline, STARTUP keyword: In-buffer settings. (line 107) +* logrefile, STARTUP keyword: In-buffer settings. (line 107) +* logrepeat, STARTUP keyword: In-buffer settings. (line 107) +* logreschedule, STARTUP keyword: In-buffer settings. (line 107) +* Ludlam, Eric M.: Cooperation. (line 45) +* macro replacement, during export: Macro replacement. (line 6) +* maintainer: Feedback. (line 6) +* mapping entries, API: Using the mapping API. + (line 6) +* mark ring: Handling links. (line 143) +* marking characters, tables: Advanced features. (line 38) +* match view: Matching tags and properties. + (line 6) +* matching, of properties: Matching tags and properties. + (line 6) +* matching, of tags: Matching tags and properties. + (line 6) +* matching, tags: Tags. (line 6) +* math symbols: Special symbols. (line 6) +* MathJax: Math formatting in HTML export. + (line 6) +* MH-E links: External links. (line 6) +* mind map: Freemind export. (line 6) +* minor mode for structure editing: Orgstruct mode. (line 6) +* minor mode for tables: Orgtbl mode. (line 6) +* MobileOrg: MobileOrg. (line 6) +* mode, for calc: Formula syntax for Calc. + (line 14) +* motion commands in agenda: Agenda commands. (line 19) +* motion, between headlines: Motion. (line 6) +* name, of column or field: References. (line 120) +* named references: References. (line 99) +* names as TODO keywords: TODO types. (line 6) +* narrow columns in tables: Column width and alignment. + (line 6) +* noalign, STARTUP keyword: In-buffer settings. (line 94) +* nofnadjust, STARTUP keyword: In-buffer settings. (line 145) +* nofninline, STARTUP keyword: In-buffer settings. (line 145) +* nohideblocks, STARTUP keyword <1>: In-buffer settings. (line 156) +* nohideblocks, STARTUP keyword: Blocks. (line 13) +* noindent, STARTUP keyword: In-buffer settings. (line 86) +* noinlineimages, STARTUP keyword <1>: In-buffer settings. (line 101) +* noinlineimages, STARTUP keyword: Handling links. (line 134) +* nologdone, STARTUP keyword: In-buffer settings. (line 107) +* nolognoteclock-out, STARTUP keyword: In-buffer settings. (line 107) +* nologredeadline, STARTUP keyword: In-buffer settings. (line 107) +* nologrefile, STARTUP keyword: In-buffer settings. (line 107) +* nologrepeat, STARTUP keyword: In-buffer settings. (line 107) +* nologreschedule, STARTUP keyword: In-buffer settings. (line 107) +* occur, command: Sparse trees. (line 6) +* odd, STARTUP keyword: In-buffer settings. (line 128) +* odd-levels-only outlines: Clean view. (line 6) +* option keyword completion: Completion. (line 6) +* options, for custom agenda views: Setting Options. (line 6) +* options, for customization: Customization. (line 6) +* options, for export: Export options. (line 6) +* options, for publishing: Publishing options. (line 6) +* ordered lists: Plain lists. (line 6) +* org-agenda, command: Weekly/daily agenda. (line 9) +* org-hide-block-startup: In-buffer settings. (line 155) +* org-list-insert-radio-list: Radio lists. (line 6) +* Org-mode, turning on: Activation. (line 23) +* org-pretty-entities: In-buffer settings. (line 159) +* org-publish-project-alist: Project alist. (line 6) +* Orgstruct mode: Orgstruct mode. (line 6) +* Orgtbl mode <1>: Orgtbl mode. (line 6) +* Orgtbl mode: Tables in arbitrary syntax. + (line 6) +* Ota, Takaaki: Cooperation. (line 52) +* Outline mode: Outlines. (line 6) +* outline tree: Headlines. (line 6) +* outlines: Outlines. (line 6) +* overview, global visibility state: Visibility cycling. (line 22) +* overview, STARTUP keyword <1>: In-buffer settings. (line 80) +* overview, STARTUP keyword: Visibility cycling. (line 55) +* packages, interaction with other: Interaction. (line 6) +* paragraphs, markup rules: Paragraphs. (line 6) +* pasting, of subtrees: Structure editing. (line 6) +* PDF export <1>: DocBook export. (line 6) +* PDF export: LaTeX and PDF export. + (line 6) +* per-file keywords: Per-file keywords. (line 6) +* plain lists: Plain lists. (line 6) +* plain text external links: External links. (line 57) +* plot tables using Gnuplot: Org-Plot. (line 6) +* presentation, of agenda items: Presentation and sorting. + (line 6) +* printing sparse trees: Sparse trees. (line 47) +* priorities: Priorities. (line 6) +* priorities, of agenda items: Sorting of agenda items. + (line 6) +* progress logging: Progress logging. (line 6) +* Project management: TaskJuggler export. (line 6) +* projects, for publishing: Project alist. (line 6) +* promotion, of subtrees: Structure editing. (line 6) +* properties: Properties and Columns. + (line 6) +* properties, API <1>: Property API. (line 6) +* properties, API: Using the property API. + (line 6) +* properties, column view: Defining columns. (line 6) +* properties, inheritance: Property inheritance. + (line 6) +* properties, searching: Property searches. (line 6) +* properties, special: Special properties. (line 6) +* property EXPORT_FILE_NAME <1>: DocBook export commands. + (line 7) +* property EXPORT_FILE_NAME: LaTeX/PDF export commands. + (line 7) +* property syntax: Property syntax. (line 6) +* property, _ALL: Property syntax. (line 37) +* property, ARCHIVE <1>: Moving subtrees. (line 29) +* property, ARCHIVE: Property inheritance. + (line 34) +* property, ATTACH_DIR: Attachments. (line 71) +* property, ATTACH_DIR_INHERIT: Attachments. (line 76) +* property, CATEGORY <1>: Categories. (line 12) +* property, CATEGORY: Property inheritance. + (line 30) +* property, COLUMNS <1>: In-buffer settings. (line 30) +* property, COLUMNS: Property inheritance. + (line 22) +* property, COOKIE_DATA <1>: Breaking down tasks. (line 21) +* property, COOKIE_DATA: Checkboxes. (line 30) +* property, CUSTOM_ID <1>: Handling links. (line 21) +* property, CUSTOM_ID: Internal links. (line 6) +* property, DESCRIPTION: iCalendar export. (line 46) +* property, Effort: Effort estimates. (line 6) +* property, EXPORT_FILE_NAME <1>: HTML Export commands. + (line 7) +* property, EXPORT_FILE_NAME: ASCII/Latin-1/UTF-8 export. + (line 12) +* property, EXPORT_TITLE: Document title. (line 15) +* property, ID <1>: Handling links. (line 21) +* property, ID <2>: Capturing column view. + (line 22) +* property, ID: iCalendar export. (line 21) +* property, LATEX_CLASS: Header and sectioning. + (line 8) +* property, LATEX_CLASS_OPTIONS: Header and sectioning. + (line 8) +* property, LOCATION: iCalendar export. (line 46) +* property, LOG_INTO_DRAWER: Tracking TODO state changes. + (line 6) +* property, LOGGING <1>: Property inheritance. + (line 38) +* property, LOGGING: Tracking TODO state changes. + (line 42) +* property, ORDERED <1>: TODO dependencies. (line 30) +* property, ORDERED <2>: Checkboxes. (line 46) +* property, ORDERED: TODO dependencies. (line 6) +* property, special, ALLTAGS: Special properties. (line 13) +* property, special, BLOCKED: Special properties. (line 13) +* property, special, CATEGORY: Special properties. (line 13) +* property, special, CLOCKSUM <1>: Special properties. (line 13) +* property, special, CLOCKSUM: Agenda column view. (line 28) +* property, special, CLOSED: Special properties. (line 13) +* property, special, DEADLINE: Special properties. (line 13) +* property, special, ITEM: Special properties. (line 13) +* property, special, PRIORITY: Special properties. (line 13) +* property, special, SCHEDULED: Special properties. (line 13) +* property, special, TAGS: Special properties. (line 13) +* property, special, TIMESTAMP: Special properties. (line 13) +* property, special, TIMESTAMP_IA: Special properties. (line 13) +* property, special, TODO: Special properties. (line 13) +* property, SUMMARY: iCalendar export. (line 46) +* property, VISIBILITY: Visibility cycling. (line 65) +* property: CLOCK_MODELINE_TOTAL: Clocking commands. (line 16) +* property: LAST_REPEAT: Clocking commands. (line 16) +* protocols, for external access: Protocols. (line 6) +* publishing: Publishing. (line 6) +* query editing, in agenda: Agenda commands. (line 179) +* quoted HTML tags: Export options. (line 39) +* radio lists: Radio lists. (line 6) +* radio tables: Radio tables. (line 6) +* radio targets: Radio targets. (line 6) +* range references: References. (line 62) +* ranges, time: Timestamps. (line 6) +* recomputing table fields: Updating the table. (line 6) +* references: References. (line 6) +* references, named: References. (line 99) +* references, remote: References. (line 120) +* references, to a different table: References. (line 120) +* references, to fields: References. (line 15) +* references, to ranges: References. (line 62) +* refiling notes: Refiling notes. (line 6) +* region, active <1>: ASCII/Latin-1/UTF-8 export. + (line 11) +* region, active <2>: HTML Export commands. + (line 6) +* region, active <3>: LaTeX/PDF export commands. + (line 6) +* region, active <4>: DocBook export commands. + (line 6) +* region, active <5>: Structure editing. (line 124) +* region, active: Built-in table editor. + (line 156) +* regular expressions, with tags search: Matching tags and properties. + (line 55) +* relative timer: Relative timer. (line 6) +* remember.el: Cooperation. (line 42) +* remote editing, bulk, from agenda: Agenda commands. (line 388) +* remote editing, from agenda: Agenda commands. (line 258) +* remote editing, undo: Agenda commands. (line 259) +* remote references: References. (line 120) +* repeated tasks: Repeated tasks. (line 6) +* report, of clocked time: The clock table. (line 6) +* resolve idle time: Resolving idle time. (line 6) +* RMAIL links: External links. (line 6) +* Rose, Sebastian: JavaScript support. (line 6) +* row, of field coordinates: References. (line 84) +* RSS feeds: RSS Feeds. (line 6) +* rsync: Uploading files. (line 6) +* SCHEDULED keyword: Deadlines and scheduling. + (line 27) +* scheduling: Timestamps. (line 6) +* Schulte, Eric: Working With Source Code. + (line 6) +* Scripts, for agenda processing: Extracting agenda information. + (line 6) +* search option in file links: Search options. (line 6) +* search strings, custom: Custom searches. (line 6) +* search view: Search view. (line 6) +* searching for tags: Tag searches. (line 6) +* searching, for text: Search view. (line 6) +* searching, of properties: Property searches. (line 6) +* section-numbers: Export options. (line 39) +* sectioning structure, for LaTeX export: Header and sectioning. + (line 6) +* setting tags: Setting tags. (line 6) +* SHELL links: External links. (line 6) +* shift-selection-mode <1>: Plain lists. (line 101) +* shift-selection-mode: Conflicts. (line 6) +* show all, command: Visibility cycling. (line 33) +* show all, global visibility state: Visibility cycling. (line 22) +* show hidden text: Visibility cycling. (line 6) +* showall, STARTUP keyword <1>: Visibility cycling. (line 55) +* showall, STARTUP keyword: In-buffer settings. (line 80) +* showeverything, STARTUP keyword <1>: Visibility cycling. (line 55) +* showeverything, STARTUP keyword: In-buffer settings. (line 80) +* showstars, STARTUP keyword: In-buffer settings. (line 128) +* sitemap, of published pages: Sitemap. (line 6) +* sorting, of agenda items: Sorting of agenda items. + (line 6) +* sorting, of subtrees: Structure editing. (line 6) +* source code, batch execution: Batch execution. (line 6) +* source code, block header arguments: Header arguments. (line 6) +* source code, block structure: Structure of code blocks. + (line 6) +* source code, editing: Editing source code. (line 6) +* source code, evaluating: Evaluating code blocks. + (line 6) +* source code, exporting: Exporting code blocks. + (line 6) +* source code, extracting: Extracting source code. + (line 6) +* source code, languages: Languages. (line 6) +* source code, library: Library of Babel. (line 6) +* source code, noweb reference: Noweb reference syntax. + (line 6) +* source code, results of evaluation: Results of evaluation. + (line 6) +* source code, working with: Working With Source Code. + (line 6) +* sparse tree, for deadlines: Inserting deadline/schedule. + (line 31) +* sparse tree, for TODO: TODO basics. (line 36) +* sparse tree, tag based: Tags. (line 6) +* sparse trees: Sparse trees. (line 6) +* Special characters in DocBook export: Special characters. (line 6) +* special keywords: In-buffer settings. (line 6) +* special strings: Export options. (line 39) +* special symbols: Special symbols. (line 6) +* speed keys: Speed keys. (line 6) +* speedbar.el: Cooperation. (line 45) +* spreadsheet capabilities: The spreadsheet. (line 6) +* square brackets, around links: External links. (line 57) +* statistics, for checkboxes: Checkboxes. (line 30) +* statistics, for TODO items: Breaking down tasks. (line 6) +* storing links: Handling links. (line 10) +* Storm, Kim. F.: Conflicts. (line 19) +* strike-through text, markup rules: Emphasis and monospace. + (line 6) +* structure editing: Structure editing. (line 6) +* structure of document: Document Structure. (line 6) +* sublevels, inclusion into tags match: Tag inheritance. (line 6) +* sublevels, inclusion into TODO list: Global TODO list. (line 35) +* subscript: Subscripts and superscripts. + (line 6) +* subtree cycling: Visibility cycling. (line 10) +* subtree visibility states: Visibility cycling. (line 10) +* subtree, cut and paste: Structure editing. (line 6) +* subtree, subtree visibility state: Visibility cycling. (line 10) +* subtrees, cut and paste: Structure editing. (line 6) +* summary: Summary. (line 6) +* superscript: Subscripts and superscripts. + (line 6) +* syntax, noweb: Noweb reference syntax. + (line 6) +* syntax, of formulas: Formula syntax for Calc. + (line 6) +* table editor, built-in: Built-in table editor. + (line 6) +* table editor, table.el: Cooperation. (line 52) +* table of contents: Export options. (line 39) +* table of contents, markup rules: Table of contents. (line 6) +* table.el: Cooperation. (line 49) +* tables <1>: Tables. (line 6) +* tables: Export options. (line 39) +* tables, in DocBook export: Tables in DocBook export. + (line 6) +* tables, in HTML: Tables in HTML export. + (line 6) +* tables, in LaTeX export: Tables in LaTeX export. + (line 6) +* tables, in other modes: Tables in arbitrary syntax. + (line 6) +* tables, markup rules: Images and tables. (line 6) +* tag completion: Completion. (line 6) +* tag filtering, in agenda: Agenda commands. (line 179) +* tag inheritance: Tag inheritance. (line 6) +* tag searches: Tag searches. (line 6) +* tags: Tags. (line 6) +* tags view: Matching tags and properties. + (line 6) +* tags, setting: Setting tags. (line 6) +* targets, for links: Internal links. (line 6) +* targets, radio: Radio targets. (line 6) +* TaskJuggler export: TaskJuggler export. (line 6) +* tasks, breaking down: Breaking down tasks. (line 6) +* tasks, repeated: Repeated tasks. (line 6) +* template insertion: Easy Templates. (line 6) +* templates, for Capture: Capture templates. (line 6) +* TeX interpretation: Embedded LaTeX. (line 6) +* TeX macros <1>: Special symbols. (line 6) +* TeX macros: Export options. (line 39) +* TeX symbol completion: Completion. (line 6) +* TeX-like syntax for sub- and superscripts: Export options. (line 39) +* text areas, in HTML: Text areas in HTML export. + (line 6) +* text before first headline, markup rules: Initial text. (line 6) +* text search: Search view. (line 6) +* thanks: History and Acknowledgments. + (line 6) +* time clocking: Clocking work time. (line 6) +* time format, custom: Custom time format. (line 6) +* time grid: Time-of-day specifications. + (line 26) +* time info, in export: Export options. (line 39) +* time, reading in minibuffer: The date/time prompt. + (line 6) +* time-of-day specification: Time-of-day specifications. + (line 6) +* time-sorted view: Timeline. (line 6) +* timeline, single file: Timeline. (line 6) +* timerange: Timestamps. (line 40) +* times: Dates and Times. (line 6) +* timestamp <1>: Timestamps. (line 14) +* timestamp: Dates and Times. (line 6) +* timestamp, inactive: Timestamps. (line 49) +* timestamp, with repeater interval: Timestamps. (line 24) +* timestamps: Timestamps. (line 6) +* timestamps, creating: Creating timestamps. (line 6) +* TODO dependencies: TODO dependencies. (line 6) +* TODO items: TODO Items. (line 6) +* TODO keyword matching: Global TODO list. (line 18) +* TODO keyword matching, with tags search: Matching tags and properties. + (line 59) +* TODO keyword sets: Multiple sets in one file. + (line 6) +* TODO keywords completion: Completion. (line 6) +* TODO list, global: Global TODO list. (line 6) +* TODO types: TODO types. (line 6) +* TODO workflow: Workflow states. (line 6) +* transient mark mode <1>: Structure editing. (line 124) +* transient mark mode: Built-in table editor. + (line 156) +* transient-mark-mode <1>: HTML Export commands. + (line 6) +* transient-mark-mode <2>: LaTeX/PDF export commands. + (line 6) +* transient-mark-mode <3>: ASCII/Latin-1/UTF-8 export. + (line 11) +* transient-mark-mode: DocBook export commands. + (line 6) +* translator function: Translator functions. + (line 6) +* trees, sparse: Sparse trees. (line 6) +* trees, visibility: Visibility cycling. (line 6) +* tty key bindings: TTY keys. (line 6) +* types as TODO keywords: TODO types. (line 6) +* underlined text, markup rules: Emphasis and monospace. + (line 6) +* undoing remote-editing events: Agenda commands. (line 259) +* unison: Uploading files. (line 6) +* updating, table: Updating the table. (line 6) +* URL links: External links. (line 6) +* USENET links: External links. (line 6) +* UTF-8 export: ASCII/Latin-1/UTF-8 export. + (line 6) +* variables, for customization: Customization. (line 6) +* vectors, in table calculations: Formula syntax for Calc. + (line 11) +* verbatim text, markup rules: Emphasis and monospace. + (line 6) +* viper.el: Conflicts. (line 62) +* visibility cycling: Visibility cycling. (line 6) +* visibility cycling, drawers: Drawers. (line 6) +* visible text, printing: Sparse trees. (line 47) +* VM links: External links. (line 6) +* WANDERLUST links: External links. (line 6) +* weekly agenda: Weekly/daily agenda. (line 6) +* Wiegley, John: Cooperation. (line 42) +* windmove.el: Conflicts. (line 49) +* workflow states as TODO keywords: Workflow states. (line 6) +* XEmacs: Installation. (line 6) +* XOXO export: XOXO export. (line 6) +* yasnippet.el: Conflicts. (line 39) + + +File: org, Node: Key Index, Next: Command and Function Index, Prev: Main Index, Up: Top + +Key index +********* + + +* Menu: + +* $: Agenda commands. (line 293) +* ': CDLaTeX mode. (line 42) +* +: Agenda commands. (line 315) +* ,: Agenda commands. (line 307) +* ,org-agenda-filter-by-tag-refine: Agenda commands. (line 238) +* -: Agenda commands. (line 320) +* .: Agenda commands. (line 90) +* /: Agenda commands. (line 179) +* :: Agenda commands. (line 303) +* ;: Countdown timer. (line 6) +* < <1>: Agenda files. (line 56) +* < <2>: The date/time prompt. + (line 76) +* <: Using column view. (line 70) +* <RET> <1>: The date/time prompt. + (line 76) +* <RET> <2>: Agenda commands. (line 37) +* <RET> <3>: Setting tags. (line 115) +* <RET> <4>: Handling links. (line 118) +* <RET>: Built-in table editor. + (line 65) +* <SPC> <1>: Agenda commands. (line 28) +* <SPC>: Setting tags. (line 112) +* <TAB> <1>: Editing and debugging formulas. + (line 56) +* <TAB> <2>: Visibility cycling. (line 10) +* <TAB> <3>: Structure editing. (line 32) +* <TAB> <4>: Plain lists. (line 91) +* <TAB> <5>: Built-in table editor. + (line 58) +* <TAB> <6>: CDLaTeX mode. (line 22) +* <TAB> <7>: Agenda commands. (line 34) +* <TAB>: Setting tags. (line 107) +* > <1>: The date/time prompt. + (line 76) +* > <2>: Using column view. (line 70) +* > <3>: Agenda commands. (line 365) +* >: Agenda files. (line 60) +* ?: Pulling from MobileOrg. + (line 33) +* [: Agenda commands. (line 245) +* ]: Agenda commands. (line 245) +* ^: CDLaTeX mode. (line 32) +* _: CDLaTeX mode. (line 32) +* `: CDLaTeX mode. (line 38) +* a <1>: Agenda commands. (line 281) +* a: Using column view. (line 59) +* b: Agenda commands. (line 87) +* B: Agenda commands. (line 396) +* c: Agenda commands. (line 422) +* C: Agenda commands. (line 455) +* c: Agenda commands. (line 423) +* C-#: Advanced features. (line 9) +* C-': Agenda files. (line 22) +* C-,: Agenda files. (line 22) +* C-0 C-c C-w: Refiling notes. (line 40) +* C-<RET>: Structure editing. (line 18) +* C-_: Agenda commands. (line 259) +* C-c !: Creating timestamps. (line 15) +* C-c #: Checkboxes. (line 83) +* C-c $: Moving subtrees. (line 9) +* C-c %: Handling links. (line 140) +* C-c &: Handling links. (line 144) +* C-c ' <1>: Literal examples. (line 65) +* C-c ' <2>: Editing source code. (line 6) +* C-c ' <3>: Editing and debugging formulas. + (line 36) +* C-c ' <4>: Include files. (line 22) +* C-c ': Cooperation. (line 61) +* C-c * <1>: Plain lists. (line 146) +* C-c * <2>: Structure editing. (line 113) +* C-c *: Updating the table. (line 13) +* C-c +: Built-in table editor. + (line 156) +* C-c ,: Priorities. (line 24) +* C-c ,org-match-sparse-tree <1>: Property searches. (line 9) +* C-c ,org-match-sparse-tree: Tag searches. (line 9) +* C-c - <1>: Built-in table editor. + (line 101) +* C-c -: Plain lists. (line 135) +* C-c .: Creating timestamps. (line 10) +* C-c / <1>: Sparse trees. (line 15) +* C-c /: Conflicts. (line 62) +* C-c / a: Inserting deadline/schedule. + (line 38) +* C-c / b: Inserting deadline/schedule. + (line 35) +* C-c / d: Inserting deadline/schedule. + (line 28) +* C-c / m <1>: Property searches. (line 9) +* C-c / m: Tag searches. (line 9) +* C-c / p: Property searches. (line 28) +* C-c / r: Sparse trees. (line 17) +* C-c / t: TODO basics. (line 33) +* C-c ;: Comment lines. (line 12) +* C-c <: Creating timestamps. (line 26) +* C-c <RET>: Built-in table editor. + (line 105) +* C-c = <1>: Column formulas. (line 27) +* C-c =: Editing and debugging formulas. + (line 13) +* C-c >: Creating timestamps. (line 30) +* C-c ?: Editing and debugging formulas. + (line 22) +* C-c [: Agenda files. (line 15) +* C-c ]: Agenda files. (line 19) +* C-c ^ <1>: Plain lists. (line 156) +* C-c ^ <2>: Built-in table editor. + (line 109) +* C-c ^: Structure editing. (line 94) +* C-c `: Built-in table editor. + (line 174) +* C-c a !: Stuck projects. (line 14) +* C-c a #: Stuck projects. (line 13) +* C-c a ?: Pulling from MobileOrg. + (line 43) +* C-c a a: Weekly/daily agenda. (line 9) +* C-c a C: Storing searches. (line 9) +* C-c a e: Exporting Agenda Views. + (line 65) +* C-c a L: Timeline. (line 10) +* C-c a m: Property searches. (line 11) +* C-c a M: Tag searches. (line 16) +* C-c a m: Tag searches. (line 12) +* C-c a M: Property searches. (line 15) +* C-c a m: Matching tags and properties. + (line 12) +* C-c a M: Matching tags and properties. + (line 17) +* C-c a s: Search view. (line 9) +* C-c a t <1>: TODO basics. (line 44) +* C-c a t: Global TODO list. (line 9) +* C-c a T: Global TODO list. (line 15) +* C-c c: Using capture. (line 6) +* C-c c C: Capture templates. (line 10) +* C-c C-a <1>: Attachments. (line 26) +* C-c C-a: Agenda commands. (line 328) +* C-c C-a a: Attachments. (line 31) +* C-c C-a c: Attachments. (line 37) +* C-c C-a d: Attachments. (line 63) +* C-c C-a D: Attachments. (line 66) +* C-c C-a F: Attachments. (line 60) +* C-c C-a f: Attachments. (line 57) +* C-c C-a i: Attachments. (line 75) +* C-c C-a l: Attachments. (line 37) +* C-c C-a m: Attachments. (line 37) +* C-c C-a n: Attachments. (line 41) +* C-c C-a o: Attachments. (line 48) +* C-c C-a O: Attachments. (line 54) +* C-c C-a s: Attachments. (line 70) +* C-c C-a z: Attachments. (line 44) +* C-c C-b <1>: Motion. (line 15) +* C-c C-b: Beamer class export. (line 83) +* C-c C-c <1>: Previewing LaTeX fragments. + (line 15) +* C-c C-c <2>: Clocking commands. (line 41) +* C-c C-c <3>: The clock table. (line 15) +* C-c C-c <4>: Clocking commands. (line 41) +* C-c C-c <5>: Using capture. (line 15) +* C-c C-c <6>: Cooperation. (line 52) +* C-c C-c <7>: The very busy C-c C-c key. + (line 6) +* C-c C-c <8>: Plain lists. (line 129) +* C-c C-c <9>: Footnotes. (line 87) +* C-c C-c <10>: Built-in table editor. + (line 57) +* C-c C-c <11>: Capturing column view. + (line 51) +* C-c C-c <12>: Using column view. (line 52) +* C-c C-c <13>: Editing and debugging formulas. + (line 91) +* C-c C-c <14>: Key bindings and useful functions. + (line 11) +* C-c C-c <15>: Property syntax. (line 57) +* C-c C-c <16>: Evaluating code blocks. + (line 13) +* C-c C-c <17>: Checkboxes. (line 52) +* C-c C-c: Setting tags. (line 18) +* C-c C-c c: Property syntax. (line 75) +* C-c C-c d: Property syntax. (line 69) +* C-c C-c D: Property syntax. (line 72) +* C-c C-c s: Property syntax. (line 61) +* C-c C-d <1>: Inserting deadline/schedule. + (line 9) +* C-c C-d: Agenda commands. (line 335) +* C-c C-e: The export dispatcher. + (line 12) +* C-c C-e A: ASCII/Latin-1/UTF-8 export. + (line 18) +* C-c C-e a: ASCII/Latin-1/UTF-8 export. + (line 11) +* C-c C-e b: HTML Export commands. + (line 13) +* C-c C-e c: iCalendar export. (line 39) +* C-c C-e D: DocBook export commands. + (line 6) +* C-c C-e d: LaTeX/PDF export commands. + (line 31) +* C-c C-e E: Triggering publication. + (line 16) +* C-c C-e F: Triggering publication. + (line 13) +* C-c C-e H: HTML Export commands. + (line 16) +* C-c C-e h: HTML Export commands. + (line 6) +* C-c C-e I: iCalendar export. (line 34) +* C-c C-e i: iCalendar export. (line 32) +* C-c C-e j: TaskJuggler export. (line 24) +* C-c C-e J: TaskJuggler export. (line 27) +* C-c C-e l: LaTeX/PDF export commands. + (line 6) +* C-c C-e L: LaTeX/PDF export commands. + (line 13) +* C-c C-e m: Freemind export. (line 8) +* C-c C-e N: ASCII/Latin-1/UTF-8 export. + (line 24) +* C-c C-e n: ASCII/Latin-1/UTF-8 export. + (line 21) +* C-c C-e P: Triggering publication. + (line 10) +* C-c C-e p: LaTeX/PDF export commands. + (line 28) +* C-c C-e R: HTML Export commands. + (line 19) +* C-c C-e t: Export options. (line 16) +* C-c C-e U: ASCII/Latin-1/UTF-8 export. + (line 28) +* C-c C-e u: ASCII/Latin-1/UTF-8 export. + (line 25) +* C-c C-e V: DocBook export commands. + (line 13) +* C-c C-e v <1>: The export dispatcher. + (line 17) +* C-c C-e v: Sparse trees. (line 47) +* C-c C-e v D: DocBook export commands. + (line 32) +* C-c C-e v x: XOXO export. (line 11) +* C-c C-e X: Triggering publication. + (line 8) +* C-c C-e x: XOXO export. (line 10) +* C-c C-f: Motion. (line 12) +* C-c C-j: Motion. (line 21) +* C-c C-k <1>: Visibility cycling. (line 43) +* C-c C-k: Using capture. (line 31) +* C-c C-l: Handling links. (line 65) +* C-c C-n: Motion. (line 8) +* C-c C-o <1>: Handling links. (line 101) +* C-c C-o <2>: Agenda commands. (line 56) +* C-c C-o <3>: Key bindings and useful functions. + (line 11) +* C-c C-o <4>: Footnotes. (line 91) +* C-c C-o: Creating timestamps. (line 35) +* C-c C-p: Motion. (line 9) +* C-c C-q <1>: Editing and debugging formulas. + (line 49) +* C-c C-q: Setting tags. (line 10) +* C-c C-r <1>: Visibility cycling. (line 34) +* C-c C-r: Editing and debugging formulas. + (line 52) +* C-c C-s <1>: Inserting deadline/schedule. + (line 14) +* C-c C-s: Agenda commands. (line 331) +* C-c C-t <1>: TODO basics. (line 13) +* C-c C-t: Clocking commands. (line 46) +* C-c C-u: Motion. (line 18) +* C-c C-v a: Key bindings and useful functions. + (line 18) +* C-c C-v b: Key bindings and useful functions. + (line 18) +* C-c C-v C-a: Key bindings and useful functions. + (line 18) +* C-c C-v C-b: Key bindings and useful functions. + (line 18) +* C-c C-v C-f: Key bindings and useful functions. + (line 20) +* C-c C-v C-l: Key bindings and useful functions. + (line 25) +* C-c C-v C-p: Key bindings and useful functions. + (line 26) +* C-c C-v C-s: Key bindings and useful functions. + (line 28) +* C-c C-v C-t: Key bindings and useful functions. + (line 30) +* C-c C-v C-z: Key bindings and useful functions. + (line 32) +* C-c C-v f: Key bindings and useful functions. + (line 20) +* C-c C-v g: Key bindings and useful functions. + (line 22) +* C-c C-v h: Key bindings and useful functions. + (line 24) +* C-c C-v i: Library of Babel. (line 16) +* C-c C-v l: Key bindings and useful functions. + (line 25) +* C-c C-v p: Key bindings and useful functions. + (line 26) +* C-c C-v s: Key bindings and useful functions. + (line 28) +* C-c C-v t <1>: Extracting source code. + (line 26) +* C-c C-v t: Key bindings and useful functions. + (line 30) +* C-c C-v z: Key bindings and useful functions. + (line 32) +* C-c C-w <1>: Structure editing. (line 90) +* C-c C-w <2>: Agenda commands. (line 278) +* C-c C-w <3>: Refiling notes. (line 11) +* C-c C-w: Using capture. (line 22) +* C-c C-x ,: Relative timer. (line 21) +* C-c C-x -: Relative timer. (line 13) +* C-c C-x .: Relative timer. (line 10) +* C-c C-x 0: Relative timer. (line 30) +* C-c C-x ;: Countdown timer. (line 6) +* C-c C-x <: Agenda files. (line 42) +* C-c C-x > <1>: Agenda commands. (line 172) +* C-c C-x >: Agenda files. (line 49) +* C-c C-x \ <1>: Subscripts and superscripts. + (line 27) +* C-c C-x \: Special symbols. (line 31) +* C-c C-x A <1>: Internal archiving. (line 49) +* C-c C-x A: Agenda commands. (line 289) +* C-c C-x a <1>: Agenda commands. (line 286) +* C-c C-x a: Internal archiving. (line 36) +* C-c C-x b <1>: Visibility cycling. (line 47) +* C-c C-x b: Agenda commands. (line 47) +* C-c C-x c: Structure editing. (line 82) +* C-c C-x C-a <1>: Agenda commands. (line 281) +* C-c C-x C-a: Archiving. (line 11) +* C-c C-x C-b: Checkboxes. (line 55) +* C-c C-x C-c <1>: Using column view. (line 9) +* C-c C-x C-c <2>: Agenda column view. (line 11) +* C-c C-x C-c: Agenda commands. (line 161) +* C-c C-x C-d: Clocking commands. (line 59) +* C-c C-x C-e <1>: Clocking commands. (line 38) +* C-c C-x C-e: Effort estimates. (line 17) +* C-c C-x C-i: Clocking commands. (line 6) +* C-c C-x C-j: Clocking commands. (line 54) +* C-c C-x C-k: Inserting deadline/schedule. + (line 22) +* C-c C-x C-l: Previewing LaTeX fragments. + (line 9) +* C-c C-x C-n: Handling links. (line 150) +* C-c C-x C-o: Clocking commands. (line 30) +* C-c C-x C-p: Handling links. (line 150) +* C-c C-x C-r: The clock table. (line 10) +* C-c C-x C-s <1>: Agenda commands. (line 293) +* C-c C-x C-s: Moving subtrees. (line 9) +* C-c C-x C-t: Custom time format. (line 12) +* C-c C-x C-u <1>: Capturing column view. + (line 51) +* C-c C-x C-u <2>: Dynamic blocks. (line 21) +* C-c C-x C-u: The clock table. (line 15) +* C-c C-x C-v: Handling links. (line 131) +* C-c C-x C-w <1>: Built-in table editor. + (line 130) +* C-c C-x C-w: Structure editing. (line 56) +* C-c C-x C-x: Clocking commands. (line 50) +* C-c C-x C-y <1>: Built-in table editor. + (line 134) +* C-c C-x C-y: Structure editing. (line 64) +* C-c C-x e: Effort estimates. (line 14) +* C-c C-x f: Footnotes. (line 51) +* C-c C-x G: RSS Feeds. (line 27) +* C-c C-x g: RSS Feeds. (line 23) +* C-c C-x i: Capturing column view. + (line 49) +* C-c C-x M-w <1>: Structure editing. (line 60) +* C-c C-x M-w: Built-in table editor. + (line 126) +* C-c C-x o <1>: Checkboxes. (line 75) +* C-c C-x o: TODO dependencies. (line 29) +* C-c C-x p <1>: Header arguments in Org-mode properties. + (line 23) +* C-c C-x p: Property syntax. (line 48) +* C-c C-y <1>: Creating timestamps. (line 56) +* C-c C-y: Clocking commands. (line 41) +* C-c C-z <1>: Agenda commands. (line 323) +* C-c C-z: Drawers. (line 28) +* C-c l <1>: Handling links. (line 9) +* C-c l: Literal examples. (line 73) +* C-c { <1>: Editing and debugging formulas. + (line 32) +* C-c {: CDLaTeX mode. (line 20) +* C-c |: Built-in table editor. + (line 41) +* C-c }: Editing and debugging formulas. + (line 80) +* C-c ~: Cooperation. (line 63) +* C-k: Agenda commands. (line 272) +* C-S-<left> <1>: Multiple sets in one file. + (line 25) +* C-S-<left>: Agenda commands. (line 270) +* C-S-<RET>: Structure editing. (line 27) +* C-S-<right> <1>: Agenda commands. (line 267) +* C-S-<right>: Multiple sets in one file. + (line 25) +* C-TAB: Internal archiving. (line 46) +* C-u C-c !: Creating timestamps. (line 19) +* C-u C-c *: Updating the table. (line 16) +* C-u C-c .: Creating timestamps. (line 19) +* C-u C-c = <1>: Field formulas. (line 26) +* C-u C-c =: Editing and debugging formulas. + (line 13) +* C-u C-c c: Using capture. (line 43) +* C-u C-c C-c: Updating the table. (line 19) +* C-u C-c C-l: Handling links. (line 86) +* C-u C-c C-t: TODO basics. (line 22) +* C-u C-c C-w: Refiling notes. (line 28) +* C-u C-c C-x ,: Relative timer. (line 25) +* C-u C-c C-x a: Internal archiving. (line 39) +* C-u C-c C-x C-s: Moving subtrees. (line 11) +* C-u C-c C-x C-u <1>: Capturing column view. + (line 55) +* C-u C-c C-x C-u <2>: Dynamic blocks. (line 22) +* C-u C-c C-x C-u: The clock table. (line 19) +* C-u C-u <TAB>: Visibility cycling. (line 68) +* C-u C-u C-c *: Updating the table. (line 22) +* C-u C-u C-c =: Editing and debugging formulas. + (line 16) +* C-u C-u C-c c: Using capture. (line 45) +* C-u C-u C-c C-c: Updating the table. (line 22) +* C-u C-u C-c C-e: The export dispatcher. + (line 21) +* C-u C-u C-c C-t: Multiple sets in one file. + (line 25) +* C-u C-u C-c C-w: Refiling notes. (line 31) +* C-u C-u C-u <TAB>: Visibility cycling. (line 33) +* C-u C-u C-u C-c C-t: TODO dependencies. (line 34) +* C-up: Key bindings and useful functions. + (line 12) +* C-v: The date/time prompt. + (line 76) +* C-x C-s <1>: Editing and debugging formulas. + (line 46) +* C-x C-s: Agenda commands. (line 157) +* C-x C-w <1>: Exporting Agenda Views. + (line 12) +* C-x C-w: Agenda commands. (line 472) +* C-x n s: Structure editing. (line 107) +* C-x n w: Structure editing. (line 110) +* C-y: Structure editing. (line 70) +* d: Agenda commands. (line 65) +* D: Agenda commands. (line 99) +* e: Using column view. (line 46) +* E: Agenda commands. (line 135) +* F: Agenda commands. (line 40) +* f: Agenda commands. (line 81) +* g <1>: Using column view. (line 23) +* g: Agenda commands. (line 154) +* G: Agenda commands. (line 143) +* H: Agenda commands. (line 459) +* i: Agenda commands. (line 427) +* I: Agenda commands. (line 370) +* J: Agenda commands. (line 96) +* j: Agenda commands. (line 93) +* J: Agenda commands. (line 380) +* k: Agenda commands. (line 338) +* k a: Inserting deadline/schedule. + (line 25) +* k s: Inserting deadline/schedule. + (line 25) +* l: Agenda commands. (line 103) +* L: Agenda commands. (line 31) +* m: Agenda commands. (line 388) +* M: Agenda commands. (line 446) +* M-<down> <1>: Built-in table editor. + (line 90) +* M-<down>: Editing and debugging formulas. + (line 76) +* M-<left> <1>: Plain lists. (line 110) +* M-<left> <2>: Built-in table editor. + (line 82) +* M-<left>: Structure editing. (line 38) +* M-<RET> <1>: Built-in table editor. + (line 141) +* M-<RET> <2>: Plain lists. (line 74) +* M-<RET> <3>: Structure editing. (line 6) +* M-<RET>: Relative timer. (line 17) +* M-<right> <1>: Built-in table editor. + (line 82) +* M-<right> <2>: Structure editing. (line 41) +* M-<right>: Plain lists. (line 110) +* M-<TAB> <1>: Per-file keywords. (line 24) +* M-<TAB> <2>: Property syntax. (line 45) +* M-<TAB> <3>: Completion. (line 16) +* M-<TAB> <4>: Setting tags. (line 6) +* M-<TAB>: Editing and debugging formulas. + (line 63) +* M-<up> <1>: Built-in table editor. + (line 90) +* M-<up>: Editing and debugging formulas. + (line 76) +* M-a: Built-in table editor. + (line 70) +* M-down: Key bindings and useful functions. + (line 13) +* M-e: Built-in table editor. + (line 74) +* M-S-<down> <1>: Structure editing. (line 53) +* M-S-<down> <2>: Built-in table editor. + (line 97) +* M-S-<down> <3>: Editing and debugging formulas. + (line 71) +* M-S-<down>: Plain lists. (line 104) +* M-S-<left> <1>: Built-in table editor. + (line 84) +* M-S-<left> <2>: The date/time prompt. + (line 76) +* M-S-<left> <3>: Structure editing. (line 44) +* M-S-<left>: Plain lists. (line 115) +* M-S-<RET> <1>: Structure editing. (line 23) +* M-S-<RET> <2>: Checkboxes. (line 72) +* M-S-<RET>: Plain lists. (line 88) +* M-S-<right> <1>: The date/time prompt. + (line 76) +* M-S-<right> <2>: Structure editing. (line 47) +* M-S-<right> <3>: Built-in table editor. + (line 87) +* M-S-<right>: Plain lists. (line 115) +* M-S-<up> <1>: Editing and debugging formulas. + (line 71) +* M-S-<up> <2>: Built-in table editor. + (line 94) +* M-S-<up> <3>: Plain lists. (line 104) +* M-S-<up>: Structure editing. (line 50) +* M-v: The date/time prompt. + (line 76) +* M-x org-iswitchb: Agenda files. (line 26) +* mouse-1 <1>: Footnotes. (line 91) +* mouse-1 <2>: Handling links. (line 122) +* mouse-1: The date/time prompt. + (line 76) +* mouse-2 <1>: Agenda commands. (line 34) +* mouse-2 <2>: Footnotes. (line 91) +* mouse-2: Handling links. (line 122) +* mouse-3 <1>: Handling links. (line 127) +* mouse-3: Agenda commands. (line 28) +* n <1>: Using column view. (line 42) +* n: Agenda commands. (line 19) +* o: Agenda commands. (line 64) +* O: Agenda commands. (line 374) +* p <1>: Using column view. (line 42) +* p: Agenda commands. (line 20) +* P: Agenda commands. (line 312) +* q <1>: Using column view. (line 26) +* q: Agenda commands. (line 485) +* r <1>: Agenda commands. (line 147) +* r <2>: Global TODO list. (line 23) +* r: Using column view. (line 19) +* R: Agenda commands. (line 125) +* S: Agenda commands. (line 450) +* s: Agenda commands. (line 157) +* S-<down> <1>: Priorities. (line 29) +* S-<down> <2>: Agenda commands. (line 320) +* S-<down> <3>: Creating timestamps. (line 44) +* S-<down> <4>: Plain lists. (line 97) +* S-<down> <5>: Editing and debugging formulas. + (line 66) +* S-<down>: The date/time prompt. + (line 76) +* S-<left> <1>: Creating timestamps. (line 39) +* S-<left> <2>: Plain lists. (line 151) +* S-<left> <3>: The date/time prompt. + (line 76) +* S-<left> <4>: Using column view. (line 35) +* S-<left> <5>: The clock table. (line 23) +* S-<left> <6>: TODO basics. (line 28) +* S-<left> <7>: Editing and debugging formulas. + (line 66) +* S-<left> <8>: Multiple sets in one file. + (line 32) +* S-<left> <9>: Agenda commands. (line 361) +* S-<left>: Property syntax. (line 65) +* S-<RET>: Built-in table editor. + (line 159) +* S-<right> <1>: Using column view. (line 35) +* S-<right> <2>: Multiple sets in one file. + (line 32) +* S-<right> <3>: Creating timestamps. (line 39) +* S-<right> <4>: TODO basics. (line 28) +* S-<right> <5>: The date/time prompt. + (line 76) +* S-<right> <6>: Plain lists. (line 151) +* S-<right> <7>: Editing and debugging formulas. + (line 66) +* S-<right> <8>: Agenda commands. (line 350) +* S-<right> <9>: The clock table. (line 23) +* S-<right>: Property syntax. (line 65) +* S-<TAB> <1>: Built-in table editor. + (line 62) +* S-<TAB>: Visibility cycling. (line 22) +* S-<up> <1>: Priorities. (line 29) +* S-<up> <2>: Creating timestamps. (line 44) +* S-<up> <3>: The date/time prompt. + (line 76) +* S-<up> <4>: Editing and debugging formulas. + (line 66) +* S-<up>: Agenda commands. (line 315) +* S-M-<left>: Using column view. (line 75) +* S-M-<RET>: TODO basics. (line 52) +* S-M-<right>: Using column view. (line 72) +* t: Agenda commands. (line 263) +* T: Agenda commands. (line 298) +* U: Agenda commands. (line 393) +* u: Agenda commands. (line 390) +* v: Using column view. (line 55) +* v [: Agenda commands. (line 114) +* v a: Agenda commands. (line 118) +* v A: Agenda commands. (line 121) +* v d: Agenda commands. (line 65) +* v E: Agenda commands. (line 135) +* v L: Agenda commands. (line 106) +* v l: Agenda commands. (line 103) +* v m: Agenda commands. (line 69) +* v R: Agenda commands. (line 125) +* v w: Agenda commands. (line 68) +* v y: Agenda commands. (line 70) +* w: Agenda commands. (line 68) +* x: Agenda commands. (line 486) +* X: Agenda commands. (line 377) +* z: Agenda commands. (line 323) +* {: Agenda commands. (line 245) +* }: Agenda commands. (line 245) + + +File: org, Node: Command and Function Index, Next: Variable Index, Prev: Key Index, Up: Top + +Command and function index +************************** + + +* Menu: + +* <1>: Agenda commands. (line 238) +* <2>: Tag searches. (line 9) +* : Property searches. (line 9) +* lisp-complete-symbol: Editing and debugging formulas. + (line 63) +* org-aganda-day-view: Agenda commands. (line 65) +* org-agenda-action: Agenda commands. (line 338) +* org-agenda-add-note: Agenda commands. (line 323) +* org-agenda-archive: Agenda commands. (line 293) +* org-agenda-archive-default-with-confirmation: Agenda commands. + (line 281) +* org-agenda-archive-to-archive-sibling: Agenda commands. (line 289) +* org-agenda-archives-mode: Agenda commands. (line 118) +* org-agenda-archives-mode 'files: Agenda commands. (line 121) +* org-agenda-bulk-action: Agenda commands. (line 396) +* org-agenda-bulk-mark: Agenda commands. (line 388) +* org-agenda-bulk-remove-all-marks: Agenda commands. (line 393) +* org-agenda-bulk-unmark: Agenda commands. (line 390) +* org-agenda-clock-cancel: Agenda commands. (line 377) +* org-agenda-clock-goto: Agenda commands. (line 96) +* org-agenda-clock-in: Agenda commands. (line 370) +* org-agenda-clock-out: Agenda commands. (line 374) +* org-agenda-clockreport-mode: Agenda commands. (line 125) +* org-agenda-columns <1>: Agenda commands. (line 161) +* org-agenda-columns: Agenda column view. (line 11) +* org-agenda-convert-date: Agenda commands. (line 455) +* org-agenda-date-prompt: Agenda commands. (line 365) +* org-agenda-deadline: Agenda commands. (line 335) +* org-agenda-diary-entry: Agenda commands. (line 427) +* org-agenda-do-date-earlier: Agenda commands. (line 361) +* org-agenda-do-date-later: Agenda commands. (line 350) +* org-agenda-earlier: Agenda commands. (line 87) +* org-agenda-entry-text-mode: Agenda commands. (line 135) +* org-agenda-exit: Agenda commands. (line 486) +* org-agenda-filter-by-tag: Agenda commands. (line 179) +* org-agenda-follow-mode: Agenda commands. (line 40) +* org-agenda-goto: Agenda commands. (line 34) +* org-agenda-goto-calendar: Agenda commands. (line 422) +* org-agenda-goto-date: Agenda commands. (line 93) +* org-agenda-goto-today: Agenda commands. (line 90) +* org-agenda-holidays: Agenda commands. (line 459) +* org-agenda-kill: Agenda commands. (line 272) +* org-agenda-later: Agenda commands. (line 81) +* org-agenda-list: Weekly/daily agenda. (line 9) +* org-agenda-list-stuck-projects: Stuck projects. (line 13) +* org-agenda-log-mode: Agenda commands. (line 103) +* org-agenda-manipulate-query-add: Agenda commands. (line 114) +* org-agenda-month-view: Agenda commands. (line 69) +* org-agenda-month-year: Agenda commands. (line 70) +* org-agenda-next-line: Agenda commands. (line 19) +* org-agenda-open-link: Agenda commands. (line 56) +* org-agenda-phases-of-moon: Agenda commands. (line 446) +* org-agenda-previous-line: Agenda commands. (line 20) +* org-agenda-priority-down: Agenda commands. (line 320) +* org-agenda-priority-up: Agenda commands. (line 315) +* org-agenda-quit: Agenda commands. (line 485) +* org-agenda-recenter: Agenda commands. (line 31) +* org-agenda-refile: Agenda commands. (line 278) +* org-agenda-remove-restriction-lock <1>: Agenda files. (line 60) +* org-agenda-remove-restriction-lock: Agenda commands. (line 172) +* org-agenda-rodo: Agenda commands. (line 154) +* org-agenda-schedule: Agenda commands. (line 331) +* org-agenda-set-restriction-lock: Agenda files. (line 42) +* org-agenda-set-tags: Agenda commands. (line 303) +* org-agenda-show-and-scroll-up: Agenda commands. (line 28) +* org-agenda-show-priority: Agenda commands. (line 312) +* org-agenda-show-tags: Agenda commands. (line 298) +* org-agenda-sunrise-sunset: Agenda commands. (line 450) +* org-agenda-switch-to: Agenda commands. (line 37) +* org-agenda-to-front: Agenda files. (line 15) +* org-agenda-todo: Agenda commands. (line 263) +* org-agenda-todo-nextset: Agenda commands. (line 267) +* org-agenda-todo-previousset: Agenda commands. (line 270) +* org-agenda-toggle-archive-tag: Agenda commands. (line 286) +* org-agenda-toggle-diary: Agenda commands. (line 99) +* org-agenda-toggle-time-grid: Agenda commands. (line 143) +* org-agenda-tree-to-indirect-buffer: Agenda commands. (line 47) +* org-agenda-undo: Agenda commands. (line 259) +* org-archive-subtree: Moving subtrees. (line 9) +* org-archive-subtree-default: Archiving. (line 11) +* org-archive-to-archive-sibling: Internal archiving. (line 49) +* org-attach <1>: Attachments. (line 26) +* org-attach: Agenda commands. (line 328) +* org-attach-attach: Attachments. (line 31) +* org-attach-delete-all: Attachments. (line 66) +* org-attach-delete-one: Attachments. (line 63) +* org-attach-new: Attachments. (line 41) +* org-attach-open: Attachments. (line 48) +* org-attach-open-in-emacs: Attachments. (line 54) +* org-attach-reveal: Attachments. (line 57) +* org-attach-reveal-in-emacs: Attachments. (line 60) +* org-attach-set-directory: Attachments. (line 70) +* org-attach-set-inherit: Attachments. (line 75) +* org-attach-sync: Attachments. (line 44) +* org-backward-same-level: Motion. (line 15) +* org-beamer-select-environment: Beamer class export. (line 83) +* org-buffer-property-keys: Using the property API. + (line 35) +* org-calendar-goto-agenda: Agenda commands. (line 423) +* org-capture: Using capture. (line 6) +* org-capture-finalize: Using capture. (line 15) +* org-capture-kill: Using capture. (line 31) +* org-capture-refile: Using capture. (line 22) +* org-check-after-date: Inserting deadline/schedule. + (line 38) +* org-check-before-date: Inserting deadline/schedule. + (line 35) +* org-check-deadlines: Inserting deadline/schedule. + (line 28) +* org-clock-cancel: Clocking commands. (line 50) +* org-clock-display: Clocking commands. (line 59) +* org-clock-goto: Clocking commands. (line 54) +* org-clock-in: Clocking commands. (line 6) +* org-clock-modify-effort-estimate <1>: Effort estimates. (line 17) +* org-clock-modify-effort-estimate: Clocking commands. (line 38) +* org-clock-out: Clocking commands. (line 30) +* org-clock-report: The clock table. (line 10) +* org-clocktable-try-shift: The clock table. (line 23) +* org-clone-subtree-with-time-shift: Structure editing. (line 82) +* org-columns: Using column view. (line 9) +* org-columns-delete: Using column view. (line 75) +* org-columns-edit-allowed: Using column view. (line 59) +* org-columns-edit-value: Using column view. (line 46) +* org-columns-narrow: Using column view. (line 70) +* org-columns-new: Using column view. (line 72) +* org-columns-next-allowed-value: Using column view. (line 42) +* org-columns-previous-allowed-value: Using column view. (line 42) +* org-columns-quit: Using column view. (line 26) +* org-columns-redo: Using column view. (line 19) +* org-columns-set-tags-or-toggle: Using column view. (line 52) +* org-columns-show-value: Using column view. (line 55) +* org-columns-widen: Using column view. (line 70) +* org-complete: Property syntax. (line 45) +* org-compute-property-at-point: Property syntax. (line 75) +* org-copy-subtree: Structure editing. (line 60) +* org-cut-subtree: Structure editing. (line 56) +* org-cycle <1>: Visibility cycling. (line 10) +* org-cycle <2>: Structure editing. (line 32) +* org-cycle: Plain lists. (line 91) +* org-cycle-agenda-files: Agenda files. (line 22) +* org-date-from-calendar: Creating timestamps. (line 26) +* org-dblock-update <1>: The clock table. (line 15) +* org-dblock-update <2>: Dynamic blocks. (line 21) +* org-dblock-update: Capturing column view. + (line 51) +* org-deadline: Inserting deadline/schedule. + (line 9) +* org-delete-property: Property syntax. (line 69) +* org-delete-property-globally: Property syntax. (line 72) +* org-demote: Using the mapping API. + (line 82) +* org-demote-subtree: Structure editing. (line 47) +* org-do-demote: Structure editing. (line 41) +* org-do-promote: Structure editing. (line 38) +* org-edit-special: Cooperation. (line 61) +* org-entry-add-to-multivalued-property: Using the property API. + (line 51) +* org-entry-delete: Using the property API. + (line 29) +* org-entry-get: Using the property API. + (line 20) +* org-entry-get-multivalued-property: Using the property API. + (line 47) +* org-entry-member-in-multivalued-property: Using the property API. + (line 61) +* org-entry-properties: Using the property API. + (line 10) +* org-entry-put: Using the property API. + (line 32) +* org-entry-put-multivalued-property: Using the property API. + (line 42) +* org-entry-remove-from-multivalued-property: Using the property API. + (line 56) +* org-evaluate-time-range <1>: Creating timestamps. (line 56) +* org-evaluate-time-range: Clocking commands. (line 41) +* org-export: The export dispatcher. + (line 21) +* org-export-as-ascii: ASCII/Latin-1/UTF-8 export. + (line 11) +* org-export-as-ascii-to-buffer: ASCII/Latin-1/UTF-8 export. + (line 18) +* org-export-as-docbook: DocBook export commands. + (line 6) +* org-export-as-docbook-pdf-and-open: DocBook export commands. + (line 13) +* org-export-as-freemind: Freemind export. (line 8) +* org-export-as-html: HTML Export commands. + (line 6) +* org-export-as-html-and-open: HTML Export commands. + (line 13) +* org-export-as-html-to-buffer: HTML Export commands. + (line 16) +* org-export-as-latex: LaTeX/PDF export commands. + (line 6) +* org-export-as-latex-to-buffer: LaTeX/PDF export commands. + (line 13) +* org-export-as-latin1: ASCII/Latin-1/UTF-8 export. + (line 21) +* org-export-as-latin1-to-buffer: ASCII/Latin-1/UTF-8 export. + (line 24) +* org-export-as-pdf: LaTeX/PDF export commands. + (line 28) +* org-export-as-pdf-and-open: LaTeX/PDF export commands. + (line 31) +* org-export-as-taskjuggler: TaskJuggler export. (line 24) +* org-export-as-taskjuggler-and-open: TaskJuggler export. (line 27) +* org-export-as-utf8: ASCII/Latin-1/UTF-8 export. + (line 25) +* org-export-as-utf8-to-buffer: ASCII/Latin-1/UTF-8 export. + (line 28) +* org-export-as-xoxo: XOXO export. (line 10) +* org-export-icalendar-all-agenda-files: iCalendar export. (line 34) +* org-export-icalendar-combine-agenda-files: iCalendar export. + (line 39) +* org-export-icalendar-this-file: iCalendar export. (line 32) +* org-export-region-as-html: HTML Export commands. + (line 19) +* org-export-visible: The export dispatcher. + (line 17) +* org-feed-goto-inbox: RSS Feeds. (line 27) +* org-feed-update-all: RSS Feeds. (line 23) +* org-force-cycle-archived: Internal archiving. (line 46) +* org-forward-same-level: Motion. (line 12) +* org-global-cycle: Visibility cycling. (line 22) +* org-goto: Motion. (line 21) +* org-goto-calendar: Creating timestamps. (line 30) +* org-insert-columns-dblock: Capturing column view. + (line 49) +* org-insert-export-options-template: Export options. (line 16) +* org-insert-heading <1>: Structure editing. (line 6) +* org-insert-heading <2>: Relative timer. (line 17) +* org-insert-heading: Plain lists. (line 74) +* org-insert-heading-respect-content: Structure editing. (line 18) +* org-insert-link: Handling links. (line 65) +* org-insert-property-drawer <1>: Property syntax. (line 55) +* org-insert-property-drawer: Using the property API. + (line 38) +* org-insert-todo-heading <1>: Structure editing. (line 23) +* org-insert-todo-heading <2>: Checkboxes. (line 72) +* org-insert-todo-heading: TODO basics. (line 52) +* org-insert-todo-heading-respect-content: Structure editing. (line 27) +* org-map-entries: Using the mapping API. + (line 13) +* org-mark-entry-for-agenda-action: Inserting deadline/schedule. + (line 22) +* org-mark-ring-goto: Handling links. (line 144) +* org-mark-ring-push: Handling links. (line 140) +* org-move-subtree-down: Structure editing. (line 53) +* org-move-subtree-up: Structure editing. (line 50) +* org-narrow-to-subtree: Structure editing. (line 107) +* org-next-link: Handling links. (line 150) +* org-occur: Sparse trees. (line 17) +* org-open-at-point <1>: Handling links. (line 101) +* org-open-at-point: Creating timestamps. (line 35) +* org-paste-subtree: Structure editing. (line 64) +* org-previous-link: Handling links. (line 150) +* org-priority <1>: Using the mapping API. + (line 70) +* org-priority: Priorities. (line 24) +* org-priority-down: Priorities. (line 29) +* org-priority-up: Priorities. (line 29) +* org-promote: Using the mapping API. + (line 79) +* org-promote-subtree: Structure editing. (line 44) +* org-property-action: Property syntax. (line 57) +* org-property-next-allowed-value: Property syntax. (line 65) +* org-property-previous-allowed-value: Property syntax. (line 65) +* org-publish: Triggering publication. + (line 8) +* org-publish-all: Triggering publication. + (line 16) +* org-publish-current-file: Triggering publication. + (line 13) +* org-publish-current-project: Triggering publication. + (line 10) +* org-refile <1>: Structure editing. (line 90) +* org-refile: Refiling notes. (line 11) +* org-refile-cache-clear: Refiling notes. (line 40) +* org-refile-goto-last-stored: Refiling notes. (line 31) +* org-remove-file: Agenda files. (line 19) +* org-reveal: Visibility cycling. (line 34) +* org-save-all-org-buffers: Agenda commands. (line 157) +* org-schedule: Inserting deadline/schedule. + (line 14) +* org-search-view: Search view. (line 9) +* org-set-effort: Effort estimates. (line 14) +* org-set-property: Property syntax. (line 61) +* org-set-startup-visibility: Visibility cycling. (line 68) +* org-set-tags-command: Setting tags. (line 18) +* org-show-todo-key: TODO basics. (line 33) +* org-sort-entries-or-items: Structure editing. (line 94) +* org-sparse-tree: Sparse trees. (line 15) +* org-speedbar-set-agenda-restriction: Agenda files. (line 56) +* org-store-agenda-views: Exporting Agenda Views. + (line 65) +* org-store-link: Handling links. (line 9) +* org-table-align: Built-in table editor. + (line 57) +* org-table-beginning-of-field: Built-in table editor. + (line 70) +* org-table-copy-down: Built-in table editor. + (line 159) +* org-table-copy-region: Built-in table editor. + (line 126) +* org-table-create-or-convert-from-region: Built-in table editor. + (line 187) +* org-table-create-with-table.el: Cooperation. (line 63) +* org-table-cut-region: Built-in table editor. + (line 130) +* org-table-delete-column: Built-in table editor. + (line 84) +* org-table-edit-field: Built-in table editor. + (line 174) +* org-table-edit-formulas: Editing and debugging formulas. + (line 36) +* org-table-end-of-field: Built-in table editor. + (line 74) +* org-table-eval-formula <1>: Editing and debugging formulas. + (line 13) +* org-table-eval-formula <2>: Field formulas. (line 26) +* org-table-eval-formula: Column formulas. (line 27) +* org-table-export: Built-in table editor. + (line 195) +* org-table-fedit-abort: Editing and debugging formulas. + (line 49) +* org-table-fedit-finish: Editing and debugging formulas. + (line 46) +* org-table-fedit-line-down: Editing and debugging formulas. + (line 71) +* org-table-fedit-line-up: Editing and debugging formulas. + (line 71) +* org-table-fedit-lisp-indent: Editing and debugging formulas. + (line 56) +* org-table-fedit-ref-down: Editing and debugging formulas. + (line 66) +* org-table-fedit-ref-left: Editing and debugging formulas. + (line 66) +* org-table-fedit-ref-right: Editing and debugging formulas. + (line 66) +* org-table-fedit-ref-up: Editing and debugging formulas. + (line 66) +* org-table-fedit-scroll-down: Editing and debugging formulas. + (line 76) +* org-table-fedit-scroll-up: Editing and debugging formulas. + (line 76) +* org-table-fedit-toggle-ref-type: Editing and debugging formulas. + (line 52) +* org-table-field-info: Editing and debugging formulas. + (line 22) +* org-table-hline-and-move: Built-in table editor. + (line 105) +* org-table-insert-column: Built-in table editor. + (line 87) +* org-table-insert-hline: Built-in table editor. + (line 101) +* org-table-insert-row: Built-in table editor. + (line 97) +* org-table-iterate: Updating the table. (line 22) +* org-table-iterate-buffer-tables: Updating the table. (line 33) +* org-table-kill-row: Built-in table editor. + (line 94) +* org-table-move-column-left: Built-in table editor. + (line 82) +* org-table-move-column-right: Built-in table editor. + (line 82) +* org-table-move-row-down: Built-in table editor. + (line 90) +* org-table-move-row-up: Built-in table editor. + (line 90) +* org-table-next-field: Built-in table editor. + (line 58) +* org-table-next-row: Built-in table editor. + (line 65) +* org-table-paste-rectangle: Built-in table editor. + (line 134) +* org-table-previous-field: Built-in table editor. + (line 62) +* org-table-recalculate: Updating the table. (line 13) +* org-table-recalculate-buffer-tables: Updating the table. (line 30) +* org-table-rotate-recalc-marks: Advanced features. (line 9) +* org-table-sort-lines: Built-in table editor. + (line 109) +* org-table-sum: Built-in table editor. + (line 156) +* org-table-toggle-coordinate-overlays: Editing and debugging formulas. + (line 80) +* org-table-toggle-formula-debugger: Editing and debugging formulas. + (line 32) +* org-table-wrap-region: Built-in table editor. + (line 141) +* org-tags-view <1>: Matching tags and properties. + (line 17) +* org-tags-view <2>: Tag searches. (line 16) +* org-tags-view: Property searches. (line 15) +* org-time-stamp: Creating timestamps. (line 10) +* org-time-stamp-inactive: Creating timestamps. (line 15) +* org-timeline: Timeline. (line 10) +* org-timer: Relative timer. (line 10) +* org-timer-item: Relative timer. (line 13) +* org-timer-start: Relative timer. (line 30) +* org-timestamp-down-day: Creating timestamps. (line 39) +* org-timestamp-down-down: Creating timestamps. (line 44) +* org-timestamp-up: Creating timestamps. (line 44) +* org-timestamp-up-day: Creating timestamps. (line 39) +* org-todo <1>: Clocking commands. (line 46) +* org-todo <2>: TODO basics. (line 13) +* org-todo: Using the mapping API. + (line 66) +* org-todo-list <1>: Global TODO list. (line 9) +* org-todo-list: TODO basics. (line 44) +* org-toggle-archive-tag: Internal archiving. (line 36) +* org-toggle-checkbox: Checkboxes. (line 55) +* org-toggle-heading: Structure editing. (line 113) +* org-toggle-inline-images: Handling links. (line 131) +* org-toggle-ordered-property <1>: Checkboxes. (line 75) +* org-toggle-ordered-property: TODO dependencies. (line 29) +* org-toggle-tag: Using the mapping API. + (line 74) +* org-toggle-time-stamp-overlays: Custom time format. (line 12) +* org-tree-to-indirect-buffer: Visibility cycling. (line 47) +* org-update-all-dblocks: Capturing column view. + (line 55) +* org-update-statistics-cookies: Checkboxes. (line 83) +* org-write-agenda <1>: Agenda commands. (line 472) +* org-write-agenda: Exporting Agenda Views. + (line 12) +* org-yank: Structure editing. (line 70) +* outline-next-visible-heading: Motion. (line 8) +* outline-previous-visible-heading: Motion. (line 9) +* outline-up-heading: Motion. (line 18) +* show-all: Visibility cycling. (line 33) +* show-branches: Visibility cycling. (line 43) +* widen: Structure editing. (line 110) + + +File: org, Node: Variable Index, Prev: Command and Function Index, Up: Top + +Variable index +************** + +This is not a complete index of variables and faces, only the ones that +are mentioned in the manual. For a more complete list, use `M-x +org-customize <RET>' and then click yourself through the tree. + + +* Menu: + +* cdlatex-simplify-sub-super-scripts: CDLaTeX mode. (line 32) +* constants-unit-system <1>: In-buffer settings. (line 139) +* constants-unit-system: References. (line 106) +* htmlize-output-type: Exporting Agenda Views. + (line 21) +* LaTeX-verbatim-environments: A LaTeX example. (line 21) +* org-adapt-indentation: Clean view. (line 46) +* org-agenda-add-entry-text-maxlines: Exporting Agenda Views. + (line 21) +* org-agenda-columns-add-appointments-to-effort-sum: Effort estimates. + (line 41) +* org-agenda-confirm-kill: Agenda commands. (line 275) +* org-agenda-custom-commands <1>: Sparse trees. (line 31) +* org-agenda-custom-commands <2>: Extracting agenda information. + (line 6) +* org-agenda-custom-commands <3>: Setting Options. (line 6) +* org-agenda-custom-commands: Storing searches. (line 9) +* org-agenda-diary-file: Agenda commands. (line 430) +* org-agenda-dim-blocked-tasks: TODO dependencies. (line 39) +* org-agenda-entry-text-maxlines: Agenda commands. (line 138) +* org-agenda-exporter-settings <1>: Agenda commands. (line 473) +* org-agenda-exporter-settings: Exporting Agenda Views. + (line 13) +* org-agenda-files <1>: iCalendar export. (line 37) +* org-agenda-files <2>: Sorting of agenda items. + (line 8) +* org-agenda-files: Agenda files. (line 6) +* org-agenda-filter-preset: Agenda commands. (line 180) +* org-agenda-log-mode-items: Agenda commands. (line 106) +* org-agenda-ndays: Weekly/daily agenda. (line 15) +* org-agenda-overriding-header: Special agenda views. + (line 40) +* org-agenda-prefix-format: Presentation and sorting. + (line 6) +* org-agenda-restore-windows-after-quit: Agenda Views. (line 40) +* org-agenda-show-inherited-tags: Agenda commands. (line 301) +* org-agenda-skip-archived-trees: Internal archiving. (line 21) +* org-agenda-skip-function <1>: Using the mapping API. + (line 51) +* org-agenda-skip-function: Special agenda views. + (line 43) +* org-agenda-skip-scheduled-if-done: Deadlines and scheduling. + (line 30) +* org-agenda-sorting-strategy: Sorting of agenda items. + (line 27) +* org-agenda-span: Weekly/daily agenda. (line 15) +* org-agenda-start-with-clockreport-mode: Agenda commands. (line 128) +* org-agenda-start-with-entry-text-mode: Agenda commands. (line 138) +* org-agenda-start-with-follow-mode: Agenda commands. (line 43) +* org-agenda-tags-todo-honor-ignore-options: Matching tags and properties. + (line 20) +* org-agenda-text-search-extra-files <1>: Agenda dispatcher. (line 31) +* org-agenda-text-search-extra-files: Search view. (line 24) +* org-agenda-time-grid <1>: Agenda commands. (line 146) +* org-agenda-time-grid: Time-of-day specifications. + (line 41) +* org-agenda-todo-ignore-deadlines: Global TODO list. (line 38) +* org-agenda-todo-ignore-scheduled: Global TODO list. (line 38) +* org-agenda-todo-ignore-timestamp: Global TODO list. (line 38) +* org-agenda-todo-ignore-with-date: Global TODO list. (line 38) +* org-agenda-todo-list-sublevels <1>: Global TODO list. (line 47) +* org-agenda-todo-list-sublevels: Breaking down tasks. (line 6) +* org-agenda-use-time-grid <1>: Time-of-day specifications. + (line 41) +* org-agenda-use-time-grid: Agenda commands. (line 146) +* org-agenda-window-setup: Agenda Views. (line 40) +* org-archive-default-command <1>: Agenda commands. (line 284) +* org-archive-default-command: Archiving. (line 12) +* org-archive-location <1>: In-buffer settings. (line 16) +* org-archive-location: Moving subtrees. (line 10) +* org-archive-save-context-info: Moving subtrees. (line 33) +* org-attach-directory: Attachments. (line 6) +* org-attach-method: Attachments. (line 32) +* org-babel-default-header-args <1>: System-wide header arguments. + (line 6) +* org-babel-default-header-args: Header arguments in Org-mode properties. + (line 23) +* org-calc-default-modes: Formula syntax for Calc. + (line 14) +* org-clock-idle-time: Resolving idle time. (line 11) +* org-clock-into-drawer: Clocking commands. (line 7) +* org-clock-modeline-total: Clocking commands. (line 16) +* org-clocktable-defaults: The clock table. (line 37) +* org-coderef-label-format: Literal examples. (line 57) +* org-columns-default-format <1>: Agenda commands. (line 164) +* org-columns-default-format <2>: Agenda column view. (line 18) +* org-columns-default-format <3>: Effort estimates. (line 31) +* org-columns-default-format: Using column view. (line 10) +* org-columns-skip-archived-trees: Internal archiving. (line 31) +* org-combined-agenda-icalendar-file: iCalendar export. (line 42) +* org-confirm-babel-evaluate: Code evaluation security. + (line 34) +* org-confirm-elisp-link-function: Code evaluation security. + (line 45) +* org-confirm-shell-link-function: Code evaluation security. + (line 42) +* org-create-file-search-functions: Custom searches. (line 12) +* org-ctrl-c-ctrl-c-hook: Context-sensitive commands. + (line 6) +* org-ctrl-k-protect-subtree: Headlines. (line 6) +* org-cycle-emulate-tab: Visibility cycling. (line 16) +* org-cycle-global-at-bob: Visibility cycling. (line 16) +* org-cycle-include-plain-lists: Plain lists. (line 67) +* org-cycle-open-archived-trees: Internal archiving. (line 11) +* org-cycle-separator-lines: Headlines. (line 22) +* org-deadline-warning-days <1>: Deadlines and scheduling. + (line 12) +* org-deadline-warning-days: Inserting deadline/schedule. + (line 31) +* org-default-notes-file <1>: Setting up capture. (line 9) +* org-default-notes-file: Template elements. (line 48) +* org-default-priority <1>: In-buffer settings. (line 54) +* org-default-priority: Priorities. (line 38) +* org-display-custom-times <1>: Custom time format. (line 6) +* org-display-custom-times: Publishing options. (line 12) +* org-display-internal-link-with-indirect-buffer: Handling links. + (line 130) +* org-disputed-keys: Conflicts. (line 34) +* org-done (face): Faces for TODO keywords. + (line 6) +* org-drawers <1>: In-buffer settings. (line 45) +* org-drawers: Drawers. (line 6) +* org-effort-property: Effort estimates. (line 6) +* org-empty-line-terminates-plain-lists: Plain lists. (line 29) +* org-enable-table-editor: Built-in table editor. + (line 30) +* org-enforce-todo-dependencies: TODO dependencies. (line 6) +* org-entities <1>: Special characters. (line 6) +* org-entities: Special symbols. (line 15) +* org-execute-file-search-functions: Custom searches. (line 12) +* org-export-ascii-links-to-notes: ASCII/Latin-1/UTF-8 export. + (line 50) +* org-export-author-info: Publishing options. (line 12) +* org-export-creator-info: Publishing options. (line 12) +* org-export-default-language <1>: Export options. (line 19) +* org-export-default-language: Publishing options. (line 12) +* org-export-docbook-default-image-attributes: Images in DocBook export. + (line 15) +* org-export-docbook-doctype: Special characters. (line 6) +* org-export-docbook-inline-image-extensions: Images in DocBook export. + (line 35) +* org-export-docbook-xsl-fo-proc-command: DocBook export commands. + (line 19) +* org-export-docbook-xslt-proc-command: DocBook export commands. + (line 19) +* org-export-docbook-xslt-stylesheet: DocBook export commands. + (line 25) +* org-export-email: Publishing options. (line 12) +* org-export-exclude-tags <1>: Publishing options. (line 12) +* org-export-exclude-tags: Selective export. (line 6) +* org-export-headline-levels <1>: Publishing options. (line 12) +* org-export-headline-levels: Headings and sections. + (line 6) +* org-export-highlight-first-table-line: Publishing options. (line 12) +* org-export-html-auto-postamble: Publishing options. (line 12) +* org-export-html-auto-preamble: Publishing options. (line 12) +* org-export-html-expand: Publishing options. (line 12) +* org-export-html-extension: Publishing options. (line 12) +* org-export-html-extra: CSS support. (line 37) +* org-export-html-inline-images <1>: Publishing options. (line 12) +* org-export-html-inline-images: Images in HTML export. + (line 6) +* org-export-html-link-home: Publishing options. (line 12) +* org-export-html-link-org-files-as-html: Publishing options. (line 12) +* org-export-html-link-up: Publishing options. (line 12) +* org-export-html-postamble: Publishing options. (line 12) +* org-export-html-preamble: Publishing options. (line 12) +* org-export-html-style <1>: CSS support. (line 37) +* org-export-html-style: Publishing options. (line 12) +* org-export-html-style-default: CSS support. (line 37) +* org-export-html-style-extra: Publishing options. (line 12) +* org-export-html-style-include-default <1>: Publishing options. + (line 12) +* org-export-html-style-include-default: CSS support. (line 37) +* org-export-html-table-tag <1>: Publishing options. (line 12) +* org-export-html-table-tag: Tables in HTML export. + (line 6) +* org-export-html-tag-class-prefix: CSS support. (line 6) +* org-export-html-todo-kwd-class-prefix: CSS support. (line 6) +* org-export-html-use-infojs: JavaScript support. (line 57) +* org-export-html-with-timestamp: Publishing options. (line 12) +* org-export-latex-classes: Header and sectioning. + (line 8) +* org-export-latex-default-class: Header and sectioning. + (line 8) +* org-export-latex-default-packages-alist: Header and sectioning. + (line 8) +* org-export-latex-packages-alist: Header and sectioning. + (line 8) +* org-export-preserve-breaks: Publishing options. (line 12) +* org-export-publishing-directory: Publishing options. (line 12) +* org-export-run-in-background: The export dispatcher. + (line 24) +* org-export-section-number-format: Publishing options. (line 12) +* org-export-select-tags <1>: Selective export. (line 6) +* org-export-select-tags: Publishing options. (line 12) +* org-export-skip-text-before-1st-heading <1>: Publishing options. + (line 12) +* org-export-skip-text-before-1st-heading: Initial text. (line 12) +* org-export-taskjuggler-default-reports: TaskJuggler export. (line 119) +* org-export-taskjuggler-project-tag: TaskJuggler export. (line 34) +* org-export-taskjuggler-resource-tag: TaskJuggler export. (line 48) +* org-export-with-archived-trees <1>: Internal archiving. (line 27) +* org-export-with-archived-trees: Publishing options. (line 12) +* org-export-with-drawers: Publishing options. (line 12) +* org-export-with-emphasize: Publishing options. (line 12) +* org-export-with-fixed-width: Publishing options. (line 12) +* org-export-with-footnotes: Publishing options. (line 12) +* org-export-with-LaTeX-fragments <1>: LaTeX fragments. (line 43) +* org-export-with-LaTeX-fragments: Publishing options. (line 12) +* org-export-with-priority: Publishing options. (line 12) +* org-export-with-section-numbers: Publishing options. (line 12) +* org-export-with-special-strings: Publishing options. (line 12) +* org-export-with-sub-superscripts <1>: Publishing options. (line 12) +* org-export-with-sub-superscripts: Subscripts and superscripts. + (line 15) +* org-export-with-tables: Publishing options. (line 12) +* org-export-with-tags: Publishing options. (line 12) +* org-export-with-TeX-macros: Publishing options. (line 12) +* org-export-with-timestamps: Publishing options. (line 12) +* org-export-with-toc <1>: Publishing options. (line 12) +* org-export-with-toc: Table of contents. (line 6) +* org-export-with-todo-keywords: Publishing options. (line 12) +* org-fast-tag-selection-include-todo: Fast access to TODO states. + (line 16) +* org-fast-tag-selection-single-key: Setting tags. (line 143) +* org-file-apps <1>: Attachments. (line 49) +* org-file-apps: Handling links. (line 104) +* org-footnote-auto-adjust <1>: In-buffer settings. (line 143) +* org-footnote-auto-adjust: Footnotes. (line 58) +* org-footnote-auto-label <1>: Footnotes. (line 44) +* org-footnote-auto-label: In-buffer settings. (line 143) +* org-footnote-define-inline <1>: Footnotes. (line 58) +* org-footnote-define-inline: In-buffer settings. (line 143) +* org-footnote-section: Footnotes. (line 58) +* org-format-latex-header: LaTeX fragments. (line 6) +* org-format-latex-options <1>: Previewing LaTeX fragments. + (line 20) +* org-format-latex-options: LaTeX fragments. (line 39) +* org-from-is-user-regexp: Template expansion. (line 39) +* org-global-properties <1>: Property syntax. (line 40) +* org-global-properties: Effort estimates. (line 31) +* org-goto-auto-isearch: Motion. (line 26) +* org-goto-interface: Motion. (line 37) +* org-hide (face): Clean view. (line 66) +* org-hide-block-startup: Blocks. (line 6) +* org-hide-leading-stars <1>: Clean view. (line 50) +* org-hide-leading-stars: In-buffer settings. (line 125) +* org-hierarchical-checkbox-statistics: Checkboxes. (line 30) +* org-hierarchical-todo-statistics: Breaking down tasks. (line 25) +* org-highest-priority <1>: In-buffer settings. (line 54) +* org-highest-priority: Priorities. (line 38) +* org-icalendar-alarm-time: iCalendar export. (line 6) +* org-icalendar-categories: iCalendar export. (line 6) +* org-icalendar-include-body: iCalendar export. (line 46) +* org-icalendar-include-todo: iCalendar export. (line 6) +* org-icalendar-store-UID: iCalendar export. (line 21) +* org-icalendar-use-deadline: iCalendar export. (line 6) +* org-icalendar-use-scheduled: iCalendar export. (line 6) +* org-imenu-depth: Cooperation. (line 38) +* org-infojs-options: JavaScript support. (line 57) +* org-insert-mode-line-in-empty-file: Activation. (line 29) +* org-irc-link-to-logs: Handling links. (line 45) +* org-keep-stored-link-after-insertion: Handling links. (line 66) +* org-latex-low-levels: LaTeX/PDF export commands. + (line 37) +* org-link-abbrev-alist <1>: In-buffer settings. (line 49) +* org-link-abbrev-alist: Link abbreviations. (line 12) +* org-link-to-org-use-id: Handling links. (line 21) +* org-list-automatic-rules <1>: Checkboxes. (line 6) +* org-list-automatic-rules: Plain lists. (line 77) +* org-list-demote-modify-bullet: Plain lists. (line 56) +* org-list-end-regexp: Plain lists. (line 29) +* org-list-ending-method: Plain lists. (line 29) +* org-log-done <1>: Tracking TODO state changes. + (line 26) +* org-log-done <2>: Agenda commands. (line 106) +* org-log-done: In-buffer settings. (line 105) +* org-log-into-drawer <1>: Agenda commands. (line 326) +* org-log-into-drawer: Tracking TODO state changes. + (line 6) +* org-log-note-clock-out <1>: Clocking commands. (line 33) +* org-log-note-clock-out: In-buffer settings. (line 105) +* org-log-refile: Refiling notes. (line 12) +* org-log-repeat <1>: Repeated tasks. (line 32) +* org-log-repeat: In-buffer settings. (line 105) +* org-log-states-order-reversed: Tracking TODO state changes. + (line 6) +* org-lowest-priority <1>: In-buffer settings. (line 54) +* org-lowest-priority: Priorities. (line 38) +* org-M-RET-may-split-line <1>: Plain lists. (line 77) +* org-M-RET-may-split-line: Structure editing. (line 7) +* org-odd-levels-only <1>: Matching tags and properties. + (line 59) +* org-odd-levels-only <2>: Clean view. (line 74) +* org-odd-levels-only <3>: In-buffer settings. (line 125) +* org-odd-levels-only: Special agenda views. + (line 43) +* org-outline-path-complete-in-steps: Refiling notes. (line 12) +* org-overriding-columns-format: Agenda column view. (line 18) +* org-plain-list-ordered-item-terminator: Plain lists. (line 135) +* org-popup-calendar-for-date-prompt: The date/time prompt. + (line 70) +* org-priority-faces: Priorities. (line 13) +* org-priority-start-cycle-with-default: Priorities. (line 33) +* org-property-allowed-value-functions: Using the property API. + (line 65) +* org-publish-project-alist <1>: Publishing options. (line 66) +* org-publish-project-alist: Project alist. (line 6) +* org-publish-use-timestamps-flag: Triggering publication. + (line 21) +* org-put-time-stamp-overlays: In-buffer settings. (line 135) +* org-read-date-display-live: The date/time prompt. + (line 84) +* org-read-date-prefer-future: The date/time prompt. + (line 6) +* org-refile-allow-creating-parent-nodes: Refiling notes. (line 12) +* org-refile-targets: Refiling notes. (line 12) +* org-refile-use-cache: Refiling notes. (line 12) +* org-refile-use-outline-path: Refiling notes. (line 12) +* org-remove-highlights-with-change <1>: Sparse trees. (line 20) +* org-remove-highlights-with-change: Clocking commands. (line 62) +* org-replace-disputed-keys: Conflicts. (line 19) +* org-return-follows-link: Handling links. (line 121) +* org-reverse-note-order: Refiling notes. (line 12) +* org-show-entry-below: Sparse trees. (line 6) +* org-show-following-heading: Sparse trees. (line 6) +* org-show-hierarchy-above: Sparse trees. (line 6) +* org-show-siblings: Sparse trees. (line 6) +* org-sort-agenda-noeffort-is-high: Agenda commands. (line 198) +* org-sparse-tree-open-archived-trees: Internal archiving. (line 17) +* org-special-ctrl-a/e: Headlines. (line 6) +* org-special-ctrl-k: Headlines. (line 6) +* org-speed-commands-user: Speed keys. (line 6) +* org-startup-align-all-tables <1>: In-buffer settings. (line 91) +* org-startup-align-all-tables: Column width and alignment. + (line 33) +* org-startup-folded <1>: Visibility cycling. (line 55) +* org-startup-folded: In-buffer settings. (line 80) +* org-startup-indented: In-buffer settings. (line 86) +* org-startup-with-inline-images <1>: In-buffer settings. (line 98) +* org-startup-with-inline-images: Handling links. (line 134) +* org-store-link-functions: Adding hyperlink types. + (line 65) +* org-stuck-projects: Stuck projects. (line 17) +* org-support-shift-select <1>: Plain lists. (line 101) +* org-support-shift-select <2>: Conflicts. (line 6) +* org-support-shift-select: Plain lists. (line 154) +* org-table-auto-blank-field: Built-in table editor. + (line 30) +* org-table-copy-increment: Built-in table editor. + (line 162) +* org-table-export-default-format: Built-in table editor. + (line 195) +* org-table-formula: In-buffer settings. (line 35) +* org-table-formula-constants <1>: References. (line 99) +* org-table-formula-constants <2>: Cooperation. (line 17) +* org-table-formula-constants: In-buffer settings. (line 35) +* org-table-use-standard-references: Editing and debugging formulas. + (line 6) +* org-tag-alist <1>: Setting tags. (line 23) +* org-tag-alist: In-buffer settings. (line 165) +* org-tag-faces: Tags. (line 10) +* org-tag-persistent-alist: Setting tags. (line 38) +* org-tags-column: Setting tags. (line 11) +* org-tags-exclude-from-inheritance: Tag inheritance. (line 22) +* org-tags-match-list-sublevels <1>: Matching tags and properties. + (line 20) +* org-tags-match-list-sublevels <2>: Tag inheritance. (line 26) +* org-tags-match-list-sublevels <3>: Tag searches. (line 19) +* org-tags-match-list-sublevels: Property searches. (line 18) +* org-time-stamp-custom-formats: Custom time format. (line 6) +* org-time-stamp-overlay-formats: In-buffer settings. (line 135) +* org-time-stamp-rounding-minutes: Creating timestamps. (line 23) +* org-todo (face): Faces for TODO keywords. + (line 6) +* org-todo-keyword-faces: Faces for TODO keywords. + (line 6) +* org-todo-keywords <1>: Global TODO list. (line 18) +* org-todo-keywords <2>: In-buffer settings. (line 182) +* org-todo-keywords <3>: TODO basics. (line 36) +* org-todo-keywords: TODO extensions. (line 6) +* org-todo-repeat-to-state: Repeated tasks. (line 17) +* org-todo-state-tags-triggers: TODO basics. (line 57) +* org-track-ordered-property-with-tag <1>: Checkboxes. (line 78) +* org-track-ordered-property-with-tag: TODO dependencies. (line 30) +* org-treat-insert-todo-heading-as-state-change: Structure editing. + (line 26) +* org-treat-S-cursor-todo-selection-as-state-change: TODO basics. + (line 29) +* org-use-property-inheritance <1>: Property inheritance. + (line 6) +* org-use-property-inheritance <2>: Using the property API. + (line 18) +* org-use-property-inheritance: iCalendar export. (line 46) +* org-use-speed-commands: Speed keys. (line 6) +* org-use-tag-inheritance: Tag inheritance. (line 22) +* org-yank-adjusted-subtrees: Structure editing. (line 73) +* org-yank-folded-subtrees: Structure editing. (line 73) +* parse-time-months: The date/time prompt. + (line 57) +* parse-time-weekdays: The date/time prompt. + (line 57) +* ps-landscape-mode: Exporting Agenda Views. + (line 21) +* ps-number-of-columns: Exporting Agenda Views. + (line 21) +* user-full-name <1>: Publishing options. (line 12) +* user-full-name: Export options. (line 19) +* user-mail-address <1>: Export options. (line 19) +* user-mail-address: Publishing options. (line 12) + + + +Tag Table: +Node: Top1274 +Node: Introduction21174 +Node: Summary21644 +Node: Installation24537 +Node: Activation26700 +Node: Feedback28438 +Ref: Feedback-Footnote-131016 +Node: Conventions31143 +Node: Document Structure32502 +Node: Outlines33426 +Node: Headlines34082 +Ref: Headlines-Footnote-135082 +Node: Visibility cycling35258 +Ref: Visibility cycling-Footnote-138300 +Ref: Visibility cycling-Footnote-238358 +Ref: Visibility cycling-Footnote-338408 +Node: Motion38678 +Node: Structure editing40015 +Ref: Structure editing-Footnote-146382 +Node: Sparse trees46482 +Ref: Sparse trees-Footnote-148787 +Ref: Sparse trees-Footnote-248993 +Ref: Sparse trees-Footnote-349064 +Node: Plain lists49179 +Ref: Plain lists-Footnote-156646 +Ref: Plain lists-Footnote-257004 +Ref: Plain lists-Footnote-357100 +Ref: Plain lists-Footnote-457189 +Ref: Plain lists-Footnote-557260 +Ref: Plain lists-Footnote-657318 +Ref: Plain lists-Footnote-757562 +Ref: Plain lists-Footnote-857738 +Ref: Plain lists-Footnote-957838 +Node: Drawers57916 +Ref: Drawers-Footnote-159132 +Node: Blocks59237 +Node: Footnotes59798 +Ref: Footnotes-Footnote-164371 +Ref: Footnotes-Footnote-264468 +Node: Orgstruct mode64545 +Node: Tables65654 +Node: Built-in table editor66295 +Node: Column width and alignment75458 +Ref: Column width and alignment-Footnote-178016 +Ref: Column width and alignment-Footnote-278062 +Node: Column groups78159 +Node: Orgtbl mode79671 +Node: The spreadsheet80470 +Node: References81770 +Ref: References-Footnote-187444 +Ref: References-Footnote-287585 +Ref: References-Footnote-387688 +Node: Formula syntax for Calc87978 +Ref: Formula syntax for Calc-Footnote-190891 +Node: Formula syntax for Lisp91215 +Node: Field formulas92938 +Node: Column formulas94401 +Node: Editing and debugging formulas96166 +Node: Updating the table100834 +Node: Advanced features102176 +Node: Org-Plot106613 +Node: Hyperlinks109474 +Node: Link format110231 +Node: Internal links111509 +Ref: Internal links-Footnote-1113322 +Ref: Internal links-Footnote-2113508 +Node: Radio targets113748 +Node: External links114438 +Node: Handling links117881 +Ref: Handling links-Footnote-1125671 +Ref: Handling links-Footnote-2125967 +Ref: Handling links-Footnote-3126213 +Ref: Handling links-Footnote-4126290 +Ref: Handling links-Footnote-5126364 +Node: Using links outside Org126446 +Node: Link abbreviations126931 +Node: Search options129229 +Ref: Search options-Footnote-1131110 +Node: Custom searches131191 +Node: TODO Items132201 +Ref: TODO Items-Footnote-1133309 +Node: TODO basics133423 +Node: TODO extensions136023 +Node: Workflow states137053 +Ref: Workflow states-Footnote-1138378 +Node: TODO types138471 +Ref: TODO types-Footnote-1140069 +Node: Multiple sets in one file140151 +Node: Fast access to TODO states142016 +Ref: Fast access to TODO states-Footnote-1142878 +Node: Per-file keywords143172 +Ref: Per-file keywords-Footnote-1144568 +Node: Faces for TODO keywords144769 +Node: TODO dependencies145813 +Node: Progress logging147986 +Node: Closing items148698 +Ref: Closing items-Footnote-1149747 +Ref: Closing items-Footnote-2149816 +Node: Tracking TODO state changes149889 +Ref: Tracking TODO state changes-Footnote-1152782 +Ref: Tracking TODO state changes-Footnote-2152839 +Node: Tracking your habits153127 +Node: Priorities157326 +Ref: Priorities-Footnote-1159331 +Node: Breaking down tasks159400 +Ref: Breaking down tasks-Footnote-1161392 +Node: Checkboxes161488 +Ref: Checkboxes-Footnote-1166006 +Ref: Checkboxes-Footnote-2166129 +Node: Tags166298 +Node: Tag inheritance167297 +Ref: Tag inheritance-Footnote-1168669 +Ref: Tag inheritance-Footnote-2168769 +Node: Setting tags168895 +Ref: Setting tags-Footnote-1175154 +Node: Tag searches175237 +Node: Properties and Columns176470 +Node: Property syntax177874 +Node: Special properties180862 +Node: Property searches182279 +Node: Property inheritance183711 +Node: Column view185527 +Node: Defining columns186761 +Node: Scope of column definitions187159 +Node: Column attributes188089 +Ref: Column attributes-Footnote-1192698 +Node: Using column view192831 +Node: Capturing column view195693 +Ref: Capturing column view-Footnote-1198685 +Node: Property API198821 +Node: Dates and Times199175 +Node: Timestamps200154 +Ref: Timestamps-Footnote-1202512 +Node: Creating timestamps202643 +Node: The date/time prompt205386 +Ref: The date/time prompt-Footnote-1209671 +Ref: The date/time prompt-Footnote-2209834 +Ref: The date/time prompt-Footnote-3209940 +Node: Custom time format210033 +Node: Deadlines and scheduling211757 +Ref: Deadlines and scheduling-Footnote-1214450 +Node: Inserting deadline/schedule214605 +Ref: Inserting deadline/schedule-Footnote-1216633 +Ref: Inserting deadline/schedule-Footnote-2216741 +Node: Repeated tasks216849 +Ref: Repeated tasks-Footnote-1220195 +Ref: Repeated tasks-Footnote-2220444 +Node: Clocking work time220643 +Ref: Clocking work time-Footnote-1221826 +Node: Clocking commands221964 +Ref: Clocking commands-Footnote-1225701 +Ref: Clocking commands-Footnote-2225808 +Ref: Clocking commands-Footnote-3225858 +Ref: Clocking commands-Footnote-4225916 +Node: The clock table225994 +Ref: The clock table-Footnote-1232157 +Node: Resolving idle time232282 +Ref: Resolving idle time-Footnote-1235536 +Node: Effort estimates235874 +Ref: Effort estimates-Footnote-1238643 +Ref: Effort estimates-Footnote-2238731 +Node: Relative timer238838 +Node: Countdown timer240685 +Node: Capture - Refile - Archive241176 +Node: Capture242157 +Node: Setting up capture243491 +Ref: Setting up capture-Footnote-1243916 +Node: Using capture243982 +Node: Capture templates246138 +Node: Template elements247766 +Node: Template expansion252767 +Ref: Template expansion-Footnote-1255818 +Ref: Template expansion-Footnote-2255905 +Ref: Template expansion-Footnote-3256087 +Node: Attachments256185 +Ref: Attachments-Footnote-1259567 +Node: RSS Feeds259717 +Node: Protocols261307 +Node: Refiling notes262021 +Ref: Refiling notes-Footnote-1264161 +Node: Archiving264257 +Node: Moving subtrees264956 +Ref: Moving subtrees-Footnote-1266667 +Node: Internal archiving267111 +Node: Agenda Views269741 +Node: Agenda files271932 +Ref: Agenda files-Footnote-1274745 +Ref: Agenda files-Footnote-2274894 +Node: Agenda dispatcher275087 +Ref: Agenda dispatcher-Footnote-1277302 +Ref: Agenda dispatcher-Footnote-2277396 +Node: Built-in agenda views277498 +Node: Weekly/daily agenda278147 +Ref: Weekly/daily agenda-Footnote-1283063 +Ref: Weekly/daily agenda-Footnote-2283290 +Node: Global TODO list283403 +Node: Matching tags and properties285931 +Node: Timeline292550 +Node: Search view293242 +Node: Stuck projects294535 +Ref: Stuck projects-Footnote-1296595 +Node: Presentation and sorting296625 +Node: Categories297418 +Ref: Categories-Footnote-1298219 +Node: Time-of-day specifications298656 +Node: Sorting of agenda items300628 +Node: Agenda commands302166 +Ref: Agenda commands-Footnote-1323930 +Ref: Agenda commands-Footnote-2324011 +Ref: Agenda commands-Footnote-3324422 +Node: Custom agenda views324505 +Node: Storing searches325146 +Ref: Storing searches-Footnote-1327680 +Node: Block agenda327797 +Node: Setting Options329035 +Node: Exporting Agenda Views331961 +Ref: Exporting Agenda Views-Footnote-1336862 +Ref: Exporting Agenda Views-Footnote-2336920 +Ref: Exporting Agenda Views-Footnote-3337076 +Ref: Exporting Agenda Views-Footnote-4337263 +Node: Agenda column view337345 +Node: Markup340027 +Node: Structural markup elements341000 +Node: Document title341733 +Node: Headings and sections342495 +Node: Table of contents343165 +Node: Initial text343928 +Node: Lists345042 +Node: Paragraphs345326 +Node: Footnote markup346476 +Node: Emphasis and monospace346831 +Node: Horizontal rules347231 +Node: Comment lines347506 +Node: Images and tables348040 +Node: Literal examples349521 +Ref: Literal examples-Footnote-1353158 +Ref: Literal examples-Footnote-2354136 +Ref: Literal examples-Footnote-3354315 +Ref: Literal examples-Footnote-4354552 +Node: Include files354646 +Node: Index entries355687 +Node: Macro replacement356149 +Node: Embedded LaTeX356979 +Ref: Embedded LaTeX-Footnote-1357921 +Node: Special symbols358111 +Ref: Special symbols-Footnote-1359723 +Node: Subscripts and superscripts359878 +Node: LaTeX fragments361132 +Ref: LaTeX fragments-Footnote-1363772 +Ref: LaTeX fragments-Footnote-2363945 +Ref: LaTeX fragments-Footnote-3364250 +Node: Previewing LaTeX fragments364427 +Node: CDLaTeX mode365436 +Ref: CDLaTeX mode-Footnote-1367923 +Node: Exporting368071 +Node: Selective export369847 +Node: Export options370676 +Ref: Export options-Footnote-1375199 +Node: The export dispatcher375290 +Ref: The export dispatcher-Footnote-1376596 +Node: ASCII/Latin-1/UTF-8 export376694 +Ref: ASCII/Latin-1/UTF-8 export-Footnote-1379092 +Ref: ASCII/Latin-1/UTF-8 export-Footnote-2379150 +Node: HTML export379202 +Node: HTML Export commands380152 +Ref: HTML Export commands-Footnote-1382104 +Ref: HTML Export commands-Footnote-2382162 +Node: Quoting HTML tags382214 +Node: Links in HTML export382865 +Node: Tables in HTML export384000 +Node: Images in HTML export384545 +Ref: Images in HTML export-Footnote-1385842 +Node: Math formatting in HTML export385904 +Ref: Math formatting in HTML export-Footnote-1387340 +Node: Text areas in HTML export387475 +Node: CSS support388319 +Ref: CSS support-Footnote-1391210 +Ref: CSS support-Footnote-2391396 +Node: JavaScript support391596 +Node: LaTeX and PDF export395209 +Ref: LaTeX and PDF export-Footnote-1396082 +Node: LaTeX/PDF export commands396342 +Ref: LaTeX/PDF export commands-Footnote-1398259 +Ref: LaTeX/PDF export commands-Footnote-2398317 +Node: Header and sectioning398369 +Ref: Header and sectioning-Footnote-1399445 +Node: Quoting LaTeX code399571 +Node: Tables in LaTeX export400206 +Node: Images in LaTeX export400939 +Node: Beamer class export402606 +Node: DocBook export408306 +Node: DocBook export commands409174 +Ref: DocBook export commands-Footnote-1410727 +Ref: DocBook export commands-Footnote-2410787 +Node: Quoting DocBook code410839 +Node: Recursive sections411888 +Node: Tables in DocBook export412616 +Node: Images in DocBook export413081 +Node: Special characters415015 +Node: TaskJuggler export416056 +Node: Freemind export421348 +Node: XOXO export421636 +Node: iCalendar export422108 +Ref: iCalendar export-Footnote-1424807 +Ref: iCalendar export-Footnote-2424897 +Ref: iCalendar export-Footnote-3424997 +Node: Publishing425134 +Node: Configuration426002 +Node: Project alist426778 +Node: Sources and destinations427940 +Node: Selecting files429457 +Node: Publishing action430456 +Ref: Publishing action-Footnote-1432246 +Node: Publishing options432600 +Node: Publishing links436209 +Node: Sitemap437891 +Node: Generating an index439413 +Node: Uploading files439996 +Node: Sample configuration441759 +Node: Simple example442248 +Node: Complex example442921 +Node: Triggering publication445008 +Node: Working With Source Code445994 +Node: Structure of code blocks447622 +Node: Editing source code448989 +Node: Exporting code blocks450420 +Node: Extracting source code452142 +Node: Evaluating code blocks453503 +Ref: Evaluating code blocks-Footnote-1455201 +Ref: Evaluating code blocks-Footnote-2455509 +Node: Library of Babel455637 +Node: Languages456447 +Node: Header arguments458419 +Node: Using header arguments458904 +Node: System-wide header arguments459664 +Node: Language-specific header arguments460487 +Node: Buffer-wide header arguments460890 +Node: Header arguments in Org-mode properties461665 +Node: Code block specific header arguments462689 +Node: Header arguments in function calls463823 +Node: Specific header arguments464189 +Node: var465717 +Node: results470206 +Node: file474215 +Node: dir474997 +Node: exports477914 +Node: tangle478566 +Node: comments479277 +Node: no-expand480272 +Node: session480763 +Node: noweb481208 +Node: cache482687 +Node: hlines483523 +Node: colnames485036 +Node: rownames486104 +Node: shebang486966 +Node: eval487361 +Node: Results of evaluation487904 +Node: Noweb reference syntax491103 +Node: Key bindings and useful functions492098 +Node: Batch execution493564 +Node: Miscellaneous494659 +Node: Completion495435 +Node: Easy Templates497410 +Node: Speed keys498794 +Node: Code evaluation security499620 +Node: Customization501794 +Node: In-buffer settings502385 +Ref: In-buffer settings-Footnote-1511615 +Node: The very busy C-c C-c key511663 +Node: Clean view513571 +Ref: Clean view-Footnote-1517557 +Ref: Clean view-Footnote-2517618 +Ref: Clean view-Footnote-3517802 +Ref: Clean view-Footnote-4517863 +Ref: Clean view-Footnote-5517975 +Ref: Clean view-Footnote-6518030 +Node: TTY keys518155 +Node: Interaction519921 +Node: Cooperation520297 +Node: Conflicts524093 +Node: Hacking527410 +Node: Hooks528262 +Node: Add-on packages528678 +Node: Adding hyperlink types529219 +Node: Context-sensitive commands533141 +Ref: Context-sensitive commands-Footnote-1534717 +Node: Tables in arbitrary syntax534851 +Node: Radio tables536263 +Node: A LaTeX example538805 +Ref: A LaTeX example-Footnote-1542727 +Ref: A LaTeX example-Footnote-2542875 +Node: Translator functions543310 +Ref: Translator functions-Footnote-1546533 +Node: Radio lists546621 +Node: Dynamic blocks547750 +Node: Special agenda views549848 +Ref: Special agenda views-Footnote-1553826 +Node: Extracting agenda information553961 +Node: Using the property API558033 +Node: Using the mapping API561325 +Node: MobileOrg565655 +Node: Setting up the staging area567132 +Ref: Setting up the staging area-Footnote-1568231 +Ref: Setting up the staging area-Footnote-2568532 +Node: Pushing to MobileOrg568793 +Ref: Pushing to MobileOrg-Footnote-1569784 +Ref: Pushing to MobileOrg-Footnote-2570200 +Node: Pulling from MobileOrg570257 +Ref: Pulling from MobileOrg-Footnote-1572677 +Ref: Pulling from MobileOrg-Footnote-2572737 +Node: History and Acknowledgments573114 +Node: Main Index584282 +Node: Key Index650959 +Node: Command and Function Index696062 +Node: Variable Index727252 + +End Tag Table diff --git a/.emacs.d/org-7.4/doc/org.pdf b/.emacs.d/org-7.4/doc/org.pdf Binary files differnew file mode 100644 index 0000000..0257c40 --- /dev/null +++ b/.emacs.d/org-7.4/doc/org.pdf diff --git a/.emacs.d/org-7.4/doc/org.texi b/.emacs.d/org-7.4/doc/org.texi new file mode 100644 index 0000000..5a67678 --- /dev/null +++ b/.emacs.d/org-7.4/doc/org.texi @@ -0,0 +1,14774 @@ + +\input texinfo +@c %**start of header +@setfilename ../../info/org +@settitle The Org Manual + +@set VERSION 7.4 +@set DATE December 2010 + +@c Use proper quote and backtick for code sections in PDF output +@c Cf. Texinfo manual 14.2 +@set txicodequoteundirected +@set txicodequotebacktick + +@c Version and Contact Info +@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} +@set AUTHOR Carsten Dominik +@set MAINTAINER Carsten Dominik +@set MAINTAINEREMAIL @email{carsten at orgmode dot org} +@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer} +@c %**end of header +@finalout + + +@c ----------------------------------------------------------------------------- + +@c Macro definitions for commands and keys +@c ======================================= + +@c The behavior of the key/command macros will depend on the flag cmdnames +@c When set, commands names are shown. When clear, they are not shown. + +@set cmdnames + +@c Below we define the following macros for Org key tables: + +@c orgkey{key} A key item +@c orgcmd{key,cmd} Key with command name +@c xorgcmd{key,cmmand} Key with command name as @itemx +@c orgcmdnki{key,cmd} Like orgcmd, but do not index the key +@c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key +@c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or" +@c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but +@c different functions, so format as @itemx +@c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short" +@c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx +@c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands + +@c a key but no command +@c Inserts: @item key +@macro orgkey{key} +@kindex \key\ +@item @kbd{\key\} +@end macro + +@macro xorgkey{key} +@kindex \key\ +@itemx @kbd{\key\} +@end macro + +@c one key with a command +@c Inserts: @item KEY COMMAND +@macro orgcmd{key,command} +@ifset cmdnames +@kindex \key\ +@findex \command\ +@iftex +@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key\ +@item @kbd{\key\} +@end ifclear +@end macro + +@c One key with one command, formatted using @itemx +@c Inserts: @itemx KEY COMMAND +@macro xorgcmd{key,command} +@ifset cmdnames +@kindex \key\ +@findex \command\ +@iftex +@itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key\ +@itemx @kbd{\key\} +@end ifclear +@end macro + +@c one key with a command, bit do not index the key +@c Inserts: @item KEY COMMAND +@macro orgcmdnki{key,command} +@ifset cmdnames +@findex \command\ +@iftex +@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@item @kbd{\key\} +@end ifclear +@end macro + +@c one key with a command, and special text to replace key in item +@c Inserts: @item TEXT COMMAND +@macro orgcmdtkc{text,key,command} +@ifset cmdnames +@kindex \key\ +@findex \command\ +@iftex +@item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key\ +@item @kbd{\text\} +@end ifclear +@end macro + +@c two keys with one command +@c Inserts: @item KEY1 or KEY2 COMMAND +@macro orgcmdkkc{key1,key2,command} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command\ +@iftex +@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} +@end ifclear +@end macro + +@c Two keys with one command name, but different functions, so format as +@c @itemx +@c Inserts: @item KEY1 +@c @itemx KEY2 COMMAND +@macro orgcmdkxkc{key1,key2,command} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command\ +@iftex +@item @kbd{\key1\} +@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\key1\} +@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@item @kbd{\key1\} +@itemx @kbd{\key2\} +@end ifclear +@end macro + +@c Same as previous, but use "or short" +@c Inserts: @item KEY1 or short KEY2 COMMAND +@macro orgcmdkskc{key1,key2,command} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command\ +@iftex +@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} +@end ifclear +@end macro + +@c Same as previous, but use @itemx +@c Inserts: @itemx KEY1 or short KEY2 COMMAND +@macro xorgcmdkskc{key1,key2,command} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command\ +@iftex +@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\} +@end iftex +@ifnottex +@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} +@end ifclear +@end macro + +@c two keys with two commands +@c Inserts: @item KEY1 COMMAND1 +@c @itemx KEY2 COMMAND2 +@macro orgcmdkkcc{key1,key2,command1,command2} +@ifset cmdnames +@kindex \key1\ +@kindex \key2\ +@findex \command1\ +@findex \command2\ +@iftex +@item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\} +@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\} +@end iftex +@ifnottex +@item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\}) +@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\}) +@end ifnottex +@end ifset +@ifclear cmdnames +@kindex \key1\ +@kindex \key2\ +@item @kbd{\key1\} +@itemx @kbd{\key2\} +@end ifclear +@end macro +@c ----------------------------------------------------------------------------- + +@iftex +@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed} +@end iftex + +@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 version @value{VERSION}. + +Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010 +Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 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 the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Org Mode: (org). Outline-based notes management and organizer +@end direntry + +@titlepage +@title The Org Manual + +@subtitle Release @value{VERSION} +@author by Carsten Dominik +with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, and Thomas Dye + +@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:: Storing information about an entry +* Dates and Times:: Making items useful for planning +* Capture - Refile - Archive:: The ins and outs for projects +* Agenda Views:: Collecting information into views +* Markup:: Prepare text for rich export +* Exporting:: Sharing and publishing of notes +* Publishing:: Create a web site of linked Org files +* Working With Source Code:: Export, evaluate, and tangle code blocks +* Miscellaneous:: All the rest which did not fit elsewhere +* Hacking:: How to hack your way around +* MobileOrg:: Viewing and capture on a mobile device +* History and Acknowledgments:: How Org came into being +* Main Index:: An index of Org's concepts and features +* Key Index:: Key bindings and where they are described +* Command and Function Index:: Command names and some internal functions +* Variable Index:: Variables mentioned in the manual + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Summary:: Brief summary of what Org does +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. +* Conventions:: Type-setting conventions in the manual + +Document structure + +* Outlines:: Org 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 +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Drawers:: Tucking stuff away +* Blocks:: Folding blocks +* Footnotes:: How footnotes are defined in Org's syntax +* Orgstruct mode:: Structure editing outside Org + +Tables + +* Built-in table editor:: Simple tables +* Column width and alignment:: Overrule the automatic settings +* Column groups:: Grouping to trigger vertical lines +* Orgtbl mode:: The table editor as minor mode +* The spreadsheet:: The table editor has spreadsheet capabilities +* Org-Plot:: Plotting from org tables + +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 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:: 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 + +Internal links + +* Radio targets:: Make targets trigger links in plain text + +TODO items + +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* Progress logging:: Dates and notes for progress +* 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 does the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Fast access to TODO states:: Single letter selection of a state +* Per-file keywords:: Different files, different requirements +* Faces for TODO keywords:: Highlighting states +* TODO dependencies:: When one task needs to wait for others + +Progress logging + +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Tracking your habits:: How consistent have you been? + +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 +* Property inheritance:: Passing values down the tree +* 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 +* Capturing column view:: A dynamic block for column view + +Defining columns + +* Scope of column definitions:: Where defined, where valid? +* Column attributes:: Appearance and content of a column + +Dates and times + +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task +* Effort estimates:: Planning work effort in advance +* Relative timer:: Notes with a running timer +* Countdown timer:: Starting a countdown timer for a task + +Creating timestamps + +* The date/time prompt:: How Org-mode helps you entering date and time +* Custom time format:: Making dates look different + +Deadlines and scheduling + +* Inserting deadline/schedule:: Planning items +* Repeated tasks:: Items that show up again and again + +Clocking work time + +* Clocking commands:: Starting and stopping a clock +* The clock table:: Detailed reports +* Resolving idle time:: Resolving time when you've been idle + +Capture - Refile - Archive + +* Capture:: Capturing new stuff +* Attachments:: Add files to tasks +* RSS Feeds:: Getting input from RSS feeds +* Protocols:: External (e.g. Browser) access to Emacs and Org +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects + +Capture + +* Setting up capture:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types + +Capture templates + +* Template elements:: What is needed for a complete template entry +* Template expansion:: Filling in information about time and context + +Archiving + +* Moving subtrees:: Moving a tree to an archive file +* Internal archiving:: Switch off a tree but keep it in the file + +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 +* Exporting Agenda Views:: Writing a view to a file +* Agenda column view:: Using column view for collected entries + +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 +* Search view:: Find entries by searching for text +* 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 + +Markup for rich export + +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Index entries:: Making an index +* Macro replacement:: Use macros to create complex output +* Embedded LaTeX:: LaTeX can be freely used inside Org documents + +Structural markup elements + +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Initial text:: Text before the first heading? +* Lists:: Lists +* Paragraphs:: Paragraphs +* Footnote markup:: Footnotes +* Emphasis and monospace:: Bold, italic, etc. +* Horizontal rules:: Make a line +* Comment lines:: What will *not* be exported + +Embedded @LaTeX{} + +* Special symbols:: Greek letters and other symbols +* Subscripts and superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Previewing LaTeX fragments:: What will this snippet look like? +* CDLaTeX mode:: Speed up entering of formulas + +Exporting + +* Selective export:: Using tags to select and exclude trees +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* TaskJuggler export:: Exporting to TaskJuggler +* Freemind export:: Exporting to Freemind mind maps +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format + +HTML export + +* HTML Export commands:: How to invoke HTML export +* Quoting HTML tags:: Using direct HTML in Org-mode +* Links in HTML export:: How links will be interpreted and formatted +* Tables in HTML export:: How to modify the formatting of tables +* Images in HTML export:: How to insert figures into HTML output +* Math formatting in HTML export:: Beautiful math also on the web +* Text areas in HTML export:: An alternative way to show an example +* CSS support:: Changing the appearance of the output +* JavaScript support:: Info and Folding in a web browser + +@LaTeX{} and PDF export + +* LaTeX/PDF export commands:: Which key invokes which commands +* Header and sectioning:: Setting up the export file structure +* Quoting LaTeX code:: Incorporating literal @LaTeX{} code +* Tables in LaTeX export:: Options for exporting tables to @LaTeX{} +* Images in LaTeX export:: How to insert figures into @LaTeX{} output +* Beamer class export:: Turning the file into a presentation + +DocBook export + +* DocBook export commands:: How to invoke DocBook export +* Quoting DocBook code:: Incorporating DocBook code in Org files +* Recursive sections:: Recursive sections in DocBook +* Tables in DocBook export:: Tables are exported as HTML tables +* Images in DocBook export:: How to insert figures into DocBook output +* Special characters:: How to handle special characters + +Publishing + +* Configuration:: Defining projects +* Uploading files:: How to get files up on the server +* 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? +* Sitemap:: Generating a list of all pages +* Generating an index:: An index that reaches across pages + +Sample configuration + +* Simple example:: One-component publishing +* Complex example:: A multi-component publishing example + +Working with source code + +* Structure of code blocks:: Code block syntax described +* Editing source code:: Language major-mode editing +* Exporting code blocks:: Export contents and/or results +* Extracting source code:: Create pure source code files +* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Library of Babel:: Use and contribute to a library of useful code blocks +* Languages:: List of supported code block languages +* Header arguments:: Configure code block functionality +* Results of evaluation:: How evaluation results are handled +* Noweb reference syntax:: Literate programming in Org-mode +* Key bindings and useful functions:: Work quickly with code blocks +* Batch execution:: Call functions from the command line + +Header arguments + +* Using header arguments:: Different ways to set header arguments +* Specific header arguments:: List of header arguments + +Using header arguments + +* System-wide header arguments:: Set global default values +* Language-specific header arguments:: Set default values by language +* Buffer-wide header arguments:: Set default values for a specific buffer +* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Code block specific header arguments:: The most common way to set values +* Header arguments in function calls:: The most specific level + +Specific header arguments + +* var:: Pass arguments to code blocks +* results:: Specify the type of results and how they will + be collected and handled +* file:: Specify a path for file output +* dir:: Specify the default (possibly remote) + directory for code block execution +* exports:: Export code and/or results +* tangle:: Toggle tangling and specify file name +* comments:: Toggle insertion of comments in tangled + code files +* no-expand:: Turn off variable assignment and noweb + expansion during tangling +* session:: Preserve the state of code evaluation +* noweb:: Toggle expansion of noweb references +* cache:: Avoid re-evaluating unchanged code blocks +* hlines:: Handle horizontal lines in tables +* colnames:: Handle column names in tables +* rownames:: Handle row names in tables +* shebang:: Make tangled files executable +* eval:: Limit evaluation of specific code blocks + +Miscellaneous + +* Completion:: M-TAB knows what you need +* Easy Templates:: Quick insertion of structural elements +* Speed keys:: Electric commands at the beginning of a headline +* Code evaluation security:: Org mode files evaluate inline code +* Customization:: Adapting Org 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 on a tty +* Interaction:: Other Emacs packages + +Interaction with other packages + +* Cooperation:: Packages Org cooperates with +* Conflicts:: Packages that lead to conflicts + +Hacking + +* Hooks:: Who to reach into Org's internals +* Add-on packages:: Available extensions +* Adding hyperlink types:: New custom link types +* Context-sensitive commands:: How to add functionality to such commands +* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs +* Dynamic blocks:: Automatically filled blocks +* Special agenda views:: Customized views +* Extracting agenda information:: Postprocessing of agenda information +* Using the property API:: Writing programs that use entry properties +* Using the mapping API:: Mapping over all or selected entries + +Tables and lists in arbitrary syntax + +* Radio tables:: Sending and receiving radio tables +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify +* Radio lists:: Doing the same for lists + +MobileOrg + +* Setting up the staging area:: Where to interact with the mobile device +* Pushing to MobileOrg:: Uploading Org files and agendas +* Pulling from MobileOrg:: Integrating captured and flagged items + +@end detailmenu +@end menu + +@node Introduction, Document Structure, Top, Top +@chapter Introduction +@cindex introduction + +@menu +* Summary:: Brief summary of what Org does +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. +* Conventions:: Type-setting conventions in the manual +@end menu + +@node Summary, Installation, Introduction, Introduction +@section Summary +@cindex summary + +Org is a mode for keeping notes, maintaining TODO lists, and doing +project planning with a fast and effective plain-text system. + +Org develops organizational tasks around NOTES files that contain +lists or information about projects as plain text. Org 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 supports TODO items, deadlines, +timestamps, 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 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 web pages. + +As a project planning environment, Org works by adding metadata to outline +nodes. Based on this data, specific entries can be extracted in queries and +create dynamic @i{agenda views}. + +Org mode contains the Org Babel environment which allows you to work with +embedded source code blocks in a file, to facilitate code evaluation, +documentation, and tangling. + +Org'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 @LaTeX{}. The structure +editing and list creation capabilities can be used outside Org with +the minor Orgstruct mode. + +Org 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 is a toolbox and can be used in different ways and for different +ends, for example: + +@example +@r{@bullet{} an outline extension with visibility cycling and structure editing} +@r{@bullet{} an ASCII system and table editor for taking structured notes} +@r{@bullet{} a TODO list editor} +@r{@bullet{} a full agenda and planner with deadlines and work scheduling} +@pindex GTD, Getting Things Done +@r{@bullet{} an environment in which to implement David Allen's GTD system} +@r{@bullet{} a simple hypertext system, with HTML and @LaTeX{} export} +@r{@bullet{} a publishing tool to create a set of interlinked webpages} +@r{@bullet{} an environment for literate programming} +@end example + + +@cindex FAQ +There is a website for Org which provides links to the newest +version of Org, as well as additional information, frequently asked +questions (FAQ), links to tutorials, etc@. This page is located at +@uref{http://orgmode.org}. + +@page + + +@node Installation, Activation, Summary, Introduction +@section Installation +@cindex installation +@cindex XEmacs + +@b{Important:} @i{If you are using a version of Org that 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 from the Web, either as a distribution @file{.zip} +or @file{.tar} file, or as a Git archive, you must take the following steps +to install it: go into the unpacked Org 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, you can simply run Org directly from +the distribution directory by adding the @file{lisp} subdirectory to the +Emacs load path. To do this, add the following line to @file{.emacs}: + +@example +(setq load-path (cons "~/path/to/orgdir/lisp" load-path)) +@end example + +@noindent +If you plan to use code from the @file{contrib} subdirectory, do a similar +step for this directory: + +@example +(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) +@end example + +@noindent Now byte-compile the Lisp files with the shell command: + +@example +make +@end example + +@noindent If you are running Org from the distribution directory, this is +all. If you want to install Org into the system directories, use (as +administrator) + +@example +make install +@end example + +Installing Info files is system dependent, because of differences in the +@file{install-info} program. In Debian it copies the info files into the +correct directory and modifies the info directory file. In many other +systems, the files need to be copied to the correct directory separately, and +@file{install-info} then only modifies the directory file. Check your system +documentation to find out which of the following commands you need: + +@example +make install-info +make install-info-debian +@end example + +Then add the following line to @file{.emacs}. It is needed so that +Emacs can autoload functions that are located in files not immediately loaded +when Org-mode starts. +@lisp +(require 'org-install) +@end lisp + +Do not forget to activate Org as described in the following section. +@page + +@node Activation, Feedback, Installation, Introduction +@section Activation +@cindex activation +@cindex autoload +@cindex global key bindings +@cindex key bindings, global + +Add the following lines to your @file{.emacs} file. The last three lines +define @emph{global} keys for the commands @command{org-store-link}, +@command{org-agenda}, and @command{org-iswitchb}---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) +(global-set-key "\C-cb" 'org-iswitchb) +@end lisp + +Furthermore, you must activate @code{font-lock-mode} in Org +buffers, because significant functionality depends on font-locking being +active. You can do this with either one of the following two lines +(XEmacs users must use the second option): +@lisp +(global-font-lock-mode 1) ; for all buffers +(add-hook 'org-mode-hook 'turn-on-font-lock) ; Org 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 + +@vindex org-insert-mode-line-in-empty-file +@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}. + +Many commands in Org work on the region if the region is @i{active}. To make +use of this, you need to have @code{transient-mark-mode} +(@code{zmacs-regions} in XEmacs) turned on. In Emacs 23 this is the default, +in Emacs 22 you need to do this yourself with +@lisp +(transient-mark-mode 1) +@end lisp +@noindent If you do not like @code{transient-mark-mode}, you can create an +active region by using the mouse to select a region, or pressing +@kbd{C-@key{SPC}} twice before moving the cursor. + +@node Feedback, Conventions, Activation, Introduction +@section Feedback +@cindex feedback +@cindex bug reports +@cindex maintainer +@cindex author + +If you find problems with Org, or if you have questions, remarks, or ideas +about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}. +If you are not a member of the mailing list, your mail will be passed to the +list after a moderator has approved it@footnote{Please consider subscribing +to the mailing list, in order to minimize the work the mailing list +moderators have to do.}. + +For bug reports, please first try to reproduce the bug with the latest +version of Org available---if you are running an outdated version, it is +quite possible that the bug has been fixed already. If the bug persists, +prepare a report and provide as much information as possible, including the +version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org +(@kbd{M-x org-version @key{RET}}), as well as the Org related setup in +@file{.emacs}. The easiest way to do this is to use the command +@example +@kbd{M-x org-submit-bug-report} +@end example +@noindent which will put all this information into an Emacs mail buffer so +that you only need to add your description. If you re not sending the Email +from within Emacs, please copy and paste the content into your Email program. + +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 program. + +@subsubheading How to create a useful backtrace + +@cindex backtrace of an error +If working with Org 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 +Reload uncompiled versions of all Org-mode Lisp files. The backtrace +contains much more information if it is produced with uncompiled code. +To do this, use +@example +C-u M-x org-reload RET +@end example +@noindent +or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the +menu. +@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 Conventions, , Feedback, Introduction +@section Typesetting conventions used in this manual + +Org uses three types of keywords: TODO keywords, tags, and property +names. In this manual we use the following conventions: + +@table @code +@item TODO +@itemx WAITING +TODO keywords are written with all capitals, even if they are +user-defined. +@item boss +@itemx ARCHIVE +User-defined tags are written in lowercase; built-in tags with special +meaning are written with all capitals. +@item Release +@itemx PRIORITY +User-defined properties are capitalized; built-in properties with +special meaning are written with all capitals. +@end table + +The manual lists both the keys and the corresponding commands for accessing +functionality. Org mode often uses the same key for different functions, +depending on context. The command that is bound to such keys has a generic +name, like @code{org-metaright}. In the manual we will, wherever possible, +give the function that is internally called by the generic command. For +example, in the chapter on document structure, @kbd{M-@key{right}} will be +listed to call @code{org-do-demote}, while in the chapter on tables, it will +be listed to call org-table-move-column-right. + +If you prefer, you can compile the manual without the command names by +unsetting the flag @code{cmdnames} in @file{org.texi}. + +@node Document Structure, Tables, Introduction, Top +@chapter Document structure +@cindex document structure +@cindex structure of document + +Org is based on Outline mode and provides flexible commands to +edit the structure of the document. + +@menu +* Outlines:: Org 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 +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Drawers:: Tucking stuff away +* Blocks:: Folding blocks +* Footnotes:: How footnotes are defined in Org's syntax +* Orgstruct mode:: Structure editing outside Org +@end menu + +@node Outlines, Headlines, Document Structure, Document Structure +@section Outlines +@cindex outlines +@cindex Outline mode + +Org 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 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 +@vindex org-special-ctrl-a/e +@vindex org-special-ctrl-k +@vindex org-ctrl-k-protect-subtree + +Headlines define the structure of an outline tree. The headlines in Org +start with one or more stars, on the left margin@footnote{See the variables +@code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and +@code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a}, +@kbd{C-e}, and @kbd{C-k} 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. + +@vindex org-cycle-separator-lines +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 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 @asis +@orgcmd{@key{TAB},org-cycle} +@emph{Subtree cycling}: Rotate current subtree among the states + +@example +,-> FOLDED -> CHILDREN -> SUBTREE --. +'-----------------------------------' +@end example + +@vindex org-cycle-emulate-tab +@vindex org-cycle-global-at-bob +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 +@orgcmd{S-@key{TAB},org-global-cycle} +@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 numeric prefix argument 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 +@orgcmd{C-u C-u C-u @key{TAB},show-all} +Show all, including drawers. +@orgcmd{C-c C-r,org-reveal} +Reveal context around point, showing the current entry, the following heading +and the hierarchy above. Useful for working near a location that has been +exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command +(@pxref{Agenda commands}). With a prefix argument show, on each +level, all sibling headings. With double prefix arg, also show the entire +subtree of the parent. +@orgcmd{C-c C-k,show-branches} +Expose all the headings of the subtree, CONTENT view for just one subtree. +@orgcmd{C-c C-x b,org-tree-to-indirect-buffer} +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 a numeric +prefix argument N, go up to level N and then take that tree. If N is +negative then go up that many levels. With a @kbd{C-u} prefix, do not remove +the previously used indirect buffer. +@end table + +@vindex org-startup-folded +@cindex @code{overview}, STARTUP keyword +@cindex @code{content}, STARTUP keyword +@cindex @code{showall}, STARTUP keyword +@cindex @code{showeverything}, STARTUP keyword + +When Emacs first visits an Org 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 +#+STARTUP: showeverything +@end example + +@cindex property, VISIBILITY +@noindent +Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties +and Columns}) will get their visibility adapted accordingly. Allowed values +for this property are @code{folded}, @code{children}, @code{content}, and +@code{all}. +@table @asis +@orgcmd{C-u C-u @key{TAB},org-set-startup-visibility} +Switch back to the startup visibility of the buffer, i.e. whatever is +requested by startup options and @samp{VISIBILITY} properties in individual +entries. +@end table + +@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 @asis +@orgcmd{C-c C-n,outline-next-visible-heading} +Next heading. +@orgcmd{C-c C-p,outline-previous-visible-heading} +Previous heading. +@orgcmd{C-c C-f,org-forward-same-level} +Next heading same level. +@orgcmd{C-c C-b,org-backward-same-level} +Previous heading same level. +@orgcmd{C-c C-u,outline-up-heading} +Backward to higher level heading. +@orgcmd{C-c C-j,org-goto} +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: +@vindex org-goto-auto-isearch +@example +@key{TAB} @r{Cycle visibility.} +@key{down} / @key{up} @r{Next/previous visible headline.} +@key{RET} @r{Select this location.} +@kbd{/} @r{Do a Sparse-tree search} +@r{The following keys work if you turn off @code{org-goto-auto-isearch}} +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.} +q @r{Quit} +@end example +@vindex org-goto-interface +@noindent +See also the variable @code{org-goto-interface}. +@end table + +@node Structure editing, Sparse trees, 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 sorting, of subtrees +@cindex subtrees, cut and paste + +@table @asis +@orgcmd{M-@key{RET},org-insert-heading} +@vindex org-M-RET-may-split-line +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 argument, 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@footnote{If you do not want the line to be split, +customize the variable @code{org-M-RET-may-split-line}.}. 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. +@orgcmd{C-@key{RET},org-insert-heading-respect-content} +Just like @kbd{M-@key{RET}}, except when adding a new heading below the +current heading, the new heading is placed after the body instead of before +it. This command works from anywhere in the entry. +@orgcmd{M-S-@key{RET},org-insert-todo-heading} +@vindex org-treat-insert-todo-heading-as-state-change +Insert new TODO entry with same level as current heading. See also the +variable @code{org-treat-insert-todo-heading-as-state-change}. +@orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content} +Insert new TODO entry with same level as current heading. Like +@kbd{C-@key{RET}}, the new headline will be inserted after the current +subtree. +@orgcmd{@key{TAB},org-cycle} +In a new entry with no text yet, the first @key{TAB} demotes the entry to +become a child of the previous one. The next @key{TAB} makes it a parent, +and so on, all the way to top level. Yet another @key{TAB}, and you are back +to the initial level. +@orgcmd{M-@key{left},org-do-promote} +Promote current heading by one level. +@orgcmd{M-@key{right},org-do-demote} +Demote current heading by one level. +@orgcmd{M-S-@key{left},org-promote-subtree} +Promote the current subtree by one level. +@orgcmd{M-S-@key{right},org-demote-subtree} +Demote the current subtree by one level. +@orgcmd{M-S-@key{up},org-move-subtree-up} +Move subtree up (swap with previous subtree of same +level). +@orgcmd{M-S-@key{down},org-move-subtree-down} +Move subtree down (swap with next subtree of same level). +@orgcmd{C-c C-x C-w,org-cut-subtree} +Kill subtree, i.e. remove it from buffer but save in kill ring. +With a numeric prefix argument N, kill N sequential subtrees. +@orgcmd{C-c C-x M-w,org-copy-subtree} +Copy subtree to kill ring. With a numeric prefix argument N, copy the N +sequential subtrees. +@orgcmd{C-c C-x C-y,org-paste-subtree} +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 numeric prefix argument, or by yanking after a +headline marker like @samp{****}. +@orgcmd{C-y,org-yank} +@vindex org-yank-adjusted-subtrees +@vindex org-yank-folded-subtrees +Depending on the variables @code{org-yank-adjusted-subtrees} and +@code{org-yank-folded-subtrees}, Org's internal @code{yank} command will +paste subtrees folded and in a clever way, using the same command as @kbd{C-c +C-x C-y}. With the default settings, no level adjustment will take place, +but the yanked tree will be folded unless doing so would swallow text +previously visible. Any prefix argument to this command will force a normal +@code{yank} to be executed, with the prefix passed along. A good way to +force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a +yank, it will yank previous kill items plainly, without adjustment and +folding. +@orgcmd{C-c C-x c,org-clone-subtree-with-time-shift} +Clone a subtree by making a number of sibling copies of it. You will be +prompted for the number of copies to make, and you can also specify if any +timestamps in the entry should be shifted. This can be useful, for example, +to create a number of tasks related to a series of lectures to prepare. For +more details, see the docstring of the command +@code{org-clone-subtree-with-time-shift}. +@orgcmd{C-c C-w,org-refile} +Refile entry or region to a different location. @xref{Refiling notes}. +@orgcmd{C-c ^,org-sort-entries-or-items} +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 (first timestamp with active preferred, +creation time, scheduled time, deadline time), by priority, by TODO keyword +(in the sequence the keywords have been defined in the setup) or by the value +of a property. Reverse sorting is possible as well. You can also supply +your own function to extract the sorting key. 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. +@orgcmd{C-x n s,org-narrow-to-subtree} +Narrow buffer to current subtree. +@orgcmd{C-x n w,widen} +Widen buffer to remove narrowing. +@orgcmd{C-c *,org-toggle-heading} +Turn a normal line or plain list item into a headline (so that it becomes a +subheading at its location). Also turn a headline into a normal line by +removing the stars. If there is an active region, turn all lines in the +region into headlines. If the first line in the region was an item, turn +only the item lines into headlines. Finally, if the first line is a +headline, remove the stars from all headlines in the region. +@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 Sparse trees, Plain lists, Structure editing, Document Structure +@section Sparse trees +@cindex sparse trees +@cindex trees, sparse +@cindex folding, sparse trees +@cindex occur, command + +@vindex org-show-hierarchy-above +@vindex org-show-following-heading +@vindex org-show-siblings +@vindex org-show-entry-below +An important feature of Org-mode is the ability to construct @emph{sparse +trees} for selected information in an outline tree, so 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}, +@code{org-show-siblings}, and @code{org-show-entry-below} 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, all these +commands can be accessed through a dispatcher: + +@table @asis +@orgcmd{C-c /,org-sparse-tree} +This prompts for an extra key to select a sparse-tree creating command. +@orgcmd{C-c / r,org-occur} +@vindex org-remove-highlights-with-change +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@footnote{This depends on the option +@code{org-remove-highlights-with-change}}, 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 +@vindex org-agenda-custom-commands +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}. + +The other sparse tree commands select headings based on TODO keywords, +tags, or properties and will be discussed later in this manual. + +@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 supports editing such lists, and every exporter +(@pxref{Exporting}) can parse and format them. + +Org knows ordered lists, unordered lists, and description lists. +@itemize @bullet +@item +@emph{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 to not use it for plain list items.} +as bullets. +@item +@vindex org-plain-list-ordered-item-terminator +@emph{Ordered} list items start with a numeral followed by either a period or +a right parenthesis@footnote{You can filter out any of them by configuring +@code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or +@samp{1)}. If you want a list to start with a different value (e.g. 20), start +the text of the item with @code{[@@20]}@footnote{If there's a checkbox in the +item, the cookie must be put @emph{before} the checkbox.}. Those constructs +can be used in any item of the list in order to enforce a particular +numbering. +@item +@emph{Description} list items are unordered list items, and contain the +separator @samp{ :: } to separate the description @emph{term} from the +description. +@end itemize + +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. + +@vindex org-list-ending-method +@vindex org-list-end-regexp +@vindex org-empty-line-terminates-plain-lists +Two methods@footnote{To disable either of them, configure +@code{org-list-ending-method}.} are provided to terminate lists. A list ends +before the next line that is indented like the bullet/number or less, or it +ends before two blank lines@footnote{See also +@code{org-empty-line-terminates-plain-lists}.}. In both cases, all levels of +the list are closed@footnote{So you cannot have a sublist, some text and then +another sublist while still in the same top-level list item. This used to be +possible, but it was only supported in the HTML exporter and difficult to +manage with automatic indentation.}. For finer control, you can end lists +with any pattern set in @code{org-list-end-regexp}. Here is an example: + +@example +@group +** Lord of the Rings + My favorite scenes are (in this order) + 1. The attack of the Rohirrim + 2. Eowyn's 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 + He makes a really funny face when it happens. + - on DVD only + But in the end, no individual scenes matter but the film as a whole. + Important actors in this film are: + - @b{Elijah Wood} :: He plays Frodo + - @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember + him very well from his role as Mikey Walsh in @i{The Goonies}. +@end group +@end example + +Org supports these lists by tuning filling and wrapping commands to deal with +them correctly@footnote{Org 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)}}, and by exporting them +properly (@pxref{Exporting}). Since indentation is what governs the +structure of these lists, many structural constructs like @code{#+BEGIN_...} +blocks can be indented to signal that they should be considered as a list +item. + +@vindex org-list-demote-modify-bullet +If you find that using a different bullet for a sub-list (than that used for +the current list-level) improves readability, customize the variable +@code{org-list-demote-modify-bullet}. + +@vindex org-list-automatic-rules +The following commands act on items when the cursor is in the first line of +an item (the line with the bullet or number). Some of them imply the +application of automatic rules to keep list structure intact. If some of +these actions get in your way, configure @code{org-list-automatic-rules} +to disable them individually. + +@table @asis +@orgcmd{@key{TAB},org-cycle} +@vindex org-cycle-include-plain-lists +Items can be folded just like headline levels. Normally this works only if +the cursor is on a plain list item. For more details, see the variable +@code{org-cycle-include-plain-lists}. If this variable is set to +@code{integrate}, plain list items will be treated like low-level +headlines. 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. +@orgcmd{M-@key{RET},org-insert-heading} +@vindex org-M-RET-may-split-line +@vindex org-list-automatic-rules +Insert new item at current level. With a prefix argument, 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@footnote{If you do not want the line to be split, customize the variable +@code{org-M-RET-may-split-line}.}. If this command is executed @emph{before +an item's body}, 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. + +As a new item cannot be inserted in a structural construct (like an example +or source code block) within a list, Org will instead insert it right before +the structure, or return an error. +@kindex M-S-@key{RET} +@item M-S-@key{RET} +Insert a new item with a checkbox (@pxref{Checkboxes}). +@orgcmd{@key{TAB},org-cycle} +In a new item with no text yet, the first @key{TAB} demotes the item to +become a child of the previous one. Subsequent @key{TAB}s move the item to +meaningful levels in the list and eventually get it back to its initial +position. +@kindex S-@key{down} +@item S-@key{up} +@itemx S-@key{down} +@cindex shift-selection-mode +@vindex org-support-shift-select +Jump to the previous/next item in the current list, but only if +@code{org-support-shift-select} is off. If not, you can still use paragraph +jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite +similar effect. +@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-@key{left} +@kindex M-@key{right} +@item M-@key{left} +@itemx M-@key{right} +Decrease/increase the indentation of an item, leaving children alone. +@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. + +As a special case, using this command on the very first item of a list will +move the whole list. This behavior can be disabled by configuring +@code{org-list-automatic-rules}. The global indentation of a list has no +influence on the text @emph{after} the list. +@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. Also, makes sure that all the +items on this list level use the same bullet and that the numbering of list +items (if applicable) is correct. +@kindex C-c - +@vindex org-plain-list-ordered-item-terminator +@vindex org-list-automatic-rules +@item C-c - +Cycle the entire list level through the different itemize/enumerate bullets +(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them, +depending on @code{org-plain-list-ordered-item-terminator}, the type of list, +and its position@footnote{See @code{bullet} rule in +@code{org-list-automatic-rules} for more information.}. With a numeric +prefix argument N, select the Nth bullet from this list. If there is an +active region when calling this, all lines will be converted to list items. +If the first line already was a list item, any item markers will be removed +from the list. Finally, even without an active region, a normal line will be +converted into a list item. +@kindex C-c * +@item C-c * +Turn a plain list item into a headline (so that it becomes a subheading at +its location). @xref{Structure editing}, for a detailed explanation. +@kindex S-@key{left} +@kindex S-@key{right} +@item S-@key{left}/@key{right} +@vindex org-support-shift-select +This command also cycles bullet styles when the cursor in on the bullet or +anywhere in an item line, details depending on +@code{org-support-shift-select}. +@kindex C-c ^ +@item C-c ^ +Sort the plain list. You will be prompted for the sorting method: +numerically, alphabetically, by time, or by custom function. +@end table + +@node Drawers, Blocks, Plain lists, Document Structure +@section Drawers +@cindex drawers +@cindex #+DRAWERS +@cindex visibility cycling, drawers + +@vindex org-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}@footnote{You can define drawers on a per-file basis +with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers +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 the @code{PROPERTIES} drawer for +storing properties (@pxref{Properties and Columns}), and you can also arrange +for state change notes (@pxref{Tracking TODO state changes}) and clock times +(@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you +want to store a quick note in the LOGBOOK drawer, in a similar way to state changes, use + +@table @kbd +@kindex C-c C-z +@item C-c C-z +Add a time-stamped note to the LOGBOOK drawer. +@end table + +@node Blocks, Footnotes, Drawers, Document Structure +@section Blocks + +@vindex org-hide-block-startup +@cindex blocks, folding +Org-mode uses begin...end blocks for various purposes from including source +code examples (@pxref{Literal examples}) to capturing time logging +information (@pxref{Clocking work time}). These blocks can be folded and +unfolded by pressing TAB in the begin line. You can also get all blocks +folded at startup by configuring the variable @code{org-hide-block-startup} +or on a per-file basis by using + +@cindex @code{hideblocks}, STARTUP keyword +@cindex @code{nohideblocks}, STARTUP keyword +@example +#+STARTUP: hideblocks +#+STARTUP: nohideblocks +@end example + +@node Footnotes, Orgstruct mode, Blocks, Document Structure +@section Footnotes +@cindex footnotes + +Org-mode supports the creation of footnotes. In contrast to the +@file{footnote.el} package, Org-mode's footnotes are designed for work on a +larger document, not only for one-off documents like emails. The basic +syntax is similar to the one used by @file{footnote.el}, i.e. a footnote is +defined in a paragraph that is started by a footnote marker in square +brackets in column 0, no indentation allowed. If you need a paragraph break +inside a footnote, use the @LaTeX{} idiom @samp{\par}. The footnote reference +is simply the marker in square brackets, inside text. For example: + +@example +The Org homepage[fn:1] now looks a lot better than it used to. +... +[fn:1] The link is: http://orgmode.org +@end example + +Org-mode extends the number-based syntax to @emph{named} footnotes and +optional inline definition. Using plain numbers as markers (as +@file{footnote.el} does) is supported for backward compatibility, but not +encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded +LaTeX}). Here are the valid references: + +@table @code +@item [1] +A plain numeric footnote marker. Compatible with @file{footnote.el}, but not +recommended because something like @samp{[1]} could easily be part of a code +snippet. +@item [fn:name] +A named footnote reference, where @code{name} is a unique label word, or, for +simplicity of automatic creation, a number. +@item [fn:: This is the inline definition of this footnote] +A @LaTeX{}-like anonymous footnote where the definition is given directly at the +reference point. +@item [fn:name: a definition] +An inline definition of a footnote, which also specifies a name for the note. +Since Org allows multiple references to the same note, you can then use +@code{[fn:name]} to create additional references. +@end table + +@vindex org-footnote-auto-label +Footnote labels can be created automatically, or you can create names yourself. +This is handled by the variable @code{org-footnote-auto-label} and its +corresponding @code{#+STARTUP} keywords. See the docstring of that variable +for details. + +@noindent The following command handles footnotes: + +@table @kbd +@kindex C-c C-x f +@item C-c C-x f +The footnote action command. + +When the cursor is on a footnote reference, jump to the definition. When it +is at a definition, jump to the (first) reference. + +@vindex org-footnote-define-inline +@vindex org-footnote-section +@vindex org-footnote-auto-adjust +Otherwise, create a new footnote. Depending on the variable +@code{org-footnote-define-inline}@footnote{The corresponding in-buffer +setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the +definition will be placed right into the text as part of the reference, or +separately into the location determined by the variable +@code{org-footnote-section}. + +When this command is called with a prefix argument, a menu of additional +options is offered: +@example +s @r{Sort the footnote definitions by reference sequence. During editing,} + @r{Org makes no effort to sort footnote definitions into a particular} + @r{sequence. If you want them sorted, use this command, which will} + @r{also move entries according to @code{org-footnote-section}. Automatic} + @r{sorting after each insertion/deletion can be configured using the} + @r{variable @code{org-footnote-auto-adjust}.} +r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering} + @r{after each insertion/deletion can be configured using the variable} + @r{@code{org-footnote-auto-adjust}.} +S @r{Short for first @code{r}, then @code{s} action.} +n @r{Normalize the footnotes by collecting all definitions (including} + @r{inline definitions) into a special section, and then numbering them} + @r{in sequence. The references will then also be numbers. This is} + @r{meant to be the final step before finishing a document (e.g. sending} + @r{off an email). The exporters do this automatically, and so could} + @r{something like @code{message-send-hook}.} +d @r{Delete the footnote at point, and all definitions of and references} + @r{to it.} +@end example +Depending on the variable @code{org-footnote-auto-adjust}@footnote{the +corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.}, +renumbering and sorting footnotes can be automatic after each insertion or +deletion. + +@kindex C-c C-c +@item C-c C-c +If the cursor is on a footnote reference, jump to the definition. If it is a +the definition, jump back to the reference. When called at a footnote +location with a prefix argument, offer the same menu as @kbd{C-c C-x f}. +@kindex C-c C-o +@kindex mouse-1 +@kindex mouse-2 +@item C-c C-o @r{or} mouse-1/2 +Footnote labels are also links to the corresponding definition/reference, and +you can use the usual commands to follow these links. +@end table + +@node Orgstruct mode, , Footnotes, 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 @code{orgstruct-mode} makes +this possible. Toggle the mode with @kbd{M-x orgstruct-mode}, or +turn it on by default, for example in Mail mode, with one of: + +@lisp +(add-hook 'mail-mode-hook 'turn-on-orgstruct) +(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 like a +headline or 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 shadows. When you use +@code{orgstruct++-mode}, Org will also export indentation and autofill +settings into that mode, and detect item context after the first line of an +item. + +@node Tables, Hyperlinks, Document Structure, Top +@chapter Tables +@cindex tables +@cindex editing tables + +Org comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported using the Emacs @file{calc} package +@ifinfo +(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}). +@end ifinfo +@ifnotinfo +(see the Emacs Calculator manual for more information about the Emacs +calculator). +@end ifnotinfo + +@menu +* Built-in table editor:: Simple tables +* Column width and alignment:: Overrule the automatic settings +* Column groups:: Grouping to trigger vertical lines +* Orgtbl mode:: The table editor as minor mode +* The spreadsheet:: The table editor has spreadsheet capabilities +* Org-Plot:: Plotting from org tables +@end menu + +@node Built-in table editor, Column width and alignment, Tables, Tables +@section The built-in table editor +@cindex table editor, built-in + +Org 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. Even faster would be to type @code{|Name|Phone|Age} followed by +@kbd{C-c @key{RET}}. + +@vindex org-enable-table-editor +@vindex org-table-auto-blank-field +When typing text into a field, Org 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} +@orgcmd{C-c |,org-table-create-or-convert-from-region} +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 every line contains a comma, comma-separated values (CSV) are assumed. +If not, lines are split at whitespace into fields. You can use a prefix +argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u +C-u} forces TAB, and a numeric argument N indicates that at least N +consecutive spaces, or alternatively a TAB will be the separator. +@* +If there is no active region, this command creates an empty Org +table. But it's easier just to start typing, like +@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}. + +@tsubheading{Re-aligning and field motion} +@orgcmd{C-c C-c,org-table-align} +Re-align the table without moving the cursor. +@c +@orgcmd{<TAB>,org-table-next-field} +Re-align the table, move to the next field. Creates a new row if +necessary. +@c +@orgcmd{S-@key{TAB},org-table-previous-field} +Re-align, move to previous field. +@c +@orgcmd{@key{RET},org-table-next-row} +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. +@c +@orgcmd{M-a,org-table-beginning-of-field} +Move to beginning of the current table field, or on to the previous field. +@orgcmd{M-e,org-table-end-of-field} +Move to end of the current table field, or on to the next field. + +@tsubheading{Column and row editing} +@orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right} +Move the current column left/right. +@c +@orgcmd{M-S-@key{left},org-table-delete-column} +Kill the current column. +@c +@orgcmd{M-S-@key{right},org-table-insert-column} +Insert a new column to the left of the cursor position. +@c +@orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down} +Move the current row up/down. +@c +@orgcmd{M-S-@key{up},org-table-kill-row} +Kill the current row or horizontal line. +@c +@orgcmd{M-S-@key{down},org-table-insert-row} +Insert a new row above the current row. With a prefix argument, the line is +created below the current one. +@c +@orgcmd{C-c -,org-table-insert-hline} +Insert a horizontal line below current row. With a prefix argument, the line +is created above the current line. +@c +@orgcmd{C-c @key{RET},org-table-hline-and-move} +Insert a horizontal line below current row, and move the cursor into the row +below that line. +@c +@orgcmd{C-c ^,org-table-sort-lines} +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} +@orgcmd{C-c C-x M-w,org-table-copy-region} +Copy a rectangular region from a table to a special clipboard. Point and +mark determine edge fields of the rectangle. If there is no active region, +copy just the current field. The process ignores horizontal separator lines. +@c +@orgcmd{C-c C-x C-w,org-table-cut-region} +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 +@orgcmd{C-c C-x C-y,org-table-paste-rectangle} +Paste a rectangular region into a table. +The upper left 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 +@orgcmd{M-@key{RET},org-table-wrap-region} +Split the current field at the cursor position and move the rest to the line +below. 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 numeric prefix argument may be used to change the number +of desired lines. If there is no region, but you specify a prefix argument, +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 +@orgcmd{C-c +,org-table-sum} +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 +@orgcmd{S-@key{RET},org-table-copy-down} +@vindex org-table-copy-increment +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. Integers that are too large will not +be incremented. Also, a @code{0} prefix argument temporarily disables the +increment. This key is also used by shift-selection and related modes +(@pxref{Conflicts}). + +@tsubheading{Miscellaneous} +@orgcmd{C-c `,org-table-edit-field} +Edit the current field in a separate window. This is useful for fields that +are not fully visible (@pxref{Column width and alignment}). When called with +a @kbd{C-u} prefix, just make the full field visible, so that it can be +edited in place. +@c +@item M-x org-table-import +Import a file as a table. The table should be TAB or whitespace +separated. Use, for example, to import a spreadsheet 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. +@orgcmd{C-c |,org-table-create-or-convert-from-region} +Tables can also be imported by pasting tabular text into the Org +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 +@findex org-table-export +@vindex org-table-export-default-format +Export the table, by default as a TAB-separated file. Use for data +exchange with, for example, spreadsheet or database programs. The format +used to export the file can be configured in the variable +@code{org-table-export-default-format}. You may also use properties +@code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file +name and the format for table export in a subtree. Org supports quite +general formats for exported tables. The exporter format is the same as the +format used by Orgtbl radio tables, see @ref{Translator functions}, for a +detailed description. +@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 Column width and alignment, Column groups, Built-in table editor, Tables +@section Column width and alignment +@cindex narrow columns in tables +@cindex alignment in tables + +The width of columns is automatically determined by the table editor. And +also the alignment of a column is determined automatically from the fraction +of number-like versus non-number fields in the column. + +Sometimes a single field or a few fields need to carry more text, leading to +inconveniently wide columns. Or maybe you want to make a table with several +columns having a fixed width, regardless of content. To set@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 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 but is hidden. +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}. + +@vindex org-startup-align-all-tables +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 + +If you would like to overrule the automatic alignment of number-rich columns +to the right and of string-rich column to the left, you can use @samp{<r>}, +@samp{c}@footnote{Centering does not work inside Emacs, but it does have an +effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may +also combine alignment and field width like this: @samp{<l10>}. + +Lines which only contain these formatting cookies will be removed +automatically when exporting the document. + +@node Column groups, Orgtbl mode, Column width and alignment, Tables +@section Column groups +@cindex grouping columns in tables + +When Org 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 column 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: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1))) +@end example + +It is also sufficient to just insert the column group starters after +every vertical line you would 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 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 @LaTeX{} tables with the underlying ease and power of +Orgtbl mode, including spreadsheet capabilities. For details, see +@ref{Tables in arbitrary syntax}. + +@node The spreadsheet, Org-Plot, 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's implementation +is not identical to other spreadsheets. For example, Org 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. There is +also a formula debugger, and a formula editor with features for highlighting +fields in the table corresponding to the references at the point in the +formula, moving these references by arrow keys + +@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, 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's @code{B3} behaves like @code{$B$3} in other spreadsheets. + +@noindent +Org also uses another, more general operator that looks like this: +@example +@@@var{row}$@var{column} +@end example + +@noindent +Column references can be absolute like @samp{1}, @samp{2},...@samp{@var{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{@var{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@footnote{Note that only +hlines are counted that @emph{separate} table lines. If the table +starts with a hline above the header, it does not count.}, @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. + +@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'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'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. + +As a special case, references like @samp{$LR5} and @samp{$LR12} can be used +to refer in a stable way to the 5th and 12th field in the last row of the +table. + +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 Field coordinates in formulas +@cindex field coordinates +@cindex coordinates, of field +@cindex row, of field coordinates +@cindex column, of field coordinates + +For Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used to +get the row or column number of the field where the formula result goes. +The traditional Lisp formula equivalents are @code{org-table-current-dline} +and @code{org-table-current-column}. Examples: + +@example +if(@@# % 2, $#, string("")) @r{column number on odd lines only} +$3 = remote(FOO, @@@@#$2) @r{copy column 2 from table FOO into} + @r{column 3 of the current table} +@end example + +@noindent For the second example, table FOO must have at least as many rows +as the current table. Inefficient@footnote{The computation time scales as +O(N^2) because table FOO is parsed for each field to be copied.} for large +number of rows. + +@subsubheading Named references +@cindex named references +@cindex references, named +@cindex name, of column or field +@cindex constants, in calculations +@cindex #+CONSTANTS + +@vindex org-table-formula-constants +@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 +@vindex constants-unit-system +@pindex constants.el +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{constants.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. + +@subsubheading Remote references +@cindex remote references +@cindex references, remote +@cindex references, to a different table +@cindex name, of column or field +@cindex constants, in calculations +@cindex #+TBLNAME + +You may also reference constants, fields and ranges from a different table, +either in the current file or even in a different file. The syntax is + +@example +remote(NAME-OR-ID,REF) +@end example + +@noindent +where NAME can be the name of a table in the current file as set by a +@code{#+TBLNAME: NAME} line before the table. It can also be the ID of an +entry, even in a different file, and the reference then refers to the first +table in that entry. REF is an absolute field or range reference as +described above for example @code{@@3$3} or @code{$somename}, valid in the +referenced table. + +@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} +@vindex org-calc-default-modes +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 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 8)} to keep tables +compact. The default settings can be configured using the variable +@code{org-calc-default-modes}. + +@example +p20 @r{set the internal Calc calculation precision to 20 digits} +n3 s3 e2 f4 @r{Normal, scientific, engineering, or fixed} + @r{format of the result of Calc passed back to Org.} + @r{Calc formatting is unlimited in precision as} + @r{long as the Calc calculation precision is greater.} +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} +L @r{literal} +@end example + +@noindent +Unless you use large integer numbers or high-precision-calculation +and -display for floating point numbers you may alternatively provide a +@code{printf} format specifier to reformat the Calc result after it has been +passed back to Org instead of letting Calc already do the +formatting@footnote{The @code{printf} reformatting is limited in precision +because the value passed to it is converted into an @code{integer} or +@code{double}. The @code{integer} is limited in size by truncating the +signed value to 32 bits. The @code{double} is limited in precision to 64 +bits overall which leaves approximately 16 significant decimal digits.}. +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 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 conscious 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, enclose 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. Here are 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 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. + +@cindex #+TBLFM +Formulas are stored in a special line starting with @samp{#+TBLFM:} +directly below the table. If you type 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 course this is not true if you edit the table structure +with normal editing commands---then you must fix the equations yourself. +The left-hand side of a formula may also be a named field (@pxref{Advanced +features}), or a last-row reference like @samp{$LR3}. + +Instead of typing an equation into the field, you may also use the +following command + +@table @kbd +@orgcmd{C-u C-c =,org-table-eval-formula} +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 allows you 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 will only remember the most recently used formula. In the +@samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The left-hand +side of a column formula cannot currently be the name of column, it +must be the numeric column reference. + +Instead of typing an equation into the field, you may also use the +following command: + +@table @kbd +@orgcmd{C-c =,org-table-eval-formula} +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 numeric prefix argument(e.g. @kbd{C-5 C-c =}) the command +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 + +@vindex org-table-use-standard-references +You can edit individual formulas in the minibuffer or directly in the +field. Org can also prepare a special buffer with all active +formulas of a table. When offering a formula for editing, Org +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 +@orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula} +Edit the formula associated with the current column/field in the +minibuffer. See @ref{Column formulas}, and @ref{Field formulas}. +@orgcmd{C-u C-u C-c =,org-table-eval-formula} +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 ?}. +@orgcmd{C-c ?,org-table-field-info} +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 @} +@findex org-table-toggle-coordinate-overlays +@item C-c @} +Toggle the display of row and column numbers for a table, using overlays +(@command{org-table-toggle-coordinate-overlays}). These are updated each +time the table is aligned; you can force it with @kbd{C-c C-c}. +@kindex C-c @{ +@findex org-table-toggle-formula-debugger +@item C-c @{ +Toggle the formula debugger on and off +(@command{org-table-toggle-formula-debugger}). See below. +@orgcmd{C-c ',org-table-edit-formulas} +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 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 +@orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish} +Exit the formula editor and store the modified formulas. With @kbd{C-u} +prefix, also apply the new formulas to the entire table. +@orgcmd{C-c C-q,org-table-fedit-abort} +Exit the formula editor without installing changes. +@orgcmd{C-c C-r,org-table-fedit-toggle-ref-type} +Toggle all references in the formula editor between standard (like +@code{B3}) and internal (like @code{@@3$2}). +@orgcmd{@key{TAB},org-table-fedit-lisp-indent} +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. +@orgcmd{M-@key{TAB},lisp-complete-symbol} +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} +@findex org-table-fedit-ref-up +@findex org-table-fedit-ref-down +@findex org-table-fedit-ref-left +@findex org-table-fedit-ref-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. +@orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down} +Move the test line for column formulas in the Org buffer up and +down. +@orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up} +Scroll the window displaying the table. +@kindex C-c @} +@findex org-table-toggle-coordinate-overlays +@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-automatic. + +In order to recalculate a line of a table or the entire table, use the +following commands: + +@table @kbd +@orgcmd{C-c *,org-table-recalculate} +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 +@orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate} +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. +@item M-x org-table-recalculate-buffer-tables +@findex org-table-recalculate-buffer-tables +Recompute all tables in the current buffer. +@item M-x org-table-iterate-buffer-tables +@findex org-table-iterate-buffer-tables +Iterate all tables in the current buffer, in order to converge table-to-table +dependencies. +@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 +@orgcmd{C-#,org-table-rotate-recalc-marks} +Rotate the calculation mark in first column through the states @samp{ }, +@samp{#}, @samp{*}, @samp{!}, @samp{$}. 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 | +| # | 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 or column group markers. +@end table + +Finally, just to whet your appetite for what can be done with the +fantastic @file{calc.el} package, here is a table that computes the Taylor +series of degree @code{n} at location @code{x} for a couple of +functions. + +@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 Org-Plot, , The spreadsheet, Tables +@section Org-Plot +@cindex graph, in tables +@cindex plot tables using Gnuplot +@cindex #+PLOT + +Org-Plot can produce 2D and 3D graphs of information stored in org tables +using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode} +@uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}. To see +this in action, ensure that you have both Gnuplot and Gnuplot mode installed +on your system, then call @code{org-plot/gnuplot} on the following table. + +@example +@group +#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]" +| Sede | Max cites | H-index | +|-----------+-----------+---------| +| Chile | 257.72 | 21.39 | +| Leeds | 165.77 | 19.68 | +| Sao Paolo | 71.00 | 11.50 | +| Stockholm | 134.19 | 14.33 | +| Morelia | 257.56 | 17.67 | +@end group +@end example + +Notice that Org Plot is smart enough to apply the table's headers as labels. +Further control over the labels, type, content, and appearance of plots can +be exercised through the @code{#+PLOT:} lines preceding a table. See below +for a complete list of Org-plot options. For more information and examples +see the Org-plot tutorial at +@uref{http://orgmode.org/worg/org-tutorials/org-plot.php}. + +@subsubheading Plot Options + +@table @code +@item set +Specify any @command{gnuplot} option to be set when graphing. + +@item title +Specify the title of the plot. + +@item ind +Specify which column of the table to use as the @code{x} axis. + +@item deps +Specify the columns to graph as a Lisp style list, surrounded by parentheses +and separated by spaces for example @code{dep:(3 4)} to graph the third and +fourth columns (defaults to graphing all other columns aside from the @code{ind} +column). + +@item type +Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}. + +@item with +Specify a @code{with} option to be inserted for every col being plotted +(e.g. @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...). +Defaults to @code{lines}. + +@item file +If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}. + +@item labels +List of labels to be used for the @code{deps} (defaults to the column headers +if they exist). + +@item line +Specify an entire line to be inserted in the Gnuplot script. + +@item map +When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a +flat mapping rather than a @code{3d} slope. + +@item timefmt +Specify format of Org-mode timestamps as they will be parsed by Gnuplot. +Defaults to @samp{%Y-%m-%d-%H:%M:%S}. + +@item script +If you want total control, you can specify a script file (place the file name +between double-quotes) which will be used to plot. Before plotting, every +instance of @code{$datafile} in the specified script will be replaced with +the path to the generated data file. Note: even if you set this option, you +may still want to specify the plot type, as that can impact the content of +the data file. +@end table + +@node Hyperlinks, TODO Items, Tables, Top +@chapter Hyperlinks +@cindex hyperlinks + +Like HTML, Org provides links inside a file, external links to +other files, Usenet articles, emails, and much more. + +@menu +* Link format:: How links in Org 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:: 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 +@end menu + +@node Link format, Internal links, Hyperlinks, Hyperlinks +@section Link format +@cindex link format +@cindex format, of links + +Org 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 + +@noindent +Once a link in the buffer is complete (all brackets present), Org +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 + +@cindex property, CUSTOM_ID +If the link does not look like a URL, it is considered to be internal in the +current file. The most important case is a link like +@samp{[[#my-custom-id]]} which will link to the entry with the +@code{CUSTOM_ID} property @samp{my-custom-id}. Such custom IDs are very good +for HTML export (@pxref{HTML export}) where they produce pretty section +links. You are responsible yourself to make sure these custom IDs are unique +in a 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}). Links to custom IDs will +point to the corresponding headline. The preferred match for a text link is +a @i{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, or in the line directly before the +first headline.}. + +If no dedicated target exists, Org will search for a headline that is exactly +the link text but may also include a TODO keyword and tags@footnote{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.}. In non-Org files, the search will look for the words in the +link text. In the above example the search would be for @samp{my target}. + +Following a link pushes a mark onto Org'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 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 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 IRC 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 supports links to files, websites, Usenet and email messages, +BBDB database entries and links to both IRC conversations and their +logs. 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} +doi:10.1000/182 @r{DOI for an electronic resource} +file:/home/dominik/images/jupiter.jpg @r{file, absolute path} +/home/dominik/images/jupiter.jpg @r{same as above} +file:papers/last.pdf @r{file, relative path} +./papers/last.pdf @r{same as above} +file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine} +/myself@@some.where:papers/last.pdf @r{same as above} +file:sometextfile::NNN @r{file with line number to jump to} +file:projects.org @r{another Org file} +file:projects.org::some words @r{text search in Org file} +file:projects.org::*task title @r{heading search in Org file} +docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN} +id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} +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:R.*Stallman @r{BBDB link (with regexp)} +irc:/irc.com/#emacs/bob @r{IRC link} +info:org:External%20links @r{Info node link (with encoded space)} +shell:ls *.org @r{A shell command} +elisp:org-agenda @r{Interactive Elisp command} +elisp:(find-file-other-frame "Elisp.org") @r{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 square brackets, around links +@cindex plain text external links +Org 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 square brackets. + +@node Handling links, Using links outside Org, External links, Hyperlinks +@section Handling links +@cindex links, handling + +Org provides methods to create a link in the correct syntax, to +insert it into an Org file, and to follow the link. + +@table @kbd +@orgcmd{C-c l,org-store-link} +@cindex storing links +Store a link to the current location. This is a @emph{global} command (you +must create the key binding yourself) which can be used in any buffer to +create a link. The link will be stored for later insertion into an Org +buffer (see below). What kind of link will be created depends on the current +buffer: + +@b{Org-mode buffers}@* +For Org files, if there is a @samp{<<target>>} at the cursor, the link points +to the target. Otherwise it points to the current headline, which will also +be the description. + +@vindex org-link-to-org-use-id +@cindex property, CUSTOM_ID +@cindex property, ID +If the headline has a @code{CUSTOM_ID} property, a link to this custom ID +will be stored. In addition or alternatively (depending on the value of +@code{org-link-to-org-use-id}), a globally unique @code{ID} property will be +created and/or used to construct a link. So using this command in Org +buffers will potentially create two links: a human-readable from the custom +ID, and one that is globally unique and works even if the entry is moved from +file to file. Later, when inserting the link, you need to decide which one +to use. + +@b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@* +Pretty much all Emacs mail clients are supported. The link will point to the +current article, or, in some GNUS buffers, to the group. The description is +constructed from the author and the subject. + +@b{Web browsers: W3 and W3M}@* +Here the link will be the current URL, with the page title as description. + +@b{Contacts: BBDB}@* +Links created in a BBDB buffer will point to the current entry. + +@b{Chat: IRC}@* +@vindex org-irc-link-to-logs +For IRC links, if you set the variable @code{org-irc-link-to-logs} to +@code{t}, a @samp{file:/} style link to the relevant point in the logs for +the current conversation is created. Otherwise an @samp{irc:/} style link to +the user/channel/server under the point will be stored. + +@b{Other files}@* +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}. + +@b{Agenda view}@* +When the cursor is in an agenda view, the created link points to the +entry referenced by the current line. + +@c +@orgcmd{C-c C-l,org-insert-link} +@cindex link completion +@cindex completion, of links +@cindex inserting links +@vindex org-keep-stored-link-after-insertion +Insert a link@footnote{ Note that you don't have to use this command to +insert a link. Links in Org 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.}. 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. 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 argument 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. + +@b{Inserting stored links}@* +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} (or @kbd{M-p/n}). + +@b{Completion support}@* Completion with @key{TAB} will help you to insert +valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes +defined through link abbreviations (@pxref{Link abbreviations}). If you +press @key{RET} after inserting only the @var{prefix}, Org will offer +specific completion support for some link types@footnote{This works by +calling a special function @code{org-PREFIX-complete-link}.} For +example, if you type @kbd{file @key{RET}}, file name completion (alternative +access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb +@key{RET}} you can complete contact names. +@orgkey C-u C-c C-l +@cindex file name completion +@cindex completion, of file names +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 sub-directory 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 +@orgcmd{C-c C-o,org-open-at-point} +@vindex org-file-apps +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 command 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 timestamp, 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. If you want to avoid +opening in Emacs, use a @kbd{C-u C-u} prefix.@* +If the cursor is on a headline, but not on a link, offer all links in the +headline and entry text. +@orgkey @key{RET} +@vindex org-return-follows-link +When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow +the link at point. +@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 and later, @kbd{mouse-1} will also follow a link. +@c +@kindex mouse-3 +@item mouse-3 +@vindex org-display-internal-link-with-indirect-buffer +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 +@orgcmd{C-c C-x C-v,org-toggle-inline-images} +@cindex inlining images +@cindex images, inlining +@vindex org-startup-with-inline-images +@cindex @code{inlineimages}, STARTUP keyword +@cindex @code{noinlineimages}, STARTUP keyword +Toggle the inline display of linked images. Normally this will only inline +images that have no description part in the link, i.e. images that will also +be inlined during export. When called with a prefix argument, also display +images that do have a link description. You can ask for inline images to be +displayed at startup by configuring the variable +@code{org-startup-with-inline-images}@footnote{with corresponding +@code{#+STARTUP} keywords @code{inlineimages} and @code{inlineimages}}. +@orgcmd{C-c %,org-mark-ring-push} +@cindex mark ring +Push the current position onto the mark ring, to be able to return +easily. Commands following an internal link do this automatically. +@c +@orgcmd{C-c &,org-mark-ring-goto} +@cindex links, returning to +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 +@orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link} +@cindex links, finding next/previous +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, Link abbreviations, Handling links, Hyperlinks +@section Using links outside Org + +You can insert and follow links that have Org syntax not only in +Org, 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, 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 +@vindex org-link-abbrev-alist +where the tag is optional. +The @i{linkword} must be a word, starting with a letter, followed by +letters, numbers, @samp{-}, and @samp{_}. 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: + +@smalllisp +@group +(setq org-link-abbrev-alist + '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") + ("google" . "http://www.google.com/search?q=") + ("gmap" . "http://maps.google.com/maps?q=%s") + ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1") + ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST"))) +@end group +@end smalllisp + +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]]}, show the map location of the Free Software +Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office +@code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out +what the Org author is doing besides Emacs hacking with +@code{[[ads:Dominik,C]]}. + +If you need special abbreviations just for a single Org buffer, you +can define them in the file with + +@cindex #+LINK +@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. You may also define a function +@code{org-PREFIX-complete-link} that implements special (e.g. completion) +support for inserting such a link with @kbd{C-c C-l}. Such a function should +not accept any arguments, and return the full link with prefix. + +@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::#my-custom-id]] +[[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 file, restrict search to headlines. +@item #my-custom-id +Link to a heading with a @code{CUSTOM_ID} property +@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, , 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, Bib@TeX{} database files have many entries like +@samp{year="1993"} which would not result in good search strings, +because the only unique identification for a Bib@TeX{} entry is the +citation key. + +@vindex org-create-file-search-functions +@vindex org-execute-file-search-functions +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 actually uses this mechanism +for Bib@TeX{} database files, and you can use the corresponding code as +an implementation example. See the file @file{org-bibtex.el}. + +@node TODO Items, Tags, Hyperlinks, Top +@chapter TODO items +@cindex TODO items + +Org-mode does not maintain TODO lists as separate documents@footnote{Of +course, you can make a document that contains only long lists of TODO items, +but this is not required.}. Instead, TODO items are an integral part of the +notes file, because TODO items usually come up while taking notes! With Org +mode, simply mark any entry in a tree as being a TODO item. In this way, +information is not duplicated, and the entire context from which the TODO +item emerged is always present. + +Of course, this technique for managing TODO items scatters them +throughout your notes file. Org-mode compensates for this by providing +methods to give you an overview of all the things that you have to do. + +@menu +* TODO basics:: Marking and displaying TODO entries +* TODO extensions:: Workflow and assignments +* Progress logging:: Dates and notes for progress +* 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 becomes a TODO item when it starts with the word +@samp{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 +@orgcmd{C-c C-t,org-todo} +@cindex cycling, of TODO states +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}). + +@orgkey{C-u C-c C-t} +Select a specific keyword using completion or (if it has been set up) +the fast selection interface. For the latter, you need to assign keys +to TODO states, see @ref{Per-file keywords}, and @ref{Setting tags}, for +more information. + +@kindex S-@key{right} +@kindex S-@key{left} +@item S-@key{right} @ @r{/} @ S-@key{left} +@vindex org-treat-S-cursor-todo-selection-as-state-change +Select the following/preceding TODO state, similar to cycling. Useful +mostly if more than two TODO states are possible (@pxref{TODO +extensions}). See also @ref{Conflicts}, for a discussion of the interaction +with @code{shift-selection-mode}. See also the variable +@code{org-treat-S-cursor-todo-selection-as-state-change}. +@orgcmd{C-c / t,org-show-todo-key} +@cindex sparse tree, for TODO +@vindex org-todo-keywords +View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the +entire buffer, but shows all TODO items (with not-DONE state) and the +headings hierarchy above them. With a prefix argument (or by using @kbd{C-c +/ T}), 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|...} to list +entries that match any one of these keywords. With numeric prefix argument +N, show the tree for the Nth keyword in the variable +@code{org-todo-keywords}. With two prefix arguments, find all TODO states, +both un-done and done. +@orgcmd{C-c a t,org-todo-list} +Show the global TODO list. Collects the TODO items (with not-DONE states) +from all agenda files (@pxref{Agenda Views}) into a single buffer. The new +buffer will be in @code{agenda-mode}, which provides commands to examine and +manipulate the TODO entries from the new buffer (@pxref{Agenda commands}). +@xref{Global TODO list}, for more information. +@orgcmd{S-M-@key{RET},org-insert-todo-heading} +Insert a new TODO entry below the current one. +@end table + +@noindent +@vindex org-todo-state-tags-triggers +Changing a TODO state can also trigger tag changes. See the docstring of the +option @code{org-todo-state-tags-triggers} for details. + +@node TODO extensions, Progress logging, TODO basics, TODO Items +@section Extended use of TODO keywords +@cindex extended TODO keywords + +@vindex org-todo-keywords +By default, marked TODO entries have one of only two states: TODO and +DONE. Org-mode allows you to classify TODO items in more complex ways +with @emph{TODO keywords} (stored in @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 does the rest +* Multiple sets in one file:: Mixing it all, and still finding your way +* Fast access to TODO states:: Single letter selection of a state +* Per-file keywords:: Different files, different requirements +* Faces for TODO keywords:: Highlighting states +* TODO dependencies:: When one task needs to wait for others +@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 numeric prefix argument to quickly select a specific state. For +example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY. +Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you +define many keywords, you can use in-buffer completion +(@pxref{Completion}) or even a special one-key selection scheme +(@pxref{Fast access to TODO states}) 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 / t}. For example, to see all things +Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items +from all agenda files into a single buffer, you would use the numeric prefix +argument as well when creating the global TODO list: @kbd{C-3 C-c a t}. + +@node Multiple sets in one file, Fast access to TODO states, 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} +@kindex C-u C-u C-c C-t +@item C-u C-u C-c C-t +@itemx 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-u C-u C-c C-t} or @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}. Note that the @kbd{C-S-} key binding conflict with +@code{shift-selection-mode} (@pxref{Conflicts}). +@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. See also +@ref{Conflicts}, for a discussion of the interaction with +@code{shift-selection-mode}. +@end table + +@node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions +@subsection Fast access to TODO states + +If you would like to quickly change an entry to an arbitrary TODO state +instead of cycling through the states, you can set up keys for +single-letter access to the states. This is done by adding the section +key after each keyword, in parentheses. For example: + +@lisp +(setq org-todo-keywords + '((sequence "TODO(t)" "|" "DONE(d)") + (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") + (sequence "|" "CANCELED(c)"))) +@end lisp + +@vindex org-fast-tag-selection-include-todo +If you then press @code{C-c C-t} followed by the selection key, the entry +will be switched to this state. @key{SPC} can be used to remove any TODO +keyword from an entry.@footnote{Check also the variable +@code{org-fast-tag-selection-include-todo}, it allows you to change the TODO +state through the tags interface (@pxref{Setting tags}), in case you like to +mingle the two concepts. Note that this means you need to come up with +unique keys across both sets of keywords.} + +@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions +@subsection Setting up keywords for individual files +@cindex keyword options +@cindex per-file keywords +@cindex #+TODO +@cindex #+TYP_TODO +@cindex #+SEQ_TODO + +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 +#+TODO: TODO FEEDBACK VERIFY | DONE CANCELED +@end example +@noindent (you may also write @code{#+SEQ_TODO} to be explicit about the +interpretation, but it means the same as @code{#+TODO}), or +@example +#+TYP_TODO: Fred Sara Lucy Mike | DONE +@end example + +A setup for using several sets in parallel would be: + +@example +#+TODO: TODO | DONE +#+TODO: REPORT BUG KNOWNCAUSE | FIXED +#+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 Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions +@subsection Faces for TODO keywords +@cindex faces, for TODO keywords + +@vindex org-todo @r{(face)} +@vindex org-done @r{(face)} +@vindex org-todo-keyword-faces +Org-mode highlights TODO keywords with special faces: @code{org-todo} +for keywords indicating that an item still has to be acted upon, and +@code{org-done} for keywords indicating that an item is finished. If +you are using more than 2 different states, you might want to use +special faces for some of them. This can be done using the variable +@code{org-todo-keyword-faces}. For example: + +@lisp +@group +(setq org-todo-keyword-faces + '(("TODO" . org-warning) ("STARTED" . "yellow") + ("CANCELED" . (:foreground "blue" :weight bold)))) +@end group +@end lisp + +While using a list with face properties as shown for CANCELED @emph{should} +work, this does not aways seem to be the case. If necessary, define a +special face and use that. A string is interpreted as a color. The variable +@code{org-faces-easy-properties} determines if that color is interpreted as a +foreground or a background color. + +@node TODO dependencies, , Faces for TODO keywords, TODO extensions +@subsection TODO dependencies +@cindex TODO dependencies +@cindex dependencies, of TODO states + +@vindex org-enforce-todo-dependencies +@cindex property, ORDERED +The structure of Org files (hierarchy and lists) makes it easy to define TODO +dependencies. Usually, a parent TODO task should not be marked DONE until +all subtasks (defined as children tasks) are marked as DONE. And sometimes +there is a logical sequence to a number of (sub)tasks, so that one task +cannot be acted upon before all siblings above it are done. If you customize +the variable @code{org-enforce-todo-dependencies}, Org will block entries +from changing state to DONE while they have children that are not DONE. +Furthermore, if an entry has a property @code{ORDERED}, each of its children +will be blocked until all earlier siblings are marked DONE. Here is an +example: + +@example +* TODO Blocked until (two) is done +** DONE one +** TODO two + +* Parent + :PROPERTIES: + :ORDERED: t + :END: +** TODO a +** TODO b, needs to wait for (a) +** TODO c, needs to wait for (a) and (b) +@end example + +@table @kbd +@orgcmd{C-c C-x o,org-toggle-ordered-property} +@vindex org-track-ordered-property-with-tag +@cindex property, ORDERED +Toggle the @code{ORDERED} property of the current entry. A property is used +for this behavior because this should be local to the current entry, not +inherited like a tag. However, if you would like to @i{track} the value of +this property with a tag for better visibility, customize the variable +@code{org-track-ordered-property-with-tag}. +@orgkey{C-u C-u C-u C-c C-t} +Change TODO state, circumventing any state blocking. +@end table + +@vindex org-agenda-dim-blocked-tasks +If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries +that cannot be closed because of such dependencies will be shown in a dimmed +font or even made invisible in agenda views (@pxref{Agenda Views}). + +@cindex checkboxes and TODO dependencies +@vindex org-enforce-todo-dependencies +You can also block changes of TODO states by looking at checkboxes +(@pxref{Checkboxes}). If you set the variable +@code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked +checkboxes will be blocked from switching to DONE. + +If you need more complex dependency structures, for example dependencies +between entries in different trees or files, check out the contributed +module @file{org-depend.el}. + +@page +@node Progress logging, Priorities, TODO extensions, TODO Items +@section Progress logging +@cindex progress logging +@cindex logging, of progress + +Org-mode can automatically record a timestamp and possibly a note when +you mark a TODO item as DONE, or even each time you change the state of +a TODO item. This system is highly configurable, settings can be on a +per-keyword basis and can be localized to a file or even a subtree. For +information on how to clock working time for a task, see @ref{Clocking +work time}. + +@menu +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +* Tracking your habits:: How consistent have you been? +@end menu + +@node Closing items, Tracking TODO state changes, Progress logging, Progress logging +@subsection Closing items + +The most basic logging is to keep track of @emph{when} a certain TODO +item was finished. This is achieved with@footnote{The corresponding +in-buffer setting is: @code{#+STARTUP: logdone}} + +@lisp +(setq org-log-done 'time) +@end lisp + +@noindent +Then each time you turn an entry from a TODO (not-done) state into any +of the DONE states, 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. 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 'note) +@end lisp + +@noindent +You will then be prompted for a note, and that note will be stored below +the entry with a @samp{Closing Note} heading. + +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 with a @samp{CLOSED} timestamp on each day, +giving you an overview of what has been done. + +@node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging +@subsection Tracking TODO state changes +@cindex drawer, for state change recording + +@vindex org-log-states-order-reversed +@vindex org-log-into-drawer +@cindex property, LOG_INTO_DRAWER +When TODO keywords are used as workflow states (@pxref{Workflow states}), you +might want to keep track of when a state change occurred and maybe take a +note about this change. You can either record just a timestamp, or a +time-stamped note for a change. These records will be inserted after the +headline as an itemized list, newest first@footnote{See the variable +@code{org-log-states-order-reversed}}. When taking a lot of notes, you might +want to get the notes out of the way into a drawer (@pxref{Drawers}). +Customize the variable @code{org-log-into-drawer} to get this +behavior---the recommended drawer for this is called @code{LOGBOOK}. You can +also overrule the setting of this variable for a subtree by setting a +@code{LOG_INTO_DRAWER} property. + +Since it is normally too much to record a note for every state, Org-mode +expects configuration on a per-keyword basis for this. This is achieved by +adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note) +in parentheses after each keyword. For example, with the setting + +@lisp +(setq org-todo-keywords + '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)"))) +@end lisp + +@noindent +@vindex org-log-done +you not only define global TODO keywords and fast access keys, but also +request that a time is recorded when the entry is set to +DONE@footnote{It is possible that Org-mode will record two timestamps +when you are using both @code{org-log-done} and state change logging. +However, it will never prompt for two notes---if you have configured +both, the state change recording note will take precedence and cancel +the @samp{Closing Note}.}, and that a note is recorded when switching to +WAIT or CANCELED. The setting for WAIT is even more special: the +@samp{!} after the slash means that in addition to the note taken when +entering the state, a timestamp should be recorded when @i{leaving} the +WAIT state, if and only if the @i{target} state does not configure +logging for entering it. So it has no effect when switching from WAIT +to DONE, because DONE is configured to record a timestamp only. But +when switching from WAIT back to TODO, the @samp{/!} in the WAIT +setting now triggers a timestamp even though TODO has no logging +configured. + +You can use the exact same syntax for setting logging preferences local +to a buffer: +@example +#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) +@end example + +@cindex property, LOGGING +In order to define logging settings that are local to a subtree or a +single item, define a LOGGING property in this entry. Any non-empty +LOGGING property resets all logging settings to nil. You may then turn +on logging for this specific tree using STARTUP keywords like +@code{lognotedone} or @code{logrepeat}, as well as adding state specific +settings like @code{TODO(!)}. For example + +@example +* TODO Log each state with only a time + :PROPERTIES: + :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!) + :END: +* TODO Only log when switching to WAIT, and when repeating + :PROPERTIES: + :LOGGING: WAIT(@@) logrepeat + :END: +* TODO No logging at all + :PROPERTIES: + :LOGGING: nil + :END: +@end example + +@node Tracking your habits, , Tracking TODO state changes, Progress logging +@subsection Tracking your habits +@cindex habits + +Org has the ability to track the consistency of a special category of TODOs, +called ``habits''. A habit has the following properties: + +@enumerate +@item +You have enabled the @code{habits} module by customizing the variable +@code{org-modules}. +@item +The habit is a TODO, with a TODO keyword representing an open state. +@item +The property @code{STYLE} is set to the value @code{habit}. +@item +The TODO has a scheduled date, usually with a @code{.+} style repeat +interval. A @code{++} style may be appropriate for habits with time +constraints, e.g., must be done on weekends, or a @code{+} style for an +unusual habit that can have a backlog, e.g., weekly reports. +@item +The TODO may also have minimum and maximum ranges specified by using the +syntax @samp{.+2d/3d}, which says that you want to do the task at least every +three days, but at most every two days. +@item +You must also have state logging for the @code{DONE} state enabled, in order +for historical data to be represented in the consistency graph. If it's not +enabled it's not an error, but the consistency graphs will be largely +meaningless. +@end enumerate + +To give you an idea of what the above rules look like in action, here's an +actual habit with some history: + +@example +** TODO Shave + SCHEDULED: <2009-10-17 Sat .+2d/4d> + - State "DONE" from "TODO" [2009-10-15 Thu] + - State "DONE" from "TODO" [2009-10-12 Mon] + - State "DONE" from "TODO" [2009-10-10 Sat] + - State "DONE" from "TODO" [2009-10-04 Sun] + - State "DONE" from "TODO" [2009-10-02 Fri] + - State "DONE" from "TODO" [2009-09-29 Tue] + - State "DONE" from "TODO" [2009-09-25 Fri] + - State "DONE" from "TODO" [2009-09-19 Sat] + - State "DONE" from "TODO" [2009-09-16 Wed] + - State "DONE" from "TODO" [2009-09-12 Sat] + :PROPERTIES: + :STYLE: habit + :LAST_REPEAT: [2009-10-19 Mon 00:36] + :END: +@end example + +What this habit says is: I want to shave at most every 2 days (given by the +@code{SCHEDULED} date and repeat interval) and at least every 4 days. If +today is the 15th, then the habit first appears in the agenda on Oct 17, +after the minimum of 2 days has elapsed, and will appear overdue on Oct 19, +after four days have elapsed. + +What's really useful about habits is that they are displayed along with a +consistency graph, to show how consistent you've been at getting that task +done in the past. This graph shows every day that the task was done over the +past three weeks, with colors for each day. The colors used are: + +@table @code +@item Blue +If the task wasn't to be done yet on that day. +@item Green +If the task could have been done on that day. +@item Yellow +If the task was going to be overdue the next day. +@item Red +If the task was overdue on that day. +@end table + +In addition to coloring each day, the day is also marked with an asterisk if +the task was actually done that day, and an exclamation mark to show where +the current day falls in the graph. + +There are several configuration variables that can be used to change the way +habits are displayed in the agenda. + +@table @code +@item org-habit-graph-column +The buffer column at which the consistency graph should be drawn. This will +overwrite any text in that column, so it's a good idea to keep your habits' +titles brief and to the point. +@item org-habit-preceding-days +The amount of history, in days before today, to appear in consistency graphs. +@item org-habit-following-days +The number of days after today that will appear in consistency graphs. +@item org-habit-show-habits-only-for-today +If non-nil, only show habits in today's agenda view. This is set to true by +default. +@end table + +Lastly, pressing @kbd{K} in the agenda buffer will cause habits to +temporarily be disabled and they won't appear at all. Press @kbd{K} again to +bring them back. They are also subject to tag filtering, if you have habits +which should only be done in certain contexts, for example. + +@node Priorities, Breaking down tasks, Progress logging, TODO Items +@section Priorities +@cindex priorities + +If you use Org-mode extensively, you may end up with enough TODO items that +it starts to make sense to prioritize them. Prioritizing can be done by +placing a @emph{priority cookie} into the headline of a TODO item, like this + +@example +*** TODO [#A] Write letter to Sam Fortune +@end example + +@noindent +@vindex org-priority-faces +By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and +@samp{C}. @samp{A} is the highest priority. An entry without a cookie is +treated just like priority @samp{B}. Priorities make a difference only for +sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they +have no inherent meaning to Org-mode. The cookies can be highlighted with +special faces by customizing the variable @code{org-priority-faces}. + +Priorities can be attached to any outline node; they do not need to be TODO +items. + +@table @kbd +@item @kbd{C-c ,} +@kindex @kbd{C-c ,} +@findex org-priority +Set the priority of the current headline (@command{org-priority}). 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 +@orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down} +@vindex org-priority-start-cycle-with-default +Increase/decrease priority of current headline@footnote{See also the option +@code{org-priority-start-cycle-with-default}.}. Note that these keys are +also used to modify timestamps (@pxref{Creating timestamps}). See also +@ref{Conflicts}, for a discussion of the interaction with +@code{shift-selection-mode}. +@end table + +@vindex org-highest-priority +@vindex org-lowest-priority +@vindex org-default-priority +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): + +@cindex #+PRIORITIES +@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 +@cindex statistics, for TODO items + +@vindex org-agenda-todo-list-sublevels +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}.}. To keep +the overview over the fraction of subtasks that are already completed, insert +either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will +be updated each time the TODO status of a child changes, or when pressing +@kbd{C-c C-c} on the cookie. For example: + +@example +* Organize Party [33%] +** TODO Call people [1/2] +*** TODO Peter +*** DONE Sarah +** TODO Buy food +** DONE Talk to neighbor +@end example + +@cindex property, COOKIE_DATA +If a heading has both checkboxes and TODO children below it, the meaning of +the statistics cookie become ambiguous. Set the property +@code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve +this issue. + +@vindex org-hierarchical-todo-statistics +If you would like to have the statistics cookie count any TODO entries in the +subtree (not just direct children), configure the variable +@code{org-hierarchical-todo-statistics}. To do this for a single subtree, +include the word @samp{recursive} into the value of the @code{COOKIE_DATA} +property. + +@example +* Parent capturing statistics [2/20] + :PROPERTIES: + :COOKIE_DATA: todo recursive + :END: +@end example + +If you would like a TODO entry to automatically change to DONE +when all children are done, you can use the following setup: + +@example +(defun org-summary-todo (n-done n-not-done) + "Switch entry to DONE when all subentries are done, to TODO otherwise." + (let (org-log-done org-log-states) ; turn off logging + (org-todo (if (= n-not-done 0) "DONE" "TODO")))) + +(add-hook 'org-after-todo-statistics-hook 'org-summary-todo) +@end example + + +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 + +@vindex org-list-automatic-rules +Every item in a plain list@footnote{With the exception of description +lists. But you can allow it by modifying @code{org-list-automatic-rules} +accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting +it with the string @samp{[ ]}. This feature is similar to TODO items +(@pxref{TODO Items}), but is 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 use the mouse (thanks to Piotr Zielinski's +@file{org-mouse.el}). + +Here is an example of a checkbox list. + +@example +* TODO Organize party [2/4] + - [-] call people [1/3] + - [ ] Peter + - [X] Sarah + - [ ] Sam + - [X] order food + - [ ] think about what music to play + - [X] talk to the neighbors +@end example + +Checkboxes work hierarchically, so if a checkbox item has children that +are checkboxes, toggling one of the children checkboxes will make the +parent checkbox reflect if none, some, or all of the children are +checked. + +@cindex statistics, for checkboxes +@cindex checkbox statistics +@cindex property, COOKIE_DATA +@vindex org-hierarchical-checkbox-statistics +The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies +indicating how many checkboxes present in this entry have been checked off, +and the total number of checkboxes present. 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 checkboxes of direct children structurally below the +headline/item on which the cookie appears@footnote{Set the variable +@code{org-hierarchical-checkbox-statistics} if you want such cookies to +represent the all checkboxes below the cookie, not just the direct +children.}. You have to insert the cookie yourself by typing either +@samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m} +result, as in the examples above. With @samp{[%]} you get information about +the percentage of checkboxes checked (in the above example, this would be +@samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie can +count either checkboxes below the heading or TODO states of children, and it +will display whatever was changed last. Set the property @code{COOKIE_DATA} +to either @samp{checkbox} or @samp{todo} to resolve this issue. + +@cindex blocking, of checkboxes +@cindex checkbox blocking +@cindex property, ORDERED +If the current outline node has an @code{ORDERED} property, checkboxes must +be checked off in sequence, and an error will be thrown if you try to check +off a box while there are unchecked boxes above it. + +@noindent The following commands work with checkboxes: + +@table @kbd +@orgcmd{C-c C-c,org-toggle-checkbox} +Toggle checkbox status or (with prefix arg) checkbox presence at point. With +double prefix argument, set it to @samp{[-]}, which is considered to be an +intermediate state. +@orgcmd{C-c C-x C-b,org-toggle-checkbox} +Toggle checkbox status or (with prefix arg) checkbox presence at point. With +double prefix argument, set it to @samp{[-]}, which is considered to be an +intermediate state. +@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. With a prefix +arg, add or remove the checkbox for all items in the region. +@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 +@orgcmd{M-S-@key{RET},org-insert-todo-heading} +Insert a new item with a checkbox. +This works only if the cursor is already in a plain list item +(@pxref{Plain lists}). +@orgcmd{C-c C-x o,org-toggle-ordered-property} +@vindex org-track-ordered-property-with-tag +@cindex property, ORDERED +Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must +be checked off in sequence. A property is used for this behavior because +this should be local to the current entry, not inherited like a tag. +However, if you would like to @i{track} the value of this property with a tag +for better visibility, customize the variable +@code{org-track-ordered-property-with-tag}. +@orgcmd{C-c #,org-update-statistics-cookies} +Update the statistics cookie 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}}. TODO statistics cookies update when +changing TODO states. If you delete boxes/entries or add/change them by +hand, use this command to get things back into sync. Or simply toggle any +entry twice (checkboxes 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 + +An excellent way to implement labels and contexts for cross-correlating +information is to assign @i{tags} to headlines. Org-mode has extensive +support for tags. + +@vindex org-tag-faces +Every headline can contain a list of tags; they occur 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, e.g., +@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. +Tags will by default be in bold face with the same color as the headline. +You may specify special faces for specific tags using the variable +@code{org-tag-faces}, in much the same way as you can for TODO keywords +(@pxref{Faces for TODO keywords}). + +@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 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:} even though the final heading is not +explicitly marked with those tags. You can also set tags that all entries in +a file should inherit just as if these tags were defined in a hypothetical +level zero that surrounds the entire file. Use a line like this@footnote{As +with all these in-buffer settings, pressing @kbd{C-c C-c} activates any +changes in the line.}: + +@cindex #+FILETAGS +@example +#+FILETAGS: :Peter:Boss:Secret: +@end example + +@noindent +@vindex org-use-tag-inheritance +@vindex org-tags-exclude-from-inheritance +To limit tag inheritance to specific tags, or to turn it off entirely, use +the variables @code{org-use-tag-inheritance} and +@code{org-tags-exclude-from-inheritance}. + +@vindex org-tags-match-list-sublevels +When a headline matches during a tags search while tag inheritance is turned +on, all the sublevels in the same tree will (for a simple match form) match +as well@footnote{This is only true if the search does not involve more +complex tests including properties (@pxref{Property searches}).}. The list +of matches may then become very long. If you only want to see the first tags +match in a subtree, configure the variable +@code{org-tags-match-list-sublevels} (not recommended). + +@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 +@orgcmd{C-c C-q,org-set-tags-command} +@cindex completion, of tags +@vindex org-tags-column +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}). +@orgcmd{C-c C-c,org-set-tags-command} +When the cursor is in a headline, this does the same as @kbd{C-c C-q}. +@end table + +@vindex org-tag-alist +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 + +@cindex #+TAGS +@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, add an empty TAGS option line to that file: + +@example +#+TAGS: +@end example + +@vindex org-tag-persistent-alist +If you have a preferred set of tags that you would like to use in every file, +in addition to those defined on a per-file basis by TAGS option lines, then +you may specify a list of tags with the variable +@code{org-tag-persistent-alist}. You may turn this off on a per-file basis +by adding a STARTUP option line to that file: + +@example +#+STARTUP: noptag +@end example + +By default Org-mode uses the standard minibuffer completion facilities for +entering tags. However, it also implements another, quicker, tag selection +method called @emph{fast tag selection}. This allows you to select and +deselect tags with just a single key press. For this to work well you should +assign unique letters to most of your commonly used tags. You can do this +globally by configuring the variable @code{org-tag-alist} in your +@file{.emacs} file. For example, you may find the need to tag many items in +different files with @samp{:@@home:}. In this case you can set something +like: + +@lisp +(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) +@end lisp + +@noindent If the tag is only relevant to the file you are working on, then you +can instead set the TAGS option line as: + +@example +#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) +@end example + +@noindent The tags interface will show the available tags in a splash +window. If you want to start a new line after a specific tag, insert +@samp{\n} into the tag list + +@example +#+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p) +@end example + +@noindent or write them in two lines: + +@example +#+TAGS: @@work(w) @@home(h) @@tennisclub(t) +#+TAGS: laptop(l) pc(p) +@end example + +@noindent +You can also group together tags that are mutually exclusive by using +braces, as in: + +@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. Multiple such groups are allowed. + +@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of +these lines to activate any changes. + +@noindent +To set these mutually exclusive groups in the variable @code{org-tags-alist}, +you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead +of the braces. Similarly, you can use @code{:newline} to indicate a line +break. The previous example would be set globally by the following +configuration: + +@lisp +(setq org-tag-alist '((:startgroup . nil) + ("@@work" . ?w) ("@@home" . ?h) + ("@@tennisclub" . ?t) + (:endgroup . nil) + ("laptop" . ?l) ("pc" . ?p))) +@end lisp + +If at least one tag has a selection key then 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 valid 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}}. + +@vindex org-fast-tag-selection-single-key +If you find that most of the time you need only a single key press 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 system of tags has been set up, it can be used to collect related +information into special lists. + +@table @kbd +@orgcmdkkc{C-c / m,C-c \,org-match-sparse-tree} +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. +@orgcmd{C-c a m,org-tags-view} +Create a global list of tag matches from all agenda files. +@xref{Matching tags and properties}. +@orgcmd{C-c a M,org-tags-view} +@vindex org-tags-match-list-sublevels +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 + +These commands all prompt for a match string which allows basic Boolean logic +like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and +@samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries +which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the search +string is rich and allows also matching against TODO keywords, entry levels +and properties. For a complete description with many examples, see +@ref{Matching tags and properties}. + + +@node Properties and Columns, Dates and Times, 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. Second, you can use properties to +implement (very basic) database capabilities in an Org buffer. For +an example of the first application, imagine maintaining a file where +you document bugs and plan releases for a piece of software. Instead of +using tags like @code{:release_1:}, @code{:release_2:}, one can use a +property, say @code{:Release:}, that in different subtrees has different +values, such as @code{1.0} or @code{2.0}. For an example of the second +application of properties, imagine keeping track of your music CDs, +where properties could be things such as the album, artist, date of +release, number of tracks, and so on. + +Properties can be conveniently edited and viewed 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 +* Property inheritance:: Passing values down the tree +* 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 Grammophon + :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" Philips EMI + :END: +@end example + +If you want to set properties that can be inherited by any entry in a +file, use a line like +@cindex property, _ALL +@cindex #+PROPERTY +@example +#+PROPERTY: NDisks_ALL 1 2 3 4 +@end example + +@vindex org-global-properties +Property values set with the global variable +@code{org-global-properties} can be inherited by all entries in all +Org files. + +@noindent +The following commands help to work with properties: + +@table @kbd +@orgcmd{M-@key{TAB},org-complete} +After an initial colon in a line, complete property keys. All keys used +in the current file will be offered as possible completions. +@orgcmd{C-c C-x p,org-set-property} +Set a property. This prompts for a property name and a value. If +necessary, the property drawer is created as well. +@item M-x org-insert-property-drawer +@findex 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. +@orgcmd{C-c C-c,org-property-action} +With the cursor in a property drawer, this executes property commands. +@orgcmd{C-c C-c s,org-set-property} +Set a property in the current entry. Both the property and the value +can be inserted using completion. +@orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value} +Switch property at point to the next/previous allowed value. +@orgcmd{C-c C-c d,org-delete-property} +Remove a property from the current entry. +@orgcmd{C-c C-c D,org-delete-property-globally} +Globally remove a property, from all entries in the current file. +@orgcmd{C-c C-c c,org-compute-property-at-point} +Compute the property at point, using the operator and scope from the +nearest column format definition. +@end table + +@node Special properties, Property searches, Property syntax, Properties and Columns +@section Special properties +@cindex properties, special + +Special properties provide an alternative access method to Org-mode +features, like the TODO state or the priority of an entry, discussed in the +previous chapters. This interface exists so that you can include +these states in a column view (@pxref{Column view}), or to use them in +queries. The following property names are special and should not be +used as keys in the properties drawer: + +@cindex property, special, TODO +@cindex property, special, TAGS +@cindex property, special, ALLTAGS +@cindex property, special, CATEGORY +@cindex property, special, PRIORITY +@cindex property, special, DEADLINE +@cindex property, special, SCHEDULED +@cindex property, special, CLOSED +@cindex property, special, TIMESTAMP +@cindex property, special, TIMESTAMP_IA +@cindex property, special, CLOCKSUM +@cindex property, special, BLOCKED +@c guessing that ITEM is needed in this area; also, should this list be sorted? +@cindex property, special, ITEM +@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.} +CATEGORY @r{The category of an entry.} +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 timestamp, without the angular brackets.} +CLOSED @r{When was this entry closed?} +TIMESTAMP @r{The first keyword-less timestamp in the entry.} +TIMESTAMP_IA @r{The first inactive timestamp in the entry.} +CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}} + @r{must be run first to compute the values.} +BLOCKED @r{"t" if task is currently blocked by children or siblings} +ITEM @r{The content of the entry.} +@end example + +@node Property searches, Property inheritance, Special properties, Properties and Columns +@section Property searches +@cindex properties, searching +@cindex searching, of properties + +To create sparse trees and special lists with selection based on properties, +the same commands are used as for tag searches (@pxref{Tag searches}). +@table @kbd +@orgcmdkkc{C-c / m,C-c \,org-match-sparse-tree} +Create a sparse tree with all matching entries. With a +@kbd{C-u} prefix argument, ignore headlines that are not a TODO line. +@orgcmd{C-c a m,org-tags-view} +Create a global list of tag/property matches from all agenda files. +@xref{Matching tags and properties}. +@orgcmd{C-c a M,org-tags-view} +@vindex org-tags-match-list-sublevels +Create a global list of tag matches from all agenda files, but check +only TODO items and force checking of subitems (see variable +@code{org-tags-match-list-sublevels}). +@end table + +The syntax for the search string is described in @ref{Matching tags and +properties}. + +There is also a special command for creating sparse trees based on a +single property: + +@table @kbd +@orgkey{C-c / p} +Create a sparse tree based on the value of a property. This first +prompts for the name of a property, and then for a value. A sparse tree +is created with all entries that define this property with the given +value. If you enclose the value in curly braces, it is interpreted as +a regular expression and matched against the property values. +@end table + +@node Property inheritance, Column view, Property searches, Properties and Columns +@section Property Inheritance +@cindex properties, inheritance +@cindex inheritance, of properties + +@vindex org-use-property-inheritance +The outline structure of Org-mode documents lends itself to an +inheritance model of properties: if the parent in a tree has a certain +property, the children can inherit this property. Org-mode does not +turn this on by default, because it can slow down property searches +significantly and is often not needed. However, if you find inheritance +useful, you can turn it on by setting the variable +@code{org-use-property-inheritance}. It may be set to @code{t} to make +all properties inherited from the parent, to a list of properties +that should be inherited, or to a regular expression that matches +inherited properties. If a property has the value @samp{nil}, this is +interpreted as an explicit undefine of the property, so that inheritance +search will stop at this value and return @code{nil}. + +Org-mode has a few properties for which inheritance is hard-coded, at +least for the special applications for which they are used: + +@cindex property, COLUMNS +@table @code +@item COLUMNS +The @code{:COLUMNS:} property defines the format of column view +(@pxref{Column view}). It is inherited in the sense that the level +where a @code{:COLUMNS:} property is defined is used as the starting +point for a column view table, independently of the location in the +subtree from where columns view is turned on. +@item CATEGORY +@cindex property, CATEGORY +For agenda view, a category set through a @code{:CATEGORY:} property +applies to the entire subtree. +@item ARCHIVE +@cindex property, ARCHIVE +For archiving, the @code{:ARCHIVE:} property may define the archive +location for the entire subtree (@pxref{Moving subtrees}). +@item LOGGING +@cindex property, LOGGING +The LOGGING property may define logging settings for an entry or a +subtree (@pxref{Tracking TODO state changes}). +@end table + +@node Column view, Property API, Property inheritance, 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 node 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 +* Capturing column view:: A dynamic block for 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 + +@cindex #+COLUMNS +@example +#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO +@end example + +To specify a format that only applies to a specific tree, add a +@code{: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 + %[@var{width}]@var{property}[(@var{title})][@{@var{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 +@var{width} @r{An integer specifying the width of the column in characters.} + @r{If omitted, the width will be determined automatically.} +@var{property} @r{The property that should be edited in this column.} + @r{Special properties representing meta data are allowed here} + @r{as well (@pxref{Special properties})} +@var{title} @r{The header text for the column. If omitted, the property} + @r{name is used.} +@{@var{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.} + @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.} + @{$@} @r{Currency, short for @samp{+;%.2f}.} + @{:@} @r{Sum times, HH:MM, plain numbers are hours.} + @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.} + @{X/@} @r{Checkbox status, @samp{[n/m]}.} + @{X%@} @r{Checkbox status, @samp{[n%]}.} + @{min@} @r{Smallest number in column.} + @{max@} @r{Largest number.} + @{mean@} @r{Arithmetic mean of numbers.} + @{:min@} @r{Smallest time value in column.} + @{:max@} @r{Largest time value.} + @{:mean@} @r{Arithmetic mean of time values.} + @{@@min@} @r{Minimum age (in days/hours/mins/seconds).} + @{@@max@} @r{Maximum age (in days/hours/mins/seconds).} + @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).} + @{est+@} @r{Add low-high estimates.} +@end example + +@noindent +Be aware that you can only have one summary type for any property you +include. Subsequent columns referencing the same property will all display the +same summary information. + +The @code{est+} summary type requires further explanation. It is used for +combining estimates, expressed as low-high ranges. For example, instead +of estimating a particular task will take 5 days, you might estimate it as +5-6 days if you're fairly confident you know how much work is required, or +1-10 days if you don't really know what needs to be done. Both ranges +average at 5.5 days, but the first represents a more predictable delivery. + +When combining a set of such estimates, simply adding the lows and highs +produces an unrealistically wide result. Instead, @code{est+} adds the +statistical mean and variance of the sub-tasks, generating a final estimate +from the sum. For example, suppose you had ten tasks, each of which was +estimated at 0.5 to 2 days of work. Straight addition produces an estimate +of 5 to 20 days, representing what to expect if everything goes either +extremely well or extremely poorly. In contrast, @code{est+} estimates the +full job more realistically, at 10-15 days. + +Here is an example for a complete columns definition, along with allowed +values. + +@example +:COLUMNS: %25ITEM %9Approved(Approved?)@{X@} %Owner %11Status \@footnote{Please note that the COLUMNS definition must be on a single line---it is wrapped here only because of formatting constraints.} + %10Time_Estimate@{:@} %CLOCKSUM +:Owner_ALL: Tammy Mark Karl Lisa Don +:Status_ALL: "In progress" "Not started yet" "Finished" "" +:Approved_ALL: "[ ]" "[X]" +@end example + +@noindent +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 @samp{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_Estimate} 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. The +@samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervals +in the subtree. + +@node Using column view, Capturing column view, Defining columns, Column view +@subsection Using column view + +@table @kbd +@tsubheading{Turning column view on and off} +@orgcmd{C-c C-x C-c,org-columns} +@vindex org-columns-default-format +Turn on column view. If the cursor is before the first headline in the file, +column view is turned on for the entire file, using the @code{#+COLUMNS} +definition. If the cursor is somewhere inside the outline, 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 tree starting at the entry that contains the @code{:COLUMNS:} +property. If no such property 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. +@orgcmd{r,org-columns-redo} +Recreate the column view, to include recent changes made in the buffer. +@orgcmd{g,org-columns-redo} +Same as @kbd{r}. +@orgcmd{q,org-columns-quit} +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. +@item 1..9,0 +Directly select the Nth allowed value, @kbd{0} selects the 10th value. +@orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value} +Same as @kbd{S-@key{left}/@key{right}} +@orgcmd{e,org-columns-edit-value} +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. +@orgcmd{C-c C-c,org-columns-set-tags-or-toggle} +When there is a checkbox at point, toggle it. +@orgcmd{v,org-columns-show-value} +View the full value of this property. This is useful if the width of +the column is smaller than that of the value. +@orgcmd{a,org-columns-edit-allowed} +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} +@orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen} +Make the column narrower/wider by one character. +@orgcmd{S-M-@key{right},org-columns-new} +Insert a new column, to the left of the current column. +@orgcmd{S-M-@key{left},org-columns-delete} +Delete the current column. +@end table + +@node Capturing column view, , Using column view, Column view +@subsection Capturing column view + +Since column view is just an overlay over a buffer, it cannot be +exported or printed directly. If you want to capture a column view, use +a @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame +of this block looks like this: + +@cindex #+BEGIN, columnview +@example +* The column view +#+BEGIN: columnview :hlines 1 :id "label" + +#+END: +@end example + +@noindent This dynamic block has the following parameters: + +@table @code +@item :id +This is the most important parameter. Column view is a feature that is +often localized to a certain (sub)tree, and the capture block might be +at a different location in the file. To identify the tree whose view to +capture, you can use 4 values: +@cindex property, ID +@example +local @r{use the tree in which the capture block is located} +global @r{make a global view, including all headings in the file} +"file:@var{path-to-file}" + @r{run column view at the top of this file} +"@var{ID}" @r{call column view in the tree that has an @code{:ID:}} + @r{property with the value @i{label}. You can use} + @r{@kbd{M-x org-id-copy} to create a globally unique ID for} + @r{the current entry and copy it to the kill-ring.} +@end example +@item :hlines +When @code{t}, insert an hline after every line. When a number @var{N}, insert +an hline before each headline with level @code{<= @var{N}}. +@item :vlines +When set to @code{t}, force column groups to get vertical lines. +@item :maxlevel +When set to a number, don't capture entries below this level. +@item :skip-empty-rows +When set to @code{t}, skip rows where the only non-empty specifier of the +column view is @code{ITEM}. + +@end table + +@noindent +The following commands insert or update the dynamic block: + +@table @kbd +@orgcmd{C-c C-x i,org-insert-columns-dblock} +Insert a dynamic block capturing a column view. You will be prompted +for the scope or ID of the view. +@orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update} +Update dynamic block at point. The cursor needs to be in the +@code{#+BEGIN} line of the dynamic block. +@orgcmd{C-u C-c C-x C-u,org-update-all-dblocks} +Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if +you have several clock table blocks, column-capturing blocks or other dynamic +blocks in a buffer. +@end table + +You can add formulas to the column view table and you may add plotting +instructions in front of the table---these will survive an update of the +block. If there is a @code{#+TBLFM:} after the table, the table will +actually be recalculated automatically after an update. + +An alternative way to capture and process property values into a table is +provided by Eric Schulte's @file{org-collector.el} which is a contributed +package@footnote{Contributed packages are not part of Emacs, but are +distributed with the main distribution of Org (visit +@uref{http://orgmode.org}).}. It provides a general API to collect +properties from entries in a certain scope, and arbitrary Lisp expressions to +process these values before inserting them into a table or a dynamic block. + +@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 Dates and Times, Capture - Refile - Archive, Properties and Columns, Top +@chapter Dates and times +@cindex dates +@cindex times +@cindex timestamp +@cindex date stamp + +To assist project planning, TODO items can be labeled with a date and/or +a time. The specially formatted string carrying the date and time +information is called a @emph{timestamp} in Org-mode. This may be a +little confusing because timestamp is often used as indicating when +something was created or last changed. However, in Org-mode this term +is used in a much wider sense. + +@menu +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task +* Effort estimates:: Planning work effort in advance +* Relative timer:: Notes with a running timer +* Countdown timer:: Starting a countdown timer for a task +@end menu + + +@node Timestamps, Creating timestamps, Dates and Times, Dates and Times +@section Timestamps, deadlines, and scheduling +@cindex timestamps +@cindex ranges, time +@cindex date stamps +@cindex deadlines +@cindex scheduling + +A timestamp is a specification of a date (possibly with a 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 inspired by the standard ISO 8601 date/time +format. To use an alternative format, see @ref{Custom time format}.}. A +timestamp 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 timestamp; Event; Appointment +@cindex timestamp +A simple timestamp just assigns a date/time to an item. This is just +like writing down an appointment or event in a paper agenda. In the +timeline and agenda displays, the headline of an entry associated with a +plain timestamp 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 Timestamp with repeater interval +@cindex timestamp, with repeater interval +A timestamp 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 timestamps 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 timestamp +@cindex timestamp, inactive +@cindex inactive timestamp +Just like a plain timestamp, but with square brackets instead of +angular ones. These timestamps 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, Timestamps, Dates and Times +@section Creating timestamps +@cindex creating timestamps +@cindex timestamps, creating + +For Org-mode to recognize timestamps, they need to be in the specific +format. All commands listed below produce timestamps in the correct +format. + +@table @kbd +@orgcmd{C-c .,org-time-stamp} +Prompt for a date and insert a corresponding timestamp. When the cursor is +at an existing timestamp in the buffer, the command is used to modify this +timestamp instead of inserting a new one. When this command is used twice in +succession, a time range is inserted. +@c +@orgcmd{C-c !,org-time-stamp-inactive} +Like @kbd{C-c .}, but insert an inactive timestamp that will not cause +an agenda entry. +@c +@kindex C-u C-c . +@kindex C-u C-c ! +@item C-u C-c . +@itemx C-u C-c ! +@vindex org-time-stamp-rounding-minutes +Like @kbd{C-c .} and @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 +@orgcmd{C-c <,org-date-from-calendar} +Insert a timestamp corresponding to the cursor date in the Calendar. +@c +@orgcmd{C-c >,org-goto-calendar} +Access the Emacs calendar for the current date. If there is a +timestamp in the current line, go to the corresponding date +instead. +@c +@orgcmd{C-c C-o,org-open-at-point} +Access the agenda for the date given by the timestamp or -range at +point (@pxref{Weekly/daily agenda}). +@c +@orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day} +Change date at cursor by one day. These key bindings conflict with +shift-selection and related modes (@pxref{Conflicts}). +@c +@orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down} +Change the item under the cursor in a timestamp. The cursor can be on a +year, month, day, hour or minute. When the timestamp contains a time range +like @samp{15:30-16:30}, modifying the first time will also shift the second, +shifting the time block with constant length. To change the length, modify +the second time. Note that if the cursor is in a headline and not at a +timestamp, these same keys modify the priority of an item. +(@pxref{Priorities}). The key bindings also conflict with shift-selection and +related modes (@pxref{Conflicts}). +@c +@orgcmd{C-c C-y,org-evaluate-time-range} +@cindex evaluate time range +Evaluate a time range by computing the difference between start and end. +With a prefix argument, 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 different +@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 + +@vindex org-read-date-prefer-future +When Org-mode prompts for a date/time, the default is shown in default +date/time format, and the prompt therefore seems to ask for a specific +format. But it will in fact accept any string containing some date and/or +time information, and it is really smart about interpreting your input. 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 derive anything you have not specified from the @emph{default date +and time}. The default is usually the current date and time, but when +modifying an existing timestamp, or when entering the second stamp of a +range, it is taken from the stamp in the buffer. When filling in +information, Org-mode assumes that most of the time you will want to enter a +date in the future: if you omit the month/year and the given day/month is +@i{before} today, it will assume that you mean a future date@footnote{See the +variable @code{org-read-date-prefer-future}. You may set that variable to +the symbol @code{time} to even make a time before now shift the date to +tomorrow.}. If the date has been automatically shifted into the future, the +time prompt will show this with @samp{(=>F).} + +For example, let's assume that today is @b{June 13, 2006}. Here is how +various inputs will be interpreted, the items filled in by Org-mode are +in @b{bold}. + +@example +3-2-5 --> 2003-02-05 +2/5/3 --> 2003-02-05 +14 --> @b{2006}-@b{06}-14 +12 --> @b{2006}-@b{07}-12 +2/5 --> @b{2007}-02-05 +Fri --> nearest Friday (default date or later) +sep 15 --> @b{2006}-09-15 +feb 15 --> @b{2007}-02-15 +sep 12 9 --> 2009-09-12 +12:45 --> @b{2006}-@b{06}-@b{13} 12:45 +22 sept 0:34 --> @b{2006}-09-22 0:34 +w4 --> ISO week for of the current year @b{2006} +2012 w4 fri --> Friday of ISO week 4 in 2012 +2012-w04-5 --> Same as above +@end example + +Furthermore you can specify a relative date by giving, as the +@emph{first} thing in the input: a plus/minus sign, a number and a +letter ([dwmy]) to indicate change in days, weeks, months, or years. With a +single plus or minus, the date is always relative to today. With a +double plus or minus, it is relative to the default date. If instead of +a single letter, you use the abbreviation of day name, the date will be +the Nth such day. E.g. + +@example ++0 --> today +. --> today ++4d --> four days from today ++4 --> same as above ++2w --> two weeks from today +++5 --> five days from default date ++2tue --> second Tuesday from now. +@end example + +@vindex parse-time-months +@vindex parse-time-weekdays +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}. + +You can specify a time range by giving start and end times or by giving a +start time and a duration (in HH:MM format). Use `-' or `-@{@}-' as the separator +in the former case and use '+' as the separator in the latter case. E.g. + +@example +11am-1:15pm --> 11:00-13:15 +11am--1:15pm --> same as above +11am+2:15 --> same as above +@end example + +@cindex calendar, for selecting date +@vindex org-popup-calendar-for-date-prompt +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: + +@kindex < +@kindex > +@kindex M-v +@kindex C-v +@kindex mouse-1 +@kindex S-@key{right} +@kindex S-@key{left} +@kindex S-@key{down} +@kindex S-@key{up} +@kindex M-S-@key{right} +@kindex M-S-@key{left} +@kindex @key{RET} +@example +@key{RET} @r{Choose date at cursor in calendar.} +mouse-1 @r{Select date by clicking on it.} +S-@key{right}/@key{left} @r{One day forward/backward.} +S-@key{down}/@key{up} @r{One week forward/backward.} +M-S-@key{right}/@key{left} @r{One month forward/backward.} +> / < @r{Scroll calendar forward/backward by one month.} +M-v / C-v @r{Scroll calendar forward/backward by 3 months.} +@end example + +@vindex org-read-date-display-live +The actions of the date/time prompt may seem complex, but I assure you they +will grow on you, and you will start getting annoyed by pretty much any other +way of entering a date/time out there. To help you understand what is going +on, the current interpretation of your input will be displayed live in the +minibuffer@footnote{If you find this distracting, turn the display of with +@code{org-read-date-display-live}.}. + +@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 + +@vindex org-display-custom-times +@vindex org-time-stamp-custom-formats +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 +@orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays} +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 timestamp 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 timestamp. 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 timestamp contains a range of clock times or a repeater, these +will not be overlaid, but remain in the buffer as they were. +@item +When you delete a timestamp 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 timestamp 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, Clocking work time, Creating timestamps, Dates and Times +@section Deadlines and scheduling + +A timestamp may be preceded by special keywords to facilitate planning: + +@table @var +@item DEADLINE +@cindex DEADLINE keyword + +Meaning: the task (most likely a TODO item, though not necessarily) is supposed +to be finished on that date. + +@vindex org-deadline-warning-days +On the deadline date, the task will be listed in the agenda. In +addition, the agenda 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 + +Meaning: you are planning to start working on that task on the given +date. + +@vindex org-agenda-skip-scheduled-if-done +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 + +@noindent +@b{Important:} Scheduling an item in Org-mode should @i{not} be +understood in the same way that we understand @i{scheduling a meeting}. +Setting a date for a meeting is just a simple appointment, you should +mark this entry with a simple plain timestamp, to get this item shown +on the date where it applies. This is a frequent misunderstanding by +Org users. In Org-mode, @i{scheduling} means setting a date when you +want to start working on an action item. +@end table + +You may use timestamps with repeaters in scheduling and deadline +entries. Org-mode will issue early and late warnings based on the +assumption that the timestamp represents the @i{nearest instance} of +the repeater. However, the use of diary sexp entries like +@c +@code{<%%(diary-float t 42)>} +@c +in scheduling and deadline timestamps is limited. Org-mode does not +know enough about the internals of each sexp function to issue early and +late warnings. However, it will show the item on each day where the +sexp entry matches. + +@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 deadlines or schedules + +The following commands allow you to quickly insert a deadline or to schedule +an item: + +@table @kbd +@c +@orgcmd{C-c C-d,org-deadline} +Insert @samp{DEADLINE} keyword along with a stamp. The insertion will happen +in the line directly following the headline. When called with a prefix arg, +an existing deadline will be removed from the entry. Depending on the +variable @code{org-log-redeadline}@footnote{with corresponding +@code{#+STARTUP} keywords @code{logredeadline}, @code{lognoteredeadline}, +and @code{nologredeadline}}, a note will be taken when changing an existing +deadline. +@c FIXME Any CLOSED timestamp will be removed.???????? +@c +@orgcmd{C-c C-s,org-schedule} +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. When called with a prefix argument, remove the scheduling +date from the entry. Depending on the variable +@code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP} +keywords @code{logredeadline}, @code{lognoteredeadline}, and +@code{nologredeadline}}, a note will be taken when changing an existing +scheduling time. +@c +@orgcmd{C-c C-x C-k,org-mark-entry-for-agenda-action} +@kindex k a +@kindex k s +Mark the current entry for agenda action. After you have marked the entry +like this, you can open the agenda or the calendar to find an appropriate +date. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to +schedule the marked item. +@c +@orgcmd{C-c / d,org-check-deadlines} +@cindex sparse tree, for deadlines +@vindex org-deadline-warning-days +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 / d} shows +all deadlines due tomorrow. +@c +@orgcmd{C-c / b,org-check-before-date} +Sparse tree for deadlines and scheduled items before a given date. +@c +@orgcmd{C-c / a,org-check-after-date} +Sparse tree for deadlines and scheduled items after a given date. +@end table + +@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling +@subsection Repeated tasks +@cindex tasks, repeated +@cindex repeated tasks + +Some tasks need to be repeated again and again. Org-mode helps to +organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, +or plain timestamp. In the following example +@example +** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> +@end example +@noindent +the @code{+1m} is a repeater; the intended interpretation is that the task +has a deadline on <2005-10-01> and repeats itself every (one) month starting +from that time. If you need both a repeater and a special warning period in +a deadline entry, the repeater should come first and the warning period last: +@code{DEADLINE: <2005-10-01 Sat +1m -3d>}. + +@vindex org-todo-repeat-to-state +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 timestamp by the repeater interval, and +immediately set the entry state back to TODO@footnote{In fact, the target +state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or +the variable @code{org-todo-repeat-to-state}. If neither of these is +specified, the target state defaults to the first state of the TODO state +sequence.}. 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 + +@vindex org-log-repeat +A timestamp@footnote{You can change this using the option +@code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat}, +@code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you +will also be prompted for a note.} will be added under the deadline, 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. + +With the @samp{+1m} cookie, the date shift will always be exactly one +month. So if you have not paid the rent for three months, marking this +entry DONE will still keep it as an overdue deadline. Depending on the +task, this may not be the best way to handle it. For example, if you +forgot to call your father for 3 weeks, it does not make sense to call +him 3 times in a single day to make up for it. Finally, there are tasks +like changing batteries which should always repeat a certain time +@i{after} the last time you did it. For these tasks, Org-mode has +special repeaters @samp{++} and @samp{.+}. For example: + +@example +** TODO Call Father + DEADLINE: <2008-02-10 Sun ++1w> + Marking this DONE will shift the date by at least one week, + but also by as many weeks as it takes to get this date into + the future. However, it stays on a Sunday, even if you called + and marked it done on Saturday. +** TODO Check the batteries in the smoke detectors + DEADLINE: <2005-11-01 Tue .+1m> + Marking this DONE will shift the date to one month after + today. +@end example + +You may have both scheduling and deadline information for a specific +task---just make sure that the repeater intervals on both are the same. + +An alternative to using a repeater is to create a number of copies of a task +subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was +created for this purpose, it is described in @ref{Structure editing}. + + +@node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and Times +@section Clocking work time +@cindex clocking time +@cindex time clocking + +Org-mode allows you to clock the time you spend 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. And it +remembers a history or tasks recently clocked, to that you can jump quickly +between a number of tasks absorbing your time. + +To save the clock history across Emacs sessions, use +@lisp +(setq org-clock-persist 'history) +(org-clock-persistence-insinuate) +@end lisp +When you clock into a new task after resuming Emacs, the incomplete +clock@footnote{To resume the clock under the assumption that you have worked +on this task while outside Emacs, use @code{(setq org-clock-persist t)}.} +will be found (@pxref{Resolving idle time}) and you will be prompted about +what to do with it. + +@menu +* Clocking commands:: Starting and stopping a clock +* The clock table:: Detailed reports +* Resolving idle time:: Resolving time when you've been idle +@end menu + +@node Clocking commands, The clock table, Clocking work time, Clocking work time +@subsection Clocking commands + +@table @kbd +@orgcmd{C-c C-x C-i,org-clock-in} +@vindex org-clock-into-drawer +Start the clock on the current item (clock-in). This inserts the CLOCK +keyword together with a timestamp. If this is not the first clocking of +this item, the multiple CLOCK lines will be wrapped into a +@code{:LOGBOOK:} drawer (see also the variable +@code{org-clock-into-drawer}). When called with a @kbd{C-u} prefix argument, +select the task from a list of recently clocked tasks. With two @kbd{C-u +C-u} prefixes, clock into the task at point and mark it as the default task. +The default task will always be available when selecting a clocking task, +with letter @kbd{d}.@* +@cindex property: CLOCK_MODELINE_TOTAL +@cindex property: LAST_REPEAT +@vindex org-clock-modeline-total +While the clock is running, the current clocking time is shown in the mode +line, along with the title of the task. The clock time shown will be all +time ever clocked for this task and its children. If the task has an effort +estimate (@pxref{Effort estimates}), the mode line displays the current +clocking time against it@footnote{To add an effort estimate ``on the fly'', +hook a function doing this to @code{org-clock-in-prepare-hook}.} If the task +is a repeating one (@pxref{Repeated tasks}), only the time since the last +reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property} +will be shown. More control over what time is shown can be exercised with +the @code{CLOCK_MODELINE_TOTAL} property. It may have the values +@code{current} to show only the current clocking instance, @code{today} to +show all time clocked on this tasks today (see also the variable +@code{org-extend-today-until}), @code{all} to include all time, or +@code{auto} which is the default@footnote{See also the variable +@code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the +mode line entry will pop up a menu with clocking options. +@c +@orgcmd{C-c C-x C-o,org-clock-out} +@vindex org-log-note-clock-out +Stop the clock (clock-out). This 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-note-clock-out} for the +possibility to record an additional note together with the clock-out +timestamp@footnote{The corresponding in-buffer setting is: +@code{#+STARTUP: lognoteclock-out}}. +@orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate} +Update the effort estimate for the current clock task. +@kindex C-c C-y +@kindex C-c C-c +@orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range} +Recompute the time interval after changing one of the timestamps. This +is only necessary if you edit the timestamps directly. If you change +them with @kbd{S-@key{cursor}} keys, the update is automatic. +@orgcmd{C-c C-t,org-todo} +Changing the TODO state of an item to DONE automatically stops the clock +if it is running in this same item. +@orgcmd{C-c C-x C-x,org-clock-cancel} +Cancel the current clock. This is useful if a clock was started by +mistake, or if you ended up working on something else. +@orgcmd{C-c C-x C-j,org-clock-goto} +Jump to the headline of the currently clocked in task. With a @kbd{C-u} +prefix arg, select the target task from a list of recently clocked tasks. +@orgcmd{C-c C-x C-d,org-clock-display} +@vindex org-remove-highlights-with-change +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}. +@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 The clock table, Resolving idle time, Clocking commands, Clocking work time +@subsection The clock table +@cindex clocktable, dynamic block +@cindex report, of clocked time + +Org mode can produce quite complex reports based on the time clocking +information. Such a report is called a @emph{clock table}, because it is +formatted as one or several Org tables. + +@table @kbd +@orgcmd{C-c C-x C-r,org-clock-report} +Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock +report as an Org-mode table into the current file. When the cursor is +at an existing clock table, just update it. When called with a prefix +argument, jump to the first clock report in the current document and +update it. +@orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update} +Update dynamic block at point. The cursor needs to be in the +@code{#+BEGIN} line of the dynamic block. +@orgkey{C-u C-c C-x C-u} +Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if +you have several clock table blocks in a buffer. +@orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift} +Shift the current @code{:block} interval and update the table. The cursor +needs to be in the @code{#+BEGIN: clocktable} line for this command. If +@code{:block} is @code{today}, it will be shifted to @code{today-1} etc. +@end table + + +Here is an example of the frame for a clock table as it is inserted into the +buffer with the @kbd{C-c C-x C-r} command: + +@cindex #+BEGIN, clocktable +@example +#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file +#+END: clocktable +@end example +@noindent +@vindex org-clocktable-defaults +The @samp{BEGIN} line and specify a number of options to define the scope, +structure, and formatting of the report. Defaults for all these options can +be configured in the variable @code{org-clocktable-defaults}. + +@noindent First there are options that determine which clock entries are to +be selected: +@example +:maxlevel @r{Maximum level depth to which times are listed in the table.} + @r{Clocks at deeper levels will be summed into the upper level.} +:scope @r{The scope to consider. This can be any of the following:} + nil @r{the current buffer or narrowed region} + file @r{the full current buffer} + subtree @r{the subtree where the clocktable is located} + tree@var{N} @r{the surrounding level @var{N} tree, for example @code{tree3}} + tree @r{the surrounding level 1 tree} + agenda @r{all agenda files} + ("file"..) @r{scan these files} + file-with-archives @r{current file and its archives} + agenda-with-archives @r{all agenda files, including archives} +:block @r{The time block to consider. This block is specified either} + @r{absolute, or relative to the current time and may be any of} + @r{these formats:} + 2007-12-31 @r{New year eve 2007} + 2007-12 @r{December 2007} + 2007-W50 @r{ISO-week 50 in 2007} + 2007-Q2 @r{2nd quarter in 2007} + 2007 @r{the year 2007} + today, yesterday, today-@var{N} @r{a relative day} + thisweek, lastweek, thisweek-@var{N} @r{a relative week} + thismonth, lastmonth, thismonth-@var{N} @r{a relative month} + thisyear, lastyear, thisyear-@var{N} @r{a relative year} + @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.} +:tstart @r{A time string specifying when to start considering times.} +:tend @r{A time string specifying when to stop considering times.} +:step @r{@code{week} or @code{day}, to split the table into chunks.} + @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.} +:stepskip0 @r{Do not show steps that have zero time.} +:fileskip0 @r{Do not show table sections from files which did not contribute.} +:tags @r{A tags match to select entries that should contribute}. +@end example + +Then there are options which determine the formatting of the table. There +options are interpreted by the function @code{org-clocktable-write-default}, +but you can specify your own function using the @code{:formatter} parameter. +@example +:emphasize @r{When @code{t}, emphasize level one and level two items.} +:link @r{Link the item headlines in the table to their origins.} +:narrow @r{An integer to limit the width of the headline column in} + @r{the org table. If you write it like @samp{50!}, then the} + @r{headline will also be shortened in export.} +:indent @r{Indent each headline field according to its level.} +:tcolumns @r{Number of columns to be used for times. If this is smaller} + @r{than @code{:maxlevel}, lower levels will be lumped into one column.} +:level @r{Should a level number column be included?} +:compact @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}} + @r{All are overwritten except if there is an explicit @code{:narrow}} +:timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,} + @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.} +:formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.} + @r{As a special case, @samp{:formula %} adds a column with % time.} + @r{If you do not specify a formula here, any existing formula} + @r{below the clock table will survive updates and be evaluated.} +:formatter @r{A function to format clock data and insert it into the buffer.} +@end example +To get a clock summary of the current level 1 tree, for the current +day, you could write +@example +#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t +#+END: clocktable +@end example +@noindent +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 into the manual.} +@example +#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" + :tend "<2006-08-10 Thu 12:00>" +#+END: clocktable +@end example +A summary of the current subtree with % times would be +@example +#+BEGIN: clocktable :scope subtree :link t :formula % +#+END: clocktable +@end example +A horizontally compact representation of everything clocked during last week +would be +@example +#+BEGIN: clocktable :scope agenda :block lastweek :compact t +#+END: clocktable +@end example + +@node Resolving idle time, , The clock table, Clocking work time +@subsection Resolving idle time +@cindex resolve idle time + +@cindex idle, resolve, dangling +If you clock in on a work item, and then walk away from your +computer---perhaps to take a phone call---you often need to ``resolve'' the +time you were away by either subtracting it from the current clock, or +applying it to another one. + +@vindex org-clock-idle-time +By customizing the variable @code{org-clock-idle-time} to some integer, such +as 10 or 15, Emacs can alert you when you get back to your computer after +being idle for that many minutes@footnote{On computers using Mac OS X, +idleness is based on actual user idleness, not just Emacs' idle time. For +X11, you can install a utility program @file{x11idle.c}, available in the +UTILITIES directory of the Org git distribution, to get the same general +treatment of idleness. On other systems, idle time refers to Emacs idle time +only.}, and ask what you want to do with the idle time. There will be a +question waiting for you when you get back, indicating how much idle time has +passed (constantly updated with the current amount), as well as a set of +choices to correct the discrepancy: + +@table @kbd +@item k +To keep some or all of the minutes and stay clocked in, press @kbd{k}. Org +will ask how many of the minutes to keep. Press @key{RET} to keep them all, +effectively changing nothing, or enter a number to keep that many minutes. +@item K +If you use the shift key and press @kbd{K}, it will keep however many minutes +you request and then immediately clock out of that task. If you keep all of +the minutes, this is the same as just clocking out of the current task. +@item s +To keep none of the minutes, use @kbd{s} to subtract all the away time from +the clock, and then check back in from the moment you returned. +@item S +To keep none of the minutes and just clock out at the start of the away time, +use the shift key and press @kbd{S}. Remember that using shift will always +leave you clocked out, no matter which option you choose. +@item C +To cancel the clock altogether, use @kbd{C}. Note that if instead of +canceling you subtract the away time, and the resulting clock amount is less +than a minute, the clock will still be canceled rather than clutter up the +log with an empty entry. +@end table + +What if you subtracted those away minutes from the current clock, and now +want to apply them to a new clock? Simply clock in to any task immediately +after the subtraction. Org will notice that you have subtracted time ``on +the books'', so to speak, and will ask if you want to apply those minutes to +the next task you clock in on. + +There is one other instance when this clock resolution magic occurs. Say you +were clocked in and hacking away, and suddenly your cat chased a mouse who +scared a hamster that crashed into your UPS's power button! You suddenly +lose all your buffers, but thanks to auto-save you still have your recent Org +mode changes, including your last clock in. + +If you restart Emacs and clock into any task, Org will notice that you have a +dangling clock which was never clocked out from your last session. Using +that clock's starting time as the beginning of the unaccounted-for period, +Org will ask how you want to resolve that time. The logic and behavior is +identical to dealing with away time due to idleness; it's just happening due +to a recovery event rather than a set amount of idle time. + +You can also check all the files visited by your Org agenda for dangling +clocks at any time using @kbd{M-x org-resolve-clocks}. + +@node Effort estimates, Relative timer, Clocking work time, Dates and Times +@section Effort estimates +@cindex effort estimates + +@cindex property, Effort +@vindex org-effort-property +If you want to plan your work in a very detailed way, or if you need to +produce offers with quotations of the estimated work effort, you may want to +assign effort estimates to entries. If you are also clocking your work, you +may later want to compare the planned effort with the actual working time, a +great way to improve planning estimates. Effort estimates are stored in a +special property @samp{Effort}@footnote{You may change the property being +used with the variable @code{org-effort-property}.}. You can set the effort +for an entry with the following commands: + +@table @kbd +@orgcmd{C-c C-x e,org-set-effort} +Set the effort estimate for the current entry. With a numeric prefix +argument, set it to the Nth allowed value (see below). This command is also +accessible from the agenda with the @kbd{e} key. +@orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate} +Modify the effort estimate of the item currently being clocked. +@end table + +Clearly the best way to work with effort estimates is through column view +(@pxref{Column view}). You should start by setting up discrete values for +effort estimates, and a @code{COLUMNS} format that displays these values +together with clock sums (if you want to clock your time). For a specific +buffer you can use + +@example +#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 8:00 +#+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM +@end example + +@noindent +@vindex org-global-properties +@vindex org-columns-default-format +or, even better, you can set up these values globally by customizing the +variables @code{org-global-properties} and @code{org-columns-default-format}. +In particular if you want to use this setup also in the agenda, a global +setup may be advised. + +The way to assign estimates to individual items is then to switch to column +mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the +value. The values you enter will immediately be summed up in the hierarchy. +In the column next to it, any clocked time will be displayed. + +@vindex org-agenda-columns-add-appointments-to-effort-sum +If you switch to column view in the daily/weekly agenda, the effort column +will summarize the estimated work effort for each day@footnote{Please note +the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda +column view}).}, and you can use this to find space in your schedule. To get +an overview of the entire part of the day that is committed, you can set the +option @code{org-agenda-columns-add-appointments-to-effort-sum}. The +appointments on a day that take place over a specified time interval will +then also be added to the load estimate of the day. + +Effort estimates can be used in secondary agenda filtering that is triggered +with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have +these estimates defined consistently, two or three key presses will narrow +down the list to stuff that fits into an available time slot. + +@node Relative timer, Countdown timer, Effort estimates, Dates and Times +@section Taking notes with a relative timer +@cindex relative timer + +When taking notes during, for example, a meeting or a video viewing, it can +be useful to have access to times relative to a starting time. Org provides +such a relative timer and make it easy to create timed notes. + +@table @kbd +@orgcmd{C-c C-x .,org-timer} +Insert a relative time into the buffer. The first time you use this, the +timer will be started. When called with a prefix argument, the timer is +restarted. +@orgcmd{C-c C-x -,org-timer-item} +Insert a description list item with the current relative time. With a prefix +argument, first reset the timer to 0. +@orgcmd{M-@key{RET},org-insert-heading} +Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert +new timer items. +@c for key sequences with a comma, command name macros fail :( +@kindex C-c C-x , +@item C-c C-x , +Pause the timer, or continue it if it is already paused +(@command{org-timer-pause-or-continue}). +@c removed the sentence because it is redundant to the following item +@kindex C-u C-c C-x , +@item C-u C-c C-x , +Stop the timer. After this, you can only start a new timer, not continue the +old one. This command also removes the timer from the mode line. +@orgcmd{C-c C-x 0,org-timer-start} +Reset the timer without inserting anything into the buffer. By default, the +timer is reset to 0. When called with a @kbd{C-u} prefix, reset the timer to +specific starting offset. The user is prompted for the offset, with a +default taken from a timer string at point, if any, So this can be used to +restart taking notes after a break in the process. When called with a double +prefix argument @kbd{C-u C-u}, change all timer strings in the active region +by a certain amount. This can be used to fix timer strings if the timer was +not started at exactly the right moment. +@end table + +@node Countdown timer, , Relative timer, Dates and Times +@section Countdown timer +@cindex Countdown timer +@kindex C-c C-x ; +@kindex ; + +Calling @code{org-timer-set-timer} from an Org-mode buffer runs a countdown +timer. Use @key{;} from agenda buffers, @key{C-c C-x ;} everwhere else. + +@code{org-timer-set-timer} prompts the user for a duration and displays a +countdown timer in the modeline. @code{org-timer-default-timer} sets the +default countdown value. Giving a prefix numeric argument overrides this +default value. + +@node Capture - Refile - Archive, Agenda Views, Dates and Times, Top +@chapter Capture - Refile - Archive +@cindex capture + +An important part of any organization system is the ability to quickly +capture new ideas and tasks, and to associate reference material with them. +Org does this using a process called @i{capture}. It also can store files +related to a task (@i{attachments}) in a special directory. Once in the +system, tasks and projects need to be moved around. Moving completed project +trees to an archive file keeps the system compact and fast. + +@menu +* Capture:: Capturing new stuff +* Attachments:: Add files to tasks +* RSS Feeds:: Getting input from RSS feeds +* Protocols:: External (e.g. Browser) access to Emacs and Org +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects +@end menu + +@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive +@section Capture +@cindex capture + +Org's method for capturing new items is heavily inspired by John Wiegley +excellent remember package. Up to version 6.36 Org used a special setup +for @file{remember.el}. @file{org-remember.el} is still part of Org-mode for +backward compatibility with existing setups. You can find the documentation +for org-remember at @url{http://orgmode.org/org-remember.pdf}. + +The new capturing setup described here is preferred and should be used by new +users. To convert your @code{org-remember-templates}, run the command +@example +@kbd{M-x org-capture-import-remember-templates @key{RET}} +@end example +@noindent and then customize the new variable with @kbd{M-x +customize-variable org-capture-templates}, check the result, and save the +customization. You can then use both remember and capture until +you are familiar with the new mechanism. + +Capture lets you quickly store notes with little interruption of your work +flow. The basic process of capturing is very similar to remember, but Org +does enhance it with templates and more. + +@menu +* Setting up capture:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types +@end menu + +@node Setting up capture, Using capture, Capture, Capture +@subsection Setting up capture + +The following customization sets a default target file for notes, and defines +a global key@footnote{Please select your own key, @kbd{C-c c} is only a +suggestion.} for capturing new material. + +@vindex org-default-notes-file +@example +(setq org-default-notes-file (concat org-directory "/notes.org")) +(define-key global-map "\C-cc" 'org-capture) +@end example + +@node Using capture, Capture templates, Setting up capture, Capture +@subsection Using capture + +@table @kbd +@orgcmd{C-c c,org-capture} +Call the command @code{org-capture}. Note that this keybinding is global and +not active by default - you need to install it. If you have templates +defined @pxref{Capture templates}, it will offer these templates for +selection or use a new Org outline node as the default template. It will +insert the template into the target file and switch to an indirect buffer +narrowed to this new node. You may then insert the information you want. + +@orgcmd{C-c C-c,org-capture-finalize} +Once you have finished entering information into the capture buffer, @kbd{C-c +C-c} will return you to the window configuration before the capture process, +so that you can resume your work without further distraction. When called +with a prefix arg, finalize and then jump to the captured item. + +@orgcmd{C-c C-w,org-capture-refile} +Finalize the capture process by refiling (@pxref{Refiling notes}) the note to +a different place. Please realize that this is a normal refiling command +that will be executed---so the cursor position at the moment you run this +command is important. If you have inserted a tree with a parent and +children, first move the cursor back to the parent. Any prefix argument +given to this command will be passed on to the @code{org-refile} command. + +@orgcmd{C-c C-k,org-capture-kill} +Abort the capture process and return to the previous state. + +@end table + +You can also call @code{org-capture} in a special way from the agenda, using +the @kbd{k c} key combination. With this access, any timestamps inserted by +the selected capture template will default to the cursor date in the agenda, +rather than to the current date. + +To find the locations of the last stored capture, use @code{org-capture} with +prefix commands: + +@table @kbd +@orgkey{C-u C-c c} +Visit the target location of a cpature template. You get to select the +template in the usual way. +@orgkey{C-u C-u C-c c} +Visit the last stored capture item in its buffer. +@end table + +@node Capture templates, , Using capture, Capture +@subsection Capture templates +@cindex templates, for Capture + +You can use templates for different types of capture items, and +for different target locations. The easiest way to create such templates is +through the customize interface. + +@table @kbd +@orgkey{C-c c C} +Customize the variable @code{org-capture-templates}. +@end table + +Before we give the formal description of template definitions, let's look at +an example. Say you would like to use one template to create general TODO +entries, and you want to put these entries under the heading @samp{Tasks} in +your file @file{~/org/gtd.org}. Also, a date tree in the file +@file{journal.org} should capture journal entries. A possible configuration +would look like: + +@example +(setq org-capture-templates + '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") + "* TODO %?\n %i\n %a") + ("j" "Journal" entry (file+datetree "~/org/journal.org") + "* %?\nEntered on %U\n %i\n %a"))) +@end example + +@noindent If you then press @kbd{C-c c t}, Org will prepare the template +for you like this: +@example +* TODO + [[file:@var{link to where you initiated capture}]] +@end example + +@noindent +During expansion of the template, @code{%a} has been replaced by a link to +the location from where you called the capture command. This can be +extremely useful for deriving tasks from emails, for example. You fill in +the task definition, press @code{C-c C-c} and Org returns you to the same +place where you started the capture process. + + +@menu +* Template elements:: What is needed for a complete template entry +* Template expansion:: Filling in information about time and context +@end menu + +@node Template elements, Template expansion, Capture templates, Capture templates +@subsubsection Template elements + +Now lets look at the elements of a template definition. Each entry in +@code{org-capture-templates} is a list with the following items: + +@table @var +@item keys +The keys that will select the template, as a string, characters +only, for example @code{"a"} for a template to be selected with a +single key, or @code{"bt"} for selection with two keys. When using +several keys, keys using the same prefix key must be sequential +in the list and preceded by a 2-element entry explaining the +prefix key, for example +@example + ("b" "Templates for marking stuff to buy") +@end example +@noindent If you do not define a template for the @kbd{C} key, this key will +be used to open the customize buffer for this complex variable. + +@item description +A short string describing the template, which will be shown during +selection. + +@item type +The type of entry, a symbol. Valid values are: +@table @code +@item entry +An Org-mode node, with a headline. Will be filed as the child of the +target entry or as a top-level entry. The target file should be an Org-mode +file. +@item item +A plain list item, placed in the first plain list at the target +location. Again the target file should be an Org file. +@item checkitem +A checkbox item. This only differs from the plain list item by the +default template. +@item table-line +a new line in the first table at the target location. Where exactly the +line will be inserted depends on the properties @code{:prepend} and +@code{:table-line-pos} (see below). +@item plain +Text to be inserted as it is. +@end table + +@item target +@vindex org-default-notes-file +Specification of where the captured item should be placed. In Org-mode +files, targets usually define a node. Entries will become children of this +node. Other types will be added to the table or list in the body of this +node. Most target specifications contain a file name. If that file name is +the empty string, it defaults to @code{org-default-notes-file}. + +Valid values are: +@table @code +@item (file "path/to/file") +Text will be placed at the beginning or end of that file. + +@item (id "id of existing org entry") +Filing as child of this entry, or in the body of the entry. + +@item (file+headline "path/to/file" "node headline") +Fast configuration if the target heading is unique in the file. + +@item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...) +For non-unique headings, the full path is safer. + +@item (file+regexp "path/to/file" "regexp to find location") +Use a regular expression to position the cursor. + +@item (file+datetree "path/to/file") +Will create a heading in a date tree for today's date. + +@item (file+datetree+prompt "path/to/file") +Will create a heading in a date tree, but will prompt for the date. + +@item (file+function "path/to/file" function-finding-location) +A function to find the right location in the file. + +@item (clock) +File to the entry that is currently being clocked. + +@item (function function-finding-location) +Most general way, write your own function to find both +file and location. +@end table + +@item template +The template for creating the capture item. If you leave this empty, an +appropriate default template will be used. Otherwise this is a string with +escape codes, which will be replaced depending on time and context of the +capture call. The string with escapes may be loaded from a template file, +using the special syntax @code{(file "path/to/template")}. See below for +more details. + +@item properties +The rest of the entry is a property list of additional options. +Recognized properties are: +@table @code +@item :prepend +Normally new captured information will be appended at +the target location (last child, last table line, last list item...). +Setting this property will change that. + +@item :immediate-finish +When set, do not offer to edit the information, just +file it away immediately. This makes sense if the template only needs +information that can be added automatically. + +@item :empty-lines +Set this to the number of lines to insert +before and after the new item. Default 0, only common other value is 1. + +@item :clock-in +Start the clock in this item. + +@item :clock-resume +If starting the capture interrupted a clock, restart that clock when finished +with the capture. + +@item :unnarrowed +Do not narrow the target buffer, simply show the full buffer. Default is to +narrow it so that you only see the new material. + +@item :kill-buffer +If the target file was not yet visited when capture was invoked, kill the +buffer again after capture is completed. +@end table +@end table + +@node Template expansion, , Template elements, Capture templates +@subsubsection Template expansion + +In the template itself, special @kbd{%}-escapes@footnote{If you need one of +these sequences literally, escape the @kbd{%} with a backslash.} allow +dynamic insertion of content: + +@comment SJE: should these sentences terminate in period? +@smallexample +%^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.} + @r{You may specify a default value and a completion table with} + @r{%^@{prompt|default|completion2|completion3...@}} + @r{The arrow keys access a prompt-specific history.} +%a @r{annotation, normally the link created with @code{org-store-link}} +%A @r{like @code{%a}, but prompt for the description part} +%i @r{initial content, the region when capture is called while the} + @r{region is active.} + @r{The entire text will be indented like @code{%i} itself.} +%t @r{timestamp, date only} +%T @r{timestamp with date and time} +%u, %U @r{like the above, but inactive timestamps} +%^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})} +%c @r{Current kill ring head.} +%x @r{Content of the X clipboard.} +%^C @r{Interactive selection of which kill or clip to use.} +%^L @r{Like @code{%^C}, but insert as link.} +%k @r{title of the currently clocked task} +%K @r{link to the currently clocked task} +%^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.} +%^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}} +%:keyword @r{specific information for certain link types, see below} +%[@var{file}] @r{insert the contents of the file given by @var{file}} +%(@var{sexp}) @r{evaluate Elisp @var{sexp} and replace with the result} +@end smallexample + +@noindent +For specific link types, the following keywords will be +defined@footnote{If you define your own link types (@pxref{Adding +hyperlink types}), any property you store with +@code{org-store-link-props} can be accessed in capture templates in a +similar way.}: + +@vindex org-from-is-user-regexp +@smallexample +Link type | Available keywords +-------------------+---------------------------------------------- +bbdb | %:name %:company +irc | %:server %:port %:nick +vm, wl, mh, mew, rmail | %:type %:subject %:message-id + | %:from %:fromname %:fromaddress + | %:to %:toname %:toaddress + | %:date @r{(message date header field)} + | %:date-timestamp @r{(date as active timestamp)} + | %:date-timestamp-inactive @r{(date as inactive timestamp)} + | %: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 smallexample + +@noindent +To place the cursor after template expansion use: + +@smallexample +%? @r{After completing the template, position cursor here.} +@end smallexample + + +@node Attachments, RSS Feeds, Capture, Capture - Refile - Archive +@section Attachments +@cindex attachments + +@vindex org-attach-directory +It is often useful to associate reference material with an outline node/task. +Small chunks of plain text can simply be stored in the subtree of a project. +Hyperlinks (@pxref{Hyperlinks}) can establish associations with +files that live elsewhere on your computer or in the cloud, like emails or +source code files belonging to a project. Another method is @i{attachments}, +which are files located in a directory belonging to an outline node. Org +uses directories named by the unique ID of each entry. These directories are +located in the @file{data} directory which lives in the same directory where +your Org file lives@footnote{If you move entries or Org files from one +directory to another, you may want to configure @code{org-attach-directory} +to contain an absolute path.}. If you initialize this directory with +@code{git init}, Org will automatically commit changes when it sees them. +The attachment system has been contributed to Org by John Wiegley. + +In cases where it seems better to do so, you can also attach a directory of your +choice to an entry. You can also make children inherit the attachment +directory from a parent, so that an entire subtree uses the same attached +directory. + +@noindent The following commands deal with attachments: + +@table @kbd + +@orgcmd{C-c C-a,org-attach} +The dispatcher for commands related to the attachment system. After these +keys, a list of commands is displayed and you must press an additional key +to select a command: + +@table @kbd +@orgcmdtkc{a,C-c C-a a,org-attach-attach} +@vindex org-attach-method +Select a file and move it into the task's attachment directory. The file +will be copied, moved, or linked, depending on @code{org-attach-method}. +Note that hard links are not supported on all systems. + +@kindex C-c C-a c +@kindex C-c C-a m +@kindex C-c C-a l +@item c/m/l +Attach a file using the copy/move/link method. +Note that hard links are not supported on all systems. + +@orgcmdtkc{n,C-c C-a n,org-attach-new} +Create a new attachment as an Emacs buffer. + +@orgcmdtkc{z,C-c C-a z,org-attach-sync} +Synchronize the current task with its attachment directory, in case you added +attachments yourself. + +@orgcmdtkc{p,C-c C-a o,org-attach-open} +@vindex org-file-apps +Open current task's attachment. If there is more than one, prompt for a +file name first. Opening will follow the rules set by @code{org-file-apps}. +For more details, see the information on following hyperlinks +(@pxref{Handling links}). + +@orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs} +Also open the attachment, but force opening the file in Emacs. + +@orgcmdtkc{f,C-c C-a f,org-attach-reveal} +Open the current task's attachment directory. + +@orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs} +Also open the directory, but force using @command{dired} in Emacs. + +@orgcmdtkc{d,C-c C-a d,org-attach-delete-one} +Select and delete a single attachment. + +@orgcmdtkc{D,C-c C-a D,org-attach-delete-all} +Delete all of a task's attachments. A safer way is to open the directory in +@command{dired} and delete from there. + +@orgcmdtkc{s,C-c C-a s,org-attach-set-directory} +@cindex property, ATTACH_DIR +Set a specific directory as the entry's attachment directory. This works by +putting the directory path into the @code{ATTACH_DIR} property. + +@orgcmdtkc{i,C-c C-a i,org-attach-set-inherit} +@cindex property, ATTACH_DIR_INHERIT +Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the +same directory for attachments as the parent does. +@end table +@end table + +@node RSS Feeds, Protocols, Attachments, Capture - Refile - Archive +@section RSS feeds +@cindex RSS feeds +@cindex Atom feeds + +Org can add and change entries based on information found in RSS feeds and +Atom feeds. You could use this to make a task out of each new podcast in a +podcast feed. Or you could use a phone-based note-creating service on the +web to import tasks into Org. To access feeds, configure the variable +@code{org-feed-alist}. The docstring of this variable has detailed +information. Here is just an example: + +@example +(setq org-feed-alist + '(("Slashdot" + "http://rss.slashdot.org/Slashdot/slashdot" + "~/txt/org/feeds.org" "Slashdot Entries"))) +@end example + +@noindent +will configure that new items from the feed provided by +@code{rss.slashdot.org} will result in new entries in the file +@file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever +the following command is used: + +@table @kbd +@orgcmd{C-c C-x g,org-feed-update-all} +@item C-c C-x g +Collect items from the feeds configured in @code{org-feed-alist} and act upon +them. +@orgcmd{C-c C-x G,org-feed-goto-inbox} +Prompt for a feed name and go to the inbox configured for this feed. +@end table + +Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which +it will store information about the status of items in the feed, to avoid +adding the same item several times. You should add @samp{FEEDSTATUS} to the +list of drawers in that file: + +@example +#+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS +@end example + +For more information, including how to read atom feeds, see +@file{org-feed.el} and the docstring of @code{org-feed-alist}. + +@node Protocols, Refiling notes, RSS Feeds, Capture - Refile - Archive +@section Protocols for external access +@cindex protocols, for external access +@cindex emacsserver + +You can set up Org for handling protocol calls from outside applications that +are passed to Emacs through the @file{emacsserver}. For example, you can +configure bookmarks in your web browser to send a link to the current page to +Org and create a note from it using capture (@pxref{Capture}). Or you +could create a bookmark that will tell Emacs to open the local source file of +a remote website you are looking at with the browser. See +@uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed +documentation and setup instructions. + +@node Refiling notes, Archiving, Protocols, Capture - Refile - Archive +@section Refiling notes +@cindex refiling notes + +When reviewing the captured data, you may want to refile some of the entries +into a different list, for example into a project. Cutting, finding the +right location, and then pasting the note is cumbersome. To simplify this +process, you can use the following special command: + +@table @kbd +@orgcmd{C-c C-w,org-refile} +@vindex org-reverse-note-order +@vindex org-refile-targets +@vindex org-refile-use-outline-path +@vindex org-outline-path-complete-in-steps +@vindex org-refile-allow-creating-parent-nodes +@vindex org-log-refile +@vindex org-refile-use-cache +Refile the entry or region at point. This command offers possible locations +for refiling the entry and lets you select one with completion. The item (or +all items in the region) is filed below the target heading as a subitem. +Depending on @code{org-reverse-note-order}, it will be either the first or +last subitem.@* +By default, all level 1 headlines in the current buffer are considered to be +targets, but you can have more complex definitions across a number of files. +See the variable @code{org-refile-targets} for details. If you would like to +select a location via a file-path-like completion along the outline path, see +the variables @code{org-refile-use-outline-path} and +@code{org-outline-path-complete-in-steps}. If you would like to be able to +create new nodes as new parents for refiling on the fly, check the +variable @code{org-refile-allow-creating-parent-nodes}. +When the variable @code{org-log-refile}@footnote{with corresponding +@code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile}, +and @code{nologrefile}} is set, a time stamp or a note will be +recorded when an entry has been refiled. +@orgkey{C-u C-c C-w} +Use the refile interface to jump to a heading. +@orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored} +Jump to the location where @code{org-refile} last moved a tree to. +@item C-2 C-c C-w +Refile as the child of the item currently being clocked. +@item C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w + +@orgcmdtkc{C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w,C-0 C-c C-w,org-refile-cache-clear} + +Clear the target cache. Caching of refile targets can be turned on by +setting @code{org-refile-use-cache}. To make the command see new possible +targets, you have to clear the cache with this command. +@end table + +@node Archiving, , Refiling notes, Capture - Refile - Archive +@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. Archiving is important to keep your working files compact and global +searches like the construction of agenda views fast. + +@table @kbd +@orgcmd{C-c C-x C-a,org-archive-subtree-default} +@vindex org-archive-default-command +Archive the current entry using the command specified in the variable +@code{org-archive-default-command}. +@end table + +@menu +* Moving subtrees:: Moving a tree to an archive file +* Internal archiving:: Switch off a tree but keep it in the file +@end menu + +@node Moving subtrees, Internal archiving, Archiving, Archiving +@subsection Moving a tree to the archive file +@cindex external archiving + +The most common archiving action is to move a project tree to another file, +the archive file. + +@table @kbd +@orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree} +@vindex org-archive-location +Archive the subtree starting at the cursor position to the location +given by @code{org-archive-location}. +@orgkey{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@footnote{For backward compatibility, +the following also works: If there are several such lines in a file, +each specifies the archive location for the text below it. The first +such line also applies to any text before its definition. However, +using this method is @emph{strongly} deprecated as it is incompatible +with the outline structure of the document. The correct method for +setting multiple archive locations in a buffer is using properties.}: + +@cindex #+ARCHIVE +@example +#+ARCHIVE: %s_done:: +@end example + +@cindex property, ARCHIVE +@noindent +If you would like to have a special ARCHIVE location for a single entry +or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the +location as the value (@pxref{Properties and Columns}). + +@vindex org-archive-save-context-info +When a subtree is moved, it receives a number of special properties that +record context information like the file from where the entry came, its +outline path the archiving time etc. Configure the variable +@code{org-archive-save-context-info} to adjust the amount of information +added. + + +@node Internal archiving, , Moving subtrees, Archiving +@subsection Internal archiving + +If you want to just switch off (for agenda views) certain subtrees without +moving them to a different file, you can use the @code{ARCHIVE tag}. + +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 +@vindex org-cycle-open-archived-trees +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 +@vindex org-sparse-tree-open-archived-trees +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 +@vindex org-agenda-skip-archived-trees +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}, in which case these trees will always +be included. In the agenda you can press @kbd{v a} to get archives +temporarily included. +@item +@vindex org-export-with-archived-trees +Archived trees are not exported (@pxref{Exporting}), only the headline +is. Configure the details using the variable +@code{org-export-with-archived-trees}. +@item +@vindex org-columns-skip-archived-trees +Archived trees are excluded from column view unless the variable +@code{org-columns-skip-archived-trees} is configured to @code{nil}. +@end itemize + +The following commands help manage the ARCHIVE tag: + +@table @kbd +@orgcmd{C-c C-x a,org-toggle-archive-tag} +Toggle the ARCHIVE tag for the current headline. When the tag is set, +the headline changes to a shadowed face, and the subtree below it is +hidden. +@orgkey{C-u C-c C-x 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. +@orgcmd{C-@kbd{TAB},org-force-cycle-archived} +Cycle a tree even if it is tagged with ARCHIVE. +@orgcmd{C-c C-x A,org-archive-to-archive-sibling} +Move the current entry to the @emph{Archive Sibling}. This is a sibling of +the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The +entry becomes a child of that sibling and in this way retains a lot of its +original context, including inherited tags and approximate position in the +outline. +@end table + + +@node Agenda Views, Markup, Capture - Refile - Archive, Top +@chapter Agenda views +@cindex agenda views + +Due to the way Org 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 of open action items, or of events that are +important for a particular date, this information must be collected, +sorted and displayed in an organized way. + +Org can select items based on various criteria and display them +in a separate buffer. Seven 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{match view}, showings headlines based on the tags, properties, and +TODO state associated with them, +@item +a @emph{timeline view} that shows all events in a single Org file, +in time-sorted view, +@item +a @emph{text search view} that shows all entries from multiple files +that contain specified keywords, +@item +a @emph{stuck projects view} showing projects that currently don't move +along, and +@item +@emph{custom views} that are special 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 files, and even to +edit these files remotely. + +@vindex org-agenda-window-setup +@vindex org-agenda-restore-windows-after-quit +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 +* Exporting Agenda Views:: Writing a view to a file +* Agenda column view:: Using column view for collected entries +@end menu + +@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views +@section Agenda files +@cindex agenda files +@cindex files for agenda + +@vindex org-agenda-files +The information to be shown is normally 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.}. If a directory is part of this list, +all files with the extension @file{.org} in this directory will be part +of the list. + +Thus, even if you only work with a single Org file, that file should +be put into the list@footnote{When using the dispatcher, pressing +@kbd{<} 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 +@orgcmd{C-c [,org-agenda-to-front} +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 a prefix argument, file is added/moved to the end. +@orgcmd{C-c ],org-remove-file} +Remove current file from the list of agenda files. +@kindex C-, +@orgcmd{C-',org-cycle-agenda-files} +@itemx C-, +Cycle through agenda file list, visiting one file after the other. +@kindex M-x org-iswitchb +@item M-x org-iswitchb +Command to use an @code{iswitchb}-like interface to switch to and between Org +buffers. +@end table + +@noindent +The Org menu contains the current list of files and can be used +to visit any of them. + +If you would like to focus the agenda temporarily on a file not in +this list, or on just one file in the list, or even on only a subtree in a +file, then this can be done in different ways. For a single agenda command, +you may press @kbd{<} once or several times in the dispatcher +(@pxref{Agenda dispatcher}). To restrict the agenda scope for an +extended period, use the following commands: + +@table @kbd +@orgcmd{C-c C-x <,org-agenda-set-restriction-lock} +Permanently restrict the agenda to the current subtree. When with a +prefix argument, or with the cursor before the first headline in a file, +the agenda scope is set to the entire file. This restriction remains in +effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<} +or @kbd{>} in the agenda dispatcher. If there is a window displaying an +agenda view, the new restriction takes effect immediately. +@orgcmd{C-c C-x >,org-agenda-remove-restriction-lock} +Remove the permanent restriction created by @kbd{C-c C-x <}. +@end table + +@noindent +When working with @file{speedbar.el}, you can use the following commands in +the Speedbar frame: +@table @kbd +@orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction} +Permanently restrict the agenda to the item---either an Org file or a subtree +in such a file---at the cursor in the Speedbar frame. +If there is a window displaying an agenda view, the new restriction takes +effect immediately. +@orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock} +Lift the restriction. +@end table + +@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, which 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 s +Create a list of entries selected by a boolean expression of keywords +and/or regular expressions that must or must not occur in the entry. +@item / +@vindex org-agenda-text-search-extra-files +Search for a regular expression in all agenda files and additionally in +the files listed in @code{org-agenda-text-search-extra-files}. This +uses the Emacs command @code{multi-occur}. A prefix argument can be +used to specify the number of context lines for each match, default is +1. +@item # @r{/} ! +Create a list of stuck projects (@pxref{Stuck projects}). +@item < +Restrict an agenda command to the current buffer@footnote{For backward +compatibility, you can also press @kbd{1} to restrict to the current +buffer.}. After pressing @kbd{<}, you still need to press the character +selecting the command. +@item < < +If there is an active region, restrict the following agenda command to +the region. Otherwise, restrict it to the current subtree@footnote{For +backward compatibility, you can also press @kbd{0} to restrict to the +current region/subtree.}. After pressing @kbd{< <}, 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 +* Search view:: Find entries by searching for text +* 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 +@orgcmd{C-c a a,org-agenda-list} +Compile an agenda for the current week from a list of Org files. The agenda +shows the entries for each day. With a numeric prefix@footnote{For backward +compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be +listed before the agenda. This feature is deprecated, use the dedicated TODO +list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1 +C-c a a}) you may set the number of days to be displayed. +@end table + +@vindex org-agenda-span +@vindex org-agenda-ndays +The default number of days displayed in the agenda is set by the variable +@code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This +variable can be set to any number of days you want to see by default in the +agenda, or to a span name, such a @code{day}, @code{week}, @code{month} or +@code{year}. + +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. It can be very useful to combine output from Org 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 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 whitespace is allowed before them. For example, +the following segment of an Org 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 5 14 1956)@footnote{Note that the order of the arguments (month, day, year) depends on the setting of @code{calendar-date-style}.} Arthur Dent is %d years old +%%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old +@end example + +@subsubheading Anniversaries from BBDB +@cindex BBDB, anniversaries +@cindex anniversaries, from BBDB + +If you are using the Big Brothers Database to store your contacts, you will +very likely prefer to store anniversaries in BBDB rather than in a +separate Org or diary file. Org supports this and will show BBDB +anniversaries as part of the agenda. All you need to do is to add the +following to one your your agenda files: + +@example +* Anniversaries + :PROPERTIES: + :CATEGORY: Anniv + :END: +%%(org-bbdb-anniversaries) +@end example + +You can then go ahead and define anniversaries for a BBDB record. Basically, +you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB +record and then add the date in the format @code{YYYY-MM-DD}, followed by a +space and the class of the anniversary (@samp{birthday} or @samp{wedding}, or +a format string). If you omit the class, it will default to @samp{birthday}. +Here are a few examples, the header for the file @file{org-bbdb.el} contains +more detailed information. + +@example +1973-06-22 +1955-08-02 wedding +2008-04-14 %s released version 6.01 of org-mode, %d years ago +@end example + +After a change to BBDB, or for the first agenda display during an Emacs +session, the agenda display will suffer a short delay as Org updates its +hash with anniversaries. However, from then on things will be very fast---much +faster in fact than a long list of @samp{%%(diary-anniversary)} entries +in an Org or Diary file. + +@subsubheading Appointment reminders +@cindex @file{appt.el} +@cindex appointment reminders + +Org can interact with Emacs appointments notification facility. To add all +the appointments of your agenda files, use the command +@code{org-agenda-to-appt}. This command also lets you filter through the +list of your appointments and add only those belonging to a specific category +or matching a regular expression. See the docstring for details. + +@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 +@orgcmd{C-c a t,org-todo-list} +Show the global TODO list. This collects the TODO items from all agenda +files (@pxref{Agenda Views}) into a single buffer. By default, this lists +items with a state the is not a DONE state. 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}). +@orgcmd{C-c a T,org-todo-list} +@cindex TODO keyword matching +@vindex org-todo-keywords +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}. You are +prompted for a keyword, and you may also specify several keywords by +separating them with @samp{|} as the 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 +@vindex org-agenda-todo-ignore-scheduled +@vindex org-agenda-todo-ignore-deadlines +@vindex org-agenda-todo-ignore-timestamp +@vindex org-agenda-todo-ignore-with-date +Some people view a TODO item that has been @emph{scheduled} for execution or +have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}. +Configure the variables @code{org-agenda-todo-ignore-scheduled}, +@code{org-agenda-todo-ignore-deadlines}, +@code{org-agenda-todo-ignore-timestamp} and/or +@code{org-agenda-todo-ignore-with-date} to exclude such items from the global +TODO list. +@item +@vindex org-agenda-todo-list-sublevels +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 +@cindex match view + +If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}), +or have properties (@pxref{Properties and Columns}), you can select headlines +based on this metadata and collect them into an agenda buffer. The match +syntax described here also applies when creating sparse trees with @kbd{C-c / +m}. + +@table @kbd +@orgcmd{C-c a m,org-tags-view} +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}). +@orgcmd{C-c a M,org-tags-view} +@vindex org-tags-match-list-sublevels +@vindex org-agenda-tags-todo-honor-ignore-options +Like @kbd{C-c a m}, but only select headlines that are also TODO items in a +not-DONE state and force checking subitems (see variable +@code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items, +see the variable @code{org-agenda-tags-todo-honor-ignore-options}. 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}. + +@subsubheading Match syntax + +@cindex Boolean logic, for tag/property searches +A search string can use Boolean operators @samp{&} for AND and @samp{|} for +OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently +not implemented. Each element in the search is either a tag, a regular +expression matching tags, or an expression like @code{PROPERTY OPERATOR +VALUE} with a comparison operator, accessing a property value. Each element +may 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. Here are some examples, using only tags. + +@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 regular expressions, with tags search +Instead of a tag, you may also specify a regular expression 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 TODO keyword matching, with tags search +@cindex level, require for tags/property match +@cindex category, require for tags/property match +@vindex org-odd-levels-only +You may also test for properties (@pxref{Properties and Columns}) at the same +time as matching tags. The properties may be real properties, or special +properties that represent other metadata (@pxref{Special properties}). For +example, the ``property'' @code{TODO} represents the TODO keyword of the +entry. Or, the ``property'' @code{LEVEL} represents the level of an entry. +So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines +that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword +DONE. In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not +count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc. + +Here are more examples: +@table @samp +@item work+TODO="WAITING" +Select @samp{:work:}-tagged TODO lines with the specific TODO +keyword @samp{WAITING}. +@item work+TODO="WAITING"|home+TODO="WAITING" +Waiting tasks both at work and at home. +@end table + +When matching properties, a number of different operators can be used to test +the value of a property. Here is a complex example: + +@example ++work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \ + +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>" +@end example + +@noindent +The type of comparison will depend on how the comparison value is written: +@itemize @minus +@item +If the comparison value is a plain number, a numerical comparison is done, +and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=}, +@samp{>=}, and @samp{<>}. +@item +If the comparison value is enclosed in double-quotes, +a string comparison is done, and the same operators are allowed. +@item +If the comparison value is enclosed in double-quotes @emph{and} angular +brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are +assumed to be date/time specifications in the standard Org way, and the +comparison will be done accordingly. Special values that will be recognized +are @code{"<now>"} for now (including time), and @code{"<today>"}, and +@code{"<tomorrow>"} for these days at 0:00 hours, i.e. without a time +specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units +@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year, +respectively, can be used. +@item +If the comparison value is enclosed +in curly braces, a regexp match is performed, with @samp{=} meaning that the +regexp matches the property value, and @samp{<>} meaning that it does not +match. +@end itemize + +So the search string in the example 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}, an @samp{Effort} +property that is numerically smaller than 2, a @samp{:With:} property that is +matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled +on or after October 11, 2008. + +Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing any +other properties will slow down the search. However, once you have paid the +price by accessing one property, testing additional properties is cheap +again. + +You can configure Org-mode to use property inheritance during a search, but +beware that this can slow down searches considerably. See @ref{Property +inheritance}, for details. + +For backward compatibility, and also for typing speed, there is also a +different way to test TODO states in a search. For this, terminate the +tags/property part of the search string (which may include several terms +connected with @samp{|}) with a @samp{/} and then specify a Boolean +expression just for TODO keywords. The syntax is then similar to that for +tags, but should be applied with care: for example, a positive selection on +several TODO keywords cannot 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 +(resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO +part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will +not match TODO keywords in a DONE state. Examples: + +@table @samp +@item work/WAITING +Same as @samp{work+TODO="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 + +@node Timeline, Search view, 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 +@orgcmd{C-c a L,org-timeline} +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 Search view, Stuck projects, Timeline, Built-in agenda views +@subsection Search view +@cindex search view +@cindex text search +@cindex searching, for text + +This agenda view is a general text search facility for Org-mode entries. +It is particularly useful to find notes. + +@table @kbd +@orgcmd{C-c a s,org-search-view} +This is a special search that lets you select entries by matching a substring +or specific words using a boolean logic. +@end table +For example, the search string @samp{computer equipment} will find entries +that contain @samp{computer equipment} as a substring. If the two words are +separated by more space or a line break, the search will still match. +Search view can also search for specific keywords in the entry, using Boolean +logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}} +will search for note entries that contain the keywords @code{computer} +and @code{wifi}, but not the keyword @code{ethernet}, and which are also +not matched by the regular expression @code{8\.11[bg]}, meaning to +exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on +word search, other @samp{+} characters are optional. For more details, see +the docstring of the command @code{org-search-view}. + +@vindex org-agenda-text-search-extra-files +Note that in addition to the agenda files, this command will also search +the files listed in @code{org-agenda-text-search-extra-files}. + +@node Stuck projects, , Search view, 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 +@orgcmd{C-c a #,org-agenda-list-stuck-projects} +List projects that are stuck. +@kindex C-c a ! +@item C-c a ! +@vindex org-stuck-projects +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. + +Let's 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. Let's 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@footnote{@xref{Tag searches}.} +@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 + +Note that if a project is identified as non-stuck, the subtree of this entry +will still be searched for stuck projects. + +@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda Views +@section Presentation and sorting +@cindex presentation, of agenda items + +@vindex org-agenda-prefix-format +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 +@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@footnote{For +backward compatibility, the following also works: if there are several +such lines in a file, each specifies the category for the text below it. +The first category also applies to any text before the first CATEGORY +line. However, using this method is @emph{strongly} deprecated as it is +incompatible with the outline structure of the document. The correct +method for setting multiple categories in a buffer is using a +property.}: + +@example +#+CATEGORY: Thesis +@end example + +@noindent +@cindex property, CATEGORY +If you would like to have a special CATEGORY for a single entry or a +(sub)tree, give the entry a @code{:CATEGORY:} property with the +special category you want to apply as the value. + +@noindent +The display in the agenda buffer looks best if the category is not +longer than 10 characters. + +@noindent +You can set up icons for category by customizing the +@code{org-agenda-category-icon-alist} variable. + +@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 timestamp 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 timestamps, 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 Marvin 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 Marvin escorts the Hitchhikers to the bridge +@end example + +@vindex org-agenda-use-time-grid +@vindex org-agenda-time-grid +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 +@vindex org-agenda-files +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}). The priority used for sorting derives from the +priority cookie, with additions depending on how close an item is to its due +or scheduled date. +@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 + +@vindex org-agenda-sorting-strategy +Sorting can be customized using the variable +@code{org-agenda-sorting-strategy}, and may also include criteria based on +the estimated effort of an entry (@pxref{Effort estimates}). + +@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 +@orgcmd{n,org-agenda-next-line} +Next line (same as @key{up} and @kbd{C-p}). +@orgcmd{p,org-agenda-previous-line} +Previous line (same as @key{down} and @kbd{C-n}). +@tsubheading{View/Go to Org file} +@orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up} +Display the original location of the item in another window. +With prefix arg, make sure that the entire entry is made visible in the +outline, not only the heading. +@c +@orgcmd{L,org-agenda-recenter} +Display original location and recenter that window. +@c +@orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto} +Go to the original location of the item in another window. +@c +@orgcmd{@key{RET},org-agenda-switch-to} +Go to the original location of the item and delete other windows. +@c +@orgcmd{F,org-agenda-follow-mode} +@vindex org-agenda-start-with-follow-mode +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 +@orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer} +Display the entire subtree of the current item in an indirect buffer. With a +numeric prefix argument N, go up to level N and then take that tree. If N is +negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the +previously used indirect buffer. + +@orgcmd{C-c C-o,org-agenda-open-link} +Follow a link in the entry. This will offer a selection of any links in the +text belonging to the referenced Org node. If there is only one link, it +will be followed without a selection prompt. + +@tsubheading{Change display} +@cindex display changing, in agenda +@kindex o +@item o +Delete other windows. +@c +@c @kindex v d +@c @kindex d +@c @kindex v w +@c @kindex w +@c @kindex v m +@c @kindex v y +@c @item v d @ @r{or short} @ d +@c @itemx v w @ @r{or short} @ w +@c @itemx v m +@c @itemx v y +@orgcmdkskc{v d,d,org-aganda-day-view} +@xorgcmdkskc{v w,w,org-aganda-day-view} +@xorgcmd{v m,org-agenda-month-view} +@xorgcmd{v y,org-agenda-month-year} +Switch to day/week/month/year view. When switching to day or week view, +this setting becomes the default for subsequent agenda commands. Since +month and year views are slow to create, they do not become the default. +A numeric prefix argument may be used to jump directly to a specific day +of the year, ISO week, month, or year, respectively. For example, +@kbd{32 d} jumps to February 1st, @kbd{9 w} to ISO week number 9. When +setting day, week, or month view, a year may be encoded in the prefix +argument as well. For example, @kbd{200712 w} will jump to week 12 in +2007. If such a year specification has only one or two digits, it will +be mapped to the interval 1938-2037. +@c +@orgcmd{f,org-agenda-later} +Go forward in time to display the following @code{org-agenda-current-span} 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-current-span} days. +@c +@orgcmd{b,org-agenda-earlier} +Go backward in time to display earlier dates. +@c +@orgcmd{.,org-agenda-goto-today} +Go to today. +@c +@orgcmd{j,org-agenda-goto-date} +Prompt for a date and go there. +@c +@orgcmd{J,org-agenda-clock-goto} +Go to the currently clocked-in task @i{in the agenda buffer}. +@c +@orgcmd{D,org-agenda-toggle-diary} +Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}. +@c +@orgcmdkskc{v l,l,org-agenda-log-mode} +@kindex v L +@vindex org-log-done +@vindex org-agenda-log-mode-items +Toggle Logbook mode. In Logbook mode, entries that were 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. You can configure the entry +types that should be included in log mode using the variable +@code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show +all possible logbook entries, including state changes. When called with two +prefix args @kbd{C-u C-u}, show only logging information, nothing else. +@kbd{v L} is equivalent to @kbd{C-u v l}. +@c +@orgcmdkskc{v [,[,org-agenda-manipulate-query-add} +Include inactive timestamps into the current view. Only for weekly/daily +agenda and timeline views. +@c +@orgcmd{v a,org-agenda-archives-mode} +@xorgcmd{v A,org-agenda-archives-mode 'files} +Toggle Archives mode. In Archives mode, trees that are marked +@code{ARCHIVED} are also scanned when producing the agenda. When you use the +capital @kbd{A}, even all archive files are included. To exit archives mode, +press @kbd{v a} again. +@c +@orgcmdkskc{v R,R,org-agenda-clockreport-mode} +@vindex org-agenda-start-with-clockreport-mode +Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will +always show a table with the clocked times for the timespan and file scope +covered by the current agenda view. The initial setting for this mode in new +agenda buffers can be set with the variable +@code{org-agenda-start-with-clockreport-mode}. By using a prefix argument +when toggling this mode (i.e. @kbd{C-u R}), the clock table will not show +contributions from entries that are hidden by agenda filtering@footnote{Only +tags filtering will be respected here, effort filtering is ignored.}. +@c +@orgcmdkskc{v E,E,org-agenda-entry-text-mode} +@vindex org-agenda-start-with-entry-text-mode +@vindex org-agenda-entry-text-maxlines +Toggle entry text mode. In entry text mode, a number of lines from the Org +outline node referenced by an agenda line will be displayed below the line. +The maximum number of lines is given by the variable +@code{org-agenda-entry-text-maxlines}. Calling this command with a numeric +prefix argument will temporarily modify that number to the prefix value. +@c +@orgcmd{G,org-agenda-toggle-time-grid} +@vindex org-agenda-use-time-grid +@vindex org-agenda-time-grid +Toggle the time grid on and off. See also the variables +@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}. +@c +@orgcmd{r,org-agenda-rodo} +Recreate the agenda buffer, for example to reflect the changes after +modification of the timestamps of items with @kbd{S-@key{left}} and +@kbd{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. +@orgcmd{g,org-agenda-rodo} +Same as @kbd{r}. +@c +@orgcmdkskc{C-x C-s,s,org-save-all-org-buffers} +Save all Org buffers in the current Emacs session, and also the locations of +IDs. +@c +@orgcmd{C-c C-x C-c,org-agenda-columns} +@vindex org-columns-default-format +Invoke column view (@pxref{Column view}) in the agenda buffer. The column +view format is taken from the entry at point, or (if there is no entry at +point), from the first entry in the agenda view. So whatever the format for +that entry would be in the original buffer (taken from a property, from a +@code{#+COLUMNS} line, or from the default variable +@code{org-columns-default-format}), will be used in the agenda. + +@orgcmd{C-c C-x >,org-agenda-remove-restriction-lock} +Remove the restriction lock on the agenda, if it is currently restricted to a +file or subtree (@pxref{Agenda files}). + +@tsubheading{Secondary filtering and query editing} +@cindex filtering, by tag and effort, in agenda +@cindex tag filtering, in agenda +@cindex effort filtering, in agenda +@cindex query editing, in agenda + +@orgcmd{/,org-agenda-filter-by-tag} +@vindex org-agenda-filter-preset +Filter the current agenda view with respect to a tag and/or effort estimates. +The difference between this and a custom agenda command is that filtering is +very fast, so that you can switch quickly between different filters without +having to recreate the agenda.@footnote{Custom commands can preset a filter by +binding the variable @code{org-agenda-filter-preset} as an option. This +filter will then be applied to the view and persist as a basic filter through +refreshes and more secondary filtering. The filter is a global property of +the entire agenda view---in a block agenda, you should only set this in the +global options section, not in the section of an individual block.} + +You will be prompted for a tag selection letter; @key{SPC} will mean any tag at +all. Pressing @key{TAB} at that prompt will offer use completion to select a +tag (including any tags that do not have a selection character). The command +then hides all entries that do not contain or inherit this tag. When called +with prefix arg, remove the entries that @emph{do} have the tag. A second +@kbd{/} at the prompt will turn off the filter and unhide any hidden entries. +If the first key you press is either @kbd{+} or @kbd{-}, the previous filter +will be narrowed by requiring or forbidding the selected additional tag. +Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also +immediately use the @kbd{\} command. + +@vindex org-sort-agenda-noeffort-is-high +In order to filter for effort estimates, you should set up allowed +efforts globally, for example +@lisp +(setq org-global-properties + '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) +@end lisp +You can then filter for an effort by first typing an operator, one of +@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort +estimate in your array of allowed values, where @kbd{0} means the 10th value. +The filter will then restrict to entries with effort smaller-or-equal, equal, +or larger-or-equal than the selected value. If the digits 0-9 are not used +as fast access keys to tags, you can also simply press the index digit +directly without an operator. In this case, @kbd{<} will be assumed. For +application of the operator, entries without a defined effort will be treated +according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter +for tasks without effort definition, press @kbd{?} as the operator. + +Org also supports automatic, context-aware tag filtering. If the variable +@code{org-agenda-auto-exclude-function} is set to a user-defined function, +that function can decide which tags should be excluded from the agenda +automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET} +as a sub-option key and runs the auto exclusion logic. For example, let's +say you use a @code{Net} tag to identify tasks which need network access, an +@code{Errand} tag for errands in town, and a @code{Call} tag for making phone +calls. You could auto-exclude these tags based on the availability of the +Internet, and outside of business hours, with something like this: + +@lisp +@group +(defun org-my-auto-exclude-function (tag) + (and (cond + ((string= tag "Net") + (/= 0 (call-process "/sbin/ping" nil nil nil + "-c1" "-q" "-t1" "mail.gnu.org"))) + ((or (string= tag "Errand") (string= tag "Call")) + (let ((hour (nth 2 (decode-time)))) + (or (< hour 8) (> hour 21))))) + (concat "-" tag))) + +(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function) +@end group +@end lisp + +@orgcmd{\,org-agenda-filter-by-tag-refine} +Narrow the current agenda filter by an additional condition. When called with +prefix arg, remove the entries that @emph{do} have the tag, or that do match +the effort criterion. You can achieve the same effect by pressing @kbd{+} or +@kbd{-} as the first key after the @kbd{/} command. + +@c +@kindex [ +@kindex ] +@kindex @{ +@kindex @} +@item [ ] @{ @} +@table @i +@item @r{in} search view +add new search words (@kbd{[} and @kbd{]}) or new regular expressions +(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will +add a positive search term prefixed by @samp{+}, indicating that this search +term @i{must} occur/match in the entry. The closing bracket/brace will add a +negative search term which @i{must not} occur/match in the entry for it to be +selected. +@end table + +@tsubheading{Remote editing} +@cindex remote editing, from agenda + +@item 0-9 +Digit argument. +@c +@cindex undoing remote-editing events +@cindex remote editing, undo +@orgcmd{C-_,org-agenda-undo} +Undo a change due to a remote editing command. The change is undone +both in the agenda buffer and in the remote buffer. +@c +@orgcmd{t,org-agenda-todo} +Change the TODO state of the item, both in the agenda and in the +original org file. +@c +@orgcmd{C-S-@key{right},org-agenda-todo-nextset} +@orgcmd{C-S-@key{left},org-agenda-todo-previousset} +Switch to the next/previous set of TODO keywords. +@c +@orgcmd{C-k,org-agenda-kill} +@vindex org-agenda-confirm-kill +Delete the current agenda item along with the entire subtree belonging +to it in the original Org 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 +@orgcmd{C-c C-w,org-agenda-refile} +Refile the entry at point. +@c +@orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation} +@vindex org-archive-default-command +Archive the subtree corresponding to the entry at point using the default +archiving command set in @code{org-archive-default-command}. When using the +@code{a} key, confirmation will be required. +@c +@orgcmd{C-c C-x a,org-agenda-toggle-archive-tag} +Toggle the ARCHIVE tag for the current headline. +@c +@orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling} +Move the subtree corresponding to the current entry to its @emph{archive +sibling}. +@c +@orgcmdkskc{C-c C-x C-s,$,org-agenda-archive} +Archive the subtree corresponding to the current headline. This means the +entry will be moved to the configured archive location, most likely a +different file. +@c +@orgcmd{T,org-agenda-show-tags} +@vindex org-agenda-show-inherited-tags +Show all tags associated with the current item. This is useful if you have +turned off @code{org-agenda-show-inherited-tags}, but still want to see all +tags of a headline occasionally. +@c +@orgcmd{:,org-agenda-set-tags} +Set tags for the current headline. If there is an active region in the +agenda, change a tag for all headings in the region. +@c +@kindex , +@item , +Set the priority for the current item (@command{org-agenda-priority}). +Org-mode prompts for the priority character. If you reply with @key{SPC}, the +priority cookie is removed from the entry. +@c +@orgcmd{P,org-agenda-show-priority} +Display weighted priority of current item. +@c +@orgcmdkkc{+,S-@key{up},org-agenda-priority-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 +@orgcmdkkc{-,S-@key{down},org-agenda-priority-down} +Decrease the priority of the current item. +@c +@orgcmdkkc{z,C-c C-z,org-agenda-add-note} +@vindex org-log-into-drawer +Add a note to the entry. This note will be recorded, and then filed to the +same location where state change notes are put. Depending on +@code{org-log-into-drawer}, this may be inside a drawer. +@c +@orgcmd{C-c C-a,org-attach} +Dispatcher for all command related to attachments. +@c +@orgcmd{C-c C-s,org-agenda-schedule} +Schedule this item. With prefix arg remove the scheduling timestamp +@c +@orgcmd{C-c C-d,org-agenda-deadline} +Set a deadline for this item. With prefix arg remove the deadline. +@c +@orgcmd{k,org-agenda-action} +Agenda actions, to set dates for selected items to the cursor date. +This command also works in the calendar! The command prompts for an +additional key: +@example +m @r{Mark the entry at point for action. You can also make entries} + @r{in Org files with @kbd{C-c C-x C-k}.} +d @r{Set the deadline of the marked entry to the date at point.} +s @r{Schedule the marked entry at the date at point.} +r @r{Call @code{org-capture} with the cursor date as default date.} +@end example +@noindent +Press @kbd{r} afterward to refresh the agenda and see the effect of the +command. +@c +@orgcmd{S-@key{right},org-agenda-do-date-later} +Change the timestamp associated with the current line by one day into the +future. With a numeric prefix argument, change it by that many days. For +example, @kbd{3 6 5 S-@key{right}} will change it by a year. With a +@kbd{C-u} prefix, change the time by one hour. If you immediately repeat the +command, it will continue to change hours even without the prefix arg. With +a double @kbd{C-u C-u} prefix, do the same for changing minutes. The stamp +is changed in the original Org file, but the change is not directly reflected +in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer. +@c +@orgcmd{S-@key{left},org-agenda-do-date-earlier} +Change the timestamp associated with the current line by one day +into the past. +@c +@orgcmd{>,org-agenda-date-prompt} +Change the timestamp associated with the current line. The key @kbd{>} has +been chosen, because it is the same as @kbd{S-.} on my keyboard. +@c +@orgcmd{I,org-agenda-clock-in} +Start the clock on the current item. If a clock is running already, it +is stopped first. +@c +@orgcmd{O,org-agenda-clock-out} +Stop the previously started clock. +@c +@orgcmd{X,org-agenda-clock-cancel} +Cancel the currently running clock. +@c +@orgcmd{J,org-agenda-clock-goto} +Jump to the running clock in another window. + +@tsubheading{Bulk remote editing selected entries} +@cindex remote editing, bulk, from agenda + +@orgcmd{m,org-agenda-bulk-mark} +Mark the entry at point for bulk action. With prefix arg, mark that many +successive entries. +@c +@orgcmd{u,org-agenda-bulk-unmark} +Unmark entry for bulk action. +@c +@orgcmd{U,org-agenda-bulk-remove-all-marks} +Unmark all marked entries for bulk action. +@c +@orgcmd{B,org-agenda-bulk-action} +Bulk action: act on all marked entries in the agenda. This will prompt for +another key to select the action to be applied. The prefix arg to @kbd{B} +will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove +these special timestamps. +@example +r @r{Prompt for a single refile target and move all entries. The entries} + @r{will no longer be in the agenda; refresh (@kbd{g}) to bring them back.} +$ @r{Archive all selected entries.} +A @r{Archive entries by moving them to their respective archive siblings.} +t @r{Change TODO state. This prompts for a single TODO keyword and} + @r{changes the state of all selected entries, bypassing blocking and} + @r{suppressing logging notes (but not time stamps).} ++ @r{Add a tag to all selected entries.} +- @r{Remove a tag from all selected entries.} +s @r{Schedule all items to a new date. To shift existing schedule dates} + @r{by a fixed number of days, use something starting with double plus} + @r{at the prompt, for example @samp{++8d} or @samp{++2w}.} +S @r{Reschedule randomly by N days. N will be prompted for. With prefix} + @r{arg (@kbd{C-u B S}), scatter only accross weekdays.} +d @r{Set deadline to a specific date.} +@end example + + +@tsubheading{Calendar commands} +@cindex calendar commands, from agenda + +@orgcmd{c,org-agenda-goto-calendar} +Open the Emacs calendar and move to the date at the agenda cursor. +@c +@orgcmd{c,org-calendar-goto-agenda} +When in the calendar, compute and show the Org-mode agenda for the +date at the cursor. +@c +@cindex diary entries, creating from agenda +@orgcmd{i,org-agenda-diary-entry} +@vindex org-agenda-diary-file +Insert a new entry into the diary, using the date at the cursor and (for +block entries) the date at the mark. This will add to the Emacs diary +file@footnote{This file is parsed for the agenda when +@code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i} +command in the calendar. The diary file will pop up in another window, where +you can add the entry. + +If you configure @code{org-agenda-diary-file} to point to an Org-mode file, +Org will create entries (in org-mode syntax) in that file instead. Most +entries will be stored in a date-based outline tree that will later make it +easy to archive appointments from previous months/years. The tree will be +built under an entry with a @code{DATE_TREE} property, or else with years as +top-level entries. Emacs will prompt you for the entry text---if you specify +it, the entry will be created in @code{org-agenda-diary-file} without further +interaction. If you directly press @key{RET} at the prompt without typing +text, the target file will be shown in another window for you to finish the +entry there. See also the @kbd{k r} command. +@c +@orgcmd{M,org-agenda-phases-of-moon} +Show the phases of the moon for the three months around current date. +@c +@orgcmd{S,org-agenda-sunrise-sunset} +Show sunrise and sunset times. The geographical location must be set +with calendar variables, see the documentation for the Emacs calendar. +@c +@orgcmd{C,org-agenda-convert-date} +Convert the date at cursor into many other cultural and historic +calendars. +@c +@orgcmd{H,org-agenda-holidays} +Show holidays for three months around the cursor date. + +@item M-x org-export-icalendar-combine-agenda-files +Export a single iCalendar file containing entries from all agenda files. +This is a globally available command, and also available in the agenda menu. + +@tsubheading{Exporting to a file} +@orgcmd{C-x C-w,org-write-agenda} +@cindex exporting agenda views +@cindex agenda views, exporting +@vindex org-agenda-exporter-settings +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}), PDF (extension @file{.pdf}), +and plain text (any other extension). When called with a @kbd{C-u} prefix +argument, immediately open the newly created file. 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} +@orgcmd{q,org-agenda-quit} +Quit agenda, remove the agenda buffer. +@c +@cindex agenda files, removing buffers +@orgcmd{x,org-agenda-exit} +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, Exporting 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 +@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 +@vindex org-agenda-custom-commands +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\\>") + ("h" . "HOME+Name tags searches") ; description for "h" prefix + ("hl" tags "+home+Lisa") + ("hp" tags "+home+Peter") + ("hk" tags "+home+Kim"))) +@end group +@end lisp + +@noindent +The initial string in each entry defines the keys you have to press +after the dispatcher command @kbd{C-c a} in order to access the command. +Usually this will be just a single character, but if you have many +similar commands, you can also define two-letter combinations where the +first character is the same in several combinations and serves as a +prefix key@footnote{You can provide a description for a prefix key by +inserting a cons cell with the prefix and the description.}. 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} +@item C-c a h +as a prefix command for a HOME tags search where you have to press an +additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa, +Peter, or Kim) as additional tag to match. +@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, , Block agenda, Custom agenda views +@subsection Setting options for custom commands +@cindex options, for custom agenda views + +@vindex org-agenda-custom-commands +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))) + ("N" search "" + ((org-agenda-files '("~org/notes.org")) + (org-agenda-text-search-extra-files 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. The command @kbd{C-c a N} will do a text search limited +to only a single file. + +@vindex org-agenda-custom-commands +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 parentheses 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, Agenda column view, Custom agenda views, Agenda Views +@section 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's +@file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the +ghostscript @file{ps2pdf} utility must be installed on the system. Selecting +a PDF file with also create the postscript file.}, and iCalendar files. If +you want to do this only occasionally, use the command + +@table @kbd +@orgcmd{C-x C-w,org-write-agenda} +@cindex exporting agenda views +@cindex agenda views, exporting +@vindex org-agenda-exporter-settings +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}), iCalendar (extension +@file{.ics}), 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 + +@vindex org-agenda-add-entry-text-maxlines +@vindex htmlize-output-type +@vindex ps-number-of-columns +@vindex ps-landscape-mode +@lisp +(setq org-agenda-exporter-settings + '((ps-number-of-columns 2) + (ps-landscape-mode t) + (org-agenda-add-entry-text-maxlines 5) + (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 file names.}. Here is an example +that first defines 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 file names 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" "~/calendars/office.ics")))) +@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. If the extension is @file{.ics}, iCalendar export is +run export over all files that were used to construct the agenda, and +limit the export to entries listed in the agenda. Any other +extension produces a plain ASCII file. + +The export files are @emph{not} created when you use one of those +commands interactively because this might use too much overhead. +Instead, there is a special command to produce @emph{all} specified +files in one step: + +@table @kbd +@orgcmd{C-c a e,org-store-agenda-views} +Export all agenda views that have export file names 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@footnote{Quoting depends on the +system you use, please check the FAQ for examples.} +@example +emacs -eval '(org-batch-store-agenda-views \ + org-agenda-span month \ + org-agenda-start-day "2007-11-01" \ + 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 a 30-day +extent. + +You can also extract agenda information in a way that allows further +processing by other programs. See @ref{Extracting agenda information}, for +more information. + + +@node Agenda column view, , Exporting Agenda Views, Agenda Views +@section Using column view in the agenda +@cindex column view, in agenda +@cindex agenda, column view + +Column view (@pxref{Column view}) is normally used to view and edit +properties embedded in the hierarchical structure of an Org file. It can be +quite useful to use column view also from the agenda, where entries are +collected by certain criteria. + +@table @kbd +@orgcmd{C-c C-x C-c,org-agenda-columns} +Turn on column view in the agenda. +@end table + +To understand how to use this properly, it is important to realize that the +entries in the agenda are no longer in their proper outline environment. +This causes the following issues: + +@enumerate +@item +@vindex org-columns-default-format +@vindex org-overriding-columns-format +Org needs to make a decision which @code{COLUMNS} format to use. Since the +entries in the agenda are collected from different files, and different files +may have different @code{COLUMNS} formats, this is a non-trivial problem. +Org first checks if the variable @code{org-overriding-columns-format} is +currently set, and if so, takes the format from there. Otherwise it takes +the format associated with the first item in the agenda, or, if that item +does not have a specific format (defined in a property, or in its file), it +uses @code{org-columns-default-format}. +@item +@cindex property, special, CLOCKSUM +If any of the columns has a summary type defined (@pxref{Column attributes}), +turning on column view in the agenda will visit all relevant agenda files and +make sure that the computations of this property are up to date. This is +also true for the special @code{CLOCKSUM} property. Org will then sum the +values displayed in the agenda. In the daily/weekly agenda, the sums will +cover a single day; in all other views they cover the entire block. It is +vital to realize that the agenda may show the same entry @emph{twice} (for +example as scheduled and as a deadline), and it may show two entries from the +same hierarchy (for example a @emph{parent} and its @emph{child}). In these +cases, the summation in the agenda will lead to incorrect results because +some values will count double. +@item +When the column view in the agenda shows the @code{CLOCKSUM}, that is always +the entire clocked time for this item. So even in the daily/weekly agenda, +the clocksum listed in column view may originate from times outside the +current view. This has the advantage that you can compare these values with +a column listing the planned total effort for a task---one of the major +applications for column view in the agenda. If you want information about +clocked time in the displayed period use clock table mode (press @kbd{R} in +the agenda). +@end enumerate + + +@node Markup, Exporting, Agenda Views, Top +@chapter Markup for rich export + +When exporting Org-mode documents, the exporter tries to reflect the +structure of the document as accurately as possible in the backend. Since +export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting, +Org-mode has rules on how to prepare text for rich export. This section +summarizes the markup rules used in an Org-mode buffer. + +@menu +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Index entries:: Making an index +* Macro replacement:: Use macros to create complex output +* Embedded LaTeX:: LaTeX can be freely used inside Org documents +@end menu + +@node Structural markup elements, Images and tables, Markup, Markup +@section Structural markup elements + +@menu +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Initial text:: Text before the first heading? +* Lists:: Lists +* Paragraphs:: Paragraphs +* Footnote markup:: Footnotes +* Emphasis and monospace:: Bold, italic, etc. +* Horizontal rules:: Make a line +* Comment lines:: What will *not* be exported +@end menu + +@node Document title, Headings and sections, Structural markup elements, Structural markup elements +@subheading Document title +@cindex document title, markup rules + +@noindent +The title of the exported document is taken from the special line + +@cindex #+TITLE +@example +#+TITLE: This is the title of the document +@end example + +@noindent +If this line does not exist, the title is derived from the first non-empty, +non-comment line in the buffer. If no such line exists, or if you have +turned off exporting of the text before the first headline (see below), the +title will be the file name without extension. + +@cindex property, EXPORT_TITLE +If you are exporting only a subtree by marking is as the region, the heading +of the subtree will become the title of the document. If the subtree has a +property @code{EXPORT_TITLE}, that will take precedence. + +@node Headings and sections, Table of contents, Document title, Structural markup elements +@subheading Headings and sections +@cindex headings and sections, markup rules + +@vindex org-export-headline-levels +The outline structure of the document as described in @ref{Document +Structure}, forms the basis for defining sections of the exported document. +However, since the outline structure is also used for (for example) lists of +tasks, only the first three outline levels will be used as headings. Deeper +levels will become itemized lists. You can change the location of this +switch globally by setting the variable @code{org-export-headline-levels}, or on a +per-file basis with a line + +@cindex #+OPTIONS +@example +#+OPTIONS: H:4 +@end example + +@node Table of contents, Initial text, Headings and sections, Structural markup elements +@subheading Table of contents +@cindex table of contents, markup rules + +@vindex org-export-with-toc +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. The depth of the table of contents is by default the same as the +number of headline levels, but you can choose a smaller number, or turn off +the table of contents entirely, by configuring the variable +@code{org-export-with-toc}, or on a per-file basis with a line like + +@example +#+OPTIONS: toc:2 (only to two levels in TOC) +#+OPTIONS: toc:nil (no TOC at all) +@end example + +@node Initial text, Lists, Table of contents, Structural markup elements +@subheading Text before the first headline +@cindex text before first headline, markup rules +@cindex #+TEXT + +Org-mode normally exports the text before the first headline, and even uses +the first line as the document title. The text will be fully marked up. If +you need to include literal HTML, @LaTeX{}, or DocBook code, use the special +constructs described below in the sections for the individual exporters. + +@vindex org-export-skip-text-before-1st-heading +Some people like to use the space before the first headline for setup and +internal links and therefore would like to control the exported text before +the first headline in a different way. You can do so by setting the variable +@code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-file +basis, you can get the same effect with @samp{#+OPTIONS: skip:t}. + +@noindent +If you still want to have some text before the first headline, use the +@code{#+TEXT} construct: + +@example +#+OPTIONS: skip:t +#+TEXT: This text will go before the *first* headline. +#+TEXT: [TABLE-OF-CONTENTS] +#+TEXT: This goes between the table of contents and the first headline +@end example + +@node Lists, Paragraphs, Initial text, Structural markup elements +@subheading Lists +@cindex lists, markup rules + +Plain lists as described in @ref{Plain lists}, are translated to the backend's +syntax for such lists. Most backends support unordered, ordered, and +description lists. + +@node Paragraphs, Footnote markup, Lists, Structural markup elements +@subheading Paragraphs, line breaks, and quoting +@cindex paragraphs, markup rules + +Paragraphs are separated by at least one empty line. If you need to enforce +a line break within a paragraph, use @samp{\\} at the end of a line. + +To keep the line breaks in a region, but otherwise use normal formatting, you +can use this construct, which can also be used to format poetry. + +@cindex #+BEGIN_VERSE +@example +#+BEGIN_VERSE + Great clouds overhead + Tiny black birds rise and fall + Snow covers Emacs + + -- AlexSchroeder +#+END_VERSE +@end example + +When quoting a passage from another document, it is customary to format this +as a paragraph that is indented on both the left and the right margin. You +can include quotations in Org-mode documents like this: + +@cindex #+BEGIN_QUOTE +@example +#+BEGIN_QUOTE +Everything should be made as simple as possible, +but not any simpler -- Albert Einstein +#+END_QUOTE +@end example + +If you would like to center some text, do it like this: +@cindex #+BEGIN_CENTER +@example +#+BEGIN_CENTER +Everything should be made as simple as possible, \\ +but not any simpler +#+END_CENTER +@end example + + +@node Footnote markup, Emphasis and monospace, Paragraphs, Structural markup elements +@subheading Footnote markup +@cindex footnotes, markup rules +@cindex @file{footnote.el} + +Footnotes defined in the way described in @ref{Footnotes}, will be exported by +all backends. Org allows multiple references to the same note, and +different backends support this to varying degrees. + +@node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements +@subheading Emphasis and monospace + +@cindex underlined text, markup rules +@cindex bold text, markup rules +@cindex italic text, markup rules +@cindex verbatim text, markup rules +@cindex code text, markup rules +@cindex strike-through text, markup rules +You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} +and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text +in the code and verbatim string is not processed for Org-mode specific +syntax; it is exported verbatim. + +@node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements +@subheading Horizontal rules +@cindex horizontal rules, markup rules +A line consisting of only dashes, and at least 5 of them, will be +exported as a horizontal line (@samp{<hr/>} in HTML). + +@node Comment lines, , Horizontal rules, Structural markup elements +@subheading Comment lines +@cindex comment lines +@cindex exporting, not +@cindex #+BEGIN_COMMENT + +Lines starting with @samp{#} in column zero are treated as comments and will +never be exported. If you want an indented line to be treated as a comment, +start it with @samp{#+ }. Also entire subtrees starting with the word +@samp{COMMENT} will never be exported. Finally, regions surrounded by +@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported. + +@table @kbd +@kindex C-c ; +@item C-c ; +Toggle the COMMENT keyword at the beginning of an entry. +@end table + + +@node Images and tables, Literal examples, Structural markup elements, Markup +@section Images and Tables + +@cindex tables, markup rules +@cindex #+CAPTION +@cindex #+LABEL +Both the native Org-mode tables (@pxref{Tables}) and tables formatted with +the @file{table.el} package will be exported properly. For Org-mode tables, +the lines before the first horizontal separator line will become table header +lines. You can use the following lines somewhere before the table to assign +a caption and a label for cross references, and in the text you can refer to +the object with @code{\ref@{tab:basic-data@}}: + +@example +#+CAPTION: This is the caption for the next table (or link) +#+LABEL: tbl:basic-data + | ... | ...| + |-----|----| +@end example + +@cindex inlined images, markup rules +Some backends (HTML, @LaTeX{}, and DocBook) allow you to directly include +images into the exported document. Org does this, if a link to an image +files does not have a description part, for example @code{[[./img/a.jpg]]}. +If you wish to define a caption for the image and maybe a label for internal +cross references, make sure that the link is on a line by itself and precede +it with @code{#+CAPTION} and @code{#+LABEL} as follows: + +@example +#+CAPTION: This is the caption for the next figure link (or table) +#+LABEL: fig:SED-HR4049 +[[./img/a.jpg]] +@end example + +You may also define additional attributes for the figure. As this is +backend-specific, see the sections about the individual backends for more +information. + +@xref{Handling links,the discussion of image links}. + +@node Literal examples, Include files, Images and tables, Markup +@section Literal examples +@cindex literal examples, markup rules +@cindex code line references, markup rules + +You can include literal examples that should not be subjected to +markup. Such examples will be typeset in monospace, so this is well suited +for source code and similar examples. +@cindex #+BEGIN_EXAMPLE + +@example +#+BEGIN_EXAMPLE +Some example from a text file. +#+END_EXAMPLE +@end example + +Note that such blocks may be @i{indented} in order to align nicely with +indented text and in particular with plain list structure (@pxref{Plain +lists}). For simplicity when using small examples, you can also start the +example lines with a colon followed by a space. There may also be additional +whitespace before the colon: + +@example +Here is an example + : Some example from a text file. +@end example + +@cindex formatting source code, markup rules +If the example is source code from a programming language, or any other text +that can be marked up by font-lock in Emacs, you can ask for the example to +look like the fontified Emacs buffer@footnote{This works automatically for +the HTML backend (it requires version 1.34 of the @file{htmlize.el} package, +which is distributed with Org). Fontified code chunks in LaTeX can be +achieved using either the listings or the +@url{http://code.google.com/p/minted, minted,} package. To use listings, turn +on the variable @code{org-export-latex-listings} and ensure that the listings +package is included by the LaTeX header (e.g. by configuring +@code{org-export-latex-packages-alist}). See the listings documentation for +configuration options, including obtaining colored output. For minted it is +necessary to install the program @url{http://pygments.org, pygments}, in +addition to setting @code{org-export-latex-minted}, ensuring that the minted +package is included by the LaTeX header, and ensuring that the +@code{-shell-escape} option is passed to @file{pdflatex} (see +@code{org-latex-to-pdf-process}). See the documentation of the variables +@code{org-export-latex-listings} and @code{org-export-latex-minted} for +further details.}. This is done with the @samp{src} block, where you also +need to specify the name of the major mode that should be used to fontify the +example: +@cindex #+BEGIN_SRC + +@example +#+BEGIN_SRC emacs-lisp + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_SRC +@end example + +Both in @code{example} and in @code{src} snippets, you can add a @code{-n} +switch to the end of the @code{BEGIN} line, to get the lines of the example +numbered. If you use a @code{+n} switch, the numbering from the previous +numbered snippet will be continued in the current one. In literal examples, +Org will interpret strings like @samp{(ref:name)} as labels, and use them as +targets for special hyperlinks like @code{[[(name)]]} (i.e. the reference name +enclosed in single parenthesis). In HTML, hovering the mouse over such a +link will remote-highlight the corresponding code line, which is kind of +cool. + +You can also add a @code{-r} switch which @i{removes} the labels from the +source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the +labels in the source code while using line numbers for the links, which might +be useful to explain those in an org-mode example code.}. With the @code{-n} +switch, links to these references will be labeled by the line numbers from +the code listing, otherwise links will use the labels with no parentheses. +Here is an example: + +@example +#+BEGIN_SRC emacs-lisp -n -r +(save-excursion (ref:sc) + (goto-char (point-min)) (ref:jump) +#+END_SRC +In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]] +jumps to point-min. +@end example + +@vindex org-coderef-label-format +If the syntax for the label format conflicts with the language syntax, use a +@code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal +-n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}. + +HTML export also allows examples to be published as text areas, @xref{Text +areas in HTML export}. + +@table @kbd +@kindex C-c ' +@item C-c ' +Edit the source code example at point in its native mode. This works by +switching to a temporary buffer with the source code. You need to exit by +pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*} +or @samp{#} will get a comma prepended, to keep them from being interpreted +by Org as outline nodes or special comments. These commas will be stripped +for editing with @kbd{C-c '}, and also for export.}. The edited version will +then replace the old version in the Org buffer. Fixed-width regions +(where each line starts with a colon followed by a space) will be edited +using @code{artist-mode}@footnote{You may select a different-mode with the +variable @code{org-edit-fixed-width-region-mode}.} to allow creating ASCII +drawings easily. Using this command in an empty line will create a new +fixed-width region. +@kindex C-c l +@item C-c l +Calling @code{org-store-link} while editing a source code example in a +temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure +that it is unique in the current buffer, and insert it with the proper +formatting like @samp{(ref:label)} at the end of the current line. Then the +label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}. +@end table + + +@node Include files, Index entries, Literal examples, Markup +@section Include files +@cindex include files, markup rules + +During export, you can include the content of another file. For example, to +include your @file{.emacs} file, you could use: +@cindex #+INCLUDE + +@example +#+INCLUDE: "~/.emacs" src emacs-lisp +@end example +@noindent +The optional second and third parameter are the markup (e.g. @samp{quote}, +@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the +language for formatting the contents. The markup is optional; if it is not +given, the text will be assumed to be in Org-mode format and will be +processed normally. The include line will also allow additional keyword +parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the +first line and for each following line, @code{:minlevel} in order to get +org-mode content demoted to a specified level, as well as any options +accepted by the selected markup. For example, to include a file as an item, +use + +@example +#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " " +@end example + +@table @kbd +@kindex C-c ' +@item C-c ' +Visit the include file at point. +@end table + +@node Index entries, Macro replacement, Include files, Markup +@section Index entries +@cindex index entries, for publishing + +You can specify entries that will be used for generating an index during +publishing. This is done by lines starting with @code{#+INDEX}. An entry +the contains an exclamation mark will create a sub item. See @ref{Generating +an index} for more information. + +@example +* Curriculum Vitae +#+INDEX: CV +#+INDEX: Application!CV +@end example + + + + +@node Macro replacement, Embedded LaTeX, Index entries, Markup +@section Macro replacement +@cindex macro replacement, during export +@cindex #+MACRO + +You can define text snippets with + +@example +#+MACRO: name replacement text $1, $2 are arguments +@end example + +@noindent which can be referenced anywhere in the document (even in +code examples) with @code{@{@{@{name(arg1,arg2)@}@}@}}. In addition to +defined macros, @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc., +will reference information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and +similar lines. Also, @code{@{@{@{date(@var{FORMAT})@}@}@}} and +@code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date time +and to the modification time of the file being exported, respectively. +@var{FORMAT} should be a format string understood by +@code{format-time-string}. + +Macro expansion takes place during export, and some people use it to +construct complex HTML code. + + +@node Embedded LaTeX, , Macro replacement, Markup +@section Embedded @LaTeX{} +@cindex @TeX{} interpretation +@cindex @LaTeX{} interpretation + +Plain ASCII is normally sufficient for almost all note taking. Exceptions +include scientific notes, which often require mathematical symbols and the +occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on +Donald E. Knuth's @TeX{} system. Many of the features described here as +``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this +distinction.} is widely used to typeset scientific documents. Org-mode +supports embedding @LaTeX{} code into its files, because many academics are +used to writing and reading @LaTeX{} source code, and because it can be +readily processed to produce pretty output for a number of export backends. + +@menu +* Special symbols:: Greek letters and other symbols +* Subscripts and superscripts:: Simple syntax for raising/lowering text +* LaTeX fragments:: Complex formulas made easy +* Previewing LaTeX fragments:: What will this snippet look like? +* CDLaTeX mode:: Speed up entering of formulas +@end menu + +@node Special symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX +@subsection Special symbols +@cindex math symbols +@cindex special symbols +@cindex @TeX{} macros +@cindex @LaTeX{} fragments, markup rules +@cindex HTML entities +@cindex @LaTeX{} entities + +You can use @LaTeX{} 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 @LaTeX{} +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 + +@vindex org-entities +During export, these symbols will be transformed into the native format of +the exporter backend. Strings like @code{\alpha} will be exported as +@code{α} in the HTML output, and as @code{$\alpha$} in the @LaTeX{} +output. Similarly, @code{\nbsp} will become @code{ } in HTML and +@code{~} in @LaTeX{}. If you need such a symbol inside a word, terminate it +like this: @samp{\Aacute@{@}stor}. + +A large number of entities is provided, with names taken from both HTML and +@LaTeX{}; see the variable @code{org-entities} for the complete list. +@samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and +@samp{...} are all converted into special commands creating hyphens of +different lengths or a compact set of dots. + +If you would like to see entities displayed as UTF8 characters, use the +following command@footnote{You can turn this on by default by setting the +variable @code{org-pretty-entities}, or on a per-file base with the +@code{#+STARTUP} option @code{entitiespretty}.}: + +@table @kbd +@kindex C-c C-x \ +@item C-c C-x \ +Toggle display of entities as UTF-8 characters. This does not change the +buffer content which remains plain ASCII, but it overlays the UTF-8 character +for display purposes only. +@end table + +@node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX +@subsection Subscripts and superscripts +@cindex subscript +@cindex superscript + +Just like in @LaTeX{}, @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 of 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 + +@vindex org-export-with-sub-superscripts +To avoid interpretation as raised or lowered text, you can quote @samp{^} and +@samp{_} with a backslash: @samp{\^} and @samp{\_}. If you write a text +where the underscore is often used in a different context, Org's convention +to always interpret these as subscripts can get in your way. Configure the +variable @code{org-export-with-sub-superscripts} to globally change this +convention, or use, on a per-file basis: + +@example +#+OPTIONS: ^:@{@} +@end example + +@noindent With this setting, @samp{a_b} will not be interpreted as a +subscript, but @samp{a_@{b@}} will. + +@table @kbd +@kindex C-c C-x \ +@item C-c C-x \ +In addition to showing entities as UTF-8 characters, this command will also +format sub- and superscripts in a WYSIWYM way. +@end table + +@node LaTeX fragments, Previewing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX +@subsection @LaTeX{} fragments +@cindex @LaTeX{} fragments + +@vindex org-format-latex-header +Going beyond symbols and sub- and superscripts, a full formula language is +needed. Org-mode can contain @LaTeX{} math fragments, and it supports ways +to process these for several export backends. When exporting to @LaTeX{}, +the code is obviously left as it is. When exporting to HTML, Org invokes the +@uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in +HTML export}) to process and display the math@footnote{If you plan to use +this regularly or on pages with significant page views, you should install +@file{MathJax} on your own +server in order to limit the load of our server.}. Finally, it can also +process the mathematical expressions into images@footnote{For this to work +you need to be on a system with a working @LaTeX{} installation. You also +need the @file{dvipng} program, available at +@url{http://sourceforge.net/projects/dvipng/}. The @LaTeX{} header that will +be used when processing a fragment can be configured with the variable +@code{org-format-latex-header}.} that can be displayed in a browser or in +DocBook documents. + +@LaTeX{} fragments don't need any special marking at all. The following +snippets will be identified as @LaTeX{} source code: +@itemize @bullet +@item +Environments of any kind@footnote{When @file{MathJax} is used, only the +environment recognized by @file{MathJax} will be processed. When +@file{dvipng} is used to create images, any @LaTeX{} environments will be +handled.}. The only requirement is that the @code{\begin} statement appears +on a new line, preceded by only whitespace. +@item +Text within the usual @LaTeX{} 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, punctuation or a dash. +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 +@vindex org-format-latex-options +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 @LaTeX{} converter. + +@vindex org-export-with-LaTeX-fragments +LaTeX processing can be configured with the variable +@code{org-export-with-LaTeX-fragments}. The default setting is @code{t} +which means @file{MathJax} for HTML, and no processing for DocBook, ASCII and +LaTeX backends. You can also set this variable on a per-file basis using one +of these lines: + +@example +#+OPTIONS: LaTeX:t @r{Do the right thing automatically (MathJax)} +#+OPTIONS: LaTeX:dvipng @r{Force using dvipng images} +#+OPTIONS: LaTeX:nil @r{Do not process @LaTeX{} fragments at all} +#+OPTIONS: LaTeX:verbatim @r{Verbatim export, for jsMath or so} +@end example + +@node Previewing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX +@subsection Previewing LaTeX fragments +@cindex LaTeX fragments, preview + +If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to +produce 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 @LaTeX{} 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 + +@vindex org-format-latex-options +You can customize the variable @code{org-format-latex-options} to influence +some aspects of the preview. In particular, the @code{:scale} (and for HTML +export, @code{:html-scale}) property can be used to adjust the size of the +preview images. + +@node CDLaTeX mode, , Previewing LaTeX fragments, Embedded LaTeX +@subsection Using CDLa@TeX{} to enter math +@cindex CDLa@TeX{} + +CDLa@TeX{} mode is a minor mode that is normally used in combination with a +major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of +environments and math templates. Inside Org-mode, you can make use of +some of the features of CDLa@TeX{} mode. You need to install +@file{cdlatex.el} and @file{texmathp.el} (the latter comes also with +AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. +Don't use CDLa@TeX{} 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 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 CDLa@TeX{} 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 +@LaTeX{} 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 ^ +@vindex cdlatex-simplify-sub-super-scripts +Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} 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 @LaTeX{} fragments. If you wait more than 1.5 seconds +after the backquote, a help window will pop up. +@item +@kindex ' +Pressing the single-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 single-quote, a help window will pop up. Character +modification will work only inside @LaTeX{} fragments; outside the quote +is normal. +@end itemize + +@node Exporting, Publishing, Markup, 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 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. @LaTeX{} export lets you use Org-mode and +its structured editing functions to easily create @LaTeX{} files. DocBook +export makes it possible to convert Org files to many other formats using +DocBook tools. For project management you can create gantt and resource +charts by using TaskJuggler export. 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. + +Org supports export of selected regions when @code{transient-mark-mode} is +enabled (default in Emacs 23). + +@menu +* Selective export:: Using tags to select and exclude trees +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* TaskJuggler export:: Exporting to TaskJuggler +* Freemind export:: Exporting to Freemind mind maps +* XOXO export:: Exporting to XOXO +* iCalendar export:: Exporting in iCalendar format +@end menu + +@node Selective export, Export options, Exporting, Exporting +@section Selective export +@cindex export, selective by tags + +@vindex org-export-select-tags +@vindex org-export-exclude-tags +You may use tags to select the parts of a document that should be exported, +or to exclude parts from export. This behavior is governed by two variables: +@code{org-export-select-tags} and @code{org-export-exclude-tags}. + +Org first checks if any of the @emph{select} tags is present in the buffer. +If yes, all trees that do not carry one of these tags will be excluded. If a +selected tree is a subtree, the heading hierarchy above it will also be +selected for export, but not the text below those headings. + +@noindent +If none of the select tags is found, the whole buffer will be selected for +export. + +@noindent +Finally, all subtrees that are marked by any of the @emph{exclude} tags will +be removed from the export buffer. + +@node Export options, The export dispatcher, Selective export, Exporting +@section 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}). For a summary of other in-buffer settings not +specifically related to export, see @ref{In-buffer settings}. +In particular, note that you can place commonly-used (export) options in +a separate file which can be included using @code{#+SETUPFILE}. + +@table @kbd +@orgcmd{C-c C-e t,org-insert-export-options-template} +Insert template with export options, see example below. +@end table + +@cindex #+TITLE +@cindex #+AUTHOR +@cindex #+DATE +@cindex #+EMAIL +@cindex #+DESCRIPTION +@cindex #+KEYWORDS +@cindex #+LANGUAGE +@cindex #+TEXT +@cindex #+OPTIONS +@cindex #+BIND +@cindex #+LINK_UP +@cindex #+LINK_HOME +@cindex #+EXPORT_SELECT_TAGS +@cindex #+EXPORT_EXCLUDE_TAGS +@cindex #+XSLT +@cindex #+LATEX_HEADER +@vindex user-full-name +@vindex user-mail-address +@vindex org-export-default-language +@example +#+TITLE: the title to be shown (default is the buffer name) +#+AUTHOR: the author (default taken from @code{user-full-name}) +#+DATE: a date, fixed, or a format string for @code{format-time-string} +#+EMAIL: his/her email address (default from @code{user-mail-address}) +#+DESCRIPTION: the page description, e.g. for the XHTML meta tag +#+KEYWORDS: the page keywords, e.g. for the XHTML meta tag +#+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 ... +#+BIND: lisp-var lisp-val, e.g.: org-export-latex-low-levels itemize + @r{You need to confirm using these, or configure @code{org-export-allow-BIND}} +#+LINK_UP: the ``up'' link of an exported page +#+LINK_HOME: the ``home'' link of an exported page +#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@} +#+EXPORT_SELECT_TAGS: Tags that select a tree for export +#+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export +#+XSLT: the XSLT stylesheet used by DocBook exporter to generate FO file +@end example + +@noindent +The OPTIONS line is a compact@footnote{If you want to configure many options +this way, you can use several OPTIONS lines.} form to specify export +settings. Here you can: +@cindex headline levels +@cindex section-numbers +@cindex table of contents +@cindex line-break preservation +@cindex quoted HTML tags +@cindex fixed-width sections +@cindex tables +@cindex @TeX{}-like syntax for sub- and superscripts +@cindex footnotes +@cindex special strings +@cindex emphasized text +@cindex @TeX{} macros +@cindex @LaTeX{} 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 line-break-preservation (DOES NOT WORK)} +@@: @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.} +-: @r{turn on/off conversion of special strings.} +f: @r{turn on/off footnotes like this[1].} +todo: @r{turn on/off inclusion of TODO keywords into exported text} +pri: @r{turn on/off priority cookies} +tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}} +<: @r{turn on/off inclusion of any time/date stamps like DEADLINES} +*: @r{turn on/off emphasized text (bold, italic, underlined)} +TeX: @r{turn on/off simple @TeX{} macros in plain text} +LaTeX: @r{configure export of @LaTeX{} fragments. Default @code{auto}} +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} +email: @r{turn on/off inclusion of author email into exported file} +creator: @r{turn on/off inclusion of creator info into exported file} +timestamp: @r{turn on/off inclusion creation time into exported file} +d: @r{turn on/off inclusion of drawers} +@end example +@noindent +These options take effect in both the HTML and @LaTeX{} export, except for +@code{TeX} and @code{LaTeX}, which are respectively @code{t} and @code{nil} +for the @LaTeX{} export. The default values for these and many other options +are given by a set of variables. For a list of such variables, the +corresponding OPTIONS keys and also the publishing keys (@pxref{Project +alist}), see the constant @code{org-export-plist-vars}. + +When exporting only a single subtree by selecting it with @kbd{C-c @@} before +calling an export command, the subtree can overrule some of the file's export +settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE}, +@code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and +@code{EXPORT_OPTIONS}. + +@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting +@section The export dispatcher +@cindex dispatcher, for export commands + +All export commands can be reached using the export dispatcher, which is a +prefix key that prompts for an additional key specifying the command. +Normally the entire file is exported, but if there is an active region that +contains one outline tree, the first heading is used as document title and +the subtrees are exported. + +@table @kbd +@orgcmd{C-c C-e,org-export} +@vindex org-export-run-in-background +Dispatcher for export and publishing commands. Displays a help-window +listing the additional key(s) needed to launch an export or publishing +command. The prefix arg is passed through to the exporter. A double prefix +@kbd{C-u C-u} causes most commands to be executed in the background, in a +separate Emacs process@footnote{To make this behavior the default, customize +the variable @code{org-export-run-in-background}.}. +@orgcmd{C-c C-e v,org-export-visible} +Like @kbd{C-c C-e}, but only export the text that is currently visible +(i.e. not hidden by outline visibility). +@orgcmd{C-u C-u C-c C-e,org-export} +@vindex org-export-run-in-background +Call the exporter, but reverse the setting of +@code{org-export-run-in-background}, i.e. request background processing if +not set, or force processing in the current Emacs process if set. +@end table + +@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting +@section ASCII/Latin-1/UTF-8 export +@cindex ASCII export +@cindex Latin-1 export +@cindex UTF-8 export + +ASCII export produces a simple and very readable version of an Org-mode +file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file +with special characters and symbols available in these encodings. + +@cindex region, active +@cindex active region +@cindex transient-mark-mode +@table @kbd +@orgcmd{C-c C-e a,org-export-as-ascii} +@cindex property, EXPORT_FILE_NAME +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@footnote{This requires +@code{transient-mark-mode} be turned on.}, only the region will be +exported. If the selected region is a single tree@footnote{To select the +current subtree, use @kbd{C-c @@}.}, the tree head will +become the document title. If the tree head entry has or inherits an +@code{EXPORT_FILE_NAME} property, that name will be used for the +export. +@orgcmd{C-c C-e A,org-export-as-ascii-to-buffer} +Export to a temporary buffer. Do not create a file. +@orgcmd{C-c C-e n,org-export-as-latin1} +@xorgcmd{C-c C-e N,org-export-as-latin1-to-buffer} +Like the above commands, but use Latin-1 encoding. +@orgcmd{C-c C-e u,org-export-as-utf8} +@xorgcmd{C-c C-e U,org-export-as-utf8-to-buffer} +Like the above commands, but use UTF-8 encoding. +@item C-c C-e v a/n/u +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 body line 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. + +@vindex org-export-ascii-links-to-notes +Links will be exported in a footnote-like style, with the descriptive part in +the text and the link in a note before the next heading. See the variable +@code{org-export-ascii-links-to-notes} for details and other options. + +@node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 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 Gruber's @emph{markdown} +language, but with additional support for tables. + +@menu +* HTML Export commands:: How to invoke HTML export +* Quoting HTML tags:: Using direct HTML in Org-mode +* Links in HTML export:: How links will be interpreted and formatted +* Tables in HTML export:: How to modify the formatting of tables +* Images in HTML export:: How to insert figures into HTML output +* Math formatting in HTML export:: Beautiful math also on the web +* Text areas in HTML export:: An alternative way to show an example +* CSS support:: Changing the appearance of the output +* JavaScript support:: Info and Folding in a web browser +@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 +@orgcmd{C-c C-e h,org-export-as-html} +@cindex property, EXPORT_FILE_NAME +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@footnote{This requires +@code{transient-mark-mode} be turned on.}, only the region will be +exported. If the selected region is a single tree@footnote{To select the +current subtree, use @kbd{C-c @@}.}, the tree head will become the document +title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} +property, that name will be used for the export. +@orgcmd{C-c C-e b,org-export-as-html-and-open} +Export as HTML file and immediately open it with a browser. +@orgcmd{C-c C-e H,org-export-as-html-to-buffer} +Export to a temporary buffer. Do not create a file. +@orgcmd{C-c C-e R,org-export-region-as-html} +Export the active region to a temporary buffer. With a prefix argument, do +not produce the file header and footer, but just the plain HTML section for +the region. This is good for cut-and-paste operations. +@item C-c C-e v h/b/H/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 numeric 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 in HTML export, 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 + +@cindex #+HTML +@cindex #+BEGIN_HTML +@example +#+HTML: Literal HTML code for export +@end example + +@noindent or +@cindex #+BEGIN_HTML + +@example +#+BEGIN_HTML +All lines between these markers are exported literally +#+END_HTML +@end example + + +@node Links in HTML export, Tables in HTML export, Quoting HTML tags, HTML export +@subsection Links in HTML export + +@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. This +includes automatic links created by radio targets (@pxref{Radio +targets}). Links to external files will still work if the target file is on +the same @i{relative} path as the published Org 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, at the same relative +path. @samp{id:} links can then be used to jump to specific entries across +files. For information related to linking files while publishing them to a +publishing directory see @ref{Publishing links}. + +If you want to specify attributes for links, you can do so using a special +@code{#+ATTR_HTML} line to define attributes that will be added to the +@code{<a>} or @code{<img>} tags. Here is an example that sets @code{title} +and @code{style} attributes for a link: + +@cindex #+ATTR_HTML +@example +#+ATTR_HTML: title="The Org-mode homepage" style="color:red;" +[[http://orgmode.org]] +@end example + +@node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export +@subsection Tables +@cindex tables, in HTML +@vindex org-export-html-table-tag + +Org-mode tables are exported to HTML using the table tag defined in +@code{org-export-html-table-tag}. The default setting makes tables without +cell borders and frame. If you would like to change this for individual +tables, place something like the following before the table: + +@cindex #+CAPTION +@cindex #+ATTR_HTML +@example +#+CAPTION: This is a table with lines around and between cells +#+ATTR_HTML: border="2" rules="all" frame="all" +@end example + +@node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export +@subsection Images in HTML export + +@cindex images, inline in HTML +@cindex inlining images in HTML +@vindex org-export-html-inline-images +HTML export can inline images given as links in the Org 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 + +If you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}. +In the example below we specify the @code{alt} and @code{title} attributes to +support text viewers and accessibility, and align it to the right. + +@cindex #+CAPTION +@cindex #+ATTR_HTML +@example +#+CAPTION: A black cat stalking a spider +#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right" +[[./img/a.jpg]] +@end example + +@noindent +and you could use @code{http} addresses just as well. + +@node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export +@subsection Math formatting in HTML export +@cindex MathJax +@cindex dvipng + +@LaTeX{} math snippets (@pxref{LaTeX fragments}) can be displayed in two +different ways on HTML pages. The default is to use the +@uref{http://www.mathjax.org, MathJax system} which should work out of the +box with Org mode installation because @code{http://orgmode.org} serves +@file{MathJax} for Org-mode users for small applications and for testing +purposes. @b{If you plan to use this regularly or on pages with significant +page views, you should install@footnote{Installation instructions can be +found on the MathJax website, see +@uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on +your own server in order to limit the load of our server.} To configure +@file{MathJax}, use the variable @code{org-export-html-mathjax-options} or +insert something like the following into the buffer: + +@example +#+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js" +@end example + +@noindent See the docstring of the variable +@code{org-export-html-mathjax-options} for the meaning of the parameters in +this line. + +If you prefer, you can also request that @LaTeX{} fragments are processed +into small images that will be inserted into the browser page. Before the +availability of MathJax, this was the default method for Org files. This +method requires that the @file{dvipng} program is available on your system. +You can still get this processing with + +@example +#+OPTIONS: LaTeX:dvipng +@end example + +@node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export +@subsection Text areas in HTML export + +@cindex text areas, in HTML +An alternative way to publish literal code examples in HTML is to use text +areas, where the example can even be edited before pasting it into an +application. It is triggered by a @code{-t} switch at an @code{example} or +@code{src} block. Using this switch disables any options for syntax and +label highlighting, and line numbering, which may be present. You may also +use @code{-h} and @code{-w} switches to specify the height and width of the +text area, which default to the number of lines in the example, and 80, +respectively. For example + +@example +#+BEGIN_EXAMPLE -t -w 40 + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_EXAMPLE +@end example + + +@node CSS support, JavaScript support, Text areas in HTML export, HTML export +@subsection CSS support +@cindex CSS, for HTML export +@cindex HTML export, CSS + +@vindex org-export-html-todo-kwd-class-prefix +@vindex org-export-html-tag-class-prefix +You can also give style information for the exported file. The HTML exporter +assigns the following special CSS classes@footnote{If the classes on TODO +keywords and tags lead to conflicts, use the variables +@code{org-export-html-todo-kwd-class-prefix} and +@code{org-export-html-tag-class-prefix} to make them unique.} to appropriate +parts of the document---your style specifications may change these, in +addition to any of the standard classes like for headlines, tables, etc. +@example +p.author @r{author information, including email} +p.date @r{publishing date} +p.creator @r{creator info, about org-mode version} +.title @r{document title} +.todo @r{TODO keywords, all not-done states} +.done @r{the DONE keywords, all stated the count as done} +.WAITING @r{each TODO keyword also uses a class named after itself} +.timestamp @r{timestamp} +.timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED} +.timestamp-wrapper @r{span around keyword plus timestamp} +.tag @r{tag in a headline} +._HOME @r{each tag uses itself as a class, "@@" replaced by "_"} +.target @r{target for links} +.linenr @r{the line number in a code example} +.code-highlighted @r{for highlighting referenced code lines} +div.outline-N @r{div for outline level N (headline plus text))} +div.outline-text-N @r{extra div for text at outline level N} +.section-number-N @r{section number in headlines, different for each level} +div.figure @r{how to format an inlined image} +pre.src @r{formatted source code} +pre.example @r{normal example} +p.verse @r{verse paragraph} +div.footnotes @r{footnote section headline} +p.footnote @r{footnote definition paragraph, containing a footnote} +.footref @r{a footnote reference number (always a <sup>)} +.footnum @r{footnote number in footnote definition (always <sup>)} +@end example + +@vindex org-export-html-style-default +@vindex org-export-html-style-include-default +@vindex org-export-html-style +@vindex org-export-html-extra +@vindex org-export-html-style-default +Each exported file contains a compact default style that defines these +classes in a basic way@footnote{This style is defined in the constant +@code{org-export-html-style-default}, which you should not modify. To turn +inclusion of these defaults off, customize +@code{org-export-html-style-include-default}}. You may overwrite these +settings, or add to them by using the variables @code{org-export-html-style} +(for Org-wide settings) and @code{org-export-html-style-extra} (for more +fine-grained settings, like file-local settings). To set the latter variable +individually for each file, you can use + +@cindex #+STYLE +@example +#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +@end example + +@noindent +For longer style definitions, you can use several such lines. You could also +directly write a @code{<style>} @code{</style>} section in this way, without +referring to an external file. + +In order to add styles to a subtree, use the @code{:HTML_CONTAINER_CLASS:} +property to assign a class to the tree. In order to specify CSS styles for a +particular headline, you can use the id specified in a @code{:CUSTOM_ID:} +property. + +@c FIXME: More about header and footer styles +@c FIXME: Talk about links and targets. + +@node JavaScript support, , CSS support, HTML export +@subsection JavaScript supported display of web pages + +@cindex Rose, Sebastian +Sebastian Rose has written a JavaScript program especially designed to +enhance the web viewing experience of HTML files created with Org. This +program allows you to view large files in two different ways. The first one +is an @emph{Info}-like mode where each section is displayed separately and +navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys +as well, press @kbd{?} for an overview of the available keys). The second +view type is a @emph{folding} view much like Org provides inside Emacs. The +script is available at @url{http://orgmode.org/org-info.js} and you can find +the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}. +We host the script at our site, but if you use it a lot, you might +not want to be dependent on @url{orgmode.org} and prefer to install a local +copy on your own web server. + +To use the script, you need to make sure that the @file{org-jsinfo.el} module +gets loaded. It should be loaded by default, but you can try @kbd{M-x +customize-variable @key{RET} org-modules @key{RET}} to convince yourself that +this is indeed the case. All it then takes to make use of the program is +adding a single line to the Org file: + +@cindex #+INFOJS_OPT +@example +#+INFOJS_OPT: view:info toc:nil +@end example + +@noindent +If this line is found, the HTML header will automatically contain the code +needed to invoke the script. Using the line above, you can set the following +viewing options: + +@example +path: @r{The path to the script. The default is to grab the script from} + @r{@url{http://orgmode.org/org-info.js}, but you might want to have} + @r{a local copy and use a path like @samp{../scripts/org-info.js}.} +view: @r{Initial view when website is first shown. Possible values are:} + info @r{Info-like interface with one section per page.} + overview @r{Folding interface, initially showing only top-level.} + content @r{Folding interface, starting with all headlines visible.} + showall @r{Folding interface, all headlines and text visible.} +sdepth: @r{Maximum headline level that will still become an independent} + @r{section for info and folding modes. The default is taken from} + @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).} + @r{If this is smaller than in @code{org-export-headline-levels}, each} + @r{info/folding section can still contain child headlines.} +toc: @r{Should the table of contents @emph{initially} be visible?} + @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.} +tdepth: @r{The depth of the table of contents. The defaults are taken from} + @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.} +ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?} + @r{If yes, the toc will never be displayed as a section.} +ltoc: @r{Should there be short contents (children) in each section?} + @r{Make this @code{above} if the section should be above initial text.} +mouse: @r{Headings are highlighted when the mouse is over them. Should be} + @r{@samp{underline} (default) or a background color like @samp{#cccccc}.} +buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the} + @r{default), only one such button will be present.} +@end example +@noindent +@vindex org-infojs-options +@vindex org-export-html-use-infojs +You can choose default values for these options by customizing the variable +@code{org-infojs-options}. If you always want to apply the script to your +pages, configure the variable @code{org-export-html-use-infojs}. + +@node LaTeX and PDF export, DocBook export, HTML export, Exporting +@section @LaTeX{} and PDF export +@cindex @LaTeX{} export +@cindex PDF export +@cindex Guerry, Bastien + +Org-mode contains a @LaTeX{} exporter written by Bastien Guerry. With +further processing@footnote{The default LaTeX output is designed for +processing with pdftex or latex. It includes packages that are not +compatible with xetex and possibly luatex. See the variables +@code{org-export-latex-default-packages-alist} and +@code{org-export-latex-packages-alist}.}, this backend is also used to +produce PDF output. Since the @LaTeX{} output uses @file{hyperref} to +implement links and cross references, the PDF output file will be fully +linked. + +@menu +* LaTeX/PDF export commands:: Which key invokes which commands +* Header and sectioning:: Setting up the export file structure +* Quoting LaTeX code:: Incorporating literal @LaTeX{} code +* Tables in LaTeX export:: Options for exporting tables to @LaTeX{} +* Images in LaTeX export:: How to insert figures into @LaTeX{} output +* Beamer class export:: Turning the file into a presentation +@end menu + +@node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export +@subsection @LaTeX{} export commands + +@cindex region, active +@cindex active region +@cindex transient-mark-mode +@table @kbd +@orgcmd{C-c C-e l,org-export-as-latex} +@cindex property EXPORT_FILE_NAME +Export as @LaTeX{} file @file{myfile.tex}. For an Org file +@file{myfile.org}, the ASCII file will be @file{myfile.tex}. The file will +be overwritten without warning. If there is an active region@footnote{This +requires @code{transient-mark-mode} be turned on.}, only the region will be +exported. If the selected region is a single tree@footnote{To select the +current subtree, use @kbd{C-c @@}.}, the tree head will become the document +title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME} +property, that name will be used for the export. +@orgcmd{C-c C-e L,org-export-as-latex-to-buffer} +Export to a temporary buffer. Do not create a file. +@item C-c C-e v l/L +Export only the visible part of the document. +@item M-x org-export-region-as-latex +Convert the region to @LaTeX{} 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 @LaTeX{} +code. +@orgcmd{C-c C-e p,org-export-as-pdf} +Export as @LaTeX{} and then process to PDF. +@orgcmd{C-c C-e d,org-export-as-pdf-and-open} +Export as @LaTeX{} and then process to PDF, then open the resulting PDF file. +@end table + +@cindex headline levels, for exporting +@vindex org-latex-low-levels +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 numeric 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 Header and sectioning, Quoting LaTeX code, LaTeX/PDF export commands, LaTeX and PDF export +@subsection Header and sectioning structure +@cindex @LaTeX{} class +@cindex @LaTeX{} sectioning structure +@cindex @LaTeX{} header +@cindex header, for LaTeX files +@cindex sectioning structure, for LaTeX export + +By default, the @LaTeX{} output uses the class @code{article}. + +@vindex org-export-latex-default-class +@vindex org-export-latex-classes +@vindex org-export-latex-default-packages-alist +@vindex org-export-latex-packages-alist +@cindex #+LATEX_HEADER +@cindex #+LATEX_CLASS +@cindex #+LATEX_CLASS_OPTIONS +@cindex property, LATEX_CLASS +@cindex property, LATEX_CLASS_OPTIONS +You can change this globally by setting a different value for +@code{org-export-latex-default-class} or locally by adding an option like +@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:} +property that applies when exporting a region containing only this (sub)tree. +The class must be listed in @code{org-export-latex-classes}. This variable +defines a header template for each class@footnote{Into which the values of +@code{org-export-latex-default-packages-alist} and +@code{org-export-latex-packages-alist} are spliced.}, and allows you to +define the sectioning structure for each class. You can also define your own +classes there. @code{#+LaTeX_CLASS_OPTIONS} or a @code{LaTeX_CLASS_OPTIONS} +property can specify the options for the @code{\documentclass} macro. You +can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to the +header. See the docstring of @code{org-export-latex-classes} for more +information. + +@node Quoting LaTeX code, Tables in LaTeX export, Header and sectioning, LaTeX and PDF export +@subsection Quoting @LaTeX{} code + +Embedded @LaTeX{} as described in @ref{Embedded LaTeX}, will be correctly +inserted into the @LaTeX{} file. This includes simple macros like +@samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore, +you can add special code that should only be present in @LaTeX{} export with +the following constructs: + +@cindex #+LaTeX +@cindex #+BEGIN_LaTeX +@example +#+LaTeX: Literal LaTeX code for export +@end example + +@noindent or +@cindex #+BEGIN_LaTeX + +@example +#+BEGIN_LaTeX +All lines between these markers are exported literally +#+END_LaTeX +@end example + + +@node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export +@subsection Tables in @LaTeX{} export +@cindex tables, in @LaTeX{} export + +For @LaTeX{} export of a table, you can specify a label and a caption +(@pxref{Images and tables}). You can also use the @code{ATTR_LaTeX} line to +request a @code{longtable} environment for the table, so that it may span +several pages, or provide the @code{multicolumn} keyword that will make the +table span the page in a multicolumn environment (@code{table*} environment). +Finally, you can set the alignment string: + +@cindex #+CAPTION +@cindex #+LABEL +@cindex #+ATTR_LaTeX +@example +#+CAPTION: A long table +#+LABEL: tbl:long +#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l +| ..... | ..... | +| ..... | ..... | +@end example + + +@node Images in LaTeX export, Beamer class export, Tables in LaTeX export, LaTeX and PDF export +@subsection Images in @LaTeX{} export +@cindex images, inline in @LaTeX{} +@cindex inlining images in @LaTeX{} + +Images that are linked to without a description part in the link, like +@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF +output file resulting from @LaTeX{} processing. Org will use an +@code{\includegraphics} macro to insert the image. If you have specified a +caption and/or a label as described in @ref{Images and tables}, the figure +will be wrapped into a @code{figure} environment and thus become a floating +element. You can use an @code{#+ATTR_LaTeX:} line to specify the various +options that can be used in the optional argument of the +@code{\includegraphics} macro. To modify the placement option of the +@code{figure} environment, add something like @samp{placement=[h!]} to the +Attributes. + +If you would like to let text flow around the image, add the word @samp{wrap} +to the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the left +half of the page. To fine-tune, the @code{placement} field will be the set +of additional arguments needed by the @code{wrapfigure} environment. Note +that if you change the size of the image, you need to use compatible settings +for @code{\includegraphics} and @code{wrapfigure}. + +@cindex #+CAPTION +@cindex #+LABEL +@cindex #+ATTR_LaTeX +@example +#+CAPTION: The black-body emission of the disk around HR 4049 +#+LABEL: fig:SED-HR4049 +#+ATTR_LaTeX: width=5cm,angle=90 +[[./img/sed-hr4049.pdf]] + +#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@} +[[./img/hst.png]] +@end example + +If you need references to a label created in this way, write +@samp{\ref@{fig:SED-HR4049@}} just like in @LaTeX{}. + +@node Beamer class export, , Images in LaTeX export, LaTeX and PDF export +@subsection Beamer class export + +The LaTeX class @file{beamer} allows production of high quality presentations +using LaTeX and pdf processing. Org-mode has special support for turning an +Org-mode file or tree into a @file{beamer} presentation. + +When the LaTeX class for the current buffer (as set with @code{#+LaTeX_CLASS: +beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is +@code{beamer}, a special export mode will turn the file or tree into a beamer +presentation. Any tree with not-too-deep level nesting should in principle be +exportable as a beamer presentation. By default, the top-level entries (or +the first level below the selected subtree heading) will be turned into +frames, and the outline structure below this level will become itemize lists. +You can also configure the variable @code{org-beamer-frame-level} to a +different level---then the hierarchy above frames will produce the sectioning +structure of the presentation. + +A template for useful in-buffer settings or properties can be inserted into +the buffer with @kbd{M-x org-insert-beamer-options-template}. Among other +things, this will install a column view format which is very handy for +editing special properties used by beamer. + +You can influence the structure of the presentation using the following +properties: + +@table @code +@item BEAMER_env +The environment that should be used to format this entry. Valid environments +are defined in the constant @code{org-beamer-environments-default}, and you +can define more in @code{org-beamer-environments-extra}. If this property is +set, the entry will also get a @code{:B_environment:} tag to make this +visible. This tag has no semantic meaning, it is only a visual aid. +@item BEAMER_envargs +The beamer-special arguments that should be used for the environment, like +@code{[t]} or @code{[<+->]} of @code{<2-3>}. If the @code{BEAMER_col} +property is also set, something like @code{C[t]} can be added here as well to +set an options argument for the implied @code{columns} environment. +@code{c[t]} or @code{c<2->} will set an options for the implied @code{column} +environment. +@item BEAMER_col +The width of a column that should start with this entry. If this property is +set, the entry will also get a @code{:BMCOL:} property to make this visible. +Also this tag is only a visual aid. When this is a plain number, it will be +interpreted as a fraction of @code{\textwidth}. Otherwise it will be assumed +that you have specified the units, like @samp{3cm}. The first such property +in a frame will start a @code{columns} environment to surround the columns. +This environment is closed when an entry has a @code{BEAMER_col} property +with value 0 or 1, or automatically at the end of the frame. +@item BEAMER_extra +Additional commands that should be inserted after the environment has been +opened. For example, when creating a frame, this can be used to specify +transitions. +@end table + +Frames will automatically receive a @code{fragile} option if they contain +source code that uses the verbatim environment. Special @file{beamer} +specific code can be inserted using @code{#+BEAMER:} and +@code{#+BEGIN_beamer...#+end_beamer} constructs, similar to other export +backends, but with the difference that @code{#+LaTeX:} stuff will be included +in the presentation as well. + +Outline nodes with @code{BEAMER_env} property value @samp{note} or +@samp{noteNH} will be formatted as beamer notes, i,e, they will be wrapped +into @code{\note@{...@}}. The former will include the heading as part of the +note text, the latter will ignore the heading of that node. To simplify note +generation, it is actually enough to mark the note with a @emph{tag} (either +@code{:B_note:} or @code{:B_noteNH:}) instead of creating the +@code{BEAMER_env} property. + +You can turn on a special minor mode @code{org-beamer-mode} for editing +support with + +@example +#+STARTUP: beamer +@end example + +@table @kbd +@orgcmd{C-c C-b,org-beamer-select-environment} +In @code{org-beamer-mode}, this key offers fast selection of a beamer +environment or the @code{BEAMER_col} property. +@end table + +Column view provides a great way to set the environment of a node and other +important parameters. Make sure you are using a COLUMN format that is geared +toward this special purpose. The command @kbd{M-x +org-insert-beamer-options-template} defines such a format. + +Here is a simple example Org document that is intended for beamer export. + +@smallexample +#+LaTeX_CLASS: beamer +#+TITLE: Example Presentation +#+AUTHOR: Carsten Dominik +#+LaTeX_CLASS_OPTIONS: [presentation] +#+BEAMER_FRAME_LEVEL: 2 +#+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@} +#+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex) + +* This is the first structural section + +** Frame 1 \\ with a subtitle +*** Thanks to Eric Fraga :BMCOL:B_block: + :PROPERTIES: + :BEAMER_env: block + :BEAMER_envargs: C[t] + :BEAMER_col: 0.5 + :END: + for the first viable beamer setup in Org +*** Thanks to everyone else :BMCOL:B_block: + :PROPERTIES: + :BEAMER_col: 0.5 + :BEAMER_env: block + :BEAMER_envargs: <2-> + :END: + for contributing to the discussion +**** This will be formatted as a beamer note :B_note: +** Frame 2 \\ where we will not use columns +*** Request :B_block: + Please test this stuff! + :PROPERTIES: + :BEAMER_env: block + :END: +@end smallexample + +For more information, see the documentation on Worg. + +@node DocBook export, TaskJuggler export, LaTeX and PDF export, Exporting +@section DocBook export +@cindex DocBook export +@cindex PDF export +@cindex Cui, Baoqiu + +Org contains a DocBook exporter written by Baoqiu Cui. Once an Org file is +exported to DocBook format, it can be further processed to produce other +formats, including PDF, HTML, man pages, etc., using many available DocBook +tools and stylesheets. + +Currently DocBook exporter only supports DocBook V5.0. + +@menu +* DocBook export commands:: How to invoke DocBook export +* Quoting DocBook code:: Incorporating DocBook code in Org files +* Recursive sections:: Recursive sections in DocBook +* Tables in DocBook export:: Tables are exported as HTML tables +* Images in DocBook export:: How to insert figures into DocBook output +* Special characters:: How to handle special characters +@end menu + +@node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export +@subsection DocBook export commands + +@cindex region, active +@cindex active region +@cindex transient-mark-mode +@table @kbd +@orgcmd{C-c C-e D,org-export-as-docbook} +@cindex property EXPORT_FILE_NAME +Export as DocBook file. For an Org file, @file{myfile.org}, the DocBook XML +file will be @file{myfile.xml}. The file will be overwritten without +warning. If there is an active region@footnote{This requires +@code{transient-mark-mode} to be turned on}, only the region will be +exported. If the selected region is a single tree@footnote{To select the +current subtree, use @kbd{C-c @@}.}, the tree head will become the document +title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} +property, that name will be used for the export. +@orgcmd{C-c C-e V,org-export-as-docbook-pdf-and-open} +Export as DocBook file, process to PDF, then open the resulting PDF file. + +@vindex org-export-docbook-xslt-proc-command +@vindex org-export-docbook-xsl-fo-proc-command +Note that, in order to produce PDF output based on exported DocBook file, you +need to have XSLT processor and XSL-FO processor software installed on your +system. Check variables @code{org-export-docbook-xslt-proc-command} and +@code{org-export-docbook-xsl-fo-proc-command}. + +@vindex org-export-docbook-xslt-stylesheet +The stylesheet argument @code{%s} in variable +@code{org-export-docbook-xslt-proc-command} is replaced by the value of +variable @code{org-export-docbook-xslt-stylesheet}, which needs to be set by +the user. You can also overrule this global setting on a per-file basis by +adding an in-buffer setting @code{#+XSLT:} to the Org file. + +@orgkey{C-c C-e v D} +Export only the visible part of the document. +@end table + +@node Quoting DocBook code, Recursive sections, DocBook export commands, DocBook export +@subsection Quoting DocBook code + +You can quote DocBook code in Org files and copy it verbatim into exported +DocBook file with the following constructs: + +@cindex #+DOCBOOK +@cindex #+BEGIN_DOCBOOK +@example +#+DOCBOOK: Literal DocBook code for export +@end example + +@noindent or +@cindex #+BEGIN_DOCBOOK + +@example +#+BEGIN_DOCBOOK +All lines between these markers are exported by DocBook exporter +literally. +#+END_DOCBOOK +@end example + +For example, you can use the following lines to include a DocBook warning +admonition. As to what this warning says, you should pay attention to the +document context when quoting DocBook code in Org files. You may make +exported DocBook XML files invalid by not quoting DocBook code correctly. + +@example +#+BEGIN_DOCBOOK +<warning> + <para>You should know what you are doing when quoting DocBook XML code + in your Org file. Invalid DocBook XML may be generated by + DocBook exporter if you are not careful!</para> +</warning> +#+END_DOCBOOK +@end example + +@node Recursive sections, Tables in DocBook export, Quoting DocBook code, DocBook export +@subsection Recursive sections +@cindex DocBook recursive sections + +DocBook exporter exports Org files as articles using the @code{article} +element in DocBook. Recursive sections, i.e. @code{section} elements, are +used in exported articles. Top level headlines in Org files are exported as +top level sections, and lower level headlines are exported as nested +sections. The entire structure of Org files will be exported completely, no +matter how many nested levels of headlines there are. + +Using recursive sections makes it easy to port and reuse exported DocBook +code in other DocBook document types like @code{book} or @code{set}. + +@node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export +@subsection Tables in DocBook export +@cindex tables, in DocBook export + +Tables in Org files are exported as HTML tables, which have been supported since +DocBook V4.3. + +If a table does not have a caption, an informal table is generated using the +@code{informaltable} element; otherwise, a formal table will be generated +using the @code{table} element. + +@node Images in DocBook export, Special characters, Tables in DocBook export, DocBook export +@subsection Images in DocBook export +@cindex images, inline in DocBook +@cindex inlining images in DocBook + +Images that are linked to without a description part in the link, like +@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, will be exported to DocBook +using @code{mediaobject} elements. Each @code{mediaobject} element contains +an @code{imageobject} that wraps an @code{imagedata} element. If you have +specified a caption for an image as described in @ref{Images and tables}, a +@code{caption} element will be added in @code{mediaobject}. If a label is +also specified, it will be exported as an @code{xml:id} attribute of the +@code{mediaobject} element. + +@vindex org-export-docbook-default-image-attributes +Image attributes supported by the @code{imagedata} element, like @code{align} +or @code{width}, can be specified in two ways: you can either customize +variable @code{org-export-docbook-default-image-attributes} or use the +@code{#+ATTR_DOCBOOK:} line. Attributes specified in variable +@code{org-export-docbook-default-image-attributes} are applied to all inline +images in the Org file to be exported (unless they are overridden by image +attributes specified in @code{#+ATTR_DOCBOOK:} lines). + +The @code{#+ATTR_DOCBOOK:} line can be used to specify additional image +attributes or override default image attributes for individual images. If +the same attribute appears in both the @code{#+ATTR_DOCBOOK:} line and +variable @code{org-export-docbook-default-image-attributes}, the former +takes precedence. Here is an example about how image attributes can be +set: + +@cindex #+CAPTION +@cindex #+LABEL +@cindex #+ATTR_DOCBOOK +@example +#+CAPTION: The logo of Org-mode +#+LABEL: unicorn-svg +#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%" +[[./img/org-mode-unicorn.svg]] +@end example + +@vindex org-export-docbook-inline-image-extensions +By default, DocBook exporter recognizes the following image file types: +@file{jpeg}, @file{jpg}, @file{png}, @file{gif}, and @file{svg}. You can +customize variable @code{org-export-docbook-inline-image-extensions} to add +more types to this list as long as DocBook supports them. + +@node Special characters, , Images in DocBook export, DocBook export +@subsection Special characters in DocBook export +@cindex Special characters in DocBook export + +@vindex org-export-docbook-doctype +@vindex org-entities +Special characters that are written in @TeX{}-like syntax, such as @code{\alpha}, +@code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter. These +characters are rewritten to XML entities, like @code{α}, +@code{Γ}, and @code{Ζ}, based on the list saved in variable +@code{org-entities}. As long as the generated DocBook file includes the +corresponding entities, these special characters are recognized. + +You can customize variable @code{org-export-docbook-doctype} to include the +entities you need. For example, you can set variable +@code{org-export-docbook-doctype} to the following value to recognize all +special characters included in XHTML entities: + +@example +"<!DOCTYPE article [ +<!ENTITY % xhtml1-symbol PUBLIC +\"-//W3C//ENTITIES Symbol for HTML//EN//XML\" +\"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\" +> +%xhtml1-symbol; +]> +" +@end example + +@node TaskJuggler export, Freemind export, DocBook export, Exporting +@section TaskJuggler export +@cindex TaskJuggler export +@cindex Project management + +@uref{http://www.taskjuggler.org/, TaskJuggler} is a project management tool. +It provides an optimizing scheduler that computes your project time lines and +resource assignments based on the project outline and the constraints that +you have provided. + +The TaskJuggler exporter is a bit different from other exporters, such as the +HTML and LaTeX exporters for example, in that it does not export all the +nodes of a document or strictly follow the order of the nodes in the +document. + +Instead the TaskJuggler exporter looks for a tree that defines the tasks and +a optionally tree that defines the resources for this project. It then +creates a TaskJuggler file based on these trees and the attributes defined in +all the nodes. + +@subsection TaskJuggler export commands + +@table @kbd +@orgcmd{C-c C-e j,org-export-as-taskjuggler} +Export as TaskJuggler file. + +@orgcmd{C-c C-e J,org-export-as-taskjuggler-and-open} +Export as TaskJuggler file and then open the file with TaskJugglerUI. +@end table + +@subsection Tasks + +@vindex org-export-taskjuggler-project-tag +Create your tasks as you usually do with Org-mode. Assign efforts to each +task using properties (it's easiest to do this in the column view). You +should end up with something similar to the example by Peter Jones in +@url{http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org}. +Now mark the top node of your tasks with a tag named +@code{:taskjuggler_project:} (or whatever you customized +@code{org-export-taskjuggler-project-tag} to). You are now ready to export +the project plan with @kbd{C-c C-e J} which will export the project plan and +open a gantt chart in TaskJugglerUI. + +@subsection Resources + +@vindex org-export-taskjuggler-resource-tag +Next you can define resources and assign those to work on specific tasks. You +can group your resources hierarchically. Tag the top node of the resources +with @code{:taskjuggler_resource:} (or whatever you customized +@code{org-export-taskjuggler-resource-tag} to). You can optionally assign an +identifier (named @samp{resource_id}) to the resources (using the standard +Org properties commands, @pxref{Property syntax}) or you can let the exporter +generate identifiers automatically (the exporter picks the first word of the +headline as the identifier as long as it is unique---see the documentation of +@code{org-taskjuggler-get-unique-id}). Using that identifier you can then +allocate resources to tasks. This is again done with the @samp{allocate} +property on the tasks. Do this in column view or when on the task type +@kbd{C-c C-x p allocate @key{RET} <resource_id> @key{RET}}. + +Once the allocations are done you can again export to TaskJuggler and check +in the Resource Allocation Graph which person is working on what task at what +time. + +@subsection Export of properties + +The exporter also takes TODO state information into consideration, i.e. if a +task is marked as done it will have the corresponding attribute in +TaskJuggler (@samp{complete 100}). Also it will export any property on a task +resource or resource node which is known to TaskJuggler, such as +@samp{limits}, @samp{vacation}, @samp{shift}, @samp{booking}, +@samp{efficiency}, @samp{journalentry}, @samp{rate} for resources or +@samp{account}, @samp{start}, @samp{note}, @samp{duration}, @samp{end}, +@samp{journalentry}, @samp{milestone}, @samp{reference}, @samp{responsible}, +@samp{scheduling}, etc for tasks. + +@subsection Dependencies + +The exporter will handle dependencies that are defined in the tasks either +with the @samp{ORDERED} attribute (@pxref{TODO dependencies}), with the +@samp{BLOCKER} attribute (see @file{org-depend.el}) or alternatively with a +@samp{depends} attribute. Both the @samp{BLOCKER} and the @samp{depends} +attribute can be either @samp{previous-sibling} or a reference to an +identifier (named @samp{task_id}) which is defined for another task in the +project. @samp{BLOCKER} and the @samp{depends} attribute can define multiple +dependencies separated by either space or comma. You can also specify +optional attributes on the dependency by simply appending it. The following +examples should illustrate this: + +@example +* Preparation + :PROPERTIES: + :task_id: preparation + :ORDERED: t + :END: +* Training material + :PROPERTIES: + :task_id: training_material + :ORDERED: t + :END: +** Markup Guidelines + :PROPERTIES: + :Effort: 2.0 + :END: +** Workflow Guidelines + :PROPERTIES: + :Effort: 2.0 + :END: +* Presentation + :PROPERTIES: + :Effort: 2.0 + :BLOCKER: training_material @{ gapduration 1d @} preparation + :END: +@end example + +@subsection Reports + +@vindex org-export-taskjuggler-default-reports +TaskJuggler can produce many kinds of reports (e.g. gantt chart, resource +allocation, etc). The user defines what kind of reports should be generated +for a project in the TaskJuggler file. The exporter will automatically insert +some default reports in the file. These defaults are defined in +@code{org-export-taskjuggler-default-reports}. They can be modified using +customize along with a number of other options. For a more complete list, see +@kbd{M-x customize-group @key{RET} org-export-taskjuggler @key{RET}}. + +For more information and examples see the Org-taskjuggler tutorial at +@uref{http://orgmode.org/worg/org-tutorials/org-taskjuggler.php}. + +@node Freemind export, XOXO export, TaskJuggler export, Exporting +@section Freemind export +@cindex Freemind export +@cindex mind map + +The Freemind exporter was written by Lennart Borgman. + +@table @kbd +@orgcmd{C-c C-e m,org-export-as-freemind} +Export as Freemind mind map @file{myfile.mm}. +@end table + +@node XOXO export, iCalendar export, Freemind 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 +@orgcmd{C-c C-e x,org-export-as-xoxo} +Export as XOXO file @file{myfile.html}. +@orgkey{C-c C-e v x} +Export only the visible part of the document. +@end table + +@node iCalendar export, , XOXO export, Exporting +@section iCalendar export +@cindex iCalendar export + +@vindex org-icalendar-include-todo +@vindex org-icalendar-use-deadline +@vindex org-icalendar-use-scheduled +@vindex org-icalendar-categories +@vindex org-icalendar-alarm-time +Some people 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 show deadlines and other time-stamped items in Org +files 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}. Plain timestamps are exported as VEVENT, +and TODO items as VTODO. It will also create events from deadlines that are +in non-TODO items. Deadlines and scheduling dates in TODO items will be used +to set the start and due dates for the TODO entry@footnote{See the variables +@code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}. +As categories, it will use the tags locally defined in the heading, and the +file/tree category@footnote{To add inherited tags or the TODO state, +configure the variable @code{org-icalendar-categories}.}. See the variable +@code{org-icalendar-alarm-time} for a way to assign alarms to entries with a +time. + +@vindex org-icalendar-store-UID +@cindex property, ID +The iCalendar standard requires each entry to have a globally unique +identifier (UID). Org creates these identifiers during export. If you set +the variable @code{org-icalendar-store-UID}, the UID will be stored in the +@code{:ID:} property of the entry and re-used next time you report this +entry. Since a single entry can give rise to multiple iCalendar entries (as +a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds +prefixes to the UID, depending on what triggered the inclusion of the entry. +In this way the UID remains unique, but a synchronization program can still +figure out from which entry all the different instances originate. + +@table @kbd +@orgcmd{C-c C-e i,org-export-icalendar-this-file} +Create iCalendar entries for the current file and store them in the same +directory, using a file extension @file{.ics}. +@orgcmd{C-c C-e I, org-export-icalendar-all-agenda-files} +@vindex org-agenda-files +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. +@orgcmd{C-c C-e c,org-export-icalendar-combine-agenda-files} +@vindex org-combined-agenda-icalendar-file +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 + +@vindex org-use-property-inheritance +@vindex org-icalendar-include-body +@cindex property, SUMMARY +@cindex property, DESCRIPTION +@cindex property, LOCATION +The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION +property can be inherited from higher in the hierarchy if you configure +@code{org-use-property-inheritance} accordingly.} properties if the selected +entries have them. If not, the summary will be derived from the headline, +and the description from the body (limited to +@code{org-icalendar-include-body} characters). + +How this calendar is best read and updated, depends on the application +you are using. The FAQ covers this issue. + +@node Publishing, Working With Source Code, Exporting, Top +@chapter Publishing +@cindex publishing + +Org includes a publishing management system that allows you to configure +automatic HTML conversion of @emph{projects} composed of interlinked org +files. You can also configure Org to automatically upload your exported HTML +pages and related attachments, such as images and source code files, to a web +server. + +You can also use Org to convert files into PDF, or even combine HTML and PDF +conversion so that files are available in both formats on the server. + +Publishing has been contributed to Org by David O'Toole. + +@menu +* Configuration:: Defining projects +* Uploading files:: How to get files up on the server +* Sample configuration:: Example projects +* Triggering publication:: Publication commands +@end menu + +@node Configuration, Uploading files, 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? +* Sitemap:: Generating a list of all pages +* Generating an index:: An index that reaches across pages +@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 + +@vindex org-publish-project-alist +Publishing 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{i.e. a well-formed property list with alternating keys and values} +@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 +@code{:components} property are taken to be sub-projects, which group +together files requiring different publishing options. When you publish such +a ``meta-project'', all the components will also be published, in the +sequence given. + +@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 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 where output files will be published. You can directly +publish to a webserver using a file name syntax appropriate for +the Emacs @file{tramp} package. Or you can publish to a local directory and +use external tools to upload your website (@pxref{Uploading files}). +@item @code{:preparation-function} +@tab Function or list of functions to be called before starting the +publishing process, for example, to run @code{make} for updating files to be +published. The project property list is scoped into this call as the +variable @code{project-plist}. +@item @code{:completion-function} +@tab Function or list of functions called after finishing the publishing +process, for example, to change permissions of the resulting files. The +project property list is scoped into this call as the variable +@code{project-plist}. +@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. Set this to the symbol @code{any} if you want to get all +files in @code{:base-directory}, even without extension. + +@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}. + +@item @code{:recursive} +@tab Non-nil means, check base-directory recursively for files to publish. +@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 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 content as PDF files using +@code{org-publish-org-to-pdf}, or as @code{ascii}, @code{latin1} or +@code{utf8} encoded files using the corresponding functions. If you want to +publish the Org file itself, but with @i{archived}, @i{commented}, and +@i{tag-excluded} trees removed, use @code{org-publish-org-to-org} and set the +parameters @code{:plain-source} and/or @code{:htmlized-source}. This will +produce @file{file.org} and @file{file.org.html} in the publishing +directory@footnote{@file{file-source.org} and @file{file-source.org.html} if +source and publishing directories are equal. Note that with this kind of +setup, you need to add @code{:exclude "-source\\.org"} to the project +definition in @code{org-publish-project-alist} to prevent the published +source files from being considered as new org files the next time the project +is published.}. Other files like images only need to be copied to the +publishing destination; for this you may use @code{org-publish-attachment}. +For non-Org files, you always 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. +@item @code{:plain-source} +@tab Non-nil means, publish plain source. +@item @code{:htmlized-source} +@tab Non-nil means, publish htmlized source. +@end multitable + +The function must accept three arguments: a property list containing at least +a @code{:publishing-directory} property, the name of the file to be +published, and the path to the publishing directory of the output file. It +should take the specified file, make the necessary transformation (if any) +and place the result into the destination folder. + +@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 @LaTeX{} exporters. In most cases, these properties correspond to user +variables in Org. The table below lists these properties along +with the variable they belong to. See the documentation string for the +respective variable for details. + +@vindex org-export-html-link-up +@vindex org-export-html-link-home +@vindex org-export-default-language +@vindex org-display-custom-times +@vindex org-export-headline-levels +@vindex org-export-with-section-numbers +@vindex org-export-section-number-format +@vindex org-export-with-toc +@vindex org-export-preserve-breaks +@vindex org-export-with-archived-trees +@vindex org-export-with-emphasize +@vindex org-export-with-sub-superscripts +@vindex org-export-with-special-strings +@vindex org-export-with-footnotes +@vindex org-export-with-drawers +@vindex org-export-with-tags +@vindex org-export-with-todo-keywords +@vindex org-export-with-priority +@vindex org-export-with-TeX-macros +@vindex org-export-with-LaTeX-fragments +@vindex org-export-skip-text-before-1st-heading +@vindex org-export-with-fixed-width +@vindex org-export-with-timestamps +@vindex org-export-author-info +@vindex org-export-email +@vindex org-export-creator-info +@vindex org-export-with-tables +@vindex org-export-highlight-first-table-line +@vindex org-export-html-style-include-default +@vindex org-export-html-style +@vindex org-export-html-style-extra +@vindex org-export-html-link-org-files-as-html +@vindex org-export-html-inline-images +@vindex org-export-html-extension +@vindex org-export-html-table-tag +@vindex org-export-html-expand +@vindex org-export-html-with-timestamp +@vindex org-export-publishing-directory +@vindex org-export-html-preamble +@vindex org-export-html-postamble +@vindex org-export-html-auto-preamble +@vindex org-export-html-auto-postamble +@vindex user-full-name +@vindex user-mail-address +@vindex org-export-select-tags +@vindex org-export-exclude-tags + +@multitable @columnfractions 0.32 0.68 +@item @code{:link-up} @tab @code{org-export-html-link-up} +@item @code{:link-home} @tab @code{org-export-html-link-home} +@item @code{:language} @tab @code{org-export-default-language} +@item @code{:customtime} @tab @code{org-display-custom-times} +@item @code{:headline-levels} @tab @code{org-export-headline-levels} +@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} +@item @code{:section-number-format} @tab @code{org-export-section-number-format} +@item @code{:table-of-contents} @tab @code{org-export-with-toc} +@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks} +@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{:special-strings} @tab @code{org-export-with-special-strings} +@item @code{:footnotes} @tab @code{org-export-with-footnotes} +@item @code{:drawers} @tab @code{org-export-with-drawers} +@item @code{:tags} @tab @code{org-export-with-tags} +@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords} +@item @code{:priority} @tab @code{org-export-with-priority} +@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} +@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} +@item @code{:latex-listings} @tab @code{org-export-latex-listings} +@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading} +@item @code{:fixed-width} @tab @code{org-export-with-fixed-width} +@item @code{:timestamps} @tab @code{org-export-with-timestamps} +@item @code{:author-info} @tab @code{org-export-author-info} +@item @code{:email-info} @tab @code{org-export-email-info} +@item @code{:creator-info} @tab @code{org-export-creator-info} +@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-include-default} @tab @code{org-export-html-style-include-default} +@item @code{:style} @tab @code{org-export-html-style} +@item @code{:style-extra} @tab @code{org-export-html-style-extra} +@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{:html-extension} @tab @code{org-export-html-extension} +@item @code{:xml-declaration} @tab @code{org-export-html-xml-declaration} +@item @code{:html-table-tag} @tab @code{org-export-html-table-tag} +@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} : @code{addr;addr;..} +@item @code{:select-tags} @tab @code{org-export-select-tags} +@item @code{:exclude-tags} @tab @code{org-export-exclude-tags} +@item @code{:latex-image-options} @tab @code{org-export-latex-image-default-option} +@end multitable + +Most of the @code{org-export-with-*} variables have the same effect in +both HTML and @LaTeX{} exporters, except for @code{:TeX-macros} and +@code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the +@LaTeX{} export. + +@vindex org-publish-project-alist +When a property is given a value in @code{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, Sitemap, Publishing options, Configuration +@subsection Links between published files +@cindex links, publishing + +To create a link from one Org file to another, you would use +something like @samp{[[file:foo.org][The foo]]} or simply +@samp{file:foo.org.} (@pxref{Hyperlinks}). When published, 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. If you also publish the Org source file and want +to link to that, use an @code{http:} link instead of a @code{file:} link, +because @code{file:} links are converted to link to the corresponding +@file{html} file. + +You may also link to related files, such as images. Provided you are careful +with relative file names, and provided you have also configured Org to upload +the related files, these links will work too. See @ref{Complex example}, for +an example of this usage. + +Sometimes an Org 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 Sitemap, Generating an index, Publishing links, Configuration +@subsection Generating a sitemap +@cindex sitemap, of published pages + +The following properties may be used to control publishing of +a map of files for a given project. + +@multitable @columnfractions 0.35 0.65 +@item @code{:auto-sitemap} +@tab When non-nil, publish a sitemap during @code{org-publish-current-project} +or @code{org-publish-all}. + +@item @code{:sitemap-filename} +@tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which +becomes @file{sitemap.html}). + +@item @code{:sitemap-title} +@tab Title of sitemap page. Defaults to name of file. + +@item @code{:sitemap-function} +@tab Plug-in function to use for generation of the sitemap. +Defaults to @code{org-publish-org-sitemap}, which generates a plain list +of links to all files in the project. + +@item @code{:sitemap-sort-folders} +@tab Where folders should appear in the sitemap. Set this to @code{first} +(default) or @code{last} to display folders first or last, +respectively. Any other value will mix files and folders. + +@item @code{:sitemap-alphabetically} +@tab The site map is normally sorted alphabetically. Set this explicitly to +@code{nil} to turn off sorting. + +@item @code{:sitemap-ignore-case} +@tab Should sorting be case-sensitive? Default @code{nil}. + +@end multitable + +@node Generating an index, , Sitemap, Configuration +@subsection Generating an index +@cindex index, in a publishing project + +Org-mode can generate an index across the files of a publishing project. + +@multitable @columnfractions 0.25 0.75 +@item @code{:makeindex} +@tab When non-nil, generate in index in the file @file{theindex.org} and +publish it as @file{theindex.html}. +@end multitable + +The file will be create when first publishing a project with the +@code{:makeindex} set. The file only contains a statement @code{#+include: +"theindex.inc"}. You can then built around this include statement by adding +a title, style information etc. + +@node Uploading files, Sample configuration, Configuration, Publishing +@section Uploading files +@cindex rsync +@cindex unison + +For those people already utilizing third party sync tools such as +@command{rsync} or @command{unison}, it might be preferable not to use the built in +@i{remote} publishing facilities of Org-mode which rely heavily on +Tramp. Tramp, while very useful and powerful, tends not to be +so efficient for multiple file transfer and has been known to cause problems +under heavy usage. + +Specialized synchronization utilities offer several advantages. In addition +to timestamp comparison, they also do content and permissions/attribute +checks. For this reason you might prefer to publish your web to a local +directory (possibly even @i{in place} with your Org files) and then use +@file{unison} or @file{rsync} to do the synchronization with the remote host. + +Since Unison (for example) can be configured as to which files to transfer to +a certain remote destination, it can greatly simplify the project publishing +definition. Simply keep all files in the correct location, process your Org +files with @code{org-publish} and let the synchronization tool do the rest. +You do not need, in this scenario, to include attachments such as @file{jpg}, +@file{css} or @file{gif} files in the project definition since the 3rd party +tool syncs them. + +Publishing to a local directory is also much faster than to a remote one, so +that you can afford more easily to republish entire projects. If you set +@code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main +benefit of re-including any changed external files such as source example +files you might include with @code{#+INCLUDE}. The timestamp mechanism in +Org is not smart enough to detect if included files have been modified. + +@node Sample configuration, Triggering publication, Uploading files, Publishing +@section Sample configuration + +Below we provide two example configurations. The first one is a simple +project publishing only a set of Org 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 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 +style sheets. 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 would 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 web server, 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 properly configured, Org can publish with the following commands: + +@table @kbd +@orgcmd{C-c C-e X,org-publish} +Prompt for a specific project and publish all files that belong to it. +@orgcmd{C-c C-e P,org-publish-current-project} +Publish the project containing the current file. +@orgcmd{C-c C-e F,org-publish-current-file} +Publish only the current file. +@orgcmd{C-c C-e E,org-publish-all} +Publish every project. +@end table + +@vindex org-publish-use-timestamps-flag +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 to any of the commands +above, or by customizing the variable @code{org-publish-use-timestamps-flag}. +This may be necessary in particular if files include other files via +@code{#+SETUPFILE:} or @code{#+INCLUDE:}. + +@comment node-name, next, previous, up +@comment Working With Source Code, Miscellaneous, Publishing, Top + +@node Working With Source Code, Miscellaneous, Publishing, Top +@chapter Working with source code +@cindex Schulte, Eric +@cindex Davison, Dan +@cindex source code, working with + +Source code can be included in Org-mode documents using a @samp{src} block, +e.g. + +@example +#+BEGIN_SRC emacs-lisp + (defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_SRC +@end example + +Org-mode provides a number of features for working with live source code, +including editing of code blocks in their native major-mode, evaluation of +code blocks, tangling of code blocks, and exporting code blocks and their +results in several formats. This functionality was contributed by Eric +Schulte and Dan Davison, and was originally named Org-babel. + +The following sections describe Org-mode's code block handling facilities. + +@menu +* Structure of code blocks:: Code block syntax described +* Editing source code:: Language major-mode editing +* Exporting code blocks:: Export contents and/or results +* Extracting source code:: Create pure source code files +* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Library of Babel:: Use and contribute to a library of useful code blocks +* Languages:: List of supported code block languages +* Header arguments:: Configure code block functionality +* Results of evaluation:: How evaluation results are handled +* Noweb reference syntax:: Literate programming in Org-mode +* Key bindings and useful functions:: Work quickly with code blocks +* Batch execution:: Call functions from the command line +@end menu + +@comment node-name, next, previous, up +@comment Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code + +@node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code +@section Structure of code blocks +@cindex code block, structure +@cindex source code, block structure + +The structure of code blocks is as follows: + +@example +#+srcname: <name> +#+begin_src <language> <switches> <header arguments> + <body> +#+end_src +@end example + +code blocks can also be embedded in text as so called inline code blocks as + +@example +src_<language>@{<body>@} +@end example + +or + +@example +src_<language>[<header arguments>]@{<body>@} +@end example + +@table @code +@item <name> +This name is associated with the code block. This is similar to the +@samp{#+tblname} lines that can be used to name tables in Org-mode files. +Referencing the name of a code block makes it possible to evaluate the +block from other places in the file, other files, or from Org-mode table +formulas (see @ref{The spreadsheet}). +@item <language> +The language of the code in the block. +@item <switches> +Switches controlling exportation of the code block (see switches discussion in +@ref{Literal examples}) +@item <header arguments> +Optional header arguments control many aspects of evaluation, export and +tangling of code blocks. See the @ref{Header arguments} +section. Header arguments can also be set on a per-buffer or per-subtree +basis using properties. +@item <body> +The source code. +@end table + +@comment node-name, next, previous, up +@comment Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code + +@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code +@section Editing source code +@cindex code block, editing +@cindex source code, editing + +@kindex C-c ' +Use @kbd{C-c '} to edit the current code block. This brings up +a language major-mode edit buffer containing the body of the code +block. Saving this buffer will write the new contents back to the Org +buffer. Use @kbd{C-c '} again to exit. + +The @code{org-src-mode} minor mode will be active in the edit buffer. The +following variables can be used to configure the behavior of the edit +buffer. See also the customization group @code{org-edit-structure} for +further configuration options. + +@table @code +@item org-src-lang-modes +If an Emacs major-mode named @code{<lang>-mode} exists, where +@code{<lang>} is the language named in the header line of the code block, +then the edit buffer will be placed in that major-mode. This variable +can be used to map arbitrary language names to existing major modes. +@item org-src-window-setup +Controls the way Emacs windows are rearranged when the edit buffer is created. +@item org-src-preserve-indentation +This variable is especially useful for tangling languages such as +Python, in which whitespace indentation in the output is critical. +@item org-src-ask-before-returning-to-edit-buffer +By default, Org will ask before returning to an open edit buffer. Set +this variable to nil to switch without asking. +@end table + +@comment node-name, next, previous, up +@comment Exporting code blocks, Extracting source code, Editing source code, Working With Source Code + +@node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code +@section Exporting code blocks +@cindex code block, exporting +@cindex source code, exporting + +It is possible to export the @emph{contents} of code blocks, the +@emph{results} of code block evaluation, @emph{neither}, or @emph{both}. For +most languages, the default exports the contents of code blocks. However, for +some languages (e.g. @code{ditaa}) the default exports the results of code +block evaluation. For information on exporting code block bodies, see +@ref{Literal examples}. + +The @code{:exports} header argument can be used to specify export +behavior: + +@subsubheading Header arguments: +@table @code +@item :exports code +The default in most languages. The body of the code block is exported, as +described in @ref{Literal examples}. +@item :exports results +The code block will be evaluated and the results will be placed in the +Org-mode buffer for export, either updating previous results of the code +block located anywhere in the buffer or, if no previous results exist, +placing the results immediately after the code block. The body of the code +block will not be exported. +@item :exports both +Both the code block and its results will be exported. +@item :exports none +Neither the code block nor its results will be exported. +@end table + +It is possible to inhibit the evaluation of code blocks during export. +Setting the @code{org-export-babel-evaluate} variable to @code{nil} will +ensure that no code blocks are evaluated as part of the export process. This +can be useful in situations where potentially untrusted Org-mode files are +exported in an automated fashion, for example when Org-mode is used as the +markup language for a wiki. + +@comment node-name, next, previous, up +@comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code +@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code +@section Extracting source code +@cindex source code, extracting +@cindex code block, extracting source code + +Creating pure source code files by extracting code from source blocks is +referred to as ``tangling''---a term adopted from the literate programming +community. During ``tangling'' of code blocks their bodies are expanded +using @code{org-babel-expand-src-block} which can expand both variable and +``noweb'' style references (see @ref{Noweb reference syntax}). + +@subsubheading Header arguments +@table @code +@item :tangle no +The default. The code block is not included in the tangled output. +@item :tangle yes +Include the code block in the tangled output. The output file name is the +name of the org file with the extension @samp{.org} replaced by the extension +for the block language. +@item :tangle filename +Include the code block in the tangled output to file @samp{filename}. +@end table + +@kindex C-c C-v t +@subsubheading Functions +@table @code +@item org-babel-tangle +Tangle the current file. Bound to @kbd{C-c C-v t}. +@item org-babel-tangle-file +Choose a file to tangle. Bound to @kbd{C-c C-v f}. +@end table + +@subsubheading Hooks +@table @code +@item org-babel-post-tangle-hook +This hook is run from within code files tangled by @code{org-babel-tangle}. +Example applications could include post-processing, compilation or evaluation +of tangled code files. +@end table + +@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code +@section Evaluating code blocks +@cindex code block, evaluating +@cindex source code, evaluating + +Code blocks can be evaluated@footnote{Whenever code is evaluated there is a +potential for that code to do harm. Org-mode provides a number of safeguards +to ensure that it only evaluates code with explicit confirmation from the +user. For information on these safeguards (and on how to disable them) see +@ref{Code evaluation security}.} and the results placed in the Org-mode +buffer. By default, evaluation is only turned on for @code{emacs-lisp} code +blocks, however support exists for evaluating blocks in many languages. See +@ref{Languages} for a list of supported languages. See @ref{Structure of +code blocks} for information on the syntax used to define a code block. + +@kindex C-c C-c +There are a number of ways to evaluate code blocks. The simplest is to press +@kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The +@code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code +evaluation from the @kbd{C-c C-c} key binding.}. This will call the +@code{org-babel-execute-src-block} function to evaluate the block and insert +its results into the Org-mode buffer. + +It is also possible to evaluate named code blocks from anywhere in an +Org-mode buffer or an Org-mode table. @code{#+call} (or synonymously +@code{#+function} or @code{#+lob}) lines can be used to remotely execute code +blocks located in the current Org-mode buffer or in the ``Library of Babel'' +(see @ref{Library of Babel}). These lines use the following syntax. + +@example +#+call: <name>(<arguments>) <header arguments> +#+function: <name>(<arguments>) <header arguments> +#+lob: <name>(<arguments>) <header arguments> +@end example + +@table @code +@item <name> +The name of the code block to be evaluated. +@item <arguments> +Arguments specified in this section will be passed to the code block. +@item <header arguments> +Header arguments can be placed after the function invocation. See +@ref{Header arguments} for more information on header arguments. +@end table + + +@node Library of Babel, Languages, Evaluating code blocks, Working With Source Code +@section Library of Babel +@cindex babel, library of +@cindex source code, library +@cindex code block, library + +The ``Library of Babel'' is a library of code blocks +that can be called from any Org-mode file. The library is housed in an +Org-mode file located in the @samp{contrib} directory of Org-mode. +Org-mode users can deposit functions they believe to be generally +useful in the library. + +Code blocks defined in the ``Library of Babel'' can be called remotely as if +they were in the current Org-mode buffer (see @ref{Evaluating code blocks} +for information on the syntax of remote code block evaluation). + +@kindex C-c C-v i +Code blocks located in any Org-mode file can be loaded into the ``Library of +Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v +i}. + +@node Languages, Header arguments, Library of Babel, Working With Source Code +@section Languages +@cindex babel, languages +@cindex source code, languages +@cindex code block, languages + +Code blocks in the following languages are supported. + +@multitable @columnfractions 0.28 0.3 0.22 0.2 +@item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier} +@item Asymptote @tab asymptote @tab C @tab C +@item C++ @tab C++ @tab Clojure @tab clojure +@item CSS @tab css @tab ditaa @tab ditaa +@item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp +@item gnuplot @tab gnuplot @tab Haskell @tab haskell +@item LaTeX @tab latex @tab MATLAB @tab matlab +@item Mscgen @tab mscgen @tab Objective Caml @tab ocaml +@item Octave @tab octave @tab Oz @tab oz +@item Perl @tab perl @tab Python @tab python +@item R @tab R @tab Ruby @tab ruby +@item Sass @tab sass @tab GNU Screen @tab screen +@item shell @tab sh @tab SQL @tab sql +@item SQLite @tab sqlite +@end multitable + +Language-specific documentation is available for some languages. If +available, it can be found at +@uref{http://orgmode.org/worg/org-contrib/babel/languages}. + +The @code{org-babel-load-languages} controls which languages are enabled for +evaluation (by default only @code{emacs-lisp} is enabled). This variable can +be set using the customization interface or by adding code like the following +to your emacs configuration. + +@quotation +The following disables @code{emacs-lisp} evaluation and enables evaluation of +@code{R} code blocks. +@end quotation + +@lisp +(org-babel-do-load-languages + 'org-babel-load-languages + '((emacs-lisp . nil) + (R . t))) +@end lisp + +It is also possible to enable support for a language by loading the related +elisp file with @code{require}. + +@quotation +The following adds support for evaluating @code{clojure} code blocks. +@end quotation + +@lisp +(require 'ob-clojure) +@end lisp + +@node Header arguments, Results of evaluation, Languages, Working With Source Code +@section Header arguments +@cindex code block, header arguments +@cindex source code, block header arguments + +Code block functionality can be configured with header arguments. This +section provides an overview of the use of header arguments, and then +describes each header argument in detail. + +@menu +* Using header arguments:: Different ways to set header arguments +* Specific header arguments:: List of header arguments +@end menu + +@node Using header arguments, Specific header arguments, Header arguments, Header arguments +@subsection Using header arguments + +The values of header arguments can be set in six different ways, each more +specific (and having higher priority) than the last. +@menu +* System-wide header arguments:: Set global default values +* Language-specific header arguments:: Set default values by language +* Buffer-wide header arguments:: Set default values for a specific buffer +* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Code block specific header arguments:: The most common way to set values +* Header arguments in function calls:: The most specific level +@end menu + + +@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments +@subsubheading System-wide header arguments +@vindex org-babel-default-header-args +System-wide values of header arguments can be specified by customizing the +@code{org-babel-default-header-args} variable: + +@example +:session => "none" +:results => "replace" +:exports => "code" +:cache => "no" +:noweb => "no" +@end example + +@c @example +@c org-babel-default-header-args is a variable defined in `org-babel.el'. +@c Its value is +@c ((:session . "none") +@c (:results . "replace") +@c (:exports . "code") +@c (:cache . "no") +@c (:noweb . "no")) + + +@c Documentation: +@c Default arguments to use when evaluating a code block. +@c @end example + +For example, the following example could be used to set the default value of +@code{:noweb} header arguments to @code{yes}. This would have the effect of +expanding @code{:noweb} references by default when evaluating source code +blocks. + +@lisp +(setq org-babel-default-header-args +(cons '(:noweb . "yes") +(assq-delete-all :noweb org-babel-default-header-args))) +@end lisp + +@node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments +@subsubheading Language-specific header arguments +Each language can define its own set of default header arguments. See the +language-specific documentation available online at +@uref{http://orgmode.org/worg/org-contrib/babel}. + +@node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments +@subsubheading Buffer-wide header arguments +Buffer-wide header arguments may be specified through the use of a special +line placed anywhere in an Org-mode file. The line consists of the +@code{#+BABEL:} keyword followed by a series of header arguments which may be +specified using the standard header argument syntax. + +For example the following would set @code{session} to @code{*R*}, and +@code{results} to @code{silent} for every code block in the buffer, ensuring +that all execution took place in the same session, and no results would be +inserted into the buffer. + +@example +#+BABEL: :session *R* :results silent +@end example + +@node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments +@subsubheading Header arguments in Org-mode properties + +Header arguments are also read from Org-mode properties (see @ref{Property +syntax}), which can be set on a buffer-wide or per-heading basis. An example +of setting a header argument for all code blocks in a buffer is + +@example +#+property: tangle yes +@end example + +When properties are used to set default header arguments, they are looked up +with inheritance, so the value of the @code{:cache} header argument will default +to @code{yes} in all code blocks in the subtree rooted at the following +heading: + +@example +* outline header +:PROPERTIES: +:cache: yes +:END: +@end example + +@kindex C-c C-x p +@vindex org-babel-default-header-args +Properties defined in this way override the properties set in +@code{org-babel-default-header-args}. It is convenient to use the +@code{org-set-property} function bound to @kbd{C-c C-x p} to set properties +in Org-mode documents. + +@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org-mode properties, Using header arguments +@subsubheading Code block specific header arguments + +The most common way to assign values to header arguments is at the +code block level. This can be done by listing a sequence of header +arguments and their values as part of the @code{#+begin_src} line. +Properties set in this way override both the values of +@code{org-babel-default-header-args} and header arguments specified as +properties. In the following example, the @code{:results} header argument +is set to @code{silent}, meaning the results of execution will not be +inserted in the buffer, and the @code{:exports} header argument is set to +@code{code}, meaning only the body of the code block will be +preserved on export to HTML or LaTeX. + +@example +#+source: factorial +#+begin_src haskell :results silent :exports code :var n=0 +fac 0 = 1 +fac n = n * fac (n-1) +#+end_src +@end example +Similarly, it is possible to set header arguments for inline code blocks: + +@example +src_haskell[:exports both]@{fac 5@} +@end example + +@node Header arguments in function calls, , Code block specific header arguments, Using header arguments +@comment node-name, next, previous, up +@subsubheading Header arguments in function calls + +At the most specific level, header arguments for ``Library of Babel'' or +function call lines can be set as shown below: + +@example +#+call: factorial(n=5) :exports results +@end example + +@node Specific header arguments, , Using header arguments, Header arguments +@subsection Specific header arguments +The following header arguments are defined: + +@menu +* var:: Pass arguments to code blocks +* results:: Specify the type of results and how they will + be collected and handled +* file:: Specify a path for file output +* dir:: Specify the default (possibly remote) + directory for code block execution +* exports:: Export code and/or results +* tangle:: Toggle tangling and specify file name +* comments:: Toggle insertion of comments in tangled + code files +* no-expand:: Turn off variable assignment and noweb + expansion during tangling +* session:: Preserve the state of code evaluation +* noweb:: Toggle expansion of noweb references +* cache:: Avoid re-evaluating unchanged code blocks +* hlines:: Handle horizontal lines in tables +* colnames:: Handle column names in tables +* rownames:: Handle row names in tables +* shebang:: Make tangled files executable +* eval:: Limit evaluation of specific code blocks +@end menu + +@node var, results, Specific header arguments, Specific header arguments +@subsubsection @code{:var} +The @code{:var} header argument is used to pass arguments to code blocks. +The specifics of how arguments are included in a code block vary by language; +these are addressed in the language-specific documentation. However, the +syntax used to specify arguments is the same across all languages. The +values passed to arguments can be literal values, values from org-mode tables +and literal example blocks, or the results of other code blocks. + +These values can be indexed in a manner similar to arrays---see the +``indexable variable values'' heading below. + +The following syntax is used to pass arguments to code blocks using the +@code{:var} header argument. + +@example +:var name=assign +@end example + +where @code{assign} can take one of the following forms + +@itemize @bullet +@item literal value +either a string @code{"string"} or a number @code{9}. +@item reference +a table name: + +@example +#+tblname: example-table +| 1 | +| 2 | +| 3 | +| 4 | + +#+source: table-length +#+begin_src emacs-lisp :var table=example-table +(length table) +#+end_src + +#+results: table-length +: 4 +@end example + +a code block name, as assigned by @code{#+srcname:}, followed by +parentheses: + +@example +#+begin_src emacs-lisp :var length=table-length() +(* 2 length) +#+end_src + +#+results: +: 8 +@end example + +In addition, an argument can be passed to the code block referenced +by @code{:var}. The argument is passed within the parentheses following the +code block name: + +@example +#+source: double +#+begin_src emacs-lisp :var input=8 +(* 2 input) +#+end_src + +#+results: double +: 16 + +#+source: squared +#+begin_src emacs-lisp :var input=double(input=1) +(* input input) +#+end_src + +#+results: squared +: 4 +@end example +@end itemize + +@subsubheading Alternate argument syntax +It is also possible to specify arguments in a potentially more natural way +using the @code{#+source:} line of a code block. As in the following +example arguments can be packed inside of parenthesis, separated by commas, +following the source name. + +@example +#+source: double(input=0, x=2) +#+begin_src emacs-lisp +(* 2 (+ input x)) +#+end_src +@end example + +@subsubheading Indexable variable values +It is possible to reference portions of variable values by ``indexing'' into +the variables. Indexes are 0 based with negative values counting back from +the end. If an index is separated by @code{,}s then each subsequent section +will index into the next deepest nesting or dimension of the value. The +following example assigns the last cell of the first row the table +@code{example-table} to the variable @code{data}: + +@example +#+results: example-table +| 1 | a | +| 2 | b | +| 3 | c | +| 4 | d | + +#+begin_src emacs-lisp :var data=example-table[0,-1] + data +#+end_src + +#+results: +: a +@end example + +Ranges of variable values can be referenced using two integers separated by a +@code{:}, in which case the entire inclusive range is referenced. For +example the following assigns the middle three rows of @code{example-table} +to @code{data}. + +@example +#+results: example-table +| 1 | a | +| 2 | b | +| 3 | c | +| 4 | d | +| 5 | 3 | + +#+begin_src emacs-lisp :var data=example-table[1:3] + data +#+end_src + +#+results: +| 2 | b | +| 3 | c | +| 4 | d | +@end example + +Additionally, an empty index, or the single character @code{*}, are both +interpreted to mean the entire range and as such are equivalent to +@code{0:-1}, as shown in the following example in which the entire first +column is referenced. + +@example +#+results: example-table +| 1 | a | +| 2 | b | +| 3 | c | +| 4 | d | + +#+begin_src emacs-lisp :var data=example-table[,0] + data +#+end_src + +#+results: +| 1 | 2 | 3 | 4 | +@end example + +It is possible to index into the results of code blocks as well as tables. +Any number of dimensions can be indexed. Dimensions are separated from one +another by commas, as shown in the following example. + +@example +#+source: 3D +#+begin_src emacs-lisp + '(((1 2 3) (4 5 6) (7 8 9)) + ((10 11 12) (13 14 15) (16 17 18)) + ((19 20 21) (22 23 24) (25 26 27))) +#+end_src + +#+begin_src emacs-lisp :var data=3D[1,,1] + data +#+end_src + +#+results: +| 11 | 14 | 17 | +@end example + +@node results, file, var, Specific header arguments +@subsubsection @code{:results} + +There are three classes of @code{:results} header argument. Only one option +per class may be supplied per code block. + +@itemize @bullet +@item +@b{collection} header arguments specify how the results should be collected +from the code block +@item +@b{type} header arguments specify what type of result the code block will +return---which has implications for how they will be inserted into the +Org-mode buffer +@item +@b{handling} header arguments specify how the results of evaluating the code +block should be handled. +@end itemize + +@subsubheading Collection +The following options are mutually exclusive, and specify how the results +should be collected from the code block. + +@itemize @bullet +@item @code{value} +This is the default. The result is the value of the last statement in the +code block. This header argument places the evaluation in functional +mode. Note that in some languages, e.g., Python, use of this result type +requires that a @code{return} statement be included in the body of the source +code block. E.g., @code{:results value}. +@item @code{output} +The result is the collection of everything printed to STDOUT during the +execution of the code block. This header argument places the +evaluation in scripting mode. E.g., @code{:results output}. +@end itemize + +@subsubheading Type + +The following options are mutually exclusive and specify what type of results +the code block will return. By default, results are inserted as either a +table or scalar depending on their value. + +@itemize @bullet +@item @code{table}, @code{vector} +The results should be interpreted as an Org-mode table. If a single value is +returned, it will be converted into a table with one row and one column. +E.g., @code{:results value table}. +@item @code{list} +The results should be interpreted as an Org-mode list. If a single scalar +value is returned it will be converted into a list with only one element. +@item @code{scalar}, @code{verbatim} +The results should be interpreted literally---they will not be +converted into a table. The results will be inserted into the Org-mode +buffer as quoted text. E.g., @code{:results value verbatim}. +@item @code{file} +The results will be interpreted as the path to a file, and will be inserted +into the Org-mode buffer as a file link. E.g., @code{:results value file}. +@item @code{raw}, @code{org} +The results are interpreted as raw Org-mode code and are inserted directly +into the buffer. If the results look like a table they will be aligned as +such by Org-mode. E.g., @code{:results value raw}. +@item @code{html} +Results are assumed to be HTML and will be enclosed in a @code{begin_html} +block. E.g., @code{:results value html}. +@item @code{latex} +Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block. +E.g., @code{:results value latex}. +@item @code{code} +Result are assumed to be parseable code and are enclosed in a code block. +E.g., @code{:results value code}. +@item @code{pp} +The result is converted to pretty-printed code and is enclosed in a code +block. This option currently supports Emacs Lisp, Python, and Ruby. E.g., +@code{:results value pp}. +@end itemize + +@subsubheading Handling +The following results options indicate what happens with the +results once they are collected. + +@itemize @bullet +@item @code{silent} +The results will be echoed in the minibuffer but will not be inserted into +the Org-mode buffer. E.g., @code{:results output silent}. +@item @code{replace} +The default value. Any existing results will be removed, and the new results +will be inserted into the Org-mode buffer in their place. E.g., +@code{:results output replace}. +@item @code{append} +If there are pre-existing results of the code block then the new results will +be appended to the existing results. Otherwise the new results will be +inserted as with @code{replace}. +@item @code{prepend} +If there are pre-existing results of the code block then the new results will +be prepended to the existing results. Otherwise the new results will be +inserted as with @code{replace}. +@end itemize + +@node file, dir, results, Specific header arguments +@subsubsection @code{:file} + +The header argument @code{:file} is used to specify a path for file output. +An Org-mode style @code{file:} link is inserted into the buffer as the result +(see @ref{Link format}). Common examples are graphical output from R, +gnuplot, ditaa and LaTeX code blocks. + +Note that for some languages, including R, gnuplot, LaTeX and ditaa, +graphical output is sent to the specified file without the file being +referenced explicitly in the code block. See the documentation for the +individual languages for details. In contrast, general purpose languages such +as Python and Ruby require that the code explicitly create output +corresponding to the path indicated by @code{:file}. + + +@node dir, exports, file, Specific header arguments +@subsubsection @code{:dir} and remote execution + +While the @code{:file} header argument can be used to specify the path to the +output file, @code{:dir} specifies the default directory during code block +execution. If it is absent, then the directory associated with the current +buffer is used. In other words, supplying @code{:dir path} temporarily has +the same effect as changing the current directory with @kbd{M-x cd path}, and +then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets +the value of the Emacs variable @code{default-directory}. + +When using @code{:dir}, you should supply a relative path for file output +(e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which +case that path will be interpreted relative to the default directory. + +In other words, if you want your plot to go into a folder called @file{Work} +in your home directory, you could use + +@example +#+begin_src R :file myplot.png :dir ~/Work +matplot(matrix(rnorm(100), 10), type="l") +#+end_src +@end example + +@subsubheading Remote execution +A directory on a remote machine can be specified using tramp file syntax, in +which case the code will be evaluated on the remote machine. An example is + +@example +#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: +plot(1:10, main=system("hostname", intern=TRUE)) +#+end_src +@end example + +Text results will be returned to the local Org-mode buffer as usual, and file +output will be created on the remote machine with relative paths interpreted +relative to the remote directory. An Org-mode link to the remote file will be +created. + +So, in the above example a plot will be created on the remote machine, +and a link of the following form will be inserted in the org buffer: + +@example +[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]] +@end example + +Most of this functionality follows immediately from the fact that @code{:dir} +sets the value of the Emacs variable @code{default-directory}, thanks to +tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to +install tramp separately in order for these features to work correctly. + +@subsubheading Further points + +@itemize @bullet +@item +If @code{:dir} is used in conjunction with @code{:session}, although it will +determine the starting directory for a new session as expected, no attempt is +currently made to alter the directory associated with an existing session. +@item +@code{:dir} should typically not be used to create files during export with +@code{:exports results} or @code{:exports both}. The reason is that, in order +to retain portability of exported material between machines, during export +links inserted into the buffer will *not* be expanded against @code{default +directory}. Therefore, if @code{default-directory} is altered using +@code{:dir}, it is probable that the file will be created in a location to +which the link does not point. +@end itemize + +@node exports, tangle, dir, Specific header arguments +@subsubsection @code{:exports} + +The @code{:exports} header argument specifies what should be included in HTML +or LaTeX exports of the Org-mode file. + +@itemize @bullet +@item @code{code} +The default. The body of code is included into the exported file. E.g., +@code{:exports code}. +@item @code{results} +The result of evaluating the code is included in the exported file. E.g., +@code{:exports results}. +@item @code{both} +Both the code and results are included in the exported file. E.g., +@code{:exports both}. +@item @code{none} +Nothing is included in the exported file. E.g., @code{:exports none}. +@end itemize + +@node tangle, comments, exports, Specific header arguments +@subsubsection @code{:tangle} + +The @code{:tangle} header argument specifies whether or not the code +block should be included in tangled extraction of source code files. + +@itemize @bullet +@item @code{tangle} +The code block is exported to a source code file named after the +basename (name w/o extension) of the Org-mode file. E.g., @code{:tangle +yes}. +@item @code{no} +The default. The code block is not exported to a source code file. +E.g., @code{:tangle no}. +@item other +Any other string passed to the @code{:tangle} header argument is interpreted +as a file basename to which the block will be exported. E.g., @code{:tangle +basename}. +@end itemize + +@node comments, no-expand, tangle, Specific header arguments +@subsubsection @code{:comments} +By default code blocks are tangled to source-code files without any insertion +of comments beyond those which may already exist in the body of the code +block. The @code{:comments} header argument can be set as follows to control +the insertion of extra comments into the tangled code file. + +@itemize @bullet +@item @code{no} +The default. No extra comments are inserted during tangling. +@item @code{link} +The code block is wrapped in comments which contain pointers back to the +original Org file from which the code was tangled. +@item @code{yes} +A synonym for ``link'' to maintain backwards compatibility. +@item @code{org} +Include text from the org-mode file as a comment. + +The text is picked from the leading context of the tangled code and is +limited by the nearest headline or source block as the case may be. +@item @code{both} +Turns on both the ``link'' and ``org'' comment options. +@end itemize + +@node no-expand, session, comments, Specific header arguments +@subsubsection @code{:no-expand} + +By default, code blocks are expanded with @code{org-babel-expand-src-block} +during tangling. This has the effect of assigning values to variables +specified with @code{:var} (see @ref{var}), and of replacing ``noweb'' +references (see @ref{Noweb reference syntax}) with their targets. The +@code{:no-expand} header argument can be used to turn off this behavior. + +@node session, noweb, no-expand, Specific header arguments +@subsubsection @code{:session} + +The @code{:session} header argument starts a session for an interpreted +language where state is preserved. + +By default, a session is not started. + +A string passed to the @code{:session} header argument will give the session +a name. This makes it possible to run concurrent sessions for each +interpreted language. + +@node noweb, cache, session, Specific header arguments +@subsubsection @code{:noweb} + +The @code{:noweb} header argument controls expansion of ``noweb'' style (see +@ref{Noweb reference syntax}) references in a code block. This header +argument can have one of three values: @code{yes} @code{no} or @code{tangle}. + +@itemize @bullet +@item @code{yes} +All ``noweb'' syntax references in the body of the code block will be +expanded before the block is evaluated, tangled or exported. +@item @code{no} +The default. No ``noweb'' syntax specific action is taken on evaluating +code blocks, However, noweb references will still be expanded during +tangling. +@item @code{tangle} +All ``noweb'' syntax references in the body of the code block will be +expanded before the block is tangled, however ``noweb'' references will not +be expanded when the block is evaluated or exported. +@end itemize + +@subsubheading Noweb prefix lines +Noweb insertions are now placed behind the line prefix of the +@code{<<reference>>}. +This behavior is illustrated in the following example. Because the +@code{<<example>>} noweb reference appears behind the SQL comment syntax, +each line of the expanded noweb reference will be commented. + +This code block: + +@example +-- <<example>> +@end example + + +expands to: + +@example +-- this is the +-- multi-line body of example +@end example + +Note that noweb replacement text that does not contain any newlines will not +be affected by this change, so it is still possible to use inline noweb +references. + +@node cache, hlines, noweb, Specific header arguments +@subsubsection @code{:cache} + +The @code{:cache} header argument controls the use of in-buffer caching of +the results of evaluating code blocks. It can be used to avoid re-evaluating +unchanged code blocks. This header argument can have one of two +values: @code{yes} or @code{no}. + +@itemize @bullet +@item @code{no} +The default. No caching takes place, and the code block will be evaluated +every time it is called. +@item @code{yes} +Every time the code block is run a SHA1 hash of the code and arguments +passed to the block will be generated. This hash is packed into the +@code{#+results:} line and will be checked on subsequent +executions of the code block. If the code block has not +changed since the last time it was evaluated, it will not be re-evaluated. +@end itemize + +@node hlines, colnames, cache, Specific header arguments +@subsubsection @code{:hlines} + +Tables are frequently represented with one or more horizontal lines, or +hlines. The @code{:hlines} argument to a code block accepts the +values @code{yes} or @code{no}, with a default value of @code{no}. + +@itemize @bullet +@item @code{no} +Strips horizontal lines from the input table. In most languages this is the +desired effect because an @code{hline} symbol is interpreted as an unbound +variable and raises an error. Setting @code{:hlines no} or relying on the +default value yields the following results. + +@example +#+tblname: many-cols +| a | b | c | +|---+---+---| +| d | e | f | +|---+---+---| +| g | h | i | + +#+source: echo-table +#+begin_src python :var tab=many-cols + return tab +#+end_src + +#+results: echo-table +| a | b | c | +| d | e | f | +| g | h | i | +@end example + +@item @code{yes} +Leaves hlines in the table. Setting @code{:hlines yes} has this effect. + +@example +#+tblname: many-cols +| a | b | c | +|---+---+---| +| d | e | f | +|---+---+---| +| g | h | i | + +#+source: echo-table +#+begin_src python :var tab=many-cols :hlines yes + return tab +#+end_src + +#+results: echo-table +| a | b | c | +|---+---+---| +| d | e | f | +|---+---+---| +| g | h | i | +@end example +@end itemize + +@node colnames, rownames, hlines, Specific header arguments +@subsubsection @code{:colnames} + +The @code{:colnames} header argument accepts the values @code{yes}, +@code{no}, or @code{nil} for unassigned. The default value is @code{nil}. + +@itemize @bullet +@item @code{nil} +If an input table looks like it has column names +(because its second row is an hline), then the column +names will be removed from the table before +processing, then reapplied to the results. + +@example +#+tblname: less-cols +| a | +|---| +| b | +| c | + +#+srcname: echo-table-again +#+begin_src python :var tab=less-cols + return [[val + '*' for val in row] for row in tab] +#+end_src + +#+results: echo-table-again +| a | +|----| +| b* | +| c* | +@end example + +@item @code{no} +No column name pre-processing takes place + +@item @code{yes} +Column names are removed and reapplied as with @code{nil} even if the table +does not ``look like'' it has column names (i.e. the second row is not an +hline) +@end itemize + +@node rownames, shebang, colnames, Specific header arguments +@subsubsection @code{:rownames} + +The @code{:rownames} header argument can take on the values @code{yes} +or @code{no}, with a default value of @code{no}. + +@itemize @bullet +@item @code{no} +No row name pre-processing will take place. + +@item @code{yes} +The first column of the table is removed from the table before processing, +and is then reapplied to the results. + +@example +#+tblname: with-rownames +| one | 1 | 2 | 3 | 4 | 5 | +| two | 6 | 7 | 8 | 9 | 10 | + +#+srcname: echo-table-once-again +#+begin_src python :var tab=with-rownames :rownames yes + return [[val + 10 for val in row] for row in tab] +#+end_src + +#+results: echo-table-once-again +| one | 11 | 12 | 13 | 14 | 15 | +| two | 16 | 17 | 18 | 19 | 20 | +@end example +@end itemize + +@node shebang, eval, rownames, Specific header arguments +@subsubsection @code{:shebang} + +Setting the @code{:shebang} header argument to a string value +(e.g. @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the +first line of any tangled file holding the code block, and the file +permissions of the tangled file are set to make it executable. + +@node eval, , shebang, Specific header arguments +@subsubsection @code{:eval} +The @code{:eval} header argument can be used to limit the evaluation of +specific code blocks. @code{:eval} accepts two arguments ``never'' and +``query''. @code{:eval never} will ensure that a code block is never +evaluated, this can be useful for protecting against the evaluation of +dangerous code blocks. @code{:eval query} will require a query for every +execution of a code block regardless of the value of the +@code{org-confirm-babel-evaluate} variable. + +@node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code +@section Results of evaluation +@cindex code block, results of evaluation +@cindex source code, results of evaluation + +The way in which results are handled depends on whether a session is invoked, +as well as on whether @code{:results value} or @code{:results output} is +used. The following table shows the possibilities: + +@multitable @columnfractions 0.26 0.33 0.41 +@item @tab @b{Non-session} @tab @b{Session} +@item @code{:results value} @tab value of last expression @tab value of last expression +@item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output +@end multitable + +Note: With @code{:results value}, the result in both @code{:session} and +non-session is returned to Org-mode as a table (a one- or two-dimensional +vector of strings or numbers) when appropriate. + +@subsection Non-session +@subsubsection @code{:results value} +This is the default. Internally, the value is obtained by wrapping the code +in a function definition in the external language, and evaluating that +function. Therefore, code should be written as if it were the body of such a +function. In particular, note that Python does not automatically return a +value from a function unless a @code{return} statement is present, and so a +@samp{return} statement will usually be required in Python. + +This is the only one of the four evaluation contexts in which the code is +automatically wrapped in a function definition. + +@subsubsection @code{:results output} +The code is passed to the interpreter as an external process, and the +contents of the standard output stream are returned as text. (In certain +languages this also contains the error output stream; this is an area for +future work.) + +@subsection Session +@subsubsection @code{:results value} +The code is passed to the interpreter running as an interactive Emacs +inferior process. The result returned is the result of the last evaluation +performed by the interpreter. (This is obtained in a language-specific +manner: the value of the variable @code{_} in Python and Ruby, and the value +of @code{.Last.value} in R). + +@subsubsection @code{:results output} +The code is passed to the interpreter running as an interactive Emacs +inferior process. The result returned is the concatenation of the sequence of +(text) output from the interactive interpreter. Notice that this is not +necessarily the same as what would be sent to @code{STDOUT} if the same code +were passed to a non-interactive interpreter running as an external +process. For example, compare the following two blocks: + +@example +#+begin_src python :results output + print "hello" + 2 + print "bye" +#+end_src + +#+resname: +: hello +: bye +@end example + +In non-session mode, the `2' is not printed and does not appear. +@example +#+begin_src python :results output :session + print "hello" + 2 + print "bye" +#+end_src + +#+resname: +: hello +: 2 +: bye +@end example + +But in @code{:session} mode, the interactive interpreter receives input `2' +and prints out its value, `2'. (Indeed, the other print statements are +unnecessary here). + +@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code +@section Noweb reference syntax +@cindex code block, noweb reference +@cindex syntax, noweb +@cindex source code, noweb reference + +The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate +Programming system allows named blocks of code to be referenced by using the +familiar Noweb syntax: + +@example +<<code-block-name>> +@end example + +When a code block is tangled or evaluated, whether or not ``noweb'' +references are expanded depends upon the value of the @code{:noweb} header +argument. If @code{:noweb yes}, then a Noweb reference is expanded before +evaluation. If @code{:noweb no}, the default, then the reference is not +expanded before evaluation. + +Note: the default value, @code{:noweb no}, was chosen to ensure that +correct code is not broken in a language, such as Ruby, where +@code{<<arg>>} is a syntactically valid construct. If @code{<<arg>>} is not +syntactically valid in languages that you use, then please consider setting +the default value. + +@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code +@section Key bindings and useful functions +@cindex code block, key bindings + +Many common Org-mode key sequences are re-bound depending on +the context. + +Within a code block, the following key bindings +are active: + +@multitable @columnfractions 0.25 0.75 +@kindex C-c C-c +@item @kbd{C-c C-c} @tab org-babel-execute-src-block +@kindex C-c C-o +@item @kbd{C-c C-o} @tab org-babel-open-src-block-result +@kindex C-up +@item @kbd{C-@key{up}} @tab org-babel-load-in-session +@kindex M-down +@item @kbd{M-@key{down}} @tab org-babel-pop-to-session +@end multitable + +In an Org-mode buffer, the following key bindings are active: + +@multitable @columnfractions 0.45 0.55 +@kindex C-c C-v a +@kindex C-c C-v C-a +@item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab org-babel-sha1-hash +@kindex C-c C-v b +@kindex C-c C-v C-b +@item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab org-babel-execute-buffer +@kindex C-c C-v f +@kindex C-c C-v C-f +@item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab org-babel-tangle-file +@kindex C-c C-v g +@item @kbd{C-c C-v g} @tab org-babel-goto-named-source-block +@kindex C-c C-v h +@item @kbd{C-c C-v h} @tab org-babel-describe-bindings +@kindex C-c C-v l +@kindex C-c C-v C-l +@item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab org-babel-lob-ingest +@kindex C-c C-v p +@kindex C-c C-v C-p +@item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab org-babel-expand-src-block +@kindex C-c C-v s +@kindex C-c C-v C-s +@item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab org-babel-execute-subtree +@kindex C-c C-v t +@kindex C-c C-v C-t +@item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab org-babel-tangle +@kindex C-c C-v z +@kindex C-c C-v C-z +@item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab org-babel-switch-to-session +@end multitable + +@c When possible these keybindings were extended to work when the control key is +@c kept pressed, resulting in the following additional keybindings. + +@c @multitable @columnfractions 0.25 0.75 +@c @item @kbd{C-c C-v C-a} @tab org-babel-sha1-hash +@c @item @kbd{C-c C-v C-b} @tab org-babel-execute-buffer +@c @item @kbd{C-c C-v C-f} @tab org-babel-tangle-file +@c @item @kbd{C-c C-v C-l} @tab org-babel-lob-ingest +@c @item @kbd{C-c C-v C-p} @tab org-babel-expand-src-block +@c @item @kbd{C-c C-v C-s} @tab org-babel-execute-subtree +@c @item @kbd{C-c C-v C-t} @tab org-babel-tangle +@c @item @kbd{C-c C-v C-z} @tab org-babel-switch-to-session +@c @end multitable + +@node Batch execution, , Key bindings and useful functions, Working With Source Code +@section Batch execution +@cindex code block, batch execution +@cindex source code, batch execution + +It is possible to call functions from the command line. This shell +script calls @code{org-babel-tangle} on every one of its arguments. + +Be sure to adjust the paths to fit your system. + +@example +#!/bin/sh +# -*- mode: shell-script -*- +# +# tangle files with org-mode +# +DIR=`pwd` +FILES="" +ORGINSTALL="~/src/org/lisp/org-install.el" + +# wrap each argument in the code required to call tangle on it +for i in $@@; do + FILES="$FILES \"$i\"" +done + +emacs -Q --batch -l $ORGINSTALL \ +--eval "(progn +(add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\")) +(add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\")) +(require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle) +(mapc (lambda (file) + (find-file (expand-file-name file \"$DIR\")) + (org-babel-tangle) + (kill-buffer)) '($FILES)))" 2>&1 |grep tangled +@end example + +@node Miscellaneous, Hacking, Working With Source Code, Top +@chapter Miscellaneous + +@menu +* Completion:: M-TAB knows what you need +* Easy Templates:: Quick insertion of structural elements +* Speed keys:: Electric commands at the beginning of a headline +* Code evaluation security:: Org mode files evaluate inline code +* Customization:: Adapting Org 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 on a tty +* Interaction:: Other Emacs packages +@end menu + + +@node Completion, Easy Templates, 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 + +Emacs would not be Emacs without completion, and Org-mode uses it whenever it +makes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface for +some of the completion prompts, you can specify your preference by setting at +most one of the variables @code{org-completion-use-iswitchb} +@code{org-completion-use-ido}. + +Org 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 Easy Templates, Speed keys, Completion, Miscellaneous +@section Easy Templates +@cindex template insertion +@cindex insertion, of templates + +Org-mode supports insertion of empty structural elements (like +@code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key +strokes. This is achieved through a native template expansion mechanism. +Note that Emacs has several other template mechanisms which could be used in +a similar way, for example @file{yasnippet}. + +To insert a structural element, type a @samp{<}, followed by a template +selector and @kbd{@key{TAB}}. Completion takes effect only when the above +keystrokes are typed on a line by itself. + +The following template selectors are currently supported. + +@multitable @columnfractions 0.1 0.9 +@item @kbd{s} @tab @code{#+begin_src ... #+end_src} +@item @kbd{e} @tab @code{#+begin_example ... #+end_example} +@item @kbd{q} @tab @code{#+begin_quote ... #+end_quote} +@item @kbd{v} @tab @code{#+begin_verse ... #+end_verse} +@item @kbd{c} @tab @code{#+begin_center ... #+end_center} +@item @kbd{l} @tab @code{#+begin_latex ... #+end_latex} +@item @kbd{L} @tab @code{#+latex:} +@item @kbd{h} @tab @code{#+begin_html ... #+end_html} +@item @kbd{H} @tab @code{#+html:} +@item @kbd{a} @tab @code{#+begin_ascii ... #+end_ascii} +@item @kbd{A} @tab @code{#+ascii:} +@item @kbd{i} @tab @code{#+include:} line +@end multitable + +For example, on an empty line, typing "<e" and then pressing TAB, will expand +into a complete EXAMPLE template. + +You can install additional templates by customizing the variable +@code{org-structure-template-alist}. See the docstring of the variable for +additional details. + +@node Speed keys, Code evaluation security, Easy Templates, Miscellaneous +@section Speed keys +@cindex speed keys +@vindex org-use-speed-commands +@vindex org-speed-commands-user + +Single keys can be made to execute commands when the cursor is at the +beginning of a headline, i.e. before the first star. Configure the variable +@code{org-use-speed-commands} to activate this feature. There is a +pre-defined list of commands, and you can add more such commands using the +variable @code{org-speed-commands-user}. Speed keys do not only speed up +navigation and other commands, but they also provide an alternative way to +execute commands bound to keys that are not or not easily available on a TTY, +or on a small mobile device with a limited keyboard. + +To see which commands are available, activate the feature and press @kbd{?} +with the cursor at the beginning of a headline. + +@node Code evaluation security, Customization, Speed keys, Miscellaneous +@section Code evaluation and security issues + +Org provides tools to work with the code snippets, including evaluating them. + +Running code on your machine always comes with a security risk. Badly +written or malicious code can be executed on purpose or by accident. Org has +default settings which will only evaluate such code if you give explicit +permission to do so, and as a casual user of these features you should leave +these precautions intact. + +For people who regularly work with such code, the confirmation prompts can +become annoying, and you might want to turn them off. This can be done, but +you must be aware of the risks that are involved. + +Code evaluation can happen under the following circumstances: + +@table @i +@item Source code blocks +Source code blocks can be evaluated during export, or when pressing @kbd{C-c +C-c} in the block. The most important thing to realize here is that Org mode +files which contain code snippets are, in a certain sense, like executable +files. So you should accept them and load them into Emacs only from trusted +sources---just like you would do with a program you install on your computer. + +Make sure you know what you are doing before customizing the variables +which take off the default security brakes. + +@defopt org-confirm-babel-evaluate +When set to t user is queried before code block evaluation +@end defopt + +@item Following @code{shell} and @code{elisp} links +Org has two link types that can directly evaluate code (@pxref{External +links}). These links can be problematic because the code to be evaluated is +not visible. + +@defopt org-confirm-shell-link-function +Function to queries user about shell link execution. +@end defopt +@defopt org-confirm-elisp-link-function +Functions to query user for Emacs Lisp link execution. +@end defopt + +@item Formulas in tables +Formulas in tables (@pxref{The spreadsheet}) are code that is evaluated +either by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter. +@end table + +@node Customization, In-buffer settings, Code evaluation security, 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. 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. + +@vindex org-archive-location +@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 ..... +@cindex property, COLUMNS +Set the default format for columns view. This format applies when +columns view is invoked in locations where no @code{COLUMNS} property +applies. +@item #+CONSTANTS: name1=value1 ... +@vindex org-table-formula-constants +@vindex org-table-formula +Set file-local values for constants to be used in table formulas. This +line sets the local variable @code{org-table-formula-constants-local}. +The global version of this variable is +@code{org-table-formula-constants}. +@item #+FILETAGS: :tag1:tag2:tag3: +Set tags that can be inherited by any entry in the file, including the +top-level entries. +@item #+DRAWERS: NAME1 ..... +@vindex org-drawers +Set the file-local set of drawers. The corresponding global variable is +@code{org-drawers}. +@item #+LINK: linkword replace +@vindex org-link-abbrev-alist +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 +@vindex org-highest-priority +@vindex org-lowest-priority +@vindex org-default-priority +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 than 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. +@cindex #+SETUPFILE +@item #+SETUPFILE: file +This line defines a file that holds more in-buffer setup. Normally this is +entirely ignored. Only when the buffer is parsed for option-setting lines +(i.e. when starting Org-mode for a file, when pressing @kbd{C-c C-c} in a +settings line, or when exporting), then the contents of this file are parsed +as if they had been included in the buffer. In particular, the file can be +any other Org-mode file with internal setup. You can visit the file the +cursor is in the line with @kbd{C-c '}. +@item #+STARTUP: +@cindex #+STARTUP: +This line sets options to be used at startup of Org-mode, when an +Org 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}. +@vindex org-startup-folded +@cindex @code{overview}, STARTUP keyword +@cindex @code{content}, STARTUP keyword +@cindex @code{showall}, STARTUP keyword +@cindex @code{showeverything}, STARTUP keyword +@example +overview @r{top-level headlines only} +content @r{all headlines} +showall @r{no folding of any entries} +showeverything @r{show even drawer contents} +@end example + +@vindex org-startup-indented +@cindex @code{indent}, STARTUP keyword +@cindex @code{noindent}, STARTUP keyword +Dynamic virtual indentation is controlled by the variable +@code{org-startup-indented}@footnote{Emacs 23 and Org-mode 6.29 are required} +@example +indent @r{start with @code{org-indent-mode} turned on} +noindent @r{start with @code{org-indent-mode} turned off} +@end example + +@vindex org-startup-align-all-tables +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 + +@vindex org-startup-with-inline-images +When visiting a file, inline images can be automatically displayed. The +corresponding variable is @code{org-startup-with-inline-images}, with a +default value @code{nil} to avoid delays when visiting a file. +@cindex @code{inlineimages}, STARTUP keyword +@cindex @code{noinlineimages}, STARTUP keyword +@example +inlineimages @r{show inline images} +noinlineimages @r{don't show inline images on startup} +@end example + +@vindex org-log-done +@vindex org-log-note-clock-out +@vindex org-log-repeat +Logging the closing and reopening of TODO items and clock intervals can be +configured using these options (see variables @code{org-log-done}, +@code{org-log-note-clock-out} and @code{org-log-repeat}) +@cindex @code{logdone}, STARTUP keyword +@cindex @code{lognotedone}, STARTUP keyword +@cindex @code{nologdone}, STARTUP keyword +@cindex @code{lognoteclock-out}, STARTUP keyword +@cindex @code{nolognoteclock-out}, STARTUP keyword +@cindex @code{logrepeat}, STARTUP keyword +@cindex @code{lognoterepeat}, STARTUP keyword +@cindex @code{nologrepeat}, STARTUP keyword +@cindex @code{logreschedule}, STARTUP keyword +@cindex @code{lognotereschedule}, STARTUP keyword +@cindex @code{nologreschedule}, STARTUP keyword +@cindex @code{logredeadline}, STARTUP keyword +@cindex @code{lognoteredeadline}, STARTUP keyword +@cindex @code{nologredeadline}, STARTUP keyword +@cindex @code{logrefile}, STARTUP keyword +@cindex @code{lognoterefile}, STARTUP keyword +@cindex @code{nologrefile}, STARTUP keyword +@example +logdone @r{record a timestamp when an item is marked DONE} +lognotedone @r{record timestamp and a note when DONE} +nologdone @r{don't record when items are marked DONE} +logrepeat @r{record a time when reinstating a repeating item} +lognoterepeat @r{record a note when reinstating a repeating item} +nologrepeat @r{do not record when reinstating repeating item} +lognoteclock-out @r{record a note when clocking out} +nolognoteclock-out @r{don't record a note when clocking out} +logreschedule @r{record a timestamp when scheduling time changes} +lognotereschedule @r{record a note when scheduling time changes} +nologreschedule @r{do not record when a scheduling date changes} +logredeadline @r{record a timestamp when deadline changes} +lognoteredeadline @r{record a note when deadline changes} +nologredeadline @r{do not record when a deadline date changes} +logrefile @r{record a timestamp when refiling} +lognoterefile @r{record a note when refiling} +nologrefile @r{do not record when refiling} +@end example +@vindex org-hide-leading-stars +@vindex org-odd-levels-only +Here are the options for hiding leading stars in outline headings, and for +indenting outlines. 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} +indent @r{virtual indentation according to outline level} +noindent @r{no virtual indentation according to outline level} +odd @r{allow only odd outline levels (1,3,...)} +oddeven @r{allow all outline levels} +@end example +@vindex org-put-time-stamp-overlays +@vindex org-time-stamp-overlay-formats +To turn on custom format overlays over timestamps (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 +@vindex constants-unit-system +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 +@vindex org-footnote-define-inline +@vindex org-footnote-auto-label +@vindex org-footnote-auto-adjust +To influence footnote settings, use the following keywords. The +corresponding variables are @code{org-footnote-define-inline}, +@code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}. +@cindex @code{fninline}, STARTUP keyword +@cindex @code{nofninline}, STARTUP keyword +@cindex @code{fnlocal}, STARTUP keyword +@cindex @code{fnprompt}, STARTUP keyword +@cindex @code{fnauto}, STARTUP keyword +@cindex @code{fnconfirm}, STARTUP keyword +@cindex @code{fnplain}, STARTUP keyword +@cindex @code{fnadjust}, STARTUP keyword +@cindex @code{nofnadjust}, STARTUP keyword +@example +fninline @r{define footnotes inline} +fnnoinline @r{define footnotes in separate section} +fnlocal @r{define footnotes near first reference, but not inline} +fnprompt @r{prompt for footnote labels} +fnauto @r{create [fn:1]-like labels automatically (default)} +fnconfirm @r{offer automatic label for editing or confirmation} +fnplain @r{create [1]-like labels automatically} +fnadjust @r{automatically renumber and sort footnotes} +nofnadjust @r{do not renumber and sort automatically} +@end example +@cindex org-hide-block-startup +To hide blocks on startup, use these keywords. The corresponding variable is +@code{org-hide-block-startup}. +@cindex @code{hideblocks}, STARTUP keyword +@cindex @code{nohideblocks}, STARTUP keyword +@example +hideblocks @r{Hide all begin/end blocks on startup} +nohideblocks @r{Do not hide blocks on startup} +@end example +@cindex org-pretty-entities +The display of entities as UTF-8 characters is governed by the variable +@code{org-pretty-entities} and the keywords +@cindex @code{entitiespretty}, STARTUP keyword +@cindex @code{entitiesplain}, STARTUP keyword +@example +entitiespretty @r{Show entities as UTF-8 characters where possible} +entitiesplain @r{Leave entities plain} +@end example +@item #+TAGS: TAG1(c1) TAG2(c2) +@vindex org-tag-alist +These lines (several such lines are allowed) specify the valid 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:, #+DATE:, +@itemx #+OPTIONS:, #+BIND:, #+XSLT:, +@itemx #+DESCRIPTION:, #+KEYWORDS:, +@itemx #+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:, +@itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS: +These lines provide settings for exporting files. For more details see +@ref{Export options}. +@item #+TODO: #+SEQ_TODO: #+TYP_TODO: +@vindex org-todo-keywords +These lines set the TODO keywords and their interpretation in the +current file. The corresponding variable is @code{org-todo-keywords}. +@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, 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, 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 current buffer is a capture 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 at a footnote reference, go to the corresponding +definition, and vice versa. +@item +If the cursor is on a statistics cookie, update it. +@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. +@item +If the cursor is on the @code{#+BEGIN} line of a dynamic block, the +block is updated. +@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 dynamic indentation +@cindex odd-levels-only outlines +@cindex clean outline view + +Some people find it noisy and distracting that the Org headlines start with a +potentially large number of stars, and that text below the headlines is not +indented. While this is no problem when writing a @emph{book-like} document +where the outline headings are really section headings, in a more +@emph{list-oriented} outline, indented structure is a lot cleaner: + +@example +@group +* Top level headline | * Top level headline +** Second level | * Second level +*** 3rd level | * 3rd level +some text | some text +*** 3rd level | * 3rd level +more text | more text +* Another top level headline | * Another top level headline +@end group +@end example + +@noindent + +If you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crash +with @code{org-indent-mode}} and version 6.29 of Org, this kind of view can +be achieved dynamically at display time using @code{org-indent-mode}. In +this minor mode, all lines are prefixed for display with the necessary amount +of space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix} +property, such that @code{visual-line-mode} (or purely setting +@code{word-wrap}) wraps long lines (including headlines) correctly indented. +}. Also headlines are prefixed with additional stars, so that the amount of +indentation shifts by two@footnote{See the variable +@code{org-indent-indentation-per-level}.} spaces per level. All headline +stars but the last one are made invisible using the @code{org-hide} +face@footnote{Turning on @code{org-indent-mode} sets +@code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to +@code{nil}.} - see below under @samp{2.} for more information on how this +works. You can turn on @code{org-indent-mode} for all files by customizing +the variable @code{org-startup-indented}, or you can turn it on for +individual files using + +@example +#+STARTUP: indent +@end example + +If you want a similar effect in an earlier version of Emacs and/or Org, or if +you want the indentation to be hard space characters so that the plain text +file looks as similar as possible to the Emacs display, Org supports you in +the following way: + +@enumerate +@item +@emph{Indentation of text below headlines}@* +You may indent text below each headline to make the left boundary line up +with the headline, like + +@example +*** 3rd level + more text, now indented +@end example + +@vindex org-adapt-indentation +Org supports this with paragraph filling, line wrapping, and structure +editing@footnote{See also the variable @code{org-adapt-indentation}.}, +preserving or adapting the indentation as appropriate. + +@item +@vindex org-hide-leading-stars +@emph{Hiding leading stars}@* You can modify the display in such a way that +all leading stars become invisible. To do this in a global way, configure +the variable @code{org-hide-leading-stars} or change this on a per-file basis +with + +@example +#+STARTUP: hidestars +#+STARTUP: showstars +@end example + +With hidden stars, the tree becomes: + +@example +@group +* Top level headline + * Second level + * 3rd level + ... +@end group +@end example + +@noindent +@vindex org-hide @r{(face)} +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. + +@item +@vindex org-odd-levels-only +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@footnote{When you need to specify a level for a property search +or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc@.}. In this +way we get the outline view shown at the beginning of this section. In order +to make the structure editing and export commands handle this convention +correctly, configure the variable @code{org-odd-levels-only}, or set this on +a per-file basis with one of the following lines: + +@example +#+STARTUP: odd +#+STARTUP: oddeven +@end example + +You can convert an Org 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}. +@end enumerate + +@node TTY keys, Interaction, Clean view, Miscellaneous +@section Using Org on a tty +@cindex tty key bindings + +Because Org contains a large number of commands, by default many of +Org's core commands are bound to keys that are generally not +accessible on a tty, such as the cursor keys (@key{left}, @key{right}, +@key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used +together with modifiers like @key{Meta} and/or @key{Shift}. To access +these commands on a tty when special keys are unavailable, the following +alternative bindings can be used. The tty bindings below will likely be +more cumbersome; you may find for some of the bindings below that a +customized workaround suits you better. For example, changing a timestamp +is really only fun with @kbd{S-@key{cursor}} keys, whereas on a +tty you would rather use @kbd{C-c .} to re-insert the timestamp. + +@multitable @columnfractions 0.15 0.2 0.1 0.2 +@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2} +@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab +@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}} +@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab +@item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}} +@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab +@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}} +@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab +@item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}} +@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab +@item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab +@item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}} +@item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab +@item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab +@item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab +@item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab +@item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab +@item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab +@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab +@end multitable + + +@node Interaction, , TTY keys, Miscellaneous +@section Interaction with other packages +@cindex packages, interaction with other +Org lives in the world of GNU Emacs and interacts in various ways +with other code out there. + +@menu +* Cooperation:: Packages Org cooperates with +* Conflicts:: Packages that lead to conflicts +@end menu + +@node Cooperation, Conflicts, Interaction, Interaction +@subsection Packages that Org cooperates with + +@table @asis +@cindex @file{calc.el} +@cindex Gillespie, Dave +@item @file{calc.el} by Dave Gillespie +Org uses the Calc package for implementing spreadsheet +functionality in its tables (@pxref{The spreadsheet}). Org +checks for the availability of Calc by looking for the function +@code{calc-eval} which will have been autoloaded during 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}. +@item @file{constants.el} by Carsten Dominik +@cindex @file{constants.el} +@cindex Dominik, Carsten +@vindex org-table-formula-constants +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 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} +@cindex Dominik, Carsten +Org-mode can make use of the CDLa@TeX{} package to efficiently enter +@LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}. +@item @file{imenu.el} by Ake Stenhoff and Lars Lindberg +@cindex @file{imenu.el} +Imenu allows menu access to an index of items in a file. Org-mode +supports Imenu---all you need to do to get the index is the following: +@lisp +(add-hook 'org-mode-hook + (lambda () (imenu-add-to-menubar "Imenu"))) +@end lisp +@vindex org-imenu-depth +By default the index is two levels deep---you can modify the depth using +the option @code{org-imenu-depth}. +@item @file{remember.el} by John Wiegley +@cindex @file{remember.el} +@cindex Wiegley, John +Org used to use this package for capture, but no longer does. +@item @file{speedbar.el} by Eric M. Ludlam +@cindex @file{speedbar.el} +@cindex Ludlam, Eric M. +Speedbar is a package that creates a special frame displaying files and +index items in files. Org-mode supports Speedbar and allows you to +drill into Org files directly from the Speedbar. It also allows you to +restrict the scope of agenda commands to a file or a subtree by using +the command @kbd{<} in the Speedbar frame. +@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} +@cindex Ota, Takaaki + +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). +Org-mode will recognize these tables and export them properly. Because of +interference with other Org-mode functionality, you unfortunately cannot edit +these tables directly in the buffer. Instead, you need to use the command +@kbd{C-c '} to edit them, similar to source code snippets. + +@table @kbd +@orgcmd{C-c ',org-edit-special} +Edit a @file{table.el} table. Works when the cursor is in a table.el table. +@c +@orgcmd{C-c ~,org-table-create-with-table.el} +Insert a @file{table.el} table. If there is already a table at point, this +command converts it between the @file{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 since Emacs 22. +@item @file{footnote.el} by Steven L. Baur +@cindex @file{footnote.el} +@cindex Baur, Steven L. +Org-mode recognizes numerical footnotes as provided by this package. +However, Org-mode also has its own footnote support (@pxref{Footnotes}), +which makes using @file{footnote.el} unnecessary. +@end table + +@node Conflicts, , Cooperation, Interaction +@subsection Packages that lead to conflicts with Org-mode + +@table @asis + +@cindex @code{shift-selection-mode} +@vindex org-support-shift-select +In Emacs 23, @code{shift-selection-mode} is on by default, meaning that +cursor motions combined with the shift key should start or enlarge regions. +This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change +timestamps, TODO keywords, priorities, and item bullet types if the cursor is +at such a location. By default, @kbd{S-@key{cursor}} commands outside +special contexts don't do anything, but you can customize the variable +@code{org-support-shift-select}. Org-mode then tries to accommodate shift +selection by (i) using it outside of the special contexts where special +commands apply, and by (ii) extending an existing active region even if the +cursor moves across a special context. + +@item @file{CUA.el} by Kim. F. Storm +@cindex @file{CUA.el} +@cindex Storm, Kim. F. +@vindex org-replace-disputed-keys +Key bindings in Org conflict with the @kbd{S-<cursor>} keys used by CUA mode +(as well as @code{pc-select-mode} and @code{s-region-mode}) to select and extend the +region. In fact, Emacs 23 has this built-in in the form of +@code{shift-selection-mode}, see previous paragraph. If you are using Emacs +23, you probably don't want to use another package for this purpose. However, +if you prefer to leave these keys to a different package while working in +Org-mode, configure the variable @code{org-replace-disputed-keys}. When set, +Org will move the following key bindings in Org 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-+ +C-S-LEFT -> M-S-- C-S-RIGHT -> M-S-+ +@end example + +@vindex org-disputed-keys +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{yasnippet.el} +@cindex @file{yasnippet.el} +The way Org-mode binds the TAB key (binding to @code{[tab]} instead of +@code{"\t"}) overrules YASnippet's access to this key. The following code +fixed this problem: + +@lisp +(add-hook 'org-mode-hook + (lambda () + (org-set-local 'yas/trigger-key [tab]) + (define-key yas/keymap [tab] 'yas/next-field-group))) +@end lisp + +@item @file{windmove.el} by Hovav Shacham +@cindex @file{windmove.el} +This package also uses the @kbd{S-<cursor>} keys, so everything written +in the paragraph above about CUA mode also applies here. If you want make +the windmove function active in locations where Org-mode does not have +special functionality on @kbd{S-@key{cursor}}, add this to your +configuration: + +@lisp +;; Make windmove work in org-mode: +(add-hook 'org-shiftup-final-hook 'windmove-up) +(add-hook 'org-shiftleft-final-hook 'windmove-left) +(add-hook 'org-shiftdown-final-hook 'windmove-down) +(add-hook 'org-shiftright-final-hook 'windmove-right) +@end lisp + +@item @file{viper.el} by Michael Kifer +@cindex @file{viper.el} +@kindex C-c / +Viper uses @kbd{C-c /} and therefore makes this key not access the +corresponding Org-mode command @code{org-sparse-tree}. You need to find +another key for this command, or override the key in +@code{viper-vi-global-user-map} with + +@lisp +(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree) +@end lisp + +@end table + + +@node Hacking, MobileOrg, Miscellaneous, Top +@appendix Hacking +@cindex hacking + +This appendix covers some aspects where users can extend the functionality of +Org. + +@menu +* Hooks:: Who to reach into Org's internals +* Add-on packages:: Available extensions +* Adding hyperlink types:: New custom link types +* Context-sensitive commands:: How to add functionality to such commands +* Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs +* Dynamic blocks:: Automatically filled blocks +* Special agenda views:: Customized views +* Extracting agenda information:: Postprocessing of agenda information +* Using the property API:: Writing programs that use entry properties +* Using the mapping API:: Mapping over all or selected entries +@end menu + +@node Hooks, Add-on packages, Hacking, Hacking +@section Hooks +@cindex hooks + +Org has a large number of hook variables that can be used to add +functionality. This appendix about hacking is going to illustrate the +use of some of them. A complete list of all hooks with documentation is +maintained by the Worg project and can be found at +@uref{http://orgmode.org/worg/org-configs/org-hooks.php}. + +@node Add-on packages, Adding hyperlink types, Hooks, Hacking +@section Add-on packages +@cindex add-on packages + +A large number of add-on packages have been written by various authors. +These packages are not part of Emacs, but they are distributed as contributed +packages with the separate release available at the Org-mode home page at +@uref{http://orgmode.org}. The list of contributed packages, along with +documentation about each package, is maintained by the Worg project at +@uref{http://orgmode.org/worg/org-contrib/}. + + + +@node Adding hyperlink types, Context-sensitive commands, Add-on packages, Hacking +@section Adding hyperlink types +@cindex hyperlinks, adding new types + +Org has a large number of hyperlink types built-in +(@pxref{Hyperlinks}). If you would like to add new link types, Org +provides an interface for doing so. Let's 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 + +(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 +Let's 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 +@vindex org-store-link-functions +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 man pages. 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}, 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 +return the value @code{nil}. If yes, the link is created by getting the +manual topic 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 an Org +buffer with @kbd{C-c C-l}. + +When it makes sense for your new link type, you may also define a function +@code{org-PREFIX-complete-link} that implements special (e.g. completion) +support for inserting such a link with @kbd{C-c C-l}. Such a function should +not accept any arguments, and return the full link with prefix. + +@node Context-sensitive commands, Tables in arbitrary syntax, Adding hyperlink types, Hacking +@section Context-sensitive commands +@cindex context-sensitive commands, hooks +@cindex add-ons, context-sensitive commands +@vindex org-ctrl-c-ctrl-c-hook + +Org has several commands that act differently depending on context. The most +important example it the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}). +Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property. + +Add-ons can tap into this functionality by providing a function that detects +special context for that add-on and executes functionality appropriate for +the context. Here is an example from Dan Davison's @file{org-R.el} which +allows you to evaluate commands based on the @file{R} programming language +@footnote{@file{org-R.el} has been replaced by the org-mode functionality +described in @ref{Working With Source Code} and is now obsolete.}. For this +package, special contexts are lines that start with @code{#+R:} or +@code{#+RR:}. + +@lisp +(defun org-R-apply-maybe () + "Detect if this is context for org-R and execute R commands." + (if (save-excursion + (beginning-of-line 1) + (looking-at "#\\+RR?:")) + (progn (call-interactively 'org-R-apply) + t) ;; to signal that we took action + nil)) ;; to signal that we did not + +(add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe) +@end lisp + +The function first checks if the cursor is in such a line. If that is the +case, @code{org-R-apply} is called and the function returns @code{t} to +signal that action was taken, and @kbd{C-c C-c} will stop looking for other +contexts. If the function finds it should do nothing locally, it returns @code{nil} so that other, similar functions can have a try. + + +@node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking +@section Tables and lists in arbitrary syntax +@cindex tables, in other modes +@cindex lists, 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 @LaTeX{}. 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. + +Bastien added the ability to do the same with lists, in Orgstruct mode. You +can use Org's facilities to edit and structure lists by turning +@code{orgstruct-mode} on, then locally exporting such lists in another format +(HTML, @LaTeX{} or Texinfo.) + + +@menu +* Radio tables:: Sending and receiving radio tables +* A LaTeX example:: Step by step, almost a tutorial +* Translator functions:: Copy and modify +* Radio lists:: Doing the same for lists +@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: +@cindex #+ORGTBL +@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 as separate lines for +this parameter! + +@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 @LaTeX{} 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 @LaTeX{}. +@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} +makes 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 of radio tables +@cindex @LaTeX{}, and Orgtbl mode + +The best way to wrap the source table in @LaTeX{} 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 @LaTeX{}, 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, let's say we use @samp{salesfigures}. You +will then get the following template: + +@cindex #+ORGTBL, SEND +@example +% BEGIN RECEIVE ORGTBL salesfigures +% END RECEIVE ORGTBL salesfigures +\begin@{comment@} +#+ORGTBL: SEND salesfigures orgtbl-to-latex +| | | +\end@{comment@} +@end example + +@noindent +@vindex @LaTeX{}-verbatim-environments +The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function +@code{orgtbl-to-latex} to convert the table into @LaTeX{} 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 AUC@TeX{} 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 let's 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 skips 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 @LaTeX{} 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 (see also @pxref{Translator functions}): + +@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, it 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\\%%")}. +A function of one argument can be used in place of the strings; the +function must return a formatted string. + +@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. Similar to @code{fmt}, functions of two arguments can be +supplied instead of strings. +@end table + +@node Translator functions, Radio lists, 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-csv} +(comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values) +@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 processing 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 @LaTeX{} 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 @LaTeX{} 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 @email{emacs-orgmode@@gnu.org} so that +others can benefit from your work. + +@node Radio lists, , Translator functions, Tables in arbitrary syntax +@subsection Radio lists +@cindex radio lists +@cindex org-list-insert-radio-list + +Sending and receiving radio lists works exactly the same way as sending and +receiving radio tables (@pxref{Radio tables}). As for radio tables, you can +insert radio list templates in HTML, @LaTeX{} and Texinfo modes by calling +@code{org-list-insert-radio-list}. + +Here are the differences with radio tables: + +@itemize @minus +@item +Orgstruct mode must be active. +@item +Use the @code{ORGLST} keyword instead of @code{ORGTBL}. +@item +The available translation functions for radio lists don't take +parameters. +@item +@kbd{C-c C-c} will work when pressed on the first item of the list. +@end itemize + +Here is a @LaTeX{} example. Let's say that you have this in your +@LaTeX{} file: + +@cindex #+ORGLST +@example +% BEGIN RECEIVE ORGLST to-buy +% END RECEIVE ORGLST to-buy +\begin@{comment@} +#+ORGLST: SEND to-buy org-list-to-latex +- a new house +- a new computer + + a new keyboard + + a new mouse +- a new life +\end@{comment@} +@end example + +Pressing `C-c C-c' on @code{a new house} and will insert the converted +@LaTeX{} list between the two marker lines. + +@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking +@section Dynamic blocks +@cindex dynamic blocks + +Org 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 blocks 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. + +@cindex #+BEGIN:dynamic block +@example +#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... + +#+END: +@end example + +Dynamic blocks are updated with the following commands + +@table @kbd +@orgcmd{C-c C-x C-u,org-dblock-update} +Update dynamic block at point. +@orgkey{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. If you want +to use the original content in the writer function, you can use the +extra parameter @code{: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 such that it does nothing in buffers that are not in +@code{org-mode}. + +@node Special agenda views, Extracting agenda information, Dynamic blocks, Hacking +@section Special agenda views +@cindex agenda views, user-defined + +Org provides a special hook that can be used to narrow down the selection +made by these agenda views: @code{todo}, @code{alltodo}, @code{tags}, @code{tags-todo}, +@code{tags-tree}. 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-skip-unless-waiting) + (org-agenda-overriding-header "Projects waiting for something: ")))) +@end lisp + +@vindex org-agenda-overriding-header +Note that this also binds @code{org-agenda-overriding-header} to get a +meaningful header in the agenda view. + +@vindex org-odd-levels-only +@vindex org-agenda-skip-function +A general way to create custom searches is to base them on a search for +entries with a certain level limit. If you want to study all entries with +your custom search function, simply do a search for +@samp{LEVEL>0}@footnote{Note that, when using @code{org-odd-levels-only}, a +level number corresponds to order in the hierarchy, not to the number of +stars.}, and then use @code{org-agenda-skip-function} to select the entries +you really want to have. + +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-if 'todo '("TODO" "WAITING")) +Skip current entry if the TODO keyword is TODO or WAITING. +@item '(org-agenda-skip-entry-if 'todo 'done) +Skip current entry if the TODO keyword marks a DONE state. +@item '(org-agenda-skip-entry-if 'timestamp) +Skip current entry if it has any timestamp, may also be deadline or scheduled. +@item '(org-agenda-skip-entry 'regexp "regular expression") +Skip current entry if the regular expression matches in the entry. +@item '(org-agenda-skip-entry 'notregexp "regular expression") +Skip current entry unless the regular expression matches. +@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 Extracting agenda information, Using the property API, Special agenda views, Hacking +@section Extracting agenda information +@cindex agenda, pipe +@cindex Scripts, for agenda processing + +@vindex org-agenda-custom-commands +Org 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-span month \ + 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 keyword, 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) +led 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 and prints all the items, preceded by a checkbox: + +@example +#!/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); + # process and print + print "[ ] $head\n"; +@} +@end example + +@node Using the property API, Using the mapping API, Extracting agenda information, 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 +@vindex org-use-property-inheritance +@defun org-entry-get pom property &optional inherit +Get value of PROPERTY for entry at point-or-marker POM. By default, +this only looks at properties defined locally in the entry. If INHERIT +is non-nil and the entry does not have the property, then also check +higher levels of the hierarchy. If INHERIT is the symbol +@code{selective}, use inheritance if and only if the setting of +@code{org-use-property-inheritance} selects PROPERTY for inheritance. +@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 + +@defun org-entry-put-multivalued-property pom property &rest values +Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a list of +strings. They will be concatenated, with spaces as separators. +@end defun + +@defun org-entry-get-multivalued-property pom property +Treat the value of the property PROPERTY as a whitespace-separated list of +values and return the values as a list of strings. +@end defun + +@defun org-entry-add-to-multivalued-property pom property value +Treat the value of the property PROPERTY as a whitespace-separated list of +values and make sure that VALUE is in this list. +@end defun + +@defun org-entry-remove-from-multivalued-property pom property value +Treat the value of the property PROPERTY as a whitespace-separated list of +values and make sure that VALUE is @emph{not} in this list. +@end defun + +@defun org-entry-member-in-multivalued-property pom property value +Treat the value of the property PROPERTY as a whitespace-separated list of +values and check if VALUE is in this list. +@end defun + +@defopt org-property-allowed-value-functions +Hook for functions supplying allowed values for a specific property. +The functions must take a single argument, the name of the property, and +return a flat list of allowed values. If @samp{:ETC} is one of +the values, use the values as completion help, but allow also other values +to be entered. The functions must return @code{nil} if they are not +responsible for this property. +@end defopt + +@node Using the mapping API, , Using the property API, Hacking +@section Using the mapping API +@cindex API, for mapping +@cindex mapping entries, API + +Org has sophisticated mapping capabilities to find all entries satisfying +certain criteria. Internally, this functionality is used to produce agenda +views, but there is also an API that can be used to execute arbitrary +functions for each or selected entries. The main entry point for this API +is: + +@defun org-map-entries func &optional match scope &rest skip +Call FUNC at each headline selected by MATCH in SCOPE. + +FUNC is a function or a Lisp form. The function will be called without +arguments, with the cursor positioned at the beginning of the headline. +The return values of all calls to the function will be collected and +returned as a list. + +The call to FUNC will be wrapped into a save-excursion form, so FUNC +does not need to preserve point. After evaluation, the cursor will be +moved to the end of the line (presumably of the headline of the +processed entry) and search continues from there. Under some +circumstances, this may not produce the wanted results. For example, +if you have removed (e.g. archived) the current (sub)tree it could +mean that the next entry will be skipped entirely. In such cases, you +can specify the position from where search should continue by making +FUNC set the variable `org-map-continue-from' to the desired buffer +position. + +MATCH is a tags/property/todo match as it is used in the agenda match view. +Only headlines that are matched by this query will be considered during +the iteration. When MATCH is nil or t, all headlines will be +visited by the iteration. + +SCOPE determines the scope of this command. It can be any of: + +@example +nil @r{the current buffer, respecting the restriction if any} +tree @r{the subtree started with the entry at point} +file @r{the current buffer, without restriction} +file-with-archives + @r{the current buffer, and any archives associated with it} +agenda @r{all agenda files} +agenda-with-archives + @r{all agenda files with any archive files associated with them} +(file1 file2 ...) + @r{if this is a list, all files in the list will be scanned} +@end example +@noindent +The remaining args are treated as settings for the skipping facilities of +the scanner. The following items can be given here: + +@vindex org-agenda-skip-function +@example +archive @r{skip trees with the archive tag} +comment @r{skip trees with the COMMENT keyword} +function or Lisp form + @r{will be used as value for @code{org-agenda-skip-function},} + @r{so whenever the function returns t, FUNC} + @r{will not be called for that entry and search will} + @r{continue from the point where the function leaves it} +@end example +@end defun + +The function given to that mapping routine can really do anything you like. +It can use the property API (@pxref{Using the property API}) to gather more +information about the entry, or in order to change metadata in the entry. +Here are a couple of functions that might be handy: + +@defun org-todo &optional arg +Change the TODO state of the entry. See the docstring of the functions for +the many possible values for the argument ARG. +@end defun + +@defun org-priority &optional action +Change the priority of the entry. See the docstring of this function for the +possible values for ACTION. +@end defun + +@defun org-toggle-tag tag &optional onoff +Toggle the tag TAG in the current entry. Setting ONOFF to either @code{on} +or @code{off} will not toggle tag, but ensure that it is either on or off. +@end defun + +@defun org-promote +Promote the current entry. +@end defun + +@defun org-demote +Demote the current entry. +@end defun + +Here is a simple example that will turn all entries in the current file with +a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}. +Entries in comment trees and in archive trees will be ignored. + +@lisp +(org-map-entries + '(org-todo "UPCOMING") + "+TOMORROW" 'file 'archive 'comment) +@end lisp + +The following example counts the number of entries with TODO keyword +@code{WAITING}, in all agenda files. + +@lisp +(length (org-map-entries t "/+WAITING" 'agenda)) +@end lisp + +@node MobileOrg, History and Acknowledgments, Hacking, Top +@appendix MobileOrg +@cindex iPhone +@cindex MobileOrg + +@uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the +@i{iPhone/iPod Touch} series of devices, developed by Richard Moreland. +@i{MobileOrg} offers offline viewing and capture support for an Org-mode +system rooted on a ``real'' computer. It does also allow you to record +changes to existing entries. Android users should check out +@uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android} +by Matt Jones. + +This appendix describes the support Org has for creating agenda views in a +format that can be displayed by @i{MobileOrg}, and for integrating notes +captured and changes made by @i{MobileOrg} into the main system. + +For changing tags and TODO states in MobileOrg, you should have set up the +customization variables @code{org-todo-keywords} and @code{org-tags-alist} to +cover all important tags and TODO keywords, even if individual files use only +part of these. MobileOrg will also offer you states and tags set up with +in-buffer settings, but it will understand the logistics of TODO state +@i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags +(@pxref{Setting tags}) only for those set in these variables. + +@menu +* Setting up the staging area:: Where to interact with the mobile device +* Pushing to MobileOrg:: Uploading Org files and agendas +* Pulling from MobileOrg:: Integrating captured and flagged items +@end menu + +@node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg +@section Setting up the staging area + +MobileOrg needs to interact with Emacs through a directory on a server. If you +are using a public server, you should consider to encrypt the files that are +uploaded to the server. This can be done with Org-mode 7.02 and with +@i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl} +installation on your system. To turn on encryption, set a password in +@i{MobileOrg} and, on the Emacs side, configure the variable +@code{org-mobile-use-encryption}@footnote{If you can safely store the +password in your Emacs setup, you might also want to configure +@code{org-mobile-encryption-password}. Please read the docstring of that +variable. Note that encryption will apply only to the contents of the +@file{.org} files. The file names themselves will remain visible.}. + +The easiest way to create that directory is to use a free +@uref{http://dropbox.com,Dropbox.com} account@footnote{If you cannot use +Dropbox, or if your version of MobileOrg does not support it, you can use a +webdav server. For more information, check out the documentation of MobileOrg and also this +@uref{http://orgmode.org/worg/org-faq.php#mobileorg_webdav, FAQ entry}.}. +When MobileOrg first connects to your Dropbox, it will create a directory +@i{MobileOrg} inside the Dropbox. After the directory has been created, tell +Emacs about it: + +@lisp +(setq org-mobile-directory "~/Dropbox/MobileOrg") +@end lisp + +Org-mode has commands to put files for @i{MobileOrg} into that directory, +and to read captured notes from there. + +@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg +@section Pushing to MobileOrg + +This operation copies all files currently listed in @code{org-mobile-files} +to the directory @code{org-mobile-directory}. By default this list contains +all agenda files (as listed in @code{org-agenda-files}), but additional files +can be included by customizing @code{org-mobiles-files}. File names will be +staged with paths relative to @code{org-directory}, so all files should be +inside this directory. The push operation also creates a special Org file +@file{agendas.org} with all custom agenda view defined by the +user@footnote{While creating the agendas, Org-mode will force ID properties +on all referenced entries, so that these entries can be uniquely identified +if @i{MobileOrg} flags them for further action. If you do not want to get +these properties in so many entries, you can set the variable +@code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then +rely on outline paths, in the hope that these will be unique enough.}. +Finally, Org writes the file @file{index.org}, containing links to all other +files. @i{MobileOrg} first reads this file from the server, and then +downloads all agendas and Org files listed in it. To speed up the download, +MobileOrg will only read files whose checksums@footnote{stored automatically +in the file @file{checksums.dat}} have changed. + +@node Pulling from MobileOrg, , Pushing to MobileOrg, MobileOrg +@section Pulling from MobileOrg + +When @i{MobileOrg} synchronizes with the server, it not only pulls the Org +files for viewing. It also appends captured entries and pointers to flagged +and changed entries to the file @file{mobileorg.org} on the server. Org has +a @emph{pull} operation that integrates this information into an inbox file +and operates on the pointers to flagged entries. Here is how it works: + +@enumerate +@item +Org moves all entries found in +@file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this +operation.} and appends them to the file pointed to by the variable +@code{org-mobile-inbox-for-pull}. Each captured entry and each editing event +will be a top-level entry in the inbox file. +@item +After moving the entries, Org will attempt to implement the changes made in +@i{MobileOrg}. Some changes are applied directly and without user +interaction. Examples are all changes to tags, TODO state, headline and body +text that can be cleanly applied. Entries that have been flagged for further +action will receive a tag @code{:FLAGGED:}, so that they can be easily found +again. When there is a problem finding an entry or applying the change, the +pointer entry will remain in the inbox and will be marked with an error +message. You need to later resolve these issues by hand. +@item +Org will then generate an agenda view with all flagged entries. The user +should then go through these entries and do whatever actions are necessary. +If a note has been stored while flagging an entry in @i{MobileOrg}, that note +will be displayed in the echo area when the cursor is on the corresponding +agenda line. +@table @kbd +@kindex ? +@item ? +Pressing @kbd{?} in that special agenda will display the full flagging note in +another window and also push it onto the kill ring. So you could use @kbd{? +z C-y C-c C-c} to store that flagging note as a normal note in the entry. +Pressing @kbd{?} twice in succession will offer to remove the +@code{:FLAGGED:} tag along with the recorded flagging note (which is stored +in a property). In this way you indicate that the intended processing for +this flagged entry is finished. +@end table +@end enumerate + +@kindex C-c a ? +If you are not able to process all flagged entries directly, you can always +return to this agenda view@footnote{Note, however, that there is a subtle +difference. The view created automatically by @kbd{M-x org-mobile-pull +@key{RET}} is guaranteed to search all files that have been addressed by the +last pull. This might include a file that is not currently in your list of +agenda files. If you later use @kbd{C-c a ?} to regenerate the view, only +the current agenda files will be searched.} using @kbd{C-c a ?}. + +@node History and Acknowledgments, Main Index, MobileOrg, Top +@appendix History and acknowledgments +@cindex acknowledgments +@cindex history +@cindex thanks + +Org was born 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 show +parts of the outline tree, that seemed entirely unacceptable to me. Also, +when using outlines to take notes, I constantly wanted 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{timestamps}, and +@emph{table support}. These areas highlighted the two main goals that Org +still has today: to be 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 to +@email{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. The list may not be +complete, if I have forgotten someone, please accept my apologies and +let me know. + +Before I get to this list, a few special mentions are in order: + +@table @i +@item Bastien Guerry +Bastien has written a large number of extensions to Org (most of them +integrated into the core by now), including the LaTeX exporter and the plain +list parser. His support during the early days, when he basically acted as +co-maintainer, was central to the success of this project. Bastien also +invented Worg, helped establishing the Web presence of Org, and sponsors +hosting costs for the orgmode.org website. +@item Eric Schulte and Dan Davison +Eric and Dan are jointly responsible for the Org-babel system, which turns +Org into a multi-language environment for evaluating code and doing literate +programming and reproducible research. +@item John Wiegley +John has contributed a number of great ideas and patches directly to Org, +including the attachment system (@file{org-attach.el}), integration with +Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO +items, habit tracking (@file{org-habits.el}), and encryption +(@file{org-crypt.el}). Also, the capture system is really an extended copy +of his great @file{remember.el}. +@item Sebastian Rose +Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work +of an ignorant amateur. Sebastian has pushed this part of Org onto a much +higher level. He also wrote @file{org-info.js}, a Java script for displaying +webpages derived from Org using an Info-like or a folding interface with +single-key navigation. +@end table + +@noindent OK, now to the full list of contributions! Again, please let me +know what I am missing here! + +@itemize @bullet + +@item +@i{Russel Adams} came up with the idea for drawers. +@item +@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}. +@item +@i{Christophe Bataillon} created the great unicorn logo that we use on the +Org-mode website. +@item +@i{Alex Bochannek} provided a patch for rounding timestamps. +@item +@i{Jan Böcker} wrote @file{org-docview.el}. +@item +@i{Brad Bozarth} showed how to pull RSS feed data into Org-mode files. +@item +@i{Tom Breton} wrote @file{org-choose.el}. +@item +@i{Charles Cave}'s suggestion sparked the implementation of templates +for Remember, which are now templates for capture. +@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 copying some linking code from Planner. +@item +@i{Baoqiu Cui} contributed the DocBook exporter. +@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{Nick Dokos} tracked down several nasty bugs. +@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{Thomas S. Dye} contributed documentation on Worg and helped integrating +the Org-Babel documentation into the manual. +@item +@i{Christian Egli} converted the documentation into Texinfo format, inspired +the agenda, patched CSS formatting into the HTML exporter, and wrote +@file{org-taskjuggler.el}. +@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{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes. +@item +@i{John Foerch} figured out how to make incremental search show context +around a match in a hidden outline tree. +@item +@i{Raimar Finken} wrote @file{org-git-line.el}. +@item +@i{Mikael Fornius} works as a mailing list moderator. +@item +@i{Austin Frank} works as a mailing list moderator. +@item +@i{Eric Fraga} drove the development of BEAMER export with ideas and +testing. +@item +@i{Barry Gidden} did proofreading the manual in preparation for the book +publication through Network Theory Ltd. +@item +@i{Niels Giesen} had the idea to automatically archive DONE trees. +@item +@i{Nicolas Goaziou} rewrote much of the plain list code. +@item +@i{Kai Grossjohann} pointed out key-binding conflicts with other packages. +@item +@i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a +book. +@item +@i{Bernt Hansen} has driven much of the support for auto-repeating tasks, +task state change logging, and the clocktable. His clear explanations have +been critical when we started to adopt the Git version control system. +@item +@i{Manuel Hermenegildo} has contributed various ideas, small fixes and +patches. +@item +@i{Phil Jackson} wrote @file{org-irc.el}. +@item +@i{Scott Jaderholm} proposed footnotes, control over whitespace between +folded entries, and column view for properties. +@item +@i{Matt Jones} wrote @i{MobileOrg Android}. +@item +@i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}. +@item +@i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also +provided frequent feedback and some patches. +@item +@i{Matt Lundin} has proposed last-row references for table formulas and named +invisible anchors. He has also worked a lot on the FAQ. +@item +@i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org, +and is a prolific contributor on the mailing list with competent replies, +small fixes and patches. +@item +@i{Jason F. McBrayer} suggested agenda export to CSV format. +@item +@i{Max Mikhanosha} came up with the idea of refiling. +@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{Richard Moreland} wrote @i{MobileOrg} for the iPhone. +@item +@i{Rick Moynihan} proposed allowing multiple TODO sequences in a file +and being able to quickly restrict the agenda to a subtree. +@item +@i{Todd Neal} provided patches for links to Info files and Elisp forms. +@item +@i{Greg Newman} refreshed the unicorn logo into its current form. +@item +@i{Tim O'Callaghan} suggested in-file links, search options for general +file links, and TAGS. +@item +@i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text +version of the reference card. +@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{Martin Pohlack} provided the code snippet to bundle character insertion +into bundles of 20 for undo. +@item +@i{T.V. Raman} reported bugs and suggested improvements. +@item +@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality +control. +@item +@i{Paul Rivier} provided the basic implementation of named footnotes. He +also acted as mailing list moderator for some time. +@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} generalized the send-receive mechanism for Orgtbl tables with +extensive patches. +@item +@i{Philip Rooke} created the Org reference card, provided lots +of feedback, developed and applied standards to the Org documentation. +@item +@i{Christian Schlauer} proposed angular brackets around links, among +other things. +@item +@i{Paul Sexton} wrote @file{org-ctags.el}. +@item +Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s +@file{organizer-mode.el}. +@item +@i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal +examples, and remote highlighting for referenced code lines. +@item +@i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is +now packaged into Org's @file{contrib} directory. +@item +@i{Daniel Sinder} came up with the idea of internal archiving by locking +subtrees. +@item +@i{Dale Smith} proposed link abbreviations. +@item +@i{James TD Smith} has contributed a large number of patches for useful +tweaks and features. +@item +@i{Adam Spiers} asked for global linking commands, inspired the link +extension system, added support for mairix, and proposed the mapping API. +@item +@i{Ulf Stegemann} created the table to translate special symbols to HTML, +LaTeX, UTF-8, Latin-1 and ASCII. +@item +@i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content +with links transformation to Org syntax. +@item +@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual +chapter about publishing. +@item +@i{Sebastien Vauban} reported many issues with LaTeX and BEAMER export and +enabled source code highlighling in Gnus. +@item +@i{Stefan Vollmar} organized a video-recorded talk at the +Max-Planck-Institute for Neurology. He also inspired the creation of a +concept index for HTML export. +@item +@i{J@"urgen Vollmer} contributed code generating the table of contents +in HTML output. +@item +@i{Samuel Wales} has provided important feedback and bug reports. +@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{Carsten Wimmer} suggested some changes and helped fix a bug in +linking to Gnus. +@item +@i{Roland Winkler} requested additional key bindings to make Org +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 Main Index, Key Index, History and Acknowledgments, Top +@unnumbered Concept index + +@printindex cp + +@node Key Index, Command and Function Index, Main Index, Top +@unnumbered Key index + +@printindex ky + +@node Command and Function Index, Variable Index, Key Index, Top +@unnumbered Command and function index + +@printindex fn + +@node Variable Index, , Command and Function Index, Top +@unnumbered Variable index + +This is not a complete index of variables and faces, only the ones that are +mentioned in the manual. For a more complete list, use @kbd{M-x +org-customize @key{RET}} and then click yourself through the tree. + +@printindex vr + +@bye + +@ignore + arch-tag: 7893d1Fe-cc57-4d13-b5e5-f494a1CBC7ac +@end ignore + +@c Local variables: +@c fill-column: 77 +@c indent-tabs-mode: nil +@c paragraph-start: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" +@c paragraph-separate: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" +@c End: + + +@c LocalWords: webdavhost pre diff --git a/.emacs.d/org-7.4/doc/orgcard.pdf b/.emacs.d/org-7.4/doc/orgcard.pdf Binary files differnew file mode 100644 index 0000000..c23afff --- /dev/null +++ b/.emacs.d/org-7.4/doc/orgcard.pdf diff --git a/.emacs.d/org-7.4/doc/orgcard.tex b/.emacs.d/org-7.4/doc/orgcard.tex new file mode 100644 index 0000000..c55c55d --- /dev/null +++ b/.emacs.d/org-7.4/doc/orgcard.tex @@ -0,0 +1,686 @@ +% Reference Card for Org Mode +\def\orgversionnumber{7.4} +\def\versionyear{2010} % latest update +\def\year{2010} % latest copyright year + +%**start of header +\newcount\columnsperpage +\newcount\letterpaper + +% This file can be printed with 1, 2, or 3 columns per page (see below). +% Specify how many you want here. +\columnsperpage=3 + +% PDF output layout. 0 for A4, 1 for letter (US), a `l' is added for +% a landscape layout. +\input pdflayout.sty +\pdflayout=(0l) + +% Nothing else needs to be changed below this line. +% Copyright (C) 1987, 1993, 1996, 1997, 2001, 2002, 2003, 2004, 2005, +% 2006, 2007, 2008, 2009 Free Software Foundation, Inc. + +% This file is part of GNU Emacs. + +% GNU Emacs is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. + +% GNU Emacs is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. + +% You should have received a copy of the GNU General Public License +% along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. + +% This file is intended to be processed by plain TeX (TeX82). +% +% The final reference card has six columns, three on each side. +% This file can be used to produce it in any of three ways: +% 1 column per page +% produces six separate pages, each of which needs to be reduced to 80%. +% This gives the best resolution. +% 2 columns per page +% produces three already-reduced pages. +% You will still need to cut and paste. +% 3 columns per page +% produces two pages which must be printed sideways to make a +% ready-to-use 8.5 x 11 inch reference card. +% For this you need a dvi device driver that can print sideways. +% Which mode to use is controlled by setting \columnsperpage above. +% +% To compile and print this document: +% tex refcard.tex +% dvips -t landscape refcard.dvi +% +% Author: +% Stephen Gildea +% Internet: gildea@stop.mail-abuse.org +% +% Thanks to Paul Rubin, Bob Chassell, Len Tower, and Richard Mlynarik +% for their many good ideas. + +\def\shortcopyrightnotice{\vskip 1ex plus 2 fill + \centerline{\small \copyright\ \year\ Free Software Foundation, Inc. + Permissions on back. v\orgversionnumber}} + +\def\copyrightnotice{ +\vskip 1ex plus 100 fill\begingroup\small +\centerline{Copyright \copyright\ \year\ Free Software Foundation, Inc.} +\centerline{v\orgversionnumber{} for Org-Mode \orgversionnumber{}, \versionyear} +\centerline{Author: Philip Rooke} +\centerline{based on refcard design and format by Stephen Gildea} + +Permission is granted to make and distribute copies of +this card provided the copyright notice and this permission notice +are preserved on all copies. + +\endgroup} + +% make \bye not \outer so that the \def\bye in the \else clause below +% can be scanned without complaint. +\def\bye{\par\vfill\supereject\end} + +\newdimen\intercolumnskip %horizontal space between columns +\newbox\columna %boxes to hold columns already built +\newbox\columnb + +\def\ncolumns{\the\columnsperpage} + +\message{[\ncolumns\space + column\if 1\ncolumns\else s\fi\space per page]} + +\def\scaledmag#1{ scaled \magstep #1} + +% This multi-way format was designed by Stephen Gildea October 1986. +% Note that the 1-column format is fontfamily-independent. +\if 1\ncolumns %one-column format uses normal size + \hsize 4in + \vsize 10in + \voffset -.7in + \font\titlefont=\fontname\tenbf \scaledmag3 + \font\headingfont=\fontname\tenbf \scaledmag2 + \font\smallfont=\fontname\sevenrm + \font\smallsy=\fontname\sevensy + + \footline{\hss\folio} + \def\makefootline{\baselineskip10pt\hsize6.5in\line{\the\footline}} +\else %2 or 3 columns uses prereduced size + \if 1\the\letterpaper + \hsize 3.2in + \vsize 7.95in + \hoffset -.75in + \voffset -.745in + \else + \hsize 3.2in + \vsize 7.65in + \hoffset -.25in + \voffset -.745in + \fi + \font\titlefont=cmbx10 \scaledmag2 + \font\headingfont=cmbx10 \scaledmag1 + \font\smallfont=cmr6 + \font\smallsy=cmsy6 + \font\eightrm=cmr8 + \font\eightbf=cmbx8 + \font\eightit=cmti8 + \font\eighttt=cmtt8 + \font\eightmi=cmmi8 + \font\eightsy=cmsy8 + \textfont0=\eightrm + \textfont1=\eightmi + \textfont2=\eightsy + \def\rm{\eightrm} + \def\bf{\eightbf} + \def\it{\eightit} + \def\tt{\eighttt} + \if 1\the\letterpaper + \normalbaselineskip=.8\normalbaselineskip + \else + \normalbaselineskip=.7\normalbaselineskip + \fi + \normallineskip=.8\normallineskip + \normallineskiplimit=.8\normallineskiplimit + \normalbaselines\rm %make definitions take effect + + \if 2\ncolumns + \let\maxcolumn=b + \footline{\hss\rm\folio\hss} + \def\makefootline{\vskip 2in \hsize=6.86in\line{\the\footline}} + \else \if 3\ncolumns + \let\maxcolumn=c + \nopagenumbers + \else + \errhelp{You must set \columnsperpage equal to 1, 2, or 3.} + \errmessage{Illegal number of columns per page} + \fi\fi + + \intercolumnskip=.46in + \def\abc{a} + \output={% %see The TeXbook page 257 + % This next line is useful when designing the layout. + %\immediate\write16{Column \folio\abc\space starts with \firstmark} + \if \maxcolumn\abc \multicolumnformat \global\def\abc{a} + \else\if a\abc + \global\setbox\columna\columnbox \global\def\abc{b} + %% in case we never use \columnb (two-column mode) + \global\setbox\columnb\hbox to -\intercolumnskip{} + \else + \global\setbox\columnb\columnbox \global\def\abc{c}\fi\fi} + \def\multicolumnformat{\shipout\vbox{\makeheadline + \hbox{\box\columna\hskip\intercolumnskip + \box\columnb\hskip\intercolumnskip\columnbox} + \makefootline}\advancepageno} + \def\columnbox{\leftline{\pagebody}} + + \def\bye{\par\vfill\supereject + \if a\abc \else\null\vfill\eject\fi + \if a\abc \else\null\vfill\eject\fi + \end} +\fi + +% we won't be using math mode much, so redefine some of the characters +% we might want to talk about +%\catcode`\^=12 +\catcode`\_=12 + +% we also need the tilde, for file names. +\catcode`\~=12 + +\chardef\\=`\\ +\chardef\{=`\{ +\chardef\}=`\} + +\hyphenation{mini-buf-fer} + +\parindent 0pt +\parskip 1ex plus .5ex minus .5ex + +\def\small{\smallfont\textfont2=\smallsy\baselineskip=.8\baselineskip} + +% newcolumn - force a new column. Use sparingly, probably only for +% the first column of a page, which should have a title anyway. +\outer\def\newcolumn{\vfill\eject} + +% title - page title. Argument is title text. +\outer\def\title#1{{\titlefont\centerline{#1}}\vskip 1ex plus .5ex} + +% section - new major section. Argument is section name. +\outer\def\section#1{\par\filbreak + \vskip 3ex plus 2ex minus 2ex {\headingfont #1}\mark{#1}% + \vskip 2ex plus 1ex minus 1.5ex} + +\newdimen\keyindent + +% beginindentedkeys...endindentedkeys - key definitions will be +% indented, but running text, typically used as headings to group +% definitions, will not. +\def\beginindentedkeys{\keyindent=1em} +\def\endindentedkeys{\keyindent=0em} +\endindentedkeys + +% paralign - begin paragraph containing an alignment. +% If an \halign is entered while in vertical mode, a parskip is never +% inserted. Using \paralign instead of \halign solves this problem. +\def\paralign{\vskip\parskip\halign} + +% \<...> - surrounds a variable name in a code example +\def\<#1>{{\it #1\/}} + +% kbd - argument is characters typed literally. Like the Texinfo command. +\def\kbd#1{{\tt#1}\null} %\null so not an abbrev even if period follows + +% beginexample...endexample - surrounds literal text, such a code example. +% typeset in a typewriter font with line breaks preserved +\def\beginexample{\par\leavevmode\begingroup + \obeylines\obeyspaces\parskip0pt\tt} +{\obeyspaces\global\let =\ } +\def\endexample{\endgroup} + +% key - definition of a key. +% \key{description of key}{key-name} +% prints the description left-justified, and the key-name in a \kbd +% form near the right margin. +\def\key#1#2{\leavevmode\hbox to \hsize{\vtop + {\hsize=.75\hsize\rightskip=1em + \hskip\keyindent\relax#1}\kbd{#2}\hfil}} + +\newbox\metaxbox +\setbox\metaxbox\hbox{\kbd{M-x }} +\newdimen\metaxwidth +\metaxwidth=\wd\metaxbox + +% metax - definition of a M-x command. +% \metax{description of command}{M-x command-name} +% Tries to justify the beginning of the command name at the same place +% as \key starts the key name. (The "M-x " sticks out to the left.) +\def\metax#1#2{\leavevmode\hbox to \hsize{\hbox to .75\hsize + {\hskip\keyindent\relax#1\hfil}% + \hskip -\metaxwidth minus 1fil + \kbd{#2}\hfil}} + +% threecol - like "key" but with two key names. +% for example, one for doing the action backward, and one for forward. +\def\threecol#1#2#3{\hskip\keyindent\relax#1\hfil&\kbd{#2}\hfil\quad + &\kbd{#3}\hfil\quad\cr} + +\def\noteone{{\small \hfill [1]}} +\def\notetwo{{\small \hfill [2]}} + + +%**end of header + + +\title{Org-Mode Reference Card (1/2)} + +\centerline{(for version \orgversionnumber)} + +\section{Getting Started} +\metax{To read the on-line documentation try}{M-x org-info} + +\section{Visibility Cycling} + +\key{rotate current subtree between states}{TAB} +\key{rotate entire buffer between states}{S-TAB} +\key{restore property-dependent startup visibility}{C-u C-u TAB} +\metax{show the whole file, including drawers}{C-u C-u C-u TAB} +\key{reveal context around point}{C-c C-r} + +\section{Motion} + +\key{next/previous heading}{C-c C-n/p} +\key{next/previous heading, same level}{C-c C-f/b} +\key{backward to higher level heading}{C-c C-u} +\key{jump to another place in document}{C-c C-j} +\key{previous/next plain list item}{S-UP/DOWN\notetwo} + +\section{Structure Editing} + +\key{insert new heading/item at current level}{M-RET} +\key{insert new heading after subtree}{C-RET} +\key{insert new TODO entry/checkbox item}{M-S-RET} +\key{insert TODO entry/ckbx after subtree}{C-S-RET} +\key{turn (head)line into item, cycle item type}{C-c -} +\key{turn item/line into headline}{C-c *} +\key{promote/demote heading}{M-LEFT/RIGHT} +\metax{promote/demote current subtree}{M-S-LEFT/RIGHT} +\metax{move subtree/list item up/down}{M-S-UP/DOWN} +\metax{sort subtree/region/plain-list}{C-c \^{}} +\metax{clone a subtree}{C-c C-x c} +\metax{kill/copy subtree}{C-c C-x C-w/M-w} +\metax{yank subtree}{C-c C-x C-y or C-y} +\metax{narrow buffer to subtree / widen}{C-x n s/w} + +\section{Capture - Refile - Archiving} +\key{capture a new item (C-u C-u = goto last)}{C-c c \noteone} +\key{refile subtree (C-u C-u = goto last)}{C-c C-w} +\key{archive subtree using the default command}{C-c C-x C-a} +\key{move subtree to archive file}{C-c C-x C-s} +\key{toggle ARCHIVE tag / to ARCHIVE sibling}{C-c C-x a/A} +\key{force cycling of an ARCHIVEd tree}{C-TAB} + +\section{Filtering and Sparse Trees} + +\key{construct a sparse tree by various criteria}{C-c /} +\key{view TODO's in sparse tree}{C-c / t/T} +\key{global TODO list in agenda mode}{C-c a t \noteone} +\key{time sorted view of current org file}{C-c a L} + +\section{Tables} + +{\bf Creating a table} + +%\metax{insert a new Org-mode table}{M-x org-table-create} +\metax{just start typing, e.g.}{|Name|Phone|Age RET |- TAB} +\key{convert region to table}{C-c |} +\key{... separator at least 3 spaces}{C-3 C-c |} + +{\bf Commands available inside tables} + +The following commands work when the cursor is {\it inside a table}. +Outside of tables, the same keys may have other functionality. + +{\bf Re-aligning and field motion} + +\key{re-align the table without moving the cursor}{C-c C-c} +\key{re-align the table, move to next field}{TAB} +\key{move to previous field}{S-TAB} +\key{re-align the table, move to next row}{RET} +\key{move to beginning/end of field}{M-a/e} + +{\bf Row and column editing} + +\key{move the current column left}{M-LEFT/RIGHT} +\key{kill the current column}{M-S-LEFT} +\key{insert new column to left of cursor position}{M-S-RIGHT} + +\key{move the current row up/down}{M-UP/DOWN} +\key{kill the current row or horizontal line}{M-S-UP} +\key{insert new row above the current row}{M-S-DOWN} +\key{insert hline below (\kbd{C-u} : above) current row}{C-c -} +\key{insert hline and move to line below it}{C-c RET} +\key{sort lines in region}{C-c \^{}} + +{\bf Regions} + +\metax{cut/copy/paste rectangular region}{C-c C-x C-w/M-w/C-y} +%\key{copy rectangular region}{C-c C-x M-w} +%\key{paste rectangular region}{C-c C-x C-y} +\key{fill paragraph across selected cells}{C-c C-q} + +{\bf Miscellaneous} + +\key{to limit column width to \kbd{N} characters, use}{...| <N> |...} +\key{edit the current field in a separate window}{C-c `} +\key{make current field fully visible}{C-u TAB} +\metax{export as tab-separated file}{M-x org-table-export} +\metax{import tab-separated file}{M-x org-table-import} +\key{sum numbers in current column/rectangle}{C-c +} + +{\bf Tables created with the \kbd{table.el} package} + +\key{insert a new \kbd{table.el} table}{C-c ~} +\key{recognize existing table.el table}{C-c C-c} +\key{convert table (Org-mode $\leftrightarrow$ table.el)}{C-c ~} + +{\bf Spreadsheet} + +Formulas typed in field are executed by \kbd{TAB}, +\kbd{RET} and \kbd{C-c C-c}. \kbd{=} introduces a column +formula, \kbd{:=} a field formula. + +\key{Example: Add Col1 and Col2}{|=\$1+\$2 |} +\key{... with printf format specification}{|=\$1+\$2;\%.2f|} +\key{... with constants from constants.el}{|=\$1/\$c/\$cm |} +\metax{sum from 2nd to 3rd hline}{|:=vsum(@II..@III)|} +\key{apply current column formula}{| = |} + +\key{set and eval column formula}{C-c =} +\key{set and eval field formula}{C-u C-c =} +\key{re-apply all stored equations to current line}{C-c *} +\key{re-apply all stored equations to entire table}{C-u C-c *} +\key{iterate table to stability}{C-u C-u C-c *} +\key{rotate calculation mark through \# * ! \^ \_ \$}{C-\#} +\key{show line, column, formula reference}{C-c ?} +\key{toggle grid / debugger}{C-c \}/\{} + +\newcolumn +{\it Formula Editor} + +\key{edit formulas in separate buffer}{C-c '} +\key{exit and install new formulas}{C-c C-c} +\key{exit, install, and apply new formulas}{C-u C-c C-c} +\key{abort}{C-c C-q} +\key{toggle reference style}{C-c C-r} +\key{pretty-print Lisp formula}{TAB} +\key{complete Lisp symbol}{M-TAB} +\key{shift reference point}{S-cursor} +\key{shift test line for column references}{M-up/down} +\key{scroll the window showing the table}{M-S-up/down} +\key{toggle table coordinate grid}{C-c \}} + +\section{Links} + +\key{globally store link to the current location}{C-c l \noteone} +\key{insert a link (TAB completes stored links)}{C-c C-l} +\key{insert file link with file name completion}{C-u C-c C-l} +\key{edit (also hidden part of) link at point}{C-c C-l} + +\key{open file links in emacs}{C-c C-o} +\key{...force open in emacs/other window}{C-u C-c C-o} +\key{open link at point}{mouse-1/2} +\key{...force open in emacs/other window}{mouse-3} +\key{record a position in mark ring}{C-c \%} +\key{jump back to last followed link(s)}{C-c \&} +\key{find next link}{C-c C-x C-n} +\key{find previous link}{C-c C-x C-p} +\key{edit code snippet of file at point}{C-c '} +\key{toggle inline display of linked images}{C-c C-x C-v} + +\section{Working with Code (Babel)} + +\key{execute code block at point}{C-c C-c} +\key{open results of code block at point}{C-c C-o} +\key{view expanded body of code block at point}{C-c C-v v} +\key{go to named code block}{C-c C-v g} +\key{go to named result}{C-c C-v r} +\key{go to the head of the current code block}{C-c C-v u} +\key{go to the next code block}{C-c C-v n} +\key{go to the previous code block}{C-c C-v p} +\key{demarcate a code block}{C-c C-v d} +\key{execute the next key sequence in the code edit buffer}{C-c C-v x} +\key{execute all code blocks in current buffer}{C-c C-v b} +\key{execute all code blocks in current subtree}{C-c C-v s} +\key{tangle code blocks in current file}{C-c C-v t} +\key{tangle code blocks in supplied file}{C-c C-v f} +\key{ingest all code blocks in supplied file into the Library of Babel}{C-c C-v i} +\key{switch to the session of the current code block}{C-c C-v z} +\key{load expanded body of the current code block into a session}{C-c C-v l} +\key{view sha1 hash of the current code block}{C-c C-v a} + +\section{Completion} + +In-buffer completion completes TODO keywords at headline start, TeX +macros after ``{\tt \\}'', option keywords after ``{\tt \#-}'', TAGS +after ``{\tt :}'', and dictionary words elsewhere. + +\key{complete word at point}{M-TAB} + + +\newcolumn +\title{Org-Mode Reference Card (2/2)} + +\centerline{(for version \orgversionnumber)} + +\section{TODO Items and Checkboxes} + +\key{rotate the state of the current item}{C-c C-t} +\metax{select next/previous state}{S-LEFT/RIGHT} +\metax{select next/previous set}{C-S-LEFT/RIGHT} +\key{toggle ORDERED property}{C-c C-x o} +\key{view TODO items in a sparse tree}{C-c C-v} +\key{view 3rd TODO keyword's sparse tree}{C-3 C-c C-v} + +\key{set the priority of the current item}{C-c , [ABC]} +\key{remove priority cookie from current item}{C-c , SPC} +\key{raise/lower priority of current item}{S-UP/DOWN\notetwo} + +\key{insert new checkbox item in plain list}{M-S-RET} +\key{toggle checkbox(es) in region/entry/at point}{C-c C-x C-b} +\key{toggle checkbox at point}{C-c C-c} +%\metax{checkbox statistics cookies: insert {\tt [/]} or {\tt [\%]}}{} +\key{update checkbox statistics (\kbd{C-u} : whole file)}{C-c \#} + +\section{Tags} + +\key{set tags for current heading}{C-c C-q} +\key{realign tags in all headings}{C-u C-c C-q} +\key{create sparse tree with matching tags}{C-c \\} +\key{globally (agenda) match tags at cursor}{C-c C-o} + +\section{Properties and Column View} + +\key{set property/effort}{C-c C-x p/e} +\key{special commands in property lines}{C-c C-c} +\key{next/previous allowed value}{S-left/right} +\key{turn on column view}{C-c C-x C-c} +\key{capture columns view in dynamic block}{C-c C-x i} + +\key{quit column view}{q} +\key{show full value}{v} +\key{edit value}{e} +\metax{next/previous allowed value}{n/p or S-left/right} +\key{edit allowed values list}{a} +\key{make column wider/narrower}{> / <} +\key{move column left/right}{M-left/right} +\key{add new column}{M-S-right} +\key{Delete current column}{M-S-left} + + +\section{Timestamps} + +\key{prompt for date and insert timestamp}{C-c .} +\key{like \kbd{C-c} . but insert date and time format}{C-u C-c .} +\key{like \kbd{C-c .} but make stamp inactive}{C-c !} % FIXME +\key{insert DEADLINE timestamp}{C-c C-d} +\key{insert SCHEDULED timestamp}{C-c C-s} +\key{create sparse tree with all deadlines due}{C-c / d} +\key{the time between 2 dates in a time range}{C-c C-y} +\metax{change timestamp at cursor $\pm 1$ day}{S-RIGHT/LEFT\notetwo} +\key{change year/month/day at cursor by $\pm 1$}{S-UP/DOWN\notetwo} +\key{access the calendar for the current date}{C-c >} +\key{insert timestamp matching date in calendar}{C-c <} +\key{access agenda for current date}{C-c C-o} +\key{select date while prompted}{mouse-1/RET} +%\key{... select date in calendar}{mouse-1/RET} +%\key{... scroll calendar back/forward one month}{< / >} +%\key{... forward/backward one day}{S-LEFT/RIGHT} +%\key{... forward/backward one week}{S-UP/DOWN} +%\key{... forward/backward one month}{M-S-LEFT/RIGHT} +\key{toggle custom format display for dates/times}{C-c C-x C-t} + +\newcolumn + +{\bf Clocking time} + +\key{start clock on current item}{C-c C-x C-i} +\key{stop/cancel clock on current item}{C-c C-x C-o/x} +\key{display total subtree times}{C-c C-x C-d} +\key{remove displayed times}{C-c C-c} +\key{insert/update table with clock report}{C-c C-x C-r} + +\section{Agenda Views} + +\key{add/move current file to front of agenda}{C-c [} +\key{remove current file from your agenda}{C-c ]} +\key{cycle through agenda file list}{C-'} +\key{set/remove restriction lock}{C-c C-x </>} + +\key{compile agenda for the current week}{C-c a a \noteone} +\key{compile global TODO list}{C-c a t \noteone} +\key{compile TODO list for specific keyword}{C-c a T \noteone} +\key{match tags, TODO kwds, properties}{C-c a m \noteone} +\key{match only in TODO entries}{C-c a M \noteone} +\key{find stuck projects}{C-c a \# \noteone} +\key{show timeline of current org file}{C-c a L \noteone} +\key{configure custom commands}{C-c a C \noteone} +%\key{configure stuck projects}{C-c a ! \noteone} +\key{agenda for date at cursor}{C-c C-o} + +{\bf Commands available in an agenda buffer} + +{\bf View Org file} + +\key{show original location of item}{SPC/mouse-3} +%\key{... also available with}{mouse-3} +\key{show and recenter window}{L} +\key{goto original location in other window}{TAB/mouse-2} +%\key{... also available with}{mouse-2} +\key{goto original location, delete other windows}{RET} +\key{show subtree in indirect buffer, ded.\ frame}{C-c C-x b} +\key{toggle follow-mode}{F} + +{\bf Change display} + +\key{delete other windows}{o} +\key{view mode dispatcher}{v} +\key{switch to day/week/month/year view}{d w vm vy} +\key{toggle diary entries / time grid / habits}{D / G / K} +\key{toggle entry text / clock report}{E / R} +\key{toggle display of logbook entries}{l / v l/L} +\key{toggle inclusion of archived trees/files}{v a/A} +\key{refresh agenda buffer with any changes}{r / g} +\key{filter with respect to a tag}{/} +\key{save all org-mode buffers}{s} +\key{display next/previous day,week,...}{f / b} +\key{goto today / some date (prompt)}{. / j} + +{\bf Remote editing} + +\key{digit argument}{0-9} +\key{change state of current TODO item}{t} +\key{kill item and source}{C-k} +\key{archive default}{\$ / a} +\key{refile the subtree}{C-c C-w} +\key{set/show tags of current headline}{: / T} +\key{set effort property (prefix=nth)}{e} +\key{set / compute priority of current item}{, / P} +\key{raise/lower priority of current item}{S-UP/DOWN\notetwo} +\key{run an attachment command}{C-c C-a} +\key{schedule/set deadline for this item}{C-c C-s/d} +\metax{change timestamp one day earlier/later}{S-LEFT/RIGHT\notetwo} +\key{change timestamp to today}{>} +\key{insert new entry into diary}{i} +\newcolumn +\key{start/stop/cancel the clock on current item}{I / O / X} +\key{jump to running clock entry}{J} +\key{mark / unmark / execute bulk action}{m / u / B} + +{\bf Misc} + +\key{follow one or offer all links in current entry}{C-c C-o} + +{\bf Calendar commands} + +\key{find agenda cursor date in calendar}{c} +\key{compute agenda for calendar cursor date}{c} +\key{show phases of the moon}{M} +\key{show sunrise/sunset times}{S} +\key{show holidays}{H} +\key{convert date to other calendars}{C} + +{\bf Quit and Exit} + +\key{quit agenda, remove agenda buffer}{q} +\key{exit agenda, remove all agenda buffers}{x} + +\section{LaTeX and cdlatex-mode} + +\key{preview LaTeX fragment}{C-c C-x C-l} +\key{expand abbreviation (cdlatex-mode)}{TAB} +\key{insert/modify math symbol (cdlatex-mode)}{` / '} +\key{insert citation using RefTeX}{C-c C-x [} + +\section{Exporting and Publishing} + +Exporting creates files with extensions {\it .txt\/} and {\it .html\/} +in the current directory. Publishing puts the resulting file into +some other place. + +\key{export/publish dispatcher}{C-c C-e} + +\key{export visible part only}{C-c C-e v} +\key{insert template of export options}{C-c C-e t} +\key{toggle fixed width for entry or region}{C-c :} +\key{toggle pretty display of scripts, entities}{C-c C-x {\tt\char`\\}} + +{\bf Comments: Text not being exported} + +Lines starting with \kbd{\#} and subtrees starting with COMMENT are +never exported. + +\key{toggle COMMENT keyword on entry}{C-c ;} + +\section{Dynamic Blocks} + +\key{update dynamic block at point}{C-c C-x C-u} +\metax{update all dynamic blocks}{C-u C-c C-x C-u} + +\section{Notes} +[1] This is only a suggestion for a binding of this command. Choose +your own key as shown under INSTALLATION. + +[2] Keybinding affected by {\tt org-support-shift-select} and also + {\tt org-replace-disputed-keys}. + +\copyrightnotice + +\bye + +% Local variables: +% compile-command: "tex refcard" +% End: + +% arch-tag: 139f6750-5cfc-49ca-92b5-237fe5795290 diff --git a/.emacs.d/org-7.4/doc/orgcard_letter.pdf b/.emacs.d/org-7.4/doc/orgcard_letter.pdf Binary files differnew file mode 100644 index 0000000..91182ac --- /dev/null +++ b/.emacs.d/org-7.4/doc/orgcard_letter.pdf diff --git a/.emacs.d/org-7.4/doc/orgguide.pdf b/.emacs.d/org-7.4/doc/orgguide.pdf Binary files differnew file mode 100644 index 0000000..2b3a0dc --- /dev/null +++ b/.emacs.d/org-7.4/doc/orgguide.pdf diff --git a/.emacs.d/org-7.4/doc/orgguide.texi b/.emacs.d/org-7.4/doc/orgguide.texi new file mode 100644 index 0000000..992ba80 --- /dev/null +++ b/.emacs.d/org-7.4/doc/orgguide.texi @@ -0,0 +1,2699 @@ +\input texinfo +@c %**start of header +@setfilename ../../info/orgguide +@settitle The compact Org-mode Guide + +@set VERSION 7.4 +@set DATE December 2010 + +@c Use proper quote and backtick for code sections in PDF output +@c Cf. Texinfo manual 14.2 +@set txicodequoteundirected +@set txicodequotebacktick + +@c Version and Contact Info +@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} +@set AUTHOR Carsten Dominik +@set MAINTAINER Carsten Dominik +@set MAINTAINEREMAIL @email{carsten at orgmode dot org} +@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer} +@c %**end of header +@finalout + +@c Macro definitions +@iftex +@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed} +@end iftex +@macro Ie {} +I.e., +@end macro +@macro ie {} +i.e., +@end macro +@macro Eg {} +E.g., +@end macro +@macro eg {} +e.g., +@end macro + +@c Subheadings inside a table. +@macro tsubheading{text} +@ifinfo +@subsubheading \text\ +@end ifinfo +@ifnotinfo +@item @b{\text\} +@end ifnotinfo +@end macro + +@macro seealso{text} +@noindent @b{Further reading}@*@noindent \text\ +@end macro +@copying + +Copyright @copyright{} 2010 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.3 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 the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Org Mode Guide: (orgguide). Abbreviated Org-mode Manual +@end direntry + +@titlepage +@title The compact Org-mode Guide + +@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. +@shortcontents + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Org Mode Guide + +@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:: Properties +* Dates and Times:: Making items useful for planning +* Capture - Refile - Archive:: The ins and outs for projects +* Agenda Views:: Collecting information into views +* Markup:: Prepare text for rich export +* Exporting:: Sharing and publishing of notes +* Publishing:: Create a web site of linked Org files +* Working With Source Code:: Source code snippets embedded in Org +* Miscellaneous:: All the rest which did not fit elsewhere + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* Preface:: Welcome +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. + +Document Structure + +* Outlines:: Org 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 +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Footnotes:: How footnotes are defined in Org's syntax + +Hyperlinks + +* Link format:: How links in Org 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 +* Targeted links:: Point at a location in a file + +TODO Items + +* Using TODO states:: Setting and switching states +* Multi-state workflows:: More than just on/off +* Progress logging:: Dates and notes for progress +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists + +Progress logging + +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? + +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 + +Dates and Times + +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task + +Capture - Refile - Archive + +* Capture:: +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects + +Capture + +* Setting up a capture location:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types + +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? +* 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 +* Search view:: Find entries by searching for text + +Markup for rich export + +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Embedded LaTeX:: LaTeX can be freely used inside Org documents + +Structural markup elements + +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Paragraphs:: Paragraphs +* Emphasis and monospace:: Bold, italic, etc. +* Comment lines:: What will *not* be exported + +Exporting + +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* iCalendar export:: + +Miscellaneous + +* Completion:: M-TAB knows what you need +* Clean view:: Getting rid of leading stars in the outline +* MobileOrg:: Org-mode on the iPhone + +@end detailmenu +@end menu + +@node Introduction, Document Structure, Top, Top +@chapter Introduction + +@menu +* Preface:: Welcome +* Installation:: How to install a downloaded version of Org +* Activation:: How to activate Org for certain buffers +* Feedback:: Bug reports, ideas, patches etc. +@end menu + +@node Preface, Installation, Introduction, Introduction +@section Preface + +Org is a mode for keeping notes, maintaining TODO lists, and doing project +planning with a fast and effective plain-text system. It is also an +authoring and publishing system. + +@i{This document is a much compressed derivative of the +@uref{http://orgmode.org/index.html#sec-4_1, comprehensive Org-mode manual}. +It contains all basic features and commands, along with important hints for +customization. It is intended for beginners who would shy back from a 200 +page manual because of sheer size.} + +@node Installation, Activation, Preface, Introduction +@section Installation + +@b{Important:} @i{If you are using a version of Org that 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 from the Web, either as a distribution @file{.zip} +or @file{.tar} file, or as a Git archive, it is best to run it directly from +the distribution directory. You need to add the @file{lisp} subdirectories +to the Emacs load path. To do this, add the following line to @file{.emacs}: + +@smallexample +(setq load-path (cons "~/path/to/orgdir/lisp" load-path)) +(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) +@end smallexample + +@noindent For speed you should byte-compile the Lisp files with the shell +command: + +@smallexample +make +@end smallexample + +Then add the following line to @file{.emacs}. It is needed so that +Emacs can autoload functions that are located in files not immediately loaded +when Org-mode starts. +@smalllisp +(require 'org-install) +@end smalllisp + +@node Activation, Feedback, Installation, Introduction +@section Activation + +Add the following lines to your @file{.emacs} file. The last three lines +define @emph{global} keys for some commands --- please choose suitable keys +yourself. + +@smalllisp +;; The following lines are always needed. Choose your own keys. +(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) +(add-hook 'org-mode-hook 'turn-on-font-lock) ; not needed when global-font-lock-mode is on +(global-set-key "\C-cl" 'org-store-link) +(global-set-key "\C-ca" 'org-agenda) +(global-set-key "\C-cb" 'org-iswitchb) +@end smalllisp + +With this setup, all files with extension @samp{.org} will be put +into Org mode. + +@node Feedback, , Activation, Introduction +@section Feedback + +If you find problems with Org, or if you have questions, remarks, or ideas +about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}. +For information on how to submit bug reports, see the main manual. + +@node Document Structure, Tables, Introduction, Top +@chapter Document Structure + +Org is based on Outline mode and provides flexible commands to +edit the structure of the document. + +@menu +* Outlines:: Org 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 +* Sparse trees:: Matches embedded in context +* Plain lists:: Additional structure within an entry +* Footnotes:: How footnotes are defined in Org's syntax +@end menu + +@node Outlines, Headlines, Document Structure, Document Structure +@section Outlines + +Org 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 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 + +Headlines define the structure of an outline tree. The headlines in +Org 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: + +@smallexample +* Top level headline +** Second level +*** 3rd level + some text +*** 3rd level + more text + +* Another top level headline +@end smallexample + +@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. + +@node Visibility cycling, Motion, Headlines, Document Structure +@section Visibility cycling + +Outlines make it possible to hide parts of the text in the buffer. +Org uses just two commands, bound to @key{TAB} and +@kbd{S-@key{TAB}} to change the visibility in the buffer. + +@table @kbd +@item @key{TAB} +@emph{Subtree cycling}: Rotate current subtree among the states + +@smallexample +,-> FOLDED -> CHILDREN -> SUBTREE --. +'-----------------------------------' +@end smallexample + +When called with a prefix argument (@kbd{C-u @key{TAB}}) or with the shift +key, global cycling is invoked. + +@item S-@key{TAB} @r{and} C-u @key{TAB} +@emph{Global cycling}: Rotate the entire buffer among the states + +@smallexample +,-> OVERVIEW -> CONTENTS -> SHOW ALL --. +'--------------------------------------' +@end smallexample + +@item C-u C-u C-u @key{TAB} +Show all, including drawers. +@end table + +When Emacs first visits an Org 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 a startup keyword @code{overview}, @code{content}, +@code{showall}, like this: + +@smallexample +#+STARTUP: content +@end smallexample + + +@node Motion, Structure editing, Visibility cycling, Document Structure +@section Motion +The following commands jump to other headlines in the buffer. + +@table @kbd +@item C-c C-n +Next heading. +@item C-c C-p +Previous heading. +@item C-c C-f +Next heading same level. +@item C-c C-b +Previous heading same level. +@item C-c C-u +Backward to higher level heading. +@end table + +@node Structure editing, Sparse trees, Motion, Document Structure +@section Structure editing + +@table @kbd +@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}). 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@footnote{If you do not want the line to be split, +customize the variable @code{org-M-RET-may-split-line}.}. +@item M-S-@key{RET} +Insert new TODO entry with same level as current heading. +@item @key{TAB} @r{in new, empty entry} +In a new entry with no text yet, @key{TAB} will cycle through reasonable +levels. +@item M-@key{left}@r{/}@key{right} +Promote/demote current heading by one level. +@item M-S-@key{left}@r{/}@key{right} +Promote/demote the current subtree by one level. +@item M-S-@key{up}@r{/}@key{down} +Move subtree up/down (swap with previous/next subtree of same +level). +@item C-c C-w +Refile entry or region to a different location. @xref{Refiling notes}. +@item C-x n s/w +Narrow buffer to current subtree / widen it again +@end table + +When there is an active region (Transient Mark mode), promotion and +demotion work on all headlines in the region. + +@node Sparse trees, Plain lists, Structure editing, Document Structure +@section Sparse trees + +An important feature of Org mode is the ability to construct @emph{sparse +trees} for selected information in an outline tree, so 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}, +@code{org-show-siblings}, and @code{org-show-entry-below} 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, all these +commands can be accessed through a dispatcher: + +@table @kbd +@item C-c / +This prompts for an extra key to select a sparse-tree creating command. +@item C-c / r +Occur. Prompts for a regexp and shows a sparse tree with all matches. Each +match is also highlighted; the highlights disappear by pressing @kbd{C-c C-c}. +@end table + +The other sparse tree commands select headings based on TODO keywords, +tags, or properties and will be discussed later in this manual. + +@node Plain lists, Footnotes, Sparse trees, Document Structure +@section Plain 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 supports editing such lists, +and the HTML exporter (@pxref{Exporting}) parses and formats them. + +Org knows ordered lists, unordered lists, and description lists. +@itemize @bullet +@item +@emph{Unordered} list items start with @samp{-}, @samp{+}, or +@samp{*} as bullets. +@item +@emph{Ordered} list items start with @samp{1.} or @samp{1)}. +@item +@emph{Description} list use @samp{ :: } to separate the @emph{term} from the +description. +@end itemize + +Items belonging to the same list must have the same indentation on the first +line. A list ends before the next line that is indented like the +bullet/number, or less. It also ends before two blank lines. An example: + +@smallexample +@group +** Lord of the Rings + My favorite scenes are (in this order) + 1. The attack of the Rohirrim + 2. Eowyn's fight with the witch king + + this was already my favorite scene in the book + + I really like Miranda Otto. + Important actors in this film are: + - @b{Elijah Wood} :: He plays Frodo + - @b{Sean Austin} :: He plays Sam, Frodo's friend. +@end group +@end smallexample + +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 +@item @key{TAB} +Items can be folded just like headline levels. +@item M-@key{RET} +Insert new item at current level. With a prefix argument, force a new +heading (@pxref{Structure editing}). +@item M-S-@key{RET} +Insert a new item with a checkbox (@pxref{Checkboxes}). +@item M-S-@key{up}@r{/}@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. +@item M-@key{left}@r{/}M-@key{right} +Decrease/increase the indentation of an item, leaving children alone. +@item M-S-@key{left}@r{/}@key{right} +Decrease/increase the indentation of the item, including subitems. +@item C-c C-c +If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the +state of the checkbox. Also make sure all items have the same bullet type +and renumber ordered lists. +@item C-c - +Cycle the entire list level through the different itemize/enumerate bullets +(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). +@end table + +@node Footnotes, , Plain lists, Document Structure +@section Footnotes + +A footnote is defined in a paragraph that is started by a footnote marker in +square brackets in column 0, no indentation allowed. The footnote reference +is simply the marker in square brackets, inside text. For example: + +@smallexample +The Org homepage[fn:1] now looks a lot better than it used to. +... +[fn:1] The link is: http://orgmode.org +@end smallexample + +@noindent The following commands handle footnotes: + +@table @kbd +@item C-c C-x f +The footnote action command. When the cursor is on a footnote reference, +jump to the definition. When it is at a definition, jump to the (first) +reference. Otherwise, create a new footnote. When this command is called +with a prefix argument, a menu of additional options including renumbering is +offered. + +@item C-c C-c +Jump between definition and reference. +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Document-Structure.html#Document-Structure, +Chapter 2 of the manual}@* +@uref{http://sachachua.com/wp/2008/01/outlining-your-notes-with-org/, +Sacha Chua's tutorial}} + + +@node Tables, Hyperlinks, Document Structure, Top +@chapter Tables + +Org comes with a fast and intuitive table editor. Spreadsheet-like +calculations are supported in connection with the Emacs @file{calc} +package +@ifinfo +(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}). +@end ifinfo +@ifnotinfo +(see the Emacs Calculator manual for more information about the Emacs +calculator). +@end ifnotinfo + +Org 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: + +@smallexample +| Name | Phone | Age | +|-------+-------+-----| +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +@end smallexample + +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 + +@smallexample +|Name|Phone|Age| +|- +@end smallexample + +@noindent and then press @key{TAB} to align the table and start filling in +fields. Even faster would be to type @code{|Name|Phone|Age} followed by +@kbd{C-c @key{RET}}. + +When typing text into a field, Org 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. + +@table @kbd +@tsubheading{Creation and conversion} +@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 every line contains a comma, comma-separated values (CSV) are assumed. +If not, lines are split at whitespace into fields. +@* +If there is no active region, this command creates an empty Org +table. But it's easier just to start typing, like +@kbd{|Name|Phone|Age C-c @key{RET}}. + +@tsubheading{Re-aligning and field motion} +@item C-c C-c +Re-align the table without moving the cursor. +@c +@item @key{TAB} +Re-align the table, move to the next field. Creates a new row if +necessary. +@c +@item S-@key{TAB} +Re-align, move to previous field. +@c +@item @key{RET} +Re-align the table and move down to next row. Creates a new row if +necessary. + +@tsubheading{Column and row editing} +@item M-@key{left} +@itemx M-@key{right} +Move the current column left/right. +@c +@item M-S-@key{left} +Kill the current column. +@c +@item M-S-@key{right} +Insert a new column to the left of the cursor position. +@c +@item M-@key{up} +@itemx M-@key{down} +Move the current row up/down. +@c +@item M-S-@key{up} +Kill the current row or horizontal line. +@c +@item M-S-@key{down} +Insert a new row above the current row. With a prefix argument, the line is +created below the current one. +@c +@item C-c - +Insert a horizontal line below current row. With a prefix argument, the line +is created above the current line. +@c +@item C-c @key{RET} +Insert a horizontal line below current row, and move the cursor into the row +below that line. +@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. + +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Tables.html#Tables, Chapter 3 of the +manual}@* +@uref{http://orgmode.org/worg/org-tutorials/tables.php, Bastien's +table tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-spreadsheet-intro.php, +Bastien's spreadsheet tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-plot.php, Eric's plotting tutorial}} + +@node Hyperlinks, TODO Items, Tables, Top +@chapter Hyperlinks + +Like HTML, Org provides links inside a file, external links to +other files, Usenet articles, emails, and much more. + +@menu +* Link format:: How links in Org 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 +* Targeted links:: Point at a location in a file +@end menu + +@node Link format, Internal links, Hyperlinks, Hyperlinks +@section Link format + +Org will recognize plain URL-like links and activate them as +clickable links. The general link format, however, looks like this: + +@smallexample +[[link][description]] @r{or alternatively} [[link]] +@end smallexample + +@noindent +Once a link in the buffer is complete (all brackets present), Org will change +the display so that @samp{description} is displayed instead of +@samp{[[link][description]]} and @samp{link} is displayed instead of +@samp{[[link]]}. To edit the invisible @samp{link} part, use @kbd{C-c +C-l} with the cursor on the link. + +@node Internal links, External links, Link format, Hyperlinks +@section Internal links + +If the link does not look like a URL, it is considered to be internal in the +current file. The most important case is a link like +@samp{[[#my-custom-id]]} which will link to the entry with the +@code{CUSTOM_ID} property @samp{my-custom-id}. + +Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]} +lead to a text search in the current file for the corresponding target which +looks like @samp{<<My Target>>}. + +@node External links, Handling links, Internal links, Hyperlinks +@section External links + +Org supports links to files, websites, Usenet and email messages, +BBDB database entries and links to both IRC conversations and their +logs. 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. Here are some examples: + +@smallexample +http://www.astro.uva.nl/~dominik @r{on the web} +file:/home/dominik/images/jupiter.jpg @r{file, absolute path} +/home/dominik/images/jupiter.jpg @r{same as above} +file:papers/last.pdf @r{file, relative path} +file:projects.org @r{another Org file} +docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN} +id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} +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} +wl:folder#id @r{WANDERLUST message link} +mhe:folder#id @r{MH-E message link} +rmail:folder#id @r{RMAIL message link} +gnus:group#id @r{Gnus article link} +bbdb:R.*Stallman @r{BBDB link (with regexp)} +irc:/irc.com/#emacs/bob @r{IRC link} +info:org:External%20links @r{Info node link (with encoded space)} +@end smallexample + +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: + +@smallexample +[[http://www.gnu.org/software/emacs/][GNU Emacs]] +@end smallexample + +@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. + +@node Handling links, Targeted links, External links, Hyperlinks +@section Handling links + +Org provides methods to create a link in the correct syntax, to +insert it into an Org file, and to follow the link. + +@table @kbd +@item C-c l +Store a link to the current location. This is a @emph{global} command (you +must create the key binding yourself) which can be used in any buffer to +create a link. The link will be stored for later insertion into an Org +buffer (see below). +@c +@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, or use history keys @key{up} and @key{down} to access +stored links. You will be prompted for the description part of the link. +When called with a @kbd{C-u} prefix argument, file name completion is used to +link to a file. +@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 +@item C-c C-o @r{or} mouse-1 @r{or} mouse-2 +Open link at point. +@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 +@end table + +@node Targeted links, , Handling links, Hyperlinks +@section Targeted links + +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 colon. + +Here is the syntax of the different ways to attach a search to a file +link, together with an explanation: + +@smallexample +[[file:~/code/main.c::255]] @r{Find line 255} +[[file:~/xx.org::My Target]] @r{Find @samp{<<My Target>>}} +[[file:~/xx.org::#my-custom-id]] @r{Find entry with custom id} +@end smallexample + +@seealso{ +@uref{http://orgmode.org/manual/Hyperlinks.html#Hyperlinks, Chapter 4 of the +manual}} + +@node TODO Items, Tags, Hyperlinks, Top +@chapter TODO Items + +Org mode does not maintain TODO lists as separate documents@footnote{Of +course, you can make a document that contains only long lists of TODO items, +but this is not required.}. Instead, TODO items are an integral part of the +notes file, because TODO items usually come up while taking notes! With Org +mode, simply mark any entry in a tree as being a TODO item. In this way, +information is not duplicated, and the entire context from which the TODO +item emerged is always present. + +Of course, this technique for managing TODO items scatters them +throughout your notes file. Org mode compensates for this by providing +methods to give you an overview of all the things that you have to do. + +@menu +* Using TODO states:: Setting and switching states +* Multi-state workflows:: More than just on/off +* Progress logging:: Dates and notes for progress +* Priorities:: Some things are more important than others +* Breaking down tasks:: Splitting a task into manageable pieces +* Checkboxes:: Tick-off lists +@end menu + +@node Using TODO states, Multi-state workflows, TODO Items, TODO Items +@section Using TODO states + +Any headline becomes a TODO item when it starts with the word +@samp{TODO}, for example: + +@smallexample +*** TODO Write letter to Sam Fortune +@end smallexample + +@noindent +The most important commands to work with TODO entries are: + +@table @kbd +@item C-c C-t +Rotate the TODO state of the current item among + +@smallexample +,-> (unmarked) -> TODO -> DONE --. +'--------------------------------' +@end smallexample + +The same rotation can also be done ``remotely'' from the timeline and +agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). + +@item S-@key{right}@r{/}@key{left} +Select the following/preceding TODO state, similar to cycling. +@item C-c / t +View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the +buffer, but shows all TODO items and the headings hierarchy above +them. +@item C-c a t +Show the global TODO list. Collects the TODO items from all agenda files +(@pxref{Agenda Views}) into a single buffer. @xref{Global TODO list}, for +more information. +@item S-M-@key{RET} +Insert a new TODO entry below the current one. +@end table + +@noindent +Changing a TODO state can also trigger tag changes. See the docstring of the +option @code{org-todo-state-tags-triggers} for details. + +@node Multi-state workflows, Progress logging, Using TODO states, TODO Items +@section Multi-state workflows + +You can use TODO keywords to indicate different @emph{sequential} states +in the process of working on an item, for example: + +@smalllisp +(setq org-todo-keywords + '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) +@end smalllisp + +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. +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. + +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: + +@smalllisp +(setq org-todo-keywords + '((sequence "TODO(t)" "|" "DONE(d)") + (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") + (sequence "|" "CANCELED(c)"))) +@end smalllisp + +The keywords should all be different, this helps Org mode to keep track of +which subsequence should be used for a given entry. The example also shows +how to define keys for fast access of a particular state, by adding a letter +in parenthesis after each keyword - you will be prompted for the key after +@kbd{C-c C-t}. + +To define TODO keywords that are valid only in a single file, use the +following text anywhere in the file. + +@smallexample +#+TODO: TODO(t) | DONE(d) +#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) +#+TODO: | CANCELED(c) +@end smallexample + +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. + +@node Progress logging, Priorities, Multi-state workflows, TODO Items +@section Progress logging + +Org mode can automatically record a timestamp and possibly a note when +you mark a TODO item as DONE, or even each time you change the state of +a TODO item. This system is highly configurable, settings can be on a +per-keyword basis and can be localized to a file or even a subtree. For +information on how to clock working time for a task, see @ref{Clocking +work time}. + +@menu +* Closing items:: When was this entry marked DONE? +* Tracking TODO state changes:: When did the status change? +@end menu + +@node Closing items, Tracking TODO state changes, Progress logging, Progress logging +@unnumberedsubsec Closing items + +The most basic logging is to keep track of @emph{when} a certain TODO +item was finished. This is achieved with@footnote{The corresponding +in-buffer setting is: @code{#+STARTUP: logdone}}. + +@smalllisp +(setq org-log-done 'time) +@end smalllisp + +@noindent +Then each time you turn an entry from a TODO (not-done) state into any of the +DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after +the headline. If you want to record a note along with the timestamp, +use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP: +lognotedone}} + +@smalllisp +(setq org-log-done 'note) +@end smalllisp + +@noindent +You will then be prompted for a note, and that note will be stored below +the entry with a @samp{Closing Note} heading. + +@node Tracking TODO state changes, , Closing items, Progress logging +@unnumberedsubsec Tracking TODO state changes + +You might want to keep track of TODO state changes. You can either record +just a timestamp, or a time-stamped note for a change. These records will be +inserted after the headline as an itemized list. When taking a lot of notes, +you might want to get the notes out of the way into a drawer. Customize the +variable @code{org-log-into-drawer} to get this behavior. + +For state logging, Org mode expects configuration on a per-keyword basis. +This is achieved by adding special markers @samp{!} (for a timestamp) and +@samp{@@} (for a note) in parentheses after each keyword. For example: +@smallexample +#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) +@end smallexample +@noindent +will define TODO keywords and fast access keys, and also request that a time +is recorded when the entry is set to DONE, and that a note is recorded when +switching to WAIT or CANCELED. The same syntax works also when setting +@code{org-todo-keywords}. + +@node Priorities, Breaking down tasks, Progress logging, TODO Items +@section Priorities + +If you use Org mode extensively, you may end up with enough TODO items that +it starts to make sense to prioritize them. Prioritizing can be done by +placing a @emph{priority cookie} into the headline of a TODO item, like this + +@smallexample +*** TODO [#A] Write letter to Sam Fortune +@end smallexample + +@noindent +Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}. +@samp{A} is the highest, @samp{B} the default if none is given. Priorities +make a difference only in the agenda. + +@table @kbd +@item @kbd{C-c ,} +Set the priority of the current headline. Press @samp{A}, @samp{B} or +@samp{C} to select a priority, or @key{SPC} to remove the cookie. +@c +@item S-@key{up} +@itemx S-@key{down} +Increase/decrease priority of current headline +@end table + +@node Breaking down tasks, Checkboxes, Priorities, TODO Items +@section Breaking tasks down into subtasks + +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. To keep the overview over the fraction +of subtasks that are already completed, insert either @samp{[/]} or +@samp{[%]} anywhere in the headline. These cookies will be updated each time +the TODO status of a child changes, or when pressing @kbd{C-c C-c} on the +cookie. For example: + +@smallexample +* Organize Party [33%] +** TODO Call people [1/2] +*** TODO Peter +*** DONE Sarah +** TODO Buy food +** DONE Talk to neighbor +@end smallexample + +@node Checkboxes, , Breaking down tasks, TODO Items +@section Checkboxes + +Every item in a plain list (@pxref{Plain lists}) can be made into a checkbox +by starting it with the string @samp{[ ]}. Checkboxes are not included into +the global TODO list, so they are often great to split a task into a number +of simple steps. +Here is an example of a checkbox list. + +@smallexample +* TODO Organize party [1/3] + - [-] call people [1/2] + - [ ] Peter + - [X] Sarah + - [X] order food + - [ ] think about what music to play +@end smallexample + +Checkboxes work hierarchically, so if a checkbox item has children that +are checkboxes, toggling one of the children checkboxes will make the +parent checkbox reflect if none, some, or all of the children are +checked. + +@noindent The following commands work with checkboxes: + +@table @kbd +@item C-c C-c +Toggle checkbox status or (with prefix arg) checkbox presence at point. +@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}). +@end table + +@seealso{ +@uref{http://orgmode.org/manual/TODO-Items.html#TODO-Items, Chapter 5 of the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/orgtutorial_dto.php, David +O'Toole's introductory tutorial}@* +@uref{http://members.optusnet.com.au/~charles57/GTD/gtd_workflow.html, +Charles Cave's GTD setup}} + +@node Tags, Properties, TODO Items, Top +@chapter Tags + +An excellent way to implement labels and contexts for cross-correlating +information is to assign @i{tags} to headlines. Org mode has extensive +support for tags. + +Every headline can contain a list of tags; they occur 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, e.g., +@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. +Tags will by default be in bold face with the same color as the headline. + +@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 + +@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 + +@smallexample +* Meeting with the French group :work: +** Summary by Frank :boss:notes: +*** TODO Prepare slides for him :action: +@end smallexample + +@noindent +the final heading will have the tags @samp{:work:}, @samp{:boss:}, +@samp{:notes:}, and @samp{:action:} even though the final heading is not +explicitly marked with those tags. You can also set tags that all entries in +a file should inherit just as if these tags were defined in a hypothetical +level zero that surrounds the entire file. Use a line like this@footnote{As +with all these in-buffer settings, pressing @kbd{C-c C-c} activates any +changes in the line.}: + +@smallexample +#+FILETAGS: :Peter:Boss:Secret: +@end smallexample + +@node Setting tags, Tag searches, Tag inheritance, Tags +@section Setting tags + +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 +@item C-c C-q +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. +@item C-c C-c +When the cursor is in a headline, this does the same as @kbd{C-c C-q}. +@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 + +@smallexample +#+TAGS: @@work @@home @@tennisclub +#+TAGS: laptop car pc sailboat +@end smallexample + +By default Org mode uses the standard minibuffer completion facilities for +entering tags. However, it also implements another, quicker, tag selection +method called @emph{fast tag selection}. This allows you to select and +deselect tags with just a single key press. For this to work well you should +assign unique letters to most of your commonly used tags. You can do this +globally by configuring the variable @code{org-tag-alist} in your +@file{.emacs} file. For example, you may find the need to tag many items in +different files with @samp{:@@home:}. In this case you can set something +like: + +@smalllisp +(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) +@end smalllisp + +@noindent If the tag is only relevant to the file you are working on, then you +can instead set the TAGS option line as: + +@smallexample +#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) +@end smallexample + +@node Tag searches, , Setting tags, Tags +@section Tag searches + +Once a system of tags has been set up, it can be used to collect related +information into special lists. + +@table @kbd +@item C-c \ +@itemx C-c / m +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. +@item C-c a m +Create a global list of tag matches from all agenda files. +@xref{Matching tags and properties}. +@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 + +These commands all prompt for a match string which allows basic Boolean logic +like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and +@samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries +which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the +search string is rich and allows also matching against TODO keywords, entry +levels and properties. For a complete description with many examples, see +@ref{Matching tags and properties}. + +@seealso{ +@uref{http://orgmode.org/manual/Tags.html#Tags, Chapter 6 of the manual}@* +@uref{http://sachachua.com/wp/2008/01/tagging-in-org-plus-bonus-code-for-timeclocks-and-tags/, +Sacha Chua's article about tagging in Org-mode}} + +@node Properties, Dates and Times, Tags, Top +@chapter Properties + +Properties are key-value pairs associates with and entry. They live in a +special drawer 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: + +@smallexample +* CD collection +** Classic +*** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Publisher: Deutsche Grammophon + :NDisks: 1 + :END: +@end smallexample + +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: + +@smallexample +* CD collection + :PROPERTIES: + :NDisks_ALL: 1 2 3 4 + :Publisher_ALL: "Deutsche Grammophon" Philips EMI + :END: +@end smallexample +or globally using @code{org-global-properties}, or file-wide like this: +@smallexample +#+PROPERTY: NDisks_ALL 1 2 3 4 +@end smallexample + +@table @kbd +@item C-c C-x p +Set a property. This prompts for a property name and a value. +@item C-c C-c d +Remove a property from the current entry. +@end table + +To create sparse trees and special lists with selection based on properties, +the same commands are used as for tag searches (@pxref{Tag searches}). The +syntax for the search string is described in @ref{Matching tags and +properties}. + +@table @kbd +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Properties-and-Columns.html#Properties-and-Columns, +Chapter 7 of the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/org-column-view-tutorial.php,Bastien +Guerry's column view tutorial}} + +@node Dates and Times, Capture - Refile - Archive, Properties, Top +@chapter Dates and Times + +To assist project planning, TODO items can be labeled with a date and/or +a time. The specially formatted string carrying the date and time +information is called a @emph{timestamp} in Org mode. + +@menu +* Timestamps:: Assigning a time to a tree entry +* Creating timestamps:: Commands which insert timestamps +* Deadlines and scheduling:: Planning your work +* Clocking work time:: Tracking how long you spend on a task +@end menu + + +@node Timestamps, Creating timestamps, Dates and Times, Dates and Times +@section Timestamps + +A timestamp is a specification of a date (possibly with a 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>}. A +timestamp 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: + +@noindent @b{Plain timestamp; Event; Appointment}@* +A simple timestamp just assigns a date/time to an item. This is just +like writing down an appointment or event in a paper agenda. + +@smallexample +* Meet Peter at the movies <2006-11-01 Wed 19:15> +* Discussion on climate change <2006-11-02 Thu 20:00-22:00> +@end smallexample + +@noindent @b{Timestamp with repeater interval}@* +A timestamp 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: +@smallexample +* Pick up Sam at school <2007-05-16 Wed 12:30 +1w> +@end smallexample + +@noindent @b{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 +@smallexample +* The nerd meeting on every 2nd Thursday of the month + <%%(diary-float t 4 2)> +@end smallexample + +@noindent @b{Time/Date range}@* +Two timestamps connected by @samp{--} denote a range. +@smallexample +** Meeting in Amsterdam + <2004-08-23 Mon>--<2004-08-26 Thu> +@end smallexample + +@noindent @b{Inactive timestamp}@* +Just like a plain timestamp, but with square brackets instead of +angular ones. These timestamps are inactive in the sense that they do +@emph{not} trigger an entry to show up in the agenda. + +@smallexample +* Gillian comes late for the fifth time [2006-11-01 Wed] +@end smallexample + + +@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times +@section Creating timestamps + +For Org mode to recognize timestamps, they need to be in the specific +format. All commands listed below produce timestamps in the correct +format. + +@table @kbd +@item C-c . +Prompt for a date and insert a corresponding timestamp. When the cursor is +at an existing timestamp in the buffer, the command is used to modify this +timestamp instead of inserting a new one. When this command is used twice in +succession, a time range is inserted. With a prefix, also add the current +time. +@c +@item C-c ! +Like @kbd{C-c .}, but insert an inactive timestamp that will not cause +an agenda entry. +@c +@item S-@key{left}@r{/}@key{right} +Change date at cursor by one day. +@c +@item S-@key{up}@r{/}@key{down} +Change the item under the cursor in a timestamp. The cursor can be on a +year, month, day, hour or minute. When the timestamp contains a time range +like @samp{15:30-16:30}, modifying the first time will also shift the second, +shifting the time block with constant length. To change the length, modify +the second time. +@end table + +When Org mode prompts for a date/time, it will accept any string containing +some date and/or time information, and intelligently interpret the string, +deriving defaults for unspecified information from the current date and time. +You can also select a date in the pop-up calendar. See the manual for more +information on how exactly the date/time prompt works. + +@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times +@section Deadlines and scheduling + +A timestamp may be preceded by special keywords to facilitate planning: + +@noindent @b{DEADLINE}@* +Meaning: the task (most likely a TODO item, though not necessarily) is supposed +to be finished on that date. +@table @kbd +@item C-c C-d +Insert @samp{DEADLINE} keyword along with a stamp, in the line following the +headline. +@end table + +On the deadline date, the task will be listed in the agenda. In +addition, the agenda 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: + +@smallexample +*** TODO write article about the Earth for the Guide + The editor in charge is [[bbdb:Ford Prefect]] + DEADLINE: <2004-02-29 Sun> +@end smallexample + + +@noindent @b{SCHEDULED}@* +Meaning: you are @i{planning to start working} on that task on the given +date@footnote{This is quite different from what is normally understood by +@i{scheduling a meeting}, which is done in Org-mode by just inserting a time +stamp without keyword.}. + +@table @kbd +@item C-c C-s +Insert @samp{SCHEDULED} keyword along with a stamp, in the line following the +headline. +@end table + +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. + +@smallexample +*** TODO Call Trillian for a date on New Years Eve. + SCHEDULED: <2004-12-25 Sat> +@end smallexample + +Some tasks need to be repeated again and again. Org mode helps to +organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, +or plain timestamp. In the following example +@smallexample +** TODO Pay the rent + DEADLINE: <2005-10-01 Sat +1m> +@end smallexample +@noindent +the @code{+1m} is a repeater; the intended interpretation is that the task +has a deadline on <2005-10-01> and repeats itself every (one) month starting +from that time. + +@node Clocking work time, , Deadlines and scheduling, Dates and Times +@section Clocking work time + +Org mode allows you to clock the time you spend on specific tasks in a +project. + +@table @kbd +@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. When called with a @kbd{C-u} prefix +argument, select the task from a list of recently clocked tasks. +@c +@item C-c C-x C-o +Stop the clock (clock-out). This 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}. +@item C-c C-x C-e +Update the effort estimate for the current clock task. +@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. +@item C-c C-x C-j +Jump to the entry that contains the currently running clock. With a +@kbd{C-u} prefix arg, select the target task from a list of recently clocked +tasks. +@item C-c C-x C-r +Insert a dynamic block containing a clock +report as an Org-mode table into the current file. When the cursor is +at an existing clock table, just update it. +@smallexample +#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file +#+END: clocktable +@end smallexample +@noindent +For details about how to customize this view, see @uref{http://orgmode.org/manual/Clocking-work-time.html#Clocking-work-time,the manual}. +@item C-c C-c +Update dynamic block at point. The cursor needs to be in the +@code{#+BEGIN} line of the dynamic block. +@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. + +@seealso{ +@uref{http://orgmode.org/manual/Dates-and-Times.html#Dates-and-Times, +Chapter 8 of the manual}@* +@uref{http://members.optusnet.com.au/~charles57/GTD/org_dates/, Charles +Cave's Date and Time tutorial}@* +@uref{http://doc.norang.ca/org-mode.html#Clocking, Bernt Hansen's clocking workflow}} + +@node Capture - Refile - Archive, Agenda Views, Dates and Times, Top +@chapter Capture - Refile - Archive + +An important part of any organization system is the ability to quickly +capture new ideas and tasks, and to associate reference material with them. +Org defines a capture process to create tasks. It stores files related to a +task (@i{attachments}) in a special directory. Once in the system, tasks and +projects need to be moved around. Moving completed project trees to an +archive file keeps the system compact and fast. + +@menu +* Capture:: +* Refiling notes:: Moving a tree from one place to another +* Archiving:: What to do with finished projects +@end menu + +@node Capture, Refiling notes, Capture - Refile - Archive, Capture - Refile - Archive +@section Capture + +Org's method for capturing new items is heavily inspired by John Wiegley +excellent remember package. It lets you store quick notes with little +interruption of your work flow. Org lets you define templates for new +entries and associate them with different targets for storing notes. + +@menu +* Setting up a capture location:: Where notes will be stored +* Using capture:: Commands to invoke and terminate capture +* Capture templates:: Define the outline of different note types +@end menu + +@node Setting up a capture location, Using capture, Capture, Capture +@unnumberedsubsec Setting up a capture location + +The following customization sets a default target@footnote{Using capture +templates, you can define more fine-grained capture locations, see +@ref{Capture templates}.} file for notes, and defines a global +key@footnote{Please select your own key, @kbd{C-c c} is only a suggestion.} +for capturing new stuff. + +@example +(setq org-default-notes-file (concat org-directory "/notes.org")) +(define-key global-map "\C-cc" 'org-capture) +@end example + +@node Using capture, Capture templates, Setting up a capture location, Capture +@unnumberedsubsec Using capture + +@table @kbd +@item C-c c +Start a capture process. You will be placed into a narrowed indirect buffer +to edit the item. +@item C-c C-c +Once you are done entering information into the capture buffer, +@kbd{C-c C-c} will return you to the window configuration before the capture +process, so that you can resume your work without further distraction. +@item C-c C-w +Finalize by moving the entry to a refile location (@pxref{Refiling notes}). +@item C-c C-k +Abort the capture process and return to the previous state. +@end table + +@node Capture templates, , Using capture, Capture +@unnumberedsubsec Capture templates + +You can use templates to generate different types of capture notes, and to +store them in different places. For example, if you would like +to store new tasks under a heading @samp{Tasks} in file @file{TODO.org}, and +journal entries in a date tree in @file{journal.org} you could +use: + +@smallexample +(setq org-capture-templates + '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") + "* TODO %?\n %i\n %a") + ("j" "Journal" entry (file+datetree "~/org/journal.org") + "* %?\nEntered on %U\n %i\n %a"))) +@end smallexample + +@noindent In these entries, the first string is the key to reach the +template, the second is a short description. Then follows the type of the +entry and a definition of the target location for storing the note. Finally, +the template itself, a string with %-escapes to fill in information based on +time and context. + +When you call @kbd{M-x org-capture}, Org will prompt for a key to select the +template (if you have more than one template) and then prepare the buffer like +@smallexample +* TODO + [[file:@var{link to where you were when initiating capture}]] +@end smallexample + +@noindent +During expansion of the template, special @kbd{%}-escapes@footnote{If you +need one of these sequences literally, escape the @kbd{%} with a backslash.} +allow dynamic insertion of content. Here is a small selection of the +possibilities, consult the manual for more. +@smallexample +%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.} +%t @r{timestamp, date only} +%T @r{timestamp with date and time} +%u, %U @r{like the above, but inactive timestamps} +@end smallexample + +@node Refiling notes, Archiving, Capture, Capture - Refile - Archive +@section Refiling notes + +When reviewing the captured data, you may want to refile some of the entries +into a different list, for example into a project. Cutting, finding the +right location, and then pasting the note is cumbersome. To simplify this +process, you can use the following special command: + +@table @kbd +@item C-c C-w +Refile the entry or region at point. This command offers possible locations +for refiling the entry and lets you select one with completion. The item (or +all items in the region) is filed below the target heading as a subitem.@* +By default, all level 1 headlines in the current buffer are considered to be +targets, but you can have more complex definitions across a number of files. +See the variable @code{org-refile-targets} for details. +@item C-u C-c C-w +Use the refile interface to jump to a heading. +@item C-u C-u C-c C-w +Jump to the location where @code{org-refile} last moved a tree to. +@end table + +@node Archiving, , Refiling notes, Capture - Refile - Archive +@section 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. Archiving is important to keep your working files compact and global +searches like the construction of agenda views fast. +The most common archiving action is to move a project tree to another file, +the archive file. + +@table @kbd +@item C-c C-x C-a +Archive the current entry using the command specified in the variable +@code{org-archive-default-command}. +@item C-c C-x C-s@ @r{or short} @ C-c $ +Archive the subtree starting at the cursor position to the location +given by @code{org-archive-location}. +@end table + +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 + +@smallexample +#+ARCHIVE: %s_done:: +@end smallexample + +@seealso{ +@uref{http://orgmode.org/manual/Capture-_002d-Refile-_002d-Archive.html#Capture-_002d-Refile-_002d-Archive, +Chapter 9 of the manual}@* +@uref{http://members.optusnet.com.au/~charles57/GTD/remember.html, Charles +Cave's remember tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-protocol-custom-handler.php, +Sebastian Rose's tutorial for capturing from a web browser}}@uref{}@* + +@node Agenda Views, Markup, Capture - Refile - Archive, Top +@chapter Agenda Views + +Due to the way Org 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 of open action items, or of events that are important for a +particular date, this information must be collected, sorted and displayed in +an organized way. There are several different views, see below. + +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 files, and even to edit these files remotely. +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}. + +@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? +* 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 + +The information to be shown is normally collected from all @emph{agenda +files}, the files listed in the variable +@code{org-agenda-files}. + +@table @kbd +@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 a prefix argument, file is added/moved to the end. +@item C-c ] +Remove current file from the list of agenda files. +@item C-, +Cycle through agenda file list, visiting one file after the other. +@end table + +@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views +@section The agenda dispatcher +The views are created through a dispatcher, which should be bound to a +global key---for example @kbd{C-c a} (@pxref{Installation}). After +pressing @kbd{C-c a}, an additional letter is required to execute a +command: +@table @kbd +@item a +The calendar-like agenda (@pxref{Weekly/daily agenda}). +@item t @r{/} T +A list of all TODO items (@pxref{Global TODO list}). +@item m @r{/} M +A list of headlines matching a TAGS expression (@pxref{Matching +tags and properties}). +@item L +The timeline view for the current buffer (@pxref{Timeline}). +@item s +A list of entries selected by a boolean expression of keywords +and/or regular expressions that must or must not occur in the entry. +@end table + +@node Built-in agenda views, Agenda commands, Agenda dispatcher, Agenda Views +@section The built-in agenda 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 +* Search view:: Find entries by searching for text +@end menu + +@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views +@subsection The weekly/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 +@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. +@end table + +Emacs contains the calendar and diary by Edward M. Reingold. Org-mode +understands the syntax of the diary and allows you to use diary sexp entries +directly in Org files: + +@smallexample +* Birthdays and similar stuff +#+CATEGORY: Holiday +%%(org-calendar-holiday) ; special function for holiday names +#+CATEGORY: Ann +%%(diary-anniversary 5 14 1956)@footnote{Note that the order of the arguments (month, day, year) depends on the setting of @code{calendar-date-style}.} Arthur Dent is %d years old +%%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old +@end smallexample + +Org can interact with Emacs appointments notification facility. To add all +the appointments of your agenda files, use the command +@code{org-agenda-to-appt}. See the docstring for details. + +@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views +@subsection The global TODO list + +The global TODO list contains all unfinished TODO items formatted and +collected into a single place. Remote editing of TODO items lets 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}. + +@table @kbd +@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. +@item C-c a T +Like the above, but allows selection of a specific TODO keyword. +@end table + +@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views +@subsection Matching tags and properties + +If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}), +or have properties (@pxref{Properties}), you can select headlines +based on this metadata and collect them into an agenda buffer. The match +syntax described here also applies when creating sparse trees with @kbd{C-c / +m}. The commands available in the tags list are described in @ref{Agenda +commands}. + +@table @kbd +@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}). +@item C-c a M +Like @kbd{C-c a m}, but only select headlines that are also TODO items. +@end table + +@subsubheading Match syntax + +A search string can use Boolean operators @samp{&} for AND and @samp{|} for +OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently +not implemented. Each element in the search is either a tag, a regular +expression matching tags, or an expression like @code{PROPERTY OPERATOR +VALUE} with a comparison operator, accessing a property value. Each element +may 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. Here are some examples, using only tags. + +@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 + +You may also test for properties at the same +time as matching tags, see the manual for more information. + +@node Timeline, Search view, Matching tags and properties, Built-in agenda views +@subsection Timeline for a single file + +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 +@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 + +@node Search view, , Timeline, Built-in agenda views +@subsection Search view + +This agenda view is a general text search facility for Org mode entries. +It is particularly useful to find notes. + +@table @kbd +@item C-c a s +This is a special search that lets you select entries by matching a substring +or specific words using a boolean logic. +@end table +For example, the search string @samp{computer equipment} will find entries +that contain @samp{computer equipment} as a substring. +Search view can also search for specific keywords in the entry, using Boolean +logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}} +will search for note entries that contain the keywords @code{computer} +and @code{wifi}, but not the keyword @code{ethernet}, and which are also +not matched by the regular expression @code{8\.11[bg]}, meaning to +exclude both 8.11b and 8.11g. + +Note that in addition to the agenda files, this command will also search +the files listed in @code{org-agenda-text-search-extra-files}. + +@node Agenda commands, Custom agenda views, Built-in agenda views, Agenda Views +@section Commands in the agenda buffer + +Entries in the agenda buffer are linked back to the Org file or diary +file where they originate. Commands are provided to show and jump to the +original entry location, and to edit the Org files ``remotely'' from +the agenda buffer. This is just a selection of the many commands, explore +the @code{Agenda} menu and the manual for a complete list. + +@table @kbd +@tsubheading{Motion} +@item n +Next line (same as @key{up} and @kbd{C-p}). +@item p +Previous line (same as @key{down} and @kbd{C-n}). +@tsubheading{View/Go to Org file} +@item mouse-3 +@itemx @key{SPC} +Display the original location of the item in another window. +With prefix arg, make sure that the entire entry is made visible in the +outline, not only the heading. +@c +@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 +@itemx @key{RET} +Go to the original location of the item and delete other windows. +@c + +@tsubheading{Change display} +@item o +Delete other windows. +@c +@item d @r{/} w +Switch to day/week view. +@c +@item f @r{and} b +Go forward/backward in time to display the following +@code{org-agenda-current-span} days. For example, if the display covers a +week, switch to the following/previous week. +@c +@item . +Go to today. +@c +@item j +Prompt for a date and go there. +@c +@item v l @ @r{or short} @ l +Toggle Logbook mode. In Logbook mode, entries that were 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. When called with a @kbd{C-u} +prefix, show all possible logbook entries, including state changes. +@c +@item r @r{or} g +Recreate the agenda buffer, to reflect the changes. +@item s +Save all Org buffers in the current Emacs session, and also the locations of +IDs. + +@tsubheading{Secondary filtering and query editing} + +@item / +Filter the current agenda view with respect to a tag. You are prompted for a +letter to select a tag. Press @samp{-} first to select against the tag. + +@item \ +Narrow the current agenda filter by an additional condition. + +@tsubheading{Remote editing (see the manual for many more commands)} + +@item 0-9 +Digit argument. +@c +@item t +Change the TODO state of the item, in the agenda and in the +org file. +@c +@item C-k +Delete the current agenda item along with the entire subtree belonging +to it in the original Org file. +@c +@item C-c C-w +Refile the entry at point. +@c +@item C-c C-x C-a @ @r{or short} @ a +Archive the subtree corresponding to the entry at point using the default +archiving command set in @code{org-archive-default-command}. +@c +@item C-c C-x C-s @ @r{or short} @ $ +Archive the subtree corresponding to the current headline. +@c +@item C-c C-s +Schedule this item, with prefix arg remove the scheduling timestamp +@c +@item C-c C-d +Set a deadline for this item, with prefix arg remove the deadline. +@c +@item S-@key{right} @r{and} S-@key{left} +Change the timestamp associated with the current line by one day. +@c +@item I +Start the clock on the current item. +@c +@item O / X +Stop/cancel the previously started clock. + +@item J +Jump to the running clock in another window. +@end table + +@node Custom agenda views, , Agenda commands, Agenda Views +@section Custom agenda views + +The main 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). +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: + +@smalllisp +@group +(setq org-agenda-custom-commands + '(("w" todo "WAITING") + ("u" tags "+boss-urgent") + ("v" tags-todo "+boss-urgent"))) +@end group +@end smalllisp + +@noindent +The initial string in each entry defines the keys you have to press after the +dispatcher command @kbd{C-c a} in order to access the command. Usually this +will be just a single character. 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 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 +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Agenda-Views.html#Agenda-Views, Chapter 10 of +the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/org-custom-agenda-commands.php, +Mat Lundin's tutorial about custom agenda commands}@* +@uref{http://www.newartisans.com/2007/08/using-org-mode-as-a-day-planner.html, +John Wiegley's setup}} + +@node Markup, Exporting, Agenda Views, Top +@chapter Markup for rich export + +When exporting Org-mode documents, the exporter tries to reflect the +structure of the document as accurately as possible in the backend. Since +export targets like HTML, La@TeX{}, or DocBook allow much richer formatting, +Org mode has rules on how to prepare text for rich export. This section +summarizes the markup rules used in an Org-mode buffer. + +@menu +* Structural markup elements:: The basic structure as seen by the exporter +* Images and tables:: Tables and Images will be included +* Literal examples:: Source code examples with special formatting +* Include files:: Include additional files into a document +* Embedded LaTeX:: LaTeX can be freely used inside Org documents +@end menu + +@node Structural markup elements, Images and tables, Markup, Markup +@section Structural markup elements + +@menu +* Document title:: Where the title is taken from +* Headings and sections:: The document structure as seen by the exporter +* Table of contents:: The if and where of the table of contents +* Paragraphs:: Paragraphs +* Emphasis and monospace:: Bold, italic, etc. +* Comment lines:: What will *not* be exported +@end menu + +@node Document title, Headings and sections, Structural markup elements, Structural markup elements +@subheading Document title + +@noindent +The title of the exported document is taken from the special line + +@smallexample +#+TITLE: This is the title of the document +@end smallexample + +@node Headings and sections, Table of contents, Document title, Structural markup elements +@subheading Headings and sections + +The outline structure of the document as described in @ref{Document +Structure}, forms the basis for defining sections of the exported document. +However, since the outline structure is also used for (for example) lists of +tasks, only the first three outline levels will be used as headings. Deeper +levels will become itemized lists. You can change the location of this +switch globally by setting the variable @code{org-export-headline-levels}, or on a +per-file basis with a line + +@smallexample +#+OPTIONS: H:4 +@end smallexample + +@node Table of contents, Paragraphs, Headings and sections, Structural markup elements +@subheading Table of contents + +The table of contents is normally inserted directly before the first headline +of the file. + +@smallexample +#+OPTIONS: toc:2 (only to two levels in TOC) +#+OPTIONS: toc:nil (no TOC at all) +@end smallexample + +@node Paragraphs, Emphasis and monospace, Table of contents, Structural markup elements +@subheading Paragraphs, line breaks, and quoting + +Paragraphs are separated by at least one empty line. If you need to enforce +a line break within a paragraph, use @samp{\\} at the end of a line. + +To keep the line breaks in a region, but otherwise use normal formatting, you +can use this construct, which can also be used to format poetry. + +@smallexample +#+BEGIN_VERSE + Great clouds overhead + Tiny black birds rise and fall + Snow covers Emacs + + -- AlexSchroeder +#+END_VERSE +@end smallexample + +When quoting a passage from another document, it is customary to format this +as a paragraph that is indented on both the left and the right margin. You +can include quotations in Org-mode documents like this: + +@smallexample +#+BEGIN_QUOTE +Everything should be made as simple as possible, +but not any simpler -- Albert Einstein +#+END_QUOTE +@end smallexample + +If you would like to center some text, do it like this: +@smallexample +#+BEGIN_CENTER +Everything should be made as simple as possible, \\ +but not any simpler +#+END_CENTER +@end smallexample + +@node Emphasis and monospace, Comment lines, Paragraphs, Structural markup elements +@subheading Emphasis and monospace + +You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} +and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text +in the code and verbatim string is not processed for Org-mode specific +syntax, it is exported verbatim. To insert a horizontal rules, use a line +consisting of only dashes, and at least 5 of them. + +@node Comment lines, , Emphasis and monospace, Structural markup elements +@subheading Comment lines + +Lines starting with @samp{#} in column zero are treated as comments and will +never be exported. If you want an indented line to be treated as a comment, +start it with @samp{#+ }. Also entire subtrees starting with the word +@samp{COMMENT} will never be exported. Finally, regions surrounded by +@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported. + +@table @kbd +@item C-c ; +Toggle the COMMENT keyword at the beginning of an entry. +@end table + +@node Images and tables, Literal examples, Structural markup elements, Markup +@section Images and Tables + +For Org mode tables, the lines before the first horizontal separator line +will become table header lines. You can use the following lines somewhere +before the table to assign a caption and a label for cross references, and in +the text you can refer to the object with @code{\ref@{tab:basic-data@}}: + +@smallexample +#+CAPTION: This is the caption for the next table (or link) +#+LABEL: tbl:basic-data + | ... | ...| + |-----|----| +@end smallexample + +Some backends (HTML, La@TeX{}, and DocBook) allow you to directly include +images into the exported document. Org does this, if a link to an image +files does not have a description part, for example @code{[[./img/a.jpg]]}. +If you wish to define a caption for the image and maybe a label for internal +cross references, you sure that the link is on a line by itself precede it +with: + +@smallexample +#+CAPTION: This is the caption for the next figure link (or table) +#+LABEL: fig:SED-HR4049 +[[./img/a.jpg]] +@end smallexample + +You may also define additional attributes for the figure. As this is +backend-specific, see the sections about the individual backends for more +information. + + +@node Literal examples, Include files, Images and tables, Markup +@section Literal examples + +You can include literal examples that should not be subjected to +markup. Such examples will be typeset in monospace, so this is well suited +for source code and similar examples. + +@smallexample +#+BEGIN_EXAMPLE +Some example from a text file. +#+END_EXAMPLE +@end smallexample + +For simplicity when using small examples, you can also start the example +lines with a colon followed by a space. There may also be additional +whitespace before the colon: + +@smallexample +Here is an example + : Some example from a text file. +@end smallexample + +For source code from a programming language, or any other text +that can be marked up by font-lock in Emacs, you can ask for it to +look like the fontified Emacs buffer + +@smallexample +#+BEGIN_SRC emacs-lisp +(defun org-xor (a b) + "Exclusive or." + (if a (not b) b)) +#+END_SRC +@end smallexample + +To edit the example in a special buffer supporting this language, use +@kbd{C-c '} to both enter and leave the editing buffer. + +@node Include files, Embedded LaTeX, Literal examples, Markup +@section Include files + +During export, you can include the content of another file. For example, to +include your @file{.emacs} file, you could use: + +@smallexample +#+INCLUDE: "~/.emacs" src emacs-lisp +@end smallexample +@noindent +The optional second and third parameter are the markup (e.g. @samp{quote}, +@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the +language for formatting the contents. The markup is optional, if it is not +given, the text will be assumed to be in Org mode format and will be +processed normally. @kbd{C-c '} will visit the included file. + +@node Embedded LaTeX, , Include files, Markup +@section Embedded La@TeX{} + +For scientific notes which need to be able to contain mathematical symbols +and the occasional formula, Org-mode supports embedding La@TeX{} code into +its files. You can directly use TeX-like macros for special symbols, enter +formulas and entire LaTeX environments. + +@smallexample +Angles are written as Greek letters \alpha, \beta and \gamma. 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. If $a^2=b$ and $b=2$, then the solution must be either +$a=+\sqrt@{2@}$ or $a=-\sqrt@{2@}$. + +\begin@{equation@} +x=\sqrt@{b@} +\end@{equation@} +@end smallexample +@noindent With +@uref{http://orgmode.org/manual/LaTeX-fragments.html#LaTeX-fragments,special +setup}, LaTeX snippets will be included as images when exporting to HTML. + +@seealso{ +@uref{http://orgmode.org/manual/Markup.html#Markup, Chapter 11 of the manual}} + +@node Exporting, Publishing, Markup, Top +@chapter Exporting + +Org-mode documents can be exported into a variety of other formats: ASCII +export for inclusion into emails, HTML to publish on the web, La@TeX{}/PDF +for beautiful printed documents and DocBook to enter the world of many other +formats using DocBook tools. There is also export to iCalendar format so +that planning information can be incorporated into desktop calendars. + +@menu +* Export options:: Per-file export settings +* The export dispatcher:: How to access exporter commands +* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding +* HTML export:: Exporting to HTML +* LaTeX and PDF export:: Exporting to La@TeX{}, and processing to PDF +* DocBook export:: Exporting to DocBook +* iCalendar export:: +@end menu + +@node Export options, The export dispatcher, Exporting, Exporting +@section Export options + +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}. + +@table @kbd +@item C-c C-e t +Insert template with export options, see example below. +@end table + +@smallexample +#+TITLE: the title to be shown (default is the buffer name) +#+AUTHOR: the author (default taken from @code{user-full-name}) +#+DATE: a date, fixed, of a format string for @code{format-time-string} +#+EMAIL: his/her email address (default from @code{user-mail-address}) +#+DESCRIPTION: the page description, e.g. for the XHTML meta tag +#+KEYWORDS: the page keywords, e.g. for the XHTML meta tag +#+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 ... +#+LINK_UP: the ``up'' link of an exported page +#+LINK_HOME: the ``home'' link of an exported page +#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@} +@end smallexample + +@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting +@section The export dispatcher + +All export commands can be reached using the export dispatcher, which is a +prefix key that prompts for an additional key specifying the command. +Normally the entire file is exported, but if there is an active region that +contains one outline tree, the first heading is used as document title and +the subtrees are exported. + +@table @kbd +@item C-c C-e +Dispatcher for export and publishing commands. +@end table + +@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting +@section ASCII/Latin-1/UTF-8 export + +ASCII export produces a simple and very readable version of an Org-mode +file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file +with special characters and symbols available in these encodings. + +@table @kbd +@item C-c C-e a +Export as ASCII file. +@item C-c C-e n @ @ @r{and} @ @ C-c C-e N +Like the above commands, but use Latin-1 encoding. +@item C-c C-e u @ @ @r{and} @ @ C-c C-e U +Like the above commands, but use UTF-8 encoding. +@end table + +@node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting +@section HTML export + +@table @kbd +@item C-c C-e h +Export as HTML file @file{myfile.html}. +@item C-c C-e b +Export as HTML file and immediately open it with a browser. +@end table + +To insert HTML that should be copied verbatim to +the exported file use either + +@smallexample +#+HTML: Literal HTML code for export +@end smallexample +@noindent or +@smallexample +#+BEGIN_HTML +All lines between these markers are exported literally +#+END_HTML +@end smallexample + +@node LaTeX and PDF export, DocBook export, HTML export, Exporting +@section La@TeX{} and PDF export + +@table @kbd +@item C-c C-e l +Export as La@TeX{} file @file{myfile.tex}. +@item C-c C-e p +Export as La@TeX{} and then process to PDF. +@item C-c C-e d +Export as La@TeX{} and then process to PDF, then open the resulting PDF file. +@end table + +By default, the La@TeX{} output uses the class @code{article}. You can +change this by adding an option like @code{#+LaTeX_CLASS: myclass} in your +file. The class must be listed in @code{org-export-latex-classes}. + +Embedded La@TeX{} as described in @ref{Embedded LaTeX}, will be correctly +inserted into the La@TeX{} file. Similarly to the HTML exporter, you can use +@code{#+LaTeX:} and @code{#+BEGIN_LaTeX ... #+END_LaTeX} construct to add +verbatim LaTeX code. + +@node DocBook export, iCalendar export, LaTeX and PDF export, Exporting +@section DocBook export + +@table @kbd +@item C-c C-e D +Export as DocBook file. +@end table + +Similarly to the HTML exporter, you can use @code{#+DocBook:} and +@code{#+BEGIN_DocBook ... #+END_DocBook} construct to add verbatim LaTeX +code. + +@node iCalendar export, , DocBook export, Exporting +@section iCalendar export + +@table @kbd +@item C-c C-e i +Create iCalendar entries for the current file in a @file{.ics} file. +@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 + +@seealso{ +@uref{http://orgmode.org/manual/Exporting.html#Exporting, Chapter 12 of the manual}@* +@uref{http://orgmode.org/worg/org-tutorials/images-and-xhtml-export.php, +Sebastian Rose's image handling tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-latex-export.php, Thomas +Dye's LaTeX export tutorial} +@uref{http://orgmode.org/worg/org-tutorials/org-beamer/tutorial.php, Eric +Fraga's BEAMER presentation tutorial}} + +@node Publishing, Working With Source Code, Exporting, Top +@chapter Publishing + +Org includes a publishing management system that allows you to configure +automatic HTML conversion of @emph{projects} composed of interlinked org +files. You can also configure Org to automatically upload your exported HTML +pages and related attachments, such as images and source code files, to a web +server. For detailed instructions about setup, see the manual. + +Here is an example: + +@smalllisp +(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 smalllisp + +@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 E +Publish every project. +@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 to any of the commands +above. + +@seealso{ +@uref{http://orgmode.org/manual/Publishing.html#Publishing, Chapter 13 of the +manual}@* +@uref{http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.php, +Sebastian Rose's publishing tutorial}@* +@uref{http://orgmode.org/worg/org-tutorials/org-jekyll.php, Ian Barton's +Jekyll/blogging setup}} + +@node Working With Source Code, Miscellaneous, Publishing, Top +@chapter Working with source code +Org-mode provides a number of features for working with source code, +including editing of code blocks in their native major-mode, evaluation of +code blocks, tangling of code blocks, and exporting code blocks and their +results in several formats. + +@subheading Structure of Code Blocks +The structure of code blocks is as follows: + +@example +#+srcname: <name> +#+begin_src <language> <switches> <header arguments> + <body> +#+end_src +@end example + +Where @code{<name>} is a string used to name the code block, +@code{<language>} specifies the language of the code block +(e.g. @code{emacs-lisp}, @code{shell}, @code{R}, @code{python}, etc...), +@code{<switches>} can be used to control export of the code block, +@code{<header arguments>} can be used to control many aspects of code block +behavior as demonstrated below, and @code{<body>} contains the actual source +code. + +@subheading Editing source code +Use @kbd{C-c '} to edit the current code block. This brings up a language +major-mode edit buffer containing the body of the code block. Saving this +buffer will write the new contents back to the Org buffer. Use @kbd{C-c '} +again to exit the edit buffer. + +@subheading Evaluating code blocks +Use @kbd{C-c C-c} to evaluate the current code block and insert its results +in the Org-mode buffer. By default, evaluation is only turned on for +@code{emacs-lisp} code blocks, however support exists for evaluating blocks +in many languages. For a complete list of supported languages see the +manual. The following shows a code block and its results. + +@example +#+begin_src emacs-lisp + (+ 1 2 3 4) +#+end_src + +#+results: +: 10 +@end example + +@subheading Extracting source code +Use @kbd{C-c C-v t} to create pure source code files by extracting code from +source blocks in the current buffer. This is referred to as ``tangling''---a +term adopted from the literate programming community. During ``tangling'' of +code blocks their bodies are expanded using @code{org-babel-expand-src-block} +which can expand both variable and ``noweb'' style references. In order to +tangle a code block it must have a @code{:tangle} header argument, see the +manual for details. + +@subheading Library of Babel +Use @kbd{C-c C-v l} to load the code blocks from an Org-mode files into the +``Library of Babel'', these blocks can then be evaluated from any Org-mode +buffer. A collection of generally useful code blocks is distributed with +Org-mode in @code{contrib/library-of-babel.org}. + +@subheading Header Arguments +Many aspects of the evaluation and export of code blocks are controlled +through header arguments. These can be specified globally, at the file +level, at the outline subtree level, and at the individual code block level. +The following describes some of the header arguments. +@table @code +@item :var +The @code{:var} header argument is used to pass arguments to code blocks. +The values passed to arguments can be literal values, values from org-mode +tables and literal example blocks, or the results of other named code blocks. +@item :results +The @code{:results} header argument controls the @emph{collection}, +@emph{type}, and @emph{handling} of code block results. Values of +@code{output} or @code{value} (the default) specify how results are collected +from a code block's evaluation. Values of @code{vector}, @code{scalar} +@code{file} @code{raw} @code{html} @code{latex} and @code{code} specify the +type of the results of the code block which dictates how they will be +incorporated into the Org-mode buffer. Values of @code{silent}, +@code{replace}, @code{prepend}, and @code{append} specify handling of code +block results, specifically if and how the results should be inserted into +the Org-mode buffer. +@item :session +A header argument of @code{:session} will cause the code block to be +evaluated in a persistent interactive inferior process in Emacs. This allows +for persisting state between code block evaluations, and for manual +inspection of the results of evaluation. +@item :exports +Any combination of the @emph{code} or the @emph{results} of a block can be +retained on export, this is specified by setting the @code{:results} header +argument to @code{code} @code{results} @code{none} or @code{both}. +@item :tangle +A header argument of @code{:tangle yes} will cause a code block's contents to +be tangled to a file named after the filename of the Org-mode buffer. An +alternate file name can be specified with @code{:tangle filename}. +@item :cache +A header argument of @code{:cache yes} will cause associate a hash of the +expanded code block with the results, ensuring that code blocks are only +re-run when their inputs have changed. +@item :noweb +A header argument of @code{:noweb yes} will expand ``noweb'' style references +on evaluation and tangling. +@item :file +Code blocks which output results to files (e.g. graphs, diagrams and figures) +can accept a @code{:file filename} header argument in which case the results +are saved to the named file, and a link to the file is inserted into the +Org-mode buffer. +@end table + +@seealso{ +@uref{http://orgmode.org/manual/Literal-examples.html#Literal-examples, +Chapter 11.3 of the manual}@* +@uref{http://orgmode.org/worg/org-contrib/babel/index.php, +The Babel site on Worg}} + +@node Miscellaneous, , Working With Source Code, Top +@chapter Miscellaneous + +@menu +* Completion:: M-TAB knows what you need +* Clean view:: Getting rid of leading stars in the outline +* MobileOrg:: Org-mode on the iPhone +@end menu + +@node Completion, Clean view, Miscellaneous, Miscellaneous +@section Completion + +Org supports in-buffer completion with @kbd{M-@key{TAB}}. 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. For +example, this command will complete @TeX{} symbols after @samp{\}, TODO +keywords at the beginning of a headline, and tags after @samp{:} in a +headline. + +@node Clean view, MobileOrg, Completion, Miscellaneous +@section A cleaner outline view + +Some people find it noisy and distracting that the Org headlines start with a +potentially large number of stars, and that text below the headlines is not +indented. While this is no problem when writing a @emph{book-like} document +where the outline headings are really section headings, in a more +@emph{list-oriented} outline, indented structure is a lot cleaner: + +@smallexample +@group +* Top level headline | * Top level headline +** Second level | * Second level +*** 3rd level | * 3rd level +some text | some text +*** 3rd level | * 3rd level +more text | more text +* Another top level headline | * Another top level headline +@end group +@end smallexample + +@noindent +If you are using at least Emacs 23.1.50.3 and version 6.29 of Org, this kind +of view can be achieved dynamically at display time using +@code{org-indent-mode}, which will prepend intangible space to each line. +You can turn on @code{org-indent-mode} for all files by customizing the +variable @code{org-startup-indented}, or you can turn it on for individual +files using + +@smallexample +#+STARTUP: indent +@end smallexample + +If you want a similar effect in earlier version of Emacs and/or Org, or if +you want the indentation to be hard space characters so that the plain text +file looks as similar as possible to the Emacs display, Org supports you by +helping to indent (with @key{TAB}) text below each headline, by hiding +leading stars, and by only using levels 1, 3, etc to get two characters +indentation for each level. To get this support in a file, use + +@smallexample +#+STARTUP: hidestars odd +@end smallexample + +@node MobileOrg, , Clean view, Miscellaneous +@section MobileOrg + +@i{MobileOrg} is an application for the @i{iPhone/iPod Touch} series of +devices, developed by Richard Moreland. For details, see the Org-mode +manual. + +@seealso{ +@uref{http://orgmode.org/manual/Miscellaneous.html#Miscellaneous, Chapter 15 +of the manual}@* +@uref{http://orgmode.org/manual/MobileOrg.html#MobileOrg, Appendix B of the +manual}@* +@uref{http://orgmode.org/orgcard.pdf,Key reference card}} + +@bye + +@ignore + arch-tag: 8f0a8557-0acc-4436-b2b2-0197699e1452 +@end ignore + +@c Local variables: +@c fill-column: 77 +@c End: + + +@c LocalWords: webdavhost pre diff --git a/.emacs.d/org-7.4/doc/pdflayout.sty b/.emacs.d/org-7.4/doc/pdflayout.sty new file mode 100644 index 0000000..114f9aa --- /dev/null +++ b/.emacs.d/org-7.4/doc/pdflayout.sty @@ -0,0 +1,47 @@ +% Copyright (C) 2007, 2008, 2009 Free Software Foundation, Inc. + +% This file is part of GNU Emacs. + +% GNU Emacs is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. + +% GNU Emacs is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. + +% You should have received a copy of the GNU General Public License +% along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. + +% This file defines `\pdflayout': +% - \pdflayout=(0) is A4 portrait, +% - \pdflayout=(1) is letter (US) portrait, +% - \pdflayout=(0l) is A4 landscape. +% - \pdflayout=(1l) is letter (US) landscape, + +\input ifpdf.sty + +\ifpdf + \def\pdflayout=(#1#2){ + \if0#1 % A4 + \pdfpagewidth=21cm + \pdfpageheight=29.7cm + \else\if1#1 % Letter + \pdfpagewidth=8.5in + \pdfpageheight=11in + \fi\fi + \if l#2 % Landscape + \edef\oldwidth{\the\pdfpagewidth} + \pdfpagewidth=\pdfpageheight + \pdfpageheight=\oldwidth + \fi + } +\else + \def\pdflayout=(#1#2){} +\fi + +% archtag: 63c938a5-cc78-4964-962d-603c90d34afc + +% arch-tag: 3464d27c-1439-473a-bc47-a7c501e8c156 |