Replace use of VPATH in most doc/ Makefiles.
* doc/lispref/Makefile.in (VPATH): Remove.
(infodir): Make it absolute.
(mkinfodir, $(infodir)/elisp, infoclean): No need to cd $srcdir.
* doc/lispintro/Makefile.in (VPATH): Remove.
(infodir): Make it absolute.
(mkinfodir, $(infodir)/eintr, infoclean): No need to cd $srcdir.
* doc/emacs/Makefile.in (VPATH): Remove.
(infodir): Make it absolute.
(mkinfodir, $(infodir)/emacs, infoclean): No need to cd $srcdir.
* doc/misc/Makefile.in: Comment.
\input texinfo@c %**start of header@setfilename ../../info/org@settitle The Org Manual@set VERSION 7.01@set DATE July 2010@c Use proper quote and backtick for code sections in PDF output@c Cf. Texinfo manual 14.2@set txicodequoteundirected@set txicodequotebacktick@c Version and Contact Info@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}@set AUTHOR Carsten Dominik@set MAINTAINER Carsten Dominik@set MAINTAINEREMAIL @email{carsten at orgmode dot org}@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}@c %**end of header@finalout@c Macro definitions@iftex@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}@end iftex@macro Ie {}I.e.,@end macro@macro ie {}i.e.,@end macro@macro Eg {}E.g.,@end macro@macro eg {}e.g.,@end macro@c Subheadings inside a table.@macro tsubheading{text}@ifinfo@subsubheading \text\@end ifinfo@ifnotinfo@item @b{\text\}@end ifnotinfo@end macro@copyingThis manual is for Org version @value{VERSION}.Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010Free Software Foundation, Inc.@quotationPermission is granted to copy, distribute and/or modify this documentunder the terms of the GNU Free Documentation License, Version 1.3 orany later version published by the Free Software Foundation; with noInvariant Sections, with the Front-Cover texts being ``A GNU Manual,''and with the Back-Cover Texts as in (a) below. A copy of the licenseis included in the section entitled ``GNU Free Documentation License.''(a) The FSF's Back-Cover Text is: ``You have the freedom to copy andmodify this GNU manual. Buying copies from the FSF supports it indeveloping GNU and promoting software freedom.''This document is part of a collection distributed under the GNU FreeDocumentation License. If you want to distribute this documentseparately from the collection, you can do so by adding a copy of thelicense to the document, as described in section 6 of the license.@end quotation@end copying@dircategory Emacs@direntry* Org Mode: (org). Outline-based notes management and organizer@end direntry@titlepage@title The Org Manual@subtitle Release @value{VERSION}@author by Carsten Dominikwith contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, and Thomas Dye@c The following two commands start the copyright page.@page@vskip 0pt plus 1filll@insertcopying@end titlepage@c Output the table of contents at the beginning.@contents@ifnottex@node Top, Introduction, (dir), (dir)@top Org Mode Manual@insertcopying@end ifnottex@menu* Introduction:: Getting started* Document Structure:: A tree works like your brain* Tables:: Pure magic for quick formatting* Hyperlinks:: Notes in context* TODO Items:: Every tree branch can be a TODO item* Tags:: Tagging headlines and matching sets of tags* Properties and Columns:: Storing information about an entry* Dates and Times:: Making items useful for planning* Capture - Refile - Archive:: The ins and outs for projects* Agenda Views:: Collecting information into views* Markup:: Prepare text for rich export* Exporting:: Sharing and publishing of notes* Publishing:: Create a web site of linked Org files* Working With Source Code:: Export, evaluate, and tangle code blocks* Miscellaneous:: All the rest which did not fit elsewhere* Hacking:: How to hack your way around* MobileOrg:: Viewing and capture on a mobile device* History and Acknowledgments:: How Org came into being* Main Index:: An index of Org's concepts and features* Key Index:: Key bindings and where they are described* Variable Index:: Variables mentioned in the manual@detailmenu --- The Detailed Node Listing ---Introduction* Summary:: Brief summary of what Org does* Installation:: How to install a downloaded version of Org* Activation:: How to activate Org for certain buffers* Feedback:: Bug reports, ideas, patches etc.* Conventions:: Type-setting conventions in the manualDocument 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 OrgTables* 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 tablesThe 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 recalcHyperlinks* 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 enoughInternal links* Radio targets:: Make targets trigger links in plain textTODO 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 listsExtended 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 othersProgress 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 tagsProperties 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 programmersColumn 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 viewDefining columns* Scope of column definitions:: Where defined, where valid?* Column attributes:: Appearance and content of a columnDates 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* Resolving idle time:: Resolving time if you've been idle* Effort estimates:: Planning work effort in advance* Relative timer:: Notes with a running timerCreating timestamps* The date/time prompt:: How Org-mode helps you entering date and time* Custom time format:: Making dates look differentDeadlines and scheduling* Inserting deadline/schedule:: Planning items* Repeated tasks:: Items that show up again and againCapture - 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 projectsCapture* Setting up capture:: Where notes will be stored* Using capture:: Commands to invoke and terminate capture* Capture templates:: Define the outline of different note typesCapture templates* Template elements:: What is needed for a complete template entry* Template expansion:: Filling in information about time and contextArchiving* Moving subtrees:: Moving a tree to an archive file* Internal archiving:: Switch off a tree but keep it in the fileAgenda 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 entriesThe 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 reviewPresentation 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 thingsCustom agenda views* Storing searches:: Type once, use often* Block agenda:: All the stuff you need in a single buffer* Setting Options:: Changing the rulesMarkup 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 documentsStructural 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 exportedEmbedded La@TeX{}* 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 formulasExporting* 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 La@TeX{}, 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 formatHTML 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* 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 browserLa@TeX{} 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 La@TeX{} code* Tables in LaTeX export:: Options for exporting tables to La@TeX{}* Images in LaTeX export:: How to insert figures into La@TeX{} output* Beamer class export:: Turning the file into a presentationDocBook 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 charactersPublishing* Configuration:: Defining projects* Uploading files:: How to get files up on the server* Sample configuration:: Example projects* Triggering publication:: Publication commandsConfiguration* 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 pagesSample configuration* Simple example:: One-component publishing* Complex example:: A multi-component publishing exampleWorking 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 lineHeader arguments* Using header arguments:: Different ways to set header arguments* Specific header arguments:: List of header argumentsUsing 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 valuesSpecific 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 directory for code block execution* exports:: Export code and/or results* tangle:: Toggle tangling and specify file name* 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 executableMiscellaneous* Completion:: M-TAB knows what you need* 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 packagesInteraction with other packages* Cooperation:: Packages Org cooperates with* Conflicts:: Packages that lead to conflictsHacking* 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 La@TeX{} 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 entriesTables 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 listsMobileOrg* Setting up the staging area:: Where to interact with the mobile device* Pushing to MobileOrg:: Uploading Org files and agendas* Pulling from MobileOrg:: Integrating captured and flagged items@end detailmenu@end menu@node Introduction, Document Structure, Top, Top@chapter Introduction@cindex introduction@menu* Summary:: Brief summary of what Org does* Installation:: How to install a downloaded version of Org* Activation:: How to activate Org for certain buffers* Feedback:: Bug reports, ideas, patches etc.* Conventions:: Type-setting conventions in the manual@end menu@node Summary, Installation, Introduction, Introduction@section Summary@cindex summaryOrg is a mode for keeping notes, maintaining TODO lists, and doingproject planning with a fast and effective plain-text system.Org develops organizational tasks around NOTES files that containlists or information about projects as plain text. Org isimplemented on top of Outline mode, which makes it possible to keep thecontent of large files well structured. Visibility cycling andstructure editing help to work with the tree. Tables are easily createdwith a built-in table editor. Org supports TODO items, deadlines,timestamps, and scheduling. It dynamically compiles entries into anagenda that utilizes and smoothly integrates much of the Emacs calendarand 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 astructured ASCII file, as HTML, or (TODO and agenda items only) as aniCalendar file. It can also serve as a publishing tool for a set oflinked web pages.As a project planning environment, Org works by adding metadata to outlinenodes. Based on this data, specific entries can be extracted in queries andcreate dynamic @i{agenda views}.Org mode contains the Org Babel environment which allows to work withembedded source code block in a file, to facilitate code evaluation,documentation, and tangling.Org's automatic, context-sensitive table editor with spreadsheetcapabilities can be integrated into any major mode by activating theminor Orgtbl mode. Using a translation step, it can be used to maintaintables in arbitrary file types, for example in La@TeX{}. The structureediting and list creation capabilities can be used outside Org withthe minor Orgstruct mode.Org keeps simple things simple. When first fired up, it shouldfeel like a straightforward, easy to use outliner. Complexity is notimposed, but a large amount of functionality is available when you needit. Org is a toolbox and can be used in different ways and for differentends, for example:@example@r{@bullet{} an outline extension with visibility cycling and structure editing}@r{@bullet{} an ASCII system and table editor for taking structured notes}@r{@bullet{} a TODO list editor}@r{@bullet{} a full agenda and planner with deadlines and work scheduling}@pindex GTD, Getting Things Done@r{@bullet{} an environment in which to implement David Allen's GTD system}@r{@bullet{} a simple hypertext system, with HTML and La@TeX{} export}@r{@bullet{} a publishing tool to create a set of interlinked webpages}@r{@bullet{} an environment for literate programming}@end example@cindex FAQThere is a website for Org which provides links to the newestversion of Org, as well as additional information, frequently askedquestions (FAQ), links to tutorials, etc@. This page is located at@uref{http://orgmode.org}.@page@node Installation, Activation, Summary, Introduction@section Installation@cindex installation@cindex XEmacs@b{Important:} @i{If you are using a version of Org that is part of the Emacsdistribution or an XEmacs package, please skip this section and go directlyto @ref{Activation}.}If you have downloaded Org from the Web, either as a distribution @file{.zip}or @file{.tar} file, or as a Git archive, you must take the following stepsto install it: go into the unpacked Org distribution directory and edit thetop section of the file @file{Makefile}. You must set the name of the Emacsbinary (likely either @file{emacs} or @file{xemacs}), and the paths to thedirectories where local Lisp and Info files are kept. If you don't haveaccess to the system-wide directories, you can simply run Org directly fromthe distribution directory by adding the @file{lisp} subdirectory to theEmacs load path. To do this, add the following line to @file{.emacs}:@example(setq load-path (cons "~/path/to/orgdir/lisp" load-path))@end example@noindentIf you plan to use code from the @file{contrib} subdirectory, do a similarstep for this directory:@example(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))@end example@sp 2@cartoucheXEmacs users now need to install the file @file{noutline.el} fromthe @file{xemacs} sub-directory of the Org distribution. Use thecommand:@example make install-noutline@end example@end cartouche@sp 2@noindent Now byte-compile the Lisp files with the shell command:@examplemake@end example@noindent If you are running Org from the distribution directory, this isall. If you want to install Org into the system directories, use (asadministrator)@examplemake install@end exampleInstalling Info files is system dependent, because of differences in the@file{install-info} program. In Debian it copies the info files into thecorrect directory and modifies the info directory file. In many othersystems, the files need to be copied to the correct directory separately, and@file{install-info} then only modifies the directory file. Check your systemdocumentation to find out which of the following commands you need:@examplemake install-infomake install-info-debian@end exampleThen add the following line to @file{.emacs}. It is needed so thatEmacs can autoload functions that are located in files not immediately loadedwhen Org-mode starts.@lisp(require 'org-install)@end lispDo not forget to activate Org as described in the following section.@page@node Activation, Feedback, Installation, Introduction@section Activation@cindex activation@cindex autoload@cindex global key bindings@cindex key bindings, globalAdd the following lines to your @file{.emacs} file. The last three linesdefine @emph{global} keys for the commands @command{org-store-link},@command{org-agenda}, and @command{org-iswitchb}---please choose suitablekeys yourself.@lisp;; The following lines are always needed. Choose your own keys.(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))(global-set-key "\C-cl" 'org-store-link)(global-set-key "\C-ca" 'org-agenda)(global-set-key "\C-cb" 'org-iswitchb)@end lispFurthermore, you must activate @code{font-lock-mode} in Orgbuffers, because significant functionality depends on font-locking beingactive. You can do this with either one of the following two lines(XEmacs users must use the second option):@lisp(global-font-lock-mode 1) ; for all buffers(add-hook 'org-mode-hook 'turn-on-font-lock) ; Org buffers only@end lisp@cindex Org-mode, turning onWith this setup, all files with extension @samp{.org} will be putinto Org-mode. As an alternative, make the first line of a file looklike this:@exampleMY PROJECTS -*- mode: org; -*-@end example@vindex org-insert-mode-line-in-empty-file@noindent which will select Org-mode for this buffer no matter whatthe file's name is. See also the variable@code{org-insert-mode-line-in-empty-file}.Many commands in Org work on the region if the region is @i{active}. To makeuse of this, you need to have @code{transient-mark-mode}(@code{zmacs-regions} in XEmacs) turned on. In Emacs 23 this is the default,in Emacs 22 you need to do this yourself with@lisp(transient-mark-mode 1)@end lisp@noindent If you do not like @code{transient-mark-mode}, you can create anactive region by using the mouse to select a region, or pressing@kbd{C-@key{SPC}} twice before moving the cursor.@node Feedback, Conventions, Activation, Introduction@section Feedback@cindex feedback@cindex bug reports@cindex maintainer@cindex authorIf you find problems with Org, or if you have questions, remarks, or ideasabout it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.If you are not a member of the mailing list, your mail will be passed to thelist after a moderator has approved it.For bug reports, please provide as much information as possible, includingthe version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org(@kbd{M-x org-version @key{RET}}), as well as the Org related setup in@file{.emacs}. The easiest way to do this is to use the command@example@kbd{M-x org-submit-bug-report}@end example@noindent which will put all this information into an Emacs mail buffer sothat you only need to add your description. If you re not sending the Emailfrom 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 tocreate one). Often a small example file helps, along with clear informationabout:@enumerate@item What exactly did you do?@item What did you expect to happen?@item What happened instead?@end enumerate@noindent Thank you for helping to improve this mode.@subsubheading How to create a useful backtrace@cindex backtrace of an errorIf working with Org produces an error with a message you don'tunderstand, you may have hit a bug. The best way to report this is byproviding, in addition to what was mentioned above, a @emph{backtrace}.This is information from the built-in debugger about where and how theerror occurred. Here is how to produce a useful backtrace:@enumerate@itemReload uncompiled versions of all Org-mode Lisp files. The backtracecontains much more information if it is produced with uncompiled code.To do this, use@exampleC-u M-x org-reload RET@end example@noindentor select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from themenu.@itemGo to the @code{Options} menu and select @code{Enter Debugger on Error}(XEmacs has this option in the @code{Troubleshooting} sub-menu).@itemDo whatever you have to do to hit the error. Don't forget todocument the steps you take.@itemWhen you hit the error, a @file{*Backtrace*} buffer will appear on thescreen. Save this buffer to a file (for example using @kbd{C-x C-w}) andattach it to your bug report.@end enumerate@node Conventions, , Feedback, Introduction@section Typesetting conventions used in this manualOrg uses three types of keywords: TODO keywords, tags, and propertynames. In this manual we use the following conventions:@table @code@item TODO@itemx WAITINGTODO keywords are written with all capitals, even if they areuser-defined.@item boss@itemx ARCHIVEUser-defined tags are written in lowercase; built-in tags with specialmeaning are written with all capitals.@item Release@itemx PRIORITYUser-defined properties are capitalized; built-in properties withspecial meaning are written with all capitals.@end table@node Document Structure, Tables, Introduction, Top@chapter Document structure@cindex document structure@cindex structure of documentOrg is based on Outline mode and provides flexible commands toedit the structure of the document.@menu* Outlines:: Org is based on Outline mode* Headlines:: How to typeset Org tree headlines* Visibility cycling:: Show and hide, much simplified* Motion:: Jumping to other headlines* Structure editing:: Changing sequence and level of headlines* Sparse trees:: Matches embedded in context* Plain lists:: Additional structure within an entry* Drawers:: Tucking stuff away* Blocks:: Folding blocks* Footnotes:: How footnotes are defined in Org's syntax* Orgstruct mode:: Structure editing outside Org@end menu@node Outlines, Headlines, Document Structure, Document Structure@section Outlines@cindex outlines@cindex Outline modeOrg is implemented on top of Outline mode. Outlines allow adocument to be organized in a hierarchical structure, which (at leastfor me) is the best representation of notes and thoughts. An overviewof this structure is achieved by folding (hiding) large parts of thedocument to show only the general document structure and the partscurrently being worked on. Org greatly simplifies the use ofoutlines by compressing the entire show/hide functionality into a singlecommand, @command{org-cycle}, which is bound to the @key{TAB} key.@node Headlines, Visibility cycling, Outlines, Document Structure@section Headlines@cindex headlines@cindex outline tree@vindex org-special-ctrl-a/e@vindex org-special-ctrl-k@vindex org-ctrl-k-protect-subtreeHeadlines define the structure of an outline tree. The headlines in Orgstart with one or more stars, on the left margin@footnote{See the variables@code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and@code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},@kbd{C-e}, and @kbd{C-k} in headlines.}. For example:@example* Top level headline** Second level*** 3rd level some text*** 3rd level more text* Another top level headline@end example@noindent Some people find the many stars too noisy and would prefer anoutline that has whitespace followed by a single star as headlinestarters. @ref{Clean view}, describes a setup to realize this.@vindex org-cycle-separator-linesAn empty line after the end of a subtree is considered part of it andwill be hidden when the subtree is folded. However, if you leave atleast two empty lines, one empty line will remain visible after foldingthe subtree, in order to structure the collapsed view. See thevariable @code{org-cycle-separator-lines} to modify this behavior.@node Visibility cycling, Motion, Headlines, Document Structure@section Visibility cycling@cindex cycling, visibility@cindex visibility cycling@cindex trees, visibility@cindex show hidden text@cindex hide textOutlines make it possible to hide parts of the text in the buffer.Org uses just two commands, bound to @key{TAB} and@kbd{S-@key{TAB}} to change the visibility in the buffer.@cindex subtree visibility states@cindex subtree cycling@cindex folded, subtree visibility state@cindex children, subtree visibility state@cindex subtree, subtree visibility state@table @kbd@kindex @key{TAB}@item @key{TAB}@emph{Subtree cycling}: Rotate current subtree among the states@example,-> FOLDED -> CHILDREN -> SUBTREE --.'-----------------------------------'@end example@vindex org-cycle-emulate-tab@vindex org-cycle-global-at-bobThe cursor must be on a headline for this to work@footnote{see, however,the option @code{org-cycle-emulate-tab}.}. When the cursor is at thebeginning of the buffer and the first line is not a headline, then@key{TAB} actually runs global cycling (see below)@footnote{see theoption @code{org-cycle-global-at-bob}.}. Also when called with a prefixargument (@kbd{C-u @key{TAB}}), global cycling is invoked.@cindex global visibility states@cindex global cycling@cindex overview, global visibility state@cindex contents, global visibility state@cindex show all, global visibility state@kindex S-@key{TAB}@item S-@key{TAB}@itemx C-u @key{TAB}@emph{Global cycling}: Rotate the entire buffer among the states@example,-> OVERVIEW -> CONTENTS -> SHOW ALL --.'--------------------------------------'@end exampleWhen @kbd{S-@key{TAB}} is called with a numeric prefix argument N, theCONTENTS view up to headlines of level N will be shown. Note that insidetables, @kbd{S-@key{TAB}} jumps to the previous field.@cindex show all, command@kindex C-u C-u C-u @key{TAB}@item C-u C-u C-u @key{TAB}Show all, including drawers.@kindex C-c C-r@item C-c C-rReveal context around point, showing the current entry, the following headingand the hierarchy above. Useful for working near a location that has beenexposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command(@pxref{Agenda commands}). With a prefix argument show, on eachlevel, all sibling headings. With double prefix arg, also show the entiresubtree of the parent.@kindex C-c C-k@item C-c C-kExpose all the headings of the subtree, CONTENT view for just one subtree.@kindex C-c C-x b@item C-c C-x bShow the current subtree in an indirect buffer@footnote{The indirectbuffer@ifinfo(@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual})@end ifinfo@ifnotinfo(see the Emacs manual for more information about indirect buffers)@end ifnotinfowill contain the entire buffer, but will be narrowed to the currenttree. Editing the indirect buffer will also change the original buffer,but without affecting visibility in that buffer.}. With a numericprefix argument N, go up to level N and then take that tree. If N isnegative then go up that many levels. With a @kbd{C-u} prefix, do not removethe previously used indirect buffer.@end table@vindex org-startup-folded@cindex @code{overview}, STARTUP keyword@cindex @code{content}, STARTUP keyword@cindex @code{showall}, STARTUP keyword@cindex @code{showeverything}, STARTUP keywordWhen Emacs first visits an Org file, the global state is set toOVERVIEW, i.e. only the top level headlines are visible. This can beconfigured through the variable @code{org-startup-folded}, or on aper-file basis by adding one of the following lines anywhere in thebuffer:@example#+STARTUP: overview#+STARTUP: content#+STARTUP: showall#+STARTUP: showeverything@end example@cindex property, VISIBILITY@noindentFurthermore, any entries with a @samp{VISIBILITY} property (@pxref{Propertiesand Columns}) will get their visibility adapted accordingly. Allowed valuesfor this property are @code{folded}, @code{children}, @code{content}, and@code{all}.@table @kbd@kindex C-u C-u @key{TAB}@item C-u C-u @key{TAB}Switch back to the startup visibility of the buffer, i.e. whatever isrequested by startup options and @samp{VISIBILITY} properties in individualentries.@end table@node Motion, Structure editing, Visibility cycling, Document Structure@section Motion@cindex motion, between headlines@cindex jumping, to headlines@cindex headline navigationThe following commands jump to other headlines in the buffer.@table @kbd@kindex C-c C-n@item C-c C-nNext heading.@kindex C-c C-p@item C-c C-pPrevious heading.@kindex C-c C-f@item C-c C-fNext heading same level.@kindex C-c C-b@item C-c C-bPrevious heading same level.@kindex C-c C-u@item C-c C-uBackward to higher level heading.@kindex C-c C-j@item C-c C-jJump to a different place without changing the current outlinevisibility. Shows the document structure in a temporary buffer, whereyou can use the following keys to find your destination:@vindex org-goto-auto-isearch@example@key{TAB} @r{Cycle visibility.}@key{down} / @key{up} @r{Next/previous visible headline.}@key{RET} @r{Select this location.}@kbd{/} @r{Do a Sparse-tree search}@r{The following keys work if you turn off @code{org-goto-auto-isearch}}n / p @r{Next/previous visible headline.}f / b @r{Next/previous headline same level.}u @r{One level up.}0-9 @r{Digit argument.}q @r{Quit}@end example@vindex org-goto-interface@noindentSee also the variable @code{org-goto-interface}.@end table@node Structure editing, Sparse trees, Motion, Document Structure@section Structure editing@cindex structure editing@cindex headline, promotion and demotion@cindex promotion, of subtrees@cindex demotion, of subtrees@cindex subtree, cut and paste@cindex pasting, of subtrees@cindex cutting, of subtrees@cindex copying, of subtrees@cindex sorting, of subtrees@cindex subtrees, cut and paste@table @kbd@kindex M-@key{RET}@item M-@key{RET}@vindex org-M-RET-may-split-lineInsert new heading with same level as current. If the cursor is in aplain list item, a new item is created (@pxref{Plain lists}). To forcecreation of a new headline, use a prefix argument, or first press @key{RET}to get to the beginning of the next line. When this command is used inthe middle of a line, the line is split and the rest of the line becomesthe new headline@footnote{If you do not want the line to be split,customize the variable @code{org-M-RET-may-split-line}.}. If thecommand is used at the beginning of a headline, the new headline iscreated 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 isused at the end of a folded subtree (i.e. behind the ellipses at the endof a headline), then a headline like the current one will be insertedafter the end of the subtree.@kindex C-@key{RET}@item C-@key{RET}Just like @kbd{M-@key{RET}}, except when adding a new heading below thecurrent heading, the new heading is placed after the body instead of beforeit. This command works from anywhere in the entry.@kindex M-S-@key{RET}@item M-S-@key{RET}@vindex org-treat-insert-todo-heading-as-state-changeInsert new TODO entry with same level as current heading. See also thevariable @code{org-treat-insert-todo-heading-as-state-change}.@kindex C-S-@key{RET}@item C-S-@key{RET}Insert new TODO entry with same level as current heading. Like@kbd{C-@key{RET}}, the new headline will be inserted after the currentsubtree.@kindex @key{TAB}@item @key{TAB} @r{in new, empty entry}In a new entry with no text yet, the first @key{TAB} demotes the entry tobecome a child of the previous one. The next @key{TAB} makes it a parent,and so on, all the way to top level. Yet another @key{TAB}, and you are backto the initial level.@kindex M-@key{left}@item M-@key{left}Promote current heading by one level.@kindex M-@key{right}@item M-@key{right}Demote current heading by one level.@kindex M-S-@key{left}@item M-S-@key{left}Promote the current subtree by one level.@kindex M-S-@key{right}@item M-S-@key{right}Demote the current subtree by one level.@kindex M-S-@key{up}@item M-S-@key{up}Move subtree up (swap with previous subtree of samelevel).@kindex M-S-@key{down}@item M-S-@key{down}Move subtree down (swap with next subtree of same level).@kindex C-c C-x C-w@item C-c C-x C-wKill subtree, i.e. remove it from buffer but save in kill ring.With a numeric prefix argument N, kill N sequential subtrees.@kindex C-c C-x M-w@item C-c C-x M-wCopy subtree to kill ring. With a numeric prefix argument N, copy the Nsequential subtrees.@kindex C-c C-x C-y@item C-c C-x C-yYank subtree from kill ring. This does modify the level of the subtree tomake sure the tree fits in nicely at the yank position. The yank level canalso be specified with a numeric prefix argument, or by yanking after aheadline marker like @samp{****}.@kindex C-y@item C-y@vindex org-yank-adjusted-subtrees@vindex org-yank-folded-subtreesDepending on the variables @code{org-yank-adjusted-subtrees} and@code{org-yank-folded-subtrees}, Org's internal @code{yank} command willpaste subtrees folded and in a clever way, using the same command as @kbd{C-cC-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 textpreviously visible. Any prefix argument to this command will force a normal@code{yank} to be executed, with the prefix passed along. A good way toforce a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after ayank, it will yank previous kill items plainly, without adjustment andfolding.@kindex C-c C-x c@item C-c C-x cClone a subtree by making a number of sibling copies of it. You will beprompted for the number of copies to make, and you can also specify if anytimestamps 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. Formore details, see the docstring of the command@code{org-clone-subtree-with-time-shift}.@kindex C-c C-w@item C-c C-wRefile entry or region to a different location. @xref{Refiling notes}.@kindex C-c ^@item C-c ^Sort same-level entries. When there is an active region, all entries in theregion will be sorted. Otherwise the children of the current headline aresorted. The command prompts for the sorting method, which can bealphabetically, 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 valueof a property. Reverse sorting is possible as well. You can also supplyyour own function to extract the sorting key. With a @kbd{C-u} prefix,sorting will be case-sensitive. With two @kbd{C-u C-u} prefixes, duplicateentries will also be removed.@kindex C-x n s@item C-x n sNarrow buffer to current subtree.@kindex C-x n w@item C-x n wWiden buffer to remove narrowing.@kindex C-c *@item C-c *Turn a normal line or plain list item into a headline (so that it becomes asubheading at its location). Also turn a headline into a normal line byremoving the stars. If there is an active region, turn all lines in theregion into headlines. If the first line in the region was an item, turnonly the item lines into headlines. Finally, if the first line is aheadline, remove the stars from all headlines in the region.@end table@cindex region, active@cindex active region@cindex transient mark modeWhen there is an active region (Transient Mark mode), promotion anddemotion work on all headlines in the region. To select a region ofheadlines, it is best to place both point and mark at the beginning of aline, mark at the beginning of the first headline, and point at the linejust after the last headline to change. Note that when the cursor isinside a table (@pxref{Tables}), the Meta-Cursor keys have differentfunctionality.@node Sparse trees, Plain lists, Structure editing, Document Structure@section Sparse trees@cindex sparse trees@cindex trees, sparse@cindex folding, sparse trees@cindex occur, command@vindex org-show-hierarchy-above@vindex org-show-following-heading@vindex org-show-siblings@vindex org-show-entry-belowAn important feature of Org-mode is the ability to construct @emph{sparsetrees} for selected information in an outline tree, so that the entiredocument is folded as much as possible, but the selected information is madevisible along with the headline structure above it@footnote{See also thevariables @code{org-show-hierarchy-above}, @code{org-show-following-heading},@code{org-show-siblings}, and @code{org-show-entry-below} for detailedcontrol on how much context is shown around each match.}. Just try it outand you will see immediately how it works.Org-mode contains several commands creating such trees, all thesecommands can be accessed through a dispatcher:@table @kbd@kindex C-c /@item C-c /This prompts for an extra key to select a sparse-tree creating command.@kindex C-c / r@item C-c / r@vindex org-remove-highlights-with-changeOccur. Prompts for a regexp and shows a sparse tree with all matches. Ifthe match is in a headline, the headline is made visible. If the match is inthe body of an entry, headline and body are made visible. In order toprovide minimal context, also the full hierarchy of headlines above the matchis shown, as well as the headline following the match. Each match is alsohighlighted; the highlights disappear when the buffer is changed by anediting command@footnote{This depends on the option@code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.When called with a @kbd{C-u} prefix argument, previous highlights are kept,so several calls to this command can be stacked.@end table@noindent@vindex org-agenda-custom-commandsFor frequently used sparse trees of specific search strings, you canuse the variable @code{org-agenda-custom-commands} to define fastkeyboard access to specific sparse trees. These commands will then beaccessible through the agenda dispatcher (@pxref{Agenda dispatcher}).For example:@lisp(setq org-agenda-custom-commands '(("f" occur-tree "FIXME")))@end lisp@noindent will define the key @kbd{C-c a f} as a shortcut for creatinga sparse tree matching the string @samp{FIXME}.The other sparse tree commands select headings based on TODO keywords,tags, or properties and will be discussed later in this manual.@kindex C-c C-e v@cindex printing sparse trees@cindex visible text, printingTo print a sparse tree, you can use the Emacs command@code{ps-print-buffer-with-faces} which does not print invisible partsof the document @footnote{This does not work under XEmacs, becauseXEmacs uses selective display for outlining, not text properties.}.Or you can use the command @kbd{C-c C-e v} to export only the visiblepart of the document and print the resulting file.@node Plain lists, Drawers, Sparse trees, Document Structure@section Plain lists@cindex plain lists@cindex lists, plain@cindex lists, ordered@cindex ordered listsWithin an entry of the outline tree, hand-formatted lists can provideadditional structure. They also provide a way to create lists ofcheckboxes (@pxref{Checkboxes}). Org supports editing such lists,and the HTML exporter (@pxref{Exporting}) parses and formats them.Org knows ordered lists, unordered lists, and description lists.@itemize @bullet@item@emph{Unordered} list items start with @samp{-}, @samp{+}, or@samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented orthey will be seen as top-level headlines. Also, when you are hiding leadingstars to get a clean outline view, plain list items starting with a star arevisually indistinguishable from true headlines. In short: even though@samp{*} is supported, it may be better to not use it for plain list items.}as bullets.@item@emph{Ordered} list items start with a numeral followed by either a period ora right parenthesis, such as @samp{1.} or @samp{1)}. If you want a list tostart a different value (e.g. 20), start the text of the item with@code{[@@start:20]}.@item@emph{Description} list items are unordered list items, and contain theseparator @samp{ :: } to separate the description @emph{term} from thedescription.@end itemize@vindex org-empty-line-terminates-plain-listsItems belonging to the same list must have the same indentation on the firstline. In particular, if an ordered list reaches number @samp{10.}, then the2--digit numbers must be written left-aligned with the other numbers in thelist. Indentation also determines the end of a list item. It ends beforethe next line that is indented like the bullet/number, or less. Empty linesare part of the previous item, so you can have several paragraphs in oneitem. If you would like an empty line to terminate all currently open plainlists, configure the variable @code{org-empty-line-terminates-plain-lists}.Here is an example:@example@group** Lord of the Rings My favorite scenes are (in this order) 1. The attack of the Rohirrim 2. 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 - on DVD only He makes a really funny face when it happens. But in the end, no individual scenes matter but the film as a whole. Important actors in this film are: - @b{Elijah Wood} :: He plays Frodo - @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember him very well from his role as Mikey Walsh in @i{The Goonies}.@end group@end exampleOrg supports these lists by tuning filling and wrapping commands to deal withthem correctly@footnote{Org only changes the filling settings for Emacs. ForXEmacs, you should use Kyle E. Jones' @file{filladapt.el}. To turn this on,put into @file{.emacs}: @code{(require 'filladapt)}}, and by exporting themproperly (@pxref{Exporting}). Since indentation is what governs thestructure of these lists, many structural constructs like @code{#+BEGIN_...}blocks can be indented to signal that they should be part of a list item.@vindex org-list-demote-modify-bulletIf you find that using a different bullet for a sub-list (than that used forthe current list-level) improves readability, customize the variable@code{org-list-demote-modify-bullet}.The following commands act on items when the cursor is in the first lineof an item (the line with the bullet or number).@table @kbd@kindex @key{TAB}@item @key{TAB}@vindex org-cycle-include-plain-listsItems can be folded just like headline levels. Normally this works only ifthe cursor is on a plain list item. For more details, see the variable@code{org-cycle-include-plain-lists}. to @code{integrate}, plain list itemswill be treated like low-level. The level of an item is then given by theindentation of the bullet/number. Items are always subordinate to realheadlines, however; the hierarchies remain completely separated.If @code{org-cycle-include-plain-lists} has not been set, @key{TAB}fixes the indentation of the current line in a heuristic way.@kindex M-@key{RET}@item M-@key{RET}@vindex org-M-RET-may-split-lineInsert new item at current level. With a prefix argument, force a newheading (@pxref{Structure editing}). If this command is used in the middleof a line, the line is @emph{split} and the rest of the line becomes the newitem@footnote{If you do not want the line to be split, customize the variable@code{org-M-RET-may-split-line}.}. If this command is executed in the@emph{whitespace before a bullet or number}, the new item is created@emph{before} the current item. If the command is executed in the whitespace before the text that is part of an item but does not contain thebullet, a bullet is added to the current line.@kindex M-S-@key{RET}@item M-S-@key{RET}Insert a new item with a checkbox (@pxref{Checkboxes}).@kindex @key{TAB}@item @key{TAB} @r{in new, empty item}In a new item with no text yet, the first @key{TAB} demotes the item tobecome a child of the previous one. The next @key{TAB} makes it a parent,and so on, all the way to the left margin. Yet another @key{TAB}, and youare back to the initial level.@kindex S-@key{up}@kindex S-@key{down}@item S-@key{up}@itemx S-@key{down}@cindex shift-selection-mode@vindex org-support-shift-selectJump to the previous/next item in the current list, but only if@code{org-support-shift-select} is off. If not, you can still use paragraphjumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quitesimilar effect.@kindex M-S-@key{up}@kindex M-S-@key{down}@item M-S-@key{up}@itemx M-S-@key{down}Move the item including subitems up/down (swap with previous/next itemof same indentation). If the list is ordered, renumbering isautomatic.@kindex M-@key{left}@kindex M-@key{right}@item M-@key{left}@itemx M-@key{right}Decrease/increase the indentation of an item, leaving children alone.@kindex M-S-@key{left}@kindex M-S-@key{right}@item M-S-@key{left}@itemx M-S-@key{right}Decrease/increase the indentation of the item, including subitems.Initially, the item tree is selected based on current indentation.When these commands are executed several times in direct succession,the initially selected region is used, even if the new indentationwould imply a different hierarchy. To use the new hierarchy, breakthe command chain with a cursor motion or so.@kindex C-c C-c@item C-c C-cIf there is a checkbox (@pxref{Checkboxes}) in the item line, toggle thestate of the checkbox. If not, this command makes sure that all theitems on this list level use the same bullet. Furthermore, if this isan ordered list, make sure the numbering is OK.@kindex C-c -@item C-c -Cycle the entire list level through the different itemize/enumerate bullets(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). With a numeric prefixargument N, select the Nth bullet from this list. If there is an activeregion when calling this, all lines will be converted to list items. If thefirst line already was a list item, any item markers will be removed from thelist. Finally, even without an active region, a normal line will beconverted into a list item.@kindex C-c *@item C-c *Turn a plain list item into a headline (so that it becomes a subheading atits location). @xref{Structure editing}, for a detailed explanation.@kindex S-@key{left}@kindex S-@key{right}@item S-@key{left}/@key{right}@vindex org-support-shift-selectThis command also cycles bullet styles when the cursor in on the bullet oranywhere in an item line, details depending on@code{org-support-shift-select}.@kindex C-c ^@item C-c ^Sort the plain list. You will be prompted for the sorting method:numerically, alphabetically, by time, or by custom function.@end table@node Drawers, Blocks, Plain lists, Document Structure@section Drawers@cindex drawers@cindex #+DRAWERS@cindex visibility cycling, drawers@vindex org-drawersSometimes you want to keep information associated with an entry, but younormally don't want to see it. For this, Org-mode has @emph{drawers}.Drawers need to be configured with the variable@code{org-drawers}@footnote{You can define drawers on a per-file basiswith a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawerslook like this:@example** This is a headline Still outside the drawer :DRAWERNAME: This is inside the drawer. :END: After the drawer.@end exampleVisibility cycling (@pxref{Visibility cycling}) on the headline will hide andshow the entry, but keep the drawer collapsed to a single line. In order tolook inside the drawer, you need to move the cursor to the drawer line andpress @key{TAB} there. Org-mode uses the @code{PROPERTIES} drawer forstoring properties (@pxref{Properties and Columns}), and you can also arrangefor state change notes (@pxref{Tracking TODO state changes}) and clock times(@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If youwant to store a quick note in the LOGBOOK drawer, in a similar way as this isdone by state changes, use@table @kbd@kindex C-c C-z@item C-c C-zAdd a time-stamped note to the LOGBOOK drawer.@end table@node Blocks, Footnotes, Drawers, Document Structure@section Blocks@vindex org-hide-block-startup@cindex blocks, foldingOrg-mode uses begin...end blocks for various purposes from including sourcecode examples (@pxref{Literal examples}) to capturing time logginginformation (@pxref{Clocking work time}). These blocks can be folded andunfolded by pressing TAB in the begin line. You can also get all blocksfolded at startup by configuring the variable @code{org-hide-block-startup}or on a per-file basis by using@cindex @code{hideblocks}, STARTUP keyword@cindex @code{nohideblocks}, STARTUP keyword@example#+STARTUP: hideblocks#+STARTUP: nohideblocks@end example@node Footnotes, Orgstruct mode, Blocks, Document Structure@section Footnotes@cindex footnotesOrg-mode supports the creation of footnotes. In contrast to the@file{footnote.el} package, Org-mode's footnotes are designed for work on alarger document, not only for one-off documents like emails. The basicsyntax is similar to the one used by @file{footnote.el}, i.e. a footnote isdefined in a paragraph that is started by a footnote marker in squarebrackets in column 0, no indentation allowed. If you need a paragraph breakinside a footnote, use the La@TeX{} idiom @samp{\par}. The footnote referenceis simply the marker in square brackets, inside text. For example:@exampleThe Org homepage[fn:1] now looks a lot better than it used to....[fn:1] The link is: http://orgmode.org@end exampleOrg-mode extends the number-based syntax to @emph{named} footnotes andoptional inline definition. Using plain numbers as markers (as@file{footnote.el} does) is supported for backward compatibility, but notencouraged because of possible conflicts with La@TeX{} snippets (@pxref{EmbeddedLaTeX}). Here are the valid references:@table @code@item [1]A plain numeric footnote marker. Compatible with @file{footnote.el}, but notrecommended because something like @samp{[1]} could easily be part of a codesnippet.@item [fn:name]A named footnote reference, where @code{name} is a unique label word, or, forsimplicity of automatic creation, a number.@item [fn:: This is the inline definition of this footnote]A La@TeX{}-like anonymous footnote where the definition is given directly at thereference point.@item [fn:name: a definition]An inline definition of a footnote, which also specifies a name for the note.Since Org allows multiple references to the same note, you can then use@code{[fn:name]} to create additional references.@end table@vindex org-footnote-auto-labelFootnote labels can be created automatically, or you can create names yourself.This is handled by the variable @code{org-footnote-auto-label} and itscorresponding @code{#+STARTUP} keywords, see the docstring of that variablefor details.@noindent The following command handles footnotes:@table @kbd@kindex C-c C-x f@item C-c C-x fThe footnote action command.When the cursor is on a footnote reference, jump to the definition. When itis at a definition, jump to the (first) reference.@vindex org-footnote-define-inline@vindex org-footnote-section@vindex org-footnote-auto-adjustOtherwise, create a new footnote. Depending on the variable@code{org-footnote-define-inline}@footnote{The corresponding in-buffersetting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, thedefinition will be placed right into the text as part of the reference, orseparately into the location determined by the variable@code{org-footnote-section}.When this command is called with a prefix argument, a menu of additionaloptions is offered:@examples @r{Sort the footnote definitions by reference sequence. During editing,} @r{Org makes no effort to sort footnote definitions into a particular} @r{sequence. If you want them sorted, use this command, which will} @r{also move entries according to @code{org-footnote-section}. Automatic} @r{sorting after each insertion/deletion can be configured using the} @r{variable @code{org-footnote-auto-adjust}.}r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering} @r{after each insertion/deletion can be configured using the variable} @r{@code{org-footnote-auto-adjust}.}S @r{Short for first @code{r}, then @code{s} action.}n @r{Normalize the footnotes by collecting all definitions (including} @r{inline definitions) into a special section, and then numbering them} @r{in sequence. The references will then also be numbers. This is} @r{meant to be the final step before finishing a document (e.g. sending} @r{off an email). The exporters do this automatically, and so could} @r{something like @code{message-send-hook}.}d @r{Delete the footnote at point, and all definitions of and references} @r{to it.}@end exampleDepending on the variable @code{org-footnote-auto-adjust}@footnote{thecorresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},renumbering and sorting footnotes can be automatic after each insertion ordeletion.@kindex C-c C-c@item C-c C-cIf the cursor is on a footnote reference, jump to the definition. If it is athe definition, jump back to the reference. When called at a footnotelocation with a prefix argument, offer the same menu as @kbd{C-c C-x f}.@kindex C-c C-o@kindex mouse-1@kindex mouse-2@item C-c C-o @r{or} mouse-1/2Footnote labels are also links to the corresponding definition/reference, andyou can use the usual commands to follow these links.@end table@node Orgstruct mode, , Footnotes, Document Structure@section The Orgstruct minor mode@cindex Orgstruct mode@cindex minor mode for structure editingIf you like the intuitive way the Org-mode structure editing and listformatting works, you might want to use these commands in other modes likeText mode or Mail mode as well. The minor mode @code{orgstruct-mode} makesthis possible. Toggle the mode with @kbd{M-x orgstruct-mode}, orturn it on by default, for example in Mail mode, with one of:@lisp(add-hook 'mail-mode-hook 'turn-on-orgstruct)(add-hook 'mail-mode-hook 'turn-on-orgstruct++)@end lispWhen this mode is active and the cursor is on a line that looks to Org like aheadline or the first line of a list item, most structure editing commandswill work, even if the same keys normally have different functionality in themajor mode you are using. If the cursor is not in one of those speciallines, Orgstruct mode lurks silently in the shadow. When you use@code{orgstruct++-mode}, Org will also export indentation and autofillsettings into that mode, and detect item context after the first line of anitem.@node Tables, Hyperlinks, Document Structure, Top@chapter Tables@cindex tables@cindex editing tablesOrg comes with a fast and intuitive table editor. Spreadsheet-likecalculations are supported in connection with the Emacs @file{calc}package@ifinfo(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}).@end ifinfo@ifnotinfo(see the Emacs Calculator manual for more information about the Emacscalculator).@end ifnotinfo@menu* Built-in table editor:: Simple tables* Column width and alignment:: Overrule the automatic settings* Column groups:: Grouping to trigger vertical lines* Orgtbl mode:: The table editor as minor mode* The spreadsheet:: The table editor has spreadsheet capabilities* Org-Plot:: Plotting from org tables@end menu@node Built-in table editor, Column width and alignment, Tables, Tables@section The built-in table editor@cindex table editor, built-inOrg makes it easy to format tables in plain ASCII. Any line with@samp{|} as the first non-whitespace character is considered part of atable. @samp{|} is also the column separator. A table might look likethis:@example| Name | Phone | Age ||-------+-------+-----|| Peter | 1234 | 17 || Anna | 4321 | 25 |@end exampleA table is re-aligned automatically each time you press @key{TAB} or@key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves tothe next field (@key{RET} to the next row) and creates new table rowsat the end of the table or before horizontal lines. The indentationof the table is set by the first line. Any line starting with@samp{|-} is considered as a horizontal separator line and will beexpanded on the next re-align to span the whole table width. So, tocreate the above table, you would only type@example|Name|Phone|Age||-@end example@noindent and then press @key{TAB} to align the table and start filling infields. Even faster would be to type @code{|Name|Phone|Age} followed by@kbd{C-c @key{RET}}.@vindex org-enable-table-editor@vindex org-table-auto-blank-fieldWhen typing text into a field, Org treats @key{DEL},@key{Backspace}, and all character keys in a special way, so thatinserting and deleting avoids shifting other fields. Also, whentyping @emph{immediately after the cursor was moved into a new fieldwith @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, thefield is automatically made blank. If this behavior is toounpredictable for you, configure the variables@code{org-enable-table-editor} and @code{org-table-auto-blank-field}.@table @kbd@tsubheading{Creation and conversion}@kindex C-c |@item C-c |Convert the active region to table. If every line contains at least oneTAB 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 prefixargument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-uC-u} forces TAB, and a numeric argument N indicates that at least Nconsecutive spaces, or alternatively a TAB will be the separator.@*If there is no active region, this command creates an empty Orgtable. But it's easier just to start typing, like@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.@tsubheading{Re-aligning and field motion}@kindex C-c C-c@item C-c C-cRe-align the table without moving the cursor.@c@kindex @key{TAB}@item @key{TAB}Re-align the table, move to the next field. Creates a new row ifnecessary.@c@kindex S-@key{TAB}@item S-@key{TAB}Re-align, move to previous field.@c@kindex @key{RET}@item @key{RET}Re-align the table and move down to next row. Creates a new row ifnecessary. At the beginning or end of a line, @key{RET} still doesNEWLINE, so it can be used to split a table.@c@kindex M-a@item M-aMove to beginning of the current table field, or on to the previous field.@kindex M-e@item M-eMove to end of the current table field, or on to the next field.@tsubheading{Column and row editing}@kindex M-@key{left}@kindex M-@key{right}@item M-@key{left}@itemx M-@key{right}Move the current column left/right.@c@kindex M-S-@key{left}@item M-S-@key{left}Kill the current column.@c@kindex M-S-@key{right}@item M-S-@key{right}Insert a new column to the left of the cursor position.@c@kindex M-@key{up}@kindex M-@key{down}@item M-@key{up}@itemx M-@key{down}Move the current row up/down.@c@kindex M-S-@key{up}@item M-S-@key{up}Kill the current row or horizontal line.@c@kindex M-S-@key{down}@item M-S-@key{down}Insert a new row above the current row. With a prefix argument, the line iscreated below the current one.@c@kindex C-c -@item C-c -Insert a horizontal line below current row. With a prefix argument, the lineis created above the current line.@c@kindex C-c @key{RET}@item C-c @key{RET}Insert a horizontal line below current row, and move the cursor into the rowbelow that line.@c@kindex C-c ^@item C-c ^Sort the table lines in the region. The position of point indicates thecolumn to be used for sorting, and the range of lines is the rangebetween the nearest horizontal separator lines, or the entire table. Ifpoint is before the first column, you will be prompted for the sortingcolumn. If there is an active region, the mark specifies the first lineand the sorting column, while point should be in the last line to beincluded into the sorting. The command prompts for the sorting type(alphabetically, numerically, or by time). When called with a prefixargument, alphabetic sorting will be case-sensitive.@tsubheading{Regions}@kindex C-c C-x M-w@item C-c C-x M-wCopy a rectangular region from a table to a special clipboard. Point andmark determine edge fields of the rectangle. If there is no active region,copy just the current field. The process ignores horizontal separator lines.@c@kindex C-c C-x C-w@item C-c C-x C-wCopy a rectangular region from a table to a special clipboard, andblank all fields in the rectangle. So this is the ``cut'' operation.@c@kindex C-c C-x C-y@item C-c C-x C-yPaste a rectangular region into a table.The upper left corner ends up in the current field. All involved fieldswill be overwritten. If the rectangle does not fit into the present table,the table is enlarged as needed. The process ignores horizontal separatorlines.@c@kindex M-@key{RET}@itemx M-@kbd{RET}Wrap several fields in a column like a paragraph. If there is an activeregion, and both point and mark are in the same column, the text in thecolumn is wrapped to minimum width for the given number of lines. A numericprefix argument may be used to change the number of desired lines. If thereis no region, the current field is split at the cursor position and the textfragment to the right of the cursor is prepended to the field one linedown. If there is no region, but you specify a prefix argument, the currentfield is made blank, and the content is appended to the field above.@tsubheading{Calculations}@cindex formula, in tables@cindex calculations, in tables@cindex region, active@cindex active region@cindex transient mark mode@kindex C-c +@item C-c +Sum the numbers in the current column, or in the rectangle defined bythe active region. The result is shown in the echo area and canbe inserted with @kbd{C-y}.@c@kindex S-@key{RET}@item S-@key{RET}@vindex org-table-copy-incrementWhen current field is empty, copy from first non-empty field above. When notempty, copy current field down to next row and move cursor along with it.Depending on the variable @code{org-table-copy-increment}, integer fieldvalues will be incremented during copy. Integers that are too large will notbe incremented. Also, a @code{0} prefix argument temporarily disables theincrement. This key is also used by shift-selection and related modes(@pxref{Conflicts}).@tsubheading{Miscellaneous}@kindex C-c `@item C-c `Edit the current field in a separate window. This is useful for fields thatare not fully visible (@pxref{Column width and alignment}). When called witha @kbd{C-u} prefix, just make the full field visible, so that it can beedited in place.@c@item M-x org-table-importImport a file as a table. The table should be TAB or whitespaceseparated. Use, for example, to import a spreadsheet table or datafrom a database, because these programs generally can writeTAB-separated text files. This command works by inserting the file intothe buffer and then converting the region to a table. Any prefixargument is passed on to the converter, which uses it to determine theseparator.@item C-c |Tables can also be imported by pasting tabular text into the Orgbuffer, selecting the pasted text with @kbd{C-x C-x} and then using the@kbd{C-c |} command (see above under @i{Creation and conversion}).@c@item M-x org-table-export@vindex org-table-export-default-formatExport the table, by default as a TAB-separated file. Use for dataexchange with, for example, spreadsheet or database programs. The formatused to export the file can be configured in the variable@code{org-table-export-default-format}. You may also use properties@code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the filename and the format for table export in a subtree. Org supports quitegeneral formats for exported tables. The exporter format is the same as theformat used by Orgtbl radio tables, see @ref{Translator functions}, for adetailed description.@end tableIf you don't like the automatic table editor because it gets in yourway on lines which you would like to start with @samp{|}, you can turnit off with@lisp(setq org-enable-table-editor nil)@end lisp@noindent Then the only table command that still works is@kbd{C-c C-c} to do a manual re-align.@node Column width and alignment, Column groups, Built-in table editor, Tables@section Column width and alignment@cindex narrow columns in tables@cindex alignment in tablesThe width of columns is automatically determined by the table editor. Andalso the alignment of a column is determined automatically from the fractionof number-like versus non-number fields in the column.Sometimes a single field or a few fields need to carry more text, leading toinconveniently wide columns. Or maybe you want to make a table with severalcolumns having a fixed width, regardless of content. To set@footnote{Thisfeature does not work on XEmacs.} the width of a column, one field anywherein the column may contain just the string @samp{<N>} where @samp{N} is aninteger specifying the width of the column in characters. The next re-alignwill then set the width of this column to this value.@example@group|---+------------------------------| |---+--------|| | | | | <6> || 1 | one | | 1 | one || 2 | two | ----\ | 2 | two || 3 | This is a long chunk of text | ----/ | 3 | This=> || 4 | four | | 4 | four ||---+------------------------------| |---+--------|@end group@end example@noindentFields that are wider become clipped and end in the string @samp{=>}.Note that the full text is still in the buffer, it is only invisible.To see the full text, hold the mouse over the field---a tool-tip windowwill show the full content. To edit such a field, use the command@kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This willopen a new window with the full field. Edit it and finish with @kbd{C-cC-c}.@vindex org-startup-align-all-tablesWhen visiting a file containing a table with narrowed columns, thenecessary character hiding has not yet happened, and the table needs tobe aligned before it looks nice. Setting the option@code{org-startup-align-all-tables} will realign all tables in a fileupon visiting, but also slow down startup. You can also set this optionon a per-file basis with:@example#+STARTUP: align#+STARTUP: noalign@end exampleIf you would like to overrule the automatic alignment of number-rich columnsto the right and of string-rich column to the left, you and use @samp{<r>} or@samp{<l>} in a similar fashion. You may also combine alignment and fieldwidth like this: @samp{<l10>}.Lines which only contain these formatting cookies will be removedautomatically when exporting the document.@node Column groups, Orgtbl mode, Column width and alignment, Tables@section Column groups@cindex grouping columns in tablesWhen Org exports tables, it does so by default without verticallines because that is visually more satisfying in general. Occasionallyhowever, vertical lines can be useful to structure a table into groupsof columns, much like horizontal lines can do for groups of rows. Inorder to specify column groups, you can use a special row where thefirst field contains only @samp{/}. The further fields can eithercontain @samp{<} to indicate that this column should start a group,@samp{>} to indicate the end of a column, or @samp{<>} to make a columna group of its own. Boundaries between column groups will upon export bemarked with vertical lines. Here is an example:@example| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) ||---+-----+-----+-----+---------+------------|| / | < | | > | < | > || 1 | 1 | 1 | 1 | 1 | 1 || 2 | 4 | 8 | 16 | 1.4142 | 1.1892 || 3 | 9 | 27 | 81 | 1.7321 | 1.3161 ||---+-----+-----+-----+---------+------------|#+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))@end exampleIt is also sufficient to just insert the column group starters afterevery vertical line you would like to have:@example| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) ||----+-----+-----+-----+---------+------------|| / | < | | | < | |@end example@node Orgtbl mode, The spreadsheet, Column groups, Tables@section The Orgtbl minor mode@cindex Orgtbl mode@cindex minor mode for tablesIf you like the intuitive way the Org table editor works, youmight 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 togglethe mode with @kbd{M-x orgtbl-mode}. To turn it on by default, forexample in mail mode, use@lisp(add-hook 'mail-mode-hook 'turn-on-orgtbl)@end lispFurthermore, with some special setup, it is possible to maintain tablesin arbitrary syntax with Orgtbl mode. For example, it is possible toconstruct La@TeX{} tables with the underlying ease and power ofOrgtbl mode, including spreadsheet capabilities. For details, see@ref{Tables in arbitrary syntax}.@node The spreadsheet, Org-Plot, Orgtbl mode, Tables@section The spreadsheet@cindex calculations, in tables@cindex spreadsheet capabilities@cindex @file{calc} packageThe table editor makes use of the Emacs @file{calc} package to implementspreadsheet-like capabilities. It can also evaluate Emacs Lisp forms toderive fields from other fields. While fully featured, Org's implementationis not identical to other spreadsheets. For example, Org knows the conceptof a @emph{column formula} that will be applied to all non-header fields in acolumn without having to copy the formula to each relevant field. There isalso a formula debugger, and a formula editor with features for highlightingfields in the table corresponding to the references at the point in theformula, moving these references by arrow keys@menu* References:: How to refer to another field or range* Formula syntax for Calc:: Using Calc to compute stuff* Formula syntax for Lisp:: Writing formulas in Emacs Lisp* Field formulas:: Formulas valid for a single field* Column formulas:: Formulas valid for an entire column* Editing and debugging formulas:: Fixing formulas* Updating the table:: Recomputing all dependent fields* Advanced features:: Field names, parameters and automatic recalc@end menu@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet@subsection References@cindex referencesTo compute fields in the table from other fields, formulas mustreference other fields or ranges. In Org, fields can be referencedby name, by absolute coordinates, and by relative coordinates. To findout what the coordinates of a field are, press @kbd{C-c ?} in thatfield, or press @kbd{C-c @}} to toggle the display of a grid.@subsubheading Field references@cindex field references@cindex references, to fieldsFormulas can reference the value of another field in two ways. Like inany other spreadsheet, you may reference fields with a letter/numbercombination like @code{B3}, meaning the 2nd field in the 3rd row.@c Such references are always fixed to that field, they don't change@c when you copy and paste a formula to a different field. So@c Org's @code{B3} behaves like @code{$B$3} in other spreadsheets.@noindentOrg also uses another, more general operator that looks like this:@example@@@var{row}$@var{column}@end example@noindentColumn references can be absolute like @samp{1}, @samp{2},...@samp{@var{N}},or relative to the current column like @samp{+1} or @samp{-2}.The row specification only counts data lines and ignores horizontalseparator lines (hlines). You can use absolute row numbers@samp{1}...@samp{@var{N}}, and row numbers relative to the current row like@samp{+3} or @samp{-1}. Or specify the row relative to one of thehlines: @samp{I} refers to the first hline@footnote{Note that onlyhlines are counted that @emph{separate} table lines. If the tablestarts with a hline above the header, it does not count.}, @samp{II} tothe second, etc@. @samp{-I} refers to the first such line above thecurrent line, @samp{+I} to the first such line below the current line.You can also write @samp{III+2} which is the second data line after thethird hline in the table.@samp{0} refers to the current row and column. Also, if you omiteither the column or the row part of the reference, the currentrow/column is implied.Org's references with @emph{unsigned} numbers are fixed referencesin the sense that if you use the same reference in the formula for twodifferent fields, the same field will be referenced each time.Org's references with @emph{signed} numbers are floatingreferences because the same reference operator can reference differentfields depending on the field being calculated by the formula.As a special case, references like @samp{$LR5} and @samp{$LR12} can be usedto refer in a stable way to the 5th and 12th field in the last row of thetable.Here are a few examples:@example@@2$3 @r{2nd row, 3rd column}C2 @r{same as previous}$5 @r{column 5 in the current row}E& @r{same as previous}@@2 @r{current column, row 2}@@-1$-3 @r{the field one row up, three columns to the left}@@-I$2 @r{field just under hline above current row, column 2}@end example@subsubheading Range references@cindex range references@cindex references, to rangesYou may reference a rectangular range of fields by specifying two fieldreferences connected by two dots @samp{..}. If both fields are in thecurrent row, you may simply use @samp{$2..$7}, but if at least one fieldis in a different row, you need to use the general @code{@@row$column}format at least for the first field (i.e the reference must start with@samp{@@} in order to be interpreted correctly). Examples:@example$1..$3 @r{First three fields in the current row.}$P..$Q @r{Range, using column names (see under Advanced)}@@2$1..@@4$3 @r{6 fields between these two fields.}A2..C4 @r{Same as above.}@@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row}@end example@noindent Range references return a vector of values that can be fedinto Calc vector functions. Empty fields in ranges are normallysuppressed, so that the vector contains only the non-empty fields (butsee the @samp{E} mode switch below). If there are no non-empty fields,@samp{[0]} is returned to avoid syntax errors in formulas.@subsubheading Field coordinates in formulas@cindex field coordinates@cindex coordinates, of field@cindex row, of field coordinates@cindex column, of field coordinatesFor Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used toget the row or column number of the field where the formula result goes.The traditional Lisp formula equivalents are @code{org-table-current-dline}and @code{org-table-current-column}. Examples:@exampleif(@@# % 2, $#, string("")) @r{column number on odd lines only}$3 = remote(FOO, @@@@#$2) @r{copy column 2 from table FOO into} @r{column 3 of the current table}@end example@noindent For the second example, table FOO must have at least as many rowsas the current table. Inefficient@footnote{The computation time scales asO(N^2) because table FOO is parsed for each field to be copied.} for largenumber of rows.@subsubheading Named references@cindex named references@cindex references, named@cindex name, of column or field@cindex constants, in calculations@cindex #+CONSTANTS@vindex org-table-formula-constants@samp{$name} is interpreted as the name of a column, parameter orconstant. Constants are defined globally through the variable@code{org-table-formula-constants}, and locally (for the file) through aline like@example#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6@end example@noindent@vindex constants-unit-system@pindex constants.elAlso properties (@pxref{Properties and Columns}) can be used asconstants in table formulas: for a property @samp{:Xyz:} use the name@samp{$PROP_Xyz}, and the property will be searched in the currentoutline entry and in the hierarchy above it. If you have the@file{constants.el} package, it will also be used to resolve constants,including natural constants like @samp{$h} for Planck's constant, andunits like @samp{$km} for kilometers@footnote{@file{constants.el} cansupply the values of constants in two different unit systems, @code{SI}and @code{cgs}. Which one is used depends on the value of the variable@code{constants-unit-system}. You can use the @code{#+STARTUP} options@code{constSI} and @code{constcgs} to set this value for the currentbuffer.}. Column names and parameters can be specified in special tablelines. These are described below, see @ref{Advanced features}. Allnames must start with a letter, and further consist of letters andnumbers.@subsubheading Remote references@cindex remote references@cindex references, remote@cindex references, to a different table@cindex name, of column or field@cindex constants, in calculations@cindex #+TBLNAMEYou 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@exampleremote(NAME-OR-ID,REF)@end example@noindentwhere NAME can be the name of a table in the current file as set by a@code{#+TBLNAME: NAME} line before the table. It can also be the ID of anentry, even in a different file, and the reference then refers to the firsttable in that entry. REF is an absolute field or range reference asdescribed above for example @code{@@3$3} or @code{$somename}, valid in thereferenced table.@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet@subsection Formula syntax for Calc@cindex formula syntax, Calc@cindex syntax, of formulasA formula can be any algebraic expression understood by the Emacs@file{Calc} package. @b{Note that @file{calc} has thenon-standard convention that @samp{/} has lower precedence than@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Beforeevaluation by @code{calc-eval} (@pxref{Calling Calc fromYour Programs,calc-eval,Calling Calc from Your Lisp Programs,Calc,GNUEmacs Calc Manual}),@c FIXME: The link to the Calc manual in HTML does not work.variable substitution takes place according to the rules described above.@cindex vectors, in table calculationsThe range vectors can be directly fed into the Calc vector functionslike @samp{vmean} and @samp{vsum}.@cindex format specifier@cindex mode, for @file{calc}@vindex org-calc-default-modesA formula can contain an optional mode string after a semicolon. Thisstring consists of flags to influence Calc and other modes duringexecution. By default, Org uses the standard Calc modes (precision12, angular units degrees, fraction and symbolic modes off). The displayformat, however, has been changed to @code{(float 8)} to keep tablescompact. The default settings can be configured using the variable@code{org-calc-default-modes}.@examplep20 @r{set the internal Calc calculation precision to 20 digits}n3 s3 e2 f4 @r{Normal, scientific, engineering, or fixed} @r{format of the result of Calc passed back to Org.} @r{Calc formatting is unlimited in precision as} @r{long as the Calc calculation precision is greater.}D R @r{angle modes: degrees, radians}F S @r{fraction and symbolic modes}N @r{interpret all fields as numbers, use 0 for non-numbers}T @r{force text interpretation}E @r{keep empty fields in ranges}L @r{literal}@end example@noindentUnless you use large integer numbers or high-precision-calculationand -display for floating point numbers you may alternatively provide a@code{printf} format specifier to reformat the Calc result after it has beenpassed back to Org instead of letting Calc already do theformatting@footnote{The @code{printf} reformatting is limited in precisionbecause the value passed to it is converted into an @code{integer} or@code{double}. The @code{integer} is limited in size by truncating thesigned value to 32 bits. The @code{double} is limited in precision to 64bits overall which leaves approximately 16 significant decimal digits.}.A few examples:@example$1+$2 @r{Sum of first and second field}$1+$2;%.2f @r{Same, format result to two decimals}exp($2)+exp($1) @r{Math functions can be used}$0;%.1f @r{Reformat current cell to 1 decimal}($3-32)*5/9 @r{Degrees F -> C conversion}$c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}sin($1);Dp3%.1e @r{Same, but use printf specifier for display}vmean($2..$7) @r{Compute column range mean, using vector function}vmean($2..$7);EN @r{Same, but treat empty fields as 0}taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree}@end exampleCalc also contains a complete set of logical operations. For example@exampleif($1<20,teen,string("")) @r{``teen'' if age $1 less than 20, else empty}@end example@node Formula syntax for Lisp, Field formulas, Formula syntax for Calc, The spreadsheet@subsection Emacs Lisp forms as formulas@cindex Lisp forms, as table formulasIt is also possible to write a formula in Emacs Lisp; this can be usefulfor string manipulation and control structures, if Calc'sfunctionality is not enough. If a formula starts with a single-quotefollowed by an opening parenthesis, then it is evaluated as a Lisp form.The evaluation should return either a string or a number. Just as with@file{calc} formulas, you can specify modes and a printf format after asemicolon. With Emacs Lisp forms, you need to be conscious about the wayfield references are interpolated into the form. By default, areference will be interpolated as a Lisp string (in double-quotes)containing the field. If you provide the @samp{N} mode switch, allreferenced elements will be numbers (non-number fields will be zero) andinterpolated as Lisp numbers, without quotes. If you provide the@samp{L} flag, all fields will be interpolated literally, without quotes.I.e., if you want a reference to be interpreted as a string by the Lispform, enclose the reference operator itself in double-quotes, like@code{"$3"}. Ranges are inserted as space-separated fields, so you canembed them in list or vector syntax. A few examples, note how the@samp{N} mode is used when we do computations in Lisp.@example@r{Swap the first two characters of the content of column 1} '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))@r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}} '(+ $1 $2);N@r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}} '(apply '+ '($1..$4));N@end example@node Field formulas, Column formulas, Formula syntax for Lisp, The spreadsheet@subsection Field formulas@cindex field formula@cindex formula, for individual table fieldTo assign a formula to a particular field, type it directly into thefield, preceded by @samp{:=}, for example @samp{:=$1+$2}. When youpress @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still inthe field, the formula will be stored as the formula for this field,evaluated, and the current field replaced with the result.@cindex #+TBLFMFormulas are stored in a special line starting with @samp{#+TBLFM:}directly below the table. If you typed the equation in the 4th field ofthe 3rd data line in the table, the formula will look like@samp{@@3$4=$1+$2}. When inserting/deleting/swapping column and rowswith the appropriate commands, @i{absolute references} (but not relativeones) in stored formulas are modified in order to still reference thesame field. Of course this is not true if you edit the table structurewith normal editing commands---then you must fix the equations yourself.The left-hand side of a formula may also be a named field (@pxref{Advancedfeatures}), or a last-row reference like @samp{$LR3}.Instead of typing an equation into the field, you may also use thefollowing command@table @kbd@kindex C-u C-c =@item C-u C-c =Install a new formula for the current field. The command prompts for aformula with default taken from the @samp{#+TBLFM:} line, appliesit to the current field, and stores it.@end table@node Column formulas, Editing and debugging formulas, Field formulas, The spreadsheet@subsection Column formulas@cindex column formula@cindex formula, for table columnOften in a table, the same formula should be used for all fields in aparticular column. Instead of having to copy the formula to all fieldsin that column, Org allows you to assign a single formula to an entirecolumn. If the table contains horizontal separator hlines, everythingbefore the first such line is considered part of the table @emph{header}and will not be modified by column formulas.To assign a formula to a column, type it directly into any field in thecolumn, preceded by an equal sign, like @samp{=$1+$2}. When you press@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,the formula will be stored as the formula for the current column, evaluatedand the current field replaced with the result. If the field contains only@samp{=}, the previously stored formula for this column is used. For eachcolumn, Org will only remember the most recently used formula. In the@samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The left-handside of a column formula cannot currently be the name of column, itmust be the numeric column reference.Instead of typing an equation into the field, you may also use thefollowing command:@table @kbd@kindex C-c =@item C-c =Install a new formula for the current column and replace current field withthe result of the formula. The command prompts for a formula, with defaulttaken from the @samp{#+TBLFM} line, applies it to the current field andstores it. With a numeric prefix argument(e.g. @kbd{C-5 C-c =}) the commandwill apply it to that many consecutive fields in the current column.@end table@node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet@subsection Editing and debugging formulas@cindex formula editing@cindex editing, of table formulas@vindex org-table-use-standard-referencesYou can edit individual formulas in the minibuffer or directly in thefield. Org can also prepare a special buffer with all activeformulas of a table. When offering a formula for editing, Orgconverts references to the standard format (like @code{B3} or @code{D&})if possible. If you prefer to only work with the internal format (like@code{@@3$2} or @code{$4}), configure the variable@code{org-table-use-standard-references}.@table @kbd@kindex C-c =@kindex C-u C-c =@item C-c =@itemx C-u C-c =Edit the formula associated with the current column/field in theminibuffer. See @ref{Column formulas}, and @ref{Field formulas}.@kindex C-u C-u C-c =@item C-u C-u C-c =Re-insert the active formula (either afield formula, or a column formula) into the current field, so that youcan edit it directly in the field. The advantage over editing in theminibuffer is that you can use the command @kbd{C-c ?}.@kindex C-c ?@item C-c ?While editing a formula in a table field, highlight the field(s)referenced by the reference at the cursor position in the formula.@kindex C-c @}@item C-c @}Toggle the display of row and column numbers for a table, usingoverlays. These are updated each time the table is aligned; you canforce it with @kbd{C-c C-c}.@kindex C-c @{@item C-c @{Toggle the formula debugger on and off. See below.@kindex C-c '@item C-c 'Edit all formulas for the current table in a special buffer, where theformulas will be displayed one per line. If the current field has anactive formula, the cursor in the formula editor will mark it.While inside the special buffer, Org will automatically highlightany field or range reference at the cursor position. You may edit,remove and add formulas, and use the following commands:@table @kbd@kindex C-c C-c@kindex C-x C-s@item C-c C-c@itemx C-x C-sExit the formula editor and store the modified formulas. With @kbd{C-u}prefix, also apply the new formulas to the entire table.@kindex C-c C-q@item C-c C-qExit the formula editor without installing changes.@kindex C-c C-r@item C-c C-rToggle all references in the formula editor between standard (like@code{B3}) and internal (like @code{@@3$2}).@kindex @key{TAB}@item @key{TAB}Pretty-print or indent Lisp formula at point. When in a line containinga Lisp formula, format the formula according to Emacs Lisp rules.Another @key{TAB} collapses the formula back again. In the openformula, @key{TAB} re-indents just like in Emacs Lisp mode.@kindex M-@key{TAB}@item M-@key{TAB}Complete Lisp symbols, just like in Emacs Lisp mode.@kindex S-@key{up}@kindex S-@key{down}@kindex S-@key{left}@kindex S-@key{right}@item S-@key{up}/@key{down}/@key{left}/@key{right}Shift the reference at point. For example, if the reference is@code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.This also works for relative references and for hline references.@kindex M-S-@key{up}@kindex M-S-@key{down}@item M-S-@key{up}/@key{down}Move the test line for column formulas in the Org buffer up anddown.@kindex M-@key{up}@kindex M-@key{down}@item M-@key{up}/@key{down}Scroll the window displaying the table.@kindex C-c @}@item C-c @}Turn the coordinate grid in the table on and off.@end table@end tableMaking a table field blank does not remove the formula associated withthe field, because that is stored in a different line (the @samp{#+TBLFM}line)---during the next recalculation the field will be filled again.To remove a formula from a field, you have to give an empty reply whenprompted for the formula, or to edit the @samp{#+TBLFM} line.@kindex C-c C-cYou may edit the @samp{#+TBLFM} directly and re-apply the changedequations with @kbd{C-c C-c} in that line or with the normalrecalculation commands in the table.@subsubheading Debugging formulas@cindex formula debugging@cindex debugging, of table formulasWhen the evaluation of a formula leads to an error, the field contentbecomes the string @samp{#ERROR}. If you would like see what is goingon during variable substitution and calculation in order to find a bug,turn on formula debugging in the @code{Tbl} menu and repeat thecalculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in afield. Detailed information will be displayed.@node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet@subsection Updating the table@cindex recomputing table fields@cindex updating, tableRecalculation of a table is normally not automatic, but needs to betriggered by a command. See @ref{Advanced features}, for a way to makerecalculation at least semi-automatic.In order to recalculate a line of a table or the entire table, use thefollowing commands:@table @kbd@kindex C-c *@item C-c *Recalculate the current row by first applying the stored column formulasfrom left to right, and all field formulas in the current row.@c@kindex C-u C-c *@item C-u C-c *@kindex C-u C-c C-c@itemx C-u C-c C-cRecompute the entire table, line by line. Any lines before the firsthline are left alone, assuming that these are part of the table header.@c@kindex C-u C-u C-c *@kindex C-u C-u C-c C-c@item C-u C-u C-c *@itemx C-u C-u C-c C-cIterate the table by recomputing it until no further changes occur.This may be necessary if some computed fields use the value of otherfields that are computed @i{later} in the calculation sequence.@item M-x org-table-recalculate-buffer-tablesRecompute all tables in the current buffer.@item M-x org-table-iterate-buffer-tablesIterate all tables in the current buffer, in order to converge table-to-tabledependencies.@end table@node Advanced features, , Updating the table, The spreadsheet@subsection Advanced featuresIf you want the recalculation of fields to happen automatically, or ifyou want to be able to assign @i{names} to fields and columns, you needto reserve the first column of the table for special marking characters.@table @kbd@kindex C-#@item C-#Rotate the calculation mark in first column through the states @samp{ },@samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,change all marks in the region.@end tableHere is an example of a table that collects exam results of students andmakes use of these features:@example@group|---+---------+--------+--------+--------+-------+------|| | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note ||---+---------+--------+--------+--------+-------+------|| ! | | P1 | P2 | P3 | Tot | || # | Maximum | 10 | 15 | 25 | 50 | 10.0 || ^ | | m1 | m2 | m3 | mt | ||---+---------+--------+--------+--------+-------+------|| # | Peter | 10 | 8 | 23 | 41 | 8.2 || # | Sam | 2 | 4 | 3 | 9 | 1.8 ||---+---------+--------+--------+--------+-------+------|| | Average | | | | 29.7 | || ^ | | | | | at | || $ | max=50 | | | | | ||---+---------+--------+--------+--------+-------+------|#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f@end group@end example@noindent @b{Important}: please note that for these special tables,recalculating the table with @kbd{C-u C-c *} will only affect rows thatare marked @samp{#} or @samp{*}, and fields that have a formula assignedto the field itself. The column formulas are not applied in rows withempty first field.@cindex marking characters, tablesThe marking characters have the following meaning:@table @samp@item !The fields in this line define names for the columns, so that you mayrefer to a column as @samp{$Tot} instead of @samp{$6}.@item ^This row defines names for the fields @emph{above} the row. With sucha definition, any formula in the table may use @samp{$m1} to refer tothe value @samp{10}. Also, if you assign a formula to a names field, itwill be stored as @samp{$name=...}.@item _Similar to @samp{^}, but defines names for the fields in the row@emph{below}.@item $Fields in this row can define @emph{parameters} for formulas. Forexample, if a field in a @samp{$} row contains @samp{max=50}, thenformulas in this table can refer to the value 50 using @samp{$max}.Parameters work exactly like constants, only that they can be defined ona per-table basis.@item #Fields in this row are automatically recalculated when pressing@key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this rowis selected for a global recalculation with @kbd{C-u C-c *}. Unmarkedlines will be left alone by this command.@item *Selects this line for global recalculation with @kbd{C-u C-c *}, butnot for automatic recalculation. Use this when automaticrecalculation slows down editing too much.@itemUnmarked lines are exempt from recalculation with @kbd{C-u C-c *}.All lines that should be recalculated should be marked with @samp{#}or @samp{*}.@item /Do not export this line. Useful for lines that contain the narrowing@samp{<N>} markers or column group markers.@end tableFinally, just to whet your appetite for what can be done with thefantastic @file{calc.el} package, here is a table that computes the Taylorseries of degree @code{n} at location @code{x} for a couple offunctions.@example@group|---+-------------+---+-----+--------------------------------------|| | Func | n | x | Result ||---+-------------+---+-----+--------------------------------------|| # | exp(x) | 1 | x | 1 + x || # | exp(x) | 2 | x | 1 + x + x^2 / 2 || # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 || # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 || # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 || * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 ||---+-------------+---+-----+--------------------------------------|#+TBLFM: $5=taylor($2,$4,$3);n3@end group@end example@node Org-Plot, , The spreadsheet, Tables@section Org-Plot@cindex graph, in tables@cindex plot tables using Gnuplot@cindex #+PLOTOrg-Plot can produce 2D and 3D graphs of information stored in org tablesusing @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}@uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}. To seethis in action, ensure that you have both Gnuplot and Gnuplot mode installedon your system, then call @code{org-plot/gnuplot} on the following table.@example@group#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"| Sede | Max cites | H-index ||-----------+-----------+---------|| Chile | 257.72 | 21.39 || Leeds | 165.77 | 19.68 || Sao Paolo | 71.00 | 11.50 || Stockholm | 134.19 | 14.33 || Morelia | 257.56 | 17.67 |@end group@end exampleNotice 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 canbe exercised through the @code{#+PLOT:} lines preceding a table. See belowfor a complete list of Org-plot options. For more information and examplessee the Org-plot tutorial at@uref{http://orgmode.org/worg/org-tutorials/org-plot.php}.@subsubheading Plot Options@table @code@item setSpecify any @command{gnuplot} option to be set when graphing.@item titleSpecify the title of the plot.@item indSpecify which column of the table to use as the @code{x} axis.@item depsSpecify the columns to graph as a Lisp style list, surrounded by parenthesesand separated by spaces for example @code{dep:(3 4)} to graph the third andfourth columns (defaults to graphing all other columns aside from the @code{ind}column).@item typeSpecify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.@item withSpecify a @code{with} option to be inserted for every col being plotted(e.g. @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).Defaults to @code{lines}.@item fileIf you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.@item labelsList of labels to be used for the deps (defaults to the column headers ifthey exist).@item lineSpecify an entire line to be inserted in the Gnuplot script.@item mapWhen plotting @code{3d} or @code{grid} types, set this to @code{t} to graph aflat mapping rather than a @code{3d} slope.@item timefmtSpecify format of Org-mode timestamps as they will be parsed by Gnuplot.Defaults to @samp{%Y-%m-%d-%H:%M:%S}.@item scriptIf you want total control, you can specify a script file (place the file namebetween double-quotes) which will be used to plot. Before plotting, everyinstance of @code{$datafile} in the specified script will be replaced withthe path to the generated data file. Note: even if you set this option, youmay still want to specify the plot type, as that can impact the content ofthe data file.@end table@node Hyperlinks, TODO Items, Tables, Top@chapter Hyperlinks@cindex hyperlinksLike HTML, Org provides links inside a file, external links toother files, Usenet articles, emails, and much more.@menu* Link format:: How links in Org are formatted* Internal links:: Links to other places in the current file* External links:: URL-like links to the world* Handling links:: Creating, inserting and following* Using links outside Org:: Linking from my C source code?* Link abbreviations:: Shortcuts for writing complex links* Search options:: Linking to a specific location* Custom searches:: When the default search is not enough@end menu@node Link format, Internal links, Hyperlinks, Hyperlinks@section Link format@cindex link format@cindex format, of linksOrg will recognize plain URL-like links and activate them asclickable links. The general link format, however, looks like this:@example[[link][description]] @r{or alternatively} [[link]]@end example@noindentOnce a link in the buffer is complete (all brackets present), Orgwill change the display so that @samp{description} is displayed insteadof @samp{[[link][description]]} and @samp{link} is displayed instead of@samp{[[link]]}. Links will be highlighted in the face @code{org-link},which by default is an underlined face. You can directly edit thevisible part of a link. Note that this can be either the @samp{link}part (if there is no description) or the @samp{description} part. Toedit also the invisible @samp{link} part, use @kbd{C-c C-l} with thecursor on the link.If you place the cursor at the beginning or just behind the end of thedisplayed text and press @key{BACKSPACE}, you will remove the(invisible) bracket at that location. This makes the link incompleteand the internals are again displayed as plain text. Inserting themissing bracket hides the link internals again. To show theinternal structure of all links, use the menu entry@code{Org->Hyperlinks->Literal links}.@node Internal links, External links, Link format, Hyperlinks@section Internal links@cindex internal links@cindex links, internal@cindex targets, for links@cindex property, CUSTOM_IDIf the link does not look like a URL, it is considered to be internal in thecurrent file. The most important case is a link like@samp{[[#my-custom-id]]} which will link to the entry with the@code{CUSTOM_ID} property @samp{my-custom-id}. Such custom IDs are very goodfor HTML export (@pxref{HTML export}) where they produce pretty sectionlinks. You are responsible yourself to make sure these custom IDs are uniquein a file.Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}lead to a text search in the current file.The link can be followed with @kbd{C-c C-o} when the cursor is on the link,or with a mouse click (@pxref{Handling links}). Links to custom IDs willpoint to the corresponding headline. The preferred match for a text link isa @i{dedicated target}: the same string in double angular brackets. Targetsmay be located anywhere; sometimes it is convenient to put them into acomment line. For example@example# <<My Target>>@end example@noindent In HTML export (@pxref{HTML export}), such targets will becomenamed anchors for direct access through @samp{http} links@footnote{Note thattext before the first headline is usually not exported, so the first suchtarget should be after the first headline, or in the line directly before thefirst headline.}.If no dedicated target exists, Org will search for the words in the link. Inthe above example the search would be for @samp{my target}. Links startingwith a star like @samp{*My Target} restrict the search toheadlines@footnote{To insert a link targeting a headline, in-buffercompletion can be used. Just type a star followed by a few optional lettersinto the buffer and press @kbd{M-@key{TAB}}. All headlines in the currentbuffer will be offered as completions. @xref{Handling links}, for morecommands creating links.}. When searching, Org-mode will first try anexact match, but then move on to more and more lenient searches. Forexample, the link @samp{[[*My Targets]]} will find any of the following:@example** My targets** TODO my targets are bright** my 20 targets are@end exampleFollowing a link pushes a mark onto Org's own mark ring. You canreturn to the previous position with @kbd{C-c &}. Using this commandseveral times in direct succession goes back to positions recordedearlier.@menu* Radio targets:: Make targets trigger links in plain text@end menu@node Radio targets, , Internal links, Internal links@subsection Radio targets@cindex radio targets@cindex targets, radio@cindex links, radio targetsOrg can automatically turn any occurrences of certain target namesin normal text into a link. So without explicitly creating a link, thetext connects to the target radioing its position. Radio targets areenclosed by triple angular brackets. For example, a target @samp{<<<MyTarget>>>} causes each occurrence of @samp{my target} in normal text tobecome activated as a link. The Org file is scanned automaticallyfor radio targets only when the file is first loaded into Emacs. Toupdate the target list during editing, press @kbd{C-c C-c} with thecursor on or at a target.@node External links, Handling links, Internal links, Hyperlinks@section External links@cindex links, external@cindex external links@cindex links, external@cindex Gnus links@cindex BBDB links@cindex IRC links@cindex URL links@cindex file links@cindex VM links@cindex RMAIL links@cindex WANDERLUST links@cindex MH-E links@cindex USENET links@cindex SHELL links@cindex Info links@cindex Elisp linksOrg supports links to files, websites, Usenet and email messages,BBDB database entries and links to both IRC conversations and theirlogs. External links are URL-like locators. They start with a shortidentifying string followed by a colon. There can be no space afterthe colon. The following list shows examples for each link type.@examplehttp://www.astro.uva.nl/~dominik @r{on the web}doi:10.1000/182 @r{DOI for an electronic resource}file:/home/dominik/images/jupiter.jpg @r{file, absolute path}/home/dominik/images/jupiter.jpg @r{same as above}file:papers/last.pdf @r{file, relative path}./papers/last.pdf @r{same as above}file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine}/myself@@some.where:papers/last.pdf @r{same as above}file:sometextfile::NNN @r{file with line number to jump to}file:projects.org @r{another Org file}file:projects.org::some words @r{text search in Org file}file:projects.org::*task title @r{heading search in Org file}docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN}id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}news:comp.emacs @r{Usenet link}mailto:adent@@galaxy.net @r{Mail link}vm:folder @r{VM folder link}vm:folder#id @r{VM message link}vm://myself@@some.where.org/folder#id @r{VM on remote machine}wl:folder @r{WANDERLUST folder link}wl:folder#id @r{WANDERLUST message link}mhe:folder @r{MH-E folder link}mhe:folder#id @r{MH-E message link}rmail:folder @r{RMAIL folder link}rmail:folder#id @r{RMAIL message link}gnus:group @r{Gnus group link}gnus:group#id @r{Gnus article link}bbdb:R.*Stallman @r{BBDB link (with regexp)}irc:/irc.com/#emacs/bob @r{IRC link}info:org:External%20links @r{Info node link (with encoded space)}shell:ls *.org @r{A shell command}elisp:org-agenda @r{Interactive Elisp command}elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}@end exampleA link should be enclosed in double brackets and may contain adescriptive text to be displayed instead of the URL (@pxref{Linkformat}), for example:@example[[http://www.gnu.org/software/emacs/][GNU Emacs]]@end example@noindentIf the description is a file name or URL that points to an image, HTMLexport (@pxref{HTML export}) will inline the image as a clickablebutton. If there is no description at all and the link points to animage,that image will be inlined into the exported HTML file.@cindex square brackets, around links@cindex plain text external linksOrg also finds external links in the normal text and activates themas links. If spaces must be part of the link (for example in@samp{bbdb:Richard Stallman}), or if you need to remove ambiguitiesabout the end of the link, enclose them in square brackets.@node Handling links, Using links outside Org, External links, Hyperlinks@section Handling links@cindex links, handlingOrg provides methods to create a link in the correct syntax, toinsert it into an Org file, and to follow the link.@table @kbd@kindex C-c l@cindex storing links@item C-c lStore a link to the current location. This is a @emph{global} command (youmust create the key binding yourself) which can be used in any buffer tocreate a link. The link will be stored for later insertion into an Orgbuffer (see below). What kind of link will be created depends on the currentbuffer:@b{Org-mode buffers}@*For Org files, if there is a @samp{<<target>>} at the cursor, the link pointsto the target. Otherwise it points to the current headline, which will alsobe the description.@vindex org-link-to-org-use-id@cindex property, CUSTOM_ID@cindex property, IDIf the headline has a @code{CUSTOM_ID} property, a link to this custom IDwill be stored. In addition or alternatively (depending on the value of@code{org-link-to-org-use-id}), a globally unique @code{ID} property will becreated and/or used to construct a link. So using this command in Orgbuffers will potentially create two links: a human-readable from the customID, and one that is globally unique and works even if the entry is moved fromfile to file. Later, when inserting the link, you need to decide which oneto use.@b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*Pretty much all Emacs mail clients are supported. The link will point to thecurrent article, or, in some GNUS buffers, to the group. The description isconstructed from the author and the subject.@b{Web browsers: W3 and W3M}@*Here the link will be the current URL, with the page title as description.@b{Contacts: BBDB}@*Links created in a BBDB buffer will point to the current entry.@b{Chat: IRC}@*@vindex org-irc-link-to-logsFor IRC links, if you set the variable @code{org-irc-link-to-logs} to@code{t}, a @samp{file:/} style link to the relevant point in the logs forthe current conversation is created. Otherwise an @samp{irc:/} style link tothe user/channel/server under the point will be stored.@b{Other files}@*For any other files, the link will point to the file, with a search string(@pxref{Search options}) pointing to the contents of the current line. Ifthere is an active region, the selected words will form the basis of thesearch string. If the automatically created link is not working correctly oraccurately enough, you can write custom functions to select the search stringand to do the search for particular file types---see @ref{Custom searches}.The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.@b{Agenda view}@*When the cursor is in an agenda view, the created link points to theentry referenced by the current line.@c@kindex C-c C-l@cindex link completion@cindex completion, of links@cindex inserting links@item C-c C-l@vindex org-keep-stored-link-after-insertionInsert a link@footnote{ Note that you don't have to use this command toinsert a link. Links in Org are plain text, and you can type or paste themstraight into the buffer. By using this command, the links are automaticallyenclosed in double brackets, and you will be asked for the optionaldescriptive text.}. This prompts for a link to be inserted into the buffer.You can just type a link, using text for an internal link, or one of the linktype prefixes mentioned in the examples above. The link will be insertedinto the buffer@footnote{After insertion of a stored link, the link will beremoved from the list of stored links. To keep it in the list later use, usea triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option@code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.If some text was selected when this command is called, the selected textbecomes the default description.@b{Inserting stored links}@*All links stored during thecurrent session are part of the history for this prompt, so you can accessthem with @key{up} and @key{down} (or @kbd{M-p/n}).@b{Completion support}@* Completion with @key{TAB} will help you to insertvalid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixesdefined through link abbreviations (@pxref{Link abbreviations}). If youpress @key{RET} after inserting only the @var{prefix}, Org will offerspecific completion support for some link types@footnote{This works bycalling a special function @code{org-PREFIX-complete-link}.} Forexample, if you type @kbd{file @key{RET}}, file name completion (alternativeaccess: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb@key{RET}} you can complete contact names.@kindex C-u C-c C-l@cindex file name completion@cindex completion, of file names@item C-u C-c C-lWhen @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link toa file will be inserted and you may use file name completion to selectthe name of the file. The path to the file is inserted relative to thedirectory of the current Org file, if the linked file is in the currentdirectory or in a sub-directory of it, or if the path is written relativeto the current directory using @samp{../}. Otherwise an absolute pathis used, if possible with @samp{~/} for your home directory. You canforce an absolute path with two @kbd{C-u} prefixes.@c@item C-c C-l @ @r{(with cursor on existing link)}When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit thelink and description parts of the link.@c@cindex following links@kindex C-c C-o@kindex @key{RET}@item C-c C-o @ @r{(or, if @code{org-return-follows-link} is set, also} @key{RET}@vindex org-file-appsOpen link at point. This will launch a web browser for URLs (using@command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB forthe corresponding links, and execute the command in a shell link. When thecursor 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 correspondingTAGS view. If the cursor is on a timestamp, it compiles the agenda for thatdate. Furthermore, it will visit text and remote files in @samp{file:} linkswith Emacs and select a suitable application for local non-text files.Classification of files is based on file extension only. See option@code{org-file-apps}. If you want to override the default application andvisit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoidopening in Emacs, use a @kbd{C-u C-u} prefix.@*If the cursor is on a headline, but not on a link, offer all links in theheadline and entry text.@c@kindex mouse-2@kindex mouse-1@item mouse-2@itemx mouse-1On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}would. Under Emacs 22, @kbd{mouse-1} will also follow a link.@c@kindex mouse-3@item mouse-3@vindex org-display-internal-link-with-indirect-bufferLike @kbd{mouse-2}, but force file links to be opened with Emacs, andinternal links to be displayed in another window@footnote{See thevariable @code{org-display-internal-link-with-indirect-buffer}}.@c@cindex inlining images@cindex images, inlining@kindex C-c C-x C-v@item C-c C-x C-vToggle the inline display of linked images. Normally this will only inlineimages that have no description part in the link, i.e. images that will alsobe inlined during export. When called with a prefix argument, also displayimages that do have a link description.@cindex mark ring@kindex C-c %@item C-c %Push the current position onto the mark ring, to be able to returneasily. Commands following an internal link do this automatically.@c@cindex links, returning to@kindex C-c &@item C-c &Jump back to a recorded position. A position is recorded by thecommands following internal links, and by @kbd{C-c %}. Using thiscommand several times in direct succession moves through a ring ofpreviously recorded positions.@c@kindex C-c C-x C-n@kindex C-c C-x C-p@cindex links, finding next/previous@item C-c C-x C-n@itemx C-c C-x C-pMove forward/backward to the next link in the buffer. At the limit ofthe buffer, the search fails once, and then wraps around. The keybindings for this are really too long, you might want to bind this alsoto @kbd{C-n} and @kbd{C-p}@lisp(add-hook 'org-load-hook (lambda () (define-key 'org-mode-map "\C-n" 'org-next-link) (define-key 'org-mode-map "\C-p" 'org-previous-link)))@end lisp@end table@node Using links outside Org, Link abbreviations, Handling links, Hyperlinks@section Using links outside OrgYou can insert and follow links that have Org syntax not only inOrg, but in any Emacs buffer. For this, you should create twoglobal commands, like this (please select suitable global keysyourself):@lisp(global-set-key "\C-c L" 'org-insert-link-global)(global-set-key "\C-c o" 'org-open-at-point-global)@end lisp@node Link abbreviations, Search options, Using links outside Org, Hyperlinks@section Link abbreviations@cindex link abbreviations@cindex abbreviation, linksLong URLs can be cumbersome to type, and often many similar links areneeded in a document. For this you can use link abbreviations. Anabbreviated link looks like this@example[[linkword:tag][description]]@end example@noindent@vindex org-link-abbrev-alistwhere the tag is optional.The @i{linkword} must be a word, starting with a letter, followed byletters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolvedaccording to the information in the variable @code{org-link-abbrev-alist}that relates the linkwords to replacement text. Here is an example:@lisp@group(setq org-link-abbrev-alist '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") ("google" . "http://www.google.com/search?q=") ("ads" . "http://adsabs.harvard.edu/cgi-bin/ nph-abs_connect?author=%s&db_key=AST")))@end group@end lispIf the replacement text contains the string @samp{%s}, it will bereplaced with the tag. Otherwise the tag will be appended to the stringin order to create the link. You may also specify a function that willbe called with the tag as the only argument to create the link.With the above setting, you could link to a specific bug with@code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with@code{[[google:OrgMode]]} and find out what the Org author isdoing besides Emacs hacking with @code{[[ads:Dominik,C]]}.If you need special abbreviations just for a single Org buffer, youcan define them in the file with@cindex #+LINK@example#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=#+LINK: google http://www.google.com/search?q=%s@end example@noindentIn-buffer completion (@pxref{Completion}) can be used after @samp{[} tocomplete link abbreviations. You may also define a function@code{org-PREFIX-complete-link} that implements special (e.g. completion)support for inserting such a link with @kbd{C-c C-l}. Such a function shouldnot accept any arguments, and return the full link with prefix.@node Search options, Custom searches, Link abbreviations, Hyperlinks@section Search options in file links@cindex search option in file links@cindex file links, searchingFile links can contain additional information to make Emacs jump to aparticular location in the file when following a link. This can be aline number or a search option after a double@footnote{For backwardcompatibility, line numbers can also follow a single colon.} colon. Forexample, when the command @kbd{C-c l} creates a link (@pxref{Handlinglinks}) to a file, it encodes the words in the current line as a searchstring that can be used to find this line back later when following thelink with @kbd{C-c C-o}.Here is the syntax of the different ways to attach a search to a filelink, together with an explanation:@example[[file:~/code/main.c::255]][[file:~/xx.org::My Target]][[file:~/xx.org::*My Target]][[file:~/xx.org::#my-custom-id]][[file:~/xx.org::/regexp/]]@end example@table @code@item 255Jump to line 255.@item My TargetSearch for a link target @samp{<<My Target>>}, or do a text search for@samp{my target}, similar to the search in internal links, see@ref{Internal links}. In HTML export (@pxref{HTML export}), such a filelink will become an HTML reference to the corresponding named anchor inthe linked file.@item *My TargetIn an Org file, restrict search to headlines.@item #my-custom-idLink to a heading with a @code{CUSTOM_ID} property@item /regexp/Do a regular expression search for @code{regexp}. This uses the Emacscommand @code{occur} to list all matches in a separate window. If thetarget file is in Org-mode, @code{org-occur} is used to create asparse tree with the matches.@c If the target file is a directory,@c @code{grep} will be used to search all files in the directory.@end tableAs a degenerate case, a file link with an empty file name can be usedto search the current file. For example, @code{[[file:::find me]]} doesa search for @samp{find me} in the current file, just as@samp{[[find me]]} would.@node Custom searches, , Search options, Hyperlinks@section Custom Searches@cindex custom search strings@cindex search strings, customThe default mechanism for creating search strings and for doing theactual search related to a file link may not work correctly in allcases. For example, Bib@TeX{} database files have many entries like@samp{year="1993"} which would not result in good search strings,because the only unique identification for a Bib@TeX{} entry is thecitation key.@vindex org-create-file-search-functions@vindex org-execute-file-search-functionsIf you come across such a problem, you can write custom functions to setthe right search string for a particular file type, and to do the searchfor the string in the file. Using @code{add-hook}, these functions needto be added to the hook variables@code{org-create-file-search-functions} and@code{org-execute-file-search-functions}. See the docstring for thesevariables for more information. Org actually uses this mechanismfor Bib@TeX{} database files, and you can use the corresponding code asan implementation example. See the file @file{org-bibtex.el}.@node TODO Items, Tags, Hyperlinks, Top@chapter TODO items@cindex TODO itemsOrg-mode does not maintain TODO lists as separate documents@footnote{Ofcourse, you can make a document that contains only long lists of TODO items,but this is not required.}. Instead, TODO items are an integral part of thenotes file, because TODO items usually come up while taking notes! With Orgmode, 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 TODOitem emerged is always present.Of course, this technique for managing TODO items scatters themthroughout your notes file. Org-mode compensates for this by providingmethods to give you an overview of all the things that you have to do.@menu* TODO basics:: Marking and displaying TODO entries* TODO extensions:: Workflow and assignments* Progress logging:: Dates and notes for progress* Priorities:: Some things are more important than others* Breaking down tasks:: Splitting a task into manageable pieces* Checkboxes:: Tick-off lists@end menu@node TODO basics, TODO extensions, TODO Items, TODO Items@section Basic TODO functionalityAny headline becomes a TODO item when it starts with the word@samp{TODO}, for example:@example*** TODO Write letter to Sam Fortune@end example@noindentThe most important commands to work with TODO entries are:@table @kbd@kindex C-c C-t@cindex cycling, of TODO states@item C-c C-tRotate the TODO state of the current item among@example,-> (unmarked) -> TODO -> DONE --.'--------------------------------'@end exampleThe same rotation can also be done ``remotely'' from the timeline andagenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).@kindex C-u C-c C-t@item C-u C-c C-tSelect a specific keyword using completion or (if it has been set up)the fast selection interface. For the latter, you need to assign keysto TODO states, see @ref{Per-file keywords}, and @ref{Setting tags}, formore information.@kindex S-@key{right}@kindex S-@key{left}@vindex org-treat-S-cursor-todo-selection-as-state-change@item S-@key{right}@itemx S-@key{left}Select the following/preceding TODO state, similar to cycling. Usefulmostly if more than two TODO states are possible (@pxref{TODOextensions}). See also @ref{Conflicts}, for a discussion of the interactionwith @code{shift-selection-mode}. See also the variable@code{org-treat-S-cursor-todo-selection-as-state-change}.@kindex C-c / t@cindex sparse tree, for TODO@itemx C-c / t@vindex org-todo-keywordsView TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds theentire buffer, but shows all TODO items (with not-DONE state) and theheadings hierarchy above them. With a prefix argument (or by using @kbd{C-c/ T}), search for a specific TODO. You will be prompted for the keyword, andyou can also give a list of keywords like @code{KWD1|KWD2|...} to listentries that match any one of these keywords. With numeric prefix argumentN, show the tree for the Nth keyword in the variable@code{org-todo-keywords}. With two prefix arguments, find all TODO states,both un-done and done.@kindex C-c a t@item C-c a tShow the global TODO list. Collects the TODO items (with not-DONE states)from all agenda files (@pxref{Agenda Views}) into a single buffer. The newbuffer will be in @code{agenda-mode}, which provides commands to examine andmanipulate the TODO entries from the new buffer (@pxref{Agenda commands}).@xref{Global TODO list}, for more information.@kindex S-M-@key{RET}@item S-M-@key{RET}Insert a new TODO entry below the current one.@end table@noindent@vindex org-todo-state-tags-triggersChanging a TODO state can also trigger tag changes. See the docstring of theoption @code{org-todo-state-tags-triggers} for details.@node TODO extensions, Progress logging, TODO basics, TODO Items@section Extended use of TODO keywords@cindex extended TODO keywords@vindex org-todo-keywordsBy default, marked TODO entries have one of only two states: TODO andDONE. Org-mode allows you to classify TODO items in more complex wayswith @emph{TODO keywords} (stored in @code{org-todo-keywords}). Withspecial setup, the TODO keyword system can work differently in differentfiles.Note that @i{tags} are another way to classify headlines in general andTODO items in particular (@pxref{Tags}).@menu* Workflow states:: From TODO to DONE in steps* TODO types:: I do this, Fred does the rest* Multiple sets in one file:: Mixing it all, and still finding your way* Fast access to TODO states:: Single letter selection of a state* Per-file keywords:: Different files, different requirements* Faces for TODO keywords:: Highlighting states* TODO dependencies:: When one task needs to wait for others@end menu@node Workflow states, TODO types, TODO extensions, TODO extensions@subsection TODO keywords as workflow states@cindex TODO workflow@cindex workflow states as TODO keywordsYou can use TODO keywords to indicate different @emph{sequential} statesin the process of working on an item, for example@footnote{Changingthis variable only becomes effective after restarting Org-mode in abuffer.}:@lisp(setq org-todo-keywords '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))@end lispThe vertical bar separates the TODO keywords (states that @emph{needaction}) from the DONE states (which need @emph{no further action}). Ifyou don't provide the separator bar, the last state is used as the DONEstate.@cindex completion, of TODO keywordsWith this setup, the command @kbd{C-c C-t} will cycle an entry from TODOto FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You mayalso use a numeric prefix argument to quickly select a specific state. Forexample @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.Or you can use @kbd{S-@key{left}} to go backward through the sequence. If youdefine many keywords, you can use in-buffer completion(@pxref{Completion}) or even a special one-key selection scheme(@pxref{Fast access to TODO states}) to insert these words into thebuffer. Changing a TODO state can be logged with a timestamp, see@ref{Tracking TODO state changes}, for more information.@node TODO types, Multiple sets in one file, Workflow states, TODO extensions@subsection TODO keywords as types@cindex TODO types@cindex names as TODO keywords@cindex types as TODO keywordsThe second possibility is to use TODO keywords to indicate different@emph{types} of action items. For example, you might want to indicatethat items are for ``work'' or ``home''. Or, when you work with severalpeople on a single project, you might want to assign action itemsdirectly to persons, by using their names as TODO keywords. This wouldbe set up like this:@lisp(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))@end lispIn this case, different keywords do not indicate a sequence, but ratherdifferent types. So the normal work flow would be to assign a task to aperson, and later to mark it DONE. Org-mode supports this style by adaptingthe workings of the command @kbd{C-c C-t}@footnote{This is also true for the@kbd{t} command in the timeline and agenda buffers.}. When used severaltimes in succession, it will still cycle through all names, in order to firstselect the right type for a task. But when you return to the item after sometime and execute @kbd{C-c C-t} again, it will switch from any name directlyto DONE. Use prefix arguments or completion to quickly select a specificname. You can also review the items of a specific TODO type in a sparse treeby using a numeric prefix to @kbd{C-c / t}. For example, to see all thingsLucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's itemsfrom all agenda files into a single buffer, you would use the numeric prefixargument as well when creating the global TODO list: @kbd{C-3 C-c a t}.@node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions@subsection Multiple keyword sets in one file@cindex TODO keyword setsSometimes you may want to use different sets of TODO keywords inparallel. For example, you may want to have the basic@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and aseparate state indicating that an item has been canceled (so it is notDONE, but also does not require action). Your setup would then looklike this:@lisp(setq org-todo-keywords '((sequence "TODO" "|" "DONE") (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") (sequence "|" "CANCELED")))@end lispThe keywords should all be different, this helps Org-mode to keep trackof which subsequence should be used for a given entry. In this setup,@kbd{C-c C-t} only operates within a subsequence, so it switches from@code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to(nothing) to @code{REPORT}. Therefore you need a mechanism to initiallyselect the correct sequence. Besides the obvious ways like typing akeyword or using completion, you may also apply the following commands:@table @kbd@kindex C-S-@key{right}@kindex C-S-@key{left}@kindex C-u C-u C-c C-t@item C-u C-u C-c C-t@itemx C-S-@key{right}@itemx C-S-@key{left}These keys jump from one TODO subset to the next. In the above example,@kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or@code{DONE} to @code{REPORT}, and any of the words in the second row to@code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with@code{shift-selection-mode} (@pxref{Conflicts}).@kindex S-@key{right}@kindex S-@key{left}@item S-@key{right}@itemx S-@key{left}@kbd{S-@key{<left>}} and @kbd{S-@key{<right>}} and walk through @emph{all}keywords from all sets, so for example @kbd{S-@key{<right>}} would switchfrom @code{DONE} to @code{REPORT} in the example above. See also@ref{Conflicts}, for a discussion of the interaction with@code{shift-selection-mode}.@end table@node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions@subsection Fast access to TODO statesIf you would like to quickly change an entry to an arbitrary TODO stateinstead of cycling through the states, you can set up keys forsingle-letter access to the states. This is done by adding the sectionkey after each keyword, in parentheses. For example:@lisp(setq org-todo-keywords '((sequence "TODO(t)" "|" "DONE(d)") (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") (sequence "|" "CANCELED(c)")))@end lisp@vindex org-fast-tag-selection-include-todoIf you then press @code{C-c C-t} followed by the selection key, the entrywill be switched to this state. @key{SPC} can be used to remove any TODOkeyword from an entry.@footnote{Check also the variable@code{org-fast-tag-selection-include-todo}, it allows you to change the TODOstate through the tags interface (@pxref{Setting tags}), in case you like tomingle the two concepts. Note that this means you need to come up withunique keys across both sets of keywords.}@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions@subsection Setting up keywords for individual files@cindex keyword options@cindex per-file keywords@cindex #+TODO@cindex #+TYP_TODO@cindex #+SEQ_TODOIt can be very useful to use different aspects of the TODO mechanism indifferent files. For file-local settings, you need to add special linesto the file which set the keywords and interpretation for that fileonly. For example, to set one of the two examples discussed above, youneed one of the following lines, starting in column zero anywhere in thefile:@example#+TODO: TODO FEEDBACK VERIFY | DONE CANCELED@end example@noindent (you may also write @code{#+SEQ_TODO} to be explicit about theinterpretation, but it means the same as @code{#+TODO}), or@example#+TYP_TODO: Fred Sara Lucy Mike | DONE@end exampleA setup for using several sets in parallel would be:@example#+TODO: TODO | DONE#+TODO: REPORT BUG KNOWNCAUSE | FIXED#+TODO: | CANCELED@end example@cindex completion, of option keywords@kindex M-@key{TAB}@noindent To make sure you are using the correct keyword, type@samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.@cindex DONE, final TODO keywordRemember that the keywords after the vertical bar (or the last keywordif no bar is there) must always mean that the item is DONE (although youmay use a different word). After changing one of these lines, use@kbd{C-c C-c} with the cursor still in the line to make the changesknown to Org-mode@footnote{Org-mode parses these lines only whenOrg-mode is activated after visiting a file. @kbd{C-c C-c} with thecursor in a line starting with @samp{#+} is simply restarting Org-modefor the current buffer.}.@node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions@subsection Faces for TODO keywords@cindex faces, for TODO keywords@vindex org-todo @r{(face)}@vindex org-done @r{(face)}@vindex org-todo-keyword-facesOrg-mode highlights TODO keywords with special faces: @code{org-todo}for keywords indicating that an item still has to be acted upon, and@code{org-done} for keywords indicating that an item is finished. Ifyou are using more than 2 different states, you might want to usespecial faces for some of them. This can be done using the variable@code{org-todo-keyword-faces}. For example:@lisp@group(setq org-todo-keyword-faces '(("TODO" . org-warning) ("STARTED" . "yellow") ("CANCELED" . (:foreground "blue" :weight bold))))@end group@end lispWhile using a list with face properties as shown for CANCELED @emph{should}work, this does not aways seem to be the case. If necessary, define aspecial face and use that. A string is interpreted as a color. The variable@code{org-faces-easy-properties} determines if that color is interpreted as aforeground or a background color.@node TODO dependencies, , Faces for TODO keywords, TODO extensions@subsection TODO dependencies@cindex TODO dependencies@cindex dependencies, of TODO states@vindex org-enforce-todo-dependencies@cindex property, ORDEREDThe structure of Org files (hierarchy and lists) makes it easy to define TODOdependencies. Usually, a parent TODO task should not be marked DONE untilall subtasks (defined as children tasks) are marked as DONE. And sometimesthere is a logical sequence to a number of (sub)tasks, so that one taskcannot be acted upon before all siblings above it are done. If you customizethe variable @code{org-enforce-todo-dependencies}, Org will block entriesfrom changing state to DONE while they have children that are not DONE.Furthermore, if an entry has a property @code{ORDERED}, each of its childrenwill be blocked until all earlier siblings are marked DONE. Here is anexample:@example* TODO Blocked until (two) is done** DONE one** TODO two* Parent :PROPERTIES: :ORDERED: t :END:** TODO a** TODO b, needs to wait for (a)** TODO c, needs to wait for (a) and (b)@end example@table @kbd@kindex C-c C-x o@item C-c C-x o@vindex org-track-ordered-property-with-tag@cindex property, ORDEREDToggle the @code{ORDERED} property of the current entry. A property is usedfor this behavior because this should be local to the current entry, notinherited like a tag. However, if you would like to @i{track} the value ofthis property with a tag for better visibility, customize the variable@code{org-track-ordered-property-with-tag}.@kindex C-u C-u C-u C-c C-t@item C-u C-u C-u C-c C-tChange TODO state, circumventing any state blocking.@end table@vindex org-agenda-dim-blocked-tasksIf you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entriesthat cannot be closed because of such dependencies will be shown in a dimmedfont or even made invisible in agenda views (@pxref{Agenda Views}).@cindex checkboxes and TODO dependencies@vindex org-enforce-todo-dependenciesYou can also block changes of TODO states by looking at checkboxes(@pxref{Checkboxes}). If you set the variable@code{org-enforce-todo-checkbox-dependencies}, an entry that has uncheckedcheckboxes will be blocked from switching to DONE.If you need more complex dependency structures, for example dependenciesbetween entries in different trees or files, check out the contributedmodule @file{org-depend.el}.@page@node Progress logging, Priorities, TODO extensions, TODO Items@section Progress logging@cindex progress logging@cindex logging, of progressOrg-mode can automatically record a timestamp and possibly a note whenyou mark a TODO item as DONE, or even each time you change the state ofa TODO item. This system is highly configurable, settings can be on aper-keyword basis and can be localized to a file or even a subtree. Forinformation on how to clock working time for a task, see @ref{Clockingwork time}.@menu* Closing items:: When was this entry marked DONE?* Tracking TODO state changes:: When did the status change?* Tracking your habits:: How consistent have you been?@end menu@node Closing items, Tracking TODO state changes, Progress logging, Progress logging@subsection Closing itemsThe most basic logging is to keep track of @emph{when} a certain TODOitem was finished. This is achieved with@footnote{The correspondingin-buffer setting is: @code{#+STARTUP: logdone}}.@lisp(setq org-log-done 'time)@end lisp@noindentThen each time you turn an entry from a TODO (not-done) state into anyof the DONE states, a line @samp{CLOSED: [timestamp]} will be insertedjust after the headline. If you turn the entry back into a TODO itemthrough further state cycling, that line will be removed again. If youwant to record a note along with the timestamp, use@footnote{Thecorresponding in-buffer setting is: @code{#+STARTUP: lognotedone}}@lisp(setq org-log-done 'note)@end lisp@noindentYou will then be prompted for a note, and that note will be stored belowthe entry with a @samp{Closing Note} heading.In the timeline (@pxref{Timeline}) and in the agenda(@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key todisplay the TODO items with a @samp{CLOSED} timestamp on each day,giving you an overview of what has been done.@node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging@subsection Tracking TODO state changes@cindex drawer, for state change recording@vindex org-log-states-order-reversed@vindex org-log-into-drawer@cindex property, LOG_INTO_DRAWERWhen TODO keywords are used as workflow states (@pxref{Workflow states}), youmight want to keep track of when a state change occurred and maybe take anote about this change. You can either record just a timestamp, or atime-stamped note for a change. These records will be inserted after theheadline as an itemized list, newest first@footnote{See the variable@code{org-log-states-order-reversed}}. When taking a lot of notes, you mightwant to get the notes out of the way into a drawer (@pxref{Drawers}).Customize the variable @code{org-log-into-drawer} to get thisbehavior---the recommended drawer for this is called @code{LOGBOOK}. You canalso overrule the setting of this variable for a subtree by setting a@code{LOG_INTO_DRAWER} property.Since it is normally too much to record a note for every state, Org-modeexpects configuration on a per-keyword basis for this. This is achieved byadding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note)in parentheses after each keyword. For example, with the setting@lisp(setq org-todo-keywords '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))@end lisp@noindent@vindex org-log-doneyou not only define global TODO keywords and fast access keys, but alsorequest that a time is recorded when the entry is set toDONE@footnote{It is possible that Org-mode will record two timestampswhen you are using both @code{org-log-done} and state change logging.However, it will never prompt for two notes---if you have configuredboth, the state change recording note will take precedence and cancelthe @samp{Closing Note}.}, and that a note is recorded when switching toWAIT or CANCELED. The setting for WAIT is even more special: the@samp{!} after the slash means that in addition to the note taken whenentering the state, a timestamp should be recorded when @i{leaving} theWAIT state, if and only if the @i{target} state does not configurelogging for entering it. So it has no effect when switching from WAITto DONE, because DONE is configured to record a timestamp only. Butwhen switching from WAIT back to TODO, the @samp{/!} in the WAITsetting now triggers a timestamp even though TODO has no loggingconfigured.You can use the exact same syntax for setting logging preferences localto a buffer:@example#+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)@end example@cindex property, LOGGINGIn order to define logging settings that are local to a subtree or asingle item, define a LOGGING property in this entry. Any non-emptyLOGGING property resets all logging settings to nil. You may then turnon logging for this specific tree using STARTUP keywords like@code{lognotedone} or @code{logrepeat}, as well as adding state specificsettings like @code{TODO(!)}. For example@example* TODO Log each state with only a time :PROPERTIES: :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!) :END:* TODO Only log when switching to WAIT, and when repeating :PROPERTIES: :LOGGING: WAIT(@@) logrepeat :END:* TODO No logging at all :PROPERTIES: :LOGGING: nil :END:@end example@node Tracking your habits, , Tracking TODO state changes, Progress logging@subsection Tracking your habits@cindex habitsOrg has the ability to track the consistency of a special category of TODOs,called ``habits''. A habit has the following properties:@enumerate@itemYou have enabled the @code{habits} module by customizing the variable@code{org-modules}.@itemThe habit is a TODO, with a TODO keyword representing an open state.@itemThe property @code{STYLE} is set to the value @code{habit}.@itemThe TODO has a scheduled date, with a @code{.+} style repeat interval.@itemThe TODO may also have minimum and maximum ranges specified by using thesyntax @samp{.+2d/3d}, which says that you want to do the task at least everythree days, but at most every two days.@itemYou must also have state logging for the @code{DONE} state enabled, in orderfor historical data to be represented in the consistency graph. If it's notenabled it's not an error, but the consistency graphs will be largelymeaningless.@end enumerateTo give you an idea of what the above rules look like in action, here's anactual habit with some history:@example** TODO Shave SCHEDULED: <2009-10-17 Sat .+2d/4d> - State "DONE" from "TODO" [2009-10-15 Thu] - State "DONE" from "TODO" [2009-10-12 Mon] - State "DONE" from "TODO" [2009-10-10 Sat] - State "DONE" from "TODO" [2009-10-04 Sun] - State "DONE" from "TODO" [2009-10-02 Fri] - State "DONE" from "TODO" [2009-09-29 Tue] - State "DONE" from "TODO" [2009-09-25 Fri] - State "DONE" from "TODO" [2009-09-19 Sat] - State "DONE" from "TODO" [2009-09-16 Wed] - State "DONE" from "TODO" [2009-09-12 Sat] :PROPERTIES: :STYLE: habit :LAST_REPEAT: [2009-10-19 Mon 00:36] :END:@end exampleWhat this habit says is: I want to shave at most every 2 days (given by the@code{SCHEDULED} date and repeat interval) and at least every 4 days. Iftoday 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 aconsistency graph, to show how consistent you've been at getting that taskdone in the past. This graph shows every day that the task was done over thepast three weeks, with colors for each day. The colors used are:@table @code@item BlueIf the task wasn't to be done yet on that day.@item GreenIf the task could have been done on that day.@item YellowIf the task was going to be overdue the next day.@item RedIf the task was overdue on that day.@end tableIn addition to coloring each day, the day is also marked with an asterisk ifthe task was actually done that day, and an exclamation mark to show wherethe current day falls in the graph.There are several configuration variables that can be used to change the wayhabits are displayed in the agenda.@table @code@item org-habit-graph-columnThe buffer column at which the consistency graph should be drawn. This willoverwrite any text in that column, so it's a good idea to keep your habits'titles brief and to the point.@item org-habit-preceding-daysThe amount of history, in days before today, to appear in consistency graphs.@item org-habit-following-daysThe number of days after today that will appear in consistency graphs.@item org-habit-show-habits-only-for-todayIf non-nil, only show habits in today's agenda view. This is set to true bydefault.@end tableLastly, pressing @kbd{K} in the agenda buffer will cause habits totemporarily be disabled and they won't appear at all. Press @kbd{K} again tobring them back. They are also subject to tag filtering, if you have habitswhich should only be done in certain contexts, for example.@node Priorities, Breaking down tasks, Progress logging, TODO Items@section Priorities@cindex prioritiesIf you use Org-mode extensively, you may end up with enough TODO items thatit starts to make sense to prioritize them. Prioritizing can be done byplacing a @emph{priority cookie} into the headline of a TODO item, like this@example*** TODO [#A] Write letter to Sam Fortune@end example@noindent@vindex org-priority-facesBy default, Org-mode supports three priorities: @samp{A}, @samp{B}, and@samp{C}. @samp{A} is the highest priority. An entry without a cookie istreated as priority @samp{B}. Priorities make a difference only in theagenda (@pxref{Weekly/daily agenda}); outside the agenda, they have noinherent meaning to Org-mode. The cookies can be highlighted with specialfaces by customizing the variable @code{org-priority-faces}.Priorities can be attached to any outline tree entries; they do not needto be TODO items.@table @kbd@kindex @kbd{C-c ,}@item @kbd{C-c ,}Set the priority of the current headline. The command prompts for apriority character @samp{A}, @samp{B} or @samp{C}. When you press@key{SPC} instead, the priority cookie is removed from the headline.The priorities can also be changed ``remotely'' from the timeline andagenda buffer with the @kbd{,} command (@pxref{Agenda commands}).@c@kindex S-@key{up}@kindex S-@key{down}@item S-@key{up}@itemx S-@key{down}@vindex org-priority-start-cycle-with-defaultIncrease/decrease priority of current headline@footnote{See also the option@code{org-priority-start-cycle-with-default}.}. Note that these keys arealso used to modify timestamps (@pxref{Creating timestamps}). See also@ref{Conflicts}, for a discussion of the interaction with@code{shift-selection-mode}.@end table@vindex org-highest-priority@vindex org-lowest-priority@vindex org-default-priorityYou can change the range of allowed priorities by setting the variables@code{org-highest-priority}, @code{org-lowest-priority}, and@code{org-default-priority}. For an individual buffer, you may setthese values (highest, lowest, default) like this (please make sure thatthe highest priority is earlier in the alphabet than the lowestpriority):@cindex #+PRIORITIES@example#+PRIORITIES: A C B@end example@node Breaking down tasks, Checkboxes, Priorities, TODO Items@section Breaking tasks down into subtasks@cindex tasks, breaking down@cindex statistics, for TODO items@vindex org-agenda-todo-list-sublevelsIt is often advisable to break down large tasks into smaller, manageablesubtasks. You can do this by creating an outline tree below a TODO item,with detailed subtasks on the tree@footnote{To keep subtasks out of theglobal TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keepthe overview over the fraction of subtasks that are already completed, inserteither @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies willbe updated each time the TODO status of a child changes, or when pressing@kbd{C-c C-c} on the cookie. For example:@example* Organize Party [33%]** TODO Call people [1/2]*** TODO Peter*** DONE Sarah** TODO Buy food** DONE Talk to neighbor@end example@cindex property, COOKIE_DATAIf a heading has both checkboxes and TODO children below it, the meaning ofthe statistics cookie become ambiguous. Set the property@code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolvethis issue.@vindex org-hierarchical-todo-statisticsIf you would like to have the statistics cookie count any TODO entries in thesubtree (not just direct children), configure the variable@code{org-hierarchical-todo-statistics}. To do this for a single subtree,include the word @samp{recursive} into the value of the @code{COOKIE_DATA}property.@example* Parent capturing statistics [2/20] :PROPERTIES: :COOKIE_DATA: todo recursive :END:@end exampleIf you would like a TODO entry to automatically change to DONEwhen all children are done, you can use the following setup:@example(defun org-summary-todo (n-done n-not-done) "Switch entry to DONE when all subentries are done, to TODO otherwise." (let (org-log-done org-log-states) ; turn off logging (org-todo (if (= n-not-done 0) "DONE" "TODO"))))(add-hook 'org-after-todo-statistics-hook 'org-summary-todo)@end exampleAnother possibility is the use of checkboxes to identify (a hierarchy of) alarge number of subtasks (@pxref{Checkboxes}).@node Checkboxes, , Breaking down tasks, TODO Items@section Checkboxes@cindex checkboxesEvery item in a plain list (@pxref{Plain lists}) can be made into acheckbox by starting it with the string @samp{[ ]}. This feature issimilar to TODO items (@pxref{TODO Items}), but is more lightweight.Checkboxes are not included into the global TODO list, so they are oftengreat to split a task into a number of simple steps. Or you can usethem in a shopping list. To toggle a checkbox, use @kbd{C-c C-c}, oruse the mouse (thanks to Piotr Zielinski's @file{org-mouse.el}).Here is an example of a checkbox list.@example* TODO Organize party [2/4] - [-] call people [1/3] - [ ] Peter - [X] Sarah - [ ] Sam - [X] order food - [ ] think about what music to play - [X] talk to the neighbors@end exampleCheckboxes work hierarchically, so if a checkbox item has children thatare checkboxes, toggling one of the children checkboxes will make theparent checkbox reflect if none, some, or all of the children arechecked.@cindex statistics, for checkboxes@cindex checkbox statistics@cindex property, COOKIE_DATA@vindex org-hierarchical-checkbox-statisticsThe @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookiesindicating 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 howmany checkboxes remain, even without opening a folded entry. The cookies canbe placed into a headline or into (the first line of) a plain list item.Each cookie covers checkboxes of direct children structurally below theheadline/item on which the cookie appears@footnote{Set the variable@code{org-hierarchical-checkbox-statistics} if you want such cookies torepresent the all checkboxes below the cookie, not just the directchildren.}. You have to insert the cookie yourself by typing either@samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}result, as in the examples above. With @samp{[%]} you get information aboutthe percentage of checkboxes checked (in the above example, this would be@samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie cancount either checkboxes below the heading or TODO states of children, and itwill display whatever was changed last. Set the property @code{COOKIE_DATA}to either @samp{checkbox} or @samp{todo} to resolve this issue.@cindex blocking, of checkboxes@cindex checkbox blocking@cindex property, ORDEREDIf the current outline node has an @code{ORDERED} property, checkboxes mustbe checked off in sequence, and an error will be thrown if you try to checkoff a box while there are unchecked boxes above it.@noindent The following commands work with checkboxes:@table @kbd@kindex C-c C-c@item C-c C-cToggle checkbox status or (with prefix arg) checkbox presence at point. Withdouble prefix argument, set it to @samp{[-]}, which is considered to be anintermediate state.@kindex C-c C-x C-b@item C-c C-x C-bToggle checkbox status or (with prefix arg) checkbox presence at point. Withdouble prefix argument, set it to @samp{[-]}, which is considered to be anintermediate state.@itemize @minus@itemIf there is an active region, toggle the first checkbox in the regionand set all remaining boxes to the same status as the first. With a prefixarg, add or remove the checkbox for all items in the region.@itemIf the cursor is in a headline, toggle checkboxes in the region betweenthis headline and the next (so @emph{not} the entire subtree).@itemIf there is no active region, just toggle the checkbox at point.@end itemize@kindex M-S-@key{RET}@item M-S-@key{RET}Insert a new item with a checkbox.This works only if the cursor is already in a plain list item(@pxref{Plain lists}).@kindex C-c C-x o@item C-c C-x o@vindex org-track-ordered-property-with-tag@cindex property, ORDEREDToggle the @code{ORDERED} property of the entry, to toggle if checkboxes mustbe checked off in sequence. A property is used for this behavior becausethis should be local to the current entry, not inherited like a tag.However, if you would like to @i{track} the value of this property with a tagfor better visibility, customize the variable@code{org-track-ordered-property-with-tag}.@kindex C-c #@item C-c #Update the statistics cookie in the current outline entry. When called witha @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies areupdated automatically if you toggle checkboxes with @kbd{C-c C-c} and makenew ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update whenchanging TODO states. If you delete boxes/entries or add/change them byhand, use this command to get things back into sync. Or simply toggle anyentry twice (checkboxes with @kbd{C-c C-c}).@end table@node Tags, Properties and Columns, TODO Items, Top@chapter Tags@cindex tags@cindex headline tagging@cindex matching, tags@cindex sparse tree, tag basedAn excellent way to implement labels and contexts for cross-correlatinginformation is to assign @i{tags} to headlines. Org-mode has extensivesupport for tags.@vindex org-tag-facesEvery headline can contain a list of tags; they occur at the end of theheadline. Tags are normal words containing letters, numbers, @samp{_}, and@samp{@@}. Tags must be preceded and followed by a single colon, e.g.,@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.Tags will by default be in bold face with the same color as the headline.You may specify special faces for specific tags using the variable@code{org-tag-faces}, in much the same way as you can for TODO keywords(@pxref{Faces for TODO keywords}).@menu* Tag inheritance:: Tags use the tree structure of the outline* Setting tags:: How to assign tags to a headline* Tag searches:: Searching for combinations of tags@end menu@node Tag inheritance, Setting tags, Tags, Tags@section Tag inheritance@cindex tag inheritance@cindex inheritance, of tags@cindex sublevels, inclusion into tags match@i{Tags} make use of the hierarchical structure of outline trees. If aheading has a certain tag, all subheadings will inherit the tag aswell. For example, in the list@example* Meeting with the French group :work:** Summary by Frank :boss:notes:*** TODO Prepare slides for him :action:@end example@noindentthe final heading will have the tags @samp{:work:}, @samp{:boss:},@samp{:notes:}, and @samp{:action:} even though the final heading is notexplicitly marked with those tags. You can also set tags that all entries ina file should inherit just as if these tags were defined in a hypotheticallevel zero that surrounds the entire file. Use a line like this@footnote{Aswith all these in-buffer settings, pressing @kbd{C-c C-c} activates anychanges in the line.}:@cindex #+FILETAGS@example#+FILETAGS: :Peter:Boss:Secret:@end example@noindent@vindex org-use-tag-inheritance@vindex org-tags-exclude-from-inheritanceTo limit tag inheritance to specific tags, or to turn it off entirely, usethe variables @code{org-use-tag-inheritance} and@code{org-tags-exclude-from-inheritance}.@vindex org-tags-match-list-sublevelsWhen a headline matches during a tags search while tag inheritance is turnedon, all the sublevels in the same tree will (for a simple match form) matchas well@footnote{This is only true if the search does not involve morecomplex tests including properties (@pxref{Property searches}).}. The listof matches may then become very long. If you only want to see the first tagsmatch in a subtree, configure the variable@code{org-tags-match-list-sublevels} (not recommended).@node Setting tags, Tag searches, Tag inheritance, Tags@section Setting tags@cindex setting tags@cindex tags, setting@kindex M-@key{TAB}Tags can simply be typed into the buffer at the end of a headline.After a colon, @kbd{M-@key{TAB}} offers completion on tags. There isalso a special command for inserting tags:@table @kbd@kindex C-c C-q@item C-c C-q@cindex completion, of tags@vindex org-tags-columnEnter new tags for the current headline. Org-mode will either offercompletion or a special single-key interface for setting tags, seebelow. After pressing @key{RET}, the tags will be inserted and alignedto @code{org-tags-column}. When called with a @kbd{C-u} prefix, alltags in the current buffer will be aligned to that column, just to makethings look nice. TAGS are automatically realigned after promotion,demotion, and TODO state changes (@pxref{TODO basics}).@kindex C-c C-c@item C-c C-cWhen the cursor is in a headline, this does the same as @kbd{C-c C-q}.@end table@vindex org-tag-alistOrg will support tag insertion based on a @emph{list of tags}. Bydefault this list is constructed dynamically, containing all tagscurrently used in the buffer. You may also globally specify a hard listof tags with the variable @code{org-tag-alist}. Finally you can setthe default tags for a given file with lines like@cindex #+TAGS@example#+TAGS: @@work @@home @@tennisclub#+TAGS: laptop car pc sailboat@end exampleIf you have globally defined your preferred set of tags using thevariable @code{org-tag-alist}, but would like to use a dynamic tag listin a specific file, add an empty TAGS option line to that file:@example#+TAGS:@end example@vindex org-tag-persistent-alistIf 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, thenyou may specify a list of tags with the variable@code{org-tag-persistent-alist}. You may turn this off on a per-file basisby adding a STARTUP option line to that file:@example#+STARTUP: noptag@end exampleBy default Org-mode uses the standard minibuffer completion facilities forentering tags. However, it also implements another, quicker, tag selectionmethod called @emph{fast tag selection}. This allows you to select anddeselect tags with just a single key press. For this to work well you shouldassign unique letters to most of your commonly used tags. You can do thisglobally by configuring the variable @code{org-tag-alist} in your@file{.emacs} file. For example, you may find the need to tag many items indifferent files with @samp{:@@home:}. In this case you can set somethinglike:@lisp(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))@end lisp@noindent If the tag is only relevant to the file you are working on, then youcan instead set the TAGS option line as:@example#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)@end example@noindent The tags interface will show the available tags in a splashwindow. If you want to start a new line after a specific tag, insert@samp{\n} into the tag list@example#+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p)@end example@noindent or write them in two lines:@example#+TAGS: @@work(w) @@home(h) @@tennisclub(t)#+TAGS: laptop(l) pc(p)@end example@noindentYou can also group together tags that are mutually exclusive by usingbraces, as in:@example#+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)@end example@noindent you indicate that at most one of @samp{@@work}, @samp{@@home},and @samp{@@tennisclub} should be selected. Multiple such groups are allowed.@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one ofthese lines to activate any changes.@noindentTo set these mutually exclusive groups in the variable @code{org-tags-alist},you must use the dummy tags @code{:startgroup} and @code{:endgroup} insteadof the braces. Similarly, you can use @code{:newline} to indicate a linebreak. The previous example would be set globally by the followingconfiguration:@lisp(setq org-tag-alist '((:startgroup . nil) ("@@work" . ?w) ("@@home" . ?h) ("@@tennisclub" . ?t) (:endgroup . nil) ("laptop" . ?l) ("pc" . ?p)))@end lispIf at least one tag has a selection key then pressing @kbd{C-c C-c} willautomatically present you with a special interface, listing inherited tags,the tags of the current headline, and a list of all valid tags withcorresponding keys@footnote{Keys will automatically be assigned to tags whichhave no configured keys.}. In this interface, you can use the followingkeys:@table @kbd@item a-z...Pressing keys assigned to tags will add or remove them from the list oftags in the current line. Selecting a tag in a group of mutuallyexclusive tags will turn off any other tags from that group.@kindex @key{TAB}@item @key{TAB}Enter a tag in the minibuffer, even if the tag is not in the predefinedlist. You will be able to complete on all tags present in the buffer.@kindex @key{SPC}@item @key{SPC}Clear all tags for this line.@kindex @key{RET}@item @key{RET}Accept the modified set.@item C-gAbort without installing changes.@item qIf @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.@item !Turn off groups of mutually exclusive tags. Use this to (as anexception) assign several tags from such a group.@item C-cToggle auto-exit after the next change (see below).If you are using expert mode, the first @kbd{C-c} will display theselection window.@end table@noindentThis method lets you assign tags to a headline with very few keys. Withthe above setup, you could clear the current tags and set @samp{@@home},@samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-cC-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to@samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} oralternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag@samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h@key{RET} @key{RET}}.@vindex org-fast-tag-selection-single-keyIf you find that most of the time you need only a single key press tomodify your list of tags, set the variable@code{org-fast-tag-selection-single-key}. Then you no longer have topress @key{RET} to exit fast tag selection---it will immediately exitafter the first change. If you then occasionally need more keys, press@kbd{C-c} to turn off auto-exit for the current tag selection process(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-cC-c}). If you set the variable to the value @code{expert}, the specialwindow is not even shown for single-key tag selection, it comes up onlywhen you press an extra @kbd{C-c}.@node Tag searches, , Setting tags, Tags@section Tag searches@cindex tag searches@cindex searching for tagsOnce a system of tags has been set up, it can be used to collect relatedinformation into special lists.@table @kbd@kindex C-c \@kindex C-c / m@item C-c \@itemx C-c / mCreate a sparse tree with all headlines matching a tags search. With a@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.@kindex C-c a m@item C-c a mCreate a global list of tag matches from all agenda files.@xref{Matching tags and properties}.@kindex C-c a M@item C-c a M@vindex org-tags-match-list-sublevelsCreate a global list of tag matches from all agenda files, but checkonly TODO items and force checking subitems (see variable@code{org-tags-match-list-sublevels}).@end tableThese commands all prompt for a match string which allows basic Boolean logiclike @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and@samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entrieswhich are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the searchstring is rich and allows also matching against TODO keywords, entry levelsand properties. For a complete description with many examples, see@ref{Matching tags and properties}.@node Properties and Columns, Dates and Times, Tags, Top@chapter Properties and columns@cindex propertiesProperties are a set of key-value pairs associated with an entry. Thereare two main applications for properties in Org-mode. First, propertiesare like tags, but with a value. Second, you can use properties toimplement (very basic) database capabilities in an Org buffer. Foran example of the first application, imagine maintaining a file whereyou document bugs and plan releases for a piece of software. Instead ofusing tags like @code{:release_1:}, @code{:release_2:}, one can use aproperty, say @code{:Release:}, that in different subtrees has differentvalues, such as @code{1.0} or @code{2.0}. For an example of the secondapplication of properties, imagine keeping track of your music CDs,where properties could be things such as the album, artist, date ofrelease, number of tracks, and so on.Properties can be conveniently edited and viewed in column view(@pxref{Column view}).@menu* Property syntax:: How properties are spelled out* Special properties:: Access to other Org-mode features* Property searches:: Matching property values* Property inheritance:: Passing values down the tree* Column view:: Tabular viewing and editing* Property API:: Properties for Lisp programmers@end menu@node Property syntax, Special properties, Properties and Columns, Properties and Columns@section Property syntax@cindex property syntax@cindex drawer, for propertiesProperties are key-value pairs. They need to be inserted into a specialdrawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each propertyis specified on a single line, with the key (surrounded by colons)first, and the value after it. Here is an example:@example* CD collection** Classic*** Goldberg Variations :PROPERTIES: :Title: Goldberg Variations :Composer: J.S. Bach :Artist: Glen Gould :Publisher: Deutsche Grammophon :NDisks: 1 :END:@end exampleYou may define the allowed values for a particular property @samp{:Xyz:}by setting a property @samp{:Xyz_ALL:}. This special property is@emph{inherited}, so if you set it in a level 1 entry, it will apply tothe entire tree. When allowed values are defined, setting thecorresponding property becomes easier and is less prone to typingerrors. For the example with the CD collection, we can predefinepublishers and the number of disks in a box like this:@example* CD collection :PROPERTIES: :NDisks_ALL: 1 2 3 4 :Publisher_ALL: "Deutsche Grammophon" Philips EMI :END:@end exampleIf you want to set properties that can be inherited by any entry in afile, use a line like@cindex property, _ALL@cindex #+PROPERTY@example#+PROPERTY: NDisks_ALL 1 2 3 4@end example@vindex org-global-propertiesProperty values set with the global variable@code{org-global-properties} can be inherited by all entries in allOrg files.@noindentThe following commands help to work with properties:@table @kbd@kindex M-@key{TAB}@item M-@key{TAB}After an initial colon in a line, complete property keys. All keys usedin the current file will be offered as possible completions.@kindex C-c C-x p@item C-c C-x pSet a property. This prompts for a property name and a value. Ifnecessary, the property drawer is created as well.@item M-x org-insert-property-drawerInsert a property drawer into the current entry. The drawer will beinserted early in the entry, but after the lines with planninginformation like deadlines.@kindex C-c C-c@item C-c C-cWith the cursor in a property drawer, this executes property commands.@item C-c C-c sSet a property in the current entry. Both the property and the valuecan be inserted using completion.@kindex S-@key{right}@kindex S-@key{left}@item S-@key{left}/@key{right}Switch property at point to the next/previous allowed value.@item C-c C-c dRemove a property from the current entry.@item C-c C-c DGlobally remove a property, from all entries in the current file.@item C-c C-c cCompute the property at point, using the operator and scope from thenearest column format definition.@end table@node Special properties, Property searches, Property syntax, Properties and Columns@section Special properties@cindex properties, specialSpecial properties provide an alternative access method to Org-modefeatures, like the TODO state or the priority of an entry, discussed in theprevious chapters. This interface exists so that you can includethese states in a column view (@pxref{Column view}), or to use them inqueries. The following property names are special and should not beused as keys in the properties drawer:@cindex property, special, TODO@cindex property, special, TAGS@cindex property, special, ALLTAGS@cindex property, special, CATEGORY@cindex property, special, PRIORITY@cindex property, special, DEADLINE@cindex property, special, SCHEDULED@cindex property, special, CLOSED@cindex property, special, TIMESTAMP@cindex property, special, TIMESTAMP_IA@cindex property, special, CLOCKSUM@cindex property, special, BLOCKED@c guessing that ITEM is needed in this area; also, should this list be sorted?@cindex property, special, ITEM@exampleTODO @r{The TODO keyword of the entry.}TAGS @r{The tags defined directly in the headline.}ALLTAGS @r{All tags, including inherited ones.}CATEGORY @r{The category of an entry.}PRIORITY @r{The priority of the entry, a string with a single letter.}DEADLINE @r{The deadline time string, without the angular brackets.}SCHEDULED @r{The scheduling timestamp, without the angular brackets.}CLOSED @r{When was this entry closed?}TIMESTAMP @r{The first keyword-less timestamp in the entry.}TIMESTAMP_IA @r{The first inactive timestamp in the entry.}CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}} @r{must be run first to compute the values.}BLOCKED @r{"t" if task is currently blocked by children or siblings}ITEM @r{The content of the entry.}@end example@node Property searches, Property inheritance, Special properties, Properties and Columns@section Property searches@cindex properties, searching@cindex searching, of propertiesTo create sparse trees and special lists with selection based on properties,the same commands are used as for tag searches (@pxref{Tag searches}).@table @kbd@kindex C-c \@kindex C-c / m@item C-c \@itemx C-c / mCreate a sparse tree with all matching entries. With a@kbd{C-u} prefix argument, ignore headlines that are not a TODO line.@kindex C-c a m@item C-c a mCreate a global list of tag/property matches from all agenda files.@xref{Matching tags and properties}.@kindex C-c a M@item C-c a M@vindex org-tags-match-list-sublevelsCreate a global list of tag matches from all agenda files, but checkonly TODO items and force checking of subitems (see variable@code{org-tags-match-list-sublevels}).@end tableThe syntax for the search string is described in @ref{Matching tags andproperties}.There is also a special command for creating sparse trees based on asingle property:@table @kbd@kindex C-c / p@item C-c / pCreate a sparse tree based on the value of a property. This firstprompts for the name of a property, and then for a value. A sparse treeis created with all entries that define this property with the givenvalue. If you enclose the value into curly braces, it is interpreted asa regular expression and matched against the property values.@end table@node Property inheritance, Column view, Property searches, Properties and Columns@section Property Inheritance@cindex properties, inheritance@cindex inheritance, of properties@vindex org-use-property-inheritanceThe outline structure of Org-mode documents lends itself for aninheritance model of properties: if the parent in a tree has a certainproperty, the children can inherit this property. Org-mode does notturn this on by default, because it can slow down property searchessignificantly and is often not needed. However, if you find inheritanceuseful, you can turn it on by setting the variable@code{org-use-property-inheritance}. It may be set to @code{t} to makeall properties inherited from the parent, to a list of propertiesthat should be inherited, or to a regular expression that matchesinherited properties. If a property has the value @samp{nil}, this isinterpreted as an explicit undefine of he property, so that inheritancesearch will stop at this value and return @code{nil}.Org-mode has a few properties for which inheritance is hard-coded, atleast for the special applications for which they are used:@cindex property, COLUMNS@table @code@item COLUMNSThe @code{:COLUMNS:} property defines the format of column view(@pxref{Column view}). It is inherited in the sense that the levelwhere a @code{:COLUMNS:} property is defined is used as the startingpoint for a column view table, independently of the location in thesubtree from where columns view is turned on.@item CATEGORY@cindex property, CATEGORYFor agenda view, a category set through a @code{:CATEGORY:} propertyapplies to the entire subtree.@item ARCHIVE@cindex property, ARCHIVEFor archiving, the @code{:ARCHIVE:} property may define the archivelocation for the entire subtree (@pxref{Moving subtrees}).@item LOGGING@cindex property, LOGGINGThe LOGGING property may define logging settings for an entry or asubtree (@pxref{Tracking TODO state changes}).@end table@node Column view, Property API, Property inheritance, Properties and Columns@section Column viewA great way to view and edit properties in an outline tree is@emph{column view}. In column view, each outline node is turned into atable row. Columns in this table provide access to properties of theentries. Org-mode implements columns by overlaying a tabular structureover the headline of each item. While the headlines have been turnedinto a table row, you can still change the visibility of the outlinetree. For example, you get a compact table by switching to CONTENTSview (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column viewis active), but you can still open, read, and edit the entry below eachheadline. Or, you can switch to column view after executing a sparsetree command and in this way get a table only for the selected items.Column view also works in agenda buffers (@pxref{Agenda Views}) wherequeries have collected selected items, possibly from a number of files.@menu* Defining columns:: The COLUMNS format property* Using column view:: How to create and use column view* Capturing column view:: A dynamic block for column view@end menu@node Defining columns, Using column view, Column view, Column view@subsection Defining columns@cindex column view, for properties@cindex properties, column viewSetting up a column view first requires defining the columns. This isdone by defining a column format line.@menu* Scope of column definitions:: Where defined, where valid?* Column attributes:: Appearance and content of a column@end menu@node Scope of column definitions, Column attributes, Defining columns, Defining columns@subsubsection Scope of column definitionsTo define a column format for an entire file, use a line like@cindex #+COLUMNS@example#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO@end exampleTo specify a format that only applies to a specific tree, add a@code{:COLUMNS:} property to the top node of that tree, for example:@example** Top node for columns view :PROPERTIES: :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO :END:@end exampleIf a @code{:COLUMNS:} property is present in an entry, it defines columnsfor the entry itself, and for the entire subtree below it. Since thecolumn definition is part of the hierarchical structure of the document,you can define columns on level 1 that are general enough for allsublevels, and more specific columns further down, when you edit adeeper part of the tree.@node Column attributes, , Scope of column definitions, Defining columns@subsubsection Column attributesA column definition sets the attributes of a column. The generaldefinition looks like this:@example %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]@end example@noindentExcept for the percent sign and the property name, all items areoptional. The individual parts have the following meaning:@example@var{width} @r{An integer specifying the width of the column in characters.} @r{If omitted, the width will be determined automatically.}@var{property} @r{The property that should be edited in this column.} @r{Special properties representing meta data are allowed here} @r{as well (@pxref{Special properties})}(title) @r{The header text for the column. If omitted, the} @r{property name is used.}@{@var{summary-type}@} @r{The summary type. If specified, the column values for} @r{parent nodes are computed from the children.} @r{Supported summary types are:} @{+@} @r{Sum numbers in this column.} @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.} @{$@} @r{Currency, short for @samp{+;%.2f}.} @{:@} @r{Sum times, HH:MM, plain numbers are hours.} @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.} @{X/@} @r{Checkbox status, @samp{[n/m]}.} @{X%@} @r{Checkbox status, @samp{[n%]}.} @{min@} @r{Smallest number in column.} @{max@} @r{Largest number.} @{mean@} @r{Arithmetic mean of numbers.} @{:min@} @r{Smallest time value in column.} @{:max@} @r{Largest time value.} @{:mean@} @r{Arithmetic mean of time values.} @{@@min@} @r{Minimum age (in days/hours/mins/seconds).} @{@@max@} @r{Maximum age (in days/hours/mins/seconds).} @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).}@end example@noindentBe aware that you can only have one summary type for any property youinclude. Subsequent columns referencing the same property will all display thesame summary information.Here is an example for a complete columns definition, along with allowedvalues.@example:COLUMNS: %25ITEM %9Approved(Approved?)@{X@} %Owner %11Status \@footnote{Please note that the COLUMNS definition must be on a single line---it is wrapped here only because of formatting constraints.} %10Time_Estimate@{:@} %CLOCKSUM:Owner_ALL: Tammy Mark Karl Lisa Don:Status_ALL: "In progress" "Not started yet" "Finished" "":Approved_ALL: "[ ]" "[X]"@end example@noindentThe first column, @samp{%25ITEM}, means the first 25 characters of theitem itself, i.e. of the headline. You probably always should start thecolumn definition with the @samp{ITEM} specifier. The other specifierscreate columns @samp{Owner} with a list of names as allowed values, for@samp{Status} with four different possible values, and for a checkboxfield @samp{Approved}. When no width is given after the @samp{%}character, the column will be exactly as wide as it needs to be in orderto fully display all values. The @samp{Approved} column does have amodified title (@samp{Approved?}, with a question mark). Summaries willbe created for the @samp{Time_Estimate} column by adding time durationexpressions like HH:MM, and for the @samp{Approved} column, by providingan @samp{[X]} status if all children have been checked. The@samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervalsin the subtree.@node Using column view, Capturing column view, Defining columns, Column view@subsection Using column view@table @kbd@tsubheading{Turning column view on and off}@kindex C-c C-x C-c@item C-c C-x C-c@vindex org-columns-default-formatTurn on column view. If the cursor is before the first headline in the file,column view is turned on for the entire file, using the @code{#+COLUMNS}definition. If the cursor is somewhere inside the outline, this commandsearches the hierarchy, up from point, for a @code{:COLUMNS:} property thatdefines a format. When one is found, the column view table is establishedfor the tree starting at the entry that contains the @code{:COLUMNS:}property. If no such property is found, the format is taken from the@code{#+COLUMNS} line or from the variable @code{org-columns-default-format},and column view is established for the current entry and its subtree.@kindex r@item rRecreate the column view, to include recent changes made in the buffer.@kindex g@item gSame as @kbd{r}.@kindex q@item qExit column view.@tsubheading{Editing values}@item @key{left} @key{right} @key{up} @key{down}Move through the column view from field to field.@kindex S-@key{left}@kindex S-@key{right}@item S-@key{left}/@key{right}Switch to the next/previous allowed value of the field. For this, youhave to have specified allowed values for a property.@item 1..9,0Directly select the nth allowed value, @kbd{0} selects the 10th value.@kindex n@kindex p@itemx n / pSame as @kbd{S-@key{left}/@key{right}}@kindex e@item eEdit the property at point. For the special properties, this willinvoke the same interface that you normally use to change thatproperty. For example, when editing a TAGS property, the tag completionor fast selection interface will pop up.@kindex C-c C-c@item C-c C-cWhen there is a checkbox at point, toggle it.@kindex v@item vView the full value of this property. This is useful if the width ofthe column is smaller than that of the value.@kindex a@item aEdit the list of allowed values for this property. If the list is foundin the hierarchy, the modified values is stored there. If no list isfound, the new value is stored in the first entry that is part of thecurrent column view.@tsubheading{Modifying the table structure}@kindex <@kindex >@item < / >Make the column narrower/wider by one character.@kindex S-M-@key{right}@item S-M-@key{right}Insert a new column, to the left of the current column.@kindex S-M-@key{left}@item S-M-@key{left}Delete the current column.@end table@node Capturing column view, , Using column view, Column view@subsection Capturing column viewSince column view is just an overlay over a buffer, it cannot beexported or printed directly. If you want to capture a column view, usea @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frameof this block looks like this:@cindex #+BEGIN, columnview@example* The column view#+BEGIN: columnview :hlines 1 :id "label"#+END:@end example@noindent This dynamic block has the following parameters:@table @code@item :idThis is the most important parameter. Column view is a feature that isoften localized to a certain (sub)tree, and the capture block might beat a different location in the file. To identify the tree whose view tocapture, you can use 4 values:@cindex property, ID@examplelocal @r{use the tree in which the capture block is located}global @r{make a global view, including all headings in the file}"file:@var{path-to-file}" @r{run column view at the top of this file}"@var{ID}" @r{call column view in the tree that has an @code{:ID:}} @r{property with the value @i{label}. You can use} @r{@kbd{M-x org-id-copy} to create a globally unique ID for} @r{the current entry and copy it to the kill-ring.}@end example@item :hlinesWhen @code{t}, insert an hline after every line. When a number @var{N}, insertan hline before each headline with level @code{<= @var{N}}.@item :vlinesWhen set to @code{t}, force column groups to get vertical lines.@item :maxlevelWhen set to a number, don't capture entries below this level.@item :skip-empty-rowsWhen set to @code{t}, skip rows where the only non-empty specifier of thecolumn view is @code{ITEM}.@end table@noindentThe following commands insert or update the dynamic block:@table @kbd@kindex C-c C-x i@item C-c C-x iInsert a dynamic block capturing a column view. You will be promptedfor the scope or ID of the view.@kindex C-c C-c@item C-c C-c@kindex C-c C-x C-u@itemx C-c C-x C-uUpdate dynamic block at point. The cursor needs to be in the@code{#+BEGIN} line of the dynamic block.@kindex C-u C-c C-x C-u@item C-u C-c C-x C-uUpdate all dynamic blocks (@pxref{Dynamic blocks}). This is useful ifyou have several clock table blocks in a buffer.@end tableYou can add formulas to the column view table and you may add plottinginstructions in front of the table---these will survive an update of theblock. If there is a @code{#+TBLFM:} after the table, the table willactually be recalculated automatically after an update.An alternative way to capture and process property values into a table isprovided by Eric Schulte's @file{org-collector.el} which is a contributedpackage@footnote{Contributed packages are not part of Emacs, but aredistributed with the main distribution of Org (visit@uref{http://orgmode.org}).}. It provides a general API to collectproperties from entries in a certain scope, and arbitrary Lisp expressions toprocess these values before inserting them into a table or a dynamic block.@node Property API, , Column view, Properties and Columns@section The Property API@cindex properties, API@cindex API, for propertiesThere is a full API for accessing and changing properties. This API canbe used by Emacs Lisp programs to work with properties and to implementfeatures based on them. For more information see @ref{Using theproperty API}.@node Dates and Times, Capture - Refile - Archive, Properties and Columns, Top@chapter Dates and times@cindex dates@cindex times@cindex timestamp@cindex date stampTo assist project planning, TODO items can be labeled with a date and/ora time. The specially formatted string carrying the date and timeinformation is called a @emph{timestamp} in Org-mode. This may be alittle confusing because timestamp is often used as indicating whensomething was created or last changed. However, in Org-mode this termis 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* Resolving idle time:: Resolving time if you've been idle* Effort estimates:: Planning work effort in advance* Relative timer:: Notes with a running timer@end menu@node Timestamps, Creating timestamps, Dates and Times, Dates and Times@section Timestamps, deadlines, and scheduling@cindex timestamps@cindex ranges, time@cindex date stamps@cindex deadlines@cindex schedulingA timestamp is a specification of a date (possibly with a time or a range oftimes) in a special format, either @samp{<2003-09-16 Tue>} or@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 date/timeformat. To use an alternative format, see @ref{Custom time format}.}. Atimestamp can appear anywhere in the headline or body of an Org tree entry.Its presence causes entries to be shown on specific dates in the agenda(@pxref{Weekly/daily agenda}). We distinguish:@table @var@item Plain timestamp; Event; Appointment@cindex timestampA simple timestamp just assigns a date/time to an item. This is justlike writing down an appointment or event in a paper agenda. In thetimeline and agenda displays, the headline of an entry associated with aplain timestamp will be shown exactly on that date.@example* Meet Peter at the movies <2006-11-01 Wed 19:15>* Discussion on climate change <2006-11-02 Thu 20:00-22:00>@end example@item Timestamp with repeater interval@cindex timestamp, with repeater intervalA timestamp may contain a @emph{repeater interval}, indicating that itapplies not only on the given date, but again and again after a certaininterval of N days (d), weeks (w), months (m), or years (y). Thefollowing will show up in the agenda every Wednesday:@example* Pick up Sam at school <2007-05-16 Wed 12:30 +1w>@end example@item Diary-style sexp entriesFor more complex date specifications, Org-mode supports using thespecial sexp diary entries implemented in the Emacs calendar/diarypackage. For example@example* The nerd meeting on every 2nd Thursday of the month <%%(diary-float t 4 2)>@end example@item Time/Date range@cindex timerange@cindex date rangeTwo timestamps connected by @samp{--} denote a range. The headlinewill be shown on the first and last day of the range, and on any datesthat are displayed and fall in the range. Here is an example:@example** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu>@end example@item Inactive timestamp@cindex timestamp, inactive@cindex inactive timestampJust like a plain timestamp, but with square brackets instead ofangular ones. These timestamps are inactive in the sense that they do@emph{not} trigger an entry to show up in the agenda.@example* Gillian comes late for the fifth time [2006-11-01 Wed]@end example@end table@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times@section Creating timestamps@cindex creating timestamps@cindex timestamps, creatingFor Org-mode to recognize timestamps, they need to be in the specificformat. All commands listed below produce timestamps in the correctformat.@table @kbd@kindex C-c .@item C-c .Prompt for a date and insert a corresponding timestamp. When the cursor isat an existing timestamp in the buffer, the command is used to modify thistimestamp instead of inserting a new one. When this command is used twice insuccession, a time range is inserted.@c@kindex C-c !@item C-c !Like @kbd{C-c .}, but insert an inactive timestamp that will not causean agenda entry.@c@kindex C-u C-c .@kindex C-u C-c !@item C-u C-c .@itemx C-u C-c !@vindex org-time-stamp-rounding-minutesLike @kbd{C-c .} and @kbd{C-c !}, but use the alternative format whichcontains date and time. The default time can be rounded to multiples of 5minutes, see the option @code{org-time-stamp-rounding-minutes}.@c@kindex C-c <@item C-c <Insert a timestamp corresponding to the cursor date in the Calendar.@c@kindex C-c >@item C-c >Access the Emacs calendar for the current date. If there is atimestamp in the current line, go to the corresponding dateinstead.@c@kindex C-c C-o@item C-c C-oAccess the agenda for the date given by the timestamp or -range atpoint (@pxref{Weekly/daily agenda}).@c@kindex S-@key{left}@kindex S-@key{right}@item S-@key{left}@itemx S-@key{right}Change date at cursor by one day. These key bindings conflict withshift-selection and related modes (@pxref{Conflicts}).@c@kindex S-@key{up}@kindex S-@key{down}@item S-@key{up}@itemx S-@key{down}Change the item under the cursor in a timestamp. The cursor can be on ayear, month, day, hour or minute. When the timestamp contains a time rangelike @samp{15:30-16:30}, modifying the first time will also shift the second,shifting the time block with constant length. To change the length, modifythe second time. Note that if the cursor is in a headline and not at atimestamp, these same keys modify the priority of an item.(@pxref{Priorities}). The key bindings also conflict with shift-selection andrelated modes (@pxref{Conflicts}).@c@kindex C-c C-y@cindex evaluate time range@item C-c C-yEvaluate a time range by computing the difference between start and end.With a prefix argument, insert result after the time range (in a table: intothe following column).@end table@menu* The date/time prompt:: How Org-mode helps you entering date and time* Custom time format:: Making dates look different@end menu@node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps@subsection The date/time prompt@cindex date, reading in minibuffer@cindex time, reading in minibuffer@vindex org-read-date-prefer-futureWhen Org-mode prompts for a date/time, the default is shown in defaultdate/time format, and the prompt therefore seems to ask for a specificformat. But it will in fact accept any string containing some date and/ortime information, and it is really smart about interpreting your input. Youcan, for example, use @kbd{C-y} to paste a (possibly multi-line) stringcopied from an email message. Org-mode will find whatever information is inthere and derive anything you have not specified from the @emph{default dateand time}. The default is usually the current date and time, but whenmodifying an existing timestamp, or when entering the second stamp of arange, it is taken from the stamp in the buffer. When filling ininformation, Org-mode assumes that most of the time you will want to enter adate in the future: if you omit the month/year and the given day/month is@i{before} today, it will assume that you mean a future date@footnote{See thevariable @code{org-read-date-prefer-future}. You may set that variable tothe symbol @code{time} to even make a time before now shift the date totomorrow.}. If the date has been automatically shifted into the future, thetime prompt will show this with @samp{(=>F).}For example, let's assume that today is @b{June 13, 2006}. Here is howvarious inputs will be interpreted, the items filled in by Org-mode arein @b{bold}.@example3-2-5 --> 2003-02-052/5/3 --> 2003-02-0514 --> @b{2006}-@b{06}-1412 --> @b{2006}-@b{07}-122/5 --> @b{2007}-02-05Fri --> nearest Friday (default date or later)sep 15 --> @b{2006}-09-15feb 15 --> @b{2007}-02-15sep 12 9 --> 2009-09-1212:45 --> @b{2006}-@b{06}-@b{13} 12:4522 sept 0:34 --> @b{2006}-09-22 0:34w4 --> ISO week for of the current year @b{2006}2012 w4 fri --> Friday of ISO week 4 in 20122012-w04-5 --> Same as above@end exampleFurthermore you can specify a relative date by giving, as the@emph{first} thing in the input: a plus/minus sign, a number and aletter ([dwmy]) to indicate change in days, weeks, months, or years. With asingle plus or minus, the date is always relative to today. With adouble plus or minus, it is relative to the default date. If instead ofa single letter, you use the abbreviation of day name, the date will bethe nth such day. E.g.@example+0 --> today. --> today+4d --> four days from today+4 --> same as above+2w --> two weeks from today++5 --> five days from default date+2tue --> second Tuesday from now.@end example@vindex parse-time-months@vindex parse-time-weekdaysThe function understands English month and weekday abbreviations. Ifyou want to use unabbreviated names and/or other languages, configurethe variables @code{parse-time-months} and @code{parse-time-weekdays}.@cindex calendar, for selecting date@vindex org-popup-calendar-for-date-promptParallel to the minibuffer prompt, a calendar is popped up@footnote{Ifyou don't need/want the calendar, configure the variable@code{org-popup-calendar-for-date-prompt}.}. When you exit the dateprompt, either by clicking on a date in the calendar, or by pressing@key{RET}, the date selected in the calendar will be combined with theinformation entered at the prompt. You can control the calendar fullyfrom the minibuffer:@kindex <@kindex >@kindex M-v@kindex C-v@kindex mouse-1@kindex S-@key{right}@kindex S-@key{left}@kindex S-@key{down}@kindex S-@key{up}@kindex M-S-@key{right}@kindex M-S-@key{left}@kindex @key{RET}@example@key{RET} @r{Choose date at cursor in calendar.}mouse-1 @r{Select date by clicking on it.}S-@key{right}/@key{left} @r{One day forward/backward.}S-@key{down}/@key{up} @r{One week forward/backward.}M-S-@key{right}/@key{left} @r{One month forward/backward.}> / < @r{Scroll calendar forward/backward by one month.}M-v / C-v @r{Scroll calendar forward/backward by 3 months.}@end example@vindex org-read-date-display-liveThe actions of the date/time prompt may seem complex, but I assure you theywill grow on you, and you will start getting annoyed by pretty much any otherway of entering a date/time out there. To help you understand what is goingon, the current interpretation of your input will be displayed live in theminibuffer@footnote{If you find this distracting, turn the display of with@code{org-read-date-display-live}.}.@node Custom time format, , The date/time prompt, Creating timestamps@subsection Custom time format@cindex custom date/time format@cindex time format, custom@cindex date format, custom@vindex org-display-custom-times@vindex org-time-stamp-custom-formatsOrg-mode uses the standard ISO notation for dates and times as it isdefined in ISO 8601. If you cannot get used to this and require anotherrepresentation of date and time to keep you happy, you can get it bycustomizing the variables @code{org-display-custom-times} and@code{org-time-stamp-custom-formats}.@table @kbd@kindex C-c C-x C-t@item C-c C-x C-tToggle the display of custom formats for dates and times.@end table@noindentOrg-mode needs the default format for scanning, so the custom date/timeformat does not @emph{replace} the default format---instead it is put@emph{over} the default format using text properties. This has thefollowing consequences:@itemize @bullet@itemYou cannot place the cursor onto a timestamp anymore, only before orafter.@itemThe @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjusteach component of a timestamp. If the cursor is at the beginning ofthe stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, thetime will be changed by one minute.@itemIf the timestamp contains a range of clock times or a repeater, thesewill not be overlayed, but remain in the buffer as they were.@itemWhen you delete a timestamp character-by-character, it will onlydisappear from the buffer after @emph{all} (invisible) charactersbelonging to the ISO timestamp have been removed.@itemIf the custom timestamp format is longer than the default and you areusing dates in tables, table alignment will be messed up. If the customformat is shorter, things do work as expected.@end itemize@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times@section Deadlines and schedulingA timestamp may be preceded by special keywords to facilitate planning:@table @var@item DEADLINE@cindex DEADLINE keywordMeaning: the task (most likely a TODO item, though not necessarily) is supposedto be finished on that date.@vindex org-deadline-warning-daysOn the deadline date, the task will be listed in the agenda. Inaddition, the agenda for @emph{today} will carry a warning about theapproaching or missed deadline, starting@code{org-deadline-warning-days} before the due date, and continuinguntil the entry is marked DONE. An example:@example*** TODO write article about the Earth for the Guide The editor in charge is [[bbdb:Ford Prefect]] DEADLINE: <2004-02-29 Sun>@end exampleYou can specify a different lead time for warnings for a specificdeadlines using the following syntax. Here is an example with a warningperiod of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}.@item SCHEDULED@cindex SCHEDULED keywordMeaning: you are planning to start working on that task on the givendate.@vindex org-agenda-skip-scheduled-if-doneThe headline will be listed under the given date@footnote{It will stillbe listed on that date after it has been marked DONE. If you don't likethis, set the variable @code{org-agenda-skip-scheduled-if-done}.}. Inaddition, a reminder that the scheduled date has passed will be presentin the compilation for @emph{today}, until the entry is marked DONE.I.e. the task will automatically be forwarded until completed.@example*** TODO Call Trillian for a date on New Years Eve. SCHEDULED: <2004-12-25 Sat>@end example@noindent@b{Important:} Scheduling an item in Org-mode should @i{not} beunderstood in the same way that we understand @i{scheduling a meeting}.Setting a date for a meeting is just a simple appointment, you shouldmark this entry with a simple plain timestamp, to get this item shownon the date where it applies. This is a frequent misunderstanding byOrg users. In Org-mode, @i{scheduling} means setting a date when youwant to start working on an action item.@end tableYou may use timestamps with repeaters in scheduling and deadlineentries. Org-mode will issue early and late warnings based on theassumption that the timestamp represents the @i{nearest instance} ofthe repeater. However, the use of diary sexp entries like@c@code{<%%(diary-float t 42)>}@cin scheduling and deadline timestamps is limited. Org-mode does notknow enough about the internals of each sexp function to issue early andlate warnings. However, it will show the item on each day where thesexp entry matches.@menu* Inserting deadline/schedule:: Planning items* Repeated tasks:: Items that show up again and again@end menu@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling@subsection Inserting deadlines or schedulesThe following commands allow you to quickly insert a deadline or to schedulean item:@table @kbd@c@kindex C-c C-d@item C-c C-dInsert @samp{DEADLINE} keyword along with a stamp. The insertion will happenin the line directly following the headline. When called with a prefix arg,an existing deadline will be removed from the entry. Depending on thevariable @code{org-log-redeadline}@footnote{with corresponding@code{#+STARTUP} keywords @code{logredeadline}, @code{lognoteredeadline},and @code{nologredeadline}}, a note will be taken when changing an existingdeadline.@c FIXME Any CLOSED timestamp will be removed.????????@c@kindex C-c C-s@item C-c C-sInsert @samp{SCHEDULED} keyword along with a stamp. The insertion willhappen in the line directly following the headline. Any CLOSED timestampwill be removed. When called with a prefix argument, remove the schedulingdate from the entry. Depending on the variable@code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}keywords @code{logredeadline}, @code{lognoteredeadline}, and@code{nologredeadline}}, a note will be taken when changing an existingscheduling time.@c@kindex C-c C-x C-k@kindex k a@kindex k s@item C-c C-x C-kMark the current entry for agenda action. After you have marked the entrylike this, you can open the agenda or the calendar to find an appropriatedate. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} toschedule the marked item.@c@kindex C-c / d@cindex sparse tree, for deadlines@item C-c / d@vindex org-deadline-warning-daysCreate a sparse tree with all deadlines that are either past-due, orwhich will become due within @code{org-deadline-warning-days}.With @kbd{C-u} prefix, show all deadlines in the file. With a numericprefix, check that many days. For example, @kbd{C-1 C-c / d} showsall deadlines due tomorrow.@c@kindex C-c / b@item C-c / bSparse tree for deadlines and scheduled items before a given date.@c@kindex C-c / a@item C-c / aSparse tree for deadlines and scheduled items after a given date.@end table@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling@subsection Repeated tasks@cindex tasks, repeated@cindex repeated tasksSome tasks need to be repeated again and again. Org-mode helps toorganize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,or plain timestamp. In the following example@example** TODO Pay the rent DEADLINE: <2005-10-01 Sat +1m>@end example@noindentthe @code{+1m} is a repeater; the intended interpretation is that the taskhas a deadline on <2005-10-01> and repeats itself every (one) month startingfrom that time. If you need both a repeater and a special warning period ina deadline entry, the repeater should come first and the warning period last:@code{DEADLINE: <2005-10-01 Sat +1m -3d>}.@vindex org-todo-repeat-to-stateDeadlines and scheduled items produce entries in the agenda when they areover-due, so it is important to be able to mark such an entry as completedonce you have done so. When you mark a DEADLINE or a SCHEDULE with the TODOkeyword DONE, it will no longer produce entries in the agenda. The problemwith this is, however, that then also the @emph{next} instance of therepeated entry will not be active. Org-mode deals with this in the followingway: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it willshift the base date of the repeating timestamp by the repeater interval, andimmediately set the entry state back to TODO@footnote{In fact, the targetstate is taken from, in this sequence, the @code{REPEAT_TO_STATE} property orthe variable @code{org-todo-repeat-to-state}. If neither of these isspecified, the target state defaults to the first state of the TODO statesequence.}. In the example above, setting the state to DONE would actuallyswitch the date like this:@example** TODO Pay the rent DEADLINE: <2005-11-01 Tue +1m>@end example@vindex org-log-repeatA timestamp@footnote{You can change this using the option@code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},@code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, youwill also be prompted for a note.} will be added under the deadline, to keepa 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 bevisible in the agenda when checking past dates, but all future instanceswill be visible.With the @samp{+1m} cookie, the date shift will always be exactly onemonth. So if you have not paid the rent for three months, marking thisentry DONE will still keep it as an overdue deadline. Depending on thetask, this may not be the best way to handle it. For example, if youforgot to call you father for 3 weeks, it does not make sense to callhim 3 times in a single day to make up for it. Finally, there are taskslike changing batteries which should always repeat a certain time@i{after} the last time you did it. For these tasks, Org-mode hasspecial repeaters markers with @samp{++} and @samp{.+}. For example:@example** TODO Call Father DEADLINE: <2008-02-10 Sun ++1w> Marking this DONE will shift the date by at least one week, but also by as many weeks as it takes to get this date into the future. However, it stays on a Sunday, even if you called and marked it done on Saturday.** TODO Check the batteries in the smoke detectors DEADLINE: <2005-11-01 Tue .+1m> Marking this DONE will shift the date to one month after today.@end exampleYou may have both scheduling and deadline information for a specifictask---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 tasksubtree, with dates shifted in each copy. The command @kbd{C-c C-x c} wascreated for this purpose, it is described in @ref{Structure editing}.@node Clocking work time, Resolving idle time, Deadlines and scheduling, Dates and Times@section Clocking work timeOrg-mode allows you to clock the time you spend on specific tasks in aproject. 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, theclock is stopped and the corresponding time interval is recorded. Italso computes the total time spent on each subtree of a project. And itremembers a history or tasks recently clocked, to that you can jump quicklybetween a number of tasks absorbing your time.To save the clock history across Emacs sessions, use@lisp(setq org-clock-persist 'history)(org-clock-persistence-insinuate)@end lispWhen you clock into a new task after resuming Emacs, the incompleteclock@footnote{To resume the clock under the assumption that you have workedon this task while outside Emacs, use @code{(setq org-clock-persist t)}.}will be found (@pxref{Resolving idle time}) and you will be prompted aboutwhat to do with it.@table @kbd@kindex C-c C-x C-i@item C-c C-x C-i@vindex org-clock-into-drawerStart the clock on the current item (clock-in). This inserts the CLOCKkeyword together with a timestamp. If this is not the first clocking ofthis item, the multiple CLOCK lines will be wrapped into a@code{:LOGBOOK:} drawer (see also the variable@code{org-clock-into-drawer}). When called with a @kbd{C-u} prefix argument,select the task from a list of recently clocked tasks. With two @kbd{C-uC-u} prefixes, clock into the task at point and mark it as the default task.The default task will always be available when selecting a clocking task,with letter @kbd{d}.@*@cindex property: CLOCK_MODELINE_TOTAL@cindex property: LAST_REPEAT@vindex org-clock-modeline-totalWhile the clock is running, the current clocking time is shown in the modeline, along with the title of the task. The clock time shown will be alltime ever clocked for this task and its children. If the task has an effortestimate (@pxref{Effort estimates}), the mode line displays the currentclocking time against it@footnote{To add an effort estimate ``on the fly'',hook a function doing this to @code{org-clock-in-prepare-hook}.} If the taskis a repeating one (@pxref{Repeated tasks}), only the time since the lastreset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}will be shown. More control over what time is shown can be exercised withthe @code{CLOCK_MODELINE_TOTAL} property. It may have the values@code{current} to show only the current clocking instance, @code{today} toshow all time clocked on this tasks today (see also the variable@code{org-extend-today-until}), @code{all} to include all time, or@code{auto} which is the default@footnote{See also the variable@code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto themode line entry will pop up a menu with clocking options.@kindex C-c C-x C-o@item C-c C-x C-o@vindex org-log-note-clock-outStop the clock (clock-out). This inserts another timestamp at the samelocation where the clock was last started. It also directly computesthe resulting time in inserts it after the time range as @samp{=>HH:MM}. See the variable @code{org-log-note-clock-out} for thepossibility to record an additional note together with the clock-outtimestamp@footnote{The corresponding in-buffer setting is:@code{#+STARTUP: lognoteclock-out}}.@kindex C-c C-x C-e@item C-c C-x C-eUpdate the effort estimate for the current clock task.@kindex C-c C-y@kindex C-c C-c@item C-c C-y @ @ @r{or}@ @ C-c C-cRecompute the time interval after changing one of the timestamps. Thisis only necessary if you edit the timestamps directly. If you changethem with @kbd{S-@key{cursor}} keys, the update is automatic.@kindex C-c C-t@item C-c C-tChanging the TODO state of an item to DONE automatically stops the clockif it is running in this same item.@kindex C-c C-x C-x@item C-c C-x C-xCancel the current clock. This is useful if a clock was started bymistake, or if you ended up working on something else.@kindex C-c C-x C-j@item C-c C-x C-jJump to the entry that contains the currently running clock. With a@kbd{C-u} prefix arg, select the target task from a list of recently clockedtasks.@kindex C-c C-x C-d@item C-c C-x C-d@vindex org-remove-highlights-with-changeDisplay time summaries for each subtree in the current buffer. Thisputs overlays at the end of each headline, showing the total timerecorded under that heading, including the time of any subheadings. Youcan use visibility cycling to study the tree, but the overlays disappearwhen you change the buffer (see variable@code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}.@kindex C-c C-x C-r@item C-c C-x C-rInsert a dynamic block (@pxref{Dynamic blocks}) containing a clockreport as an Org-mode table into the current file. When the cursor isat an existing clock table, just update it. When called with a prefixargument, jump to the first clock report in the current document andupdate it.@cindex #+BEGIN, clocktable@example#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file#+END: clocktable@end example@noindentIf such a block already exists at point, its content is replaced by thenew table. The @samp{BEGIN} line can specify options:@example:maxlevel @r{Maximum level depth to which times are listed in the table.}:emphasize @r{When @code{t}, emphasize level one and level two items.}:scope @r{The scope to consider. This can be any of the following:} nil @r{the current buffer or narrowed region} file @r{the full current buffer} subtree @r{the subtree where the clocktable is located} tree@var{N} @r{the surrounding level @var{N} tree, for example @code{tree3}} tree @r{the surrounding level 1 tree} agenda @r{all agenda files} ("file"..) @r{scan these files} file-with-archives @r{current file and its archives} agenda-with-archives @r{all agenda files, including archives}:block @r{The time block to consider. This block is specified either} @r{absolute, or relative to the current time and may be any of} @r{these formats:} 2007-12-31 @r{New year eve 2007} 2007-12 @r{December 2007} 2007-W50 @r{ISO-week 50 in 2007} 2007 @r{the year 2007} today, yesterday, today-@var{N} @r{a relative day} thisweek, lastweek, thisweek-@var{N} @r{a relative week} thismonth, lastmonth, thismonth-@var{N} @r{a relative month} thisyear, lastyear, thisyear-@var{N} @r{a relative year} @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}:tstart @r{A time string specifying when to start considering times.}:tend @r{A time string specifying when to stop considering times.}:step @r{@code{week} or @code{day}, to split the table into chunks.} @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}:stepskip0 @r{Don't show steps that have zero time}:tags @r{A tags match to select entries that should contribute}:link @r{Link the item headlines in the table to their origins.}:formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.} @r{As a special case, @samp{:formula %} adds a column with % time.} @r{If you do not specify a formula here, any existing formula.} @r{below the clock table will survive updates and be evaluated.}:timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,} @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}@end exampleTo get a clock summary of the current level 1 tree, for the currentday, you could write@example#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t#+END: clocktable@end example@noindentand to use a specific time range you could write@footnote{Note that allparameters must be specified in a single line---the line is broken hereonly to fit it into the manual.}@example#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" :tend "<2006-08-10 Thu 12:00>"#+END: clocktable@end exampleA summary of the current subtree with % times would be@example#+BEGIN: clocktable :scope subtree :link t :formula %#+END: clocktable@end example@kindex C-c C-c@item C-c C-c@kindex C-c C-x C-u@itemx C-c C-x C-uUpdate dynamic block at point. The cursor needs to be in the@code{#+BEGIN} line of the dynamic block.@kindex C-u C-c C-x C-u@item C-u C-c C-x C-uUpdate all dynamic blocks (@pxref{Dynamic blocks}). This is useful ifyou have several clock table blocks in a buffer.@kindex S-@key{left}@kindex S-@key{right}@item S-@key{left}@itemx S-@key{right}Shift the current @code{:block} interval and update the table. The cursorneeds to be in the @code{#+BEGIN: clocktable} line for this command. If@code{:block} is @code{today}, it will be shifted to @code{today-1} etc.@end tableThe @kbd{l} key may be used in the timeline (@pxref{Timeline}) and inthe agenda (@pxref{Weekly/daily agenda}) to show which tasks have beenworked on or closed during a day.@node Resolving idle time, Effort estimates, Clocking work time, Dates and Times@section Resolving idle time@cindex resolve idle time@cindex idle, resolve, danglingIf you clock in on a work item, and then walk away from yourcomputer---perhaps to take a phone call---you often need to ``resolve'' thetime you were away by either subtracting it from the current clock, orapplying it to another one.@vindex org-clock-idle-timeBy customizing the variable @code{org-clock-idle-time} to some integer, suchas 10 or 15, Emacs can alert you when you get back to your computer afterbeing idle for that many minutes@footnote{On computers using Mac OS X,idleness is based on actual user idleness, not just Emacs' idle time. ForX11, you can install a utility program @file{x11idle.c}, available in theUTILITIES directory of the Org git distribution, to get the same generaltreatment of idleness. On other systems, idle time refers to Emacs idle timeonly.}, and ask what you want to do with the idle time. There will be aquestion waiting for you when you get back, indicating how much idle time haspassed (constantly updated with the current amount), as well as a set ofchoices to correct the discrepancy:@table @kbd@item kTo keep some or all of the minutes and stay clocked in, press @kbd{k}. Orgwill ask how many of the minutes to keep. Press @key{RET} to keep them all,effectively changing nothing, or enter a number to keep that many minutes.@item KIf you use the shift key and press @kbd{K}, it will keep however many minutesyou request and then immediately clock out of that task. If you keep all ofthe minutes, this is the same as just clocking out of the current task.@item sTo keep none of the minutes, use @kbd{s} to subtract all the away time fromthe clock, and then check back in from the moment you returned.@item STo keep none of the minutes and just clock out at the start of the away time,use the shift key and press @kbd{S}. Remember that using shift will alwaysleave you clocked out, no matter which option you choose.@item CTo cancel the clock altogether, use @kbd{C}. Note that if instead ofcanceling you subtract the away time, and the resulting clock amount is lessthan a minute, the clock will still be canceled rather than clutter up thelog with an empty entry.@end tableWhat if you subtracted those away minutes from the current clock, and nowwant to apply them to a new clock? Simply clock in to any task immediatelyafter the subtraction. Org will notice that you have subtracted time ``onthe books'', so to speak, and will ask if you want to apply those minutes tothe next task you clock in on.There is one other instance when this clock resolution magic occurs. Say youwere clocked in and hacking away, and suddenly your cat chased a mouse whoscared a hamster that crashed into your UPS's power button! You suddenlylose all your buffers, but thanks to auto-save you still have your recent Orgmode changes, including your last clock in.If you restart Emacs and clock into any task, Org will notice that you have adangling clock which was never clocked out from your last session. Usingthat 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 isidentical to dealing with away time due to idleness, it's just happening dueto a recovery event rather than a set amount of idle time.You can also check all the files visited by your Org agenda for danglingclocks at any time using @kbd{M-x org-resolve-clocks}.@node Effort estimates, Relative timer, Resolving idle time, Dates and Times@section Effort estimates@cindex effort estimates@cindex property, Effort@vindex org-effort-propertyIf you want to plan your work in a very detailed way, or if you need toproduce offers with quotations of the estimated work effort, you may want toassign effort estimates to entries. If you are also clocking your work, youmay later want to compare the planned effort with the actual working time, agreat way to improve planning estimates. Effort estimates are stored in aspecial property @samp{Effort}@footnote{You may change the property beingused with the variable @code{org-effort-property}.}. You can set the effortfor an entry with the following commands:@table @kbd@kindex C-c C-x e@item C-c C-x eSet the effort estimate for the current entry. With a numeric prefixargument, set it to the NTH allowed value (see below). This command is alsoaccessible from the agenda with the @kbd{e} key.@kindex C-c C-x C-e@item C-c C-x C-eModify the effort estimate of the item currently being clocked.@end tableClearly the best way to work with effort estimates is through column view(@pxref{Column view}). You should start by setting up discrete values foreffort estimates, and a @code{COLUMNS} format that displays these valuestogether with clock sums (if you want to clock your time). For a specificbuffer you can use@example#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 8:00#+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM@end example@noindent@vindex org-global-properties@vindex org-columns-default-formator, even better, you can set up these values globally by customizing thevariables @code{org-global-properties} and @code{org-columns-default-format}.In particular if you want to use this setup also in the agenda, a globalsetup may be advised.The way to assign estimates to individual items is then to switch to columnmode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change thevalue. The values you enter will immediately be summed up in the hierarchy.In the column next to it, any clocked time will be displayed.@vindex org-agenda-columns-add-appointments-to-effort-sumIf you switch to column view in the daily/weekly agenda, the effort columnwill summarize the estimated work effort for each day@footnote{Please notethe pitfalls of summing hierarchical data in a flat list (@pxref{Agendacolumn view}).}, and you can use this to find space in your schedule. To getan overview of the entire part of the day that is committed, you can set theoption @code{org-agenda-columns-add-appointments-to-effort-sum}. Theappointments on a day that take place over a specified time interval willthen also be added to the load estimate of the day.Effort estimates can be used in secondary agenda filtering that is triggeredwith the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you havethese estimates defined consistently, two or three key presses will narrowdown the list to stuff that fits into an available time slot.@node Relative timer, , Effort estimates, Dates and Times@section Taking notes with a relative timer@cindex relative timerWhen taking notes during, for example, a meeting or a video viewing, it canbe useful to have access to times relative to a starting time. Org providessuch a relative timer and make it easy to create timed notes.@table @kbd@kindex C-c C-x .@item C-c C-x .Insert a relative time into the buffer. The first time you use this, thetimer will be started. When called with a prefix argument, the timer isrestarted.@kindex C-c C-x -@item C-c C-x -Insert a description list item with the current relative time. With a prefixargument, first reset the timer to 0.@kindex M-@key{RET}@item M-@key{RET}Once the timer list is started, you can also use @kbd{M-@key{RET}} to insertnew timer items.@kindex C-c C-x ,@item C-c C-x ,Pause the timer, or continue it if it is already paused.@c removed the sentence because it is redundant to the following item@kindex C-u C-c C-x ,@item C-u C-c C-x ,Stop the timer. After this, you can only start a new timer, not continue theold one. This command also removes the timer from the mode line.@kindex C-c C-x 0@item C-c C-x 0Reset the timer without inserting anything into the buffer. By default, thetimer is reset to 0. When called with a @kbd{C-u} prefix, reset the timer tospecific starting offset. The user is prompted for the offset, with adefault taken from a timer string at point, if any, So this can be used torestart taking notes after a break in the process. When called with a doubleprefix argument @kbd{C-u C-u}, change all timer strings in the active regionby a certain amount. This can be used to fix timer strings if the timer wasnot started at exactly the right moment.@end table@node Capture - Refile - Archive, Agenda Views, Dates and Times, Top@chapter Capture - Refile - Archive@cindex captureAn important part of any organization system is the ability to quicklycapture new ideas and tasks, and to associate reference material with them.Org does this using a process called @i{capture}. It also can store filesrelated to a task (@i{attachments}) in a special directory. Once in thesystem, tasks and projects need to be moved around. Moving completed projecttrees to an archive file keeps the system compact and fast.@menu* Capture:: Capturing new stuff* Attachments:: Add files to tasks* RSS Feeds:: Getting input from RSS feeds* Protocols:: External (e.g. Browser) access to Emacs and Org* Refiling notes:: Moving a tree from one place to another* Archiving:: What to do with finished projects@end menu@node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive@section Capture@cindex captureOrg's method for capturing new items is heavily inspired by John Wiegleyexcellent remember package. Up to version 6.36 Org used a special setupfor @file{remember.el}. @file{org-remember.el} is still part of Org-mode forbackward compatibility with existing setups. You can find the documentationfor org-remember at @url{http://orgmode.org/org-remember.pdf}.The new capturing setup described here is preferred and should be used by newusers. To convert your @code{org-remember-templates}, run the command@example@kbd{M-x org-capture-import-remember-templates @key{RET}}@end example@noindent and then customize the new variable with @kbd{M-xcustomize-variable org-capture-templates}, check the result, and save thecustomization. You can then use both remember and capture untilyou are familiar with the new mechanism.Capture lets you quickly store notes with little interruption of your workflow. The basic process of capturing is very similar to remember, but Orgdoes enhance it with templates and more.@menu* Setting up capture:: Where notes will be stored* Using capture:: Commands to invoke and terminate capture* Capture templates:: Define the outline of different note types@end menu@node Setting up capture, Using capture, Capture, Capture@subsection Setting up captureThe following customization sets a default target file for notes, and definesa global key@footnote{Please select your own key, @kbd{C-c c} is only asuggestion.} for capturing new material.@example(setq org-default-notes-file (concat org-directory "/notes.org"))(define-key global-map "\C-cc" 'org-capture)@end example@node Using capture, Capture templates, Setting up capture, Capture@subsection Using capture@table @kbd@kindex C-c c@item C-c cCall the command @code{org-capture}. If you have templates defined@pxref{Capture templates}, it will offer these templates for selection or usea new Org outline node as the default template. It will insert the templateinto the target file and switch to an indirect buffer narrowed to this newnode. You may then insert the information you want.@kindex C-c C-c@item C-c C-cOnce you have finished entering information into the capture buffer, @kbd{C-c C-c} will return you to the window configuration before the captureprocess, so that you can resume your work without further distraction.@kindex C-c C-w@item C-c C-wFinalize the capture process by refiling (@pxref{Refiling notes}) the note toa different place.@kindex C-c C-k@item C-c C-kAbort the capture process and return to the previous state.@end tableYou can also call @code{org-capture} in a special way from the agenda, usingthe @kbd{k c} key combination. With this access, any timestamps inserted bythe selected capture template will default to the cursor date in the agenda,rather than to the current date.@node Capture templates, , Using capture, Capture@subsection Capture templates@cindex templates, for CaptureYou can use templates for different types of capture items, andfor different target locations. The easiest way to create such templates isthrough the customize interface.@table @kbd@kindex C-c c C@item C-c c CCustomize the variable @code{org-capture-templates}.@end tableBefore we give the formal description of template definitions, let's look atan example. Say you would like to use one template to create general TODOentries, and you want to put these entries under the heading @samp{Tasks} inyour file @file{~/org/gtd.org}. Also, a date tree in the file@file{journal.org} should capture journal entries. A possible configurationwould look like:@example(setq org-capture-templates '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks") "* TODO %?\n %i\n %a") ("j" "Journal" entry (file+datetree "~/org/journal.org") "* %?\nEntered on %U\n %i\n %a")))@end example@noindent If you then press @kbd{C-c c t}, Org will prepare the templatefor you like this:@example* TODO [[file:@var{link to where you initiated capture}]]@end example@noindentDuring expansion of the template, @code{%a} has been replaced by a link tothe location from where you called the capture command. This can beextremely useful for deriving tasks from emails, for example. You fill inthe task definition, press @code{C-c C-c} and Org returns you to the sameplace where you started the capture process.@menu* Template elements:: What is needed for a complete template entry* Template expansion:: Filling in information about time and context@end menu@node Template elements, Template expansion, Capture templates, Capture templates@subsubsection Template elementsNow lets look at the elements of a template definition. Each entry in@code{org-capture-templates} is a list with the following items: @table @var@item keysThe keys that will select the template, as a string, charactersonly, for example @code{"a"} for a template to be selected with asingle key, or @code{"bt"} for selection with two keys. When usingseveral keys, keys using the same prefix key must be sequential in the list and preceded by a 2-element entry explaining theprefix key, for example@example ("b" "Templates for marking stuff to buy")@end example@noindent If you do not define a template for the @kbd{C} key, this key willbe used to open the customize buffer for this complex variable.@item descriptionA short string describing the template, which will be shown duringselection.@item typeThe type of entry, a symbol. Valid values are:@table @code@item entryAn Org-mode node, with a headline. Will be filed as the child of thetarget entry or as a top-level entry. The target file should be an Org-modefile.@item itemA plain list item, placed in the first plain list at the targetlocation. Again the target file should be an Org file.@item checkitemA checkbox item. This only differs from the plain list item by thedefault template.@item table-linea new line in the first table at the target location. Where exactly theline will be inserted depends on the properties @code{:prepend} and@code{:table-line-pos} (see below).@item plainText to be inserted as it is.@end table@item targetSpecification of where the captured item should be placed.In Org-mode files, targets usually define a node. Entries will becomechildren of this node, other types will be added to the table or list in thebody of this node.Valid values are:@table @code@item (file "path/to/file")Text will be placed at the beginning or end of that file.@item (id "id of existing org entry")Filing as child of this entry, or in the body of the entry.@item (file+headline "path/to/file" "node headline")Fast configuration if the target heading is unique in the file.@item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)For non-unique headings, the full path is safer.@item (file+regexp "path/to/file" "regexp to find location")Use a regular expression to position the cursor.@item (file+datetree "path/to/file")Will create a heading in a date tree.@item (file+function "path/to/file" function-finding-location)A function to find the right location in the file.@item (clock)File to the entry that is currently being clocked.@item (function function-finding-location)Most general way, write your own function to find bothfile and location.@end table@item templateThe template for creating the capture item. If you leave this empty, anappropriate default template will be used. Otherwise this is a string withescape codes, which will be replaced depending on time and context of thecapture call. The string with escapes may be loaded from a template file,using the special syntax @code{(file "path/to/template")}. See below formore details.@item propertiesThe rest of the entry is a property list of additional options.Recognized properties are:@table @code@item :prependNormally new captured information will be appended atthe target location (last child, last table line, last list item...).Setting this property will change that.@item :immediate-finishWhen set, do not offer to edit the information, justfile it away immediately. This makes sense if the template only needsinformation that can be added automatically.@item :empty-linesSet this to the number of lines to insertbefore and after the new item. Default 0, only common other value is 1.@item :clock-inStart the clock in this item.@item :clock-resumeIf starting the capture interrupted a clock, restart that clock when finishedwith the capture.@item :unnarrowedDo not narrow the target buffer, simply show the full buffer. Default is tonarrow it so that you only see the new material.@end table@end table@node Template expansion, , Template elements, Capture templates@subsubsection Template expansionIn the template itself, special @kbd{%}-escapes@footnote{If you need one ofthese sequences literally, escape the @kbd{%} with a backslash.} allowdynamic insertion of content:@comment SJE: should these sentences terminate in period?@smallexample%^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.} @r{You may specify a default value and a completion table with} @r{%^@{prompt|default|completion2|completion3...@}} @r{The arrow keys access a prompt-specific history.}%a @r{annotation, normally the link created with @code{org-store-link}}%A @r{like @code{%a}, but prompt for the description part}%i @r{initial content, the region when capture is called while the} @r{region is active.} @r{The entire text will be indented like @code{%i} itself.}%t @r{timestamp, date only}%T @r{timestamp with date and time}%u, %U @r{like the above, but inactive timestamps}%^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}} @r{You may define a prompt like @code{%^@{Birthday@}t}}%n @r{user name (taken from @code{user-full-name})}%c @r{Current kill ring head.}%x @r{Content of the X clipboard.}%^C @r{Interactive selection of which kill or clip to use.}%^L @r{Like @code{%^C}, but insert as link.}%k @r{title of the currently clocked task}%K @r{link to the currently clocked task}%^g @r{prompt for tags, with completion on tags in target file.}%^G @r{prompt for tags, with completion all tags in all agenda files.}%^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}}%:keyword @r{specific information for certain link types, see below}%[@var{file}] @r{insert the contents of the file given by @var{file}}%(@var{sexp}) @r{evaluate Elisp @var{sexp} and replace with the result}@end smallexample@noindentFor specific link types, the following keywords will bedefined@footnote{If you define your own link types (@pxref{Addinghyperlink types}), any property you store with@code{org-store-link-props} can be accessed in capture templates in asimilar way.}:@vindex org-from-is-user-regexp@smallexampleLink type | Available keywords-------------------+----------------------------------------------bbdb | %:name %:companybbdb | %::server %:port %:nickvm, wl, mh, rmail | %:type %:subject %:message-id | %:from %:fromname %:fromaddress | %:to %:toname %:toaddress | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}}gnus | %:group, @r{for messages also all email fields}w3, w3m | %:urlinfo | %:file %:nodecalendar | %:date@end smallexample@noindentTo place the cursor after template expansion use:@smallexample%? @r{After completing the template, position cursor here.}@end smallexample@node Attachments, RSS Feeds, Capture, Capture - Refile - Archive@section Attachments@cindex attachments@vindex org-attach-directoryIt is often useful to associate reference material with an outline node/task.Small chunks of plain text can simply be stored in the subtree of a project.Hyperlinks (@pxref{Hyperlinks}) can establish associations withfiles that live elsewhere on your computer or in the cloud, like emails orsource code files belonging to a project. Another method is @i{attachments},which are files located in a directory belonging to an outline node. Orguses directories named by the unique ID of each entry. These directories arelocated in the @file{data} directory which lives in the same directory whereyour Org file lives@footnote{If you move entries or Org files from onedirectory to another, you may want to configure @code{org-attach-directory}to contain an absolute path.}. If you initialize this directory with@code{git init}, Org will automatically commit changes when it sees them.The attachment system has been contributed to Org by John Wiegley.In cases where it seems better to do so, you can also attach a directory of yourchoice to an entry. You can also make children inherit the attachmentdirectory from a parent, so that an entire subtree uses the same attacheddirectory.@noindent The following commands deal with attachments:@table @kbd@kindex C-c C-a@item C-c C-aThe dispatcher for commands related to the attachment system. After thesekeys, a list of commands is displayed and you must press an additional keyto select a command:@table @kbd@kindex C-c C-a a@item a@vindex org-attach-methodSelect a file and move it into the task's attachment directory. The filewill be copied, moved, or linked, depending on @code{org-attach-method}.Note that hard links are not supported on all systems.@kindex C-c C-a c@kindex C-c C-a m@kindex C-c C-a l@item c/m/lAttach a file using the copy/move/link method.Note that hard links are not supported on all systems.@kindex C-c C-a n@item nCreate a new attachment as an Emacs buffer.@kindex C-c C-a z@item zSynchronize the current task with its attachment directory, in case you addedattachments yourself.@kindex C-c C-a o@item o@vindex org-file-appsOpen current task's attachment. If there is more than one, prompt for afile name first. Opening will follow the rules set by @code{org-file-apps}.For more details, see the information on following hyperlinks(@pxref{Handling links}).@kindex C-c C-a O@item OAlso open the attachment, but force opening the file in Emacs.@kindex C-c C-a f@item fOpen the current task's attachment directory.@kindex C-c C-a F@item FAlso open the directory, but force using @command{dired} in Emacs.@kindex C-c C-a d@item dSelect and delete a single attachment.@kindex C-c C-a D@item DDelete all of a task's attachments. A safer way is to open the directory in@command{dired} and delete from there.@kindex C-c C-a s@item C-c C-a s@cindex property, ATTACH_DIRSet a specific directory as the entry's attachment directory. This works byputting the directory path into the @code{ATTACH_DIR} property.@kindex C-c C-a i@item C-c C-a i@cindex property, ATTACH_DIR_INHERITSet the @code{ATTACH_DIR_INHERIT} property, so that children will use thesame directory for attachments as the parent does.@end table@end table@node RSS Feeds, Protocols, Attachments, Capture - Refile - Archive@section RSS feeds@cindex RSS feeds@cindex Atom feedsOrg can add and change entries based on information found in RSS feeds andAtom feeds. You could use this to make a task out of each new podcast in apodcast feed. Or you could use a phone-based note-creating service on theweb to import tasks into Org. To access feeds, configure the variable@code{org-feed-alist}. The docstring of this variable has detailedinformation. Here is just an example:@example(setq org-feed-alist '(("Slashdot" "http://rss.slashdot.org/Slashdot/slashdot" "~/txt/org/feeds.org" "Slashdot Entries")))@end example@noindentwill configure that new items from the feed provided by@code{rss.slashdot.org} will result in new entries in the file@file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, wheneverthe following command is used:@table @kbd@kindex C-c C-x g@item C-c C-x gCollect items from the feeds configured in @code{org-feed-alist} and act uponthem.@kindex C-c C-x G@item C-c C-x GPrompt for a feed name and go to the inbox configured for this feed.@end tableUnder the same headline, Org will create a drawer @samp{FEEDSTATUS} in whichit will store information about the status of items in the feed, to avoidadding the same item several times. You should add @samp{FEEDSTATUS} to thelist of drawers in that file:@example#+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS@end exampleFor more information, including how to read atom feeds, see@file{org-feed.el} and the docstring of @code{org-feed-alist}.@node Protocols, Refiling notes, RSS Feeds, Capture - Refile - Archive@section Protocols for external access@cindex protocols, for external access@cindex emacsserverYou can set up Org for handling protocol calls from outside applications thatare passed to Emacs through the @file{emacsserver}. For example, you canconfigure bookmarks in your web browser to send a link to the current page toOrg and create a note from it using capture (@pxref{Capture}). Or youcould create a bookmark that will tell Emacs to open the local source file ofa remote website you are looking at with the browser. See@uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detaileddocumentation and setup instructions.@node Refiling notes, Archiving, Protocols, Capture - Refile - Archive@section Refiling notes@cindex refiling notesWhen reviewing the captured data, you may want to refile some of the entriesinto a different list, for example into a project. Cutting, finding theright location, and then pasting the note is cumbersome. To simplify thisprocess, you can use the following special command:@table @kbd@kindex C-c C-w@item C-c C-w@vindex org-reverse-note-order@vindex org-refile-targets@vindex org-refile-use-outline-path@vindex org-outline-path-complete-in-steps@vindex org-refile-allow-creating-parent-nodes@vindex org-log-refile@vindex org-refile-use-cacheRefile the entry or region at point. This command offers possible locationsfor refiling the entry and lets you select one with completion. The item (orall items in the region) is filed below the target heading as a subitem.Depending on @code{org-reverse-note-order}, it will be either the first orlast subitem.@*By default, all level 1 headlines in the current buffer are considered to betargets, but you can have more complex definitions across a number of files.See the variable @code{org-refile-targets} for details. If you would like toselect a location via a file-path-like completion along the outline path, seethe variables @code{org-refile-use-outline-path} and@code{org-outline-path-complete-in-steps}. If you would like to be able tocreate new nodes as new parents for refiling on the fly, check thevariable @code{org-refile-allow-creating-parent-nodes}.When the variable @code{org-log-refile}@footnote{with corresponding@code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},and @code{nologrefile}} is set, a time stamp or a note will berecorded when an entry has been refiled.@kindex C-u C-c C-w@item C-u C-c C-wUse the refile interface to jump to a heading.@kindex C-u C-u C-c C-w@item C-u C-u C-c C-wJump to the location where @code{org-refile} last moved a tree to.@item C-2 C-c C-wRefile as the child of the item currently being clocked.@item C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-wClear the target cache. Caching of refile targets can be turned on bysetting @code{org-refile-use-cache}. To make the command seen new possibletargets, you have to clear the cache with this command.@end table@node Archiving, , Refiling notes, Capture - Refile - Archive@section Archiving@cindex archivingWhen a project represented by a (sub)tree is finished, you may wantto move the tree out of the way and to stop it from contributing to theagenda. Archiving is important to keep your working files compact and globalsearches like the construction of agenda views fast.@table @kbd@kindex C-c C-x C-a@item C-c C-x C-a@vindex org-archive-default-commandArchive the current entry using the command specified in the variable@code{org-archive-default-command}.@end table@menu* Moving subtrees:: Moving a tree to an archive file* Internal archiving:: Switch off a tree but keep it in the file@end menu@node Moving subtrees, Internal archiving, Archiving, Archiving@subsection Moving a tree to the archive file@cindex external archivingThe most common archiving action is to move a project tree to another file,the archive file.@table @kbd@kindex C-c $@kindex C-c C-x C-s@item C-c C-x C-s@ @r{or short} @ C-c $@vindex org-archive-locationArchive the subtree starting at the cursor position to the locationgiven by @code{org-archive-location}.@kindex C-u C-c C-x C-s@item C-u C-c C-x C-sCheck if any direct children of the current headline could be moved tothe archive. To do this, each subtree is checked for open TODO entries.If none are found, the command offers to move it to the archivelocation. If the cursor is @emph{not} on a headline when this commandis invoked, the level 1 trees will be checked.@end table@cindex archive locationsThe default archive location is a file in the same directory as thecurrent file, with the name derived by appending @file{_archive} to thecurrent file name. For information and examples on how to change this,see the documentation string of the variable@code{org-archive-location}. There is also an in-buffer option forsetting this variable, for example@footnote{For backward compatibility,the following also works: If there are several such lines in a file,each specifies the archive location for the text below it. The firstsuch line also applies to any text before its definition. However,using this method is @emph{strongly} deprecated as it is incompatiblewith the outline structure of the document. The correct method forsetting multiple archive locations in a buffer is using properties.}:@cindex #+ARCHIVE@example#+ARCHIVE: %s_done::@end example@cindex property, ARCHIVE@noindentIf you would like to have a special ARCHIVE location for a single entryor a (sub)tree, give the entry an @code{:ARCHIVE:} property with thelocation as the value (@pxref{Properties and Columns}).@vindex org-archive-save-context-infoWhen a subtree is moved, it receives a number of special properties thatrecord context information like the file from where the entry came, itsoutline path the archiving time etc. Configure the variable@code{org-archive-save-context-info} to adjust the amount of informationadded.@node Internal archiving, , Moving subtrees, Archiving@subsection Internal archivingIf you want to just switch off (for agenda views) certain subtrees withoutmoving them to a different file, you can use the @code{ARCHIVE tag}.A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays atits location in the outline tree, but behaves in the following way:@itemize @minus@item@vindex org-cycle-open-archived-treesIt does not open when you attempt to do so with a visibility cyclingcommand (@pxref{Visibility cycling}). You can force cycling archivedsubtrees with @kbd{C-@key{TAB}}, or by setting the option@code{org-cycle-open-archived-trees}. Also normal outline commands like@code{show-all} will open archived subtrees.@item@vindex org-sparse-tree-open-archived-treesDuring sparse tree construction (@pxref{Sparse trees}), matches inarchived subtrees are not exposed, unless you configure the option@code{org-sparse-tree-open-archived-trees}.@item@vindex org-agenda-skip-archived-treesDuring agenda view construction (@pxref{Agenda Views}), the content ofarchived trees is ignored unless you configure the option@code{org-agenda-skip-archived-trees}, in which case these trees will alwaysbe included. In the agenda you can press @kbd{v a} to get archivestemporarily included.@item@vindex org-export-with-archived-treesArchived trees are not exported (@pxref{Exporting}), only the headlineis. Configure the details using the variable@code{org-export-with-archived-trees}.@item@vindex org-columns-skip-archived-treesArchived trees are excluded from column view unless the variable@code{org-columns-skip-archived-trees} is configured to @code{nil}.@end itemizeThe following commands help manage the ARCHIVE tag:@table @kbd@kindex C-c C-x a@item C-c C-x aToggle the ARCHIVE tag for the current headline. When the tag is set,the headline changes to a shadowed face, and the subtree below it ishidden.@kindex C-u C-c C-x a@item C-u C-c C-x aCheck if any direct children of the current headline should be archived.To do this, each subtree is checked for open TODO entries. If none arefound, the command offers to set the ARCHIVE tag for the child. If thecursor is @emph{not} on a headline when this command is invoked, thelevel 1 trees will be checked.@kindex C-@kbd{TAB}@item C-@kbd{TAB}Cycle a tree even if it is tagged with ARCHIVE.@kindex C-c C-x A@item C-c C-x AMove the current entry to the @emph{Archive Sibling}. This is a sibling ofthe entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. Theentry becomes a child of that sibling and in this way retains a lot of itsoriginal context, including inherited tags and approximate position in theoutline.@end table@node Agenda Views, Markup, Capture - Refile - Archive, Top@chapter Agenda views@cindex agenda viewsDue to the way Org works, TODO items, time-stamped items, andtagged headlines can be scattered throughout a file or even a number offiles. To get an overview of open action items, or of events that areimportant 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 themin a separate buffer. Seven different view types are provided:@itemize @bullet@iteman @emph{agenda} that is like a calendar and shows informationfor specific dates,@itema @emph{TODO list} that covers all unfinishedaction items,@itema @emph{match view}, showings headlines based on the tags, properties, andTODO state associated with them,@itema @emph{timeline view} that shows all events in a single Org file,in time-sorted view,@itema @emph{text search view} that shows all entries from multiple filesthat contain specified keywords,@itema @emph{stuck projects view} showing projects that currently don't movealong, and@item@emph{custom views} that are special searches and combinations of differentviews.@end itemize@noindentThe extracted information is displayed in a special @emph{agendabuffer}. This buffer is read-only, but provides commands to visit thecorresponding locations in the original Org files, and even toedit these files remotely.@vindex org-agenda-window-setup@vindex org-agenda-restore-windows-after-quitTwo variables control how the agenda buffer is displayed and whether thewindow configuration is restored when the agenda exits:@code{org-agenda-window-setup} and@code{org-agenda-restore-windows-after-quit}.@menu* Agenda files:: Files being searched for agenda information* Agenda dispatcher:: Keyboard access to agenda views* Built-in agenda views:: What is available out of the box?* Presentation and sorting:: How agenda items are prepared for display* Agenda commands:: Remote editing of Org trees* Custom agenda views:: Defining special searches and views* Exporting Agenda Views:: Writing a view to a file* Agenda column view:: Using column view for collected entries@end menu@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views@section Agenda files@cindex agenda files@cindex files for agenda@vindex org-agenda-filesThe information to be shown is normally collected from all @emph{agendafiles}, the files listed in the variable@code{org-agenda-files}@footnote{If the value of that variable is not alist, but a single file name, then the list of agenda files will bemaintained in that external file.}. If a directory is part of this list,all files with the extension @file{.org} in this directory will be partof the list.Thus, even if you only work with a single Org file, that file shouldbe put into the list@footnote{When using the dispatcher, pressing@kbd{<} before selecting a command will actually limit the command tothe current file, and ignore @code{org-agenda-files} until the nextdispatcher command.}. You can customize @code{org-agenda-files}, butthe easiest way to maintain it is through the following commands@cindex files, adding to agenda list@table @kbd@kindex C-c [@item C-c [Add current file to the list of agenda files. The file is added tothe front of the list. If it was already in the list, it is moved tothe front. With a prefix argument, file is added/moved to the end.@kindex C-c ]@item C-c ]Remove current file from the list of agenda files.@kindex C-,@kindex C-'@item C-,@itemx C-'Cycle through agenda file list, visiting one file after the other.@kindex M-x org-iswitchb@item M-x org-iswitchbCommand to use an @code{iswitchb}-like interface to switch to and between Orgbuffers.@end table@noindentThe Org menu contains the current list of files and can be usedto visit any of them.If you would like to focus the agenda temporarily on a file not inthis list, or on just one file in the list, or even on only a subtree in afile, then this can be done in different ways. For a single agenda command,you may press @kbd{<} once or several times in the dispatcher(@pxref{Agenda dispatcher}). To restrict the agenda scope for anextended period, use the following commands:@table @kbd@kindex C-c C-x <@item C-c C-x <Permanently restrict the agenda to the current subtree. When with aprefix argument, or with the cursor before the first headline in a file,the agenda scope is set to the entire file. This restriction remains ineffect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}or @kbd{>} in the agenda dispatcher. If there is a window displaying anagenda view, the new restriction takes effect immediately.@kindex C-c C-x >@item C-c C-x >Remove the permanent restriction created by @kbd{C-c C-x <}.@end table@noindentWhen working with @file{speedbar.el}, you can use the following commands inthe Speedbar frame:@table @kbd@kindex <@item < @r{in the speedbar frame}Permanently restrict the agenda to the item---either an Org file or a subtreein such a file---at the cursor in the Speedbar frame.If there is a window displaying an agenda view, the new restriction takeseffect immediately.@kindex >@item > @r{in the speedbar frame}Lift the restriction.@end table@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views@section The agenda dispatcher@cindex agenda dispatcher@cindex dispatching agenda commandsThe views are created through a dispatcher, which should be bound to aglobal key---for example @kbd{C-c a} (@pxref{Installation}). In thefollowing we will assume that @kbd{C-c a} is indeed how the dispatcheris accessed and list keyboard access to commands accordingly. Afterpressing @kbd{C-c a}, an additional letter is required to execute acommand. The dispatcher offers the following default commands:@table @kbd@item aCreate the calendar-like agenda (@pxref{Weekly/daily agenda}).@item t @r{/} TCreate a list of all TODO items (@pxref{Global TODO list}).@item m @r{/} MCreate a list of headlines matching a TAGS expression (@pxref{Matchingtags and properties}).@item LCreate the timeline view for the current buffer (@pxref{Timeline}).@item sCreate a list of entries selected by a boolean expression of keywordsand/or regular expressions that must or must not occur in the entry.@item /@vindex org-agenda-text-search-extra-filesSearch for a regular expression in all agenda files and additionally inthe files listed in @code{org-agenda-text-search-extra-files}. Thisuses the Emacs command @code{multi-occur}. A prefix argument can beused to specify the number of context lines for each match, default is1.@item # @r{/} !Create a list of stuck projects (@pxref{Stuck projects}).@item <Restrict an agenda command to the current buffer@footnote{For backwardcompatibility, you can also press @kbd{1} to restrict to the currentbuffer.}. After pressing @kbd{<}, you still need to press the characterselecting the command.@item < <If there is an active region, restrict the following agenda command tothe region. Otherwise, restrict it to the current subtree@footnote{Forbackward compatibility, you can also press @kbd{0} to restrict to thecurrent region/subtree.}. After pressing @kbd{< <}, you still need to press thecharacter selecting the command.@end tableYou can also define custom commands that will be accessible through thedispatcher, just like the default commands. This includes thepossibility to create extended agenda buffers that contain severalblocks together, for example the weekly agenda, the global TODO list anda number of special tags matches. @xref{Custom agenda views}.@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda Views@section The built-in agenda viewsIn this section we describe the built-in views.@menu* Weekly/daily agenda:: The calendar page with current tasks* Global TODO list:: All unfinished action items* Matching tags and properties:: Structured information with fine-tuned search* Timeline:: Time-sorted view for single file* Search view:: Find entries by searching for text* Stuck projects:: Find projects you need to review@end menu@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views@subsection The weekly/daily agenda@cindex agenda@cindex weekly agenda@cindex daily agendaThe purpose of the weekly/daily @emph{agenda} is to act like a page of apaper agenda, showing all the tasks for the current week or day.@table @kbd@cindex org-agenda, command@kindex C-c a a@item C-c a a@vindex org-agenda-ndaysCompile an agenda for the current week from a list of Org files. The agendashows the entries for each day. With a numeric prefix@footnote{For backwardcompatibility, the universal prefix @kbd{C-u} causes all TODO entries to belisted before the agenda. This feature is deprecated, use the dedicated TODOlist, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1C-c a a}) you may set the number of days to be displayed (see also thevariable @code{org-agenda-ndays})@end tableRemote editing from the agenda buffer means, for example, that you canchange the dates of deadlines and appointments from the agenda buffer.The commands available in the Agenda buffer are listed in @ref{Agendacommands}.@subsubheading Calendar/Diary integration@cindex calendar integration@cindex diary integrationEmacs contains the calendar and diary by Edward M. Reingold. Thecalendar displays a three-month calendar with holidays from differentcountries and cultures. The diary allows you to keep track ofanniversaries, lunar phases, sunrise/set, recurrent appointments(weekly, monthly) and more. In this way, it is quite complementary toOrg. It can be very useful to combine output from Org withthe diary.In order to include entries from the Emacs diary into Org-mode'sagenda, you only need to customize the variable@lisp(setq org-agenda-include-diary t)@end lisp@noindent After that, everything will happen automatically. All diaryentries including holidays, anniversaries, etc., will be included in theagenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and@key{RET} can be used from the agenda buffer to jump to the diaryfile in order to edit existing diary entries. The @kbd{i} command toinsert new entries for the current date works in the agenda buffer, aswell as the commands @kbd{S}, @kbd{M}, and @kbd{C} to displaySunrise/Sunset times, show lunar phases and to convert to othercalendars, respectively. @kbd{c} can be used to switch back and forthbetween calendar and agenda.If you are using the diary only for sexp entries and holidays, it isfaster to not use the above setting, but instead to copy or even movethe entries into an Org file. Org-mode evaluates diary-style sexpentries, and does it faster because there is no overhead for firstcreating the diary display. Note that the sexp entries must start atthe left margin, no whitespace is allowed before them. For example,the following segment of an Org file will be processed and entrieswill be made in the agenda:@example* Birthdays and similar stuff#+CATEGORY: Holiday%%(org-calendar-holiday) ; special function for holiday names#+CATEGORY: Ann%%(diary-anniversary 5 14 1956)@footnote{Note that the order of the arguments (month, day, year) depends on the setting of @code{calendar-date-style}.} Arthur Dent is %d years old%%(diary-anniversary 10 2 1869) Mahatma Gandhi would be %d years old@end example@subsubheading Anniversaries from BBDB@cindex BBDB, anniversaries@cindex anniversaries, from BBDBIf you are using the Big Brothers Database to store your contacts, you willvery likely prefer to store anniversaries in BBDB rather than in aseparate Org or diary file. Org supports this and will show BBDBanniversaries as part of the agenda. All you need to do is to add thefollowing to one your your agenda files:@example* Anniversaries :PROPERTIES: :CATEGORY: Anniv :END:%%(org-bbdb-anniversaries)@end exampleYou can then go ahead and define anniversaries for a BBDB record. Basically,you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDBrecord and then add the date in the format @code{YYYY-MM-DD}, followed by aspace and the class of the anniversary (@samp{birthday} or @samp{wedding}, ora format string). If you omit the class, it will default to @samp{birthday}.Here are a few examples, the header for the file @file{org-bbdb.el} containsmore detailed information.@example1973-06-221955-08-02 wedding2008-04-14 %s released version 6.01 of org-mode, %d years ago@end exampleAfter a change to BBDB, or for the first agenda display during an Emacssession, the agenda display will suffer a short delay as Org updates itshash with anniversaries. However, from then on things will be very fast---muchfaster in fact than a long list of @samp{%%(diary-anniversary)} entriesin an Org or Diary file.@subsubheading Appointment reminders@cindex @file{appt.el}@cindex appointment remindersOrg can interact with Emacs appointments notification facility. To add allthe appointments of your agenda files, use the command@code{org-agenda-to-appt}. This command also lets you filter through thelist of your appointments and add only those belonging to a specific categoryor matching a regular expression. See the docstring for details.@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views@subsection The global TODO list@cindex global TODO list@cindex TODO list, globalThe global TODO list contains all unfinished TODO items formatted andcollected into a single place.@table @kbd@kindex C-c a t@item C-c a tShow the global TODO list. This collects the TODO items from all agendafiles (@pxref{Agenda Views}) into a single buffer. By default, this listsitems with a state the is not a DONE state. The buffer is in@code{agenda-mode}, so there are commands to examine and manipulate the TODOentries directly from that buffer (@pxref{Agenda commands}).@kindex C-c a T@item C-c a T@cindex TODO keyword matching@vindex org-todo-keywordsLike the above, but allows selection of a specific TODO keyword. You canalso do this by specifying a prefix argument to @kbd{C-c a t}. You areprompted for a keyword, and you may also specify several keywords byseparating them with @samp{|} as the boolean OR operator. With a numericprefix, the nth keyword in @code{org-todo-keywords} is selected.@kindex rThe @kbd{r} key in the agenda buffer regenerates it, and you can givea prefix argument to this command to change the selected TODO keyword,for example @kbd{3 r}. If you often need a search for a specifickeyword, define a custom command for it (@pxref{Agenda dispatcher}).@*Matching specific TODO keywords can also be done as part of a tagssearch (@pxref{Tag searches}).@end tableRemote editing of TODO items means that you can change the state of aTODO entry with a single key press. The commands available in theTODO list are described in @ref{Agenda commands}.@cindex sublevels, inclusion into TODO listNormally the global TODO list simply shows all headlines with TODOkeywords. This list can become very long. There are two ways to keepit more compact:@itemize @minus@item@vindex org-agenda-todo-ignore-scheduled@vindex org-agenda-todo-ignore-deadlines@vindex org-agenda-todo-ignore-with-dateSome people view a TODO item that has been @emph{scheduled} for execution orhave a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.Configure the variables @code{org-agenda-todo-ignore-scheduled},@code{org-agenda-todo-ignore-deadlines}, and/or@code{org-agenda-todo-ignore-with-date} to exclude such items from theglobal TODO list.@item@vindex org-agenda-todo-list-sublevelsTODO items may have sublevels to break up the task into subtasks. Insuch cases it may be enough to list only the highest level TODO headlineand omit the sublevels from the global list. Configure the variable@code{org-agenda-todo-list-sublevels} to get this behavior.@end itemize@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views@subsection Matching tags and properties@cindex matching, of tags@cindex matching, of properties@cindex tags view@cindex match viewIf headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),or have properties (@pxref{Properties and Columns}), you can select headlinesbased on this metadata and collect them into an agenda buffer. The matchsyntax described here also applies when creating sparse trees with @kbd{C-c /m}.@table @kbd@kindex C-c a m@item C-c a mProduce a list of all headlines that match a given set of tags. Thecommand prompts for a selection criterion, which is a boolean logicexpression with tags, like @samp{+work+urgent-withboss} or@samp{work|home} (@pxref{Tags}). If you often need a specific search,define a custom command for it (@pxref{Agenda dispatcher}).@kindex C-c a M@item C-c a M@vindex org-tags-match-list-sublevels@vindex org-agenda-tags-todo-honor-ignore-optionsLike @kbd{C-c a m}, but only select headlines that are also TODO items in anot-DONE state and force checking subitems (see variable@code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items,see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matchingspecific TODO keywords together with a tags match is also possible, see@ref{Tag searches}.@end tableThe commands available in the tags list are described in @ref{Agendacommands}.@subsubheading Match syntax@cindex Boolean logic, for tag/property searchesA search string can use Boolean operators @samp{&} for AND and @samp{|} forOR. @samp{&} binds more strongly than @samp{|}. Parentheses are currentlynot implemented. Each element in the search is either a tag, a regularexpression matching tags, or an expression like @code{PROPERTY OPERATORVALUE} with a comparison operator, accessing a property value. Each elementmay be preceded by @samp{-}, to select against it, and @samp{+} is syntacticsugar for positive selection. The AND operator @samp{&} is optional when@samp{+} or @samp{-} is present. Here are some examples, using only tags.@table @samp@item +work-bossSelect headlines tagged @samp{:work:}, but discard those also tagged@samp{:boss:}.@item work|laptopSelects lines tagged @samp{:work:} or @samp{:laptop:}.@item work|laptop+nightLike before, but require the @samp{:laptop:} lines to be tagged also@samp{:night:}.@end table@cindex regular expressions, with tags searchInstead of a tag, you may also specify a regular expression enclosed in curlybraces. For example,@samp{work+@{^boss.*@}} matches headlines that contain the tag@samp{:work:} and any tag @i{starting} with @samp{boss}.@cindex TODO keyword matching, with tags search@cindex level, require for tags/property match@cindex category, require for tags/property match@vindex org-odd-levels-onlyYou may also test for properties (@pxref{Properties and Columns}) at the sametime as matching tags. The properties may be real properties, or specialproperties that represent other metadata (@pxref{Special properties}). Forexample, the ``property'' @code{TODO} represents the TODO keyword of theentry. Or, the ``property'' @code{LEVEL} represents the level of an entry.So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlinesthat have the tag @samp{boss} and are @emph{not} marked with the TODO keywordDONE. In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does notcount the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.Here are more examples:@table @samp@item work+TODO="WAITING"Select @samp{:work:}-tagged TODO lines with the specific TODOkeyword @samp{WAITING}.@item work+TODO="WAITING"|home+TODO="WAITING"Waiting tasks both at work and at home.@end tableWhen matching properties, a number of different operators can be used to testthe value of a property. Here is a complex example:@example+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \ +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"@end example@noindentThe type of comparison will depend on how the comparison value is written:@itemize @minus@itemIf the comparison value is a plain number, a numerical comparison is done,and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},@samp{>=}, and @samp{<>}.@itemIf the comparison value is enclosed in double-quotes,a string comparison is done, and the same operators are allowed.@itemIf the comparison value is enclosed in double-quotes @emph{and} angularbrackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values areassumed to be date/time specifications in the standard Org way, and thecomparison will be done accordingly. Special values that will be recognizedare @code{"<now>"} for now (including time), and @code{"<today>"}, and@code{"<tomorrow>"} for these days at 0:00 hours, i.e. without a timespecification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,respectively, can be used.@itemIf the comparison value is enclosedin curly braces, a regexp match is performed, with @samp{=} meaning that theregexp matches the property value, and @samp{<>} meaning that it does notmatch.@end itemizeSo the search string in the example finds entries tagged @samp{:work:} butnot @samp{:boss:}, which also have a priority value @samp{A}, a@samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}property that is numerically smaller than 2, a @samp{:With:} property that ismatched by the regular expression @samp{Sarah\|Denny}, and that are scheduledon or after October 11, 2008.Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing anyother properties will slow down the search. However, once you have paid theprice by accessing one property, testing additional properties is cheapagain.You can configure Org-mode to use property inheritance during a search, butbeware that this can slow down searches considerably. See @ref{Propertyinheritance}, for details.For backward compatibility, and also for typing speed, there is also adifferent way to test TODO states in a search. For this, terminate thetags/property part of the search string (which may include several termsconnected with @samp{|}) with a @samp{/} and then specify a Booleanexpression just for TODO keywords. The syntax is then similar to that fortags, but should be applied with care: for example, a positive selection onseveral TODO keywords cannot meaningfully be combined with boolean AND.However, @emph{negative selection} combined with AND can be meaningful. Tomake sure that only lines are checked that actually have any TODO keyword(resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODOpart after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} willnot match TODO keywords in a DONE state. Examples:@table @samp@item work/WAITINGSame as @samp{work+TODO="WAITING"}@item work/!-WAITING-NEXTSelect @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}nor @samp{NEXT}@item work/!+WAITING|+NEXTSelect @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or@samp{NEXT}.@end table@node Timeline, Search view, Matching tags and properties, Built-in agenda views@subsection Timeline for a single file@cindex timeline, single file@cindex time-sorted viewThe timeline summarizes all time-stamped items from a single Org-modefile in a @emph{time-sorted view}. The main purpose of this command isto give an overview over events in a project.@table @kbd@kindex C-c a L@item C-c a LShow a time-sorted view of the Org file, with all time-stamped items.When called with a @kbd{C-u} prefix, all unfinished TODO entries(scheduled or not) are also listed under the current date.@end table@noindentThe commands available in the timeline buffer are listed in@ref{Agenda commands}.@node Search view, Stuck projects, Timeline, Built-in agenda views@subsection Search view@cindex search view@cindex text search@cindex searching, for textThis agenda view is a general text search facility for Org-mode entries.It is particularly useful to find notes.@table @kbd@kindex C-c a s@item C-c a sThis is a special search that lets you select entries by matching a substringor specific words using a boolean logic.@end tableFor example, the search string @samp{computer equipment} will find entriesthat contain @samp{computer equipment} as a substring. If the two words areseparated by more space or a line break, the search will still match.Search view can also search for specific keywords in the entry, using Booleanlogic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}will search for note entries that contain the keywords @code{computer}and @code{wifi}, but not the keyword @code{ethernet}, and which are alsonot matched by the regular expression @code{8\.11[bg]}, meaning toexclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn onword search, other @samp{+} characters are optional. For more details, seethe docstring of the command @code{org-search-view}.@vindex org-agenda-text-search-extra-filesNote that in addition to the agenda files, this command will also searchthe files listed in @code{org-agenda-text-search-extra-files}.@node Stuck projects, , Search view, Built-in agenda views@subsection Stuck projectsIf you are following a system like David Allen's GTD to organize yourwork, one of the ``duties'' you have is a regular review to make surethat all projects move along. A @emph{stuck} project is a project thathas no defined next actions, so it will never show up in the TODO listsOrg-mode produces. During the review, you need to identify suchprojects and define next actions for them.@table @kbd@kindex C-c a #@item C-c a #List projects that are stuck.@kindex C-c a !@item C-c a !@vindex org-stuck-projectsCustomize the variable @code{org-stuck-projects} to define what a stuckproject is and how to find it.@end tableYou almost certainly will have to configure this view before it willwork for you. The built-in default assumes that all your projects arelevel-2 headlines, and that a project is not stuck if it has at leastone entry marked with a TODO keyword TODO or NEXT or NEXTACTION.Let's assume that you, in your own way of using Org-mode, identifyprojects with a tag PROJECT, and that you use a TODO keyword MAYBE toindicate a project that should not be considered yet. Let's furtherassume that the TODO keyword DONE marks finished projects, and that NEXTand TODO indicate next actions. The tag @@SHOP indicates shopping andis a next action even without the NEXT tag. Finally, if the projectcontains the special word IGNORE anywhere, it should not be listedeither. In this case you would start by identifying eligible projectswith a tags/todo match@footnote{@xref{Tag searches}.}@samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, andIGNORE in the subtree to identify projects that are not stuck. Thecorrect customization for this is@lisp(setq org-stuck-projects '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP") "\\<IGNORE\\>"))@end lispNote that if a project is identified as non-stuck, the subtree of this entrywill still be searched for stuck projects.@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda Views@section Presentation and sorting@cindex presentation, of agenda items@vindex org-agenda-prefix-formatBefore displaying items in an agenda view, Org-mode visually preparesthe items and sorts them. Each item occupies a single line. The linestarts with a @emph{prefix} that contains the @emph{category}(@pxref{Categories}) of the item and other important information. You cancustomize the prefix using the option @code{org-agenda-prefix-format}.The prefix is followed by a cleaned-up version of the outline headlineassociated with the item.@menu* Categories:: Not all tasks are equal* Time-of-day specifications:: How the agenda knows the time* Sorting of agenda items:: The order of things@end menu@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting@subsection Categories@cindex categoryThe category is a broad label assigned to each agenda item. By default,the category is simply derived from the file name, but you can alsospecify it with a special line in the buffer, like this@footnote{Forbackward compatibility, the following also works: if there are severalsuch lines in a file, each specifies the category for the text below it.The first category also applies to any text before the first CATEGORYline. However, using this method is @emph{strongly} deprecated as it isincompatible with the outline structure of the document. The correctmethod for setting multiple categories in a buffer is using aproperty.}:@example#+CATEGORY: Thesis@end example@noindent@cindex property, CATEGORYIf you would like to have a special CATEGORY for a single entry or a(sub)tree, give the entry a @code{:CATEGORY:} property with thespecial category you want to apply as the value.@noindentThe display in the agenda buffer looks best if the category is notlonger than 10 characters.@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting@subsection Time-of-day specifications@cindex time-of-day specificationOrg-mode checks each agenda item for a time-of-day specification. Thetime can be part of the timestamp that triggered inclusion into theagenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Timeranges can be specified with two timestamps, like@c@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.In the headline of the entry itself, a time(range) may also appear asplain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agendaintegrates the Emacs diary (@pxref{Weekly/daily agenda}), timespecifications in diary entries are recognized as well.For agenda display, Org-mode extracts the time and displays it in astandard 24 hour format as part of the prefix. The example times inthe previous paragraphs would end up in the agenda like this:@example 8:30-13:00 Arthur Dent lies in front of the bulldozer 12:45...... Ford Prefect arrives and takes Arthur to the pub 19:00...... The Vogon reads his poem 20:30-22:15 Marvin escorts the Hitchhikers to the bridge@end example@cindex time gridIf the agenda is in single-day mode, or for the display of today, thetimed entries are embedded in a time grid, like@example 8:00...... ------------------ 8:30-13:00 Arthur Dent lies in front of the bulldozer 10:00...... ------------------ 12:00...... ------------------ 12:45...... Ford Prefect arrives and takes Arthur to the pub 14:00...... ------------------ 16:00...... ------------------ 18:00...... ------------------ 19:00...... The Vogon reads his poem 20:00...... ------------------ 20:30-22:15 Marvin escorts the Hitchhikers to the bridge@end example@vindex org-agenda-use-time-grid@vindex org-agenda-time-gridThe time grid can be turned on and off with the variable@code{org-agenda-use-time-grid}, and can be configured with@code{org-agenda-time-grid}.@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting@subsection Sorting of agenda items@cindex sorting, of agenda items@cindex priorities, of agenda itemsBefore being inserted into a view, the items are sorted. How this isdone depends on the type of view.@itemize @bullet@item@vindex org-agenda-filesFor the daily/weekly agenda, the items for each day are sorted. Thedefault order is to first collect all items containing an explicittime-of-day specification. These entries will be shown at the beginningof the list, as a @emph{schedule} for the day. After that, items remaingrouped in categories, in the sequence given by @code{org-agenda-files}.Within each category, items are sorted by priority (@pxref{Priorities}),which is composed of the base priority (2000 for priority @samp{A}, 1000for @samp{B}, and 0 for @samp{C}), plus additional increments foroverdue scheduled or deadline items.@itemFor the TODO list, items remain in the order of categories, but withineach category, sorting takes place according to priority(@pxref{Priorities}). The priority used for sorting derives from thepriority cookie, with additions depending on how close an item is to its dueor scheduled date.@itemFor tags matches, items are not sorted at all, but just appear in thesequence in which they are found in the agenda files.@end itemize@vindex org-agenda-sorting-strategySorting can be customized using the variable@code{org-agenda-sorting-strategy}, and may also include criteria based onthe estimated effort of an entry (@pxref{Effort estimates}).@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views@section Commands in the agenda buffer@cindex commands, in agenda bufferEntries in the agenda buffer are linked back to the Org file or diaryfile where they originate. You are not allowed to edit the agendabuffer itself, but commands are provided to show and jump to theoriginal entry location, and to edit the Org files ``remotely'' fromthe 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. Forthe other commands, the cursor needs to be in the desired line.@table @kbd@tsubheading{Motion}@cindex motion commands in agenda@kindex n@item nNext line (same as @key{up} and @kbd{C-p}).@kindex p@item pPrevious line (same as @key{down} and @kbd{C-n}).@tsubheading{View/Go to Org file}@kindex mouse-3@kindex @key{SPC}@item mouse-3@itemx @key{SPC}Display the original location of the item in another window.With prefix arg, make sure that the entire entry is made visible in theoutline, not only the heading.@c@kindex L@item LDisplay original location and recenter that window.@c@kindex mouse-2@kindex mouse-1@kindex @key{TAB}@item mouse-2@itemx mouse-1@itemx @key{TAB}Go to the original location of the item in another window. Under Emacs22, @kbd{mouse-1} will also works for this.@c@kindex @key{RET}@itemx @key{RET}Go to the original location of the item and delete other windows.@c@kindex F@item F@vindex org-agenda-start-with-follow-modeToggle Follow mode. In Follow mode, as you move the cursor throughthe agenda buffer, the other window always shows the correspondinglocation in the Org file. The initial setting for this mode in newagenda buffers can be set with the variable@code{org-agenda-start-with-follow-mode}.@c@kindex C-c C-x b@item C-c C-x bDisplay the entire subtree of the current item in an indirect buffer. With anumeric prefix argument N, go up to level N and then take that tree. If N isnegative, go up that many levels. With a @kbd{C-u} prefix, do not remove thepreviously used indirect buffer.@kindex C-c C-o@item C-c C-oFollow a link in the entry. This will offer a selection of any links in thetext belonging to the referenced Org node. If there is only one link, itwill be followed without a selection prompt.@tsubheading{Change display}@cindex display changing, in agenda@kindex o@item oDelete other windows.@c@kindex v d@kindex d@kindex v w@kindex w@kindex v m@kindex v y@item v d @ @r{or short} @ d@itemx v w @ @r{or short} @ w@itemx v m@itemx v ySwitch to day/week/month/year view. When switching to day or week view,this setting becomes the default for subsequent agenda commands. Sincemonth 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 dayof the year, ISO week, month, or year, respectively. For example,@kbd{32 d} jumps to February 1st, @kbd{9 w} to ISO week number 9. Whensetting day, week, or month view, a year may be encoded in the prefixargument as well. For example, @kbd{200712 w} will jump to week 12 in2007. If such a year specification has only one or two digits, it willbe mapped to the interval 1938-2037.@c@kindex f@item f@vindex org-agenda-ndaysGo forward in time to display the following @code{org-agenda-ndays} days.For example, if the display covers a week, switch to the following week.With prefix arg, go forward that many times @code{org-agenda-ndays} days.@c@kindex b@item bGo backward in time to display earlier dates.@c@kindex .@item .Go to today.@c@kindex j@item jPrompt for a date and go there.@c@kindex D@item DToggle the inclusion of diary entries. See @ref{Weekly/daily agenda}.@c@kindex v l@kindex v L@kindex l@item v l @ @r{or short} @ l@vindex org-log-done@vindex org-agenda-log-mode-itemsToggle Logbook mode. In Logbook mode, entries that were marked DONE whilelogging was on (variable @code{org-log-done}) are shown in the agenda, as areentries that have been clocked on that day. You can configure the entrytypes that should be included in log mode using the variable@code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, showall possible logbook entries, including state changes. When called with twoprefix args @kbd{C-u C-u}, show only logging information, nothing else.@kbd{v L} is equivalent to @kbd{C-u v l}.@c@kindex v [@kindex [@item v [ @ @r{or short} @ [Include inactive timestamps into the current view. Only for weekly/dailyagenda and timeline views.@c@kindex v a@kindex v A@item v a@itemx v AToggle Archives mode. In Archives mode, trees that are marked@code{ARCHIVED} are also scanned when producing the agenda. When you use thecapital @kbd{A}, even all archive files are included. To exit archives mode,press @kbd{v a} again.@c@kindex v R@kindex R@item v R @ @r{or short} @ R@vindex org-agenda-start-with-clockreport-modeToggle Clockreport mode. In Clockreport mode, the daily/weekly agenda willalways show a table with the clocked times for the timespan and file scopecovered by the current agenda view. The initial setting for this mode in newagenda buffers can be set with the variable@code{org-agenda-start-with-clockreport-mode}.@c@kindex v E@kindex E@item v E @ @r{or short} @ E@vindex org-agenda-start-with-entry-text-mode@vindex org-agenda-entry-text-maxlinesToggle entry text mode. In entry text mode, a number of lines from the Orgoutline node referenced by an agenda line will be displayed below the line.The maximum number of lines is given by the variable@code{org-agenda-entry-text-maxlines}. Calling this command with a numericprefix argument will temporarily modify that number to the prefix value.@c@kindex G@item G@vindex org-agenda-use-time-grid@vindex org-agenda-time-gridToggle the time grid on and off. See also the variables@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.@c@kindex r@item rRecreate the agenda buffer, for example to reflect the changes aftermodification of the timestamps of items with @kbd{S-@key{left}} and@kbd{S-@key{right}}. When the buffer is the global TODO list, a prefixargument is interpreted to create a selective list for a specific TODOkeyword.@kindex g@item gSame as @kbd{r}.@c@kindex s@kindex C-x C-s@item s@itemx C-x C-sSave all Org buffers in the current Emacs session, and also the locations ofIDs.@c@kindex C-c C-x C-c@item C-c C-x C-c@vindex org-columns-default-formatInvoke column view (@pxref{Column view}) in the agenda buffer. The columnview format is taken from the entry at point, or (if there is no entry atpoint), from the first entry in the agenda view. So whatever the format forthat entry would be in the original buffer (taken from a property, from a@code{#+COLUMNS} line, or from the default variable@code{org-columns-default-format}), will be used in the agenda.@kindex C-c C-x >@item C-c C-x >Remove the restriction lock on the agenda, if it is currently restricted to afile or subtree (@pxref{Agenda files}).@tsubheading{Secondary filtering and query editing}@cindex filtering, by tag and effort, in agenda@cindex tag filtering, in agenda@cindex effort filtering, in agenda@cindex query editing, in agenda@kindex /@item /@vindex org-agenda-filter-presetFilter 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 isvery fast, so that you can switch quickly between different filters withouthaving to recreate the agenda@footnote{Custom commands can preset a filter bybinding the variable @code{org-agenda-filter-preset} as an option. Thisfilter will then be applied to the view and persist as a basic filter throughrefreshes and more secondary filtering.}You will be prompted for a tag selection letter, SPC will mean any tag atall. Pressing @key{TAB} at that prompt will offer use completion to select atag (including any tags that do not have a selection character). The commandthen hides all entries that do not contain or inherit this tag. When calledwith prefix arg, remove the entries that @emph{do} have the tag. A second@kbd{/} at the prompt will turn off the filter and unhide any hidden entries.If the first key you press is either @kbd{+} or @kbd{-}, the previous filterwill be narrowed by requiring or forbidding the selected additional tag.Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can alsoimmediately use the @kbd{\} command.@vindex org-sort-agenda-noeffort-is-highIn order to filter for effort estimates, you should set-up allowedefforts globally, for example@lisp(setq org-global-properties '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))@end lispYou can then filter for an effort by first typing an operator, one of@kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effortestimate in your array of allowed values, where @kbd{0} means the 10th value.The filter will then restrict to entries with effort smaller-or-equal, equal,or larger-or-equal than the selected value. If the digits 0-9 are not usedas fast access keys to tags, you can also simply press the index digitdirectly without an operator. In this case, @kbd{<} will be assumed. Forapplication of the operator, entries without a defined effort will be treatedaccording to the value of @code{org-sort-agenda-noeffort-is-high}. To filterfor tasks without effort definition, press @kbd{?} as the operator.Org also supports automatic, context-aware tag filtering. If the variable@code{org-agenda-auto-exclude-function} is set to a user-defined function,that function can decide which tags should be excluded from the agendaautomatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}as a sub-option key and runs the auto exclusion logic. For example, let'ssay you use a @code{Net} tag to identify tasks which need network access, an@code{Errand} tag for errands in town, and a @code{Call} tag for making phonecalls. You could auto-exclude these tags based on the availability of theInternet, and outside of business hours, with something like this:@lisp@group(defun org-my-auto-exclude-function (tag) (and (cond ((string= tag "Net") (/= 0 (call-process "/sbin/ping" nil nil nil "-c1" "-q" "-t1" "mail.gnu.org"))) ((or (string= tag "Errand") (string= tag "Call")) (let ((hour (nth 2 (decode-time)))) (or (< hour 8) (> hour 21))))) (concat "-" tag)))(setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)@end group@end lisp@kindex \@item \Narrow the current agenda filter by an additional condition. When called withprefix arg, remove the entries that @emph{do} have the tag, or that do matchthe effort criterion. You can achieve the same effect by pressing @kbd{+} or@kbd{-} as the first key after the @kbd{/} command.@kindex [@kindex ]@kindex @{@kindex @}@item [ ] @{ @}@table @i@item @r{in} search viewadd new search words (@kbd{[} and @kbd{]}) or new regular expressions(@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace willadd a positive search term prefixed by @samp{+}, indicating that this searchterm @i{must} occur/match in the entry. The closing bracket/brace will add anegative search term which @i{must not} occur/match in the entry for it to beselected.@end table@page@tsubheading{Remote editing}@cindex remote editing, from agenda@item 0-9Digit argument.@c@cindex undoing remote-editing events@cindex remote editing, undo@kindex C-_@item C-_Undo a change due to a remote editing command. The change is undoneboth in the agenda buffer and in the remote buffer.@c@kindex t@item tChange the TODO state of the item, both in the agenda and in theoriginal org file.@c@kindex C-S-@key{right}@kindex C-S-@key{left}@item C-S-@key{right}@r{/}@key{left}Switch to the next/previous set of TODO keywords.@c@kindex C-k@item C-k@vindex org-agenda-confirm-killDelete the current agenda item along with the entire subtree belongingto it in the original Org file. If the text to be deleted remotelyis longer than one line, the kill needs to be confirmed by the user. Seevariable @code{org-agenda-confirm-kill}.@c@kindex C-c C-w@item C-c C-wRefile the entry at point.@c@kindex C-c C-x C-a@kindex a@item C-c C-x C-a @ @r{or short} @ a@vindex org-archive-default-commandArchive the subtree corresponding to the entry at point using the defaultarchiving command set in @code{org-archive-default-command}. When using the@code{a} key, confirmation will be required.@c@kindex C-c C-x a@item C-c C-x aToggle the ARCHIVE tag for the current headline.@c@kindex C-c C-x A@item C-c C-x AMove the subtree corresponding to the current entry to its @emph{archivesibling}.@c@kindex $@kindex C-c C-x C-s@item C-c C-x C-s @ @r{or short} @ $Archive the subtree corresponding to the current headline. This means theentry will be moved to the configured archive location, most likely adifferent file.@c@kindex T@item T@vindex org-agenda-show-inherited-tagsShow all tags associated with the current item. This is useful if you haveturned off @code{org-agenda-show-inherited-tags}, but still want to see alltags of a headline occasionally.@c@kindex :@item :Set tags for the current headline. If there is an active region in theagenda, change a tag for all headings in the region.@c@kindex ,@item ,Set the priority for the current item. Org-mode prompts for thepriority character. If you reply with @key{SPC}, the priority cookieis removed from the entry.@c@kindex P@item PDisplay weighted priority of current item.@c@kindex +@kindex S-@key{up}@item +@itemx S-@key{up}Increase the priority of the current item. The priority is changed inthe original buffer, but the agenda is not resorted. Use the @kbd{r}key for this.@c@kindex -@kindex S-@key{down}@item -@itemx S-@key{down}Decrease the priority of the current item.@c@kindex C-c C-z@kindex z@item z @ @r{or also} @ C-c C-z@vindex org-log-into-drawerAdd a note to the entry. This note will be recorded, and then files to thesame location where state change notes are put. Depending on@code{org-log-into-drawer}, this maybe inside a drawer.@c@kindex C-c C-a@item C-c C-aDispatcher for all command related to attachments.@c@kindex C-c C-s@item C-c C-sSchedule this item, with prefix arg remove the scheduling timestamp@c@kindex C-c C-d@item C-c C-dSet a deadline for this item, with prefix arg remove the deadline.@c@kindex k@item kAgenda actions, to set dates for selected items to the cursor date.This command also works in the calendar! The command prompts for anadditional key:@examplem @r{Mark the entry at point for action. You can also make entries} @r{in Org files with @kbd{C-c C-x C-k}.}d @r{Set the deadline of the marked entry to the date at point.}s @r{Schedule the marked entry at the date at point.}r @r{Call @code{org-capture} with the cursor date as default date.}@end example@noindentPress @kbd{r} afterward to refresh the agenda and see the effect of thecommand.@c@kindex S-@key{right}@item S-@key{right}Change the timestamp associated with the current line by one day into thefuture. With a numeric prefix argument, change it by that many days. Forexample, @kbd{3 6 5 S-@key{right}} will change it by a year. With a@kbd{C-u} prefix, change the time by one hour. If you immediately repeat thecommand, it will continue to change hours even without the prefix arg. Witha double @kbd{C-u C-u} prefix, do the same for changing minutes. The stampis changed in the original Org file, but the change is not directly reflectedin the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.@c@kindex S-@key{left}@item S-@key{left}Change the timestamp associated with the current line by one dayinto the past.@c@kindex >@item >Change the timestamp associated with the current line. The key @kbd{>} hasbeen chosen, because it is the same as @kbd{S-.} on my keyboard.@c@kindex I@item IStart the clock on the current item. If a clock is running already, itis stopped first.@c@kindex O@item OStop the previously started clock.@c@kindex X@item XCancel the currently running clock.@kindex J@item JJump to the running clock in another window.@tsubheading{Bulk remote editing selected entries}@cindex remote editing, bulk, from agenda@kindex m@item mMark the entry at point for bulk action.@kindex u@item uUnmark entry for bulk action.@kindex U@item UUnmark all marked entries for bulk action.@kindex B@item BBulk action: act on all marked entries in the agenda. This will prompt foranother key to select the action to be applied. The prefix arg to @kbd{B}will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-removethese special timestamps.@exampler @r{Prompt for a single refile target and move all entries. The entries} @r{will no longer be in the agenda, refresh (@kbd{g}) to bring them back.}$ @r{Archive all selected entries.}A @r{Archive entries by moving them to their respective archive siblings.}t @r{Change TODO state. This prompts for a single TODO keyword and} @r{changes the state of all selected entries, bypassing blocking and} @r{suppressing logging notes (but not time stamps).}+ @r{Add a tag to all selected entries.}- @r{Remove a tag from all selected entries.}s @r{Schedule all items to a new date. To shift existing schedule dates} @r{by a fixed number of days, use something starting with double plus} @r{at the prompt, for example @samp{++8d} or @samp{++2w}.}d @r{Set deadline to a specific date.}@end example@tsubheading{Calendar commands}@cindex calendar commands, from agenda@kindex c@item cOpen the Emacs calendar and move to the date at the agenda cursor.@c@item cWhen in the calendar, compute and show the Org-mode agenda for thedate at the cursor.@c@cindex diary entries, creating from agenda@kindex i@item i@vindex org-agenda-diary-fileInsert a new entry into the diary, using the date at the cursor and (forblock entries) the date at the mark. This will add to the Emacs diaryfile@footnote{This file is parsed for the agenda when@code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}command in the calendar. The diary file will pop up in another window, whereyou can add the entry.If you configure @code{org-agenda-diary-file} to point to an Org-mode file,Org will create entries (in org-mode syntax) in that file instead. Mostentries will be stored in a date-based outline tree that will later make iteasy to archive appointments from previous months/years. The tree will bebuilt under an entry with a @code{DATE_TREE} property, or else with years astop-level entries. Emacs will prompt you for the entry text - if you specifyit, the entry will be created in @code{org-agenda-diary-file} without furtherinteraction. If you directly press @key{RET} at the prompt without typingtext, the target file will be shown in another window for you to finish theentry there. See also the @kbd{k r} command.@c@kindex M@item MShow the phases of the moon for the three months around current date.@c@kindex S@item SShow sunrise and sunset times. The geographical location must be setwith calendar variables, see the documentation for the Emacs calendar.@c@kindex C@item CConvert the date at cursor into many other cultural and historiccalendars.@c@kindex H@item HShow holidays for three months around the cursor date.@item M-x org-export-icalendar-combine-agenda-filesExport a single iCalendar file containing entries from all agenda files.This is a globally available command, and also available in the agenda menu.@tsubheading{Exporting to a file}@kindex C-x C-w@item C-x C-w@cindex exporting agenda views@cindex agenda views, exporting@vindex org-agenda-exporter-settingsWrite the agenda view to a file. Depending on the extension of the selectedfile name, the view will be exported as HTML (extension @file{.html} or@file{.htm}), Postscript (extension @file{.ps}), PDF (extension @file{.pdf}),and plain text (any other extension). When called with a @kbd{C-u} prefixargument, immediately open the newly created file. Use the variable@code{org-agenda-exporter-settings} to set options for @file{ps-print} andfor @file{htmlize} to be used during export.@tsubheading{Quit and Exit}@kindex q@item qQuit agenda, remove the agenda buffer.@c@kindex x@cindex agenda files, removing buffers@item xExit agenda, remove the agenda buffer and all buffers loaded by Emacsfor the compilation of the agenda. Buffers created by the user tovisit Org files will not be removed.@end table@node Custom agenda views, Exporting Agenda Views, Agenda commands, Agenda Views@section Custom agenda views@cindex custom agenda views@cindex agenda views, customCustom agenda commands serve two purposes: to store and quickly accessfrequently used TODO and tags searches, and to create special compositeagenda buffers. Custom agenda commands will be accessible through thedispatcher (@pxref{Agenda dispatcher}), just like the default commands.@menu* Storing searches:: Type once, use often* Block agenda:: All the stuff you need in a single buffer* Setting Options:: Changing the rules@end menu@node Storing searches, Block agenda, Custom agenda views, Custom agenda views@subsection Storing searchesThe first application of custom searches is the definition of keyboardshortcuts for frequently used searches, either creating an agendabuffer, or a sparse tree (the latter covering of course only the currentbuffer).@kindex C-c a C@vindex org-agenda-custom-commandsCustom commands are configured in the variable@code{org-agenda-custom-commands}. You can customize this variable, forexample by pressing @kbd{C-c a C}. You can also directly set it withEmacs Lisp in @file{.emacs}. The following example contains all validsearch types:@lisp@group(setq org-agenda-custom-commands '(("w" todo "WAITING") ("W" todo-tree "WAITING") ("u" tags "+boss-urgent") ("v" tags-todo "+boss-urgent") ("U" tags-tree "+boss-urgent") ("f" occur-tree "\\<FIXME\\>") ("h" . "HOME+Name tags searches") ; description for "h" prefix ("hl" tags "+home+Lisa") ("hp" tags "+home+Peter") ("hk" tags "+home+Kim")))@end group@end lisp@noindentThe initial string in each entry defines the keys you have to pressafter the dispatcher command @kbd{C-c a} in order to access the command.Usually this will be just a single character, but if you have manysimilar commands, you can also define two-letter combinations where thefirst character is the same in several combinations and serves as aprefix key@footnote{You can provide a description for a prefix key byinserting a cons cell with the prefix and the description.}. The secondparameter is the search type, followed by the string or regularexpression to be used for the matching. The example above willtherefore define:@table @kbd@item C-c a was a global search for TODO entries with @samp{WAITING} as the TODOkeyword@item C-c a Was the same search, but only in the current buffer and displaying theresults as a sparse tree@item C-c a uas a global tags search for headlines marked @samp{:boss:} but not@samp{:urgent:}@item C-c a vas the same search as @kbd{C-c a u}, but limiting the search toheadlines that are also TODO items@item C-c a Uas the same search as @kbd{C-c a u}, but only in the current buffer anddisplaying the result as a sparse tree@item C-c a fto create a sparse tree (again: current buffer only) with all entriescontaining the word @samp{FIXME}@item C-c a has a prefix command for a HOME tags search where you have to press anadditional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,Peter, or Kim) as additional tag to match.@end table@node Block agenda, Setting Options, Storing searches, Custom agenda views@subsection Block agenda@cindex block agenda@cindex agenda, with block viewsAnother possibility is the construction of agenda views that comprisethe results of @emph{several} commands, each of which creates a block inthe agenda buffer. The available commands include @code{agenda} for thedaily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}for the global TODO list (as constructed with @kbd{C-c a t}), and thematching commands discussed above: @code{todo}, @code{tags}, and@code{tags-todo}. Here are two examples:@lisp@group(setq org-agenda-custom-commands '(("h" "Agenda and Home-related tasks" ((agenda "") (tags-todo "home") (tags "garden"))) ("o" "Agenda and Office-related tasks" ((agenda "") (tags-todo "work") (tags "office")))))@end group@end lisp@noindentThis will define @kbd{C-c a h} to create a multi-block view for stuffyou need to attend to at home. The resulting agenda buffer will containyour agenda for the current week, all TODO items that carry the tag@samp{home}, and also all lines tagged with @samp{garden}. Finally thecommand @kbd{C-c a o} provides a similar view for office tasks.@node Setting Options, , Block agenda, Custom agenda views@subsection Setting options for custom commands@cindex options, for custom agenda views@vindex org-agenda-custom-commandsOrg-mode contains a number of variables regulating agenda constructionand display. The global variables define the behavior for all agendacommands, including the custom commands. However, if you want to changesome settings just for a single custom view, you can do so. Settingoptions requires inserting a list of variable names and values at theright spot in @code{org-agenda-custom-commands}. For example:@lisp@group(setq org-agenda-custom-commands '(("w" todo "WAITING" ((org-agenda-sorting-strategy '(priority-down)) (org-agenda-prefix-format " Mixed: "))) ("U" tags-tree "+boss-urgent" ((org-show-following-heading nil) (org-show-hierarchy-above nil))) ("N" search "" ((org-agenda-files '("~org/notes.org")) (org-agenda-text-search-extra-files nil)))))@end group@end lisp@noindentNow the @kbd{C-c a w} command will sort the collected entries only bypriority, and the prefix format is modified to just say @samp{ Mixed: }instead of giving the category of the entry. The sparse tags tree of@kbd{C-c a U} will now turn out ultra-compact, because neither theheadline hierarchy above the match, nor the headline following the matchwill be shown. The command @kbd{C-c a N} will do a text search limitedto only a single file.@vindex org-agenda-custom-commandsFor command sets creating a block agenda,@code{org-agenda-custom-commands} has two separate spots for settingoptions. You can add options that should be valid for just a singlecommand in the set, and options that should be valid for all commands inthe set. The former are just added to the command entry, the lattermust come after the list of command entries. Going back to the blockagenda example (@pxref{Block agenda}), let's change the sorting strategyfor the @kbd{C-c a h} commands to @code{priority-down}, but let's sortthe results for GARDEN tags query in the opposite order,@code{priority-up}. This would look like this:@lisp@group(setq org-agenda-custom-commands '(("h" "Agenda and Home-related tasks" ((agenda) (tags-todo "home") (tags "garden" ((org-agenda-sorting-strategy '(priority-up))))) ((org-agenda-sorting-strategy '(priority-down)))) ("o" "Agenda and Office-related tasks" ((agenda) (tags-todo "work") (tags "office")))))@end group@end lispAs you see, the values and parentheses setting is a little complex.When in doubt, use the customize interface to set this variable---itfully supports its structure. Just one caveat: when setting options inthis interface, the @emph{values} are just Lisp expressions. So if thevalue is a string, you need to add the double-quotes around the valueyourself.@node Exporting Agenda Views, Agenda column view, Custom agenda views, Agenda Views@section Exporting Agenda Views@cindex agenda views, exportingIf you are away from your computer, it can be very useful to have a printedversion of some agenda views to carry around. Org-mode can export customagenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's@file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, theghostscript @file{ps2pdf} utility must be installed on the system. Selectinga PDF file with also create the postscript file.}, and iCalendar files. Ifyou want to do this only occasionally, use the command@table @kbd@kindex C-x C-w@item C-x C-w@cindex exporting agenda views@cindex agenda views, exporting@vindex org-agenda-exporter-settingsWrite the agenda view to a file. Depending on the extension of the selectedfile name, the view will be exported as HTML (extension @file{.html} or@file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension@file{.ics}), or plain text (any other extension). Use the variable@code{org-agenda-exporter-settings} to set options for @file{ps-print} andfor @file{htmlize} to be used during export, for example@vindex org-agenda-add-entry-text-maxlines@vindex htmlize-output-type@vindex ps-number-of-columns@vindex ps-landscape-mode@lisp(setq org-agenda-exporter-settings '((ps-number-of-columns 2) (ps-landscape-mode t) (org-agenda-add-entry-text-maxlines 5) (htmlize-output-type 'css)))@end lisp@end tableIf you need to export certain agenda views frequently, you can associateany custom agenda command with a list of output file names@footnote{If you want to store standard views like the weekly agendaor the global TODO list as well, you need to define custom commands forthem in order to be able to specify file names.}. Here is an examplethat first defines custom commands for the agenda and the globalTODO list, together with a number of files to which to export them.Then we define two block agenda commands and specify file names for themas well. File names can be relative to the current working directory,or absolute.@lisp@group(setq org-agenda-custom-commands '(("X" agenda "" nil ("agenda.html" "agenda.ps")) ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps")) ("h" "Agenda and Home-related tasks" ((agenda "") (tags-todo "home") (tags "garden")) nil ("~/views/home.html")) ("o" "Agenda and Office-related tasks" ((agenda) (tags-todo "work") (tags "office")) nil ("~/views/office.ps" "~/calendars/office.ics"))))@end group@end lispThe extension of the file name determines the type of export. If it is@file{.html}, Org-mode will use the @file{htmlize.el} package to convertthe buffer to HTML and save it to this file name. If the extension is@file{.ps}, @code{ps-print-buffer-with-faces} is used to producePostscript output. If the extension is @file{.ics}, iCalendar export isrun export over all files that were used to construct the agenda, andlimit the export to entries listed in the agenda. Any otherextension produces a plain ASCII file.The export files are @emph{not} created when you use one of thosecommands interactively because this might use too much overhead.Instead, there is a special command to produce @emph{all} specifiedfiles in one step:@table @kbd@kindex C-c a e@item C-c a eExport all agenda views that have export file names associated withthem.@end tableYou can use the options section of the custom agenda commands to alsoset options for the export commands. For example:@lisp(setq org-agenda-custom-commands '(("X" agenda "" ((ps-number-of-columns 2) (ps-landscape-mode t) (org-agenda-prefix-format " [ ] ") (org-agenda-with-colors nil) (org-agenda-remove-tags t)) ("theagenda.ps"))))@end lisp@noindentThis command sets two options for the Postscript exporter, to make itprint in two columns in landscape format---the resulting page can be cutin two and then used in a paper agenda. The remaining settings modifythe agenda prefix to omit category and scheduling information, andinstead include a checkbox to check off items. We also remove the tagsto make the lines compact, and we don't want to use colors for theblack-and-white printer. Settings specified in@code{org-agenda-exporter-settings} will also apply, but the settingsin @code{org-agenda-custom-commands} take precedence.@noindentFrom the command line you may also use@exampleemacs -f org-batch-store-agenda-views -kill@end example@noindentor, if you need to modify some parameters@footnote{Quoting depends on thesystem you use, please check the FAQ for examples.}@exampleemacs -eval '(org-batch-store-agenda-views \ org-agenda-ndays 30 \ org-agenda-start-day "2007-11-01" \ org-agenda-include-diary nil \ org-agenda-files (quote ("~/org/project.org")))' \ -kill@end example@noindentwhich will create the agenda views restricted to the file@file{~/org/project.org}, without diary entries and with a 30-dayextent.You can also extract agenda information in a way that allows furtherprocessing by other programs. See @ref{Extracting agenda information}, formore information.@node Agenda column view, , Exporting Agenda Views, Agenda Views@section Using column view in the agenda@cindex column view, in agenda@cindex agenda, column viewColumn view (@pxref{Column view}) is normally used to view and editproperties embedded in the hierarchical structure of an Org file. It can bequite useful to use column view also from the agenda, where entries arecollected by certain criteria.@table @kbd@kindex C-c C-x C-c@item C-c C-x C-cTurn on column view in the agenda.@end tableTo understand how to use this properly, it is important to realize that theentries in the agenda are no longer in their proper outline environment.This causes the following issues:@enumerate@item@vindex org-columns-default-format@vindex org-overriding-columns-formatOrg needs to make a decision which @code{COLUMNS} format to use. Since theentries in the agenda are collected from different files, and different filesmay have different @code{COLUMNS} formats, this is a non-trivial problem.Org first checks if the variable @code{org-overriding-columns-format} iscurrently set, and if so, takes the format from there. Otherwise it takesthe format associated with the first item in the agenda, or, if that itemdoes not have a specific format (defined in a property, or in its file), ituses @code{org-columns-default-format}.@item@cindex property, special, CLOCKSUMIf any of the columns has a summary type defined (@pxref{Column attributes}),turning on column view in the agenda will visit all relevant agenda files andmake sure that the computations of this property are up to date. This isalso true for the special @code{CLOCKSUM} property. Org will then sum thevalues displayed in the agenda. In the daily/weekly agenda, the sums willcover a single day, in all other views they cover the entire block. It isvital to realize that the agenda may show the same entry @emph{twice} (forexample as scheduled and as a deadline), and it may show two entries from thesame hierarchy (for example a @emph{parent} and its @emph{child}). In thesecases, the summation in the agenda will lead to incorrect results becausesome values will count double.@itemWhen the column view in the agenda shows the @code{CLOCKSUM}, that is alwaysthe entire clocked time for this item. So even in the daily/weekly agenda,the clocksum listed in column view may originate from times outside thecurrent view. This has the advantage that you can compare these values witha column listing the planned total effort for a task---one of the majorapplications for column view in the agenda. If you want information aboutclocked time in the displayed period use clock table mode (press @kbd{R} inthe agenda).@end enumerate@node Markup, Exporting, Agenda Views, Top@chapter Markup for rich exportWhen exporting Org-mode documents, the exporter tries to reflect thestructure of the document as accurately as possible in the backend. Sinceexport targets like HTML, La@TeX{}, or DocBook allow much richer formatting,Org-mode has rules on how to prepare text for rich export. This sectionsummarizes the markup rules used in an Org-mode buffer.@menu* Structural markup elements:: The basic structure as seen by the exporter* Images and tables:: Tables and Images will be included* Literal examples:: Source code examples with special formatting* Include files:: Include additional files into a document* Index entries:: Making an index* Macro replacement:: Use macros to create complex output* Embedded LaTeX:: LaTeX can be freely used inside Org documents@end menu@node Structural markup elements, Images and tables, Markup, Markup@section Structural markup elements@menu* Document title:: Where the title is taken from* Headings and sections:: The document structure as seen by the exporter* Table of contents:: The if and where of the table of contents* Initial text:: Text before the first heading?* Lists:: Lists* Paragraphs:: Paragraphs* Footnote markup:: Footnotes* Emphasis and monospace:: Bold, italic, etc.* Horizontal rules:: Make a line* Comment lines:: What will *not* be exported@end menu@node Document title, Headings and sections, Structural markup elements, Structural markup elements@subheading Document title@cindex document title, markup rules@noindentThe title of the exported document is taken from the special line@cindex #+TITLE@example#+TITLE: This is the title of the document@end example@noindentIf 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 haveturned off exporting of the text before the first headline (see below), thetitle will be the file name without extension.@cindex property, EXPORT_TITLEIf you are exporting only a subtree by marking is as the region, the headingof the subtree will become the title of the document. If the subtree has aproperty @code{EXPORT_TITLE}, that will take precedence.@node Headings and sections, Table of contents, Document title, Structural markup elements@subheading Headings and sections@cindex headings and sections, markup rules@vindex org-export-headline-levelsThe outline structure of the document as described in @ref{DocumentStructure}, forms the basis for defining sections of the exported document.However, since the outline structure is also used for (for example) lists oftasks, only the first three outline levels will be used as headings. Deeperlevels will become itemized lists. You can change the location of thisswitch globally by setting the variable @code{org-export-headline-levels}, or on aper-file basis with a line@cindex #+OPTIONS@example#+OPTIONS: H:4@end example@node Table of contents, Initial text, Headings and sections, Structural markup elements@subheading Table of contents@cindex table of contents, markup rules@vindex org-export-with-tocThe table of contents is normally inserted directly before the first headlineof the file. If you would like to get it to a different location, insert thestring @code{[TABLE-OF-CONTENTS]} on a line by itself at the desiredlocation. The depth of the table of contents is by default the same as thenumber of headline levels, but you can choose a smaller number, or turn offthe table of contents entirely, by configuring the variable@code{org-export-with-toc}, or on a per-file basis with a line like@example#+OPTIONS: toc:2 (only to two levels in TOC)#+OPTIONS: toc:nil (no TOC at all)@end example@node Initial text, Lists, Table of contents, Structural markup elements@subheading Text before the first headline@cindex text before first headline, markup rules@cindex #+TEXTOrg-mode normally exports the text before the first headline, and even usesthe first line as the document title. The text will be fully marked up. Ifyou need to include literal HTML, La@TeX{}, or DocBook code, use the specialconstructs described below in the sections for the individual exporters.@vindex org-export-skip-text-before-1st-headingSome people like to use the space before the first headline for setup andinternal links and therefore would like to control the exported text beforethe first headline in a different way. You can do so by setting the variable@code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-filebasis, you can get the same effect with @samp{#+OPTIONS: skip:t}.@noindentIf you still want to have some text before the first headline, use the@code{#+TEXT} construct:@example#+OPTIONS: skip:t#+TEXT: This text will go before the *first* headline.#+TEXT: [TABLE-OF-CONTENTS]#+TEXT: This goes between the table of contents and the first headline@end example@node Lists, Paragraphs, Initial text, Structural markup elements@subheading Lists@cindex lists, markup rulesPlain lists as described in @ref{Plain lists}, are translated to the backend'ssyntax for such lists. Most backends support unordered, ordered, anddescription lists.@node Paragraphs, Footnote markup, Lists, Structural markup elements@subheading Paragraphs, line breaks, and quoting@cindex paragraphs, markup rulesParagraphs are separated by at least one empty line. If you need to enforcea line break within a paragraph, use @samp{\\} at the end of a line.To keep the line breaks in a region, but otherwise use normal formatting, youcan use this construct, which can also be used to format poetry.@cindex #+BEGIN_VERSE@example#+BEGIN_VERSE Great clouds overhead Tiny black birds rise and fall Snow covers Emacs -- AlexSchroeder#+END_VERSE@end exampleWhen quoting a passage from another document, it is customary to format thisas a paragraph that is indented on both the left and the right margin. Youcan include quotations in Org-mode documents like this:@cindex #+BEGIN_QUOTE@example#+BEGIN_QUOTEEverything should be made as simple as possible,but not any simpler -- Albert Einstein#+END_QUOTE@end exampleIf you would like to center some text, do it like this:@cindex #+BEGIN_CENTER@example#+BEGIN_CENTEREverything should be made as simple as possible, \\but not any simpler#+END_CENTER@end example@node Footnote markup, Emphasis and monospace, Paragraphs, Structural markup elements@subheading Footnote markup@cindex footnotes, markup rules@cindex @file{footnote.el}Footnotes defined in the way described in @ref{Footnotes}, will be exported byall backends. Org allows multiple references to the same note, anddifferent backends support this to varying degrees.@node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements@subheading Emphasis and monospace@cindex underlined text, markup rules@cindex bold text, markup rules@cindex italic text, markup rules@cindex verbatim text, markup rules@cindex code text, markup rules@cindex strike-through text, markup rulesYou can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Textin the code and verbatim string is not processed for Org-mode specificsyntax, it is exported verbatim.@node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements@subheading Horizontal rules@cindex horizontal rules, markup rulesA line consisting of only dashes, and at least 5 of them, will beexported as a horizontal line (@samp{<hr/>} in HTML).@node Comment lines, , Horizontal rules, Structural markup elements@subheading Comment lines@cindex comment lines@cindex exporting, not@cindex #+BEGIN_COMMENTLines starting with @samp{#} in column zero are treated as comments and willnever be exported. If you want an indented line to be treated as a comment,start it with @samp{#+ }. Also entire subtrees starting with the word@samp{COMMENT} will never be exported. Finally, regions surrounded by@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported.@table @kbd@kindex C-c ;@item C-c ;Toggle the COMMENT keyword at the beginning of an entry.@end table@node Images and tables, Literal examples, Structural markup elements, Markup@section Images and Tables@cindex tables, markup rules@cindex #+CAPTION@cindex #+LABELBoth the native Org-mode tables (@pxref{Tables}) and tables formatted withthe @file{table.el} package will be exported properly. For Org-mode tables,the lines before the first horizontal separator line will become table headerlines. You can use the following lines somewhere before the table to assigna caption and a label for cross references, and in the text you can refer tothe object with @code{\ref@{tab:basic-data@}}:@example#+CAPTION: This is the caption for the next table (or link)#+LABEL: tbl:basic-data | ... | ...| |-----|----|@end example@cindex inlined images, markup rulesSome backends (HTML, La@TeX{}, and DocBook) allow you to directly includeimages into the exported document. Org does this, if a link to an imagefiles does not have a description part, for example @code{[[./img/a.jpg]]}.If you wish to define a caption for the image and maybe a label for internalcross references, make sure that the link is on a line by itself and precedeit with @code{#+CAPTION} and @code{#+LABEL} as follows:@example#+CAPTION: This is the caption for the next figure link (or table)#+LABEL: fig:SED-HR4049[[./img/a.jpg]]@end exampleYou may also define additional attributes for the figure. As this isbackend-specific, see the sections about the individual backends for moreinformation.@node Literal examples, Include files, Images and tables, Markup@section Literal examples@cindex literal examples, markup rules@cindex code line references, markup rulesYou can include literal examples that should not be subjected tomarkup. Such examples will be typeset in monospace, so this is well suitedfor source code and similar examples.@cindex #+BEGIN_EXAMPLE@example#+BEGIN_EXAMPLESome example from a text file.#+END_EXAMPLE@end exampleNote that such blocks may be @i{indented} in order to align nicely withindented text and in particular with plain list structure (@pxref{Plainlists}). For simplicity when using small examples, you can also start theexample lines with a colon followed by a space. There may also be additionalwhitespace before the colon:@exampleHere is an example : Some example from a text file.@end example@cindex formatting source code, markup rulesIf the example is source code from a programming language, or any other textthat can be marked up by font-lock in Emacs, you can ask for the example tolook like the fontified Emacs buffer@footnote{Currently this works for theHTML backend, and requires the @file{htmlize.el} package version 1.34 orlater. It also works for LaTeX with the listings package, if you turn on theoption @code{org-export-latex-listings} and make sure that the listingspackage is included by the LaTeX header.}. This is done with the @samp{src}block, where you also need to specify the name of the major mode that shouldbe used to fontify the example:@cindex #+BEGIN_SRC@example#+BEGIN_SRC emacs-lisp (defun org-xor (a b) "Exclusive or." (if a (not b) b))#+END_SRC@end exampleBoth in @code{example} and in @code{src} snippets, you can add a @code{-n}switch to the end of the @code{BEGIN} line, to get the lines of the examplenumbered. If you use a @code{+n} switch, the numbering from the previousnumbered snippet will be continued in the current one. In literal examples,Org will interpret strings like @samp{(ref:name)} as labels, and use them astargets for special hyperlinks like @code{[[(name)]]} (i.e. the reference nameenclosed in single parenthesis). In HTML, hovering the mouse over such alink will remote-highlight the corresponding code line, which is kind ofcool.You can also add a @code{-r} switch which @i{removes} the labels from thesource code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} thelabels in the source code while using line numbers for the links, which mightbe useful to explain those in an org-mode example code.}. With the @code{-n}switch, links to these references will be labeled by the line numbers fromthe code listing, otherwise links will use the labels with no parentheses.Here is an example:@example#+BEGIN_SRC emacs-lisp -n -r(save-excursion (ref:sc) (goto-char (point-min)) (ref:jump)#+END_SRCIn line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]jumps to point-min.@end example@vindex org-coderef-label-formatIf the syntax for the label format conflicts with the language syntax, use a@code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal-n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}.HTML export also allows examples to be published as text areas, @xref{Textareas in HTML export}.@table @kbd@kindex C-c '@item C-c 'Edit the source code example at point in its native mode. This works byswitching to a temporary buffer with the source code. You need to exit bypressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*}or @samp{#} will get a comma prepended, to keep them from being interpretedby Org as outline nodes or special comments. These commas will be strippedfor editing with @kbd{C-c '}, and also for export.}, the edited version willthen replace the old version in the Org buffer. Fixed-width regions(where each line starts with a colon followed by a space) will be editedusing @code{artist-mode}@footnote{You may select a different-mode with thevariable @code{org-edit-fixed-width-region-mode}.} to allow creating ASCIIdrawings easily. Using this command in an empty line will create a newfixed-width region.@kindex C-c l@item C-c lCalling @code{org-store-link} while editing a source code example in atemporary buffer created with @kbd{C-c '} will prompt for a label, make surethat it is unique in the current buffer, and insert it with the properformatting like @samp{(ref:label)} at the end of the current line. Then thelabel is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.@end table@node Include files, Index entries, Literal examples, Markup@section Include files@cindex include files, markup rulesDuring export, you can include the content of another file. For example, toinclude your @file{.emacs} file, you could use:@cindex #+INCLUDE@example#+INCLUDE: "~/.emacs" src emacs-lisp@end example@noindentThe optional second and third parameter are the markup (e.g. @samp{quote},@samp{example}, or @samp{src}), and, if the markup is @samp{src}, thelanguage for formatting the contents. The markup is optional, if it is notgiven, the text will be assumed to be in Org-mode format and will beprocessed normally. The include line will also allow additional keywordparameters @code{:prefix1} and @code{:prefix} to specify prefixes for thefirst line and for each following line, as well as any options accepted bythe selected markup. For example, to include a file as an item, use@example#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " "@end example@table @kbd@kindex C-c '@item C-c 'Visit the include file at point.@end table@node Index entries, Macro replacement, Include files, Markup@section Index entries@cindex index entries, for publishingYou can specify entries that will be used for generating an index duringpublishing. This is done by lines starting with @code{#+INDEX}. An entrythe contains an exclamation mark will create a sub item. See @ref{Generatingan index} for more information.@example* Curriculum Vitae#+INDEX: CV#+INDEX: Application!CV@end example@node Macro replacement, Embedded LaTeX, Index entries, Markup@section Macro replacement@cindex macro replacement, during export@cindex #+MACROYou can define text snippets with@example#+MACRO: name replacement text $1, $2 are arguments@end example@noindent which can be referenced anywhere in the document (even incode examples) with @code{@{@{@{name(arg1,arg2)@}@}@}}. In addition todefined macros, @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc.,will reference information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, andsimilar lines. Also, @code{@{@{@{date(@var{FORMAT})@}@}@}} and@code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date timeand to the modification time of the file being exported, respectively.@var{FORMAT} should be a format string understood by@code{format-time-string}.Macro expansion takes place during export, and some people use it toconstruct complex HTML code.@node Embedded LaTeX, , Macro replacement, Markup@section Embedded La@TeX{}@cindex @TeX{} interpretation@cindex La@TeX{} interpretationPlain ASCII is normally sufficient for almost all note taking. Oneexception, however, are scientific notes which need to be able to containmathematical symbols and the occasional formula. La@TeX{}@footnote{La@TeX{}is a macro system based on Donald E. Knuth's @TeX{} system. Many of thefeatures described here as ``La@TeX{}'' are really from @TeX{}, but forsimplicity I am blurring this distinction.} is widely used to typesetscientific documents. Org-mode supports embedding La@TeX{} code into itsfiles, because many academics are used to reading La@TeX{} source code, andbecause it can be readily processed into images for HTML production.It is not necessary to mark La@TeX{} macros and code in any special way.If you observe a few conventions, Org-mode knows how to find it and whatto do with it.@menu* Special symbols:: Greek letters and other symbols* Subscripts and superscripts:: Simple syntax for raising/lowering text* LaTeX fragments:: Complex formulas made easy* Previewing LaTeX fragments:: What will this snippet look like?* CDLaTeX mode:: Speed up entering of formulas@end menu@node Special symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX@subsection Special symbols@cindex math symbols@cindex special symbols@cindex @TeX{} macros@cindex La@TeX{} fragments, markup rules@cindex HTML entities@cindex La@TeX{} entitiesYou can use La@TeX{} macros to insert special symbols like @samp{\alpha} toindicate the Greek letter, or @samp{\to} to indicate an arrow. Completionfor these macros is available, just type @samp{\} and maybe a few letters,and press @kbd{M-@key{TAB}} to see possible completions. Unlike La@TeX{}code, Org-mode allows these macros to be present without surrounding mathdelimiters, for example:@exampleAngles are written as Greek letters \alpha, \beta and \gamma.@end example@vindex org-entitiesDuring export, these symbols will be transformed into the native format ofthe exporter backend. Strings like @code{\alpha} will be exported as@code{α} in the HTML output, and as @code{$\alpha$} in the La@TeX{}output. Similarly, @code{\nbsp} will become @code{ } in HTML and@code{~} in La@TeX{}. If you need such a symbol inside a word, terminate itlike this: @samp{\Aacute@{@}stor}.A large number of entities is provided, with names taken from both HTML andLa@TeX{}, see the variable @code{org-entities} for the complete list.@samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and@samp{...} are all converted into special commands creating hyphens ofdifferent lengths or a compact set of dots.If you would like to see entities displayed as utf8 characters, use thefollowing command@footnote{You can turn this on by default by setting thevariable @code{org-pretty-entities}, or on a per-file base with the@code{#+STARTUP} option @code{entitiespretty}.}:@table @kbd@kindex C-c C-x \@item C-c C-x \Toggle display of entities as UTF8 characters. This does not change thebuffer content which remains plain ASCII, but it overlays the UTF8 characterfor display purposes only.@end table@node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX@subsection Subscripts and superscripts@cindex subscript@cindex superscriptJust like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super-and subscripts. Again, these can be used without embedding them inmath-mode delimiters. To increase the readability of ASCII text, it isnot necessary (but OK) to surround multi-character sub- and superscriptswith curly braces. For example@exampleThe mass if the sun is M_sun = 1.989 x 10^30 kg. The radius ofthe sun is R_@{sun@} = 6.96 x 10^8 m.@end example@vindex org-export-with-sub-superscriptsTo avoid interpretation as raised or lowered text, you can quote @samp{^} and@samp{_} with a backslash: @samp{\^} and @samp{\_}. If you write a textwhere the underscore is often used in a different context, Org's conventionto always interpret these as subscripts can get in your way. Configure thevariable @code{org-export-with-sub-superscripts} to globally change thisconvention, or use, on a per-file basis:@example#+OPTIONS: ^:@{@}@end example@table @kbd@kindex C-c C-x \@item C-c C-x \In addition to showing entities as UTF8 characters, this command will alsoformat sub- and superscripts in a WYSIWYM way.@end table@node LaTeX fragments, Previewing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX@subsection La@TeX{} fragments@cindex La@TeX{} fragments@vindex org-format-latex-headerWith symbols, sub- and superscripts, HTML is pretty much at its end whenit comes to representing mathematical formulas@footnote{Yes, there isMathML, but that is not yet fully supported by many browsers, and thereis no decent converter for turning La@TeX{} or ASCII representations offormulas into MathML. So for the time being, converting formulas intoimages seems the way to go.}. More complex expressions need a dedicatedformula processor. To this end, Org-mode can contain arbitrary La@TeX{}fragments. It provides commands to preview the typeset result of thesefragments, and upon export to HTML, all fragments will be converted toimages and inlined into the HTML document@footnote{The La@TeX{} exportwill not use images for displaying La@TeX{} fragments but include thesefragments directly into the La@TeX{} code.}. For this to work youneed to be on a system with a working La@TeX{} installation. You alsoneed the @file{dvipng} program, available at@url{http://sourceforge.net/projects/dvipng/}. The La@TeX{} header thatwill be used when processing a fragment can be configured with thevariable @code{org-format-latex-header}.La@TeX{} fragments don't need any special marking at all. The followingsnippets will be identified as La@TeX{} source code:@itemize @bullet@itemEnvironments of any kind. The only requirement is that the@code{\begin} statement appears on a new line, preceded by onlywhitespace.@itemText within the usual La@TeX{} math delimiters. To avoid conflicts withcurrency specifications, single @samp{$} characters are only recognized asmath delimiters if the enclosed text contains at most two line breaks, isdirectly attached to the @samp{$} characters with no whitespace in between,and if the closing @samp{$} is followed by whitespace, punctuation or a dash.For the other delimiters, there is no such restriction, so when in doubt, use@samp{\(...\)} as inline math delimiters.@end itemize@noindent For example:@example\begin@{equation@} % arbitrary environments,x=\sqrt@{b@} % even tables, figures\end@{equation@} % etcIf $a^2=b$ and \( b=2 \), then the solution must beeither $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].@end example@noindent@vindex org-format-latex-optionsIf you need any of the delimiter ASCII sequences for other purposes, youcan configure the option @code{org-format-latex-options} to deselect theones you do not wish to have interpreted by the La@TeX{} converter.@node Previewing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX@subsection Previewing LaTeX fragments@cindex LaTeX fragments, previewLa@TeX{} fragments can be processed to produce preview images of thetypeset expressions:@table @kbd@kindex C-c C-x C-l@item C-c C-x C-lProduce a preview image of the La@TeX{} fragment at point and overlay itover the source code. If there is no fragment at point, process allfragments in the current entry (between two headlines). When calledwith a prefix argument, process the entire subtree. When called withtwo prefix arguments, or when the cursor is before the first headline,process the entire buffer.@kindex C-c C-c@item C-c C-cRemove the overlay preview images.@end table@vindex org-format-latex-optionsYou can customize the variable @code{org-format-latex-options} to influencesome aspects of the preview. In particular, the @code{:scale} (and for HTMLexport, @code{:html-scale}) property can be used to adjust the size of thepreview images.During HTML export (@pxref{HTML export}), all La@TeX{} fragments areconverted into images and inlined into the document if the followingsetting is active:@lisp(setq org-export-with-LaTeX-fragments t)@end lisp@node CDLaTeX mode, , Previewing LaTeX fragments, Embedded LaTeX@subsection Using CDLa@TeX{} to enter math@cindex CDLa@TeX{}CDLa@TeX{} mode is a minor mode that is normally used in combination with amajor La@TeX{} mode like AUC@TeX{} in order to speed-up insertion ofenvironments and math templates. Inside Org-mode, you can make use ofsome of the features of CDLa@TeX{} mode. You need to install@file{cdlatex.el} and @file{texmathp.el} (the latter comes also withAUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.Don't use CDLa@TeX{} mode itself under Org-mode, but use the lightversion @code{org-cdlatex-mode} that comes as part of Org-mode. Turn iton for the current buffer with @code{M-x org-cdlatex-mode}, or for allOrg files with@lisp(add-hook 'org-mode-hook 'turn-on-org-cdlatex)@end lispWhen this mode is enabled, the following features are present (for moredetails see the documentation of CDLa@TeX{} mode):@itemize @bullet@kindex C-c @{@itemEnvironment templates can be inserted with @kbd{C-c @{}.@item@kindex @key{TAB}The @key{TAB} key will do template expansion if the cursor is inside aLa@TeX{} fragment@footnote{Org-mode has a method to test if the cursor isinside such a fragment, see the documentation of the function@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} willexpand @code{fr} to @code{\frac@{@}@{@}} and position the cursorcorrectly inside the first brace. Another @key{TAB} will get you intothe second brace. Even outside fragments, @key{TAB} will expandenvironment abbreviations at the beginning of a line. For example, ifyou write @samp{equ} at the beginning of a line and press @key{TAB},this abbreviation will be expanded to an @code{equation} environment.To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.@item@kindex _@kindex ^@vindex cdlatex-simplify-sub-super-scriptsPressing @kbd{_} and @kbd{^} inside a La@TeX{} fragment will insert thesecharacters together with a pair of braces. If you use @key{TAB} to moveout of the braces, and if the braces surround only a single character ormacro, they are removed again (depending on the variable@code{cdlatex-simplify-sub-super-scripts}).@item@kindex `Pressing the backquote @kbd{`} followed by a character inserts mathmacros, also outside La@TeX{} fragments. If you wait more than 1.5 secondsafter the backquote, a help window will pop up.@item@kindex 'Pressing the single-quote @kbd{'} followed by another character modifiesthe symbol before point with an accent or a font. If you wait more than1.5 seconds after the backquote, a help window will pop up. Charactermodification will work only inside La@TeX{} fragments, outside the quoteis normal.@end itemize@node Exporting, Publishing, Markup, Top@chapter Exporting@cindex exportingOrg-mode documents can be exported into a variety of other formats. Forprinting and sharing of notes, ASCII export produces a readable and simpleversion of an Org file. HTML export allows you to publish a notes file onthe web, while the XOXO format provides a solid base for exchange with abroad range of other applications. La@TeX{} export lets you use Org-mode andits structured editing functions to easily create La@TeX{} files. DocBookexport makes it possible to convert Org files to many other formats usingDocBook tools. For project management you can create gantt and resourcecharts by using TaskJuggler export. To incorporate entries with associatedtimes like deadlines or appointments into a desktop calendar program likeiCal, Org-mode can also produce extracts in the iCalendar format. CurrentlyOrg-mode only supports export, not import of these different formats.Org supports export of selected regions when @code{transient-mark-mode} isenabled (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 La@TeX{}, and processing to PDF* DocBook export:: Exporting to DocBook* TaskJuggler export:: Exporting to TaskJuggler* Freemind export:: Exporting to Freemind mind maps* XOXO export:: Exporting to XOXO* iCalendar export:: Exporting in iCalendar format@end menu@node Selective export, Export options, Exporting, Exporting@section Selective export@cindex export, selective by tags@vindex org-export-select-tags@vindex org-export-exclude-tagsYou may use tags to select the parts of a document that should be exported,or to exclude parts from export. This behavior is governed by two variables:@code{org-export-select-tags} and @code{org-export-exclude-tags}.Org first checks if any of the @emph{select} tags is present in the buffer.If yes, all trees that do not carry one of these tags will be excluded. If aselected tree is a subtree, the heading hierarchy above it will also beselected for export, but not the text below those headings.@noindentIf none of the select tags is found, the whole buffer will be selected forexport.@noindentFinally, all subtrees that are marked by any of the @emph{exclude} tags willbe removed from the export buffer.@node Export options, The export dispatcher, Selective export, Exporting@section Export options@cindex options, for export@cindex completion, of option keywordsThe exporter recognizes special lines in the buffer which provideadditional information. These lines may be put anywhere in the file.The whole set of lines can be inserted into the buffer with @kbd{C-cC-e t}. For individual lines, a good way to make sure the keyword iscorrect is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion(@pxref{Completion}). For a summary of other in-buffer settings notspecifically related to export, see @ref{In-buffer settings}.In particular, note that you can place commonly-used (export) options ina separate file which can be included using @code{#+SETUPFILE}.@table @kbd@kindex C-c C-e t@item C-c C-e tInsert template with export options, see example below.@end table@cindex #+TITLE@cindex #+AUTHOR@cindex #+DATE@cindex #+EMAIL@cindex #+DESCRIPTION@cindex #+KEYWORDS@cindex #+LANGUAGE@cindex #+TEXT@cindex #+OPTIONS@cindex #+BIND@cindex #+LINK_UP@cindex #+LINK_HOME@cindex #+EXPORT_SELECT_TAGS@cindex #+EXPORT_EXCLUDE_TAGS@cindex #+XSLT@cindex #+LATEX_HEADER@vindex user-full-name@vindex user-mail-address@vindex org-export-default-language@example#+TITLE: the title to be shown (default is the buffer name)#+AUTHOR: the author (default taken from @code{user-full-name})#+DATE: a date, fixed, of a format string for @code{format-time-string}#+EMAIL: his/her email address (default from @code{user-mail-address})#+DESCRIPTION: the page description, e.g. for the XHTML meta tag#+KEYWORDS: the page keywords, e.g. for the XHTML meta tag#+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language})#+TEXT: Some descriptive text to be inserted at the beginning.#+TEXT: Several lines may be given.#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...#+BIND: lisp-var lisp-val, e.g.: org-export-latex-low-levels itemize @r{You need to confirm using these, or configure @code{org-export-allow-BIND}}#+LINK_UP: the ``up'' link of an exported page#+LINK_HOME: the ``home'' link of an exported page#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@}#+EXPORT_SELECT_TAGS: Tags that select a tree for export#+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export#+XSLT: the XSLT stylesheet used by DocBook exporter to generate FO file@end example@noindentThe OPTIONS line is a compact@footnote{If you want to configure many optionsthis way, you can use several OPTIONS lines.} form to specify export settings. Hereyou can:@cindex headline levels@cindex section-numbers@cindex table of contents@cindex line-break preservation@cindex quoted HTML tags@cindex fixed-width sections@cindex tables@cindex @TeX{}-like syntax for sub- and superscripts@cindex footnotes@cindex special strings@cindex emphasized text@cindex @TeX{} macros@cindex La@TeX{} fragments@cindex author info, in export@cindex time info, in export@exampleH: @r{set the number of headline levels for export}num: @r{turn on/off section-numbers}toc: @r{turn on/off table of contents, or set level limit (integer)}\n: @r{turn on/off line-break-preservation (DOES NOT WORK)}@@: @r{turn on/off quoted HTML tags}:: @r{turn on/off fixed-width sections}|: @r{turn on/off tables}^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If} @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but} @r{the simple @code{a_b} will be left as it is.}-: @r{turn on/off conversion of special strings.}f: @r{turn on/off footnotes like this[1].}todo: @r{turn on/off inclusion of TODO keywords into exported text}pri: @r{turn on/off priority cookies}tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}}<: @r{turn on/off inclusion of any time/date stamps like DEADLINES}*: @r{turn on/off emphasized text (bold, italic, underlined)}TeX: @r{turn on/off simple @TeX{} macros in plain text}LaTeX: @r{turn on/off La@TeX{} fragments}skip: @r{turn on/off skipping the text before the first heading}author: @r{turn on/off inclusion of author name/email into exported file}email: @r{turn on/off inclusion of author email into exported file}creator: @r{turn on/off inclusion of creator info into exported file}timestamp: @r{turn on/off inclusion creation time into exported file}d: @r{turn on/off inclusion of drawers}@end example@noindentThese options take effect in both the HTML and La@TeX{} export, exceptfor @code{TeX} and @code{LaTeX}, which are respectively @code{t} and@code{nil} for the La@TeX{} export.When exporting only a single subtree by selecting it with @kbd{C-c @@} beforecalling an export command, the subtree can overrule some of the file's exportsettings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE},@code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and@code{EXPORT_OPTIONS}.@node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting@section The export dispatcher@cindex dispatcher, for export commandsAll export commands can be reached using the export dispatcher, which is aprefix key that prompts for an additional key specifying the command.Normally the entire file is exported, but if there is an active region thatcontains one outline tree, the first heading is used as document title andthe subtrees are exported.@table @kbd@kindex C-c C-e@item C-c C-e@vindex org-export-run-in-backgroundDispatcher for export and publishing commands. Displays a help-windowlisting the additional key(s) needed to launch an export or publishingcommand. The prefix arg is passed through to the exporter. A double prefix@kbd{C-u C-u} causes most commands to be executed in the background, in aseparate Emacs process@footnote{To make this behavior the default, customizethe variable @code{org-export-run-in-background}.}.@kindex C-c C-e v@item C-c C-e vLike @kbd{C-c C-e}, but only export the text that is currently visible(i.e. not hidden by outline visibility).@kindex C-u C-u C-c C-e@item C-u C-u C-c C-e@vindex org-export-run-in-backgroundCall an the exporter, but reverse the setting of@code{org-export-run-in-background}, i.e. request background processing ifnot set, or force processing in the current Emacs process if set.@end table@node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting@section ASCII/Latin-1/UTF-8 export@cindex ASCII export@cindex Latin-1 export@cindex UTF-8 exportASCII export produces a simple and very readable version of an Org-modefile, containing only plain ASCII. Latin-1 and UTF-8 export augment the filewith special characters and symbols available in these encodings.@cindex region, active@cindex active region@cindex transient-mark-mode@table @kbd@kindex C-c C-e a@item C-c C-e a@cindex property, EXPORT_FILE_NAMEExport as ASCII file. For an Org file, @file{myfile.org}, the ASCII filewill be @file{myfile.txt}. The file will be overwritten withoutwarning. If there is an active region@footnote{This requires@code{transient-mark-mode} be turned on.}, only the region will beexported. If the selected region is a single tree@footnote{To select thecurrent subtree, use @kbd{C-c @@}.}, the tree head willbecome the document title. If the tree head entry has or inherits an@code{EXPORT_FILE_NAME} property, that name will be used for theexport.@kindex C-c C-e A@item C-c C-e AExport to a temporary buffer, do not create a file.@kindex C-c C-e n@kindex C-c C-e N@item C-c C-e n @ @ @r{and} @ @ C-c C-e NLike the above commands, but use Latin-1 encoding.@kindex C-c C-e u@kindex C-c C-e U@item C-c C-e u @ @ @r{and} @ @ C-c C-e ULike the above commands, but use UTF-8 encoding.@kindex C-c C-e v a@kindex C-c C-e v n@kindex C-c C-e v u@item C-c C-e v a @ @ @r{and} @ @ C-c C-e v n @ @ @r{and} @ @ C-c C-e v uExport only the visible part of the document.@end table@cindex headline levels, for exportingIn the exported version, the first 3 outline levels will becomeheadlines, defining a general document structure. Additional levelswill be exported as itemized lists. If you want that transition to occurat a different level, specify it with a prefix argument. For example,@example@kbd{C-1 C-c C-e a}@end example@noindentcreates only top level headlines and does the rest as items. Whenheadlines are converted to items, the indentation of the text followingthe headline is changed to fit nicely under the item. This is done withthe assumption that the first body line indicates the base indentation ofthe body text. Any indentation larger than this is adjusted to preservethe layout relative to the first line. Should there be lines with lessindentation than the first, these are left alone.@vindex org-export-ascii-links-to-notesLinks will be exported in a footnote-like style, with the descriptive part inthe text and the link in a note before the next heading. See the variable@code{org-export-ascii-links-to-notes} for details and other options.@node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting@section HTML export@cindex HTML exportOrg-mode contains an HTML (XHTML 1.0 strict) exporter with extensiveHTML formatting, in ways similar to John Gruber's @emph{markdown}language, but with additional support for tables.@menu* HTML Export commands:: How to invoke HTML export* Quoting HTML tags:: Using direct HTML in Org-mode* Links in HTML export:: How links will be interpreted and formatted* Tables in HTML export:: How to modify the formatting of tables* Images in HTML export:: How to insert figures into HTML output* Text areas in HTML export:: An alternative way to show an example* CSS support:: Changing the appearance of the output* JavaScript support:: Info and Folding in a web browser@end menu@node HTML Export commands, Quoting HTML tags, HTML export, HTML export@subsection HTML export commands@cindex region, active@cindex active region@cindex transient-mark-mode@table @kbd@kindex C-c C-e h@item C-c C-e h@cindex property, EXPORT_FILE_NAMEExport as HTML file @file{myfile.html}. For an Org file @file{myfile.org},the ASCII file will be @file{myfile.html}. The file will be overwrittenwithout warning. If there is an active region@footnote{This requires@code{transient-mark-mode} be turned on.}, only the region will beexported. If the selected region is a single tree@footnote{To select thecurrent subtree, use @kbd{C-c @@}.}, the tree head will become the documenttitle. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}property, that name will be used for the export.@kindex C-c C-e b@item C-c C-e bExport as HTML file and immediately open it with a browser.@kindex C-c C-e H@item C-c C-e HExport to a temporary buffer, do not create a file.@kindex C-c C-e R@item C-c C-e RExport the active region to a temporary buffer. With a prefix argument, donot produce the file header and footer, but just the plain HTML section forthe region. This is good for cut-and-paste operations.@kindex C-c C-e v h@kindex C-c C-e v b@kindex C-c C-e v H@kindex C-c C-e v R@item C-c C-e v h@item C-c C-e v b@item C-c C-e v H@item C-c C-e v RExport only the visible part of the document.@item M-x org-export-region-as-htmlConvert the region to HTML under the assumption that it was Org-modesyntax before. This is a global command that can be invoked in anybuffer.@item M-x org-replace-region-by-HTMLReplace the active region (assumed to be in Org-mode syntax) by HTMLcode.@end table@cindex headline levels, for exportingIn the exported version, the first 3 outline levels will become headlines,defining a general document structure. Additional levels will be exported asitemized lists. If you want that transition to occur at a different level,specify it with a numeric prefix argument. For example,@example@kbd{C-2 C-c C-e b}@end example@noindentcreates two levels of headings and does the rest as items.@node Quoting HTML tags, Links in HTML export, HTML Export commands, HTML export@subsection Quoting HTML tagsPlain @samp{<} and @samp{>} are always transformed to @samp{<} and@samp{>} in HTML export. If you want to include simple HTML tagswhich should be interpreted as such, mark them with @samp{@@} as in@samp{@@<b>bold text@@</b>}. Note that this really works only forsimple tags. For more extensive HTML that should be copied verbatim tothe exported file use either@cindex #+HTML@cindex #+BEGIN_HTML@example#+HTML: Literal HTML code for export@end example@noindent or@cindex #+BEGIN_HTML@example#+BEGIN_HTMLAll lines between these markers are exported literally#+END_HTML@end example@node Links in HTML export, Tables in HTML export, Quoting HTML tags, HTML export@subsection Links in HTML export@cindex links, in HTML export@cindex internal links, in HTML export@cindex external links, in HTML exportInternal links (@pxref{Internal links}) will continue to work in HTML. Thisincludes automatic links created by radio targets (@pxref{Radiotargets}). Links to external files will still work if the target file is onthe same @i{relative} path as the published Org file. Links to other@file{.org} files will be translated into HTML links under the assumptionthat an HTML version also exists of the linked file, at the same relativepath. @samp{id:} links can then be used to jump to specific entries acrossfiles. For information related to linking files while publishing them to apublishing directory see @ref{Publishing links}.If you want to specify attributes for links, you can do so using a special@code{#+ATTR_HTML} line to define attributes that will be added to the@code{<a>} or @code{<img>} tags. Here is an example that sets @code{title}and @code{style} attributes for a link:@cindex #+ATTR_HTML@example#+ATTR_HTML: title="The Org-mode homepage" style="color:red;"[[http://orgmode.org]]@end example@node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export@subsection Tables@cindex tables, in HTML@vindex org-export-html-table-tagOrg-mode tables are exported to HTML using the table tag defined in@code{org-export-html-table-tag}. The default setting makes tables withoutcell borders and frame. If you would like to change this for individualtables, place something like the following before the table:@cindex #+CAPTION@cindex #+ATTR_HTML@example#+CAPTION: This is a table with lines around and between cells#+ATTR_HTML: border="2" rules="all" frame="all"@end example@node Images in HTML export, Text areas in HTML export, Tables in HTML export, HTML export@subsection Images in HTML export@cindex images, inline in HTML@cindex inlining images in HTML@vindex org-export-html-inline-imagesHTML export can inline images given as links in the Org file, andit can make an image the clickable part of a link. Bydefault@footnote{But see the variable@code{org-export-html-inline-images}.}, images are inlined if a link doesnot have a description. So @samp{[[file:myimg.jpg]]} will be inlined,while @samp{[[file:myimg.jpg][the image]]} will just produce a link@samp{the image} that points to the image. If the description partitself is a @code{file:} link or a @code{http:} URL pointing to animage, this image will be inlined and activated so that clicking on theimage will activate the link. For example, to include a thumbnail thatwill link to a high resolution version of the image, you could use:@example[[file:highres.jpg][file:thumb.jpg]]@end exampleIf you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}.In the example below we specify the @code{alt} and @code{title} attributes tosupport text viewers and accessibility, and align it to the right.@cindex #+CAPTION@cindex #+ATTR_HTML@example#+CAPTION: A black cat stalking a spider#+ATTR_HTML: alt="cat/spider image" title="Action!" align="right"[[./img/a.jpg]]@end example@noindentand you could use @code{http} addresses just as well.@node Text areas in HTML export, CSS support, Images in HTML export, HTML export@subsection Text areas in HTML export@cindex text areas, in HTMLAn alternative way to publish literal code examples in HTML is to use textareas, where the example can even be edited before pasting it into anapplication. It is triggered by a @code{-t} switch at an @code{example} or@code{src} block. Using this switch disables any options for syntax andlabel highlighting, and line numbering, which may be present. You may alsouse @code{-h} and @code{-w} switches to specify the height and width of thetext area, which default to the number of lines in the example, and 80,respectively. For example@example#+BEGIN_EXAMPLE -t -w 40 (defun org-xor (a b) "Exclusive or." (if a (not b) b))#+END_EXAMPLE@end example@node CSS support, JavaScript support, Text areas in HTML export, HTML export@subsection CSS support@cindex CSS, for HTML export@cindex HTML export, CSS@vindex org-export-html-todo-kwd-class-prefix@vindex org-export-html-tag-class-prefixYou can also give style information for the exported file. The HTML exporterassigns the following special CSS classes@footnote{If the classes on TODOkeywords and tags lead to conflicts, use the variables@code{org-export-html-todo-kwd-class-prefix} and@code{org-export-html-tag-class-prefix} to make them unique.} to appropriateparts of the document---your style specifications may change these, inaddition to any of the standard classes like for headlines, tables, etc.@examplep.author @r{author information, including email}p.date @r{publishing date}p.creator @r{creator info, about org-mode version}.title @r{document title}.todo @r{TODO keywords, all not-done states}.done @r{the DONE keywords, all stated the count as done}.WAITING @r{each TODO keyword also uses a class named after itself}.timestamp @r{timestamp}.timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED}.timestamp-wrapper @r{span around keyword plus timestamp}.tag @r{tag in a headline}._HOME @r{each tag uses itself as a class, "@@" replaced by "_"}.target @r{target for links}.linenr @r{the line number in a code example}.code-highlighted @r{for highlighting referenced code lines}div.outline-N @r{div for outline level N (headline plus text))}div.outline-text-N @r{extra div for text at outline level N}.section-number-N @r{section number in headlines, different for each level}div.figure @r{how to format an inlined image}pre.src @r{formatted source code}pre.example @r{normal example}p.verse @r{verse paragraph}div.footnotes @r{footnote section headline}p.footnote @r{footnote definition paragraph, containing a footnote}.footref @r{a footnote reference number (always a <sup>)}.footnum @r{footnote number in footnote definition (always <sup>)}@end example@vindex org-export-html-style-default@vindex org-export-html-style-include-default@vindex org-export-html-style@vindex org-export-html-extra@vindex org-export-html-style-defaultEach exported file contains a compact default style that defines theseclasses in a basic way@footnote{This style is defined in the constant@code{org-export-html-style-default}, which you should not modify. To turninclusion of these defaults off, customize@code{org-export-html-style-include-default}}. You may overwrite thesesettings, or add to them by using the variables @code{org-export-html-style}(for Org-wide settings) and @code{org-export-html-style-extra} (for moregranular settings, like file-local settings). To set the latter variableindividually for each file, you can use@cindex #+STYLE@example#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />@end example@noindentFor longer style definitions, you can use several such lines. You could alsodirectly write a @code{<style>} @code{</style>} section in this way, withoutreferring to an external file.@c FIXME: More about header and footer styles@c FIXME: Talk about links and targets.@node JavaScript support, , CSS support, HTML export@subsection JavaScript supported display of web pages@cindex Rose, SebastianSebastian Rose has written a JavaScript program especially designed toenhance the web viewing experience of HTML files created with Org. Thisprogram allows you to view large files in two different ways. The first oneis an @emph{Info}-like mode where each section is displayed separately andnavigation can be done with the @kbd{n} and @kbd{p} keys (and some other keysas well, press @kbd{?} for an overview of the available keys). The secondview type is a @emph{folding} view much like Org provides inside Emacs. Thescript is available at @url{http://orgmode.org/org-info.js} and you can findthe documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}.We host the script at our site, but if you use it a lot, you mightnot want to be dependent on @url{orgmode.org} and prefer to install a localcopy on your own web server.To use the script, you need to make sure that the @file{org-jsinfo.el} modulegets loaded. It should be loaded by default, but you can try @kbd{M-xcustomize-variable @key{RET} org-modules @key{RET}} to convince yourself thatthis is indeed the case. All it then takes to make use of the program isadding a single line to the Org file:@cindex #+INFOJS_OPT@example#+INFOJS_OPT: view:info toc:nil@end example@noindentIf this line is found, the HTML header will automatically contain the codeneeded to invoke the script. Using the line above, you can set the followingviewing options:@examplepath: @r{The path to the script. The default is to grab the script from} @r{@url{http://orgmode.org/org-info.js}, but you might want to have} @r{a local copy and use a path like @samp{../scripts/org-info.js}.}view: @r{Initial view when website is first shown. Possible values are:} info @r{Info-like interface with one section per page.} overview @r{Folding interface, initially showing only top-level.} content @r{Folding interface, starting with all headlines visible.} showall @r{Folding interface, all headlines and text visible.}sdepth: @r{Maximum headline level that will still become an independent} @r{section for info and folding modes. The default is taken from} @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).} @r{If this is smaller than in @code{org-export-headline-levels}, each} @r{info/folding section can still contain child headlines.}toc: @r{Should the table of content @emph{initially} be visible?} @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}tdepth: @r{The depth of the table of contents. The defaults are taken from} @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}ftoc: @r{Does the css of the page specify a fixed position for the "toc"?} @r{If yes, the toc will never be displayed as a section.}ltoc: @r{Should there be short contents (children) in each section?} @r{Make this @code{above} if the section should be above initial text.}mouse: @r{Headings are highlighted when the mouse is over them. Should be} @r{@samp{underline} (default) or a background color like @samp{#cccccc}.}buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the} @r{default), only one such button will be present.}@end example@noindent@vindex org-infojs-options@vindex org-export-html-use-infojsYou can choose default values for these options by customizing the variable@code{org-infojs-options}. If you always want to apply the script to yourpages, configure the variable @code{org-export-html-use-infojs}.@node LaTeX and PDF export, DocBook export, HTML export, Exporting@section La@TeX{} and PDF export@cindex La@TeX{} export@cindex PDF export@cindex Guerry, BastienOrg-mode contains a La@TeX{} exporter written by Bastien Guerry. Withfurther processing@footnote{The default LaTeX output is designed forprocessing with pdftex or latex. It includes packages that are notcompatible with xetex and possibly luatex. See the variables@code{org-export-latex-default-packages-alist} and@code{org-export-latex-packages-alist}.}, this backend is also used toproduce PDF output. Since the La@TeX{} output uses @file{hyperref} toimplement links and cross references, the PDF output file will be fullylinked.@menu* LaTeX/PDF export commands:: Which key invokes which commands* Header and sectioning:: Setting up the export file structure* Quoting LaTeX code:: Incorporating literal La@TeX{} code* Tables in LaTeX export:: Options for exporting tables to La@TeX{}* Images in LaTeX export:: How to insert figures into La@TeX{} output* Beamer class export:: Turning the file into a presentation@end menu@node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export@subsection La@TeX{} export commands@cindex region, active@cindex active region@cindex transient-mark-mode@table @kbd@kindex C-c C-e l@item C-c C-e l@cindex property EXPORT_FILE_NAMEExport as La@TeX{} file @file{myfile.tex}. For an Org file@file{myfile.org}, the ASCII file will be @file{myfile.tex}. The file willbe overwritten without warning. If there is an active region@footnote{Thisrequires @code{transient-mark-mode} be turned on.}, only the region will beexported. If the selected region is a single tree@footnote{To select thecurrent subtree, use @kbd{C-c @@}.}, the tree head will become the documenttitle. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME}property, that name will be used for the export.@kindex C-c C-e L@item C-c C-e LExport to a temporary buffer, do not create a file.@kindex C-c C-e v l@kindex C-c C-e v L@item C-c C-e v l@item C-c C-e v LExport only the visible part of the document.@item M-x org-export-region-as-latexConvert the region to La@TeX{} under the assumption that it was Org-modesyntax before. This is a global command that can be invoked in anybuffer.@item M-x org-replace-region-by-latexReplace the active region (assumed to be in Org-mode syntax) by La@TeX{}code.@kindex C-c C-e p@item C-c C-e pExport as La@TeX{} and then process to PDF.@kindex C-c C-e d@item C-c C-e dExport as La@TeX{} and then process to PDF, then open the resulting PDF file.@end table@cindex headline levels, for exporting@vindex org-latex-low-levelsIn the exported version, the first 3 outline levels will becomeheadlines, defining a general document structure. Additional levelswill be exported as description lists. The exporter can ignore them orconvert them to a custom string depending on@code{org-latex-low-levels}.If you want that transition to occur at a different level, specify itwith a numeric prefix argument. For example,@example@kbd{C-2 C-c C-e l}@end example@noindentcreates two levels of headings and does the rest as items.@node Header and sectioning, Quoting LaTeX code, LaTeX/PDF export commands, LaTeX and PDF export@subsection Header and sectioning structure@cindex La@TeX{} class@cindex La@TeX{} sectioning structure@cindex La@TeX{} header@cindex header, for LaTeX files@cindex sectioning structure, for LaTeX exportBy default, the La@TeX{} output uses the class @code{article}.@vindex org-export-latex-default-class@vindex org-export-latex-classes@vindex org-export-latex-default-packages-alist@vindex org-export-latex-packages-alist@cindex #+LATEX_HEADER@cindex #+LATEX_CLASS@cindex #+LATEX_CLASS_OPTIONS@cindex property, LATEX_CLASS@cindex property, LATEX_CLASS_OPTIONSYou can change this globally by setting a different value for@code{org-export-latex-default-class} or locally by adding an option like@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:}property that applies when exporting a region containing only this (sub)tree.The class must be listed in @code{org-export-latex-classes}. This variabledefines a header template for each class@footnote{Into which the values of@code{org-export-latex-default-packages-alist} and@code{org-export-latex-packages-alist} are spliced.}, and allows you todefine the sectioning structure for each class. You can also define your ownclasses there. @code{#+LaTeX_CLASS_OPTIONS} or a @code{LaTeX_CLASS_OPTIONS}property can specify the options for the @code{\documentclass} macro. Youcan also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to theheader. See the docstring of @code{org-export-latex-classes} for moreinformation.@node Quoting LaTeX code, Tables in LaTeX export, Header and sectioning, LaTeX and PDF export@subsection Quoting La@TeX{} codeEmbedded La@TeX{} as described in @ref{Embedded LaTeX}, will be correctlyinserted into the La@TeX{} file. This includes simple macros like@samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore,you can add special code that should only be present in La@TeX{} export withthe following constructs:@cindex #+LaTeX@cindex #+BEGIN_LaTeX@example#+LaTeX: Literal LaTeX code for export@end example@noindent or@cindex #+BEGIN_LaTeX@example#+BEGIN_LaTeXAll lines between these markers are exported literally#+END_LaTeX@end example@node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export@subsection Tables in La@TeX{} export@cindex tables, in La@TeX{} exportFor La@TeX{} export of a table, you can specify a label and a caption(@pxref{Images and tables}). You can also use the @code{ATTR_LaTeX} line torequest a @code{longtable} environment for the table, so that it may spanseveral pages, or provide the @code{multicolumn} keyword that will make thetable span the page in a multicolumn environment (@code{table*} environment).Finally, you can set the alignment string:@cindex #+CAPTION@cindex #+LABEL@cindex #+ATTR_LaTeX@example#+CAPTION: A long table#+LABEL: tbl:long#+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l| ..... | ..... || ..... | ..... |@end example@node Images in LaTeX export, Beamer class export, Tables in LaTeX export, LaTeX and PDF export@subsection Images in La@TeX{} export@cindex images, inline in La@TeX{}@cindex inlining images in La@TeX{}Images that are linked to without a description part in the link, like@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDFoutput file resulting from La@TeX{} processing. Org will use an@code{\includegraphics} macro to insert the image. If you have specified acaption and/or a label as described in @ref{Images and tables}, the figurewill be wrapped into a @code{figure} environment and thus become a floatingelement. You can use an @code{#+ATTR_LaTeX:} line to specify the variousoptions that can be used in the optional argument of the@code{\includegraphics} macro. To modify the placement option of the@code{figure} environment, add something like @samp{placement=[h!]} to theAttributes.If you would like to let text flow around the image, add the word @samp{wrap}to the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the lefthalf of the page. To fine-tune, the @code{placement} field will be the setof additional arguments needed by the @code{wrapfigure} environment. Notethat if you change the size of the image, you need to use compatible settingsfor @code{\includegraphics} and @code{wrapfigure}.@cindex #+CAPTION@cindex #+LABEL@cindex #+ATTR_LaTeX@example#+CAPTION: The black-body emission of the disk around HR 4049#+LABEL: fig:SED-HR4049#+ATTR_LaTeX: width=5cm,angle=90[[./img/sed-hr4049.pdf]]#+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@}[[./img/hst.png]]@end exampleIf you need references to a label created in this way, write@samp{\ref@{fig:SED-HR4049@}} just like in La@TeX{}.@node Beamer class export, , Images in LaTeX export, LaTeX and PDF export@subsection Beamer class exportThe LaTeX class @file{beamer} allows production of high quality presentationsusing LaTeX and pdf processing. Org-mode has special support for turning anOrg-mode file or tree into a @file{beamer} presentation.When the LaTeX class for the current buffer (as set with @code{#+LaTeX_CLASS:beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is@code{beamer}, a special export mode will turn the file or tree into a beamerpresentation. Any tree with not-too-deep level nesting should in principle beexportable as a beamer presentation. By default, the top-level entries (orthe first level below the selected subtree heading) will be turned intoframes, and the outline structure below this level will become itemize lists.You can also configure the variable @code{org-beamer-frame-level} to adifferent level - then the hierarchy above frames will produce the sectioningstructure of the presentation.A template for useful in-buffer settings or properties can be inserted intothe buffer with @kbd{M-x org-beamer-settings-template}. Among other things,this will install a column view format which is very handy for editingspecial properties used by beamer.You can influence the structure of the presentation using the followingproperties:@table @code@item BEAMER_envThe environment that should be used to format this entry. Valid environmentsare defined in the constant @code{org-beamer-environments-default}, and youcan define more in @code{org-beamer-environments-extra}. If this property isset, the entry will also get a @code{:B_environment:} tag to make thisvisible. This tag has no semantic meaning, it is only a visual aid.@item BEAMER_envargsThe beamer-special arguments that should be used for the environment, like@code{[t]} or @code{[<+->]} of @code{<2-3>}. If the @code{BEAMER_col}property is also set, something like @code{C[t]} can be added here as well toset an options argument for the implied @code{columns} environment.@code{c[t]} will set an option for the implied @code{column} environment.@item BEAMER_colThe width of a column that should start with this entry. If this property isset, the entry will also get a @code{:BMCOL:} property to make this visible.Also this tag is only a visual aid. When this is a plain number, it will beinterpreted as a fraction of @code{\textwidth}. Otherwise it will be assumedthat you have specified the units, like @samp{3cm}. The first such propertyin a frame will start a @code{columns} environment to surround the columns.This environment is closed when an entry has a @code{BEAMER_col} propertywith value 0 or 1, or automatically at the end of the frame.@item BEAMER_extraAdditional commands that should be inserted after the environment has beenopened. For example, when creating a frame, this can be used to specifytransitions.@end tableFrames will automatically receive a @code{fragile} option if they containsource code that uses the verbatim environment. Special @file{beamer}specific code can be inserted using @code{#+BEAMER:} and@code{#+BEGIN_beamer...#+end_beamer} constructs, similar to other exportbackends, but with the difference that @code{#+LaTeX:} stuff will be includedin the presentation as well.Outline nodes with @code{BEAMER_env} property value @samp{note} or@samp{noteNH} will be formatted as beamer notes, i,e, they will be wrappedinto @code{\note@{...@}}. The former will include the heading as part of thenote text, the latter will ignore the heading of that node. To simplify notegeneration, it is actually enough to mark the note with a @emph{tag} (either@code{:B_note:} or @code{:B_noteNH:}) instead of creating the@code{BEAMER_env} property.You can turn on a special minor mode @code{org-beamer-mode} for editingsupport with@example#+STARTUP: beamer@end example@table @kbd@kindex C-c C-b@item C-c C-bIn @code{org-beamer-mode}, this key offers fast selection of a beamerenvironment or the @code{BEAMER_col} property.@end tableColumn view provides a great way to set the environment of a node and otherimportant parameters. Make sure you are using a COLUMN format that is gearedtoward this special purpose. The command @kbd{M-xorg-beamer-settings-template} defines such a format.Here is a simple example Org document that is intended for beamer export.@smallexample#+LaTeX_CLASS: beamer#+TITLE: Example Presentation#+AUTHOR: Carsten Dominik#+LaTeX_CLASS_OPTIONS: [presentation]#+BEAMER_FRAME_LEVEL: 2#+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@}#+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex)* This is the first structural section** Frame 1 \\ with a subtitle*** Thanks to Eric Fraga :BMCOL:B_block: :PROPERTIES: :BEAMER_env: block :BEAMER_envargs: C[t] :BEAMER_col: 0.5 :END: for the first viable beamer setup in Org*** Thanks to everyone else :BMCOL:B_block: :PROPERTIES: :BEAMER_col: 0.5 :BEAMER_env: block :BEAMER_envargs: <2-> :END: for contributing to the discussion**** This will be formatted as a beamer note :B_note:** Frame 2 \\ where we will not use columns*** Request :B_block: Please test this stuff! :PROPERTIES: :BEAMER_env: block :END:@end smallexampleFor more information, see the documentation on Worg.@node DocBook export, TaskJuggler export, LaTeX and PDF export, Exporting@section DocBook export@cindex DocBook export@cindex PDF export@cindex Cui, BaoqiuOrg contains a DocBook exporter written by Baoqiu Cui. Once an Org file isexported to DocBook format, it can be further processed to produce otherformats, including PDF, HTML, man pages, etc., using many available DocBooktools and stylesheets.Currently DocBook exporter only supports DocBook V5.0.@menu* DocBook export commands:: How to invoke DocBook export* Quoting DocBook code:: Incorporating DocBook code in Org files* Recursive sections:: Recursive sections in DocBook* Tables in DocBook export:: Tables are exported as HTML tables* Images in DocBook export:: How to insert figures into DocBook output* Special characters:: How to handle special characters@end menu@node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export@subsection DocBook export commands@cindex region, active@cindex active region@cindex transient-mark-mode@table @kbd@kindex C-c C-e D@item C-c C-e D@cindex property EXPORT_FILE_NAMEExport as DocBook file. For an Org file, @file{myfile.org}, the DocBook XMLfile will be @file{myfile.xml}. The file will be overwritten withoutwarning. If there is an active region@footnote{This requires@code{transient-mark-mode} to be turned on}, only the region will beexported. If the selected region is a single tree@footnote{To select thecurrent subtree, use @kbd{C-c @@}.}, the tree head will become the documenttitle. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}property, that name will be used for the export.@kindex C-c C-e V@item C-c C-e VExport as DocBook file, process to PDF, then open the resulting PDF file.@vindex org-export-docbook-xslt-proc-command@vindex org-export-docbook-xsl-fo-proc-commandNote that, in order to produce PDF output based on exported DocBook file, youneed to have XSLT processor and XSL-FO processor software installed on yoursystem. Check variables @code{org-export-docbook-xslt-proc-command} and@code{org-export-docbook-xsl-fo-proc-command}.@vindex org-export-docbook-xslt-stylesheetThe stylesheet argument @code{%s} in variable@code{org-export-docbook-xslt-proc-command} is replaced by the value ofvariable @code{org-export-docbook-xslt-stylesheet}, which needs to be set bythe user. You can also overrule this global setting on a per-file basis byadding an in-buffer setting @code{#+XSLT:} to the Org file.@kindex C-c C-e v D@item C-c C-e v DExport only the visible part of the document.@end table@node Quoting DocBook code, Recursive sections, DocBook export commands, DocBook export@subsection Quoting DocBook codeYou can quote DocBook code in Org files and copy it verbatim into exportedDocBook file with the following constructs:@cindex #+DOCBOOK@cindex #+BEGIN_DOCBOOK@example#+DOCBOOK: Literal DocBook code for export@end example@noindent or@cindex #+BEGIN_DOCBOOK@example#+BEGIN_DOCBOOKAll lines between these markers are exported by DocBook exporterliterally.#+END_DOCBOOK@end exampleFor example, you can use the following lines to include a DocBook warningadmonition. As to what this warning says, you should pay attention to thedocument context when quoting DocBook code in Org files. You may makeexported DocBook XML files invalid by not quoting DocBook code correctly.@example#+BEGIN_DOCBOOK<warning> <para>You should know what you are doing when quoting DocBook XML code in your Org file. Invalid DocBook XML file may be generated by DocBook exporter if you are not careful!</para></warning>#+END_DOCBOOK@end example@node Recursive sections, Tables in DocBook export, Quoting DocBook code, DocBook export@subsection Recursive sections@cindex DocBook recursive sectionsDocBook exporter exports Org files as articles using the @code{article}element in DocBook. Recursive sections, i.e. @code{section} elements, areused in exported articles. Top level headlines in Org files are exported astop level sections, and lower level headlines are exported as nestedsections. The entire structure of Org files will be exported completely, nomatter how many nested levels of headlines there are.Using recursive sections makes it easy to port and reuse exported DocBookcode in other DocBook document types like @code{book} or @code{set}.@node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export@subsection Tables in DocBook export@cindex tables, in DocBook exportTables in Org files are exported as HTML tables, which have been supported sinceDocBook V4.3.If a table does not have a caption, an informal table is generated using the@code{informaltable} element; otherwise, a formal table will be generatedusing the @code{table} element.@node Images in DocBook export, Special characters, Tables in DocBook export, DocBook export@subsection Images in DocBook export@cindex images, inline in DocBook@cindex inlining images in DocBookImages that are linked to without a description part in the link, like@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, will be exported to DocBookusing @code{mediaobject} elements. Each @code{mediaobject} element containsan @code{imageobject} that wraps an @code{imagedata} element. If you havespecified a caption for an image as described in @ref{Images and tables}, a@code{caption} element will be added in @code{mediaobject}. If a label isalso specified, it will be exported as an @code{xml:id} attribute of the@code{mediaobject} element.@vindex org-export-docbook-default-image-attributesImage attributes supported by the @code{imagedata} element, like @code{align}or @code{width}, can be specified in two ways: you can either customizevariable @code{org-export-docbook-default-image-attributes} or use the@code{#+ATTR_DOCBOOK:} line. Attributes specified in variable@code{org-export-docbook-default-image-attributes} are applied to all inlineimages in the Org file to be exported (unless they are overridden by imageattributes specified in @code{#+ATTR_DOCBOOK:} lines).The @code{#+ATTR_DOCBOOK:} line can be used to specify additional imageattributes or override default image attributes for individual images. Ifthe same attribute appears in both the @code{#+ATTR_DOCBOOK:} line andvariable @code{org-export-docbook-default-image-attributes}, the formertakes precedence. Here is an example about how image attributes can beset:@cindex #+CAPTION@cindex #+LABEL@cindex #+ATTR_DOCBOOK@example#+CAPTION: The logo of Org-mode#+LABEL: unicorn-svg#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"[[./img/org-mode-unicorn.svg]]@end example@vindex org-export-docbook-inline-image-extensionsBy default, DocBook exporter recognizes the following image file types:@file{jpeg}, @file{jpg}, @file{png}, @file{gif}, and @file{svg}. You cancustomize variable @code{org-export-docbook-inline-image-extensions} to addmore types to this list as long as DocBook supports them.@node Special characters, , Images in DocBook export, DocBook export@subsection Special characters in DocBook export@cindex Special characters in DocBook export@vindex org-export-docbook-doctype@vindex org-entitiesSpecial characters that are written in @TeX{}-like syntax, such as @code{\alpha},@code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter. Thesecharacters are rewritten to XML entities, like @code{α},@code{Γ}, and @code{Ζ}, based on the list saved in variable@code{org-entities}. As long as the generated DocBook file includes thecorresponding entities, these special characters are recognized.You can customize variable @code{org-export-docbook-doctype} to include theentities you need. For example, you can set variable@code{org-export-docbook-doctype} to the following value to recognize allspecial characters included in XHTML entities:@example"<!DOCTYPE article [<!ENTITY % xhtml1-symbol PUBLIC\"-//W3C//ENTITIES Symbol for HTML//EN//XML\"\"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\">%xhtml1-symbol;]>"@end example@node TaskJuggler export, Freemind export, DocBook export, Exporting@section TaskJuggler export@cindex TaskJuggler export@cindex Project management@uref{http://www.taskjuggler.org/, TaskJuggler} is a project management tool.It provides an optimizing scheduler that computes your project time lines andresource assignments based on the project outline and the constraints thatyou have provided.The TaskJuggler exporter is a bit different from other exporters, such as theHTML and LaTeX exporters for example, in that it does not export all thenodes of a document or strictly follow the order of the nodes in thedocument.Instead the TaskJuggler exporter looks for a tree that defines the tasks anda optionally tree that defines the resources for this project. It thencreates a TaskJuggler file based on these trees and the attributes defined inall the nodes.@subsection TaskJuggler export commands@table @kbd@kindex C-c C-e j@item C-c C-e jExport as TaskJuggler file.@kindex C-c C-e J@item C-c C-e JExport as TaskJuggler file and then open the file with TaskJugglerUI.@end table@subsection Tasks@vindex org-export-taskjuggler-project-tagCreate your tasks as you usually do with Org-mode. Assign efforts to eachtask using properties (it's easiest to do this in the column view). Youshould end up with something similar to the example by Peter Jones in@url{http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org}.Now mark the top node of your tasks with a tag named@code{:taskjuggler_project:} (or whatever you customized@code{org-export-taskjuggler-project-tag} to). You are now ready to exportthe project plan with @kbd{C-c C-e J} which will export the project plan andopen a gantt chart in TaskJugglerUI.@subsection Resources@vindex org-export-taskjuggler-resource-tagNext you can define resources and assign those to work on specific tasks. Youcan group your resources hierarchically. Tag the top node of the resourceswith @code{:taskjuggler_resource:} (or whatever you customized@code{org-export-taskjuggler-resource-tag} to). You can optionally assign anidentifier (named @samp{resource_id}) to the resources (using the standardOrg properties commands, @pxref{Property syntax}) or you can let the exportergenerate identifiers automatically (the exporter picks the first word of theheadline as the identifier as long as it is unique, see the documentation of@code{org-taskjuggler-get-unique-id}). Using that identifier you can thenallocate resources to tasks. This is again done with the @samp{allocate}property on the tasks. Do this in column view or when on the task type@kbd{C-c C-x p allocate @key{RET} <resource_id> @key{RET}}.Once the allocations are done you can again export to TaskJuggler and checkin the Resource Allocation Graph which person is working on what task at whattime.@subsection Export of propertiesThe exporter also takes TODO state information into consideration, i.e. if atask is marked as done it will have the corresponding attribute inTaskJuggler (@samp{complete 100}). Also it will export any property on a taskresource or resource node which is known to TaskJuggler, such as@samp{limits}, @samp{vacation}, @samp{shift}, @samp{booking},@samp{efficiency}, @samp{journalentry}, @samp{rate} for resources or@samp{account}, @samp{start}, @samp{note}, @samp{duration}, @samp{end},@samp{journalentry}, @samp{milestone}, @samp{reference}, @samp{responsible},@samp{scheduling}, etc for tasks.@subsection DependenciesThe exporter will handle dependencies that are defined in the tasks eitherwith the @samp{ORDERED} attribute (@pxref{TODO dependencies}), with the@samp{BLOCKER} attribute (see org-depend.el) or alternatively with a@samp{depends} attribute. Both the @samp{BLOCKER} and the @samp{depends}attribute can be either @samp{previous-sibling} or a reference to anidentifier (named @samp{task_id}) which is defined for another task in theproject. @samp{BLOCKER} and the @samp{depends} attribute can define multipledependencies separated by either space or comma. You can also specifyoptional attributes on the dependency by simply appending it. The followingexamples should illustrate this:@example* Preparation :PROPERTIES: :task_id: preparation :ORDERED: t :END:* Training material :PROPERTIES: :task_id: training_material :ORDERED: t :END:** Markup Guidelines :PROPERTIES: :Effort: 2.0 :END:** Workflow Guidelines :PROPERTIES: :Effort: 2.0 :END:* Presentation :PROPERTIES: :Effort: 2.0 :BLOCKER: training_material @{ gapduration 1d @} preparation :END:@end example@subsection Reports@vindex org-export-taskjuggler-default-reportsTaskJuggler can produce many kinds of reports (e.g. gantt chart, resourceallocation, etc). The user defines what kind of reports should be generatedfor a project in the TaskJuggler file. The exporter will automatically insertsome default reports in the file. These defaults are defined in@code{org-export-taskjuggler-default-reports}. They can be modified usingcustomize along with a number of other options. For a more complete list, see@kbd{M-x customize-group @key{RET} org-export-taskjuggler @key{RET}}.For more information and examples see the Org-taskjuggler tutorial at@uref{http://orgmode.org/worg/org-tutorials/org-taskjuggler.php}.@node Freemind export, XOXO export, TaskJuggler export, Exporting@section Freemind export@cindex Freemind export@cindex mind mapThe Freemind exporter was written by Lennart Borgman.@table @kbd@kindex C-c C-e m@item C-c C-e mExport as Freemind mind map @file{myfile.mm}.@end table@node XOXO export, iCalendar export, Freemind export, Exporting@section XOXO export@cindex XOXO exportOrg-mode contains an exporter that produces XOXO-style output.Currently, this exporter only handles the general outline structure anddoes not interpret any additional Org-mode features.@table @kbd@kindex C-c C-e x@item C-c C-e xExport as XOXO file @file{myfile.html}.@kindex C-c C-e v@item C-c C-e v xExport only the visible part of the document.@end table@node iCalendar export, , XOXO export, Exporting@section iCalendar export@cindex iCalendar export@vindex org-icalendar-include-todo@vindex org-icalendar-use-deadline@vindex org-icalendar-use-scheduled@vindex org-icalendar-categoriesSome people use Org-mode for keeping track of projects, but still prefer astandard calendar application for anniversaries and appointments. In thiscase it can be useful to show deadlines and other time-stamped items in Orgfiles in the calendar application. Org-mode can export calendar informationin the standard iCalendar format. If you also want to have TODO entriesincluded in the export, configure the variable@code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT,and TODO items as VTODO. It will also create events from deadlines that arein non-TODO items. Deadlines and scheduling dates in TODO items will be usedto set the start and due dates for the TODO entry@footnote{See the variables@code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}.As categories, it will use the tags locally defined in the heading, and thefile/tree category@footnote{To add inherited tags or the TODO state,configure the variable @code{org-icalendar-categories}.}.@vindex org-icalendar-store-UID@cindex property, IDThe iCalendar standard requires each entry to have a globally uniqueidentifier (UID). Org creates these identifiers during export. If you setthe variable @code{org-icalendar-store-UID}, the UID will be stored in the@code{:ID:} property of the entry and re-used next time you report thisentry. Since a single entry can give rise to multiple iCalendar entries (asa timestamp, a deadline, a scheduled item, and as a TODO item), Org addsprefixes to the UID, depending on what triggered the inclusion of the entry.In this way the UID remains unique, but a synchronization program can stillfigure out from which entry all the different instances originate.@table @kbd@kindex C-c C-e i@item C-c C-e iCreate iCalendar entries for the current file and store them in the samedirectory, using a file extension @file{.ics}.@kindex C-c C-e I@item C-c C-e I@vindex org-agenda-filesLike @kbd{C-c C-e i}, but do this for all files in@code{org-agenda-files}. For each of these files, a separate iCalendarfile will be written.@kindex C-c C-e c@item C-c C-e c@vindex org-combined-agenda-icalendar-fileCreate a single large iCalendar file from all files in@code{org-agenda-files} and write it to the file given by@code{org-combined-agenda-icalendar-file}.@end table@vindex org-use-property-inheritance@vindex org-icalendar-include-body@cindex property, SUMMARY@cindex property, DESCRIPTION@cindex property, LOCATIONThe export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATIONproperty can be inherited from higher in the hierarchy if you configure@code{org-use-property-inheritance} accordingly.} properties if the selectedentries have them. If not, the summary will be derived from the headline,and the description from the body (limited to@code{org-icalendar-include-body} characters).How this calendar is best read and updated, depends on the applicationyou are using. The FAQ covers this issue.@node Publishing, Working With Source Code, Exporting, Top@chapter Publishing@cindex publishingOrg includes a publishing management system that allows you to configureautomatic HTML conversion of @emph{projects} composed of interlinked orgfiles. You can also configure Org to automatically upload your exported HTMLpages and related attachments, such as images and source code files, to a webserver.You can also use Org to convert files into PDF, or even combine HTML and PDFconversion so that files are available in both formats on the server.Publishing has been contributed to Org by David O'Toole.@menu* Configuration:: Defining projects* Uploading files:: How to get files up on the server* Sample configuration:: Example projects* Triggering publication:: Publication commands@end menu@node Configuration, Uploading files, Publishing, Publishing@section ConfigurationPublishing needs significant configuration to specify files, destinationand many other properties of a project.@menu* Project alist:: The central configuration variable* Sources and destinations:: From here to there* Selecting files:: What files are part of the project?* Publishing action:: Setting the function doing the publishing* Publishing options:: Tweaking HTML export* Publishing links:: Which links keep working after publishing?* Sitemap:: Generating a list of all pages* Generating an index:: An index that reaches across pages@end menu@node Project alist, Sources and destinations, Configuration, Configuration@subsection The variable @code{org-publish-project-alist}@cindex org-publish-project-alist@cindex projects, for publishing@vindex org-publish-project-alistPublishing is configured almost entirely through setting the value of onevariable, called @code{org-publish-project-alist}. Each element of the listconfigures one project, and may be in one of the two following forms:@lisp ("project-name" :property value :property value ...)@r{or} ("project-name" :components ("project-name" "project-name" ...))@end lispIn both cases, projects are configured by specifying property values. Aproject defines the set of files that will be published, as well as thepublishing configuration to use when publishing those files. When a projecttakes the second form listed above, the individual members of the@code{:components} property are taken to be sub-projects, which grouptogether files requiring different publishing options. When you publish sucha ``meta-project'', all the components will also be published, in thesequence given.@node Sources and destinations, Selecting files, Project alist, Configuration@subsection Sources and destinations for files@cindex directories, for publishingMost properties are optional, but some should always be set. Inparticular, Org needs to know where to look for source files,and where to put published files.@multitable @columnfractions 0.3 0.7@item @code{:base-directory}@tab Directory containing publishing source files@item @code{:publishing-directory}@tab Directory where output files will be published. You can directlypublish to a webserver using a file name syntax appropriate forthe Emacs @file{tramp} package. Or you can publish to a local directory anduse external tools to upload your website (@pxref{Uploading files}).@item @code{:preparation-function}@tab Function or list of functions to be called before starting thepublishing process, for example, to run @code{make} for updating files to bepublished. The project property list is scoped into this call as thevariable @code{project-plist}.@item @code{:completion-function}@tab Function or list of functions called after finishing the publishingprocess, for example, to change permissions of the resulting files. Theproject property list is scoped into this call as the variable@code{project-plist}.@end multitable@noindent@node Selecting files, Publishing action, Sources and destinations, Configuration@subsection Selecting files@cindex files, selecting for publishingBy default, all files with extension @file{.org} in the base directoryare considered part of the project. This can be modified by setting theproperties@multitable @columnfractions 0.25 0.75@item @code{:base-extension}@tab Extension (without the dot!) of source files. This actually is aregular expression. Set this to the symbol @code{any} if you want to get allfiles in @code{:base-directory}, even without extension.@item @code{:exclude}@tab Regular expression to match file names that should not bepublished, even though they have been selected on the basis of theirextension.@item @code{:include}@tab List of files to be included regardless of @code{:base-extension}and @code{:exclude}.@end multitable@node Publishing action, Publishing options, Selecting files, Configuration@subsection Publishing action@cindex action, for publishingPublishing means that a file is copied to the destination directory andpossibly transformed in the process. The default transformation is to exportOrg files as HTML files, and this is done by the function@code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTMLexport}). But you also can publish your content as PDF files using@code{org-publish-org-to-pdf}. If you want to publish the Org file itself,but with @i{archived}, @i{commented}, and @i{tag-excluded} trees removed, use@code{org-publish-org-to-org} and set the parameters @code{:plain-source}and/or @code{:htmlized-source}. This will produce @file{file.org} and@file{file.org.html} in the publishingdirectory@footnote{@file{file-source.org} and @file{file-source.org.html} ifsource and publishing directories are equal. Note that with this kind ofsetup, you need to add @code{:exclude "-source\\.org"} to the projectdefinition in @code{org-publish-project-alist} to avoid that the publishedsource files will be considered as new org files the next time the project ispublished.}. Other files like images onlyneed to be copied to the publishing destination, for this you may use@code{org-publish-attachment}. For non-Org files, you always need tospecify the publishing function:@multitable @columnfractions 0.3 0.7@item @code{:publishing-function}@tab Function executing the publication of a file. This may also be alist of functions, which will all be called in turn.@item @code{:plain-source}@tab Non-nil means, publish plain source.@item @code{:htmlized-source}@tab Non-nil means, publish htmlized source.@end multitableThe function must accept three arguments: a property list containing at leasta @code{:publishing-directory} property, the name of the file to bepublished, and the path to the publishing directory of the output file. Itshould take the specified file, make the necessary transformation (if any)and place the result into the destination folder.@node Publishing options, Publishing links, Publishing action, Configuration@subsection Options for the HTML/La@TeX{} exporters@cindex options, for publishingThe property list can be used to set many export options for the HTMLand La@TeX{} exporters. In most cases, these properties correspond to uservariables in Org. The table below lists these properties alongwith the variable they belong to. See the documentation string for therespective variable for details.@vindex org-export-html-link-up@vindex org-export-html-link-home@vindex org-export-default-language@vindex org-display-custom-times@vindex org-export-headline-levels@vindex org-export-with-section-numbers@vindex org-export-section-number-format@vindex org-export-with-toc@vindex org-export-preserve-breaks@vindex org-export-with-archived-trees@vindex org-export-with-emphasize@vindex org-export-with-sub-superscripts@vindex org-export-with-special-strings@vindex org-export-with-footnotes@vindex org-export-with-drawers@vindex org-export-with-tags@vindex org-export-with-todo-keywords@vindex org-export-with-priority@vindex org-export-with-TeX-macros@vindex org-export-with-LaTeX-fragments@vindex org-export-skip-text-before-1st-heading@vindex org-export-with-fixed-width@vindex org-export-with-timestamps@vindex org-export-author-info@vindex org-export-email@vindex org-export-creator-info@vindex org-export-with-tables@vindex org-export-highlight-first-table-line@vindex org-export-html-style-include-default@vindex org-export-html-style@vindex org-export-html-style-extra@vindex org-export-html-link-org-files-as-html@vindex org-export-html-inline-images@vindex org-export-html-extension@vindex org-export-html-table-tag@vindex org-export-html-expand@vindex org-export-html-with-timestamp@vindex org-export-publishing-directory@vindex org-export-html-preamble@vindex org-export-html-postamble@vindex org-export-html-auto-preamble@vindex org-export-html-auto-postamble@vindex user-full-name@vindex user-mail-address@vindex org-export-select-tags@vindex org-export-exclude-tags@multitable @columnfractions 0.32 0.68@item @code{:link-up} @tab @code{org-export-html-link-up}@item @code{:link-home} @tab @code{org-export-html-link-home}@item @code{:language} @tab @code{org-export-default-language}@item @code{:customtime} @tab @code{org-display-custom-times}@item @code{:headline-levels} @tab @code{org-export-headline-levels}@item @code{:section-numbers} @tab @code{org-export-with-section-numbers}@item @code{:section-number-format} @tab @code{org-export-section-number-format}@item @code{:table-of-contents} @tab @code{org-export-with-toc}@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}@item @code{:archived-trees} @tab @code{org-export-with-archived-trees}@item @code{:emphasize} @tab @code{org-export-with-emphasize}@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts}@item @code{:special-strings} @tab @code{org-export-with-special-strings}@item @code{:footnotes} @tab @code{org-export-with-footnotes}@item @code{:drawers} @tab @code{org-export-with-drawers}@item @code{:tags} @tab @code{org-export-with-tags}@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords}@item @code{:priority} @tab @code{org-export-with-priority}@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}@item @code{:latex-listings} @tab @code{org-export-latex-listings}@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading}@item @code{:fixed-width} @tab @code{org-export-with-fixed-width}@item @code{:timestamps} @tab @code{org-export-with-timestamps}@item @code{:author-info} @tab @code{org-export-author-info}@item @code{:email-info} @tab @code{org-export-email-info}@item @code{:creator-info} @tab @code{org-export-creator-info}@item @code{:tables} @tab @code{org-export-with-tables}@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line}@item @code{:style-include-default} @tab @code{org-export-html-style-include-default}@item @code{:style} @tab @code{org-export-html-style}@item @code{:style-extra} @tab @code{org-export-html-style-extra}@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html}@item @code{:inline-images} @tab @code{org-export-html-inline-images}@item @code{:html-extension} @tab @code{org-export-html-extension}@item @code{:xml-declaration} @tab @code{org-export-html-xml-declaration}@item @code{:html-table-tag} @tab @code{org-export-html-table-tag}@item @code{:expand-quoted-html} @tab @code{org-export-html-expand}@item @code{:timestamp} @tab @code{org-export-html-with-timestamp}@item @code{:publishing-directory} @tab @code{org-export-publishing-directory}@item @code{:preamble} @tab @code{org-export-html-preamble}@item @code{:postamble} @tab @code{org-export-html-postamble}@item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble}@item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble}@item @code{:author} @tab @code{user-full-name}@item @code{:email} @tab @code{user-mail-address} : @code{addr;addr;..}@item @code{:select-tags} @tab @code{org-export-select-tags}@item @code{:exclude-tags} @tab @code{org-export-exclude-tags}@item @code{:latex-image-options} @tab @code{org-export-latex-image-default-option}@end multitableMost of the @code{org-export-with-*} variables have the same effect inboth HTML and La@TeX{} exporters, except for @code{:TeX-macros} and@code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in theLa@TeX{} export.@vindex org-publish-project-alistWhen a property is given a value in @code{org-publish-project-alist},its setting overrides the value of the corresponding user variable (ifany) during publishing. Options set within a file (@pxref{Exportoptions}), however, override everything.@node Publishing links, Sitemap, Publishing options, Configuration@subsection Links between published files@cindex links, publishingTo create a link from one Org file to another, you would usesomething like @samp{[[file:foo.org][The foo]]} or simply@samp{file:foo.org.} (@pxref{Hyperlinks}). When published, this linkbecomes a link to @file{foo.html}. In this way, you can interlink thepages of your "org web" project and the links will work as expected whenyou publish them to HTML. If you also publish the Org source file and wantto link to that, use an @code{http:} link instead of a @code{file:} link,because @code{file:} links are converted to link to the corresponding@file{html} file.You may also link to related files, such as images. Provided you are carefulwith relative file names, and provided you have also configured Org to uploadthe related files, these links will work too. See @ref{Complex example}, foran example of this usage.Sometimes an Org file to be published may contain links that areonly valid in your production environment, but not in the publishinglocation. In this case, use the property@multitable @columnfractions 0.4 0.6@item @code{:link-validation-function}@tab Function to validate links@end multitable@noindentto define a function for checking link validity. This function mustaccept two arguments, the file name and a directory relative to whichthe file name is interpreted in the production environment. If thisfunction returns @code{nil}, then the HTML generator will only insert adescription into the HTML file, but no link. One option for thisfunction is @code{org-publish-validate-link} which checks if the givenfile is part of any project in @code{org-publish-project-alist}.@node Sitemap, Generating an index, Publishing links, Configuration@subsection Generating a sitemap@cindex sitemap, of published pagesThe following properties may be used to control publishing ofa map of files for a given project.@multitable @columnfractions 0.35 0.65@item @code{:auto-sitemap}@tab When non-nil, publish a sitemap during @code{org-publish-current-project}or @code{org-publish-all}.@item @code{:sitemap-filename}@tab Filename for output of sitemap. Defaults to @file{sitemap.org} (whichbecomes @file{sitemap.html}).@item @code{:sitemap-title}@tab Title of sitemap page. Defaults to name of file.@item @code{:sitemap-function}@tab Plug-in function to use for generation of the sitemap.Defaults to @code{org-publish-org-sitemap}, which generates a plain listof links to all files in the project.@item @code{:sitemap-sort-folders}@tab Where folders should appear in the sitemap. Set this to @code{first}(default) or @code{last} to display folders first or last,respectively. Any other value will mix files and folders.@item @code{:sitemap-alphabetically}@tab The site map is normally sorted alphabetically. Set this explicitly to@code{nil} to turn off sorting.@item @code{:sitemap-ignore-case}@tab Should sorting be case-sensitive? Default @code{nil}.@end multitable@node Generating an index, , Sitemap, Configuration@subsection Generating an index@cindex index, in a publishing projectOrg-mode can generate an index across the files of a publishing project.@multitable @columnfractions 0.25 0.75@item @code{:makeindex}@tab When non-nil, generate in index in the file @file{theindex.org} andpublish it as @file{theindex.html}.@end multitableThe file will be create when first publishing a project with the@code{:makeindex} set. The file only contains a statement @code{#+include:"theindex.inc"}. You can then built around this include statement by addinga title, style information etc.@node Uploading files, Sample configuration, Configuration, Publishing@section Uploading files@cindex rsync@cindex unisonFor those people already utilizing third party sync tools such as@command{rsync} or @command{unison}, it might be preferable not to use the built in@i{remote} publishing facilities of Org-mode which rely heavily onTramp. Tramp, while very useful and powerful, tends not to beso efficient for multiple file transfer and has been known to cause problemsunder heavy usage.Specialized synchronization utilities offer several advantages. In additionto timestamp comparison, they also do content and permissions/attributechecks. For this reason you might prefer to publish your web to a localdirectory (possibly even @i{in place} with your Org files) and then use@file{unison} or @file{rsync} to do the synchronization with the remote host.Since Unison (for example) can be configured as to which files to transfer toa certain remote destination, it can greatly simplify the project publishingdefinition. Simply keep all files in the correct location, process your Orgfiles with @code{org-publish} and let the synchronization tool do the rest.You do not need, in this scenario, to include attachments such as @file{jpg},@file{css} or @file{gif} files in the project definition since the 3rd partytool syncs them.Publishing to a local directory is also much faster than to a remote one, sothat you can afford more easily to republish entire projects. If you set@code{org-publish-use-timestamps-flag} to @code{nil}, you gain the mainbenefit of re-including any changed external files such as source examplefiles you might include with @code{#+INCLUDE}. The timestamp mechanism inOrg is not smart enough to detect if included files have been modified.@node Sample configuration, Triggering publication, Uploading files, Publishing@section Sample configurationBelow we provide two example configurations. The first one is a simpleproject publishing only a set of Org files. The second example ismore complex, with a multi-component project.@menu* Simple example:: One-component publishing* Complex example:: A multi-component publishing example@end menu@node Simple example, Complex example, Sample configuration, Sample configuration@subsection Example: simple publishing configurationThis example publishes a set of Org files to the @file{public_html}directory on the local machine.@lisp(setq org-publish-project-alist '(("org" :base-directory "~/org/" :publishing-directory "~/public_html" :section-numbers nil :table-of-contents nil :style "<link rel=\"stylesheet\" href=\"../other/mystyle.css\" type=\"text/css\"/>")))@end lisp@node Complex example, , Simple example, Sample configuration@subsection Example: complex publishing configurationThis more complicated example publishes an entire website, includingOrg files converted to HTML, image files, Emacs Lisp source code, andstyle sheets. The publishing directory is remote and private files areexcluded.To ensure that links are preserved, care should be taken to replicateyour directory structure on the web server, and to use relative filepaths. For example, if your Org files are kept in @file{~/org} and yourpublishable images in @file{~/images}, you would link to an image with@c@examplefile:../images/myimage.png@end example@cOn the web server, the relative path to the image should be thesame. You can accomplish this by setting up an "images" folder in theright place on the web server, and publishing images to it.@lisp(setq org-publish-project-alist '(("orgfiles" :base-directory "~/org/" :base-extension "org" :publishing-directory "/ssh:user@@host:~/html/notebook/" :publishing-function org-publish-org-to-html :exclude "PrivatePage.org" ;; regexp :headline-levels 3 :section-numbers nil :table-of-contents nil :style "<link rel=\"stylesheet\" href=\"../other/mystyle.css\" type=\"text/css\"/>" :auto-preamble t :auto-postamble nil) ("images" :base-directory "~/images/" :base-extension "jpg\\|gif\\|png" :publishing-directory "/ssh:user@@host:~/html/images/" :publishing-function org-publish-attachment) ("other" :base-directory "~/other/" :base-extension "css\\|el" :publishing-directory "/ssh:user@@host:~/html/other/" :publishing-function org-publish-attachment) ("website" :components ("orgfiles" "images" "other"))))@end lisp@node Triggering publication, , Sample configuration, Publishing@section Triggering publicationOnce properly configured, Org can publish with the following commands:@table @kbd@kindex C-c C-e C@item C-c C-e CPrompt for a specific project and publish all files that belong to it.@kindex C-c C-e P@item C-c C-e PPublish the project containing the current file.@kindex C-c C-e F@item C-c C-e FPublish only the current file.@kindex C-c C-e E@item C-c C-e EPublish every project.@end table@vindex org-publish-use-timestamps-flagOrg uses timestamps to track when a file has changed. The above functionsnormally only publish changed files. You can override this and forcepublishing of all files by giving a prefix argument to any of the commandsabove, or by customizing the variable @code{org-publish-use-timestamps-flag}.This may be necessary in particular if files include other files via@code{#+SETUPFILE:} or @code{#+INCLUDE:}.@comment node-name, next, previous, up@comment Working With Source Code, Miscellaneous, Publishing, Top@node Working With Source Code, Miscellaneous, Publishing, Top@chapter Working with source code@cindex Schulte, Eric@cindex Davison, Dan@cindex source code, working withSource code can be included in Org-mode documents using a @samp{src} block,e.g.@example#+BEGIN_SRC emacs-lisp (defun org-xor (a b) "Exclusive or." (if a (not b) b))#+END_SRC@end exampleOrg-mode provides a number of features for working with live source code,including editing of code blocks in their native major-mode, evaluation ofcode blocks, tangling of code blocks, and exporting code blocks andtheir results in several formats. This functionality was contributed by DanDavison and Eric Schulte, and was originally named Org-babel.The following sections describe Org-mode's code block handling facilities.@menu* Structure of code blocks:: Code block syntax described* Editing source code:: Language major-mode editing* Exporting code blocks:: Export contents and/or results* Extracting source code:: Create pure source code files* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer* Library of Babel:: Use and contribute to a library of useful code blocks* Languages:: List of supported code block languages* Header arguments:: Configure code block functionality* Results of evaluation:: How evaluation results are handled* Noweb reference syntax:: Literate programming in Org-mode* Key bindings and useful functions:: Work quickly with code blocks* Batch execution:: Call functions from the command line@end menu@comment node-name, next, previous, up@comment Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code@node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code@section Structure of code blocks@cindex code block, structure@cindex source code, block structureThe structure of code blocks is as follows:@example#+srcname: <name>#+begin_src <language> <switches> <header arguments> <body>#+end_src@end example@table @code@item <name>This name is associated with the code block. This is similar to the@samp{#+tblname} lines that can be used to name tables in Org-mode files.Referencing the name of a code block makes it possible to evaluate theblock from other places in the file, other files, or from Org-mode tableformulas (see @ref{The spreadsheet}).@item <language>The language of the code in the block.@item <switches>Switches controlling exportation of the code block (see switches discussion in@ref{Literal examples})@item <header arguments>Optional header arguments control many aspects of evaluation, export andtangling of code blocks. See the @ref{Header arguments}section. Header arguments can also be set on a per-buffer or per-subtreebasis using properties.@item <body>The source code.@end table@comment node-name, next, previous, up@comment Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code@node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code@section Editing source code@cindex code block, editing@cindex source code, editing@kindex C-c 'Use @kbd{C-c '} to edit the current code block. This brings upa language major-mode edit buffer containing the body of the codeblock. Saving this buffer will write the new contents back to the Orgbuffer. Use @kbd{C-c '} again to exit.The @code{org-src-mode} minor mode will be active in the edit buffer. Thefollowing variables can be used to configure the behavior of the editbuffer. See also the customization group @code{org-edit-structure} forfurther configuration options.@table @code@item org-src-lang-modesIf an Emacs major-mode named @code{<lang>-mode} exists, where@code{<lang>} is the language named in the header line of the code block,then the edit buffer will be placed in that major-mode. This variablecan be used to map arbitrary language names to existing major modes.@item org-src-window-setupControls the way Emacs windows are rearranged when the edit buffer is created.@item org-src-preserve-indentationThis variable is especially useful for tangling languages such aspython, in which whitespace indentation in the output is critical.@item org-src-ask-before-returning-to-edit-bufferBy default, Org will ask before returning to an open edit buffer. Setthis variable to nil to switch without asking.@end table@comment node-name, next, previous, up@comment Exporting code blocks, Extracting source code, Editing source code, Working With Source Code@node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code@section Exporting code blocks@cindex code block, exporting@cindex source code, exportingIt is possible to export the @emph{contents} of code blocks, the@emph{results} of code block evaluation, @emph{neither}, or @emph{both}. Formost languages, the default exports the contents of code blocks. However, forsome languages (e.g. @code{ditaa}) the default exports the results of codeblock evaluation. For information on exporting code block bodies, see@ref{Literal examples}.The @code{:exports} header argument can be used to specify exportbehavior:@subsubheading Header arguments:@table @code@item :exports codeThe default in most languages. The body of the code block is exported, asdescribed in @ref{Literal examples}.@item :exports resultsThe code block will be evaluated and the results will be placed in theOrg-mode buffer for export, either updating previous results of the codeblock located anywhere in the buffer or, if no previous results exist,placing the results immediately after the code block. The body of the codeblock will not be exported.@item :exports bothBoth the code block and its results will be exported.@item :exports noneNeither the code block nor its results will be exported.@end tableIt is possible to inhibit the evaluation of code blocks during export.Setting the the @code{org-export-babel-evaluate} variable to @code{nil} willensure that no code blocks are evaluated as part of the export process. Thiscan be useful in situations where potentially untrusted Org-mode files areexported in an automated fashion, for example when Org-mode is used as themarkup language for a wiki.@comment node-name, next, previous, up@comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code@node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code@section Extracting source code@cindex source code, extracting@cindex code block, extracting source codeCreating pure source code files by extracting code from source blocks isreferred to as ``tangling''---a term adopted from the literate programmingcommunity. During ``tangling'' of code blocks their bodies are expandedusing @code{org-babel-expand-src-block} which can expand both variable and``noweb'' style references (see @ref{Noweb reference syntax}).@subsubheading Header arguments@table @code@item :tangle noThe default. The code block is not included in the tangled output.@item :tangle yesInclude the code block in the tangled output. The output file name is thename of the org file with the extension @samp{.org} replaced by the extensionfor the block language.@item :tangle filenameInclude the code block in the tangled output to file @samp{filename}.@end table@kindex C-c C-v t@subsubheading Functions@table @code@item org-babel-tangle @kbd{C-c C-v t}Tangle the current file.@item org-babel-tangle-fileChoose a file to tangle.@end table@subsubheading Hooks@table @code@item org-babel-post-tangle-hookThis hook is run from within code files tangled by @code{org-babel-tangle}.Example applications could include post-processing, compilation or evaluationof tangled code files.@end table@node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code@section Evaluating code blocks@cindex code block, evaluating@cindex source code, evaluatingCode blocks can be evaluated@footnote{Whenever code is evaluated there is apotential for that code to do harm. Org-mode provides a number of safeguardsto ensure that it only evaluates code with explicit confirmation from theuser. For information on these safeguards (and on how to disable them) see@ref{Code evaluation security}.} and the results placed in the Org-modebuffer. By default, evaluation is only turned on for @code{emacs-lisp} codeblocks, however support exists for evaluating blocks in many languages. See@ref{Languages} for a list of supported languages. See @ref{Structure ofcode blocks} for information on the syntax used to define a code block.@kindex C-c C-cThere are a number of ways to evaluate code blocks. The simplest is to press@kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The@code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove codeevaluation from the @kbd{C-c C-c} key binding.}. This will call the@code{org-babel-execute-src-block} function to evaluate the block and insertits results into the Org-mode buffer.It is also possible to evaluate named code blocks from anywhere in anOrg-mode buffer or an Org-mode table. @code{#+call} (or synonymously@code{#+function} or @code{#+lob}) lines can be used to remotely execute codeblocks located in the current Org-mode buffer or in the ``Library of Babel''(see @ref{Library of Babel}). These lines use the following syntax.@example#+call: <name>(<arguments>) <header arguments>#+function: <name>(<arguments>) <header arguments>#+lob: <name>(<arguments>) <header arguments>@end example@table @code@item <name>The name of the code block to be evaluated.@item <arguments>Arguments specified in this section will be passed to the code block.@item <header arguments>Header arguments can be placed after the function invocation. See@ref{Header arguments} for more information on header arguments.@end table@node Library of Babel, Languages, Evaluating code blocks, Working With Source Code@section Library of Babel@cindex babel, library of@cindex source code, library@cindex code block, libraryThe ``Library of Babel'' is a library of code blocksthat can be called from any Org-mode file. The library is housed in anOrg-mode file located in the @samp{contrib} directory of Org-mode.Org-mode users can deposit functions they believe to be generallyuseful in the library.Code blocks defined in the ``Library of Babel'' can be called remotely as ifthey were in the current Org-mode buffer (see @ref{Evaluating code blocks}for information on the syntax of remote code block evaluation).@kindex C-c C-v lCode blocks located in any Org-mode file can be loaded into the ``Library ofBabel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-vl}.@node Languages, Header arguments, Library of Babel, Working With Source Code@section Languages@cindex babel, languages@cindex source code, languages@cindex code block, languagesCode blocks in the following languages are supported.@multitable @columnfractions 0.28 0.3 0.22 0.2@item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}@item Asymptote @tab asymptote @tab C @tab C@item C++ @tab C++ @tab Clojure @tab clojure@item css @tab css @tab ditaa @tab ditaa@item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp@item gnuplot @tab gnuplot @tab Haskell @tab haskell@item LaTeX @tab latex @tab Matlab @tab matlab@item Mscgen @tab mscgen @tab Objective Caml @tab ocaml@item Octave @tab octave @tab OZ @tab oz@item Perl @tab perl @tab Python @tab python@item R @tab R @tab Ruby @tab ruby@item Sass @tab sass @tab GNU Screen @tab screen@item shell @tab sh @tab SQL @tab sql@item Sqlite @tab sqlite@end multitableLanguage-specific documentation is available for some languages. Ifavailable, it can be found at@uref{http://orgmode.org/worg/org-contrib/babel/languages}.The @code{org-babel-load-languages} controls which languages are enabled forevaluation (by default only @code{emacs-lisp} is enabled). This variable canbe set using the customization interface or by adding code like the followingto your emacs configuration.@quotationThe following disables @code{emacs-lisp} evaluation and enables evaluation of@code{R} code blocks.@end quotation@lisp(org-babel-do-load-languages 'org-babel-load-languages '((emacs-lisp . nil) (R . t)))@end lispIt is also possible to enable support for a language by loading the relatedelisp file with @code{require}.@quotationThe following adds support for evaluating @code{clojure} code blocks.@end quotation@lisp(require 'ob-clojure)@end lisp@node Header arguments, Results of evaluation, Languages, Working With Source Code@section Header arguments@cindex code block, header arguments@cindex source code, block header argumentsCode block functionality can be configured with header arguments. Thissection provides an overview of the use of header arguments, and thendescribes each header argument in detail.@menu* Using header arguments:: Different ways to set header arguments* Specific header arguments:: List of header arguments@end menu@node Using header arguments, Specific header arguments, Header arguments, Header arguments@subsection Using header argumentsThe values of header arguments can be set in five different ways, each morespecific (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@end menu@node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments@subsubheading System-wide header arguments@vindex org-babel-default-header-argsSystem-wide values of header arguments can be specified by customizing the@code{org-babel-default-header-args} variable:@example:session => "none":results => "replace":exports => "code":cache => "no":noweb => "no"@end example@c @example@c org-babel-default-header-args is a variable defined in `org-babel.el'.@c Its value is@c ((:session . "none")@c (:results . "replace")@c (:exports . "code")@c (:cache . "no")@c (:noweb . "no"))@c Documentation:@c Default arguments to use when evaluating a code block.@c @end exampleFor example, the following example could be used to set the default value of@code{:noweb} header arguments to @code{yes}. This would have the effect ofexpanding @code{:noweb} references by default when evaluating source codeblocks.@lisp(setq org-babel-default-header-args(cons '(:noweb . "yes")(assq-delete-all :noweb org-babel-default-header-args)))@end lisp@node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments@subsubheading Language-specific header argumentsEach language can define its own set of default header arguments. See thelanguage-specific documentation available online at@uref{http://orgmode.org/worg/org-contrib/babel}.@node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments@subsubheading Buffer-wide header argumentsBuffer-wide header arguments may be specified through the use of a specialline placed anywhere in an Org-mode file. The line consists of the@code{#+BABEL:} keyword followed by a series of header arguments which may bespecified using the standard header argument syntax.For example the following would set @code{session} to @code{*R*}, and@code{results} to @code{silent} for every code block in the buffer, ensuringthat all execution took place in the same session, and no results would beinserted into the buffer.@example#+BABEL: :session *R* :results silent@end example@node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments@subsubheading Header arguments in Org-mode propertiesHeader arguments are also read from Org-mode properties (see @ref{Propertysyntax}), which can be set on a buffer-wide or per-heading basis. An exampleof setting a header argument for all code blocks in a buffer is@example#+property: tangle yes@end exampleWhen properties are used to set default header arguments, they are looked upwith inheritance, so the value of the @code{:cache} header argument will defaultto @code{yes} in all code blocks in the subtree rooted at the followingheading:@example* outline header:PROPERTIES::cache: yes:END:@end example@kindex C-c C-x p@vindex org-babel-default-header-argsProperties defined in this way override the properties set in@code{org-babel-default-header-args}. It is convenient to use the@code{org-set-property} function bound to @kbd{C-c C-x p} to set propertiesin Org-mode documents.@node Code block specific header arguments, , Header arguments in Org-mode properties, Using header arguments@subsubheading Code block specific header argumentsThe most common way to assign values to header arguments is at thecode block level. This can be done by listing a sequence of headerarguments and their values as part of the @code{#+begin_src} line.Properties set in this way override both the values of@code{org-babel-default-header-args} and header arguments specified asproperties. In the following example, the @code{:results} header argumentis set to @code{silent}, meaning the results of execution will not beinserted in the buffer, and the @code{:exports} header argument is set to@code{code}, meaning only the body of the code block will bepreserved on export to HTML or LaTeX.@example#+source: factorial#+begin_src haskell :results silent :exports code :var n=0fac 0 = 1fac n = n * fac (n-1)#+end_src@end exampleSimilarly, it is possible to set header arguments for inline code blocks:@examplesrc_haskell[:exports both]@{fac 5@}@end exampleHeader arguments for ``Library of Babel'' or function call lines can be set as shown below:@example#+call: factorial(n=5) :exports results@end example@node Specific header arguments, , Using header arguments, Header arguments@subsection Specific header argumentsThe 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* no-expand:: Turn off variable assignment and noweb expansion during tangling* comments:: Toggle insertion of comments in tangled code files* session:: Preserve the state of code evaluation* noweb:: Toggle expansion of noweb references* cache:: Avoid re-evaluating unchanged code blocks* hlines:: Handle horizontal lines in tables* colnames:: Handle column names in tables* rownames:: Handle row names in tables* shebang:: Make tangled files executable* eval:: Limit evaluation of specific code blocks@end menu@node var, results, Specific header arguments, Specific header arguments@subsubsection @code{:var}The @code{:var} header argument is used to pass arguments to code blocks.The specifics of how arguments are included in a code block vary by language;these are addressed in the language-specific documentation. However, thesyntax used to specify arguments is the same across all languages. Thevalues passed to arguments can be literal values, values from org-mode tablesand literal example blocks, or the results of other code blocks.These values can be indexed in a manner similar to arrays---see the``indexable variable values'' heading below.The following syntax is used to pass arguments to code blocks using the@code{:var} header argument.@example:var name=assign@end examplewhere @code{assign} can take one of the following forms@itemize @bullet@item literal valueeither a string @code{"string"} or a number @code{9}.@item referencea table name:@example#+tblname: example-table| 1 || 2 || 3 || 4 |#+source: table-length#+begin_src emacs-lisp :var table=example-table(length table)#+end_src#+results: table-length: 4@end examplea code block name, as assigned by @code{#+srcname:}, followed byparentheses:@example#+begin_src emacs-lisp :var length=table-length()(* 2 length)#+end_src#+results:: 8@end exampleIn addition, an argument can be passed to the code block referencedby @code{:var}. The argument is passed within the parentheses following thecode block name:@example#+source: double#+begin_src emacs-lisp :var input=8(* 2 input)#+end_src#+results: double: 16#+source: squared#+begin_src emacs-lisp :var input=double(input=1)(* input input)#+end_src#+results: squared: 4@end example@end itemize@subsubheading Alternate argument syntaxIt is also possible to specify arguments in a potentially more natural wayusing the @code{#+source:} line of a code block. As in the followingexample arguments can be packed inside of parenthesis, separated by commas,following the source name.@example#+source: double(input=0, x=2)#+begin_src emacs-lisp(* 2 (+ input x))#+end_src@end example@subsubheading Indexable variable valuesIt is possible to reference portions of variable values by ``indexing'' intothe variables. Indexes are 0 based with negative values counting back fromthe end. If an index is separated by @code{,}s then each subsequent sectionwill index into the next deepest nesting or dimension of the value. Thefollowing example assigns the last cell of the first row the table@code{example-table} to the variable @code{data}:@example#+results: example-table| 1 | a || 2 | b || 3 | c || 4 | d |#+begin_src emacs-lisp :var data=example-table[0,-1] data#+end_src#+results:: a@end exampleRanges of variable values can be referenced using two integers separated by a@code{:}, in which case the entire inclusive range is referenced. Forexample the following assigns the middle three rows of @code{example-table}to @code{data}.@example#+results: example-table| 1 | a || 2 | b || 3 | c || 4 | d || 5 | 3 |#+begin_src emacs-lisp :var data=example-table[1:3] data#+end_src#+results:| 2 | b || 3 | c || 4 | d |@end exampleAdditionally, an empty index, or the single character @code{*}, are bothinterpreted to mean the entire range and as such are equivalent to@code{0:-1}, as shown in the following example in which the entire firstcolumn is referenced.@example#+results: example-table| 1 | a || 2 | b || 3 | c || 4 | d |#+begin_src emacs-lisp :var data=example-table[,0] data#+end_src#+results:| 1 | 2 | 3 | 4 |@end exampleIt 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 oneanother by commas, as shown in the following example.@example#+source: 3D#+begin_src emacs-lisp '(((1 2 3) (4 5 6) (7 8 9)) ((10 11 12) (13 14 15) (16 17 18)) ((19 20 21) (22 23 24) (25 26 27)))#+end_src#+begin_src emacs-lisp :var data=3D[1,,1] data#+end_src#+results:| 11 | 14 | 17 |@end example@node results, file, var, Specific header arguments@subsubsection @code{:results}There are three classes of @code{:results} header argument. Only one option ofeach type may be supplied per code block.@itemize @bullet@item@b{collection} header arguments specify how the results should be collectedfrom the code block@item@b{type} header arguments specify what type of result the code block willreturn---which has implications for how they will be inserted into theOrg-mode buffer@item@b{handling} header arguments specify how the results of evaluating the codeblock should be handled.@end itemize@subsubheading CollectionThe following options are mutually exclusive, and specify how the resultsshould be collected from the code block.@itemize @bullet@item @code{value}This is the default. The result is the value of the last statement in thecode block. This header argument places the evaluation in functionalmode. Note that in some languages, e.g., python, use of this result typerequires that a @code{return} statement be included in the body of the sourcecode block. E.g., @code{:results value}.@item @code{output}The result is the collection of everything printed to STDOUT during theexecution of the code block. This header argument places theevaluation in scripting mode. E.g., @code{:results output}.@end itemize@subsubheading TypeThe following options are mutually exclusive and specify what type of resultsthe code block will return. By default, results are inserted as either atable or scalar depending on their value.@itemize @bullet@item @code{table}, @code{vector}The results should be interpreted as an Org-mode table. If a single value isreturned, it will be converted into a table with one row and one column.E.g., @code{:results value table}.@item @code{scalar}, @code{verbatim}The results should be interpreted literally---they will not beconverted into a table. The results will be inserted into the Org-modebuffer as quoted text. E.g., @code{:results value verbatim}.@item @code{file}The results will be interpreted as the path to a file, and will be insertedinto the Org-mode buffer as a file link. E.g., @code{:results value file}.@item @code{raw}, @code{org}The results are interpreted as raw Org-mode code and are inserted directlyinto the buffer. If the results look like a table they will be aligned assuch by Org-mode. E.g., @code{:results value raw}.@item @code{html}Results are assumed to be HTML and will be enclosed in a @code{begin_html}block. E.g., @code{:results value html}.@item @code{latex}Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block.E.g., @code{:results value latex}.@item @code{code}Result are assumed to be parseable code and are enclosed in a code block.E.g., @code{:results value code}.@item @code{pp}The result is converted to pretty-printed code and is enclosed in a codeblock. This option currently supports Emacs Lisp, python, and ruby. E.g.,@code{:results value pp}.@end itemize@subsubheading HandlingThe following results options indicate what happens with theresults once they are collected.@itemize @bullet@item @code{silent}The results will be echoed in the minibuffer but will not be inserted intothe Org-mode buffer. E.g., @code{:results output silent}.@item @code{replace}The default value. Any existing results will be removed, and the new resultswill be inserted into the Org-mode buffer in their place. E.g.,@code{:results output replace}.@item @code{append}If there are pre-existing results of the code block then the new results willbe appended to the existing results. Otherwise the new results will beinserted as with @code{replace}.@item @code{prepend}If there are pre-existing results of the code block then the new results willbe prepended to the existing results. Otherwise the new results will beinserted as with @code{replace}.@end itemize@node file, dir, results, Specific header arguments@subsubsection @code{:file}The header argument @code{:file} is used to specify a path for file output.An Org-mode style @code{file:} link is inserted into the buffer as the result(see @ref{Link format}). Common examples are graphical output from R,gnuplot, ditaa and LaTeX code blocks.Note that for some languages, including R, gnuplot, LaTeX and ditaa,graphical output is sent to the specified file without the file beingreferenced explicitly in the code block. See the documentation for theindividual languages for details. In contrast, general purpose languages suchas python and ruby require that the code explicitly create outputcorresponding to the path indicated by @code{:file}.@node dir, exports, file, Specific header arguments@subsubsection @code{:dir} and remote executionWhile the @code{:file} header argument can be used to specify the path to theoutput file, @code{:dir} specifies the default directory during code blockexecution. If it is absent, then the directory associated with the currentbuffer is used. In other words, supplying @code{:dir path} temporarily hasthe same effect as changing the current directory with @kbd{M-x cd path}, andthen not supplying @code{:dir}. Under the surface, @code{:dir} simply setsthe value of the Emacs variable @code{default-directory}.When using @code{:dir}, you should supply a relative path for file output(e.g. @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in whichcase 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 yourhome directory, you could use@example#+begin_src R :file myplot.png :dir ~/Workmatplot(matrix(rnorm(100), 10), type="l")#+end_src@end example@subsubheading Remote executionA directory on a remote machine can be specified using tramp file syntax, inwhich case the code will be evaluated on the remote machine. An example is@example#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu:plot(1:10, main=system("hostname", intern=TRUE))#+end_src@end exampleText results will be returned to the local Org-mode buffer as usual, and fileoutput will be created on the remote machine with relative paths interpretedrelative to the remote directory. An Org-mode link to the remote file will becreated.So, in the above example a plot will be created on the remote machine,and a link of the following form will be inserted in the org buffer:@example[[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]@end exampleMost of this functionality follows immediately from the fact that @code{:dir}sets the value of the Emacs variable @code{default-directory}, thanks totramp. Those using XEmacs, or GNU Emacs prior to version 23 may need toinstall tramp separately in order for the these features to work correctly.@subsubheading Further points@itemize @bullet@itemIf @code{:dir} is used in conjunction with @code{:session}, although it willdetermine the starting directory for a new session as expected, no attempt iscurrently made to alter the directory associated with an existing session.@item@code{:dir} should typically not be used to create files during export with@code{:exports results} or @code{:exports both}. The reason is that, in orderto retain portability of exported material between machines, during exportlinks inserted into the buffer will *not* be expanded against @code{defaultdirectory}. Therefore, if @code{default-directory} is altered using@code{:dir}, it is probable that the file will be created in a location towhich the link does not point.@end itemize@node exports, tangle, dir, Specific header arguments@subsubsection @code{:exports}The @code{:exports} header argument specifies what should be included in HTMLor LaTeX exports of the Org-mode file.@itemize @bullet@item @code{code}The default. The body of code is included into the exported file. E.g.,@code{:exports code}.@item @code{results}The result of evaluating the code is included in the exported file. E.g.,@code{:exports results}.@item @code{both}Both the code and results are included in the exported file. E.g.,@code{:exports both}.@item @code{none}Nothing is included in the exported file. E.g., @code{:exports none}.@end itemize@node tangle, comments, exports, Specific header arguments@subsubsection @code{:tangle}The @code{:tangle} header argument specifies whether or not the codeblock should be included in tangled extraction of source code files.@itemize @bullet@item @code{yes}The code block is exported to a source code file named after thebasename (name w/o extension) of the Org-mode file. E.g., @code{:tangleyes}.@item @code{no}The default. The code block is not exported to a source code file.E.g., @code{:tangle no}.@item otherAny other string passed to the @code{:tangle} header argument is interpretedas a file basename to which the block will be exported. E.g., @code{:tanglebasename}.@end itemize@node comments, no-expand, tangle, Specific header arguments@subsubsection @code{:comments}By default code blocks are tangled to source-code files without any insertionof comments beyond those which may already exist in the body of the codeblock. The @code{:comments} header argument can be set to ``yes''e.g. @code{:comments yes} to enable the insertion of comments around codeblocks during tangling. The inserted comments contain pointers back to theoriginal Org file from which the comment was tangled.@node no-expand, session, comments, Specific header arguments@subsubsection @code{:no-expand}By default, code blocks are expanded with @code{org-babel-expand-src-block}during tangling. This has the effect of assigning values to variablesspecified with @code{:var} (see @ref{var}), and of replacing ``noweb''references (see @ref{Noweb reference syntax}) with their targets. The@code{:no-expand} header argument can be used to turn off this behavior.@node session, noweb, no-expand, Specific header arguments@subsubsection @code{:session}The @code{:session} header argument starts a session for an interpretedlanguage where state is preserved.By default, a session is not started.A string passed to the @code{:session} header argument will give the sessiona name. This makes it possible to run concurrent sessions for eachinterpreted language.@node noweb, cache, session, Specific header arguments@subsubsection @code{:noweb}The @code{:noweb} header argument controls expansion of ``noweb'' style (see@ref{Noweb reference syntax}) references in a code block. This headerargument can have one of two values: @code{yes} or @code{no}.@itemize @bullet@item @code{no}The default. No ``noweb'' syntax specific action is taken on evaluatingcode blocks, However, noweb references will still be expanded duringtangling.@item @code{yes}All ``noweb'' syntax references in the body of the code block will beexpanded before the block is evaluated.@end itemize@subsubheading Noweb prefix linesNoweb insertions are now placed behind the line prefix of the@code{<<reference>>}.This behavior is illustrated in the following example. Because the@code{<<example>>} noweb reference appears behind the SQL comment syntax,each line of the expanded noweb reference will be commented.This code block:@example-- <<example>>@end exampleexpands to:@example-- this is the-- multi-line body of example@end exampleNote that noweb replacement text that does not contain any newlines will notbe affected by this change, so it is still possible to use inline nowebreferences.@node cache, hlines, noweb, Specific header arguments@subsubsection @code{:cache}The @code{:cache} header argument controls the use of in-buffer caching ofthe results of evaluating code blocks. It can be used to avoid re-evaluatingunchanged code blocks. This header argument can have one of twovalues: @code{yes} or @code{no}.@itemize @bullet@item @code{no}The default. No caching takes place, and the code block will be evaluatedevery time it is called.@item @code{yes}Every time the code block is run a sha1 hash of the code and argumentspassed to the block will be generated. This hash is packed into the@code{#+results:} line and will be checked on subsequentexecutions of the code block. If the code block has notchanged since the last time it was evaluated, it will not be re-evaluated.@end itemize@node hlines, colnames, cache, Specific header arguments@subsubsection @code{:hlines}Tables are frequently represented with one or more horizontal lines, orhlines. The @code{:hlines} argument to a code block accepts thevalues @code{yes} or @code{no}, with a default value of @code{no}.@itemize @bullet@item @code{no}Strips horizontal lines from the input table. In most languages this is thedesired effect because an @code{hline} symbol is interpreted as an unboundvariable and raises an error. Setting @code{:hlines no} or relying on thedefault value yields the following results.@example#+tblname: many-cols| a | b | c ||---+---+---|| d | e | f ||---+---+---|| g | h | i |#+source: echo-table#+begin_src python :var tab=many-cols return tab#+end_src#+results: echo-table| a | b | c || d | e | f || g | h | i |@end example@item @code{yes}Leaves hlines in the table. Setting @code{:hlines yes} has this effect.@example#+tblname: many-cols| a | b | c ||---+---+---|| d | e | f ||---+---+---|| g | h | i |#+source: echo-table#+begin_src python :var tab=many-cols :hlines yes return tab#+end_src#+results: echo-table| a | b | c ||---+---+---|| d | e | f ||---+---+---|| g | h | i |@end example@end itemize@node colnames, rownames, hlines, Specific header arguments@subsubsection @code{:colnames}The @code{:colnames} header argument accepts the values @code{yes},@code{no}, or @code{nil} for unassigned. The default value is @code{nil}.@itemize @bullet@item @code{nil}If an input table looks like it has column names(because its second row is an hline), then the columnnames will be removed from the table beforeprocessing, then reapplied to the results.@example#+tblname: less-cols| a ||---|| b || c |#+srcname: echo-table-again#+begin_src python :var tab=less-cols return [[val + '*' for val in row] for row in tab]#+end_src#+results: echo-table-again| a ||----|| b* || c* |@end example@item @code{no}No column name pre-processing takes place@item @code{yes}Column names are removed and reapplied as with @code{nil} even if the tabledoes not ``look like'' it has column names (i.e. the second row is not anhline)@end itemize@node rownames, shebang, colnames, Specific header arguments@subsubsection @code{:rownames}The @code{:rownames} header argument can take on the values @code{yes}or @code{no}, with a default value of @code{no}.@itemize @bullet@item @code{no}No row name pre-processing will take place.@item @code{yes}The first column of the table is removed from the table before processing,and is then reapplied to the results.@example#+tblname: with-rownames| one | 1 | 2 | 3 | 4 | 5 || two | 6 | 7 | 8 | 9 | 10 |#+srcname: echo-table-once-again#+begin_src python :var tab=with-rownames :rownames yes return [[val + 10 for val in row] for row in tab]#+end_src#+results: echo-table-once-again| one | 11 | 12 | 13 | 14 | 15 || two | 16 | 17 | 18 | 19 | 20 |@end example@end itemize@node shebang, eval, rownames, Specific header arguments@subsubsection @code{:shebang}Setting the @code{:shebang} header argument to a string value(e.g. @code{:shebang "#!/bin/bash"}) causes the string to be inserted as thefirst line of any tangled file holding the code block, and the filepermissions of the tangled file are set to make it executable.@node eval, , shebang, Specific header arguments@subsubsection @code{:eval}The @code{:eval} header argument can be used to limit the evaluation ofspecific code blocks. @code{:eval} accepts two arguments ``never'' and``query''. @code{:eval never} will ensure that a code block is neverevaluated, this can be useful for protecting against the evaluation ofdangerous code blocks. @code{:eval query} will require a query for everyexecution of a code block regardless of the value of the@code{org-confirm-babel-evaluate} variable.@node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code@section Results of evaluation@cindex code block, results of evaluation@cindex source code, results of evaluationThe way in which results are handled depends on whether a session is invoked,as well as on whether @code{:results value} or @code{:results output} isused. The following table shows the possibilities:@multitable @columnfractions 0.26 0.33 0.41@item @tab @b{Non-session} @tab @b{Session}@item @code{:results value} @tab value of last expression @tab value of last expression@item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output@end multitableNote: With @code{:results value}, the result in both @code{:session} andnon-session is returned to Org-mode as a table (a one- or two-dimensionalvector of strings or numbers) when appropriate.@subsection Non-session@subsubsection @code{:results value}This is the default. Internally, the value is obtained by wrapping the codein a function definition in the external language, and evaluating thatfunction. Therefore, code should be written as if it were the body of such afunction. In particular, note that python does not automatically return avalue from a function unless a @code{return} statement is present, and so a@samp{return} statement will usually be required in python.This is the only one of the four evaluation contexts in which the code isautomatically wrapped in a function definition.@subsubsection @code{:results output}The code is passed to the interpreter as an external process, and thecontents of the standard output stream are returned as text. (In certainlanguages this also contains the error output stream; this is an area forfuture work.)@subsection @code{:session}@subsubsection @code{:results value}The code is passed to the interpreter running as an interactive Emacsinferior process. The result returned is the result of the last evaluationperformed by the interpreter. (This is obtained in a language-specificmanner: the value of the variable @code{_} in python and ruby, and the valueof @code{.Last.value} in R).@subsubsection @code{:results output}The code is passed to the interpreter running as an interactive Emacsinferior process. The result returned is the concatenation of the sequence of(text) output from the interactive interpreter. Notice that this is notnecessarily the same as what would be sent to @code{STDOUT} if the same codewere passed to a non-interactive interpreter running as an externalprocess. For example, compare the following two blocks:@example#+begin_src python :results output print "hello" 2 print "bye"#+end_src#+resname:: hello: bye@end exampleIn non-session mode, the '2' is not printed and does not appear.@example#+begin_src python :results output :session print "hello" 2 print "bye"#+end_src#+resname:: hello: 2: bye@end exampleBut in @code{:session} mode, the interactive interpreter receives input '2'and prints out its value, '2'. (Indeed, the other print statements areunnecessary here).@node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code@section Noweb reference syntax@cindex code block, noweb reference@cindex syntax, noweb@cindex source code, noweb referenceThe ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) LiterateProgramming system allows named blocks of code to be referenced by using thefamiliar Noweb syntax:@example<<code-block-name>>@end exampleWhen a code block is tangled or evaluated, whether or not ``noweb''references are expanded depends upon the value of the @code{:noweb} headerargument. If @code{:noweb yes}, then a Noweb reference is expanded beforeevaluation. If @code{:noweb no}, the default, then the reference is notexpanded before evaluation.Note: the default value, @code{:noweb no}, was chosen to ensure thatcorrect code is not broken in a language, such as Ruby, where@code{<<arg>>} is a syntactically valid construct. If @code{<<arg>>} is notsyntactically valid in languages that you use, then please consider settingthe default value.@node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code@section Key bindings and useful functions@cindex code block, key bindingsMany common Org-mode key sequences are re-bound depending onthe context.Within a code block, the following key bindingsare active:@multitable @columnfractions 0.25 0.75@kindex C-c C-c@item @kbd{C-c C-c} @tab org-babel-execute-src-block@kindex C-c C-o@item @kbd{C-c C-o} @tab org-babel-open-src-block-result@kindex C-up@item @kbd{C-@key{up}} @tab org-babel-load-in-session@kindex M-down@item @kbd{M-@key{down}} @tab org-babel-pop-to-session@end multitableIn an Org-mode buffer, the following key bindings are active:@multitable @columnfractions 0.45 0.55@kindex C-c C-v a@kindex C-c C-v C-a@item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab org-babel-sha1-hash@kindex C-c C-v b@kindex C-c C-v C-b@item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab org-babel-execute-buffer@kindex C-c C-v f@kindex C-c C-v C-f@item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab org-babel-tangle-file@kindex C-c C-v g@item @kbd{C-c C-v g} @tab org-babel-goto-named-source-block@kindex C-c C-v h@item @kbd{C-c C-v h} @tab org-babel-describe-bindings@kindex C-c C-v l@kindex C-c C-v C-l@item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab org-babel-lob-ingest@kindex C-c C-v p@kindex C-c C-v C-p@item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab org-babel-expand-src-block@kindex C-c C-v s@kindex C-c C-v C-s@item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab org-babel-execute-subtree@kindex C-c C-v t@kindex C-c C-v C-t@item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab org-babel-tangle@kindex C-c C-v z@kindex C-c C-v C-z@item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab org-babel-switch-to-session@end multitable@c When possible these keybindings were extended to work when the control key is@c kept pressed, resulting in the following additional keybindings.@c @multitable @columnfractions 0.25 0.75@c @item @kbd{C-c C-v C-a} @tab org-babel-sha1-hash@c @item @kbd{C-c C-v C-b} @tab org-babel-execute-buffer@c @item @kbd{C-c C-v C-f} @tab org-babel-tangle-file@c @item @kbd{C-c C-v C-l} @tab org-babel-lob-ingest@c @item @kbd{C-c C-v C-p} @tab org-babel-expand-src-block@c @item @kbd{C-c C-v C-s} @tab org-babel-execute-subtree@c @item @kbd{C-c C-v C-t} @tab org-babel-tangle@c @item @kbd{C-c C-v C-z} @tab org-babel-switch-to-session@c @end multitable@node Batch execution, , Key bindings and useful functions, Working With Source Code@section Batch execution@cindex code block, batch execution@cindex source code, batch executionIt is possible to call functions from the command line. This shellscript calls @code{org-babel-tangle} on every one of its arguments.Be sure to adjust the paths to fit your system.@example#!/bin/sh# -*- mode: shell-script -*-## tangle a file with org-mode#DIR=`pwd`FILES=""# wrap each argument in the code required to call tangle on itfor i in $@@; doFILES="$FILES \"$i\""doneemacsclient \--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)))"@end example@node Miscellaneous, Hacking, Working With Source Code, Top@chapter Miscellaneous@menu* Completion:: M-TAB knows what you need* Speed keys:: Electric commands at the beginning of a headline* Code evaluation security:: Org mode files evaluate inline code* Customization:: Adapting Org to your taste* In-buffer settings:: Overview of the #+KEYWORDS* The very busy C-c C-c key:: When in doubt, press C-c C-c* Clean view:: Getting rid of leading stars in the outline* TTY keys:: Using Org on a tty* Interaction:: Other Emacs packages@end menu@node Completion, Speed keys, Miscellaneous, Miscellaneous@section Completion@cindex completion, of @TeX{} symbols@cindex completion, of TODO keywords@cindex completion, of dictionary words@cindex completion, of option keywords@cindex completion, of tags@cindex completion, of property keys@cindex completion, of link abbreviations@cindex @TeX{} symbol completion@cindex TODO keywords completion@cindex dictionary word completion@cindex option keyword completion@cindex tag completion@cindex link abbreviations, completion ofEmacs would not be Emacs without completion, and Org-mode uses it whenever itmakes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface forsome of the completion prompts, you can specify your preference by setting atmost one of the variables @code{org-completion-use-iswitchb}@code{org-completion-use-ido}.Org supports in-buffer completion. This type of completion doesnot make use of the minibuffer. You simply type a few letters intothe buffer and use the key to complete text right there.@table @kbd@kindex M-@key{TAB}@item M-@key{TAB}Complete word at point@itemize @bullet@itemAt the beginning of a headline, complete TODO keywords.@itemAfter @samp{\}, complete @TeX{} symbols supported by the exporter.@itemAfter @samp{*}, complete headlines in the current buffer so that theycan be used in search links like @samp{[[*find this headline]]}.@itemAfter @samp{:} in a headline, complete tags. The list of tags is takenfrom the variable @code{org-tag-alist} (possibly set through the@samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is createddynamically from all tags used in the current buffer.@itemAfter @samp{:} and not in a headline, complete property keys. The listof keys is constructed dynamically from all keys used in the currentbuffer.@itemAfter @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).@itemAfter @samp{#+}, complete the special keywords like @samp{TYP_TODO} or@samp{OPTIONS} which set file-specific options for Org-mode. When theoption keyword is already complete, pressing @kbd{M-@key{TAB}} againwill insert example settings for this keyword.@itemIn the line after @samp{#+STARTUP: }, complete startup keywords,i.e. valid keys for this line.@itemElsewhere, complete dictionary words using Ispell.@end itemize@end table@node Speed keys, Code evaluation security, Completion, Miscellaneous@section Speed keys@cindex speed keys@vindex org-use-speed-commands@vindex org-speed-commands-userSingle keys can be made to execute commands when the cursor is at thebeginning of a headline, i.e. before the first star. Configure the variable@code{org-use-speed-commands} to activate this feature. There is apre-defined list of commands, and you can add more such commands using thevariable @code{org-speed-commands-user}. Speed keys do not only speed upnavigation and other commands, but they also provide an alternative way toexecute commands bound to keys that are not or not easily available on a tty,or on a small mobile device with a limited keyboard.To see which commands are available, activate the feature and press @kbd{?}with the cursor at the beginning of a headline.@node Code evaluation security, Customization, Speed keys, Miscellaneous@section Code evaluation and security issuesOrg provides tool to work with the code snippets, including evaluating them.Running code on your machine always comes with a security risk. Badlywritten or malicious code can be executed on purpose or by accident. Org hasdefault settings which will only evaluate such code if you give explicitpermission to do so, and as a casual user of these features you should leavethese precautions intact.For people who regularly work with such code, the confirmation prompts canbecome annoying, and you might want to turn them off. This can be done, butyou must be aware of the risks that are involved.Code evaluation can happen under the following circumstances:@table @i@item Source code blocksSource code blocks can be evaluated during export, or when pressing @kbd{C-cC-c} in the block. The most important thing to realize here is that Org modefiles which contain code snippets are in a certain sense like executablefiles. So you should accept them and load them into Emacs only from trustedsources - just like you would do with a program you install on your computer.Make sure you know what you are doing before customizing the variableswhich take of the default security brakes.@defopt org-confirm-babel-evaluateWhen set to t user is queried before code block evaluation@end defopt@item Following @code{shell} and @code{elisp} linksOrg has two link types that can directly evaluate code (@pxref{Externallinks}). These links can be problematic because the code to be evaluated hisnot visible.@defopt org-confirm-shell-link-functionFunction to queries user about shell link execution.@end defopt@defopt org-confirm-elisp-link-functionFunctions to query user for Emacs Lisp link execution.@end defopt@item Following @code{shell} and @code{elisp} linksOrg has two link types that can directly evaluate code (@pxref{Externallinks}). These links can be problematic because the code to be evaluated hisnot visible. @b{Security advice:} Do not use these links, use source codeblocks which make the associated actions much more transparent.@item Formulas in tablesFormulas in tables (@pxref{The spreadsheet}) are code that is evaluatedeither by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter.@end table@node Customization, In-buffer settings, Code evaluation security, Miscellaneous@section Customization@cindex customization@cindex options, for customization@cindex variables, for customizationThere are more than 180 variables that can be used to customizeOrg. For the sake of compactness of the manual, I am notdescribing the variables here. A structured overview of customizationvariables is available with @kbd{M-x org-customize}. Or select@code{Browse Org Group} from the @code{Org->Customization} menu. Manysettings can also be activated on a per-file basis, by putting speciallines into the buffer (@pxref{In-buffer settings}).@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous@section Summary of in-buffer settings@cindex in-buffer settings@cindex special keywordsOrg-mode uses special lines in the buffer to define settings on aper-file basis. These lines start with a @samp{#+} followed by akeyword, a colon, and then individual words defining a setting. Severalsetting words can be in the same line, but you can also have multiplelines for the keyword. While these settings are described throughoutthe manual, here is a summary. After changing any of those lines in thebuffer, press @kbd{C-c C-c} with the cursor still in the line toactivate the changes immediately. Otherwise they become effective onlywhen the file is visited again in a new Emacs session.@vindex org-archive-location@table @kbd@item #+ARCHIVE: %s_done::This line sets the archive location for the agenda file. It applies forall subsequent lines until the next @samp{#+ARCHIVE} line, or the endof the file. The first such line also applies to any entries before it.The corresponding variable is @code{org-archive-location}.@item #+CATEGORY:This line sets the category for the agenda file. The category appliesfor all subsequent lines until the next @samp{#+CATEGORY} line, or theend of the file. The first such line also applies to any entries before it.@item #+COLUMNS: %25ITEM .....@cindex property, COLUMNSSet the default format for columns view. This format applies whencolumns view is invoked in locations where no @code{COLUMNS} propertyapplies.@item #+CONSTANTS: name1=value1 ...@vindex org-table-formula-constants@vindex org-table-formulaSet file-local values for constants to be used in table formulas. Thisline set the local variable @code{org-table-formula-constants-local}.The global version of this variable is@code{org-table-formula-constants}.@item #+FILETAGS: :tag1:tag2:tag3:Set tags that can be inherited by any entry in the file, including thetop-level entries.@item #+DRAWERS: NAME1 .....@vindex org-drawersSet the file-local set of drawers. The corresponding global variable is@code{org-drawers}.@item #+LINK: linkword replace@vindex org-link-abbrev-alistThese lines (several are allowed) specify link abbreviations.@xref{Link abbreviations}. The corresponding variable is@code{org-link-abbrev-alist}.@item #+PRIORITIES: highest lowest default@vindex org-highest-priority@vindex org-lowest-priority@vindex org-default-priorityThis line sets the limits and the default for the priorities. All threemust be either letters A-Z or numbers 0-9. The highest priority musthave a lower ASCII number that the lowest priority.@item #+PROPERTY: Property_Name ValueThis line sets a default inheritance value for entries in the currentbuffer, most useful for specifying the allowed values of a property.@cindex #+SETUPFILE@item #+SETUPFILE: fileThis line defines a file that holds more in-buffer setup. Normally this isentirely ignored. Only when the buffer is parsed for option-setting lines(i.e. when starting Org-mode for a file, when pressing @kbd{C-c C-c} in asettings line, or when exporting), then the contents of this file are parsedas if they had been included in the buffer. In particular, the file can beany other Org-mode file with internal setup. You can visit the file thecursor is in the line with @kbd{C-c '}.@item #+STARTUP:@cindex #+STARTUP:This line sets options to be used at startup of Org-mode, when anOrg file is being visited.The first set of options deals with the initial visibility of the outlinetree. The corresponding variable for global default settings is@code{org-startup-folded}, with a default value @code{t}, which means@code{overview}.@vindex org-startup-folded@cindex @code{overview}, STARTUP keyword@cindex @code{content}, STARTUP keyword@cindex @code{showall}, STARTUP keyword@cindex @code{showeverything}, STARTUP keyword@exampleoverview @r{top-level headlines only}content @r{all headlines}showall @r{no folding of any entries}showeverything @r{show even drawer contents}@end example@vindex org-startup-indented@cindex @code{indent}, STARTUP keyword@cindex @code{noindent}, STARTUP keywordDynamic virtual indentation is controlled by the variable@code{org-startup-indented}@footnote{Emacs 23 and Org-mode 6.29 are required}@exampleindent @r{start with @code{org-indent-mode} turned on}noindent @r{start with @code{org-indent-mode} turned off}@end example@vindex org-startup-align-all-tablesThen there are options for aligning tables upon visiting a file. Thisis useful in files containing narrowed table columns. The correspondingvariable is @code{org-startup-align-all-tables}, with a default value@code{nil}.@cindex @code{align}, STARTUP keyword@cindex @code{noalign}, STARTUP keyword@examplealign @r{align all tables}noalign @r{don't align tables on startup}@end example@vindex org-log-done@vindex org-log-note-clock-out@vindex org-log-repeatLogging the closing and reopening of TODO items and clock intervals can beconfigured using these options (see variables @code{org-log-done},@code{org-log-note-clock-out} and @code{org-log-repeat})@cindex @code{logdone}, STARTUP keyword@cindex @code{lognotedone}, STARTUP keyword@cindex @code{nologdone}, STARTUP keyword@cindex @code{lognoteclock-out}, STARTUP keyword@cindex @code{nolognoteclock-out}, STARTUP keyword@cindex @code{logrepeat}, STARTUP keyword@cindex @code{lognoterepeat}, STARTUP keyword@cindex @code{nologrepeat}, STARTUP keyword@cindex @code{logreschedule}, STARTUP keyword@cindex @code{lognotereschedule}, STARTUP keyword@cindex @code{nologreschedule}, STARTUP keyword@cindex @code{logredeadline}, STARTUP keyword@cindex @code{lognoteredeadline}, STARTUP keyword@cindex @code{nologredeadline}, STARTUP keyword@cindex @code{logrefile}, STARTUP keyword@cindex @code{lognoterefile}, STARTUP keyword@cindex @code{nologrefile}, STARTUP keyword@examplelogdone @r{record a timestamp when an item is marked DONE}lognotedone @r{record timestamp and a note when DONE}nologdone @r{don't record when items are marked DONE}logrepeat @r{record a time when reinstating a repeating item}lognoterepeat @r{record a note when reinstating a repeating item}nologrepeat @r{do not record when reinstating repeating item}lognoteclock-out @r{record a note when clocking out}nolognoteclock-out @r{don't record a note when clocking out}logreschedule @r{record a timestamp when scheduling time changes}lognotereschedule @r{record a note when scheduling time changes}nologreschedule @r{do not record when a scheduling date changes}logredeadline @r{record a timestamp when deadline changes}lognoteredeadline @r{record a note when deadline changes}nologredeadline @r{do not record when a deadline date changes}logrefile @r{record a timestamp when refiling}lognoterefile @r{record a note when refiling}nologrefile @r{do not record when refiling}@end example@vindex org-hide-leading-stars@vindex org-odd-levels-onlyHere are the options for hiding leading stars in outline headings, and forindenting outlines. The corresponding variables are@code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with adefault setting @code{nil} (meaning @code{showstars} and @code{oddeven}).@cindex @code{hidestars}, STARTUP keyword@cindex @code{showstars}, STARTUP keyword@cindex @code{odd}, STARTUP keyword@cindex @code{even}, STARTUP keyword@examplehidestars @r{make all but one of the stars starting a headline invisible.}showstars @r{show all stars starting a headline}indent @r{virtual indentation according to outline level}noindent @r{no virtual indentation according to outline level}odd @r{allow only odd outline levels (1,3,...)}oddeven @r{allow all outline levels}@end example@vindex org-put-time-stamp-overlays@vindex org-time-stamp-overlay-formatsTo turn on custom format overlays over timestamps (variables@code{org-put-time-stamp-overlays} and@code{org-time-stamp-overlay-formats}), use@cindex @code{customtime}, STARTUP keyword@examplecustomtime @r{overlay custom time format}@end example@vindex constants-unit-systemThe following options influence the table spreadsheet (variable@code{constants-unit-system}).@cindex @code{constcgs}, STARTUP keyword@cindex @code{constSI}, STARTUP keyword@exampleconstcgs @r{@file{constants.el} should use the c-g-s unit system}constSI @r{@file{constants.el} should use the SI unit system}@end example@vindex org-footnote-define-inline@vindex org-footnote-auto-label@vindex org-footnote-auto-adjustTo influence footnote settings, use the following keywords. Thecorresponding variables are @code{org-footnote-define-inline},@code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.@cindex @code{fninline}, STARTUP keyword@cindex @code{nofninline}, STARTUP keyword@cindex @code{fnlocal}, STARTUP keyword@cindex @code{fnprompt}, STARTUP keyword@cindex @code{fnauto}, STARTUP keyword@cindex @code{fnconfirm}, STARTUP keyword@cindex @code{fnplain}, STARTUP keyword@cindex @code{fnadjust}, STARTUP keyword@cindex @code{nofnadjust}, STARTUP keyword@examplefninline @r{define footnotes inline}fnnoinline @r{define footnotes in separate section}fnlocal @r{define footnotes near first reference, but not inline}fnprompt @r{prompt for footnote labels}fnauto @r{create [fn:1]-like labels automatically (default)}fnconfirm @r{offer automatic label for editing or confirmation}fnplain @r{create [1]-like labels automatically}fnadjust @r{automatically renumber and sort footnotes}nofnadjust @r{do not renumber and sort automatically}@end example@cindex org-hide-block-startupTo hide blocks on startup, use these keywords. The corresponding variable is@code{org-hide-block-startup}.@cindex @code{hideblocks}, STARTUP keyword@cindex @code{nohideblocks}, STARTUP keyword@examplehideblocks @r{Hide all begin/end blocks on startup}nohideblocks @r{Do not hide blocks on startup}@end example@cindex org-pretty-entitiesThe the display of entities as UTF8 characters is governed by the variable@code{org-pretty-entities} and the keywords@cindex @code{entitiespretty}, STARTUP keyword@cindex @code{entitiesplain}, STARTUP keyword@exampleentitiespretty @r{Show entities as UTF8 characters where possible}entitiesplain @r{Leave entities plain}@end example@item #+TAGS: TAG1(c1) TAG2(c2)@vindex org-tag-alistThese lines (several such lines are allowed) specify the valid tags inthis file, and (potentially) the corresponding @emph{fast tag selection}keys. The corresponding variable is @code{org-tag-alist}.@item #+TBLFM:This line contains the formulas for the table directly above the line.@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,@itemx #+OPTIONS:, #+BIND:, #+XSLT:,@itemx #+DESCRIPTION:, #+KEYWORDS:,@itemx #+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,@itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:These lines provide settings for exporting files. For more details see@ref{Export options}.@item #+TODO: #+SEQ_TODO: #+TYP_TODO:@vindex org-todo-keywordsThese lines set the TODO keywords and their interpretation in thecurrent file. The corresponding variable is @code{org-todo-keywords}.@end table@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous@section The very busy C-c C-c key@kindex C-c C-c@cindex C-c C-c, overviewThe key @kbd{C-c C-c} has many purposes in Org, which are allmentioned scattered throughout this manual. One specific function ofthis key is to add @emph{tags} to a headline (@pxref{Tags}). In manyother circumstances it means something like @emph{``Hey Org, lookhere and update according to what you see here''}. Here is a summary ofwhat this means in different contexts.@itemize @minus@itemIf there are highlights in the buffer from the creation of a sparsetree, or from clock display, remove these highlights.@itemIf the cursor is in one of the special @code{#+KEYWORD} lines, thistriggers scanning the buffer for these lines and updating theinformation.@itemIf the cursor is inside a table, realign the table. This commandworks even if the automatic table editor has been turned off.@itemIf the cursor is on a @code{#+TBLFM} line, re-apply the formulas tothe entire table.@itemIf the current buffer is a capture buffer, close the note and file it.With a prefix argument, file it, without further interaction, to thedefault location.@itemIf the cursor is on a @code{<<<target>>>}, update radio targets andcorresponding links in this buffer.@itemIf the cursor is in a property line or at the start or end of a propertydrawer, offer property commands.@itemIf the cursor is at a footnote reference, go to the correspondingdefinition, and vice versa.@itemIf the cursor is on a statistics cookie, update it.@itemIf the cursor is in a plain list item with a checkbox, toggle the statusof the checkbox.@itemIf the cursor is on a numbered item in a plain list, renumber theordered list.@itemIf the cursor is on the @code{#+BEGIN} line of a dynamic block, theblock is updated.@end itemize@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous@section A cleaner outline view@cindex hiding leading stars@cindex dynamic indentation@cindex odd-levels-only outlines@cindex clean outline viewSome people find it noisy and distracting that the Org headlines start with apotentially large number of stars, and that text below the headlines is notindented. While this is no problem when writing a @emph{book-like} documentwhere the outline headings are really section headings, in a more@emph{list-oriented} outline, indented structure is a lot cleaner:@example@group* Top level headline | * Top level headline** Second level | * Second level*** 3rd level | * 3rd levelsome text | some text*** 3rd level | * 3rd levelmore text | more text* Another top level headline | * Another top level headline@end group@end example@noindentIf you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crashwith @code{org-indent-mode}} and version 6.29 of Org, this kind of view canbe achieved dynamically at display time using @code{org-indent-mode}. Inthis minor mode, all lines are prefixed for display with the necessary amountof space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix}property, such that @code{visual-line-mode} (or purely setting@code{word-wrap}) wraps long lines (including headlines) correctly indented.}. Also headlines are prefixed with additional stars, so that the amount ofindentation shifts by two@footnote{See the variable@code{org-indent-indentation-per-level}.} spaces per level. All headlinestars but the last one are made invisible using the @code{org-hide}face@footnote{Turning on @code{org-indent-mode} sets@code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to@code{nil}.} - see below under @samp{2.} for more information on how thisworks. You can turn on @code{org-indent-mode} for all files by customizingthe variable @code{org-startup-indented}, or you can turn it on forindividual files using@example#+STARTUP: indent@end exampleIf you want a similar effect in earlier version of Emacs and/or Org, or ifyou want the indentation to be hard space characters so that the plain textfile looks as similar as possible to the Emacs display, Org supports you inthe following way:@enumerate@item@emph{Indentation of text below headlines}@*You may indent text below each headline to make the left boundary line upwith the headline, like@example*** 3rd level more text, now indented@end example@vindex org-adapt-indentationOrg supports this with paragraph filling, line wrapping, and structureediting@footnote{See also the variable @code{org-adapt-indentation}.},preserving or adapting the indentation as appropriate.@item@vindex org-hide-leading-stars@emph{Hiding leading stars}@* You can modify the display in such a way thatall leading stars become invisible. To do this in a global way, configurethe variable @code{org-hide-leading-stars} or change this on a per-file basiswith@example#+STARTUP: hidestars#+STARTUP: showstars@end exampleWith hidden stars, the tree becomes:@example@group* Top level headline * Second level * 3rd level ...@end group@end example@noindent@vindex org-hide @r{(face)}The leading stars are not truly replaced by whitespace, they are onlyfontified with the face @code{org-hide} that uses the background color asfont color. If you are not using either white or black background, you mayhave to customize this face to get the wanted effect. Another possibility isto set this font such that the extra stars are @i{almost} invisible, forexample using the color @code{grey90} on a white background.@item@vindex org-odd-levels-onlyThings become cleaner still if you skip all the even levels and use only oddlevels 1, 3, 5..., effectively adding two stars to go from one outline levelto the next@footnote{When you need to specify a level for a property searchor refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc@.}. In thisway we get the outline view shown at the beginning of this section. In orderto make the structure editing and export commands handle this conventioncorrectly, configure the variable @code{org-odd-levels-only}, or set this ona per-file basis with one of the following lines:@example#+STARTUP: odd#+STARTUP: oddeven@end exampleYou can convert an Org file from single-star-per-level to thedouble-star-per-level convention with @kbd{M-x org-convert-to-odd-levelsRET} in that file. The reverse operation is @kbd{M-xorg-convert-to-oddeven-levels}.@end enumerate@node TTY keys, Interaction, Clean view, Miscellaneous@section Using Org on a tty@cindex tty key bindingsBecause Org contains a large number of commands, by default many ofOrg's core commands are bound to keys that are generally notaccessible on a tty, such as the cursor keys (@key{left}, @key{right},@key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when usedtogether with modifiers like @key{Meta} and/or @key{Shift}. To accessthese commands on a tty when special keys are unavailable, the followingalternative bindings can be used. The tty bindings below will likely bemore cumbersome; you may find for some of the bindings below that acustomized workaround suits you better. For example, changing a timestampis really only fun with @kbd{S-@key{cursor}} keys, whereas on atty you would rather use @kbd{C-c .} to re-insert the timestamp.@multitable @columnfractions 0.15 0.2 0.1 0.2@item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab@item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab@item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab@item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab@item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}@item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab@item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab@item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab@item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab@item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab@item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab@end multitable@node Interaction, , TTY keys, Miscellaneous@section Interaction with other packages@cindex packages, interaction with otherOrg lives in the world of GNU Emacs and interacts in various wayswith other code out there.@menu* Cooperation:: Packages Org cooperates with* Conflicts:: Packages that lead to conflicts@end menu@node Cooperation, Conflicts, Interaction, Interaction@subsection Packages that Org cooperates with@table @asis@cindex @file{calc.el}@cindex Gillespie, Dave@item @file{calc.el} by Dave GillespieOrg uses the Calc package for implementing spreadsheetfunctionality in its tables (@pxref{The spreadsheet}). Orgchecks for the availability of Calc by looking for the function@code{calc-eval} which will have been autoloaded during setup if Calc hasbeen installed properly. As of Emacs 22, Calc is part of the Emacsdistribution. Another possibility for interaction between the twopackages is using Calc for embedded calculations. @xref{Embedded Mode,, Embedded Mode, Calc, GNU Emacs Calc Manual}.@item @file{constants.el} by Carsten Dominik@cindex @file{constants.el}@cindex Dominik, Carsten@vindex org-table-formula-constantsIn a table formula (@pxref{The spreadsheet}), it is possible to usenames for natural constants or units. Instead of defining your ownconstants in the variable @code{org-table-formula-constants}, installthe @file{constants} package which defines a large number of constantsand units, and lets you use unit prefixes like @samp{M} for@samp{Mega}, etc@. You will need version 2.0 of this package, availableat @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks forthe function @code{constants-get}, which has to be autoloaded in yoursetup. See the installation instructions in the file@file{constants.el}.@item @file{cdlatex.el} by Carsten Dominik@cindex @file{cdlatex.el}@cindex Dominik, CarstenOrg-mode can make use of the CDLa@TeX{} package to efficiently enterLa@TeX{} fragments into Org files. See @ref{CDLaTeX mode}.@item @file{imenu.el} by Ake Stenhoff and Lars Lindberg@cindex @file{imenu.el}Imenu allows menu access to an index of items in a file. Org-modesupports Imenu---all you need to do to get the index is the following:@lisp(add-hook 'org-mode-hook (lambda () (imenu-add-to-menubar "Imenu")))@end lisp@vindex org-imenu-depthBy default the index is two levels deep---you can modify the depth usingthe option @code{org-imenu-depth}.@item @file{remember.el} by John Wiegley@cindex @file{remember.el}@cindex Wiegley, JohnOrg used to use this package for capture, but no longer does.@item @file{speedbar.el} by Eric M. Ludlam@cindex @file{speedbar.el}@cindex Ludlam, Eric M.Speedbar is a package that creates a special frame displaying files andindex items in files. Org-mode supports Speedbar and allows you todrill into Org files directly from the Speedbar. It also allows you torestrict the scope of agenda commands to a file or a subtree by usingthe command @kbd{<} in the Speedbar frame.@cindex @file{table.el}@item @file{table.el} by Takaaki Ota@kindex C-c C-c@cindex table editor, @file{table.el}@cindex @file{table.el}@cindex Ota, TakaakiComplex ASCII tables with automatic line wrapping, column- and row-spanning,and alignment can be created using the Emacs table package by Takaaki Ota(@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22).Org-mode will recognize these tables and export them properly. Because ofinterference with other Org-mode functionality, you unfortunately cannot editthese tables directly in the buffer. Instead, you need to use the command@kbd{C-c '} to edit them, similar to source code snippets.@table @kbd@kindex C-c '@item C-c 'Edit a @file{table.el} table. Works when the cursor is in a table.el table.@c@kindex C-c ~@item C-c ~Insert a @file{table.el} table. If there is already a table at point, thiscommand converts it between the @file{table.el} format and the Org-modeformat. See the documentation string of the command@code{org-convert-table} for the restrictions under which this ispossible.@end table@file{table.el} is part of Emacs since Emacs 22.@item @file{footnote.el} by Steven L. Baur@cindex @file{footnote.el}@cindex Baur, Steven L.Org-mode recognizes numerical footnotes as provided by this package.However, Org-mode also has its own footnote support (@pxref{Footnotes}),which makes using @file{footnote.el} unnecessary.@end table@node Conflicts, , Cooperation, Interaction@subsection Packages that lead to conflicts with Org-mode@table @asis@cindex @code{shift-selection-mode}@vindex org-support-shift-selectIn Emacs 23, @code{shift-selection-mode} is on by default, meaning thatcursor motions combined with the shift key should start or enlarge regions.This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to changetimestamps, TODO keywords, priorities, and item bullet types if the cursor isat such a location. By default, @kbd{S-@key{cursor}} commands outsidespecial contexts don't do anything, but you can customize the variable@code{org-support-shift-select}. Org-mode then tries to accommodate shiftselection by (i) using it outside of the special contexts where specialcommands apply, and by (ii) extending an existing active region even if thecursor moves across a special context.@item @file{CUA.el} by Kim. F. Storm@cindex @file{CUA.el}@cindex Storm, Kim. F.@vindex org-replace-disputed-keysKey bindings in Org conflict with the @kbd{S-<cursor>} keys used by CUA mode(as well as @code{pc-select-mode} and @code{s-region-mode}) to select and extend theregion. In fact, Emacs 23 has this built-in in the form of@code{shift-selection-mode}, see previous paragraph. If you are using Emacs23, 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 inOrg-mode, configure the variable @code{org-replace-disputed-keys}. When set,Org will move the following key bindings in Org files, and in the agendabuffer (but not during date selection).@exampleS-UP -> M-p S-DOWN -> M-nS-LEFT -> M-- S-RIGHT -> M-+C-S-LEFT -> M-S-- C-S-RIGHT -> M-S-+@end example@vindex org-disputed-keysYes, these are unfortunately more difficult to remember. If you wantto have other replacement keys, look at the variable@code{org-disputed-keys}.@item @file{yasnippet.el}@cindex @file{yasnippet.el}The way Org-mode binds the TAB key (binding to @code{[tab]} instead of@code{"\t"}) overrules yasnippets' access to this key. The following codefixed this problem:@lisp(add-hook 'org-mode-hook (lambda () (org-set-local 'yas/trigger-key [tab]) (define-key yas/keymap [tab] 'yas/next-field-group)))@end lisp@item @file{windmove.el} by Hovav Shacham@cindex @file{windmove.el}This package also uses the @kbd{S-<cursor>} keys, so everything writtenin the paragraph above about CUA mode also applies here. If you want makethe windmove function active in locations where Org-mode does not havespecial functionality on @kbd{S-@key{cursor}}, add this to yourconfiguration:@lisp;; Make windmove work in org-mode:(add-hook 'org-shiftup-final-hook 'windmove-up)(add-hook 'org-shiftleft-final-hook 'windmove-left)(add-hook 'org-shiftdown-final-hook 'windmove-down)(add-hook 'org-shiftright-final-hook 'windmove-right)@end lisp@item @file{viper.el} by Michael Kifer@cindex @file{viper.el}@kindex C-c /Viper uses @kbd{C-c /} and therefore makes this key not access thecorresponding Org-mode command @code{org-sparse-tree}. You need to findanother key for this command, or override the key in@code{viper-vi-global-user-map} with@lisp(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)@end lisp@end table@node Hacking, MobileOrg, Miscellaneous, Top@appendix Hacking@cindex hackingThis appendix covers some aspects where users can extend the functionality ofOrg.@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 La@TeX{} and other programs* Dynamic blocks:: Automatically filled blocks* Special agenda views:: Customized views* Extracting agenda information:: Postprocessing of agenda information* Using the property API:: Writing programs that use entry properties* Using the mapping API:: Mapping over all or selected entries@end menu@node Hooks, Add-on packages, Hacking, Hacking@section Hooks@cindex hooksOrg has a large number of hook variables that can be used to addfunctionality. This appendix about hacking is going to illustrate theuse of some of them. A complete list of all hooks with documentation ismaintained by the Worg project and can be found at@uref{http://orgmode.org/worg/org-configs/org-hooks.php}.@node Add-on packages, Adding hyperlink types, Hooks, Hacking@section Add-on packages@cindex add-on packagesA large number of add-on packages have been written by various authors.These packages are not part of Emacs, but they are distributed as contributedpackages with the separate release available at the Org-mode home page at@uref{http://orgmode.org}. The list of contributed packages, along withdocumentation about each package, is maintained by the Worg project at@uref{http://orgmode.org/worg/org-contrib/}.@node Adding hyperlink types, Context-sensitive commands, Add-on packages, Hacking@section Adding hyperlink types@cindex hyperlinks, adding new typesOrg has a large number of hyperlink types built-in(@pxref{Hyperlinks}). If you would like to add new link types, Orgprovides an interface for doing so. Let's look at an example file,@file{org-man.el}, that will add support for creating links like@samp{[[man:printf][The printf manpage]]} to show Unix manual pages insideEmacs:@lisp;;; org-man.el - Support for links to manpages in Org(require 'org)(org-add-link-type "man" 'org-man-open)(add-hook 'org-store-link-functions 'org-man-store-link)(defcustom org-man-command 'man "The Emacs command to be used to display a man page." :group 'org-link :type '(choice (const man) (const woman)))(defun org-man-open (path) "Visit the manpage on PATH.PATH should be a topic that can be thrown at the man command." (funcall org-man-command path))(defun org-man-store-link () "Store a link to a manpage." (when (memq major-mode '(Man-mode woman-mode)) ;; This is a man page, we do make this link (let* ((page (org-man-get-page-name)) (link (concat "man:" page)) (description (format "Manpage for %s" page))) (org-store-link-props :type "man" :link link :description description))))(defun org-man-get-page-name () "Extract the page name from the buffer name." ;; This works for both `Man-mode' and `woman-mode'. (if (string-match " \\(\\S-+\\)\\*" (buffer-name)) (match-string 1 (buffer-name)) (error "Cannot create link to this man page")))(provide 'org-man);;; org-man.el ends here@end lisp@noindentYou would activate this new link type in @file{.emacs} with@lisp(require 'org-man)@end lisp@noindentLet's go through the file and see what it does.@enumerate@itemIt does @code{(require 'org)} to make sure that @file{org.el} has beenloaded.@itemThe next line calls @code{org-add-link-type} to define a new link typewith prefix @samp{man}. The call also contains the name of a functionthat will be called to follow such a link.@item@vindex org-store-link-functionsThe next line adds a function to @code{org-store-link-functions}, inorder to allow the command @kbd{C-c l} to record a useful link in abuffer displaying a man page.@end enumerateThe rest of the file defines the necessary variables and functions.First there is a customization variable that determines which Emacscommand should be used to display man pages. There are two options,@code{man} and @code{woman}. Then the function to follow a link isdefined. It gets the link path as an argument---in this case the linkpath is just a topic for the manual command. The function calls thevalue of @code{org-man-command} to display the man page.Finally the function @code{org-man-store-link} is defined. When you tryto store a link with @kbd{C-c l}, this function will be called totry to make a link. The function must first decide if it is supposed tocreate the link for this buffer type; we do this by checking the valueof the variable @code{major-mode}. If not, the function must exit andreturn the value @code{nil}. If yes, the link is created by getting themanual topic from the buffer name and prefixing it with the string@samp{man:}. Then it must call the command @code{org-store-link-props}and set the @code{:type} and @code{:link} properties. Optionally youcan also set the @code{:description} property to provide a default forthe link description when the link is later inserted into an Orgbuffer with @kbd{C-c C-l}.When is makes sense for your new link type, you may also define a function@code{org-PREFIX-complete-link} that implements special (e.g. completion)support for inserting such a link with @kbd{C-c C-l}. Such a function shouldnot accept any arguments, and return the full link with prefix.@node Context-sensitive commands, Tables in arbitrary syntax, Adding hyperlink types, Hacking@section Context-sensitive commands@cindex context-sensitive commands, hooks@cindex add-ons, context-sensitive commands@vindex org-ctrl-c-ctrl-c-hookOrg has several commands that act differently depending on context. The mostimportant example it the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property.Add-ons can tap into this functionality by providing a function that detectsspecial context for that add-on and executes functionality appropriate forthe context. Here is an example from Dan Davison's @file{org-R.el} whichallows you to evaluate commands based on the @file{R} programming language. Forthis package, special contexts are lines that start with @code{#+R:} or@code{#+RR:}.@lisp(defun org-R-apply-maybe () "Detect if this is context for org-R and execute R commands." (if (save-excursion (beginning-of-line 1) (looking-at "#\\+RR?:")) (progn (call-interactively 'org-R-apply) t) ;; to signal that we took action nil)) ;; to signal that we did not(add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe)@end lispThe function first checks if the cursor is in such a line. If that is thecase, @code{org-R-apply} is called and the function returns @code{t} tosignal that action was taken, and @kbd{C-c C-c} will stop looking for othercontexts. If the function finds it should do nothing locally, it returns @code{nil} so that other, similar functions can have a try.@node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking@section Tables and lists in arbitrary syntax@cindex tables, in other modes@cindex lists, in other modes@cindex Orgtbl modeSince Orgtbl mode can be used as a minor mode in arbitrary buffers, afrequent feature request has been to make it work with native tables inspecific languages, for example La@TeX{}. However, this is extremelyhard to do in a general way, would lead to a customization nightmare,and would take away much of the simplicity of the Orgtbl-mode tableeditor.This appendix describes a different approach. We keep the Orgtbl modetable in its native format (the @i{source table}), and use a customfunction to @i{translate} the table to the correct syntax, and to@i{install} it in the right location (the @i{target table}). This putsthe burden of writing conversion functions on the user, but it allowsfor a very flexible system.Bastien added the ability to do the same with lists, in Orgstruct mode. Youcan use Org's facilities to edit and structure lists by turning@code{orgstruct-mode} on, then locally exporting such lists in another format(HTML, La@TeX{} or Texinfo.)@menu* Radio tables:: Sending and receiving radio tables* A LaTeX example:: Step by step, almost a tutorial* Translator functions:: Copy and modify* Radio lists:: Doing the same for lists@end menu@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax@subsection Radio tables@cindex radio tablesTo define the location of the target table, you first need to create twolines that are comments in the current mode, but contain magic words forOrgtbl mode to find. Orgtbl mode will insert the translated tablebetween these lines, replacing whatever was there before. For example:@example/* BEGIN RECEIVE ORGTBL table_name *//* END RECEIVE ORGTBL table_name */@end example@noindentJust above the source table, we put a special line that tellsOrgtbl mode how to translate this table and where to install it. Forexample:@cindex #+ORGTBL@example#+ORGTBL: SEND table_name translation_function arguments....@end example@noindent@code{table_name} is the reference name for the table that is also usedin the receiver lines. @code{translation_function} is the Lisp functionthat does the translation. Furthermore, the line can contain a list ofarguments (alternating key and value) at the end. The arguments will bepassed as a property list to the translation function forinterpretation. A few standard parameters are already recognized andacted upon before the translation function is called:@table @code@item :skip NSkip the first N lines of the table. Hlines do count as separate lines forthis parameter!@item :skipcols (n1 n2 ...)List of columns that should be skipped. If the table has a column withcalculation marks, that column is automatically discarded as well.Please note that the translator function sees the table @emph{after} theremoval of these columns, the function never knows that there have beenadditional columns.@end table@noindentThe one problem remaining is how to keep the source table in the bufferwithout disturbing the normal workings of the file, for example duringcompilation of a C file or processing of a La@TeX{} file. There are anumber of different solutions:@itemize @bullet@itemThe table could be placed in a block comment if that is supported by thelanguage. For example, in C mode you could wrap the table between@samp{/*} and @samp{*/} lines.@itemSometimes it is possible to put the table after some kind of @i{END}statement, for example @samp{\bye} in @TeX{} and @samp{\end@{document@}}in La@TeX{}.@itemYou can just comment the table line-by-line whenever you want to processthe file, and uncomment it whenever you need to edit the table. Thisonly sounds tedious---the command @kbd{M-x orgtbl-toggle-comment}makes this comment-toggling very easy, in particular if you bind it to akey.@end itemize@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax@subsection A La@TeX{} example of radio tables@cindex La@TeX{}, and Orgtbl modeThe best way to wrap the source table in La@TeX{} is to use the@code{comment} environment provided by @file{comment.sty}. It has to beactivated by placing @code{\usepackage@{comment@}} into the documentheader. Orgtbl mode can insert a radio table skeleton@footnote{Bydefault this works only for La@TeX{}, HTML, and Texinfo. Configure thevariable @code{orgtbl-radio-tables} to install templates for othermodes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You willbe prompted for a table name, let's say we use @samp{salesfigures}. Youwill then get the following template:@cindex #+ORGTBL, SEND@example% BEGIN RECEIVE ORGTBL salesfigures% END RECEIVE ORGTBL salesfigures\begin@{comment@}#+ORGTBL: SEND salesfigures orgtbl-to-latex| | |\end@{comment@}@end example@noindent@vindex La@TeX{}-verbatim-environmentsThe @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function@code{orgtbl-to-latex} to convert the table into La@TeX{} and to put itinto the receiver location with name @code{salesfigures}. You may nowfill in the table, feel free to use the spreadsheet features@footnote{Ifthe @samp{#+TBLFM} line contains an odd number of dollar characters,this may cause problems with font-lock in La@TeX{} mode. As shown in theexample you can fix this by adding an extra line inside the@code{comment} environment that is used to balance the dollarexpressions. If you are using AUC@TeX{} with the font-latex library, amuch better solution is to add the @code{comment} environment to thevariable @code{LaTeX-verbatim-environments}.}:@example% BEGIN RECEIVE ORGTBL salesfigures% END RECEIVE ORGTBL salesfigures\begin@{comment@}#+ORGTBL: SEND salesfigures orgtbl-to-latex| Month | Days | Nr sold | per day ||-------+------+---------+---------|| Jan | 23 | 55 | 2.4 || Feb | 21 | 16 | 0.8 || March | 22 | 278 | 12.6 |#+TBLFM: $4=$3/$2;%.1f% $ (optional extra dollar to keep font-lock happy, see footnote)\end@{comment@}@end example@noindentWhen you are done, press @kbd{C-c C-c} in the table to get the convertedtable inserted between the two marker lines.Now let's assume you want to make the table header by hand, because youwant to control how columns are aligned, etc@. In this case we make surethat the table translator skips the first 2 lines of the sourcetable, and tell the command to work as a @i{splice}, i.e. to not produceheader and footer commands of the target table:@example\begin@{tabular@}@{lrrr@}Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\% BEGIN RECEIVE ORGTBL salesfigures% END RECEIVE ORGTBL salesfigures\end@{tabular@}%\begin@{comment@}#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2| Month | Days | Nr sold | per day ||-------+------+---------+---------|| Jan | 23 | 55 | 2.4 || Feb | 21 | 16 | 0.8 || March | 22 | 278 | 12.6 |#+TBLFM: $4=$3/$2;%.1f\end@{comment@}@end exampleThe La@TeX{} translator function @code{orgtbl-to-latex} is already part ofOrgtbl mode. It uses a @code{tabular} environment to typeset the tableand marks horizontal lines with @code{\hline}. Furthermore, itinterprets the following parameters (see also @pxref{Translator functions}):@table @code@item :splice nil/tWhen set to t, return only table body lines, don't wrap them into atabular environment. Default is nil.@item :fmt fmtA format to be used to wrap each field, it should contain @code{%s} for theoriginal field value. For example, to wrap each field value in dollars,you could use @code{:fmt "$%s$"}. This may also be a property list withcolumn numbers and formats. for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.A function of one argument can be used in place of the strings; thefunction must return a formatted string.@item :efmt efmtUse this format to print numbers with exponentials. The format shouldhave @code{%s} twice for inserting mantissa and exponent, for example@code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. Thismay also be a property list with column numbers and formats, for example@code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After@code{efmt} has been applied to a value, @code{fmt} will also beapplied. Similar to @code{fmt}, functions of two arguments can besupplied instead of strings.@end table@node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax@subsection Translator functions@cindex HTML, and Orgtbl mode@cindex translator functionOrgtbl mode has several translator functions built-in: @code{orgtbl-to-csv}(comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values)@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}.Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the samecode that produces tables during HTML export.}, these all use a generictranslator, @code{orgtbl-to-generic}. For example, @code{orgtbl-to-latex}itself is a very short function that computes the column definitions for the@code{tabular} environment, defines a few field and line separators and thenhands processing over to the generic translator. Here is the entire code:@lisp@group(defun orgtbl-to-latex (table params) "Convert the Orgtbl mode TABLE to LaTeX." (let* ((alignment (mapconcat (lambda (x) (if x "r" "l")) org-table-last-alignment "")) (params2 (list :tstart (concat "\\begin@{tabular@}@{" alignment "@}") :tend "\\end@{tabular@}" :lstart "" :lend " \\\\" :sep " & " :efmt "%s\\,(%s)" :hline "\\hline"))) (orgtbl-to-generic table (org-combine-plists params2 params))))@end group@end lispAs you can see, the properties passed into the function (variable@var{PARAMS}) are combined with the ones newly defined in the function(variable @var{PARAMS2}). The ones passed into the function (i.e. theones set by the @samp{ORGTBL SEND} line) take precedence. So if youwould like to use the La@TeX{} translator, but wanted the line endings tobe @samp{\\[2mm]} instead of the default @samp{\\}, you could justoverrule the default with@example#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"@end exampleFor a new language, you can either write your own converter function inanalogy with the La@TeX{} translator, or you can use the generic functiondirectly. For example, if you have a language where a table is startedwith @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines arestarted with @samp{!BL!}, ended with @samp{!EL!}, and where the fieldseparator is a TAB, you could call the generic translator like this (ona single line!):@example#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!" :lstart "!BL! " :lend " !EL!" :sep "\t"@end example@noindentPlease check the documentation string of the function@code{orgtbl-to-generic} for a full list of parameters understood bythat function, and remember that you can pass each of them into@code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other functionusing the generic function.Of course you can also write a completely new function doing complicatedthings the generic translator cannot do. A translator function takestwo arguments. The first argument is the table, a list of lines, eachline either the symbol @code{hline} or a list of fields. The secondargument is the property list containing all parameters specified in the@samp{#+ORGTBL: SEND} line. The function must return a single stringcontaining the formatted table. If you write a generally usefultranslator, please post it on @email{emacs-orgmode@@gnu.org} so thatothers can benefit from your work.@node Radio lists, , Translator functions, Tables in arbitrary syntax@subsection Radio lists@cindex radio lists@cindex org-list-insert-radio-listSending and receiving radio lists works exactly the same way than sending andreceiving radio tables (@pxref{Radio tables}). As for radio tables, you caninsert radio lists templates in HTML, La@TeX{} and Texinfo modes by calling@code{org-list-insert-radio-list}.Here are the differences with radio tables:@itemize @minus@itemOrgstruct mode must be active.@itemUse the @code{ORGLST} keyword instead of @code{ORGTBL}.@itemThe available translation functions for radio lists don't takeparameters.@item@kbd{C-c C-c} will work when pressed on the first item of the list.@end itemizeHere is a La@TeX{} example. Let's say that you have this in yourLa@TeX{} file:@cindex #+ORGLST@example% BEGIN RECEIVE ORGLST to-buy% END RECEIVE ORGLST to-buy\begin@{comment@}#+ORGLST: SEND to-buy org-list-to-latex- a new house- a new computer + a new keyboard + a new mouse- a new life\end@{comment@}@end examplePressing `C-c C-c' on @code{a new house} and will insert the convertedLa@TeX{} list between the two marker lines.@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking@section Dynamic blocks@cindex dynamic blocksOrg documents can contain @emph{dynamic blocks}. These arespecially marked regions that are updated by some user-written function.A good example for such a block is the clock table inserted by thecommand @kbd{C-c C-x C-r} (@pxref{Clocking work time}).Dynamic block are enclosed by a BEGIN-END structure that assigns a nameto the block and can also specify parameters for the function producingthe content of the block.#+BEGIN:dynamic block@example#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...#+END:@end exampleDynamic blocks are updated with the following commands@table @kbd@kindex C-c C-x C-u@item C-c C-x C-uUpdate dynamic block at point.@kindex C-u C-c C-x C-u@item C-u C-c C-x C-uUpdate all dynamic blocks in the current file.@end tableUpdating a dynamic block means to remove all the text between BEGIN andEND, parse the BEGIN line for parameters and then call the specificwriter function for this block to insert the new content. If you wantto use the original content in the writer function, you can use theextra parameter @code{:content}.For a block with name @code{myblock}, the writer function is@code{org-dblock-write:myblock} with as only parameter a property listwith the parameters given in the begin line. Here is a trivial exampleof a block that keeps track of when the block update function was lastrun:@example#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"#+END:@end example@noindentThe corresponding block writer function could look like this:@lisp(defun org-dblock-write:block-update-time (params) (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) (insert "Last block update at: " (format-time-string fmt (current-time)))))@end lispIf you want to make sure that all dynamic blocks are always up-to-date,you could add the function @code{org-update-all-dblocks} to a hook, forexample @code{before-save-hook}. @code{org-update-all-dblocks} iswritten in a way such that it does nothing in buffers that are not in@code{org-mode}.@node Special agenda views, Extracting agenda information, Dynamic blocks, Hacking@section Special agenda views@cindex agenda views, user-definedOrg provides a special hook that can be used to narrow down theselection made by any of the agenda views. You may specify a functionthat is used at each match to verify if the match should indeed be partof 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 WAITINGtag anywhere in the project tree. Let's further assume that you havemarked all tree headings that define a project with the TODO keywordPROJECT. In this case you would run a TODO search for the keywordPROJECT, but skip the match unless there is a WAITING tag anywhere inthe subtree belonging to the project line.To achieve this, you must write a function that searches the subtree forthe tag. If the tag is found, the function must return @code{nil} toindicate that this match should not be skipped. If there is no suchtag, return the location of the end of the subtree, to indicate thatsearch should continue from there.@lisp(defun my-skip-unless-waiting () "Skip trees that are not waiting" (let ((subtree-end (save-excursion (org-end-of-subtree t)))) (if (re-search-forward ":waiting:" subtree-end t) nil ; tag found, do not skip subtree-end))) ; tag not found, continue after end of subtree@end lispNow you may use this function in an agenda custom command, for examplelike this:@lisp(org-add-agenda-custom-command '("b" todo "PROJECT" ((org-agenda-skip-function 'my-skip-unless-waiting) (org-agenda-overriding-header "Projects waiting for something: "))))@end lisp@vindex org-agenda-overriding-headerNote that this also binds @code{org-agenda-overriding-header} to get ameaningful header in the agenda view.@vindex org-odd-levels-only@vindex org-agenda-skip-functionA general way to create custom searches is to base them on a search forentries with a certain level limit. If you want to study all entries withyour custom search function, simply do a search for@samp{LEVEL>0}@footnote{Note that, when using @code{org-odd-levels-only}, alevel number corresponds to order in the hierarchy, not to the number ofstars.}, and then use @code{org-agenda-skip-function} to select the entriesyou really want to have.You may also put a Lisp form into @code{org-agenda-skip-function}. Inparticular, you may use the functions @code{org-agenda-skip-entry-if}and @code{org-agenda-skip-subtree-if} in this form, for example:@table @code@item '(org-agenda-skip-entry-if 'scheduled)Skip current entry if it has been scheduled.@item '(org-agenda-skip-entry-if 'notscheduled)Skip current entry if it has not been scheduled.@item '(org-agenda-skip-entry-if 'deadline)Skip current entry if it has a deadline.@item '(org-agenda-skip-entry-if 'scheduled 'deadline)Skip current entry if it has a deadline, or if it is scheduled.@item '(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))Skip current entry if the TODO keyword is TODO or WAITING.@item '(org-agenda-skip-entry-if 'todo 'done)Skip current entry if the TODO keyword marks a DONE state.@item '(org-agenda-skip-entry-if 'timestamp)Skip current entry if it has any timestamp, may also be deadline or scheduled.@item '(org-agenda-skip-entry 'regexp "regular expression")Skip current entry if the regular expression matches in the entry.@item '(org-agenda-skip-entry 'notregexp "regular expression")Skip current entry unless the regular expression matches.@item '(org-agenda-skip-subtree-if 'regexp "regular expression")Same as above, but check and skip the entire subtree.@end tableTherefore we could also have written the search for WAITING projectslike this, even without defining a special function:@lisp(org-add-agenda-custom-command '("b" todo "PROJECT" ((org-agenda-skip-function '(org-agenda-skip-subtree-if 'regexp ":waiting:")) (org-agenda-overriding-header "Projects waiting for something: "))))@end lisp@node Extracting agenda information, Using the property API, Special agenda views, Hacking@section Extracting agenda information@cindex agenda, pipe@cindex Scripts, for agenda processing@vindex org-agenda-custom-commandsOrg provides commands to access agenda information for the commandline in Emacs batch mode. This extracted information can be sentdirectly to a printer, or it can be read by a program that does furtherprocessing of the data. The first of these commands is the function@code{org-batch-agenda}, that produces an agenda view and sends it asASCII 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 commandsyou have configured in @code{org-agenda-custom-commands}, basically anykey you can use after @kbd{C-c a}. For example, to directly print thecurrent TODO list, you could use@exampleemacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr@end exampleIf the parameter is a string with 2 or more characters, it is used as atags/TODO match string. For example, to print your local shopping list(all items with the tag @samp{shop}, but excluding the tag@samp{NewYork}), you could use@exampleemacs -batch -l ~/.emacs \ -eval '(org-batch-agenda "+shop-NewYork")' | lpr@end example@noindentYou may also modify parameters on the fly like this:@exampleemacs -batch -l ~/.emacs \ -eval '(org-batch-agenda "a" \ org-agenda-ndays 30 \ org-agenda-include-diary nil \ org-agenda-files (quote ("~/org/project.org")))' \ | lpr@end example@noindentwhich will produce a 30-day agenda, fully restricted to the Org file@file{~/org/projects.org}, not even including the diary.If you want to process the agenda data in more sophisticated ways, youcan use the command @code{org-batch-agenda-csv} to get a comma-separatedlist of values for each agenda item. Each line in the output willcontain a number of fields separated by commas. The fields in a lineare:@examplecategory @r{The category of the item}head @r{The headline, without TODO keyword, TAGS and PRIORITY}type @r{The type of the agenda entry, can be} todo @r{selected in TODO match} tagsmatch @r{selected in tags match} diary @r{imported from diary} deadline @r{a deadline} scheduled @r{scheduled} timestamp @r{appointment, selected by timestamp} closed @r{entry was closed on date} upcoming-deadline @r{warning about nearing deadline} past-scheduled @r{forwarded scheduled item} block @r{entry has date block including date}todo @r{The TODO keyword, if any}tags @r{All tags including inherited ones, separated by colons}date @r{The relevant date, like 2007-2-14}time @r{The time, like 15:00-16:50}extra @r{String with extra planning info}priority-l @r{The priority letter if any was given}priority-n @r{The computed numerical priority}@end example@noindentTime 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 fromEmacs/Org and prints all the items, preceded by a checkbox:@example#!/usr/bin/perl# define the Emacs command to run$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";# run it and capture the output$agenda = qx@{$cmd 2>/dev/null@};# loop over all linesforeach $line (split(/\n/,$agenda)) @{ # get the individual values ($category,$head,$type,$todo,$tags,$date,$time,$extra, $priority_l,$priority_n) = split(/,/,$line); # process and print print "[ ] $head\n";@}@end example@node Using the property API, Using the mapping API, Extracting agenda information, Hacking@section Using the property API@cindex API, for properties@cindex properties, APIHere is a description of the functions that can be used to work withproperties.@defun org-entry-properties &optional pom whichGet 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 theentry. The return value is an alist, keys may occur multiple timesif the property key was used several times.@*POM may also be nil, in which case the current entry is used.If WHICH is nil or `all', get all properties. If WHICH is`special' or `standard', only get that subclass.@end defun@vindex org-use-property-inheritance@defun org-entry-get pom property &optional inheritGet value of PROPERTY for entry at point-or-marker POM. By default,this only looks at properties defined locally in the entry. If INHERITis non-nil and the entry does not have the property, then also checkhigher levels of the hierarchy. If INHERIT is the symbol@code{selective}, use inheritance if and only if the setting of@code{org-use-property-inheritance} selects PROPERTY for inheritance.@end defun@defun org-entry-delete pom propertyDelete the property PROPERTY from entry at point-or-marker POM.@end defun@defun org-entry-put pom property valueSet PROPERTY to VALUE for entry at point-or-marker POM.@end defun@defun org-buffer-property-keys &optional include-specialsGet all property keys in the current buffer.@end defun@defun org-insert-property-drawerInsert a property drawer at point.@end defun@defun org-entry-put-multivalued-property pom property &rest valuesSet PROPERTY at point-or-marker POM to VALUES. VALUES should be a list ofstrings. They will be concatenated, with spaces as separators.@end defun@defun org-entry-get-multivalued-property pom propertyTreat the value of the property PROPERTY as a whitespace-separated list ofvalues and return the values as a list of strings.@end defun@defun org-entry-add-to-multivalued-property pom property valueTreat the value of the property PROPERTY as a whitespace-separated list ofvalues and make sure that VALUE is in this list.@end defun@defun org-entry-remove-from-multivalued-property pom property valueTreat the value of the property PROPERTY as a whitespace-separated list ofvalues and make sure that VALUE is @emph{not} in this list.@end defun@defun org-entry-member-in-multivalued-property pom property valueTreat the value of the property PROPERTY as a whitespace-separated list ofvalues and check if VALUE is in this list.@end defun@defopt org-property-allowed-value-functionsHook for functions supplying allowed values for specific.The functions must take a single argument, the name of the property, andreturn a flat list of allowed values. If @samp{:ETC} is one ofthe values, use the values as completion help, but allow also other valuesto be entered. The functions must return @code{nil} if they are notresponsible for this property.@end defopt@node Using the mapping API, , Using the property API, Hacking@section Using the mapping API@cindex API, for mapping@cindex mapping entries, APIOrg has sophisticated mapping capabilities to find all entries satisfyingcertain criteria. Internally, this functionality is used to produce agendaviews, but there is also an API that can be used to execute arbitraryfunctions for each or selected entries. The main entry point for this APIis:@defun org-map-entries func &optional match scope &rest skipCall FUNC at each headline selected by MATCH in SCOPE.FUNC is a function or a Lisp form. The function will be called withoutarguments, with the cursor positioned at the beginning of the headline.The return values of all calls to the function will be collected andreturned as a list.The call to FUNC will be wrapped into a save-excursion form, so FUNCdoes not need to preserve point. After evaluation, the cursor will bemoved to the end of the line (presumably of the headline of theprocessed entry) and search continues from there. Under somecircumstances, this may not produce the wanted results. For example,if you have removed (e.g. archived) the current (sub)tree it couldmean that the next entry will be skipped entirely. In such cases, youcan specify the position from where search should continue by makingFUNC set the variable `org-map-continue-from' to the desired bufferposition.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 duringthe iteration. When MATCH is nil or t, all headlines will bevisited by the iteration.SCOPE determines the scope of this command. It can be any of:@examplenil @r{the current buffer, respecting the restriction if any}tree @r{the subtree started with the entry at point}file @r{the current buffer, without restriction}file-with-archives @r{the current buffer, and any archives associated with it}agenda @r{all agenda files}agenda-with-archives @r{all agenda files with any archive files associated with them}(file1 file2 ...) @r{if this is a list, all files in the list will be scanned}@end example@noindentThe remaining args are treated as settings for the skipping facilities ofthe scanner. The following items can be given here:@vindex org-agenda-skip-function@examplearchive @r{skip trees with the archive tag}comment @r{skip trees with the COMMENT keyword}function or Lisp form @r{will be used as value for @code{org-agenda-skip-function},} @r{so whenever the function returns t, FUNC} @r{will not be called for that entry and search will} @r{continue from the point where the function leaves it}@end example@end defunThe function given to that mapping routine can really do anything you like.It can use the property API (@pxref{Using the property API}) to gather moreinformation about the entry, or in order to change metadata in the entry.Here are a couple of functions that might be handy:@defun org-todo &optional argChange the TODO state of the entry, see the docstring of the functions forthe many possible values for the argument ARG.@end defun@defun org-priority &optional actionChange the priority of the entry, see the docstring of this function for thepossible values for ACTION.@end defun@defun org-toggle-tag tag &optional onoffToggle the tag TAG in the current entry. Setting ONOFF to either @code{on}or @code{off} will not toggle tag, but ensure that it is either on or off.@end defun@defun org-promotePromote the current entry.@end defun@defun org-demoteDemote the current entry.@end defunHere is a simple example that will turn all entries in the current file witha tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}.Entries in comment trees and in archive trees will be ignored.@lisp(org-map-entries '(org-todo "UPCOMING") "+TOMORROW" 'file 'archive 'comment)@end lispThe following example counts the number of entries with TODO keyword@code{WAITING}, in all agenda files.@lisp(length (org-map-entries t "/+WAITING" 'agenda))@end lisp@node MobileOrg, History and Acknowledgments, Hacking, Top@appendix MobileOrg@cindex iPhone@cindex MobileOrg@uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the@i{iPhone/iPod Touch} series of devices, developed by Richard Moreland.@i{MobileOrg} offers offline viewing and capture support for an Org-modesystem rooted on a ``real'' computer. It does also allow you to recordchanges to existing entries. Android users should check out@uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}by Matt Jones.This appendix describes the support Org has for creating agenda views in aformat that can be displayed by @i{MobileOrg}, and for integrating notescaptured and changes made by @i{MobileOrg} into the main system.For changing tags and TODO states in MobileOrg, you should have set up thecustomization variables @code{org-todo-keywords} and @code{org-tags-alist} tocover all important tags and TODO keywords, even if individual files use onlypart of these. MobileOrg will also offer you states and tags set up within-buffer settings, but it will understand the logistics of TODO state@i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags(@pxref{Setting tags}) only for those set in these variables.@menu* Setting up the staging area:: Where to interact with the mobile device* Pushing to MobileOrg:: Uploading Org files and agendas* Pulling from MobileOrg:: Integrating captured and flagged items@end menu@node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg@section Setting up the staging areaMobileOrg needs to interact with Emacs through directory on aserver@footnote{If you are using a public server, you might prefer to encryptthe files on the server. This can be done with Org-mode 6.35 and, hopefully,with MobileOrg 1.4 (please check before trying to use this). On the Emacsside, configure the variables @code{org-mobile-use-encryption} and@code{org-mobile-encryption-password}.}. The easiest way to create thatdirectory is to use a free @uref{http://dropbox.com,Dropbox.com}account@footnote{If you cannot use Dropbox, or if your version of MobileOrgdoes not support it, you can use a webdav server. For more information,check out the the documentation of MobileOrg and also this@uref{http://orgmode.org/worg/org-faq.php#mobileorg_webdav, FAQ entry}.}.When MobileOrg first connects to your Dropbox, it will create a directory@i{MobileOrg} inside the Dropbox. After the directory has been created, tellEmacs about it:@lisp(setq org-mobile-directory "~/Dropbox/MobileOrg")@end lispOrg-mode has commands to put files for @i{MobileOrg} into that directory,and to read captured notes from there.@node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg@section Pushing to MobileOrgThis operation copies all files currently listed in @code{org-mobile-files}to the directory @code{org-mobile-directory}. By default this list containsall agenda files (as listed in @code{org-agenda-files}), but additional filescan be included by customizing @code{org-mobiles-files}. File names will bestaged with path relative to @code{org-directory}, so all files should beinside this directory. The push operation also creates a special Org file@file{agendas.org} with all custom agenda view defined by theuser@footnote{While creating the agendas, Org-mode will force (see thevariable @code{org-mobile-force-id-on-agenda-items}) ID properties on allreferenced entries, so that these entries can be uniquelyidentified if @i{MobileOrg} flags them for further action.}. Finally, Orgwrites the file @file{index.org}, containing links to all other files.@i{MobileOrg} first reads this file from the server, and then downloads allagendas and Org files listed in it. To speed up the download, MobileOrg willonly read files whose checksums@footnote{stored automatically in the file@file{checksums.dat}} have changed.@node Pulling from MobileOrg, , Pushing to MobileOrg, MobileOrg@section Pulling from MobileOrgWhen @i{MobileOrg} synchronizes with the server, it not only pulls the Orgfiles for viewing. It also appends captured entries and pointers to flaggedand changed entries to the file @file{mobileorg.org} on the server. Org hasa @emph{pull} operation that integrates this information into an inbox fileand operates on the pointers to flagged entries. Here is how it works:@enumerate@itemOrg moves all entries found in@file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after thisoperation.} and appends them to the file pointed to by the variable@code{org-mobile-inbox-for-pull}. Each captured entry and each editing eventwill be a top-level entry in the inbox file.@itemAfter moving the entries, Org will attempt to implement the changes made in@i{MobileOrg}. Some changes are applied directly and without userinteraction. Examples are all changes to tags, TODO state, headline and bodytext that can be cleanly applied. Entries that have been flagged for furtheraction will receive a tag @code{:FLAGGED:}, so that they can be easily foundagain. When there is a problem finding an entry or applying the change, thepointer entry will remain in the inbox and will be marked with an errormessage. You need to later resolve these issues by hand.@itemOrg will then generate an agenda view with all flagged entries. The usershould then go through these entries and do whatever actions are necessary.If a note has been stored while flagging an entry in @i{MobileOrg}, that notewill be displayed in the echo area when the cursor is on the correspondingagenda line.@table @kbd@kindex ?@item ?Pressing @kbd{?} in that special agenda will display the full flagging note inanother window and also push it onto the kill ring. So you could use @kbd{?z C-y C-c C-c} to store that flagging note as a normal note in the entry.Pressing @kbd{?} twice in succession will offer to remove the@code{:FLAGGED:} tag along with the recorded flagging note (which is storedin a property). In this way you indicate, that the intended processing forthis flagged entry is finished.@end table@end enumerate@kindex C-c a ?If you are not able to process all flagged entries directly, you can alwaysreturn to this agenda view using @kbd{C-c a ?}. Note, however, that there isa subtle difference. The view created automatically by @kbd{M-xorg-mobile-pull @key{RET}} is guaranteed to search all files that have beenaddressed by the last pull. This might include a file that is not currentlyin your list of agenda files. If you later use @kbd{C-c a ?} to regeneratethe view, only the current agenda files will be searched.@node History and Acknowledgments, Main Index, MobileOrg, Top@appendix History and acknowledgments@cindex acknowledgments@cindex history@cindex thanksOrg was born in 2003, out of frustration over the user interface of the EmacsOutline mode. I was trying to organize my notes and projects, and usingEmacs seemed to be the natural way to go. However, having to remember elevendifferent commands with two or three keys per command, only to hide and showparts of the outline tree, that seemed entirely unacceptable to me. Also,when using outlines to take notes, I constantly wanted to restructure thetree, organizing it parallel to my thoughts and plans. @emph{Visibilitycycling} and @emph{structure editing} were originally implemented in thepackage @file{outline-magic.el}, but quickly moved to the more general@file{org.el}. As this environment became comfortable for project planning,the next step was adding @emph{TODO entries}, basic @emph{timestamps}, and@emph{table support}. These areas highlighted the two main goals that Orgstill has today: to be a new, outline-based, plain text mode with innovativeand intuitive editing features, and to incorporate project planningfunctionality directly into a notes file.Since the first release, literally thousands of emails to me or to@email{emacs-orgmode@@gnu.org} have provided a constant stream of bugreports, feedback, new ideas, and sometimes patches and add-on code.Many thanks to everyone who has helped to improve this package. I amtrying to keep here a list of the people who had significant influencein shaping one or more aspects of Org. The list may not becomplete, if I have forgotten someone, please accept my apologies andlet me know.Before I get to this list, a few special mentions are in order:@table @i@item Bastien GuerryBastien has written a large number of extensions to Org (most of themintegrated into the core by now), including the LaTeX exporter and the plainlist parser. His support during the early days, when he basically acted asco-maintainer, was central to the success of this project. Bastien alsoinvented Worg, helped establishing the Web presence of Org, and sponsorshosting costs for the orgmode.org website.@item Eric Schulte and Dan DavisonEric and Dan are jointly responsible for the Org-babel system, which turnsOrg into a multi-language environment for evaluating code and doing literateprogramming and reproducible research.@item John WiegleyJohn has also contributed a number of great ideas and patchesdirectly to Org, including the attachment system (@file{org-attach.el}),integration with Apple Mail (@file{org-mac-message.el}), hierarchicaldependencies of TODO items, habit tracking (@file{org-habits.el}), andencryption (@file{org-crypt.el}). Also, the capture system is really anextended copy of his great @file{remember.el}.@item Sebastian RoseWithout Sebastian, the HTML/XHTML publishing of Org would be the pitiful workof an ignorant amateur. Sebastian has pushed this part of Org onto a muchhigher level. He also wrote @file{org-info.js}, a Java script for displayingwebpages derived from Org using an Info-like or a folding interface withsingle-key navigation.@end table@noindent OK, now to the full list of contributions! Again, please let meknow what I am missing here!@itemize @bullet@item@i{Russel Adams} came up with the idea for drawers.@item@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.@item@i{Christophe Bataillon} created the great unicorn logo that we use on theOrg-mode website.@item@i{Alex Bochannek} provided a patch for rounding timestamps.@item@i{Jan B旦cker} wrote @file{org-docview.el}.@item@i{Brad Bozarth} showed how to pull RSS feed data into Org-mode files.@item@i{Tom Breton} wrote @file{org-choose.el}.@item@i{Charles Cave}'s suggestion sparked the implementation of templatesfor Remember, which are now templates for capture.@item@i{Pavel Chalmoviansky} influenced the agenda treatment of items withspecified time.@item@i{Gregory Chernov} patched support for Lisp forms into tablecalculations and improved XEmacs compatibility, in particular by porting@file{nouline.el} to XEmacs.@item@i{Sacha Chua} suggested copying some linking code from Planner.@item@i{Baoqiu Cui} contributed the DocBook exporter.@item@i{Eddward DeVilla} proposed and tested checkbox statistics. He alsocame up with the idea of properties, and that there should be an API forthem.@item@i{Nick Dokos} tracked down several nasty bugs.@item@i{Kees Dullemond} used to edit projects lists directly in HTML and soinspired some of the early development, including HTML export. He alsoasked for a way to narrow wide table columns.@item@i{Thomas S. Dye} contributed documentation on Worg and helped integratingthe Org-Babel documentation into the manual.@item@i{Christian Egli} converted the documentation into Texinfo format,patched CSS formatting into the HTML exporter, and inspired the agenda.@item@i{David Emery} provided a patch for custom CSS support in exportedHTML agendas.@item@i{Nic Ferrier} contributed mailcap and XOXO support.@item@i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.@item@i{John Foerch} figured out how to make incremental search show contextaround a match in a hidden outline tree.@item@i{Raimar Finken} wrote @file{org-git-line.el}.@item@i{Mikael Fornius} works as a mailing list moderator.@item@i{Austin Frank} works as a mailing list moderator.@item@i{Niels Giesen} had the idea to automatically archive DONE trees.@item@i{Kai Grossjohann} pointed out key-binding conflicts with other packages.@item@i{Bernt Hansen} has driven much of the support for auto-repeating tasks,task state change logging, and the clocktable. His clear explanations havebeen critical when we started to adopt the Git version control system.@item@i{Manuel Hermenegildo} has contributed various ideas, small fixes andpatches.@item@i{Phil Jackson} wrote @file{org-irc.el}.@item@i{Scott Jaderholm} proposed footnotes, control over whitespace betweenfolded entries, and column view for properties.@item@i{Matt Jones} wrote @i{MobileOrg Android}.@item@i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.@item@i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He alsoprovided frequent feedback and some patches.@item@i{Matt Lundin} has proposed last-row references for table formulas and namedinvisible anchors. He has also worked a lot on the FAQ.@item@i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,and is a prolific contributor on the mailing list with competent replies,small fixes and patches.@item@i{Jason F. McBrayer} suggested agenda export to CSV format.@item@i{Max Mikhanosha} came up with the idea of refiling.@item@i{Dmitri Minaev} sent a patch to set priority limits on a per-filebasis.@item@i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compilerhappy.@item@i{Richard Moreland} wrote @i{MobileOrg} for the iPhone.@item@i{Rick Moynihan} proposed allowing multiple TODO sequences in a fileand being able to quickly restrict the agenda to a subtree.@item@i{Todd Neal} provided patches for links to Info files and Elisp forms.@item@i{Greg Newman} refreshed the unicorn logo into its current form.@item@i{Tim O'Callaghan} suggested in-file links, search options for generalfile links, and TAGS.@item@i{Osamu Okano} wrote @file{orgcard2ref.pl}, a perl program to create a textversion of the reference card.@item@i{Takeshi Okano} translated the manual and David O'Toole's tutorialinto Japanese.@item@i{Oliver Oppitz} suggested multi-state TODO items.@item@i{Scott Otterson} sparked the introduction of descriptive text forlinks, among other things.@item@i{Pete Phillips} helped during the development of the TAGS feature, andprovided frequent feedback.@item@i{Martin Pohlack} provided the code snippet to bundle character insertioninto bundles of 20 for undo.@item@i{T.V. Raman} reported bugs and suggested improvements.@item@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and qualitycontrol.@item@i{Paul Rivier} provided the basic implementation of named footnotes. Healso acted as mailing list moderator for some time.@item@i{Kevin Rogers} contributed code to access VM files on remote hosts.@item@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, aconflict with @file{allout.el}.@item@i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables withextensive patches.@item@i{Philip Rooke} created the Org reference card, provided lotsof feedback, developed and applied standards to the Org documentation.@item@i{Christian Schlauer} proposed angular brackets around links, amongother things.@item@i{Paul Sexton} wrote @file{org-ctags.el}.@itemLinking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s@file{organizer-mode.el}.@item@i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literalexamples, and remote highlighting for referenced code lines.@item@i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that isnow packaged into Org's @file{contrib} directory.@item@i{Daniel Sinder} came up with the idea of internal archiving by lockingsubtrees.@item@i{Dale Smith} proposed link abbreviations.@item@i{James TD Smith} has contributed a large number of patches for usefultweaks and features.@item@i{Adam Spiers} asked for global linking commands, inspired the linkextension system, added support for mairix, and proposed the mapping API.@item@i{Ulf Stegemann} created the table to translate special symbols to HTML,LaTeX, UTF-8, Latin-1 and ASCII.@item@i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML contentwith links transformation to Org syntax.@item@i{David O'Toole} wrote @file{org-publish.el} and drafted the manualchapter about publishing.@item@i{Stefan Vollmar} organized a video-recorded talk at theMax-Planck-Institute for Neurology. He also inspired the creation of aconcept index for HTML export.@item@i{J@"urgen Vollmer} contributed code generating the table of contentsin HTML output.@item@i{Samuel Wales} has provided important feedback and bug reports.@item@i{Chris Wallace} provided a patch implementing the @samp{QUOTE}keyword.@item@i{David Wainberg} suggested archiving, and improvements to the linkingsystem.@item@i{Carsten Wimmer} suggested some changes and helped fix a bug inlinking to Gnus.@item@i{Roland Winkler} requested additional key bindings to make Orgwork on a tty.@item@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocksand contributed various ideas and code snippets.@end itemize@node Main Index, Key Index, History and Acknowledgments, Top@unnumbered Concept index@printindex cp@node Key Index, Variable Index, Main Index, Top@unnumbered Key index@printindex ky@node Variable Index, , Key Index, Top@unnumbered Variable indexThis is not a complete index of variables and faces, only the ones that arementioned in the manual. For a more complete list, use @kbd{M-xorg-customize @key{RET}} and then click yourself through the tree.@printindex vr@bye@ignore arch-tag: 7893d1Fe-cc57-4d13-b5e5-f494a1CBC7ac@end ignore@c Local variables:@c fill-column: 77@c End:@c LocalWords: webdavhost pre