3 @setfilename ../../info/org
4 @settitle The Org Manual
6 @include org-version.inc
8 @c Use proper quote and backtick for code sections in PDF output
9 @c Cf. Texinfo manual 14.2
10 @set txicodequoteundirected
11 @set txicodequotebacktick
13 @c Version and Contact Info
14 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page}
15 @set AUTHOR Carsten Dominik
16 @set MAINTAINER Carsten Dominik
17 @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
18 @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
19 @documentencoding UTF-8
24 @c -----------------------------------------------------------------------------
26 @c Macro definitions for commands and keys
27 @c =======================================
29 @c The behavior of the key/command macros will depend on the flag cmdnames
30 @c When set, commands names are shown. When clear, they are not shown.
34 @c Below we define the following macros for Org key tables:
36 @c orgkey{key} A key item
37 @c orgcmd{key,cmd} Key with command name
38 @c xorgcmd{key,cmd} Key with command name as @itemx
39 @c orgcmdnki{key,cmd} Like orgcmd, but do not index the key
40 @c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key
41 @c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or"
42 @c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but
43 @c different functions, so format as @itemx
44 @c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short"
45 @c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx
46 @c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands
48 @c a key but no command
60 @c one key with a command
61 @c Inserts: @item KEY COMMAND
62 @macro orgcmd{key,command}
67 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
70 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
79 @c One key with one command, formatted using @itemx
80 @c Inserts: @itemx KEY COMMAND
81 @macro xorgcmd{key,command}
86 @itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
89 @itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
98 @c one key with a command, bit do not index the key
99 @c Inserts: @item KEY COMMAND
100 @macro orgcmdnki{key,command}
104 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
107 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
115 @c one key with a command, and special text to replace key in item
116 @c Inserts: @item TEXT COMMAND
117 @macro orgcmdtkc{text,key,command}
122 @item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
125 @item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
134 @c two keys with one command
135 @c Inserts: @item KEY1 or KEY2 COMMAND
136 @macro orgcmdkkc{key1,key2,command}
142 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
145 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
151 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
155 @c Two keys with one command name, but different functions, so format as
157 @c Inserts: @item KEY1
158 @c @itemx KEY2 COMMAND
159 @macro orgcmdkxkc{key1,key2,command}
166 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
170 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
181 @c Same as previous, but use "or short"
182 @c Inserts: @item KEY1 or short KEY2 COMMAND
183 @macro orgcmdkskc{key1,key2,command}
189 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
192 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
198 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
202 @c Same as previous, but use @itemx
203 @c Inserts: @itemx KEY1 or short KEY2 COMMAND
204 @macro xorgcmdkskc{key1,key2,command}
210 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
213 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
219 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
223 @c two keys with two commands
224 @c Inserts: @item KEY1 COMMAND1
225 @c @itemx KEY2 COMMAND2
226 @macro orgcmdkkcc{key1,key2,command1,command2}
233 @item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
234 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
237 @item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
238 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
248 @c -----------------------------------------------------------------------------
251 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
254 @c Subheadings inside a table.
255 @macro tsubheading{text}
257 @subsubheading \text\
265 This manual is for Org version @value{VERSION}.
267 Copyright @copyright{} 2004--2014 Free Software Foundation, Inc.
270 Permission is granted to copy, distribute and/or modify this document
271 under the terms of the GNU Free Documentation License, Version 1.3 or
272 any later version published by the Free Software Foundation; with no
273 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
274 and with the Back-Cover Texts as in (a) below. A copy of the license
275 is included in the section entitled ``GNU Free Documentation License.''
277 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
278 modify this GNU manual.''
282 @dircategory Emacs editing modes
284 * Org Mode: (org). Outline-based notes management and organizer
288 @title The Org Manual
290 @subtitle Release @value{VERSION}
291 @author by Carsten Dominik
292 with contributions by Bastien Guerry, Nicolas Goaziou, Eric Schulte,
293 Jambunathan K, Dan Davison, Thomas Dye, David O'Toole, and Philip Rooke.
295 @c The following two commands start the copyright page.
297 @vskip 0pt plus 1filll
301 @c Output the short table of contents at the beginning.
304 @c Output the table of contents at the beginning.
308 @c FIXME These hand-written next,prev,up node pointers make editing a lot
309 @c harder. There should be no need for them, makeinfo can do it
310 @c automatically for any document with a normal structure.
311 @node Top, Introduction, (dir), (dir)
318 * Introduction:: Getting started
319 * Document structure:: A tree works like your brain
320 * Tables:: Pure magic for quick formatting
321 * Hyperlinks:: Notes in context
322 * TODO items:: Every tree branch can be a TODO item
323 * Tags:: Tagging headlines and matching sets of tags
324 * Properties and columns:: Storing information about an entry
325 * Dates and times:: Making items useful for planning
326 * Capture - Refile - Archive:: The ins and outs for projects
327 * Agenda views:: Collecting information into views
328 * Markup:: Prepare text for rich export
329 * Exporting:: Sharing and publishing notes
330 * Publishing:: Create a web site of linked Org files
331 * Working with source code:: Export, evaluate, and tangle code blocks
332 * Miscellaneous:: All the rest which did not fit elsewhere
333 * Hacking:: How to hack your way around
334 * MobileOrg:: Viewing and capture on a mobile device
335 * History and acknowledgments:: How Org came into being
336 * GNU Free Documentation License:: The license for this documentation.
337 * Main Index:: An index of Org's concepts and features
338 * Key Index:: Key bindings and where they are described
339 * Command and Function Index:: Command names and some internal functions
340 * Variable Index:: Variables mentioned in the manual
343 --- The Detailed Node Listing ---
347 * Summary:: Brief summary of what Org does
348 * Installation:: Installing Org
349 * Activation:: How to activate Org for certain buffers
350 * Feedback:: Bug reports, ideas, patches etc.
351 * Conventions:: Typesetting conventions in the manual
355 * Outlines:: Org is based on Outline mode
356 * Headlines:: How to typeset Org tree headlines
357 * Visibility cycling:: Show and hide, much simplified
358 * Motion:: Jumping to other headlines
359 * Structure editing:: Changing sequence and level of headlines
360 * Sparse trees:: Matches embedded in context
361 * Plain lists:: Additional structure within an entry
362 * Drawers:: Tucking stuff away
363 * Blocks:: Folding blocks
364 * Footnotes:: How footnotes are defined in Org's syntax
365 * Orgstruct mode:: Structure editing outside Org
366 * Org syntax:: Formal description of Org's syntax
370 * Global and local cycling:: Cycling through various visibility states
371 * Initial visibility:: Setting the initial visibility state
372 * Catching invisible edits:: Preventing mistakes when editing invisible parts
376 * Built-in table editor:: Simple tables
377 * Column width and alignment:: Overrule the automatic settings
378 * Column groups:: Grouping to trigger vertical lines
379 * Orgtbl mode:: The table editor as minor mode
380 * The spreadsheet:: The table editor has spreadsheet capabilities
381 * Org-Plot:: Plotting from org tables
385 * References:: How to refer to another field or range
386 * Formula syntax for Calc:: Using Calc to compute stuff
387 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
388 * Durations and time values:: How to compute durations and time values
389 * Field and range formulas:: Formula for specific (ranges of) fields
390 * Column formulas:: Formulas valid for an entire column
391 * Lookup functions:: Lookup functions for searching tables
392 * Editing and debugging formulas:: Fixing formulas
393 * Updating the table:: Recomputing all dependent fields
394 * Advanced features:: Field and column names, parameters and automatic recalc
398 * Link format:: How links in Org are formatted
399 * Internal links:: Links to other places in the current file
400 * External links:: URL-like links to the world
401 * Handling links:: Creating, inserting and following
402 * Using links outside Org:: Linking from my C source code?
403 * Link abbreviations:: Shortcuts for writing complex links
404 * Search options:: Linking to a specific location
405 * Custom searches:: When the default search is not enough
409 * Radio targets:: Make targets trigger links in plain text
413 * TODO basics:: Marking and displaying TODO entries
414 * TODO extensions:: Workflow and assignments
415 * Progress logging:: Dates and notes for progress
416 * Priorities:: Some things are more important than others
417 * Breaking down tasks:: Splitting a task into manageable pieces
418 * Checkboxes:: Tick-off lists
420 Extended use of TODO keywords
422 * Workflow states:: From TODO to DONE in steps
423 * TODO types:: I do this, Fred does the rest
424 * Multiple sets in one file:: Mixing it all, and still finding your way
425 * Fast access to TODO states:: Single letter selection of a state
426 * Per-file keywords:: Different files, different requirements
427 * Faces for TODO keywords:: Highlighting states
428 * TODO dependencies:: When one task needs to wait for others
432 * Closing items:: When was this entry marked DONE?
433 * Tracking TODO state changes:: When did the status change?
434 * Tracking your habits:: How consistent have you been?
438 * Tag inheritance:: Tags use the tree structure of the outline
439 * Setting tags:: How to assign tags to a headline
440 * Tag groups:: Use one tag to search for several tags
441 * Tag searches:: Searching for combinations of tags
443 Properties and columns
445 * Property syntax:: How properties are spelled out
446 * Special properties:: Access to other Org mode features
447 * Property searches:: Matching property values
448 * Property inheritance:: Passing values down the tree
449 * Column view:: Tabular viewing and editing
450 * Property API:: Properties for Lisp programmers
454 * Defining columns:: The COLUMNS format property
455 * Using column view:: How to create and use column view
456 * Capturing column view:: A dynamic block for column view
460 * Scope of column definitions:: Where defined, where valid?
461 * Column attributes:: Appearance and content of a column
465 * Timestamps:: Assigning a time to a tree entry
466 * Creating timestamps:: Commands which insert timestamps
467 * Deadlines and scheduling:: Planning your work
468 * Clocking work time:: Tracking how long you spend on a task
469 * Effort estimates:: Planning work effort in advance
470 * Relative timer:: Notes with a running timer
471 * Countdown timer:: Starting a countdown timer for a task
475 * The date/time prompt:: How Org mode helps you entering date and time
476 * Custom time format:: Making dates look different
478 Deadlines and scheduling
480 * Inserting deadline/schedule:: Planning items
481 * Repeated tasks:: Items that show up again and again
485 * Clocking commands:: Starting and stopping a clock
486 * The clock table:: Detailed reports
487 * Resolving idle time:: Resolving time when you've been idle
489 Capture - Refile - Archive
491 * Capture:: Capturing new stuff
492 * Attachments:: Add files to tasks
493 * RSS feeds:: Getting input from RSS feeds
494 * Protocols:: External (e.g., Browser) access to Emacs and Org
495 * Refile and copy:: Moving/copying a tree from one place to another
496 * Archiving:: What to do with finished projects
500 * Setting up capture:: Where notes will be stored
501 * Using capture:: Commands to invoke and terminate capture
502 * Capture templates:: Define the outline of different note types
506 * Template elements:: What is needed for a complete template entry
507 * Template expansion:: Filling in information about time and context
508 * Templates in contexts:: Only show a template in a specific context
512 * Moving subtrees:: Moving a tree to an archive file
513 * Internal archiving:: Switch off a tree but keep it in the file
517 * Agenda files:: Files being searched for agenda information
518 * Agenda dispatcher:: Keyboard access to agenda views
519 * Built-in agenda views:: What is available out of the box?
520 * Presentation and sorting:: How agenda items are prepared for display
521 * Agenda commands:: Remote editing of Org trees
522 * Custom agenda views:: Defining special searches and views
523 * Exporting agenda views:: Writing a view to a file
524 * Agenda column view:: Using column view for collected entries
526 The built-in agenda views
528 * Weekly/daily agenda:: The calendar page with current tasks
529 * Global TODO list:: All unfinished action items
530 * Matching tags and properties:: Structured information with fine-tuned search
531 * Timeline:: Time-sorted view for single file
532 * Search view:: Find entries by searching for text
533 * Stuck projects:: Find projects you need to review
535 Presentation and sorting
537 * Categories:: Not all tasks are equal
538 * Time-of-day specifications:: How the agenda knows the time
539 * Sorting agenda items:: The order of things
540 * Filtering/limiting agenda items:: Dynamically narrow the agenda
544 * Storing searches:: Type once, use often
545 * Block agenda:: All the stuff you need in a single buffer
546 * Setting options:: Changing the rules
548 Markup for rich export
550 * Structural markup elements:: The basic structure as seen by the exporter
551 * Images and tables:: Images, tables and caption mechanism
552 * Literal examples:: Source code examples with special formatting
553 * Include files:: Include additional files into a document
554 * Index entries:: Making an index
555 * Macro replacement:: Use macros to create templates
556 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
557 * Special blocks:: Containers targeted at export back-ends
559 Structural markup elements
561 * Document title:: Where the title is taken from
562 * Headings and sections:: The document structure as seen by the exporter
563 * Table of contents:: The if and where of the table of contents
565 * Paragraphs:: Paragraphs
566 * Footnote markup:: Footnotes
567 * Emphasis and monospace:: Bold, italic, etc.
568 * Horizontal rules:: Make a line
569 * Comment lines:: What will *not* be exported
573 * Special symbols:: Greek letters and other symbols
574 * Subscripts and superscripts:: Simple syntax for raising/lowering text
575 * @LaTeX{} fragments:: Complex formulas made easy
576 * Previewing @LaTeX{} fragments:: What will this snippet look like?
577 * CDLaTeX mode:: Speed up entering of formulas
581 * The export dispatcher:: The main exporter interface
582 * Export back-ends:: Built-in export formats
583 * Export settings:: Generic export settings
584 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
585 * Beamer export:: Exporting as a Beamer presentation
586 * HTML export:: Exporting to HTML
587 * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
588 * Markdown export:: Exporting to Markdown
589 * OpenDocument text export:: Exporting to OpenDocument Text
590 * Org export:: Exporting to Org
591 * iCalendar export:: Exporting to iCalendar
592 * Other built-in back-ends:: Exporting to @code{Texinfo} or a man page
593 * Export in foreign buffers:: Author tables and lists in Org syntax
594 * Advanced configuration:: Fine-tuning the export output
598 * HTML Export commands:: How to invoke HTML export
599 * HTML doctypes:: Org can export to various (X)HTML flavors
600 * HTML preamble and postamble:: How to insert a preamble and a postamble
601 * Quoting HTML tags:: Using direct HTML in Org mode
602 * Links in HTML export:: How links will be interpreted and formatted
603 * Tables in HTML export:: How to modify the formatting of tables
604 * Images in HTML export:: How to insert figures into HTML output
605 * Math formatting in HTML export:: Beautiful math also on the web
606 * Text areas in HTML export:: An alternative way to show an example
607 * CSS support:: Changing the appearance of the output
608 * JavaScript support:: Info and Folding in a web browser
610 @LaTeX{} and PDF export
612 * @LaTeX{} export commands:: How to export to LaTeX and PDF
613 * Header and sectioning:: Setting up the export file structure
614 * Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code
615 * @LaTeX{} specific attributes:: Controlling @LaTeX{} output
617 OpenDocument text export
619 * Pre-requisites for ODT export:: What packages ODT exporter relies on
620 * ODT export commands:: How to invoke ODT export
621 * Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files
622 * Applying custom styles:: How to apply custom styles to the output
623 * Links in ODT export:: How links will be interpreted and formatted
624 * Tables in ODT export:: How Tables are exported
625 * Images in ODT export:: How to insert images
626 * Math formatting in ODT export:: How @LaTeX{} fragments are formatted
627 * Labels and captions in ODT export:: How captions are rendered
628 * Literal examples in ODT export:: How source and example blocks are formatted
629 * Advanced topics in ODT export:: Read this if you are a power user
631 Math formatting in ODT export
633 * Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments
634 * Working with MathML or OpenDocument formula files:: How to embed equations in native format
636 Advanced topics in ODT export
638 * Configuring a document converter:: How to register a document converter
639 * Working with OpenDocument style files:: Explore the internals
640 * Creating one-off styles:: How to produce custom highlighting etc
641 * Customizing tables in ODT export:: How to define and use Table templates
642 * Validating OpenDocument XML:: How to debug corrupt OpenDocument files
646 * Configuration:: Defining projects
647 * Uploading files:: How to get files up on the server
648 * Sample configuration:: Example projects
649 * Triggering publication:: Publication commands
653 * Project alist:: The central configuration variable
654 * Sources and destinations:: From here to there
655 * Selecting files:: What files are part of the project?
656 * Publishing action:: Setting the function doing the publishing
657 * Publishing options:: Tweaking HTML/@LaTeX{} export
658 * Publishing links:: Which links keep working after publishing?
659 * Sitemap:: Generating a list of all pages
660 * Generating an index:: An index that reaches across pages
664 * Simple example:: One-component publishing
665 * Complex example:: A multi-component publishing example
667 Working with source code
669 * Structure of code blocks:: Code block syntax described
670 * Editing source code:: Language major-mode editing
671 * Exporting code blocks:: Export contents and/or results
672 * Extracting source code:: Create pure source code files
673 * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
674 * Library of Babel:: Use and contribute to a library of useful code blocks
675 * Languages:: List of supported code block languages
676 * Header arguments:: Configure code block functionality
677 * Results of evaluation:: How evaluation results are handled
678 * Noweb reference syntax:: Literate programming in Org mode
679 * Key bindings and useful functions:: Work quickly with code blocks
680 * Batch execution:: Call functions from the command line
684 * Using header arguments:: Different ways to set header arguments
685 * Specific header arguments:: List of header arguments
687 Using header arguments
689 * System-wide header arguments:: Set global default values
690 * Language-specific header arguments:: Set default values by language
691 * Header arguments in Org mode properties:: Set default values for a buffer or heading
692 * Language-specific header arguments in Org mode properties:: Set language-specific default values for a buffer or heading
693 * Code block specific header arguments:: The most common way to set values
694 * Header arguments in function calls:: The most specific level
696 Specific header arguments
698 * var:: Pass arguments to code blocks
699 * Results:: Specify the type of results and how they will
700 be collected and handled
701 * file:: Specify a path for file output
702 * file-desc:: Specify a description for file results
703 * dir:: Specify the default (possibly remote)
704 directory for code block execution
705 * exports:: Export code and/or results
706 * tangle:: Toggle tangling and specify file name
707 * mkdirp:: Toggle creation of parent directories of target
708 files during tangling
709 * comments:: Toggle insertion of comments in tangled
711 * padline:: Control insertion of padding lines in tangled
713 * no-expand:: Turn off variable assignment and noweb
714 expansion during tangling
715 * session:: Preserve the state of code evaluation
716 * noweb:: Toggle expansion of noweb references
717 * noweb-ref:: Specify block's noweb reference resolution target
718 * noweb-sep:: String used to separate noweb references
719 * cache:: Avoid re-evaluating unchanged code blocks
720 * sep:: Delimiter for writing tabular results outside Org
721 * hlines:: Handle horizontal lines in tables
722 * colnames:: Handle column names in tables
723 * rownames:: Handle row names in tables
724 * shebang:: Make tangled files executable
725 * tangle-mode:: Set permission of tangled files
726 * eval:: Limit evaluation of specific code blocks
727 * wrap:: Mark source block evaluation results
728 * post:: Post processing of code block results
729 * prologue:: Text to prepend to code block body
730 * epilogue:: Text to append to code block body
734 * Completion:: M-TAB knows what you need
735 * Easy templates:: Quick insertion of structural elements
736 * Speed keys:: Electric commands at the beginning of a headline
737 * Code evaluation security:: Org mode files evaluate inline code
738 * Customization:: Adapting Org to your taste
739 * In-buffer settings:: Overview of the #+KEYWORDS
740 * The very busy C-c C-c key:: When in doubt, press C-c C-c
741 * Clean view:: Getting rid of leading stars in the outline
742 * TTY keys:: Using Org on a tty
743 * Interaction:: Other Emacs packages
744 * org-crypt:: Encrypting Org files
746 Interaction with other packages
748 * Cooperation:: Packages Org cooperates with
749 * Conflicts:: Packages that lead to conflicts
753 * Hooks:: How to reach into Org's internals
754 * Add-on packages:: Available extensions
755 * Adding hyperlink types:: New custom link types
756 * Adding export back-ends:: How to write new export back-ends
757 * Context-sensitive commands:: How to add functionality to such commands
758 * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
759 * Dynamic blocks:: Automatically filled blocks
760 * Special agenda views:: Customized views
761 * Speeding up your agendas:: Tips on how to speed up your agendas
762 * Extracting agenda information:: Post-processing of agenda information
763 * Using the property API:: Writing programs that use entry properties
764 * Using the mapping API:: Mapping over all or selected entries
766 Tables and lists in arbitrary syntax
768 * Radio tables:: Sending and receiving radio tables
769 * A @LaTeX{} example:: Step by step, almost a tutorial
770 * Translator functions:: Copy and modify
771 * Radio lists:: Sending and receiving lists
775 * Setting up the staging area:: Where to interact with the mobile device
776 * Pushing to MobileOrg:: Uploading Org files and agendas
777 * Pulling from MobileOrg:: Integrating captured and flagged items
783 @chapter Introduction
787 * Summary:: Brief summary of what Org does
788 * Installation:: Installing Org
789 * Activation:: How to activate Org for certain buffers
790 * Feedback:: Bug reports, ideas, patches etc.
791 * Conventions:: Typesetting conventions in the manual
798 Org is a mode for keeping notes, maintaining TODO lists, and project planning
799 with a fast and effective plain-text system. It also is an authoring system
800 with unique support for literate programming and reproducible research.
802 Org is implemented on top of Outline mode, which makes it possible to keep
803 the content of large files well structured. Visibility cycling and structure
804 editing help to work with the tree. Tables are easily created with a
805 built-in table editor. Plain text URL-like links connect to websites,
806 emails, Usenet messages, BBDB entries, and any files related to the projects.
808 Org develops organizational tasks around notes files that contain lists or
809 information about projects as plain text. Project planning and task
810 management makes use of metadata which is part of an outline node. Based on
811 this data, specific entries can be extracted in queries and create dynamic
812 @i{agenda views} that also integrate the Emacs calendar and diary. Org can
813 be used to implement many different project planning schemes, such as David
816 Org files can serve as a single source authoring system with export to many
817 different formats such as HTML, @LaTeX{}, Open Document, and Markdown. New
818 export backends can be derived from existing ones, or defined from scratch.
820 Org files can include source code blocks, which makes Org uniquely suited for
821 authoring technical documents with code examples. Org source code blocks are
822 fully functional; they can be evaluated in place and their results can be
823 captured in the file. This makes it possible to create a single file
824 reproducible research compendium.
826 Org keeps simple things simple. When first fired up, it should feel like a
827 straightforward, easy to use outliner. Complexity is not imposed, but a
828 large amount of functionality is available when needed. Org is a toolbox.
829 Many users usilize only a (very personal) fraction of Org's capabilities, and
830 know that there is more whenever they need it.
832 All of this is achieved with strictly plain text files, the most portable and
833 future-proof file format. Org runs in Emacs. Emacs is one of the most
834 widely ported programs, so that Org mode is available on every major
838 There is a website for Org which provides links to the newest
839 version of Org, as well as additional information, frequently asked
840 questions (FAQ), links to tutorials, etc. This page is located at
841 @uref{http://orgmode.org}.
842 @cindex print edition
844 An earlier version (7.3) of this manual is available as a
845 @uref{http://www.network-theory.co.uk/org/manual/, paperback book from
851 @section Installation
855 Org is part of recent distributions of GNU Emacs, so you normally don't need
856 to install it. If, for one reason or another, you want to install Org on top
857 of this pre-packaged version, there are three ways to do it:
860 @item By using Emacs package system.
861 @item By downloading Org as an archive.
862 @item By using Org's git repository.
865 We @b{strongly recommend} to stick to a single installation method.
867 @subsubheading Using Emacs packaging system
869 Recent Emacs distributions include a packaging system which lets you install
870 Elisp libraries. You can install Org with @kbd{M-x package-install RET org}.
871 You need to do this in a session where no @code{.org} file has been visited.
872 Then, to make sure your Org configuration is taken into account, initialize
873 the package system with @code{(package-initialize)} in your @file{.emacs}
874 before setting any Org option. If you want to use Org's package repository,
875 check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
877 @subsubheading Downloading Org as an archive
879 You can download Org latest release from @uref{http://orgmode.org/, Org's
880 website}. In this case, make sure you set the load-path correctly in your
884 (add-to-list 'load-path "~/path/to/orgdir/lisp")
887 The downloaded archive contains contributed libraries that are not included
888 in Emacs. If you want to use them, add the @file{contrib} directory to your
892 (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
895 Optionally, you can compile the files and/or install them in your system.
896 Run @code{make help} to list compilation and installation options.
898 @subsubheading Using Org's git repository
900 You can clone Org's repository and install Org like this:
904 $ git clone git://orgmode.org/org-mode.git
908 Note that in this case, @code{make autoloads} is mandatory: it defines Org's
909 version in @file{org-version.el} and Org's autoloads in
910 @file{org-loaddefs.el}.
912 Remember to add the correct load-path as described in the method above.
914 You can also compile with @code{make}, generate the documentation with
915 @code{make doc}, create a local configuration with @code{make config} and
916 install Org with @code{make install}. Please run @code{make help} to get
917 the list of compilation/installation options.
919 For more detailed explanations on Org's build system, please check the Org
920 Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
928 @cindex global key bindings
929 @cindex key bindings, global
932 @findex org-store-link
935 Since Emacs 22.2, files with the @file{.org} extension use Org mode by
936 default. If you are using an earlier version of Emacs, add this line to your
940 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
943 Org mode buffers need font-lock to be turned on: this is the default in
944 Emacs@footnote{If you don't use font-lock globally, turn it on in Org buffer
945 with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
947 There are compatibility issues between Org mode and some other Elisp
948 packages, please take the time to check the list (@pxref{Conflicts}).
950 The four Org commands @command{org-store-link}, @command{org-capture},
951 @command{org-agenda}, and @command{org-iswitchb} should be accessible through
952 global keys (i.e., anywhere in Emacs, not just in Org buffers). Here are
953 suggested bindings for these keys, please modify the keys to your own
956 (global-set-key "\C-cl" 'org-store-link)
957 (global-set-key "\C-ca" 'org-agenda)
958 (global-set-key "\C-cc" 'org-capture)
959 (global-set-key "\C-cb" 'org-iswitchb)
962 @cindex Org mode, turning on
963 To turn on Org mode in a file that does not have the extension @file{.org},
964 make the first line of a file look like this:
967 MY PROJECTS -*- mode: org; -*-
970 @vindex org-insert-mode-line-in-empty-file
971 @noindent which will select Org mode for this buffer no matter what
972 the file's name is. See also the variable
973 @code{org-insert-mode-line-in-empty-file}.
975 Many commands in Org work on the region if the region is @i{active}. To make
976 use of this, you need to have @code{transient-mark-mode}
977 (@code{zmacs-regions} in XEmacs) turned on. In Emacs 23 this is the default,
978 in Emacs 22 you need to do this yourself with
980 (transient-mark-mode 1)
982 @noindent If you do not like @code{transient-mark-mode}, you can create an
983 active region by using the mouse to select a region, or pressing
984 @kbd{C-@key{SPC}} twice before moving the cursor.
993 If you find problems with Org, or if you have questions, remarks, or ideas
994 about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
995 If you are not a member of the mailing list, your mail will be passed to the
996 list after a moderator has approved it@footnote{Please consider subscribing
997 to the mailing list, in order to minimize the work the mailing list
998 moderators have to do.}.
1000 For bug reports, please first try to reproduce the bug with the latest
1001 version of Org available---if you are running an outdated version, it is
1002 quite possible that the bug has been fixed already. If the bug persists,
1003 prepare a report and provide as much information as possible, including the
1004 version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
1005 (@kbd{M-x org-version RET}), as well as the Org related setup in
1006 @file{.emacs}. The easiest way to do this is to use the command
1008 @kbd{M-x org-submit-bug-report RET}
1010 @noindent which will put all this information into an Emacs mail buffer so
1011 that you only need to add your description. If you are not sending the Email
1012 from within Emacs, please copy and paste the content into your Email program.
1014 Sometimes you might face a problem due to an error in your Emacs or Org mode
1015 setup. Before reporting a bug, it is very helpful to start Emacs with minimal
1016 customizations and reproduce the problem. Doing so often helps you determine
1017 if the problem is with your customization or with Org mode itself. You can
1018 start a typical minimal session with a command like the example below.
1021 $ emacs -Q -l /path/to/minimal-org.el
1024 However if you are using Org mode as distributed with Emacs, a minimal setup
1025 is not necessary. In that case it is sufficient to start Emacs as
1026 @code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
1030 ;;; Minimal setup to load latest `org-mode'
1032 ;; activate debugging
1033 (setq debug-on-error t
1037 ;; add latest org-mode to load path
1038 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
1039 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
1042 If an error occurs, a backtrace can be very useful (see below on how to
1043 create one). Often a small example file helps, along with clear information
1047 @item What exactly did you do?
1048 @item What did you expect to happen?
1049 @item What happened instead?
1051 @noindent Thank you for helping to improve this program.
1053 @subsubheading How to create a useful backtrace
1055 @cindex backtrace of an error
1056 If working with Org produces an error with a message you don't
1057 understand, you may have hit a bug. The best way to report this is by
1058 providing, in addition to what was mentioned above, a @emph{backtrace}.
1059 This is information from the built-in debugger about where and how the
1060 error occurred. Here is how to produce a useful backtrace:
1064 Reload uncompiled versions of all Org mode Lisp files. The backtrace
1065 contains much more information if it is produced with uncompiled code.
1068 @kbd{C-u M-x org-reload RET}
1071 or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
1074 Go to the @code{Options} menu and select @code{Enter Debugger on Error}
1075 (XEmacs has this option in the @code{Troubleshooting} sub-menu).
1077 Do whatever you have to do to hit the error. Don't forget to
1078 document the steps you take.
1080 When you hit the error, a @file{*Backtrace*} buffer will appear on the
1081 screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
1082 attach it to your bug report.
1086 @section Typesetting conventions used in this manual
1088 @subsubheading TODO keywords, tags, properties, etc.
1090 Org mainly uses three types of keywords: TODO keywords, tags and property
1091 names. In this manual we use the following conventions:
1096 TODO keywords are written with all capitals, even if they are
1100 User-defined tags are written in lowercase; built-in tags with special
1101 meaning are written with all capitals.
1104 User-defined properties are capitalized; built-in properties with
1105 special meaning are written with all capitals.
1108 Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
1109 and @i{environment keywords} (like @code{#+BEGIN_HTML} to start a @code{HTML}
1110 environment). They are written in uppercase in the manual to enhance its
1111 readability, but you can use lowercase in your Org files@footnote{Easy
1112 templates insert lowercase keywords and Babel dynamically inserts
1115 @subsubheading Keybindings and commands
1121 The manual suggests a few global keybindings, in particular @kbd{C-c a} for
1122 @code{org-agenda} and @kbd{C-c c} for @code{org-capture}. These are only
1123 suggestions, but the rest of the manual assumes that these keybindings are in
1124 place in order to list commands by key access.
1126 Also, the manual lists both the keys and the corresponding commands for
1127 accessing a functionality. Org mode often uses the same key for different
1128 functions, depending on context. The command that is bound to such keys has
1129 a generic name, like @code{org-metaright}. In the manual we will, wherever
1130 possible, give the function that is internally called by the generic command.
1131 For example, in the chapter on document structure, @kbd{M-@key{right}} will
1132 be listed to call @code{org-do-demote}, while in the chapter on tables, it
1133 will be listed to call @code{org-table-move-column-right}. If you prefer,
1134 you can compile the manual without the command names by unsetting the flag
1135 @code{cmdnames} in @file{org.texi}.
1137 @node Document structure
1138 @chapter Document structure
1139 @cindex document structure
1140 @cindex structure of document
1142 Org is based on Outline mode and provides flexible commands to
1143 edit the structure of the document.
1146 * Outlines:: Org is based on Outline mode
1147 * Headlines:: How to typeset Org tree headlines
1148 * Visibility cycling:: Show and hide, much simplified
1149 * Motion:: Jumping to other headlines
1150 * Structure editing:: Changing sequence and level of headlines
1151 * Sparse trees:: Matches embedded in context
1152 * Plain lists:: Additional structure within an entry
1153 * Drawers:: Tucking stuff away
1154 * Blocks:: Folding blocks
1155 * Footnotes:: How footnotes are defined in Org's syntax
1156 * Orgstruct mode:: Structure editing outside Org
1157 * Org syntax:: Formal description of Org's syntax
1163 @cindex Outline mode
1165 Org is implemented on top of Outline mode. Outlines allow a
1166 document to be organized in a hierarchical structure, which (at least
1167 for me) is the best representation of notes and thoughts. An overview
1168 of this structure is achieved by folding (hiding) large parts of the
1169 document to show only the general document structure and the parts
1170 currently being worked on. Org greatly simplifies the use of
1171 outlines by compressing the entire show/hide functionality into a single
1172 command, @command{org-cycle}, which is bound to the @key{TAB} key.
1177 @cindex outline tree
1178 @vindex org-special-ctrl-a/e
1179 @vindex org-special-ctrl-k
1180 @vindex org-ctrl-k-protect-subtree
1182 Headlines define the structure of an outline tree. The headlines in Org
1183 start with one or more stars, on the left margin@footnote{See the variables
1184 @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
1185 @code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
1186 @kbd{C-e}, and @kbd{C-k} in headlines.} @footnote{Clocking only works with
1187 headings indented less then 30 stars.}. For example:
1190 * Top level headline
1197 * Another top level headline
1200 @noindent Some people find the many stars too noisy and would prefer an
1201 outline that has whitespace followed by a single star as headline
1202 starters. @ref{Clean view}, describes a setup to realize this.
1204 @vindex org-cycle-separator-lines
1205 An empty line after the end of a subtree is considered part of it and
1206 will be hidden when the subtree is folded. However, if you leave at
1207 least two empty lines, one empty line will remain visible after folding
1208 the subtree, in order to structure the collapsed view. See the
1209 variable @code{org-cycle-separator-lines} to modify this behavior.
1211 @node Visibility cycling
1212 @section Visibility cycling
1213 @cindex cycling, visibility
1214 @cindex visibility cycling
1215 @cindex trees, visibility
1216 @cindex show hidden text
1220 * Global and local cycling:: Cycling through various visibility states
1221 * Initial visibility:: Setting the initial visibility state
1222 * Catching invisible edits:: Preventing mistakes when editing invisible parts
1225 @node Global and local cycling
1226 @subsection Global and local cycling
1228 Outlines make it possible to hide parts of the text in the buffer.
1229 Org uses just two commands, bound to @key{TAB} and
1230 @kbd{S-@key{TAB}} to change the visibility in the buffer.
1232 @cindex subtree visibility states
1233 @cindex subtree cycling
1234 @cindex folded, subtree visibility state
1235 @cindex children, subtree visibility state
1236 @cindex subtree, subtree visibility state
1238 @orgcmd{@key{TAB},org-cycle}
1239 @emph{Subtree cycling}: Rotate current subtree among the states
1242 ,-> FOLDED -> CHILDREN -> SUBTREE --.
1243 '-----------------------------------'
1246 @vindex org-cycle-emulate-tab
1247 @vindex org-cycle-global-at-bob
1248 The cursor must be on a headline for this to work@footnote{see, however,
1249 the option @code{org-cycle-emulate-tab}.}. When the cursor is at the
1250 beginning of the buffer and the first line is not a headline, then
1251 @key{TAB} actually runs global cycling (see below)@footnote{see the
1252 option @code{org-cycle-global-at-bob}.}. Also when called with a prefix
1253 argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
1255 @cindex global visibility states
1256 @cindex global cycling
1257 @cindex overview, global visibility state
1258 @cindex contents, global visibility state
1259 @cindex show all, global visibility state
1260 @orgcmd{S-@key{TAB},org-global-cycle}
1261 @itemx C-u @key{TAB}
1262 @emph{Global cycling}: Rotate the entire buffer among the states
1265 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
1266 '--------------------------------------'
1269 When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the
1270 CONTENTS view up to headlines of level N will be shown. Note that inside
1271 tables, @kbd{S-@key{TAB}} jumps to the previous field.
1273 @cindex set startup visibility, command
1274 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1275 Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
1276 @cindex show all, command
1277 @orgcmd{C-u C-u C-u @key{TAB},show-all}
1278 Show all, including drawers.
1279 @cindex revealing context
1280 @orgcmd{C-c C-r,org-reveal}
1281 Reveal context around point, showing the current entry, the following heading
1282 and the hierarchy above. Useful for working near a location that has been
1283 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
1284 (@pxref{Agenda commands}). With a prefix argument show, on each
1285 level, all sibling headings. With a double prefix argument, also show the
1286 entire subtree of the parent.
1287 @cindex show branches, command
1288 @orgcmd{C-c C-k,show-branches}
1289 Expose all the headings of the subtree, CONTENT view for just one subtree.
1290 @cindex show children, command
1291 @orgcmd{C-c @key{TAB},show-children}
1292 Expose all direct children of the subtree. With a numeric prefix argument N,
1293 expose all children down to level N@.
1294 @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
1295 Show the current subtree in an indirect buffer@footnote{The indirect
1298 (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual})
1301 (see the Emacs manual for more information about indirect buffers)
1303 will contain the entire buffer, but will be narrowed to the current
1304 tree. Editing the indirect buffer will also change the original buffer,
1305 but without affecting visibility in that buffer.}. With a numeric
1306 prefix argument N, go up to level N and then take that tree. If N is
1307 negative then go up that many levels. With a @kbd{C-u} prefix, do not remove
1308 the previously used indirect buffer.
1309 @orgcmd{C-c C-x v,org-copy-visible}
1310 Copy the @i{visible} text in the region into the kill ring.
1313 @node Initial visibility
1314 @subsection Initial visibility
1316 @cindex visibility, initialize
1317 @vindex org-startup-folded
1318 @vindex org-agenda-inhibit-startup
1319 @cindex @code{overview}, STARTUP keyword
1320 @cindex @code{content}, STARTUP keyword
1321 @cindex @code{showall}, STARTUP keyword
1322 @cindex @code{showeverything}, STARTUP keyword
1324 When Emacs first visits an Org file, the global state is set to OVERVIEW,
1325 i.e., only the top level headlines are visible@footnote{When
1326 @code{org-agenda-inhibit-startup} is non-@code{nil}, Org will not honor the default
1327 visibility state when first opening a file for the agenda (@pxref{Speeding up
1328 your agendas}).}. This can be configured through the variable
1329 @code{org-startup-folded}, or on a per-file basis by adding one of the
1330 following lines anywhere in the buffer:
1336 #+STARTUP: showeverything
1339 The startup visibility options are ignored when the file is open for the
1340 first time during the agenda generation: if you want the agenda to honor
1341 the startup visibility, set @code{org-agenda-inhibit-startup} to @code{nil}.
1343 @cindex property, VISIBILITY
1345 Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
1346 and columns}) will get their visibility adapted accordingly. Allowed values
1347 for this property are @code{folded}, @code{children}, @code{content}, and
1351 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1352 Switch back to the startup visibility of the buffer, i.e., whatever is
1353 requested by startup options and @samp{VISIBILITY} properties in individual
1357 @node Catching invisible edits
1358 @subsection Catching invisible edits
1360 @vindex org-catch-invisible-edits
1361 @cindex edits, catching invisible
1362 Sometimes you may inadvertently edit an invisible part of the buffer and be
1363 confused on what has been edited and how to undo the mistake. Setting
1364 @code{org-catch-invisible-edits} to non-@code{nil} will help prevent this. See the
1365 docstring of this option on how Org should catch invisible edits and process
1370 @cindex motion, between headlines
1371 @cindex jumping, to headlines
1372 @cindex headline navigation
1373 The following commands jump to other headlines in the buffer.
1376 @orgcmd{C-c C-n,outline-next-visible-heading}
1378 @orgcmd{C-c C-p,outline-previous-visible-heading}
1380 @orgcmd{C-c C-f,org-forward-same-level}
1381 Next heading same level.
1382 @orgcmd{C-c C-b,org-backward-same-level}
1383 Previous heading same level.
1384 @orgcmd{C-c C-u,outline-up-heading}
1385 Backward to higher level heading.
1386 @orgcmd{C-c C-j,org-goto}
1387 Jump to a different place without changing the current outline
1388 visibility. Shows the document structure in a temporary buffer, where
1389 you can use the following keys to find your destination:
1390 @vindex org-goto-auto-isearch
1392 @key{TAB} @r{Cycle visibility.}
1393 @key{down} / @key{up} @r{Next/previous visible headline.}
1394 @key{RET} @r{Select this location.}
1395 @kbd{/} @r{Do a Sparse-tree search}
1396 @r{The following keys work if you turn off @code{org-goto-auto-isearch}}
1397 n / p @r{Next/previous visible headline.}
1398 f / b @r{Next/previous headline same level.}
1400 0-9 @r{Digit argument.}
1403 @vindex org-goto-interface
1405 See also the option @code{org-goto-interface}.
1408 @node Structure editing
1409 @section Structure editing
1410 @cindex structure editing
1411 @cindex headline, promotion and demotion
1412 @cindex promotion, of subtrees
1413 @cindex demotion, of subtrees
1414 @cindex subtree, cut and paste
1415 @cindex pasting, of subtrees
1416 @cindex cutting, of subtrees
1417 @cindex copying, of subtrees
1418 @cindex sorting, of subtrees
1419 @cindex subtrees, cut and paste
1422 @orgcmd{M-@key{RET},org-insert-heading}
1423 @vindex org-M-RET-may-split-line
1424 Insert a new heading/item with the same level as the one at point.
1425 If the cursor is in a plain list item, a new item is created
1426 (@pxref{Plain lists}). To prevent this behavior in lists, call the
1427 command with a prefix argument. When this command is used in the
1428 middle of a line, the line is split and the rest of the line becomes
1429 the new item or headline@footnote{If you do not want the line to be
1430 split, customize the variable @code{org-M-RET-may-split-line}.}. If
1431 the command is used at the @emph{beginning} of a headline, the new
1432 headline is created before the current line. If the command is used
1433 at the @emph{end} of a folded subtree (i.e., behind the ellipses at
1434 the end of a headline), then a headline will be
1435 inserted after the end of the subtree. Calling this command with
1436 @kbd{C-u C-u} will unconditionally respect the headline's content and
1437 create a new item at the end of the parent subtree.
1438 @orgcmd{C-@key{RET},org-insert-heading-respect-content}
1439 Just like @kbd{M-@key{RET}}, except when adding a new heading below the
1440 current heading, the new heading is placed after the body instead of before
1441 it. This command works from anywhere in the entry.
1442 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
1443 @vindex org-treat-insert-todo-heading-as-state-change
1444 Insert new TODO entry with same level as current heading. See also the
1445 variable @code{org-treat-insert-todo-heading-as-state-change}.
1446 @orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
1447 Insert new TODO entry with same level as current heading. Like
1448 @kbd{C-@key{RET}}, the new headline will be inserted after the current
1450 @orgcmd{@key{TAB},org-cycle}
1451 In a new entry with no text yet, the first @key{TAB} demotes the entry to
1452 become a child of the previous one. The next @key{TAB} makes it a parent,
1453 and so on, all the way to top level. Yet another @key{TAB}, and you are back
1454 to the initial level.
1455 @orgcmd{M-@key{left},org-do-promote}
1456 Promote current heading by one level.
1457 @orgcmd{M-@key{right},org-do-demote}
1458 Demote current heading by one level.
1459 @orgcmd{M-S-@key{left},org-promote-subtree}
1460 Promote the current subtree by one level.
1461 @orgcmd{M-S-@key{right},org-demote-subtree}
1462 Demote the current subtree by one level.
1463 @orgcmd{M-S-@key{up},org-move-subtree-up}
1464 Move subtree up (swap with previous subtree of same
1466 @orgcmd{M-S-@key{down},org-move-subtree-down}
1467 Move subtree down (swap with next subtree of same level).
1468 @orgcmd{M-h,org-mark-element}
1469 Mark the element at point. Hitting repeatedly will mark subsequent elements
1470 of the one just marked. E.g., hitting @key{M-h} on a paragraph will mark it,
1471 hitting @key{M-h} immediately again will mark the next one.
1472 @orgcmd{C-c @@,org-mark-subtree}
1473 Mark the subtree at point. Hitting repeatedly will mark subsequent subtrees
1474 of the same level than the marked subtree.
1475 @orgcmd{C-c C-x C-w,org-cut-subtree}
1476 Kill subtree, i.e., remove it from buffer but save in kill ring.
1477 With a numeric prefix argument N, kill N sequential subtrees.
1478 @orgcmd{C-c C-x M-w,org-copy-subtree}
1479 Copy subtree to kill ring. With a numeric prefix argument N, copy the N
1480 sequential subtrees.
1481 @orgcmd{C-c C-x C-y,org-paste-subtree}
1482 Yank subtree from kill ring. This does modify the level of the subtree to
1483 make sure the tree fits in nicely at the yank position. The yank level can
1484 also be specified with a numeric prefix argument, or by yanking after a
1485 headline marker like @samp{****}.
1486 @orgcmd{C-y,org-yank}
1487 @vindex org-yank-adjusted-subtrees
1488 @vindex org-yank-folded-subtrees
1489 Depending on the options @code{org-yank-adjusted-subtrees} and
1490 @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
1491 paste subtrees folded and in a clever way, using the same command as @kbd{C-c
1492 C-x C-y}. With the default settings, no level adjustment will take place,
1493 but the yanked tree will be folded unless doing so would swallow text
1494 previously visible. Any prefix argument to this command will force a normal
1495 @code{yank} to be executed, with the prefix passed along. A good way to
1496 force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a
1497 yank, it will yank previous kill items plainly, without adjustment and
1499 @orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
1500 Clone a subtree by making a number of sibling copies of it. You will be
1501 prompted for the number of copies to make, and you can also specify if any
1502 timestamps in the entry should be shifted. This can be useful, for example,
1503 to create a number of tasks related to a series of lectures to prepare. For
1504 more details, see the docstring of the command
1505 @code{org-clone-subtree-with-time-shift}.
1506 @orgcmd{C-c C-w,org-refile}
1507 Refile entry or region to a different location. @xref{Refile and copy}.
1508 @orgcmd{C-c ^,org-sort}
1509 Sort same-level entries. When there is an active region, all entries in the
1510 region will be sorted. Otherwise the children of the current headline are
1511 sorted. The command prompts for the sorting method, which can be
1512 alphabetically, numerically, by time (first timestamp with active preferred,
1513 creation time, scheduled time, deadline time), by priority, by TODO keyword
1514 (in the sequence the keywords have been defined in the setup) or by the value
1515 of a property. Reverse sorting is possible as well. You can also supply
1516 your own function to extract the sorting key. With a @kbd{C-u} prefix,
1517 sorting will be case-sensitive.
1518 @orgcmd{C-x n s,org-narrow-to-subtree}
1519 Narrow buffer to current subtree.
1520 @orgcmd{C-x n b,org-narrow-to-block}
1521 Narrow buffer to current block.
1522 @orgcmd{C-x n w,widen}
1523 Widen buffer to remove narrowing.
1524 @orgcmd{C-c *,org-toggle-heading}
1525 Turn a normal line or plain list item into a headline (so that it becomes a
1526 subheading at its location). Also turn a headline into a normal line by
1527 removing the stars. If there is an active region, turn all lines in the
1528 region into headlines. If the first line in the region was an item, turn
1529 only the item lines into headlines. Finally, if the first line is a
1530 headline, remove the stars from all headlines in the region.
1533 @cindex region, active
1534 @cindex active region
1535 @cindex transient mark mode
1536 When there is an active region (Transient Mark mode), promotion and
1537 demotion work on all headlines in the region. To select a region of
1538 headlines, it is best to place both point and mark at the beginning of a
1539 line, mark at the beginning of the first headline, and point at the line
1540 just after the last headline to change. Note that when the cursor is
1541 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
1546 @section Sparse trees
1547 @cindex sparse trees
1548 @cindex trees, sparse
1549 @cindex folding, sparse trees
1550 @cindex occur, command
1552 @vindex org-show-hierarchy-above
1553 @vindex org-show-following-heading
1554 @vindex org-show-siblings
1555 @vindex org-show-entry-below
1556 An important feature of Org mode is the ability to construct @emph{sparse
1557 trees} for selected information in an outline tree, so that the entire
1558 document is folded as much as possible, but the selected information is made
1559 visible along with the headline structure above it@footnote{See also the
1560 variables @code{org-show-hierarchy-above}, @code{org-show-following-heading},
1561 @code{org-show-siblings}, and @code{org-show-entry-below} for detailed
1562 control on how much context is shown around each match.}. Just try it out
1563 and you will see immediately how it works.
1565 Org mode contains several commands for creating such trees, all these
1566 commands can be accessed through a dispatcher:
1569 @orgcmd{C-c /,org-sparse-tree}
1570 This prompts for an extra key to select a sparse-tree creating command.
1571 @orgcmd{C-c / r,org-occur}
1572 @vindex org-remove-highlights-with-change
1573 Prompts for a regexp and shows a sparse tree with all matches. If
1574 the match is in a headline, the headline is made visible. If the match is in
1575 the body of an entry, headline and body are made visible. In order to
1576 provide minimal context, also the full hierarchy of headlines above the match
1577 is shown, as well as the headline following the match. Each match is also
1578 highlighted; the highlights disappear when the buffer is changed by an
1579 editing command@footnote{This depends on the option
1580 @code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
1581 When called with a @kbd{C-u} prefix argument, previous highlights are kept,
1582 so several calls to this command can be stacked.
1583 @orgcmdkkc{M-g n,M-g M-n,next-error}
1584 Jump to the next sparse tree match in this buffer.
1585 @orgcmdkkc{M-g p,M-g M-p,previous-error}
1586 Jump to the previous sparse tree match in this buffer.
1590 @vindex org-agenda-custom-commands
1591 For frequently used sparse trees of specific search strings, you can
1592 use the option @code{org-agenda-custom-commands} to define fast
1593 keyboard access to specific sparse trees. These commands will then be
1594 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
1598 (setq org-agenda-custom-commands
1599 '(("f" occur-tree "FIXME")))
1602 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
1603 a sparse tree matching the string @samp{FIXME}.
1605 The other sparse tree commands select headings based on TODO keywords,
1606 tags, or properties and will be discussed later in this manual.
1609 @cindex printing sparse trees
1610 @cindex visible text, printing
1611 To print a sparse tree, you can use the Emacs command
1612 @code{ps-print-buffer-with-faces} which does not print invisible parts
1613 of the document @footnote{This does not work under XEmacs, because
1614 XEmacs uses selective display for outlining, not text properties.}.
1615 Or you can use @kbd{C-c C-e C-v} to export only the visible part of
1616 the document and print the resulting file.
1619 @section Plain lists
1621 @cindex lists, plain
1622 @cindex lists, ordered
1623 @cindex ordered lists
1625 Within an entry of the outline tree, hand-formatted lists can provide
1626 additional structure. They also provide a way to create lists of checkboxes
1627 (@pxref{Checkboxes}). Org supports editing such lists, and every exporter
1628 (@pxref{Exporting}) can parse and format them.
1630 Org knows ordered lists, unordered lists, and description lists.
1633 @emph{Unordered} list items start with @samp{-}, @samp{+}, or
1634 @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
1635 they will be seen as top-level headlines. Also, when you are hiding leading
1636 stars to get a clean outline view, plain list items starting with a star may
1637 be hard to distinguish from true headlines. In short: even though @samp{*}
1638 is supported, it may be better to not use it for plain list items.} as
1641 @vindex org-plain-list-ordered-item-terminator
1642 @vindex org-list-allow-alphabetical
1643 @emph{Ordered} list items start with a numeral followed by either a period or
1644 a right parenthesis@footnote{You can filter out any of them by configuring
1645 @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
1646 @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
1647 @samp{A)} by configuring @code{org-list-allow-alphabetical}. To minimize
1648 confusion with normal text, those are limited to one character only. Beyond
1649 that limit, bullets will automatically fallback to numbers.}. If you want a
1650 list to start with a different value (e.g., 20), start the text of the item
1651 with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
1652 must be put @emph{before} the checkbox. If you have activated alphabetical
1653 lists, you can also use counters like @code{[@@b]}.}. Those constructs can
1654 be used in any item of the list in order to enforce a particular numbering.
1656 @emph{Description} list items are unordered list items, and contain the
1657 separator @samp{ :: } to distinguish the description @emph{term} from the
1661 Items belonging to the same list must have the same indentation on the first
1662 line. In particular, if an ordered list reaches number @samp{10.}, then the
1663 2--digit numbers must be written left-aligned with the other numbers in the
1664 list. An item ends before the next line that is less or equally indented
1665 than its bullet/number.
1667 @vindex org-list-empty-line-terminates-plain-lists
1668 A list ends whenever every item has ended, which means before any line less
1669 or equally indented than items at top level. It also ends before two blank
1670 lines@footnote{See also @code{org-list-empty-line-terminates-plain-lists}.}.
1671 In that case, all items are closed. Here is an example:
1675 ** Lord of the Rings
1676 My favorite scenes are (in this order)
1677 1. The attack of the Rohirrim
1678 2. Eowyn's fight with the witch king
1679 + this was already my favorite scene in the book
1680 + I really like Miranda Otto.
1681 3. Peter Jackson being shot by Legolas
1683 He makes a really funny face when it happens.
1684 But in the end, no individual scenes matter but the film as a whole.
1685 Important actors in this film are:
1686 - @b{Elijah Wood} :: He plays Frodo
1687 - @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember
1688 him very well from his role as Mikey Walsh in @i{The Goonies}.
1692 Org supports these lists by tuning filling and wrapping commands to deal with
1693 them correctly@footnote{Org only changes the filling settings for Emacs. For
1694 XEmacs, you should use Kyle E. Jones' @file{filladapt.el}. To turn this on,
1695 put into @file{.emacs}: @code{(require 'filladapt)}}, and by exporting them
1696 properly (@pxref{Exporting}). Since indentation is what governs the
1697 structure of these lists, many structural constructs like @code{#+BEGIN_...}
1698 blocks can be indented to signal that they belong to a particular item.
1700 @vindex org-list-demote-modify-bullet
1701 @vindex org-list-indent-offset
1702 If you find that using a different bullet for a sub-list (than that used for
1703 the current list-level) improves readability, customize the variable
1704 @code{org-list-demote-modify-bullet}. To get a greater difference of
1705 indentation between items and their sub-items, customize
1706 @code{org-list-indent-offset}.
1708 @vindex org-list-automatic-rules
1709 The following commands act on items when the cursor is in the first line of
1710 an item (the line with the bullet or number). Some of them imply the
1711 application of automatic rules to keep list structure intact. If some of
1712 these actions get in your way, configure @code{org-list-automatic-rules}
1713 to disable them individually.
1716 @orgcmd{@key{TAB},org-cycle}
1717 @cindex cycling, in plain lists
1718 @vindex org-cycle-include-plain-lists
1719 Items can be folded just like headline levels. Normally this works only if
1720 the cursor is on a plain list item. For more details, see the variable
1721 @code{org-cycle-include-plain-lists}. If this variable is set to
1722 @code{integrate}, plain list items will be treated like low-level
1723 headlines. The level of an item is then given by the indentation of the
1724 bullet/number. Items are always subordinate to real headlines, however; the
1725 hierarchies remain completely separated. In a new item with no text yet, the
1726 first @key{TAB} demotes the item to become a child of the previous
1727 one. Subsequent @key{TAB}s move the item to meaningful levels in the list
1728 and eventually get it back to its initial position.
1729 @orgcmd{M-@key{RET},org-insert-heading}
1730 @vindex org-M-RET-may-split-line
1731 @vindex org-list-automatic-rules
1732 Insert new item at current level. With a prefix argument, force a new
1733 heading (@pxref{Structure editing}). If this command is used in the middle
1734 of an item, that item is @emph{split} in two, and the second part becomes the
1735 new item@footnote{If you do not want the item to be split, customize the
1736 variable @code{org-M-RET-may-split-line}.}. If this command is executed
1737 @emph{before item's body}, the new item is created @emph{before} the current
1742 @kindex M-S-@key{RET}
1744 Insert a new item with a checkbox (@pxref{Checkboxes}).
1745 @kindex S-@key{down}
1748 @cindex shift-selection-mode
1749 @vindex org-support-shift-select
1750 @vindex org-list-use-circular-motion
1751 Jump to the previous/next item in the current list@footnote{If you want to
1752 cycle around items that way, you may customize
1753 @code{org-list-use-circular-motion}.}, but only if
1754 @code{org-support-shift-select} is off. If not, you can still use paragraph
1755 jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
1758 @kindex M-@key{down}
1761 Move the item including subitems up/down@footnote{See
1762 @code{org-list-use-circular-motion} for a cyclic behavior.} (swap with
1763 previous/next item of same indentation). If the list is ordered, renumbering
1765 @kindex M-@key{left}
1766 @kindex M-@key{right}
1769 Decrease/increase the indentation of an item, leaving children alone.
1770 @kindex M-S-@key{left}
1771 @kindex M-S-@key{right}
1772 @item M-S-@key{left}
1773 @itemx M-S-@key{right}
1774 Decrease/increase the indentation of the item, including subitems.
1775 Initially, the item tree is selected based on current indentation. When
1776 these commands are executed several times in direct succession, the initially
1777 selected region is used, even if the new indentation would imply a different
1778 hierarchy. To use the new hierarchy, break the command chain with a cursor
1781 As a special case, using this command on the very first item of a list will
1782 move the whole list. This behavior can be disabled by configuring
1783 @code{org-list-automatic-rules}. The global indentation of a list has no
1784 influence on the text @emph{after} the list.
1787 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1788 state of the checkbox. In any case, verify bullets and indentation
1789 consistency in the whole list.
1791 @vindex org-plain-list-ordered-item-terminator
1793 Cycle the entire list level through the different itemize/enumerate bullets
1794 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
1795 depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
1796 and its indentation. With a numeric prefix argument N, select the Nth bullet
1797 from this list. If there is an active region when calling this, selected
1798 text will be changed into an item. With a prefix argument, all lines will be
1799 converted to list items. If the first line already was a list item, any item
1800 marker will be removed from the list. Finally, even without an active
1801 region, a normal line will be converted into a list item.
1804 Turn a plain list item into a headline (so that it becomes a subheading at
1805 its location). @xref{Structure editing}, for a detailed explanation.
1808 Turn the whole plain list into a subtree of the current heading. Checkboxes
1809 (@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
1811 @kindex S-@key{left}
1812 @kindex S-@key{right}
1814 @vindex org-support-shift-select
1815 This command also cycles bullet styles when the cursor in on the bullet or
1816 anywhere in an item line, details depending on
1817 @code{org-support-shift-select}.
1819 @cindex sorting, of plain list
1821 Sort the plain list. You will be prompted for the sorting method:
1822 numerically, alphabetically, by time, by checked status for check lists,
1823 or by a custom function.
1829 @cindex visibility cycling, drawers
1831 @cindex org-insert-drawer
1833 Sometimes you want to keep information associated with an entry, but you
1834 normally don't want to see it. For this, Org mode has @emph{drawers}. They
1835 can contain anything but a headline and another drawer. Drawers look like
1839 ** This is a headline
1840 Still outside the drawer
1842 This is inside the drawer.
1847 You can interactively insert drawers at point by calling
1848 @code{org-insert-drawer}, which is bound to @key{C-c C-x d}. With an active
1849 region, this command will put the region inside the drawer. With a prefix
1850 argument, this command calls @code{org-insert-property-drawer} and add a
1851 property drawer right below the current headline. Completion over drawer
1852 keywords is also possible using @key{M-TAB}.
1854 Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
1855 show the entry, but keep the drawer collapsed to a single line. In order to
1856 look inside the drawer, you need to move the cursor to the drawer line and
1857 press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
1858 storing properties (@pxref{Properties and columns}), and you can also arrange
1859 for state change notes (@pxref{Tracking TODO state changes}) and clock times
1860 (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
1861 want to store a quick note in the LOGBOOK drawer, in a similar way to state
1867 Add a time-stamped note to the LOGBOOK drawer.
1870 @vindex org-export-with-drawers
1871 @vindex org-export-with-properties
1872 You can select the name of the drawers which should be exported with
1873 @code{org-export-with-drawers}. In that case, drawer contents will appear in
1874 export output. Property drawers are not affected by this variable: configure
1875 @code{org-export-with-properties} instead.
1880 @vindex org-hide-block-startup
1881 @cindex blocks, folding
1882 Org mode uses begin...end blocks for various purposes from including source
1883 code examples (@pxref{Literal examples}) to capturing time logging
1884 information (@pxref{Clocking work time}). These blocks can be folded and
1885 unfolded by pressing TAB in the begin line. You can also get all blocks
1886 folded at startup by configuring the option @code{org-hide-block-startup}
1887 or on a per-file basis by using
1889 @cindex @code{hideblocks}, STARTUP keyword
1890 @cindex @code{nohideblocks}, STARTUP keyword
1892 #+STARTUP: hideblocks
1893 #+STARTUP: nohideblocks
1900 Org mode supports the creation of footnotes. In contrast to the
1901 @file{footnote.el} package, Org mode's footnotes are designed for work on
1902 a larger document, not only for one-off documents like emails.
1904 A footnote is started by a footnote marker in square brackets in column 0, no
1905 indentation allowed. It ends at the next footnote definition, headline, or
1906 after two consecutive empty lines. The footnote reference is simply the
1907 marker in square brackets, inside text. For example:
1910 The Org homepage[fn:1] now looks a lot better than it used to.
1912 [fn:1] The link is: http://orgmode.org
1915 Org mode extends the number-based syntax to @emph{named} footnotes and
1916 optional inline definition. Using plain numbers as markers (as
1917 @file{footnote.el} does) is supported for backward compatibility, but not
1918 encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded
1919 @LaTeX{}}). Here are the valid references:
1923 A plain numeric footnote marker. Compatible with @file{footnote.el}, but not
1924 recommended because something like @samp{[1]} could easily be part of a code
1927 A named footnote reference, where @code{name} is a unique label word, or, for
1928 simplicity of automatic creation, a number.
1929 @item [fn:: This is the inline definition of this footnote]
1930 A @LaTeX{}-like anonymous footnote where the definition is given directly at the
1932 @item [fn:name: a definition]
1933 An inline definition of a footnote, which also specifies a name for the note.
1934 Since Org allows multiple references to the same note, you can then use
1935 @code{[fn:name]} to create additional references.
1938 @vindex org-footnote-auto-label
1939 Footnote labels can be created automatically, or you can create names yourself.
1940 This is handled by the variable @code{org-footnote-auto-label} and its
1941 corresponding @code{#+STARTUP} keywords. See the docstring of that variable
1944 @noindent The following command handles footnotes:
1949 The footnote action command.
1951 When the cursor is on a footnote reference, jump to the definition. When it
1952 is at a definition, jump to the (first) reference.
1954 @vindex org-footnote-define-inline
1955 @vindex org-footnote-section
1956 @vindex org-footnote-auto-adjust
1957 Otherwise, create a new footnote. Depending on the option
1958 @code{org-footnote-define-inline}@footnote{The corresponding in-buffer
1959 setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
1960 definition will be placed right into the text as part of the reference, or
1961 separately into the location determined by the option
1962 @code{org-footnote-section}.
1964 When this command is called with a prefix argument, a menu of additional
1967 s @r{Sort the footnote definitions by reference sequence. During editing,}
1968 @r{Org makes no effort to sort footnote definitions into a particular}
1969 @r{sequence. If you want them sorted, use this command, which will}
1970 @r{also move entries according to @code{org-footnote-section}. Automatic}
1971 @r{sorting after each insertion/deletion can be configured using the}
1972 @r{option @code{org-footnote-auto-adjust}.}
1973 r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering}
1974 @r{after each insertion/deletion can be configured using the option}
1975 @r{@code{org-footnote-auto-adjust}.}
1976 S @r{Short for first @code{r}, then @code{s} action.}
1977 n @r{Normalize the footnotes by collecting all definitions (including}
1978 @r{inline definitions) into a special section, and then numbering them}
1979 @r{in sequence. The references will then also be numbers. This is}
1980 @r{meant to be the final step before finishing a document (e.g., sending}
1982 d @r{Delete the footnote at point, and all definitions of and references}
1985 Depending on the variable @code{org-footnote-auto-adjust}@footnote{the
1986 corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},
1987 renumbering and sorting footnotes can be automatic after each insertion or
1992 If the cursor is on a footnote reference, jump to the definition. If it is a
1993 the definition, jump back to the reference. When called at a footnote
1994 location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
1998 @item C-c C-o @r{or} mouse-1/2
1999 Footnote labels are also links to the corresponding definition/reference, and
2000 you can use the usual commands to follow these links.
2003 @node Orgstruct mode
2004 @section The Orgstruct minor mode
2005 @cindex Orgstruct mode
2006 @cindex minor mode for structure editing
2008 If you like the intuitive way the Org mode structure editing and list
2009 formatting works, you might want to use these commands in other modes like
2010 Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes
2011 this possible. Toggle the mode with @kbd{M-x orgstruct-mode RET}, or
2012 turn it on by default, for example in Message mode, with one of:
2015 (add-hook 'message-mode-hook 'turn-on-orgstruct)
2016 (add-hook 'message-mode-hook 'turn-on-orgstruct++)
2019 When this mode is active and the cursor is on a line that looks to Org like a
2020 headline or the first line of a list item, most structure editing commands
2021 will work, even if the same keys normally have different functionality in the
2022 major mode you are using. If the cursor is not in one of those special
2023 lines, Orgstruct mode lurks silently in the shadows.
2025 When you use @code{orgstruct++-mode}, Org will also export indentation and
2026 autofill settings into that mode, and detect item context after the first
2029 @vindex orgstruct-heading-prefix-regexp
2030 You can also use Org structure editing to fold and unfold headlines in
2031 @emph{any} file, provided you defined @code{orgstruct-heading-prefix-regexp}:
2032 the regular expression must match the local prefix to use before Org's
2033 headlines. For example, if you set this variable to @code{";; "} in Emacs
2034 Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
2035 commented lines. Some commands like @code{org-demote} are disabled when the
2036 prefix is set, but folding/unfolding will work correctly.
2042 A reference document providing a formal description of Org's syntax is
2043 available as @uref{http://orgmode.org/worg/dev/org-syntax.html, a draft on
2044 Worg}, written and maintained by Nicolas Goaziou. It defines Org's core
2045 internal concepts such as @code{headlines}, @code{sections}, @code{affiliated
2046 keywords}, @code{(greater) elements} and @code{objects}. Each part of an Org
2047 file falls into one of the categories above.
2049 To explore the abstract structure of an Org buffer, run this in a buffer:
2052 M-: (org-element-parse-buffer) RET
2055 It will output a list containing the buffer's content represented as an
2056 abstract structure. The export engine relies on the information stored in
2057 this list. Most interactive commands (e.g., for structure editing) also
2058 rely on the syntactic meaning of the surrounding context.
2063 @cindex editing tables
2065 Org comes with a fast and intuitive table editor. Spreadsheet-like
2066 calculations are supported using the Emacs @file{calc} package
2067 (@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}).
2070 * Built-in table editor:: Simple tables
2071 * Column width and alignment:: Overrule the automatic settings
2072 * Column groups:: Grouping to trigger vertical lines
2073 * Orgtbl mode:: The table editor as minor mode
2074 * The spreadsheet:: The table editor has spreadsheet capabilities
2075 * Org-Plot:: Plotting from org tables
2078 @node Built-in table editor
2079 @section The built-in table editor
2080 @cindex table editor, built-in
2082 Org makes it easy to format tables in plain ASCII@. Any line with @samp{|} as
2083 the first non-whitespace character is considered part of a table. @samp{|}
2084 is also the column separator@footnote{To insert a vertical bar into a table
2085 field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table
2086 might look like this:
2089 | Name | Phone | Age |
2090 |-------+-------+-----|
2091 | Peter | 1234 | 17 |
2092 | Anna | 4321 | 25 |
2095 A table is re-aligned automatically each time you press @key{TAB} or
2096 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
2097 the next field (@key{RET} to the next row) and creates new table rows
2098 at the end of the table or before horizontal lines. The indentation
2099 of the table is set by the first line. Any line starting with
2100 @samp{|-} is considered as a horizontal separator line and will be
2101 expanded on the next re-align to span the whole table width. So, to
2102 create the above table, you would only type
2109 @noindent and then press @key{TAB} to align the table and start filling in
2110 fields. Even faster would be to type @code{|Name|Phone|Age} followed by
2111 @kbd{C-c @key{RET}}.
2113 @vindex org-enable-table-editor
2114 @vindex org-table-auto-blank-field
2115 When typing text into a field, Org treats @key{DEL},
2116 @key{Backspace}, and all character keys in a special way, so that
2117 inserting and deleting avoids shifting other fields. Also, when
2118 typing @emph{immediately after the cursor was moved into a new field
2119 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
2120 field is automatically made blank. If this behavior is too
2121 unpredictable for you, configure the options
2122 @code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
2125 @tsubheading{Creation and conversion}
2126 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2127 Convert the active region to a table. If every line contains at least one
2128 TAB character, the function assumes that the material is tab separated.
2129 If every line contains a comma, comma-separated values (CSV) are assumed.
2130 If not, lines are split at whitespace into fields. You can use a prefix
2131 argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
2132 C-u} forces TAB, @kbd{C-u C-u C-u} will prompt for a regular expression to
2133 match the separator, and a numeric argument N indicates that at least N
2134 consecutive spaces, or alternatively a TAB will be the separator.
2136 If there is no active region, this command creates an empty Org
2137 table. But it is easier just to start typing, like
2138 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
2140 @tsubheading{Re-aligning and field motion}
2141 @orgcmd{C-c C-c,org-table-align}
2142 Re-align the table and don't move to another field.
2144 @orgcmd{<TAB>,org-table-next-field}
2145 Re-align the table, move to the next field. Creates a new row if
2148 @orgcmd{S-@key{TAB},org-table-previous-field}
2149 Re-align, move to previous field.
2151 @orgcmd{@key{RET},org-table-next-row}
2152 Re-align the table and move down to next row. Creates a new row if
2153 necessary. At the beginning or end of a line, @key{RET} still does
2154 NEWLINE, so it can be used to split a table.
2156 @orgcmd{M-a,org-table-beginning-of-field}
2157 Move to beginning of the current table field, or on to the previous field.
2158 @orgcmd{M-e,org-table-end-of-field}
2159 Move to end of the current table field, or on to the next field.
2161 @tsubheading{Column and row editing}
2162 @orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
2163 Move the current column left/right.
2165 @orgcmd{M-S-@key{left},org-table-delete-column}
2166 Kill the current column.
2168 @orgcmd{M-S-@key{right},org-table-insert-column}
2169 Insert a new column to the left of the cursor position.
2171 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
2172 Move the current row up/down.
2174 @orgcmd{M-S-@key{up},org-table-kill-row}
2175 Kill the current row or horizontal line.
2177 @orgcmd{M-S-@key{down},org-table-insert-row}
2178 Insert a new row above the current row. With a prefix argument, the line is
2179 created below the current one.
2181 @orgcmd{C-c -,org-table-insert-hline}
2182 Insert a horizontal line below current row. With a prefix argument, the line
2183 is created above the current line.
2185 @orgcmd{C-c @key{RET},org-table-hline-and-move}
2186 Insert a horizontal line below current row, and move the cursor into the row
2189 @orgcmd{C-c ^,org-table-sort-lines}
2190 Sort the table lines in the region. The position of point indicates the
2191 column to be used for sorting, and the range of lines is the range
2192 between the nearest horizontal separator lines, or the entire table. If
2193 point is before the first column, you will be prompted for the sorting
2194 column. If there is an active region, the mark specifies the first line
2195 and the sorting column, while point should be in the last line to be
2196 included into the sorting. The command prompts for the sorting type
2197 (alphabetically, numerically, or by time). When called with a prefix
2198 argument, alphabetic sorting will be case-sensitive.
2200 @tsubheading{Regions}
2201 @orgcmd{C-c C-x M-w,org-table-copy-region}
2202 Copy a rectangular region from a table to a special clipboard. Point and
2203 mark determine edge fields of the rectangle. If there is no active region,
2204 copy just the current field. The process ignores horizontal separator lines.
2206 @orgcmd{C-c C-x C-w,org-table-cut-region}
2207 Copy a rectangular region from a table to a special clipboard, and
2208 blank all fields in the rectangle. So this is the ``cut'' operation.
2210 @orgcmd{C-c C-x C-y,org-table-paste-rectangle}
2211 Paste a rectangular region into a table.
2212 The upper left corner ends up in the current field. All involved fields
2213 will be overwritten. If the rectangle does not fit into the present table,
2214 the table is enlarged as needed. The process ignores horizontal separator
2217 @orgcmd{M-@key{RET},org-table-wrap-region}
2218 Split the current field at the cursor position and move the rest to the line
2219 below. If there is an active region, and both point and mark are in the same
2220 column, the text in the column is wrapped to minimum width for the given
2221 number of lines. A numeric prefix argument may be used to change the number
2222 of desired lines. If there is no region, but you specify a prefix argument,
2223 the current field is made blank, and the content is appended to the field
2226 @tsubheading{Calculations}
2227 @cindex formula, in tables
2228 @cindex calculations, in tables
2229 @cindex region, active
2230 @cindex active region
2231 @cindex transient mark mode
2232 @orgcmd{C-c +,org-table-sum}
2233 Sum the numbers in the current column, or in the rectangle defined by
2234 the active region. The result is shown in the echo area and can
2235 be inserted with @kbd{C-y}.
2237 @orgcmd{S-@key{RET},org-table-copy-down}
2238 @vindex org-table-copy-increment
2239 When current field is empty, copy from first non-empty field above. When not
2240 empty, copy current field down to next row and move cursor along with it.
2241 Depending on the option @code{org-table-copy-increment}, integer field
2242 values will be incremented during copy. Integers that are too large will not
2243 be incremented. Also, a @code{0} prefix argument temporarily disables the
2244 increment. This key is also used by shift-selection and related modes
2245 (@pxref{Conflicts}).
2247 @tsubheading{Miscellaneous}
2248 @orgcmd{C-c `,org-table-edit-field}
2249 Edit the current field in a separate window. This is useful for fields that
2250 are not fully visible (@pxref{Column width and alignment}). When called with
2251 a @kbd{C-u} prefix, just make the full field visible, so that it can be
2252 edited in place. When called with two @kbd{C-u} prefixes, make the editor
2253 window follow the cursor through the table and always show the current
2254 field. The follow mode exits automatically when the cursor leaves the table,
2255 or when you repeat this command with @kbd{C-u C-u C-c `}.
2257 @item M-x org-table-import RET
2258 Import a file as a table. The table should be TAB or whitespace
2259 separated. Use, for example, to import a spreadsheet table or data
2260 from a database, because these programs generally can write
2261 TAB-separated text files. This command works by inserting the file into
2262 the buffer and then converting the region to a table. Any prefix
2263 argument is passed on to the converter, which uses it to determine the
2265 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2266 Tables can also be imported by pasting tabular text into the Org
2267 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
2268 @kbd{C-c |} command (see above under @i{Creation and conversion}).
2270 @item M-x org-table-export RET
2271 @findex org-table-export
2272 @vindex org-table-export-default-format
2273 Export the table, by default as a TAB-separated file. Use for data
2274 exchange with, for example, spreadsheet or database programs. The format
2275 used to export the file can be configured in the option
2276 @code{org-table-export-default-format}. You may also use properties
2277 @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
2278 name and the format for table export in a subtree. Org supports quite
2279 general formats for exported tables. The exporter format is the same as the
2280 format used by Orgtbl radio tables, see @ref{Translator functions}, for a
2281 detailed description.
2284 If you don't like the automatic table editor because it gets in your
2285 way on lines which you would like to start with @samp{|}, you can turn
2289 (setq org-enable-table-editor nil)
2292 @noindent Then the only table command that still works is
2293 @kbd{C-c C-c} to do a manual re-align.
2295 @node Column width and alignment
2296 @section Column width and alignment
2297 @cindex narrow columns in tables
2298 @cindex alignment in tables
2300 The width of columns is automatically determined by the table editor. And
2301 also the alignment of a column is determined automatically from the fraction
2302 of number-like versus non-number fields in the column.
2304 Sometimes a single field or a few fields need to carry more text, leading to
2305 inconveniently wide columns. Or maybe you want to make a table with several
2306 columns having a fixed width, regardless of content. To set@footnote{This
2307 feature does not work on XEmacs.} the width of a column, one field anywhere
2308 in the column may contain just the string @samp{<N>} where @samp{N} is an
2309 integer specifying the width of the column in characters. The next re-align
2310 will then set the width of this column to this value.
2314 |---+------------------------------| |---+--------|
2316 | 1 | one | | 1 | one |
2317 | 2 | two | ----\ | 2 | two |
2318 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
2319 | 4 | four | | 4 | four |
2320 |---+------------------------------| |---+--------|
2325 Fields that are wider become clipped and end in the string @samp{=>}.
2326 Note that the full text is still in the buffer but is hidden.
2327 To see the full text, hold the mouse over the field---a tool-tip window
2328 will show the full content. To edit such a field, use the command
2329 @kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will
2330 open a new window with the full field. Edit it and finish with @kbd{C-c
2333 @vindex org-startup-align-all-tables
2334 When visiting a file containing a table with narrowed columns, the
2335 necessary character hiding has not yet happened, and the table needs to
2336 be aligned before it looks nice. Setting the option
2337 @code{org-startup-align-all-tables} will realign all tables in a file
2338 upon visiting, but also slow down startup. You can also set this option
2339 on a per-file basis with:
2346 If you would like to overrule the automatic alignment of number-rich columns
2347 to the right and of string-rich column to the left, you can use @samp{<r>},
2348 @samp{<c>}@footnote{Centering does not work inside Emacs, but it does have an
2349 effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may
2350 also combine alignment and field width like this: @samp{<r10>}.
2352 Lines which only contain these formatting cookies will be removed
2353 automatically when exporting the document.
2356 @section Column groups
2357 @cindex grouping columns in tables
2359 When Org exports tables, it does so by default without vertical
2360 lines because that is visually more satisfying in general. Occasionally
2361 however, vertical lines can be useful to structure a table into groups
2362 of columns, much like horizontal lines can do for groups of rows. In
2363 order to specify column groups, you can use a special row where the
2364 first field contains only @samp{/}. The further fields can either
2365 contain @samp{<} to indicate that this column should start a group,
2366 @samp{>} to indicate the end of a column, or @samp{<>} (no space between @samp{<}
2367 and @samp{>}) to make a column
2368 a group of its own. Boundaries between column groups will upon export be
2369 marked with vertical lines. Here is an example:
2372 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2373 |---+-----+-----+-----+---------+------------|
2374 | / | < | | > | < | > |
2375 | 1 | 1 | 1 | 1 | 1 | 1 |
2376 | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
2377 | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
2378 |---+-----+-----+-----+---------+------------|
2379 #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
2382 It is also sufficient to just insert the column group starters after
2383 every vertical line you would like to have:
2386 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2387 |----+-----+-----+-----+---------+------------|
2392 @section The Orgtbl minor mode
2394 @cindex minor mode for tables
2396 If you like the intuitive way the Org table editor works, you
2397 might also want to use it in other modes like Text mode or Mail mode.
2398 The minor mode Orgtbl mode makes this possible. You can always toggle
2399 the mode with @kbd{M-x orgtbl-mode RET}. To turn it on by default, for
2400 example in Message mode, use
2403 (add-hook 'message-mode-hook 'turn-on-orgtbl)
2406 Furthermore, with some special setup, it is possible to maintain tables
2407 in arbitrary syntax with Orgtbl mode. For example, it is possible to
2408 construct @LaTeX{} tables with the underlying ease and power of
2409 Orgtbl mode, including spreadsheet capabilities. For details, see
2410 @ref{Tables in arbitrary syntax}.
2412 @node The spreadsheet
2413 @section The spreadsheet
2414 @cindex calculations, in tables
2415 @cindex spreadsheet capabilities
2416 @cindex @file{calc} package
2418 The table editor makes use of the Emacs @file{calc} package to implement
2419 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
2420 derive fields from other fields. While fully featured, Org's implementation
2421 is not identical to other spreadsheets. For example, Org knows the concept
2422 of a @emph{column formula} that will be applied to all non-header fields in a
2423 column without having to copy the formula to each relevant field. There is
2424 also a formula debugger, and a formula editor with features for highlighting
2425 fields in the table corresponding to the references at the point in the
2426 formula, moving these references by arrow keys
2429 * References:: How to refer to another field or range
2430 * Formula syntax for Calc:: Using Calc to compute stuff
2431 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
2432 * Durations and time values:: How to compute durations and time values
2433 * Field and range formulas:: Formula for specific (ranges of) fields
2434 * Column formulas:: Formulas valid for an entire column
2435 * Lookup functions:: Lookup functions for searching tables
2436 * Editing and debugging formulas:: Fixing formulas
2437 * Updating the table:: Recomputing all dependent fields
2438 * Advanced features:: Field and column names, parameters and automatic recalc
2442 @subsection References
2445 To compute fields in the table from other fields, formulas must
2446 reference other fields or ranges. In Org, fields can be referenced
2447 by name, by absolute coordinates, and by relative coordinates. To find
2448 out what the coordinates of a field are, press @kbd{C-c ?} in that
2449 field, or press @kbd{C-c @}} to toggle the display of a grid.
2451 @subsubheading Field references
2452 @cindex field references
2453 @cindex references, to fields
2455 Formulas can reference the value of another field in two ways. Like in
2456 any other spreadsheet, you may reference fields with a letter/number
2457 combination like @code{B3}, meaning the 2nd field in the 3rd row.
2458 @vindex org-table-use-standard-references
2459 However, Org prefers@footnote{Org will understand references typed by the
2460 user as @samp{B4}, but it will not use this syntax when offering a formula
2461 for editing. You can customize this behavior using the option
2462 @code{org-table-use-standard-references}.} to use another, more general
2463 representation that looks like this:
2465 @@@var{row}$@var{column}
2468 Column specifications can be absolute like @code{$1},
2469 @code{$2},...@code{$@var{N}}, or relative to the current column (i.e., the
2470 column of the field which is being computed) like @code{$+1} or @code{$-2}.
2471 @code{$<} and @code{$>} are immutable references to the first and last
2472 column, respectively, and you can use @code{$>>>} to indicate the third
2473 column from the right.
2475 The row specification only counts data lines and ignores horizontal separator
2476 lines (hlines). Like with columns, you can use absolute row numbers
2477 @code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
2478 current row like @code{@@+3} or @code{@@-1}. @code{@@<} and @code{@@>} are
2479 immutable references the first and last@footnote{For backward compatibility
2480 you can also use special names like @code{$LR5} and @code{$LR12} to refer in
2481 a stable way to the 5th and 12th field in the last row of the table.
2482 However, this syntax is deprecated, it should not be used for new documents.
2483 Use @code{@@>$} instead.} row in the table, respectively. You may also
2484 specify the row relative to one of the hlines: @code{@@I} refers to the first
2485 hline, @code{@@II} to the second, etc. @code{@@-I} refers to the first such
2486 line above the current line, @code{@@+I} to the first such line below the
2487 current line. You can also write @code{@@III+2} which is the second data line
2488 after the third hline in the table.
2490 @code{@@0} and @code{$0} refer to the current row and column, respectively,
2491 i.e., to the row/column for the field being computed. Also, if you omit
2492 either the column or the row part of the reference, the current row/column is
2495 Org's references with @emph{unsigned} numbers are fixed references
2496 in the sense that if you use the same reference in the formula for two
2497 different fields, the same field will be referenced each time.
2498 Org's references with @emph{signed} numbers are floating
2499 references because the same reference operator can reference different
2500 fields depending on the field being calculated by the formula.
2502 Here are a few examples:
2505 @@2$3 @r{2nd row, 3rd column (same as @code{C2})}
2506 $5 @r{column 5 in the current row (same as @code{E&})}
2507 @@2 @r{current column, row 2}
2508 @@-1$-3 @r{the field one row up, three columns to the left}
2509 @@-I$2 @r{field just under hline above current row, column 2}
2510 @@>$5 @r{field in the last row, in column 5}
2513 @subsubheading Range references
2514 @cindex range references
2515 @cindex references, to ranges
2517 You may reference a rectangular range of fields by specifying two field
2518 references connected by two dots @samp{..}. If both fields are in the
2519 current row, you may simply use @samp{$2..$7}, but if at least one field
2520 is in a different row, you need to use the general @code{@@row$column}
2521 format at least for the first field (i.e the reference must start with
2522 @samp{@@} in order to be interpreted correctly). Examples:
2525 $1..$3 @r{first three fields in the current row}
2526 $P..$Q @r{range, using column names (see under Advanced)}
2527 $<<<..$>> @r{start in third column, continue to the last but one}
2528 @@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
2529 @@-1$-2..@@-1 @r{3 fields in the row above, starting from 2 columns on the left}
2530 @@I..II @r{between first and second hline, short for @code{@@I..@@II}}
2533 @noindent Range references return a vector of values that can be fed
2534 into Calc vector functions. Empty fields in ranges are normally suppressed,
2535 so that the vector contains only the non-empty fields. For other options
2536 with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax
2539 @subsubheading Field coordinates in formulas
2540 @cindex field coordinates
2541 @cindex coordinates, of field
2542 @cindex row, of field coordinates
2543 @cindex column, of field coordinates
2545 One of the very first actions during evaluation of Calc formulas and Lisp
2546 formulas is to substitute @code{@@#} and @code{$#} in the formula with the
2547 row or column number of the field where the current result will go to. The
2548 traditional Lisp formula equivalents are @code{org-table-current-dline} and
2549 @code{org-table-current-column}. Examples:
2552 @item if(@@# % 2, $#, string(""))
2553 Insert column number on odd rows, set field to empty on even rows.
2554 @item $2 = '(identity remote(FOO, @@@@#$1))
2555 Copy text or values of each row of column 1 of the table named @code{FOO}
2556 into column 2 of the current table.
2557 @item @@3 = 2 * remote(FOO, @@1$$#)
2558 Insert the doubled value of each column of row 1 of the table named
2559 @code{FOO} into row 3 of the current table.
2562 @noindent For the second/third example, the table named @code{FOO} must have
2563 at least as many rows/columns as the current table. Note that this is
2564 inefficient@footnote{The computation time scales as O(N^2) because the table
2565 named @code{FOO} is parsed for each field to be read.} for large number of
2568 @subsubheading Named references
2569 @cindex named references
2570 @cindex references, named
2571 @cindex name, of column or field
2572 @cindex constants, in calculations
2575 @vindex org-table-formula-constants
2576 @samp{$name} is interpreted as the name of a column, parameter or
2577 constant. Constants are defined globally through the option
2578 @code{org-table-formula-constants}, and locally (for the file) through a
2582 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
2586 @vindex constants-unit-system
2587 @pindex constants.el
2588 Also properties (@pxref{Properties and columns}) can be used as
2589 constants in table formulas: for a property @samp{:Xyz:} use the name
2590 @samp{$PROP_Xyz}, and the property will be searched in the current
2591 outline entry and in the hierarchy above it. If you have the
2592 @file{constants.el} package, it will also be used to resolve constants,
2593 including natural constants like @samp{$h} for Planck's constant, and
2594 units like @samp{$km} for kilometers@footnote{@file{constants.el} can
2595 supply the values of constants in two different unit systems, @code{SI}
2596 and @code{cgs}. Which one is used depends on the value of the variable
2597 @code{constants-unit-system}. You can use the @code{#+STARTUP} options
2598 @code{constSI} and @code{constcgs} to set this value for the current
2599 buffer.}. Column names and parameters can be specified in special table
2600 lines. These are described below, see @ref{Advanced features}. All
2601 names must start with a letter, and further consist of letters and
2604 @subsubheading Remote references
2605 @cindex remote references
2606 @cindex references, remote
2607 @cindex references, to a different table
2608 @cindex name, of column or field
2609 @cindex constants, in calculations
2610 @cindex #+NAME, for table
2612 You may also reference constants, fields and ranges from a different table,
2613 either in the current file or even in a different file. The syntax is
2616 remote(NAME-OR-ID,REF)
2620 where NAME can be the name of a table in the current file as set by a
2621 @code{#+NAME: Name} line before the table. It can also be the ID of an
2622 entry, even in a different file, and the reference then refers to the first
2623 table in that entry. REF is an absolute field or range reference as
2624 described above for example @code{@@3$3} or @code{$somename}, valid in the
2627 Indirection of NAME-OR-ID: When NAME-OR-ID has the format @code{@@ROW$COLUMN}
2628 it will be substituted with the name or ID found in this field of the current
2629 table. For example @code{remote($1, @@>$2)} => @code{remote(year_2013,
2630 @@>$1)}. The format @code{B3} is not supported because it can not be
2631 distinguished from a plain table name or ID.
2633 @node Formula syntax for Calc
2634 @subsection Formula syntax for Calc
2635 @cindex formula syntax, Calc
2636 @cindex syntax, of formulas
2638 A formula can be any algebraic expression understood by the Emacs @file{Calc}
2639 package. Note that @file{calc} has the non-standard convention that @samp{/}
2640 has lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as
2641 @samp{a/(b*c)}. Before evaluation by @code{calc-eval} (@pxref{Calling Calc
2642 from Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc,
2643 GNU Emacs Calc Manual}), variable substitution takes place according to the
2644 rules described above.
2645 @cindex vectors, in table calculations
2646 The range vectors can be directly fed into the Calc vector functions
2647 like @samp{vmean} and @samp{vsum}.
2649 @cindex format specifier
2650 @cindex mode, for @file{calc}
2651 @vindex org-calc-default-modes
2652 A formula can contain an optional mode string after a semicolon. This
2653 string consists of flags to influence Calc and other modes during
2654 execution. By default, Org uses the standard Calc modes (precision
2655 12, angular units degrees, fraction and symbolic modes off). The display
2656 format, however, has been changed to @code{(float 8)} to keep tables
2657 compact. The default settings can be configured using the option
2658 @code{org-calc-default-modes}.
2660 @noindent List of modes:
2664 Set the internal Calc calculation precision to 20 digits.
2665 @item @code{n3}, @code{s3}, @code{e2}, @code{f4}
2666 Normal, scientific, engineering or fixed format of the result of Calc passed
2667 back to Org. Calc formatting is unlimited in precision as long as the Calc
2668 calculation precision is greater.
2669 @item @code{D}, @code{R}
2670 Degree and radian angle modes of Calc.
2671 @item @code{F}, @code{S}
2672 Fraction and symbolic modes of Calc.
2673 @item @code{T}, @code{t}
2674 Duration computations in Calc or Lisp, @pxref{Durations and time values}.
2676 If and how to consider empty fields. Without @samp{E} empty fields in range
2677 references are suppressed so that the Calc vector or Lisp list contains only
2678 the non-empty fields. With @samp{E} the empty fields are kept. For empty
2679 fields in ranges or empty field references the value @samp{nan} (not a
2680 number) is used in Calc formulas and the empty string is used for Lisp
2681 formulas. Add @samp{N} to use 0 instead for both formula types. For the
2682 value of a field the mode @samp{N} has higher precedence than @samp{E}.
2684 Interpret all fields as numbers, use 0 for non-numbers. See the next section
2685 to see how this is essential for computations with Lisp formulas. In Calc
2686 formulas it is used only occasionally because there number strings are
2687 already interpreted as numbers without @samp{N}.
2689 Literal, for Lisp formulas only. See the next section.
2693 Unless you use large integer numbers or high-precision-calculation and
2694 -display for floating point numbers you may alternatively provide a
2695 @samp{printf} format specifier to reformat the Calc result after it has been
2696 passed back to Org instead of letting Calc already do the
2697 formatting@footnote{The @samp{printf} reformatting is limited in precision
2698 because the value passed to it is converted into an @samp{integer} or
2699 @samp{double}. The @samp{integer} is limited in size by truncating the
2700 signed value to 32 bits. The @samp{double} is limited in precision to 64
2701 bits overall which leaves approximately 16 significant decimal digits.}. A
2705 $1+$2 @r{Sum of first and second field}
2706 $1+$2;%.2f @r{Same, format result to two decimals}
2707 exp($2)+exp($1) @r{Math functions can be used}
2708 $0;%.1f @r{Reformat current cell to 1 decimal}
2709 ($3-32)*5/9 @r{Degrees F -> C conversion}
2710 $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
2711 tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
2712 sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
2713 taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree}
2716 Calc also contains a complete set of logical operations, (@pxref{Logical
2717 Operations, , Logical Operations, calc, GNU Emacs Calc Manual}). For example
2720 @item if($1 < 20, teen, string(""))
2721 "teen" if age $1 is less than 20, else the Org table result field is set to
2722 empty with the empty string.
2723 @item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E
2724 Sum of the first two columns. When at least one of the input fields is empty
2725 the Org table result field is set to empty.
2726 @item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E
2727 Mean value of a range unless there is any empty field. Every field in the
2728 range that is empty is replaced by @samp{nan} which lets @samp{vmean} result
2729 in @samp{nan}. Then @samp{typeof == 12} detects the @samp{nan} from
2730 @samp{vmean} and the Org table result field is set to empty. Use this when
2731 the sample set is expected to never have missing values.
2732 @item if("$1..$7" == "[]", string(""), vmean($1..$7))
2733 Mean value of a range with empty fields skipped. Every field in the range
2734 that is empty is skipped. When all fields in the range are empty the mean
2735 value is not defined and the Org table result field is set to empty. Use
2736 this when the sample set can have a variable size.
2737 @item vmean($1..$7); EN
2738 To complete the example before: Mean value of a range with empty fields
2739 counting as samples with value 0. Use this only when incomplete sample sets
2740 should be padded with 0 to the full size.
2743 You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
2744 and use them in formula syntax for Calc.
2746 @node Formula syntax for Lisp
2747 @subsection Emacs Lisp forms as formulas
2748 @cindex Lisp forms, as table formulas
2750 It is also possible to write a formula in Emacs Lisp. This can be useful
2751 for string manipulation and control structures, if Calc's functionality is
2754 If a formula starts with a single-quote followed by an opening parenthesis,
2755 then it is evaluated as a Lisp form. The evaluation should return either a
2756 string or a number. Just as with @file{calc} formulas, you can specify modes
2757 and a printf format after a semicolon.
2759 With Emacs Lisp forms, you need to be conscious about the way field
2760 references are interpolated into the form. By default, a reference will be
2761 interpolated as a Lisp string (in double-quotes) containing the field. If
2762 you provide the @samp{N} mode switch, all referenced elements will be numbers
2763 (non-number fields will be zero) and interpolated as Lisp numbers, without
2764 quotes. If you provide the @samp{L} flag, all fields will be interpolated
2765 literally, without quotes. I.e., if you want a reference to be interpreted
2766 as a string by the Lisp form, enclose the reference operator itself in
2767 double-quotes, like @code{"$3"}. Ranges are inserted as space-separated
2768 fields, so you can embed them in list or vector syntax.
2770 Here are a few examples---note how the @samp{N} mode is used when we do
2771 computations in Lisp:
2774 @item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
2775 Swap the first two characters of the content of column 1.
2777 Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
2778 @item '(apply '+ '($1..$4));N
2779 Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
2782 @node Durations and time values
2783 @subsection Durations and time values
2784 @cindex Duration, computing
2785 @cindex Time, computing
2786 @vindex org-table-duration-custom-format
2788 If you want to compute time values use the @code{T} flag, either in Calc
2789 formulas or Elisp formulas:
2793 | Task 1 | Task 2 | Total |
2794 |---------+----------+----------|
2795 | 2:12 | 1:47 | 03:59:00 |
2796 | 3:02:20 | -2:07:00 | 0.92 |
2797 #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;t
2801 Input duration values must be of the form @code{HH:MM[:SS]}, where seconds
2802 are optional. With the @code{T} flag, computed durations will be displayed
2803 as @code{HH:MM:SS} (see the first formula above). With the @code{t} flag,
2804 computed durations will be displayed according to the value of the option
2805 @code{org-table-duration-custom-format}, which defaults to @code{'hours} and
2806 will display the result as a fraction of hours (see the second formula in the
2809 Negative duration values can be manipulated as well, and integers will be
2810 considered as seconds in addition and subtraction.
2812 @node Field and range formulas
2813 @subsection Field and range formulas
2814 @cindex field formula
2815 @cindex range formula
2816 @cindex formula, for individual table field
2817 @cindex formula, for range of fields
2819 To assign a formula to a particular field, type it directly into the field,
2820 preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press
2821 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2822 the formula will be stored as the formula for this field, evaluated, and the
2823 current field will be replaced with the result.
2826 Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
2827 below the table. If you type the equation in the 4th field of the 3rd data
2828 line in the table, the formula will look like @samp{@@3$4=$1+$2}. When
2829 inserting/deleting/swapping columns and rows with the appropriate commands,
2830 @i{absolute references} (but not relative ones) in stored formulas are
2831 modified in order to still reference the same field. To avoid this, in
2832 particular in range references, anchor ranges at the table borders (using
2833 @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines using the
2834 @code{@@I} notation. Automatic adaptation of field references does of course
2835 not happen if you edit the table structure with normal editing
2836 commands---then you must fix the equations yourself.
2838 Instead of typing an equation into the field, you may also use the following
2842 @orgcmd{C-u C-c =,org-table-eval-formula}
2843 Install a new formula for the current field. The command prompts for a
2844 formula with default taken from the @samp{#+TBLFM:} line, applies
2845 it to the current field, and stores it.
2848 The left-hand side of a formula can also be a special expression in order to
2849 assign the formula to a number of different fields. There is no keyboard
2850 shortcut to enter such range formulas. To add them, use the formula editor
2851 (@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
2856 Column formula, valid for the entire column. This is so common that Org
2857 treats these formulas in a special way, see @ref{Column formulas}.
2859 Row formula, applies to all fields in the specified row. @code{@@>=} means
2862 Range formula, applies to all fields in the given rectangular range. This
2863 can also be used to assign a formula to some but not all fields in a row.
2865 Named field, see @ref{Advanced features}.
2868 @node Column formulas
2869 @subsection Column formulas
2870 @cindex column formula
2871 @cindex formula, for table column
2873 When you assign a formula to a simple column reference like @code{$3=}, the
2874 same formula will be used in all fields of that column, with the following
2875 very convenient exceptions: (i) If the table contains horizontal separator
2876 hlines with rows above and below, everything before the first such hline is
2877 considered part of the table @emph{header} and will not be modified by column
2878 formulas. Therefore a header is mandatory when you use column formulas and
2879 want to add hlines to group rows, like for example to separate a total row at
2880 the bottom from the summand rows above. (ii) Fields that already get a value
2881 from a field/range formula will be left alone by column formulas. These
2882 conditions make column formulas very easy to use.
2884 To assign a formula to a column, type it directly into any field in the
2885 column, preceded by an equal sign, like @samp{=$1+$2}. When you press
2886 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2887 the formula will be stored as the formula for the current column, evaluated
2888 and the current field replaced with the result. If the field contains only
2889 @samp{=}, the previously stored formula for this column is used. For each
2890 column, Org will only remember the most recently used formula. In the
2891 @samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The
2892 left-hand side of a column formula cannot be the name of column, it must be
2893 the numeric column reference or @code{$>}.
2895 Instead of typing an equation into the field, you may also use the
2899 @orgcmd{C-c =,org-table-eval-formula}
2900 Install a new formula for the current column and replace current field with
2901 the result of the formula. The command prompts for a formula, with default
2902 taken from the @samp{#+TBLFM} line, applies it to the current field and
2903 stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
2904 will apply it to that many consecutive fields in the current column.
2907 @node Lookup functions
2908 @subsection Lookup functions
2909 @cindex lookup functions in tables
2910 @cindex table lookup functions
2912 Org has three predefined Emacs Lisp functions for lookups in tables.
2914 @item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)
2915 @findex org-lookup-first
2916 Searches for the first element @code{S} in list @code{S-LIST} for which
2920 is @code{t}; returns the value from the corresponding position in list
2921 @code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the
2922 parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same
2923 order as the corresponding parameters are in the call to
2924 @code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If
2925 @code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST}
2927 @item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)
2928 @findex org-lookup-last
2929 Similar to @code{org-lookup-first} above, but searches for the @i{last}
2930 element for which @code{PREDICATE} is @code{t}.
2931 @item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)
2932 @findex org-lookup-all
2933 Similar to @code{org-lookup-first}, but searches for @i{all} elements for
2934 which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding
2935 values. This function can not be used by itself in a formula, because it
2936 returns a list of values. However, powerful lookups can be built when this
2937 function is combined with other Emacs Lisp functions.
2940 If the ranges used in these functions contain empty fields, the @code{E} mode
2941 for the formula should usually be specified: otherwise empty fields will not be
2942 included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result
2943 in an incorrect mapping from an element of @code{S-LIST} to the corresponding
2944 element of @code{R-LIST}.
2946 These three functions can be used to implement associative arrays, count
2947 matching cells, rank results, group data etc. For practical examples
2948 see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
2951 @node Editing and debugging formulas
2952 @subsection Editing and debugging formulas
2953 @cindex formula editing
2954 @cindex editing, of table formulas
2956 @vindex org-table-use-standard-references
2957 You can edit individual formulas in the minibuffer or directly in the field.
2958 Org can also prepare a special buffer with all active formulas of a table.
2959 When offering a formula for editing, Org converts references to the standard
2960 format (like @code{B3} or @code{D&}) if possible. If you prefer to only work
2961 with the internal format (like @code{@@3$2} or @code{$4}), configure the
2962 option @code{org-table-use-standard-references}.
2965 @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
2966 Edit the formula associated with the current column/field in the
2967 minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}.
2968 @orgcmd{C-u C-u C-c =,org-table-eval-formula}
2969 Re-insert the active formula (either a
2970 field formula, or a column formula) into the current field, so that you
2971 can edit it directly in the field. The advantage over editing in the
2972 minibuffer is that you can use the command @kbd{C-c ?}.
2973 @orgcmd{C-c ?,org-table-field-info}
2974 While editing a formula in a table field, highlight the field(s)
2975 referenced by the reference at the cursor position in the formula.
2977 @findex org-table-toggle-coordinate-overlays
2979 Toggle the display of row and column numbers for a table, using overlays
2980 (@command{org-table-toggle-coordinate-overlays}). These are updated each
2981 time the table is aligned; you can force it with @kbd{C-c C-c}.
2983 @findex org-table-toggle-formula-debugger
2985 Toggle the formula debugger on and off
2986 (@command{org-table-toggle-formula-debugger}). See below.
2987 @orgcmd{C-c ',org-table-edit-formulas}
2988 Edit all formulas for the current table in a special buffer, where the
2989 formulas will be displayed one per line. If the current field has an
2990 active formula, the cursor in the formula editor will mark it.
2991 While inside the special buffer, Org will automatically highlight
2992 any field or range reference at the cursor position. You may edit,
2993 remove and add formulas, and use the following commands:
2996 @orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
2997 Exit the formula editor and store the modified formulas. With @kbd{C-u}
2998 prefix, also apply the new formulas to the entire table.
2999 @orgcmd{C-c C-q,org-table-fedit-abort}
3000 Exit the formula editor without installing changes.
3001 @orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
3002 Toggle all references in the formula editor between standard (like
3003 @code{B3}) and internal (like @code{@@3$2}).
3004 @orgcmd{@key{TAB},org-table-fedit-lisp-indent}
3005 Pretty-print or indent Lisp formula at point. When in a line containing
3006 a Lisp formula, format the formula according to Emacs Lisp rules.
3007 Another @key{TAB} collapses the formula back again. In the open
3008 formula, @key{TAB} re-indents just like in Emacs Lisp mode.
3009 @orgcmd{M-@key{TAB},lisp-complete-symbol}
3010 Complete Lisp symbols, just like in Emacs Lisp mode.
3012 @kindex S-@key{down}
3013 @kindex S-@key{left}
3014 @kindex S-@key{right}
3015 @findex org-table-fedit-ref-up
3016 @findex org-table-fedit-ref-down
3017 @findex org-table-fedit-ref-left
3018 @findex org-table-fedit-ref-right
3019 @item S-@key{up}/@key{down}/@key{left}/@key{right}
3020 Shift the reference at point. For example, if the reference is
3021 @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
3022 This also works for relative references and for hline references.
3023 @orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
3024 Move the test line for column formulas in the Org buffer up and
3026 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
3027 Scroll the window displaying the table.
3029 @findex org-table-toggle-coordinate-overlays
3031 Turn the coordinate grid in the table on and off.
3035 Making a table field blank does not remove the formula associated with
3036 the field, because that is stored in a different line (the @samp{#+TBLFM}
3037 line)---during the next recalculation the field will be filled again.
3038 To remove a formula from a field, you have to give an empty reply when
3039 prompted for the formula, or to edit the @samp{#+TBLFM} line.
3042 You may edit the @samp{#+TBLFM} directly and re-apply the changed
3043 equations with @kbd{C-c C-c} in that line or with the normal
3044 recalculation commands in the table.
3046 @anchor{Using multiple #+TBLFM lines}
3047 @subsubheading Using multiple #+TBLFM lines
3048 @cindex #+TBLFM line, multiple
3050 @cindex #+TBLFM, switching
3053 You may apply the formula temporarily. This is useful when you
3054 switch the formula. Place multiple @samp{#+TBLFM} lines right
3055 after the table, and then press @kbd{C-c C-c} on the formula to
3056 apply. Here is an example:
3068 Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
3080 Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
3081 will get the following result of applying only the first @samp{#+TBLFM} line.
3092 @subsubheading Debugging formulas
3093 @cindex formula debugging
3094 @cindex debugging, of table formulas
3095 When the evaluation of a formula leads to an error, the field content
3096 becomes the string @samp{#ERROR}. If you would like see what is going
3097 on during variable substitution and calculation in order to find a bug,
3098 turn on formula debugging in the @code{Tbl} menu and repeat the
3099 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
3100 field. Detailed information will be displayed.
3102 @node Updating the table
3103 @subsection Updating the table
3104 @cindex recomputing table fields
3105 @cindex updating, table
3107 Recalculation of a table is normally not automatic, but needs to be
3108 triggered by a command. See @ref{Advanced features}, for a way to make
3109 recalculation at least semi-automatic.
3111 In order to recalculate a line of a table or the entire table, use the
3115 @orgcmd{C-c *,org-table-recalculate}
3116 Recalculate the current row by first applying the stored column formulas
3117 from left to right, and all field/range formulas in the current row.
3123 Recompute the entire table, line by line. Any lines before the first
3124 hline are left alone, assuming that these are part of the table header.
3126 @orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
3127 Iterate the table by recomputing it until no further changes occur.
3128 This may be necessary if some computed fields use the value of other
3129 fields that are computed @i{later} in the calculation sequence.
3130 @item M-x org-table-recalculate-buffer-tables RET
3131 @findex org-table-recalculate-buffer-tables
3132 Recompute all tables in the current buffer.
3133 @item M-x org-table-iterate-buffer-tables RET
3134 @findex org-table-iterate-buffer-tables
3135 Iterate all tables in the current buffer, in order to converge table-to-table
3139 @node Advanced features
3140 @subsection Advanced features
3142 If you want the recalculation of fields to happen automatically, or if you
3143 want to be able to assign @i{names}@footnote{Such names must start by an
3144 alphabetic character and use only alphanumeric/underscore characters.} to
3145 fields and columns, you need to reserve the first column of the table for
3146 special marking characters.
3149 @orgcmd{C-#,org-table-rotate-recalc-marks}
3150 Rotate the calculation mark in first column through the states @samp{ },
3151 @samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,
3152 change all marks in the region.
3155 Here is an example of a table that collects exam results of students and
3156 makes use of these features:
3160 |---+---------+--------+--------+--------+-------+------|
3161 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
3162 |---+---------+--------+--------+--------+-------+------|
3163 | ! | | P1 | P2 | P3 | Tot | |
3164 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
3165 | ^ | | m1 | m2 | m3 | mt | |
3166 |---+---------+--------+--------+--------+-------+------|
3167 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
3168 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
3169 |---+---------+--------+--------+--------+-------+------|
3170 | | Average | | | | 25.0 | |
3171 | ^ | | | | | at | |
3172 | $ | max=50 | | | | | |
3173 |---+---------+--------+--------+--------+-------+------|
3174 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
3178 @noindent @b{Important}: please note that for these special tables,
3179 recalculating the table with @kbd{C-u C-c *} will only affect rows that
3180 are marked @samp{#} or @samp{*}, and fields that have a formula assigned
3181 to the field itself. The column formulas are not applied in rows with
3184 @cindex marking characters, tables
3185 The marking characters have the following meaning:
3189 The fields in this line define names for the columns, so that you may
3190 refer to a column as @samp{$Tot} instead of @samp{$6}.
3192 This row defines names for the fields @emph{above} the row. With such
3193 a definition, any formula in the table may use @samp{$m1} to refer to
3194 the value @samp{10}. Also, if you assign a formula to a names field, it
3195 will be stored as @samp{$name=...}.
3197 Similar to @samp{^}, but defines names for the fields in the row
3200 Fields in this row can define @emph{parameters} for formulas. For
3201 example, if a field in a @samp{$} row contains @samp{max=50}, then
3202 formulas in this table can refer to the value 50 using @samp{$max}.
3203 Parameters work exactly like constants, only that they can be defined on
3206 Fields in this row are automatically recalculated when pressing
3207 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
3208 is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
3209 lines will be left alone by this command.
3211 Selects this line for global recalculation with @kbd{C-u C-c *}, but
3212 not for automatic recalculation. Use this when automatic
3213 recalculation slows down editing too much.
3215 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
3216 All lines that should be recalculated should be marked with @samp{#}
3219 Do not export this line. Useful for lines that contain the narrowing
3220 @samp{<N>} markers or column group markers.
3223 Finally, just to whet your appetite for what can be done with the
3224 fantastic @file{calc.el} package, here is a table that computes the Taylor
3225 series of degree @code{n} at location @code{x} for a couple of
3230 |---+-------------+---+-----+--------------------------------------|
3231 | | Func | n | x | Result |
3232 |---+-------------+---+-----+--------------------------------------|
3233 | # | exp(x) | 1 | x | 1 + x |
3234 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
3235 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
3236 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
3237 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
3238 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
3239 |---+-------------+---+-----+--------------------------------------|
3240 #+TBLFM: $5=taylor($2,$4,$3);n3
3246 @cindex graph, in tables
3247 @cindex plot tables using Gnuplot
3250 Org-Plot can produce 2D and 3D graphs of information stored in org tables
3251 using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
3252 @uref{http://xafs.org/BruceRavel/GnuplotMode}. To see this in action, ensure
3253 that you have both Gnuplot and Gnuplot mode installed on your system, then
3254 call @code{org-plot/gnuplot} on the following table.
3258 #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
3259 | Sede | Max cites | H-index |
3260 |-----------+-----------+---------|
3261 | Chile | 257.72 | 21.39 |
3262 | Leeds | 165.77 | 19.68 |
3263 | Sao Paolo | 71.00 | 11.50 |
3264 | Stockholm | 134.19 | 14.33 |
3265 | Morelia | 257.56 | 17.67 |
3269 Notice that Org Plot is smart enough to apply the table's headers as labels.
3270 Further control over the labels, type, content, and appearance of plots can
3271 be exercised through the @code{#+PLOT:} lines preceding a table. See below
3272 for a complete list of Org-plot options. For more information and examples
3273 see the Org-plot tutorial at
3274 @uref{http://orgmode.org/worg/org-tutorials/org-plot.html}.
3276 @subsubheading Plot Options
3280 Specify any @command{gnuplot} option to be set when graphing.
3283 Specify the title of the plot.
3286 Specify which column of the table to use as the @code{x} axis.
3289 Specify the columns to graph as a Lisp style list, surrounded by parentheses
3290 and separated by spaces for example @code{dep:(3 4)} to graph the third and
3291 fourth columns (defaults to graphing all other columns aside from the @code{ind}
3295 Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
3298 Specify a @code{with} option to be inserted for every col being plotted
3299 (e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
3300 Defaults to @code{lines}.
3303 If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
3306 List of labels to be used for the @code{deps} (defaults to the column headers
3310 Specify an entire line to be inserted in the Gnuplot script.
3313 When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
3314 flat mapping rather than a @code{3d} slope.
3317 Specify format of Org mode timestamps as they will be parsed by Gnuplot.
3318 Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
3321 If you want total control, you can specify a script file (place the file name
3322 between double-quotes) which will be used to plot. Before plotting, every
3323 instance of @code{$datafile} in the specified script will be replaced with
3324 the path to the generated data file. Note: even if you set this option, you
3325 may still want to specify the plot type, as that can impact the content of
3333 Like HTML, Org provides links inside a file, external links to
3334 other files, Usenet articles, emails, and much more.
3337 * Link format:: How links in Org are formatted
3338 * Internal links:: Links to other places in the current file
3339 * External links:: URL-like links to the world
3340 * Handling links:: Creating, inserting and following
3341 * Using links outside Org:: Linking from my C source code?
3342 * Link abbreviations:: Shortcuts for writing complex links
3343 * Search options:: Linking to a specific location
3344 * Custom searches:: When the default search is not enough
3348 @section Link format
3350 @cindex format, of links
3352 Org will recognize plain URL-like links and activate them as
3353 clickable links. The general link format, however, looks like this:
3356 [[link][description]] @r{or alternatively} [[link]]
3360 Once a link in the buffer is complete (all brackets present), Org
3361 will change the display so that @samp{description} is displayed instead
3362 of @samp{[[link][description]]} and @samp{link} is displayed instead of
3363 @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
3364 which by default is an underlined face. You can directly edit the
3365 visible part of a link. Note that this can be either the @samp{link}
3366 part (if there is no description) or the @samp{description} part. To
3367 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
3370 If you place the cursor at the beginning or just behind the end of the
3371 displayed text and press @key{BACKSPACE}, you will remove the
3372 (invisible) bracket at that location. This makes the link incomplete
3373 and the internals are again displayed as plain text. Inserting the
3374 missing bracket hides the link internals again. To show the
3375 internal structure of all links, use the menu entry
3376 @code{Org->Hyperlinks->Literal links}.
3378 @node Internal links
3379 @section Internal links
3380 @cindex internal links
3381 @cindex links, internal
3382 @cindex targets, for links
3384 @cindex property, CUSTOM_ID
3385 If the link does not look like a URL, it is considered to be internal in the
3386 current file. The most important case is a link like
3387 @samp{[[#my-custom-id]]} which will link to the entry with the
3388 @code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself
3389 to make sure these custom IDs are unique in a file.
3391 Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
3392 lead to a text search in the current file.
3394 The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
3395 or with a mouse click (@pxref{Handling links}). Links to custom IDs will
3396 point to the corresponding headline. The preferred match for a text link is
3397 a @i{dedicated target}: the same string in double angular brackets, like
3398 @samp{<<My Target>>}.
3401 If no dedicated target exists, the link will then try to match the exact name
3402 of an element within the buffer. Naming is done with the @code{#+NAME}
3403 keyword, which has to be put in the line before the element it refers to, as
3404 in the following example
3413 If none of the above succeeds, Org will search for a headline that is exactly
3414 the link text but may also include a TODO keyword and tags@footnote{To insert
3415 a link targeting a headline, in-buffer completion can be used. Just type
3416 a star followed by a few optional letters into the buffer and press
3417 @kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as
3420 During export, internal links will be used to mark objects and assign them
3421 a number. Marked objects will then be referenced by links pointing to them.
3422 In particular, links without a description will appear as the number assigned
3423 to the marked object@footnote{When targeting a @code{#+NAME} keyword,
3424 @code{#+CAPTION} keyword is mandatory in order to get proper numbering
3425 (@pxref{Images and tables}).}. In the following excerpt from an Org buffer
3429 - <<target>>another item
3430 Here we refer to item [[target]].
3434 The last sentence will appear as @samp{Here we refer to item 2} when
3437 In non-Org files, the search will look for the words in the link text. In
3438 the above example the search would be for @samp{my target}.
3440 Following a link pushes a mark onto Org's own mark ring. You can
3441 return to the previous position with @kbd{C-c &}. Using this command
3442 several times in direct succession goes back to positions recorded
3446 * Radio targets:: Make targets trigger links in plain text
3450 @subsection Radio targets
3451 @cindex radio targets
3452 @cindex targets, radio
3453 @cindex links, radio targets
3455 Org can automatically turn any occurrences of certain target names
3456 in normal text into a link. So without explicitly creating a link, the
3457 text connects to the target radioing its position. Radio targets are
3458 enclosed by triple angular brackets. For example, a target @samp{<<<My
3459 Target>>>} causes each occurrence of @samp{my target} in normal text to
3460 become activated as a link. The Org file is scanned automatically
3461 for radio targets only when the file is first loaded into Emacs. To
3462 update the target list during editing, press @kbd{C-c C-c} with the
3463 cursor on or at a target.
3465 @node External links
3466 @section External links
3467 @cindex links, external
3468 @cindex external links
3476 @cindex USENET links
3481 Org supports links to files, websites, Usenet and email messages, BBDB
3482 database entries and links to both IRC conversations and their logs.
3483 External links are URL-like locators. They start with a short identifying
3484 string followed by a colon. There can be no space after the colon. The
3485 following list shows examples for each link type.
3488 http://www.astro.uva.nl/~dominik @r{on the web}
3489 doi:10.1000/182 @r{DOI for an electronic resource}
3490 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
3491 /home/dominik/images/jupiter.jpg @r{same as above}
3492 file:papers/last.pdf @r{file, relative path}
3493 ./papers/last.pdf @r{same as above}
3494 file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine}
3495 /myself@@some.where:papers/last.pdf @r{same as above}
3496 file:sometextfile::NNN @r{file, jump to line number}
3497 file:projects.org @r{another Org file}
3498 file:projects.org::some words @r{text search in Org file}@footnote{
3499 The actual behavior of the search will depend on the value of
3500 the option @code{org-link-search-must-match-exact-headline}. If its value
3501 is @code{nil}, then a fuzzy text search will be done. If it is t, then only the
3502 exact headline will be matched. If the value is @code{'query-to-create},
3503 then an exact headline will be searched; if it is not found, then the user
3504 will be queried to create it.}
3505 file:projects.org::*task title @r{heading search in Org file}
3506 file+sys:/path/to/file @r{open via OS, like double-click}
3507 file+emacs:/path/to/file @r{force opening by Emacs}
3508 docview:papers/last.pdf::NNN @r{open in doc-view mode at page}
3509 id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
3510 news:comp.emacs @r{Usenet link}
3511 mailto:adent@@galaxy.net @r{Mail link}
3512 mhe:folder @r{MH-E folder link}
3513 mhe:folder#id @r{MH-E message link}
3514 rmail:folder @r{RMAIL folder link}
3515 rmail:folder#id @r{RMAIL message link}
3516 gnus:group @r{Gnus group link}
3517 gnus:group#id @r{Gnus article link}
3518 bbdb:R.*Stallman @r{BBDB link (with regexp)}
3519 irc:/irc.com/#emacs/bob @r{IRC link}
3520 info:org#External links @r{Info node link}
3521 shell:ls *.org @r{A shell command}
3522 elisp:org-agenda @r{Interactive Elisp command}
3523 elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
3527 @cindex WANDERLUST links
3528 On top of these built-in link types, some are available through the
3529 @code{contrib/} directory (@pxref{Installation}). For example, these links
3530 to VM or Wanderlust messages are available when you load the corresponding
3531 libraries from the @code{contrib/} directory:
3534 vm:folder @r{VM folder link}
3535 vm:folder#id @r{VM message link}
3536 vm://myself@@some.where.org/folder#id @r{VM on remote machine}
3537 vm-imap:account:folder @r{VM IMAP folder link}
3538 vm-imap:account:folder#id @r{VM IMAP message link}
3539 wl:folder @r{WANDERLUST folder link}
3540 wl:folder#id @r{WANDERLUST message link}
3543 For customizing Org to add new link types @ref{Adding hyperlink types}.
3545 A link should be enclosed in double brackets and may contain a descriptive
3546 text to be displayed instead of the URL (@pxref{Link format}), for example:
3549 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
3553 If the description is a file name or URL that points to an image, HTML
3554 export (@pxref{HTML export}) will inline the image as a clickable
3555 button. If there is no description at all and the link points to an
3557 that image will be inlined into the exported HTML file.
3559 @cindex square brackets, around links
3560 @cindex plain text external links
3561 Org also finds external links in the normal text and activates them
3562 as links. If spaces must be part of the link (for example in
3563 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
3564 about the end of the link, enclose them in square brackets.
3566 @node Handling links
3567 @section Handling links
3568 @cindex links, handling
3570 Org provides methods to create a link in the correct syntax, to
3571 insert it into an Org file, and to follow the link.
3574 @orgcmd{C-c l,org-store-link}
3575 @cindex storing links
3576 Store a link to the current location. This is a @emph{global} command (you
3577 must create the key binding yourself) which can be used in any buffer to
3578 create a link. The link will be stored for later insertion into an Org
3579 buffer (see below). What kind of link will be created depends on the current
3582 @b{Org mode buffers}@*
3583 For Org files, if there is a @samp{<<target>>} at the cursor, the link points
3584 to the target. Otherwise it points to the current headline, which will also
3585 be the description@footnote{If the headline contains a timestamp, it will be
3586 removed from the link and result in a wrong link---you should avoid putting
3587 timestamp in the headline.}.
3589 @vindex org-id-link-to-org-use-id
3590 @cindex property, CUSTOM_ID
3591 @cindex property, ID
3592 If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
3593 will be stored. In addition or alternatively (depending on the value of
3594 @code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
3595 be created and/or used to construct a link@footnote{The library
3596 @file{org-id.el} must first be loaded, either through @code{org-customize} by
3597 enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
3598 'org-id)} in your @file{.emacs}.}. So using this command in Org buffers will
3599 potentially create two links: a human-readable from the custom ID, and one
3600 that is globally unique and works even if the entry is moved from file to
3601 file. Later, when inserting the link, you need to decide which one to use.
3603 @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
3604 Pretty much all Emacs mail clients are supported. The link will point to the
3605 current article, or, in some GNUS buffers, to the group. The description is
3606 constructed from the author and the subject.
3608 @b{Web browsers: W3 and W3M}@*
3609 Here the link will be the current URL, with the page title as description.
3611 @b{Contacts: BBDB}@*
3612 Links created in a BBDB buffer will point to the current entry.
3615 @vindex org-irc-link-to-logs
3616 For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t},
3617 a @samp{file:/} style link to the relevant point in the logs for the current
3618 conversation is created. Otherwise an @samp{irc:/} style link to the
3619 user/channel/server under the point will be stored.
3622 For any other files, the link will point to the file, with a search string
3623 (@pxref{Search options}) pointing to the contents of the current line. If
3624 there is an active region, the selected words will form the basis of the
3625 search string. If the automatically created link is not working correctly or
3626 accurately enough, you can write custom functions to select the search string
3627 and to do the search for particular file types---see @ref{Custom searches}.
3628 The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
3631 When the cursor is in an agenda view, the created link points to the
3632 entry referenced by the current line.
3635 @orgcmd{C-c C-l,org-insert-link}
3636 @cindex link completion
3637 @cindex completion, of links
3638 @cindex inserting links
3639 @vindex org-keep-stored-link-after-insertion
3640 Insert a link@footnote{Note that you don't have to use this command to
3641 insert a link. Links in Org are plain text, and you can type or paste them
3642 straight into the buffer. By using this command, the links are automatically
3643 enclosed in double brackets, and you will be asked for the optional
3644 descriptive text.}. This prompts for a link to be inserted into the buffer.
3645 You can just type a link, using text for an internal link, or one of the link
3646 type prefixes mentioned in the examples above. The link will be inserted
3647 into the buffer@footnote{After insertion of a stored link, the link will be
3648 removed from the list of stored links. To keep it in the list later use, use
3649 a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
3650 @code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
3651 If some text was selected when this command is called, the selected text
3652 becomes the default description.
3654 @b{Inserting stored links}@*
3655 All links stored during the
3656 current session are part of the history for this prompt, so you can access
3657 them with @key{up} and @key{down} (or @kbd{M-p/n}).
3659 @b{Completion support}@* Completion with @key{TAB} will help you to insert
3660 valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes
3661 defined through link abbreviations (@pxref{Link abbreviations}). If you
3662 press @key{RET} after inserting only the @var{prefix}, Org will offer
3663 specific completion support for some link types@footnote{This works by
3664 calling a special function @code{org-PREFIX-complete-link}.} For
3665 example, if you type @kbd{file @key{RET}}, file name completion (alternative
3666 access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb
3667 @key{RET}} you can complete contact names.
3669 @cindex file name completion
3670 @cindex completion, of file names
3671 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
3672 a file will be inserted and you may use file name completion to select
3673 the name of the file. The path to the file is inserted relative to the
3674 directory of the current Org file, if the linked file is in the current
3675 directory or in a sub-directory of it, or if the path is written relative
3676 to the current directory using @samp{../}. Otherwise an absolute path
3677 is used, if possible with @samp{~/} for your home directory. You can
3678 force an absolute path with two @kbd{C-u} prefixes.
3680 @item C-c C-l @ @r{(with cursor on existing link)}
3681 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
3682 link and description parts of the link.
3684 @cindex following links
3685 @orgcmd{C-c C-o,org-open-at-point}
3686 @vindex org-file-apps
3687 @vindex org-link-frame-setup
3688 Open link at point. This will launch a web browser for URLs (using
3689 @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
3690 the corresponding links, and execute the command in a shell link. When the
3691 cursor is on an internal link, this command runs the corresponding search.
3692 When the cursor is on a TAG list in a headline, it creates the corresponding
3693 TAGS view. If the cursor is on a timestamp, it compiles the agenda for that
3694 date. Furthermore, it will visit text and remote files in @samp{file:} links
3695 with Emacs and select a suitable application for local non-text files.
3696 Classification of files is based on file extension only. See option
3697 @code{org-file-apps}. If you want to override the default application and
3698 visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
3699 opening in Emacs, use a @kbd{C-u C-u} prefix.@*
3700 If the cursor is on a headline, but not on a link, offer all links in the
3701 headline and entry text. If you want to setup the frame configuration for
3702 following links, customize @code{org-link-frame-setup}.
3705 @vindex org-return-follows-link
3706 When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
3713 On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
3714 would. Under Emacs 22 and later, @kbd{mouse-1} will also follow a link.
3718 @vindex org-display-internal-link-with-indirect-buffer
3719 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
3720 internal links to be displayed in another window@footnote{See the
3721 option @code{org-display-internal-link-with-indirect-buffer}}.
3723 @orgcmd{C-c C-x C-v,org-toggle-inline-images}
3724 @cindex inlining images
3725 @cindex images, inlining
3726 @vindex org-startup-with-inline-images
3727 @cindex @code{inlineimages}, STARTUP keyword
3728 @cindex @code{noinlineimages}, STARTUP keyword
3729 Toggle the inline display of linked images. Normally this will only inline
3730 images that have no description part in the link, i.e., images that will also
3731 be inlined during export. When called with a prefix argument, also display
3732 images that do have a link description. You can ask for inline images to be
3733 displayed at startup by configuring the variable
3734 @code{org-startup-with-inline-images}@footnote{with corresponding
3735 @code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
3736 @orgcmd{C-c %,org-mark-ring-push}
3738 Push the current position onto the mark ring, to be able to return
3739 easily. Commands following an internal link do this automatically.
3741 @orgcmd{C-c &,org-mark-ring-goto}
3742 @cindex links, returning to
3743 Jump back to a recorded position. A position is recorded by the
3744 commands following internal links, and by @kbd{C-c %}. Using this
3745 command several times in direct succession moves through a ring of
3746 previously recorded positions.
3748 @orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
3749 @cindex links, finding next/previous
3750 Move forward/backward to the next link in the buffer. At the limit of
3751 the buffer, the search fails once, and then wraps around. The key
3752 bindings for this are really too long; you might want to bind this also
3753 to @kbd{C-n} and @kbd{C-p}
3755 (add-hook 'org-load-hook
3757 (define-key org-mode-map "\C-n" 'org-next-link)
3758 (define-key org-mode-map "\C-p" 'org-previous-link)))
3762 @node Using links outside Org
3763 @section Using links outside Org
3765 You can insert and follow links that have Org syntax not only in
3766 Org, but in any Emacs buffer. For this, you should create two
3767 global commands, like this (please select suitable global keys
3771 (global-set-key "\C-c L" 'org-insert-link-global)
3772 (global-set-key "\C-c o" 'org-open-at-point-global)
3775 @node Link abbreviations
3776 @section Link abbreviations
3777 @cindex link abbreviations
3778 @cindex abbreviation, links
3780 Long URLs can be cumbersome to type, and often many similar links are
3781 needed in a document. For this you can use link abbreviations. An
3782 abbreviated link looks like this
3785 [[linkword:tag][description]]
3789 @vindex org-link-abbrev-alist
3790 where the tag is optional.
3791 The @i{linkword} must be a word, starting with a letter, followed by
3792 letters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolved
3793 according to the information in the variable @code{org-link-abbrev-alist}
3794 that relates the linkwords to replacement text. Here is an example:
3798 (setq org-link-abbrev-alist
3799 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
3800 ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
3801 ("google" . "http://www.google.com/search?q=")
3802 ("gmap" . "http://maps.google.com/maps?q=%s")
3803 ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
3804 ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
3808 If the replacement text contains the string @samp{%s}, it will be
3809 replaced with the tag. Using @samp{%h} instead of @samp{%s} will
3810 url-encode the tag (see the example above, where we need to encode
3811 the URL parameter.) Using @samp{%(my-function)} will pass the tag
3812 to a custom function, and replace it by the resulting string.
3814 If the replacement text doesn't contain any specifier, it will simply
3815 be appended to the string in order to create the link.
3817 Instead of a string, you may also specify a function that will be
3818 called with the tag as the only argument to create the link.
3820 With the above setting, you could link to a specific bug with
3821 @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
3822 @code{[[google:OrgMode]]}, show the map location of the Free Software
3823 Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
3824 @code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
3825 what the Org author is doing besides Emacs hacking with
3826 @code{[[ads:Dominik,C]]}.
3828 If you need special abbreviations just for a single Org buffer, you
3829 can define them in the file with
3833 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
3834 #+LINK: google http://www.google.com/search?q=%s
3838 In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
3839 complete link abbreviations. You may also define a function
3840 @code{org-PREFIX-complete-link} that implements special (e.g., completion)
3841 support for inserting such a link with @kbd{C-c C-l}. Such a function should
3842 not accept any arguments, and return the full link with prefix.
3844 @node Search options
3845 @section Search options in file links
3846 @cindex search option in file links
3847 @cindex file links, searching
3849 File links can contain additional information to make Emacs jump to a
3850 particular location in the file when following a link. This can be a
3851 line number or a search option after a double@footnote{For backward
3852 compatibility, line numbers can also follow a single colon.} colon. For
3853 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
3854 links}) to a file, it encodes the words in the current line as a search
3855 string that can be used to find this line back later when following the
3856 link with @kbd{C-c C-o}.
3858 Here is the syntax of the different ways to attach a search to a file
3859 link, together with an explanation:
3862 [[file:~/code/main.c::255]]
3863 [[file:~/xx.org::My Target]]
3864 [[file:~/xx.org::*My Target]]
3865 [[file:~/xx.org::#my-custom-id]]
3866 [[file:~/xx.org::/regexp/]]
3873 Search for a link target @samp{<<My Target>>}, or do a text search for
3874 @samp{my target}, similar to the search in internal links, see
3875 @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
3876 link will become an HTML reference to the corresponding named anchor in
3879 In an Org file, restrict search to headlines.
3881 Link to a heading with a @code{CUSTOM_ID} property
3883 Do a regular expression search for @code{regexp}. This uses the Emacs
3884 command @code{occur} to list all matches in a separate window. If the
3885 target file is in Org mode, @code{org-occur} is used to create a
3886 sparse tree with the matches.
3887 @c If the target file is a directory,
3888 @c @code{grep} will be used to search all files in the directory.
3891 As a degenerate case, a file link with an empty file name can be used
3892 to search the current file. For example, @code{[[file:::find me]]} does
3893 a search for @samp{find me} in the current file, just as
3894 @samp{[[find me]]} would.
3896 @node Custom searches
3897 @section Custom Searches
3898 @cindex custom search strings
3899 @cindex search strings, custom
3901 The default mechanism for creating search strings and for doing the
3902 actual search related to a file link may not work correctly in all
3903 cases. For example, Bib@TeX{} database files have many entries like
3904 @samp{year="1993"} which would not result in good search strings,
3905 because the only unique identification for a Bib@TeX{} entry is the
3908 @vindex org-create-file-search-functions
3909 @vindex org-execute-file-search-functions
3910 If you come across such a problem, you can write custom functions to set
3911 the right search string for a particular file type, and to do the search
3912 for the string in the file. Using @code{add-hook}, these functions need
3913 to be added to the hook variables
3914 @code{org-create-file-search-functions} and
3915 @code{org-execute-file-search-functions}. See the docstring for these
3916 variables for more information. Org actually uses this mechanism
3917 for Bib@TeX{} database files, and you can use the corresponding code as
3918 an implementation example. See the file @file{org-bibtex.el}.
3924 Org mode does not maintain TODO lists as separate documents@footnote{Of
3925 course, you can make a document that contains only long lists of TODO items,
3926 but this is not required.}. Instead, TODO items are an integral part of the
3927 notes file, because TODO items usually come up while taking notes! With Org
3928 mode, simply mark any entry in a tree as being a TODO item. In this way,
3929 information is not duplicated, and the entire context from which the TODO
3930 item emerged is always present.
3932 Of course, this technique for managing TODO items scatters them
3933 throughout your notes file. Org mode compensates for this by providing
3934 methods to give you an overview of all the things that you have to do.
3937 * TODO basics:: Marking and displaying TODO entries
3938 * TODO extensions:: Workflow and assignments
3939 * Progress logging:: Dates and notes for progress
3940 * Priorities:: Some things are more important than others
3941 * Breaking down tasks:: Splitting a task into manageable pieces
3942 * Checkboxes:: Tick-off lists
3946 @section Basic TODO functionality
3948 Any headline becomes a TODO item when it starts with the word
3949 @samp{TODO}, for example:
3952 *** TODO Write letter to Sam Fortune
3956 The most important commands to work with TODO entries are:
3959 @orgcmd{C-c C-t,org-todo}
3960 @cindex cycling, of TODO states
3961 @vindex org-use-fast-todo-selection
3963 Rotate the TODO state of the current item among
3966 ,-> (unmarked) -> TODO -> DONE --.
3967 '--------------------------------'
3970 If TODO keywords have fast access keys (see @ref{Fast access to TODO
3971 states}), you will be prompted for a TODO keyword through the fast selection
3972 interface; this is the default behavior when
3973 @code{org-use-fast-todo-selection} is non-@code{nil}.
3975 The same rotation can also be done ``remotely'' from the timeline and agenda
3976 buffers with the @kbd{t} command key (@pxref{Agenda commands}).
3978 @orgkey{C-u C-c C-t}
3979 When TODO keywords have no selection keys, select a specific keyword using
3980 completion; otherwise force cycling through TODO states with no prompt. When
3981 @code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
3982 selection interface.
3984 @kindex S-@key{right}
3985 @kindex S-@key{left}
3986 @item S-@key{right} @ @r{/} @ S-@key{left}
3987 @vindex org-treat-S-cursor-todo-selection-as-state-change
3988 Select the following/preceding TODO state, similar to cycling. Useful
3989 mostly if more than two TODO states are possible (@pxref{TODO
3990 extensions}). See also @ref{Conflicts}, for a discussion of the interaction
3991 with @code{shift-selection-mode}. See also the variable
3992 @code{org-treat-S-cursor-todo-selection-as-state-change}.
3993 @orgcmd{C-c / t,org-show-todo-tree}
3994 @cindex sparse tree, for TODO
3995 @vindex org-todo-keywords
3996 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
3997 entire buffer, but shows all TODO items (with not-DONE state) and the
3998 headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
3999 / T}), search for a specific TODO@. You will be prompted for the keyword,
4000 and you can also give a list of keywords like @code{KWD1|KWD2|...} to list
4001 entries that match any one of these keywords. With a numeric prefix argument
4002 N, show the tree for the Nth keyword in the option @code{org-todo-keywords}.
4003 With two prefix arguments, find all TODO states, both un-done and done.
4004 @orgcmd{C-c a t,org-todo-list}
4005 Show the global TODO list. Collects the TODO items (with not-DONE states)
4006 from all agenda files (@pxref{Agenda views}) into a single buffer. The new
4007 buffer will be in @code{agenda-mode}, which provides commands to examine and
4008 manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
4009 @xref{Global TODO list}, for more information.
4010 @orgcmd{S-M-@key{RET},org-insert-todo-heading}
4011 Insert a new TODO entry below the current one.
4015 @vindex org-todo-state-tags-triggers
4016 Changing a TODO state can also trigger tag changes. See the docstring of the
4017 option @code{org-todo-state-tags-triggers} for details.
4019 @node TODO extensions
4020 @section Extended use of TODO keywords
4021 @cindex extended TODO keywords
4023 @vindex org-todo-keywords
4024 By default, marked TODO entries have one of only two states: TODO and
4025 DONE@. Org mode allows you to classify TODO items in more complex ways
4026 with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
4027 special setup, the TODO keyword system can work differently in different
4030 Note that @i{tags} are another way to classify headlines in general and
4031 TODO items in particular (@pxref{Tags}).
4034 * Workflow states:: From TODO to DONE in steps
4035 * TODO types:: I do this, Fred does the rest
4036 * Multiple sets in one file:: Mixing it all, and still finding your way
4037 * Fast access to TODO states:: Single letter selection of a state
4038 * Per-file keywords:: Different files, different requirements
4039 * Faces for TODO keywords:: Highlighting states
4040 * TODO dependencies:: When one task needs to wait for others
4043 @node Workflow states
4044 @subsection TODO keywords as workflow states
4045 @cindex TODO workflow
4046 @cindex workflow states as TODO keywords
4048 You can use TODO keywords to indicate different @emph{sequential} states
4049 in the process of working on an item, for example@footnote{Changing
4050 this variable only becomes effective after restarting Org mode in a
4054 (setq org-todo-keywords
4055 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
4058 The vertical bar separates the TODO keywords (states that @emph{need
4059 action}) from the DONE states (which need @emph{no further action}). If
4060 you don't provide the separator bar, the last state is used as the DONE
4062 @cindex completion, of TODO keywords
4063 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
4064 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@. You may
4065 also use a numeric prefix argument to quickly select a specific state. For
4066 example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
4067 Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
4068 define many keywords, you can use in-buffer completion
4069 (@pxref{Completion}) or even a special one-key selection scheme
4070 (@pxref{Fast access to TODO states}) to insert these words into the
4071 buffer. Changing a TODO state can be logged with a timestamp, see
4072 @ref{Tracking TODO state changes}, for more information.
4075 @subsection TODO keywords as types
4077 @cindex names as TODO keywords
4078 @cindex types as TODO keywords
4080 The second possibility is to use TODO keywords to indicate different
4081 @emph{types} of action items. For example, you might want to indicate
4082 that items are for ``work'' or ``home''. Or, when you work with several
4083 people on a single project, you might want to assign action items
4084 directly to persons, by using their names as TODO keywords. This would
4085 be set up like this:
4088 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
4091 In this case, different keywords do not indicate a sequence, but rather
4092 different types. So the normal work flow would be to assign a task to a
4093 person, and later to mark it DONE@. Org mode supports this style by adapting
4094 the workings of the command @kbd{C-c C-t}@footnote{This is also true for the
4095 @kbd{t} command in the timeline and agenda buffers.}. When used several
4096 times in succession, it will still cycle through all names, in order to first
4097 select the right type for a task. But when you return to the item after some
4098 time and execute @kbd{C-c C-t} again, it will switch from any name directly
4099 to DONE@. Use prefix arguments or completion to quickly select a specific
4100 name. You can also review the items of a specific TODO type in a sparse tree
4101 by using a numeric prefix to @kbd{C-c / t}. For example, to see all things
4102 Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items
4103 from all agenda files into a single buffer, you would use the numeric prefix
4104 argument as well when creating the global TODO list: @kbd{C-3 C-c a t}.
4106 @node Multiple sets in one file
4107 @subsection Multiple keyword sets in one file
4108 @cindex TODO keyword sets
4110 Sometimes you may want to use different sets of TODO keywords in
4111 parallel. For example, you may want to have the basic
4112 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
4113 separate state indicating that an item has been canceled (so it is not
4114 DONE, but also does not require action). Your setup would then look
4118 (setq org-todo-keywords
4119 '((sequence "TODO" "|" "DONE")
4120 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
4121 (sequence "|" "CANCELED")))
4124 The keywords should all be different, this helps Org mode to keep track
4125 of which subsequence should be used for a given entry. In this setup,
4126 @kbd{C-c C-t} only operates within a subsequence, so it switches from
4127 @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
4128 (nothing) to @code{REPORT}. Therefore you need a mechanism to initially
4129 select the correct sequence. Besides the obvious ways like typing a
4130 keyword or using completion, you may also apply the following commands:
4133 @kindex C-S-@key{right}
4134 @kindex C-S-@key{left}
4135 @kindex C-u C-u C-c C-t
4136 @item C-u C-u C-c C-t
4137 @itemx C-S-@key{right}
4138 @itemx C-S-@key{left}
4139 These keys jump from one TODO subset to the next. In the above example,
4140 @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or
4141 @code{DONE} to @code{REPORT}, and any of the words in the second row to
4142 @code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with
4143 @code{shift-selection-mode} (@pxref{Conflicts}).
4144 @kindex S-@key{right}
4145 @kindex S-@key{left}
4148 @kbd{S-@key{left}} and @kbd{S-@key{right}} and walk through @emph{all}
4149 keywords from all sets, so for example @kbd{S-@key{right}} would switch
4150 from @code{DONE} to @code{REPORT} in the example above. See also
4151 @ref{Conflicts}, for a discussion of the interaction with
4152 @code{shift-selection-mode}.
4155 @node Fast access to TODO states
4156 @subsection Fast access to TODO states
4158 If you would like to quickly change an entry to an arbitrary TODO state
4159 instead of cycling through the states, you can set up keys for single-letter
4160 access to the states. This is done by adding the selection character after
4161 each keyword, in parentheses@footnote{All characters are allowed except
4162 @code{@@^!}, which have a special meaning here.}. For example:
4165 (setq org-todo-keywords
4166 '((sequence "TODO(t)" "|" "DONE(d)")
4167 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
4168 (sequence "|" "CANCELED(c)")))
4171 @vindex org-fast-tag-selection-include-todo
4172 If you then press @kbd{C-c C-t} followed by the selection key, the entry
4173 will be switched to this state. @kbd{SPC} can be used to remove any TODO
4174 keyword from an entry.@footnote{Check also the option
4175 @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
4176 state through the tags interface (@pxref{Setting tags}), in case you like to
4177 mingle the two concepts. Note that this means you need to come up with
4178 unique keys across both sets of keywords.}
4180 @node Per-file keywords
4181 @subsection Setting up keywords for individual files
4182 @cindex keyword options
4183 @cindex per-file keywords
4188 It can be very useful to use different aspects of the TODO mechanism in
4189 different files. For file-local settings, you need to add special lines
4190 to the file which set the keywords and interpretation for that file
4191 only. For example, to set one of the two examples discussed above, you
4192 need one of the following lines, starting in column zero anywhere in the
4196 #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
4198 @noindent (you may also write @code{#+SEQ_TODO} to be explicit about the
4199 interpretation, but it means the same as @code{#+TODO}), or
4201 #+TYP_TODO: Fred Sara Lucy Mike | DONE
4204 A setup for using several sets in parallel would be:
4208 #+TODO: REPORT BUG KNOWNCAUSE | FIXED
4212 @cindex completion, of option keywords
4214 @noindent To make sure you are using the correct keyword, type
4215 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
4217 @cindex DONE, final TODO keyword
4218 Remember that the keywords after the vertical bar (or the last keyword
4219 if no bar is there) must always mean that the item is DONE (although you
4220 may use a different word). After changing one of these lines, use
4221 @kbd{C-c C-c} with the cursor still in the line to make the changes
4222 known to Org mode@footnote{Org mode parses these lines only when
4223 Org mode is activated after visiting a file. @kbd{C-c C-c} with the
4224 cursor in a line starting with @samp{#+} is simply restarting Org mode
4225 for the current buffer.}.
4227 @node Faces for TODO keywords
4228 @subsection Faces for TODO keywords
4229 @cindex faces, for TODO keywords
4231 @vindex org-todo @r{(face)}
4232 @vindex org-done @r{(face)}
4233 @vindex org-todo-keyword-faces
4234 Org mode highlights TODO keywords with special faces: @code{org-todo}
4235 for keywords indicating that an item still has to be acted upon, and
4236 @code{org-done} for keywords indicating that an item is finished. If
4237 you are using more than 2 different states, you might want to use
4238 special faces for some of them. This can be done using the option
4239 @code{org-todo-keyword-faces}. For example:
4243 (setq org-todo-keyword-faces
4244 '(("TODO" . org-warning) ("STARTED" . "yellow")
4245 ("CANCELED" . (:foreground "blue" :weight bold))))
4249 While using a list with face properties as shown for CANCELED @emph{should}
4250 work, this does not always seem to be the case. If necessary, define a
4251 special face and use that. A string is interpreted as a color. The option
4252 @code{org-faces-easy-properties} determines if that color is interpreted as a
4253 foreground or a background color.
4255 @node TODO dependencies
4256 @subsection TODO dependencies
4257 @cindex TODO dependencies
4258 @cindex dependencies, of TODO states
4260 @vindex org-enforce-todo-dependencies
4261 @cindex property, ORDERED
4262 The structure of Org files (hierarchy and lists) makes it easy to define TODO
4263 dependencies. Usually, a parent TODO task should not be marked DONE until
4264 all subtasks (defined as children tasks) are marked as DONE@. And sometimes
4265 there is a logical sequence to a number of (sub)tasks, so that one task
4266 cannot be acted upon before all siblings above it are done. If you customize
4267 the option @code{org-enforce-todo-dependencies}, Org will block entries
4268 from changing state to DONE while they have children that are not DONE@.
4269 Furthermore, if an entry has a property @code{ORDERED}, each of its children
4270 will be blocked until all earlier siblings are marked DONE@. Here is an
4274 * TODO Blocked until (two) is done
4283 ** TODO b, needs to wait for (a)
4284 ** TODO c, needs to wait for (a) and (b)
4288 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4289 @vindex org-track-ordered-property-with-tag
4290 @cindex property, ORDERED
4291 Toggle the @code{ORDERED} property of the current entry. A property is used
4292 for this behavior because this should be local to the current entry, not
4293 inherited like a tag. However, if you would like to @i{track} the value of
4294 this property with a tag for better visibility, customize the option
4295 @code{org-track-ordered-property-with-tag}.
4296 @orgkey{C-u C-u C-u C-c C-t}
4297 Change TODO state, circumventing any state blocking.
4300 @vindex org-agenda-dim-blocked-tasks
4301 If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries
4302 that cannot be closed because of such dependencies will be shown in a dimmed
4303 font or even made invisible in agenda views (@pxref{Agenda views}).
4305 @cindex checkboxes and TODO dependencies
4306 @vindex org-enforce-todo-dependencies
4307 You can also block changes of TODO states by looking at checkboxes
4308 (@pxref{Checkboxes}). If you set the option
4309 @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
4310 checkboxes will be blocked from switching to DONE.
4312 If you need more complex dependency structures, for example dependencies
4313 between entries in different trees or files, check out the contributed
4314 module @file{org-depend.el}.
4317 @node Progress logging
4318 @section Progress logging
4319 @cindex progress logging
4320 @cindex logging, of progress
4322 Org mode can automatically record a timestamp and possibly a note when
4323 you mark a TODO item as DONE, or even each time you change the state of
4324 a TODO item. This system is highly configurable; settings can be on a
4325 per-keyword basis and can be localized to a file or even a subtree. For
4326 information on how to clock working time for a task, see @ref{Clocking
4330 * Closing items:: When was this entry marked DONE?
4331 * Tracking TODO state changes:: When did the status change?
4332 * Tracking your habits:: How consistent have you been?
4336 @subsection Closing items
4338 The most basic logging is to keep track of @emph{when} a certain TODO
4339 item was finished. This is achieved with@footnote{The corresponding
4340 in-buffer setting is: @code{#+STARTUP: logdone}}
4343 (setq org-log-done 'time)
4346 @vindex org-closed-keep-when-no-todo
4348 Then each time you turn an entry from a TODO (not-done) state into any of the
4349 DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
4350 the headline. If you turn the entry back into a TODO item through further
4351 state cycling, that line will be removed again. If you turn the entry back
4352 to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line
4353 will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
4354 non-@code{nil}. If you want to record a note along with the timestamp,
4355 use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
4359 (setq org-log-done 'note)
4363 You will then be prompted for a note, and that note will be stored below
4364 the entry with a @samp{Closing Note} heading.
4366 In the timeline (@pxref{Timeline}) and in the agenda
4367 (@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key to
4368 display the TODO items with a @samp{CLOSED} timestamp on each day,
4369 giving you an overview of what has been done.
4371 @node Tracking TODO state changes
4372 @subsection Tracking TODO state changes
4373 @cindex drawer, for state change recording
4375 @vindex org-log-states-order-reversed
4376 @vindex org-log-into-drawer
4377 @cindex property, LOG_INTO_DRAWER
4378 When TODO keywords are used as workflow states (@pxref{Workflow states}), you
4379 might want to keep track of when a state change occurred and maybe take a
4380 note about this change. You can either record just a timestamp, or a
4381 time-stamped note for a change. These records will be inserted after the
4382 headline as an itemized list, newest first@footnote{See the option
4383 @code{org-log-states-order-reversed}}. When taking a lot of notes, you might
4384 want to get the notes out of the way into a drawer (@pxref{Drawers}).
4385 Customize @code{org-log-into-drawer} to get this behavior---the recommended
4386 drawer for this is called @code{LOGBOOK}@footnote{Note that the
4387 @code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to
4388 show an entry---use @key{C-u SPC} to keep it folded here}. You can also
4389 overrule the setting of this variable for a subtree by setting a
4390 @code{LOG_INTO_DRAWER} property.
4392 Since it is normally too much to record a note for every state, Org mode
4393 expects configuration on a per-keyword basis for this. This is achieved by
4394 adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note
4395 with timestamp) in parentheses after each keyword. For example, with the
4399 (setq org-todo-keywords
4400 '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
4403 To record a timestamp without a note for TODO keywords configured with
4404 @samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
4407 @vindex org-log-done
4408 You not only define global TODO keywords and fast access keys, but also
4409 request that a time is recorded when the entry is set to
4410 DONE@footnote{It is possible that Org mode will record two timestamps
4411 when you are using both @code{org-log-done} and state change logging.
4412 However, it will never prompt for two notes---if you have configured
4413 both, the state change recording note will take precedence and cancel
4414 the @samp{Closing Note}.}, and that a note is recorded when switching to
4415 WAIT or CANCELED@. The setting for WAIT is even more special: the
4416 @samp{!} after the slash means that in addition to the note taken when
4417 entering the state, a timestamp should be recorded when @i{leaving} the
4418 WAIT state, if and only if the @i{target} state does not configure
4419 logging for entering it. So it has no effect when switching from WAIT
4420 to DONE, because DONE is configured to record a timestamp only. But
4421 when switching from WAIT back to TODO, the @samp{/!} in the WAIT
4422 setting now triggers a timestamp even though TODO has no logging
4425 You can use the exact same syntax for setting logging preferences local
4428 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
4431 @cindex property, LOGGING
4432 In order to define logging settings that are local to a subtree or a
4433 single item, define a LOGGING property in this entry. Any non-empty
4434 LOGGING property resets all logging settings to @code{nil}. You may then turn
4435 on logging for this specific tree using STARTUP keywords like
4436 @code{lognotedone} or @code{logrepeat}, as well as adding state specific
4437 settings like @code{TODO(!)}. For example
4440 * TODO Log each state with only a time
4442 :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
4444 * TODO Only log when switching to WAIT, and when repeating
4446 :LOGGING: WAIT(@@) logrepeat
4448 * TODO No logging at all
4454 @node Tracking your habits
4455 @subsection Tracking your habits
4458 Org has the ability to track the consistency of a special category of TODOs,
4459 called ``habits''. A habit has the following properties:
4463 You have enabled the @code{habits} module by customizing @code{org-modules}.
4465 The habit is a TODO item, with a TODO keyword representing an open state.
4467 The property @code{STYLE} is set to the value @code{habit}.
4469 The TODO has a scheduled date, usually with a @code{.+} style repeat
4470 interval. A @code{++} style may be appropriate for habits with time
4471 constraints, e.g., must be done on weekends, or a @code{+} style for an
4472 unusual habit that can have a backlog, e.g., weekly reports.
4474 The TODO may also have minimum and maximum ranges specified by using the
4475 syntax @samp{.+2d/3d}, which says that you want to do the task at least every
4476 three days, but at most every two days.
4478 You must also have state logging for the @code{DONE} state enabled
4479 (@pxref{Tracking TODO state changes}), in order for historical data to be
4480 represented in the consistency graph. If it is not enabled it is not an
4481 error, but the consistency graphs will be largely meaningless.
4484 To give you an idea of what the above rules look like in action, here's an
4485 actual habit with some history:
4489 SCHEDULED: <2009-10-17 Sat .+2d/4d>
4490 - State "DONE" from "TODO" [2009-10-15 Thu]
4491 - State "DONE" from "TODO" [2009-10-12 Mon]
4492 - State "DONE" from "TODO" [2009-10-10 Sat]
4493 - State "DONE" from "TODO" [2009-10-04 Sun]
4494 - State "DONE" from "TODO" [2009-10-02 Fri]
4495 - State "DONE" from "TODO" [2009-09-29 Tue]
4496 - State "DONE" from "TODO" [2009-09-25 Fri]
4497 - State "DONE" from "TODO" [2009-09-19 Sat]
4498 - State "DONE" from "TODO" [2009-09-16 Wed]
4499 - State "DONE" from "TODO" [2009-09-12 Sat]
4502 :LAST_REPEAT: [2009-10-19 Mon 00:36]
4506 What this habit says is: I want to shave at most every 2 days (given by the
4507 @code{SCHEDULED} date and repeat interval) and at least every 4 days. If
4508 today is the 15th, then the habit first appears in the agenda on Oct 17,
4509 after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
4510 after four days have elapsed.
4512 What's really useful about habits is that they are displayed along with a
4513 consistency graph, to show how consistent you've been at getting that task
4514 done in the past. This graph shows every day that the task was done over the
4515 past three weeks, with colors for each day. The colors used are:
4519 If the task wasn't to be done yet on that day.
4521 If the task could have been done on that day.
4523 If the task was going to be overdue the next day.
4525 If the task was overdue on that day.
4528 In addition to coloring each day, the day is also marked with an asterisk if
4529 the task was actually done that day, and an exclamation mark to show where
4530 the current day falls in the graph.
4532 There are several configuration variables that can be used to change the way
4533 habits are displayed in the agenda.
4536 @item org-habit-graph-column
4537 The buffer column at which the consistency graph should be drawn. This will
4538 overwrite any text in that column, so it is a good idea to keep your habits'
4539 titles brief and to the point.
4540 @item org-habit-preceding-days
4541 The amount of history, in days before today, to appear in consistency graphs.
4542 @item org-habit-following-days
4543 The number of days after today that will appear in consistency graphs.
4544 @item org-habit-show-habits-only-for-today
4545 If non-@code{nil}, only show habits in today's agenda view. This is set to true by
4549 Lastly, pressing @kbd{K} in the agenda buffer will cause habits to
4550 temporarily be disabled and they won't appear at all. Press @kbd{K} again to
4551 bring them back. They are also subject to tag filtering, if you have habits
4552 which should only be done in certain contexts, for example.
4558 If you use Org mode extensively, you may end up with enough TODO items that
4559 it starts to make sense to prioritize them. Prioritizing can be done by
4560 placing a @emph{priority cookie} into the headline of a TODO item, like this
4563 *** TODO [#A] Write letter to Sam Fortune
4567 @vindex org-priority-faces
4568 By default, Org mode supports three priorities: @samp{A}, @samp{B}, and
4569 @samp{C}. @samp{A} is the highest priority. An entry without a cookie is
4570 treated just like priority @samp{B}. Priorities make a difference only for
4571 sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
4572 have no inherent meaning to Org mode. The cookies can be highlighted with
4573 special faces by customizing @code{org-priority-faces}.
4575 Priorities can be attached to any outline node; they do not need to be TODO
4581 @findex org-priority
4582 Set the priority of the current headline (@command{org-priority}). The
4583 command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
4584 When you press @key{SPC} instead, the priority cookie is removed from the
4585 headline. The priorities can also be changed ``remotely'' from the timeline
4586 and agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
4588 @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
4589 @vindex org-priority-start-cycle-with-default
4590 Increase/decrease priority of current headline@footnote{See also the option
4591 @code{org-priority-start-cycle-with-default}.}. Note that these keys are
4592 also used to modify timestamps (@pxref{Creating timestamps}). See also
4593 @ref{Conflicts}, for a discussion of the interaction with
4594 @code{shift-selection-mode}.
4597 @vindex org-highest-priority
4598 @vindex org-lowest-priority
4599 @vindex org-default-priority
4600 You can change the range of allowed priorities by setting the options
4601 @code{org-highest-priority}, @code{org-lowest-priority}, and
4602 @code{org-default-priority}. For an individual buffer, you may set
4603 these values (highest, lowest, default) like this (please make sure that
4604 the highest priority is earlier in the alphabet than the lowest
4607 @cindex #+PRIORITIES
4612 @node Breaking down tasks
4613 @section Breaking tasks down into subtasks
4614 @cindex tasks, breaking down
4615 @cindex statistics, for TODO items
4617 @vindex org-agenda-todo-list-sublevels
4618 It is often advisable to break down large tasks into smaller, manageable
4619 subtasks. You can do this by creating an outline tree below a TODO item,
4620 with detailed subtasks on the tree@footnote{To keep subtasks out of the
4621 global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep
4622 the overview over the fraction of subtasks that are already completed, insert
4623 either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will
4624 be updated each time the TODO status of a child changes, or when pressing
4625 @kbd{C-c C-c} on the cookie. For example:
4628 * Organize Party [33%]
4629 ** TODO Call people [1/2]
4633 ** DONE Talk to neighbor
4636 @cindex property, COOKIE_DATA
4637 If a heading has both checkboxes and TODO children below it, the meaning of
4638 the statistics cookie become ambiguous. Set the property
4639 @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
4642 @vindex org-hierarchical-todo-statistics
4643 If you would like to have the statistics cookie count any TODO entries in the
4644 subtree (not just direct children), configure
4645 @code{org-hierarchical-todo-statistics}. To do this for a single subtree,
4646 include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
4650 * Parent capturing statistics [2/20]
4652 :COOKIE_DATA: todo recursive
4656 If you would like a TODO entry to automatically change to DONE
4657 when all children are done, you can use the following setup:
4660 (defun org-summary-todo (n-done n-not-done)
4661 "Switch entry to DONE when all subentries are done, to TODO otherwise."
4662 (let (org-log-done org-log-states) ; turn off logging
4663 (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
4665 (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
4669 Another possibility is the use of checkboxes to identify (a hierarchy of) a
4670 large number of subtasks (@pxref{Checkboxes}).
4677 @vindex org-list-automatic-rules
4678 Every item in a plain list@footnote{With the exception of description
4679 lists. But you can allow it by modifying @code{org-list-automatic-rules}
4680 accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
4681 it with the string @samp{[ ]}. This feature is similar to TODO items
4682 (@pxref{TODO items}), but is more lightweight. Checkboxes are not included
4683 in the global TODO list, so they are often great to split a task into a
4684 number of simple steps. Or you can use them in a shopping list. To toggle a
4685 checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
4686 @file{org-mouse.el}).
4688 Here is an example of a checkbox list.
4691 * TODO Organize party [2/4]
4692 - [-] call people [1/3]
4697 - [ ] think about what music to play
4698 - [X] talk to the neighbors
4701 Checkboxes work hierarchically, so if a checkbox item has children that
4702 are checkboxes, toggling one of the children checkboxes will make the
4703 parent checkbox reflect if none, some, or all of the children are
4706 @cindex statistics, for checkboxes
4707 @cindex checkbox statistics
4708 @cindex property, COOKIE_DATA
4709 @vindex org-checkbox-hierarchical-statistics
4710 The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
4711 indicating how many checkboxes present in this entry have been checked off,
4712 and the total number of checkboxes present. This can give you an idea on how
4713 many checkboxes remain, even without opening a folded entry. The cookies can
4714 be placed into a headline or into (the first line of) a plain list item.
4715 Each cookie covers checkboxes of direct children structurally below the
4716 headline/item on which the cookie appears@footnote{Set the option
4717 @code{org-checkbox-hierarchical-statistics} if you want such cookies to
4718 count all checkboxes below the cookie, not just those belonging to direct
4719 children.}. You have to insert the cookie yourself by typing either
4720 @samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}
4721 result, as in the examples above. With @samp{[%]} you get information about
4722 the percentage of checkboxes checked (in the above example, this would be
4723 @samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie can
4724 count either checkboxes below the heading or TODO states of children, and it
4725 will display whatever was changed last. Set the property @code{COOKIE_DATA}
4726 to either @samp{checkbox} or @samp{todo} to resolve this issue.
4728 @cindex blocking, of checkboxes
4729 @cindex checkbox blocking
4730 @cindex property, ORDERED
4731 If the current outline node has an @code{ORDERED} property, checkboxes must
4732 be checked off in sequence, and an error will be thrown if you try to check
4733 off a box while there are unchecked boxes above it.
4735 @noindent The following commands work with checkboxes:
4738 @orgcmd{C-c C-c,org-toggle-checkbox}
4739 Toggle checkbox status or (with prefix arg) checkbox presence at point.
4740 With a single prefix argument, add an empty checkbox or remove the current
4741 one@footnote{@kbd{C-u C-c C-c} on the @emph{first} item of a list with no checkbox
4742 will add checkboxes to the rest of the list.}. With a double prefix argument, set it to @samp{[-]}, which is
4743 considered to be an intermediate state.
4744 @orgcmd{C-c C-x C-b,org-toggle-checkbox}
4745 Toggle checkbox status or (with prefix arg) checkbox presence at point. With
4746 double prefix argument, set it to @samp{[-]}, which is considered to be an
4750 If there is an active region, toggle the first checkbox in the region
4751 and set all remaining boxes to the same status as the first. With a prefix
4752 arg, add or remove the checkbox for all items in the region.
4754 If the cursor is in a headline, toggle checkboxes in the region between
4755 this headline and the next (so @emph{not} the entire subtree).
4757 If there is no active region, just toggle the checkbox at point.
4759 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
4760 Insert a new item with a checkbox. This works only if the cursor is already
4761 in a plain list item (@pxref{Plain lists}).
4762 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4763 @vindex org-track-ordered-property-with-tag
4764 @cindex property, ORDERED
4765 Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
4766 be checked off in sequence. A property is used for this behavior because
4767 this should be local to the current entry, not inherited like a tag.
4768 However, if you would like to @i{track} the value of this property with a tag
4769 for better visibility, customize @code{org-track-ordered-property-with-tag}.
4770 @orgcmd{C-c #,org-update-statistics-cookies}
4771 Update the statistics cookie in the current outline entry. When called with
4772 a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are
4773 updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
4774 new ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update when
4775 changing TODO states. If you delete boxes/entries or add/change them by
4776 hand, use this command to get things back into sync.
4782 @cindex headline tagging
4783 @cindex matching, tags
4784 @cindex sparse tree, tag based
4786 An excellent way to implement labels and contexts for cross-correlating
4787 information is to assign @i{tags} to headlines. Org mode has extensive
4790 @vindex org-tag-faces
4791 Every headline can contain a list of tags; they occur at the end of the
4792 headline. Tags are normal words containing letters, numbers, @samp{_}, and
4793 @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
4794 @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
4795 Tags will by default be in bold face with the same color as the headline.
4796 You may specify special faces for specific tags using the option
4797 @code{org-tag-faces}, in much the same way as you can for TODO keywords
4798 (@pxref{Faces for TODO keywords}).
4801 * Tag inheritance:: Tags use the tree structure of the outline
4802 * Setting tags:: How to assign tags to a headline
4803 * Tag groups:: Use one tag to search for several tags
4804 * Tag searches:: Searching for combinations of tags
4807 @node Tag inheritance
4808 @section Tag inheritance
4809 @cindex tag inheritance
4810 @cindex inheritance, of tags
4811 @cindex sublevels, inclusion into tags match
4813 @i{Tags} make use of the hierarchical structure of outline trees. If a
4814 heading has a certain tag, all subheadings will inherit the tag as
4815 well. For example, in the list
4818 * Meeting with the French group :work:
4819 ** Summary by Frank :boss:notes:
4820 *** TODO Prepare slides for him :action:
4824 the final heading will have the tags @samp{:work:}, @samp{:boss:},
4825 @samp{:notes:}, and @samp{:action:} even though the final heading is not
4826 explicitly marked with those tags. You can also set tags that all entries in
4827 a file should inherit just as if these tags were defined in a hypothetical
4828 level zero that surrounds the entire file. Use a line like this@footnote{As
4829 with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
4830 changes in the line.}:
4834 #+FILETAGS: :Peter:Boss:Secret:
4838 @vindex org-use-tag-inheritance
4839 @vindex org-tags-exclude-from-inheritance
4840 To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
4841 To turn it off entirely, use @code{org-use-tag-inheritance}.
4843 @vindex org-tags-match-list-sublevels
4844 When a headline matches during a tags search while tag inheritance is turned
4845 on, all the sublevels in the same tree will (for a simple match form) match
4846 as well@footnote{This is only true if the search does not involve more
4847 complex tests including properties (@pxref{Property searches}).}. The list
4848 of matches may then become very long. If you only want to see the first tags
4849 match in a subtree, configure @code{org-tags-match-list-sublevels} (not
4852 @vindex org-agenda-use-tag-inheritance
4853 Tag inheritance is relevant when the agenda search tries to match a tag,
4854 either in the @code{tags} or @code{tags-todo} agenda types. In other agenda
4855 types, @code{org-use-tag-inheritance} has no effect. Still, you may want to
4856 have your tags correctly set in the agenda, so that tag filtering works fine,
4857 with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control
4858 this: the default value includes all agenda types, but setting this to @code{nil}
4859 can really speed up agenda generation.
4862 @section Setting tags
4863 @cindex setting tags
4864 @cindex tags, setting
4867 Tags can simply be typed into the buffer at the end of a headline.
4868 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
4869 also a special command for inserting tags:
4872 @orgcmd{C-c C-q,org-set-tags-command}
4873 @cindex completion, of tags
4874 @vindex org-tags-column
4875 Enter new tags for the current headline. Org mode will either offer
4876 completion or a special single-key interface for setting tags, see
4877 below. After pressing @key{RET}, the tags will be inserted and aligned
4878 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
4879 tags in the current buffer will be aligned to that column, just to make
4880 things look nice. TAGS are automatically realigned after promotion,
4881 demotion, and TODO state changes (@pxref{TODO basics}).
4883 @orgcmd{C-c C-c,org-set-tags-command}
4884 When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
4887 @vindex org-tag-alist
4888 Org supports tag insertion based on a @emph{list of tags}. By
4889 default this list is constructed dynamically, containing all tags
4890 currently used in the buffer. You may also globally specify a hard list
4891 of tags with the variable @code{org-tag-alist}. Finally you can set
4892 the default tags for a given file with lines like
4896 #+TAGS: @@work @@home @@tennisclub
4897 #+TAGS: laptop car pc sailboat
4900 If you have globally defined your preferred set of tags using the
4901 variable @code{org-tag-alist}, but would like to use a dynamic tag list
4902 in a specific file, add an empty TAGS option line to that file:
4908 @vindex org-tag-persistent-alist
4909 If you have a preferred set of tags that you would like to use in every file,
4910 in addition to those defined on a per-file basis by TAGS option lines, then
4911 you may specify a list of tags with the variable
4912 @code{org-tag-persistent-alist}. You may turn this off on a per-file basis
4913 by adding a STARTUP option line to that file:
4919 By default Org mode uses the standard minibuffer completion facilities for
4920 entering tags. However, it also implements another, quicker, tag selection
4921 method called @emph{fast tag selection}. This allows you to select and
4922 deselect tags with just a single key press. For this to work well you should
4923 assign unique letters to most of your commonly used tags. You can do this
4924 globally by configuring the variable @code{org-tag-alist} in your
4925 @file{.emacs} file. For example, you may find the need to tag many items in
4926 different files with @samp{:@@home:}. In this case you can set something
4930 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
4933 @noindent If the tag is only relevant to the file you are working on, then you
4934 can instead set the TAGS option line as:
4937 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
4940 @noindent The tags interface will show the available tags in a splash
4941 window. If you want to start a new line after a specific tag, insert
4942 @samp{\n} into the tag list
4945 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p)
4948 @noindent or write them in two lines:
4951 #+TAGS: @@work(w) @@home(h) @@tennisclub(t)
4952 #+TAGS: laptop(l) pc(p)
4956 You can also group together tags that are mutually exclusive by using
4960 #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)
4963 @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
4964 and @samp{@@tennisclub} should be selected. Multiple such groups are allowed.
4966 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
4967 these lines to activate any changes.
4970 To set these mutually exclusive groups in the variable @code{org-tag-alist},
4971 you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
4972 of the braces. Similarly, you can use @code{:newline} to indicate a line
4973 break. The previous example would be set globally by the following
4977 (setq org-tag-alist '((:startgroup . nil)
4978 ("@@work" . ?w) ("@@home" . ?h)
4979 ("@@tennisclub" . ?t)
4981 ("laptop" . ?l) ("pc" . ?p)))
4984 If at least one tag has a selection key then pressing @kbd{C-c C-c} will
4985 automatically present you with a special interface, listing inherited tags,
4986 the tags of the current headline, and a list of all valid tags with
4987 corresponding keys@footnote{Keys will automatically be assigned to tags which
4988 have no configured keys.}. In this interface, you can use the following
4993 Pressing keys assigned to tags will add or remove them from the list of
4994 tags in the current line. Selecting a tag in a group of mutually
4995 exclusive tags will turn off any other tags from that group.
4998 Enter a tag in the minibuffer, even if the tag is not in the predefined
4999 list. You will be able to complete on all tags present in the buffer.
5000 You can also add several tags: just separate them with a comma.
5004 Clear all tags for this line.
5007 Accept the modified set.
5009 Abort without installing changes.
5011 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
5013 Turn off groups of mutually exclusive tags. Use this to (as an
5014 exception) assign several tags from such a group.
5016 Toggle auto-exit after the next change (see below).
5017 If you are using expert mode, the first @kbd{C-c} will display the
5022 This method lets you assign tags to a headline with very few keys. With
5023 the above setup, you could clear the current tags and set @samp{@@home},
5024 @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
5025 C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to
5026 @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
5027 alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
5028 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
5029 @key{RET} @key{RET}}.
5031 @vindex org-fast-tag-selection-single-key
5032 If you find that most of the time you need only a single key press to
5033 modify your list of tags, set @code{org-fast-tag-selection-single-key}.
5034 Then you no longer have to press @key{RET} to exit fast tag selection---it
5035 will immediately exit after the first change. If you then occasionally
5036 need more keys, press @kbd{C-c} to turn off auto-exit for the current tag
5037 selection process (in effect: start selection with @kbd{C-c C-c C-c}
5038 instead of @kbd{C-c C-c}). If you set the variable to the value
5039 @code{expert}, the special window is not even shown for single-key tag
5040 selection, it comes up only when you press an extra @kbd{C-c}.
5046 @cindex tags, groups
5047 In a set of mutually exclusive tags, the first tag can be defined as a
5048 @emph{group tag}. When you search for a group tag, it will return matches
5049 for all members in the group. In an agenda view, filtering by a group tag
5050 will display headlines tagged with at least one of the members of the
5051 group. This makes tag searches and filters even more flexible.
5053 You can set group tags by inserting a colon between the group tag and other
5054 tags---beware that all whitespaces are mandatory so that Org can parse this
5058 #+TAGS: @{ @@read : @@read_book @@read_ebook @}
5061 In this example, @samp{@@read} is a @emph{group tag} for a set of three
5062 tags: @samp{@@read}, @samp{@@read_book} and @samp{@@read_ebook}.
5064 You can also use the @code{:grouptags} keyword directly when setting
5065 @code{org-tag-alist}:
5068 (setq org-tag-alist '((:startgroup . nil)
5071 ("@@read_book" . nil)
5072 ("@@read_ebook" . nil)
5076 You cannot nest group tags or use a group tag as a tag in another group.
5079 @vindex org-group-tags
5080 If you want to ignore group tags temporarily, toggle group tags support
5081 with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you
5082 want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
5085 @section Tag searches
5086 @cindex tag searches
5087 @cindex searching for tags
5089 Once a system of tags has been set up, it can be used to collect related
5090 information into special lists.
5093 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5094 Create a sparse tree with all headlines matching a tags/property/TODO search.
5095 With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5096 @xref{Matching tags and properties}.
5097 @orgcmd{C-c a m,org-tags-view}
5098 Create a global list of tag matches from all agenda files. @xref{Matching
5099 tags and properties}.
5100 @orgcmd{C-c a M,org-tags-view}
5101 @vindex org-tags-match-list-sublevels
5102 Create a global list of tag matches from all agenda files, but check
5103 only TODO items and force checking subitems (see the option
5104 @code{org-tags-match-list-sublevels}).
5107 These commands all prompt for a match string which allows basic Boolean logic
5108 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
5109 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
5110 which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the search
5111 string is rich and allows also matching against TODO keywords, entry levels
5112 and properties. For a complete description with many examples, see
5113 @ref{Matching tags and properties}.
5116 @node Properties and columns
5117 @chapter Properties and columns
5120 A property is a key-value pair associated with an entry. Properties can be
5121 set so they are associated with a single entry, with every entry in a tree,
5122 or with every entry in an Org mode file.
5124 There are two main applications for properties in Org mode. First,
5125 properties are like tags, but with a value. Imagine maintaining a file where
5126 you document bugs and plan releases for a piece of software. Instead of
5127 using tags like @code{:release_1:}, @code{:release_2:}, you can use a
5128 property, say @code{:Release:}, that in different subtrees has different
5129 values, such as @code{1.0} or @code{2.0}. Second, you can use properties to
5130 implement (very basic) database capabilities in an Org buffer. Imagine
5131 keeping track of your music CDs, where properties could be things such as the
5132 album, artist, date of release, number of tracks, and so on.
5134 Properties can be conveniently edited and viewed in column view
5135 (@pxref{Column view}).
5138 * Property syntax:: How properties are spelled out
5139 * Special properties:: Access to other Org mode features
5140 * Property searches:: Matching property values
5141 * Property inheritance:: Passing values down the tree
5142 * Column view:: Tabular viewing and editing
5143 * Property API:: Properties for Lisp programmers
5146 @node Property syntax
5147 @section Property syntax
5148 @cindex property syntax
5149 @cindex drawer, for properties
5151 Properties are key-value pairs. When they are associated with a single entry
5152 or with a tree they need to be inserted into a special
5153 drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property
5154 is specified on a single line, with the key (surrounded by colons)
5155 first, and the value after it. Here is an example:
5160 *** Goldberg Variations
5162 :Title: Goldberg Variations
5163 :Composer: J.S. Bach
5165 :Publisher: Deutsche Grammophon
5170 Depending on the value of @code{org-use-property-inheritance}, a property set
5171 this way will either be associated with a single entry, or the sub-tree
5172 defined by the entry, see @ref{Property inheritance}.
5174 You may define the allowed values for a particular property @samp{:Xyz:}
5175 by setting a property @samp{:Xyz_ALL:}. This special property is
5176 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
5177 the entire tree. When allowed values are defined, setting the
5178 corresponding property becomes easier and is less prone to typing
5179 errors. For the example with the CD collection, we can predefine
5180 publishers and the number of disks in a box like this:
5185 :NDisks_ALL: 1 2 3 4
5186 :Publisher_ALL: "Deutsche Grammophon" Philips EMI
5190 If you want to set properties that can be inherited by any entry in a
5191 file, use a line like
5192 @cindex property, _ALL
5195 #+PROPERTY: NDisks_ALL 1 2 3 4
5198 Contrary to properties set from a special drawer, you have to refresh the
5199 buffer with @kbd{C-c C-c} to activate this change.
5201 If you want to add to the value of an existing property, append a @code{+} to
5202 the property name. The following results in the property @code{var} having
5203 the value ``foo=1 bar=2''.
5206 #+PROPERTY: var foo=1
5207 #+PROPERTY: var+ bar=2
5210 It is also possible to add to the values of inherited properties. The
5211 following results in the @code{genres} property having the value ``Classic
5212 Baroque'' under the @code{Goldberg Variations} subtree.
5220 *** Goldberg Variations
5222 :Title: Goldberg Variations
5223 :Composer: J.S. Bach
5225 :Publisher: Deutsche Grammophon
5230 Note that a property can only have one entry per Drawer.
5232 @vindex org-global-properties
5233 Property values set with the global variable
5234 @code{org-global-properties} can be inherited by all entries in all
5238 The following commands help to work with properties:
5241 @orgcmd{M-@key{TAB},pcomplete}
5242 After an initial colon in a line, complete property keys. All keys used
5243 in the current file will be offered as possible completions.
5244 @orgcmd{C-c C-x p,org-set-property}
5245 Set a property. This prompts for a property name and a value. If
5246 necessary, the property drawer is created as well.
5247 @item C-u M-x org-insert-drawer RET
5248 @cindex org-insert-drawer
5249 Insert a property drawer into the current entry. The drawer will be
5250 inserted early in the entry, but after the lines with planning
5251 information like deadlines.
5252 @orgcmd{C-c C-c,org-property-action}
5253 With the cursor in a property drawer, this executes property commands.
5254 @orgcmd{C-c C-c s,org-set-property}
5255 Set a property in the current entry. Both the property and the value
5256 can be inserted using completion.
5257 @orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
5258 Switch property at point to the next/previous allowed value.
5259 @orgcmd{C-c C-c d,org-delete-property}
5260 Remove a property from the current entry.
5261 @orgcmd{C-c C-c D,org-delete-property-globally}
5262 Globally remove a property, from all entries in the current file.
5263 @orgcmd{C-c C-c c,org-compute-property-at-point}
5264 Compute the property at point, using the operator and scope from the
5265 nearest column format definition.
5268 @node Special properties
5269 @section Special properties
5270 @cindex properties, special
5272 Special properties provide an alternative access method to Org mode features,
5273 like the TODO state or the priority of an entry, discussed in the previous
5274 chapters. This interface exists so that you can include these states in a
5275 column view (@pxref{Column view}), or to use them in queries. The following
5276 property names are special and (except for @code{:CATEGORY:}) should not be
5277 used as keys in the properties drawer:
5279 @cindex property, special, ID
5280 @cindex property, special, TODO
5281 @cindex property, special, TAGS
5282 @cindex property, special, ALLTAGS
5283 @cindex property, special, CATEGORY
5284 @cindex property, special, PRIORITY
5285 @cindex property, special, DEADLINE
5286 @cindex property, special, SCHEDULED
5287 @cindex property, special, CLOSED
5288 @cindex property, special, TIMESTAMP
5289 @cindex property, special, TIMESTAMP_IA
5290 @cindex property, special, CLOCKSUM
5291 @cindex property, special, CLOCKSUM_T
5292 @cindex property, special, BLOCKED
5293 @c guessing that ITEM is needed in this area; also, should this list be sorted?
5294 @cindex property, special, ITEM
5295 @cindex property, special, FILE
5297 ID @r{A globally unique ID used for synchronization during}
5298 @r{iCalendar or MobileOrg export.}
5299 TODO @r{The TODO keyword of the entry.}
5300 TAGS @r{The tags defined directly in the headline.}
5301 ALLTAGS @r{All tags, including inherited ones.}
5302 CATEGORY @r{The category of an entry.}
5303 PRIORITY @r{The priority of the entry, a string with a single letter.}
5304 DEADLINE @r{The deadline time string, without the angular brackets.}
5305 SCHEDULED @r{The scheduling timestamp, without the angular brackets.}
5306 CLOSED @r{When was this entry closed?}
5307 TIMESTAMP @r{The first keyword-less timestamp in the entry.}
5308 TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
5309 CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}}
5310 @r{must be run first to compute the values in the current buffer.}
5311 CLOCKSUM_T @r{The sum of CLOCK intervals in the subtree for today.}
5312 @r{@code{org-clock-sum-today} must be run first to compute the}
5313 @r{values in the current buffer.}
5314 BLOCKED @r{"t" if task is currently blocked by children or siblings}
5315 ITEM @r{The headline of the entry.}
5316 FILE @r{The filename the entry is located in.}
5319 @node Property searches
5320 @section Property searches
5321 @cindex properties, searching
5322 @cindex searching, of properties
5324 To create sparse trees and special lists with selection based on properties,
5325 the same commands are used as for tag searches (@pxref{Tag searches}).
5328 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5329 Create a sparse tree with all matching entries. With a
5330 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5331 @orgcmd{C-c a m,org-tags-view}
5332 Create a global list of tag/property matches from all agenda files.
5333 @xref{Matching tags and properties}.
5334 @orgcmd{C-c a M,org-tags-view}
5335 @vindex org-tags-match-list-sublevels
5336 Create a global list of tag matches from all agenda files, but check
5337 only TODO items and force checking of subitems (see the option
5338 @code{org-tags-match-list-sublevels}).
5341 The syntax for the search string is described in @ref{Matching tags and
5344 There is also a special command for creating sparse trees based on a
5349 Create a sparse tree based on the value of a property. This first
5350 prompts for the name of a property, and then for a value. A sparse tree
5351 is created with all entries that define this property with the given
5352 value. If you enclose the value in curly braces, it is interpreted as
5353 a regular expression and matched against the property values.
5356 @node Property inheritance
5357 @section Property Inheritance
5358 @cindex properties, inheritance
5359 @cindex inheritance, of properties
5361 @vindex org-use-property-inheritance
5362 The outline structure of Org mode documents lends itself to an
5363 inheritance model of properties: if the parent in a tree has a certain
5364 property, the children can inherit this property. Org mode does not
5365 turn this on by default, because it can slow down property searches
5366 significantly and is often not needed. However, if you find inheritance
5367 useful, you can turn it on by setting the variable
5368 @code{org-use-property-inheritance}. It may be set to @code{t} to make
5369 all properties inherited from the parent, to a list of properties
5370 that should be inherited, or to a regular expression that matches
5371 inherited properties. If a property has the value @code{nil}, this is
5372 interpreted as an explicit undefine of the property, so that inheritance
5373 search will stop at this value and return @code{nil}.
5375 Org mode has a few properties for which inheritance is hard-coded, at
5376 least for the special applications for which they are used:
5378 @cindex property, COLUMNS
5381 The @code{:COLUMNS:} property defines the format of column view
5382 (@pxref{Column view}). It is inherited in the sense that the level
5383 where a @code{:COLUMNS:} property is defined is used as the starting
5384 point for a column view table, independently of the location in the
5385 subtree from where columns view is turned on.
5387 @cindex property, CATEGORY
5388 For agenda view, a category set through a @code{:CATEGORY:} property
5389 applies to the entire subtree.
5391 @cindex property, ARCHIVE
5392 For archiving, the @code{:ARCHIVE:} property may define the archive
5393 location for the entire subtree (@pxref{Moving subtrees}).
5395 @cindex property, LOGGING
5396 The LOGGING property may define logging settings for an entry or a
5397 subtree (@pxref{Tracking TODO state changes}).
5401 @section Column view
5403 A great way to view and edit properties in an outline tree is
5404 @emph{column view}. In column view, each outline node is turned into a
5405 table row. Columns in this table provide access to properties of the
5406 entries. Org mode implements columns by overlaying a tabular structure
5407 over the headline of each item. While the headlines have been turned
5408 into a table row, you can still change the visibility of the outline
5409 tree. For example, you get a compact table by switching to CONTENTS
5410 view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
5411 is active), but you can still open, read, and edit the entry below each
5412 headline. Or, you can switch to column view after executing a sparse
5413 tree command and in this way get a table only for the selected items.
5414 Column view also works in agenda buffers (@pxref{Agenda views}) where
5415 queries have collected selected items, possibly from a number of files.
5418 * Defining columns:: The COLUMNS format property
5419 * Using column view:: How to create and use column view
5420 * Capturing column view:: A dynamic block for column view
5423 @node Defining columns
5424 @subsection Defining columns
5425 @cindex column view, for properties
5426 @cindex properties, column view
5428 Setting up a column view first requires defining the columns. This is
5429 done by defining a column format line.
5432 * Scope of column definitions:: Where defined, where valid?
5433 * Column attributes:: Appearance and content of a column
5436 @node Scope of column definitions
5437 @subsubsection Scope of column definitions
5439 To define a column format for an entire file, use a line like
5443 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5446 To specify a format that only applies to a specific tree, add a
5447 @code{:COLUMNS:} property to the top node of that tree, for example:
5450 ** Top node for columns view
5452 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5456 If a @code{:COLUMNS:} property is present in an entry, it defines columns
5457 for the entry itself, and for the entire subtree below it. Since the
5458 column definition is part of the hierarchical structure of the document,
5459 you can define columns on level 1 that are general enough for all
5460 sublevels, and more specific columns further down, when you edit a
5461 deeper part of the tree.
5463 @node Column attributes
5464 @subsubsection Column attributes
5465 A column definition sets the attributes of a column. The general
5466 definition looks like this:
5469 %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]
5473 Except for the percent sign and the property name, all items are
5474 optional. The individual parts have the following meaning:
5477 @var{width} @r{An integer specifying the width of the column in characters.}
5478 @r{If omitted, the width will be determined automatically.}
5479 @var{property} @r{The property that should be edited in this column.}
5480 @r{Special properties representing meta data are allowed here}
5481 @r{as well (@pxref{Special properties})}
5482 @var{title} @r{The header text for the column. If omitted, the property}
5484 @{@var{summary-type}@} @r{The summary type. If specified, the column values for}
5485 @r{parent nodes are computed from the children.}
5486 @r{Supported summary types are:}
5487 @{+@} @r{Sum numbers in this column.}
5488 @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.}
5489 @{$@} @r{Currency, short for @samp{+;%.2f}.}
5490 @{:@} @r{Sum times, HH:MM, plain numbers are hours.}
5491 @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
5492 @{X/@} @r{Checkbox status, @samp{[n/m]}.}
5493 @{X%@} @r{Checkbox status, @samp{[n%]}.}
5494 @{min@} @r{Smallest number in column.}
5495 @{max@} @r{Largest number.}
5496 @{mean@} @r{Arithmetic mean of numbers.}
5497 @{:min@} @r{Smallest time value in column.}
5498 @{:max@} @r{Largest time value.}
5499 @{:mean@} @r{Arithmetic mean of time values.}
5500 @{@@min@} @r{Minimum age (in days/hours/mins/seconds).}
5501 @{@@max@} @r{Maximum age (in days/hours/mins/seconds).}
5502 @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
5503 @{est+@} @r{Add low-high estimates.}
5507 Be aware that you can only have one summary type for any property you
5508 include. Subsequent columns referencing the same property will all display the
5509 same summary information.
5511 The @code{est+} summary type requires further explanation. It is used for
5512 combining estimates, expressed as low-high ranges. For example, instead
5513 of estimating a particular task will take 5 days, you might estimate it as
5514 5--6 days if you're fairly confident you know how much work is required, or
5515 1--10 days if you don't really know what needs to be done. Both ranges
5516 average at 5.5 days, but the first represents a more predictable delivery.
5518 When combining a set of such estimates, simply adding the lows and highs
5519 produces an unrealistically wide result. Instead, @code{est+} adds the
5520 statistical mean and variance of the sub-tasks, generating a final estimate
5521 from the sum. For example, suppose you had ten tasks, each of which was
5522 estimated at 0.5 to 2 days of work. Straight addition produces an estimate
5523 of 5 to 20 days, representing what to expect if everything goes either
5524 extremely well or extremely poorly. In contrast, @code{est+} estimates the
5525 full job more realistically, at 10--15 days.
5527 Numbers are right-aligned when a format specifier with an explicit width like
5528 @{%5d} or @code{%5.1f} is used.
5530 Here is an example for a complete columns definition, along with allowed
5534 :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.}
5535 %10Time_Estimate@{:@} %CLOCKSUM %CLOCKSUM_T
5536 :Owner_ALL: Tammy Mark Karl Lisa Don
5537 :Status_ALL: "In progress" "Not started yet" "Finished" ""
5538 :Approved_ALL: "[ ]" "[X]"
5542 The first column, @samp{%25ITEM}, means the first 25 characters of the
5543 item itself, i.e., of the headline. You probably always should start the
5544 column definition with the @samp{ITEM} specifier. The other specifiers
5545 create columns @samp{Owner} with a list of names as allowed values, for
5546 @samp{Status} with four different possible values, and for a checkbox
5547 field @samp{Approved}. When no width is given after the @samp{%}
5548 character, the column will be exactly as wide as it needs to be in order
5549 to fully display all values. The @samp{Approved} column does have a
5550 modified title (@samp{Approved?}, with a question mark). Summaries will
5551 be created for the @samp{Time_Estimate} column by adding time duration
5552 expressions like HH:MM, and for the @samp{Approved} column, by providing
5553 an @samp{[X]} status if all children have been checked. The
5554 @samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns are special, they lists the
5555 sums of CLOCK intervals in the subtree, either for all clocks or just for
5558 @node Using column view
5559 @subsection Using column view
5562 @tsubheading{Turning column view on and off}
5563 @orgcmd{C-c C-x C-c,org-columns}
5564 @vindex org-columns-default-format
5565 Turn on column view. If the cursor is before the first headline in the file,
5566 column view is turned on for the entire file, using the @code{#+COLUMNS}
5567 definition. If the cursor is somewhere inside the outline, this command
5568 searches the hierarchy, up from point, for a @code{:COLUMNS:} property that
5569 defines a format. When one is found, the column view table is established
5570 for the tree starting at the entry that contains the @code{:COLUMNS:}
5571 property. If no such property is found, the format is taken from the
5572 @code{#+COLUMNS} line or from the variable @code{org-columns-default-format},
5573 and column view is established for the current entry and its subtree.
5574 @orgcmd{r,org-columns-redo}
5575 Recreate the column view, to include recent changes made in the buffer.
5576 @orgcmd{g,org-columns-redo}
5578 @orgcmd{q,org-columns-quit}
5580 @tsubheading{Editing values}
5581 @item @key{left} @key{right} @key{up} @key{down}
5582 Move through the column view from field to field.
5583 @kindex S-@key{left}
5584 @kindex S-@key{right}
5585 @item S-@key{left}/@key{right}
5586 Switch to the next/previous allowed value of the field. For this, you
5587 have to have specified allowed values for a property.
5589 Directly select the Nth allowed value, @kbd{0} selects the 10th value.
5590 @orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value}
5591 Same as @kbd{S-@key{left}/@key{right}}
5592 @orgcmd{e,org-columns-edit-value}
5593 Edit the property at point. For the special properties, this will
5594 invoke the same interface that you normally use to change that
5595 property. For example, when editing a TAGS property, the tag completion
5596 or fast selection interface will pop up.
5597 @orgcmd{C-c C-c,org-columns-set-tags-or-toggle}
5598 When there is a checkbox at point, toggle it.
5599 @orgcmd{v,org-columns-show-value}
5600 View the full value of this property. This is useful if the width of
5601 the column is smaller than that of the value.
5602 @orgcmd{a,org-columns-edit-allowed}
5603 Edit the list of allowed values for this property. If the list is found
5604 in the hierarchy, the modified value is stored there. If no list is
5605 found, the new value is stored in the first entry that is part of the
5606 current column view.
5607 @tsubheading{Modifying the table structure}
5608 @orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen}
5609 Make the column narrower/wider by one character.
5610 @orgcmd{S-M-@key{right},org-columns-new}
5611 Insert a new column, to the left of the current column.
5612 @orgcmd{S-M-@key{left},org-columns-delete}
5613 Delete the current column.
5616 @node Capturing column view
5617 @subsection Capturing column view
5619 Since column view is just an overlay over a buffer, it cannot be
5620 exported or printed directly. If you want to capture a column view, use
5621 a @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
5622 of this block looks like this:
5624 @cindex #+BEGIN, columnview
5627 #+BEGIN: columnview :hlines 1 :id "label"
5632 @noindent This dynamic block has the following parameters:
5636 This is the most important parameter. Column view is a feature that is
5637 often localized to a certain (sub)tree, and the capture block might be
5638 at a different location in the file. To identify the tree whose view to
5639 capture, you can use 4 values:
5640 @cindex property, ID
5642 local @r{use the tree in which the capture block is located}
5643 global @r{make a global view, including all headings in the file}
5644 "file:@var{path-to-file}"
5645 @r{run column view at the top of this file}
5646 "@var{ID}" @r{call column view in the tree that has an @code{:ID:}}
5647 @r{property with the value @i{label}. You can use}
5648 @r{@kbd{M-x org-id-copy RET} to create a globally unique ID for}
5649 @r{the current entry and copy it to the kill-ring.}
5652 When @code{t}, insert an hline after every line. When a number @var{N}, insert
5653 an hline before each headline with level @code{<= @var{N}}.
5655 When set to @code{t}, force column groups to get vertical lines.
5657 When set to a number, don't capture entries below this level.
5658 @item :skip-empty-rows
5659 When set to @code{t}, skip rows where the only non-empty specifier of the
5660 column view is @code{ITEM}.
5665 The following commands insert or update the dynamic block:
5668 @orgcmd{C-c C-x i,org-insert-columns-dblock}
5669 Insert a dynamic block capturing a column view. You will be prompted
5670 for the scope or ID of the view.
5671 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
5672 Update dynamic block at point. The cursor needs to be in the
5673 @code{#+BEGIN} line of the dynamic block.
5674 @orgcmd{C-u C-c C-x C-u,org-update-all-dblocks}
5675 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
5676 you have several clock table blocks, column-capturing blocks or other dynamic
5680 You can add formulas to the column view table and you may add plotting
5681 instructions in front of the table---these will survive an update of the
5682 block. If there is a @code{#+TBLFM:} after the table, the table will
5683 actually be recalculated automatically after an update.
5685 An alternative way to capture and process property values into a table is
5686 provided by Eric Schulte's @file{org-collector.el} which is a contributed
5687 package@footnote{Contributed packages are not part of Emacs, but are
5688 distributed with the main distribution of Org (visit
5689 @uref{http://orgmode.org}).}. It provides a general API to collect
5690 properties from entries in a certain scope, and arbitrary Lisp expressions to
5691 process these values before inserting them into a table or a dynamic block.
5694 @section The Property API
5695 @cindex properties, API
5696 @cindex API, for properties
5698 There is a full API for accessing and changing properties. This API can
5699 be used by Emacs Lisp programs to work with properties and to implement
5700 features based on them. For more information see @ref{Using the
5703 @node Dates and times
5704 @chapter Dates and times
5710 To assist project planning, TODO items can be labeled with a date and/or
5711 a time. The specially formatted string carrying the date and time
5712 information is called a @emph{timestamp} in Org mode. This may be a
5713 little confusing because timestamp is often used to indicate when
5714 something was created or last changed. However, in Org mode this term
5715 is used in a much wider sense.
5718 * Timestamps:: Assigning a time to a tree entry
5719 * Creating timestamps:: Commands which insert timestamps
5720 * Deadlines and scheduling:: Planning your work
5721 * Clocking work time:: Tracking how long you spend on a task
5722 * Effort estimates:: Planning work effort in advance
5723 * Relative timer:: Notes with a running timer
5724 * Countdown timer:: Starting a countdown timer for a task
5729 @section Timestamps, deadlines, and scheduling
5731 @cindex ranges, time
5736 A timestamp is a specification of a date (possibly with a time or a range of
5737 times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this
5738 simplest form, the day name is optional when you type the date yourself.
5739 However, any dates inserted or modified by Org will add that day name, for
5740 reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16
5741 Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601
5742 date/time format. To use an alternative format, see @ref{Custom time
5743 format}.}. A timestamp can appear anywhere in the headline or body of an Org
5744 tree entry. Its presence causes entries to be shown on specific dates in the
5745 agenda (@pxref{Weekly/daily agenda}). We distinguish:
5748 @item Plain timestamp; Event; Appointment
5751 A simple timestamp just assigns a date/time to an item. This is just
5752 like writing down an appointment or event in a paper agenda. In the
5753 timeline and agenda displays, the headline of an entry associated with a
5754 plain timestamp will be shown exactly on that date.
5757 * Meet Peter at the movies
5758 <2006-11-01 Wed 19:15>
5759 * Discussion on climate change
5760 <2006-11-02 Thu 20:00-22:00>
5763 @item Timestamp with repeater interval
5764 @cindex timestamp, with repeater interval
5765 A timestamp may contain a @emph{repeater interval}, indicating that it
5766 applies not only on the given date, but again and again after a certain
5767 interval of N days (d), weeks (w), months (m), or years (y). The
5768 following will show up in the agenda every Wednesday:
5771 * Pick up Sam at school
5772 <2007-05-16 Wed 12:30 +1w>
5775 @item Diary-style sexp entries
5776 For more complex date specifications, Org mode supports using the special
5777 sexp diary entries implemented in the Emacs calendar/diary
5778 package@footnote{When working with the standard diary sexp functions, you
5779 need to be very careful with the order of the arguments. That order depends
5780 evilly on the variable @code{calendar-date-style} (or, for older Emacs
5781 versions, @code{european-calendar-style}). For example, to specify a date
5782 December 12, 2005, the call might look like @code{(diary-date 12 1 2005)} or
5783 @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
5784 the settings. This has been the source of much confusion. Org mode users
5785 can resort to special versions of these functions like @code{org-date} or
5786 @code{org-anniversary}. These work just like the corresponding @code{diary-}
5787 functions, but with stable ISO order of arguments (year, month, day) wherever
5788 applicable, independent of the value of @code{calendar-date-style}.}. For
5789 example with optional time
5792 * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
5793 <%%(diary-float t 4 2)>
5796 @item Time/Date range
5799 Two timestamps connected by @samp{--} denote a range. The headline
5800 will be shown on the first and last day of the range, and on any dates
5801 that are displayed and fall in the range. Here is an example:
5804 ** Meeting in Amsterdam
5805 <2004-08-23 Mon>--<2004-08-26 Thu>
5808 @item Inactive timestamp
5809 @cindex timestamp, inactive
5810 @cindex inactive timestamp
5811 Just like a plain timestamp, but with square brackets instead of
5812 angular ones. These timestamps are inactive in the sense that they do
5813 @emph{not} trigger an entry to show up in the agenda.
5816 * Gillian comes late for the fifth time
5822 @node Creating timestamps
5823 @section Creating timestamps
5824 @cindex creating timestamps
5825 @cindex timestamps, creating
5827 For Org mode to recognize timestamps, they need to be in the specific
5828 format. All commands listed below produce timestamps in the correct
5832 @orgcmd{C-c .,org-time-stamp}
5833 Prompt for a date and insert a corresponding timestamp. When the cursor is
5834 at an existing timestamp in the buffer, the command is used to modify this
5835 timestamp instead of inserting a new one. When this command is used twice in
5836 succession, a time range is inserted.
5838 @orgcmd{C-c !,org-time-stamp-inactive}
5839 Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
5846 @vindex org-time-stamp-rounding-minutes
5847 Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which
5848 contains date and time. The default time can be rounded to multiples of 5
5849 minutes, see the option @code{org-time-stamp-rounding-minutes}.
5852 Normalize timestamp, insert/fix day name if missing or wrong.
5854 @orgcmd{C-c <,org-date-from-calendar}
5855 Insert a timestamp corresponding to the cursor date in the Calendar.
5857 @orgcmd{C-c >,org-goto-calendar}
5858 Access the Emacs calendar for the current date. If there is a
5859 timestamp in the current line, go to the corresponding date
5862 @orgcmd{C-c C-o,org-open-at-point}
5863 Access the agenda for the date given by the timestamp or -range at
5864 point (@pxref{Weekly/daily agenda}).
5866 @orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day}
5867 Change date at cursor by one day. These key bindings conflict with
5868 shift-selection and related modes (@pxref{Conflicts}).
5870 @orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down}
5871 Change the item under the cursor in a timestamp. The cursor can be on a
5872 year, month, day, hour or minute. When the timestamp contains a time range
5873 like @samp{15:30-16:30}, modifying the first time will also shift the second,
5874 shifting the time block with constant length. To change the length, modify
5875 the second time. Note that if the cursor is in a headline and not at a
5876 timestamp, these same keys modify the priority of an item.
5877 (@pxref{Priorities}). The key bindings also conflict with shift-selection and
5878 related modes (@pxref{Conflicts}).
5880 @orgcmd{C-c C-y,org-evaluate-time-range}
5881 @cindex evaluate time range
5882 Evaluate a time range by computing the difference between start and end.
5883 With a prefix argument, insert result after the time range (in a table: into
5884 the following column).
5889 * The date/time prompt:: How Org mode helps you entering date and time
5890 * Custom time format:: Making dates look different
5893 @node The date/time prompt
5894 @subsection The date/time prompt
5895 @cindex date, reading in minibuffer
5896 @cindex time, reading in minibuffer
5898 @vindex org-read-date-prefer-future
5899 When Org mode prompts for a date/time, the default is shown in default
5900 date/time format, and the prompt therefore seems to ask for a specific
5901 format. But it will in fact accept date/time information in a variety of
5902 formats. Generally, the information should start at the beginning of the
5903 string. Org mode will find whatever information is in
5904 there and derive anything you have not specified from the @emph{default date
5905 and time}. The default is usually the current date and time, but when
5906 modifying an existing timestamp, or when entering the second stamp of a
5907 range, it is taken from the stamp in the buffer. When filling in
5908 information, Org mode assumes that most of the time you will want to enter a
5909 date in the future: if you omit the month/year and the given day/month is
5910 @i{before} today, it will assume that you mean a future date@footnote{See the
5911 variable @code{org-read-date-prefer-future}. You may set that variable to
5912 the symbol @code{time} to even make a time before now shift the date to
5913 tomorrow.}. If the date has been automatically shifted into the future, the
5914 time prompt will show this with @samp{(=>F).}
5916 For example, let's assume that today is @b{June 13, 2006}. Here is how
5917 various inputs will be interpreted, the items filled in by Org mode are
5921 3-2-5 @result{} 2003-02-05
5922 2/5/3 @result{} 2003-02-05
5923 14 @result{} @b{2006}-@b{06}-14
5924 12 @result{} @b{2006}-@b{07}-12
5925 2/5 @result{} @b{2007}-02-05
5926 Fri @result{} nearest Friday after the default date
5927 sep 15 @result{} @b{2006}-09-15
5928 feb 15 @result{} @b{2007}-02-15
5929 sep 12 9 @result{} 2009-09-12
5930 12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45
5931 22 sept 0:34 @result{} @b{2006}-09-22 0:34
5932 w4 @result{} ISO week for of the current year @b{2006}
5933 2012 w4 fri @result{} Friday of ISO week 4 in 2012
5934 2012-w04-5 @result{} Same as above
5937 Furthermore you can specify a relative date by giving, as the @emph{first}
5938 thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to
5939 indicate change in hours, days, weeks, months, or years. With a single plus
5940 or minus, the date is always relative to today. With a double plus or minus,
5941 it is relative to the default date. If instead of a single letter, you use
5942 the abbreviation of day name, the date will be the Nth such day, e.g.:
5947 +4d @result{} four days from today
5948 +4 @result{} same as above
5949 +2w @result{} two weeks from today
5950 ++5 @result{} five days from default date
5951 +2tue @result{} second Tuesday from now
5952 -wed @result{} last Wednesday
5955 @vindex parse-time-months
5956 @vindex parse-time-weekdays
5957 The function understands English month and weekday abbreviations. If
5958 you want to use unabbreviated names and/or other languages, configure
5959 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
5961 @vindex org-read-date-force-compatible-dates
5962 Not all dates can be represented in a given Emacs implementation. By default
5963 Org mode forces dates into the compatibility range 1970--2037 which works on
5964 all Emacs implementations. If you want to use dates outside of this range,
5965 read the docstring of the variable
5966 @code{org-read-date-force-compatible-dates}.
5968 You can specify a time range by giving start and end times or by giving a
5969 start time and a duration (in HH:MM format). Use one or two dash(es) as the
5970 separator in the former case and use '+' as the separator in the latter
5974 11am-1:15pm @result{} 11:00-13:15
5975 11am--1:15pm @result{} same as above
5976 11am+2:15 @result{} same as above
5979 @cindex calendar, for selecting date
5980 @vindex org-popup-calendar-for-date-prompt
5981 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
5982 you don't need/want the calendar, configure the variable
5983 @code{org-popup-calendar-for-date-prompt}.}. When you exit the date
5984 prompt, either by clicking on a date in the calendar, or by pressing
5985 @key{RET}, the date selected in the calendar will be combined with the
5986 information entered at the prompt. You can control the calendar fully
5987 from the minibuffer:
5994 @kindex S-@key{right}
5995 @kindex S-@key{left}
5996 @kindex S-@key{down}
5998 @kindex M-S-@key{right}
5999 @kindex M-S-@key{left}
6002 @key{RET} @r{Choose date at cursor in calendar.}
6003 mouse-1 @r{Select date by clicking on it.}
6004 S-@key{right}/@key{left} @r{One day forward/backward.}
6005 S-@key{down}/@key{up} @r{One week forward/backward.}
6006 M-S-@key{right}/@key{left} @r{One month forward/backward.}
6007 > / < @r{Scroll calendar forward/backward by one month.}
6008 M-v / C-v @r{Scroll calendar forward/backward by 3 months.}
6011 @vindex org-read-date-display-live
6012 The actions of the date/time prompt may seem complex, but I assure you they
6013 will grow on you, and you will start getting annoyed by pretty much any other
6014 way of entering a date/time out there. To help you understand what is going
6015 on, the current interpretation of your input will be displayed live in the
6016 minibuffer@footnote{If you find this distracting, turn the display off with
6017 @code{org-read-date-display-live}.}.
6019 @node Custom time format
6020 @subsection Custom time format
6021 @cindex custom date/time format
6022 @cindex time format, custom
6023 @cindex date format, custom
6025 @vindex org-display-custom-times
6026 @vindex org-time-stamp-custom-formats
6027 Org mode uses the standard ISO notation for dates and times as it is
6028 defined in ISO 8601. If you cannot get used to this and require another
6029 representation of date and time to keep you happy, you can get it by
6030 customizing the options @code{org-display-custom-times} and
6031 @code{org-time-stamp-custom-formats}.
6034 @orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays}
6035 Toggle the display of custom formats for dates and times.
6039 Org mode needs the default format for scanning, so the custom date/time
6040 format does not @emph{replace} the default format---instead it is put
6041 @emph{over} the default format using text properties. This has the
6042 following consequences:
6045 You cannot place the cursor onto a timestamp anymore, only before or
6048 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
6049 each component of a timestamp. If the cursor is at the beginning of
6050 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
6051 just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the
6052 time will be changed by one minute.
6054 If the timestamp contains a range of clock times or a repeater, these
6055 will not be overlaid, but remain in the buffer as they were.
6057 When you delete a timestamp character-by-character, it will only
6058 disappear from the buffer after @emph{all} (invisible) characters
6059 belonging to the ISO timestamp have been removed.
6061 If the custom timestamp format is longer than the default and you are
6062 using dates in tables, table alignment will be messed up. If the custom
6063 format is shorter, things do work as expected.
6067 @node Deadlines and scheduling
6068 @section Deadlines and scheduling
6070 A timestamp may be preceded by special keywords to facilitate planning:
6074 @cindex DEADLINE keyword
6076 Meaning: the task (most likely a TODO item, though not necessarily) is supposed
6077 to be finished on that date.
6079 @vindex org-deadline-warning-days
6080 @vindex org-agenda-skip-deadline-prewarning-if-scheduled
6081 On the deadline date, the task will be listed in the agenda. In
6082 addition, the agenda for @emph{today} will carry a warning about the
6083 approaching or missed deadline, starting
6084 @code{org-deadline-warning-days} before the due date, and continuing
6085 until the entry is marked DONE@. An example:
6088 *** TODO write article about the Earth for the Guide
6089 DEADLINE: <2004-02-29 Sun>
6090 The editor in charge is [[bbdb:Ford Prefect]]
6093 You can specify a different lead time for warnings for a specific
6094 deadline using the following syntax. Here is an example with a warning
6095 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. This warning is
6096 deactivated if the task gets scheduled and you set
6097 @code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}.
6100 @cindex SCHEDULED keyword
6102 Meaning: you are planning to start working on that task on the given
6105 @vindex org-agenda-skip-scheduled-if-done
6106 The headline will be listed under the given date@footnote{It will still
6107 be listed on that date after it has been marked DONE@. If you don't like
6108 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
6109 addition, a reminder that the scheduled date has passed will be present
6110 in the compilation for @emph{today}, until the entry is marked DONE, i.e.,
6111 the task will automatically be forwarded until completed.
6114 *** TODO Call Trillian for a date on New Years Eve.
6115 SCHEDULED: <2004-12-25 Sat>
6118 @vindex org-scheduled-delay-days
6119 @vindex org-agenda-skip-scheduled-delay-if-deadline
6120 If you want to @emph{delay} the display of this task in the agenda, use
6121 @code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the
6122 25th but will appear two days later. In case the task contains a repeater,
6123 the delay is considered to affect all occurrences; if you want the delay to
6124 only affect the first scheduled occurrence of the task, use @code{--2d}
6125 instead. See @code{org-scheduled-delay-days} and
6126 @code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to
6127 control this globally or per agenda.
6130 @b{Important:} Scheduling an item in Org mode should @i{not} be
6131 understood in the same way that we understand @i{scheduling a meeting}.
6132 Setting a date for a meeting is just a simple appointment, you should
6133 mark this entry with a simple plain timestamp, to get this item shown
6134 on the date where it applies. This is a frequent misunderstanding by
6135 Org users. In Org mode, @i{scheduling} means setting a date when you
6136 want to start working on an action item.
6139 You may use timestamps with repeaters in scheduling and deadline
6140 entries. Org mode will issue early and late warnings based on the
6141 assumption that the timestamp represents the @i{nearest instance} of
6142 the repeater. However, the use of diary sexp entries like
6144 @code{<%%(diary-float t 42)>}
6146 in scheduling and deadline timestamps is limited. Org mode does not
6147 know enough about the internals of each sexp function to issue early and
6148 late warnings. However, it will show the item on each day where the
6152 * Inserting deadline/schedule:: Planning items
6153 * Repeated tasks:: Items that show up again and again
6156 @node Inserting deadline/schedule
6157 @subsection Inserting deadlines or schedules
6159 The following commands allow you to quickly insert@footnote{The @samp{SCHEDULED} and
6160 @samp{DEADLINE} dates are inserted on the line right below the headline. Don't put
6161 any text between this line and the headline.} a deadline or to schedule
6166 @orgcmd{C-c C-d,org-deadline}
6167 Insert @samp{DEADLINE} keyword along with a stamp. The insertion will happen
6168 in the line directly following the headline. Any CLOSED timestamp will be
6169 removed. When called with a prefix arg, an existing deadline will be removed
6170 from the entry. Depending on the variable @code{org-log-redeadline}@footnote{with corresponding
6171 @code{#+STARTUP} keywords @code{logredeadline}, @code{lognoteredeadline},
6172 and @code{nologredeadline}}, a note will be taken when changing an existing
6175 @orgcmd{C-c C-s,org-schedule}
6176 Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will
6177 happen in the line directly following the headline. Any CLOSED timestamp
6178 will be removed. When called with a prefix argument, remove the scheduling
6179 date from the entry. Depending on the variable
6180 @code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}
6181 keywords @code{logreschedule}, @code{lognotereschedule}, and
6182 @code{nologreschedule}}, a note will be taken when changing an existing
6185 @orgcmd{C-c C-x C-k,org-mark-entry-for-agenda-action}
6188 Mark the current entry for agenda action. After you have marked the entry
6189 like this, you can open the agenda or the calendar to find an appropriate
6190 date. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to
6191 schedule the marked item.
6193 @orgcmd{C-c / d,org-check-deadlines}
6194 @cindex sparse tree, for deadlines
6195 @vindex org-deadline-warning-days
6196 Create a sparse tree with all deadlines that are either past-due, or
6197 which will become due within @code{org-deadline-warning-days}.
6198 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
6199 prefix, check that many days. For example, @kbd{C-1 C-c / d} shows
6200 all deadlines due tomorrow.
6202 @orgcmd{C-c / b,org-check-before-date}
6203 Sparse tree for deadlines and scheduled items before a given date.
6205 @orgcmd{C-c / a,org-check-after-date}
6206 Sparse tree for deadlines and scheduled items after a given date.
6209 Note that @code{org-schedule} and @code{org-deadline} supports
6210 setting the date by indicating a relative time: e.g., +1d will set
6211 the date to the next day after today, and --1w will set the date
6212 to the previous week before any current timestamp.
6214 @node Repeated tasks
6215 @subsection Repeated tasks
6216 @cindex tasks, repeated
6217 @cindex repeated tasks
6219 Some tasks need to be repeated again and again. Org mode helps to
6220 organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
6221 or plain timestamp. In the following example
6223 ** TODO Pay the rent
6224 DEADLINE: <2005-10-01 Sat +1m>
6227 the @code{+1m} is a repeater; the intended interpretation is that the task
6228 has a deadline on <2005-10-01> and repeats itself every (one) month starting
6229 from that time. You can use yearly, monthly, weekly, daily and hourly repeat
6230 cookies by using the @code{y/w/m/d/h} letters. If you need both a repeater
6231 and a special warning period in a deadline entry, the repeater should come
6232 first and the warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
6234 @vindex org-todo-repeat-to-state
6235 Deadlines and scheduled items produce entries in the agenda when they are
6236 over-due, so it is important to be able to mark such an entry as completed
6237 once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO
6238 keyword DONE, it will no longer produce entries in the agenda. The problem
6239 with this is, however, that then also the @emph{next} instance of the
6240 repeated entry will not be active. Org mode deals with this in the following
6241 way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
6242 shift the base date of the repeating timestamp by the repeater interval, and
6243 immediately set the entry state back to TODO@footnote{In fact, the target
6244 state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or
6245 the variable @code{org-todo-repeat-to-state}. If neither of these is
6246 specified, the target state defaults to the first state of the TODO state
6247 sequence.}. In the example above, setting the state to DONE would actually
6248 switch the date like this:
6251 ** TODO Pay the rent
6252 DEADLINE: <2005-11-01 Tue +1m>
6255 To mark a task with a repeater as @code{DONE}, use @kbd{C-- 1 C-c C-t}
6256 (i.e., @code{org-todo} with a numeric prefix argument of -1.)
6258 @vindex org-log-repeat
6259 A timestamp@footnote{You can change this using the option
6260 @code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},
6261 @code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you
6262 will also be prompted for a note.} will be added under the deadline, to keep
6263 a record that you actually acted on the previous instance of this deadline.
6265 As a consequence of shifting the base date, this entry will no longer be
6266 visible in the agenda when checking past dates, but all future instances
6269 With the @samp{+1m} cookie, the date shift will always be exactly one
6270 month. So if you have not paid the rent for three months, marking this
6271 entry DONE will still keep it as an overdue deadline. Depending on the
6272 task, this may not be the best way to handle it. For example, if you
6273 forgot to call your father for 3 weeks, it does not make sense to call
6274 him 3 times in a single day to make up for it. Finally, there are tasks
6275 like changing batteries which should always repeat a certain time
6276 @i{after} the last time you did it. For these tasks, Org mode has
6277 special repeaters @samp{++} and @samp{.+}. For example:
6281 DEADLINE: <2008-02-10 Sun ++1w>
6282 Marking this DONE will shift the date by at least one week,
6283 but also by as many weeks as it takes to get this date into
6284 the future. However, it stays on a Sunday, even if you called
6285 and marked it done on Saturday.
6286 ** TODO Check the batteries in the smoke detectors
6287 DEADLINE: <2005-11-01 Tue .+1m>
6288 Marking this DONE will shift the date to one month after
6292 @vindex org-agenda-skip-scheduled-if-deadline-is-shown
6293 You may have both scheduling and deadline information for a specific task.
6294 If the repeater is set for the scheduling information only, you probably want
6295 the repeater to be ignored after the deadline. If so, set the variable
6296 @code{org-agenda-skip-scheduled-if-deadline-is-shown} to
6297 @code{repeated-after-deadline}. If you want both scheduling and deadline
6298 information to repeat after the same interval, set the same repeater for both
6301 An alternative to using a repeater is to create a number of copies of a task
6302 subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was
6303 created for this purpose, it is described in @ref{Structure editing}.
6306 @node Clocking work time
6307 @section Clocking work time
6308 @cindex clocking time
6309 @cindex time clocking
6311 Org mode allows you to clock the time you spend on specific tasks in a
6312 project. When you start working on an item, you can start the clock. When
6313 you stop working on that task, or when you mark the task done, the clock is
6314 stopped and the corresponding time interval is recorded. It also computes
6315 the total time spent on each subtree@footnote{Clocking only works if all
6316 headings are indented with less than 30 stars. This is a hardcoded
6317 limitation of `lmax' in `org-clock-sum'.} of a project. And it remembers a
6318 history or tasks recently clocked, so that you can jump quickly between a
6319 number of tasks absorbing your time.
6321 To save the clock history across Emacs sessions, use
6323 (setq org-clock-persist 'history)
6324 (org-clock-persistence-insinuate)
6326 When you clock into a new task after resuming Emacs, the incomplete
6327 clock@footnote{To resume the clock under the assumption that you have worked
6328 on this task while outside Emacs, use @code{(setq org-clock-persist t)}.}
6329 will be found (@pxref{Resolving idle time}) and you will be prompted about
6333 * Clocking commands:: Starting and stopping a clock
6334 * The clock table:: Detailed reports
6335 * Resolving idle time:: Resolving time when you've been idle
6338 @node Clocking commands
6339 @subsection Clocking commands
6342 @orgcmd{C-c C-x C-i,org-clock-in}
6343 @vindex org-clock-into-drawer
6344 @vindex org-clock-continuously
6345 @cindex property, LOG_INTO_DRAWER
6346 Start the clock on the current item (clock-in). This inserts the CLOCK
6347 keyword together with a timestamp. If this is not the first clocking of
6348 this item, the multiple CLOCK lines will be wrapped into a
6349 @code{:LOGBOOK:} drawer (see also the variable
6350 @code{org-clock-into-drawer}). You can also overrule
6351 the setting of this variable for a subtree by setting a
6352 @code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
6353 When called with a @kbd{C-u} prefix argument,
6354 select the task from a list of recently clocked tasks. With two @kbd{C-u
6355 C-u} prefixes, clock into the task at point and mark it as the default task;
6356 the default task will then always be available with letter @kbd{d} when
6357 selecting a clocking task. With three @kbd{C-u C-u C-u} prefixes, force
6358 continuous clocking by starting the clock when the last clock stopped.@*
6359 @cindex property: CLOCK_MODELINE_TOTAL
6360 @cindex property: LAST_REPEAT
6361 @vindex org-clock-modeline-total
6362 While the clock is running, the current clocking time is shown in the mode
6363 line, along with the title of the task. The clock time shown will be all
6364 time ever clocked for this task and its children. If the task has an effort
6365 estimate (@pxref{Effort estimates}), the mode line displays the current
6366 clocking time against it@footnote{To add an effort estimate ``on the fly'',
6367 hook a function doing this to @code{org-clock-in-prepare-hook}.} If the task
6368 is a repeating one (@pxref{Repeated tasks}), only the time since the last
6369 reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}
6370 will be shown. More control over what time is shown can be exercised with
6371 the @code{CLOCK_MODELINE_TOTAL} property. It may have the values
6372 @code{current} to show only the current clocking instance, @code{today} to
6373 show all time clocked on this tasks today (see also the variable
6374 @code{org-extend-today-until}), @code{all} to include all time, or
6375 @code{auto} which is the default@footnote{See also the variable
6376 @code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
6377 mode line entry will pop up a menu with clocking options.
6379 @orgcmd{C-c C-x C-o,org-clock-out}
6380 @vindex org-log-note-clock-out
6381 Stop the clock (clock-out). This inserts another timestamp at the same
6382 location where the clock was last started. It also directly computes
6383 the resulting time and inserts it after the time range as @samp{=>
6384 HH:MM}. See the variable @code{org-log-note-clock-out} for the
6385 possibility to record an additional note together with the clock-out
6386 timestamp@footnote{The corresponding in-buffer setting is:
6387 @code{#+STARTUP: lognoteclock-out}}.
6388 @orgcmd{C-c C-x C-x,org-clock-in-last}
6389 @vindex org-clock-continuously
6390 Reclock the last clocked task. With one @kbd{C-u} prefix argument,
6391 select the task from the clock history. With two @kbd{C-u} prefixes,
6392 force continuous clocking by starting the clock when the last clock
6394 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6395 Update the effort estimate for the current clock task.
6398 @orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range}
6399 Recompute the time interval after changing one of the timestamps. This
6400 is only necessary if you edit the timestamps directly. If you change
6401 them with @kbd{S-@key{cursor}} keys, the update is automatic.
6402 @orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
6403 On @code{CLOCK} log lines, increase/decrease both timestamps so that the
6404 clock duration keeps the same.
6405 @orgcmd{S-M-@key{up/down},org-timestamp-up/down}
6406 On @code{CLOCK} log lines, increase/decrease the timestamp at point and
6407 the one of the previous (or the next clock) timestamp by the same duration.
6408 For example, if you hit @kbd{S-M-@key{up}} to increase a clocked-out timestamp
6409 by five minutes, then the clocked-in timestamp of the next clock will be
6410 increased by five minutes.
6411 @orgcmd{C-c C-t,org-todo}
6412 Changing the TODO state of an item to DONE automatically stops the clock
6413 if it is running in this same item.
6414 @orgcmd{C-c C-x C-q,org-clock-cancel}
6415 Cancel the current clock. This is useful if a clock was started by
6416 mistake, or if you ended up working on something else.
6417 @orgcmd{C-c C-x C-j,org-clock-goto}
6418 Jump to the headline of the currently clocked in task. With a @kbd{C-u}
6419 prefix arg, select the target task from a list of recently clocked tasks.
6420 @orgcmd{C-c C-x C-d,org-clock-display}
6421 @vindex org-remove-highlights-with-change
6422 Display time summaries for each subtree in the current buffer. This puts
6423 overlays at the end of each headline, showing the total time recorded under
6424 that heading, including the time of any subheadings. You can use visibility
6425 cycling to study the tree, but the overlays disappear when you change the
6426 buffer (see variable @code{org-remove-highlights-with-change}) or press
6430 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
6431 the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
6432 worked on or closed during a day.
6434 @strong{Important:} note that both @code{org-clock-out} and
6435 @code{org-clock-in-last} can have a global keybinding and will not
6436 modify the window disposition.
6438 @node The clock table
6439 @subsection The clock table
6440 @cindex clocktable, dynamic block
6441 @cindex report, of clocked time
6443 Org mode can produce quite complex reports based on the time clocking
6444 information. Such a report is called a @emph{clock table}, because it is
6445 formatted as one or several Org tables.
6448 @orgcmd{C-c C-x C-r,org-clock-report}
6449 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
6450 report as an Org mode table into the current file. When the cursor is
6451 at an existing clock table, just update it. When called with a prefix
6452 argument, jump to the first clock report in the current document and
6453 update it. The clock table always includes also trees with
6454 @code{:ARCHIVE:} tag.
6455 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
6456 Update dynamic block at point. The cursor needs to be in the
6457 @code{#+BEGIN} line of the dynamic block.
6458 @orgkey{C-u C-c C-x C-u}
6459 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
6460 you have several clock table blocks in a buffer.
6461 @orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift}
6462 Shift the current @code{:block} interval and update the table. The cursor
6463 needs to be in the @code{#+BEGIN: clocktable} line for this command. If
6464 @code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
6468 Here is an example of the frame for a clock table as it is inserted into the
6469 buffer with the @kbd{C-c C-x C-r} command:
6471 @cindex #+BEGIN, clocktable
6473 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
6477 @vindex org-clocktable-defaults
6478 The @samp{BEGIN} line specifies a number of options to define the scope,
6479 structure, and formatting of the report. Defaults for all these options can
6480 be configured in the variable @code{org-clocktable-defaults}.
6482 @noindent First there are options that determine which clock entries are to
6485 :maxlevel @r{Maximum level depth to which times are listed in the table.}
6486 @r{Clocks at deeper levels will be summed into the upper level.}
6487 :scope @r{The scope to consider. This can be any of the following:}
6488 nil @r{the current buffer or narrowed region}
6489 file @r{the full current buffer}
6490 subtree @r{the subtree where the clocktable is located}
6491 tree@var{N} @r{the surrounding level @var{N} tree, for example @code{tree3}}
6492 tree @r{the surrounding level 1 tree}
6493 agenda @r{all agenda files}
6494 ("file"..) @r{scan these files}
6495 file-with-archives @r{current file and its archives}
6496 agenda-with-archives @r{all agenda files, including archives}
6497 :block @r{The time block to consider. This block is specified either}
6498 @r{absolutely, or relative to the current time and may be any of}
6500 2007-12-31 @r{New year eve 2007}
6501 2007-12 @r{December 2007}
6502 2007-W50 @r{ISO-week 50 in 2007}
6503 2007-Q2 @r{2nd quarter in 2007}
6504 2007 @r{the year 2007}
6505 today, yesterday, today-@var{N} @r{a relative day}
6506 thisweek, lastweek, thisweek-@var{N} @r{a relative week}
6507 thismonth, lastmonth, thismonth-@var{N} @r{a relative month}
6508 thisyear, lastyear, thisyear-@var{N} @r{a relative year}
6509 @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}
6510 :tstart @r{A time string specifying when to start considering times.}
6511 @r{Relative times like @code{"<-2w>"} can also be used. See}
6512 @r{@ref{Matching tags and properties} for relative time syntax.}
6513 :tend @r{A time string specifying when to stop considering times.}
6514 @r{Relative times like @code{"<now>"} can also be used. See}
6515 @r{@ref{Matching tags and properties} for relative time syntax.}
6516 :wstart @r{The starting day of the week. The default is 1 for monday.}
6517 :mstart @r{The starting day of the month. The default 1 is for the first}
6518 @r{day of the month.}
6519 :step @r{@code{week} or @code{day}, to split the table into chunks.}
6520 @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}
6521 :stepskip0 @r{Do not show steps that have zero time.}
6522 :fileskip0 @r{Do not show table sections from files which did not contribute.}
6523 :tags @r{A tags match to select entries that should contribute. See}
6524 @r{@ref{Matching tags and properties} for the match syntax.}
6527 Then there are options which determine the formatting of the table. These
6528 options are interpreted by the function @code{org-clocktable-write-default},
6529 but you can specify your own function using the @code{:formatter} parameter.
6531 :emphasize @r{When @code{t}, emphasize level one and level two items.}
6532 :lang @r{Language@footnote{Language terms can be set through the variable @code{org-clock-clocktable-language-setup}.} to use for descriptive cells like "Task".}
6533 :link @r{Link the item headlines in the table to their origins.}
6534 :narrow @r{An integer to limit the width of the headline column in}
6535 @r{the org table. If you write it like @samp{50!}, then the}
6536 @r{headline will also be shortened in export.}
6537 :indent @r{Indent each headline field according to its level.}
6538 :tcolumns @r{Number of columns to be used for times. If this is smaller}
6539 @r{than @code{:maxlevel}, lower levels will be lumped into one column.}
6540 :level @r{Should a level number column be included?}
6541 :compact @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}}
6542 @r{All are overwritten except if there is an explicit @code{:narrow}}
6543 :timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,}
6544 @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}
6545 :properties @r{List of properties that should be shown in the table. Each}
6546 @r{property will get its own column.}
6547 :inherit-props @r{When this flag is @code{t}, the values for @code{:properties} will be inherited.}
6548 :formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.}
6549 @r{As a special case, @samp{:formula %} adds a column with % time.}
6550 @r{If you do not specify a formula here, any existing formula}
6551 @r{below the clock table will survive updates and be evaluated.}
6552 :formatter @r{A function to format clock data and insert it into the buffer.}
6554 To get a clock summary of the current level 1 tree, for the current
6555 day, you could write
6557 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
6561 and to use a specific time range you could write@footnote{Note that all
6562 parameters must be specified in a single line---the line is broken here
6563 only to fit it into the manual.}
6565 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
6566 :tend "<2006-08-10 Thu 12:00>"
6569 A range starting a week ago and ending right now could be written as
6571 #+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
6574 A summary of the current subtree with % times would be
6576 #+BEGIN: clocktable :scope subtree :link t :formula %
6579 A horizontally compact representation of everything clocked during last week
6582 #+BEGIN: clocktable :scope agenda :block lastweek :compact t
6586 @node Resolving idle time
6587 @subsection Resolving idle time and continuous clocking
6589 @subsubheading Resolving idle time
6590 @cindex resolve idle time
6591 @vindex org-clock-x11idle-program-name
6593 @cindex idle, resolve, dangling
6594 If you clock in on a work item, and then walk away from your
6595 computer---perhaps to take a phone call---you often need to ``resolve'' the
6596 time you were away by either subtracting it from the current clock, or
6597 applying it to another one.
6599 @vindex org-clock-idle-time
6600 By customizing the variable @code{org-clock-idle-time} to some integer, such
6601 as 10 or 15, Emacs can alert you when you get back to your computer after
6602 being idle for that many minutes@footnote{On computers using Mac OS X,
6603 idleness is based on actual user idleness, not just Emacs' idle time. For
6604 X11, you can install a utility program @file{x11idle.c}, available in the
6605 @code{contrib/scripts} directory of the Org git distribution, or install the
6606 @file{xprintidle} package and set it to the variable
6607 @code{org-clock-x11idle-program-name} if you are running Debian, to get the
6608 same general treatment of idleness. On other systems, idle time refers to
6609 Emacs idle time only.}, and ask what you want to do with the idle time.
6610 There will be a question waiting for you when you get back, indicating how
6611 much idle time has passed (constantly updated with the current amount), as
6612 well as a set of choices to correct the discrepancy:
6616 To keep some or all of the minutes and stay clocked in, press @kbd{k}. Org
6617 will ask how many of the minutes to keep. Press @key{RET} to keep them all,
6618 effectively changing nothing, or enter a number to keep that many minutes.
6620 If you use the shift key and press @kbd{K}, it will keep however many minutes
6621 you request and then immediately clock out of that task. If you keep all of
6622 the minutes, this is the same as just clocking out of the current task.
6624 To keep none of the minutes, use @kbd{s} to subtract all the away time from
6625 the clock, and then check back in from the moment you returned.
6627 To keep none of the minutes and just clock out at the start of the away time,
6628 use the shift key and press @kbd{S}. Remember that using shift will always
6629 leave you clocked out, no matter which option you choose.
6631 To cancel the clock altogether, use @kbd{C}. Note that if instead of
6632 canceling you subtract the away time, and the resulting clock amount is less
6633 than a minute, the clock will still be canceled rather than clutter up the
6634 log with an empty entry.
6637 What if you subtracted those away minutes from the current clock, and now
6638 want to apply them to a new clock? Simply clock in to any task immediately
6639 after the subtraction. Org will notice that you have subtracted time ``on
6640 the books'', so to speak, and will ask if you want to apply those minutes to
6641 the next task you clock in on.
6643 There is one other instance when this clock resolution magic occurs. Say you
6644 were clocked in and hacking away, and suddenly your cat chased a mouse who
6645 scared a hamster that crashed into your UPS's power button! You suddenly
6646 lose all your buffers, but thanks to auto-save you still have your recent Org
6647 mode changes, including your last clock in.
6649 If you restart Emacs and clock into any task, Org will notice that you have a
6650 dangling clock which was never clocked out from your last session. Using
6651 that clock's starting time as the beginning of the unaccounted-for period,
6652 Org will ask how you want to resolve that time. The logic and behavior is
6653 identical to dealing with away time due to idleness; it is just happening due
6654 to a recovery event rather than a set amount of idle time.
6656 You can also check all the files visited by your Org agenda for dangling
6657 clocks at any time using @kbd{M-x org-resolve-clocks RET} (or @kbd{C-c C-x C-z}).
6659 @subsubheading Continuous clocking
6660 @cindex continuous clocking
6661 @vindex org-clock-continuously
6663 You may want to start clocking from the time when you clocked out the
6664 previous task. To enable this systematically, set @code{org-clock-continuously}
6665 to @code{t}. Each time you clock in, Org retrieves the clock-out time of the
6666 last clocked entry for this session, and start the new clock from there.
6668 If you only want this from time to time, use three universal prefix arguments
6669 with @code{org-clock-in} and two @kbd{C-u C-u} with @code{org-clock-in-last}.
6671 @node Effort estimates
6672 @section Effort estimates
6673 @cindex effort estimates
6675 @cindex property, Effort
6676 @vindex org-effort-property
6677 If you want to plan your work in a very detailed way, or if you need to
6678 produce offers with quotations of the estimated work effort, you may want to
6679 assign effort estimates to entries. If you are also clocking your work, you
6680 may later want to compare the planned effort with the actual working time, a
6681 great way to improve planning estimates. Effort estimates are stored in a
6682 special property @samp{Effort}@footnote{You may change the property being
6683 used with the variable @code{org-effort-property}.}. You can set the effort
6684 for an entry with the following commands:
6687 @orgcmd{C-c C-x e,org-set-effort}
6688 Set the effort estimate for the current entry. With a numeric prefix
6689 argument, set it to the Nth allowed value (see below). This command is also
6690 accessible from the agenda with the @kbd{e} key.
6691 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6692 Modify the effort estimate of the item currently being clocked.
6695 Clearly the best way to work with effort estimates is through column view
6696 (@pxref{Column view}). You should start by setting up discrete values for
6697 effort estimates, and a @code{COLUMNS} format that displays these values
6698 together with clock sums (if you want to clock your time). For a specific
6702 #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
6703 #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM
6707 @vindex org-global-properties
6708 @vindex org-columns-default-format
6709 or, even better, you can set up these values globally by customizing the
6710 variables @code{org-global-properties} and @code{org-columns-default-format}.
6711 In particular if you want to use this setup also in the agenda, a global
6712 setup may be advised.
6714 The way to assign estimates to individual items is then to switch to column
6715 mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the
6716 value. The values you enter will immediately be summed up in the hierarchy.
6717 In the column next to it, any clocked time will be displayed.
6719 @vindex org-agenda-columns-add-appointments-to-effort-sum
6720 If you switch to column view in the daily/weekly agenda, the effort column
6721 will summarize the estimated work effort for each day@footnote{Please note
6722 the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda
6723 column view}).}, and you can use this to find space in your schedule. To get
6724 an overview of the entire part of the day that is committed, you can set the
6725 option @code{org-agenda-columns-add-appointments-to-effort-sum}. The
6726 appointments on a day that take place over a specified time interval will
6727 then also be added to the load estimate of the day.
6729 Effort estimates can be used in secondary agenda filtering that is triggered
6730 with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have
6731 these estimates defined consistently, two or three key presses will narrow
6732 down the list to stuff that fits into an available time slot.
6734 @node Relative timer
6735 @section Taking notes with a relative timer
6736 @cindex relative timer
6738 When taking notes during, for example, a meeting or a video viewing, it can
6739 be useful to have access to times relative to a starting time. Org provides
6740 such a relative timer and make it easy to create timed notes.
6743 @orgcmd{C-c C-x .,org-timer}
6744 Insert a relative time into the buffer. The first time you use this, the
6745 timer will be started. When called with a prefix argument, the timer is
6747 @orgcmd{C-c C-x -,org-timer-item}
6748 Insert a description list item with the current relative time. With a prefix
6749 argument, first reset the timer to 0.
6750 @orgcmd{M-@key{RET},org-insert-heading}
6751 Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert
6753 @c for key sequences with a comma, command name macros fail :(
6756 Pause the timer, or continue it if it is already paused
6757 (@command{org-timer-pause-or-continue}).
6758 @c removed the sentence because it is redundant to the following item
6759 @kindex C-u C-c C-x ,
6761 Stop the timer. After this, you can only start a new timer, not continue the
6762 old one. This command also removes the timer from the mode line.
6763 @orgcmd{C-c C-x 0,org-timer-start}
6764 Reset the timer without inserting anything into the buffer. By default, the
6765 timer is reset to 0. When called with a @kbd{C-u} prefix, reset the timer to
6766 specific starting offset. The user is prompted for the offset, with a
6767 default taken from a timer string at point, if any, So this can be used to
6768 restart taking notes after a break in the process. When called with a double
6769 prefix argument @kbd{C-u C-u}, change all timer strings in the active region
6770 by a certain amount. This can be used to fix timer strings if the timer was
6771 not started at exactly the right moment.
6774 @node Countdown timer
6775 @section Countdown timer
6776 @cindex Countdown timer
6780 Calling @code{org-timer-set-timer} from an Org mode buffer runs a countdown
6781 timer. Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everywhere else.
6783 @code{org-timer-set-timer} prompts the user for a duration and displays a
6784 countdown timer in the modeline. @code{org-timer-default-timer} sets the
6785 default countdown value. Giving a prefix numeric argument overrides this
6788 @node Capture - Refile - Archive
6789 @chapter Capture - Refile - Archive
6792 An important part of any organization system is the ability to quickly
6793 capture new ideas and tasks, and to associate reference material with them.
6794 Org does this using a process called @i{capture}. It also can store files
6795 related to a task (@i{attachments}) in a special directory. Once in the
6796 system, tasks and projects need to be moved around. Moving completed project
6797 trees to an archive file keeps the system compact and fast.
6800 * Capture:: Capturing new stuff
6801 * Attachments:: Add files to tasks
6802 * RSS feeds:: Getting input from RSS feeds
6803 * Protocols:: External (e.g., Browser) access to Emacs and Org
6804 * Refile and copy:: Moving/copying a tree from one place to another
6805 * Archiving:: What to do with finished projects
6812 Capture lets you quickly store notes with little interruption of your work
6813 flow. Org's method for capturing new items is heavily inspired by John
6814 Wiegley excellent @file{remember.el} package. Up to version 6.36, Org
6815 used a special setup for @file{remember.el}, then replaced it with
6816 @file{org-remember.el}. As of version 8.0, @file{org-remember.el} has
6817 been completely replaced by @file{org-capture.el}.
6819 If your configuration depends on @file{org-remember.el}, you need to update
6820 it and use the setup described below. To convert your
6821 @code{org-remember-templates}, run the command
6823 @kbd{M-x org-capture-import-remember-templates RET}
6825 @noindent and then customize the new variable with @kbd{M-x
6826 customize-variable org-capture-templates}, check the result, and save the
6830 * Setting up capture:: Where notes will be stored
6831 * Using capture:: Commands to invoke and terminate capture
6832 * Capture templates:: Define the outline of different note types
6835 @node Setting up capture
6836 @subsection Setting up capture
6838 The following customization sets a default target file for notes, and defines
6839 a global key@footnote{Please select your own key, @kbd{C-c c} is only a
6840 suggestion.} for capturing new material.
6842 @vindex org-default-notes-file
6845 (setq org-default-notes-file (concat org-directory "/notes.org"))
6846 (define-key global-map "\C-cc" 'org-capture)
6851 @subsection Using capture
6854 @orgcmd{C-c c,org-capture}
6855 Call the command @code{org-capture}. Note that this keybinding is global and
6856 not active by default: you need to install it. If you have templates
6858 defined @pxref{Capture templates}, it will offer these templates for
6859 selection or use a new Org outline node as the default template. It will
6860 insert the template into the target file and switch to an indirect buffer
6861 narrowed to this new node. You may then insert the information you want.
6863 @orgcmd{C-c C-c,org-capture-finalize}
6864 Once you have finished entering information into the capture buffer, @kbd{C-c
6865 C-c} will return you to the window configuration before the capture process,
6866 so that you can resume your work without further distraction. When called
6867 with a prefix arg, finalize and then jump to the captured item.
6869 @orgcmd{C-c C-w,org-capture-refile}
6870 Finalize the capture process by refiling (@pxref{Refile and copy}) the note to
6871 a different place. Please realize that this is a normal refiling command
6872 that will be executed---so the cursor position at the moment you run this
6873 command is important. If you have inserted a tree with a parent and
6874 children, first move the cursor back to the parent. Any prefix argument
6875 given to this command will be passed on to the @code{org-refile} command.
6877 @orgcmd{C-c C-k,org-capture-kill}
6878 Abort the capture process and return to the previous state.
6882 You can also call @code{org-capture} in a special way from the agenda, using
6883 the @kbd{k c} key combination. With this access, any timestamps inserted by
6884 the selected capture template will default to the cursor date in the agenda,
6885 rather than to the current date.
6887 To find the locations of the last stored capture, use @code{org-capture} with
6892 Visit the target location of a capture template. You get to select the
6893 template in the usual way.
6894 @orgkey{C-u C-u C-c c}
6895 Visit the last stored capture item in its buffer.
6898 @vindex org-capture-bookmark
6899 @cindex org-capture-last-stored
6900 You can also jump to the bookmark @code{org-capture-last-stored}, which will
6901 automatically be created unless you set @code{org-capture-bookmark} to
6904 To insert the capture at point in an Org buffer, call @code{org-capture} with
6905 a @code{C-0} prefix argument.
6907 @node Capture templates
6908 @subsection Capture templates
6909 @cindex templates, for Capture
6911 You can use templates for different types of capture items, and
6912 for different target locations. The easiest way to create such templates is
6913 through the customize interface.
6917 Customize the variable @code{org-capture-templates}.
6920 Before we give the formal description of template definitions, let's look at
6921 an example. Say you would like to use one template to create general TODO
6922 entries, and you want to put these entries under the heading @samp{Tasks} in
6923 your file @file{~/org/gtd.org}. Also, a date tree in the file
6924 @file{journal.org} should capture journal entries. A possible configuration
6929 (setq org-capture-templates
6930 '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
6931 "* TODO %?\n %i\n %a")
6932 ("j" "Journal" entry (file+datetree "~/org/journal.org")
6933 "* %?\nEntered on %U\n %i\n %a")))
6937 @noindent If you then press @kbd{C-c c t}, Org will prepare the template
6941 [[file:@var{link to where you initiated capture}]]
6945 During expansion of the template, @code{%a} has been replaced by a link to
6946 the location from where you called the capture command. This can be
6947 extremely useful for deriving tasks from emails, for example. You fill in
6948 the task definition, press @kbd{C-c C-c} and Org returns you to the same
6949 place where you started the capture process.
6951 To define special keys to capture to a particular template without going
6952 through the interactive template selection, you can create your key binding
6956 (define-key global-map "\C-cx"
6957 (lambda () (interactive) (org-capture nil "x")))
6961 * Template elements:: What is needed for a complete template entry
6962 * Template expansion:: Filling in information about time and context
6963 * Templates in contexts:: Only show a template in a specific context
6966 @node Template elements
6967 @subsubsection Template elements
6969 Now lets look at the elements of a template definition. Each entry in
6970 @code{org-capture-templates} is a list with the following items:
6974 The keys that will select the template, as a string, characters
6975 only, for example @code{"a"} for a template to be selected with a
6976 single key, or @code{"bt"} for selection with two keys. When using
6977 several keys, keys using the same prefix key must be sequential
6978 in the list and preceded by a 2-element entry explaining the
6979 prefix key, for example
6981 ("b" "Templates for marking stuff to buy")
6983 @noindent If you do not define a template for the @kbd{C} key, this key will
6984 be used to open the customize buffer for this complex variable.
6987 A short string describing the template, which will be shown during
6991 The type of entry, a symbol. Valid values are:
6995 An Org mode node, with a headline. Will be filed as the child of the target
6996 entry or as a top-level entry. The target file should be an Org mode file.
6998 A plain list item, placed in the first plain list at the target
6999 location. Again the target file should be an Org file.
7001 A checkbox item. This only differs from the plain list item by the
7004 a new line in the first table at the target location. Where exactly the
7005 line will be inserted depends on the properties @code{:prepend} and
7006 @code{:table-line-pos} (see below).
7008 Text to be inserted as it is.
7012 @vindex org-default-notes-file
7013 Specification of where the captured item should be placed. In Org mode
7014 files, targets usually define a node. Entries will become children of this
7015 node. Other types will be added to the table or list in the body of this
7016 node. Most target specifications contain a file name. If that file name is
7017 the empty string, it defaults to @code{org-default-notes-file}. A file can
7018 also be given as a variable, function, or Emacs Lisp form.
7023 @item (file "path/to/file")
7024 Text will be placed at the beginning or end of that file.
7026 @item (id "id of existing org entry")
7027 Filing as child of this entry, or in the body of the entry.
7029 @item (file+headline "path/to/file" "node headline")
7030 Fast configuration if the target heading is unique in the file.
7032 @item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
7033 For non-unique headings, the full path is safer.
7035 @item (file+regexp "path/to/file" "regexp to find location")
7036 Use a regular expression to position the cursor.
7038 @item (file+datetree "path/to/file")
7039 Will create a heading in a date tree for today's date@footnote{Datetree
7040 headlines for years accept tags, so if you use both @code{* 2013 :noexport:}
7041 and @code{* 2013} in your file, the capture will refile the note to the first
7044 @item (file+datetree+prompt "path/to/file")
7045 Will create a heading in a date tree, but will prompt for the date.
7047 @item (file+function "path/to/file" function-finding-location)
7048 A function to find the right location in the file.
7051 File to the entry that is currently being clocked.
7053 @item (function function-finding-location)
7054 Most general way, write your own function to find both
7059 The template for creating the capture item. If you leave this empty, an
7060 appropriate default template will be used. Otherwise this is a string with
7061 escape codes, which will be replaced depending on time and context of the
7062 capture call. The string with escapes may be loaded from a template file,
7063 using the special syntax @code{(file "path/to/template")}. See below for
7067 The rest of the entry is a property list of additional options.
7068 Recognized properties are:
7072 Normally new captured information will be appended at
7073 the target location (last child, last table line, last list item...).
7074 Setting this property will change that.
7076 @item :immediate-finish
7077 When set, do not offer to edit the information, just
7078 file it away immediately. This makes sense if the template only needs
7079 information that can be added automatically.
7082 Set this to the number of lines to insert
7083 before and after the new item. Default 0, only common other value is 1.
7086 Start the clock in this item.
7089 Keep the clock running when filing the captured entry.
7092 If starting the capture interrupted a clock, restart that clock when finished
7093 with the capture. Note that @code{:clock-keep} has precedence over
7094 @code{:clock-resume}. When setting both to @code{t}, the current clock will
7095 run and the previous one will not be resumed.
7098 Do not narrow the target buffer, simply show the full buffer. Default is to
7099 narrow it so that you only see the new material.
7101 @item :table-line-pos
7102 Specification of the location in the table where the new line should be
7103 inserted. It should be a string like @code{"II-3"} meaning that the new
7104 line should become the third line before the second horizontal separator
7108 If the target file was not yet visited when capture was invoked, kill the
7109 buffer again after capture is completed.
7113 @node Template expansion
7114 @subsubsection Template expansion
7116 In the template itself, special @kbd{%}-escapes@footnote{If you need one of
7117 these sequences literally, escape the @kbd{%} with a backslash.} allow
7118 dynamic insertion of content. The templates are expanded in the order given here:
7121 %[@var{file}] @r{Insert the contents of the file given by @var{file}.}
7122 %(@var{sexp}) @r{Evaluate Elisp @var{sexp} and replace with the result.}
7123 @r{For convenience, %:keyword (see below) placeholders}
7124 @r{within the expression will be expanded prior to this.}
7125 @r{The sexp must return a string.}
7126 %<...> @r{The result of format-time-string on the ... format specification.}
7127 %t @r{Timestamp, date only.}
7128 %T @r{Timestamp, with date and time.}
7129 %u, %U @r{Like the above, but inactive timestamps.}
7130 %i @r{Initial content, the region when capture is called while the}
7131 @r{region is active.}
7132 @r{The entire text will be indented like @code{%i} itself.}
7133 %a @r{Annotation, normally the link created with @code{org-store-link}.}
7134 %A @r{Like @code{%a}, but prompt for the description part.}
7135 %l @r{Like %a, but only insert the literal link.}
7136 %c @r{Current kill ring head.}
7137 %x @r{Content of the X clipboard.}
7138 %k @r{Title of the currently clocked task.}
7139 %K @r{Link to the currently clocked task.}
7140 %n @r{User name (taken from @code{user-full-name}).}
7141 %f @r{File visited by current buffer when org-capture was called.}
7142 %F @r{Full path of the file or directory visited by current buffer.}
7143 %:keyword @r{Specific information for certain link types, see below.}
7144 %^g @r{Prompt for tags, with completion on tags in target file.}
7145 %^G @r{Prompt for tags, with completion all tags in all agenda files.}
7146 %^t @r{Like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}.}
7147 @r{You may define a prompt like @code{%^@{Birthday@}t}.}
7148 %^C @r{Interactive selection of which kill or clip to use.}
7149 %^L @r{Like @code{%^C}, but insert as link.}
7150 %^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}.}
7151 %^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.}
7152 @r{You may specify a default value and a completion table with}
7153 @r{%^@{prompt|default|completion2|completion3...@}.}
7154 @r{The arrow keys access a prompt-specific history.}
7155 %\n @r{Insert the text entered at the nth %^@{@var{prompt}@}, where @code{n} is}
7156 @r{a number, starting from 1.}
7157 %? @r{After completing the template, position cursor here.}
7161 For specific link types, the following keywords will be
7162 defined@footnote{If you define your own link types (@pxref{Adding
7163 hyperlink types}), any property you store with
7164 @code{org-store-link-props} can be accessed in capture templates in a
7167 @vindex org-from-is-user-regexp
7169 Link type | Available keywords
7170 ---------------------------------+----------------------------------------------
7171 bbdb | %:name %:company
7172 irc | %:server %:port %:nick
7173 vm, vm-imap, wl, mh, mew, rmail | %:type %:subject %:message-id
7174 | %:from %:fromname %:fromaddress
7175 | %:to %:toname %:toaddress
7176 | %:date @r{(message date header field)}
7177 | %:date-timestamp @r{(date as active timestamp)}
7178 | %:date-timestamp-inactive @r{(date as inactive timestamp)}
7179 | %: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}.}}
7180 gnus | %:group, @r{for messages also all email fields}
7182 info | %:file %:node
7187 To place the cursor after template expansion use:
7190 %? @r{After completing the template, position cursor here.}
7193 @node Templates in contexts
7194 @subsubsection Templates in contexts
7196 @vindex org-capture-templates-contexts
7197 To control whether a capture template should be accessible from a specific
7198 context, you can customize @code{org-capture-templates-contexts}. Let's say
7199 for example that you have a capture template @code{"p"} for storing Gnus
7200 emails containing patches. Then you would configure this option like this:
7203 (setq org-capture-templates-contexts
7204 '(("p" (in-mode . "message-mode"))))
7207 You can also tell that the command key @code{"p"} should refer to another
7208 template. In that case, add this command key like this:
7211 (setq org-capture-templates-contexts
7212 '(("p" "q" (in-mode . "message-mode"))))
7215 See the docstring of the variable for more information.
7218 @section Attachments
7221 @vindex org-attach-directory
7222 It is often useful to associate reference material with an outline node/task.
7223 Small chunks of plain text can simply be stored in the subtree of a project.
7224 Hyperlinks (@pxref{Hyperlinks}) can establish associations with
7225 files that live elsewhere on your computer or in the cloud, like emails or
7226 source code files belonging to a project. Another method is @i{attachments},
7227 which are files located in a directory belonging to an outline node. Org
7228 uses directories named by the unique ID of each entry. These directories are
7229 located in the @file{data} directory which lives in the same directory where
7230 your Org file lives@footnote{If you move entries or Org files from one
7231 directory to another, you may want to configure @code{org-attach-directory}
7232 to contain an absolute path.}. If you initialize this directory with
7233 @code{git init}, Org will automatically commit changes when it sees them.
7234 The attachment system has been contributed to Org by John Wiegley.
7236 In cases where it seems better to do so, you can also attach a directory of your
7237 choice to an entry. You can also make children inherit the attachment
7238 directory from a parent, so that an entire subtree uses the same attached
7241 @noindent The following commands deal with attachments:
7244 @orgcmd{C-c C-a,org-attach}
7245 The dispatcher for commands related to the attachment system. After these
7246 keys, a list of commands is displayed and you must press an additional key
7247 to select a command:
7250 @orgcmdtkc{a,C-c C-a a,org-attach-attach}
7251 @vindex org-attach-method
7252 Select a file and move it into the task's attachment directory. The file
7253 will be copied, moved, or linked, depending on @code{org-attach-method}.
7254 Note that hard links are not supported on all systems.
7260 Attach a file using the copy/move/link method.
7261 Note that hard links are not supported on all systems.
7263 @orgcmdtkc{n,C-c C-a n,org-attach-new}
7264 Create a new attachment as an Emacs buffer.
7266 @orgcmdtkc{z,C-c C-a z,org-attach-sync}
7267 Synchronize the current task with its attachment directory, in case you added
7268 attachments yourself.
7270 @orgcmdtkc{o,C-c C-a o,org-attach-open}
7271 @vindex org-file-apps
7272 Open current task's attachment. If there is more than one, prompt for a
7273 file name first. Opening will follow the rules set by @code{org-file-apps}.
7274 For more details, see the information on following hyperlinks
7275 (@pxref{Handling links}).
7277 @orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs}
7278 Also open the attachment, but force opening the file in Emacs.
7280 @orgcmdtkc{f,C-c C-a f,org-attach-reveal}
7281 Open the current task's attachment directory.
7283 @orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs}
7284 Also open the directory, but force using @command{dired} in Emacs.
7286 @orgcmdtkc{d,C-c C-a d,org-attach-delete-one}
7287 Select and delete a single attachment.
7289 @orgcmdtkc{D,C-c C-a D,org-attach-delete-all}
7290 Delete all of a task's attachments. A safer way is to open the directory in
7291 @command{dired} and delete from there.
7293 @orgcmdtkc{s,C-c C-a s,org-attach-set-directory}
7294 @cindex property, ATTACH_DIR
7295 Set a specific directory as the entry's attachment directory. This works by
7296 putting the directory path into the @code{ATTACH_DIR} property.
7298 @orgcmdtkc{i,C-c C-a i,org-attach-set-inherit}
7299 @cindex property, ATTACH_DIR_INHERIT
7300 Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the
7301 same directory for attachments as the parent does.
7310 Org can add and change entries based on information found in RSS feeds and
7311 Atom feeds. You could use this to make a task out of each new podcast in a
7312 podcast feed. Or you could use a phone-based note-creating service on the
7313 web to import tasks into Org. To access feeds, configure the variable
7314 @code{org-feed-alist}. The docstring of this variable has detailed
7315 information. Here is just an example:
7319 (setq org-feed-alist
7321 "http://rss.slashdot.org/Slashdot/slashdot"
7322 "~/txt/org/feeds.org" "Slashdot Entries")))
7327 will configure that new items from the feed provided by
7328 @code{rss.slashdot.org} will result in new entries in the file
7329 @file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
7330 the following command is used:
7333 @orgcmd{C-c C-x g,org-feed-update-all}
7335 Collect items from the feeds configured in @code{org-feed-alist} and act upon
7337 @orgcmd{C-c C-x G,org-feed-goto-inbox}
7338 Prompt for a feed name and go to the inbox configured for this feed.
7341 Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which
7342 it will store information about the status of items in the feed, to avoid
7343 adding the same item several times.
7345 For more information, including how to read atom feeds, see
7346 @file{org-feed.el} and the docstring of @code{org-feed-alist}.
7349 @section Protocols for external access
7350 @cindex protocols, for external access
7353 You can set up Org for handling protocol calls from outside applications that
7354 are passed to Emacs through the @file{emacsserver}. For example, you can
7355 configure bookmarks in your web browser to send a link to the current page to
7356 Org and create a note from it using capture (@pxref{Capture}). Or you
7357 could create a bookmark that will tell Emacs to open the local source file of
7358 a remote website you are looking at with the browser. See
7359 @uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed
7360 documentation and setup instructions.
7362 @node Refile and copy
7363 @section Refile and copy
7364 @cindex refiling notes
7365 @cindex copying notes
7367 When reviewing the captured data, you may want to refile or to copy some of
7368 the entries into a different list, for example into a project. Cutting,
7369 finding the right location, and then pasting the note is cumbersome. To
7370 simplify this process, you can use the following special command:
7373 @orgcmd{C-c M-w,org-copy}
7375 Copying works like refiling, except that the original note is not deleted.
7376 @orgcmd{C-c C-w,org-refile}
7378 @vindex org-reverse-note-order
7379 @vindex org-refile-targets
7380 @vindex org-refile-use-outline-path
7381 @vindex org-outline-path-complete-in-steps
7382 @vindex org-refile-allow-creating-parent-nodes
7383 @vindex org-log-refile
7384 @vindex org-refile-use-cache
7385 @vindex org-refile-keep
7386 Refile the entry or region at point. This command offers possible locations
7387 for refiling the entry and lets you select one with completion. The item (or
7388 all items in the region) is filed below the target heading as a subitem.
7389 Depending on @code{org-reverse-note-order}, it will be either the first or
7391 By default, all level 1 headlines in the current buffer are considered to be
7392 targets, but you can have more complex definitions across a number of files.
7393 See the variable @code{org-refile-targets} for details. If you would like to
7394 select a location via a file-path-like completion along the outline path, see
7395 the variables @code{org-refile-use-outline-path} and
7396 @code{org-outline-path-complete-in-steps}. If you would like to be able to
7397 create new nodes as new parents for refiling on the fly, check the
7398 variable @code{org-refile-allow-creating-parent-nodes}.
7399 When the variable @code{org-log-refile}@footnote{with corresponding
7400 @code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},
7401 and @code{nologrefile}} is set, a timestamp or a note will be
7402 recorded when an entry has been refiled.
7403 @orgkey{C-u C-c C-w}
7404 Use the refile interface to jump to a heading.
7405 @orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored}
7406 Jump to the location where @code{org-refile} last moved a tree to.
7408 Refile as the child of the item currently being clocked.
7410 Refile and keep the entry in place. Also see @code{org-refile-keep} to make
7411 this the default behavior, and beware that this may result in duplicated
7412 @code{ID} properties.
7413 @orgcmdtkc{C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w,C-0 C-c C-w,org-refile-cache-clear}
7414 Clear the target cache. Caching of refile targets can be turned on by
7415 setting @code{org-refile-use-cache}. To make the command see new possible
7416 targets, you have to clear the cache with this command.
7423 When a project represented by a (sub)tree is finished, you may want
7424 to move the tree out of the way and to stop it from contributing to the
7425 agenda. Archiving is important to keep your working files compact and global
7426 searches like the construction of agenda views fast.
7429 @orgcmd{C-c C-x C-a,org-archive-subtree-default}
7430 @vindex org-archive-default-command
7431 Archive the current entry using the command specified in the variable
7432 @code{org-archive-default-command}.
7436 * Moving subtrees:: Moving a tree to an archive file
7437 * Internal archiving:: Switch off a tree but keep it in the file
7440 @node Moving subtrees
7441 @subsection Moving a tree to the archive file
7442 @cindex external archiving
7444 The most common archiving action is to move a project tree to another file,
7448 @orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
7449 @vindex org-archive-location
7450 Archive the subtree starting at the cursor position to the location
7451 given by @code{org-archive-location}.
7452 @orgkey{C-u C-c C-x C-s}
7453 Check if any direct children of the current headline could be moved to
7454 the archive. To do this, each subtree is checked for open TODO entries.
7455 If none are found, the command offers to move it to the archive
7456 location. If the cursor is @emph{not} on a headline when this command
7457 is invoked, the level 1 trees will be checked.
7460 @cindex archive locations
7461 The default archive location is a file in the same directory as the
7462 current file, with the name derived by appending @file{_archive} to the
7463 current file name. You can also choose what heading to file archived
7464 items under, with the possibility to add them to a datetree in a file.
7465 For information and examples on how to specify the file and the heading,
7466 see the documentation string of the variable
7467 @code{org-archive-location}.
7469 There is also an in-buffer option for setting this variable, for
7470 example@footnote{For backward compatibility, the following also works:
7471 If there are several such lines in a file, each specifies the archive
7472 location for the text below it. The first such line also applies to any
7473 text before its definition. However, using this method is
7474 @emph{strongly} deprecated as it is incompatible with the outline
7475 structure of the document. The correct method for setting multiple
7476 archive locations in a buffer is using properties.}:
7480 #+ARCHIVE: %s_done::
7483 @cindex property, ARCHIVE
7485 If you would like to have a special ARCHIVE location for a single entry
7486 or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
7487 location as the value (@pxref{Properties and columns}).
7489 @vindex org-archive-save-context-info
7490 When a subtree is moved, it receives a number of special properties that
7491 record context information like the file from where the entry came, its
7492 outline path the archiving time etc. Configure the variable
7493 @code{org-archive-save-context-info} to adjust the amount of information
7497 @node Internal archiving
7498 @subsection Internal archiving
7500 If you want to just switch off (for agenda views) certain subtrees without
7501 moving them to a different file, you can use the @code{ARCHIVE tag}.
7503 A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
7504 its location in the outline tree, but behaves in the following way:
7507 @vindex org-cycle-open-archived-trees
7508 It does not open when you attempt to do so with a visibility cycling
7509 command (@pxref{Visibility cycling}). You can force cycling archived
7510 subtrees with @kbd{C-@key{TAB}}, or by setting the option
7511 @code{org-cycle-open-archived-trees}. Also normal outline commands like
7512 @code{show-all} will open archived subtrees.
7514 @vindex org-sparse-tree-open-archived-trees
7515 During sparse tree construction (@pxref{Sparse trees}), matches in
7516 archived subtrees are not exposed, unless you configure the option
7517 @code{org-sparse-tree-open-archived-trees}.
7519 @vindex org-agenda-skip-archived-trees
7520 During agenda view construction (@pxref{Agenda views}), the content of
7521 archived trees is ignored unless you configure the option
7522 @code{org-agenda-skip-archived-trees}, in which case these trees will always
7523 be included. In the agenda you can press @kbd{v a} to get archives
7524 temporarily included.
7526 @vindex org-export-with-archived-trees
7527 Archived trees are not exported (@pxref{Exporting}), only the headline
7528 is. Configure the details using the variable
7529 @code{org-export-with-archived-trees}.
7531 @vindex org-columns-skip-archived-trees
7532 Archived trees are excluded from column view unless the variable
7533 @code{org-columns-skip-archived-trees} is configured to @code{nil}.
7536 The following commands help manage the ARCHIVE tag:
7539 @orgcmd{C-c C-x a,org-toggle-archive-tag}
7540 Toggle the ARCHIVE tag for the current headline. When the tag is set,
7541 the headline changes to a shadowed face, and the subtree below it is
7543 @orgkey{C-u C-c C-x a}
7544 Check if any direct children of the current headline should be archived.
7545 To do this, each subtree is checked for open TODO entries. If none are
7546 found, the command offers to set the ARCHIVE tag for the child. If the
7547 cursor is @emph{not} on a headline when this command is invoked, the
7548 level 1 trees will be checked.
7549 @orgcmd{C-@kbd{TAB},org-force-cycle-archived}
7550 Cycle a tree even if it is tagged with ARCHIVE.
7551 @orgcmd{C-c C-x A,org-archive-to-archive-sibling}
7552 Move the current entry to the @emph{Archive Sibling}. This is a sibling of
7553 the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The
7554 entry becomes a child of that sibling and in this way retains a lot of its
7555 original context, including inherited tags and approximate position in the
7561 @chapter Agenda views
7562 @cindex agenda views
7564 Due to the way Org works, TODO items, time-stamped items, and
7565 tagged headlines can be scattered throughout a file or even a number of
7566 files. To get an overview of open action items, or of events that are
7567 important for a particular date, this information must be collected,
7568 sorted and displayed in an organized way.
7570 Org can select items based on various criteria and display them
7571 in a separate buffer. Seven different view types are provided:
7575 an @emph{agenda} that is like a calendar and shows information
7578 a @emph{TODO list} that covers all unfinished
7581 a @emph{match view}, showings headlines based on the tags, properties, and
7582 TODO state associated with them,
7584 a @emph{timeline view} that shows all events in a single Org file,
7585 in time-sorted view,
7587 a @emph{text search view} that shows all entries from multiple files
7588 that contain specified keywords,
7590 a @emph{stuck projects view} showing projects that currently don't move
7593 @emph{custom views} that are special searches and combinations of different
7598 The extracted information is displayed in a special @emph{agenda
7599 buffer}. This buffer is read-only, but provides commands to visit the
7600 corresponding locations in the original Org files, and even to
7601 edit these files remotely.
7603 @vindex org-agenda-window-setup
7604 @vindex org-agenda-restore-windows-after-quit
7605 Two variables control how the agenda buffer is displayed and whether the
7606 window configuration is restored when the agenda exits:
7607 @code{org-agenda-window-setup} and
7608 @code{org-agenda-restore-windows-after-quit}.
7611 * Agenda files:: Files being searched for agenda information
7612 * Agenda dispatcher:: Keyboard access to agenda views
7613 * Built-in agenda views:: What is available out of the box?
7614 * Presentation and sorting:: How agenda items are prepared for display
7615 * Agenda commands:: Remote editing of Org trees
7616 * Custom agenda views:: Defining special searches and views
7617 * Exporting agenda views:: Writing a view to a file
7618 * Agenda column view:: Using column view for collected entries
7622 @section Agenda files
7623 @cindex agenda files
7624 @cindex files for agenda
7626 @vindex org-agenda-files
7627 The information to be shown is normally collected from all @emph{agenda
7628 files}, the files listed in the variable
7629 @code{org-agenda-files}@footnote{If the value of that variable is not a
7630 list, but a single file name, then the list of agenda files will be
7631 maintained in that external file.}. If a directory is part of this list,
7632 all files with the extension @file{.org} in this directory will be part
7635 Thus, even if you only work with a single Org file, that file should
7636 be put into the list@footnote{When using the dispatcher, pressing
7637 @kbd{<} before selecting a command will actually limit the command to
7638 the current file, and ignore @code{org-agenda-files} until the next
7639 dispatcher command.}. You can customize @code{org-agenda-files}, but
7640 the easiest way to maintain it is through the following commands
7642 @cindex files, adding to agenda list
7644 @orgcmd{C-c [,org-agenda-file-to-front}
7645 Add current file to the list of agenda files. The file is added to
7646 the front of the list. If it was already in the list, it is moved to
7647 the front. With a prefix argument, file is added/moved to the end.
7648 @orgcmd{C-c ],org-remove-file}
7649 Remove current file from the list of agenda files.
7651 @cindex cycling, of agenda files
7652 @orgcmd{C-',org-cycle-agenda-files}
7654 Cycle through agenda file list, visiting one file after the other.
7655 @kindex M-x org-iswitchb
7656 @item M-x org-iswitchb RET
7657 Command to use an @code{iswitchb}-like interface to switch to and between Org
7662 The Org menu contains the current list of files and can be used
7663 to visit any of them.
7665 If you would like to focus the agenda temporarily on a file not in
7666 this list, or on just one file in the list, or even on only a subtree in a
7667 file, then this can be done in different ways. For a single agenda command,
7668 you may press @kbd{<} once or several times in the dispatcher
7669 (@pxref{Agenda dispatcher}). To restrict the agenda scope for an
7670 extended period, use the following commands:
7673 @orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
7674 Permanently restrict the agenda to the current subtree. When with a
7675 prefix argument, or with the cursor before the first headline in a file,
7676 the agenda scope is set to the entire file. This restriction remains in
7677 effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
7678 or @kbd{>} in the agenda dispatcher. If there is a window displaying an
7679 agenda view, the new restriction takes effect immediately.
7680 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
7681 Remove the permanent restriction created by @kbd{C-c C-x <}.
7685 When working with @file{speedbar.el}, you can use the following commands in
7689 @orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
7690 Permanently restrict the agenda to the item---either an Org file or a subtree
7691 in such a file---at the cursor in the Speedbar frame.
7692 If there is a window displaying an agenda view, the new restriction takes
7694 @orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
7695 Lift the restriction.
7698 @node Agenda dispatcher
7699 @section The agenda dispatcher
7700 @cindex agenda dispatcher
7701 @cindex dispatching agenda commands
7702 The views are created through a dispatcher, which should be bound to a
7703 global key---for example @kbd{C-c a} (@pxref{Activation}). In the
7704 following we will assume that @kbd{C-c a} is indeed how the dispatcher
7705 is accessed and list keyboard access to commands accordingly. After
7706 pressing @kbd{C-c a}, an additional letter is required to execute a
7707 command. The dispatcher offers the following default commands:
7711 Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
7713 Create a list of all TODO items (@pxref{Global TODO list}).
7715 Create a list of headlines matching a TAGS expression (@pxref{Matching
7716 tags and properties}).
7718 Create the timeline view for the current buffer (@pxref{Timeline}).
7720 Create a list of entries selected by a boolean expression of keywords
7721 and/or regular expressions that must or must not occur in the entry.
7723 @vindex org-agenda-text-search-extra-files
7724 Search for a regular expression in all agenda files and additionally in
7725 the files listed in @code{org-agenda-text-search-extra-files}. This
7726 uses the Emacs command @code{multi-occur}. A prefix argument can be
7727 used to specify the number of context lines for each match, default is
7730 Create a list of stuck projects (@pxref{Stuck projects}).
7732 Restrict an agenda command to the current buffer@footnote{For backward
7733 compatibility, you can also press @kbd{1} to restrict to the current
7734 buffer.}. After pressing @kbd{<}, you still need to press the character
7735 selecting the command.
7737 If there is an active region, restrict the following agenda command to
7738 the region. Otherwise, restrict it to the current subtree@footnote{For
7739 backward compatibility, you can also press @kbd{0} to restrict to the
7740 current region/subtree.}. After pressing @kbd{< <}, you still need to press the
7741 character selecting the command.
7744 @vindex org-agenda-sticky
7745 Toggle sticky agenda views. By default, Org maintains only a single agenda
7746 buffer and rebuilds it each time you change the view, to make sure everything
7747 is always up to date. If you switch between views often and the build time
7748 bothers you, you can turn on sticky agenda buffers (make this the default by
7749 customizing the variable @code{org-agenda-sticky}). With sticky agendas, the
7750 dispatcher only switches to the selected view, you need to update it by hand
7751 with @kbd{r} or @kbd{g}. You can toggle sticky agenda view any time with
7752 @code{org-toggle-sticky-agenda}.
7755 You can also define custom commands that will be accessible through the
7756 dispatcher, just like the default commands. This includes the
7757 possibility to create extended agenda buffers that contain several
7758 blocks together, for example the weekly agenda, the global TODO list and
7759 a number of special tags matches. @xref{Custom agenda views}.
7761 @node Built-in agenda views
7762 @section The built-in agenda views
7764 In this section we describe the built-in views.
7767 * Weekly/daily agenda:: The calendar page with current tasks
7768 * Global TODO list:: All unfinished action items
7769 * Matching tags and properties:: Structured information with fine-tuned search
7770 * Timeline:: Time-sorted view for single file
7771 * Search view:: Find entries by searching for text
7772 * Stuck projects:: Find projects you need to review
7775 @node Weekly/daily agenda
7776 @subsection The weekly/daily agenda
7778 @cindex weekly agenda
7779 @cindex daily agenda
7781 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
7782 paper agenda, showing all the tasks for the current week or day.
7785 @cindex org-agenda, command
7786 @orgcmd{C-c a a,org-agenda-list}
7787 Compile an agenda for the current week from a list of Org files. The agenda
7788 shows the entries for each day. With a numeric prefix@footnote{For backward
7789 compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be
7790 listed before the agenda. This feature is deprecated, use the dedicated TODO
7791 list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1
7792 C-c a a}) you may set the number of days to be displayed.
7795 @vindex org-agenda-span
7796 @vindex org-agenda-ndays
7797 @vindex org-agenda-start-day
7798 @vindex org-agenda-start-on-weekday
7799 The default number of days displayed in the agenda is set by the variable
7800 @code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This
7801 variable can be set to any number of days you want to see by default in the
7802 agenda, or to a span name, such as @code{day}, @code{week}, @code{month} or
7803 @code{year}. For weekly agendas, the default is to start on the previous
7804 monday (see @code{org-agenda-start-on-weekday}). You can also set the start
7805 date using a date shift: @code{(setq org-agenda-start-day "+10d")} will
7806 start the agenda ten days from today in the future.
7808 Remote editing from the agenda buffer means, for example, that you can
7809 change the dates of deadlines and appointments from the agenda buffer.
7810 The commands available in the Agenda buffer are listed in @ref{Agenda
7813 @subsubheading Calendar/Diary integration
7814 @cindex calendar integration
7815 @cindex diary integration
7817 Emacs contains the calendar and diary by Edward M. Reingold. The
7818 calendar displays a three-month calendar with holidays from different
7819 countries and cultures. The diary allows you to keep track of
7820 anniversaries, lunar phases, sunrise/set, recurrent appointments
7821 (weekly, monthly) and more. In this way, it is quite complementary to
7822 Org. It can be very useful to combine output from Org with
7825 In order to include entries from the Emacs diary into Org mode's
7826 agenda, you only need to customize the variable
7829 (setq org-agenda-include-diary t)
7832 @noindent After that, everything will happen automatically. All diary
7833 entries including holidays, anniversaries, etc., will be included in the
7834 agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and
7835 @key{RET} can be used from the agenda buffer to jump to the diary
7836 file in order to edit existing diary entries. The @kbd{i} command to
7837 insert new entries for the current date works in the agenda buffer, as
7838 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
7839 Sunrise/Sunset times, show lunar phases and to convert to other
7840 calendars, respectively. @kbd{c} can be used to switch back and forth
7841 between calendar and agenda.
7843 If you are using the diary only for sexp entries and holidays, it is
7844 faster to not use the above setting, but instead to copy or even move
7845 the entries into an Org file. Org mode evaluates diary-style sexp
7846 entries, and does it faster because there is no overhead for first
7847 creating the diary display. Note that the sexp entries must start at
7848 the left margin, no whitespace is allowed before them. For example,
7849 the following segment of an Org file will be processed and entries
7850 will be made in the agenda:
7853 * Birthdays and similar stuff
7855 %%(org-calendar-holiday) ; special function for holiday names
7857 %%(org-anniversary 1956 5 14)@footnote{@code{org-anniversary} is just like @code{diary-anniversary}, but the argument order is always according to ISO and therefore independent of the value of @code{calendar-date-style}.} Arthur Dent is %d years old
7858 %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
7861 @subsubheading Anniversaries from BBDB
7862 @cindex BBDB, anniversaries
7863 @cindex anniversaries, from BBDB
7865 If you are using the Big Brothers Database to store your contacts, you will
7866 very likely prefer to store anniversaries in BBDB rather than in a
7867 separate Org or diary file. Org supports this and will show BBDB
7868 anniversaries as part of the agenda. All you need to do is to add the
7869 following to one of your agenda files:
7876 %%(org-bbdb-anniversaries)
7879 You can then go ahead and define anniversaries for a BBDB record. Basically,
7880 you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
7881 record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
7882 followed by a space and the class of the anniversary (@samp{birthday} or
7883 @samp{wedding}, or a format string). If you omit the class, it will default to
7884 @samp{birthday}. Here are a few examples, the header for the file
7885 @file{org-bbdb.el} contains more detailed information.
7891 2008-04-14 %s released version 6.01 of org mode, %d years ago
7894 After a change to BBDB, or for the first agenda display during an Emacs
7895 session, the agenda display will suffer a short delay as Org updates its
7896 hash with anniversaries. However, from then on things will be very fast---much
7897 faster in fact than a long list of @samp{%%(diary-anniversary)} entries
7898 in an Org or Diary file.
7900 @subsubheading Appointment reminders
7901 @cindex @file{appt.el}
7902 @cindex appointment reminders
7906 Org can interact with Emacs appointments notification facility. To add the
7907 appointments of your agenda files, use the command @code{org-agenda-to-appt}.
7908 This command lets you filter through the list of your appointments and add
7909 only those belonging to a specific category or matching a regular expression.
7910 It also reads a @code{APPT_WARNTIME} property which will then override the
7911 value of @code{appt-message-warning-time} for this appointment. See the
7912 docstring for details.
7914 @node Global TODO list
7915 @subsection The global TODO list
7916 @cindex global TODO list
7917 @cindex TODO list, global
7919 The global TODO list contains all unfinished TODO items formatted and
7920 collected into a single place.
7923 @orgcmd{C-c a t,org-todo-list}
7924 Show the global TODO list. This collects the TODO items from all agenda
7925 files (@pxref{Agenda views}) into a single buffer. By default, this lists
7926 items with a state the is not a DONE state. The buffer is in
7927 @code{agenda-mode}, so there are commands to examine and manipulate the TODO
7928 entries directly from that buffer (@pxref{Agenda commands}).
7929 @orgcmd{C-c a T,org-todo-list}
7930 @cindex TODO keyword matching
7931 @vindex org-todo-keywords
7932 Like the above, but allows selection of a specific TODO keyword. You can
7933 also do this by specifying a prefix argument to @kbd{C-c a t}. You are
7934 prompted for a keyword, and you may also specify several keywords by
7935 separating them with @samp{|} as the boolean OR operator. With a numeric
7936 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
7938 The @kbd{r} key in the agenda buffer regenerates it, and you can give
7939 a prefix argument to this command to change the selected TODO keyword,
7940 for example @kbd{3 r}. If you often need a search for a specific
7941 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
7942 Matching specific TODO keywords can also be done as part of a tags
7943 search (@pxref{Tag searches}).
7946 Remote editing of TODO items means that you can change the state of a
7947 TODO entry with a single key press. The commands available in the
7948 TODO list are described in @ref{Agenda commands}.
7950 @cindex sublevels, inclusion into TODO list
7951 Normally the global TODO list simply shows all headlines with TODO
7952 keywords. This list can become very long. There are two ways to keep
7956 @vindex org-agenda-todo-ignore-scheduled
7957 @vindex org-agenda-todo-ignore-deadlines
7958 @vindex org-agenda-todo-ignore-timestamp
7959 @vindex org-agenda-todo-ignore-with-date
7960 Some people view a TODO item that has been @emph{scheduled} for execution or
7961 have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.
7962 Configure the variables @code{org-agenda-todo-ignore-scheduled},
7963 @code{org-agenda-todo-ignore-deadlines},
7964 @code{org-agenda-todo-ignore-timestamp} and/or
7965 @code{org-agenda-todo-ignore-with-date} to exclude such items from the global
7968 @vindex org-agenda-todo-list-sublevels
7969 TODO items may have sublevels to break up the task into subtasks. In
7970 such cases it may be enough to list only the highest level TODO headline
7971 and omit the sublevels from the global list. Configure the variable
7972 @code{org-agenda-todo-list-sublevels} to get this behavior.
7975 @node Matching tags and properties
7976 @subsection Matching tags and properties
7977 @cindex matching, of tags
7978 @cindex matching, of properties
7982 If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
7983 or have properties (@pxref{Properties and columns}), you can select headlines
7984 based on this metadata and collect them into an agenda buffer. The match
7985 syntax described here also applies when creating sparse trees with @kbd{C-c /
7989 @orgcmd{C-c a m,org-tags-view}
7990 Produce a list of all headlines that match a given set of tags. The
7991 command prompts for a selection criterion, which is a boolean logic
7992 expression with tags, like @samp{+work+urgent-withboss} or
7993 @samp{work|home} (@pxref{Tags}). If you often need a specific search,
7994 define a custom command for it (@pxref{Agenda dispatcher}).
7995 @orgcmd{C-c a M,org-tags-view}
7996 @vindex org-tags-match-list-sublevels
7997 @vindex org-agenda-tags-todo-honor-ignore-options
7998 Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
7999 not-DONE state and force checking subitems (see variable
8000 @code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items,
8001 see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching
8002 specific TODO keywords together with a tags match is also possible, see
8006 The commands available in the tags list are described in @ref{Agenda
8009 @subsubheading Match syntax
8011 @cindex Boolean logic, for tag/property searches
8012 A search string can use Boolean operators @samp{&} for @code{AND} and
8013 @samp{|} for @code{OR}@. @samp{&} binds more strongly than @samp{|}.
8014 Parentheses are not implemented. Each element in the search is either a
8015 tag, a regular expression matching tags, or an expression like
8016 @code{PROPERTY OPERATOR VALUE} with a comparison operator, accessing a
8017 property value. Each element may be preceded by @samp{-}, to select
8018 against it, and @samp{+} is syntactic sugar for positive selection. The
8019 @code{AND} operator @samp{&} is optional when @samp{+} or @samp{-} is
8020 present. Here are some examples, using only tags.
8024 Select headlines tagged @samp{:work:}.
8026 Select headlines tagged @samp{:work:} and @samp{:boss:}.
8028 Select headlines tagged @samp{:work:}, but discard those also tagged
8031 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
8032 @item work|laptop+night
8033 Like before, but require the @samp{:laptop:} lines to be tagged also
8037 @cindex regular expressions, with tags search
8038 Instead of a tag, you may also specify a regular expression enclosed in curly
8039 braces. For example,
8040 @samp{work+@{^boss.*@}} matches headlines that contain the tag
8041 @samp{:work:} and any tag @i{starting} with @samp{boss}.
8043 @cindex group tags, as regular expressions
8044 Group tags (@pxref{Tag groups}) are expanded as regular expressions. E.g.,
8045 if @samp{:work:} is a group tag for the group @samp{:work:lab:conf:}, then
8046 searching for @samp{work} will search for @samp{@{\(?:work\|lab\|conf\)@}}
8047 and searching for @samp{-work} will search for all headlines but those with
8048 one of the tags in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}).
8050 @cindex TODO keyword matching, with tags search
8051 @cindex level, require for tags/property match
8052 @cindex category, require for tags/property match
8053 @vindex org-odd-levels-only
8054 You may also test for properties (@pxref{Properties and columns}) at the same
8055 time as matching tags. The properties may be real properties, or special
8056 properties that represent other metadata (@pxref{Special properties}). For
8057 example, the ``property'' @code{TODO} represents the TODO keyword of the
8058 entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of
8059 the entry. The ITEM special property cannot currently be used in tags/property
8060 searches@footnote{But @pxref{x-agenda-skip-entry-regexp,
8061 ,skipping entries based on regexp}.}.
8063 In addition to the @pxref{Special properties}, one other ``property'' can
8064 also be used. @code{LEVEL} represents the level of an entry. So a search
8065 @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines that have
8066 the tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE@.
8067 In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not count
8068 the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
8070 Here are more examples:
8073 @item work+TODO="WAITING"
8074 Select @samp{:work:}-tagged TODO lines with the specific TODO
8075 keyword @samp{WAITING}.
8076 @item work+TODO="WAITING"|home+TODO="WAITING"
8077 Waiting tasks both at work and at home.
8080 When matching properties, a number of different operators can be used to test
8081 the value of a property. Here is a complex example:
8084 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \
8085 +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
8089 The type of comparison will depend on how the comparison value is written:
8092 If the comparison value is a plain number, a numerical comparison is done,
8093 and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
8094 @samp{>=}, and @samp{<>}.
8096 If the comparison value is enclosed in double-quotes,
8097 a string comparison is done, and the same operators are allowed.
8099 If the comparison value is enclosed in double-quotes @emph{and} angular
8100 brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
8101 assumed to be date/time specifications in the standard Org way, and the
8102 comparison will be done accordingly. Special values that will be recognized
8103 are @code{"<now>"} for now (including time), and @code{"<today>"}, and
8104 @code{"<tomorrow>"} for these days at 0:00 hours, i.e., without a time
8105 specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
8106 @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
8107 respectively, can be used.
8109 If the comparison value is enclosed
8110 in curly braces, a regexp match is performed, with @samp{=} meaning that the
8111 regexp matches the property value, and @samp{<>} meaning that it does not
8115 So the search string in the example finds entries tagged @samp{:work:} but
8116 not @samp{:boss:}, which also have a priority value @samp{A}, a
8117 @samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
8118 property that is numerically smaller than 2, a @samp{:With:} property that is
8119 matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
8120 on or after October 11, 2008.
8122 Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing any
8123 other properties will slow down the search. However, once you have paid the
8124 price by accessing one property, testing additional properties is cheap
8127 You can configure Org mode to use property inheritance during a search, but
8128 beware that this can slow down searches considerably. See @ref{Property
8129 inheritance}, for details.
8131 For backward compatibility, and also for typing speed, there is also a
8132 different way to test TODO states in a search. For this, terminate the
8133 tags/property part of the search string (which may include several terms
8134 connected with @samp{|}) with a @samp{/} and then specify a Boolean
8135 expression just for TODO keywords. The syntax is then similar to that for
8136 tags, but should be applied with care: for example, a positive selection on
8137 several TODO keywords cannot meaningfully be combined with boolean AND@.
8138 However, @emph{negative selection} combined with AND can be meaningful. To
8139 make sure that only lines are checked that actually have any TODO keyword
8140 (resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
8141 part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will
8142 not match TODO keywords in a DONE state. Examples:
8146 Same as @samp{work+TODO="WAITING"}
8147 @item work/!-WAITING-NEXT
8148 Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
8150 @item work/!+WAITING|+NEXT
8151 Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
8156 @subsection Timeline for a single file
8157 @cindex timeline, single file
8158 @cindex time-sorted view
8160 The timeline summarizes all time-stamped items from a single Org mode
8161 file in a @emph{time-sorted view}. The main purpose of this command is
8162 to give an overview over events in a project.
8165 @orgcmd{C-c a L,org-timeline}
8166 Show a time-sorted view of the Org file, with all time-stamped items.
8167 When called with a @kbd{C-u} prefix, all unfinished TODO entries
8168 (scheduled or not) are also listed under the current date.
8172 The commands available in the timeline buffer are listed in
8173 @ref{Agenda commands}.
8176 @subsection Search view
8179 @cindex searching, for text
8181 This agenda view is a general text search facility for Org mode entries.
8182 It is particularly useful to find notes.
8185 @orgcmd{C-c a s,org-search-view}
8186 This is a special search that lets you select entries by matching a substring
8187 or specific words using a boolean logic.
8189 For example, the search string @samp{computer equipment} will find entries
8190 that contain @samp{computer equipment} as a substring. If the two words are
8191 separated by more space or a line break, the search will still match.
8192 Search view can also search for specific keywords in the entry, using Boolean
8193 logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
8194 will search for note entries that contain the keywords @code{computer}
8195 and @code{wifi}, but not the keyword @code{ethernet}, and which are also
8196 not matched by the regular expression @code{8\.11[bg]}, meaning to
8197 exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on
8198 word search, other @samp{+} characters are optional. For more details, see
8199 the docstring of the command @code{org-search-view}.
8201 @vindex org-agenda-text-search-extra-files
8202 Note that in addition to the agenda files, this command will also search
8203 the files listed in @code{org-agenda-text-search-extra-files}.
8205 @node Stuck projects
8206 @subsection Stuck projects
8207 @pindex GTD, Getting Things Done
8209 If you are following a system like David Allen's GTD to organize your
8210 work, one of the ``duties'' you have is a regular review to make sure
8211 that all projects move along. A @emph{stuck} project is a project that
8212 has no defined next actions, so it will never show up in the TODO lists
8213 Org mode produces. During the review, you need to identify such
8214 projects and define next actions for them.
8217 @orgcmd{C-c a #,org-agenda-list-stuck-projects}
8218 List projects that are stuck.
8221 @vindex org-stuck-projects
8222 Customize the variable @code{org-stuck-projects} to define what a stuck
8223 project is and how to find it.
8226 You almost certainly will have to configure this view before it will
8227 work for you. The built-in default assumes that all your projects are
8228 level-2 headlines, and that a project is not stuck if it has at least
8229 one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
8231 Let's assume that you, in your own way of using Org mode, identify
8232 projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
8233 indicate a project that should not be considered yet. Let's further
8234 assume that the TODO keyword DONE marks finished projects, and that NEXT
8235 and TODO indicate next actions. The tag @@SHOP indicates shopping and
8236 is a next action even without the NEXT tag. Finally, if the project
8237 contains the special word IGNORE anywhere, it should not be listed
8238 either. In this case you would start by identifying eligible projects
8239 with a tags/todo match@footnote{@xref{Tag searches}.}
8240 @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, and
8241 IGNORE in the subtree to identify projects that are not stuck. The
8242 correct customization for this is
8245 (setq org-stuck-projects
8246 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
8250 Note that if a project is identified as non-stuck, the subtree of this entry
8251 will still be searched for stuck projects.
8253 @node Presentation and sorting
8254 @section Presentation and sorting
8255 @cindex presentation, of agenda items
8257 @vindex org-agenda-prefix-format
8258 @vindex org-agenda-tags-column
8259 Before displaying items in an agenda view, Org mode visually prepares the
8260 items and sorts them. Each item occupies a single line. The line starts
8261 with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
8262 of the item and other important information. You can customize in which
8263 column tags will be displayed through @code{org-agenda-tags-column}. You can
8264 also customize the prefix using the option @code{org-agenda-prefix-format}.
8265 This prefix is followed by a cleaned-up version of the outline headline
8266 associated with the item.
8269 * Categories:: Not all tasks are equal
8270 * Time-of-day specifications:: How the agenda knows the time
8271 * Sorting agenda items:: The order of things
8272 * Filtering/limiting agenda items:: Dynamically narrow the agenda
8276 @subsection Categories
8280 The category is a broad label assigned to each agenda item. By default,
8281 the category is simply derived from the file name, but you can also
8282 specify it with a special line in the buffer, like this@footnote{For
8283 backward compatibility, the following also works: if there are several
8284 such lines in a file, each specifies the category for the text below it.
8285 The first category also applies to any text before the first CATEGORY
8286 line. However, using this method is @emph{strongly} deprecated as it is
8287 incompatible with the outline structure of the document. The correct
8288 method for setting multiple categories in a buffer is using a
8296 @cindex property, CATEGORY
8297 If you would like to have a special CATEGORY for a single entry or a
8298 (sub)tree, give the entry a @code{:CATEGORY:} property with the
8299 special category you want to apply as the value.
8302 The display in the agenda buffer looks best if the category is not
8303 longer than 10 characters.
8306 You can set up icons for category by customizing the
8307 @code{org-agenda-category-icon-alist} variable.
8309 @node Time-of-day specifications
8310 @subsection Time-of-day specifications
8311 @cindex time-of-day specification
8313 Org mode checks each agenda item for a time-of-day specification. The
8314 time can be part of the timestamp that triggered inclusion into the
8315 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
8316 ranges can be specified with two timestamps, like
8318 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
8320 In the headline of the entry itself, a time(range) may also appear as
8321 plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda
8322 integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
8323 specifications in diary entries are recognized as well.
8325 For agenda display, Org mode extracts the time and displays it in a
8326 standard 24 hour format as part of the prefix. The example times in
8327 the previous paragraphs would end up in the agenda like this:
8330 8:30-13:00 Arthur Dent lies in front of the bulldozer
8331 12:45...... Ford Prefect arrives and takes Arthur to the pub
8332 19:00...... The Vogon reads his poem
8333 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8337 If the agenda is in single-day mode, or for the display of today, the
8338 timed entries are embedded in a time grid, like
8341 8:00...... ------------------
8342 8:30-13:00 Arthur Dent lies in front of the bulldozer
8343 10:00...... ------------------
8344 12:00...... ------------------
8345 12:45...... Ford Prefect arrives and takes Arthur to the pub
8346 14:00...... ------------------
8347 16:00...... ------------------
8348 18:00...... ------------------
8349 19:00...... The Vogon reads his poem
8350 20:00...... ------------------
8351 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8354 @vindex org-agenda-use-time-grid
8355 @vindex org-agenda-time-grid
8356 The time grid can be turned on and off with the variable
8357 @code{org-agenda-use-time-grid}, and can be configured with
8358 @code{org-agenda-time-grid}.
8360 @node Sorting agenda items
8361 @subsection Sorting agenda items
8362 @cindex sorting, of agenda items
8363 @cindex priorities, of agenda items
8364 Before being inserted into a view, the items are sorted. How this is
8365 done depends on the type of view.
8368 @vindex org-agenda-files
8369 For the daily/weekly agenda, the items for each day are sorted. The
8370 default order is to first collect all items containing an explicit
8371 time-of-day specification. These entries will be shown at the beginning
8372 of the list, as a @emph{schedule} for the day. After that, items remain
8373 grouped in categories, in the sequence given by @code{org-agenda-files}.
8374 Within each category, items are sorted by priority (@pxref{Priorities}),
8375 which is composed of the base priority (2000 for priority @samp{A}, 1000
8376 for @samp{B}, and 0 for @samp{C}), plus additional increments for
8377 overdue scheduled or deadline items.
8379 For the TODO list, items remain in the order of categories, but within
8380 each category, sorting takes place according to priority
8381 (@pxref{Priorities}). The priority used for sorting derives from the
8382 priority cookie, with additions depending on how close an item is to its due
8385 For tags matches, items are not sorted at all, but just appear in the
8386 sequence in which they are found in the agenda files.
8389 @vindex org-agenda-sorting-strategy
8390 Sorting can be customized using the variable
8391 @code{org-agenda-sorting-strategy}, and may also include criteria based on
8392 the estimated effort of an entry (@pxref{Effort estimates}).
8394 @node Filtering/limiting agenda items
8395 @subsection Filtering/limiting agenda items
8397 Agenda built-in or customized commands are statically defined. Agenda
8398 filters and limits provide two ways of dynamically narrowing down the list of
8399 agenda entries: @emph{filters} and @emph{limits}. Filters only act on the
8400 display of the items, while limits take effect before the list of agenda
8401 entries is built. Filters are more often used interactively, while limits are
8402 mostly useful when defined as local variables within custom agenda commands.
8404 @subsubheading Filtering in the agenda
8405 @cindex filtering, by tag, category, top headline and effort, in agenda
8406 @cindex tag filtering, in agenda
8407 @cindex category filtering, in agenda
8408 @cindex top headline filtering, in agenda
8409 @cindex effort filtering, in agenda
8410 @cindex query editing, in agenda
8413 @orgcmd{/,org-agenda-filter-by-tag}
8414 @vindex org-agenda-tag-filter-preset
8415 Filter the agenda view with respect to a tag and/or effort estimates. The
8416 difference between this and a custom agenda command is that filtering is very
8417 fast, so that you can switch quickly between different filters without having
8418 to recreate the agenda.@footnote{Custom commands can preset a filter by
8419 binding the variable @code{org-agenda-tag-filter-preset} as an option. This
8420 filter will then be applied to the view and persist as a basic filter through
8421 refreshes and more secondary filtering. The filter is a global property of
8422 the entire agenda view---in a block agenda, you should only set this in the
8423 global options section, not in the section of an individual block.}
8425 You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
8426 all. Pressing @key{TAB} at that prompt will offer use completion to select a
8427 tag (including any tags that do not have a selection character). The command
8428 then hides all entries that do not contain or inherit this tag. When called
8429 with prefix arg, remove the entries that @emph{do} have the tag. A second
8430 @kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
8431 If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
8432 will be narrowed by requiring or forbidding the selected additional tag.
8433 Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
8434 immediately use the @kbd{\} command.
8436 @vindex org-sort-agenda-noeffort-is-high
8437 In order to filter for effort estimates, you should set up allowed
8438 efforts globally, for example
8440 (setq org-global-properties
8441 '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
8443 You can then filter for an effort by first typing an operator, one of
8444 @kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
8445 estimate in your array of allowed values, where @kbd{0} means the 10th value.
8446 The filter will then restrict to entries with effort smaller-or-equal, equal,
8447 or larger-or-equal than the selected value. If the digits 0--9 are not used
8448 as fast access keys to tags, you can also simply press the index digit
8449 directly without an operator. In this case, @kbd{<} will be assumed. For
8450 application of the operator, entries without a defined effort will be treated
8451 according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter
8452 for tasks without effort definition, press @kbd{?} as the operator.
8454 Org also supports automatic, context-aware tag filtering. If the variable
8455 @code{org-agenda-auto-exclude-function} is set to a user-defined function,
8456 that function can decide which tags should be excluded from the agenda
8457 automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
8458 as a sub-option key and runs the auto exclusion logic. For example, let's
8459 say you use a @code{Net} tag to identify tasks which need network access, an
8460 @code{Errand} tag for errands in town, and a @code{Call} tag for making phone
8461 calls. You could auto-exclude these tags based on the availability of the
8462 Internet, and outside of business hours, with something like this:
8466 (defun org-my-auto-exclude-function (tag)
8468 ((string= tag "Net")
8469 (/= 0 (call-process "/sbin/ping" nil nil nil
8470 "-c1" "-q" "-t1" "mail.gnu.org")))
8471 ((or (string= tag "Errand") (string= tag "Call"))
8472 (let ((hour (nth 2 (decode-time))))
8473 (or (< hour 8) (> hour 21)))))
8476 (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
8480 @orgcmd{\\,org-agenda-filter-by-tag-refine}
8481 Narrow the current agenda filter by an additional condition. When called with
8482 prefix arg, remove the entries that @emph{do} have the tag, or that do match
8483 the effort criterion. You can achieve the same effect by pressing @kbd{+} or
8484 @kbd{-} as the first key after the @kbd{/} command.
8493 @item @r{in} search view
8494 add new search words (@kbd{[} and @kbd{]}) or new regular expressions
8495 (@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
8496 add a positive search term prefixed by @samp{+}, indicating that this search
8497 term @i{must} occur/match in the entry. The closing bracket/brace will add a
8498 negative search term which @i{must not} occur/match in the entry for it to be
8502 @orgcmd{<,org-agenda-filter-by-category}
8503 @vindex org-agenda-category-filter-preset
8505 Filter the current agenda view with respect to the category of the item at
8506 point. Pressing @code{<} another time will remove this filter. You can add
8507 a filter preset through the option @code{org-agenda-category-filter-preset}
8510 @orgcmd{^,org-agenda-filter-by-top-headline}
8511 Filter the current agenda view and only display the siblings and the parent
8512 headline of the one at point.
8514 @orgcmd{=,org-agenda-filter-by-regexp}
8515 @vindex org-agenda-regexp-filter-preset
8517 Filter the agenda view by a regular expression: only show agenda entries
8518 matching the regular expression the user entered. When called with a prefix
8519 argument, it will filter @emph{out} entries matching the regexp. With two
8520 universal prefix arguments, it will remove all the regexp filters, which can
8521 be accumulated. You can add a filter preset through the option
8522 @code{org-agenda-category-filter-preset} (see below.)
8524 @orgcmd{|,org-agenda-filter-remove-all}
8525 Remove all filters in the current agenda view.
8528 @subsubheading Setting limits for the agenda
8529 @cindex limits, in agenda
8530 @vindex org-agenda-max-entries
8531 @vindex org-agenda-max-effort
8532 @vindex org-agenda-max-todos
8533 @vindex org-agenda-max-tags
8535 Here is a list of options that you can set, either globally, or locally in
8536 your custom agenda views@pxref{Custom agenda views}.
8539 @item org-agenda-max-entries
8540 Limit the number of entries.
8541 @item org-agenda-max-effort
8542 Limit the duration of accumulated efforts (as minutes).
8543 @item org-agenda-max-todos
8544 Limit the number of entries with TODO keywords.
8545 @item org-agenda-max-tags
8546 Limit the number of tagged entries.
8549 When set to a positive integer, each option will exclude entries from other
8550 categories: for example, @code{(setq org-agenda-max-effort 100)} will limit
8551 the agenda to 100 minutes of effort and exclude any entry that has no effort
8552 property. If you want to include entries with no effort property, use a
8553 negative value for @code{org-agenda-max-effort}.
8555 One useful setup is to use @code{org-agenda-max-entries} locally in a custom
8556 command. For example, this custom command will display the next five entries
8557 with a @code{NEXT} TODO keyword.
8560 (setq org-agenda-custom-commands
8562 ((org-agenda-max-entries 5)))))
8565 Once you mark one of these five entry as @code{DONE}, rebuilding the agenda
8566 will again the next five entries again, including the first entry that was
8569 You can also dynamically set temporary limits@footnote{Those temporary limits
8570 are lost when rebuilding the agenda.}:
8573 @orgcmd{~,org-agenda-limit-interactively}
8574 This prompts for the type of limit to apply and its value.
8577 @node Agenda commands
8578 @section Commands in the agenda buffer
8579 @cindex commands, in agenda buffer
8581 Entries in the agenda buffer are linked back to the Org file or diary
8582 file where they originate. You are not allowed to edit the agenda
8583 buffer itself, but commands are provided to show and jump to the
8584 original entry location, and to edit the Org files ``remotely'' from
8585 the agenda buffer. In this way, all information is stored only once,
8586 removing the risk that your agenda and note files may diverge.
8588 Some commands can be executed with mouse clicks on agenda lines. For
8589 the other commands, the cursor needs to be in the desired line.
8592 @tsubheading{Motion}
8593 @cindex motion commands in agenda
8594 @orgcmd{n,org-agenda-next-line}
8595 Next line (same as @key{down} and @kbd{C-n}).
8596 @orgcmd{p,org-agenda-previous-line}
8597 Previous line (same as @key{up} and @kbd{C-p}).
8598 @tsubheading{View/Go to Org file}
8599 @orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
8600 Display the original location of the item in another window.
8601 With prefix arg, make sure that the entire entry is made visible in the
8602 outline, not only the heading.
8604 @orgcmd{L,org-agenda-recenter}
8605 Display original location and recenter that window.
8607 @orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
8608 Go to the original location of the item in another window.
8610 @orgcmd{@key{RET},org-agenda-switch-to}
8611 Go to the original location of the item and delete other windows.
8613 @orgcmd{F,org-agenda-follow-mode}
8614 @vindex org-agenda-start-with-follow-mode
8615 Toggle Follow mode. In Follow mode, as you move the cursor through
8616 the agenda buffer, the other window always shows the corresponding
8617 location in the Org file. The initial setting for this mode in new
8618 agenda buffers can be set with the variable
8619 @code{org-agenda-start-with-follow-mode}.
8621 @orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
8622 Display the entire subtree of the current item in an indirect buffer. With a
8623 numeric prefix argument N, go up to level N and then take that tree. If N is
8624 negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the
8625 previously used indirect buffer.
8627 @orgcmd{C-c C-o,org-agenda-open-link}
8628 Follow a link in the entry. This will offer a selection of any links in the
8629 text belonging to the referenced Org node. If there is only one link, it
8630 will be followed without a selection prompt.
8632 @tsubheading{Change display}
8633 @cindex display changing, in agenda
8636 Interactively select another agenda view and append it to the current view.
8640 Delete other windows.
8642 @orgcmdkskc{v d,d,org-agenda-day-view}
8643 @xorgcmdkskc{v w,w,org-agenda-week-view}
8644 @xorgcmd{v t,org-agenda-fortnight-view}
8645 @xorgcmd{v m,org-agenda-month-view}
8646 @xorgcmd{v y,org-agenda-year-view}
8647 @xorgcmd{v SPC,org-agenda-reset-view}
8648 @vindex org-agenda-span
8649 Switch to day/week/month/year view. When switching to day or week view, this
8650 setting becomes the default for subsequent agenda refreshes. Since month and
8651 year views are slow to create, they do not become the default. A numeric
8652 prefix argument may be used to jump directly to a specific day of the year,
8653 ISO week, month, or year, respectively. For example, @kbd{32 d} jumps to
8654 February 1st, @kbd{9 w} to ISO week number 9. When setting day, week, or
8655 month view, a year may be encoded in the prefix argument as well. For
8656 example, @kbd{200712 w} will jump to week 12 in 2007. If such a year
8657 specification has only one or two digits, it will be mapped to the interval
8658 1938--2037. @kbd{v @key{SPC}} will reset to what is set in
8659 @code{org-agenda-span}.
8661 @orgcmd{f,org-agenda-later}
8662 Go forward in time to display the following @code{org-agenda-current-span} days.
8663 For example, if the display covers a week, switch to the following week.
8664 With prefix arg, go forward that many times @code{org-agenda-current-span} days.
8666 @orgcmd{b,org-agenda-earlier}
8667 Go backward in time to display earlier dates.
8669 @orgcmd{.,org-agenda-goto-today}
8672 @orgcmd{j,org-agenda-goto-date}
8673 Prompt for a date and go there.
8675 @orgcmd{J,org-agenda-clock-goto}
8676 Go to the currently clocked-in task @i{in the agenda buffer}.
8678 @orgcmd{D,org-agenda-toggle-diary}
8679 Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}.
8681 @orgcmdkskc{v l,l,org-agenda-log-mode}
8683 @vindex org-log-done
8684 @vindex org-agenda-log-mode-items
8685 Toggle Logbook mode. In Logbook mode, entries that were marked DONE while
8686 logging was on (variable @code{org-log-done}) are shown in the agenda, as are
8687 entries that have been clocked on that day. You can configure the entry
8688 types that should be included in log mode using the variable
8689 @code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show
8690 all possible logbook entries, including state changes. When called with two
8691 prefix arguments @kbd{C-u C-u}, show only logging information, nothing else.
8692 @kbd{v L} is equivalent to @kbd{C-u v l}.
8694 @orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
8695 Include inactive timestamps into the current view. Only for weekly/daily
8696 agenda and timeline views.
8698 @orgcmd{v a,org-agenda-archives-mode}
8699 @xorgcmd{v A,org-agenda-archives-mode 'files}
8700 Toggle Archives mode. In Archives mode, trees that are marked
8701 @code{ARCHIVED} are also scanned when producing the agenda. When you use the
8702 capital @kbd{A}, even all archive files are included. To exit archives mode,
8703 press @kbd{v a} again.
8705 @orgcmdkskc{v R,R,org-agenda-clockreport-mode}
8706 @vindex org-agenda-start-with-clockreport-mode
8707 @vindex org-clock-report-include-clocking-task
8708 Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will
8709 always show a table with the clocked times for the time span and file scope
8710 covered by the current agenda view. The initial setting for this mode in new
8711 agenda buffers can be set with the variable
8712 @code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
8713 when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
8714 contributions from entries that are hidden by agenda filtering@footnote{Only
8715 tags filtering will be respected here, effort filtering is ignored.}. See
8716 also the variable @code{org-clock-report-include-clocking-task}.
8719 @vindex org-agenda-clock-consistency-checks
8720 Show overlapping clock entries, clocking gaps, and other clocking problems in
8721 the current agenda range. You can then visit clocking lines and fix them
8722 manually. See the variable @code{org-agenda-clock-consistency-checks} for
8723 information on how to customize the definition of what constituted a clocking
8724 problem. To return to normal agenda display, press @kbd{l} to exit Logbook
8727 @orgcmdkskc{v E,E,org-agenda-entry-text-mode}
8728 @vindex org-agenda-start-with-entry-text-mode
8729 @vindex org-agenda-entry-text-maxlines
8730 Toggle entry text mode. In entry text mode, a number of lines from the Org
8731 outline node referenced by an agenda line will be displayed below the line.
8732 The maximum number of lines is given by the variable
8733 @code{org-agenda-entry-text-maxlines}. Calling this command with a numeric
8734 prefix argument will temporarily modify that number to the prefix value.
8736 @orgcmd{G,org-agenda-toggle-time-grid}
8737 @vindex org-agenda-use-time-grid
8738 @vindex org-agenda-time-grid
8739 Toggle the time grid on and off. See also the variables
8740 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
8742 @orgcmd{r,org-agenda-redo}
8743 Recreate the agenda buffer, for example to reflect the changes after
8744 modification of the timestamps of items with @kbd{S-@key{left}} and
8745 @kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix
8746 argument is interpreted to create a selective list for a specific TODO
8748 @orgcmd{g,org-agenda-redo}
8751 @orgcmdkskc{C-x C-s,s,org-save-all-org-buffers}
8752 Save all Org buffers in the current Emacs session, and also the locations of
8755 @orgcmd{C-c C-x C-c,org-agenda-columns}
8756 @vindex org-columns-default-format
8757 Invoke column view (@pxref{Column view}) in the agenda buffer. The column
8758 view format is taken from the entry at point, or (if there is no entry at
8759 point), from the first entry in the agenda view. So whatever the format for
8760 that entry would be in the original buffer (taken from a property, from a
8761 @code{#+COLUMNS} line, or from the default variable
8762 @code{org-columns-default-format}), will be used in the agenda.
8764 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
8765 Remove the restriction lock on the agenda, if it is currently restricted to a
8766 file or subtree (@pxref{Agenda files}).
8768 @tsubheading{Secondary filtering and query editing}
8770 For a detailed description of these commands, see @pxref{Filtering/limiting
8773 @orgcmd{/,org-agenda-filter-by-tag}
8774 @vindex org-agenda-tag-filter-preset
8775 Filter the agenda view with respect to a tag and/or effort estimates.
8777 @orgcmd{\\,org-agenda-filter-by-tag-refine}
8778 Narrow the current agenda filter by an additional condition.
8780 @orgcmd{<,org-agenda-filter-by-category}
8781 @vindex org-agenda-category-filter-preset
8783 Filter the current agenda view with respect to the category of the item at
8784 point. Pressing @code{<} another time will remove this filter.
8786 @orgcmd{^,org-agenda-filter-by-top-headline}
8787 Filter the current agenda view and only display the siblings and the parent
8788 headline of the one at point.
8790 @orgcmd{=,org-agenda-filter-by-regexp}
8791 @vindex org-agenda-regexp-filter-preset
8793 Filter the agenda view by a regular expression: only show agenda entries
8794 matching the regular expression the user entered. When called with a prefix
8795 argument, it will filter @emph{out} entries matching the regexp. With two
8796 universal prefix arguments, it will remove all the regexp filters, which can
8797 be accumulated. You can add a filter preset through the option
8798 @code{org-agenda-category-filter-preset} (see below.)
8800 @orgcmd{|,org-agenda-filter-remove-all}
8801 Remove all filters in the current agenda view.
8803 @tsubheading{Remote editing}
8804 @cindex remote editing, from agenda
8809 @cindex undoing remote-editing events
8810 @cindex remote editing, undo
8811 @orgcmd{C-_,org-agenda-undo}
8812 Undo a change due to a remote editing command. The change is undone
8813 both in the agenda buffer and in the remote buffer.
8815 @orgcmd{t,org-agenda-todo}
8816 Change the TODO state of the item, both in the agenda and in the
8819 @orgcmd{C-S-@key{right},org-agenda-todo-nextset}
8820 @orgcmd{C-S-@key{left},org-agenda-todo-previousset}
8821 Switch to the next/previous set of TODO keywords.
8823 @orgcmd{C-k,org-agenda-kill}
8824 @vindex org-agenda-confirm-kill
8825 Delete the current agenda item along with the entire subtree belonging
8826 to it in the original Org file. If the text to be deleted remotely
8827 is longer than one line, the kill needs to be confirmed by the user. See
8828 variable @code{org-agenda-confirm-kill}.
8830 @orgcmd{C-c C-w,org-agenda-refile}
8831 Refile the entry at point.
8833 @orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation}
8834 @vindex org-archive-default-command
8835 Archive the subtree corresponding to the entry at point using the default
8836 archiving command set in @code{org-archive-default-command}. When using the
8837 @code{a} key, confirmation will be required.
8839 @orgcmd{C-c C-x a,org-agenda-toggle-archive-tag}
8840 Toggle the ARCHIVE tag for the current headline.
8842 @orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling}
8843 Move the subtree corresponding to the current entry to its @emph{archive
8846 @orgcmdkskc{C-c C-x C-s,$,org-agenda-archive}
8847 Archive the subtree corresponding to the current headline. This means the
8848 entry will be moved to the configured archive location, most likely a
8851 @orgcmd{T,org-agenda-show-tags}
8852 @vindex org-agenda-show-inherited-tags
8853 Show all tags associated with the current item. This is useful if you have
8854 turned off @code{org-agenda-show-inherited-tags}, but still want to see all
8855 tags of a headline occasionally.
8857 @orgcmd{:,org-agenda-set-tags}
8858 Set tags for the current headline. If there is an active region in the
8859 agenda, change a tag for all headings in the region.
8863 Set the priority for the current item (@command{org-agenda-priority}).
8864 Org mode prompts for the priority character. If you reply with @key{SPC},
8865 the priority cookie is removed from the entry.
8867 @orgcmd{P,org-agenda-show-priority}
8868 Display weighted priority of current item.
8870 @orgcmdkkc{+,S-@key{up},org-agenda-priority-up}
8871 Increase the priority of the current item. The priority is changed in
8872 the original buffer, but the agenda is not resorted. Use the @kbd{r}
8875 @orgcmdkkc{-,S-@key{down},org-agenda-priority-down}
8876 Decrease the priority of the current item.
8878 @orgcmdkkc{z,C-c C-z,org-agenda-add-note}
8879 @vindex org-log-into-drawer
8880 Add a note to the entry. This note will be recorded, and then filed to the
8881 same location where state change notes are put. Depending on
8882 @code{org-log-into-drawer}, this may be inside a drawer.
8884 @orgcmd{C-c C-a,org-attach}
8885 Dispatcher for all command related to attachments.
8887 @orgcmd{C-c C-s,org-agenda-schedule}
8888 Schedule this item. With prefix arg remove the scheduling timestamp
8890 @orgcmd{C-c C-d,org-agenda-deadline}
8891 Set a deadline for this item. With prefix arg remove the deadline.
8893 @orgcmd{S-@key{right},org-agenda-do-date-later}
8894 Change the timestamp associated with the current line by one day into the
8895 future. If the date is in the past, the first call to this command will move
8897 With a numeric prefix argument, change it by that many days. For example,
8898 @kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix,
8899 change the time by one hour. If you immediately repeat the command, it will
8900 continue to change hours even without the prefix arg. With a double @kbd{C-u
8901 C-u} prefix, do the same for changing minutes.@*
8902 The stamp is changed in the original Org file, but the change is not directly
8903 reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
8905 @orgcmd{S-@key{left},org-agenda-do-date-earlier}
8906 Change the timestamp associated with the current line by one day
8909 @orgcmd{>,org-agenda-date-prompt}
8910 Change the timestamp associated with the current line. The key @kbd{>} has
8911 been chosen, because it is the same as @kbd{S-.} on my keyboard.
8913 @orgcmd{I,org-agenda-clock-in}
8914 Start the clock on the current item. If a clock is running already, it
8917 @orgcmd{O,org-agenda-clock-out}
8918 Stop the previously started clock.
8920 @orgcmd{X,org-agenda-clock-cancel}
8921 Cancel the currently running clock.
8923 @orgcmd{J,org-agenda-clock-goto}
8924 Jump to the running clock in another window.
8926 @orgcmd{k,org-agenda-capture}
8927 Like @code{org-capture}, but use the date at point as the default date for
8928 the capture template. See @code{org-capture-use-agenda-date} to make this
8929 the default behavior of @code{org-capture}.
8930 @cindex capturing, from agenda
8931 @vindex org-capture-use-agenda-date
8933 @tsubheading{Dragging agenda lines forward/backward}
8934 @cindex dragging, agenda lines
8936 @orgcmd{M-<up>,org-agenda-drag-line-backward}
8937 Drag the line at point backward one line@footnote{Moving agenda lines does
8938 not persist after an agenda refresh and does not modify the contributing
8939 @file{.org} files}. With a numeric prefix argument, drag backward by that
8942 @orgcmd{M-<down>,org-agenda-drag-line-forward}
8943 Drag the line at point forward one line. With a numeric prefix argument,
8944 drag forward by that many lines.
8946 @tsubheading{Bulk remote editing selected entries}
8947 @cindex remote editing, bulk, from agenda
8948 @vindex org-agenda-bulk-custom-functions
8950 @orgcmd{m,org-agenda-bulk-mark}
8951 Mark the entry at point for bulk action. With numeric prefix argument, mark
8952 that many successive entries.
8954 @orgcmd{*,org-agenda-bulk-mark-all}
8955 Mark all visible agenda entries for bulk action.
8957 @orgcmd{u,org-agenda-bulk-unmark}
8958 Unmark entry at point for bulk action.
8960 @orgcmd{U,org-agenda-bulk-remove-all-marks}
8961 Unmark all marked entries for bulk action.
8963 @orgcmd{M-m,org-agenda-bulk-toggle}
8964 Toggle mark of the entry at point for bulk action.
8966 @orgcmd{M-*,org-agenda-bulk-toggle-all}
8967 Toggle marks of all visible entries for bulk action.
8969 @orgcmd{%,org-agenda-bulk-mark-regexp}
8970 Mark entries matching a regular expression for bulk action.
8972 @orgcmd{B,org-agenda-bulk-action}
8973 Bulk action: act on all marked entries in the agenda. This will prompt for
8974 another key to select the action to be applied. The prefix arg to @kbd{B}
8975 will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove
8976 these special timestamps. By default, marks are removed after the bulk. If
8977 you want them to persist, set @code{org-agenda-bulk-persistent-marks} to
8978 @code{t} or hit @kbd{p} at the prompt.
8982 Toggle persistent marks.
8984 Archive all selected entries.
8986 Archive entries by moving them to their respective archive siblings.
8988 Change TODO state. This prompts for a single TODO keyword and changes the
8989 state of all selected entries, bypassing blocking and suppressing logging
8990 notes (but not timestamps).
8992 Add a tag to all selected entries.
8994 Remove a tag from all selected entries.
8996 Schedule all items to a new date. To shift existing schedule dates by a
8997 fixed number of days, use something starting with double plus at the prompt,
8998 for example @samp{++8d} or @samp{++2w}.
9000 Set deadline to a specific date.
9002 Prompt for a single refile target and move all entries. The entries will no
9003 longer be in the agenda; refresh (@kbd{g}) to bring them back.
9005 Reschedule randomly into the coming N days. N will be prompted for. With
9006 prefix arg (@kbd{C-u B S}), scatter only across weekdays.
9008 Apply a function@footnote{You can also create persistent custom functions
9009 through @code{org-agenda-bulk-custom-functions}.} to marked entries. For
9010 example, the function below sets the CATEGORY property of the entries to web.
9014 (defun set-category ()
9016 (let* ((marker (or (org-get-at-bol 'org-hd-marker)
9017 (org-agenda-error)))
9018 (buffer (marker-buffer marker)))
9019 (with-current-buffer buffer
9024 (org-back-to-heading t)
9025 (org-set-property "CATEGORY" "web"))))))
9030 @tsubheading{Calendar commands}
9031 @cindex calendar commands, from agenda
9033 @orgcmd{c,org-agenda-goto-calendar}
9034 Open the Emacs calendar and move to the date at the agenda cursor.
9036 @orgcmd{c,org-calendar-goto-agenda}
9037 When in the calendar, compute and show the Org mode agenda for the
9040 @cindex diary entries, creating from agenda
9041 @orgcmd{i,org-agenda-diary-entry}
9042 @vindex org-agenda-diary-file
9043 Insert a new entry into the diary, using the date at the cursor and (for
9044 block entries) the date at the mark. This will add to the Emacs diary
9045 file@footnote{This file is parsed for the agenda when
9046 @code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
9047 command in the calendar. The diary file will pop up in another window, where
9048 you can add the entry.
9050 If you configure @code{org-agenda-diary-file} to point to an Org mode file,
9051 Org will create entries (in Org mode syntax) in that file instead. Most
9052 entries will be stored in a date-based outline tree that will later make it
9053 easy to archive appointments from previous months/years. The tree will be
9054 built under an entry with a @code{DATE_TREE} property, or else with years as
9055 top-level entries. Emacs will prompt you for the entry text---if you specify
9056 it, the entry will be created in @code{org-agenda-diary-file} without further
9057 interaction. If you directly press @key{RET} at the prompt without typing
9058 text, the target file will be shown in another window for you to finish the
9059 entry there. See also the @kbd{k r} command.
9061 @orgcmd{M,org-agenda-phases-of-moon}
9062 Show the phases of the moon for the three months around current date.
9064 @orgcmd{S,org-agenda-sunrise-sunset}
9065 Show sunrise and sunset times. The geographical location must be set
9066 with calendar variables, see the documentation for the Emacs calendar.
9068 @orgcmd{C,org-agenda-convert-date}
9069 Convert the date at cursor into many other cultural and historic
9072 @orgcmd{H,org-agenda-holidays}
9073 Show holidays for three months around the cursor date.
9075 @item M-x org-icalendar-combine-agenda-files RET
9076 Export a single iCalendar file containing entries from all agenda files.
9077 This is a globally available command, and also available in the agenda menu.
9079 @tsubheading{Exporting to a file}
9080 @orgcmd{C-x C-w,org-agenda-write}
9081 @cindex exporting agenda views
9082 @cindex agenda views, exporting
9083 @vindex org-agenda-exporter-settings
9084 Write the agenda view to a file. Depending on the extension of the selected
9085 file name, the view will be exported as HTML (@file{.html} or @file{.htm}),
9086 Postscript (@file{.ps}), PDF (@file{.pdf}), Org (@file{.org}) and plain text
9087 (any other extension). When exporting to Org, only the body of original
9088 headlines are exported, not subtrees or inherited tags. When called with a
9089 @kbd{C-u} prefix argument, immediately open the newly created file. Use the
9090 variable @code{org-agenda-exporter-settings} to set options for
9091 @file{ps-print} and for @file{htmlize} to be used during export.
9093 @tsubheading{Quit and Exit}
9094 @orgcmd{q,org-agenda-quit}
9095 Quit agenda, remove the agenda buffer.
9097 @cindex agenda files, removing buffers
9098 @orgcmd{x,org-agenda-exit}
9099 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
9100 for the compilation of the agenda. Buffers created by the user to
9101 visit Org files will not be removed.
9105 @node Custom agenda views
9106 @section Custom agenda views
9107 @cindex custom agenda views
9108 @cindex agenda views, custom
9110 Custom agenda commands serve two purposes: to store and quickly access
9111 frequently used TODO and tags searches, and to create special composite
9112 agenda buffers. Custom agenda commands will be accessible through the
9113 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
9116 * Storing searches:: Type once, use often
9117 * Block agenda:: All the stuff you need in a single buffer
9118 * Setting options:: Changing the rules
9121 @node Storing searches
9122 @subsection Storing searches
9124 The first application of custom searches is the definition of keyboard
9125 shortcuts for frequently used searches, either creating an agenda
9126 buffer, or a sparse tree (the latter covering of course only the current
9129 @vindex org-agenda-custom-commands
9130 @cindex agenda views, main example
9131 @cindex agenda, as an agenda views
9132 @cindex agenda*, as an agenda views
9133 @cindex tags, as an agenda view
9134 @cindex todo, as an agenda view
9140 Custom commands are configured in the variable
9141 @code{org-agenda-custom-commands}. You can customize this variable, for
9142 example by pressing @kbd{C-c a C}. You can also directly set it with Emacs
9143 Lisp in @file{.emacs}. The following example contains all valid agenda
9148 (setq org-agenda-custom-commands
9151 ("w" todo "WAITING")
9152 ("W" todo-tree "WAITING")
9153 ("u" tags "+boss-urgent")
9154 ("v" tags-todo "+boss-urgent")
9155 ("U" tags-tree "+boss-urgent")
9156 ("f" occur-tree "\\<FIXME\\>")
9157 ("h" . "HOME+Name tags searches") ; description for "h" prefix
9158 ("hl" tags "+home+Lisa")
9159 ("hp" tags "+home+Peter")
9160 ("hk" tags "+home+Kim")))
9165 The initial string in each entry defines the keys you have to press
9166 after the dispatcher command @kbd{C-c a} in order to access the command.
9167 Usually this will be just a single character, but if you have many
9168 similar commands, you can also define two-letter combinations where the
9169 first character is the same in several combinations and serves as a
9170 prefix key@footnote{You can provide a description for a prefix key by
9171 inserting a cons cell with the prefix and the description.}. The second
9172 parameter is the search type, followed by the string or regular
9173 expression to be used for the matching. The example above will
9178 as a global search for agenda entries planned@footnote{@emph{Planned} means
9179 here that these entries have some planning information attached to them, like
9180 a time-stamp, a scheduled or a deadline string. See
9181 @code{org-agenda-entry-types} on how to set what planning information will be
9182 taken into account.} this week/day.
9184 as a global search for agenda entries planned this week/day, but only those
9185 with an hour specification like @code{[h]h:mm}---think of them as appointments.
9187 as a global search for TODO entries with @samp{WAITING} as the TODO
9190 as the same search, but only in the current buffer and displaying the
9191 results as a sparse tree
9193 as a global tags search for headlines marked @samp{:boss:} but not
9196 as the same search as @kbd{C-c a u}, but limiting the search to
9197 headlines that are also TODO items
9199 as the same search as @kbd{C-c a u}, but only in the current buffer and
9200 displaying the result as a sparse tree
9202 to create a sparse tree (again: current buffer only) with all entries
9203 containing the word @samp{FIXME}
9205 as a prefix command for a HOME tags search where you have to press an
9206 additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,
9207 Peter, or Kim) as additional tag to match.
9210 Note that the @code{*-tree} agenda views need to be called from an
9211 Org buffer as they operate on the current buffer only.
9214 @subsection Block agenda
9215 @cindex block agenda
9216 @cindex agenda, with block views
9218 Another possibility is the construction of agenda views that comprise
9219 the results of @emph{several} commands, each of which creates a block in
9220 the agenda buffer. The available commands include @code{agenda} for the
9221 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
9222 for the global TODO list (as constructed with @kbd{C-c a t}), and the
9223 matching commands discussed above: @code{todo}, @code{tags}, and
9224 @code{tags-todo}. Here are two examples:
9228 (setq org-agenda-custom-commands
9229 '(("h" "Agenda and Home-related tasks"
9233 ("o" "Agenda and Office-related tasks"
9241 This will define @kbd{C-c a h} to create a multi-block view for stuff
9242 you need to attend to at home. The resulting agenda buffer will contain
9243 your agenda for the current week, all TODO items that carry the tag
9244 @samp{home}, and also all lines tagged with @samp{garden}. Finally the
9245 command @kbd{C-c a o} provides a similar view for office tasks.
9247 @node Setting options
9248 @subsection Setting options for custom commands
9249 @cindex options, for custom agenda views
9251 @vindex org-agenda-custom-commands
9252 Org mode contains a number of variables regulating agenda construction
9253 and display. The global variables define the behavior for all agenda
9254 commands, including the custom commands. However, if you want to change
9255 some settings just for a single custom view, you can do so. Setting
9256 options requires inserting a list of variable names and values at the
9257 right spot in @code{org-agenda-custom-commands}. For example:
9261 (setq org-agenda-custom-commands
9262 '(("w" todo "WAITING"
9263 ((org-agenda-sorting-strategy '(priority-down))
9264 (org-agenda-prefix-format " Mixed: ")))
9265 ("U" tags-tree "+boss-urgent"
9266 ((org-show-following-heading nil)
9267 (org-show-hierarchy-above nil)))
9269 ((org-agenda-files '("~org/notes.org"))
9270 (org-agenda-text-search-extra-files nil)))))
9275 Now the @kbd{C-c a w} command will sort the collected entries only by
9276 priority, and the prefix format is modified to just say @samp{ Mixed: }
9277 instead of giving the category of the entry. The sparse tags tree of
9278 @kbd{C-c a U} will now turn out ultra-compact, because neither the
9279 headline hierarchy above the match, nor the headline following the match
9280 will be shown. The command @kbd{C-c a N} will do a text search limited
9281 to only a single file.
9283 @vindex org-agenda-custom-commands
9284 For command sets creating a block agenda,
9285 @code{org-agenda-custom-commands} has two separate spots for setting
9286 options. You can add options that should be valid for just a single
9287 command in the set, and options that should be valid for all commands in
9288 the set. The former are just added to the command entry; the latter
9289 must come after the list of command entries. Going back to the block
9290 agenda example (@pxref{Block agenda}), let's change the sorting strategy
9291 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
9292 the results for GARDEN tags query in the opposite order,
9293 @code{priority-up}. This would look like this:
9297 (setq org-agenda-custom-commands
9298 '(("h" "Agenda and Home-related tasks"
9302 ((org-agenda-sorting-strategy '(priority-up)))))
9303 ((org-agenda-sorting-strategy '(priority-down))))
9304 ("o" "Agenda and Office-related tasks"
9311 As you see, the values and parentheses setting is a little complex.
9312 When in doubt, use the customize interface to set this variable---it
9313 fully supports its structure. Just one caveat: when setting options in
9314 this interface, the @emph{values} are just Lisp expressions. So if the
9315 value is a string, you need to add the double-quotes around the value
9318 @vindex org-agenda-custom-commands-contexts
9319 To control whether an agenda command should be accessible from a specific
9320 context, you can customize @code{org-agenda-custom-commands-contexts}. Let's
9321 say for example that you have an agenda command @code{"o"} displaying a view
9322 that you only need when reading emails. Then you would configure this option
9326 (setq org-agenda-custom-commands-contexts
9327 '(("o" (in-mode . "message-mode"))))
9330 You can also tell that the command key @code{"o"} should refer to another
9331 command key @code{"r"}. In that case, add this command key like this:
9334 (setq org-agenda-custom-commands-contexts
9335 '(("o" "r" (in-mode . "message-mode"))))
9338 See the docstring of the variable for more information.
9340 @node Exporting agenda views
9341 @section Exporting agenda views
9342 @cindex agenda views, exporting
9344 If you are away from your computer, it can be very useful to have a printed
9345 version of some agenda views to carry around. Org mode can export custom
9346 agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's
9347 @file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the
9348 ghostscript @file{ps2pdf} utility must be installed on the system. Selecting
9349 a PDF file will also create the postscript file.}, and iCalendar files. If
9350 you want to do this only occasionally, use the command
9353 @orgcmd{C-x C-w,org-agenda-write}
9354 @cindex exporting agenda views
9355 @cindex agenda views, exporting
9356 @vindex org-agenda-exporter-settings
9357 Write the agenda view to a file. Depending on the extension of the selected
9358 file name, the view will be exported as HTML (extension @file{.html} or
9359 @file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension
9360 @file{.ics}), or plain text (any other extension). Use the variable
9361 @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
9362 for @file{htmlize} to be used during export, for example
9364 @vindex org-agenda-add-entry-text-maxlines
9365 @vindex htmlize-output-type
9366 @vindex ps-number-of-columns
9367 @vindex ps-landscape-mode
9369 (setq org-agenda-exporter-settings
9370 '((ps-number-of-columns 2)
9371 (ps-landscape-mode t)
9372 (org-agenda-add-entry-text-maxlines 5)
9373 (htmlize-output-type 'css)))
9377 If you need to export certain agenda views frequently, you can associate
9378 any custom agenda command with a list of output file names
9379 @footnote{If you want to store standard views like the weekly agenda
9380 or the global TODO list as well, you need to define custom commands for
9381 them in order to be able to specify file names.}. Here is an example
9382 that first defines custom commands for the agenda and the global
9383 TODO list, together with a number of files to which to export them.
9384 Then we define two block agenda commands and specify file names for them
9385 as well. File names can be relative to the current working directory,
9390 (setq org-agenda-custom-commands
9391 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
9392 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
9393 ("h" "Agenda and Home-related tasks"
9398 ("~/views/home.html"))
9399 ("o" "Agenda and Office-related tasks"
9404 ("~/views/office.ps" "~/calendars/office.ics"))))
9408 The extension of the file name determines the type of export. If it is
9409 @file{.html}, Org mode will use the @file{htmlize.el} package to convert
9410 the buffer to HTML and save it to this file name. If the extension is
9411 @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
9412 Postscript output. If the extension is @file{.ics}, iCalendar export is
9413 run export over all files that were used to construct the agenda, and
9414 limit the export to entries listed in the agenda. Any other
9415 extension produces a plain ASCII file.
9417 The export files are @emph{not} created when you use one of those
9418 commands interactively because this might use too much overhead.
9419 Instead, there is a special command to produce @emph{all} specified
9423 @orgcmd{C-c a e,org-store-agenda-views}
9424 Export all agenda views that have export file names associated with
9428 You can use the options section of the custom agenda commands to also
9429 set options for the export commands. For example:
9432 (setq org-agenda-custom-commands
9434 ((ps-number-of-columns 2)
9435 (ps-landscape-mode t)
9436 (org-agenda-prefix-format " [ ] ")
9437 (org-agenda-with-colors nil)
9438 (org-agenda-remove-tags t))
9443 This command sets two options for the Postscript exporter, to make it
9444 print in two columns in landscape format---the resulting page can be cut
9445 in two and then used in a paper agenda. The remaining settings modify
9446 the agenda prefix to omit category and scheduling information, and
9447 instead include a checkbox to check off items. We also remove the tags
9448 to make the lines compact, and we don't want to use colors for the
9449 black-and-white printer. Settings specified in
9450 @code{org-agenda-exporter-settings} will also apply, but the settings
9451 in @code{org-agenda-custom-commands} take precedence.
9454 From the command line you may also use
9456 emacs -eval (org-batch-store-agenda-views) -kill
9459 or, if you need to modify some parameters@footnote{Quoting depends on the
9460 system you use, please check the FAQ for examples.}
9462 emacs -eval '(org-batch-store-agenda-views \
9463 org-agenda-span (quote month) \
9464 org-agenda-start-day "2007-11-01" \
9465 org-agenda-include-diary nil \
9466 org-agenda-files (quote ("~/org/project.org")))' \
9470 which will create the agenda views restricted to the file
9471 @file{~/org/project.org}, without diary entries and with a 30-day
9474 You can also extract agenda information in a way that allows further
9475 processing by other programs. See @ref{Extracting agenda information}, for
9479 @node Agenda column view
9480 @section Using column view in the agenda
9481 @cindex column view, in agenda
9482 @cindex agenda, column view
9484 Column view (@pxref{Column view}) is normally used to view and edit
9485 properties embedded in the hierarchical structure of an Org file. It can be
9486 quite useful to use column view also from the agenda, where entries are
9487 collected by certain criteria.
9490 @orgcmd{C-c C-x C-c,org-agenda-columns}
9491 Turn on column view in the agenda.
9494 To understand how to use this properly, it is important to realize that the
9495 entries in the agenda are no longer in their proper outline environment.
9496 This causes the following issues:
9500 @vindex org-columns-default-format
9501 @vindex org-overriding-columns-format
9502 Org needs to make a decision which @code{COLUMNS} format to use. Since the
9503 entries in the agenda are collected from different files, and different files
9504 may have different @code{COLUMNS} formats, this is a non-trivial problem.
9505 Org first checks if the variable @code{org-agenda-overriding-columns-format} is
9506 currently set, and if so, takes the format from there. Otherwise it takes
9507 the format associated with the first item in the agenda, or, if that item
9508 does not have a specific format (defined in a property, or in its file), it
9509 uses @code{org-columns-default-format}.
9511 @cindex property, special, CLOCKSUM
9512 If any of the columns has a summary type defined (@pxref{Column attributes}),
9513 turning on column view in the agenda will visit all relevant agenda files and
9514 make sure that the computations of this property are up to date. This is
9515 also true for the special @code{CLOCKSUM} property. Org will then sum the
9516 values displayed in the agenda. In the daily/weekly agenda, the sums will
9517 cover a single day; in all other views they cover the entire block. It is
9518 vital to realize that the agenda may show the same entry @emph{twice} (for
9519 example as scheduled and as a deadline), and it may show two entries from the
9520 same hierarchy (for example a @emph{parent} and its @emph{child}). In these
9521 cases, the summation in the agenda will lead to incorrect results because
9522 some values will count double.
9524 When the column view in the agenda shows the @code{CLOCKSUM}, that is always
9525 the entire clocked time for this item. So even in the daily/weekly agenda,
9526 the clocksum listed in column view may originate from times outside the
9527 current view. This has the advantage that you can compare these values with
9528 a column listing the planned total effort for a task---one of the major
9529 applications for column view in the agenda. If you want information about
9530 clocked time in the displayed period use clock table mode (press @kbd{R} in
9534 @cindex property, special, CLOCKSUM_T
9535 When the column view in the agenda shows the @code{CLOCKSUM_T}, that is
9536 always today's clocked time for this item. So even in the weekly agenda,
9537 the clocksum listed in column view only originates from today. This lets
9538 you compare the time you spent on a task for today, with the time already
9539 spent (via @code{CLOCKSUM}) and with the planned total effort for it.
9544 @chapter Markup for rich export
9546 When exporting Org mode documents, the exporter tries to reflect the
9547 structure of the document as accurately as possible in the back-end. Since
9548 export targets like HTML and @LaTeX{} allow much richer formatting, Org mode has
9549 rules on how to prepare text for rich export. This section summarizes the
9550 markup rules used in an Org mode buffer.
9553 * Structural markup elements:: The basic structure as seen by the exporter
9554 * Images and tables:: Images, tables and caption mechanism
9555 * Literal examples:: Source code examples with special formatting
9556 * Include files:: Include additional files into a document
9557 * Index entries:: Making an index
9558 * Macro replacement:: Use macros to create templates
9559 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
9560 * Special blocks:: Containers targeted at export back-ends
9563 @node Structural markup elements
9564 @section Structural markup elements
9567 * Document title:: Where the title is taken from
9568 * Headings and sections:: The document structure as seen by the exporter
9569 * Table of contents:: The if and where of the table of contents
9571 * Paragraphs:: Paragraphs
9572 * Footnote markup:: Footnotes
9573 * Emphasis and monospace:: Bold, italic, etc.
9574 * Horizontal rules:: Make a line
9575 * Comment lines:: What will *not* be exported
9578 @node Document title
9579 @subheading Document title
9580 @cindex document title, markup rules
9583 The title of the exported document is taken from the special line
9587 #+TITLE: This is the title of the document
9591 If this line does not exist, the title will be the name of the file
9592 associated with the buffer, without extension, or the buffer name.
9594 @cindex property, EXPORT_TITLE
9595 If you are exporting only a subtree, its heading will become the title of the
9596 document. If the subtree has a property @code{EXPORT_TITLE}, that will take
9599 @node Headings and sections
9600 @subheading Headings and sections
9601 @cindex headings and sections, markup rules
9603 @vindex org-export-headline-levels
9604 The outline structure of the document as described in @ref{Document
9605 structure}, forms the basis for defining sections of the exported document.
9606 However, since the outline structure is also used for (for example) lists of
9607 tasks, only the first three outline levels will be used as headings. Deeper
9608 levels will become itemized lists. You can change the location of this
9609 switch globally by setting the variable @code{org-export-headline-levels}, or on a
9610 per-file basis with a line
9617 @node Table of contents
9618 @subheading Table of contents
9619 @cindex table of contents, markup rules
9622 @vindex org-export-with-toc
9623 The table of contents is normally inserted directly before the first headline
9624 of the file. The depth of the table is by default the same as the number of
9625 headline levels, but you can choose a smaller number, or turn off the table
9626 of contents entirely, by configuring the variable @code{org-export-with-toc},
9627 or on a per-file basis with a line like
9630 #+OPTIONS: toc:2 (only to two levels in TOC)
9631 #+OPTIONS: toc:nil (no default TOC at all)
9634 If you would like to move the table of contents to a different location, you
9635 should turn off the default table using @code{org-export-with-toc} or
9636 @code{#+OPTIONS} and insert @code{#+TOC: headlines N} at the desired
9640 #+OPTIONS: toc:nil (no default TOC)
9642 #+TOC: headlines 2 (insert TOC here, with two headline levels)
9645 Multiple @code{#+TOC: headline} lines are allowed. The same @code{TOC}
9646 keyword can also generate a list of all tables (resp.@: all listings) with a
9647 caption in the buffer.
9650 #+TOC: listings (build a list of listings)
9651 #+TOC: tables (build a list of tables)
9654 @cindex property, ALT_TITLE
9655 The headline's title usually determines its corresponding entry in a table of
9656 contents. However, it is possible to specify an alternative title by
9657 setting @code{ALT_TITLE} property accordingly. It will then be used when
9662 @cindex lists, markup rules
9664 Plain lists as described in @ref{Plain lists}, are translated to the back-end's
9665 syntax for such lists. Most back-ends support unordered, ordered, and
9669 @subheading Paragraphs, line breaks, and quoting
9670 @cindex paragraphs, markup rules
9672 Paragraphs are separated by at least one empty line. If you need to enforce
9673 a line break within a paragraph, use @samp{\\} at the end of a line.
9675 To keep the line breaks in a region, but otherwise use normal formatting, you
9676 can use this construct, which can also be used to format poetry.
9678 @cindex #+BEGIN_VERSE
9681 Great clouds overhead
9682 Tiny black birds rise and fall
9689 When quoting a passage from another document, it is customary to format this
9690 as a paragraph that is indented on both the left and the right margin. You
9691 can include quotations in Org mode documents like this:
9693 @cindex #+BEGIN_QUOTE
9696 Everything should be made as simple as possible,
9697 but not any simpler -- Albert Einstein
9701 If you would like to center some text, do it like this:
9702 @cindex #+BEGIN_CENTER
9705 Everything should be made as simple as possible, \\
9711 @node Footnote markup
9712 @subheading Footnote markup
9713 @cindex footnotes, markup rules
9714 @cindex @file{footnote.el}
9716 Footnotes defined in the way described in @ref{Footnotes}, will be exported
9717 by all back-ends. Org allows multiple references to the same note, and
9718 multiple footnotes side by side.
9720 @node Emphasis and monospace
9721 @subheading Emphasis and monospace
9723 @cindex underlined text, markup rules
9724 @cindex bold text, markup rules
9725 @cindex italic text, markup rules
9726 @cindex verbatim text, markup rules
9727 @cindex code text, markup rules
9728 @cindex strike-through text, markup rules
9729 @vindex org-fontify-emphasized-text
9730 @vindex org-emphasis-regexp-components
9731 @vindex org-emphasis-alist
9732 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
9733 and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text
9734 in the code and verbatim string is not processed for Org mode specific
9735 syntax, it is exported verbatim.
9737 To turn off fontification for marked up text, you can set
9738 @code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of
9739 available markup syntax, you can customize @code{org-emphasis-alist}. To fine
9740 tune what characters are allowed before and after the markup characters, you
9741 can tweak @code{org-emphasis-regexp-components}. Beware that changing one of
9742 the above variables will no take effect until you reload Org, for which you
9743 may need to restart Emacs.
9745 @node Horizontal rules
9746 @subheading Horizontal rules
9747 @cindex horizontal rules, markup rules
9748 A line consisting of only dashes, and at least 5 of them, will be exported as
9752 @subheading Comment lines
9753 @cindex comment lines
9754 @cindex exporting, not
9755 @cindex #+BEGIN_COMMENT
9757 Lines starting with zero or more whitespace characters followed by one
9758 @samp{#} and a whitespace are treated as comments and will never be exported.
9759 Also entire subtrees starting with the word @samp{COMMENT} will never be
9760 exported. Finally, regions surrounded by @samp{#+BEGIN_COMMENT}
9761 ... @samp{#+END_COMMENT} will not be exported.
9766 Toggle the COMMENT keyword at the beginning of an entry.
9770 @node Images and tables
9771 @section Images and Tables
9773 @cindex tables, markup rules
9776 Both the native Org mode tables (@pxref{Tables}) and tables formatted with
9777 the @file{table.el} package will be exported properly. For Org mode tables,
9778 the lines before the first horizontal separator line will become table header
9779 lines. You can use the following lines somewhere before the table to assign
9780 a caption and a label for cross references, and in the text you can refer to
9781 the object with @code{[[tab:basic-data]]} (@pxref{Internal links}):
9784 #+CAPTION: This is the caption for the next table (or link)
9785 #+NAME: tab:basic-data
9790 Optionally, the caption can take the form:
9792 #+CAPTION[Caption for list of tables]: Caption for table.
9795 @cindex inlined images, markup rules
9796 Some back-ends allow you to directly include images into the exported
9797 document. Org does this, if a link to an image files does not have
9798 a description part, for example @code{[[./img/a.jpg]]}. If you wish to
9799 define a caption for the image and maybe a label for internal cross
9800 references, make sure that the link is on a line by itself and precede it
9801 with @code{#+CAPTION} and @code{#+NAME} as follows:
9804 #+CAPTION: This is the caption for the next figure link (or table)
9805 #+NAME: fig:SED-HR4049
9810 Such images can be displayed within the buffer. @xref{Handling links,the
9811 discussion of image links}.
9813 Even though images and tables are prominent examples of captioned structures,
9814 the same caption mechanism can apply to many others (e.g., @LaTeX{}
9815 equations, source code blocks). Depending on the export back-end, those may
9816 or may not be handled.
9818 @node Literal examples
9819 @section Literal examples
9820 @cindex literal examples, markup rules
9821 @cindex code line references, markup rules
9823 You can include literal examples that should not be subjected to
9824 markup. Such examples will be typeset in monospace, so this is well suited
9825 for source code and similar examples.
9826 @cindex #+BEGIN_EXAMPLE
9830 Some example from a text file.
9834 Note that such blocks may be @i{indented} in order to align nicely with
9835 indented text and in particular with plain list structure (@pxref{Plain
9836 lists}). For simplicity when using small examples, you can also start the
9837 example lines with a colon followed by a space. There may also be additional
9838 whitespace before the colon:
9842 : Some example from a text file.
9845 @cindex formatting source code, markup rules
9846 If the example is source code from a programming language, or any other text
9847 that can be marked up by font-lock in Emacs, you can ask for the example to
9848 look like the fontified Emacs buffer@footnote{This works automatically for
9849 the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package,
9850 which is distributed with Org). Fontified code chunks in @LaTeX{} can be
9851 achieved using either the listings or the
9852 @url{http://code.google.com/p/minted, minted,} package. Refer to
9853 @code{org-latex-listings} documentation for details.}. This is done
9854 with the @samp{src} block, where you also need to specify the name of the
9855 major mode that should be used to fontify the example@footnote{Code in
9856 @samp{src} blocks may also be evaluated either interactively or on export.
9857 See @pxref{Working with source code} for more information on evaluating code
9858 blocks.}, see @ref{Easy templates} for shortcuts to easily insert code
9863 #+BEGIN_SRC emacs-lisp
9864 (defun org-xor (a b)
9870 Both in @code{example} and in @code{src} snippets, you can add a @code{-n}
9871 switch to the end of the @code{BEGIN} line, to get the lines of the example
9872 numbered. If you use a @code{+n} switch, the numbering from the previous
9873 numbered snippet will be continued in the current one. In literal examples,
9874 Org will interpret strings like @samp{(ref:name)} as labels, and use them as
9875 targets for special hyperlinks like @code{[[(name)]]} (i.e., the reference name
9876 enclosed in single parenthesis). In HTML, hovering the mouse over such a
9877 link will remote-highlight the corresponding code line, which is kind of
9880 You can also add a @code{-r} switch which @i{removes} the labels from the
9881 source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
9882 labels in the source code while using line numbers for the links, which might
9883 be useful to explain those in an Org mode example code.}. With the @code{-n}
9884 switch, links to these references will be labeled by the line numbers from
9885 the code listing, otherwise links will use the labels with no parentheses.
9889 #+BEGIN_SRC emacs-lisp -n -r
9890 (save-excursion (ref:sc)
9891 (goto-char (point-min))) (ref:jump)
9893 In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
9897 @vindex org-coderef-label-format
9898 If the syntax for the label format conflicts with the language syntax, use a
9899 @code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
9900 -n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}.
9902 HTML export also allows examples to be published as text areas (@pxref{Text
9903 areas in HTML export}).
9905 Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
9906 so often, shortcuts are provided using the Easy templates facility
9907 (@pxref{Easy templates}).
9912 Edit the source code example at point in its native mode. This works by
9913 switching to a temporary buffer with the source code. You need to exit by
9914 pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*},
9915 @samp{,*}, @samp{#+} and @samp{,#+} will get a comma prepended, to keep them
9916 from being interpreted by Org as outline nodes or special syntax. These
9917 commas will be stripped for editing with @kbd{C-c '}, and also for export.}.
9918 The edited version will then replace the old version in the Org buffer.
9919 Fixed-width regions (where each line starts with a colon followed by a space)
9920 will be edited using @code{artist-mode}@footnote{You may select
9921 a different-mode with the variable @code{org-edit-fixed-width-region-mode}.}
9922 to allow creating ASCII drawings easily. Using this command in an empty line
9923 will create a new fixed-width region.
9926 Calling @code{org-store-link} while editing a source code example in a
9927 temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure
9928 that it is unique in the current buffer, and insert it with the proper
9929 formatting like @samp{(ref:label)} at the end of the current line. Then the
9930 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
9935 @section Include files
9936 @cindex include files, markup rules
9938 During export, you can include the content of another file. For example, to
9939 include your @file{.emacs} file, you could use:
9943 #+INCLUDE: "~/.emacs" src emacs-lisp
9947 The optional second and third parameter are the markup (e.g., @samp{quote},
9948 @samp{example}, or @samp{src}), and, if the markup is @samp{src}, the
9949 language for formatting the contents. The markup is optional; if it is not
9950 given, the text will be assumed to be in Org mode format and will be
9953 Contents of the included file will belong to the same structure (headline,
9954 item) containing the @code{INCLUDE} keyword. In particular, headlines within
9955 the file will become children of the current section. That behavior can be
9956 changed by providing an additional keyword parameter, @code{:minlevel}. In
9957 that case, all headlines in the included file will be shifted so the one with
9958 the lowest level reaches that specified level. For example, to make a file
9959 become a sibling of the current top-level headline, use
9962 #+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
9965 You can also include a portion of a file by specifying a lines range using
9966 the @code{:lines} parameter. The line at the upper end of the range will not
9967 be included. The start and/or the end of the range may be omitted to use the
9971 #+INCLUDE: "~/.emacs" :lines "5-10" @r{Include lines 5 to 10, 10 excluded}
9972 #+INCLUDE: "~/.emacs" :lines "-10" @r{Include lines 1 to 10, 10 excluded}
9973 #+INCLUDE: "~/.emacs" :lines "10-" @r{Include lines from 10 to EOF}
9979 Visit the include file at point.
9983 @section Index entries
9984 @cindex index entries, for publishing
9986 You can specify entries that will be used for generating an index during
9987 publishing. This is done by lines starting with @code{#+INDEX}. An entry
9988 the contains an exclamation mark will create a sub item. See @ref{Generating
9989 an index} for more information.
9994 #+INDEX: Application!CV
10000 @node Macro replacement
10001 @section Macro replacement
10002 @cindex macro replacement, during export
10005 You can define text snippets with
10008 #+MACRO: name replacement text $1, $2 are arguments
10011 @noindent which can be referenced in
10012 paragraphs, verse blocks, table cells and some keywords with
10013 @code{@{@{@{name(arg1,arg2)@}@}@}}@footnote{Since commas separate arguments,
10014 commas within arguments have to be escaped with a backslash character.
10015 Conversely, backslash characters before a comma, and only them, need to be
10016 escaped with another backslash character.}. In addition to defined macros,
10017 @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc., will reference
10018 information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and similar lines.
10019 Also, @code{@{@{@{time(@var{FORMAT})@}@}@}} and
10020 @code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date time
10021 and to the modification time of the file being exported, respectively.
10022 @var{FORMAT} should be a format string understood by
10023 @code{format-time-string}.
10025 The surrounding brackets can be made invisible by setting
10026 @code{org-hide-macro-markers} to @code{t}.
10028 Macro expansion takes place during export.
10031 @node Embedded @LaTeX{}
10032 @section Embedded @LaTeX{}
10033 @cindex @TeX{} interpretation
10034 @cindex @LaTeX{} interpretation
10036 Plain ASCII is normally sufficient for almost all note taking. Exceptions
10037 include scientific notes, which often require mathematical symbols and the
10038 occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on
10039 Donald E. Knuth's @TeX{} system. Many of the features described here as
10040 ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
10041 distinction.} is widely used to typeset scientific documents. Org mode
10042 supports embedding @LaTeX{} code into its files, because many academics are
10043 used to writing and reading @LaTeX{} source code, and because it can be
10044 readily processed to produce pretty output for a number of export back-ends.
10047 * Special symbols:: Greek letters and other symbols
10048 * Subscripts and superscripts:: Simple syntax for raising/lowering text
10049 * @LaTeX{} fragments:: Complex formulas made easy
10050 * Previewing @LaTeX{} fragments:: What will this snippet look like?
10051 * CDLaTeX mode:: Speed up entering of formulas
10054 @node Special symbols
10055 @subsection Special symbols
10056 @cindex math symbols
10057 @cindex special symbols
10058 @cindex @TeX{} macros
10059 @cindex @LaTeX{} fragments, markup rules
10060 @cindex HTML entities
10061 @cindex @LaTeX{} entities
10063 You can use @LaTeX{}-like syntax to insert special symbols like @samp{\alpha}
10064 to indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion
10065 for these symbols is available, just type @samp{\} and maybe a few letters,
10066 and press @kbd{M-@key{TAB}} to see possible completions. Unlike @LaTeX{}
10067 code, Org mode allows these symbols to be present without surrounding math
10068 delimiters, for example:
10071 Angles are written as Greek letters \alpha, \beta and \gamma.
10074 @vindex org-entities
10075 During export, these symbols will be transformed into the native format of
10076 the exporter back-end. Strings like @code{\alpha} will be exported as
10077 @code{α} in the HTML output, and as @code{$\alpha$} in the @LaTeX{}
10078 output. Similarly, @code{\nbsp} will become @code{ } in HTML and
10079 @code{~} in @LaTeX{}. If you need such a symbol inside a word, terminate it
10080 like this: @samp{\Aacute@{@}stor}.
10082 A large number of entities is provided, with names taken from both HTML and
10083 @LaTeX{}; see the variable @code{org-entities} for the complete list.
10084 @samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and
10085 @samp{...} are all converted into special commands creating hyphens of
10086 different lengths or a compact set of dots.
10088 If you would like to see entities displayed as UTF-8 characters, use the
10089 following command@footnote{You can turn this on by default by setting the
10090 variable @code{org-pretty-entities}, or on a per-file base with the
10091 @code{#+STARTUP} option @code{entitiespretty}.}:
10094 @cindex @code{entitiespretty}, STARTUP keyword
10097 Toggle display of entities as UTF-8 characters. This does not change the
10098 buffer content which remains plain ASCII, but it overlays the UTF-8 character
10099 for display purposes only.
10102 @node Subscripts and superscripts
10103 @subsection Subscripts and superscripts
10105 @cindex superscript
10107 Just like in @LaTeX{}, @samp{^} and @samp{_} are used to indicate super- and
10108 subscripts. Again, these can be used without embedding them in math-mode
10109 delimiters. To increase the readability of ASCII text, it is not necessary
10110 (but OK) to surround multi-character sub- and superscripts with curly braces.
10114 The mass of the sun is M_sun = 1.989 x 10^30 kg. The radius of
10115 the sun is R_@{sun@} = 6.96 x 10^8 m.
10118 @vindex org-use-sub-superscripts
10119 If you write a text where the underscore is often used in a different
10120 context, Org's convention to always interpret these as subscripts can get in
10121 your way. Configure the variable @code{org-use-sub-superscripts} to change
10122 this convention. For example, when setting this variable to @code{@{@}},
10123 @samp{a_b} will not be interpreted as a subscript, but @samp{a_@{b@}} will.
10128 In addition to showing entities as UTF-8 characters, this command will also
10129 format sub- and superscripts in a WYSIWYM way.
10132 @node @LaTeX{} fragments
10133 @subsection @LaTeX{} fragments
10134 @cindex @LaTeX{} fragments
10136 @vindex org-format-latex-header
10137 Going beyond symbols and sub- and superscripts, a full formula language is
10138 needed. Org mode can contain @LaTeX{} math fragments, and it supports ways
10139 to process these for several export back-ends. When exporting to @LaTeX{},
10140 the code is obviously left as it is. When exporting to HTML, Org invokes the
10141 @uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in
10142 HTML export}) to process and display the math@footnote{If you plan to use
10143 this regularly or on pages with significant page views, you should install
10144 @file{MathJax} on your own server in order to limit the load of our server.}.
10145 Finally, it can also process the mathematical expressions into
10146 images@footnote{For this to work you need to be on a system with a working
10147 @LaTeX{} installation. You also need the @file{dvipng} program or the
10148 @file{convert}, respectively available at
10149 @url{http://sourceforge.net/projects/dvipng/} and from the @file{imagemagick}
10150 suite. The @LaTeX{} header that will be used when processing a fragment can
10151 be configured with the variable @code{org-format-latex-header}.} that can be
10152 displayed in a browser.
10154 @LaTeX{} fragments don't need any special marking at all. The following
10155 snippets will be identified as @LaTeX{} source code:
10158 Environments of any kind@footnote{When @file{MathJax} is used, only the
10159 environments recognized by @file{MathJax} will be processed. When
10160 @file{dvipng} program or @file{imagemagick} suite is used to create images,
10161 any @LaTeX{} environment will be handled.}. The only requirement is that the
10162 @code{\begin} and @code{\end} statements appear on a new line, at the
10163 beginning of the line or after whitespaces only.
10165 Text within the usual @LaTeX{} math delimiters. To avoid conflicts with
10166 currency specifications, single @samp{$} characters are only recognized as
10167 math delimiters if the enclosed text contains at most two line breaks, is
10168 directly attached to the @samp{$} characters with no whitespace in between,
10169 and if the closing @samp{$} is followed by whitespace, punctuation or a dash.
10170 For the other delimiters, there is no such restriction, so when in doubt, use
10171 @samp{\(...\)} as inline math delimiters.
10174 @noindent For example:
10181 If $a^2=b$ and \( b=2 \), then the solution must be
10182 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
10187 @c @vindex org-format-latex-options
10188 @c If you need any of the delimiter ASCII sequences for other purposes, you
10189 @c can configure the option @code{org-format-latex-options} to deselect the
10190 @c ones you do not wish to have interpreted by the @LaTeX{} converter.
10192 @vindex org-export-with-latex
10193 @LaTeX{} processing can be configured with the variable
10194 @code{org-export-with-latex}. The default setting is @code{t} which means
10195 @file{MathJax} for HTML, and no processing for ASCII and @LaTeX{} back-ends.
10196 You can also set this variable on a per-file basis using one of these
10200 #+OPTIONS: tex:t @r{Do the right thing automatically (MathJax)}
10201 #+OPTIONS: tex:nil @r{Do not process @LaTeX{} fragments at all}
10202 #+OPTIONS: tex:verbatim @r{Verbatim export, for jsMath or so}
10205 @node Previewing @LaTeX{} fragments
10206 @subsection Previewing @LaTeX{} fragments
10207 @cindex @LaTeX{} fragments, preview
10209 @vindex org-latex-create-formula-image-program
10210 If you have @file{dvipng} or @file{imagemagick} installed@footnote{Choose the
10211 converter by setting the variable
10212 @code{org-latex-create-formula-image-program} accordingly.}, @LaTeX{}
10213 fragments can be processed to produce preview images of the typeset
10217 @kindex C-c C-x C-l
10219 Produce a preview image of the @LaTeX{} fragment at point and overlay it
10220 over the source code. If there is no fragment at point, process all
10221 fragments in the current entry (between two headlines). When called
10222 with a prefix argument, process the entire subtree. When called with
10223 two prefix arguments, or when the cursor is before the first headline,
10224 process the entire buffer.
10227 Remove the overlay preview images.
10230 @vindex org-format-latex-options
10231 You can customize the variable @code{org-format-latex-options} to influence
10232 some aspects of the preview. In particular, the @code{:scale} (and for HTML
10233 export, @code{:html-scale}) property can be used to adjust the size of the
10236 @vindex org-startup-with-latex-preview
10237 You can turn on the previewing of all @LaTeX{} fragments in a file with
10240 #+STARTUP: latexpreview
10243 To disable it, simply use
10246 #+STARTUP: nolatexpreview
10250 @subsection Using CD@LaTeX{} to enter math
10253 CD@LaTeX{} mode is a minor mode that is normally used in combination with a
10254 major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
10255 environments and math templates. Inside Org mode, you can make use of
10256 some of the features of CD@LaTeX{} mode. You need to install
10257 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
10258 AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
10259 Don't use CD@LaTeX{} mode itself under Org mode, but use the light
10260 version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it
10261 on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all
10265 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
10268 When this mode is enabled, the following features are present (for more
10269 details see the documentation of CD@LaTeX{} mode):
10273 Environment templates can be inserted with @kbd{C-c @{}.
10276 The @key{TAB} key will do template expansion if the cursor is inside a
10277 @LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is
10278 inside such a fragment, see the documentation of the function
10279 @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
10280 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
10281 correctly inside the first brace. Another @key{TAB} will get you into
10282 the second brace. Even outside fragments, @key{TAB} will expand
10283 environment abbreviations at the beginning of a line. For example, if
10284 you write @samp{equ} at the beginning of a line and press @key{TAB},
10285 this abbreviation will be expanded to an @code{equation} environment.
10286 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help RET}.
10290 @vindex cdlatex-simplify-sub-super-scripts
10291 Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these
10292 characters together with a pair of braces. If you use @key{TAB} to move
10293 out of the braces, and if the braces surround only a single character or
10294 macro, they are removed again (depending on the variable
10295 @code{cdlatex-simplify-sub-super-scripts}).
10298 Pressing the backquote @kbd{`} followed by a character inserts math
10299 macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds
10300 after the backquote, a help window will pop up.
10303 Pressing the single-quote @kbd{'} followed by another character modifies
10304 the symbol before point with an accent or a font. If you wait more than
10305 1.5 seconds after the single-quote, a help window will pop up. Character
10306 modification will work only inside @LaTeX{} fragments; outside the quote
10310 @node Special blocks
10311 @section Special blocks
10312 @cindex Special blocks
10314 Org syntax includes pre-defined blocks (@pxref{Paragraphs} and @ref{Literal
10315 examples}). It is also possible to create blocks containing raw code
10316 targeted at a specific back-end (e.g., @samp{#+BEGIN_LATEX}).
10318 Any other block is a @emph{special block}.
10320 For example, @samp{#+BEGIN_ABSTRACT} and @samp{#+BEGIN_VIDEO} are special
10321 blocks. The first one is useful when exporting to @LaTeX{}, the second one
10322 when exporting to HTML5.
10324 Each export back-end decides if they should be exported, and how. When the
10325 block is ignored, its contents are still exported, as if the opening and
10326 closing block lines were not there. For example, when exporting a
10327 @samp{#+BEGIN_TEST} block, HTML back-end wraps its contents within a
10328 @samp{<div name="test">} tag.
10330 Refer to back-end specific documentation for more information.
10336 The Org mode export facilities can be used to export Org documents or parts
10337 of Org documents to a variety of other formats. In addition, these
10338 facilities can be used with @code{orgtbl-mode} and/or @code{orgstruct-mode}
10339 in foreign buffers so you can author tables and lists in Org syntax and
10340 convert them in place to the target language.
10342 ASCII export produces a readable and simple version of an Org file for
10343 printing and sharing notes. HTML export allows you to easily publish notes
10344 on the web, or to build full-fledged websites. @LaTeX{} export lets you use
10345 Org mode and its structured editing functions to create arbitrarily complex
10346 @LaTeX{} files for any kind of document. OpenDocument Text (ODT) export
10347 allows seamless collaboration across organizational boundaries. Markdown
10348 export lets you seamlessly collaborate with other developers. Finally, iCal
10349 export can extract entries with deadlines or appointments to produce a file
10350 in the iCalendar format.
10353 * The export dispatcher:: The main exporter interface
10354 * Export back-ends:: Built-in export formats
10355 * Export settings:: Generic export settings
10356 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
10357 * Beamer export:: Exporting as a Beamer presentation
10358 * HTML export:: Exporting to HTML
10359 * @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
10360 * Markdown export:: Exporting to Markdown
10361 * OpenDocument text export:: Exporting to OpenDocument Text
10362 * Org export:: Exporting to Org
10363 * iCalendar export:: Exporting to iCalendar
10364 * Other built-in back-ends:: Exporting to @code{Texinfo} or a man page
10365 * Export in foreign buffers:: Author tables and lists in Org syntax
10366 * Advanced configuration:: Fine-tuning the export output
10369 @node The export dispatcher
10370 @section The export dispatcher
10371 @vindex org-export-dispatch-use-expert-ui
10372 @cindex Export, dispatcher
10374 The main entry point for export related tasks is the dispatcher, a
10375 hierarchical menu from which it is possible to select an export format and
10376 toggle export options@footnote{It is also possible to use a less intrusive
10377 interface by setting @code{org-export-dispatch-use-expert-ui} to a
10378 non-@code{nil} value. In that case, only a prompt is visible from the
10379 minibuffer. From there one can still switch back to regular menu by pressing
10380 @key{?}.} from which it is possible to select an export format and to toggle
10385 @orgcmd{C-c C-e,org-export-dispatch}
10387 Dispatch for export and publishing commands. When called with a @kbd{C-u}
10388 prefix argument, repeat the last export command on the current buffer while
10389 preserving toggled options. If the current buffer hasn't changed and subtree
10390 export was activated, the command will affect that same subtree.
10394 Normally the entire buffer is exported, but if there is an active region
10395 only that part of the buffer will be exported.
10397 Several export options (@pxref{Export settings}) can be toggled from the
10398 export dispatcher with the following key combinations:
10402 @vindex org-export-async-init-file
10403 Toggle asynchronous export. Asynchronous export uses an external Emacs
10404 process that is configured with a specified initialization file.
10406 While exporting asynchronously, the output is not displayed. It is stored in
10407 a list called ``the export stack'', and can be viewed from there. The stack
10408 can be reached by calling the dispatcher with a double @kbd{C-u} prefix
10409 argument, or with @kbd{&} key from the dispatcher.
10411 @vindex org-export-in-background
10412 To make this behavior the default, customize the variable
10413 @code{org-export-in-background}.
10416 Toggle body-only export. Its effect depends on the back-end used.
10417 Typically, if the back-end has a header section (like @code{<head>...</head>}
10418 in the HTML back-end), a body-only export will not include this header.
10421 @vindex org-export-initial-scope
10422 Toggle subtree export. The top heading becomes the document title.
10424 You can change the default state of this option by setting
10425 @code{org-export-initial-scope}.
10428 Toggle visible-only export. Only export the text that is currently
10429 visible, i.e. not hidden by outline visibility in the buffer.
10433 @vindex org-export-copy-to-kill-ring
10434 With the exception of asynchronous export, a successful export process writes
10435 its output to the kill-ring. You can configure this behavior by altering the
10436 option @code{org-export-copy-to-kill-ring}.
10438 @node Export back-ends
10439 @section Export back-ends
10440 @cindex Export, back-ends
10442 An export back-end is a library that translates Org syntax into a foreign
10443 format. An export format is not available until the proper back-end has been
10446 @vindex org-export-backends
10447 By default, the following four back-ends are loaded: @code{ascii},
10448 @code{html}, @code{icalendar} and @code{latex}. It is possible to add more
10449 (or remove some) by customizing @code{org-export-backends}.
10451 Built-in back-ends include:
10454 @item ascii (ASCII format)
10455 @item beamer (@LaTeX{} Beamer format)
10456 @item html (HTML format)
10457 @item icalendar (iCalendar format)
10458 @item latex (@LaTeX{} format)
10459 @item man (Man page format)
10460 @item md (Markdown format)
10461 @item odt (OpenDocument Text format)
10462 @item org (Org format)
10463 @item texinfo (Texinfo format)
10466 Other back-ends might be found in the @code{contrib/} directory
10467 (@pxref{Installation}).
10469 @node Export settings
10470 @section Export settings
10471 @cindex Export, settings
10474 Export options can be set: globally with variables; for an individual file by
10475 making variables buffer-local with in-buffer settings (@pxref{In-buffer
10476 settings}), by setting individual keywords, or by specifying them in a
10477 compact form with the @code{#+OPTIONS} keyword; or for a tree by setting
10478 properties (@pxref{Properties and columns}). Options set at a specific level
10479 override options set at a more general level.
10481 @cindex #+SETUPFILE
10482 In-buffer settings may appear anywhere in the file, either directly or
10483 indirectly through a file included using @samp{#+SETUPFILE: filename} syntax.
10484 Option keyword sets tailored to a particular back-end can be inserted from
10485 the export dispatcher (@pxref{The export dispatcher}) using the @code{Insert
10486 template} command by pressing @key{#}. To insert keywords individually,
10487 a good way to make sure the keyword is correct is to type @code{#+} and then
10488 to use @kbd{M-<TAB>} for completion.
10490 The export keywords available for every back-end, and their equivalent global
10491 variables, include:
10496 @vindex user-full-name
10497 The document author (@code{user-full-name}).
10501 @vindex org-export-creator-string
10502 Entity responsible for output generation (@code{org-export-creator-string}).
10506 @vindex org-export-date-timestamp-format
10507 A date or a time-stamp@footnote{The variable
10508 @code{org-export-date-timestamp-format} defines how this time-stamp will be
10512 @cindex #+DESCRIPTION
10513 The document description. Back-ends handle it as they see fit (e.g., for the
10514 XHTML meta tag), if at all. You can use several such keywords for long
10519 @vindex user-mail-address
10520 The email address (@code{user-mail-address}).
10524 The keywords defining the contents of the document. Back-ends handle it as
10525 they see fit (e.g., for the XHTML meta tag), if at all. You can use several
10526 such keywords if the list is long.
10530 @vindex org-export-default-language
10531 The language used for translating some strings
10532 (@code{org-export-default-language}). E.g., @samp{#+LANGUAGE: fr} will tell
10533 Org to translate @emph{File} (english) into @emph{Fichier} (french) in the
10537 @cindex #+SELECT_TAGS
10538 @vindex org-export-select-tags
10539 The tags that select a tree for export (@code{org-export-select-tags}). The
10540 default value is @code{:export:}. Within a subtree tagged with
10541 @code{:export:}, you can still exclude entries with @code{:noexport:} (see
10542 below). When headlines are selectively exported with @code{:export:}
10543 anywhere in a file, text before the first headline is ignored.
10546 @cindex #+EXCLUDE_TAGS
10547 @vindex org-export-exclude-tags
10548 The tags that exclude a tree from export (@code{org-export-exclude-tags}).
10549 The default value is @code{:noexport:}. Entries with the @code{:noexport:}
10550 tag will be unconditionally excluded from the export, even if they have an
10551 @code{:export:} tag.
10555 The title to be shown (otherwise derived from buffer's name). You can use
10556 several such keywords for long titles.
10559 The @code{#+OPTIONS} keyword is a compact@footnote{If you want to configure
10560 many options this way, you can use several @code{#+OPTIONS} lines.} form that
10561 recognizes the following arguments:
10565 @vindex org-export-with-smart-quotes
10566 Toggle smart quotes (@code{org-export-with-smart-quotes}).
10569 Toggle emphasized text (@code{org-export-with-emphasize}).
10572 @vindex org-export-with-special-strings
10573 Toggle conversion of special strings
10574 (@code{org-export-with-special-strings}).
10577 @vindex org-export-with-fixed-width
10578 Toggle fixed-width sections
10579 (@code{org-export-with-fixed-width}).
10582 @vindex org-export-with-timestamps
10583 Toggle inclusion of any time/date active/inactive stamps
10584 (@code{org-export-with-timestamps}).
10587 @vindex org-export-preserve-breaks
10588 Toggle line-break-preservation (@code{org-export-preserve-breaks}).
10591 @vindex org-export-with-sub-superscripts
10592 Toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}",
10593 @samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as
10594 it is (@code{org-export-with-sub-superscripts}).
10597 @vindex org-export-with-archived-trees
10598 Configure export of archived trees. Can be set to @code{headline} to only
10599 process the headline, skipping its contents
10600 (@code{org-export-with-archived-trees}).
10603 @vindex org-export-with-author
10604 Toggle inclusion of author name into exported file
10605 (@code{org-export-with-author}).
10608 @vindex org-export-with-clocks
10609 Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}).
10612 @vindex org-export-with-creator
10613 Configure inclusion of creator info into exported file. It may be set to
10614 @code{comment} (@code{org-export-with-creator}).
10617 @vindex org-export-with-drawers
10618 Toggle inclusion of drawers, or list drawers to include
10619 (@code{org-export-with-drawers}).
10622 @vindex org-export-with-entities
10623 Toggle inclusion of entities (@code{org-export-with-entities}).
10626 @vindex org-export-with-email
10627 Toggle inclusion of the author's e-mail into exported file
10628 (@code{org-export-with-email}).
10631 @vindex org-export-with-footnotes
10632 Toggle the inclusion of footnotes (@code{org-export-with-footnotes}).
10635 @vindex org-export-headline-levels
10636 Set the number of headline levels for export
10637 (@code{org-export-headline-levels}). Below that level, headlines are treated
10638 differently. In most back-ends, they become list items.
10641 @vindex org-export-with-inlinetasks
10642 Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
10645 @vindex org-export-with-section-numbers
10646 Toggle section-numbers (@code{org-export-with-section-numbers}). It can also
10647 be set to a number @samp{n}, so only headlines at that level or above will be
10651 @vindex org-export-with-planning
10652 Toggle export of planning information (@code{org-export-with-planning}).
10653 ``Planning information'' is the line containing the @code{SCHEDULED:}, the
10654 @code{DEADLINE:} or the @code{CLOSED:} cookies or a combination of them.
10657 @vindex org-export-with-priority
10658 Toggle inclusion of priority cookies (@code{org-export-with-priority}).
10661 @vindex org-export-with-properties
10662 Toggle inclusion of property drawers, or list properties to include
10663 (@code{org-export-with-properties}).
10666 @vindex org-export-with-statistics-cookies
10667 Toggle inclusion of statistics cookies
10668 (@code{org-export-with-statistics-cookies}).
10671 @vindex org-export-with-tags
10672 Toggle inclusion of tags, may also be @code{not-in-toc}
10673 (@code{org-export-with-tags}).
10676 @vindex org-export-with-tasks
10677 Toggle inclusion of tasks (TODO items), can be @code{nil} to remove all
10678 tasks, @code{todo} to remove DONE tasks, or a list of keywords to keep
10679 (@code{org-export-with-tasks}).
10682 @vindex org-export-with-latex
10683 Configure export of @LaTeX{} fragments and environments. It may be set to
10684 @code{verbatim} (@code{org-export-with-latex}).
10687 @vindex org-export-time-stamp-file
10688 Toggle inclusion of the creation time into exported file
10689 (@code{org-export-time-stamp-file}).
10692 @vindex org-export-with-toc
10693 Toggle inclusion of the table of contents, or set the level limit
10694 (@code{org-export-with-toc}).
10697 @vindex org-export-with-todo-keywords
10698 Toggle inclusion of TODO keywords into exported text
10699 (@code{org-export-with-todo-keywords}).
10702 @vindex org-export-with-tables
10703 Toggle inclusion of tables (@code{org-export-with-tables}).
10706 @cindex property, EXPORT_FILE_NAME
10707 When exporting only a subtree, each of the previous keywords@footnote{With
10708 the exception of @samp{SETUPFILE}.} can be overridden locally by special node
10709 properties. These begin with @samp{EXPORT_}, followed by the name of the
10710 keyword they supplant. For example, @samp{DATE} and @samp{OPTIONS} keywords
10711 become, respectively, @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS}
10712 properties. Subtree export also supports the self-explicit
10713 @samp{EXPORT_FILE_NAME} property@footnote{There is no buffer-wide equivalent
10714 for this property. The file name in this case is derived from the file
10715 associated to the buffer, if possible, or asked to the user otherwise.}.
10718 @vindex org-export-allow-bind-keywords
10719 If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables
10720 can become buffer-local during export by using the BIND keyword. Its syntax
10721 is @samp{#+BIND: variable value}. This is particularly useful for in-buffer
10722 settings that cannot be changed using specific keywords.
10724 @node ASCII/Latin-1/UTF-8 export
10725 @section ASCII/Latin-1/UTF-8 export
10726 @cindex ASCII export
10727 @cindex Latin-1 export
10728 @cindex UTF-8 export
10730 ASCII export produces a simple and very readable version of an Org mode
10731 file, containing only plain ASCII@. Latin-1 and UTF-8 export augment the file
10732 with special characters and symbols available in these encodings.
10734 @vindex org-ascii-links-to-notes
10735 Links are exported in a footnote-like style, with the descriptive part in the
10736 text and the link in a note before the next heading. See the variable
10737 @code{org-ascii-links-to-notes} for details and other options.
10739 @subheading ASCII export commands
10742 @orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii}
10743 Export as an ASCII file. For an Org file, @file{myfile.org}, the ASCII file
10744 will be @file{myfile.txt}. The file will be overwritten without warning.
10745 When the original file is @file{myfile.txt}, the resulting file becomes
10746 @file{myfile.txt.txt} in order to prevent data loss.
10747 @orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii}
10748 Export to a temporary buffer. Do not create a file.
10751 @subheading Header and sectioning structure
10753 In the exported version, the first three outline levels become headlines,
10754 defining a general document structure. Additional levels are exported as
10755 lists. The transition can also occur at a different level (@pxref{Export
10758 @subheading Quoting ASCII text
10760 You can insert text that will only appear when using @code{ASCII} back-end
10761 with the following constructs:
10764 @cindex #+BEGIN_ASCII
10766 Text @@@@ascii:and additional text@@@@ within a paragraph.
10771 All lines in this block will appear only when using this back-end.
10775 @subheading ASCII specific attributes
10776 @cindex #+ATTR_ASCII
10777 @cindex horizontal rules, in ASCII export
10779 @code{ASCII} back-end only understands one attribute, @code{:width}, which
10780 specifies the length, in characters, of a given horizontal rule. It must be
10781 specified using an @code{ATTR_ASCII} line, directly preceding the rule.
10784 #+ATTR_ASCII: :width 10
10788 @node Beamer export
10789 @section Beamer export
10790 @cindex Beamer export
10792 The @LaTeX{} class @emph{Beamer} allows production of high quality
10793 presentations using @LaTeX{} and pdf processing. Org mode has special
10794 support for turning an Org mode file or tree into a Beamer presentation.
10796 @subheading Beamer export commands
10799 @orgcmd{C-c C-e l b,org-beamer-export-to-latex}
10800 Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{}
10801 file will be @file{myfile.tex}. The file will be overwritten without
10803 @orgcmd{C-c C-e l B,org-beamer-export-as-latex}
10804 Export to a temporary buffer. Do not create a file.
10805 @orgcmd{C-c C-e l P,org-beamer-export-to-pdf}
10806 Export as @LaTeX{} and then process to PDF.
10808 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
10811 @subheading Sectioning, Frames and Blocks
10813 Any tree with not-too-deep level nesting should in principle be exportable as
10814 a Beamer presentation. Headlines fall into three categories: sectioning
10815 elements, frames and blocks.
10819 @vindex org-beamer-frame-level
10820 Headlines become frames when their level is equal to
10821 @code{org-beamer-frame-level} or @code{H} value in an @code{OPTIONS} line
10822 (@pxref{Export settings}).
10824 @cindex property, BEAMER_ENV
10825 Though, if a headline in the current tree has a @code{BEAMER_ENV} property
10826 set to either to @code{frame} or @code{fullframe}, its level overrides the
10827 variable. A @code{fullframe} is a frame with an empty (ignored) title.
10830 @vindex org-beamer-environments-default
10831 @vindex org-beamer-environments-extra
10832 All frame's children become @code{block} environments. Special block types
10833 can be enforced by setting headline's @code{BEAMER_ENV} property@footnote{If
10834 this property is set, the entry will also get a @code{:B_environment:} tag to
10835 make this visible. This tag has no semantic meaning, it is only a visual
10836 aid.} to an appropriate value (see @code{org-beamer-environments-default} for
10837 supported values and @code{org-beamer-environments-extra} for adding more).
10840 @cindex property, BEAMER_REF
10841 As a special case, if the @code{BEAMER_ENV} property is set to either
10842 @code{appendix}, @code{note}, @code{noteNH} or @code{againframe}, the
10843 headline will become, respectively, an appendix, a note (within frame or
10844 between frame, depending on its level), a note with its title ignored or an
10845 @code{\againframe} command. In the latter case, a @code{BEAMER_REF} property
10846 is mandatory in order to refer to the frame being resumed, and contents are
10849 Also, a headline with an @code{ignoreheading} environment will have its
10850 contents only inserted in the output. This special value is useful to have
10851 data between frames, or to properly close a @code{column} environment.
10854 @cindex property, BEAMER_ACT
10855 @cindex property, BEAMER_OPT
10856 Headlines also support @code{BEAMER_ACT} and @code{BEAMER_OPT} properties.
10857 The former is translated as an overlay/action specification, or a default
10858 overlay specification when enclosed within square brackets. The latter
10859 specifies options@footnote{The @code{fragile} option is added automatically
10860 if it contains code that requires a verbatim environment, though.} for the
10861 current frame or block. The export back-end will automatically wrap
10862 properties within angular or square brackets when appropriate.
10864 @cindex property, BEAMER_COL
10865 Moreover, headlines handle the @code{BEAMER_COL} property. Its value should
10866 be a decimal number representing the width of the column as a fraction of the
10867 total text width. If the headline has no specific environment, its title
10868 will be ignored and its contents will fill the column created. Otherwise,
10869 the block will fill the whole column and the title will be preserved. Two
10870 contiguous headlines with a non-@code{nil} @code{BEAMER_COL} value share the same
10871 @code{columns} @LaTeX{} environment. It will end before the next headline
10872 without such a property. This environment is generated automatically.
10873 Although, it can also be explicitly created, with a special @code{columns}
10874 value for @code{BEAMER_ENV} property (if it needs to be set up with some
10875 specific options, for example).
10877 @subheading Beamer specific syntax
10879 Beamer back-end is an extension of @LaTeX{} back-end. As such, all @LaTeX{}
10880 specific syntax (e.g., @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}) is
10881 recognized. See @ref{@LaTeX{} and PDF export} for more information.
10883 @cindex #+BEAMER_THEME
10884 @cindex #+BEAMER_COLOR_THEME
10885 @cindex #+BEAMER_FONT_THEME
10886 @cindex #+BEAMER_INNER_THEME
10887 @cindex #+BEAMER_OUTER_THEME
10888 Beamer export introduces a number of keywords to insert code in the
10889 document's header. Four control appearance of the presentation:
10890 @code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME},
10891 @code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and
10892 @code{#+BEAMER_OUTER_THEME}. All of them accept optional arguments
10893 within square brackets. The last one, @code{#+BEAMER_HEADER}, is more
10894 generic and allows you to append any line of code in the header.
10897 #+BEAMER_THEME: Rochester [height=20pt]
10898 #+BEAMER_COLOR_THEME: spruce
10901 Table of contents generated from @code{toc:t} @code{OPTION} keyword are
10902 wrapped within a @code{frame} environment. Those generated from a @code{TOC}
10903 keyword (@pxref{Table of contents}) are not. In that case, it is also
10904 possible to specify options, enclosed within square brackets.
10907 #+TOC: headlines [currentsection]
10910 Beamer specific code can be inserted with the following constructs:
10913 @cindex #+BEGIN_BEAMER
10918 All lines in this block will appear only when using this back-end.
10921 Text @@@@beamer:some code@@@@ within a paragraph.
10924 In particular, this last example can be used to add overlay specifications to
10925 objects whose type is among @code{bold}, @code{item}, @code{link},
10926 @code{radio-target} and @code{target}, when the value is enclosed within
10927 angular brackets and put at the beginning the object.
10930 A *@@@@beamer:<2->@@@@useful* feature
10933 @cindex #+ATTR_BEAMER
10934 Eventually, every plain list has support for @code{:environment},
10935 @code{:overlay} and @code{:options} attributes through
10936 @code{ATTR_BEAMER} affiliated keyword. The first one allows the use
10937 of a different environment, the second sets overlay specifications and
10938 the last one inserts optional arguments in current list environment.
10941 #+ATTR_BEAMER: :overlay +-
10946 @subheading Editing support
10948 You can turn on a special minor mode @code{org-beamer-mode} for faster
10956 @orgcmd{C-c C-b,org-beamer-select-environment}
10957 In @code{org-beamer-mode}, this key offers fast selection of a Beamer
10958 environment or the @code{BEAMER_COL} property.
10961 Also, a template for useful in-buffer settings or properties can be inserted
10962 into the buffer with @kbd{M-x org-beamer-insert-options-template}. Among
10963 other things, this will install a column view format which is very handy for
10964 editing special properties used by Beamer.
10966 @subheading An example
10968 Here is a simple example Org document that is intended for Beamer export.
10971 #+TITLE: Example Presentation
10972 #+AUTHOR: Carsten Dominik
10974 #+LATEX_CLASS: beamer
10975 #+LATEX_CLASS_OPTIONS: [presentation]
10976 #+BEAMER_THEME: Madrid
10977 #+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) %8BEAMER_OPT(Opt)
10979 * This is the first structural section
10982 *** Thanks to Eric Fraga :B_block:BMCOL:
10987 for the first viable Beamer setup in Org
10988 *** Thanks to everyone else :B_block:BMCOL:
10994 for contributing to the discussion
10995 **** This will be formatted as a beamer note :B_note:
10999 ** Frame 2 (where we will not use columns)
11001 Please test this stuff!
11005 @section HTML export
11006 @cindex HTML export
11008 Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive
11009 HTML formatting, in ways similar to John Gruber's @emph{markdown}
11010 language, but with additional support for tables.
11013 * HTML Export commands:: How to invoke HTML export
11014 * HTML doctypes:: Org can export to various (X)HTML flavors
11015 * HTML preamble and postamble:: How to insert a preamble and a postamble
11016 * Quoting HTML tags:: Using direct HTML in Org mode
11017 * Links in HTML export:: How links will be interpreted and formatted
11018 * Tables in HTML export:: How to modify the formatting of tables
11019 * Images in HTML export:: How to insert figures into HTML output
11020 * Math formatting in HTML export:: Beautiful math also on the web
11021 * Text areas in HTML export:: An alternative way to show an example
11022 * CSS support:: Changing the appearance of the output
11023 * JavaScript support:: Info and Folding in a web browser
11026 @node HTML Export commands
11027 @subsection HTML export commands
11030 @orgcmd{C-c C-e h h,org-html-export-to-html}
11031 Export as an HTML file. For an Org file @file{myfile.org},
11032 the HTML file will be @file{myfile.html}. The file will be overwritten
11035 Export as an HTML file and immediately open it with a browser.
11036 @orgcmd{C-c C-e h H,org-html-export-as-html}
11037 Export to a temporary buffer. Do not create a file.
11040 @c FIXME Exporting sublevels
11041 @c @cindex headline levels, for exporting
11042 @c In the exported version, the first 3 outline levels will become headlines,
11043 @c defining a general document structure. Additional levels will be exported as
11044 @c itemized lists. If you want that transition to occur at a different level,
11045 @c specify it with a numeric prefix argument. For example,
11048 @c @kbd{C-2 C-c C-e b}
11052 @c creates two levels of headings and does the rest as items.
11054 @node HTML doctypes
11055 @subsection HTML doctypes
11056 @vindex org-html-doctype
11057 @vindex org-html-doctype-alist
11059 Org can export to various (X)HTML flavors.
11061 Setting the variable @code{org-html-doctype} allows you to export to different
11062 (X)HTML variants. The exported HTML will be adjusted according to the syntax
11063 requirements of that variant. You can either set this variable to a doctype
11064 string directly, in which case the exporter will try to adjust the syntax
11065 automatically, or you can use a ready-made doctype. The ready-made options
11072 ``html4-transitional''
11078 ``xhtml-transitional''
11089 See the variable @code{org-html-doctype-alist} for details. The default is
11092 @subsubheading Fancy HTML5 export
11093 @vindex org-html-html5-fancy
11094 @vindex org-html-html5-elements
11096 HTML5 introduces several new element types. By default, Org will not make
11097 use of these element types, but you can set @code{org-html-html5-fancy} to
11098 @code{t} (or set @code{html5-fancy} item in an @code{OPTIONS} line), to
11099 enable a few new block-level elements. These are created using arbitrary
11100 #+BEGIN and #+END blocks. For instance:
11119 #+ATTR_HTML: :controls controls :width 350
11121 #+HTML: <source src="movie.mp4" type="video/mp4">
11122 #+HTML: <source src="movie.ogg" type="video/ogg">
11123 Your browser does not support the video tag.
11130 <video controls="controls" width="350">
11131 <source src="movie.mp4" type="video/mp4">
11132 <source src="movie.ogg" type="video/ogg">
11133 <p>Your browser does not support the video tag.</p>
11137 Special blocks that do not correspond to HTML5 elements (see
11138 @code{org-html-html5-elements}) will revert to the usual behavior, i.e.,
11139 @code{#+BEGIN_LEDERHOSEN} will still export to @samp{<div class="lederhosen">}.
11141 Headlines cannot appear within special blocks. To wrap a headline and its
11142 contents in e.g., @samp{<section>} or @samp{<article>} tags, set the
11143 @code{HTML_CONTAINER} property on the headline itself.
11145 @node HTML preamble and postamble
11146 @subsection HTML preamble and postamble
11147 @vindex org-html-preamble
11148 @vindex org-html-postamble
11149 @vindex org-html-preamble-format
11150 @vindex org-html-postamble-format
11151 @vindex org-html-validation-link
11152 @vindex org-export-creator-string
11153 @vindex org-export-time-stamp-file
11155 The HTML exporter lets you define a preamble and a postamble.
11157 The default value for @code{org-html-preamble} is @code{t}, which means
11158 that the preamble is inserted depending on the relevant format string in
11159 @code{org-html-preamble-format}.
11161 Setting @code{org-html-preamble} to a string will override the default format
11162 string. If you set it to a function, it will insert the output of the
11163 function, which must be a string. Setting to @code{nil} will not insert any
11166 The default value for @code{org-html-postamble} is @code{'auto}, which means
11167 that the HTML exporter will look for information about the author, the email,
11168 the creator and the date, and build the postamble from these values. Setting
11169 @code{org-html-postamble} to @code{t} will insert the postamble from the
11170 relevant format string found in @code{org-html-postamble-format}. Setting it
11171 to @code{nil} will not insert any postamble.
11173 @node Quoting HTML tags
11174 @subsection Quoting HTML tags
11176 Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
11177 @samp{>} in HTML export. If you want to include raw HTML code, which
11178 should only appear in HTML export, mark it with @samp{@@@@html:} as in
11179 @samp{@@@@html:<b>@@@@bold text@@@@html:</b>@@@@}. For more extensive HTML
11180 that should be copied verbatim to the exported file use either
11183 @cindex #+BEGIN_HTML
11185 #+HTML: Literal HTML code for export
11189 @cindex #+BEGIN_HTML
11193 All lines between these markers are exported literally
11198 @node Links in HTML export
11199 @subsection Links in HTML export
11201 @cindex links, in HTML export
11202 @cindex internal links, in HTML export
11203 @cindex external links, in HTML export
11204 Internal links (@pxref{Internal links}) will continue to work in HTML@. This
11205 includes automatic links created by radio targets (@pxref{Radio
11206 targets}). Links to external files will still work if the target file is on
11207 the same @i{relative} path as the published Org file. Links to other
11208 @file{.org} files will be translated into HTML links under the assumption
11209 that an HTML version also exists of the linked file, at the same relative
11210 path. @samp{id:} links can then be used to jump to specific entries across
11211 files. For information related to linking files while publishing them to a
11212 publishing directory see @ref{Publishing links}.
11214 If you want to specify attributes for links, you can do so using a special
11215 @code{#+ATTR_HTML} line to define attributes that will be added to the
11216 @code{<a>} or @code{<img>} tags. Here is an example that sets @code{title}
11217 and @code{style} attributes for a link:
11219 @cindex #+ATTR_HTML
11221 #+ATTR_HTML: :title The Org mode homepage :style color:red;
11222 [[http://orgmode.org]]
11225 @node Tables in HTML export
11226 @subsection Tables in HTML export
11227 @cindex tables, in HTML
11228 @vindex org-html-table-default-attributes
11230 Org mode tables are exported to HTML using the table attributes defined in
11231 @code{org-html-table-default-attributes}. The default setting makes tables
11232 without cell borders and frame. If you would like to change this for
11233 individual tables, place something like the following before the table:
11236 @cindex #+ATTR_HTML
11238 #+CAPTION: This is a table with lines around and between cells
11239 #+ATTR_HTML: :border 2 :rules all :frame border
11242 @vindex org-html-table-row-tags
11243 You can also modify the default tags used for each row by setting
11244 @code{org-html-table-row-tags}. See the docstring for an example on
11245 how to use this option.
11247 @node Images in HTML export
11248 @subsection Images in HTML export
11250 @cindex images, inline in HTML
11251 @cindex inlining images in HTML
11252 @vindex org-html-inline-images
11253 HTML export can inline images given as links in the Org file, and
11254 it can make an image the clickable part of a link. By
11255 default@footnote{But see the variable
11256 @code{org-html-inline-images}.}, images are inlined if a link does
11257 not have a description. So @samp{[[file:myimg.jpg]]} will be inlined,
11258 while @samp{[[file:myimg.jpg][the image]]} will just produce a link
11259 @samp{the image} that points to the image. If the description part
11260 itself is a @code{file:} link or a @code{http:} URL pointing to an
11261 image, this image will be inlined and activated so that clicking on the
11262 image will activate the link. For example, to include a thumbnail that
11263 will link to a high resolution version of the image, you could use:
11266 [[file:highres.jpg][file:thumb.jpg]]
11269 If you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}.
11270 In the example below we specify the @code{alt} and @code{title} attributes to
11271 support text viewers and accessibility, and align it to the right.
11274 @cindex #+ATTR_HTML
11276 #+CAPTION: A black cat stalking a spider
11277 #+ATTR_HTML: :alt cat/spider image :title Action! :align right
11282 You could use @code{http} addresses just as well.
11284 @node Math formatting in HTML export
11285 @subsection Math formatting in HTML export
11288 @cindex imagemagick
11290 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two
11291 different ways on HTML pages. The default is to use the
11292 @uref{http://www.mathjax.org, MathJax system} which should work out of the
11293 box with Org mode installation because @uref{http://orgmode.org} serves
11294 @file{MathJax} for Org mode users for small applications and for testing
11295 purposes. @b{If you plan to use this regularly or on pages with significant
11296 page views, you should install@footnote{Installation instructions can be
11297 found on the MathJax website, see
11298 @uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on
11299 your own server in order to limit the load of our server.} To configure
11300 @file{MathJax}, use the variable @code{org-html-mathjax-options} or
11301 insert something like the following into the buffer:
11304 #+HTML_MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
11307 @noindent See the docstring of the variable
11308 @code{org-html-mathjax-options} for the meaning of the parameters in
11311 If you prefer, you can also request that @LaTeX{} fragments are processed
11312 into small images that will be inserted into the browser page. Before the
11313 availability of MathJax, this was the default method for Org files. This
11314 method requires that the @file{dvipng} program or @file{imagemagick} suite is
11315 available on your system. You can still get this processing with
11318 #+OPTIONS: tex:dvipng
11324 #+OPTIONS: tex:imagemagick
11327 @node Text areas in HTML export
11328 @subsection Text areas in HTML export
11330 @cindex text areas, in HTML
11331 An alternative way to publish literal code examples in HTML is to use text
11332 areas, where the example can even be edited before pasting it into an
11333 application. It is triggered by @code{:textarea} attribute at an
11334 @code{example} or @code{src} block.
11336 You may also use @code{:height} and @code{:width} attributes to specify the
11337 height and width of the text area, which default to the number of lines in
11338 the example, and 80, respectively. For example
11341 #+ATTR_HTML: :textarea t :width 40
11343 (defun org-xor (a b)
11351 @subsection CSS support
11352 @cindex CSS, for HTML export
11353 @cindex HTML export, CSS
11355 @vindex org-html-todo-kwd-class-prefix
11356 @vindex org-html-tag-class-prefix
11357 You can modify the CSS style definitions for the exported file. The HTML
11358 exporter assigns the following special CSS classes@footnote{If the classes on
11359 TODO keywords and tags lead to conflicts, use the variables
11360 @code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to
11361 make them unique.} to appropriate parts of the document---your style
11362 specifications may change these, in addition to any of the standard classes
11363 like for headlines, tables, etc.
11365 p.author @r{author information, including email}
11366 p.date @r{publishing date}
11367 p.creator @r{creator info, about org mode version}
11368 .title @r{document title}
11369 .todo @r{TODO keywords, all not-done states}
11370 .done @r{the DONE keywords, all states that count as done}
11371 .WAITING @r{each TODO keyword also uses a class named after itself}
11372 .timestamp @r{timestamp}
11373 .timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED}
11374 .timestamp-wrapper @r{span around keyword plus timestamp}
11375 .tag @r{tag in a headline}
11376 ._HOME @r{each tag uses itself as a class, "@@" replaced by "_"}
11377 .target @r{target for links}
11378 .linenr @r{the line number in a code example}
11379 .code-highlighted @r{for highlighting referenced code lines}
11380 div.outline-N @r{div for outline level N (headline plus text))}
11381 div.outline-text-N @r{extra div for text at outline level N}
11382 .section-number-N @r{section number in headlines, different for each level}
11383 .figure-number @r{label like "Figure 1:"}
11384 .table-number @r{label like "Table 1:"}
11385 .listing-number @r{label like "Listing 1:"}
11386 div.figure @r{how to format an inlined image}
11387 pre.src @r{formatted source code}
11388 pre.example @r{normal example}
11389 p.verse @r{verse paragraph}
11390 div.footnotes @r{footnote section headline}
11391 p.footnote @r{footnote definition paragraph, containing a footnote}
11392 .footref @r{a footnote reference number (always a <sup>)}
11393 .footnum @r{footnote number in footnote definition (always <sup>)}
11396 @vindex org-html-style-default
11397 @vindex org-html-head-include-default-style
11398 @vindex org-html-head
11399 @vindex org-html-head-extra
11400 @cindex #+HTML_INCLUDE_STYLE
11401 Each exported file contains a compact default style that defines these
11402 classes in a basic way@footnote{This style is defined in the constant
11403 @code{org-html-style-default}, which you should not modify. To turn
11404 inclusion of these defaults off, customize
11405 @code{org-html-head-include-default-style} or set @code{html-style} to
11406 @code{nil} in an @code{OPTIONS} line.}. You may overwrite these settings, or
11407 add to them by using the variables @code{org-html-head} and
11408 @code{org-html-head-extra}. You can override the global values of these
11409 variables for each file by using these keywords:
11411 @cindex #+HTML_HEAD
11412 @cindex #+HTML_HEAD_EXTRA
11414 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
11415 #+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
11419 For longer style definitions, you can use several such lines. You could also
11420 directly write a @code{<style>} @code{</style>} section in this way, without
11421 referring to an external file.
11423 In order to add styles to a subtree, use the @code{:HTML_CONTAINER_CLASS:}
11424 property to assign a class to the tree. In order to specify CSS styles for a
11425 particular headline, you can use the id specified in a @code{:CUSTOM_ID:}
11428 @c FIXME: More about header and footer styles
11429 @c FIXME: Talk about links and targets.
11431 @node JavaScript support
11432 @subsection JavaScript supported display of web pages
11434 @cindex Rose, Sebastian
11435 Sebastian Rose has written a JavaScript program especially designed to
11436 enhance the web viewing experience of HTML files created with Org. This
11437 program allows you to view large files in two different ways. The first one
11438 is an @emph{Info}-like mode where each section is displayed separately and
11439 navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys
11440 as well, press @kbd{?} for an overview of the available keys). The second
11441 view type is a @emph{folding} view much like Org provides inside Emacs. The
11442 script is available at @url{http://orgmode.org/org-info.js} and you can find
11443 the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}.
11444 We host the script at our site, but if you use it a lot, you might not want
11445 to be dependent on @url{http://orgmode.org} and prefer to install a local
11446 copy on your own web server.
11448 All it then takes to use this program is adding a single line to the Org
11451 @cindex #+INFOJS_OPT
11453 #+INFOJS_OPT: view:info toc:nil
11457 If this line is found, the HTML header will automatically contain the code
11458 needed to invoke the script. Using the line above, you can set the following
11462 path: @r{The path to the script. The default is to grab the script from}
11463 @r{@url{http://orgmode.org/org-info.js}, but you might want to have}
11464 @r{a local copy and use a path like @samp{../scripts/org-info.js}.}
11465 view: @r{Initial view when the website is first shown. Possible values are:}
11466 info @r{Info-like interface with one section per page.}
11467 overview @r{Folding interface, initially showing only top-level.}
11468 content @r{Folding interface, starting with all headlines visible.}
11469 showall @r{Folding interface, all headlines and text visible.}
11470 sdepth: @r{Maximum headline level that will still become an independent}
11471 @r{section for info and folding modes. The default is taken from}
11472 @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).}
11473 @r{If this is smaller than in @code{org-export-headline-levels}, each}
11474 @r{info/folding section can still contain child headlines.}
11475 toc: @r{Should the table of contents @emph{initially} be visible?}
11476 @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}
11477 tdepth: @r{The depth of the table of contents. The defaults are taken from}
11478 @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}
11479 ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?}
11480 @r{If yes, the toc will never be displayed as a section.}
11481 ltoc: @r{Should there be short contents (children) in each section?}
11482 @r{Make this @code{above} if the section should be above initial text.}
11483 mouse: @r{Headings are highlighted when the mouse is over them. Should be}
11484 @r{@samp{underline} (default) or a background color like @samp{#cccccc}.}
11485 buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the}
11486 @r{default), only one such button will be present.}
11489 @vindex org-html-infojs-options
11490 @vindex org-html-use-infojs
11491 You can choose default values for these options by customizing the variable
11492 @code{org-html-infojs-options}. If you always want to apply the script to your
11493 pages, configure the variable @code{org-html-use-infojs}.
11495 @node @LaTeX{} and PDF export
11496 @section @LaTeX{} and PDF export
11497 @cindex @LaTeX{} export
11500 @LaTeX{} export can produce an arbitrarily complex LaTeX document of any
11501 standard or custom document class. With further processing@footnote{The
11502 default @LaTeX{} output is designed for processing with @code{pdftex} or
11503 @LaTeX{}. It includes packages that are not compatible with @code{xetex} and
11504 possibly @code{luatex}. The @LaTeX{} exporter can be configured to support
11505 alternative TeX engines, see the options
11506 @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.},
11507 which the @LaTeX{} exporter is able to control, this back-end is able to
11508 produce PDF output. Because the @LaTeX{} exporter can be configured to use
11509 the @code{hyperref} package, the default setup produces fully-linked PDF
11512 As in @LaTeX{}, blank lines are meaningful for this back-end: a paragraph
11513 will not be started if two contiguous syntactical elements are not separated
11516 This back-end also offers enhanced support for footnotes. Thus, it handles
11517 nested footnotes, footnotes in tables and footnotes in a list item's
11521 * @LaTeX{} export commands:: How to export to LaTeX and PDF
11522 * Header and sectioning:: Setting up the export file structure
11523 * Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code
11524 * @LaTeX{} specific attributes:: Controlling @LaTeX{} output
11527 @node @LaTeX{} export commands
11528 @subsection @LaTeX{} export commands
11531 @orgcmd{C-c C-e l l,org-latex-export-to-latex}
11532 Export as a @LaTeX{} file. For an Org file @file{myfile.org}, the @LaTeX{}
11533 file will be @file{myfile.tex}. The file will be overwritten without
11535 @orgcmd{C-c C-e l L,org-latex-export-as-latex}
11536 Export to a temporary buffer. Do not create a file.
11537 @orgcmd{C-c C-e l p,org-latex-export-to-pdf}
11538 Export as @LaTeX{} and then process to PDF.
11540 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
11543 @node Header and sectioning
11544 @subsection Header and sectioning structure
11545 @cindex @LaTeX{} class
11546 @cindex @LaTeX{} sectioning structure
11547 @cindex @LaTeX{} header
11548 @cindex header, for @LaTeX{} files
11549 @cindex sectioning structure, for @LaTeX{} export
11551 By default, the first three outline levels become headlines, defining a
11552 general document structure. Additional levels are exported as @code{itemize}
11553 or @code{enumerate} lists. The transition can also occur at a different
11554 level (@pxref{Export settings}).
11556 By default, the @LaTeX{} output uses the class @code{article}.
11558 @vindex org-latex-default-class
11559 @vindex org-latex-classes
11560 @vindex org-latex-default-packages-alist
11561 @vindex org-latex-packages-alist
11562 You can change this globally by setting a different value for
11563 @code{org-latex-default-class} or locally by adding an option like
11564 @code{#+LATEX_CLASS: myclass} in your file, or with
11565 a @code{EXPORT_LATEX_CLASS} property that applies when exporting a region
11566 containing only this (sub)tree. The class must be listed in
11567 @code{org-latex-classes}. This variable defines a header template for each
11568 class@footnote{Into which the values of
11569 @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}
11570 are spliced.}, and allows you to define the sectioning structure for each
11571 class. You can also define your own classes there.
11573 @cindex #+LATEX_CLASS
11574 @cindex #+LATEX_CLASS_OPTIONS
11575 @cindex property, EXPORT_LATEX_CLASS
11576 @cindex property, EXPORT_LATEX_CLASS_OPTIONS
11577 The @code{LATEX_CLASS_OPTIONS} keyword or @code{EXPORT_LATEX_CLASS_OPTIONS}
11578 property can specify the options for the @code{\documentclass} macro. These
11579 options have to be provided, as expected by @LaTeX{}, within square brackets.
11581 @cindex #+LATEX_HEADER
11582 @cindex #+LATEX_HEADER_EXTRA
11583 You can also use the @code{LATEX_HEADER} and
11584 @code{LATEX_HEADER_EXTRA}@footnote{Unlike @code{LATEX_HEADER}, contents
11585 from @code{LATEX_HEADER_EXTRA} keywords will not be loaded when previewing
11586 @LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).} keywords in order
11587 to add lines to the header. See the docstring of @code{org-latex-classes} for
11590 An example is shown below.
11593 #+LATEX_CLASS: article
11594 #+LATEX_CLASS_OPTIONS: [a4paper]
11595 #+LATEX_HEADER: \usepackage@{xyz@}
11601 @node Quoting @LaTeX{} code
11602 @subsection Quoting @LaTeX{} code
11604 Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly
11605 inserted into the @LaTeX{} file. Furthermore, you can add special code that
11606 should only be present in @LaTeX{} export with the following constructs:
11609 @cindex #+BEGIN_LATEX
11611 Code within @@@@latex:some code@@@@ a paragraph.
11613 #+LATEX: Literal @LaTeX{} code for export
11616 All lines between these markers are exported literally
11620 @node @LaTeX{} specific attributes
11621 @subsection @LaTeX{} specific attributes
11622 @cindex #+ATTR_LATEX
11624 @LaTeX{} understands attributes specified in an @code{ATTR_LATEX} line. They
11625 affect tables, images, plain lists, special blocks and source blocks.
11627 @subsubheading Tables in @LaTeX{} export
11628 @cindex tables, in @LaTeX{} export
11630 For @LaTeX{} export of a table, you can specify a label and a caption
11631 (@pxref{Images and tables}). You can also use attributes to control table
11632 layout and contents. Valid @LaTeX{} attributes include:
11636 @vindex org-latex-default-table-mode
11637 Nature of table's contents. It can be set to @code{table}, @code{math},
11638 @code{inline-math} or @code{verbatim}. In particular, when in @code{math} or
11639 @code{inline-math} mode, every cell is exported as-is, horizontal rules are
11640 ignored and the table will be wrapped in a math environment. Also,
11641 contiguous tables sharing the same math mode will be wrapped within the same
11642 environment. Default mode is determined in
11643 @code{org-latex-default-table-mode}.
11645 @vindex org-latex-default-table-environment
11646 Environment used for the table. It can be set to any @LaTeX{} table
11647 environment, like @code{tabularx}@footnote{Requires adding the
11648 @code{tabularx} package to @code{org-latex-packages-alist}.},
11649 @code{longtable}, @code{array}, @code{tabu}@footnote{Requires adding the
11650 @code{tabu} package to @code{org-latex-packages-alist}.},
11651 @code{bmatrix}@enddots{} It defaults to
11652 @code{org-latex-default-table-environment} value.
11654 @code{#+CAPTION} keyword is the simplest way to set a caption for a table
11655 (@pxref{Images and tables}). If you need more advanced commands for that
11656 task, you can use @code{:caption} attribute instead. Its value should be raw
11657 @LaTeX{} code. It has precedence over @code{#+CAPTION}.
11660 Float environment for the table. Possible values are @code{sidewaystable},
11661 @code{multicolumn}, @code{t} and @code{nil}. When unspecified, a table with
11662 a caption will have a @code{table} environment. Moreover, @code{:placement}
11663 attribute can specify the positioning of the float.
11667 Set, respectively, the alignment string of the table, its font size and its
11668 width. They only apply on regular tables.
11670 Boolean specific to the @code{tabu} and @code{longtabu} environments, and
11671 only takes effect when used in conjunction with the @code{:width} attribute.
11672 When @code{:spread} is non-@code{nil}, the table will be spread or shrunk by the
11673 value of @code{:width}.
11677 @vindex org-latex-tables-booktabs
11678 @vindex org-latex-tables-centered
11679 They toggle, respectively, @code{booktabs} usage (assuming the package is
11680 properly loaded), table centering and removal of every horizontal rule but
11681 the first one (in a "table.el" table only). In particular,
11682 @code{org-latex-tables-booktabs} (respectively @code{org-latex-tables-centered})
11683 activates the first (respectively second) attribute globally.
11685 @itemx :math-suffix
11686 @itemx :math-arguments
11687 A string that will be inserted, respectively, before the table within the
11688 math environment, after the table within the math environment, and between
11689 the macro name and the contents of the table. The @code{:math-arguments}
11690 attribute is used for matrix macros that require more than one argument
11691 (e.g., @code{qbordermatrix}).
11694 Thus, attributes can be used in a wide array of situations, like writing
11695 a table that will span over multiple pages, or a matrix product:
11698 #+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l
11702 #+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
11705 #+ATTR_LATEX: :mode math :environment bmatrix
11710 In the example below, @LaTeX{} command
11711 @code{\bicaption@{HeadingA@}@{HeadingB@}} will set the caption.
11714 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
11720 @subsubheading Images in @LaTeX{} export
11721 @cindex images, inline in @LaTeX{}
11722 @cindex inlining images in @LaTeX{}
11724 Images that are linked to without a description part in the link, like
11725 @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF
11726 output file resulting from @LaTeX{} processing. Org will use an
11727 @code{\includegraphics} macro to insert the image@footnote{In the case of
11728 TikZ (@url{http://sourceforge.net/projects/pgf/}) images, it will become an
11729 @code{\input} macro wrapped within a @code{tikzpicture} environment.}.
11731 You can specify specify image width or height with, respectively,
11732 @code{:width} and @code{:height} attributes. It is also possible to add any
11733 other option with the @code{:options} attribute, as shown in the following
11737 #+ATTR_LATEX: :width 5cm :options angle=90
11738 [[./img/sed-hr4049.pdf]]
11741 If you need a specific command for the caption, use @code{:caption}
11742 attribute. It will override standard @code{#+CAPTION} value, if any.
11745 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
11746 [[./img/sed-hr4049.pdf]]
11749 If you have specified a caption as described in @ref{Images and tables}, the
11750 picture will be wrapped into a @code{figure} environment and thus become
11751 a floating element. You can also ask Org to export an image as a float
11752 without specifying caption by setting the @code{:float} attribute. You may
11756 @code{t}: if you want to use the standard @samp{figure} environment. It is
11757 used by default if you provide a caption to the image.
11759 @code{multicolumn}: if you wish to include an image which spans multiple
11760 columns in a page. This will export the image wrapped in a @code{figure*}
11763 @code{wrap}: if you would like to let text flow around the image. It will
11764 make the figure occupy the left half of the page.
11766 @code{nil}: if you need to avoid any floating environment, even when
11767 a caption is provided.
11770 To modify the placement option of any floating environment, set the
11771 @code{placement} attribute.
11774 #+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement @{r@}@{0.4\textwidth@}
11778 If the @code{:comment-include} attribute is set to a non-@code{nil} value,
11779 the @LaTeX{} @code{\includegraphics} macro will be commented out.
11781 @subsubheading Plain lists in @LaTeX{} export
11782 @cindex plain lists, in @LaTeX{} export
11784 Plain lists accept two optional attributes: @code{:environment} and
11785 @code{:options}. The first one allows the use of a non-standard environment
11786 (e.g., @samp{inparaenum}). The second one specifies additional arguments for
11790 #+ATTR_LATEX: :environment compactitem :options [$\circ$]
11791 - you need ``paralist'' package to reproduce this example.
11794 @subsubheading Source blocks in @LaTeX{} export
11795 @cindex source blocks, in @LaTeX{} export
11797 In addition to syntax defined in @ref{Literal examples}, names and captions
11798 (@pxref{Images and tables}), source blocks also accept a @code{:float}
11799 attribute. You may set it to:
11802 @code{t}: if you want to make the source block a float. It is the default
11803 value when a caption is provided.
11805 @code{multicolumn}: if you wish to include a source block which spans multiple
11808 @code{nil}: if you need to avoid any floating environment, even when a caption
11809 is provided. It is useful for source code that may not fit in a single page.
11813 #+ATTR_LATEX: :float nil
11814 #+BEGIN_SRC emacs-lisp
11815 Code that may not fit in a single page.
11819 @subsubheading Special blocks in @LaTeX{} export
11820 @cindex special blocks, in @LaTeX{} export
11821 @cindex abstract, in @LaTeX{} export
11822 @cindex proof, in @LaTeX{} export
11824 In @LaTeX{} back-end, special blocks become environments of the same name.
11825 Value of @code{:options} attribute will be appended as-is to that
11826 environment's opening string. For example:
11830 We demonstrate how to solve the Syracuse problem.
11833 #+ATTR_LATEX: :options [Proof of important theorem]
11836 Therefore, any even number greater than 2 is the sum of two primes.
11845 We demonstrate how to solve the Syracuse problem.
11848 \begin@{proof@}[Proof of important theorem]
11850 Therefore, any even number greater than 2 is the sum of two primes.
11854 If you need to insert a specific caption command, use @code{:caption}
11855 attribute. It will override standard @code{#+CAPTION} value, if any. For
11859 #+ATTR_LATEX: :caption \MyCaption@{HeadingA@}
11865 @subsubheading Horizontal rules
11866 @cindex horizontal rules, in @LaTeX{} export
11868 Width and thickness of a given horizontal rule can be controlled with,
11869 respectively, @code{:width} and @code{:thickness} attributes:
11872 #+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
11876 @node Markdown export
11877 @section Markdown export
11878 @cindex Markdown export
11880 @code{md} export back-end generates Markdown syntax@footnote{Vanilla flavor,
11881 as defined at @url{http://daringfireball.net/projects/markdown/}.} for an Org
11884 It is built over HTML back-end: any construct not supported by Markdown
11885 syntax (e.g., tables) will be controlled and translated by @code{html}
11886 back-end (@pxref{HTML export}).
11888 @subheading Markdown export commands
11891 @orgcmd{C-c C-e m m,org-md-export-to-markdown}
11892 Export as a text file written in Markdown syntax. For an Org file,
11893 @file{myfile.org}, the resulting file will be @file{myfile.md}. The file
11894 will be overwritten without warning.
11895 @orgcmd{C-c C-e m M,org-md-export-as-markdown}
11896 Export to a temporary buffer. Do not create a file.
11898 Export as a text file with Markdown syntax, then open it.
11901 @subheading Header and sectioning structure
11903 @vindex org-md-headline-style
11904 Markdown export can generate both @code{atx} and @code{setext} types for
11905 headlines, according to @code{org-md-headline-style}. The former introduces
11906 a hard limit of two levels, whereas the latter pushes it to six. Headlines
11907 below that limit are exported as lists. You can also set a soft limit before
11908 that one (@pxref{Export settings}).
11910 @c begin opendocument
11912 @node OpenDocument text export
11913 @section OpenDocument text export
11915 @cindex OpenDocument
11916 @cindex export, OpenDocument
11917 @cindex LibreOffice
11919 Org mode@footnote{Versions 7.8 or later} supports export to OpenDocument Text
11920 (ODT) format. Documents created by this exporter use the
11921 @cite{OpenDocument-v1.2
11922 specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
11923 Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
11924 are compatible with LibreOffice 3.4.
11927 * Pre-requisites for ODT export:: What packages ODT exporter relies on
11928 * ODT export commands:: How to invoke ODT export
11929 * Extending ODT export:: How to produce @samp{doc}, @samp{pdf} files
11930 * Applying custom styles:: How to apply custom styles to the output
11931 * Links in ODT export:: How links will be interpreted and formatted
11932 * Tables in ODT export:: How Tables are exported
11933 * Images in ODT export:: How to insert images
11934 * Math formatting in ODT export:: How @LaTeX{} fragments are formatted
11935 * Labels and captions in ODT export:: How captions are rendered
11936 * Literal examples in ODT export:: How source and example blocks are formatted
11937 * Advanced topics in ODT export:: Read this if you are a power user
11940 @node Pre-requisites for ODT export
11941 @subsection Pre-requisites for ODT export
11943 The ODT exporter relies on the @file{zip} program to create the final
11944 output. Check the availability of this program before proceeding further.
11946 @node ODT export commands
11947 @subsection ODT export commands
11949 @subsubheading Exporting to ODT
11950 @anchor{x-export-to-odt}
11952 @cindex region, active
11953 @cindex active region
11954 @cindex transient-mark-mode
11956 @orgcmd{C-c C-e o o,org-odt-export-to-odt}
11957 @cindex property EXPORT_FILE_NAME
11959 Export as OpenDocument Text file.
11961 @vindex org-odt-preferred-output-format
11962 If @code{org-odt-preferred-output-format} is specified, automatically convert
11963 the exported file to that format. @xref{x-export-to-other-formats, ,
11964 Automatically exporting to other formats}.
11966 For an Org file @file{myfile.org}, the ODT file will be
11967 @file{myfile.odt}. The file will be overwritten without warning. If there
11968 is an active region,@footnote{This requires @code{transient-mark-mode} to be
11969 turned on} only the region will be exported. If the selected region is a
11970 single tree,@footnote{To select the current subtree, use @kbd{C-c @@}} the
11971 tree head will become the document title. If the tree head entry has, or
11972 inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the
11976 Export as an OpenDocument Text file and open the resulting file.
11978 @vindex org-odt-preferred-output-format
11979 If @code{org-odt-preferred-output-format} is specified, open the converted
11980 file instead. @xref{x-export-to-other-formats, , Automatically exporting to
11984 @node Extending ODT export
11985 @subsection Extending ODT export
11987 The ODT exporter can interface with a variety of document
11988 converters and supports popular converters out of the box. As a result, you
11989 can use it to export to formats like @samp{doc} or convert a document from
11990 one format (say @samp{csv}) to another format (say @samp{ods} or @samp{xls}).
11992 @cindex @file{unoconv}
11993 @cindex LibreOffice
11994 If you have a working installation of LibreOffice, a document converter is
11995 pre-configured for you and you can use it right away. If you would like to
11996 use @file{unoconv} as your preferred converter, customize the variable
11997 @code{org-odt-convert-process} to point to @code{unoconv}. You can
11998 also use your own favorite converter or tweak the default settings of the
11999 @file{LibreOffice} and @samp{unoconv} converters. @xref{Configuring a
12000 document converter}.
12002 @subsubheading Automatically exporting to other formats
12003 @anchor{x-export-to-other-formats}
12005 @vindex org-odt-preferred-output-format
12006 Very often, you will find yourself exporting to ODT format, only to
12007 immediately save the exported document to other formats like @samp{doc},
12008 @samp{docx}, @samp{rtf}, @samp{pdf} etc. In such cases, you can specify your
12009 preferred output format by customizing the variable
12010 @code{org-odt-preferred-output-format}. This way, the export commands
12011 (@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a
12012 format that is of immediate interest to you.
12014 @subsubheading Converting between document formats
12015 @anchor{x-convert-to-other-formats}
12017 There are many document converters in the wild which support conversion to
12018 and from various file formats, including, but not limited to the
12019 ODT format. LibreOffice converter, mentioned above, is one such
12020 converter. Once a converter is configured, you can interact with it using
12021 the following command.
12023 @vindex org-odt-convert
12026 @item M-x org-odt-convert RET
12027 Convert an existing document from one format to another. With a prefix
12028 argument, also open the newly produced file.
12031 @node Applying custom styles
12032 @subsection Applying custom styles
12033 @cindex styles, custom
12034 @cindex template, custom
12036 The ODT exporter ships with a set of OpenDocument styles
12037 (@pxref{Working with OpenDocument style files}) that ensure a well-formatted
12038 output. These factory styles, however, may not cater to your specific
12039 tastes. To customize the output, you can either modify the above styles
12040 files directly, or generate the required styles using an application like
12041 LibreOffice. The latter method is suitable for expert and non-expert
12042 users alike, and is described here.
12044 @subsubheading Applying custom styles: the easy way
12048 Create a sample @file{example.org} file with the below settings and export it
12052 #+OPTIONS: H:10 num:t
12056 Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist}
12057 to locate the target styles---these typically have the @samp{Org} prefix---and
12058 modify those to your taste. Save the modified file either as an
12059 OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file.
12062 @cindex #+ODT_STYLES_FILE
12063 @vindex org-odt-styles-file
12064 Customize the variable @code{org-odt-styles-file} and point it to the
12065 newly created file. For additional configuration options
12066 @pxref{x-overriding-factory-styles,,Overriding factory styles}.
12068 If you would like to choose a style on a per-file basis, you can use the
12069 @code{#+ODT_STYLES_FILE} option. A typical setting will look like
12072 #+ODT_STYLES_FILE: "/path/to/example.ott"
12078 #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
12083 @subsubheading Using third-party styles and templates
12085 You can use third-party styles and templates for customizing your output.
12086 This will produce the desired output only if the template provides all
12087 style names that the @samp{ODT} exporter relies on. Unless this condition is
12088 met, the output is going to be less than satisfactory. So it is highly
12089 recommended that you only work with templates that are directly derived from
12090 the factory settings.
12092 @node Links in ODT export
12093 @subsection Links in ODT export
12094 @cindex links, in ODT export
12096 ODT exporter creates native cross-references for internal links. It creates
12097 Internet-style links for all other links.
12099 A link with no description and destined to a regular (un-itemized) outline
12100 heading is replaced with a cross-reference and section number of the heading.
12102 A @samp{\ref@{label@}}-style reference to an image, table etc. is replaced
12103 with a cross-reference and sequence number of the labeled entity.
12104 @xref{Labels and captions in ODT export}.
12106 @node Tables in ODT export
12107 @subsection Tables in ODT export
12108 @cindex tables, in ODT export
12110 Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el}
12111 tables is supported. However, export of complex @file{table.el} tables---tables
12112 that have column or row spans---is not supported. Such tables are
12113 stripped from the exported document.
12115 By default, a table is exported with top and bottom frames and with rules
12116 separating row and column groups (@pxref{Column groups}). Furthermore, all
12117 tables are typeset to occupy the same width. If the table specifies
12118 alignment and relative width for its columns (@pxref{Column width and
12119 alignment}) then these are honored on export.@footnote{The column widths are
12120 interpreted as weighted ratios with the default weight being 1}
12123 You can control the width of the table by specifying @code{:rel-width}
12124 property using an @code{#+ATTR_ODT} line.
12126 For example, consider the following table which makes use of all the rules
12130 #+ATTR_ODT: :rel-width 50
12131 | Area/Month | Jan | Feb | Mar | Sum |
12132 |---------------+-------+-------+-------+-------|
12134 | <l13> | <r5> | <r5> | <r5> | <r6> |
12135 | North America | 1 | 21 | 926 | 948 |
12136 | Middle East | 6 | 75 | 844 | 925 |
12137 | Asia Pacific | 9 | 27 | 790 | 826 |
12138 |---------------+-------+-------+-------+-------|
12139 | Sum | 16 | 123 | 2560 | 2699 |
12142 On export, the table will occupy 50% of text area. The columns will be sized
12143 (roughly) in the ratio of 13:5:5:5:6. The first column will be left-aligned
12144 and rest of the columns will be right-aligned. There will be vertical rules
12145 after separating the header and last columns from other columns. There will
12146 be horizontal rules separating the header and last rows from other rows.
12148 If you are not satisfied with the above formatting options, you can create
12149 custom table styles and associate them with a table using the
12150 @code{#+ATTR_ODT} line. @xref{Customizing tables in ODT export}.
12152 @node Images in ODT export
12153 @subsection Images in ODT export
12154 @cindex images, embedding in ODT
12155 @cindex embedding images in ODT
12157 @subsubheading Embedding images
12158 You can embed images within the exported document by providing a link to the
12159 desired image file with no link description. For example, to embed
12160 @samp{img.png} do either of the following:
12170 @subsubheading Embedding clickable images
12171 You can create clickable images by providing a link whose description is a
12172 link to an image file. For example, to embed a image
12173 @file{org-mode-unicorn.png} which when clicked jumps to
12174 @uref{http://Orgmode.org} website, do the following
12177 [[http://orgmode.org][./org-mode-unicorn.png]]
12180 @subsubheading Sizing and scaling of embedded images
12183 You can control the size and scale of the embedded images using the
12184 @code{#+ATTR_ODT} attribute.
12186 @cindex identify, ImageMagick
12187 @vindex org-odt-pixels-per-inch
12188 The exporter specifies the desired size of the image in the final document in
12189 units of centimeters. In order to scale the embedded images, the exporter
12190 queries for pixel dimensions of the images using one of a) ImageMagick's
12191 @file{identify} program or b) Emacs `create-image' and `image-size'
12192 APIs@footnote{Use of @file{ImageMagick} is only desirable. However, if you
12193 routinely produce documents that have large images or you export your Org
12194 files that has images using a Emacs batch script, then the use of
12195 @file{ImageMagick} is mandatory.}. The pixel dimensions are subsequently
12196 converted in to units of centimeters using
12197 @code{org-odt-pixels-per-inch}. The default value of this variable is
12198 set to @code{display-pixels-per-inch}. You can tweak this variable to
12199 achieve the best results.
12201 The examples below illustrate the various possibilities.
12204 @item Explicitly size the image
12205 To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
12208 #+ATTR_ODT: :width 10 :height 10
12212 @item Scale the image
12213 To embed @file{img.png} at half its size, do the following:
12216 #+ATTR_ODT: :scale 0.5
12220 @item Scale the image to a specific width
12221 To embed @file{img.png} with a width of 10 cm while retaining the original
12222 height:width ratio, do the following:
12225 #+ATTR_ODT: :width 10
12229 @item Scale the image to a specific height
12230 To embed @file{img.png} with a height of 10 cm while retaining the original
12231 height:width ratio, do the following
12234 #+ATTR_ODT: :height 10
12239 @subsubheading Anchoring of images
12242 You can control the manner in which an image is anchored by setting the
12243 @code{:anchor} property of it's @code{#+ATTR_ODT} line. You can specify one
12244 of the the following three values for the @code{:anchor} property:
12245 @samp{"as-char"}, @samp{"paragraph"} and @samp{"page"}.
12247 To create an image that is anchored to a page, do the following:
12249 #+ATTR_ODT: :anchor "page"
12253 @node Math formatting in ODT export
12254 @subsection Math formatting in ODT export
12256 The ODT exporter has special support for handling math.
12259 * Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments
12260 * Working with MathML or OpenDocument formula files:: How to embed equations in native format
12263 @node Working with @LaTeX{} math snippets
12264 @subsubheading Working with @LaTeX{} math snippets
12266 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT
12267 document in one of the following ways:
12273 This option is activated on a per-file basis with
12279 With this option, @LaTeX{} fragments are first converted into MathML
12280 fragments using an external @LaTeX{}-to-MathML converter program. The
12281 resulting MathML fragments are then embedded as an OpenDocument Formula in
12282 the exported document.
12284 @vindex org-latex-to-mathml-convert-command
12285 @vindex org-latex-to-mathml-jar-file
12287 You can specify the @LaTeX{}-to-MathML converter by customizing the variables
12288 @code{org-latex-to-mathml-convert-command} and
12289 @code{org-latex-to-mathml-jar-file}.
12291 If you prefer to use @file{MathToWeb}@footnote{See
12292 @uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}} as your
12293 converter, you can configure the above variables as shown below.
12296 (setq org-latex-to-mathml-convert-command
12297 "java -jar %j -unicode -force -df %o %I"
12298 org-latex-to-mathml-jar-file
12299 "/path/to/mathtoweb.jar")
12302 You can use the following commands to quickly verify the reliability of
12303 the @LaTeX{}-to-MathML converter.
12306 @item M-x org-odt-export-as-odf RET
12307 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file.
12309 @item M-x org-odt-export-as-odf-and-open RET
12310 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file
12311 and open the formula file with the system-registered application.
12315 @cindex imagemagick
12318 This option is activated on a per-file basis with
12321 #+OPTIONS: tex:dvipng
12327 #+OPTIONS: tex:imagemagick
12330 With this option, @LaTeX{} fragments are processed into PNG images and the
12331 resulting images are embedded in the exported document. This method requires
12332 that the @file{dvipng} program or @file{imagemagick} suite be available on
12336 @node Working with MathML or OpenDocument formula files
12337 @subsubheading Working with MathML or OpenDocument formula files
12339 For various reasons, you may find embedding @LaTeX{} math snippets in an
12340 ODT document less than reliable. In that case, you can embed a
12341 math equation by linking to its MathML (@file{.mml}) source or its
12342 OpenDocument formula (@file{.odf}) file as shown below:
12354 @node Labels and captions in ODT export
12355 @subsection Labels and captions in ODT export
12357 You can label and caption various category of objects---an inline image, a
12358 table, a @LaTeX{} fragment or a Math formula---using @code{#+LABEL} and
12359 @code{#+CAPTION} lines. @xref{Images and tables}. ODT exporter enumerates
12360 each labeled or captioned object of a given category separately. As a
12361 result, each such object is assigned a sequence number based on order of it's
12362 appearance in the Org file.
12364 In the exported document, a user-provided caption is augmented with the
12365 category and sequence number. Consider the following inline image in an Org
12369 #+CAPTION: Bell curve
12370 #+LABEL: fig:SED-HR4049
12374 It could be rendered as shown below in the exported document.
12377 Figure 2: Bell curve
12380 @vindex org-odt-category-map-alist
12381 You can modify the category component of the caption by customizing the
12382 option @code{org-odt-category-map-alist}. For example, to tag all embedded
12383 images with the string @samp{Illustration} (instead of the default
12384 @samp{Figure}) use the following setting:
12387 (setq org-odt-category-map-alist
12388 (("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
12391 With this, previous image will be captioned as below in the exported
12395 Illustration 2: Bell curve
12398 @node Literal examples in ODT export
12399 @subsection Literal examples in ODT export
12401 Export of literal examples (@pxref{Literal examples}) with full fontification
12402 is supported. Internally, the exporter relies on @file{htmlfontify.el} to
12403 generate all style definitions needed for a fancy listing.@footnote{Your
12404 @file{htmlfontify.el} library must at least be at Emacs 24.1 levels for
12405 fontification to be turned on.} The auto-generated styles have @samp{OrgSrc}
12406 as prefix and inherit their color from the faces used by Emacs
12407 @code{font-lock} library for the source language.
12409 @vindex org-odt-fontify-srcblocks
12410 If you prefer to use your own custom styles for fontification, you can do
12411 so by customizing the option
12412 @code{org-odt-create-custom-styles-for-srcblocks}.
12414 @vindex org-odt-create-custom-styles-for-srcblocks
12415 You can turn off fontification of literal examples by customizing the
12416 option @code{org-odt-fontify-srcblocks}.
12418 @node Advanced topics in ODT export
12419 @subsection Advanced topics in ODT export
12421 If you rely heavily on ODT export, you may want to exploit the full
12422 set of features that the exporter offers. This section describes features
12423 that would be of interest to power users.
12426 * Configuring a document converter:: How to register a document converter
12427 * Working with OpenDocument style files:: Explore the internals
12428 * Creating one-off styles:: How to produce custom highlighting etc
12429 * Customizing tables in ODT export:: How to define and use Table templates
12430 * Validating OpenDocument XML:: How to debug corrupt OpenDocument files
12433 @node Configuring a document converter
12434 @subsubheading Configuring a document converter
12436 @cindex doc, docx, rtf
12439 The ODT exporter can work with popular converters with little or no
12440 extra configuration from your side. @xref{Extending ODT export}.
12441 If you are using a converter that is not supported by default or if you would
12442 like to tweak the default converter settings, proceed as below.
12445 @item Register the converter
12447 @vindex org-odt-convert-processes
12448 Name your converter and add it to the list of known converters by
12449 customizing the option @code{org-odt-convert-processes}. Also specify how
12450 the converter can be invoked via command-line to effect the conversion.
12452 @item Configure its capabilities
12454 @vindex org-odt-convert-capabilities
12455 @anchor{x-odt-converter-capabilities} Specify the set of formats the
12456 converter can handle by customizing the variable
12457 @code{org-odt-convert-capabilities}. Use the default value for this
12458 variable as a guide for configuring your converter. As suggested by the
12459 default setting, you can specify the full set of formats supported by the
12460 converter and not limit yourself to specifying formats that are related to
12461 just the OpenDocument Text format.
12463 @item Choose the converter
12465 @vindex org-odt-convert-process
12466 Select the newly added converter as the preferred one by customizing the
12467 option @code{org-odt-convert-process}.
12470 @node Working with OpenDocument style files
12471 @subsubheading Working with OpenDocument style files
12472 @cindex styles, custom
12473 @cindex template, custom
12475 This section explores the internals of the ODT exporter and the
12476 means by which it produces styled documents. Read this section if you are
12477 interested in exploring the automatic and custom OpenDocument styles used by
12480 @anchor{x-factory-styles}
12481 @subsubheading a) Factory styles
12483 The ODT exporter relies on two files for generating its output.
12484 These files are bundled with the distribution under the directory pointed to
12485 by the variable @code{org-odt-styles-dir}. The two files are:
12488 @anchor{x-orgodtstyles-xml}
12490 @file{OrgOdtStyles.xml}
12492 This file contributes to the @file{styles.xml} file of the final @samp{ODT}
12493 document. This file gets modified for the following purposes:
12497 To control outline numbering based on user settings.
12500 To add styles generated by @file{htmlfontify.el} for fontification of code
12504 @anchor{x-orgodtcontenttemplate-xml}
12506 @file{OrgOdtContentTemplate.xml}
12508 This file contributes to the @file{content.xml} file of the final @samp{ODT}
12509 document. The contents of the Org outline are inserted between the
12510 @samp{<office:text>}@dots{}@samp{</office:text>} elements of this file.
12512 Apart from serving as a template file for the final @file{content.xml}, the
12513 file serves the following purposes:
12517 It contains automatic styles for formatting of tables which are referenced by
12521 It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
12522 elements that control how various entities---tables, images, equations,
12523 etc.---are numbered.
12527 @anchor{x-overriding-factory-styles}
12528 @subsubheading b) Overriding factory styles
12529 The following two variables control the location from which the ODT
12530 exporter picks up the custom styles and content template files. You can
12531 customize these variables to override the factory styles used by the
12535 @anchor{x-org-odt-styles-file}
12537 @code{org-odt-styles-file}
12539 Use this variable to specify the @file{styles.xml} that will be used in the
12540 final output. You can specify one of the following values:
12543 @item A @file{styles.xml} file
12545 Use this file instead of the default @file{styles.xml}
12547 @item A @file{.odt} or @file{.ott} file
12549 Use the @file{styles.xml} contained in the specified OpenDocument Text or
12552 @item A @file{.odt} or @file{.ott} file and a subset of files contained within them
12554 Use the @file{styles.xml} contained in the specified OpenDocument Text or
12555 Template file. Additionally extract the specified member files and embed
12556 those within the final @samp{ODT} document.
12558 Use this option if the @file{styles.xml} file references additional files
12559 like header and footer images.
12563 Use the default @file{styles.xml}
12566 @anchor{x-org-odt-content-template-file}
12568 @code{org-odt-content-template-file}
12570 Use this variable to specify the blank @file{content.xml} that will be used
12571 in the final output.
12574 @node Creating one-off styles
12575 @subsubheading Creating one-off styles
12577 There are times when you would want one-off formatting in the exported
12578 document. You can achieve this by embedding raw OpenDocument XML in the Org
12579 file. The use of this feature is better illustrated with couple of examples.
12582 @item Embedding ODT tags as part of regular text
12584 You can inline OpenDocument syntax by enclosing it within
12585 @samp{@@@@odt:...@@@@} markup. For example, to highlight a region of text do
12589 @@@@odt:<text:span text:style-name="Highlight">This is a highlighted
12590 text</text:span>@@@@. But this is a regular text.
12593 @strong{Hint:} To see the above example in action, edit your
12594 @file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
12595 custom @samp{Highlight} style as shown below.
12598 <style:style style:name="Highlight" style:family="text">
12599 <style:text-properties fo:background-color="#ff0000"/>
12603 @item Embedding a one-line OpenDocument XML
12605 You can add a simple OpenDocument one-liner using the @code{#+ODT:}
12606 directive. For example, to force a page break do the following:
12609 #+ODT: <text:p text:style-name="PageBreak"/>
12612 @strong{Hint:} To see the above example in action, edit your
12613 @file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
12614 custom @samp{PageBreak} style as shown below.
12617 <style:style style:name="PageBreak" style:family="paragraph"
12618 style:parent-style-name="Text_20_body">
12619 <style:paragraph-properties fo:break-before="page"/>
12623 @item Embedding a block of OpenDocument XML
12625 You can add a large block of OpenDocument XML using the
12626 @code{#+BEGIN_ODT}@dots{}@code{#+END_ODT} construct.
12628 For example, to create a one-off paragraph that uses bold text, do the
12633 <text:p text:style-name="Text_20_body_20_bold">
12634 This paragraph is specially formatted and uses bold text.
12641 @node Customizing tables in ODT export
12642 @subsubheading Customizing tables in ODT export
12643 @cindex tables, in ODT export
12646 You can override the default formatting of the table by specifying a custom
12647 table style with the @code{#+ATTR_ODT} line. For a discussion on default
12648 formatting of tables @pxref{Tables in ODT export}.
12650 This feature closely mimics the way table templates are defined in the
12652 specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
12653 OpenDocument-v1.2 Specification}}
12655 @vindex org-odt-table-styles
12656 To have a quick preview of this feature, install the below setting and
12657 export the table that follows:
12660 (setq org-odt-table-styles
12661 (append org-odt-table-styles
12662 '(("TableWithHeaderRowAndColumn" "Custom"
12663 ((use-first-row-styles . t)
12664 (use-first-column-styles . t)))
12665 ("TableWithFirstRowandLastRow" "Custom"
12666 ((use-first-row-styles . t)
12667 (use-last-row-styles . t))))))
12671 #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
12672 | Name | Phone | Age |
12673 | Peter | 1234 | 17 |
12674 | Anna | 4321 | 25 |
12677 In the above example, you used a template named @samp{Custom} and installed
12678 two table styles with the names @samp{TableWithHeaderRowAndColumn} and
12679 @samp{TableWithFirstRowandLastRow}. (@strong{Important:} The OpenDocument
12680 styles needed for producing the above template have been pre-defined for
12681 you. These styles are available under the section marked @samp{Custom
12682 Table Template} in @file{OrgOdtContentTemplate.xml}
12683 (@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need
12684 additional templates you have to define these styles yourselves.
12686 To use this feature proceed as follows:
12690 Create a table template@footnote{See the @code{<table:table-template>}
12691 element of the OpenDocument-v1.2 specification}
12693 A table template is nothing but a set of @samp{table-cell} and
12694 @samp{paragraph} styles for each of the following table cell categories:
12708 The names for the above styles must be chosen based on the name of the table
12709 template using a well-defined convention.
12711 The naming convention is better illustrated with an example. For a table
12712 template with the name @samp{Custom}, the needed style names are listed in
12713 the following table.
12715 @multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph}
12716 @headitem Table cell type
12717 @tab @code{table-cell} style
12718 @tab @code{paragraph} style
12723 @tab @samp{CustomTableCell}
12724 @tab @samp{CustomTableParagraph}
12726 @tab @samp{CustomFirstColumnTableCell}
12727 @tab @samp{CustomFirstColumnTableParagraph}
12729 @tab @samp{CustomLastColumnTableCell}
12730 @tab @samp{CustomLastColumnTableParagraph}
12732 @tab @samp{CustomFirstRowTableCell}
12733 @tab @samp{CustomFirstRowTableParagraph}
12735 @tab @samp{CustomLastRowTableCell}
12736 @tab @samp{CustomLastRowTableParagraph}
12738 @tab @samp{CustomEvenRowTableCell}
12739 @tab @samp{CustomEvenRowTableParagraph}
12741 @tab @samp{CustomOddRowTableCell}
12742 @tab @samp{CustomOddRowTableParagraph}
12744 @tab @samp{CustomEvenColumnTableCell}
12745 @tab @samp{CustomEvenColumnTableParagraph}
12747 @tab @samp{CustomOddColumnTableCell}
12748 @tab @samp{CustomOddColumnTableParagraph}
12751 To create a table template with the name @samp{Custom}, define the above
12753 @code{<office:automatic-styles>}...@code{</office:automatic-styles>} element
12754 of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory
12758 Define a table style@footnote{See the attributes @code{table:template-name},
12759 @code{table:use-first-row-styles}, @code{table:use-last-row-styles},
12760 @code{table:use-first-column-styles}, @code{table:use-last-column-styles},
12761 @code{table:use-banding-rows-styles}, and
12762 @code{table:use-banding-column-styles} of the @code{<table:table>} element in
12763 the OpenDocument-v1.2 specification}
12765 @vindex org-odt-table-styles
12766 To define a table style, create an entry for the style in the variable
12767 @code{org-odt-table-styles} and specify the following:
12770 @item the name of the table template created in step (1)
12771 @item the set of cell styles in that template that are to be activated
12774 For example, the entry below defines two different table styles
12775 @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
12776 based on the same template @samp{Custom}. The styles achieve their intended
12777 effect by selectively activating the individual cell styles in that template.
12780 (setq org-odt-table-styles
12781 (append org-odt-table-styles
12782 '(("TableWithHeaderRowAndColumn" "Custom"
12783 ((use-first-row-styles . t)
12784 (use-first-column-styles . t)))
12785 ("TableWithFirstRowandLastRow" "Custom"
12786 ((use-first-row-styles . t)
12787 (use-last-row-styles . t))))))
12791 Associate a table with the table style
12793 To do this, specify the table style created in step (2) as part of
12794 the @code{ATTR_ODT} line as shown below.
12797 #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
12798 | Name | Phone | Age |
12799 | Peter | 1234 | 17 |
12800 | Anna | 4321 | 25 |
12804 @node Validating OpenDocument XML
12805 @subsubheading Validating OpenDocument XML
12807 Occasionally, you will discover that the document created by the
12808 ODT exporter cannot be opened by your favorite application. One of
12809 the common reasons for this is that the @file{.odt} file is corrupt. In such
12810 cases, you may want to validate the document against the OpenDocument RELAX
12811 NG Compact Syntax (RNC) schema.
12813 For de-compressing the @file{.odt} file@footnote{@file{.odt} files are
12814 nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}. For
12815 general help with validation (and schema-sensitive editing) of XML files:
12816 @inforef{Introduction,,nxml-mode}.
12818 @vindex org-odt-schema-dir
12819 If you have ready access to OpenDocument @file{.rnc} files and the needed
12820 schema-locating rules in a single folder, you can customize the variable
12821 @code{org-odt-schema-dir} to point to that directory. The ODT exporter
12822 will take care of updating the @code{rng-schema-locating-files} for you.
12824 @c end opendocument
12827 @section Org export
12830 @code{org} export back-end creates a normalized version of the Org document
12831 in current buffer. In particular, it evaluates Babel code (@pxref{Evaluating
12832 code blocks}) and removes other back-ends specific contents.
12834 @subheading Org export commands
12837 @orgcmd{C-c C-e O o,org-org-export-to-org}
12838 Export as an Org document. For an Org file, @file{myfile.org}, the resulting
12839 file will be @file{myfile.org.org}. The file will be overwritten without
12841 @orgcmd{C-c C-e O O,org-org-export-as-org}
12842 Export to a temporary buffer. Do not create a file.
12844 Export to an Org file, then open it.
12847 @node iCalendar export
12848 @section iCalendar export
12849 @cindex iCalendar export
12851 @vindex org-icalendar-include-todo
12852 @vindex org-icalendar-use-deadline
12853 @vindex org-icalendar-use-scheduled
12854 @vindex org-icalendar-categories
12855 @vindex org-icalendar-alarm-time
12856 Some people use Org mode for keeping track of projects, but still prefer a
12857 standard calendar application for anniversaries and appointments. In this
12858 case it can be useful to show deadlines and other time-stamped items in Org
12859 files in the calendar application. Org mode can export calendar information
12860 in the standard iCalendar format. If you also want to have TODO entries
12861 included in the export, configure the variable
12862 @code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT,
12863 and TODO items as VTODO@. It will also create events from deadlines that are
12864 in non-TODO items. Deadlines and scheduling dates in TODO items will be used
12865 to set the start and due dates for the TODO entry@footnote{See the variables
12866 @code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}.
12867 As categories, it will use the tags locally defined in the heading, and the
12868 file/tree category@footnote{To add inherited tags or the TODO state,
12869 configure the variable @code{org-icalendar-categories}.}. See the variable
12870 @code{org-icalendar-alarm-time} for a way to assign alarms to entries with a
12873 @vindex org-icalendar-store-UID
12874 @cindex property, ID
12875 The iCalendar standard requires each entry to have a globally unique
12876 identifier (UID). Org creates these identifiers during export. If you set
12877 the variable @code{org-icalendar-store-UID}, the UID will be stored in the
12878 @code{:ID:} property of the entry and re-used next time you report this
12879 entry. Since a single entry can give rise to multiple iCalendar entries (as
12880 a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds
12881 prefixes to the UID, depending on what triggered the inclusion of the entry.
12882 In this way the UID remains unique, but a synchronization program can still
12883 figure out from which entry all the different instances originate.
12886 @orgcmd{C-c C-e c f,org-icalendar-export-to-ics}
12887 Create iCalendar entries for the current buffer and store them in the same
12888 directory, using a file extension @file{.ics}.
12889 @orgcmd{C-c C-e c a, org-icalendar-export-agenda-files}
12890 @vindex org-agenda-files
12891 Like @kbd{C-c C-e c f}, but do this for all files in
12892 @code{org-agenda-files}. For each of these files, a separate iCalendar
12893 file will be written.
12894 @orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files}
12895 @vindex org-icalendar-combined-agenda-file
12896 Create a single large iCalendar file from all files in
12897 @code{org-agenda-files} and write it to the file given by
12898 @code{org-icalendar-combined-agenda-file}.
12901 @vindex org-use-property-inheritance
12902 @vindex org-icalendar-include-body
12903 @cindex property, SUMMARY
12904 @cindex property, DESCRIPTION
12905 @cindex property, LOCATION
12906 The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION
12907 property can be inherited from higher in the hierarchy if you configure
12908 @code{org-use-property-inheritance} accordingly.} properties if the selected
12909 entries have them. If not, the summary will be derived from the headline,
12910 and the description from the body (limited to
12911 @code{org-icalendar-include-body} characters).
12913 How this calendar is best read and updated, depends on the application
12914 you are using. The FAQ covers this issue.
12916 @node Other built-in back-ends
12917 @section Other built-in back-ends
12918 @cindex export back-ends, built-in
12919 @vindex org-export-backends
12921 On top of the aforementioned back-ends, Org comes with other built-in ones:
12924 @item @file{ox-man.el}: export to a man page.
12925 @item @file{ox-texinfo.el}: export to @code{Texinfo} format.
12928 To activate these export back-ends, customize @code{org-export-backends} or
12929 load them directly with e.g., @code{(require 'ox-texinfo)}. This will add
12930 new keys in the export dispatcher (@pxref{The export dispatcher}).
12932 See the comment section of these files for more information on how to use
12935 @node Export in foreign buffers
12936 @section Export in foreign buffers
12938 Most built-in back-ends come with a command to convert the selected region
12939 into a selected format and replace this region by the exported output. Here
12940 is a list of such conversion commands:
12943 @item org-html-convert-region-to-html
12944 Convert the selected region into HTML.
12945 @item org-latex-convert-region-to-latex
12946 Convert the selected region into @LaTeX{}.
12947 @item org-texinfo-convert-region-to-texinfo
12948 Convert the selected region into @code{Texinfo}.
12949 @item org-md-convert-region-to-md
12950 Convert the selected region into @code{MarkDown}.
12953 This is particularly useful for converting tables and lists in foreign
12954 buffers. E.g., in an HTML buffer, you can turn on @code{orgstruct-mode}, then
12955 use Org commands for editing a list, and finally select and convert the list
12956 with @code{M-x org-html-convert-region-to-html RET}.
12958 @node Advanced configuration
12959 @section Advanced configuration
12963 @vindex org-export-before-processing-hook
12964 @vindex org-export-before-parsing-hook
12965 Two hooks are run during the first steps of the export process. The first
12966 one, @code{org-export-before-processing-hook} is called before expanding
12967 macros, Babel code and include keywords in the buffer. The second one,
12968 @code{org-export-before-parsing-hook}, as its name suggests, happens just
12969 before parsing the buffer. Their main use is for heavy duties, that is
12970 duties involving structural modifications of the document. For example, one
12971 may want to remove every headline in the buffer during export. The following
12972 code can achieve this:
12976 (defun my-headline-removal (backend)
12977 "Remove all headlines in the current buffer.
12978 BACKEND is the export back-end being used, as a symbol."
12980 (lambda () (delete-region (point) (progn (forward-line) (point))))))
12982 (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
12986 Note that functions used in these hooks require a mandatory argument,
12987 a symbol representing the back-end used.
12989 @subheading Filters
12991 @cindex Filters, exporting
12992 Filters are lists of functions applied on a specific part of the output from
12993 a given back-end. More explicitly, each time a back-end transforms an Org
12994 object or element into another language, all functions within a given filter
12995 type are called in turn on the string produced. The string returned by the
12996 last function will be the one used in the final output.
12998 There are filter sets for each type of element or object, for plain text,
12999 for the parse tree, for the export options and for the final output. They
13000 are all named after the same scheme: @code{org-export-filter-TYPE-functions},
13001 where @code{TYPE} is the type targeted by the filter. Valid types are:
13003 @multitable @columnfractions .33 .33 .33
13010 @item comment-block
13013 @item dynamic-block
13017 @tab export-snippet
13020 @tab footnote-definition
13021 @tab footnote-reference
13023 @tab horizontal-rule
13024 @tab inline-babel-call
13025 @item inline-src-block
13030 @tab latex-environment
13031 @item latex-fragment
13034 @item node-property
13041 @tab property-drawer
13043 @item quote-section
13046 @item special-block
13048 @tab statistics-cookie
13049 @item strike-through
13063 For example, the following snippet allows me to use non-breaking spaces in
13064 the Org buffer and get them translated into @LaTeX{} without using the
13065 @code{\nbsp} macro (where @code{_} stands for the non-breaking space):
13069 (defun my-latex-filter-nobreaks (text backend info)
13070 "Ensure \"Â \" are properly handled in LaTeX export."
13071 (when (org-export-derived-backend-p backend 'latex)
13072 (replace-regexp-in-string "Â " "~" text)))
13074 (add-to-list 'org-export-filter-plain-text-functions
13075 'my-latex-filter-nobreaks)
13079 Three arguments must be provided to a filter: the code being changed, the
13080 back-end used, and some information about the export process. You can safely
13081 ignore the third argument for most purposes. Note the use of
13082 @code{org-export-derived-backend-p}, which ensures that the filter will only
13083 be applied when using @code{latex} back-end or any other back-end derived
13084 from it (e.g., @code{beamer}).
13086 @subheading Defining filters for individual files
13088 You can customize the export for just a specific file by binding export
13089 filter variables using @code{#+BIND}. Here is an example where we introduce
13090 two filters, one to remove brackets from time stamps, and one to entirely
13091 remove any strike-through text. The functions doing the filtering are
13092 defined in an src block that allows the filter function definitions to exist
13093 in the file itself and ensures that the functions will be there when needed.
13096 #+BIND: org-export-filter-timestamp-functions (tmp-f-timestamp)
13097 #+BIND: org-export-filter-strike-through-functions (tmp-f-strike-through)
13098 #+begin_src emacs-lisp :exports results :results none
13099 (defun tmp-f-timestamp (s backend info)
13100 (replace-regexp-in-string "&[lg]t;\\|[][]" "" s))
13101 (defun tmp-f-strike-through (s backend info) "")
13105 @subheading Extending an existing back-end
13107 This is obviously the most powerful customization, since the changes happen
13108 at the parser level. Indeed, some export back-ends are built as extensions
13109 of other ones (e.g. Markdown back-end an extension of HTML back-end).
13111 Extending a back-end means that if an element type is not transcoded by the
13112 new back-end, it will be handled by the original one. Hence you can extend
13113 specific parts of a back-end without too much work.
13115 As an example, imagine we want the @code{ascii} back-end to display the
13116 language used in a source block, when it is available, but only when some
13117 attribute is non-@code{nil}, like the following:
13120 #+ATTR_ASCII: :language t
13123 Because that back-end is lacking in that area, we are going to create a new
13124 back-end, @code{my-ascii} that will do the job.
13128 (defun my-ascii-src-block (src-block contents info)
13129 "Transcode a SRC-BLOCK element from Org to ASCII.
13130 CONTENTS is nil. INFO is a plist used as a communication
13132 (if (not (org-export-read-attribute :attr_ascii src-block :language))
13133 (org-export-with-backend 'ascii src-block contents info)
13135 (format ",--[ %s ]--\n%s`----"
13136 (org-element-property :language src-block)
13137 (replace-regexp-in-string
13139 (org-element-normalize-string
13140 (org-export-format-code-default src-block info)))))))
13142 (org-export-define-derived-backend 'my-ascii 'ascii
13143 :translate-alist '((src-block . my-ascii-src-block)))
13147 The @code{my-ascii-src-block} function looks at the attribute above the
13148 element. If it isn't true, it gives hand to the @code{ascii} back-end.
13149 Otherwise, it creates a box around the code, leaving room for the language.
13150 A new back-end is then created. It only changes its behavior when
13151 translating @code{src-block} type element. Now, all it takes to use the new
13152 back-end is calling the following from an Org buffer:
13155 (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
13158 It is obviously possible to write an interactive function for this, install
13159 it in the export dispatcher menu, and so on.
13163 @chapter Publishing
13166 Org includes a publishing management system that allows you to configure
13167 automatic HTML conversion of @emph{projects} composed of interlinked org
13168 files. You can also configure Org to automatically upload your exported HTML
13169 pages and related attachments, such as images and source code files, to a web
13172 You can also use Org to convert files into PDF, or even combine HTML and PDF
13173 conversion so that files are available in both formats on the server.
13175 Publishing has been contributed to Org by David O'Toole.
13178 * Configuration:: Defining projects
13179 * Uploading files:: How to get files up on the server
13180 * Sample configuration:: Example projects
13181 * Triggering publication:: Publication commands
13184 @node Configuration
13185 @section Configuration
13187 Publishing needs significant configuration to specify files, destination
13188 and many other properties of a project.
13191 * Project alist:: The central configuration variable
13192 * Sources and destinations:: From here to there
13193 * Selecting files:: What files are part of the project?
13194 * Publishing action:: Setting the function doing the publishing
13195 * Publishing options:: Tweaking HTML/@LaTeX{} export
13196 * Publishing links:: Which links keep working after publishing?
13197 * Sitemap:: Generating a list of all pages
13198 * Generating an index:: An index that reaches across pages
13201 @node Project alist
13202 @subsection The variable @code{org-publish-project-alist}
13203 @cindex org-publish-project-alist
13204 @cindex projects, for publishing
13206 @vindex org-publish-project-alist
13207 Publishing is configured almost entirely through setting the value of one
13208 variable, called @code{org-publish-project-alist}. Each element of the list
13209 configures one project, and may be in one of the two following forms:
13212 ("project-name" :property value :property value ...)
13213 @r{i.e., a well-formed property list with alternating keys and values}
13215 ("project-name" :components ("project-name" "project-name" ...))
13219 In both cases, projects are configured by specifying property values. A
13220 project defines the set of files that will be published, as well as the
13221 publishing configuration to use when publishing those files. When a project
13222 takes the second form listed above, the individual members of the
13223 @code{:components} property are taken to be sub-projects, which group
13224 together files requiring different publishing options. When you publish such
13225 a ``meta-project'', all the components will also be published, in the
13228 @node Sources and destinations
13229 @subsection Sources and destinations for files
13230 @cindex directories, for publishing
13232 Most properties are optional, but some should always be set. In
13233 particular, Org needs to know where to look for source files,
13234 and where to put published files.
13236 @multitable @columnfractions 0.3 0.7
13237 @item @code{:base-directory}
13238 @tab Directory containing publishing source files
13239 @item @code{:publishing-directory}
13240 @tab Directory where output files will be published. You can directly
13241 publish to a web server using a file name syntax appropriate for
13242 the Emacs @file{tramp} package. Or you can publish to a local directory and
13243 use external tools to upload your website (@pxref{Uploading files}).
13244 @item @code{:preparation-function}
13245 @tab Function or list of functions to be called before starting the
13246 publishing process, for example, to run @code{make} for updating files to be
13247 published. The project property list is scoped into this call as the
13248 variable @code{project-plist}.
13249 @item @code{:completion-function}
13250 @tab Function or list of functions called after finishing the publishing
13251 process, for example, to change permissions of the resulting files. The
13252 project property list is scoped into this call as the variable
13253 @code{project-plist}.
13257 @node Selecting files
13258 @subsection Selecting files
13259 @cindex files, selecting for publishing
13261 By default, all files with extension @file{.org} in the base directory
13262 are considered part of the project. This can be modified by setting the
13264 @multitable @columnfractions 0.25 0.75
13265 @item @code{:base-extension}
13266 @tab Extension (without the dot!) of source files. This actually is a
13267 regular expression. Set this to the symbol @code{any} if you want to get all
13268 files in @code{:base-directory}, even without extension.
13270 @item @code{:exclude}
13271 @tab Regular expression to match file names that should not be
13272 published, even though they have been selected on the basis of their
13275 @item @code{:include}
13276 @tab List of files to be included regardless of @code{:base-extension}
13277 and @code{:exclude}.
13279 @item @code{:recursive}
13280 @tab non-@code{nil} means, check base-directory recursively for files to publish.
13283 @node Publishing action
13284 @subsection Publishing action
13285 @cindex action, for publishing
13287 Publishing means that a file is copied to the destination directory and
13288 possibly transformed in the process. The default transformation is to export
13289 Org files as HTML files, and this is done by the function
13290 @code{org-html-publish-to-html}, which calls the HTML exporter (@pxref{HTML
13291 export}). But you also can publish your content as PDF files using
13292 @code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc.,
13293 using the corresponding functions.
13295 If you want to publish the Org file as an @code{.org} file but with the
13296 @i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the
13297 function @code{org-org-publish-to-org}. This will produce @file{file.org}
13298 and put it in the publishing directory. If you want a htmlized version of
13299 this file, set the parameter @code{:htmlized-source} to @code{t}, it will
13300 produce @file{file.org.html} in the publishing directory@footnote{If the
13301 publishing directory is the same than the source directory, @file{file.org}
13302 will be exported as @file{file.org.org}, so probably don't want to do this.}.
13304 Other files like images only need to be copied to the publishing destination.
13305 For this you can use @code{org-publish-attachment}. For non-org files, you
13306 always need to specify the publishing function:
13308 @multitable @columnfractions 0.3 0.7
13309 @item @code{:publishing-function}
13310 @tab Function executing the publication of a file. This may also be a
13311 list of functions, which will all be called in turn.
13312 @item @code{:htmlized-source}
13313 @tab non-@code{nil} means, publish htmlized source.
13316 The function must accept three arguments: a property list containing at least
13317 a @code{:publishing-directory} property, the name of the file to be published
13318 and the path to the publishing directory of the output file. It should take
13319 the specified file, make the necessary transformation (if any) and place the
13320 result into the destination folder.
13322 @node Publishing options
13323 @subsection Options for the exporters
13324 @cindex options, for publishing
13326 The property list can be used to set many export options for the exporters.
13327 In most cases, these properties correspond to user variables in Org. The
13328 first table below lists these properties along with the variable they belong
13329 to. The second table list HTML specific properties. See the documentation
13330 string of these options for details.
13332 @vindex org-display-custom-times
13333 @vindex org-export-default-language
13334 @vindex org-export-exclude-tags
13335 @vindex org-export-headline-levels
13336 @vindex org-export-preserve-breaks
13337 @vindex org-export-publishing-directory
13338 @vindex org-export-select-tags
13339 @vindex org-export-with-archived-trees
13340 @vindex org-export-with-author
13341 @vindex org-export-with-creator
13342 @vindex org-export-with-drawers
13343 @vindex org-export-with-email
13344 @vindex org-export-with-emphasize
13345 @vindex org-export-with-fixed-width
13346 @vindex org-export-with-footnotes
13347 @vindex org-export-with-latex
13348 @vindex org-export-with-planning
13349 @vindex org-export-with-priority
13350 @vindex org-export-with-properties
13351 @vindex org-export-with-section-numbers
13352 @vindex org-export-with-special-strings
13353 @vindex org-export-with-sub-superscripts
13354 @vindex org-export-with-tables
13355 @vindex org-export-with-tags
13356 @vindex org-export-with-tasks
13357 @vindex org-export-with-timestamps
13358 @vindex org-export-with-toc
13359 @vindex org-export-with-todo-keywords
13360 @vindex user-mail-address
13361 @multitable @columnfractions 0.32 0.68
13362 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
13363 @item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
13364 @item @code{:headline-levels} @tab @code{org-export-headline-levels}
13365 @item @code{:language} @tab @code{org-export-default-language}
13366 @item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}
13367 @item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
13368 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
13369 @item @code{:select-tags} @tab @code{org-export-select-tags}
13370 @item @code{:with-author} @tab @code{org-export-with-author}
13371 @item @code{:with-creator} @tab @code{org-export-with-creator}
13372 @item @code{:with-drawers} @tab @code{org-export-with-drawers}
13373 @item @code{:with-email} @tab @code{org-export-with-email}
13374 @item @code{:with-emphasize} @tab @code{org-export-with-emphasize}
13375 @item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width}
13376 @item @code{:with-footnotes} @tab @code{org-export-with-footnotes}
13377 @item @code{:with-latex} @tab @code{org-export-with-latex}
13378 @item @code{:with-planning} @tab @code{org-export-with-planning}
13379 @item @code{:with-priority} @tab @code{org-export-with-priority}
13380 @item @code{:with-properties} @tab @code{org-export-with-properties}
13381 @item @code{:with-special-strings} @tab @code{org-export-with-special-strings}
13382 @item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts}
13383 @item @code{:with-tables} @tab @code{org-export-with-tables}
13384 @item @code{:with-tags} @tab @code{org-export-with-tags}
13385 @item @code{:with-tasks} @tab @code{org-export-with-tasks}
13386 @item @code{:with-timestamps} @tab @code{org-export-with-timestamps}
13387 @item @code{:with-toc} @tab @code{org-export-with-toc}
13388 @item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords}
13391 @vindex org-html-doctype
13392 @vindex org-html-container-element
13393 @vindex org-html-html5-fancy
13394 @vindex org-html-xml-declaration
13395 @vindex org-html-link-up
13396 @vindex org-html-link-home
13397 @vindex org-html-link-org-files-as-html
13398 @vindex org-html-link-use-abs-url
13399 @vindex org-html-head
13400 @vindex org-html-head-extra
13401 @vindex org-html-inline-images
13402 @vindex org-html-extension
13403 @vindex org-html-preamble
13404 @vindex org-html-postamble
13405 @vindex org-html-table-default-attributes
13406 @vindex org-html-table-row-tags
13407 @vindex org-html-head-include-default-style
13408 @vindex org-html-head-include-scripts
13409 @multitable @columnfractions 0.32 0.68
13410 @item @code{:html-doctype} @tab @code{org-html-doctype}
13411 @item @code{:html-container} @tab @code{org-html-container-element}
13412 @item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy}
13413 @item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration}
13414 @item @code{:html-link-up} @tab @code{org-html-link-up}
13415 @item @code{:html-link-home} @tab @code{org-html-link-home}
13416 @item @code{:html-link-org-as-html} @tab @code{org-html-link-org-files-as-html}
13417 @item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url}
13418 @item @code{:html-head} @tab @code{org-html-head}
13419 @item @code{:html-head-extra} @tab @code{org-html-head-extra}
13420 @item @code{:html-inline-images} @tab @code{org-html-inline-images}
13421 @item @code{:html-extension} @tab @code{org-html-extension}
13422 @item @code{:html-preamble} @tab @code{org-html-preamble}
13423 @item @code{:html-postamble} @tab @code{org-html-postamble}
13424 @item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
13425 @item @code{:html-table-row-tags} @tab @code{org-html-table-row-tags}
13426 @item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style}
13427 @item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts}
13430 Most of the @code{org-export-with-*} variables have the same effect in each
13433 @vindex org-publish-project-alist
13434 When a property is given a value in @code{org-publish-project-alist}, its
13435 setting overrides the value of the corresponding user variable (if any)
13436 during publishing. Options set within a file (@pxref{Export settings}),
13437 however, override everything.
13439 @node Publishing links
13440 @subsection Links between published files
13441 @cindex links, publishing
13443 To create a link from one Org file to another, you would use something like
13444 @samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org.}
13445 (@pxref{Hyperlinks}). When published, this link becomes a link to
13446 @file{foo.html}. You can thus interlink the pages of your "org web" project
13447 and the links will work as expected when you publish them to HTML@. If you
13448 also publish the Org source file and want to link to it, use an @code{http:}
13449 link instead of a @code{file:} link, because @code{file:} links are converted
13450 to link to the corresponding @file{html} file.
13452 You may also link to related files, such as images. Provided you are careful
13453 with relative file names, and provided you have also configured Org to upload
13454 the related files, these links will work too. See @ref{Complex example}, for
13455 an example of this usage.
13458 @subsection Generating a sitemap
13459 @cindex sitemap, of published pages
13461 The following properties may be used to control publishing of
13462 a map of files for a given project.
13464 @multitable @columnfractions 0.35 0.65
13465 @item @code{:auto-sitemap}
13466 @tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project}
13467 or @code{org-publish-all}.
13469 @item @code{:sitemap-filename}
13470 @tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which
13471 becomes @file{sitemap.html}).
13473 @item @code{:sitemap-title}
13474 @tab Title of sitemap page. Defaults to name of file.
13476 @item @code{:sitemap-function}
13477 @tab Plug-in function to use for generation of the sitemap.
13478 Defaults to @code{org-publish-org-sitemap}, which generates a plain list
13479 of links to all files in the project.
13481 @item @code{:sitemap-sort-folders}
13482 @tab Where folders should appear in the sitemap. Set this to @code{first}
13483 (default) or @code{last} to display folders first or last,
13484 respectively. Any other value will mix files and folders.
13486 @item @code{:sitemap-sort-files}
13487 @tab How the files are sorted in the site map. Set this to
13488 @code{alphabetically} (default), @code{chronologically} or
13489 @code{anti-chronologically}. @code{chronologically} sorts the files with
13490 older date first while @code{anti-chronologically} sorts the files with newer
13491 date first. @code{alphabetically} sorts the files alphabetically. The date of
13492 a file is retrieved with @code{org-publish-find-date}.
13494 @item @code{:sitemap-ignore-case}
13495 @tab Should sorting be case-sensitive? Default @code{nil}.
13497 @item @code{:sitemap-file-entry-format}
13498 @tab With this option one can tell how a sitemap's entry is formatted in the
13499 sitemap. This is a format string with some escape sequences: @code{%t} stands
13500 for the title of the file, @code{%a} stands for the author of the file and
13501 @code{%d} stands for the date of the file. The date is retrieved with the
13502 @code{org-publish-find-date} function and formatted with
13503 @code{org-publish-sitemap-date-format}. Default @code{%t}.
13505 @item @code{:sitemap-date-format}
13506 @tab Format string for the @code{format-time-string} function that tells how
13507 a sitemap entry's date is to be formatted. This property bypasses
13508 @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
13510 @item @code{:sitemap-sans-extension}
13511 @tab When non-@code{nil}, remove filenames' extensions from the generated sitemap.
13512 Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}).
13513 Defaults to @code{nil}.
13517 @node Generating an index
13518 @subsection Generating an index
13519 @cindex index, in a publishing project
13521 Org mode can generate an index across the files of a publishing project.
13523 @multitable @columnfractions 0.25 0.75
13524 @item @code{:makeindex}
13525 @tab When non-@code{nil}, generate in index in the file @file{theindex.org} and
13526 publish it as @file{theindex.html}.
13529 The file will be created when first publishing a project with the
13530 @code{:makeindex} set. The file only contains a statement @code{#+INCLUDE:
13531 "theindex.inc"}. You can then build around this include statement by adding
13532 a title, style information, etc.
13534 @node Uploading files
13535 @section Uploading files
13539 For those people already utilizing third party sync tools such as
13540 @command{rsync} or @command{unison}, it might be preferable not to use the built in
13541 @i{remote} publishing facilities of Org mode which rely heavily on
13542 Tramp. Tramp, while very useful and powerful, tends not to be
13543 so efficient for multiple file transfer and has been known to cause problems
13546 Specialized synchronization utilities offer several advantages. In addition
13547 to timestamp comparison, they also do content and permissions/attribute
13548 checks. For this reason you might prefer to publish your web to a local
13549 directory (possibly even @i{in place} with your Org files) and then use
13550 @file{unison} or @file{rsync} to do the synchronization with the remote host.
13552 Since Unison (for example) can be configured as to which files to transfer to
13553 a certain remote destination, it can greatly simplify the project publishing
13554 definition. Simply keep all files in the correct location, process your Org
13555 files with @code{org-publish} and let the synchronization tool do the rest.
13556 You do not need, in this scenario, to include attachments such as @file{jpg},
13557 @file{css} or @file{gif} files in the project definition since the 3rd party
13560 Publishing to a local directory is also much faster than to a remote one, so
13561 that you can afford more easily to republish entire projects. If you set
13562 @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
13563 benefit of re-including any changed external files such as source example
13564 files you might include with @code{#+INCLUDE:}. The timestamp mechanism in
13565 Org is not smart enough to detect if included files have been modified.
13567 @node Sample configuration
13568 @section Sample configuration
13570 Below we provide two example configurations. The first one is a simple
13571 project publishing only a set of Org files. The second example is
13572 more complex, with a multi-component project.
13575 * Simple example:: One-component publishing
13576 * Complex example:: A multi-component publishing example
13579 @node Simple example
13580 @subsection Example: simple publishing configuration
13582 This example publishes a set of Org files to the @file{public_html}
13583 directory on the local machine.
13586 (setq org-publish-project-alist
13588 :base-directory "~/org/"
13589 :publishing-directory "~/public_html"
13590 :section-numbers nil
13592 :html-head "<link rel=\"stylesheet\"
13593 href=\"../other/mystyle.css\"
13594 type=\"text/css\"/>")))
13597 @node Complex example
13598 @subsection Example: complex publishing configuration
13600 This more complicated example publishes an entire website, including
13601 Org files converted to HTML, image files, Emacs Lisp source code, and
13602 style sheets. The publishing directory is remote and private files are
13605 To ensure that links are preserved, care should be taken to replicate
13606 your directory structure on the web server, and to use relative file
13607 paths. For example, if your Org files are kept in @file{~/org} and your
13608 publishable images in @file{~/images}, you would link to an image with
13611 file:../images/myimage.png
13614 On the web server, the relative path to the image should be the
13615 same. You can accomplish this by setting up an "images" folder in the
13616 right place on the web server, and publishing images to it.
13619 (setq org-publish-project-alist
13621 :base-directory "~/org/"
13622 :base-extension "org"
13623 :publishing-directory "/ssh:user@@host:~/html/notebook/"
13624 :publishing-function org-html-publish-to-html
13625 :exclude "PrivatePage.org" ;; regexp
13627 :section-numbers nil
13629 :html-head "<link rel=\"stylesheet\"
13630 href=\"../other/mystyle.css\" type=\"text/css\"/>"
13634 :base-directory "~/images/"
13635 :base-extension "jpg\\|gif\\|png"
13636 :publishing-directory "/ssh:user@@host:~/html/images/"
13637 :publishing-function org-publish-attachment)
13640 :base-directory "~/other/"
13641 :base-extension "css\\|el"
13642 :publishing-directory "/ssh:user@@host:~/html/other/"
13643 :publishing-function org-publish-attachment)
13644 ("website" :components ("orgfiles" "images" "other"))))
13647 @node Triggering publication
13648 @section Triggering publication
13650 Once properly configured, Org can publish with the following commands:
13653 @orgcmd{C-c C-e P x,org-publish}
13654 Prompt for a specific project and publish all files that belong to it.
13655 @orgcmd{C-c C-e P p,org-publish-current-project}
13656 Publish the project containing the current file.
13657 @orgcmd{C-c C-e P f,org-publish-current-file}
13658 Publish only the current file.
13659 @orgcmd{C-c C-e P a,org-publish-all}
13660 Publish every project.
13663 @vindex org-publish-use-timestamps-flag
13664 Org uses timestamps to track when a file has changed. The above functions
13665 normally only publish changed files. You can override this and force
13666 publishing of all files by giving a prefix argument to any of the commands
13667 above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
13668 This may be necessary in particular if files include other files via
13669 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
13672 @node Working with source code
13673 @chapter Working with source code
13674 @cindex Schulte, Eric
13675 @cindex Davison, Dan
13676 @cindex source code, working with
13678 Source code can be included in Org mode documents using a @samp{src} block,
13682 #+BEGIN_SRC emacs-lisp
13683 (defun org-xor (a b)
13689 Org mode provides a number of features for working with live source code,
13690 including editing of code blocks in their native major-mode, evaluation of
13691 code blocks, converting code blocks into source files (known as @dfn{tangling}
13692 in literate programming), and exporting code blocks and their
13693 results in several formats. This functionality was contributed by Eric
13694 Schulte and Dan Davison, and was originally named Org-babel.
13696 The following sections describe Org mode's code block handling facilities.
13699 * Structure of code blocks:: Code block syntax described
13700 * Editing source code:: Language major-mode editing
13701 * Exporting code blocks:: Export contents and/or results
13702 * Extracting source code:: Create pure source code files
13703 * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
13704 * Library of Babel:: Use and contribute to a library of useful code blocks
13705 * Languages:: List of supported code block languages
13706 * Header arguments:: Configure code block functionality
13707 * Results of evaluation:: How evaluation results are handled
13708 * Noweb reference syntax:: Literate programming in Org mode
13709 * Key bindings and useful functions:: Work quickly with code blocks
13710 * Batch execution:: Call functions from the command line
13714 @node Structure of code blocks
13715 @section Structure of code blocks
13716 @cindex code block, structure
13717 @cindex source code, block structure
13719 @cindex #+BEGIN_SRC
13721 Live code blocks can be specified with a @samp{src} block or
13722 inline.@footnote{Note that @samp{src} blocks may be inserted using Org mode's
13723 @ref{Easy templates} system} The structure of a @samp{src} block is
13727 #+BEGIN_SRC <language> <switches> <header arguments>
13732 The @code{#+NAME:} line is optional, and can be used to name the code
13733 block. Live code blocks require that a language be specified on the
13734 @code{#+BEGIN_SRC} line. Switches and header arguments are optional.
13735 @cindex source code, inline
13737 Live code blocks can also be specified inline using
13740 src_<language>@{<body>@}
13746 src_<language>[<header arguments>]@{<body>@}
13750 @item <#+NAME: name>
13751 This line associates a name with the code block. This is similar to the
13752 @code{#+NAME: Name} lines that can be used to name tables in Org mode
13753 files. Referencing the name of a code block makes it possible to evaluate
13754 the block from other places in the file, from other files, or from Org mode
13755 table formulas (see @ref{The spreadsheet}). Names are assumed to be unique
13756 and the behavior of Org mode when two or more blocks share the same name is
13760 The language of the code in the block (see @ref{Languages}).
13761 @cindex source code, language
13763 Optional switches control code block export (see the discussion of switches in
13764 @ref{Literal examples})
13765 @cindex source code, switches
13766 @item <header arguments>
13767 Optional header arguments control many aspects of evaluation, export and
13768 tangling of code blocks (see @ref{Header arguments}).
13769 Header arguments can also be set on a per-buffer or per-subtree
13770 basis using properties.
13771 @item source code, header arguments
13773 Source code in the specified language.
13777 @node Editing source code
13778 @section Editing source code
13779 @cindex code block, editing
13780 @cindex source code, editing
13782 @vindex org-edit-src-auto-save-idle-delay
13783 @vindex org-edit-src-turn-on-auto-save
13785 Use @kbd{C-c '} to edit the current code block. This brings up a language
13786 major-mode edit buffer containing the body of the code block. Manually
13787 saving this buffer with @key{C-x C-s} will write the contents back to the Org
13788 buffer. You can also set @code{org-edit-src-auto-save-idle-delay} to save the
13789 base buffer after some idle delay, or @code{org-edit-src-turn-on-auto-save}
13790 to auto-save this buffer into a separate file using @code{auto-save-mode}.
13791 Use @kbd{C-c '} again to exit.
13793 The @code{org-src-mode} minor mode will be active in the edit buffer. The
13794 following variables can be used to configure the behavior of the edit
13795 buffer. See also the customization group @code{org-edit-structure} for
13796 further configuration options.
13799 @item org-src-lang-modes
13800 If an Emacs major-mode named @code{<lang>-mode} exists, where
13801 @code{<lang>} is the language named in the header line of the code block,
13802 then the edit buffer will be placed in that major-mode. This variable
13803 can be used to map arbitrary language names to existing major modes.
13804 @item org-src-window-setup
13805 Controls the way Emacs windows are rearranged when the edit buffer is created.
13806 @item org-src-preserve-indentation
13807 This variable is especially useful for tangling languages such as
13808 Python, in which whitespace indentation in the output is critical.
13809 @item org-src-ask-before-returning-to-edit-buffer
13810 By default, Org will ask before returning to an open edit buffer. Set this
13811 variable to @code{nil} to switch without asking.
13814 To turn on native code fontification in the @emph{Org} buffer, configure the
13815 variable @code{org-src-fontify-natively}.
13818 @node Exporting code blocks
13819 @section Exporting code blocks
13820 @cindex code block, exporting
13821 @cindex source code, exporting
13823 It is possible to export the @emph{code} of code blocks, the @emph{results}
13824 of code block evaluation, @emph{both} the code and the results of code block
13825 evaluation, or @emph{none}. For most languages, the default exports code.
13826 However, for some languages (e.g., @code{ditaa}) the default exports the
13827 results of code block evaluation. For information on exporting code block
13828 bodies, see @ref{Literal examples}.
13830 The @code{:exports} header argument can be used to specify export
13833 @subsubheading Header arguments:
13836 @cindex @code{:exports}, src header argument
13837 @item :exports code
13838 The default in most languages. The body of the code block is exported, as
13839 described in @ref{Literal examples}.
13840 @item :exports results
13841 The code block will be evaluated each time to buffer is exported, and the
13842 results will be placed in the Org mode buffer for export, either updating
13843 previous results of the code block located anywhere in the buffer or, if no
13844 previous results exist, placing the results immediately after the code block.
13845 The body of the code block will not be exported.
13846 @item :exports both
13847 Both the code block and its results will be exported.
13848 @item :exports none
13849 Neither the code block nor its results will be exported.
13852 It is possible to inhibit the evaluation of code blocks during export.
13853 Setting the @code{org-export-babel-evaluate} variable to @code{nil} will
13854 ensure that no code blocks are evaluated as part of the export process. This
13855 can be useful in situations where potentially untrusted Org mode files are
13856 exported in an automated fashion, for example when Org mode is used as the
13857 markup language for a wiki. It is also possible to set this variable to
13858 @code{'inline-only}. In that case, only inline code blocks will be
13859 evaluated, in order to insert their results. Non-inline code blocks are
13860 assumed to have their results already inserted in the buffer by manual
13861 evaluation. This setting is useful to avoid expensive recalculations during
13862 export, not to provide security.
13865 @node Extracting source code
13866 @section Extracting source code
13868 @cindex source code, extracting
13869 @cindex code block, extracting source code
13871 Creating pure source code files by extracting code from source blocks is
13872 referred to as ``tangling''---a term adopted from the literate programming
13873 community. During ``tangling'' of code blocks their bodies are expanded
13874 using @code{org-babel-expand-src-block} which can expand both variable and
13875 ``noweb'' style references (see @ref{Noweb reference syntax}).
13877 @subsubheading Header arguments
13880 @cindex @code{:tangle}, src header argument
13882 The default. The code block is not included in the tangled output.
13884 Include the code block in the tangled output. The output file name is the
13885 name of the org file with the extension @samp{.org} replaced by the extension
13886 for the block language.
13887 @item :tangle filename
13888 Include the code block in the tangled output to file @samp{filename}.
13892 @subsubheading Functions
13895 @item org-babel-tangle
13896 Tangle the current file. Bound to @kbd{C-c C-v t}.
13898 With prefix argument only tangle the current code block.
13899 @item org-babel-tangle-file
13900 Choose a file to tangle. Bound to @kbd{C-c C-v f}.
13903 @subsubheading Hooks
13906 @item org-babel-post-tangle-hook
13907 This hook is run from within code files tangled by @code{org-babel-tangle}.
13908 Example applications could include post-processing, compilation or evaluation
13909 of tangled code files.
13912 @subsubheading Jumping between code and Org
13914 When tangling code from an Org-mode buffer to a source code file, you'll
13915 frequently find yourself viewing the file of tangled source code (e.g., many
13916 debuggers point to lines of the source code file). It is useful to be able
13917 to navigate from the tangled source to the Org-mode buffer from which the
13920 The @code{org-babel-tangle-jump-to-org} function provides this jumping from
13921 code to Org-mode functionality. Two header arguments are required for
13922 jumping to work, first the @code{padline} (@ref{padline}) option must be set
13923 to true (the default setting), second the @code{comments} (@ref{comments})
13924 header argument must be set to @code{links}, which will insert comments into
13925 the source code buffer which point back to the original Org-mode file.
13927 @node Evaluating code blocks
13928 @section Evaluating code blocks
13929 @cindex code block, evaluating
13930 @cindex source code, evaluating
13933 Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
13934 potential for that code to do harm. Org mode provides safeguards to ensure
13935 that code is only evaluated after explicit confirmation from the user. For
13936 information on these safeguards (and on how to disable them) see @ref{Code
13937 evaluation security}.} and the results of evaluation optionally placed in the
13938 Org mode buffer. The results of evaluation are placed following a line that
13939 begins by default with @code{#+RESULTS} and optionally a cache identifier
13940 and/or the name of the evaluated code block. The default value of
13941 @code{#+RESULTS} can be changed with the customizable variable
13942 @code{org-babel-results-keyword}.
13944 By default, the evaluation facility is only enabled for Lisp code blocks
13945 specified as @code{emacs-lisp}. However, source code blocks in many languages
13946 can be evaluated within Org mode (see @ref{Languages} for a list of supported
13947 languages and @ref{Structure of code blocks} for information on the syntax
13948 used to define a code block).
13951 There are a number of ways to evaluate code blocks. The simplest is to press
13952 @kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The
13953 option @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used to remove code
13954 evaluation from the @kbd{C-c C-c} key binding.}. This will call the
13955 @code{org-babel-execute-src-block} function to evaluate the block and insert
13956 its results into the Org mode buffer.
13959 It is also possible to evaluate named code blocks from anywhere in an Org
13960 mode buffer or an Org mode table. Live code blocks located in the current
13961 Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel})
13962 can be executed. Named code blocks can be executed with a separate
13963 @code{#+CALL:} line or inline within a block of text.
13965 The syntax of the @code{#+CALL:} line is
13968 #+CALL: <name>(<arguments>)
13969 #+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
13972 The syntax for inline evaluation of named code blocks is
13975 ... call_<name>(<arguments>) ...
13976 ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
13981 The name of the code block to be evaluated (see @ref{Structure of code blocks}).
13983 Arguments specified in this section will be passed to the code block. These
13984 arguments use standard function call syntax, rather than
13985 header argument syntax. For example, a @code{#+CALL:} line that passes the
13986 number four to a code block named @code{double}, which declares the header
13987 argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}.
13988 @item <inside header arguments>
13989 Inside header arguments are passed through and applied to the named code
13990 block. These arguments use header argument syntax rather than standard
13991 function call syntax. Inside header arguments affect how the code block is
13992 evaluated. For example, @code{[:results output]} will collect the results of
13993 everything printed to @code{STDOUT} during execution of the code block.
13994 @item <end header arguments>
13995 End header arguments are applied to the calling instance and do not affect
13996 evaluation of the named code block. They affect how the results are
13997 incorporated into the Org mode buffer and how the call line is exported. For
13998 example, @code{:results html} will insert the results of the call line
13999 evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block.
14001 For more examples of passing header arguments to @code{#+CALL:} lines see
14002 @ref{Header arguments in function calls}.
14005 @node Library of Babel
14006 @section Library of Babel
14007 @cindex babel, library of
14008 @cindex source code, library
14009 @cindex code block, library
14011 The ``Library of Babel'' consists of code blocks that can be called from any
14012 Org mode file. Code blocks defined in the ``Library of Babel'' can be called
14013 remotely as if they were in the current Org mode buffer (see @ref{Evaluating
14014 code blocks} for information on the syntax of remote code block evaluation).
14017 The central repository of code blocks in the ``Library of Babel'' is housed
14018 in an Org mode file located in the @samp{contrib} directory of Org mode.
14020 Users can add code blocks they believe to be generally useful to their
14021 ``Library of Babel.'' The code blocks can be stored in any Org mode file and
14022 then loaded into the library with @code{org-babel-lob-ingest}.
14026 Code blocks located in any Org mode file can be loaded into the ``Library of
14027 Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v
14032 @cindex babel, languages
14033 @cindex source code, languages
14034 @cindex code block, languages
14036 Code blocks in the following languages are supported.
14038 @multitable @columnfractions 0.28 0.3 0.22 0.2
14039 @item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}
14040 @item Asymptote @tab asymptote @tab Awk @tab awk
14041 @item Emacs Calc @tab calc @tab C @tab C
14042 @item C++ @tab C++ @tab Clojure @tab clojure
14043 @item CSS @tab css @tab ditaa @tab ditaa
14044 @item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp
14045 @item gnuplot @tab gnuplot @tab Haskell @tab haskell
14046 @item Java @tab java @tab @tab
14047 @item Javascript @tab js @tab LaTeX @tab latex
14048 @item Ledger @tab ledger @tab Lisp @tab lisp
14049 @item Lilypond @tab lilypond @tab MATLAB @tab matlab
14050 @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
14051 @item Octave @tab octave @tab Org mode @tab org
14052 @item Oz @tab oz @tab Perl @tab perl
14053 @item Plantuml @tab plantuml @tab Python @tab python
14054 @item R @tab R @tab Ruby @tab ruby
14055 @item Sass @tab sass @tab Scheme @tab scheme
14056 @item GNU Screen @tab screen @tab shell @tab sh
14057 @item SQL @tab sql @tab SQLite @tab sqlite
14060 Language-specific documentation is available for some languages. If
14061 available, it can be found at
14062 @uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
14064 The option @code{org-babel-load-languages} controls which languages are
14065 enabled for evaluation (by default only @code{emacs-lisp} is enabled). This
14066 variable can be set using the customization interface or by adding code like
14067 the following to your emacs configuration.
14070 The following disables @code{emacs-lisp} evaluation and enables evaluation of
14071 @code{R} code blocks.
14075 (org-babel-do-load-languages
14076 'org-babel-load-languages
14077 '((emacs-lisp . nil)
14081 It is also possible to enable support for a language by loading the related
14082 elisp file with @code{require}.
14085 The following adds support for evaluating @code{clojure} code blocks.
14089 (require 'ob-clojure)
14092 @node Header arguments
14093 @section Header arguments
14094 @cindex code block, header arguments
14095 @cindex source code, block header arguments
14097 Code block functionality can be configured with header arguments. This
14098 section provides an overview of the use of header arguments, and then
14099 describes each header argument in detail.
14102 * Using header arguments:: Different ways to set header arguments
14103 * Specific header arguments:: List of header arguments
14106 @node Using header arguments
14107 @subsection Using header arguments
14109 The values of header arguments can be set in several way. When the header
14110 arguments in each layer have been determined, they are combined in order from
14111 the first, least specific (having the lowest priority) up to the last, most
14112 specific (having the highest priority). A header argument with a higher
14113 priority replaces the same header argument specified at lower priority.
14115 * System-wide header arguments:: Set global default values
14116 * Language-specific header arguments:: Set default values by language
14117 * Header arguments in Org mode properties:: Set default values for a buffer or heading
14118 * Language-specific header arguments in Org mode properties:: Set language-specific default values for a buffer or heading
14119 * Code block specific header arguments:: The most common way to set values
14120 * Header arguments in function calls:: The most specific level
14124 @node System-wide header arguments
14125 @subsubheading System-wide header arguments
14126 @vindex org-babel-default-header-args
14127 System-wide values of header arguments can be specified by adapting the
14128 @code{org-babel-default-header-args} variable:
14130 @cindex @code{:session}, src header argument
14131 @cindex @code{:results}, src header argument
14132 @cindex @code{:exports}, src header argument
14133 @cindex @code{:cache}, src header argument
14134 @cindex @code{:noweb}, src header argument
14137 :results => "replace"
14143 For example, the following example could be used to set the default value of
14144 @code{:noweb} header arguments to @code{yes}. This would have the effect of
14145 expanding @code{:noweb} references by default when evaluating source code
14149 (setq org-babel-default-header-args
14150 (cons '(:noweb . "yes")
14151 (assq-delete-all :noweb org-babel-default-header-args)))
14154 @node Language-specific header arguments
14155 @subsubheading Language-specific header arguments
14156 Each language can define its own set of default header arguments in variable
14157 @code{org-babel-default-header-args:<lang>}, where @code{<lang>} is the name
14158 of the language. See the language-specific documentation available online at
14159 @uref{http://orgmode.org/worg/org-contrib/babel}.
14161 @node Header arguments in Org mode properties
14162 @subsubheading Header arguments in Org mode properties
14164 Buffer-wide header arguments may be specified as properties through the use
14165 of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see
14166 @ref{Property syntax}).
14168 For example the following would set @code{session} to @code{*R*} (only for R
14169 code blocks), and @code{results} to @code{silent} for every code block in the
14170 buffer, ensuring that all execution took place in the same session, and no
14171 results would be inserted into the buffer.
14174 #+PROPERTY: header-args:R :session *R*
14175 #+PROPERTY: header-args :results silent
14178 Header arguments read from Org mode properties can also be set on a
14179 per-subtree basis using property drawers (see @ref{Property syntax}).
14180 @vindex org-use-property-inheritance
14181 When properties are used to set default header arguments, they are always
14182 looked up with inheritance, regardless of the value of
14183 @code{org-use-property-inheritance}. Properties are evaluated as seen by the
14184 outermost call or source block.@footnote{The deprecated syntax for default
14185 header argument properties, using the name of the header argument as a
14186 property name directly, evaluates the property as seen by the corresponding
14187 source block definition. This behavior has been kept for backwards
14190 In the following example the value of
14191 the @code{:cache} header argument will default to @code{yes} in all code
14192 blocks in the subtree rooted at the following heading:
14197 :header-args: :cache yes
14202 @vindex org-babel-default-header-args
14203 Properties defined in this way override the properties set in
14204 @code{org-babel-default-header-args} and are applied for all activated
14205 languages. It is convenient to use the @code{org-set-property} function
14206 bound to @kbd{C-c C-x p} to set properties in Org mode documents.
14208 @node Language-specific header arguments in Org mode properties
14209 @subsubheading Language-specific header arguments in Org mode properties
14211 Language-specific header arguments are also read from properties
14212 @code{header-args:<lang>} where @code{<lang>} is the name of the language
14213 targeted. As an example
14218 :header-args:clojure: :session *clojure-1*
14219 :header-args:R: :session *R*
14223 :header-args:clojure: :session *clojure-2*
14227 would independently set a default session header argument for R and clojure
14228 for calls and source blocks under subtree ``Heading'' and change to a
14229 different clojure setting for evaluations under subtree ``Subheading'', while
14230 the R session is inherited from ``Heading'' and therefore unchanged.
14232 @node Code block specific header arguments
14233 @subsubheading Code block specific header arguments
14235 The most common way to assign values to header arguments is at the
14236 code block level. This can be done by listing a sequence of header
14237 arguments and their values as part of the @code{#+BEGIN_SRC} line.
14238 Properties set in this way override both the values of
14239 @code{org-babel-default-header-args} and header arguments specified as
14240 properties. In the following example, the @code{:results} header argument
14241 is set to @code{silent}, meaning the results of execution will not be
14242 inserted in the buffer, and the @code{:exports} header argument is set to
14243 @code{code}, meaning only the body of the code block will be
14244 preserved on export to HTML or @LaTeX{}.
14248 #+BEGIN_SRC haskell :results silent :exports code :var n=0
14250 fac n = n * fac (n-1)
14253 Similarly, it is possible to set header arguments for inline code blocks
14256 src_haskell[:exports both]@{fac 5@}
14259 Code block header arguments can span multiple lines using @code{#+HEADER:} or
14260 @code{#+HEADERS:} lines preceding a code block or nested between the
14261 @code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block.
14265 Multi-line header arguments on an un-named code block:
14268 #+HEADERS: :var data1=1
14269 #+BEGIN_SRC emacs-lisp :var data2=2
14270 (message "data1:%S, data2:%S" data1 data2)
14277 Multi-line header arguments on a named code block:
14280 #+NAME: named-block
14281 #+HEADER: :var data=2
14282 #+BEGIN_SRC emacs-lisp
14283 (message "data:%S" data)
14286 #+RESULTS: named-block
14290 @node Header arguments in function calls
14291 @subsubheading Header arguments in function calls
14293 At the most specific level, header arguments for ``Library of Babel'' or
14294 @code{#+CALL:} lines can be set as shown in the two examples below. For more
14295 information on the structure of @code{#+CALL:} lines see @ref{Evaluating code
14298 The following will apply the @code{:exports results} header argument to the
14299 evaluation of the @code{#+CALL:} line.
14302 #+CALL: factorial(n=5) :exports results
14305 The following will apply the @code{:session special} header argument to the
14306 evaluation of the @code{factorial} code block.
14309 #+CALL: factorial[:session special](n=5)
14312 @node Specific header arguments
14313 @subsection Specific header arguments
14314 Header arguments consist of an initial colon followed by the name of the
14315 argument in lowercase letters. The following header arguments are defined:
14318 * var:: Pass arguments to code blocks
14319 * Results:: Specify the type of results and how they will
14320 be collected and handled
14321 * file:: Specify a path for file output
14322 * file-desc:: Specify a description for file results
14323 * dir:: Specify the default (possibly remote)
14324 directory for code block execution
14325 * exports:: Export code and/or results
14326 * tangle:: Toggle tangling and specify file name
14327 * mkdirp:: Toggle creation of parent directories of target
14328 files during tangling
14329 * comments:: Toggle insertion of comments in tangled
14331 * padline:: Control insertion of padding lines in tangled
14333 * no-expand:: Turn off variable assignment and noweb
14334 expansion during tangling
14335 * session:: Preserve the state of code evaluation
14336 * noweb:: Toggle expansion of noweb references
14337 * noweb-ref:: Specify block's noweb reference resolution target
14338 * noweb-sep:: String used to separate noweb references
14339 * cache:: Avoid re-evaluating unchanged code blocks
14340 * sep:: Delimiter for writing tabular results outside Org
14341 * hlines:: Handle horizontal lines in tables
14342 * colnames:: Handle column names in tables
14343 * rownames:: Handle row names in tables
14344 * shebang:: Make tangled files executable
14345 * tangle-mode:: Set permission of tangled files
14346 * eval:: Limit evaluation of specific code blocks
14347 * wrap:: Mark source block evaluation results
14348 * post:: Post processing of code block results
14349 * prologue:: Text to prepend to code block body
14350 * epilogue:: Text to append to code block body
14353 Additional header arguments are defined on a language-specific basis, see
14357 @subsubsection @code{:var}
14358 @cindex @code{:var}, src header argument
14359 The @code{:var} header argument is used to pass arguments to code blocks.
14360 The specifics of how arguments are included in a code block vary by language;
14361 these are addressed in the language-specific documentation. However, the
14362 syntax used to specify arguments is the same across all languages. In every
14363 case, variables require a default value when they are declared.
14365 The values passed to arguments can either be literal values, references, or
14366 Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}).
14367 References include anything in the Org mode file that takes a @code{#+NAME:}
14368 or @code{#+RESULTS:} line: tables, lists, @code{#+BEGIN_EXAMPLE} blocks,
14369 other code blocks and the results of other code blocks.
14371 Note: When a reference is made to another code block, the referenced block
14372 will be evaluated unless it has current cached results (see @ref{cache}).
14374 Argument values can be indexed in a manner similar to arrays (see @ref{var,
14375 Indexable variable values}).
14377 The following syntax is used to pass arguments to code blocks using the
14378 @code{:var} header argument.
14384 The argument, @code{assign}, can either be a literal value, such as a string
14385 @samp{"string"} or a number @samp{9}, or a reference to a table, a list, a
14386 literal example, another code block (with or without arguments), or the
14387 results of evaluating another code block.
14389 Here are examples of passing values by reference:
14394 an Org mode table named with either a @code{#+NAME:} line
14397 #+NAME: example-table
14403 #+NAME: table-length
14404 #+BEGIN_SRC emacs-lisp :var table=example-table
14408 #+RESULTS: table-length
14413 a simple list named with a @code{#+NAME:} line (note that nesting is not
14414 carried through to the source code block)
14417 #+NAME: example-list
14423 #+BEGIN_SRC emacs-lisp :var x=example-list
14431 @item code block without arguments
14432 a code block name (from the example above), as assigned by @code{#+NAME:},
14433 optionally followed by parentheses
14436 #+BEGIN_SRC emacs-lisp :var length=table-length()
14444 @item code block with arguments
14445 a code block name, as assigned by @code{#+NAME:}, followed by parentheses and
14446 optional arguments passed within the parentheses following the
14447 code block name using standard function call syntax
14451 #+BEGIN_SRC emacs-lisp :var input=8
14459 #+BEGIN_SRC emacs-lisp :var input=double(input=1)
14467 @item literal example
14468 a literal example block named with a @code{#+NAME:} line
14471 #+NAME: literal-example
14477 #+NAME: read-literal-example
14478 #+BEGIN_SRC emacs-lisp :var x=literal-example
14479 (concatenate 'string x " for you.")
14482 #+RESULTS: read-literal-example
14483 : A literal example
14484 : on two lines for you.
14490 @subsubheading Indexable variable values
14491 It is possible to reference portions of variable values by ``indexing'' into
14492 the variables. Indexes are 0 based with negative values counting back from
14493 the end. If an index is separated by @code{,}s then each subsequent section
14494 will index into the next deepest nesting or dimension of the value. Note
14495 that this indexing occurs @emph{before} other table related header arguments
14496 like @code{:hlines}, @code{:colnames} and @code{:rownames} are applied. The
14497 following example assigns the last cell of the first row the table
14498 @code{example-table} to the variable @code{data}:
14501 #+NAME: example-table
14507 #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
14515 Ranges of variable values can be referenced using two integers separated by a
14516 @code{:}, in which case the entire inclusive range is referenced. For
14517 example the following assigns the middle three rows of @code{example-table}
14521 #+NAME: example-table
14528 #+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
14538 Additionally, an empty index, or the single character @code{*}, are both
14539 interpreted to mean the entire range and as such are equivalent to
14540 @code{0:-1}, as shown in the following example in which the entire first
14541 column is referenced.
14544 #+NAME: example-table
14550 #+BEGIN_SRC emacs-lisp :var data=example-table[,0]
14558 It is possible to index into the results of code blocks as well as tables.
14559 Any number of dimensions can be indexed. Dimensions are separated from one
14560 another by commas, as shown in the following example.
14564 #+BEGIN_SRC emacs-lisp
14565 '(((1 2 3) (4 5 6) (7 8 9))
14566 ((10 11 12) (13 14 15) (16 17 18))
14567 ((19 20 21) (22 23 24) (25 26 27)))
14570 #+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
14578 @subsubheading Emacs Lisp evaluation of variables
14580 Emacs lisp code can be used to initialize variable values. When a variable
14581 value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be
14582 evaluated as Emacs Lisp and the result of the evaluation will be assigned as
14583 the variable value. The following example demonstrates use of this
14584 evaluation to reliably pass the file-name of the Org mode buffer to a code
14585 block---note that evaluation of header arguments is guaranteed to take place
14586 in the original Org mode file, while there is no such guarantee for
14587 evaluation of the code block body.
14590 #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
14595 Note that values read from tables and lists will not be evaluated as
14596 Emacs Lisp, as shown in the following example.
14602 #+HEADERS: :var data=table[0,0]
14612 @subsubsection @code{:results}
14613 @cindex @code{:results}, src header argument
14615 There are four classes of @code{:results} header argument. Only one option
14616 per class may be supplied per code block.
14620 @b{collection} header arguments specify how the results should be collected
14621 from the code block
14623 @b{type} header arguments specify what type of result the code block will
14624 return---which has implications for how they will be processed before
14625 insertion into the Org mode buffer
14627 @b{format} header arguments specify what type of result the code block will
14628 return---which has implications for how they will be inserted into the
14631 @b{handling} header arguments specify how the results of evaluating the code
14632 block should be handled.
14635 @subsubheading Collection
14636 The following options are mutually exclusive, and specify how the results
14637 should be collected from the code block.
14641 This is the default. The result is the value of the last statement in the
14642 code block. This header argument places the evaluation in functional
14643 mode. Note that in some languages, e.g., Python, use of this result type
14644 requires that a @code{return} statement be included in the body of the source
14645 code block. E.g., @code{:results value}.
14646 @item @code{output}
14647 The result is the collection of everything printed to STDOUT during the
14648 execution of the code block. This header argument places the
14649 evaluation in scripting mode. E.g., @code{:results output}.
14652 @subsubheading Type
14654 The following options are mutually exclusive and specify what type of results
14655 the code block will return. By default, results are inserted as either a
14656 table or scalar depending on their value.
14659 @item @code{table}, @code{vector}
14660 The results should be interpreted as an Org mode table. If a single value is
14661 returned, it will be converted into a table with one row and one column.
14662 E.g., @code{:results value table}.
14664 The results should be interpreted as an Org mode list. If a single scalar
14665 value is returned it will be converted into a list with only one element.
14666 @item @code{scalar}, @code{verbatim}
14667 The results should be interpreted literally---they will not be
14668 converted into a table. The results will be inserted into the Org mode
14669 buffer as quoted text. E.g., @code{:results value verbatim}.
14671 The results will be interpreted as the path to a file, and will be inserted
14672 into the Org mode buffer as a file link. E.g., @code{:results value file}.
14675 @subsubheading Format
14677 The following options are mutually exclusive and specify what type of results
14678 the code block will return. By default, results are inserted according to the
14679 type as specified above.
14683 The results are interpreted as raw Org mode code and are inserted directly
14684 into the buffer. If the results look like a table they will be aligned as
14685 such by Org mode. E.g., @code{:results value raw}.
14687 The results are will be enclosed in a @code{BEGIN_SRC org} block.
14688 They are not comma-escaped by default but they will be if you hit @kbd{TAB}
14689 in the block and/or if you export the file. E.g., @code{:results value org}.
14691 Results are assumed to be HTML and will be enclosed in a @code{BEGIN_HTML}
14692 block. E.g., @code{:results value html}.
14694 Results assumed to be @LaTeX{} and are enclosed in a @code{BEGIN_LaTeX} block.
14695 E.g., @code{:results value latex}.
14697 Result are assumed to be parsable code and are enclosed in a code block.
14698 E.g., @code{:results value code}.
14700 The result is converted to pretty-printed code and is enclosed in a code
14701 block. This option currently supports Emacs Lisp, Python, and Ruby. E.g.,
14702 @code{:results value pp}.
14703 @item @code{drawer}
14704 The result is wrapped in a RESULTS drawer. This can be useful for
14705 inserting @code{raw} or @code{org} syntax results in such a way that their
14706 extent is known and they can be automatically removed or replaced.
14709 @subsubheading Handling
14710 The following results options indicate what happens with the
14711 results once they are collected.
14714 @item @code{silent}
14715 The results will be echoed in the minibuffer but will not be inserted into
14716 the Org mode buffer. E.g., @code{:results output silent}.
14717 @item @code{replace}
14718 The default value. Any existing results will be removed, and the new results
14719 will be inserted into the Org mode buffer in their place. E.g.,
14720 @code{:results output replace}.
14721 @item @code{append}
14722 If there are pre-existing results of the code block then the new results will
14723 be appended to the existing results. Otherwise the new results will be
14724 inserted as with @code{replace}.
14725 @item @code{prepend}
14726 If there are pre-existing results of the code block then the new results will
14727 be prepended to the existing results. Otherwise the new results will be
14728 inserted as with @code{replace}.
14732 @subsubsection @code{:file}
14733 @cindex @code{:file}, src header argument
14735 The header argument @code{:file} is used to specify an external file in which
14736 to save code block results. After code block evaluation an Org mode style
14737 @code{[[file:]]} link (see @ref{Link format}) to the file will be inserted
14738 into the Org mode buffer. Some languages including R, gnuplot, dot, and
14739 ditaa provide special handling of the @code{:file} header argument
14740 automatically wrapping the code block body in the boilerplate code required
14741 to save output to the specified file. This is often useful for saving
14742 graphical output of a code block to the specified file.
14744 The argument to @code{:file} should be either a string specifying the path to
14745 a file, or a list of two strings in which case the first element of the list
14746 should be the path to a file and the second a description for the link.
14749 @subsubsection @code{:file-desc}
14751 The value of the @code{:file-desc} header argument is used to provide a
14752 description for file code block results which are inserted as Org mode links
14753 (see @ref{Link format}). If the @code{:file-desc} header argument is given
14754 with no value the link path will be placed in both the ``link'' and the
14755 ``description'' portion of the Org mode link.
14758 @subsubsection @code{:dir} and remote execution
14759 @cindex @code{:dir}, src header argument
14761 While the @code{:file} header argument can be used to specify the path to the
14762 output file, @code{:dir} specifies the default directory during code block
14763 execution. If it is absent, then the directory associated with the current
14764 buffer is used. In other words, supplying @code{:dir path} temporarily has
14765 the same effect as changing the current directory with @kbd{M-x cd path RET}, and
14766 then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets
14767 the value of the Emacs variable @code{default-directory}.
14769 When using @code{:dir}, you should supply a relative path for file output
14770 (e.g., @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
14771 case that path will be interpreted relative to the default directory.
14773 In other words, if you want your plot to go into a folder called @file{Work}
14774 in your home directory, you could use
14777 #+BEGIN_SRC R :file myplot.png :dir ~/Work
14778 matplot(matrix(rnorm(100), 10), type="l")
14782 @subsubheading Remote execution
14783 A directory on a remote machine can be specified using tramp file syntax, in
14784 which case the code will be evaluated on the remote machine. An example is
14787 #+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu:
14788 plot(1:10, main=system("hostname", intern=TRUE))
14792 Text results will be returned to the local Org mode buffer as usual, and file
14793 output will be created on the remote machine with relative paths interpreted
14794 relative to the remote directory. An Org mode link to the remote file will be
14797 So, in the above example a plot will be created on the remote machine,
14798 and a link of the following form will be inserted in the org buffer:
14801 [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
14804 Most of this functionality follows immediately from the fact that @code{:dir}
14805 sets the value of the Emacs variable @code{default-directory}, thanks to
14806 tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to
14807 install tramp separately in order for these features to work correctly.
14809 @subsubheading Further points
14813 If @code{:dir} is used in conjunction with @code{:session}, although it will
14814 determine the starting directory for a new session as expected, no attempt is
14815 currently made to alter the directory associated with an existing session.
14817 @code{:dir} should typically not be used to create files during export with
14818 @code{:exports results} or @code{:exports both}. The reason is that, in order
14819 to retain portability of exported material between machines, during export
14820 links inserted into the buffer will @emph{not} be expanded against @code{default
14821 directory}. Therefore, if @code{default-directory} is altered using
14822 @code{:dir}, it is probable that the file will be created in a location to
14823 which the link does not point.
14827 @subsubsection @code{:exports}
14828 @cindex @code{:exports}, src header argument
14830 The @code{:exports} header argument specifies what should be included in HTML
14831 or @LaTeX{} exports of the Org mode file.
14835 The default. The body of code is included into the exported file. E.g.,
14836 @code{:exports code}.
14837 @item @code{results}
14838 The result of evaluating the code is included in the exported file. E.g.,
14839 @code{:exports results}.
14841 Both the code and results are included in the exported file. E.g.,
14842 @code{:exports both}.
14844 Nothing is included in the exported file. E.g., @code{:exports none}.
14848 @subsubsection @code{:tangle}
14849 @cindex @code{:tangle}, src header argument
14851 The @code{:tangle} header argument specifies whether or not the code
14852 block should be included in tangled extraction of source code files.
14855 @item @code{tangle}
14856 The code block is exported to a source code file named after the full path
14857 (including the directory) and file name (w/o extension) of the Org mode file.
14858 E.g., @code{:tangle yes}.
14860 The default. The code block is not exported to a source code file.
14861 E.g., @code{:tangle no}.
14863 Any other string passed to the @code{:tangle} header argument is interpreted
14864 as a path (directory and file name relative to the directory of the Org mode
14865 file) to which the block will be exported. E.g., @code{:tangle path}.
14869 @subsubsection @code{:mkdirp}
14870 @cindex @code{:mkdirp}, src header argument
14872 The @code{:mkdirp} header argument can be used to create parent directories
14873 of tangled files when missing. This can be set to @code{yes} to enable
14874 directory creation or to @code{no} to inhibit directory creation.
14877 @subsubsection @code{:comments}
14878 @cindex @code{:comments}, src header argument
14879 By default code blocks are tangled to source-code files without any insertion
14880 of comments beyond those which may already exist in the body of the code
14881 block. The @code{:comments} header argument can be set as follows to control
14882 the insertion of extra comments into the tangled code file.
14886 The default. No extra comments are inserted during tangling.
14888 The code block is wrapped in comments which contain pointers back to the
14889 original Org file from which the code was tangled.
14891 A synonym for ``link'' to maintain backwards compatibility.
14893 Include text from the Org mode file as a comment.
14894 The text is picked from the leading context of the tangled code and is
14895 limited by the nearest headline or source block as the case may be.
14897 Turns on both the ``link'' and ``org'' comment options.
14899 Turns on the ``link'' comment option, and additionally wraps expanded noweb
14900 references in the code block body in link comments.
14904 @subsubsection @code{:padline}
14905 @cindex @code{:padline}, src header argument
14906 Control in insertion of padding lines around code block bodies in tangled
14907 code files. The default value is @code{yes} which results in insertion of
14908 newlines before and after each tangled code block. The following arguments
14913 Insert newlines before and after each code block body in tangled code files.
14915 Do not insert any newline padding in tangled output.
14919 @subsubsection @code{:no-expand}
14920 @cindex @code{:no-expand}, src header argument
14922 By default, code blocks are expanded with @code{org-babel-expand-src-block}
14923 during tangling. This has the effect of assigning values to variables
14924 specified with @code{:var} (see @ref{var}), and of replacing ``noweb''
14925 references (see @ref{Noweb reference syntax}) with their targets. The
14926 @code{:no-expand} header argument can be used to turn off this behavior.
14929 @subsubsection @code{:session}
14930 @cindex @code{:session}, src header argument
14932 The @code{:session} header argument starts a session for an interpreted
14933 language where state is preserved.
14935 By default, a session is not started.
14937 A string passed to the @code{:session} header argument will give the session
14938 a name. This makes it possible to run concurrent sessions for each
14939 interpreted language.
14942 @subsubsection @code{:noweb}
14943 @cindex @code{:noweb}, src header argument
14945 The @code{:noweb} header argument controls expansion of ``noweb'' syntax
14946 references (see @ref{Noweb reference syntax}) when the code block is
14947 evaluated, tangled, or exported. The @code{:noweb} header argument can have
14948 one of the five values: @code{no}, @code{yes}, @code{tangle}, or
14949 @code{no-export} @code{strip-export}.
14953 The default. ``Noweb'' syntax references in the body of the code block will
14954 not be expanded before the code block is evaluated, tangled or exported.
14956 ``Noweb'' syntax references in the body of the code block will be
14957 expanded before the code block is evaluated, tangled or exported.
14958 @item @code{tangle}
14959 ``Noweb'' syntax references in the body of the code block will be expanded
14960 before the code block is tangled. However, ``noweb'' syntax references will
14961 not be expanded when the code block is evaluated or exported.
14962 @item @code{no-export}
14963 ``Noweb'' syntax references in the body of the code block will be expanded
14964 before the block is evaluated or tangled. However, ``noweb'' syntax
14965 references will not be expanded when the code block is exported.
14966 @item @code{strip-export}
14967 ``Noweb'' syntax references in the body of the code block will be expanded
14968 before the block is evaluated or tangled. However, ``noweb'' syntax
14969 references will be removed when the code block is exported.
14971 ``Noweb'' syntax references in the body of the code block will only be
14972 expanded before the block is evaluated.
14975 @subsubheading Noweb prefix lines
14976 Noweb insertions are now placed behind the line prefix of the
14977 @code{<<reference>>}.
14978 This behavior is illustrated in the following example. Because the
14979 @code{<<example>>} noweb reference appears behind the SQL comment syntax,
14980 each line of the expanded noweb reference will be commented.
14992 -- multi-line body of example
14995 Note that noweb replacement text that does not contain any newlines will not
14996 be affected by this change, so it is still possible to use inline noweb
15000 @subsubsection @code{:noweb-ref}
15001 @cindex @code{:noweb-ref}, src header argument
15002 When expanding ``noweb'' style references the bodies of all code block with
15003 @emph{either} a block name matching the reference name @emph{or} a
15004 @code{:noweb-ref} header argument matching the reference name will be
15005 concatenated together to form the replacement text.
15007 By setting this header argument at the sub-tree or file level, simple code
15008 block concatenation may be achieved. For example, when tangling the
15009 following Org mode file, the bodies of code blocks will be concatenated into
15010 the resulting pure code file@footnote{(The example needs property inheritance
15011 to be turned on for the @code{noweb-ref} property, see @ref{Property
15015 #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
15018 * the mount point of the fullest disk
15020 :noweb-ref: fullest-disk
15023 ** query all mounted disks
15028 ** strip the header row
15033 ** sort by the percent full
15035 |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
15038 ** extract the mount point
15040 |awk '@{print $2@}'
15044 The @code{:noweb-sep} (see @ref{noweb-sep}) header argument holds the string
15045 used to separate accumulate noweb references like those above. By default a
15049 @subsubsection @code{:noweb-sep}
15050 @cindex @code{:noweb-sep}, src header argument
15052 The @code{:noweb-sep} header argument holds the string used to separate
15053 accumulate noweb references (see @ref{noweb-ref}). By default a newline is
15057 @subsubsection @code{:cache}
15058 @cindex @code{:cache}, src header argument
15060 The @code{:cache} header argument controls the use of in-buffer caching of
15061 the results of evaluating code blocks. It can be used to avoid re-evaluating
15062 unchanged code blocks. Note that the @code{:cache} header argument will not
15063 attempt to cache results when the @code{:session} header argument is used,
15064 because the results of the code block execution may be stored in the session
15065 outside of the Org mode buffer. The @code{:cache} header argument can have
15066 one of two values: @code{yes} or @code{no}.
15070 The default. No caching takes place, and the code block will be evaluated
15071 every time it is called.
15073 Every time the code block is run a SHA1 hash of the code and arguments
15074 passed to the block will be generated. This hash is packed into the
15075 @code{#+RESULTS:} line and will be checked on subsequent
15076 executions of the code block. If the code block has not
15077 changed since the last time it was evaluated, it will not be re-evaluated.
15080 Code block caches notice if the value of a variable argument
15081 to the code block has changed. If this is the case, the cache is
15082 invalidated and the code block is re-run. In the following example,
15083 @code{caller} will not be re-run unless the results of @code{random} have
15084 changed since it was last run.
15088 #+BEGIN_SRC R :cache yes
15092 #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
15096 #+BEGIN_SRC emacs-lisp :var x=random :cache yes
15100 #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
15105 @subsubsection @code{:sep}
15106 @cindex @code{:sep}, src header argument
15108 The @code{:sep} header argument can be used to control the delimiter used
15109 when writing tabular results out to files external to Org mode. This is used
15110 either when opening tabular results of a code block by calling the
15111 @code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block,
15112 or when writing code block results to an external file (see @ref{file})
15115 By default, when @code{:sep} is not specified output tables are tab
15119 @subsubsection @code{:hlines}
15120 @cindex @code{:hlines}, src header argument
15122 Tables are frequently represented with one or more horizontal lines, or
15123 hlines. The @code{:hlines} argument to a code block accepts the
15124 values @code{yes} or @code{no}, with a default value of @code{no}.
15128 Strips horizontal lines from the input table. In most languages this is the
15129 desired effect because an @code{hline} symbol is interpreted as an unbound
15130 variable and raises an error. Setting @code{:hlines no} or relying on the
15131 default value yields the following results.
15142 #+BEGIN_SRC python :var tab=many-cols
15146 #+RESULTS: echo-table
15153 Leaves hlines in the table. Setting @code{:hlines yes} has this effect.
15164 #+BEGIN_SRC python :var tab=many-cols :hlines yes
15168 #+RESULTS: echo-table
15178 @subsubsection @code{:colnames}
15179 @cindex @code{:colnames}, src header argument
15181 The @code{:colnames} header argument accepts the values @code{yes},
15182 @code{no}, or @code{nil} for unassigned. The default value is @code{nil}.
15183 Note that the behavior of the @code{:colnames} header argument may differ
15188 If an input table looks like it has column names
15189 (because its second row is an hline), then the column
15190 names will be removed from the table before
15191 processing, then reapplied to the results.
15200 #+NAME: echo-table-again
15201 #+BEGIN_SRC python :var tab=less-cols
15202 return [[val + '*' for val in row] for row in tab]
15205 #+RESULTS: echo-table-again
15212 Please note that column names are not removed before the table is indexed
15213 using variable indexing @xref{var, Indexable variable values}.
15216 No column name pre-processing takes place
15219 Column names are removed and reapplied as with @code{nil} even if the table
15220 does not ``look like'' it has column names (i.e., the second row is not an
15225 @subsubsection @code{:rownames}
15226 @cindex @code{:rownames}, src header argument
15228 The @code{:rownames} header argument can take on the values @code{yes} or
15229 @code{no}, with a default value of @code{no}. Note that Emacs Lisp code
15230 blocks ignore the @code{:rownames} header argument entirely given the ease
15231 with which tables with row names may be handled directly in Emacs Lisp.
15235 No row name pre-processing will take place.
15238 The first column of the table is removed from the table before processing,
15239 and is then reapplied to the results.
15242 #+NAME: with-rownames
15243 | one | 1 | 2 | 3 | 4 | 5 |
15244 | two | 6 | 7 | 8 | 9 | 10 |
15246 #+NAME: echo-table-once-again
15247 #+BEGIN_SRC python :var tab=with-rownames :rownames yes
15248 return [[val + 10 for val in row] for row in tab]
15251 #+RESULTS: echo-table-once-again
15252 | one | 11 | 12 | 13 | 14 | 15 |
15253 | two | 16 | 17 | 18 | 19 | 20 |
15256 Please note that row names are not removed before the table is indexed using
15257 variable indexing @xref{var, Indexable variable values}.
15262 @subsubsection @code{:shebang}
15263 @cindex @code{:shebang}, src header argument
15265 Setting the @code{:shebang} header argument to a string value
15266 (e.g., @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the
15267 first line of any tangled file holding the code block, and the file
15268 permissions of the tangled file are set to make it executable.
15272 @subsubsection @code{:tangle-mode}
15273 @cindex @code{:tangle-mode}, src header argument
15275 The @code{tangle-mode} header argument controls the permission set on tangled
15276 files. The value of this header argument will be passed to
15277 @code{set-file-modes}. For example, to set a tangled file as read only use
15278 @code{:tangle-mode (identity #o444)}, or to set a tangled file as executable
15279 use @code{:tangle-mode (identity #o755)}. Blocks with @code{shebang}
15280 (@ref{shebang}) header arguments will automatically be made executable unless
15281 the @code{tangle-mode} header argument is also used. The behavior is
15282 undefined if multiple code blocks with different values for the
15283 @code{tangle-mode} header argument are tangled to the same file.
15286 @subsubsection @code{:eval}
15287 @cindex @code{:eval}, src header argument
15288 The @code{:eval} header argument can be used to limit the evaluation of
15289 specific code blocks. The @code{:eval} header argument can be useful for
15290 protecting against the evaluation of dangerous code blocks or to ensure that
15291 evaluation will require a query regardless of the value of the
15292 @code{org-confirm-babel-evaluate} variable. The possible values of
15293 @code{:eval} and their effects are shown below.
15297 The code block will not be evaluated under any circumstances.
15299 Evaluation of the code block will require a query.
15300 @item never-export or no-export
15301 The code block will not be evaluated during export but may still be called
15304 Evaluation of the code block during export will require a query.
15307 If this header argument is not set then evaluation is determined by the value
15308 of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation
15312 @subsubsection @code{:wrap}
15313 @cindex @code{:wrap}, src header argument
15314 The @code{:wrap} header argument is used to mark the results of source block
15315 evaluation. The header argument can be passed a string that will be appended
15316 to @code{#+BEGIN_} and @code{#+END_}, which will then be used to wrap the
15317 results. If not string is specified then the results will be wrapped in a
15318 @code{#+BEGIN/END_RESULTS} block.
15321 @subsubsection @code{:post}
15322 @cindex @code{:post}, src header argument
15323 The @code{:post} header argument is used to post-process the results of a
15324 code block execution. When a post argument is given, the results of the code
15325 block will temporarily be bound to the @code{*this*} variable. This variable
15326 may then be included in header argument forms such as those used in @ref{var}
15327 header argument specifications allowing passing of results to other code
15328 blocks, or direct execution via Emacs Lisp.
15330 The following example illustrates the usage of the @code{:post} header
15335 #+begin_src sh :var data="" :var width="\\textwidth" :results output
15336 echo "#+ATTR_LATEX :width $width"
15340 #+header: :file /tmp/it.png
15341 #+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer
15351 #+ATTR_LATEX :width 5cm
15352 [[file:/tmp/it.png]]
15357 @subsubsection @code{:prologue}
15358 @cindex @code{:prologue}, src header argument
15359 The value of the @code{prologue} header argument will be prepended to the
15360 code block body before execution. For example, @code{:prologue "reset"} may
15361 be used to reset a gnuplot session before execution of a particular code
15362 block, or the following configuration may be used to do this for all gnuplot
15363 code blocks. Also see @ref{epilogue}.
15366 (add-to-list 'org-babel-default-header-args:gnuplot
15367 '((:prologue . "reset")))
15371 @subsubsection @code{:epilogue}
15372 @cindex @code{:epilogue}, src header argument
15373 The value of the @code{epilogue} header argument will be appended to the code
15374 block body before execution. Also see @ref{prologue}.
15376 @node Results of evaluation
15377 @section Results of evaluation
15378 @cindex code block, results of evaluation
15379 @cindex source code, results of evaluation
15381 The way in which results are handled depends on whether a session is invoked,
15382 as well as on whether @code{:results value} or @code{:results output} is
15383 used. The following table shows the table possibilities. For a full listing
15384 of the possible results header arguments see @ref{Results}.
15386 @multitable @columnfractions 0.26 0.33 0.41
15387 @item @tab @b{Non-session} @tab @b{Session}
15388 @item @code{:results value} @tab value of last expression @tab value of last expression
15389 @item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output
15392 Note: With @code{:results value}, the result in both @code{:session} and
15393 non-session is returned to Org mode as a table (a one- or two-dimensional
15394 vector of strings or numbers) when appropriate.
15396 @subsection Non-session
15397 @subsubsection @code{:results value}
15398 @cindex @code{:results}, src header argument
15399 This is the default. Internally, the value is obtained by wrapping the code
15400 in a function definition in the external language, and evaluating that
15401 function. Therefore, code should be written as if it were the body of such a
15402 function. In particular, note that Python does not automatically return a
15403 value from a function unless a @code{return} statement is present, and so a
15404 @samp{return} statement will usually be required in Python.
15406 This is the only one of the four evaluation contexts in which the code is
15407 automatically wrapped in a function definition.
15409 @subsubsection @code{:results output}
15410 @cindex @code{:results}, src header argument
15411 The code is passed to the interpreter as an external process, and the
15412 contents of the standard output stream are returned as text. (In certain
15413 languages this also contains the error output stream; this is an area for
15416 @subsection Session
15417 @subsubsection @code{:results value}
15418 @cindex @code{:results}, src header argument
15419 The code is passed to an interpreter running as an interactive Emacs inferior
15420 process. Only languages which provide tools for interactive evaluation of
15421 code have session support, so some language (e.g., C and ditaa) do not
15422 support the @code{:session} header argument, and in other languages (e.g.,
15423 Python and Haskell) which have limitations on the code which may be entered
15424 into interactive sessions, those limitations apply to the code in code blocks
15425 using the @code{:session} header argument as well.
15427 Unless the @code{:results output} option is supplied (see below) the result
15428 returned is the result of the last evaluation performed by the
15429 interpreter. (This is obtained in a language-specific manner: the value of
15430 the variable @code{_} in Python and Ruby, and the value of @code{.Last.value}
15433 @subsubsection @code{:results output}
15434 @cindex @code{:results}, src header argument
15435 The code is passed to the interpreter running as an interactive Emacs
15436 inferior process. The result returned is the concatenation of the sequence of
15437 (text) output from the interactive interpreter. Notice that this is not
15438 necessarily the same as what would be sent to @code{STDOUT} if the same code
15439 were passed to a non-interactive interpreter running as an external
15440 process. For example, compare the following two blocks:
15443 #+BEGIN_SRC python :results output
15454 In non-session mode, the `2' is not printed and does not appear.
15457 #+BEGIN_SRC python :results output :session
15469 But in @code{:session} mode, the interactive interpreter receives input `2'
15470 and prints out its value, `2'. (Indeed, the other print statements are
15473 @node Noweb reference syntax
15474 @section Noweb reference syntax
15475 @cindex code block, noweb reference
15476 @cindex syntax, noweb
15477 @cindex source code, noweb reference
15479 The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate
15480 Programming system allows named blocks of code to be referenced by using the
15481 familiar Noweb syntax:
15484 <<code-block-name>>
15487 When a code block is tangled or evaluated, whether or not ``noweb''
15488 references are expanded depends upon the value of the @code{:noweb} header
15489 argument. If @code{:noweb yes}, then a Noweb reference is expanded before
15490 evaluation. If @code{:noweb no}, the default, then the reference is not
15491 expanded before evaluation. See the @ref{noweb-ref} header argument for
15492 a more flexible way to resolve noweb references.
15494 It is possible to include the @emph{results} of a code block rather than the
15495 body. This is done by appending parenthesis to the code block name which may
15496 optionally contain arguments to the code block as shown below.
15499 <<code-block-name(optional arguments)>>
15502 Note: the default value, @code{:noweb no}, was chosen to ensure that
15503 correct code is not broken in a language, such as Ruby, where
15504 @code{<<arg>>} is a syntactically valid construct. If @code{<<arg>>} is not
15505 syntactically valid in languages that you use, then please consider setting
15508 Note: if noweb tangling is slow in large Org mode files consider setting the
15509 @code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}.
15510 This will result in faster noweb reference resolution at the expense of not
15511 correctly resolving inherited values of the @code{:noweb-ref} header
15514 @node Key bindings and useful functions
15515 @section Key bindings and useful functions
15516 @cindex code block, key bindings
15518 Many common Org mode key sequences are re-bound depending on
15521 Within a code block, the following key bindings
15524 @multitable @columnfractions 0.25 0.75
15526 @item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block}
15528 @item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result}
15530 @item @kbd{C-@key{up}} @tab @code{org-babel-load-in-session}
15532 @item @kbd{M-@key{down}} @tab @code{org-babel-pop-to-session}
15535 In an Org mode buffer, the following key bindings are active:
15537 @multitable @columnfractions 0.45 0.55
15539 @kindex C-c C-v C-p
15540 @item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block}
15542 @kindex C-c C-v C-n
15543 @item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block}
15545 @kindex C-c C-v C-e
15546 @item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe}
15548 @kindex C-c C-v C-o
15549 @item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result}
15551 @kindex C-c C-v C-v
15552 @item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block}
15554 @kindex C-c C-v C-u
15555 @item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head}
15557 @kindex C-c C-v C-g
15558 @item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block}
15560 @kindex C-c C-v C-r
15561 @item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result}
15563 @kindex C-c C-v C-b
15564 @item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
15566 @kindex C-c C-v C-s
15567 @item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
15569 @kindex C-c C-v C-d
15570 @item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block}
15572 @kindex C-c C-v C-t
15573 @item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
15575 @kindex C-c C-v C-f
15576 @item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
15578 @kindex C-c C-v C-c
15579 @item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block}
15581 @kindex C-c C-v C-j
15582 @item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg}
15584 @kindex C-c C-v C-l
15585 @item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session}
15587 @kindex C-c C-v C-i
15588 @item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest}
15590 @kindex C-c C-v C-I
15591 @item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info}
15593 @kindex C-c C-v C-z
15594 @item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session-with-code}
15596 @kindex C-c C-v C-a
15597 @item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
15599 @kindex C-c C-v C-h
15600 @item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings}
15602 @kindex C-c C-v C-x
15603 @item @kbd{C-c C-v x} @ @ @r{or} @ @ @kbd{C-c C-v C-x} @tab @code{org-babel-do-key-sequence-in-edit-buffer}
15606 @c When possible these keybindings were extended to work when the control key is
15607 @c kept pressed, resulting in the following additional keybindings.
15609 @c @multitable @columnfractions 0.25 0.75
15610 @c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
15611 @c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
15612 @c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
15613 @c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
15614 @c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
15615 @c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
15616 @c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
15617 @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
15620 @node Batch execution
15621 @section Batch execution
15622 @cindex code block, batch execution
15623 @cindex source code, batch execution
15625 It is possible to call functions from the command line. This shell
15626 script calls @code{org-babel-tangle} on every one of its arguments.
15628 Be sure to adjust the paths to fit your system.
15632 # -*- mode: shell-script -*-
15634 # tangle files with org-mode
15639 # wrap each argument in the code required to call tangle on it
15641 FILES="$FILES \"$i\""
15646 (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
15647 (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\" t))
15648 (require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
15649 (mapc (lambda (file)
15650 (find-file (expand-file-name file \"$DIR\"))
15652 (kill-buffer)) '($FILES)))" 2>&1 |grep tangled
15655 @node Miscellaneous
15656 @chapter Miscellaneous
15659 * Completion:: M-TAB knows what you need
15660 * Easy templates:: Quick insertion of structural elements
15661 * Speed keys:: Electric commands at the beginning of a headline
15662 * Code evaluation security:: Org mode files evaluate inline code
15663 * Customization:: Adapting Org to your taste
15664 * In-buffer settings:: Overview of the #+KEYWORDS
15665 * The very busy C-c C-c key:: When in doubt, press C-c C-c
15666 * Clean view:: Getting rid of leading stars in the outline
15667 * TTY keys:: Using Org on a tty
15668 * Interaction:: Other Emacs packages
15669 * org-crypt:: Encrypting Org files
15674 @section Completion
15675 @cindex completion, of @TeX{} symbols
15676 @cindex completion, of TODO keywords
15677 @cindex completion, of dictionary words
15678 @cindex completion, of option keywords
15679 @cindex completion, of tags
15680 @cindex completion, of property keys
15681 @cindex completion, of link abbreviations
15682 @cindex @TeX{} symbol completion
15683 @cindex TODO keywords completion
15684 @cindex dictionary word completion
15685 @cindex option keyword completion
15686 @cindex tag completion
15687 @cindex link abbreviations, completion of
15689 Emacs would not be Emacs without completion, and Org mode uses it whenever it
15690 makes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface for
15691 some of the completion prompts, you can specify your preference by setting at
15692 most one of the variables @code{org-completion-use-iswitchb}
15693 @code{org-completion-use-ido}.
15695 Org supports in-buffer completion. This type of completion does
15696 not make use of the minibuffer. You simply type a few letters into
15697 the buffer and use the key to complete text right there.
15700 @kindex M-@key{TAB}
15702 Complete word at point
15705 At the beginning of a headline, complete TODO keywords.
15707 After @samp{\}, complete @TeX{} symbols supported by the exporter.
15709 After @samp{*}, complete headlines in the current buffer so that they
15710 can be used in search links like @samp{[[*find this headline]]}.
15712 After @samp{:} in a headline, complete tags. The list of tags is taken
15713 from the variable @code{org-tag-alist} (possibly set through the
15714 @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
15715 dynamically from all tags used in the current buffer.
15717 After @samp{:} and not in a headline, complete property keys. The list
15718 of keys is constructed dynamically from all keys used in the current
15721 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
15723 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
15724 @samp{OPTIONS} which set file-specific options for Org mode. When the
15725 option keyword is already complete, pressing @kbd{M-@key{TAB}} again
15726 will insert example settings for this keyword.
15728 In the line after @samp{#+STARTUP: }, complete startup keywords,
15729 i.e., valid keys for this line.
15731 Elsewhere, complete dictionary words using Ispell.
15735 @node Easy templates
15736 @section Easy templates
15737 @cindex template insertion
15738 @cindex insertion, of templates
15740 Org mode supports insertion of empty structural elements (like
15741 @code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key
15742 strokes. This is achieved through a native template expansion mechanism.
15743 Note that Emacs has several other template mechanisms which could be used in
15744 a similar way, for example @file{yasnippet}.
15746 To insert a structural element, type a @samp{<}, followed by a template
15747 selector and @kbd{@key{TAB}}. Completion takes effect only when the above
15748 keystrokes are typed on a line by itself.
15750 The following template selectors are currently supported.
15752 @multitable @columnfractions 0.1 0.9
15753 @item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC}
15754 @item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
15755 @item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE}
15756 @item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE}
15757 @item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER}
15758 @item @kbd{l} @tab @code{#+BEGIN_LaTeX ... #+END_LaTeX}
15759 @item @kbd{L} @tab @code{#+LaTeX:}
15760 @item @kbd{h} @tab @code{#+BEGIN_HTML ... #+END_HTML}
15761 @item @kbd{H} @tab @code{#+HTML:}
15762 @item @kbd{a} @tab @code{#+BEGIN_ASCII ... #+END_ASCII}
15763 @item @kbd{A} @tab @code{#+ASCII:}
15764 @item @kbd{i} @tab @code{#+INDEX:} line
15765 @item @kbd{I} @tab @code{#+INCLUDE:} line
15768 For example, on an empty line, typing "<e" and then pressing TAB, will expand
15769 into a complete EXAMPLE template.
15771 You can install additional templates by customizing the variable
15772 @code{org-structure-template-alist}. See the docstring of the variable for
15773 additional details.
15776 @section Speed keys
15778 @vindex org-use-speed-commands
15779 @vindex org-speed-commands-user
15781 Single keys can be made to execute commands when the cursor is at the
15782 beginning of a headline, i.e., before the first star. Configure the variable
15783 @code{org-use-speed-commands} to activate this feature. There is a
15784 pre-defined list of commands, and you can add more such commands using the
15785 variable @code{org-speed-commands-user}. Speed keys not only speed up
15786 navigation and other commands, but they also provide an alternative way to
15787 execute commands bound to keys that are not or not easily available on a TTY,
15788 or on a small mobile device with a limited keyboard.
15790 To see which commands are available, activate the feature and press @kbd{?}
15791 with the cursor at the beginning of a headline.
15793 @node Code evaluation security
15794 @section Code evaluation and security issues
15796 Org provides tools to work with code snippets, including evaluating them.
15798 Running code on your machine always comes with a security risk. Badly
15799 written or malicious code can be executed on purpose or by accident. Org has
15800 default settings which will only evaluate such code if you give explicit
15801 permission to do so, and as a casual user of these features you should leave
15802 these precautions intact.
15804 For people who regularly work with such code, the confirmation prompts can
15805 become annoying, and you might want to turn them off. This can be done, but
15806 you must be aware of the risks that are involved.
15808 Code evaluation can happen under the following circumstances:
15811 @item Source code blocks
15812 Source code blocks can be evaluated during export, or when pressing @kbd{C-c
15813 C-c} in the block. The most important thing to realize here is that Org mode
15814 files which contain code snippets are, in a certain sense, like executable
15815 files. So you should accept them and load them into Emacs only from trusted
15816 sources---just like you would do with a program you install on your computer.
15818 Make sure you know what you are doing before customizing the variables
15819 which take off the default security brakes.
15821 @defopt org-confirm-babel-evaluate
15822 When t (the default), the user is asked before every code block evaluation.
15823 When @code{nil}, the user is not asked. When set to a function, it is called with
15824 two arguments (language and body of the code block) and should return t to
15825 ask and @code{nil} not to ask.
15828 For example, here is how to execute "ditaa" code (which is considered safe)
15832 (defun my-org-confirm-babel-evaluate (lang body)
15833 (not (string= lang "ditaa"))) ; don't ask for ditaa
15834 (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
15837 @item Following @code{shell} and @code{elisp} links
15838 Org has two link types that can directly evaluate code (@pxref{External
15839 links}). These links can be problematic because the code to be evaluated is
15842 @defopt org-confirm-shell-link-function
15843 Function to queries user about shell link execution.
15845 @defopt org-confirm-elisp-link-function
15846 Functions to query user for Emacs Lisp link execution.
15849 @item Formulas in tables
15850 Formulas in tables (@pxref{The spreadsheet}) are code that is evaluated
15851 either by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter.
15854 @node Customization
15855 @section Customization
15856 @cindex customization
15857 @cindex options, for customization
15858 @cindex variables, for customization
15860 There are more than 500 variables that can be used to customize
15861 Org. For the sake of compactness of the manual, I am not
15862 describing the variables here. A structured overview of customization
15863 variables is available with @kbd{M-x org-customize RET}. Or select
15864 @code{Browse Org Group} from the @code{Org->Customization} menu. Many
15865 settings can also be activated on a per-file basis, by putting special
15866 lines into the buffer (@pxref{In-buffer settings}).
15868 @node In-buffer settings
15869 @section Summary of in-buffer settings
15870 @cindex in-buffer settings
15871 @cindex special keywords
15873 Org mode uses special lines in the buffer to define settings on a
15874 per-file basis. These lines start with a @samp{#+} followed by a
15875 keyword, a colon, and then individual words defining a setting. Several
15876 setting words can be in the same line, but you can also have multiple
15877 lines for the keyword. While these settings are described throughout
15878 the manual, here is a summary. After changing any of these lines in the
15879 buffer, press @kbd{C-c C-c} with the cursor still in the line to
15880 activate the changes immediately. Otherwise they become effective only
15881 when the file is visited again in a new Emacs session.
15883 @vindex org-archive-location
15885 @item #+ARCHIVE: %s_done::
15886 This line sets the archive location for the agenda file. It applies for
15887 all subsequent lines until the next @samp{#+ARCHIVE} line, or the end
15888 of the file. The first such line also applies to any entries before it.
15889 The corresponding variable is @code{org-archive-location}.
15891 This line sets the category for the agenda file. The category applies
15892 for all subsequent lines until the next @samp{#+CATEGORY} line, or the
15893 end of the file. The first such line also applies to any entries before it.
15894 @item #+COLUMNS: %25ITEM ...
15895 @cindex property, COLUMNS
15896 Set the default format for columns view. This format applies when
15897 columns view is invoked in locations where no @code{COLUMNS} property
15899 @item #+CONSTANTS: name1=value1 ...
15900 @vindex org-table-formula-constants
15901 @vindex org-table-formula
15902 Set file-local values for constants to be used in table formulas. This
15903 line sets the local variable @code{org-table-formula-constants-local}.
15904 The global version of this variable is
15905 @code{org-table-formula-constants}.
15906 @item #+FILETAGS: :tag1:tag2:tag3:
15907 Set tags that can be inherited by any entry in the file, including the
15909 @item #+DRAWERS: NAME1 ...
15910 @vindex org-drawers
15911 Set the file-local set of additional drawers. The corresponding global
15912 variable is @code{org-drawers}.
15913 @item #+LINK: linkword replace
15914 @vindex org-link-abbrev-alist
15915 These lines (several are allowed) specify link abbreviations.
15916 @xref{Link abbreviations}. The corresponding variable is
15917 @code{org-link-abbrev-alist}.
15918 @item #+PRIORITIES: highest lowest default
15919 @vindex org-highest-priority
15920 @vindex org-lowest-priority
15921 @vindex org-default-priority
15922 This line sets the limits and the default for the priorities. All three
15923 must be either letters A--Z or numbers 0--9. The highest priority must
15924 have a lower ASCII number than the lowest priority.
15925 @item #+PROPERTY: Property_Name Value
15926 This line sets a default inheritance value for entries in the current
15927 buffer, most useful for specifying the allowed values of a property.
15928 @cindex #+SETUPFILE
15929 @item #+SETUPFILE: file
15930 This line defines a file that holds more in-buffer setup. Normally this is
15931 entirely ignored. Only when the buffer is parsed for option-setting lines
15932 (i.e., when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
15933 settings line, or when exporting), then the contents of this file are parsed
15934 as if they had been included in the buffer. In particular, the file can be
15935 any other Org mode file with internal setup. You can visit the file the
15936 cursor is in the line with @kbd{C-c '}.
15939 This line sets options to be used at startup of Org mode, when an
15940 Org file is being visited.
15942 The first set of options deals with the initial visibility of the outline
15943 tree. The corresponding variable for global default settings is
15944 @code{org-startup-folded}, with a default value @code{t}, which means
15946 @vindex org-startup-folded
15947 @cindex @code{overview}, STARTUP keyword
15948 @cindex @code{content}, STARTUP keyword
15949 @cindex @code{showall}, STARTUP keyword
15950 @cindex @code{showeverything}, STARTUP keyword
15952 overview @r{top-level headlines only}
15953 content @r{all headlines}
15954 showall @r{no folding of any entries}
15955 showeverything @r{show even drawer contents}
15958 @vindex org-startup-indented
15959 @cindex @code{indent}, STARTUP keyword
15960 @cindex @code{noindent}, STARTUP keyword
15961 Dynamic virtual indentation is controlled by the variable
15962 @code{org-startup-indented}@footnote{Emacs 23 and Org mode 6.29 are required}
15964 indent @r{start with @code{org-indent-mode} turned on}
15965 noindent @r{start with @code{org-indent-mode} turned off}
15968 @vindex org-startup-align-all-tables
15969 Then there are options for aligning tables upon visiting a file. This
15970 is useful in files containing narrowed table columns. The corresponding
15971 variable is @code{org-startup-align-all-tables}, with a default value
15973 @cindex @code{align}, STARTUP keyword
15974 @cindex @code{noalign}, STARTUP keyword
15976 align @r{align all tables}
15977 noalign @r{don't align tables on startup}
15980 @vindex org-startup-with-inline-images
15981 When visiting a file, inline images can be automatically displayed. The
15982 corresponding variable is @code{org-startup-with-inline-images}, with a
15983 default value @code{nil} to avoid delays when visiting a file.
15984 @cindex @code{inlineimages}, STARTUP keyword
15985 @cindex @code{noinlineimages}, STARTUP keyword
15987 inlineimages @r{show inline images}
15988 noinlineimages @r{don't show inline images on startup}
15991 @vindex org-startup-with-latex-preview
15992 When visiting a file, @LaTeX{} fragments can be converted to images
15993 automatically. The variable @code{org-startup-with-latex-preview} which
15994 controls this behavior, is set to @code{nil} by default to avoid delays on
15996 @cindex @code{latexpreview}, STARTUP keyword
15997 @cindex @code{nolatexpreview}, STARTUP keyword
15999 latexpreview @r{preview @LaTeX{} fragments}
16000 nolatexpreview @r{don't preview @LaTeX{} fragments}
16003 @vindex org-log-done
16004 @vindex org-log-note-clock-out
16005 @vindex org-log-repeat
16006 Logging the closing and reopening of TODO items and clock intervals can be
16007 configured using these options (see variables @code{org-log-done},
16008 @code{org-log-note-clock-out} and @code{org-log-repeat})
16009 @cindex @code{logdone}, STARTUP keyword
16010 @cindex @code{lognotedone}, STARTUP keyword
16011 @cindex @code{nologdone}, STARTUP keyword
16012 @cindex @code{lognoteclock-out}, STARTUP keyword
16013 @cindex @code{nolognoteclock-out}, STARTUP keyword
16014 @cindex @code{logrepeat}, STARTUP keyword
16015 @cindex @code{lognoterepeat}, STARTUP keyword
16016 @cindex @code{nologrepeat}, STARTUP keyword
16017 @cindex @code{logreschedule}, STARTUP keyword
16018 @cindex @code{lognotereschedule}, STARTUP keyword
16019 @cindex @code{nologreschedule}, STARTUP keyword
16020 @cindex @code{logredeadline}, STARTUP keyword
16021 @cindex @code{lognoteredeadline}, STARTUP keyword
16022 @cindex @code{nologredeadline}, STARTUP keyword
16023 @cindex @code{logrefile}, STARTUP keyword
16024 @cindex @code{lognoterefile}, STARTUP keyword
16025 @cindex @code{nologrefile}, STARTUP keyword
16026 @cindex @code{logdrawer}, STARTUP keyword
16027 @cindex @code{nologdrawer}, STARTUP keyword
16028 @cindex @code{logstatesreversed}, STARTUP keyword
16029 @cindex @code{nologstatesreversed}, STARTUP keyword
16031 logdone @r{record a timestamp when an item is marked DONE}
16032 lognotedone @r{record timestamp and a note when DONE}
16033 nologdone @r{don't record when items are marked DONE}
16034 logrepeat @r{record a time when reinstating a repeating item}
16035 lognoterepeat @r{record a note when reinstating a repeating item}
16036 nologrepeat @r{do not record when reinstating repeating item}
16037 lognoteclock-out @r{record a note when clocking out}
16038 nolognoteclock-out @r{don't record a note when clocking out}
16039 logreschedule @r{record a timestamp when scheduling time changes}
16040 lognotereschedule @r{record a note when scheduling time changes}
16041 nologreschedule @r{do not record when a scheduling date changes}
16042 logredeadline @r{record a timestamp when deadline changes}
16043 lognoteredeadline @r{record a note when deadline changes}
16044 nologredeadline @r{do not record when a deadline date changes}
16045 logrefile @r{record a timestamp when refiling}
16046 lognoterefile @r{record a note when refiling}
16047 nologrefile @r{do not record when refiling}
16048 logdrawer @r{store log into drawer}
16049 nologdrawer @r{store log outside of drawer}
16050 logstatesreversed @r{reverse the order of states notes}
16051 nologstatesreversed @r{do not reverse the order of states notes}
16054 @vindex org-hide-leading-stars
16055 @vindex org-odd-levels-only
16056 Here are the options for hiding leading stars in outline headings, and for
16057 indenting outlines. The corresponding variables are
16058 @code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a
16059 default setting @code{nil} (meaning @code{showstars} and @code{oddeven}).
16060 @cindex @code{hidestars}, STARTUP keyword
16061 @cindex @code{showstars}, STARTUP keyword
16062 @cindex @code{odd}, STARTUP keyword
16063 @cindex @code{even}, STARTUP keyword
16065 hidestars @r{make all but one of the stars starting a headline invisible.}
16066 showstars @r{show all stars starting a headline}
16067 indent @r{virtual indentation according to outline level}
16068 noindent @r{no virtual indentation according to outline level}
16069 odd @r{allow only odd outline levels (1,3,...)}
16070 oddeven @r{allow all outline levels}
16073 @vindex org-put-time-stamp-overlays
16074 @vindex org-time-stamp-overlay-formats
16075 To turn on custom format overlays over timestamps (variables
16076 @code{org-put-time-stamp-overlays} and
16077 @code{org-time-stamp-overlay-formats}), use
16078 @cindex @code{customtime}, STARTUP keyword
16080 customtime @r{overlay custom time format}
16083 @vindex constants-unit-system
16084 The following options influence the table spreadsheet (variable
16085 @code{constants-unit-system}).
16086 @cindex @code{constcgs}, STARTUP keyword
16087 @cindex @code{constSI}, STARTUP keyword
16089 constcgs @r{@file{constants.el} should use the c-g-s unit system}
16090 constSI @r{@file{constants.el} should use the SI unit system}
16093 @vindex org-footnote-define-inline
16094 @vindex org-footnote-auto-label
16095 @vindex org-footnote-auto-adjust
16096 To influence footnote settings, use the following keywords. The
16097 corresponding variables are @code{org-footnote-define-inline},
16098 @code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.
16099 @cindex @code{fninline}, STARTUP keyword
16100 @cindex @code{nofninline}, STARTUP keyword
16101 @cindex @code{fnlocal}, STARTUP keyword
16102 @cindex @code{fnprompt}, STARTUP keyword
16103 @cindex @code{fnauto}, STARTUP keyword
16104 @cindex @code{fnconfirm}, STARTUP keyword
16105 @cindex @code{fnplain}, STARTUP keyword
16106 @cindex @code{fnadjust}, STARTUP keyword
16107 @cindex @code{nofnadjust}, STARTUP keyword
16109 fninline @r{define footnotes inline}
16110 fnnoinline @r{define footnotes in separate section}
16111 fnlocal @r{define footnotes near first reference, but not inline}
16112 fnprompt @r{prompt for footnote labels}
16113 fnauto @r{create @code{[fn:1]}-like labels automatically (default)}
16114 fnconfirm @r{offer automatic label for editing or confirmation}
16115 fnplain @r{create @code{[1]}-like labels automatically}
16116 fnadjust @r{automatically renumber and sort footnotes}
16117 nofnadjust @r{do not renumber and sort automatically}
16120 @cindex org-hide-block-startup
16121 To hide blocks on startup, use these keywords. The corresponding variable is
16122 @code{org-hide-block-startup}.
16123 @cindex @code{hideblocks}, STARTUP keyword
16124 @cindex @code{nohideblocks}, STARTUP keyword
16126 hideblocks @r{Hide all begin/end blocks on startup}
16127 nohideblocks @r{Do not hide blocks on startup}
16130 @cindex org-pretty-entities
16131 The display of entities as UTF-8 characters is governed by the variable
16132 @code{org-pretty-entities} and the keywords
16133 @cindex @code{entitiespretty}, STARTUP keyword
16134 @cindex @code{entitiesplain}, STARTUP keyword
16136 entitiespretty @r{Show entities as UTF-8 characters where possible}
16137 entitiesplain @r{Leave entities plain}
16140 @item #+TAGS: TAG1(c1) TAG2(c2)
16141 @vindex org-tag-alist
16142 These lines (several such lines are allowed) specify the valid tags in
16143 this file, and (potentially) the corresponding @emph{fast tag selection}
16144 keys. The corresponding variable is @code{org-tag-alist}.
16147 This line contains the formulas for the table directly above the line.
16149 Table can have multiple lines containing @samp{#+TBLFM:}. Note
16150 that only the first line of @samp{#+TBLFM:} will be applied when
16151 you recalculate the table. For more details see @ref{Using
16152 multiple #+TBLFM lines} in @ref{Editing and debugging formulas}.
16154 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:,
16155 @itemx #+OPTIONS:, #+BIND:,
16156 @itemx #+DESCRIPTION:, #+KEYWORDS:,
16157 @itemx #+LaTeX_HEADER:, #+LaTeX_HEADER_EXTRA:,
16158 @itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
16159 @itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
16160 These lines provide settings for exporting files. For more details see
16161 @ref{Export settings}.
16162 @item #+TODO: #+SEQ_TODO: #+TYP_TODO:
16163 @vindex org-todo-keywords
16164 These lines set the TODO keywords and their interpretation in the
16165 current file. The corresponding variable is @code{org-todo-keywords}.
16168 @node The very busy C-c C-c key
16169 @section The very busy C-c C-c key
16171 @cindex C-c C-c, overview
16173 The key @kbd{C-c C-c} has many purposes in Org, which are all
16174 mentioned scattered throughout this manual. One specific function of
16175 this key is to add @emph{tags} to a headline (@pxref{Tags}). In many
16176 other circumstances it means something like @emph{``Hey Org, look
16177 here and update according to what you see here''}. Here is a summary of
16178 what this means in different contexts.
16182 If there are highlights in the buffer from the creation of a sparse
16183 tree, or from clock display, remove these highlights.
16185 If the cursor is in one of the special @code{#+KEYWORD} lines, this
16186 triggers scanning the buffer for these lines and updating the
16189 If the cursor is inside a table, realign the table. This command
16190 works even if the automatic table editor has been turned off.
16192 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
16195 If the current buffer is a capture buffer, close the note and file it.
16196 With a prefix argument, file it, without further interaction, to the
16199 If the cursor is on a @code{<<<target>>>}, update radio targets and
16200 corresponding links in this buffer.
16202 If the cursor is in a property line or at the start or end of a property
16203 drawer, offer property commands.
16205 If the cursor is at a footnote reference, go to the corresponding
16206 definition, and @emph{vice versa}.
16208 If the cursor is on a statistics cookie, update it.
16210 If the cursor is in a plain list item with a checkbox, toggle the status
16213 If the cursor is on a numbered item in a plain list, renumber the
16216 If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
16219 If the cursor is at a timestamp, fix the day name in the timestamp.
16223 @section A cleaner outline view
16224 @cindex hiding leading stars
16225 @cindex dynamic indentation
16226 @cindex odd-levels-only outlines
16227 @cindex clean outline view
16229 Some people find it noisy and distracting that the Org headlines start with a
16230 potentially large number of stars, and that text below the headlines is not
16231 indented. While this is no problem when writing a @emph{book-like} document
16232 where the outline headings are really section headings, in a more
16233 @emph{list-oriented} outline, indented structure is a lot cleaner:
16237 * Top level headline | * Top level headline
16238 ** Second level | * Second level
16239 *** 3rd level | * 3rd level
16240 some text | some text
16241 *** 3rd level | * 3rd level
16242 more text | more text
16243 * Another top level headline | * Another top level headline
16249 If you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crash
16250 with @code{org-indent-mode}} and version 6.29 of Org, this kind of view can
16251 be achieved dynamically at display time using @code{org-indent-mode}. In
16252 this minor mode, all lines are prefixed for display with the necessary amount
16253 of space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix}
16254 property, such that @code{visual-line-mode} (or purely setting
16255 @code{word-wrap}) wraps long lines (including headlines) correctly indented.
16256 }. Also headlines are prefixed with additional stars, so that the amount of
16257 indentation shifts by two@footnote{See the variable
16258 @code{org-indent-indentation-per-level}.} spaces per level. All headline
16259 stars but the last one are made invisible using the @code{org-hide}
16260 face@footnote{Turning on @code{org-indent-mode} sets
16261 @code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
16262 @code{nil}.}; see below under @samp{2.} for more information on how this
16263 works. You can turn on @code{org-indent-mode} for all files by customizing
16264 the variable @code{org-startup-indented}, or you can turn it on for
16265 individual files using
16271 If you want a similar effect in an earlier version of Emacs and/or Org, or if
16272 you want the indentation to be hard space characters so that the plain text
16273 file looks as similar as possible to the Emacs display, Org supports you in
16278 @emph{Indentation of text below headlines}@*
16279 You may indent text below each headline to make the left boundary line up
16280 with the headline, like
16284 more text, now indented
16287 @vindex org-adapt-indentation
16288 Org supports this with paragraph filling, line wrapping, and structure
16289 editing@footnote{See also the variable @code{org-adapt-indentation}.},
16290 preserving or adapting the indentation as appropriate.
16293 @vindex org-hide-leading-stars
16294 @emph{Hiding leading stars}@* You can modify the display in such a way that
16295 all leading stars become invisible. To do this in a global way, configure
16296 the variable @code{org-hide-leading-stars} or change this on a per-file basis
16300 #+STARTUP: hidestars
16301 #+STARTUP: showstars
16304 With hidden stars, the tree becomes:
16308 * Top level headline
16316 @vindex org-hide @r{(face)}
16317 The leading stars are not truly replaced by whitespace, they are only
16318 fontified with the face @code{org-hide} that uses the background color as
16319 font color. If you are not using either white or black background, you may
16320 have to customize this face to get the wanted effect. Another possibility is
16321 to set this font such that the extra stars are @i{almost} invisible, for
16322 example using the color @code{grey90} on a white background.
16325 @vindex org-odd-levels-only
16326 Things become cleaner still if you skip all the even levels and use only odd
16327 levels 1, 3, 5..., effectively adding two stars to go from one outline level
16328 to the next@footnote{When you need to specify a level for a property search
16329 or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc.}. In this
16330 way we get the outline view shown at the beginning of this section. In order
16331 to make the structure editing and export commands handle this convention
16332 correctly, configure the variable @code{org-odd-levels-only}, or set this on
16333 a per-file basis with one of the following lines:
16340 You can convert an Org file from single-star-per-level to the
16341 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
16342 RET} in that file. The reverse operation is @kbd{M-x
16343 org-convert-to-oddeven-levels}.
16347 @section Using Org on a tty
16348 @cindex tty key bindings
16350 Because Org contains a large number of commands, by default many of
16351 Org's core commands are bound to keys that are generally not
16352 accessible on a tty, such as the cursor keys (@key{left}, @key{right},
16353 @key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used
16354 together with modifiers like @key{Meta} and/or @key{Shift}. To access
16355 these commands on a tty when special keys are unavailable, the following
16356 alternative bindings can be used. The tty bindings below will likely be
16357 more cumbersome; you may find for some of the bindings below that a
16358 customized workaround suits you better. For example, changing a timestamp
16359 is really only fun with @kbd{S-@key{cursor}} keys, whereas on a
16360 tty you would rather use @kbd{C-c .} to re-insert the timestamp.
16362 @multitable @columnfractions 0.15 0.2 0.1 0.2
16363 @item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
16364 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab
16365 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
16366 @item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab
16367 @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
16368 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab
16369 @item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
16370 @item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab
16371 @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
16372 @item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab
16373 @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab
16374 @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
16375 @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab
16376 @item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab
16377 @item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab
16378 @item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab
16379 @item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab
16380 @item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab
16381 @item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab
16386 @section Interaction with other packages
16387 @cindex packages, interaction with other
16388 Org lives in the world of GNU Emacs and interacts in various ways
16389 with other code out there.
16392 * Cooperation:: Packages Org cooperates with
16393 * Conflicts:: Packages that lead to conflicts
16397 @subsection Packages that Org cooperates with
16400 @cindex @file{calc.el}
16401 @cindex Gillespie, Dave
16402 @item @file{calc.el} by Dave Gillespie
16403 Org uses the Calc package for implementing spreadsheet
16404 functionality in its tables (@pxref{The spreadsheet}). Org
16405 checks for the availability of Calc by looking for the function
16406 @code{calc-eval} which will have been autoloaded during setup if Calc has
16407 been installed properly. As of Emacs 22, Calc is part of the Emacs
16408 distribution. Another possibility for interaction between the two
16409 packages is using Calc for embedded calculations. @xref{Embedded Mode,
16410 , Embedded Mode, calc, GNU Emacs Calc Manual}.
16411 @item @file{constants.el} by Carsten Dominik
16412 @cindex @file{constants.el}
16413 @cindex Dominik, Carsten
16414 @vindex org-table-formula-constants
16415 In a table formula (@pxref{The spreadsheet}), it is possible to use
16416 names for natural constants or units. Instead of defining your own
16417 constants in the variable @code{org-table-formula-constants}, install
16418 the @file{constants} package which defines a large number of constants
16419 and units, and lets you use unit prefixes like @samp{M} for
16420 @samp{Mega}, etc. You will need version 2.0 of this package, available
16421 at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for
16422 the function @code{constants-get}, which has to be autoloaded in your
16423 setup. See the installation instructions in the file
16424 @file{constants.el}.
16425 @item @file{cdlatex.el} by Carsten Dominik
16426 @cindex @file{cdlatex.el}
16427 @cindex Dominik, Carsten
16428 Org mode can make use of the CD@LaTeX{} package to efficiently enter
16429 @LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}.
16430 @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
16431 @cindex @file{imenu.el}
16432 Imenu allows menu access to an index of items in a file. Org mode
16433 supports Imenu---all you need to do to get the index is the following:
16435 (add-hook 'org-mode-hook
16436 (lambda () (imenu-add-to-menubar "Imenu")))
16438 @vindex org-imenu-depth
16439 By default the index is two levels deep---you can modify the depth using
16440 the option @code{org-imenu-depth}.
16441 @item @file{remember.el} by John Wiegley
16442 @cindex @file{remember.el}
16443 @cindex Wiegley, John
16444 Org used to use this package for capture, but no longer does.
16445 @item @file{speedbar.el} by Eric M. Ludlam
16446 @cindex @file{speedbar.el}
16447 @cindex Ludlam, Eric M.
16448 Speedbar is a package that creates a special frame displaying files and
16449 index items in files. Org mode supports Speedbar and allows you to
16450 drill into Org files directly from the Speedbar. It also allows you to
16451 restrict the scope of agenda commands to a file or a subtree by using
16452 the command @kbd{<} in the Speedbar frame.
16453 @cindex @file{table.el}
16454 @item @file{table.el} by Takaaki Ota
16456 @cindex table editor, @file{table.el}
16457 @cindex @file{table.el}
16458 @cindex Ota, Takaaki
16460 Complex ASCII tables with automatic line wrapping, column- and row-spanning,
16461 and alignment can be created using the Emacs table package by Takaaki Ota
16462 (@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22).
16463 Org mode will recognize these tables and export them properly. Because of
16464 interference with other Org mode functionality, you unfortunately cannot edit
16465 these tables directly in the buffer. Instead, you need to use the command
16466 @kbd{C-c '} to edit them, similar to source code snippets.
16469 @orgcmd{C-c ',org-edit-special}
16470 Edit a @file{table.el} table. Works when the cursor is in a table.el table.
16472 @orgcmd{C-c ~,org-table-create-with-table.el}
16473 Insert a @file{table.el} table. If there is already a table at point, this
16474 command converts it between the @file{table.el} format and the Org mode
16475 format. See the documentation string of the command
16476 @code{org-convert-table} for the restrictions under which this is
16479 @file{table.el} is part of Emacs since Emacs 22.
16480 @item @file{footnote.el} by Steven L. Baur
16481 @cindex @file{footnote.el}
16482 @cindex Baur, Steven L.
16483 Org mode recognizes numerical footnotes as provided by this package.
16484 However, Org mode also has its own footnote support (@pxref{Footnotes}),
16485 which makes using @file{footnote.el} unnecessary.
16489 @subsection Packages that lead to conflicts with Org mode
16493 @cindex @code{shift-selection-mode}
16494 @vindex org-support-shift-select
16495 In Emacs 23, @code{shift-selection-mode} is on by default, meaning that
16496 cursor motions combined with the shift key should start or enlarge regions.
16497 This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change
16498 timestamps, TODO keywords, priorities, and item bullet types if the cursor is
16499 at such a location. By default, @kbd{S-@key{cursor}} commands outside
16500 special contexts don't do anything, but you can customize the variable
16501 @code{org-support-shift-select}. Org mode then tries to accommodate shift
16502 selection by (i) using it outside of the special contexts where special
16503 commands apply, and by (ii) extending an existing active region even if the
16504 cursor moves across a special context.
16506 @item @file{CUA.el} by Kim. F. Storm
16507 @cindex @file{CUA.el}
16508 @cindex Storm, Kim. F.
16509 @vindex org-replace-disputed-keys
16510 Key bindings in Org conflict with the @kbd{S-<cursor>} keys used by CUA mode
16511 (as well as @code{pc-select-mode} and @code{s-region-mode}) to select and
16512 extend the region. In fact, Emacs 23 has this built-in in the form of
16513 @code{shift-selection-mode}, see previous paragraph. If you are using Emacs
16514 23, you probably don't want to use another package for this purpose.
16515 However, if you prefer to leave these keys to a different package while
16516 working in Org mode, configure the variable @code{org-replace-disputed-keys}.
16517 When set, Org will move the following key bindings in Org files, and in the
16518 agenda buffer (but not during date selection).
16521 S-UP @result{} M-p S-DOWN @result{} M-n
16522 S-LEFT @result{} M-- S-RIGHT @result{} M-+
16523 C-S-LEFT @result{} M-S-- C-S-RIGHT @result{} M-S-+
16526 @vindex org-disputed-keys
16527 Yes, these are unfortunately more difficult to remember. If you want
16528 to have other replacement keys, look at the variable
16529 @code{org-disputed-keys}.
16531 @item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org}
16532 @cindex @file{ecomplete.el}
16534 Ecomplete provides ``electric'' address completion in address header
16535 lines in message buffers. Sadly Orgtbl mode cuts ecompletes power
16536 supply: No completion happens when Orgtbl mode is enabled in message
16537 buffers while entering text in address header lines. If one wants to
16538 use ecomplete one should @emph{not} follow the advice to automagically
16539 turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but
16540 instead---after filling in the message headers---turn on Orgtbl mode
16541 manually when needed in the messages body.
16543 @item @file{filladapt.el} by Kyle Jones
16544 @cindex @file{filladapt.el}
16546 Org mode tries to do the right thing when filling paragraphs, list items and
16547 other elements. Many users reported they had problems using both
16548 @file{filladapt.el} and Org mode, so a safe thing to do is to disable it like
16552 (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
16555 @item @file{yasnippet.el}
16556 @cindex @file{yasnippet.el}
16557 The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of
16558 @code{"\t"}) overrules YASnippet's access to this key. The following code
16559 fixed this problem:
16562 (add-hook 'org-mode-hook
16564 (org-set-local 'yas/trigger-key [tab])
16565 (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
16568 The latest version of yasnippet doesn't play well with Org mode. If the
16569 above code does not fix the conflict, start by defining the following
16573 (defun yas/org-very-safe-expand ()
16574 (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
16577 Then, tell Org mode what to do with the new function:
16580 (add-hook 'org-mode-hook
16582 (make-variable-buffer-local 'yas/trigger-key)
16583 (setq yas/trigger-key [tab])
16584 (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
16585 (define-key yas/keymap [tab] 'yas/next-field)))
16588 @item @file{windmove.el} by Hovav Shacham
16589 @cindex @file{windmove.el}
16590 This package also uses the @kbd{S-<cursor>} keys, so everything written
16591 in the paragraph above about CUA mode also applies here. If you want make
16592 the windmove function active in locations where Org mode does not have
16593 special functionality on @kbd{S-@key{cursor}}, add this to your
16597 ;; Make windmove work in org-mode:
16598 (add-hook 'org-shiftup-final-hook 'windmove-up)
16599 (add-hook 'org-shiftleft-final-hook 'windmove-left)
16600 (add-hook 'org-shiftdown-final-hook 'windmove-down)
16601 (add-hook 'org-shiftright-final-hook 'windmove-right)
16604 @item @file{viper.el} by Michael Kifer
16605 @cindex @file{viper.el}
16607 Viper uses @kbd{C-c /} and therefore makes this key not access the
16608 corresponding Org mode command @code{org-sparse-tree}. You need to find
16609 another key for this command, or override the key in
16610 @code{viper-vi-global-user-map} with
16613 (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
16621 @section org-crypt.el
16622 @cindex @file{org-crypt.el}
16623 @cindex @code{org-decrypt-entry}
16625 Org-crypt will encrypt the text of an entry, but not the headline, or
16626 properties. Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
16629 Any text below a headline that has a @samp{:crypt:} tag will be automatically
16630 be encrypted when the file is saved. If you want to use a different tag just
16631 customize the @code{org-crypt-tag-matcher} setting.
16633 To use org-crypt it is suggested that you have the following in your
16637 (require 'org-crypt)
16638 (org-crypt-use-before-save-magic)
16639 (setq org-tags-exclude-from-inheritance (quote ("crypt")))
16641 (setq org-crypt-key nil)
16642 ;; GPG key to use for encryption
16643 ;; Either the Key ID or set to nil to use symmetric encryption.
16645 (setq auto-save-default nil)
16646 ;; Auto-saving does not cooperate with org-crypt.el: so you need
16647 ;; to turn it off if you plan to use org-crypt.el quite often.
16648 ;; Otherwise, you'll get an (annoying) message each time you
16651 ;; To turn it off only locally, you can insert this:
16653 ;; # -*- buffer-auto-save-file-name: nil; -*-
16656 Excluding the crypt tag from inheritance prevents already encrypted text
16657 being encrypted again.
16663 This appendix covers some areas where users can extend the functionality of
16667 * Hooks:: How to reach into Org's internals
16668 * Add-on packages:: Available extensions
16669 * Adding hyperlink types:: New custom link types
16670 * Adding export back-ends:: How to write new export back-ends
16671 * Context-sensitive commands:: How to add functionality to such commands
16672 * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
16673 * Dynamic blocks:: Automatically filled blocks
16674 * Special agenda views:: Customized views
16675 * Speeding up your agendas:: Tips on how to speed up your agendas
16676 * Extracting agenda information:: Post-processing of agenda information
16677 * Using the property API:: Writing programs that use entry properties
16678 * Using the mapping API:: Mapping over all or selected entries
16685 Org has a large number of hook variables that can be used to add
16686 functionality. This appendix about hacking is going to illustrate the
16687 use of some of them. A complete list of all hooks with documentation is
16688 maintained by the Worg project and can be found at
16689 @uref{http://orgmode.org/worg/org-configs/org-hooks.php}.
16691 @node Add-on packages
16692 @section Add-on packages
16693 @cindex add-on packages
16695 A large number of add-on packages have been written by various authors.
16697 These packages are not part of Emacs, but they are distributed as contributed
16698 packages with the separate release available at @uref{http://orgmode.org}.
16699 See the @file{contrib/README} file in the source code directory for a list of
16700 contributed files. You may also find some more information on the Worg page:
16701 @uref{http://orgmode.org/worg/org-contrib/}.
16703 @node Adding hyperlink types
16704 @section Adding hyperlink types
16705 @cindex hyperlinks, adding new types
16707 Org has a large number of hyperlink types built-in
16708 (@pxref{Hyperlinks}). If you would like to add new link types, Org
16709 provides an interface for doing so. Let's look at an example file,
16710 @file{org-man.el}, that will add support for creating links like
16711 @samp{[[man:printf][The printf manpage]]} to show Unix manual pages inside
16715 ;;; org-man.el - Support for links to manpages in Org
16719 (org-add-link-type "man" 'org-man-open)
16720 (add-hook 'org-store-link-functions 'org-man-store-link)
16722 (defcustom org-man-command 'man
16723 "The Emacs command to be used to display a man page."
16725 :type '(choice (const man) (const woman)))
16727 (defun org-man-open (path)
16728 "Visit the manpage on PATH.
16729 PATH should be a topic that can be thrown at the man command."
16730 (funcall org-man-command path))
16732 (defun org-man-store-link ()
16733 "Store a link to a manpage."
16734 (when (memq major-mode '(Man-mode woman-mode))
16735 ;; This is a man page, we do make this link
16736 (let* ((page (org-man-get-page-name))
16737 (link (concat "man:" page))
16738 (description (format "Manpage for %s" page)))
16739 (org-store-link-props
16742 :description description))))
16744 (defun org-man-get-page-name ()
16745 "Extract the page name from the buffer name."
16746 ;; This works for both `Man-mode' and `woman-mode'.
16747 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
16748 (match-string 1 (buffer-name))
16749 (error "Cannot create link to this man page")))
16753 ;;; org-man.el ends here
16757 You would activate this new link type in @file{.emacs} with
16764 Let's go through the file and see what it does.
16767 It does @code{(require 'org)} to make sure that @file{org.el} has been
16770 The next line calls @code{org-add-link-type} to define a new link type
16771 with prefix @samp{man}. The call also contains the name of a function
16772 that will be called to follow such a link.
16774 @vindex org-store-link-functions
16775 The next line adds a function to @code{org-store-link-functions}, in
16776 order to allow the command @kbd{C-c l} to record a useful link in a
16777 buffer displaying a man page.
16780 The rest of the file defines the necessary variables and functions.
16781 First there is a customization variable that determines which Emacs
16782 command should be used to display man pages. There are two options,
16783 @code{man} and @code{woman}. Then the function to follow a link is
16784 defined. It gets the link path as an argument---in this case the link
16785 path is just a topic for the manual command. The function calls the
16786 value of @code{org-man-command} to display the man page.
16788 Finally the function @code{org-man-store-link} is defined. When you try
16789 to store a link with @kbd{C-c l}, this function will be called to
16790 try to make a link. The function must first decide if it is supposed to
16791 create the link for this buffer type; we do this by checking the value
16792 of the variable @code{major-mode}. If not, the function must exit and
16793 return the value @code{nil}. If yes, the link is created by getting the
16794 manual topic from the buffer name and prefixing it with the string
16795 @samp{man:}. Then it must call the command @code{org-store-link-props}
16796 and set the @code{:type} and @code{:link} properties. Optionally you
16797 can also set the @code{:description} property to provide a default for
16798 the link description when the link is later inserted into an Org
16799 buffer with @kbd{C-c C-l}.
16801 When it makes sense for your new link type, you may also define a function
16802 @code{org-PREFIX-complete-link} that implements special (e.g., completion)
16803 support for inserting such a link with @kbd{C-c C-l}. Such a function should
16804 not accept any arguments, and return the full link with prefix.
16806 @node Adding export back-ends
16807 @section Adding export back-ends
16808 @cindex Export, writing back-ends
16810 Org 8.0 comes with a completely rewritten export engine which makes it easy
16811 to write new export back-ends, either from scratch, or by deriving them
16812 from existing ones.
16814 Your two entry points are respectively @code{org-export-define-backend} and
16815 @code{org-export-define-derived-backend}. To grok these functions, you
16816 should first have a look at @file{ox-latex.el} (for how to define a new
16817 back-end from scratch) and @file{ox-beamer.el} (for how to derive a new
16818 back-end from an existing one.
16820 When creating a new back-end from scratch, the basic idea is to set the name
16821 of the back-end (as a symbol) and an an alist of elements and export
16822 functions. On top of this, you will need to set additional keywords like
16823 @code{:menu-entry} (to display the back-end in the export dispatcher),
16824 @code{:export-block} (to specify what blocks should not be exported by this
16825 back-end), and @code{:options-alist} (to let the user set export options that
16826 are specific to this back-end.)
16828 Deriving a new back-end is similar, except that you need to set
16829 @code{:translate-alist} to an alist of export functions that should be used
16830 instead of the parent back-end functions.
16832 For a complete reference documentation, see
16833 @url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
16834 Reference on Worg}.
16836 @node Context-sensitive commands
16837 @section Context-sensitive commands
16838 @cindex context-sensitive commands, hooks
16839 @cindex add-ons, context-sensitive commands
16840 @vindex org-ctrl-c-ctrl-c-hook
16842 Org has several commands that act differently depending on context. The most
16843 important example is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).
16844 Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property.
16846 Add-ons can tap into this functionality by providing a function that detects
16847 special context for that add-on and executes functionality appropriate for
16848 the context. Here is an example from Dan Davison's @file{org-R.el} which
16849 allows you to evaluate commands based on the @file{R} programming language
16850 @footnote{@file{org-R.el} has been replaced by the Org mode functionality
16851 described in @ref{Working with source code} and is now obsolete.}. For this
16852 package, special contexts are lines that start with @code{#+R:} or
16856 (defun org-R-apply-maybe ()
16857 "Detect if this is context for org-R and execute R commands."
16858 (if (save-excursion
16859 (beginning-of-line 1)
16860 (looking-at "#\\+RR?:"))
16861 (progn (call-interactively 'org-R-apply)
16862 t) ;; to signal that we took action
16863 nil)) ;; to signal that we did not
16865 (add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe)
16868 The function first checks if the cursor is in such a line. If that is the
16869 case, @code{org-R-apply} is called and the function returns @code{t} to
16870 signal that action was taken, and @kbd{C-c C-c} will stop looking for other
16871 contexts. If the function finds it should do nothing locally, it returns
16872 @code{nil} so that other, similar functions can have a try.
16875 @node Tables in arbitrary syntax
16876 @section Tables and lists in arbitrary syntax
16877 @cindex tables, in other modes
16878 @cindex lists, in other modes
16879 @cindex Orgtbl mode
16881 Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a
16882 frequent feature request has been to make it work with native tables in
16883 specific languages, for example @LaTeX{}. However, this is extremely
16884 hard to do in a general way, would lead to a customization nightmare,
16885 and would take away much of the simplicity of the Orgtbl mode table
16888 This appendix describes a different approach. We keep the Orgtbl mode
16889 table in its native format (the @i{source table}), and use a custom
16890 function to @i{translate} the table to the correct syntax, and to
16891 @i{install} it in the right location (the @i{target table}). This puts
16892 the burden of writing conversion functions on the user, but it allows
16893 for a very flexible system.
16895 Bastien added the ability to do the same with lists, in Orgstruct mode. You
16896 can use Org's facilities to edit and structure lists by turning
16897 @code{orgstruct-mode} on, then locally exporting such lists in another format
16898 (HTML, @LaTeX{} or Texinfo.)
16902 * Radio tables:: Sending and receiving radio tables
16903 * A @LaTeX{} example:: Step by step, almost a tutorial
16904 * Translator functions:: Copy and modify
16905 * Radio lists:: Sending and receiving lists
16909 @subsection Radio tables
16910 @cindex radio tables
16912 To define the location of the target table, you first need to create two
16913 lines that are comments in the current mode, but contain magic words
16914 @code{BEGIN/END RECEIVE ORGTBL} for Orgtbl mode to find. Orgtbl mode will
16915 insert the translated table between these lines, replacing whatever was there
16916 before. For example in C mode where comments are between @code{/* ... */}:
16919 /* BEGIN RECEIVE ORGTBL table_name */
16920 /* END RECEIVE ORGTBL table_name */
16924 Just above the source table, we put a special line that tells
16925 Orgtbl mode how to translate this table and where to install it. For
16929 #+ORGTBL: SEND table_name translation_function arguments...
16933 @code{table_name} is the reference name for the table that is also used
16934 in the receiver lines. @code{translation_function} is the Lisp function
16935 that does the translation. Furthermore, the line can contain a list of
16936 arguments (alternating key and value) at the end. The arguments will be
16937 passed as a property list to the translation function for
16938 interpretation. A few standard parameters are already recognized and
16939 acted upon before the translation function is called:
16943 Skip the first N lines of the table. Hlines do count as separate lines for
16946 @item :skipcols (n1 n2 ...)
16947 List of columns that should be skipped. If the table has a column with
16948 calculation marks, that column is automatically discarded as well.
16949 Please note that the translator function sees the table @emph{after} the
16950 removal of these columns, the function never knows that there have been
16951 additional columns.
16954 When non-@code{nil}, do not escape special characters @code{&%#_^} when exporting
16955 the table. The default value is @code{nil}.
16959 The one problem remaining is how to keep the source table in the buffer
16960 without disturbing the normal workings of the file, for example during
16961 compilation of a C file or processing of a @LaTeX{} file. There are a
16962 number of different solutions:
16966 The table could be placed in a block comment if that is supported by the
16967 language. For example, in C mode you could wrap the table between
16968 @samp{/*} and @samp{*/} lines.
16970 Sometimes it is possible to put the table after some kind of @i{END}
16971 statement, for example @samp{\bye} in @TeX{} and @samp{\end@{document@}}
16974 You can just comment the table line-by-line whenever you want to process
16975 the file, and uncomment it whenever you need to edit the table. This
16976 only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment RET}
16977 makes this comment-toggling very easy, in particular if you bind it to a
16981 @node A @LaTeX{} example
16982 @subsection A @LaTeX{} example of radio tables
16983 @cindex @LaTeX{}, and Orgtbl mode
16985 The best way to wrap the source table in @LaTeX{} is to use the
16986 @code{comment} environment provided by @file{comment.sty}. It has to be
16987 activated by placing @code{\usepackage@{comment@}} into the document
16988 header. Orgtbl mode can insert a radio table skeleton@footnote{By
16989 default this works only for @LaTeX{}, HTML, and Texinfo. Configure the
16990 variable @code{orgtbl-radio-table-templates} to install templates for other
16991 modes.} with the command @kbd{M-x orgtbl-insert-radio-table RET}. You will
16992 be prompted for a table name, let's say we use @samp{salesfigures}. You
16993 will then get the following template:
16995 @cindex #+ORGTBL, SEND
16997 % BEGIN RECEIVE ORGTBL salesfigures
16998 % END RECEIVE ORGTBL salesfigures
17000 #+ORGTBL: SEND salesfigures orgtbl-to-latex
17006 @vindex @LaTeX{}-verbatim-environments
17007 The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function
17008 @code{orgtbl-to-latex} to convert the table into @LaTeX{} and to put it
17009 into the receiver location with name @code{salesfigures}. You may now
17010 fill in the table---feel free to use the spreadsheet features@footnote{If
17011 the @samp{#+TBLFM} line contains an odd number of dollar characters,
17012 this may cause problems with font-lock in @LaTeX{} mode. As shown in the
17013 example you can fix this by adding an extra line inside the
17014 @code{comment} environment that is used to balance the dollar
17015 expressions. If you are using AUC@TeX{} with the font-latex library, a
17016 much better solution is to add the @code{comment} environment to the
17017 variable @code{LaTeX-verbatim-environments}.}:
17020 % BEGIN RECEIVE ORGTBL salesfigures
17021 % END RECEIVE ORGTBL salesfigures
17023 #+ORGTBL: SEND salesfigures orgtbl-to-latex
17024 | Month | Days | Nr sold | per day |
17025 |-------+------+---------+---------|
17026 | Jan | 23 | 55 | 2.4 |
17027 | Feb | 21 | 16 | 0.8 |
17028 | March | 22 | 278 | 12.6 |
17029 #+TBLFM: $4=$3/$2;%.1f
17030 % $ (optional extra dollar to keep font-lock happy, see footnote)
17035 When you are done, press @kbd{C-c C-c} in the table to get the converted
17036 table inserted between the two marker lines.
17038 Now let's assume you want to make the table header by hand, because you
17039 want to control how columns are aligned, etc. In this case we make sure
17040 that the table translator skips the first 2 lines of the source
17041 table, and tell the command to work as a @i{splice}, i.e., to not produce
17042 header and footer commands of the target table:
17045 \begin@{tabular@}@{lrrr@}
17046 Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
17047 % BEGIN RECEIVE ORGTBL salesfigures
17048 % END RECEIVE ORGTBL salesfigures
17052 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
17053 | Month | Days | Nr sold | per day |
17054 |-------+------+---------+---------|
17055 | Jan | 23 | 55 | 2.4 |
17056 | Feb | 21 | 16 | 0.8 |
17057 | March | 22 | 278 | 12.6 |
17058 #+TBLFM: $4=$3/$2;%.1f
17062 The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
17063 Orgtbl mode. It uses a @code{tabular} environment to typeset the table
17064 and marks horizontal lines with @code{\hline}. Furthermore, it
17065 interprets the following parameters (see also @pxref{Translator functions}):
17068 @item :splice nil/t
17069 When set to t, return only table body lines, don't wrap them into a
17070 tabular environment. Default is @code{nil}.
17073 A format to be used to wrap each field, it should contain @code{%s} for the
17074 original field value. For example, to wrap each field value in dollars,
17075 you could use @code{:fmt "$%s$"}. This may also be a property list with
17076 column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
17077 A function of one argument can be used in place of the strings; the
17078 function must return a formatted string.
17081 Use this format to print numbers with exponentials. The format should
17082 have @code{%s} twice for inserting mantissa and exponent, for example
17083 @code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This
17084 may also be a property list with column numbers and formats, for example
17085 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
17086 @code{efmt} has been applied to a value, @code{fmt} will also be
17087 applied. Similar to @code{fmt}, functions of two arguments can be
17088 supplied instead of strings.
17091 @node Translator functions
17092 @subsection Translator functions
17093 @cindex HTML, and Orgtbl mode
17094 @cindex translator function
17096 Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv}
17097 (comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values)
17098 @code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}.
17099 Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the same
17100 code that produces tables during HTML export.}, these all use a generic
17101 translator, @code{orgtbl-to-generic}. For example, @code{orgtbl-to-latex}
17102 itself is a very short function that computes the column definitions for the
17103 @code{tabular} environment, defines a few field and line separators and then
17104 hands processing over to the generic translator. Here is the entire code:
17108 (defun orgtbl-to-latex (table params)
17109 "Convert the Orgtbl mode TABLE to LaTeX."
17110 (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
17111 org-table-last-alignment ""))
17114 :tstart (concat "\\begin@{tabular@}@{" alignment "@}")
17115 :tend "\\end@{tabular@}"
17116 :lstart "" :lend " \\\\" :sep " & "
17117 :efmt "%s\\,(%s)" :hline "\\hline")))
17118 (orgtbl-to-generic table (org-combine-plists params2 params))))
17122 As you can see, the properties passed into the function (variable
17123 @var{PARAMS}) are combined with the ones newly defined in the function
17124 (variable @var{PARAMS2}). The ones passed into the function (i.e., the
17125 ones set by the @samp{ORGTBL SEND} line) take precedence. So if you
17126 would like to use the @LaTeX{} translator, but wanted the line endings to
17127 be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
17128 overrule the default with
17131 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
17134 For a new language, you can either write your own converter function in
17135 analogy with the @LaTeX{} translator, or you can use the generic function
17136 directly. For example, if you have a language where a table is started
17137 with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are
17138 started with @samp{!BL!}, ended with @samp{!EL!}, and where the field
17139 separator is a TAB, you could call the generic translator like this (on
17143 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
17144 :lstart "!BL! " :lend " !EL!" :sep "\t"
17148 Please check the documentation string of the function
17149 @code{orgtbl-to-generic} for a full list of parameters understood by
17150 that function, and remember that you can pass each of them into
17151 @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
17152 using the generic function.
17154 Of course you can also write a completely new function doing complicated
17155 things the generic translator cannot do. A translator function takes
17156 two arguments. The first argument is the table, a list of lines, each
17157 line either the symbol @code{hline} or a list of fields. The second
17158 argument is the property list containing all parameters specified in the
17159 @samp{#+ORGTBL: SEND} line. The function must return a single string
17160 containing the formatted table. If you write a generally useful
17161 translator, please post it on @email{emacs-orgmode@@gnu.org} so that
17162 others can benefit from your work.
17165 @subsection Radio lists
17166 @cindex radio lists
17167 @cindex org-list-insert-radio-list
17169 Sending and receiving radio lists works exactly the same way as sending and
17170 receiving radio tables (@pxref{Radio tables}). As for radio tables, you can
17171 insert radio list templates in HTML, @LaTeX{} and Texinfo modes by calling
17172 @code{org-list-insert-radio-list}.
17174 Here are the differences with radio tables:
17178 Orgstruct mode must be active.
17180 Use the @code{ORGLST} keyword instead of @code{ORGTBL}.
17182 The available translation functions for radio lists don't take
17185 @kbd{C-c C-c} will work when pressed on the first item of the list.
17188 Here is a @LaTeX{} example. Let's say that you have this in your
17193 % BEGIN RECEIVE ORGLST to-buy
17194 % END RECEIVE ORGLST to-buy
17196 #+ORGLST: SEND to-buy org-list-to-latex
17205 Pressing @kbd{C-c C-c} on @code{a new house} and will insert the converted
17206 @LaTeX{} list between the two marker lines.
17208 @node Dynamic blocks
17209 @section Dynamic blocks
17210 @cindex dynamic blocks
17212 Org documents can contain @emph{dynamic blocks}. These are
17213 specially marked regions that are updated by some user-written function.
17214 A good example for such a block is the clock table inserted by the
17215 command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
17217 Dynamic blocks are enclosed by a BEGIN-END structure that assigns a name
17218 to the block and can also specify parameters for the function producing
17219 the content of the block.
17221 @cindex #+BEGIN:dynamic block
17223 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
17228 Dynamic blocks are updated with the following commands
17231 @orgcmd{C-c C-x C-u,org-dblock-update}
17232 Update dynamic block at point.
17233 @orgkey{C-u C-c C-x C-u}
17234 Update all dynamic blocks in the current file.
17237 Updating a dynamic block means to remove all the text between BEGIN and
17238 END, parse the BEGIN line for parameters and then call the specific
17239 writer function for this block to insert the new content. If you want
17240 to use the original content in the writer function, you can use the
17241 extra parameter @code{:content}.
17243 For a block with name @code{myblock}, the writer function is
17244 @code{org-dblock-write:myblock} with as only parameter a property list
17245 with the parameters given in the begin line. Here is a trivial example
17246 of a block that keeps track of when the block update function was last
17250 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
17256 The corresponding block writer function could look like this:
17259 (defun org-dblock-write:block-update-time (params)
17260 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
17261 (insert "Last block update at: "
17262 (format-time-string fmt (current-time)))))
17265 If you want to make sure that all dynamic blocks are always up-to-date,
17266 you could add the function @code{org-update-all-dblocks} to a hook, for
17267 example @code{before-save-hook}. @code{org-update-all-dblocks} is
17268 written in a way such that it does nothing in buffers that are not in
17271 You can narrow the current buffer to the current dynamic block (like any
17272 other block) with @code{org-narrow-to-block}.
17274 @node Special agenda views
17275 @section Special agenda views
17276 @cindex agenda views, user-defined
17278 @vindex org-agenda-skip-function
17279 @vindex org-agenda-skip-function-global
17280 Org provides a special hook that can be used to narrow down the selection
17281 made by these agenda views: @code{agenda}, @code{agenda*}@footnote{The
17282 @code{agenda*} view is the same as @code{agenda} except that it only
17283 considers @emph{appointments}, i.e., scheduled and deadline items that have a
17284 time specification @code{[h]h:mm} in their time-stamps.}, @code{todo},
17285 @code{alltodo}, @code{tags}, @code{tags-todo}, @code{tags-tree}. You may
17286 specify a function that is used at each match to verify if the match should
17287 indeed be part of the agenda view, and if not, how much should be skipped.
17288 You can specify a global condition that will be applied to all agenda views,
17289 this condition would be stored in the variable
17290 @code{org-agenda-skip-function-global}. More commonly, such a definition is
17291 applied only to specific custom searches, using
17292 @code{org-agenda-skip-function}.
17294 Let's say you want to produce a list of projects that contain a WAITING
17295 tag anywhere in the project tree. Let's further assume that you have
17296 marked all tree headings that define a project with the TODO keyword
17297 PROJECT@. In this case you would run a TODO search for the keyword
17298 PROJECT, but skip the match unless there is a WAITING tag anywhere in
17299 the subtree belonging to the project line.
17301 To achieve this, you must write a function that searches the subtree for
17302 the tag. If the tag is found, the function must return @code{nil} to
17303 indicate that this match should not be skipped. If there is no such
17304 tag, return the location of the end of the subtree, to indicate that
17305 search should continue from there.
17308 (defun my-skip-unless-waiting ()
17309 "Skip trees that are not waiting"
17310 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
17311 (if (re-search-forward ":waiting:" subtree-end t)
17312 nil ; tag found, do not skip
17313 subtree-end))) ; tag not found, continue after end of subtree
17316 Now you may use this function in an agenda custom command, for example
17320 (org-add-agenda-custom-command
17321 '("b" todo "PROJECT"
17322 ((org-agenda-skip-function 'my-skip-unless-waiting)
17323 (org-agenda-overriding-header "Projects waiting for something: "))))
17326 @vindex org-agenda-overriding-header
17327 Note that this also binds @code{org-agenda-overriding-header} to get a
17328 meaningful header in the agenda view.
17330 @vindex org-odd-levels-only
17331 @vindex org-agenda-skip-function
17332 A general way to create custom searches is to base them on a search for
17333 entries with a certain level limit. If you want to study all entries with
17334 your custom search function, simply do a search for
17335 @samp{LEVEL>0}@footnote{Note that, when using @code{org-odd-levels-only}, a
17336 level number corresponds to order in the hierarchy, not to the number of
17337 stars.}, and then use @code{org-agenda-skip-function} to select the entries
17338 you really want to have.
17340 You may also put a Lisp form into @code{org-agenda-skip-function}. In
17341 particular, you may use the functions @code{org-agenda-skip-entry-if}
17342 and @code{org-agenda-skip-subtree-if} in this form, for example:
17345 @item (org-agenda-skip-entry-if 'scheduled)
17346 Skip current entry if it has been scheduled.
17347 @item (org-agenda-skip-entry-if 'notscheduled)
17348 Skip current entry if it has not been scheduled.
17349 @item (org-agenda-skip-entry-if 'deadline)
17350 Skip current entry if it has a deadline.
17351 @item (org-agenda-skip-entry-if 'scheduled 'deadline)
17352 Skip current entry if it has a deadline, or if it is scheduled.
17353 @item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
17354 Skip current entry if the TODO keyword is TODO or WAITING.
17355 @item (org-agenda-skip-entry-if 'todo 'done)
17356 Skip current entry if the TODO keyword marks a DONE state.
17357 @item (org-agenda-skip-entry-if 'timestamp)
17358 Skip current entry if it has any timestamp, may also be deadline or scheduled.
17359 @anchor{x-agenda-skip-entry-regexp}
17360 @item (org-agenda-skip-entry-if 'regexp "regular expression")
17361 Skip current entry if the regular expression matches in the entry.
17362 @item (org-agenda-skip-entry-if 'notregexp "regular expression")
17363 Skip current entry unless the regular expression matches.
17364 @item (org-agenda-skip-subtree-if 'regexp "regular expression")
17365 Same as above, but check and skip the entire subtree.
17368 Therefore we could also have written the search for WAITING projects
17369 like this, even without defining a special function:
17372 (org-add-agenda-custom-command
17373 '("b" todo "PROJECT"
17374 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
17375 'regexp ":waiting:"))
17376 (org-agenda-overriding-header "Projects waiting for something: "))))
17379 @node Speeding up your agendas
17380 @section Speeding up your agendas
17381 @cindex agenda views, optimization
17383 When your Org files grow in both number and size, agenda commands may start
17384 to become slow. Below are some tips on how to speed up the agenda commands.
17388 Reduce the number of Org agenda files: this will reduce the slowdown caused
17389 by accessing a hard drive.
17391 Reduce the number of DONE and archived headlines: this way the agenda does
17392 not need to skip them.
17394 @vindex org-agenda-dim-blocked-tasks
17395 Inhibit the dimming of blocked tasks:
17397 (setq org-agenda-dim-blocked-tasks nil)
17400 @vindex org-startup-folded
17401 @vindex org-agenda-inhibit-startup
17402 Inhibit agenda files startup options:
17404 (setq org-agenda-inhibit-startup nil)
17407 @vindex org-agenda-show-inherited-tags
17408 @vindex org-agenda-use-tag-inheritance
17409 Disable tag inheritance in agenda:
17411 (setq org-agenda-use-tag-inheritance nil)
17415 You can set these options for specific agenda views only. See the docstrings
17416 of these variables for details on why they affect the agenda generation, and
17417 this @uref{http://orgmode.org/worg/agenda-optimization.html, dedicated Worg
17418 page} for further explanations.
17420 @node Extracting agenda information
17421 @section Extracting agenda information
17422 @cindex agenda, pipe
17423 @cindex Scripts, for agenda processing
17425 @vindex org-agenda-custom-commands
17426 Org provides commands to access agenda information for the command
17427 line in Emacs batch mode. This extracted information can be sent
17428 directly to a printer, or it can be read by a program that does further
17429 processing of the data. The first of these commands is the function
17430 @code{org-batch-agenda}, that produces an agenda view and sends it as
17431 ASCII text to STDOUT@. The command takes a single string as parameter.
17432 If the string has length 1, it is used as a key to one of the commands
17433 you have configured in @code{org-agenda-custom-commands}, basically any
17434 key you can use after @kbd{C-c a}. For example, to directly print the
17435 current TODO list, you could use
17438 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
17441 If the parameter is a string with 2 or more characters, it is used as a
17442 tags/TODO match string. For example, to print your local shopping list
17443 (all items with the tag @samp{shop}, but excluding the tag
17444 @samp{NewYork}), you could use
17447 emacs -batch -l ~/.emacs \
17448 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
17452 You may also modify parameters on the fly like this:
17455 emacs -batch -l ~/.emacs \
17456 -eval '(org-batch-agenda "a" \
17457 org-agenda-span (quote month) \
17458 org-agenda-include-diary nil \
17459 org-agenda-files (quote ("~/org/project.org")))' \
17464 which will produce a 30-day agenda, fully restricted to the Org file
17465 @file{~/org/projects.org}, not even including the diary.
17467 If you want to process the agenda data in more sophisticated ways, you
17468 can use the command @code{org-batch-agenda-csv} to get a comma-separated
17469 list of values for each agenda item. Each line in the output will
17470 contain a number of fields separated by commas. The fields in a line
17474 category @r{The category of the item}
17475 head @r{The headline, without TODO keyword, TAGS and PRIORITY}
17476 type @r{The type of the agenda entry, can be}
17477 todo @r{selected in TODO match}
17478 tagsmatch @r{selected in tags match}
17479 diary @r{imported from diary}
17480 deadline @r{a deadline}
17481 scheduled @r{scheduled}
17482 timestamp @r{appointment, selected by timestamp}
17483 closed @r{entry was closed on date}
17484 upcoming-deadline @r{warning about nearing deadline}
17485 past-scheduled @r{forwarded scheduled item}
17486 block @r{entry has date block including date}
17487 todo @r{The TODO keyword, if any}
17488 tags @r{All tags including inherited ones, separated by colons}
17489 date @r{The relevant date, like 2007-2-14}
17490 time @r{The time, like 15:00-16:50}
17491 extra @r{String with extra planning info}
17492 priority-l @r{The priority letter if any was given}
17493 priority-n @r{The computed numerical priority}
17497 Time and date will only be given if a timestamp (or deadline/scheduled)
17498 led to the selection of the item.
17500 A CSV list like this is very easy to use in a post-processing script.
17501 For example, here is a Perl program that gets the TODO list from
17502 Emacs/Org and prints all the items, preceded by a checkbox:
17507 # define the Emacs command to run
17508 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
17510 # run it and capture the output
17511 $agenda = qx@{$cmd 2>/dev/null@};
17513 # loop over all lines
17514 foreach $line (split(/\n/,$agenda)) @{
17515 # get the individual values
17516 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
17517 $priority_l,$priority_n) = split(/,/,$line);
17518 # process and print
17519 print "[ ] $head\n";
17523 @node Using the property API
17524 @section Using the property API
17525 @cindex API, for properties
17526 @cindex properties, API
17528 Here is a description of the functions that can be used to work with
17531 @defun org-entry-properties &optional pom which
17532 Get all properties of the entry at point-or-marker POM.@*
17533 This includes the TODO keyword, the tags, time strings for deadline,
17534 scheduled, and clocking, and any additional properties defined in the
17535 entry. The return value is an alist. Keys may occur multiple times
17536 if the property key was used several times.@*
17537 POM may also be @code{nil}, in which case the current entry is used.
17538 If WHICH is @code{nil} or `all', get all properties. If WHICH is
17539 `special' or `standard', only get that subclass.
17541 @vindex org-use-property-inheritance
17542 @findex org-insert-property-drawer
17543 @defun org-entry-get pom property &optional inherit
17544 Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@. By default,
17545 this only looks at properties defined locally in the entry. If @code{INHERIT}
17546 is non-@code{nil} and the entry does not have the property, then also check
17547 higher levels of the hierarchy. If @code{INHERIT} is the symbol
17548 @code{selective}, use inheritance if and only if the setting of
17549 @code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance.
17552 @defun org-entry-delete pom property
17553 Delete the property @code{PROPERTY} from entry at point-or-marker POM.
17556 @defun org-entry-put pom property value
17557 Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM.
17560 @defun org-buffer-property-keys &optional include-specials
17561 Get all property keys in the current buffer.
17564 @defun org-insert-property-drawer
17565 Insert a property drawer for the current entry. Also
17568 @defun org-entry-put-multivalued-property pom property &rest values
17569 Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@.
17570 @code{VALUES} should be a list of strings. They will be concatenated, with
17571 spaces as separators.
17574 @defun org-entry-get-multivalued-property pom property
17575 Treat the value of the property @code{PROPERTY} as a whitespace-separated
17576 list of values and return the values as a list of strings.
17579 @defun org-entry-add-to-multivalued-property pom property value
17580 Treat the value of the property @code{PROPERTY} as a whitespace-separated
17581 list of values and make sure that @code{VALUE} is in this list.
17584 @defun org-entry-remove-from-multivalued-property pom property value
17585 Treat the value of the property @code{PROPERTY} as a whitespace-separated
17586 list of values and make sure that @code{VALUE} is @emph{not} in this list.
17589 @defun org-entry-member-in-multivalued-property pom property value
17590 Treat the value of the property @code{PROPERTY} as a whitespace-separated
17591 list of values and check if @code{VALUE} is in this list.
17594 @defopt org-property-allowed-value-functions
17595 Hook for functions supplying allowed values for a specific property.
17596 The functions must take a single argument, the name of the property, and
17597 return a flat list of allowed values. If @samp{:ETC} is one of
17598 the values, use the values as completion help, but allow also other values
17599 to be entered. The functions must return @code{nil} if they are not
17600 responsible for this property.
17603 @node Using the mapping API
17604 @section Using the mapping API
17605 @cindex API, for mapping
17606 @cindex mapping entries, API
17608 Org has sophisticated mapping capabilities to find all entries satisfying
17609 certain criteria. Internally, this functionality is used to produce agenda
17610 views, but there is also an API that can be used to execute arbitrary
17611 functions for each or selected entries. The main entry point for this API
17614 @defun org-map-entries func &optional match scope &rest skip
17615 Call @code{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}.
17617 @code{FUNC} is a function or a Lisp form. The function will be called
17618 without arguments, with the cursor positioned at the beginning of the
17619 headline. The return values of all calls to the function will be collected
17620 and returned as a list.
17622 The call to @code{FUNC} will be wrapped into a save-excursion form, so
17623 @code{FUNC} does not need to preserve point. After evaluation, the cursor
17624 will be moved to the end of the line (presumably of the headline of the
17625 processed entry) and search continues from there. Under some circumstances,
17626 this may not produce the wanted results. For example, if you have removed
17627 (e.g., archived) the current (sub)tree it could mean that the next entry will
17628 be skipped entirely. In such cases, you can specify the position from where
17629 search should continue by making @code{FUNC} set the variable
17630 @code{org-map-continue-from} to the desired buffer position.
17632 @code{MATCH} is a tags/property/todo match as it is used in the agenda match
17633 view. Only headlines that are matched by this query will be considered
17634 during the iteration. When @code{MATCH} is @code{nil} or @code{t}, all
17635 headlines will be visited by the iteration.
17637 @code{SCOPE} determines the scope of this command. It can be any of:
17640 nil @r{the current buffer, respecting the restriction if any}
17641 tree @r{the subtree started with the entry at point}
17642 region @r{The entries within the active region, if any}
17643 file @r{the current buffer, without restriction}
17645 @r{the current buffer, and any archives associated with it}
17646 agenda @r{all agenda files}
17647 agenda-with-archives
17648 @r{all agenda files with any archive files associated with them}
17650 @r{if this is a list, all files in the list will be scanned}
17653 The remaining args are treated as settings for the skipping facilities of
17654 the scanner. The following items can be given here:
17656 @vindex org-agenda-skip-function
17658 archive @r{skip trees with the archive tag}
17659 comment @r{skip trees with the COMMENT keyword}
17660 function or Lisp form
17661 @r{will be used as value for @code{org-agenda-skip-function},}
17662 @r{so whenever the function returns t, FUNC}
17663 @r{will not be called for that entry and search will}
17664 @r{continue from the point where the function leaves it}
17668 The function given to that mapping routine can really do anything you like.
17669 It can use the property API (@pxref{Using the property API}) to gather more
17670 information about the entry, or in order to change metadata in the entry.
17671 Here are a couple of functions that might be handy:
17673 @defun org-todo &optional arg
17674 Change the TODO state of the entry. See the docstring of the functions for
17675 the many possible values for the argument @code{ARG}.
17678 @defun org-priority &optional action
17679 Change the priority of the entry. See the docstring of this function for the
17680 possible values for @code{ACTION}.
17683 @defun org-toggle-tag tag &optional onoff
17684 Toggle the tag @code{TAG} in the current entry. Setting @code{ONOFF} to
17685 either @code{on} or @code{off} will not toggle tag, but ensure that it is
17690 Promote the current entry.
17694 Demote the current entry.
17697 Here is a simple example that will turn all entries in the current file with
17698 a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}.
17699 Entries in comment trees and in archive trees will be ignored.
17703 '(org-todo "UPCOMING")
17704 "+TOMORROW" 'file 'archive 'comment)
17707 The following example counts the number of entries with TODO keyword
17708 @code{WAITING}, in all agenda files.
17711 (length (org-map-entries t "/+WAITING" 'agenda))
17715 @appendix MobileOrg
17719 @i{MobileOrg} is the name of the mobile companion app for Org mode, currently
17720 available for iOS and for Android. @i{MobileOrg} offers offline viewing and
17721 capture support for an Org mode system rooted on a ``real'' computer. It
17722 also allows you to record changes to existing entries. The
17723 @uref{https://github.com/MobileOrg/, iOS implementation} for the
17724 @i{iPhone/iPod Touch/iPad} series of devices, was started by Richard Moreland
17725 and is now in the hands Sean Escriva. Android users should check out
17726 @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}
17727 by Matt Jones. The two implementations are not identical but offer similar
17730 This appendix describes the support Org has for creating agenda views in a
17731 format that can be displayed by @i{MobileOrg}, and for integrating notes
17732 captured and changes made by @i{MobileOrg} into the main system.
17734 For changing tags and TODO states in MobileOrg, you should have set up the
17735 customization variables @code{org-todo-keywords} and @code{org-tag-alist} to
17736 cover all important tags and TODO keywords, even if individual files use only
17737 part of these. MobileOrg will also offer you states and tags set up with
17738 in-buffer settings, but it will understand the logistics of TODO state
17739 @i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags
17740 (@pxref{Setting tags}) only for those set in these variables.
17743 * Setting up the staging area:: Where to interact with the mobile device
17744 * Pushing to MobileOrg:: Uploading Org files and agendas
17745 * Pulling from MobileOrg:: Integrating captured and flagged items
17748 @node Setting up the staging area
17749 @section Setting up the staging area
17751 MobileOrg needs to interact with Emacs through a directory on a server. If
17752 you are using a public server, you should consider encrypting the files that
17753 are uploaded to the server. This can be done with Org mode 7.02 and with
17754 @i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl}
17755 installation on your system. To turn on encryption, set a password in
17756 @i{MobileOrg} and, on the Emacs side, configure the variable
17757 @code{org-mobile-use-encryption}@footnote{If you can safely store the
17758 password in your Emacs setup, you might also want to configure
17759 @code{org-mobile-encryption-password}. Please read the docstring of that
17760 variable. Note that encryption will apply only to the contents of the
17761 @file{.org} files. The file names themselves will remain visible.}.
17763 The easiest way to create that directory is to use a free
17764 @uref{http://dropbox.com,Dropbox.com} account@footnote{If you cannot use
17765 Dropbox, or if your version of MobileOrg does not support it, you can use a
17766 webdav server. For more information, check out the documentation of MobileOrg and also this
17767 @uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
17768 When MobileOrg first connects to your Dropbox, it will create a directory
17769 @i{MobileOrg} inside the Dropbox. After the directory has been created, tell
17773 (setq org-mobile-directory "~/Dropbox/MobileOrg")
17776 Org mode has commands to put files for @i{MobileOrg} into that directory,
17777 and to read captured notes from there.
17779 @node Pushing to MobileOrg
17780 @section Pushing to MobileOrg
17782 This operation copies all files currently listed in @code{org-mobile-files}
17783 to the directory @code{org-mobile-directory}. By default this list contains
17784 all agenda files (as listed in @code{org-agenda-files}), but additional files
17785 can be included by customizing @code{org-mobile-files}. File names will be
17786 staged with paths relative to @code{org-directory}, so all files should be
17787 inside this directory@footnote{Symbolic links in @code{org-directory} need to
17788 have the same name as their targets.}.
17790 The push operation also creates a special Org file @file{agendas.org} with
17791 all custom agenda view defined by the user@footnote{While creating the
17792 agendas, Org mode will force ID properties on all referenced entries, so that
17793 these entries can be uniquely identified if @i{MobileOrg} flags them for
17794 further action. If you do not want to get these properties in so many
17795 entries, you can set the variable @code{org-mobile-force-id-on-agenda-items}
17796 to @code{nil}. Org mode will then rely on outline paths, in the hope that
17797 these will be unique enough.}.
17799 Finally, Org writes the file @file{index.org}, containing links to all other
17800 files. @i{MobileOrg} first reads this file from the server, and then
17801 downloads all agendas and Org files listed in it. To speed up the download,
17802 MobileOrg will only read files whose checksums@footnote{Checksums are stored
17803 automatically in the file @file{checksums.dat}} have changed.
17805 @node Pulling from MobileOrg
17806 @section Pulling from MobileOrg
17808 When @i{MobileOrg} synchronizes with the server, it not only pulls the Org
17809 files for viewing. It also appends captured entries and pointers to flagged
17810 and changed entries to the file @file{mobileorg.org} on the server. Org has
17811 a @emph{pull} operation that integrates this information into an inbox file
17812 and operates on the pointers to flagged entries. Here is how it works:
17816 Org moves all entries found in
17817 @file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this
17818 operation.} and appends them to the file pointed to by the variable
17819 @code{org-mobile-inbox-for-pull}. Each captured entry and each editing event
17820 will be a top-level entry in the inbox file.
17822 After moving the entries, Org will attempt to implement the changes made in
17823 @i{MobileOrg}. Some changes are applied directly and without user
17824 interaction. Examples are all changes to tags, TODO state, headline and body
17825 text that can be cleanly applied. Entries that have been flagged for further
17826 action will receive a tag @code{:FLAGGED:}, so that they can be easily found
17827 again. When there is a problem finding an entry or applying the change, the
17828 pointer entry will remain in the inbox and will be marked with an error
17829 message. You need to later resolve these issues by hand.
17831 Org will then generate an agenda view with all flagged entries. The user
17832 should then go through these entries and do whatever actions are necessary.
17833 If a note has been stored while flagging an entry in @i{MobileOrg}, that note
17834 will be displayed in the echo area when the cursor is on the corresponding
17840 Pressing @kbd{?} in that special agenda will display the full flagging note in
17841 another window and also push it onto the kill ring. So you could use @kbd{?
17842 z C-y C-c C-c} to store that flagging note as a normal note in the entry.
17843 Pressing @kbd{?} twice in succession will offer to remove the
17844 @code{:FLAGGED:} tag along with the recorded flagging note (which is stored
17845 in a property). In this way you indicate that the intended processing for
17846 this flagged entry is finished.
17851 If you are not able to process all flagged entries directly, you can always
17852 return to this agenda view@footnote{Note, however, that there is a subtle
17853 difference. The view created automatically by @kbd{M-x org-mobile-pull RET}
17854 is guaranteed to search all files that have been addressed by the last pull.
17855 This might include a file that is not currently in your list of agenda files.
17856 If you later use @kbd{C-c a ?} to regenerate the view, only the current
17857 agenda files will be searched.} using @kbd{C-c a ?}.
17859 @node History and acknowledgments
17860 @appendix History and acknowledgments
17861 @cindex acknowledgments
17865 @section From Carsten
17867 Org was born in 2003, out of frustration over the user interface of the Emacs
17868 Outline mode. I was trying to organize my notes and projects, and using
17869 Emacs seemed to be the natural way to go. However, having to remember eleven
17870 different commands with two or three keys per command, only to hide and show
17871 parts of the outline tree, that seemed entirely unacceptable to me. Also,
17872 when using outlines to take notes, I constantly wanted to restructure the
17873 tree, organizing it parallel to my thoughts and plans. @emph{Visibility
17874 cycling} and @emph{structure editing} were originally implemented in the
17875 package @file{outline-magic.el}, but quickly moved to the more general
17876 @file{org.el}. As this environment became comfortable for project planning,
17877 the next step was adding @emph{TODO entries}, basic @emph{timestamps}, and
17878 @emph{table support}. These areas highlighted the two main goals that Org
17879 still has today: to be a new, outline-based, plain text mode with innovative
17880 and intuitive editing features, and to incorporate project planning
17881 functionality directly into a notes file.
17883 Since the first release, literally thousands of emails to me or to
17884 @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug
17885 reports, feedback, new ideas, and sometimes patches and add-on code.
17886 Many thanks to everyone who has helped to improve this package. I am
17887 trying to keep here a list of the people who had significant influence
17888 in shaping one or more aspects of Org. The list may not be
17889 complete, if I have forgotten someone, please accept my apologies and
17892 Before I get to this list, a few special mentions are in order:
17895 @item Bastien Guerry
17896 Bastien has written a large number of extensions to Org (most of them
17897 integrated into the core by now), including the @LaTeX{} exporter and the
17898 plain list parser. His support during the early days was central to the
17899 success of this project. Bastien also invented Worg, helped establishing the
17900 Web presence of Org, and sponsored hosting costs for the orgmode.org website.
17901 Bastien stepped in as maintainer of Org between 2011 and 2013, at a time when
17902 I desparately needed a break.
17903 @item Eric Schulte and Dan Davison
17904 Eric and Dan are jointly responsible for the Org-babel system, which turns
17905 Org into a multi-language environment for evaluating code and doing literate
17906 programming and reproducible research. This has become one of Org's killer
17907 features that define what Org is today.
17909 John has contributed a number of great ideas and patches directly to Org,
17910 including the attachment system (@file{org-attach.el}), integration with
17911 Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO
17912 items, habit tracking (@file{org-habits.el}), and encryption
17913 (@file{org-crypt.el}). Also, the capture system is really an extended copy
17914 of his great @file{remember.el}.
17915 @item Sebastian Rose
17916 Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
17917 of an ignorant amateur. Sebastian has pushed this part of Org onto a much
17918 higher level. He also wrote @file{org-info.js}, a Java script for displaying
17919 web pages derived from Org using an Info-like or a folding interface with
17920 single-key navigation.
17923 @noindent See below for the full list of contributions! Again, please
17924 let me know what I am missing here!
17926 @section From Bastien
17928 I (Bastien) have been maintaining Org between 2011 and 2013. This appendix
17929 would not be complete without adding a few more acknowledgements and thanks.
17931 I am first grateful to Carsten for his trust while handing me over the
17932 maintainership of Org. His unremitting support is what really helped me
17933 getting more confident over time, with both the community and the code.
17935 When I took over maintainership, I knew I would have to make Org more
17936 collaborative than ever, as I would have to rely on people that are more
17937 knowledgeable than I am on many parts of the code. Here is a list of the
17938 persons I could rely on, they should really be considered co-maintainers,
17939 either of the code or the community:
17943 Eric is maintaining the Babel parts of Org. His reactivity here kept me away
17944 from worrying about possible bugs here and let me focus on other parts.
17946 @item Nicolas Goaziou
17947 Nicolas is maintaining the consistency of the deepest parts of Org. His work
17948 on @file{org-element.el} and @file{ox.el} has been outstanding, and it opened
17949 the doors for many new ideas and features. He rewrote many of the old
17950 exporters to use the new export engine, and helped with documenting this
17951 major change. More importantly (if that's possible), he has been more than
17952 reliable during all the work done for Org 8.0, and always very reactive on
17956 Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
17957 into a flexible and conceptually clean process. He patiently coped with the
17958 many hiccups that such a change can create for users.
17961 The Org mode mailing list would not be such a nice place without Nick, who
17962 patiently helped users so many times. It is impossible to overestimate such
17963 a great help, and the list would not be so active without him.
17966 I received support from so many users that it is clearly impossible to be
17967 fair when shortlisting a few of them, but Org's history would not be
17968 complete if the ones above were not mentioned in this manual.
17970 @section List of contributions
17975 @i{Russel Adams} came up with the idea for drawers.
17977 @i{Suvayu Ali} has steadily helped on the mailing list, providing useful
17978 feedback on many features and several patches.
17980 @i{Luis Anaya} wrote @file{ox-man.el}.
17982 @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
17984 @i{Michael Brand} helped by reporting many bugs and testing many features.
17985 He also implemented the distinction between empty fields and 0-value fields
17986 in Org's spreadsheets.
17988 @i{Christophe Bataillon} created the great unicorn logo that we use on the
17991 @i{Alex Bochannek} provided a patch for rounding timestamps.
17993 @i{Jan Böcker} wrote @file{org-docview.el}.
17995 @i{Brad Bozarth} showed how to pull RSS feed data into Org mode files.
17997 @i{Tom Breton} wrote @file{org-choose.el}.
17999 @i{Charles Cave}'s suggestion sparked the implementation of templates
18000 for Remember, which are now templates for capture.
18002 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
18005 @i{Gregory Chernov} patched support for Lisp forms into table
18006 calculations and improved XEmacs compatibility, in particular by porting
18007 @file{nouline.el} to XEmacs.
18009 @i{Sacha Chua} suggested copying some linking code from Planner, and helped
18010 make Org pupular through her blog.
18012 @i{Toby S. Cubitt} contributed to the code for clock formats.
18014 @i{Baoqiu Cui} contributed the first DocBook exporter. In Org 8.0, we go a
18015 different route: you can now export to Texinfo and export the @file{.texi}
18016 file to DocBook using @code{makeinfo}.
18018 @i{Eddward DeVilla} proposed and tested checkbox statistics. He also
18019 came up with the idea of properties, and that there should be an API for
18022 @i{Nick Dokos} tracked down several nasty bugs.
18024 @i{Kees Dullemond} used to edit projects lists directly in HTML and so
18025 inspired some of the early development, including HTML export. He also
18026 asked for a way to narrow wide table columns.
18028 @i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for
18029 several years now. He also sponsored the hosting costs until Rackspace
18030 started to host us for free.
18032 @i{Thomas S. Dye} contributed documentation on Worg and helped integrating
18033 the Org-Babel documentation into the manual.
18035 @i{Christian Egli} converted the documentation into Texinfo format, inspired
18036 the agenda, patched CSS formatting into the HTML exporter, and wrote
18037 @file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as
18038 @file{ox-taskjuggler.el} for Org 8.0.
18040 @i{David Emery} provided a patch for custom CSS support in exported
18043 @i{Sean Escriva} took over MobileOrg development on the iPhone platform.
18045 @i{Nic Ferrier} contributed mailcap and XOXO support.
18047 @i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
18049 @i{John Foerch} figured out how to make incremental search show context
18050 around a match in a hidden outline tree.
18052 @i{Raimar Finken} wrote @file{org-git-line.el}.
18054 @i{Mikael Fornius} works as a mailing list moderator.
18056 @i{Austin Frank} works as a mailing list moderator.
18058 @i{Eric Fraga} drove the development of BEAMER export with ideas and
18061 @i{Barry Gidden} did proofreading the manual in preparation for the book
18062 publication through Network Theory Ltd.
18064 @i{Niels Giesen} had the idea to automatically archive DONE trees.
18066 @i{Nicolas Goaziou} rewrote much of the plain list code. He also wrote
18067 @file{org-element.el} and @file{org-export.el}, which was a huge step forward
18068 in implementing a clean framework for Org exporters.
18070 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
18072 @i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a
18075 @i{Bernt Hansen} has driven much of the support for auto-repeating tasks,
18076 task state change logging, and the clocktable. His clear explanations have
18077 been critical when we started to adopt the Git version control system.
18079 @i{Manuel Hermenegildo} has contributed various ideas, small fixes and
18082 @i{Phil Jackson} wrote @file{org-irc.el}.
18084 @i{Scott Jaderholm} proposed footnotes, control over whitespace between
18085 folded entries, and column view for properties.
18087 @i{Matt Jones} wrote @i{MobileOrg Android}.
18089 @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
18091 @i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}.
18093 @i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also
18094 provided frequent feedback and some patches.
18096 @i{Matt Lundin} has proposed last-row references for table formulas and named
18097 invisible anchors. He has also worked a lot on the FAQ.
18099 @i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,
18100 and is a prolific contributor on the mailing list with competent replies,
18101 small fixes and patches.
18103 @i{Jason F. McBrayer} suggested agenda export to CSV format.
18105 @i{Max Mikhanosha} came up with the idea of refiling and sticky agendas.
18107 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file
18110 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
18113 @i{Richard Moreland} wrote @i{MobileOrg} for the iPhone.
18115 @i{Rick Moynihan} proposed allowing multiple TODO sequences in a file
18116 and being able to quickly restrict the agenda to a subtree.
18118 @i{Todd Neal} provided patches for links to Info files and Elisp forms.
18120 @i{Greg Newman} refreshed the unicorn logo into its current form.
18122 @i{Tim O'Callaghan} suggested in-file links, search options for general
18123 file links, and TAGS.
18125 @i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text
18126 version of the reference card.
18128 @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
18131 @i{Oliver Oppitz} suggested multi-state TODO items.
18133 @i{Scott Otterson} sparked the introduction of descriptive text for
18134 links, among other things.
18136 @i{Pete Phillips} helped during the development of the TAGS feature, and
18137 provided frequent feedback.
18139 @i{Francesco Pizzolante} provided patches that helped speeding up the agenda
18142 @i{Martin Pohlack} provided the code snippet to bundle character insertion
18143 into bundles of 20 for undo.
18145 @i{Rackspace.com} is hosting our website for free. Thank you Rackspace!
18147 @i{T.V. Raman} reported bugs and suggested improvements.
18149 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
18152 @i{Paul Rivier} provided the basic implementation of named footnotes. He
18153 also acted as mailing list moderator for some time.
18155 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
18157 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
18158 conflict with @file{allout.el}.
18160 @i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with
18163 @i{Philip Rooke} created the Org reference card, provided lots
18164 of feedback, developed and applied standards to the Org documentation.
18166 @i{Christian Schlauer} proposed angular brackets around links, among
18169 @i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can
18170 enjoy folding in non-org buffers by using Org headlines in comments.
18172 @i{Paul Sexton} wrote @file{org-ctags.el}.
18174 Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
18175 @file{organizer-mode.el}.
18177 @i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal
18178 examples, and remote highlighting for referenced code lines.
18180 @i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is
18181 now packaged into Org's @file{contrib} directory.
18183 @i{Daniel Sinder} came up with the idea of internal archiving by locking
18186 @i{Dale Smith} proposed link abbreviations.
18188 @i{James TD Smith} has contributed a large number of patches for useful
18189 tweaks and features.
18191 @i{Adam Spiers} asked for global linking commands, inspired the link
18192 extension system, added support for mairix, and proposed the mapping API.
18194 @i{Ulf Stegemann} created the table to translate special symbols to HTML,
18195 @LaTeX{}, UTF-8, Latin-1 and ASCII.
18197 @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
18198 with links transformation to Org syntax.
18200 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
18201 chapter about publishing.
18203 @i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter.
18205 @i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
18206 enabled source code highlighting in Gnus.
18208 @i{Stefan Vollmar} organized a video-recorded talk at the
18209 Max-Planck-Institute for Neurology. He also inspired the creation of a
18210 concept index for HTML export.
18212 @i{J@"urgen Vollmer} contributed code generating the table of contents
18215 @i{Samuel Wales} has provided important feedback and bug reports.
18217 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
18220 @i{David Wainberg} suggested archiving, and improvements to the linking
18223 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
18226 @i{Roland Winkler} requested additional key bindings to make Org
18229 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
18230 and contributed various ideas and code snippets.
18234 @node GNU Free Documentation License
18235 @appendix GNU Free Documentation License
18236 @include doclicense.texi
18240 @unnumbered Concept index
18245 @unnumbered Key index
18249 @node Command and Function Index
18250 @unnumbered Command and function index
18254 @node Variable Index
18255 @unnumbered Variable index
18257 This is not a complete index of variables and faces, only the ones that are
18258 mentioned in the manual. For a more complete list, use @kbd{M-x
18259 org-customize @key{RET}} and then click yourself through the tree.
18265 @c Local variables:
18267 @c indent-tabs-mode: nil
18268 @c paragraph-start: "
\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$"
18269 @c paragraph-separate: "
\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$"
18273 @c LocalWords: webdavhost pre