diff options
Diffstat (limited to '.emacs.d/org-7.4/doc/org')
| -rw-r--r-- | .emacs.d/org-7.4/doc/org | 16592 |
1 files changed, 16592 insertions, 0 deletions
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 |