1 \input texinfo @c -*- coding: utf-8 -*-
3 @setfilename ../../info/org.info
4 @settitle The Org Manual
7 @include org-version.inc
9 @c Version and Contact Info
10 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page}
11 @set AUTHOR Carsten Dominik
12 @set MAINTAINER Carsten Dominik
13 @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
14 @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
19 @c -----------------------------------------------------------------------------
21 @c Macro definitions for commands and keys
22 @c =======================================
24 @c The behavior of the key/command macros will depend on the flag cmdnames
25 @c When set, commands names are shown. When clear, they are not shown.
29 @c Below we define the following macros for Org key tables:
31 @c orgkey{key} A key item
32 @c orgcmd{key,cmd} Key with command name
33 @c xorgcmd{key,cmd} Key with command name as @itemx
34 @c orgcmdnki{key,cmd} Like orgcmd, but do not index the key
35 @c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key
36 @c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or"
37 @c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but
38 @c different functions, so format as @itemx
39 @c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short"
40 @c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx
41 @c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands
43 @c a key but no command
55 @c one key with a command
56 @c Inserts: @item KEY COMMAND
57 @macro orgcmd{key,command}
62 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
65 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
74 @c One key with one command, formatted using @itemx
75 @c Inserts: @itemx KEY COMMAND
76 @macro xorgcmd{key,command}
81 @itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
84 @itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
93 @c one key with a command, bit do not index the key
94 @c Inserts: @item KEY COMMAND
95 @macro orgcmdnki{key,command}
99 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
102 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
110 @c one key with a command, and special text to replace key in item
111 @c Inserts: @item TEXT COMMAND
112 @macro orgcmdtkc{text,key,command}
117 @item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
120 @item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
129 @c two keys with one command
130 @c Inserts: @item KEY1 or KEY2 COMMAND
131 @macro orgcmdkkc{key1,key2,command}
137 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
140 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
146 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
150 @c Two keys with one command name, but different functions, so format as
152 @c Inserts: @item KEY1
153 @c @itemx KEY2 COMMAND
154 @macro orgcmdkxkc{key1,key2,command}
161 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
165 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
176 @c Same as previous, but use "or short"
177 @c Inserts: @item KEY1 or short KEY2 COMMAND
178 @macro orgcmdkskc{key1,key2,command}
184 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
187 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
193 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
197 @c Same as previous, but use @itemx
198 @c Inserts: @itemx KEY1 or short KEY2 COMMAND
199 @macro xorgcmdkskc{key1,key2,command}
205 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
208 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
214 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
218 @c two keys with two commands
219 @c Inserts: @item KEY1 COMMAND1
220 @c @itemx KEY2 COMMAND2
221 @macro orgcmdkkcc{key1,key2,command1,command2}
228 @item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
229 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
232 @item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
233 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
243 @c -----------------------------------------------------------------------------
246 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
249 @c Subheadings inside a table.
250 @macro tsubheading{text}
252 @subsubheading \text\
260 This manual is for Org version @value{VERSION}.
262 Copyright @copyright{} 2004--2017 Free Software Foundation, Inc.
265 Permission is granted to copy, distribute and/or modify this document
266 under the terms of the GNU Free Documentation License, Version 1.3 or
267 any later version published by the Free Software Foundation; with no
268 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
269 and with the Back-Cover Texts as in (a) below. A copy of the license
270 is included in the section entitled ``GNU Free Documentation License.''
272 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
273 modify this GNU manual.''
277 @dircategory Emacs editing modes
279 * Org Mode: (org). Outline-based notes management and organizer
283 @title The Org Manual
285 @subtitle Release @value{VERSION}
286 @author by Carsten Dominik
287 with contributions by Bastien Guerry, Nicolas Goaziou, Eric Schulte,
288 Jambunathan K, Dan Davison, Thomas Dye, David O'Toole, and Philip Rooke.
290 @c The following two commands start the copyright page.
292 @vskip 0pt plus 1filll
296 @c Output the short table of contents at the beginning.
299 @c Output the table of contents at the beginning.
304 @node Top, Introduction, (dir), (dir)
311 * Introduction:: Getting started
312 * Document structure:: A tree works like your brain
313 * Tables:: Pure magic for quick formatting
314 * Hyperlinks:: Notes in context
315 * TODO items:: Every tree branch can be a TODO item
316 * Tags:: Tagging headlines and matching sets of tags
317 * Properties and columns:: Storing information about an entry
318 * Dates and times:: Making items useful for planning
319 * Capture - Refile - Archive:: The ins and outs for projects
320 * Agenda views:: Collecting information into views
321 * Markup:: Prepare text for rich export
322 * Exporting:: Sharing and publishing notes
323 * Publishing:: Create a web site of linked Org files
324 * Working with source code:: Export, evaluate, and tangle code blocks
325 * Miscellaneous:: All the rest which did not fit elsewhere
326 * Hacking:: How to hack your way around
327 * MobileOrg:: Viewing and capture on a mobile device
328 * History and acknowledgments:: How Org came into being
329 * GNU Free Documentation License:: The license for this documentation.
330 * Main Index:: An index of Org's concepts and features
331 * Key Index:: Key bindings and where they are described
332 * Command and Function Index:: Command names and some internal functions
333 * Variable Index:: Variables mentioned in the manual
336 --- The Detailed Node Listing ---
340 * Summary:: Brief summary of what Org does
341 * Installation:: Installing Org
342 * Activation:: How to activate Org for certain buffers
343 * Feedback:: Bug reports, ideas, patches etc.
344 * Conventions:: Typesetting conventions in the manual
348 * Outlines:: Org is based on Outline mode
349 * Headlines:: How to typeset Org tree headlines
350 * Visibility cycling:: Show and hide, much simplified
351 * Motion:: Jumping to other headlines
352 * Structure editing:: Changing sequence and level of headlines
353 * Sparse trees:: Matches embedded in context
354 * Plain lists:: Additional structure within an entry
355 * Drawers:: Tucking stuff away
356 * Blocks:: Folding blocks
357 * Footnotes:: How footnotes are defined in Org's syntax
358 * Orgstruct mode:: Structure editing outside Org
359 * Org syntax:: Formal description of Org's syntax
363 * Global and local cycling:: Cycling through various visibility states
364 * Initial visibility:: Setting the initial visibility state
365 * Catching invisible edits:: Preventing mistakes when editing invisible parts
369 * Built-in table editor:: Simple tables
370 * Column width and alignment:: Overrule the automatic settings
371 * Column groups:: Grouping to trigger vertical lines
372 * Orgtbl mode:: The table editor as minor mode
373 * The spreadsheet:: The table editor has spreadsheet capabilities
374 * Org-Plot:: Plotting from org tables
378 * References:: How to refer to another field or range
379 * Formula syntax for Calc:: Using Calc to compute stuff
380 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
381 * Durations and time values:: How to compute durations and time values
382 * Field and range formulas:: Formula for specific (ranges of) fields
383 * Column formulas:: Formulas valid for an entire column
384 * Lookup functions:: Lookup functions for searching tables
385 * Editing and debugging formulas:: Fixing formulas
386 * Updating the table:: Recomputing all dependent fields
387 * Advanced features:: Field and column names, parameters and automatic recalc
391 * Link format:: How links in Org are formatted
392 * Internal links:: Links to other places in the current file
393 * External links:: URL-like links to the world
394 * Handling links:: Creating, inserting and following
395 * Using links outside Org:: Linking from my C source code?
396 * Link abbreviations:: Shortcuts for writing complex links
397 * Search options:: Linking to a specific location
398 * Custom searches:: When the default search is not enough
402 * Radio targets:: Make targets trigger links in plain text
406 * TODO basics:: Marking and displaying TODO entries
407 * TODO extensions:: Workflow and assignments
408 * Progress logging:: Dates and notes for progress
409 * Priorities:: Some things are more important than others
410 * Breaking down tasks:: Splitting a task into manageable pieces
411 * Checkboxes:: Tick-off lists
413 Extended use of TODO keywords
415 * Workflow states:: From TODO to DONE in steps
416 * TODO types:: I do this, Fred does the rest
417 * Multiple sets in one file:: Mixing it all, and still finding your way
418 * Fast access to TODO states:: Single letter selection of a state
419 * Per-file keywords:: Different files, different requirements
420 * Faces for TODO keywords:: Highlighting states
421 * TODO dependencies:: When one task needs to wait for others
425 * Closing items:: When was this entry marked DONE?
426 * Tracking TODO state changes:: When did the status change?
427 * Tracking your habits:: How consistent have you been?
431 * Tag inheritance:: Tags use the tree structure of the outline
432 * Setting tags:: How to assign tags to a headline
433 * Tag hierarchy:: Create a hierarchy of tags
434 * Tag searches:: Searching for combinations of tags
436 Properties and columns
438 * Property syntax:: How properties are spelled out
439 * Special properties:: Access to other Org mode features
440 * Property searches:: Matching property values
441 * Property inheritance:: Passing values down the tree
442 * Column view:: Tabular viewing and editing
443 * Property API:: Properties for Lisp programmers
447 * Defining columns:: The COLUMNS format property
448 * Using column view:: How to create and use column view
449 * Capturing column view:: A dynamic block for column view
453 * Scope of column definitions:: Where defined, where valid?
454 * Column attributes:: Appearance and content of a column
458 * Timestamps:: Assigning a time to a tree entry
459 * Creating timestamps:: Commands which insert timestamps
460 * Deadlines and scheduling:: Planning your work
461 * Clocking work time:: Tracking how long you spend on a task
462 * Effort estimates:: Planning work effort in advance
463 * Timers:: Notes with a running timer
467 * The date/time prompt:: How Org mode helps you entering date and time
468 * Custom time format:: Making dates look different
470 Deadlines and scheduling
472 * Inserting deadline/schedule:: Planning items
473 * Repeated tasks:: Items that show up again and again
477 * Clocking commands:: Starting and stopping a clock
478 * The clock table:: Detailed reports
479 * Resolving idle time:: Resolving time when you've been idle
481 Capture - Refile - Archive
483 * Capture:: Capturing new stuff
484 * Attachments:: Add files to tasks
485 * RSS feeds:: Getting input from RSS feeds
486 * Protocols:: External (e.g., Browser) access to Emacs and Org
487 * Refile and copy:: Moving/copying a tree from one place to another
488 * Archiving:: What to do with finished projects
492 * Setting up capture:: Where notes will be stored
493 * Using capture:: Commands to invoke and terminate capture
494 * Capture templates:: Define the outline of different note types
498 * Template elements:: What is needed for a complete template entry
499 * Template expansion:: Filling in information about time and context
500 * Templates in contexts:: Only show a template in a specific context
504 * Moving subtrees:: Moving a tree to an archive file
505 * Internal archiving:: Switch off a tree but keep it in the file
509 * Agenda files:: Files being searched for agenda information
510 * Agenda dispatcher:: Keyboard access to agenda views
511 * Built-in agenda views:: What is available out of the box?
512 * Presentation and sorting:: How agenda items are prepared for display
513 * Agenda commands:: Remote editing of Org trees
514 * Custom agenda views:: Defining special searches and views
515 * Exporting agenda views:: Writing a view to a file
516 * Agenda column view:: Using column view for collected entries
518 The built-in agenda views
520 * Weekly/daily agenda:: The calendar page with current tasks
521 * Global TODO list:: All unfinished action items
522 * Matching tags and properties:: Structured information with fine-tuned search
523 * Timeline:: Time-sorted view for single file
524 * Search view:: Find entries by searching for text
525 * Stuck projects:: Find projects you need to review
527 Presentation and sorting
529 * Categories:: Not all tasks are equal
530 * Time-of-day specifications:: How the agenda knows the time
531 * Sorting agenda items:: The order of things
532 * Filtering/limiting agenda items:: Dynamically narrow the agenda
536 * Storing searches:: Type once, use often
537 * Block agenda:: All the stuff you need in a single buffer
538 * Setting options:: Changing the rules
540 Markup for rich export
542 * Paragraphs:: The basic unit of text
543 * Emphasis and monospace:: Bold, italic, etc.
544 * Horizontal rules:: Make a line
545 * Images and tables:: Images, tables and caption mechanism
546 * Literal examples:: Source code examples with special formatting
547 * Special symbols:: Greek letters and other symbols
548 * Subscripts and superscripts:: Simple syntax for raising/lowering text
549 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
553 * @LaTeX{} fragments:: Complex formulas made easy
554 * Previewing @LaTeX{} fragments:: What will this snippet look like?
555 * CDLaTeX mode:: Speed up entering of formulas
559 * The export dispatcher:: The main interface
560 * Export settings:: Common export settings
561 * Table of contents:: The if and where of the table of contents
562 * Include files:: Include additional files into a document
563 * Macro replacement:: Use macros to create templates
564 * Comment lines:: What will not be exported
565 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
566 * Beamer export:: Exporting as a Beamer presentation
567 * HTML export:: Exporting to HTML
568 * @LaTeX{} export:: Exporting to @LaTeX{}, and processing to PDF
569 * Markdown export:: Exporting to Markdown
570 * OpenDocument Text export:: Exporting to OpenDocument Text
571 * Org export:: Exporting to Org
572 * Texinfo export:: Exporting to Texinfo
573 * iCalendar export:: Exporting to iCalendar
574 * Other built-in back-ends:: Exporting to a man page
575 * Advanced configuration:: Fine-tuning the export output
576 * Export in foreign buffers:: Author tables and lists in Org syntax
580 * Beamer export commands:: For creating Beamer documents.
581 * Beamer specific export settings:: For customizing Beamer export.
582 * Sectioning Frames and Blocks in Beamer:: For composing Beamer slides.
583 * Beamer specific syntax:: For using in Org documents.
584 * Editing support:: For using helper functions.
585 * A Beamer example:: A complete presentation.
589 * HTML Export commands:: Invoking HTML export
590 * HTML Specific export settings:: Settings for HTML export
591 * HTML doctypes:: Exporting various (X)HTML flavors
592 * HTML preamble and postamble:: Inserting preamble and postamble
593 * Quoting HTML tags:: Using direct HTML in Org files
594 * Links in HTML export:: Interpreting and formatting links
595 * Tables in HTML export:: Formatting and modifying tables
596 * Images in HTML export:: Inserting figures with HTML output
597 * Math formatting in HTML export:: Handling math equations
598 * Text areas in HTML export:: Showing an alternate approach, an example
599 * CSS support:: Styling HTML output
600 * JavaScript support:: Folding scripting in the web browser
604 * @LaTeX{} export commands:: For producing @LaTeX{} and PDF documents.
605 * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end.
606 * @LaTeX{} header and sectioning:: For file structure.
607 * Quoting @LaTeX{} code:: Directly in the Org document.
608 * Tables in @LaTeX{} export:: Attributes specific to tables.
609 * Images in @LaTeX{} export:: Attributes specific to images.
610 * Plain lists in @LaTeX{} export:: Attributes specific to lists.
611 * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks.
612 * Example blocks in @LaTeX{} export:: Attributes specific to example blocks.
613 * Special blocks in @LaTeX{} export:: Attributes specific to special blocks.
614 * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules.
616 OpenDocument Text export
618 * Pre-requisites for ODT export:: Required packages.
619 * ODT export commands:: Invoking export.
620 * ODT specific export settings:: Configuration options.
621 * Extending ODT export:: Producing @file{.doc}, @file{.pdf} files.
622 * Applying custom styles:: Styling the output.
623 * Links in ODT export:: Handling and formatting links.
624 * Tables in ODT export:: Org table conversions.
625 * Images in ODT export:: Inserting images.
626 * Math formatting in ODT export:: Formatting @LaTeX{} fragments.
627 * Labels and captions in ODT export:: Rendering objects.
628 * Literal examples in ODT export:: For source code and example blocks.
629 * Advanced topics in ODT export:: For power users.
631 Math formatting in ODT export
633 * Working with @LaTeX{} math snippets:: Embedding in @LaTeX{} format.
634 * Working with MathML or OpenDocument formula files:: Embedding in native format.
636 Advanced topics in ODT export
638 * Configuring a document converter:: Registering a document converter.
639 * Working with OpenDocument style files:: Exploring internals.
640 * Creating one-off styles:: Customizing styles, highlighting.
641 * Customizing tables in ODT export:: Defining table templates.
642 * Validating OpenDocument XML:: Debugging corrupted OpenDocument files.
646 * Texinfo export commands:: Invoking commands.
647 * Texinfo specific export settings:: Setting the environment.
648 * Texinfo file header:: Generating the header.
649 * Texinfo title and copyright page:: Creating preamble pages.
650 * Texinfo @samp{Top} node:: Installing a manual in Info Top node.
651 * Headings and sectioning structure:: Building document structure.
652 * Indices:: Creating indices.
653 * Quoting Texinfo code:: Incorporating literal Texinfo code.
654 * Plain lists in Texinfo export:: List attributes.
655 * Tables in Texinfo export:: Table attributes.
656 * Images in Texinfo export:: Image attributes.
657 * Special blocks in Texinfo export:: Special block attributes.
658 * A Texinfo example:: Processing Org to Texinfo.
662 * Configuration:: Defining projects
663 * Uploading files:: How to get files up on the server
664 * Sample configuration:: Example projects
665 * Triggering publication:: Publication commands
669 * Project alist:: The central configuration variable
670 * Sources and destinations:: From here to there
671 * Selecting files:: What files are part of the project?
672 * Publishing action:: Setting the function doing the publishing
673 * Publishing options:: Tweaking HTML/@LaTeX{} export
674 * Publishing links:: Which links keep working after publishing?
675 * Sitemap:: Generating a list of all pages
676 * Generating an index:: An index that reaches across pages
680 * Simple example:: One-component publishing
681 * Complex example:: A multi-component publishing example
683 Working with source code
685 * Structure of code blocks:: Code block syntax described
686 * Editing source code:: Language major-mode editing
687 * Exporting code blocks:: Export contents and/or results
688 * Extracting source code:: Create pure source code files
689 * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
690 * Library of Babel:: Use and contribute to a library of useful code blocks
691 * Languages:: List of supported code block languages
692 * Header arguments:: Configure code block functionality
693 * Results of evaluation:: How evaluation results are handled
694 * Noweb reference syntax:: Literate programming in Org mode
695 * Key bindings and useful functions:: Work quickly with code blocks
696 * Batch execution:: Call functions from the command line
700 * Using header arguments:: Different ways to set header arguments
701 * Specific header arguments:: List of header arguments
703 Using header arguments
705 * System-wide header arguments:: Set globally, language-specific
706 * Language-specific header arguments:: Set in the Org file's headers
707 * Header arguments in Org mode properties:: Set in the Org file
708 * Language-specific mode properties::
709 * Code block specific header arguments:: The most commonly used method
710 * Arguments in function calls:: The most specific level, takes highest priority
712 Specific header arguments
714 * var:: Pass arguments to @samp{src} code blocks
715 * results:: Specify results type; how to collect
716 * file:: Specify a path for output file
717 * file-desc:: Specify a description for file results
718 * file-ext:: Specify an extension for file output
719 * output-dir:: Specify a directory for output file
720 * dir:: Specify the default directory for code block execution
721 * exports:: Specify exporting code, results, both, none
722 * tangle:: Toggle tangling; or specify file name
723 * mkdirp:: Toggle for parent directory creation for target files during tangling
724 * comments:: Toggle insertion of comments in tangled code files
725 * padline:: Control insertion of padding lines in tangled code files
726 * no-expand:: Turn off variable assignment and noweb expansion during tangling
727 * session:: Preserve the state of code evaluation
728 * noweb:: Toggle expansion of noweb references
729 * noweb-ref:: Specify block's noweb reference resolution target
730 * noweb-sep:: String to separate noweb references
731 * cache:: Avoid re-evaluating unchanged code blocks
732 * sep:: Delimiter for writing tabular results outside Org
733 * hlines:: Handle horizontal lines in tables
734 * colnames:: Handle column names in tables
735 * rownames:: Handle row names in tables
736 * shebang:: Make tangled files executable
737 * tangle-mode:: Set permission of tangled files
738 * eval:: Limit evaluation of specific code blocks
739 * wrap:: Mark source block evaluation results
740 * post:: Post processing of results of code block evaluation
741 * prologue:: Text to prepend to body of code block
742 * epilogue:: Text to append to body of code block
746 * Completion:: M-TAB guesses completions
747 * Easy templates:: Quick insertion of structural elements
748 * Speed keys:: Electric commands at the beginning of a headline
749 * Code evaluation security:: Org mode files evaluate inline code
750 * Customization:: Adapting Org to changing tastes
751 * In-buffer settings:: Overview of the #+KEYWORDS
752 * The very busy C-c C-c key:: When in doubt, press C-c C-c
753 * Clean view:: Getting rid of leading stars in the outline
754 * TTY keys:: Using Org on a tty
755 * Interaction:: With other Emacs packages
756 * org-crypt:: Encrypting Org files
758 Interaction with other packages
760 * Cooperation:: Packages Org cooperates with
761 * Conflicts:: Packages that lead to conflicts
765 * Hooks:: How to reach into Org's internals
766 * Add-on packages:: Available extensions
767 * Adding hyperlink types:: New custom link types
768 * Adding export back-ends:: How to write new export back-ends
769 * Context-sensitive commands:: How to add functionality to such commands
770 * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
771 * Dynamic blocks:: Automatically filled blocks
772 * Special agenda views:: Customized views
773 * Speeding up your agendas:: Tips on how to speed up your agendas
774 * Extracting agenda information:: Post-processing of agenda information
775 * Using the property API:: Writing programs that use entry properties
776 * Using the mapping API:: Mapping over all or selected entries
778 Tables and lists in arbitrary syntax
780 * Radio tables:: Sending and receiving radio tables
781 * A @LaTeX{} example:: Step by step, almost a tutorial
782 * Translator functions:: Copy and modify
783 * Radio lists:: Sending and receiving lists
787 * Setting up the staging area:: For the mobile device
788 * Pushing to MobileOrg:: Uploading Org files and agendas
789 * Pulling from MobileOrg:: Integrating captured and flagged items
795 @chapter Introduction
799 * Summary:: Brief summary of what Org does
800 * Installation:: Installing Org
801 * Activation:: How to activate Org for certain buffers
802 * Feedback:: Bug reports, ideas, patches etc.
803 * Conventions:: Typesetting conventions in the manual
810 Org is a mode for keeping notes, maintaining TODO lists, and project planning
811 with a fast and effective plain-text system. It also is an authoring system
812 with unique support for literate programming and reproducible research.
814 Org is implemented on top of Outline mode, which makes it possible to keep
815 the content of large files well structured. Visibility cycling and structure
816 editing help to work with the tree. Tables are easily created with a
817 built-in table editor. Plain text URL-like links connect to websites,
818 emails, Usenet messages, BBDB entries, and any files related to the projects.
820 Org develops organizational tasks around notes files that contain lists or
821 information about projects as plain text. Project planning and task
822 management makes use of metadata which is part of an outline node. Based on
823 this data, specific entries can be extracted in queries and create dynamic
824 @i{agenda views} that also integrate the Emacs calendar and diary. Org can
825 be used to implement many different project planning schemes, such as David
828 Org files can serve as a single source authoring system with export to many
829 different formats such as HTML, @LaTeX{}, Open Document, and Markdown. New
830 export backends can be derived from existing ones, or defined from scratch.
832 Org files can include source code blocks, which makes Org uniquely suited for
833 authoring technical documents with code examples. Org source code blocks are
834 fully functional; they can be evaluated in place and their results can be
835 captured in the file. This makes it possible to create a single file
836 reproducible research compendium.
838 Org keeps simple things simple. When first fired up, it should feel like a
839 straightforward, easy to use outliner. Complexity is not imposed, but a
840 large amount of functionality is available when needed. Org is a toolbox.
841 Many users actually run only a (very personal) fraction of Org's capabilities, and
842 know that there is more whenever they need it.
844 All of this is achieved with strictly plain text files, the most portable and
845 future-proof file format. Org runs in Emacs. Emacs is one of the most
846 widely ported programs, so that Org mode is available on every major
850 There is a website for Org which provides links to the newest
851 version of Org, as well as additional information, frequently asked
852 questions (FAQ), links to tutorials, etc. This page is located at
853 @uref{http://orgmode.org}.
854 @cindex print edition
856 An earlier version (7.3) of this manual is available as a
857 @uref{http://www.network-theory.co.uk/org/manual/, paperback book from
863 @section Installation
866 Org is part of recent distributions of GNU Emacs, so you normally don't need
867 to install it. If, for one reason or another, you want to install Org on top
868 of this pre-packaged version, there are three ways to do it:
871 @item By using Emacs package system.
872 @item By downloading Org as an archive.
873 @item By using Org's git repository.
876 We @b{strongly recommend} to stick to a single installation method.
878 @subsubheading Using Emacs packaging system
880 Recent Emacs distributions include a packaging system which lets you install
881 Elisp libraries. You can install Org with @kbd{M-x package-install RET org}.
883 @noindent @b{Important}: you need to do this in a session where no @code{.org} file has
884 been visited, i.e., where no Org built-in function have been loaded.
885 Otherwise autoload Org functions will mess up the installation.
887 Then, to make sure your Org configuration is taken into account, initialize
888 the package system with @code{(package-initialize)} in your Emacs init file
889 before setting any Org option. If you want to use Org's package repository,
890 check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
892 @subsubheading Downloading Org as an archive
894 You can download Org latest release from @uref{http://orgmode.org/, Org's
895 website}. In this case, make sure you set the load-path correctly in your
899 (add-to-list 'load-path "~/path/to/orgdir/lisp")
902 The downloaded archive contains contributed libraries that are not included
903 in Emacs. If you want to use them, add the @file{contrib} directory to your
907 (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
910 Optionally, you can compile the files and/or install them in your system.
911 Run @code{make help} to list compilation and installation options.
913 @subsubheading Using Org's git repository
915 You can clone Org's repository and install Org like this:
919 $ git clone git://orgmode.org/org-mode.git
923 Note that in this case, @code{make autoloads} is mandatory: it defines Org's
924 version in @file{org-version.el} and Org's autoloads in
925 @file{org-loaddefs.el}.
927 Remember to add the correct load-path as described in the method above.
929 You can also compile with @code{make}, generate the documentation with
930 @code{make doc}, create a local configuration with @code{make config} and
931 install Org with @code{make install}. Please run @code{make help} to get
932 the list of compilation/installation options.
934 For more detailed explanations on Org's build system, please check the Org
935 Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
943 @cindex global key bindings
944 @cindex key bindings, global
947 @findex org-store-link
950 Org mode buffers need font-lock to be turned on: this is the default in
951 Emacs@footnote{If you don't use font-lock globally, turn it on in Org buffer
952 with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
954 There are compatibility issues between Org mode and some other Elisp
955 packages, please take the time to check the list (@pxref{Conflicts}).
957 The four Org commands @command{org-store-link}, @command{org-capture},
958 @command{org-agenda}, and @command{org-iswitchb} should be accessible through
959 global keys (i.e., anywhere in Emacs, not just in Org buffers). Here are
960 suggested bindings for these keys, please modify the keys to your own
963 (global-set-key "\C-cl" 'org-store-link)
964 (global-set-key "\C-ca" 'org-agenda)
965 (global-set-key "\C-cc" 'org-capture)
966 (global-set-key "\C-cb" 'org-iswitchb)
969 @cindex Org mode, turning on
970 Files with the @file{.org} extension use Org mode by default. To turn on Org
971 mode in a file that does not have the extension @file{.org}, make the first
972 line of a file look like this:
975 MY PROJECTS -*- mode: org; -*-
978 @vindex org-insert-mode-line-in-empty-file
979 @noindent which will select Org mode for this buffer no matter what
980 the file's name is. See also the variable
981 @code{org-insert-mode-line-in-empty-file}.
983 Many commands in Org work on the region if the region is @i{active}. To make
984 use of this, you need to have @code{transient-mark-mode} turned on, which is
985 the default. If you do not like @code{transient-mark-mode}, you can create
986 an active region by using the mouse to select a region, or pressing
987 @kbd{C-@key{SPC}} twice before moving the cursor.
996 If you find problems with Org, or if you have questions, remarks, or ideas
997 about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
998 You can subscribe to the list
999 @uref{https://lists.gnu.org/mailman/listinfo/emacs-orgmode, on this web page}.
1000 If you are not a member of the mailing list, your mail will be passed to the
1001 list after a moderator has approved it@footnote{Please consider subscribing
1002 to the mailing list, in order to minimize the work the mailing list
1003 moderators have to do.}.
1005 For bug reports, please first try to reproduce the bug with the latest
1006 version of Org available---if you are running an outdated version, it is
1007 quite possible that the bug has been fixed already. If the bug persists,
1008 prepare a report and provide as much information as possible, including the
1009 version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
1010 (@kbd{M-x org-version RET}), as well as the Org related setup in the Emacs
1011 init file. The easiest way to do this is to use the command
1013 @kbd{M-x org-submit-bug-report RET}
1015 @noindent which will put all this information into an Emacs mail buffer so
1016 that you only need to add your description. If you are not sending the Email
1017 from within Emacs, please copy and paste the content into your Email program.
1019 Sometimes you might face a problem due to an error in your Emacs or Org mode
1020 setup. Before reporting a bug, it is very helpful to start Emacs with minimal
1021 customizations and reproduce the problem. Doing so often helps you determine
1022 if the problem is with your customization or with Org mode itself. You can
1023 start a typical minimal session with a command like the example below.
1026 $ emacs -Q -l /path/to/minimal-org.el
1029 However if you are using Org mode as distributed with Emacs, a minimal setup
1030 is not necessary. In that case it is sufficient to start Emacs as
1031 @code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
1035 ;;; Minimal setup to load latest 'org-mode'
1037 ;; activate debugging
1038 (setq debug-on-error t
1042 ;; add latest org-mode to load path
1043 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
1044 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
1047 If an error occurs, a backtrace can be very useful (see below on how to
1048 create one). Often a small example file helps, along with clear information
1052 @item What exactly did you do?
1053 @item What did you expect to happen?
1054 @item What happened instead?
1056 @noindent Thank you for helping to improve this program.
1058 @subsubheading How to create a useful backtrace
1060 @cindex backtrace of an error
1061 If working with Org produces an error with a message you don't
1062 understand, you may have hit a bug. The best way to report this is by
1063 providing, in addition to what was mentioned above, a @emph{backtrace}.
1064 This is information from the built-in debugger about where and how the
1065 error occurred. Here is how to produce a useful backtrace:
1069 Reload uncompiled versions of all Org mode Lisp files. The backtrace
1070 contains much more information if it is produced with uncompiled code.
1073 @kbd{C-u M-x org-reload RET}
1076 or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
1079 Go to the @code{Options} menu and select @code{Enter Debugger on Error}.
1081 Do whatever you have to do to hit the error. Don't forget to
1082 document the steps you take.
1084 When you hit the error, a @file{*Backtrace*} buffer will appear on the
1085 screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
1086 attach it to your bug report.
1090 @section Typesetting conventions used in this manual
1092 @subsubheading TODO keywords, tags, properties, etc.
1094 Org mainly uses three types of keywords: TODO keywords, tags and property
1095 names. In this manual we use the following conventions:
1100 TODO keywords are written with all capitals, even if they are
1104 User-defined tags are written in lowercase; built-in tags with special
1105 meaning are written with all capitals.
1108 User-defined properties are capitalized; built-in properties with
1109 special meaning are written with all capitals.
1112 Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
1113 and @i{environment keywords} (like @code{#+BEGIN_EXPORT html} to start
1114 a @code{HTML} environment). They are written in uppercase in the manual to
1115 enhance its readability, but you can use lowercase in your Org file.
1117 @subsubheading Key bindings and commands
1123 The manual suggests a few global key bindings, in particular @kbd{C-c a} for
1124 @code{org-agenda} and @kbd{C-c c} for @code{org-capture}. These are only
1125 suggestions, but the rest of the manual assumes that these key bindings are in
1126 place in order to list commands by key access.
1128 Also, the manual lists both the keys and the corresponding commands for
1129 accessing a functionality. Org mode often uses the same key for different
1130 functions, depending on context. The command that is bound to such keys has
1131 a generic name, like @code{org-metaright}. In the manual we will, wherever
1132 possible, give the function that is internally called by the generic command.
1133 For example, in the chapter on document structure, @kbd{M-@key{right}} will
1134 be listed to call @code{org-do-demote}, while in the chapter on tables, it
1135 will be listed to call @code{org-table-move-column-right}. If you prefer,
1136 you can compile the manual without the command names by unsetting the flag
1137 @code{cmdnames} in @file{org.texi}.
1139 @node Document structure
1140 @chapter Document structure
1141 @cindex document structure
1142 @cindex structure of document
1144 Org is based on Outline mode and provides flexible commands to
1145 edit the structure of the document.
1148 * Outlines:: Org is based on Outline mode
1149 * Headlines:: How to typeset Org tree headlines
1150 * Visibility cycling:: Show and hide, much simplified
1151 * Motion:: Jumping to other headlines
1152 * Structure editing:: Changing sequence and level of headlines
1153 * Sparse trees:: Matches embedded in context
1154 * Plain lists:: Additional structure within an entry
1155 * Drawers:: Tucking stuff away
1156 * Blocks:: Folding blocks
1157 * Footnotes:: How footnotes are defined in Org's syntax
1158 * Orgstruct mode:: Structure editing outside Org
1159 * Org syntax:: Formal description of Org's syntax
1165 @cindex Outline mode
1167 Org is implemented on top of Outline mode. Outlines allow a
1168 document to be organized in a hierarchical structure, which (at least
1169 for me) is the best representation of notes and thoughts. An overview
1170 of this structure is achieved by folding (hiding) large parts of the
1171 document to show only the general document structure and the parts
1172 currently being worked on. Org greatly simplifies the use of
1173 outlines by compressing the entire show/hide functionality into a single
1174 command, @command{org-cycle}, which is bound to the @key{TAB} key.
1179 @cindex outline tree
1180 @vindex org-special-ctrl-a/e
1181 @vindex org-special-ctrl-k
1182 @vindex org-ctrl-k-protect-subtree
1184 Headlines define the structure of an outline tree. The headlines in Org
1185 start with one or more stars, on the left margin@footnote{See the variables
1186 @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
1187 @code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
1188 @kbd{C-e}, and @kbd{C-k} in headlines.} @footnote{Clocking only works with
1189 headings indented less than 30 stars.}. For example:
1192 * Top level headline
1199 * Another top level headline
1202 @vindex org-footnote-section
1203 @noindent Note that a headline named after @code{org-footnote-section},
1204 which defaults to @samp{Footnotes}, is considered as special. A subtree with
1205 this headline will be silently ignored by exporting functions.
1207 Some people find the many stars too noisy and would prefer an
1208 outline that has whitespace followed by a single star as headline
1209 starters. @ref{Clean view}, describes a setup to realize this.
1211 @vindex org-cycle-separator-lines
1212 An empty line after the end of a subtree is considered part of it and
1213 will be hidden when the subtree is folded. However, if you leave at
1214 least two empty lines, one empty line will remain visible after folding
1215 the subtree, in order to structure the collapsed view. See the
1216 variable @code{org-cycle-separator-lines} to modify this behavior.
1218 @node Visibility cycling
1219 @section Visibility cycling
1220 @cindex cycling, visibility
1221 @cindex visibility cycling
1222 @cindex trees, visibility
1223 @cindex show hidden text
1227 * Global and local cycling:: Cycling through various visibility states
1228 * Initial visibility:: Setting the initial visibility state
1229 * Catching invisible edits:: Preventing mistakes when editing invisible parts
1232 @node Global and local cycling
1233 @subsection Global and local cycling
1235 Outlines make it possible to hide parts of the text in the buffer.
1236 Org uses just two commands, bound to @key{TAB} and
1237 @kbd{S-@key{TAB}} to change the visibility in the buffer.
1239 @cindex subtree visibility states
1240 @cindex subtree cycling
1241 @cindex folded, subtree visibility state
1242 @cindex children, subtree visibility state
1243 @cindex subtree, subtree visibility state
1245 @orgcmd{@key{TAB},org-cycle}
1246 @emph{Subtree cycling}: Rotate current subtree among the states
1249 ,-> FOLDED -> CHILDREN -> SUBTREE --.
1250 '-----------------------------------'
1253 @vindex org-cycle-emulate-tab
1254 @vindex org-cycle-global-at-bob
1255 The cursor must be on a headline for this to work@footnote{see, however,
1256 the option @code{org-cycle-emulate-tab}.}. When the cursor is at the
1257 beginning of the buffer and the first line is not a headline, then
1258 @key{TAB} actually runs global cycling (see below)@footnote{see the
1259 option @code{org-cycle-global-at-bob}.}. Also when called with a prefix
1260 argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
1262 @cindex global visibility states
1263 @cindex global cycling
1264 @cindex overview, global visibility state
1265 @cindex contents, global visibility state
1266 @cindex show all, global visibility state
1267 @orgcmd{S-@key{TAB},org-global-cycle}
1268 @itemx C-u @key{TAB}
1269 @emph{Global cycling}: Rotate the entire buffer among the states
1272 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
1273 '--------------------------------------'
1276 When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the
1277 CONTENTS view up to headlines of level N will be shown. Note that inside
1278 tables, @kbd{S-@key{TAB}} jumps to the previous field.
1280 @cindex set startup visibility, command
1281 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1282 Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
1283 @cindex show all, command
1284 @orgcmd{C-u C-u C-u @key{TAB},outline-show-all}
1285 Show all, including drawers.
1286 @cindex revealing context
1287 @orgcmd{C-c C-r,org-reveal}
1288 Reveal context around point, showing the current entry, the following heading
1289 and the hierarchy above. Useful for working near a location that has been
1290 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
1291 (@pxref{Agenda commands}). With a prefix argument show, on each
1292 level, all sibling headings. With a double prefix argument, also show the
1293 entire subtree of the parent.
1294 @cindex show branches, command
1295 @orgcmd{C-c C-k,outline-show-branches}
1296 Expose all the headings of the subtree, CONTENT view for just one subtree.
1297 @cindex show children, command
1298 @orgcmd{C-c @key{TAB},outline-show-children}
1299 Expose all direct children of the subtree. With a numeric prefix argument N,
1300 expose all children down to level N@.
1301 @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
1302 Show the current subtree in an indirect buffer@footnote{The indirect buffer
1303 (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) will contain the entire
1304 buffer, but will be narrowed to the current tree. Editing the indirect
1305 buffer will also change the original buffer, but without affecting visibility
1306 in that buffer.}. With a numeric prefix argument N, go up to level N and
1307 then take that tree. If N is negative then go up that many levels. With a
1308 @kbd{C-u} prefix, do not remove 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 @cindex property, VISIBILITY
1341 Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
1342 and columns}) will get their visibility adapted accordingly. Allowed values
1343 for this property are @code{folded}, @code{children}, @code{content}, and
1347 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1348 Switch back to the startup visibility of the buffer, i.e., whatever is
1349 requested by startup options and @samp{VISIBILITY} properties in individual
1353 @node Catching invisible edits
1354 @subsection Catching invisible edits
1356 @vindex org-catch-invisible-edits
1357 @cindex edits, catching invisible
1358 Sometimes you may inadvertently edit an invisible part of the buffer and be
1359 confused on what has been edited and how to undo the mistake. Setting
1360 @code{org-catch-invisible-edits} to non-@code{nil} will help prevent this. See the
1361 docstring of this option on how Org should catch invisible edits and process
1366 @cindex motion, between headlines
1367 @cindex jumping, to headlines
1368 @cindex headline navigation
1369 The following commands jump to other headlines in the buffer.
1372 @orgcmd{C-c C-n,org-next-visible-heading}
1374 @orgcmd{C-c C-p,org-previous-visible-heading}
1376 @orgcmd{C-c C-f,org-forward-same-level}
1377 Next heading same level.
1378 @orgcmd{C-c C-b,org-backward-same-level}
1379 Previous heading same level.
1380 @orgcmd{C-c C-u,outline-up-heading}
1381 Backward to higher level heading.
1382 @orgcmd{C-c C-j,org-goto}
1383 Jump to a different place without changing the current outline
1384 visibility. Shows the document structure in a temporary buffer, where
1385 you can use the following keys to find your destination:
1386 @vindex org-goto-auto-isearch
1388 @key{TAB} @r{Cycle visibility.}
1389 @key{down} / @key{up} @r{Next/previous visible headline.}
1390 @key{RET} @r{Select this location.}
1391 @kbd{/} @r{Do a Sparse-tree search}
1392 @r{The following keys work if you turn off @code{org-goto-auto-isearch}}
1393 n / p @r{Next/previous visible headline.}
1394 f / b @r{Next/previous headline same level.}
1396 0-9 @r{Digit argument.}
1399 @vindex org-goto-interface
1401 See also the option @code{org-goto-interface}.
1404 @node Structure editing
1405 @section Structure editing
1406 @cindex structure editing
1407 @cindex headline, promotion and demotion
1408 @cindex promotion, of subtrees
1409 @cindex demotion, of subtrees
1410 @cindex subtree, cut and paste
1411 @cindex pasting, of subtrees
1412 @cindex cutting, of subtrees
1413 @cindex copying, of subtrees
1414 @cindex sorting, of subtrees
1415 @cindex subtrees, cut and paste
1418 @orgcmd{M-@key{RET},org-insert-heading}
1419 @vindex org-M-RET-may-split-line
1420 Insert a new heading/item with the same level as the one at point.
1422 If the command is used at the @emph{beginning} of a line, and if there is
1423 a heading or a plain list item (@pxref{Plain lists}) at point, the new
1424 heading/item is created @emph{before} the current line. When used at the
1425 beginning of a regular line of text, turn that line into a heading.
1427 When this command is used in the middle of a line, the line is split and the
1428 rest of the line becomes the new item or headline. If you do not want the
1429 line to be split, customize @code{org-M-RET-may-split-line}.
1431 Calling the command with a @kbd{C-u} prefix unconditionally inserts a new
1432 heading at the end of the current subtree, thus preserving its contents.
1433 With a double @kbd{C-u C-u} prefix, the new heading is created at the end of
1434 the parent subtree instead.
1435 @orgcmd{C-@key{RET},org-insert-heading-respect-content}
1436 Insert a new heading at the end of the current subtree.
1437 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
1438 @vindex org-treat-insert-todo-heading-as-state-change
1439 Insert new TODO entry with same level as current heading. See also the
1440 variable @code{org-treat-insert-todo-heading-as-state-change}.
1441 @orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
1442 Insert new TODO entry with same level as current heading. Like
1443 @kbd{C-@key{RET}}, the new headline will be inserted after the current
1445 @orgcmd{@key{TAB},org-cycle}
1446 In a new entry with no text yet, the first @key{TAB} demotes the entry to
1447 become a child of the previous one. The next @key{TAB} makes it a parent,
1448 and so on, all the way to top level. Yet another @key{TAB}, and you are back
1449 to the initial level.
1450 @orgcmd{M-@key{left},org-do-promote}
1451 Promote current heading by one level.
1452 @orgcmd{M-@key{right},org-do-demote}
1453 Demote current heading by one level.
1454 @orgcmd{M-S-@key{left},org-promote-subtree}
1455 Promote the current subtree by one level.
1456 @orgcmd{M-S-@key{right},org-demote-subtree}
1457 Demote the current subtree by one level.
1458 @orgcmd{M-S-@key{up},org-move-subtree-up}
1459 Move subtree up (swap with previous subtree of same
1461 @orgcmd{M-S-@key{down},org-move-subtree-down}
1462 Move subtree down (swap with next subtree of same level).
1463 @orgcmd{M-h,org-mark-element}
1464 Mark the element at point. Hitting repeatedly will mark subsequent elements
1465 of the one just marked. E.g., hitting @key{M-h} on a paragraph will mark it,
1466 hitting @key{M-h} immediately again will mark the next one.
1467 @orgcmd{C-c @@,org-mark-subtree}
1468 Mark the subtree at point. Hitting repeatedly will mark subsequent subtrees
1469 of the same level than the marked subtree.
1470 @orgcmd{C-c C-x C-w,org-cut-subtree}
1471 Kill subtree, i.e., remove it from buffer but save in kill ring.
1472 With a numeric prefix argument N, kill N sequential subtrees.
1473 @orgcmd{C-c C-x M-w,org-copy-subtree}
1474 Copy subtree to kill ring. With a numeric prefix argument N, copy the N
1475 sequential subtrees.
1476 @orgcmd{C-c C-x C-y,org-paste-subtree}
1477 Yank subtree from kill ring. This does modify the level of the subtree to
1478 make sure the tree fits in nicely at the yank position. The yank level can
1479 also be specified with a numeric prefix argument, or by yanking after a
1480 headline marker like @samp{****}.
1481 @orgcmd{C-y,org-yank}
1482 @vindex org-yank-adjusted-subtrees
1483 @vindex org-yank-folded-subtrees
1484 Depending on the options @code{org-yank-adjusted-subtrees} and
1485 @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
1486 paste subtrees folded and in a clever way, using the same command as @kbd{C-c
1487 C-x C-y}. With the default settings, no level adjustment will take place,
1488 but the yanked tree will be folded unless doing so would swallow text
1489 previously visible. Any prefix argument to this command will force a normal
1490 @code{yank} to be executed, with the prefix passed along. A good way to
1491 force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a
1492 yank, it will yank previous kill items plainly, without adjustment and
1494 @orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
1495 Clone a subtree by making a number of sibling copies of it. You will be
1496 prompted for the number of copies to make, and you can also specify if any
1497 timestamps in the entry should be shifted. This can be useful, for example,
1498 to create a number of tasks related to a series of lectures to prepare. For
1499 more details, see the docstring of the command
1500 @code{org-clone-subtree-with-time-shift}.
1501 @orgcmd{C-c C-w,org-refile}
1502 Refile entry or region to a different location. @xref{Refile and copy}.
1503 @orgcmd{C-c ^,org-sort}
1504 Sort same-level entries. When there is an active region, all entries in the
1505 region will be sorted. Otherwise the children of the current headline are
1506 sorted. The command prompts for the sorting method, which can be
1507 alphabetically, numerically, by time (first timestamp with active preferred,
1508 creation time, scheduled time, deadline time), by priority, by TODO keyword
1509 (in the sequence the keywords have been defined in the setup) or by the value
1510 of a property. Reverse sorting is possible as well. You can also supply
1511 your own function to extract the sorting key. With a @kbd{C-u} prefix,
1512 sorting will be case-sensitive.
1513 @orgcmd{C-x n s,org-narrow-to-subtree}
1514 Narrow buffer to current subtree.
1515 @orgcmd{C-x n b,org-narrow-to-block}
1516 Narrow buffer to current block.
1517 @orgcmd{C-x n w,widen}
1518 Widen buffer to remove narrowing.
1519 @orgcmd{C-c *,org-toggle-heading}
1520 Turn a normal line or plain list item into a headline (so that it becomes a
1521 subheading at its location). Also turn a headline into a normal line by
1522 removing the stars. If there is an active region, turn all lines in the
1523 region into headlines. If the first line in the region was an item, turn
1524 only the item lines into headlines. Finally, if the first line is a
1525 headline, remove the stars from all headlines in the region.
1528 @cindex region, active
1529 @cindex active region
1530 @cindex transient mark mode
1531 When there is an active region (Transient Mark mode), promotion and
1532 demotion work on all headlines in the region. To select a region of
1533 headlines, it is best to place both point and mark at the beginning of a
1534 line, mark at the beginning of the first headline, and point at the line
1535 just after the last headline to change. Note that when the cursor is
1536 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
1541 @section Sparse trees
1542 @cindex sparse trees
1543 @cindex trees, sparse
1544 @cindex folding, sparse trees
1545 @cindex occur, command
1547 @vindex org-show-context-detail
1548 An important feature of Org mode is the ability to construct @emph{sparse
1549 trees} for selected information in an outline tree, so that the entire
1550 document is folded as much as possible, but the selected information is made
1551 visible along with the headline structure above it@footnote{See also the
1552 variable @code{org-show-context-detail} to decide how much context is shown
1553 around each match.}. Just try it out and you will see immediately how it
1556 Org mode contains several commands for creating such trees, all these
1557 commands can be accessed through a dispatcher:
1560 @orgcmd{C-c /,org-sparse-tree}
1561 This prompts for an extra key to select a sparse-tree creating command.
1562 @orgcmdkkc{C-c / r,C-c / /,org-occur}
1563 @vindex org-remove-highlights-with-change
1564 Prompts for a regexp and shows a sparse tree with all matches. If
1565 the match is in a headline, the headline is made visible. If the match is in
1566 the body of an entry, headline and body are made visible. In order to
1567 provide minimal context, also the full hierarchy of headlines above the match
1568 is shown, as well as the headline following the match. Each match is also
1569 highlighted; the highlights disappear when the buffer is changed by an
1570 editing command@footnote{This depends on the option
1571 @code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
1572 When called with a @kbd{C-u} prefix argument, previous highlights are kept,
1573 so several calls to this command can be stacked.
1574 @orgcmdkkc{M-g n,M-g M-n,next-error}
1575 Jump to the next sparse tree match in this buffer.
1576 @orgcmdkkc{M-g p,M-g M-p,previous-error}
1577 Jump to the previous sparse tree match in this buffer.
1581 @vindex org-agenda-custom-commands
1582 For frequently used sparse trees of specific search strings, you can
1583 use the option @code{org-agenda-custom-commands} to define fast
1584 keyboard access to specific sparse trees. These commands will then be
1585 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
1589 (setq org-agenda-custom-commands
1590 '(("f" occur-tree "FIXME")))
1593 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
1594 a sparse tree matching the string @samp{FIXME}.
1596 The other sparse tree commands select headings based on TODO keywords,
1597 tags, or properties and will be discussed later in this manual.
1600 @cindex printing sparse trees
1601 @cindex visible text, printing
1602 To print a sparse tree, you can use the Emacs command
1603 @code{ps-print-buffer-with-faces} which does not print invisible parts of the
1604 document. Or you can use @kbd{C-c C-e C-v} to export only the visible part
1605 of the document and print the resulting file.
1608 @section Plain lists
1610 @cindex lists, plain
1611 @cindex lists, ordered
1612 @cindex ordered lists
1614 Within an entry of the outline tree, hand-formatted lists can provide
1615 additional structure. They also provide a way to create lists of checkboxes
1616 (@pxref{Checkboxes}). Org supports editing such lists, and every exporter
1617 (@pxref{Exporting}) can parse and format them.
1619 Org knows ordered lists, unordered lists, and description lists.
1622 @emph{Unordered} list items start with @samp{-}, @samp{+}, or
1623 @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
1624 they will be seen as top-level headlines. Also, when you are hiding leading
1625 stars to get a clean outline view, plain list items starting with a star may
1626 be hard to distinguish from true headlines. In short: even though @samp{*}
1627 is supported, it may be better to not use it for plain list items.} as
1630 @vindex org-plain-list-ordered-item-terminator
1631 @vindex org-list-allow-alphabetical
1632 @emph{Ordered} list items start with a numeral followed by either a period or
1633 a right parenthesis@footnote{You can filter out any of them by configuring
1634 @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
1635 @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
1636 @samp{A)} by configuring @code{org-list-allow-alphabetical}. To minimize
1637 confusion with normal text, those are limited to one character only. Beyond
1638 that limit, bullets will automatically fallback to numbers.}. If you want a
1639 list to start with a different value (e.g., 20), start the text of the item
1640 with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
1641 must be put @emph{before} the checkbox. If you have activated alphabetical
1642 lists, you can also use counters like @code{[@@b]}.}. Those constructs can
1643 be used in any item of the list in order to enforce a particular numbering.
1645 @emph{Description} list items are unordered list items, and contain the
1646 separator @samp{ :: } to distinguish the description @emph{term} from the
1650 Items belonging to the same list must have the same indentation on the first
1651 line. In particular, if an ordered list reaches number @samp{10.}, then the
1652 2--digit numbers must be written left-aligned with the other numbers in the
1653 list. An item ends before the next line that is less or equally indented
1654 than its bullet/number.
1656 @vindex org-list-empty-line-terminates-plain-lists
1657 A list ends whenever every item has ended, which means before any line less
1658 or equally indented than items at top level. It also ends before two blank
1659 lines@footnote{See also @code{org-list-empty-line-terminates-plain-lists}.}.
1660 In that case, all items are closed. Here is an example:
1664 ** Lord of the Rings
1665 My favorite scenes are (in this order)
1666 1. The attack of the Rohirrim
1667 2. Eowyn's fight with the witch king
1668 + this was already my favorite scene in the book
1669 + I really like Miranda Otto.
1670 3. Peter Jackson being shot by Legolas
1672 He makes a really funny face when it happens.
1673 But in the end, no individual scenes matter but the film as a whole.
1674 Important actors in this film are:
1675 - @b{Elijah Wood} :: He plays Frodo
1676 - @b{Sean Astin} :: He plays Sam, Frodo's friend. I still remember
1677 him very well from his role as Mikey Walsh in @i{The Goonies}.
1681 Org supports these lists by tuning filling and wrapping commands to deal with
1682 them correctly, and by exporting them properly (@pxref{Exporting}). Since
1683 indentation is what governs the structure of these lists, many structural
1684 constructs like @code{#+BEGIN_...} blocks can be indented to signal that they
1685 belong to a particular item.
1687 @vindex org-list-demote-modify-bullet
1688 @vindex org-list-indent-offset
1689 If you find that using a different bullet for a sub-list (than that used for
1690 the current list-level) improves readability, customize the variable
1691 @code{org-list-demote-modify-bullet}. To get a greater difference of
1692 indentation between items and their sub-items, customize
1693 @code{org-list-indent-offset}.
1695 @vindex org-list-automatic-rules
1696 The following commands act on items when the cursor is in the first line of
1697 an item (the line with the bullet or number). Some of them imply the
1698 application of automatic rules to keep list structure intact. If some of
1699 these actions get in your way, configure @code{org-list-automatic-rules}
1700 to disable them individually.
1703 @orgcmd{@key{TAB},org-cycle}
1704 @cindex cycling, in plain lists
1705 @vindex org-cycle-include-plain-lists
1706 Items can be folded just like headline levels. Normally this works only if
1707 the cursor is on a plain list item. For more details, see the variable
1708 @code{org-cycle-include-plain-lists}. If this variable is set to
1709 @code{integrate}, plain list items will be treated like low-level
1710 headlines. The level of an item is then given by the indentation of the
1711 bullet/number. Items are always subordinate to real headlines, however; the
1712 hierarchies remain completely separated. In a new item with no text yet, the
1713 first @key{TAB} demotes the item to become a child of the previous
1714 one. Subsequent @key{TAB}s move the item to meaningful levels in the list
1715 and eventually get it back to its initial position.
1716 @orgcmd{M-@key{RET},org-insert-heading}
1717 @vindex org-M-RET-may-split-line
1718 @vindex org-list-automatic-rules
1719 Insert new item at current level. With a prefix argument, force a new
1720 heading (@pxref{Structure editing}). If this command is used in the middle
1721 of an item, that item is @emph{split} in two, and the second part becomes the
1722 new item@footnote{If you do not want the item to be split, customize the
1723 variable @code{org-M-RET-may-split-line}.}. If this command is executed
1724 @emph{before item's body}, the new item is created @emph{before} the current
1729 @kindex M-S-@key{RET}
1731 Insert a new item with a checkbox (@pxref{Checkboxes}).
1732 @kindex S-@key{down}
1735 @cindex shift-selection-mode
1736 @vindex org-support-shift-select
1737 @vindex org-list-use-circular-motion
1738 Jump to the previous/next item in the current list@footnote{If you want to
1739 cycle around items that way, you may customize
1740 @code{org-list-use-circular-motion}.}, but only if
1741 @code{org-support-shift-select} is off. If not, you can still use paragraph
1742 jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
1745 @kindex M-@key{down}
1748 Move the item including subitems up/down@footnote{See
1749 @code{org-list-use-circular-motion} for a cyclic behavior.} (swap with
1750 previous/next item of same indentation). If the list is ordered, renumbering
1752 @kindex M-@key{left}
1753 @kindex M-@key{right}
1756 Decrease/increase the indentation of an item, leaving children alone.
1757 @kindex M-S-@key{left}
1758 @kindex M-S-@key{right}
1759 @item M-S-@key{left}
1760 @itemx M-S-@key{right}
1761 Decrease/increase the indentation of the item, including subitems.
1762 Initially, the item tree is selected based on current indentation. When
1763 these commands are executed several times in direct succession, the initially
1764 selected region is used, even if the new indentation would imply a different
1765 hierarchy. To use the new hierarchy, break the command chain with a cursor
1768 As a special case, using this command on the very first item of a list will
1769 move the whole list. This behavior can be disabled by configuring
1770 @code{org-list-automatic-rules}. The global indentation of a list has no
1771 influence on the text @emph{after} the list.
1774 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1775 state of the checkbox. In any case, verify bullets and indentation
1776 consistency in the whole list.
1778 @vindex org-plain-list-ordered-item-terminator
1780 Cycle the entire list level through the different itemize/enumerate bullets
1781 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
1782 depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
1783 and its indentation. With a numeric prefix argument N, select the Nth bullet
1784 from this list. If there is an active region when calling this, all selected
1785 lines are converted to list items. With a prefix argument, selected text is
1786 changed into a single item. If the first line already was a list item, any
1787 item marker will be removed from the list. Finally, even without an active
1788 region, a normal line will be converted into a list item.
1791 Turn a plain list item into a headline (so that it becomes a subheading at
1792 its location). @xref{Structure editing}, for a detailed explanation.
1795 Turn the whole plain list into a subtree of the current heading. Checkboxes
1796 (@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
1798 @kindex S-@key{left}
1799 @kindex S-@key{right}
1801 @vindex org-support-shift-select
1802 This command also cycles bullet styles when the cursor in on the bullet or
1803 anywhere in an item line, details depending on
1804 @code{org-support-shift-select}.
1806 @cindex sorting, of plain list
1808 Sort the plain list. You will be prompted for the sorting method:
1809 numerically, alphabetically, by time, by checked status for check lists,
1810 or by a custom function.
1816 @cindex visibility cycling, drawers
1818 @cindex org-insert-drawer
1820 Sometimes you want to keep information associated with an entry, but you
1821 normally don't want to see it. For this, Org mode has @emph{drawers}. They
1822 can contain anything but a headline and another drawer. Drawers look like
1826 ** This is a headline
1827 Still outside the drawer
1829 This is inside the drawer.
1834 You can interactively insert drawers at point by calling
1835 @code{org-insert-drawer}, which is bound to @key{C-c C-x d}. With an active
1836 region, this command will put the region inside the drawer. With a prefix
1837 argument, this command calls @code{org-insert-property-drawer} and add
1838 a property drawer right below the current headline. Completion over drawer
1839 keywords is also possible using @kbd{M-@key{TAB}}@footnote{Many desktops
1840 intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
1841 @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}.
1843 Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
1844 show the entry, but keep the drawer collapsed to a single line. In order to
1845 look inside the drawer, you need to move the cursor to the drawer line and
1846 press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
1847 storing properties (@pxref{Properties and columns}), and you can also arrange
1848 for state change notes (@pxref{Tracking TODO state changes}) and clock times
1849 (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
1850 want to store a quick note in the LOGBOOK drawer, in a similar way to state
1856 Add a time-stamped note to the LOGBOOK drawer.
1859 @vindex org-export-with-drawers
1860 @vindex org-export-with-properties
1861 You can select the name of the drawers which should be exported with
1862 @code{org-export-with-drawers}. In that case, drawer contents will appear in
1863 export output. Property drawers are not affected by this variable: configure
1864 @code{org-export-with-properties} instead.
1869 @vindex org-hide-block-startup
1870 @cindex blocks, folding
1871 Org mode uses begin...end blocks for various purposes from including source
1872 code examples (@pxref{Literal examples}) to capturing time logging
1873 information (@pxref{Clocking work time}). These blocks can be folded and
1874 unfolded by pressing TAB in the begin line. You can also get all blocks
1875 folded at startup by configuring the option @code{org-hide-block-startup}
1876 or on a per-file basis by using
1878 @cindex @code{hideblocks}, STARTUP keyword
1879 @cindex @code{nohideblocks}, STARTUP keyword
1881 #+STARTUP: hideblocks
1882 #+STARTUP: nohideblocks
1889 Org mode supports the creation of footnotes.
1891 A footnote is started by a footnote marker in square brackets in column 0, no
1892 indentation allowed. It ends at the next footnote definition, headline, or
1893 after two consecutive empty lines. The footnote reference is simply the
1894 marker in square brackets, inside text. Markers always start with
1895 @code{fn:}. For example:
1898 The Org homepage[fn:1] now looks a lot better than it used to.
1900 [fn:1] The link is: http://orgmode.org
1903 Org mode extends the number-based syntax to @emph{named} footnotes and
1904 optional inline definition. Here are the valid references:
1908 A named footnote reference, where @code{name} is a unique label word, or, for
1909 simplicity of automatic creation, a number.
1910 @item [fn::This is the inline definition of this footnote]
1911 A @LaTeX{}-like anonymous footnote where the definition is given directly at the
1913 @item [fn:name:a definition]
1914 An inline definition of a footnote, which also specifies a name for the note.
1915 Since Org allows multiple references to the same note, you can then use
1916 @code{[fn:name]} to create additional references.
1919 @vindex org-footnote-auto-label
1920 Footnote labels can be created automatically, or you can create names yourself.
1921 This is handled by the variable @code{org-footnote-auto-label} and its
1922 corresponding @code{#+STARTUP} keywords. See the docstring of that variable
1925 @noindent The following command handles footnotes:
1930 The footnote action command.
1932 When the cursor is on a footnote reference, jump to the definition. When it
1933 is at a definition, jump to the (first) reference.
1935 @vindex org-footnote-define-inline
1936 @vindex org-footnote-section
1937 @vindex org-footnote-auto-adjust
1938 Otherwise, create a new footnote. Depending on the option
1939 @code{org-footnote-define-inline}@footnote{The corresponding in-buffer
1940 setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
1941 definition will be placed right into the text as part of the reference, or
1942 separately into the location determined by the option
1943 @code{org-footnote-section}.
1945 When this command is called with a prefix argument, a menu of additional
1948 s @r{Sort the footnote definitions by reference sequence. During editing,}
1949 @r{Org makes no effort to sort footnote definitions into a particular}
1950 @r{sequence. If you want them sorted, use this command, which will}
1951 @r{also move entries according to @code{org-footnote-section}. Automatic}
1952 @r{sorting after each insertion/deletion can be configured using the}
1953 @r{option @code{org-footnote-auto-adjust}.}
1954 r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering}
1955 @r{after each insertion/deletion can be configured using the option}
1956 @r{@code{org-footnote-auto-adjust}.}
1957 S @r{Short for first @code{r}, then @code{s} action.}
1958 n @r{Normalize the footnotes by collecting all definitions (including}
1959 @r{inline definitions) into a special section, and then numbering them}
1960 @r{in sequence. The references will then also be numbers.}
1961 d @r{Delete the footnote at point, and all definitions of and references}
1964 Depending on the variable @code{org-footnote-auto-adjust}@footnote{the
1965 corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},
1966 renumbering and sorting footnotes can be automatic after each insertion or
1971 If the cursor is on a footnote reference, jump to the definition. If it is a
1972 the definition, jump back to the reference. When called at a footnote
1973 location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
1977 @item C-c C-o @r{or} mouse-1/2
1978 Footnote labels are also links to the corresponding definition/reference, and
1979 you can use the usual commands to follow these links.
1981 @vindex org-edit-footnote-reference
1985 Edit the footnote definition corresponding to the reference at point in
1986 a seperate window. The window can be closed by pressing @kbd{C-c '}.
1990 @node Orgstruct mode
1991 @section The Orgstruct minor mode
1992 @cindex Orgstruct mode
1993 @cindex minor mode for structure editing
1995 If you like the intuitive way the Org mode structure editing and list
1996 formatting works, you might want to use these commands in other modes like
1997 Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes
1998 this possible. Toggle the mode with @kbd{M-x orgstruct-mode RET}, or
1999 turn it on by default, for example in Message mode, with one of:
2002 (add-hook 'message-mode-hook 'turn-on-orgstruct)
2003 (add-hook 'message-mode-hook 'turn-on-orgstruct++)
2006 When this mode is active and the cursor is on a line that looks to Org like a
2007 headline or the first line of a list item, most structure editing commands
2008 will work, even if the same keys normally have different functionality in the
2009 major mode you are using. If the cursor is not in one of those special
2010 lines, Orgstruct mode lurks silently in the shadows.
2012 When you use @code{orgstruct++-mode}, Org will also export indentation and
2013 autofill settings into that mode, and detect item context after the first
2016 @vindex orgstruct-heading-prefix-regexp
2017 You can also use Org structure editing to fold and unfold headlines in
2018 @emph{any} file, provided you defined @code{orgstruct-heading-prefix-regexp}:
2019 the regular expression must match the local prefix to use before Org's
2020 headlines. For example, if you set this variable to @code{";; "} in Emacs
2021 Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
2022 commented lines. Some commands like @code{org-demote} are disabled when the
2023 prefix is set, but folding/unfolding will work correctly.
2029 A reference document providing a formal description of Org's syntax is
2030 available as @uref{http://orgmode.org/worg/dev/org-syntax.html, a draft on
2031 Worg}, written and maintained by Nicolas Goaziou. It defines Org's core
2032 internal concepts such as @code{headlines}, @code{sections}, @code{affiliated
2033 keywords}, @code{(greater) elements} and @code{objects}. Each part of an Org
2034 file falls into one of the categories above.
2036 To explore the abstract structure of an Org buffer, run this in a buffer:
2039 M-: (org-element-parse-buffer) RET
2042 It will output a list containing the buffer's content represented as an
2043 abstract structure. The export engine relies on the information stored in
2044 this list. Most interactive commands (e.g., for structure editing) also
2045 rely on the syntactic meaning of the surrounding context.
2047 @cindex syntax checker
2049 You can check syntax in your documents using @code{org-lint} command.
2054 @cindex editing tables
2056 Org comes with a fast and intuitive table editor. Spreadsheet-like
2057 calculations are supported using the Emacs @file{calc} package
2058 (@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}).
2061 * Built-in table editor:: Simple tables
2062 * Column width and alignment:: Overrule the automatic settings
2063 * Column groups:: Grouping to trigger vertical lines
2064 * Orgtbl mode:: The table editor as minor mode
2065 * The spreadsheet:: The table editor has spreadsheet capabilities
2066 * Org-Plot:: Plotting from org tables
2069 @node Built-in table editor
2070 @section The built-in table editor
2071 @cindex table editor, built-in
2073 Org makes it easy to format tables in plain ASCII@. Any line with @samp{|} as
2074 the first non-whitespace character is considered part of a table. @samp{|}
2075 is also the column separator@footnote{To insert a vertical bar into a table
2076 field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table
2077 might look like this:
2080 | Name | Phone | Age |
2081 |-------+-------+-----|
2082 | Peter | 1234 | 17 |
2083 | Anna | 4321 | 25 |
2086 A table is re-aligned automatically each time you press @key{TAB} or
2087 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
2088 the next field (@key{RET} to the next row) and creates new table rows
2089 at the end of the table or before horizontal lines. The indentation
2090 of the table is set by the first line. Any line starting with
2091 @samp{|-} is considered as a horizontal separator line and will be
2092 expanded on the next re-align to span the whole table width. So, to
2093 create the above table, you would only type
2100 @noindent and then press @key{TAB} to align the table and start filling in
2101 fields. Even faster would be to type @code{|Name|Phone|Age} followed by
2102 @kbd{C-c @key{RET}}.
2104 @vindex org-enable-table-editor
2105 @vindex org-table-auto-blank-field
2106 When typing text into a field, Org treats @key{DEL},
2107 @key{Backspace}, and all character keys in a special way, so that
2108 inserting and deleting avoids shifting other fields. Also, when
2109 typing @emph{immediately after the cursor was moved into a new field
2110 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
2111 field is automatically made blank. If this behavior is too
2112 unpredictable for you, configure the options
2113 @code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
2116 @tsubheading{Creation and conversion}
2117 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2118 Convert the active region to a table. If every line contains at least one
2119 TAB character, the function assumes that the material is tab separated.
2120 If every line contains a comma, comma-separated values (CSV) are assumed.
2121 If not, lines are split at whitespace into fields. You can use a prefix
2122 argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
2123 C-u} forces TAB, @kbd{C-u C-u C-u} will prompt for a regular expression to
2124 match the separator, and a numeric argument N indicates that at least N
2125 consecutive spaces, or alternatively a TAB will be the separator.
2127 If there is no active region, this command creates an empty Org
2128 table. But it is easier just to start typing, like
2129 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
2131 @tsubheading{Re-aligning and field motion}
2132 @orgcmd{C-c C-c,org-table-align}
2133 Re-align the table and don't move to another field.
2135 @orgcmd{C-c SPC,org-table-blank-field}
2136 Blank the field at point.
2138 @orgcmd{TAB,org-table-next-field}
2139 Re-align the table, move to the next field. Creates a new row if
2142 @orgcmd{S-@key{TAB},org-table-previous-field}
2143 Re-align, move to previous field.
2145 @orgcmd{@key{RET},org-table-next-row}
2146 Re-align the table and move down to next row. Creates a new row if
2147 necessary. At the beginning or end of a line, @key{RET} still does
2148 NEWLINE, so it can be used to split a table.
2150 @orgcmd{M-a,org-table-beginning-of-field}
2151 Move to beginning of the current table field, or on to the previous field.
2152 @orgcmd{M-e,org-table-end-of-field}
2153 Move to end of the current table field, or on to the next field.
2155 @tsubheading{Column and row editing}
2156 @orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
2157 Move the current column left/right.
2159 @orgcmd{M-S-@key{left},org-table-delete-column}
2160 Kill the current column.
2162 @orgcmd{M-S-@key{right},org-table-insert-column}
2163 Insert a new column to the left of the cursor position.
2165 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
2166 Move the current row up/down.
2168 @orgcmd{M-S-@key{up},org-table-kill-row}
2169 Kill the current row or horizontal line.
2171 @orgcmd{M-S-@key{down},org-table-insert-row}
2172 Insert a new row above the current row. With a prefix argument, the line is
2173 created below the current one.
2175 @orgcmd{C-c -,org-table-insert-hline}
2176 Insert a horizontal line below current row. With a prefix argument, the line
2177 is created above the current line.
2179 @orgcmd{C-c @key{RET},org-table-hline-and-move}
2180 Insert a horizontal line below current row, and move the cursor into the row
2183 @orgcmd{C-c ^,org-table-sort-lines}
2184 Sort the table lines in the region. The position of point indicates the
2185 column to be used for sorting, and the range of lines is the range
2186 between the nearest horizontal separator lines, or the entire table. If
2187 point is before the first column, you will be prompted for the sorting
2188 column. If there is an active region, the mark specifies the first line
2189 and the sorting column, while point should be in the last line to be
2190 included into the sorting. The command prompts for the sorting type
2191 (alphabetically, numerically, or by time). You can sort in normal or
2192 reverse order. You can also supply your own key extraction and comparison
2193 functions. When called with a prefix argument, alphabetic sorting will be
2196 @tsubheading{Regions}
2197 @orgcmd{C-c C-x M-w,org-table-copy-region}
2198 Copy a rectangular region from a table to a special clipboard. Point and
2199 mark determine edge fields of the rectangle. If there is no active region,
2200 copy just the current field. The process ignores horizontal separator lines.
2202 @orgcmd{C-c C-x C-w,org-table-cut-region}
2203 Copy a rectangular region from a table to a special clipboard, and
2204 blank all fields in the rectangle. So this is the ``cut'' operation.
2206 @orgcmd{C-c C-x C-y,org-table-paste-rectangle}
2207 Paste a rectangular region into a table.
2208 The upper left corner ends up in the current field. All involved fields
2209 will be overwritten. If the rectangle does not fit into the present table,
2210 the table is enlarged as needed. The process ignores horizontal separator
2213 @orgcmd{M-@key{RET},org-table-wrap-region}
2214 Split the current field at the cursor position and move the rest to the line
2215 below. If there is an active region, and both point and mark are in the same
2216 column, the text in the column is wrapped to minimum width for the given
2217 number of lines. A numeric prefix argument may be used to change the number
2218 of desired lines. If there is no region, but you specify a prefix argument,
2219 the current field is made blank, and the content is appended to the field
2222 @tsubheading{Calculations}
2223 @cindex formula, in tables
2224 @cindex calculations, in tables
2225 @cindex region, active
2226 @cindex active region
2227 @cindex transient mark mode
2228 @orgcmd{C-c +,org-table-sum}
2229 Sum the numbers in the current column, or in the rectangle defined by
2230 the active region. The result is shown in the echo area and can
2231 be inserted with @kbd{C-y}.
2233 @orgcmd{S-@key{RET},org-table-copy-down}
2234 @vindex org-table-copy-increment
2235 When current field is empty, copy from first non-empty field above. When not
2236 empty, copy current field down to next row and move cursor along with it.
2237 Depending on the option @code{org-table-copy-increment}, integer field
2238 values will be incremented during copy. Integers that are too large will not
2239 be incremented. Also, a @code{0} prefix argument temporarily disables the
2240 increment. This key is also used by shift-selection and related modes
2241 (@pxref{Conflicts}).
2243 @tsubheading{Miscellaneous}
2244 @orgcmd{C-c `,org-table-edit-field}
2245 Edit the current field in a separate window. This is useful for fields that
2246 are not fully visible (@pxref{Column width and alignment}). When called with
2247 a @kbd{C-u} prefix, just make the full field visible, so that it can be
2248 edited in place. When called with two @kbd{C-u} prefixes, make the editor
2249 window follow the cursor through the table and always show the current
2250 field. The follow mode exits automatically when the cursor leaves the table,
2251 or when you repeat this command with @kbd{C-u C-u C-c `}.
2253 @item M-x org-table-import RET
2254 Import a file as a table. The table should be TAB or whitespace
2255 separated. Use, for example, to import a spreadsheet table or data
2256 from a database, because these programs generally can write
2257 TAB-separated text files. This command works by inserting the file into
2258 the buffer and then converting the region to a table. Any prefix
2259 argument is passed on to the converter, which uses it to determine the
2261 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2262 Tables can also be imported by pasting tabular text into the Org
2263 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
2264 @kbd{C-c |} command (see above under @i{Creation and conversion}).
2266 @item M-x org-table-export RET
2267 @findex org-table-export
2268 @vindex org-table-export-default-format
2269 Export the table, by default as a TAB-separated file. Use for data
2270 exchange with, for example, spreadsheet or database programs. The format
2271 used to export the file can be configured in the option
2272 @code{org-table-export-default-format}. You may also use properties
2273 @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
2274 name and the format for table export in a subtree. Org supports quite
2275 general formats for exported tables. The exporter format is the same as the
2276 format used by Orgtbl radio tables, see @ref{Translator functions}, for a
2277 detailed description.
2280 If you don't like the automatic table editor because it gets in your
2281 way on lines which you would like to start with @samp{|}, you can turn
2285 (setq org-enable-table-editor nil)
2288 @noindent Then the only table command that still works is
2289 @kbd{C-c C-c} to do a manual re-align.
2291 @node Column width and alignment
2292 @section Column width and alignment
2293 @cindex narrow columns in tables
2294 @cindex alignment in tables
2296 The width of columns is automatically determined by the table editor. And
2297 also the alignment of a column is determined automatically from the fraction
2298 of number-like versus non-number fields in the column.
2300 Sometimes a single field or a few fields need to carry more text, leading to
2301 inconveniently wide columns. Or maybe you want to make a table with several
2302 columns having a fixed width, regardless of content. To set the width of
2303 a column, one field anywhere in the column may contain just the string
2304 @samp{<N>} where @samp{N} is an integer specifying the width of the column in
2305 characters. The next re-align will then set the width of this column to this
2310 |---+------------------------------| |---+--------|
2312 | 1 | one | | 1 | one |
2313 | 2 | two | ----\ | 2 | two |
2314 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
2315 | 4 | four | | 4 | four |
2316 |---+------------------------------| |---+--------|
2321 Fields that are wider become clipped and end in the string @samp{=>}.
2322 Note that the full text is still in the buffer but is hidden.
2323 To see the full text, hold the mouse over the field---a tool-tip window
2324 will show the full content. To edit such a field, use the command
2325 @kbd{C-c `} (that is @kbd{C-c} followed by the grave accent). This will
2326 open a new window with the full field. Edit it and finish with @kbd{C-c
2329 @vindex org-startup-align-all-tables
2330 When visiting a file containing a table with narrowed columns, the
2331 necessary character hiding has not yet happened, and the table needs to
2332 be aligned before it looks nice. Setting the option
2333 @code{org-startup-align-all-tables} will realign all tables in a file
2334 upon visiting, but also slow down startup. You can also set this option
2335 on a per-file basis with:
2342 If you would like to overrule the automatic alignment of number-rich columns
2343 to the right and of string-rich columns to the left, you can use @samp{<r>},
2344 @samp{<c>}@footnote{Centering does not work inside Emacs, but it does have an
2345 effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may
2346 also combine alignment and field width like this: @samp{<r10>}.
2348 Lines which only contain these formatting cookies will be removed
2349 automatically when exporting the document.
2352 @section Column groups
2353 @cindex grouping columns in tables
2355 When Org exports tables, it does so by default without vertical lines because
2356 that is visually more satisfying in general. Occasionally however, vertical
2357 lines can be useful to structure a table into groups of columns, much like
2358 horizontal lines can do for groups of rows. In order to specify column
2359 groups, you can use a special row where the first field contains only
2360 @samp{/}. The further fields can either contain @samp{<} to indicate that
2361 this column should start a group, @samp{>} to indicate the end of a group, or
2362 @samp{<>} (no space between @samp{<} and @samp{>}) to make a column a group
2363 of its own. Boundaries between column groups will upon export be marked with
2364 vertical lines. Here is an example:
2367 | N | N^2 | N^3 | N^4 | ~sqrt(n)~ | ~sqrt[4](N)~ |
2368 |---+-----+-----+-----+-----------+--------------|
2369 | / | < | | > | < | > |
2370 | 1 | 1 | 1 | 1 | 1 | 1 |
2371 | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
2372 | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
2373 |---+-----+-----+-----+-----------+--------------|
2374 #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
2377 It is also sufficient to just insert the column group starters after
2378 every vertical line you would like to have:
2381 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2382 |----+-----+-----+-----+---------+------------|
2387 @section The Orgtbl minor mode
2389 @cindex minor mode for tables
2391 If you like the intuitive way the Org table editor works, you
2392 might also want to use it in other modes like Text mode or Mail mode.
2393 The minor mode Orgtbl mode makes this possible. You can always toggle
2394 the mode with @kbd{M-x orgtbl-mode RET}. To turn it on by default, for
2395 example in Message mode, use
2398 (add-hook 'message-mode-hook 'turn-on-orgtbl)
2401 Furthermore, with some special setup, it is possible to maintain tables
2402 in arbitrary syntax with Orgtbl mode. For example, it is possible to
2403 construct @LaTeX{} tables with the underlying ease and power of
2404 Orgtbl mode, including spreadsheet capabilities. For details, see
2405 @ref{Tables in arbitrary syntax}.
2407 @node The spreadsheet
2408 @section The spreadsheet
2409 @cindex calculations, in tables
2410 @cindex spreadsheet capabilities
2411 @cindex @file{calc} package
2413 The table editor makes use of the Emacs @file{calc} package to implement
2414 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
2415 derive fields from other fields. While fully featured, Org's implementation
2416 is not identical to other spreadsheets. For example, Org knows the concept
2417 of a @emph{column formula} that will be applied to all non-header fields in a
2418 column without having to copy the formula to each relevant field. There is
2419 also a formula debugger, and a formula editor with features for highlighting
2420 fields in the table corresponding to the references at the point in the
2421 formula, moving these references by arrow keys
2424 * References:: How to refer to another field or range
2425 * Formula syntax for Calc:: Using Calc to compute stuff
2426 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
2427 * Durations and time values:: How to compute durations and time values
2428 * Field and range formulas:: Formula for specific (ranges of) fields
2429 * Column formulas:: Formulas valid for an entire column
2430 * Lookup functions:: Lookup functions for searching tables
2431 * Editing and debugging formulas:: Fixing formulas
2432 * Updating the table:: Recomputing all dependent fields
2433 * Advanced features:: Field and column names, parameters and automatic recalc
2437 @subsection References
2440 To compute fields in the table from other fields, formulas must
2441 reference other fields or ranges. In Org, fields can be referenced
2442 by name, by absolute coordinates, and by relative coordinates. To find
2443 out what the coordinates of a field are, press @kbd{C-c ?} in that
2444 field, or press @kbd{C-c @}} to toggle the display of a grid.
2446 @subsubheading Field references
2447 @cindex field references
2448 @cindex references, to fields
2450 Formulas can reference the value of another field in two ways. Like in
2451 any other spreadsheet, you may reference fields with a letter/number
2452 combination like @code{B3}, meaning the 2nd field in the 3rd row.
2453 @vindex org-table-use-standard-references
2454 However, Org prefers@footnote{Org will understand references typed by the
2455 user as @samp{B4}, but it will not use this syntax when offering a formula
2456 for editing. You can customize this behavior using the option
2457 @code{org-table-use-standard-references}.} to use another, more general
2458 representation that looks like this:
2460 @@@var{row}$@var{column}
2463 Column specifications can be absolute like @code{$1},
2464 @code{$2},...@code{$@var{N}}, or relative to the current column (i.e., the
2465 column of the field which is being computed) like @code{$+1} or @code{$-2}.
2466 @code{$<} and @code{$>} are immutable references to the first and last
2467 column, respectively, and you can use @code{$>>>} to indicate the third
2468 column from the right.
2470 The row specification only counts data lines and ignores horizontal separator
2471 lines (hlines). Like with columns, you can use absolute row numbers
2472 @code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
2473 current row like @code{@@+3} or @code{@@-1}. @code{@@<} and @code{@@>} are
2474 immutable references the first and last@footnote{For backward compatibility
2475 you can also use special names like @code{$LR5} and @code{$LR12} to refer in
2476 a stable way to the 5th and 12th field in the last row of the table.
2477 However, this syntax is deprecated, it should not be used for new documents.
2478 Use @code{@@>$} instead.} row in the table, respectively. You may also
2479 specify the row relative to one of the hlines: @code{@@I} refers to the first
2480 hline, @code{@@II} to the second, etc. @code{@@-I} refers to the first such
2481 line above the current line, @code{@@+I} to the first such line below the
2482 current line. You can also write @code{@@III+2} which is the second data line
2483 after the third hline in the table.
2485 @code{@@0} and @code{$0} refer to the current row and column, respectively,
2486 i.e., to the row/column for the field being computed. Also, if you omit
2487 either the column or the row part of the reference, the current row/column is
2490 Org's references with @emph{unsigned} numbers are fixed references
2491 in the sense that if you use the same reference in the formula for two
2492 different fields, the same field will be referenced each time.
2493 Org's references with @emph{signed} numbers are floating
2494 references because the same reference operator can reference different
2495 fields depending on the field being calculated by the formula.
2497 Here are a few examples:
2500 @@2$3 @r{2nd row, 3rd column (same as @code{C2})}
2501 $5 @r{column 5 in the current row (same as @code{E&})}
2502 @@2 @r{current column, row 2}
2503 @@-1$-3 @r{the field one row up, three columns to the left}
2504 @@-I$2 @r{field just under hline above current row, column 2}
2505 @@>$5 @r{field in the last row, in column 5}
2508 @subsubheading Range references
2509 @cindex range references
2510 @cindex references, to ranges
2512 You may reference a rectangular range of fields by specifying two field
2513 references connected by two dots @samp{..}. If both fields are in the
2514 current row, you may simply use @samp{$2..$7}, but if at least one field
2515 is in a different row, you need to use the general @code{@@row$column}
2516 format at least for the first field (i.e the reference must start with
2517 @samp{@@} in order to be interpreted correctly). Examples:
2520 $1..$3 @r{first three fields in the current row}
2521 $P..$Q @r{range, using column names (see under Advanced)}
2522 $<<<..$>> @r{start in third column, continue to the last but one}
2523 @@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
2524 @@-1$-2..@@-1 @r{3 fields in the row above, starting from 2 columns on the left}
2525 @@I..II @r{between first and second hline, short for @code{@@I..@@II}}
2528 @noindent Range references return a vector of values that can be fed
2529 into Calc vector functions. Empty fields in ranges are normally suppressed,
2530 so that the vector contains only the non-empty fields. For other options
2531 with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax
2534 @subsubheading Field coordinates in formulas
2535 @cindex field coordinates
2536 @cindex coordinates, of field
2537 @cindex row, of field coordinates
2538 @cindex column, of field coordinates
2540 One of the very first actions during evaluation of Calc formulas and Lisp
2541 formulas is to substitute @code{@@#} and @code{$#} in the formula with the
2542 row or column number of the field where the current result will go to. The
2543 traditional Lisp formula equivalents are @code{org-table-current-dline} and
2544 @code{org-table-current-column}. Examples:
2547 @item if(@@# % 2, $#, string(""))
2548 Insert column number on odd rows, set field to empty on even rows.
2549 @item $2 = '(identity remote(FOO, @@@@#$1))
2550 Copy text or values of each row of column 1 of the table named @code{FOO}
2551 into column 2 of the current table.
2552 @item @@3 = 2 * remote(FOO, @@1$$#)
2553 Insert the doubled value of each column of row 1 of the table named
2554 @code{FOO} into row 3 of the current table.
2557 @noindent For the second/third example, the table named @code{FOO} must have
2558 at least as many rows/columns as the current table. Note that this is
2559 inefficient@footnote{The computation time scales as O(N^2) because the table
2560 named @code{FOO} is parsed for each field to be read.} for large number of
2563 @subsubheading Named references
2564 @cindex named references
2565 @cindex references, named
2566 @cindex name, of column or field
2567 @cindex constants, in calculations
2570 @vindex org-table-formula-constants
2571 @samp{$name} is interpreted as the name of a column, parameter or
2572 constant. Constants are defined globally through the option
2573 @code{org-table-formula-constants}, and locally (for the file) through a
2577 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
2581 @vindex constants-unit-system
2582 @pindex constants.el
2583 Also properties (@pxref{Properties and columns}) can be used as
2584 constants in table formulas: for a property @samp{:Xyz:} use the name
2585 @samp{$PROP_Xyz}, and the property will be searched in the current
2586 outline entry and in the hierarchy above it. If you have the
2587 @file{constants.el} package, it will also be used to resolve constants,
2588 including natural constants like @samp{$h} for Planck's constant, and
2589 units like @samp{$km} for kilometers@footnote{@file{constants.el} can
2590 supply the values of constants in two different unit systems, @code{SI}
2591 and @code{cgs}. Which one is used depends on the value of the variable
2592 @code{constants-unit-system}. You can use the @code{#+STARTUP} options
2593 @code{constSI} and @code{constcgs} to set this value for the current
2594 buffer.}. Column names and parameters can be specified in special table
2595 lines. These are described below, see @ref{Advanced features}. All
2596 names must start with a letter, and further consist of letters and
2599 @subsubheading Remote references
2600 @cindex remote references
2601 @cindex references, remote
2602 @cindex references, to a different table
2603 @cindex name, of column or field
2604 @cindex constants, in calculations
2605 @cindex #+NAME, for table
2607 You may also reference constants, fields and ranges from a different table,
2608 either in the current file or even in a different file. The syntax is
2611 remote(NAME-OR-ID,REF)
2615 where NAME can be the name of a table in the current file as set by a
2616 @code{#+NAME: Name} line before the table. It can also be the ID of an
2617 entry, even in a different file, and the reference then refers to the first
2618 table in that entry. REF is an absolute field or range reference as
2619 described above for example @code{@@3$3} or @code{$somename}, valid in the
2622 Indirection of NAME-OR-ID: When NAME-OR-ID has the format @code{@@ROW$COLUMN}
2623 it will be substituted with the name or ID found in this field of the current
2624 table. For example @code{remote($1, @@>$2)} => @code{remote(year_2013,
2625 @@>$1)}. The format @code{B3} is not supported because it can not be
2626 distinguished from a plain table name or ID.
2628 @node Formula syntax for Calc
2629 @subsection Formula syntax for Calc
2630 @cindex formula syntax, Calc
2631 @cindex syntax, of formulas
2633 A formula can be any algebraic expression understood by the Emacs @file{Calc}
2634 package. Note that @file{calc} has the non-standard convention that @samp{/}
2635 has lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as
2636 @samp{a/(b*c)}. Before evaluation by @code{calc-eval} (@pxref{Calling Calc
2637 from Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc,
2638 GNU Emacs Calc Manual}), variable substitution takes place according to the
2639 rules described above.
2640 @cindex vectors, in table calculations
2641 The range vectors can be directly fed into the Calc vector functions
2642 like @samp{vmean} and @samp{vsum}.
2644 @cindex format specifier
2645 @cindex mode, for @file{calc}
2646 @vindex org-calc-default-modes
2647 A formula can contain an optional mode string after a semicolon. This
2648 string consists of flags to influence Calc and other modes during
2649 execution. By default, Org uses the standard Calc modes (precision
2650 12, angular units degrees, fraction and symbolic modes off). The display
2651 format, however, has been changed to @code{(float 8)} to keep tables
2652 compact. The default settings can be configured using the option
2653 @code{org-calc-default-modes}.
2655 @noindent List of modes:
2659 Set the internal Calc calculation precision to 20 digits.
2660 @item @code{n3}, @code{s3}, @code{e2}, @code{f4}
2661 Normal, scientific, engineering or fixed format of the result of Calc passed
2662 back to Org. Calc formatting is unlimited in precision as long as the Calc
2663 calculation precision is greater.
2664 @item @code{D}, @code{R}
2665 Degree and radian angle modes of Calc.
2666 @item @code{F}, @code{S}
2667 Fraction and symbolic modes of Calc.
2668 @item @code{T}, @code{t}
2669 Duration computations in Calc or Lisp, @pxref{Durations and time values}.
2671 If and how to consider empty fields. Without @samp{E} empty fields in range
2672 references are suppressed so that the Calc vector or Lisp list contains only
2673 the non-empty fields. With @samp{E} the empty fields are kept. For empty
2674 fields in ranges or empty field references the value @samp{nan} (not a
2675 number) is used in Calc formulas and the empty string is used for Lisp
2676 formulas. Add @samp{N} to use 0 instead for both formula types. For the
2677 value of a field the mode @samp{N} has higher precedence than @samp{E}.
2679 Interpret all fields as numbers, use 0 for non-numbers. See the next section
2680 to see how this is essential for computations with Lisp formulas. In Calc
2681 formulas it is used only occasionally because there number strings are
2682 already interpreted as numbers without @samp{N}.
2684 Literal, for Lisp formulas only. See the next section.
2688 Unless you use large integer numbers or high-precision-calculation and
2689 -display for floating point numbers you may alternatively provide a
2690 @samp{printf} format specifier to reformat the Calc result after it has been
2691 passed back to Org instead of letting Calc already do the
2692 formatting@footnote{The @samp{printf} reformatting is limited in precision
2693 because the value passed to it is converted into an @samp{integer} or
2694 @samp{double}. The @samp{integer} is limited in size by truncating the
2695 signed value to 32 bits. The @samp{double} is limited in precision to 64
2696 bits overall which leaves approximately 16 significant decimal digits.}. A
2700 $1+$2 @r{Sum of first and second field}
2701 $1+$2;%.2f @r{Same, format result to two decimals}
2702 exp($2)+exp($1) @r{Math functions can be used}
2703 $0;%.1f @r{Reformat current cell to 1 decimal}
2704 ($3-32)*5/9 @r{Degrees F -> C conversion}
2705 $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
2706 tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
2707 sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
2708 taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree}
2711 Calc also contains a complete set of logical operations, (@pxref{Logical
2712 Operations, , Logical Operations, calc, GNU Emacs Calc Manual}). For example
2715 @item if($1 < 20, teen, string(""))
2716 "teen" if age $1 is less than 20, else the Org table result field is set to
2717 empty with the empty string.
2718 @item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1
2719 Sum of the first two columns. When at least one of the input fields is empty
2720 the Org table result field is set to empty. @samp{E} is required to not
2721 convert empty fields to 0. @samp{f-1} is an optional Calc format string
2722 similar to @samp{%.1f} but leaves empty results empty.
2723 @item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E
2724 Mean value of a range unless there is any empty field. Every field in the
2725 range that is empty is replaced by @samp{nan} which lets @samp{vmean} result
2726 in @samp{nan}. Then @samp{typeof == 12} detects the @samp{nan} from
2727 @samp{vmean} and the Org table result field is set to empty. Use this when
2728 the sample set is expected to never have missing values.
2729 @item if("$1..$7" == "[]", string(""), vmean($1..$7))
2730 Mean value of a range with empty fields skipped. Every field in the range
2731 that is empty is skipped. When all fields in the range are empty the mean
2732 value is not defined and the Org table result field is set to empty. Use
2733 this when the sample set can have a variable size.
2734 @item vmean($1..$7); EN
2735 To complete the example before: Mean value of a range with empty fields
2736 counting as samples with value 0. Use this only when incomplete sample sets
2737 should be padded with 0 to the full size.
2740 You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
2741 and use them in formula syntax for Calc.
2743 @node Formula syntax for Lisp
2744 @subsection Emacs Lisp forms as formulas
2745 @cindex Lisp forms, as table formulas
2747 It is also possible to write a formula in Emacs Lisp. This can be useful
2748 for string manipulation and control structures, if Calc's functionality is
2751 If a formula starts with an apostrophe followed by an opening parenthesis,
2752 then it is evaluated as a Lisp form. The evaluation should return either a
2753 string or a number. Just as with @file{calc} formulas, you can specify modes
2754 and a printf format after a semicolon.
2756 With Emacs Lisp forms, you need to be conscious about the way field
2757 references are interpolated into the form. By default, a reference will be
2758 interpolated as a Lisp string (in double-quotes) containing the field. If
2759 you provide the @samp{N} mode switch, all referenced elements will be numbers
2760 (non-number fields will be zero) and interpolated as Lisp numbers, without
2761 quotes. If you provide the @samp{L} flag, all fields will be interpolated
2762 literally, without quotes. I.e., if you want a reference to be interpreted
2763 as a string by the Lisp form, enclose the reference operator itself in
2764 double-quotes, like @code{"$3"}. Ranges are inserted as space-separated
2765 fields, so you can embed them in list or vector syntax.
2767 Here are a few examples---note how the @samp{N} mode is used when we do
2768 computations in Lisp:
2771 @item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
2772 Swap the first two characters of the content of column 1.
2774 Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
2775 @item '(apply '+ '($1..$4));N
2776 Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
2779 @node Durations and time values
2780 @subsection Durations and time values
2781 @cindex Duration, computing
2782 @cindex Time, computing
2783 @vindex org-table-duration-custom-format
2785 If you want to compute time values use the @code{T} flag, either in Calc
2786 formulas or Elisp formulas:
2790 | Task 1 | Task 2 | Total |
2791 |---------+----------+----------|
2792 | 2:12 | 1:47 | 03:59:00 |
2793 | 3:02:20 | -2:07:00 | 0.92 |
2794 #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;t
2798 Input duration values must be of the form @code{HH:MM[:SS]}, where seconds
2799 are optional. With the @code{T} flag, computed durations will be displayed
2800 as @code{HH:MM:SS} (see the first formula above). With the @code{t} flag,
2801 computed durations will be displayed according to the value of the option
2802 @code{org-table-duration-custom-format}, which defaults to @code{'hours} and
2803 will display the result as a fraction of hours (see the second formula in the
2806 Negative duration values can be manipulated as well, and integers will be
2807 considered as seconds in addition and subtraction.
2809 @node Field and range formulas
2810 @subsection Field and range formulas
2811 @cindex field formula
2812 @cindex range formula
2813 @cindex formula, for individual table field
2814 @cindex formula, for range of fields
2816 To assign a formula to a particular field, type it directly into the field,
2817 preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press
2818 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2819 the formula will be stored as the formula for this field, evaluated, and the
2820 current field will be replaced with the result.
2823 Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
2824 below the table. If you type the equation in the 4th field of the 3rd data
2825 line in the table, the formula will look like @samp{@@3$4=$1+$2}. When
2826 inserting/deleting/swapping columns and rows with the appropriate commands,
2827 @i{absolute references} (but not relative ones) in stored formulas are
2828 modified in order to still reference the same field. To avoid this, in
2829 particular in range references, anchor ranges at the table borders (using
2830 @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines using the
2831 @code{@@I} notation. Automatic adaptation of field references does of course
2832 not happen if you edit the table structure with normal editing
2833 commands---then you must fix the equations yourself.
2835 Instead of typing an equation into the field, you may also use the following
2839 @orgcmd{C-u C-c =,org-table-eval-formula}
2840 Install a new formula for the current field. The command prompts for a
2841 formula with default taken from the @samp{#+TBLFM:} line, applies
2842 it to the current field, and stores it.
2845 The left-hand side of a formula can also be a special expression in order to
2846 assign the formula to a number of different fields. There is no keyboard
2847 shortcut to enter such range formulas. To add them, use the formula editor
2848 (@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
2853 Column formula, valid for the entire column. This is so common that Org
2854 treats these formulas in a special way, see @ref{Column formulas}.
2856 Row formula, applies to all fields in the specified row. @code{@@>=} means
2859 Range formula, applies to all fields in the given rectangular range. This
2860 can also be used to assign a formula to some but not all fields in a row.
2862 Named field, see @ref{Advanced features}.
2865 @node Column formulas
2866 @subsection Column formulas
2867 @cindex column formula
2868 @cindex formula, for table column
2870 When you assign a formula to a simple column reference like @code{$3=}, the
2871 same formula will be used in all fields of that column, with the following
2872 very convenient exceptions: (i) If the table contains horizontal separator
2873 hlines with rows above and below, everything before the first such hline is
2874 considered part of the table @emph{header} and will not be modified by column
2875 formulas. Therefore a header is mandatory when you use column formulas and
2876 want to add hlines to group rows, like for example to separate a total row at
2877 the bottom from the summand rows above. (ii) Fields that already get a value
2878 from a field/range formula will be left alone by column formulas. These
2879 conditions make column formulas very easy to use.
2881 To assign a formula to a column, type it directly into any field in the
2882 column, preceded by an equal sign, like @samp{=$1+$2}. When you press
2883 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2884 the formula will be stored as the formula for the current column, evaluated
2885 and the current field replaced with the result. If the field contains only
2886 @samp{=}, the previously stored formula for this column is used. For each
2887 column, Org will only remember the most recently used formula. In the
2888 @samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The
2889 left-hand side of a column formula cannot be the name of column, it must be
2890 the numeric column reference or @code{$>}.
2892 Instead of typing an equation into the field, you may also use the
2896 @orgcmd{C-c =,org-table-eval-formula}
2897 Install a new formula for the current column and replace current field with
2898 the result of the formula. The command prompts for a formula, with default
2899 taken from the @samp{#+TBLFM} line, applies it to the current field and
2900 stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
2901 will apply it to that many consecutive fields in the current column.
2904 @node Lookup functions
2905 @subsection Lookup functions
2906 @cindex lookup functions in tables
2907 @cindex table lookup functions
2909 Org has three predefined Emacs Lisp functions for lookups in tables.
2911 @item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)
2912 @findex org-lookup-first
2913 Searches for the first element @code{S} in list @code{S-LIST} for which
2917 is @code{t}; returns the value from the corresponding position in list
2918 @code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the
2919 parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same
2920 order as the corresponding parameters are in the call to
2921 @code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If
2922 @code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST}
2924 @item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)
2925 @findex org-lookup-last
2926 Similar to @code{org-lookup-first} above, but searches for the @i{last}
2927 element for which @code{PREDICATE} is @code{t}.
2928 @item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)
2929 @findex org-lookup-all
2930 Similar to @code{org-lookup-first}, but searches for @i{all} elements for
2931 which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding
2932 values. This function can not be used by itself in a formula, because it
2933 returns a list of values. However, powerful lookups can be built when this
2934 function is combined with other Emacs Lisp functions.
2937 If the ranges used in these functions contain empty fields, the @code{E} mode
2938 for the formula should usually be specified: otherwise empty fields will not be
2939 included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result
2940 in an incorrect mapping from an element of @code{S-LIST} to the corresponding
2941 element of @code{R-LIST}.
2943 These three functions can be used to implement associative arrays, count
2944 matching cells, rank results, group data etc. For practical examples
2945 see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
2948 @node Editing and debugging formulas
2949 @subsection Editing and debugging formulas
2950 @cindex formula editing
2951 @cindex editing, of table formulas
2953 @vindex org-table-use-standard-references
2954 You can edit individual formulas in the minibuffer or directly in the field.
2955 Org can also prepare a special buffer with all active formulas of a table.
2956 When offering a formula for editing, Org converts references to the standard
2957 format (like @code{B3} or @code{D&}) if possible. If you prefer to only work
2958 with the internal format (like @code{@@3$2} or @code{$4}), configure the
2959 option @code{org-table-use-standard-references}.
2962 @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
2963 Edit the formula associated with the current column/field in the
2964 minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}.
2965 @orgcmd{C-u C-u C-c =,org-table-eval-formula}
2966 Re-insert the active formula (either a
2967 field formula, or a column formula) into the current field, so that you
2968 can edit it directly in the field. The advantage over editing in the
2969 minibuffer is that you can use the command @kbd{C-c ?}.
2970 @orgcmd{C-c ?,org-table-field-info}
2971 While editing a formula in a table field, highlight the field(s)
2972 referenced by the reference at the cursor position in the formula.
2974 @findex org-table-toggle-coordinate-overlays
2976 Toggle the display of row and column numbers for a table, using overlays
2977 (@command{org-table-toggle-coordinate-overlays}). These are updated each
2978 time the table is aligned; you can force it with @kbd{C-c C-c}.
2980 @findex org-table-toggle-formula-debugger
2982 Toggle the formula debugger on and off
2983 (@command{org-table-toggle-formula-debugger}). See below.
2984 @orgcmd{C-c ',org-table-edit-formulas}
2985 Edit all formulas for the current table in a special buffer, where the
2986 formulas will be displayed one per line. If the current field has an
2987 active formula, the cursor in the formula editor will mark it.
2988 While inside the special buffer, Org will automatically highlight
2989 any field or range reference at the cursor position. You may edit,
2990 remove and add formulas, and use the following commands:
2993 @orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
2994 Exit the formula editor and store the modified formulas. With @kbd{C-u}
2995 prefix, also apply the new formulas to the entire table.
2996 @orgcmd{C-c C-q,org-table-fedit-abort}
2997 Exit the formula editor without installing changes.
2998 @orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
2999 Toggle all references in the formula editor between standard (like
3000 @code{B3}) and internal (like @code{@@3$2}).
3001 @orgcmd{@key{TAB},org-table-fedit-lisp-indent}
3002 Pretty-print or indent Lisp formula at point. When in a line containing
3003 a Lisp formula, format the formula according to Emacs Lisp rules.
3004 Another @key{TAB} collapses the formula back again. In the open
3005 formula, @key{TAB} re-indents just like in Emacs Lisp mode.
3006 @orgcmd{M-@key{TAB},lisp-complete-symbol}
3007 Complete Lisp symbols, just like in Emacs Lisp mode.@footnote{Many desktops
3008 intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
3009 @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}
3011 @kindex S-@key{down}
3012 @kindex S-@key{left}
3013 @kindex S-@key{right}
3014 @findex org-table-fedit-ref-up
3015 @findex org-table-fedit-ref-down
3016 @findex org-table-fedit-ref-left
3017 @findex org-table-fedit-ref-right
3018 @item S-@key{up}/@key{down}/@key{left}/@key{right}
3019 Shift the reference at point. For example, if the reference is
3020 @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
3021 This also works for relative references and for hline references.
3022 @orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
3023 Move the test line for column formulas in the Org buffer up and
3025 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
3026 Scroll the window displaying the table.
3028 @findex org-table-toggle-coordinate-overlays
3030 Turn the coordinate grid in the table on and off.
3034 Making a table field blank does not remove the formula associated with
3035 the field, because that is stored in a different line (the @samp{#+TBLFM}
3036 line)---during the next recalculation the field will be filled again.
3037 To remove a formula from a field, you have to give an empty reply when
3038 prompted for the formula, or to edit the @samp{#+TBLFM} line.
3041 You may edit the @samp{#+TBLFM} directly and re-apply the changed
3042 equations with @kbd{C-c C-c} in that line or with the normal
3043 recalculation commands in the table.
3045 @anchor{Using multiple #+TBLFM lines}
3046 @subsubheading Using multiple #+TBLFM lines
3047 @cindex #+TBLFM line, multiple
3049 @cindex #+TBLFM, switching
3052 You may apply the formula temporarily. This is useful when you
3053 switch the formula. Place multiple @samp{#+TBLFM} lines right
3054 after the table, and then press @kbd{C-c C-c} on the formula to
3055 apply. Here is an example:
3067 Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
3079 Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
3080 will get the following result of applying only the first @samp{#+TBLFM} line.
3091 @subsubheading Debugging formulas
3092 @cindex formula debugging
3093 @cindex debugging, of table formulas
3094 When the evaluation of a formula leads to an error, the field content
3095 becomes the string @samp{#ERROR}. If you would like see what is going
3096 on during variable substitution and calculation in order to find a bug,
3097 turn on formula debugging in the @code{Tbl} menu and repeat the
3098 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
3099 field. Detailed information will be displayed.
3101 @node Updating the table
3102 @subsection Updating the table
3103 @cindex recomputing table fields
3104 @cindex updating, table
3106 Recalculation of a table is normally not automatic, but needs to be
3107 triggered by a command. See @ref{Advanced features}, for a way to make
3108 recalculation at least semi-automatic.
3110 In order to recalculate a line of a table or the entire table, use the
3114 @orgcmd{C-c *,org-table-recalculate}
3115 Recalculate the current row by first applying the stored column formulas
3116 from left to right, and all field/range formulas in the current row.
3122 Recompute the entire table, line by line. Any lines before the first
3123 hline are left alone, assuming that these are part of the table header.
3125 @orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
3126 Iterate the table by recomputing it until no further changes occur.
3127 This may be necessary if some computed fields use the value of other
3128 fields that are computed @i{later} in the calculation sequence.
3129 @item M-x org-table-recalculate-buffer-tables RET
3130 @findex org-table-recalculate-buffer-tables
3131 Recompute all tables in the current buffer.
3132 @item M-x org-table-iterate-buffer-tables RET
3133 @findex org-table-iterate-buffer-tables
3134 Iterate all tables in the current buffer, in order to converge table-to-table
3138 @node Advanced features
3139 @subsection Advanced features
3141 If you want the recalculation of fields to happen automatically, or if you
3142 want to be able to assign @i{names}@footnote{Such names must start by an
3143 alphabetic character and use only alphanumeric/underscore characters.} to
3144 fields and columns, you need to reserve the first column of the table for
3145 special marking characters.
3148 @orgcmd{C-#,org-table-rotate-recalc-marks}
3149 Rotate the calculation mark in first column through the states @samp{ },
3150 @samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,
3151 change all marks in the region.
3154 Here is an example of a table that collects exam results of students and
3155 makes use of these features:
3159 |---+---------+--------+--------+--------+-------+------|
3160 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
3161 |---+---------+--------+--------+--------+-------+------|
3162 | ! | | P1 | P2 | P3 | Tot | |
3163 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
3164 | ^ | | m1 | m2 | m3 | mt | |
3165 |---+---------+--------+--------+--------+-------+------|
3166 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
3167 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
3168 |---+---------+--------+--------+--------+-------+------|
3169 | | Average | | | | 25.0 | |
3170 | ^ | | | | | at | |
3171 | $ | max=50 | | | | | |
3172 |---+---------+--------+--------+--------+-------+------|
3173 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
3177 @noindent @b{Important}: please note that for these special tables,
3178 recalculating the table with @kbd{C-u C-c *} will only affect rows that
3179 are marked @samp{#} or @samp{*}, and fields that have a formula assigned
3180 to the field itself. The column formulas are not applied in rows with
3183 @cindex marking characters, tables
3184 The marking characters have the following meaning:
3188 The fields in this line define names for the columns, so that you may
3189 refer to a column as @samp{$Tot} instead of @samp{$6}.
3191 This row defines names for the fields @emph{above} the row. With such
3192 a definition, any formula in the table may use @samp{$m1} to refer to
3193 the value @samp{10}. Also, if you assign a formula to a names field, it
3194 will be stored as @samp{$name=...}.
3196 Similar to @samp{^}, but defines names for the fields in the row
3199 Fields in this row can define @emph{parameters} for formulas. For
3200 example, if a field in a @samp{$} row contains @samp{max=50}, then
3201 formulas in this table can refer to the value 50 using @samp{$max}.
3202 Parameters work exactly like constants, only that they can be defined on
3205 Fields in this row are automatically recalculated when pressing
3206 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
3207 is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
3208 lines will be left alone by this command.
3210 Selects this line for global recalculation with @kbd{C-u C-c *}, but
3211 not for automatic recalculation. Use this when automatic
3212 recalculation slows down editing too much.
3214 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
3215 All lines that should be recalculated should be marked with @samp{#}
3218 Do not export this line. Useful for lines that contain the narrowing
3219 @samp{<N>} markers or column group markers.
3222 Finally, just to whet your appetite for what can be done with the
3223 fantastic @file{calc.el} package, here is a table that computes the Taylor
3224 series of degree @code{n} at location @code{x} for a couple of
3229 |---+-------------+---+-----+--------------------------------------|
3230 | | Func | n | x | Result |
3231 |---+-------------+---+-----+--------------------------------------|
3232 | # | exp(x) | 1 | x | 1 + x |
3233 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
3234 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
3235 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
3236 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
3237 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
3238 |---+-------------+---+-----+--------------------------------------|
3239 #+TBLFM: $5=taylor($2,$4,$3);n3
3245 @cindex graph, in tables
3246 @cindex plot tables using Gnuplot
3249 Org-Plot can produce graphs of information stored in org tables, either
3250 graphically or in ASCII-art.
3252 @subheading Graphical plots using @file{Gnuplot}
3254 Org-Plot produces 2D and 3D graphs using @file{Gnuplot}
3255 @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
3256 @uref{http://xafs.org/BruceRavel/GnuplotMode}. To see this in action, ensure
3257 that you have both Gnuplot and Gnuplot mode installed on your system, then
3258 call @kbd{C-c " g} or @kbd{M-x org-plot/gnuplot @key{RET}} on the following
3263 #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
3264 | Sede | Max cites | H-index |
3265 |-----------+-----------+---------|
3266 | Chile | 257.72 | 21.39 |
3267 | Leeds | 165.77 | 19.68 |
3268 | Sao Paolo | 71.00 | 11.50 |
3269 | Stockholm | 134.19 | 14.33 |
3270 | Morelia | 257.56 | 17.67 |
3274 Notice that Org Plot is smart enough to apply the table's headers as labels.
3275 Further control over the labels, type, content, and appearance of plots can
3276 be exercised through the @code{#+PLOT:} lines preceding a table. See below
3277 for a complete list of Org-plot options. The @code{#+PLOT:} lines are
3278 optional. For more information and examples see the Org-plot tutorial at
3279 @uref{http://orgmode.org/worg/org-tutorials/org-plot.html}.
3281 @subsubheading Plot Options
3285 Specify any @command{gnuplot} option to be set when graphing.
3288 Specify the title of the plot.
3291 Specify which column of the table to use as the @code{x} axis.
3294 Specify the columns to graph as a Lisp style list, surrounded by parentheses
3295 and separated by spaces for example @code{dep:(3 4)} to graph the third and
3296 fourth columns (defaults to graphing all other columns aside from the @code{ind}
3300 Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
3303 Specify a @code{with} option to be inserted for every col being plotted
3304 (e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
3305 Defaults to @code{lines}.
3308 If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
3311 List of labels to be used for the @code{deps} (defaults to the column headers
3315 Specify an entire line to be inserted in the Gnuplot script.
3318 When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
3319 flat mapping rather than a @code{3d} slope.
3322 Specify format of Org mode timestamps as they will be parsed by Gnuplot.
3323 Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
3326 If you want total control, you can specify a script file (place the file name
3327 between double-quotes) which will be used to plot. Before plotting, every
3328 instance of @code{$datafile} in the specified script will be replaced with
3329 the path to the generated data file. Note: even if you set this option, you
3330 may still want to specify the plot type, as that can impact the content of
3334 @subheading ASCII bar plots
3336 While the cursor is on a column, typing @kbd{C-c " a} or
3337 @kbd{M-x orgtbl-ascii-plot @key{RET}} create a new column containing an
3338 ASCII-art bars plot. The plot is implemented through a regular column
3339 formula. When the source column changes, the bar plot may be updated by
3340 refreshing the table, for example typing @kbd{C-u C-c *}.
3344 | Sede | Max cites | |
3345 |---------------+-----------+--------------|
3346 | Chile | 257.72 | WWWWWWWWWWWW |
3347 | Leeds | 165.77 | WWWWWWWh |
3348 | Sao Paolo | 71.00 | WWW; |
3349 | Stockholm | 134.19 | WWWWWW: |
3350 | Morelia | 257.56 | WWWWWWWWWWWH |
3351 | Rochefourchat | 0.00 | |
3352 #+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12)
3356 The formula is an elisp call:
3358 (orgtbl-ascii-draw COLUMN MIN MAX WIDTH)
3363 is a reference to the source column.
3366 are the minimal and maximal values displayed. Sources values
3367 outside this range are displayed as @samp{too small}
3368 or @samp{too large}.
3371 is the width in characters of the bar-plot. It defaults to @samp{12}.
3379 Like HTML, Org provides links inside a file, external links to
3380 other files, Usenet articles, emails, and much more.
3383 * Link format:: How links in Org are formatted
3384 * Internal links:: Links to other places in the current file
3385 * External links:: URL-like links to the world
3386 * Handling links:: Creating, inserting and following
3387 * Using links outside Org:: Linking from my C source code?
3388 * Link abbreviations:: Shortcuts for writing complex links
3389 * Search options:: Linking to a specific location
3390 * Custom searches:: When the default search is not enough
3394 @section Link format
3396 @cindex format, of links
3398 Org will recognize plain URL-like links and activate them as
3399 clickable links. The general link format, however, looks like this:
3402 [[link][description]] @r{or alternatively} [[link]]
3406 Once a link in the buffer is complete (all brackets present), Org
3407 will change the display so that @samp{description} is displayed instead
3408 of @samp{[[link][description]]} and @samp{link} is displayed instead of
3409 @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
3410 which by default is an underlined face. You can directly edit the
3411 visible part of a link. Note that this can be either the @samp{link}
3412 part (if there is no description) or the @samp{description} part. To
3413 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
3416 If you place the cursor at the beginning or just behind the end of the
3417 displayed text and press @key{BACKSPACE}, you will remove the
3418 (invisible) bracket at that location. This makes the link incomplete
3419 and the internals are again displayed as plain text. Inserting the
3420 missing bracket hides the link internals again. To show the
3421 internal structure of all links, use the menu entry
3422 @code{Org->Hyperlinks->Literal links}.
3424 @node Internal links
3425 @section Internal links
3426 @cindex internal links
3427 @cindex links, internal
3428 @cindex targets, for links
3430 @cindex property, CUSTOM_ID
3431 If the link does not look like a URL, it is considered to be internal in the
3432 current file. The most important case is a link like
3433 @samp{[[#my-custom-id]]} which will link to the entry with the
3434 @code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself
3435 to make sure these custom IDs are unique in a file.
3437 Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
3438 lead to a text search in the current file.
3440 The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
3441 or with a mouse click (@pxref{Handling links}). Links to custom IDs will
3442 point to the corresponding headline. The preferred match for a text link is
3443 a @i{dedicated target}: the same string in double angular brackets, like
3444 @samp{<<My Target>>}.
3447 If no dedicated target exists, the link will then try to match the exact name
3448 of an element within the buffer. Naming is done with the @code{#+NAME}
3449 keyword, which has to be put in the line before the element it refers to, as
3450 in the following example
3459 If none of the above succeeds, Org will search for a headline that is exactly
3460 the link text but may also include a TODO keyword and tags@footnote{To insert
3461 a link targeting a headline, in-buffer completion can be used. Just type
3462 a star followed by a few optional letters into the buffer and press
3463 @kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as
3466 During export, internal links will be used to mark objects and assign them
3467 a number. Marked objects will then be referenced by links pointing to them.
3468 In particular, links without a description will appear as the number assigned
3469 to the marked object@footnote{When targeting a @code{#+NAME} keyword,
3470 @code{#+CAPTION} keyword is mandatory in order to get proper numbering
3471 (@pxref{Images and tables}).}. In the following excerpt from an Org buffer
3475 - <<target>>another item
3476 Here we refer to item [[target]].
3480 The last sentence will appear as @samp{Here we refer to item 2} when
3483 In non-Org files, the search will look for the words in the link text. In
3484 the above example the search would be for @samp{my target}.
3486 Following a link pushes a mark onto Org's own mark ring. You can
3487 return to the previous position with @kbd{C-c &}. Using this command
3488 several times in direct succession goes back to positions recorded
3492 * Radio targets:: Make targets trigger links in plain text
3496 @subsection Radio targets
3497 @cindex radio targets
3498 @cindex targets, radio
3499 @cindex links, radio targets
3501 Org can automatically turn any occurrences of certain target names
3502 in normal text into a link. So without explicitly creating a link, the
3503 text connects to the target radioing its position. Radio targets are
3504 enclosed by triple angular brackets. For example, a target @samp{<<<My
3505 Target>>>} causes each occurrence of @samp{my target} in normal text to
3506 become activated as a link. The Org file is scanned automatically
3507 for radio targets only when the file is first loaded into Emacs. To
3508 update the target list during editing, press @kbd{C-c C-c} with the
3509 cursor on or at a target.
3511 @node External links
3512 @section External links
3513 @cindex links, external
3514 @cindex external links
3522 @cindex USENET links
3527 Org supports links to files, websites, Usenet and email messages, BBDB
3528 database entries and links to both IRC conversations and their logs.
3529 External links are URL-like locators. They start with a short identifying
3530 string followed by a colon. There can be no space after the colon. The
3531 following list shows examples for each link type.
3534 http://www.astro.uva.nl/~dominik @r{on the web}
3535 doi:10.1000/182 @r{DOI for an electronic resource}
3536 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
3537 /home/dominik/images/jupiter.jpg @r{same as above}
3538 file:papers/last.pdf @r{file, relative path}
3539 ./papers/last.pdf @r{same as above}
3540 file:/ssh:myself@@some.where:papers/last.pdf @r{file, path on remote machine}
3541 /ssh:myself@@some.where:papers/last.pdf @r{same as above}
3542 file:sometextfile::NNN @r{file, jump to line number}
3543 file:projects.org @r{another Org file}
3544 file:projects.org::some words @r{text search in Org file}@footnote{
3545 The actual behavior of the search will depend on the value of
3546 the option @code{org-link-search-must-match-exact-headline}. If its value
3547 is @code{nil}, then a fuzzy text search will be done. If it is t, then only
3548 the exact headline will be matched, ignoring spaces and cookies. If the
3549 value is @code{query-to-create}, then an exact headline will be searched; if
3550 it is not found, then the user will be queried to create it.}
3551 file:projects.org::*task title @r{heading search in Org file}@footnote{
3552 Headline searches always match the exact headline, ignoring
3553 spaces and cookies. If the headline is not found and the value of the option
3554 @code{org-link-search-must-match-exact-headline} is @code{query-to-create},
3555 then the user will be queried to create it.}
3556 docview:papers/last.pdf::NNN @r{open in doc-view mode at page}
3557 id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
3558 news:comp.emacs @r{Usenet link}
3559 mailto:adent@@galaxy.net @r{Mail link}
3560 mhe:folder @r{MH-E folder link}
3561 mhe:folder#id @r{MH-E message link}
3562 rmail:folder @r{RMAIL folder link}
3563 rmail:folder#id @r{RMAIL message link}
3564 gnus:group @r{Gnus group link}
3565 gnus:group#id @r{Gnus article link}
3566 bbdb:R.*Stallman @r{BBDB link (with regexp)}
3567 irc:/irc.com/#emacs/bob @r{IRC link}
3568 info:org#External links @r{Info node or index link}
3569 shell:ls *.org @r{A shell command}
3570 elisp:org-agenda @r{Interactive Elisp command}
3571 elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
3575 @cindex WANDERLUST links
3576 On top of these built-in link types, some are available through the
3577 @code{contrib/} directory (@pxref{Installation}). For example, these links
3578 to VM or Wanderlust messages are available when you load the corresponding
3579 libraries from the @code{contrib/} directory:
3582 vm:folder @r{VM folder link}
3583 vm:folder#id @r{VM message link}
3584 vm://myself@@some.where.org/folder#id @r{VM on remote machine}
3585 vm-imap:account:folder @r{VM IMAP folder link}
3586 vm-imap:account:folder#id @r{VM IMAP message link}
3587 wl:folder @r{WANDERLUST folder link}
3588 wl:folder#id @r{WANDERLUST message link}
3591 For customizing Org to add new link types @ref{Adding hyperlink types}.
3593 A link should be enclosed in double brackets and may contain a descriptive
3594 text to be displayed instead of the URL (@pxref{Link format}), for example:
3597 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
3601 If the description is a file name or URL that points to an image, HTML
3602 export (@pxref{HTML export}) will inline the image as a clickable
3603 button. If there is no description at all and the link points to an
3605 that image will be inlined into the exported HTML file.
3607 @cindex square brackets, around links
3608 @cindex plain text external links
3609 Org also finds external links in the normal text and activates them
3610 as links. If spaces must be part of the link (for example in
3611 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
3612 about the end of the link, enclose them in square brackets.
3614 @node Handling links
3615 @section Handling links
3616 @cindex links, handling
3618 Org provides methods to create a link in the correct syntax, to
3619 insert it into an Org file, and to follow the link.
3622 @orgcmd{C-c l,org-store-link}
3623 @cindex storing links
3624 Store a link to the current location. This is a @emph{global} command (you
3625 must create the key binding yourself) which can be used in any buffer to
3626 create a link. The link will be stored for later insertion into an Org
3627 buffer (see below). What kind of link will be created depends on the current
3630 @b{Org mode buffers}@*
3631 For Org files, if there is a @samp{<<target>>} at the cursor, the link points
3632 to the target. Otherwise it points to the current headline, which will also
3633 be the description@footnote{If the headline contains a timestamp, it will be
3634 removed from the link and result in a wrong link---you should avoid putting
3635 timestamp in the headline.}.
3637 @vindex org-id-link-to-org-use-id
3638 @cindex property, CUSTOM_ID
3639 @cindex property, ID
3640 If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
3641 will be stored. In addition or alternatively (depending on the value of
3642 @code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
3643 be created and/or used to construct a link@footnote{The library
3644 @file{org-id.el} must first be loaded, either through @code{org-customize} by
3645 enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
3646 'org-id)} in your Emacs init file.}. So using this command in Org buffers
3647 will potentially create two links: a human-readable from the custom ID, and
3648 one that is globally unique and works even if the entry is moved from file to
3649 file. Later, when inserting the link, you need to decide which one to use.
3651 @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
3652 Pretty much all Emacs mail clients are supported. The link will point to the
3653 current article, or, in some GNUS buffers, to the group. The description is
3654 constructed from the author and the subject.
3656 @b{Web browsers: Eww, W3 and W3M}@*
3657 Here the link will be the current URL, with the page title as description.
3659 @b{Contacts: BBDB}@*
3660 Links created in a BBDB buffer will point to the current entry.
3663 @vindex org-irc-link-to-logs
3664 For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t},
3665 a @samp{file:/} style link to the relevant point in the logs for the current
3666 conversation is created. Otherwise an @samp{irc:/} style link to the
3667 user/channel/server under the point will be stored.
3670 For any other files, the link will point to the file, with a search string
3671 (@pxref{Search options}) pointing to the contents of the current line. If
3672 there is an active region, the selected words will form the basis of the
3673 search string. If the automatically created link is not working correctly or
3674 accurately enough, you can write custom functions to select the search string
3675 and to do the search for particular file types---see @ref{Custom searches}.
3676 The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
3679 When the cursor is in an agenda view, the created link points to the
3680 entry referenced by the current line.
3683 @orgcmd{C-c C-l,org-insert-link}
3684 @cindex link completion
3685 @cindex completion, of links
3686 @cindex inserting links
3687 @vindex org-keep-stored-link-after-insertion
3688 @vindex org-link-parameters
3689 Insert a link@footnote{Note that you don't have to use this command to
3690 insert a link. Links in Org are plain text, and you can type or paste them
3691 straight into the buffer. By using this command, the links are automatically
3692 enclosed in double brackets, and you will be asked for the optional
3693 descriptive text.}. This prompts for a link to be inserted into the buffer.
3694 You can just type a link, using text for an internal link, or one of the link
3695 type prefixes mentioned in the examples above. The link will be inserted
3696 into the buffer@footnote{After insertion of a stored link, the link will be
3697 removed from the list of stored links. To keep it in the list later use, use
3698 a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
3699 @code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
3700 If some text was selected when this command is called, the selected text
3701 becomes the default description.
3703 @b{Inserting stored links}@*
3704 All links stored during the
3705 current session are part of the history for this prompt, so you can access
3706 them with @key{up} and @key{down} (or @kbd{M-p/n}).
3708 @b{Completion support}@* Completion with @key{TAB} will help you to insert
3709 valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes
3710 defined through link abbreviations (@pxref{Link abbreviations}). If you
3711 press @key{RET} after inserting only the @var{prefix}, Org will offer
3712 specific completion support for some link types@footnote{This works if
3713 a completion function is defined in the @samp{:complete} property of a link
3714 in @code{org-link-parameters}.} For example, if you type @kbd{file
3715 @key{RET}}, file name completion (alternative access: @kbd{C-u C-c C-l}, see
3716 below) will be offered, and after @kbd{bbdb @key{RET}} you can complete
3719 @cindex file name completion
3720 @cindex completion, of file names
3721 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
3722 a file will be inserted and you may use file name completion to select
3723 the name of the file. The path to the file is inserted relative to the
3724 directory of the current Org file, if the linked file is in the current
3725 directory or in a sub-directory of it, or if the path is written relative
3726 to the current directory using @samp{../}. Otherwise an absolute path
3727 is used, if possible with @samp{~/} for your home directory. You can
3728 force an absolute path with two @kbd{C-u} prefixes.
3730 @item C-c C-l @ @r{(with cursor on existing link)}
3731 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
3732 link and description parts of the link.
3734 @cindex following links
3735 @orgcmd{C-c C-o,org-open-at-point}
3736 @vindex org-file-apps
3737 @vindex org-link-frame-setup
3738 Open link at point. This will launch a web browser for URLs (using
3739 @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
3740 the corresponding links, and execute the command in a shell link. When the
3741 cursor is on an internal link, this command runs the corresponding search.
3742 When the cursor is on a TAG list in a headline, it creates the corresponding
3743 TAGS view. If the cursor is on a timestamp, it compiles the agenda for that
3744 date. Furthermore, it will visit text and remote files in @samp{file:} links
3745 with Emacs and select a suitable application for local non-text files.
3746 Classification of files is based on file extension only. See option
3747 @code{org-file-apps}. If you want to override the default application and
3748 visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
3749 opening in Emacs, use a @kbd{C-u C-u} prefix.@*
3750 If the cursor is on a headline, but not on a link, offer all links in the
3751 headline and entry text. If you want to setup the frame configuration for
3752 following links, customize @code{org-link-frame-setup}.
3755 @vindex org-return-follows-link
3756 When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
3763 On links, @kbd{mouse-1} and @kbd{mouse-2} will open the link just as @kbd{C-c
3768 @vindex org-display-internal-link-with-indirect-buffer
3769 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
3770 internal links to be displayed in another window@footnote{See the
3771 option @code{org-display-internal-link-with-indirect-buffer}}.
3773 @orgcmd{C-c C-x C-v,org-toggle-inline-images}
3774 @cindex inlining images
3775 @cindex images, inlining
3776 @vindex org-startup-with-inline-images
3777 @cindex @code{inlineimages}, STARTUP keyword
3778 @cindex @code{noinlineimages}, STARTUP keyword
3779 Toggle the inline display of linked images. Normally this will only inline
3780 images that have no description part in the link, i.e., images that will also
3781 be inlined during export. When called with a prefix argument, also display
3782 images that do have a link description. You can ask for inline images to be
3783 displayed at startup by configuring the variable
3784 @code{org-startup-with-inline-images}@footnote{with corresponding
3785 @code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
3786 @orgcmd{C-c %,org-mark-ring-push}
3788 Push the current position onto the mark ring, to be able to return
3789 easily. Commands following an internal link do this automatically.
3791 @orgcmd{C-c &,org-mark-ring-goto}
3792 @cindex links, returning to
3793 Jump back to a recorded position. A position is recorded by the
3794 commands following internal links, and by @kbd{C-c %}. Using this
3795 command several times in direct succession moves through a ring of
3796 previously recorded positions.
3798 @orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
3799 @cindex links, finding next/previous
3800 Move forward/backward to the next link in the buffer. At the limit of
3801 the buffer, the search fails once, and then wraps around. The key
3802 bindings for this are really too long; you might want to bind this also
3803 to @kbd{C-n} and @kbd{C-p}
3805 (add-hook 'org-load-hook
3807 (define-key org-mode-map "\C-n" 'org-next-link)
3808 (define-key org-mode-map "\C-p" 'org-previous-link)))
3812 @node Using links outside Org
3813 @section Using links outside Org
3815 You can insert and follow links that have Org syntax not only in
3816 Org, but in any Emacs buffer. For this, you should create two
3817 global commands, like this (please select suitable global keys
3821 (global-set-key "\C-c L" 'org-insert-link-global)
3822 (global-set-key "\C-c o" 'org-open-at-point-global)
3825 @node Link abbreviations
3826 @section Link abbreviations
3827 @cindex link abbreviations
3828 @cindex abbreviation, links
3830 Long URLs can be cumbersome to type, and often many similar links are
3831 needed in a document. For this you can use link abbreviations. An
3832 abbreviated link looks like this
3835 [[linkword:tag][description]]
3839 @vindex org-link-abbrev-alist
3840 where the tag is optional.
3841 The @i{linkword} must be a word, starting with a letter, followed by
3842 letters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolved
3843 according to the information in the variable @code{org-link-abbrev-alist}
3844 that relates the linkwords to replacement text. Here is an example:
3848 (setq org-link-abbrev-alist
3849 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
3850 ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
3851 ("google" . "http://www.google.com/search?q=")
3852 ("gmap" . "http://maps.google.com/maps?q=%s")
3853 ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
3854 ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
3858 If the replacement text contains the string @samp{%s}, it will be
3859 replaced with the tag. Using @samp{%h} instead of @samp{%s} will
3860 url-encode the tag (see the example above, where we need to encode
3861 the URL parameter.) Using @samp{%(my-function)} will pass the tag
3862 to a custom function, and replace it by the resulting string.
3864 If the replacement text doesn't contain any specifier, the tag will simply be
3865 appended in order to create the link.
3867 Instead of a string, you may also specify a function that will be
3868 called with the tag as the only argument to create the link.
3870 With the above setting, you could link to a specific bug with
3871 @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
3872 @code{[[google:OrgMode]]}, show the map location of the Free Software
3873 Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
3874 @code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
3875 what the Org author is doing besides Emacs hacking with
3876 @code{[[ads:Dominik,C]]}.
3878 If you need special abbreviations just for a single Org buffer, you
3879 can define them in the file with
3883 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
3884 #+LINK: google http://www.google.com/search?q=%s
3888 In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
3889 complete link abbreviations. You may also define a function that implements
3890 special (e.g., completion) support for inserting such a link with @kbd{C-c
3891 C-l}. Such a function should not accept any arguments, and return the full
3892 link with prefix. You can add a completion function to a link like this:
3895 (org-link-set-parameters ``type'' :complete #'some-function)
3899 @node Search options
3900 @section Search options in file links
3901 @cindex search option in file links
3902 @cindex file links, searching
3904 File links can contain additional information to make Emacs jump to a
3905 particular location in the file when following a link. This can be a
3906 line number or a search option after a double@footnote{For backward
3907 compatibility, line numbers can also follow a single colon.} colon. For
3908 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
3909 links}) to a file, it encodes the words in the current line as a search
3910 string that can be used to find this line back later when following the
3911 link with @kbd{C-c C-o}.
3913 Here is the syntax of the different ways to attach a search to a file
3914 link, together with an explanation:
3917 [[file:~/code/main.c::255]]
3918 [[file:~/xx.org::My Target]]
3919 [[file:~/xx.org::*My Target]]
3920 [[file:~/xx.org::#my-custom-id]]
3921 [[file:~/xx.org::/regexp/]]
3928 Search for a link target @samp{<<My Target>>}, or do a text search for
3929 @samp{my target}, similar to the search in internal links, see
3930 @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
3931 link will become an HTML reference to the corresponding named anchor in
3934 In an Org file, restrict search to headlines.
3936 Link to a heading with a @code{CUSTOM_ID} property
3938 Do a regular expression search for @code{regexp}. This uses the Emacs
3939 command @code{occur} to list all matches in a separate window. If the
3940 target file is in Org mode, @code{org-occur} is used to create a
3941 sparse tree with the matches.
3942 @c If the target file is a directory,
3943 @c @code{grep} will be used to search all files in the directory.
3946 As a degenerate case, a file link with an empty file name can be used
3947 to search the current file. For example, @code{[[file:::find me]]} does
3948 a search for @samp{find me} in the current file, just as
3949 @samp{[[find me]]} would.
3951 @node Custom searches
3952 @section Custom Searches
3953 @cindex custom search strings
3954 @cindex search strings, custom
3956 The default mechanism for creating search strings and for doing the
3957 actual search related to a file link may not work correctly in all
3958 cases. For example, Bib@TeX{} database files have many entries like
3959 @samp{year="1993"} which would not result in good search strings,
3960 because the only unique identification for a Bib@TeX{} entry is the
3963 @vindex org-create-file-search-functions
3964 @vindex org-execute-file-search-functions
3965 If you come across such a problem, you can write custom functions to set
3966 the right search string for a particular file type, and to do the search
3967 for the string in the file. Using @code{add-hook}, these functions need
3968 to be added to the hook variables
3969 @code{org-create-file-search-functions} and
3970 @code{org-execute-file-search-functions}. See the docstring for these
3971 variables for more information. Org actually uses this mechanism
3972 for Bib@TeX{} database files, and you can use the corresponding code as
3973 an implementation example. See the file @file{org-bibtex.el}.
3979 Org mode does not maintain TODO lists as separate documents@footnote{Of
3980 course, you can make a document that contains only long lists of TODO items,
3981 but this is not required.}. Instead, TODO items are an integral part of the
3982 notes file, because TODO items usually come up while taking notes! With Org
3983 mode, simply mark any entry in a tree as being a TODO item. In this way,
3984 information is not duplicated, and the entire context from which the TODO
3985 item emerged is always present.
3987 Of course, this technique for managing TODO items scatters them
3988 throughout your notes file. Org mode compensates for this by providing
3989 methods to give you an overview of all the things that you have to do.
3992 * TODO basics:: Marking and displaying TODO entries
3993 * TODO extensions:: Workflow and assignments
3994 * Progress logging:: Dates and notes for progress
3995 * Priorities:: Some things are more important than others
3996 * Breaking down tasks:: Splitting a task into manageable pieces
3997 * Checkboxes:: Tick-off lists
4001 @section Basic TODO functionality
4003 Any headline becomes a TODO item when it starts with the word
4004 @samp{TODO}, for example:
4007 *** TODO Write letter to Sam Fortune
4011 The most important commands to work with TODO entries are:
4014 @orgcmd{C-c C-t,org-todo}
4015 @cindex cycling, of TODO states
4016 @vindex org-use-fast-todo-selection
4018 Rotate the TODO state of the current item among
4021 ,-> (unmarked) -> TODO -> DONE --.
4022 '--------------------------------'
4025 If TODO keywords have fast access keys (see @ref{Fast access to TODO
4026 states}), you will be prompted for a TODO keyword through the fast selection
4027 interface; this is the default behavior when
4028 @code{org-use-fast-todo-selection} is non-@code{nil}.
4030 The same rotation can also be done ``remotely'' from the timeline and agenda
4031 buffers with the @kbd{t} command key (@pxref{Agenda commands}).
4033 @orgkey{C-u C-c C-t}
4034 When TODO keywords have no selection keys, select a specific keyword using
4035 completion; otherwise force cycling through TODO states with no prompt. When
4036 @code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
4037 selection interface.
4039 @kindex S-@key{right}
4040 @kindex S-@key{left}
4041 @item S-@key{right} @ @r{/} @ S-@key{left}
4042 @vindex org-treat-S-cursor-todo-selection-as-state-change
4043 Select the following/preceding TODO state, similar to cycling. Useful
4044 mostly if more than two TODO states are possible (@pxref{TODO
4045 extensions}). See also @ref{Conflicts}, for a discussion of the interaction
4046 with @code{shift-selection-mode}. See also the variable
4047 @code{org-treat-S-cursor-todo-selection-as-state-change}.
4048 @orgcmd{C-c / t,org-show-todo-tree}
4049 @cindex sparse tree, for TODO
4050 @vindex org-todo-keywords
4051 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
4052 entire buffer, but shows all TODO items (with not-DONE state) and the
4053 headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
4054 / T}), search for a specific TODO@. You will be prompted for the keyword,
4055 and you can also give a list of keywords like @code{KWD1|KWD2|...} to list
4056 entries that match any one of these keywords. With a numeric prefix argument
4057 N, show the tree for the Nth keyword in the option @code{org-todo-keywords}.
4058 With two prefix arguments, find all TODO states, both un-done and done.
4059 @orgcmd{C-c a t,org-todo-list}
4060 Show the global TODO list. Collects the TODO items (with not-DONE states)
4061 from all agenda files (@pxref{Agenda views}) into a single buffer. The new
4062 buffer will be in @code{agenda-mode}, which provides commands to examine and
4063 manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
4064 @xref{Global TODO list}, for more information.
4065 @orgcmd{S-M-@key{RET},org-insert-todo-heading}
4066 Insert a new TODO entry below the current one.
4070 @vindex org-todo-state-tags-triggers
4071 Changing a TODO state can also trigger tag changes. See the docstring of the
4072 option @code{org-todo-state-tags-triggers} for details.
4074 @node TODO extensions
4075 @section Extended use of TODO keywords
4076 @cindex extended TODO keywords
4078 @vindex org-todo-keywords
4079 By default, marked TODO entries have one of only two states: TODO and
4080 DONE@. Org mode allows you to classify TODO items in more complex ways
4081 with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
4082 special setup, the TODO keyword system can work differently in different
4085 Note that @i{tags} are another way to classify headlines in general and
4086 TODO items in particular (@pxref{Tags}).
4089 * Workflow states:: From TODO to DONE in steps
4090 * TODO types:: I do this, Fred does the rest
4091 * Multiple sets in one file:: Mixing it all, and still finding your way
4092 * Fast access to TODO states:: Single letter selection of a state
4093 * Per-file keywords:: Different files, different requirements
4094 * Faces for TODO keywords:: Highlighting states
4095 * TODO dependencies:: When one task needs to wait for others
4098 @node Workflow states
4099 @subsection TODO keywords as workflow states
4100 @cindex TODO workflow
4101 @cindex workflow states as TODO keywords
4103 You can use TODO keywords to indicate different @emph{sequential} states
4104 in the process of working on an item, for example@footnote{Changing
4105 this variable only becomes effective after restarting Org mode in a
4109 (setq org-todo-keywords
4110 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
4113 The vertical bar separates the TODO keywords (states that @emph{need
4114 action}) from the DONE states (which need @emph{no further action}). If
4115 you don't provide the separator bar, the last state is used as the DONE
4117 @cindex completion, of TODO keywords
4118 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
4119 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@. You may
4120 also use a numeric prefix argument to quickly select a specific state. For
4121 example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
4122 Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
4123 define many keywords, you can use in-buffer completion
4124 (@pxref{Completion}) or even a special one-key selection scheme
4125 (@pxref{Fast access to TODO states}) to insert these words into the
4126 buffer. Changing a TODO state can be logged with a timestamp, see
4127 @ref{Tracking TODO state changes}, for more information.
4130 @subsection TODO keywords as types
4132 @cindex names as TODO keywords
4133 @cindex types as TODO keywords
4135 The second possibility is to use TODO keywords to indicate different
4136 @emph{types} of action items. For example, you might want to indicate
4137 that items are for ``work'' or ``home''. Or, when you work with several
4138 people on a single project, you might want to assign action items
4139 directly to persons, by using their names as TODO keywords. This would
4140 be set up like this:
4143 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
4146 In this case, different keywords do not indicate a sequence, but rather
4147 different types. So the normal work flow would be to assign a task to a
4148 person, and later to mark it DONE@. Org mode supports this style by adapting
4149 the workings of the command @kbd{C-c C-t}@footnote{This is also true for the
4150 @kbd{t} command in the timeline and agenda buffers.}. When used several
4151 times in succession, it will still cycle through all names, in order to first
4152 select the right type for a task. But when you return to the item after some
4153 time and execute @kbd{C-c C-t} again, it will switch from any name directly
4154 to DONE@. Use prefix arguments or completion to quickly select a specific
4155 name. You can also review the items of a specific TODO type in a sparse tree
4156 by using a numeric prefix to @kbd{C-c / t}. For example, to see all things
4157 Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items
4158 from all agenda files into a single buffer, you would use the numeric prefix
4159 argument as well when creating the global TODO list: @kbd{C-3 C-c a t}.
4161 @node Multiple sets in one file
4162 @subsection Multiple keyword sets in one file
4163 @cindex TODO keyword sets
4165 Sometimes you may want to use different sets of TODO keywords in
4166 parallel. For example, you may want to have the basic
4167 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
4168 separate state indicating that an item has been canceled (so it is not
4169 DONE, but also does not require action). Your setup would then look
4173 (setq org-todo-keywords
4174 '((sequence "TODO" "|" "DONE")
4175 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
4176 (sequence "|" "CANCELED")))
4179 The keywords should all be different, this helps Org mode to keep track
4180 of which subsequence should be used for a given entry. In this setup,
4181 @kbd{C-c C-t} only operates within a subsequence, so it switches from
4182 @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
4183 (nothing) to @code{REPORT}. Therefore you need a mechanism to initially
4184 select the correct sequence. Besides the obvious ways like typing a
4185 keyword or using completion, you may also apply the following commands:
4188 @kindex C-S-@key{right}
4189 @kindex C-S-@key{left}
4190 @kindex C-u C-u C-c C-t
4191 @item C-u C-u C-c C-t
4192 @itemx C-S-@key{right}
4193 @itemx C-S-@key{left}
4194 These keys jump from one TODO subset to the next. In the above example,
4195 @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or
4196 @code{DONE} to @code{REPORT}, and any of the words in the second row to
4197 @code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with
4198 @code{shift-selection-mode} (@pxref{Conflicts}).
4199 @kindex S-@key{right}
4200 @kindex S-@key{left}
4203 @kbd{S-@key{left}} and @kbd{S-@key{right}} and walk through @emph{all}
4204 keywords from all sets, so for example @kbd{S-@key{right}} would switch
4205 from @code{DONE} to @code{REPORT} in the example above. See also
4206 @ref{Conflicts}, for a discussion of the interaction with
4207 @code{shift-selection-mode}.
4210 @node Fast access to TODO states
4211 @subsection Fast access to TODO states
4213 If you would like to quickly change an entry to an arbitrary TODO state
4214 instead of cycling through the states, you can set up keys for single-letter
4215 access to the states. This is done by adding the selection character after
4216 each keyword, in parentheses@footnote{All characters are allowed except
4217 @code{@@^!}, which have a special meaning here.}. For example:
4220 (setq org-todo-keywords
4221 '((sequence "TODO(t)" "|" "DONE(d)")
4222 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
4223 (sequence "|" "CANCELED(c)")))
4226 @vindex org-fast-tag-selection-include-todo
4227 If you then press @kbd{C-c C-t} followed by the selection key, the entry
4228 will be switched to this state. @kbd{SPC} can be used to remove any TODO
4229 keyword from an entry.@footnote{Check also the option
4230 @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
4231 state through the tags interface (@pxref{Setting tags}), in case you like to
4232 mingle the two concepts. Note that this means you need to come up with
4233 unique keys across both sets of keywords.}
4235 @node Per-file keywords
4236 @subsection Setting up keywords for individual files
4237 @cindex keyword options
4238 @cindex per-file keywords
4243 It can be very useful to use different aspects of the TODO mechanism in
4244 different files. For file-local settings, you need to add special lines to
4245 the file which set the keywords and interpretation for that file only. For
4246 example, to set one of the two examples discussed above, you need one of the
4247 following lines anywhere in the file:
4250 #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
4252 @noindent (you may also write @code{#+SEQ_TODO} to be explicit about the
4253 interpretation, but it means the same as @code{#+TODO}), or
4255 #+TYP_TODO: Fred Sara Lucy Mike | DONE
4258 A setup for using several sets in parallel would be:
4262 #+TODO: REPORT BUG KNOWNCAUSE | FIXED
4266 @cindex completion, of option keywords
4268 @noindent To make sure you are using the correct keyword, type
4269 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
4271 @cindex DONE, final TODO keyword
4272 Remember that the keywords after the vertical bar (or the last keyword
4273 if no bar is there) must always mean that the item is DONE (although you
4274 may use a different word). After changing one of these lines, use
4275 @kbd{C-c C-c} with the cursor still in the line to make the changes
4276 known to Org mode@footnote{Org mode parses these lines only when
4277 Org mode is activated after visiting a file. @kbd{C-c C-c} with the
4278 cursor in a line starting with @samp{#+} is simply restarting Org mode
4279 for the current buffer.}.
4281 @node Faces for TODO keywords
4282 @subsection Faces for TODO keywords
4283 @cindex faces, for TODO keywords
4285 @vindex org-todo @r{(face)}
4286 @vindex org-done @r{(face)}
4287 @vindex org-todo-keyword-faces
4288 Org mode highlights TODO keywords with special faces: @code{org-todo}
4289 for keywords indicating that an item still has to be acted upon, and
4290 @code{org-done} for keywords indicating that an item is finished. If
4291 you are using more than 2 different states, you might want to use
4292 special faces for some of them. This can be done using the option
4293 @code{org-todo-keyword-faces}. For example:
4297 (setq org-todo-keyword-faces
4298 '(("TODO" . org-warning) ("STARTED" . "yellow")
4299 ("CANCELED" . (:foreground "blue" :weight bold))))
4303 While using a list with face properties as shown for CANCELED @emph{should}
4304 work, this does not always seem to be the case. If necessary, define a
4305 special face and use that. A string is interpreted as a color. The option
4306 @code{org-faces-easy-properties} determines if that color is interpreted as a
4307 foreground or a background color.
4309 @node TODO dependencies
4310 @subsection TODO dependencies
4311 @cindex TODO dependencies
4312 @cindex dependencies, of TODO states
4313 @cindex TODO dependencies, NOBLOCKING
4315 @vindex org-enforce-todo-dependencies
4316 @cindex property, ORDERED
4317 The structure of Org files (hierarchy and lists) makes it easy to define TODO
4318 dependencies. Usually, a parent TODO task should not be marked DONE until
4319 all subtasks (defined as children tasks) are marked as DONE@. And sometimes
4320 there is a logical sequence to a number of (sub)tasks, so that one task
4321 cannot be acted upon before all siblings above it are done. If you customize
4322 the option @code{org-enforce-todo-dependencies}, Org will block entries
4323 from changing state to DONE while they have children that are not DONE@.
4324 Furthermore, if an entry has a property @code{ORDERED}, each of its children
4325 will be blocked until all earlier siblings are marked DONE@. Here is an
4329 * TODO Blocked until (two) is done
4338 ** TODO b, needs to wait for (a)
4339 ** TODO c, needs to wait for (a) and (b)
4342 You can ensure an entry is never blocked by using the @code{NOBLOCKING}
4346 * This entry is never blocked
4353 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4354 @vindex org-track-ordered-property-with-tag
4355 @cindex property, ORDERED
4356 Toggle the @code{ORDERED} property of the current entry. A property is used
4357 for this behavior because this should be local to the current entry, not
4358 inherited like a tag. However, if you would like to @i{track} the value of
4359 this property with a tag for better visibility, customize the option
4360 @code{org-track-ordered-property-with-tag}.
4361 @orgkey{C-u C-u C-u C-c C-t}
4362 Change TODO state, circumventing any state blocking.
4365 @vindex org-agenda-dim-blocked-tasks
4366 If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries
4367 that cannot be closed because of such dependencies will be shown in a dimmed
4368 font or even made invisible in agenda views (@pxref{Agenda views}).
4370 @cindex checkboxes and TODO dependencies
4371 @vindex org-enforce-todo-dependencies
4372 You can also block changes of TODO states by looking at checkboxes
4373 (@pxref{Checkboxes}). If you set the option
4374 @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
4375 checkboxes will be blocked from switching to DONE.
4377 If you need more complex dependency structures, for example dependencies
4378 between entries in different trees or files, check out the contributed
4379 module @file{org-depend.el}.
4382 @node Progress logging
4383 @section Progress logging
4384 @cindex progress logging
4385 @cindex logging, of progress
4387 Org mode can automatically record a timestamp and possibly a note when
4388 you mark a TODO item as DONE, or even each time you change the state of
4389 a TODO item. This system is highly configurable; settings can be on a
4390 per-keyword basis and can be localized to a file or even a subtree. For
4391 information on how to clock working time for a task, see @ref{Clocking
4395 * Closing items:: When was this entry marked DONE?
4396 * Tracking TODO state changes:: When did the status change?
4397 * Tracking your habits:: How consistent have you been?
4401 @subsection Closing items
4403 The most basic logging is to keep track of @emph{when} a certain TODO
4404 item was finished. This is achieved with@footnote{The corresponding
4405 in-buffer setting is: @code{#+STARTUP: logdone}}
4408 (setq org-log-done 'time)
4411 @vindex org-closed-keep-when-no-todo
4413 Then each time you turn an entry from a TODO (not-done) state into any of the
4414 DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
4415 the headline. If you turn the entry back into a TODO item through further
4416 state cycling, that line will be removed again. If you turn the entry back
4417 to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line
4418 will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
4419 non-@code{nil}. If you want to record a note along with the timestamp,
4420 use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
4424 (setq org-log-done 'note)
4428 You will then be prompted for a note, and that note will be stored below
4429 the entry with a @samp{Closing Note} heading.
4431 In the timeline (@pxref{Timeline}) and in the agenda
4432 (@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key to
4433 display the TODO items with a @samp{CLOSED} timestamp on each day,
4434 giving you an overview of what has been done.
4436 @node Tracking TODO state changes
4437 @subsection Tracking TODO state changes
4438 @cindex drawer, for state change recording
4440 @vindex org-log-states-order-reversed
4441 @vindex org-log-into-drawer
4442 @cindex property, LOG_INTO_DRAWER
4443 When TODO keywords are used as workflow states (@pxref{Workflow states}), you
4444 might want to keep track of when a state change occurred and maybe take a
4445 note about this change. You can either record just a timestamp, or a
4446 time-stamped note for a change. These records will be inserted after the
4447 headline as an itemized list, newest first@footnote{See the option
4448 @code{org-log-states-order-reversed}}. When taking a lot of notes, you might
4449 want to get the notes out of the way into a drawer (@pxref{Drawers}).
4450 Customize @code{org-log-into-drawer} to get this behavior---the recommended
4451 drawer for this is called @code{LOGBOOK}@footnote{Note that the
4452 @code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to
4453 show an entry---use @key{C-u SPC} to keep it folded here}. You can also
4454 overrule the setting of this variable for a subtree by setting a
4455 @code{LOG_INTO_DRAWER} property.
4457 Since it is normally too much to record a note for every state, Org mode
4458 expects configuration on a per-keyword basis for this. This is achieved by
4459 adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note
4460 with timestamp) in parentheses after each keyword. For example, with the
4464 (setq org-todo-keywords
4465 '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
4468 To record a timestamp without a note for TODO keywords configured with
4469 @samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
4472 @vindex org-log-done
4473 You not only define global TODO keywords and fast access keys, but also
4474 request that a time is recorded when the entry is set to
4475 DONE@footnote{It is possible that Org mode will record two timestamps
4476 when you are using both @code{org-log-done} and state change logging.
4477 However, it will never prompt for two notes---if you have configured
4478 both, the state change recording note will take precedence and cancel
4479 the @samp{Closing Note}.}, and that a note is recorded when switching to
4480 WAIT or CANCELED@. The setting for WAIT is even more special: the
4481 @samp{!} after the slash means that in addition to the note taken when
4482 entering the state, a timestamp should be recorded when @i{leaving} the
4483 WAIT state, if and only if the @i{target} state does not configure
4484 logging for entering it. So it has no effect when switching from WAIT
4485 to DONE, because DONE is configured to record a timestamp only. But
4486 when switching from WAIT back to TODO, the @samp{/!} in the WAIT
4487 setting now triggers a timestamp even though TODO has no logging
4490 You can use the exact same syntax for setting logging preferences local
4493 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
4496 @cindex property, LOGGING
4497 In order to define logging settings that are local to a subtree or a
4498 single item, define a LOGGING property in this entry. Any non-empty
4499 LOGGING property resets all logging settings to @code{nil}. You may then turn
4500 on logging for this specific tree using STARTUP keywords like
4501 @code{lognotedone} or @code{logrepeat}, as well as adding state specific
4502 settings like @code{TODO(!)}. For example
4505 * TODO Log each state with only a time
4507 :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
4509 * TODO Only log when switching to WAIT, and when repeating
4511 :LOGGING: WAIT(@@) logrepeat
4513 * TODO No logging at all
4519 @node Tracking your habits
4520 @subsection Tracking your habits
4523 Org has the ability to track the consistency of a special category of TODOs,
4524 called ``habits''. A habit has the following properties:
4528 You have enabled the @code{habits} module by customizing @code{org-modules}.
4530 The habit is a TODO item, with a TODO keyword representing an open state.
4532 The property @code{STYLE} is set to the value @code{habit}.
4534 The TODO has a scheduled date, usually with a @code{.+} style repeat
4535 interval. A @code{++} style may be appropriate for habits with time
4536 constraints, e.g., must be done on weekends, or a @code{+} style for an
4537 unusual habit that can have a backlog, e.g., weekly reports.
4539 The TODO may also have minimum and maximum ranges specified by using the
4540 syntax @samp{.+2d/3d}, which says that you want to do the task at least every
4541 three days, but at most every two days.
4543 You must also have state logging for the @code{DONE} state enabled
4544 (@pxref{Tracking TODO state changes}), in order for historical data to be
4545 represented in the consistency graph. If it is not enabled it is not an
4546 error, but the consistency graphs will be largely meaningless.
4549 To give you an idea of what the above rules look like in action, here's an
4550 actual habit with some history:
4554 SCHEDULED: <2009-10-17 Sat .+2d/4d>
4557 :LAST_REPEAT: [2009-10-19 Mon 00:36]
4559 - State "DONE" from "TODO" [2009-10-15 Thu]
4560 - State "DONE" from "TODO" [2009-10-12 Mon]
4561 - State "DONE" from "TODO" [2009-10-10 Sat]
4562 - State "DONE" from "TODO" [2009-10-04 Sun]
4563 - State "DONE" from "TODO" [2009-10-02 Fri]
4564 - State "DONE" from "TODO" [2009-09-29 Tue]
4565 - State "DONE" from "TODO" [2009-09-25 Fri]
4566 - State "DONE" from "TODO" [2009-09-19 Sat]
4567 - State "DONE" from "TODO" [2009-09-16 Wed]
4568 - State "DONE" from "TODO" [2009-09-12 Sat]
4571 What this habit says is: I want to shave at most every 2 days (given by the
4572 @code{SCHEDULED} date and repeat interval) and at least every 4 days. If
4573 today is the 15th, then the habit first appears in the agenda on Oct 17,
4574 after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
4575 after four days have elapsed.
4577 What's really useful about habits is that they are displayed along with a
4578 consistency graph, to show how consistent you've been at getting that task
4579 done in the past. This graph shows every day that the task was done over the
4580 past three weeks, with colors for each day. The colors used are:
4584 If the task wasn't to be done yet on that day.
4586 If the task could have been done on that day.
4588 If the task was going to be overdue the next day.
4590 If the task was overdue on that day.
4593 In addition to coloring each day, the day is also marked with an asterisk if
4594 the task was actually done that day, and an exclamation mark to show where
4595 the current day falls in the graph.
4597 There are several configuration variables that can be used to change the way
4598 habits are displayed in the agenda.
4601 @item org-habit-graph-column
4602 The buffer column at which the consistency graph should be drawn. This will
4603 overwrite any text in that column, so it is a good idea to keep your habits'
4604 titles brief and to the point.
4605 @item org-habit-preceding-days
4606 The amount of history, in days before today, to appear in consistency graphs.
4607 @item org-habit-following-days
4608 The number of days after today that will appear in consistency graphs.
4609 @item org-habit-show-habits-only-for-today
4610 If non-@code{nil}, only show habits in today's agenda view. This is set to true by
4614 Lastly, pressing @kbd{K} in the agenda buffer will cause habits to
4615 temporarily be disabled and they won't appear at all. Press @kbd{K} again to
4616 bring them back. They are also subject to tag filtering, if you have habits
4617 which should only be done in certain contexts, for example.
4623 If you use Org mode extensively, you may end up with enough TODO items that
4624 it starts to make sense to prioritize them. Prioritizing can be done by
4625 placing a @emph{priority cookie} into the headline of a TODO item, like this
4628 *** TODO [#A] Write letter to Sam Fortune
4632 @vindex org-priority-faces
4633 By default, Org mode supports three priorities: @samp{A}, @samp{B}, and
4634 @samp{C}. @samp{A} is the highest priority. An entry without a cookie is
4635 treated just like priority @samp{B}. Priorities make a difference only for
4636 sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
4637 have no inherent meaning to Org mode. The cookies can be highlighted with
4638 special faces by customizing @code{org-priority-faces}.
4640 Priorities can be attached to any outline node; they do not need to be TODO
4646 @findex org-priority
4647 Set the priority of the current headline (@command{org-priority}). The
4648 command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
4649 When you press @key{SPC} instead, the priority cookie is removed from the
4650 headline. The priorities can also be changed ``remotely'' from the timeline
4651 and agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
4653 @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
4654 @vindex org-priority-start-cycle-with-default
4655 Increase/decrease priority of current headline@footnote{See also the option
4656 @code{org-priority-start-cycle-with-default}.}. Note that these keys are
4657 also used to modify timestamps (@pxref{Creating timestamps}). See also
4658 @ref{Conflicts}, for a discussion of the interaction with
4659 @code{shift-selection-mode}.
4662 @vindex org-highest-priority
4663 @vindex org-lowest-priority
4664 @vindex org-default-priority
4665 You can change the range of allowed priorities by setting the options
4666 @code{org-highest-priority}, @code{org-lowest-priority}, and
4667 @code{org-default-priority}. For an individual buffer, you may set
4668 these values (highest, lowest, default) like this (please make sure that
4669 the highest priority is earlier in the alphabet than the lowest
4672 @cindex #+PRIORITIES
4677 @node Breaking down tasks
4678 @section Breaking tasks down into subtasks
4679 @cindex tasks, breaking down
4680 @cindex statistics, for TODO items
4682 @vindex org-agenda-todo-list-sublevels
4683 It is often advisable to break down large tasks into smaller, manageable
4684 subtasks. You can do this by creating an outline tree below a TODO item,
4685 with detailed subtasks on the tree@footnote{To keep subtasks out of the
4686 global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep
4687 the overview over the fraction of subtasks that are already completed, insert
4688 either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will
4689 be updated each time the TODO status of a child changes, or when pressing
4690 @kbd{C-c C-c} on the cookie. For example:
4693 * Organize Party [33%]
4694 ** TODO Call people [1/2]
4698 ** DONE Talk to neighbor
4701 @cindex property, COOKIE_DATA
4702 If a heading has both checkboxes and TODO children below it, the meaning of
4703 the statistics cookie become ambiguous. Set the property
4704 @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
4707 @vindex org-hierarchical-todo-statistics
4708 If you would like to have the statistics cookie count any TODO entries in the
4709 subtree (not just direct children), configure
4710 @code{org-hierarchical-todo-statistics}. To do this for a single subtree,
4711 include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
4715 * Parent capturing statistics [2/20]
4717 :COOKIE_DATA: todo recursive
4721 If you would like a TODO entry to automatically change to DONE
4722 when all children are done, you can use the following setup:
4725 (defun org-summary-todo (n-done n-not-done)
4726 "Switch entry to DONE when all subentries are done, to TODO otherwise."
4727 (let (org-log-done org-log-states) ; turn off logging
4728 (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
4730 (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
4734 Another possibility is the use of checkboxes to identify (a hierarchy of) a
4735 large number of subtasks (@pxref{Checkboxes}).
4742 @vindex org-list-automatic-rules
4743 Every item in a plain list@footnote{With the exception of description
4744 lists. But you can allow it by modifying @code{org-list-automatic-rules}
4745 accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
4746 it with the string @samp{[ ]}. This feature is similar to TODO items
4747 (@pxref{TODO items}), but is more lightweight. Checkboxes are not included
4748 in the global TODO list, so they are often great to split a task into a
4749 number of simple steps. Or you can use them in a shopping list. To toggle a
4750 checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
4751 @file{org-mouse.el}).
4753 Here is an example of a checkbox list.
4756 * TODO Organize party [2/4]
4757 - [-] call people [1/3]
4762 - [ ] think about what music to play
4763 - [X] talk to the neighbors
4766 Checkboxes work hierarchically, so if a checkbox item has children that
4767 are checkboxes, toggling one of the children checkboxes will make the
4768 parent checkbox reflect if none, some, or all of the children are
4771 @cindex statistics, for checkboxes
4772 @cindex checkbox statistics
4773 @cindex property, COOKIE_DATA
4774 @vindex org-checkbox-hierarchical-statistics
4775 The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
4776 indicating how many checkboxes present in this entry have been checked off,
4777 and the total number of checkboxes present. This can give you an idea on how
4778 many checkboxes remain, even without opening a folded entry. The cookies can
4779 be placed into a headline or into (the first line of) a plain list item.
4780 Each cookie covers checkboxes of direct children structurally below the
4781 headline/item on which the cookie appears@footnote{Set the option
4782 @code{org-checkbox-hierarchical-statistics} if you want such cookies to
4783 count all checkboxes below the cookie, not just those belonging to direct
4784 children.}. You have to insert the cookie yourself by typing either
4785 @samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}
4786 result, as in the examples above. With @samp{[%]} you get information about
4787 the percentage of checkboxes checked (in the above example, this would be
4788 @samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie can
4789 count either checkboxes below the heading or TODO states of children, and it
4790 will display whatever was changed last. Set the property @code{COOKIE_DATA}
4791 to either @samp{checkbox} or @samp{todo} to resolve this issue.
4793 @cindex blocking, of checkboxes
4794 @cindex checkbox blocking
4795 @cindex property, ORDERED
4796 If the current outline node has an @code{ORDERED} property, checkboxes must
4797 be checked off in sequence, and an error will be thrown if you try to check
4798 off a box while there are unchecked boxes above it.
4800 @noindent The following commands work with checkboxes:
4803 @orgcmd{C-c C-c,org-toggle-checkbox}
4804 Toggle checkbox status or (with prefix arg) checkbox presence at point. With
4805 a single prefix argument, add an empty checkbox or remove the current
4806 one@footnote{@kbd{C-u C-c C-c} before the @emph{first} bullet in a list with
4807 no checkbox will add checkboxes to the rest of the list.}. With a double
4808 prefix argument, set it to @samp{[-]}, which is considered to be an
4810 @orgcmd{C-c C-x C-b,org-toggle-checkbox}
4811 Toggle checkbox status or (with prefix arg) checkbox presence at point. With
4812 double prefix argument, set it to @samp{[-]}, which is considered to be an
4816 If there is an active region, toggle the first checkbox in the region
4817 and set all remaining boxes to the same status as the first. With a prefix
4818 arg, add or remove the checkbox for all items in the region.
4820 If the cursor is in a headline, toggle the state of the first checkbox in the
4821 region between this headline and the next---so @emph{not} the entire
4822 subtree---and propagate this new state to all other checkboxes in the same
4825 If there is no active region, just toggle the checkbox at point.
4827 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
4828 Insert a new item with a checkbox. This works only if the cursor is already
4829 in a plain list item (@pxref{Plain lists}).
4830 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4831 @vindex org-track-ordered-property-with-tag
4832 @cindex property, ORDERED
4833 Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
4834 be checked off in sequence. A property is used for this behavior because
4835 this should be local to the current entry, not inherited like a tag.
4836 However, if you would like to @i{track} the value of this property with a tag
4837 for better visibility, customize @code{org-track-ordered-property-with-tag}.
4838 @orgcmd{C-c #,org-update-statistics-cookies}
4839 Update the statistics cookie in the current outline entry. When called with
4840 a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are
4841 updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
4842 new ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update when
4843 changing TODO states. If you delete boxes/entries or add/change them by
4844 hand, use this command to get things back into sync.
4850 @cindex headline tagging
4851 @cindex matching, tags
4852 @cindex sparse tree, tag based
4854 An excellent way to implement labels and contexts for cross-correlating
4855 information is to assign @i{tags} to headlines. Org mode has extensive
4858 @vindex org-tag-faces
4859 Every headline can contain a list of tags; they occur at the end of the
4860 headline. Tags are normal words containing letters, numbers, @samp{_}, and
4861 @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
4862 @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
4863 Tags will by default be in bold face with the same color as the headline.
4864 You may specify special faces for specific tags using the option
4865 @code{org-tag-faces}, in much the same way as you can for TODO keywords
4866 (@pxref{Faces for TODO keywords}).
4869 * Tag inheritance:: Tags use the tree structure of the outline
4870 * Setting tags:: How to assign tags to a headline
4871 * Tag hierarchy:: Create a hierarchy of tags
4872 * Tag searches:: Searching for combinations of tags
4875 @node Tag inheritance
4876 @section Tag inheritance
4877 @cindex tag inheritance
4878 @cindex inheritance, of tags
4879 @cindex sublevels, inclusion into tags match
4881 @i{Tags} make use of the hierarchical structure of outline trees. If a
4882 heading has a certain tag, all subheadings will inherit the tag as
4883 well. For example, in the list
4886 * Meeting with the French group :work:
4887 ** Summary by Frank :boss:notes:
4888 *** TODO Prepare slides for him :action:
4892 the final heading will have the tags @samp{:work:}, @samp{:boss:},
4893 @samp{:notes:}, and @samp{:action:} even though the final heading is not
4894 explicitly marked with all those tags. You can also set tags that all
4895 entries in a file should inherit just as if these tags were defined in
4896 a hypothetical level zero that surrounds the entire file. Use a line like
4897 this@footnote{As with all these in-buffer settings, pressing @kbd{C-c C-c}
4898 activates any changes in the line.}:
4902 #+FILETAGS: :Peter:Boss:Secret:
4906 @vindex org-use-tag-inheritance
4907 @vindex org-tags-exclude-from-inheritance
4908 To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
4909 To turn it off entirely, use @code{org-use-tag-inheritance}.
4911 @vindex org-tags-match-list-sublevels
4912 When a headline matches during a tags search while tag inheritance is turned
4913 on, all the sublevels in the same tree will (for a simple match form) match
4914 as well@footnote{This is only true if the search does not involve more
4915 complex tests including properties (@pxref{Property searches}).}. The list
4916 of matches may then become very long. If you only want to see the first tags
4917 match in a subtree, configure @code{org-tags-match-list-sublevels} (not
4920 @vindex org-agenda-use-tag-inheritance
4921 Tag inheritance is relevant when the agenda search tries to match a tag,
4922 either in the @code{tags} or @code{tags-todo} agenda types. In other agenda
4923 types, @code{org-use-tag-inheritance} has no effect. Still, you may want to
4924 have your tags correctly set in the agenda, so that tag filtering works fine,
4925 with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control
4926 this: the default value includes all agenda types, but setting this to @code{nil}
4927 can really speed up agenda generation.
4930 @section Setting tags
4931 @cindex setting tags
4932 @cindex tags, setting
4935 Tags can simply be typed into the buffer at the end of a headline.
4936 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
4937 also a special command for inserting tags:
4940 @orgcmd{C-c C-q,org-set-tags-command}
4941 @cindex completion, of tags
4942 @vindex org-tags-column
4943 Enter new tags for the current headline. Org mode will either offer
4944 completion or a special single-key interface for setting tags, see
4945 below. After pressing @key{RET}, the tags will be inserted and aligned
4946 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
4947 tags in the current buffer will be aligned to that column, just to make
4948 things look nice. TAGS are automatically realigned after promotion,
4949 demotion, and TODO state changes (@pxref{TODO basics}).
4951 @orgcmd{C-c C-c,org-set-tags-command}
4952 When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
4955 @vindex org-tag-alist
4956 Org supports tag insertion based on a @emph{list of tags}. By
4957 default this list is constructed dynamically, containing all tags
4958 currently used in the buffer. You may also globally specify a hard list
4959 of tags with the variable @code{org-tag-alist}. Finally you can set
4960 the default tags for a given file with lines like
4964 #+TAGS: @@work @@home @@tennisclub
4965 #+TAGS: laptop car pc sailboat
4968 If you have globally defined your preferred set of tags using the
4969 variable @code{org-tag-alist}, but would like to use a dynamic tag list
4970 in a specific file, add an empty TAGS option line to that file:
4976 @vindex org-tag-persistent-alist
4977 If you have a preferred set of tags that you would like to use in every file,
4978 in addition to those defined on a per-file basis by TAGS option lines, then
4979 you may specify a list of tags with the variable
4980 @code{org-tag-persistent-alist}. You may turn this off on a per-file basis
4981 by adding a STARTUP option line to that file:
4987 By default Org mode uses the standard minibuffer completion facilities for
4988 entering tags. However, it also implements another, quicker, tag selection
4989 method called @emph{fast tag selection}. This allows you to select and
4990 deselect tags with just a single key press. For this to work well you should
4991 assign unique, case-sensitive, letters to most of your commonly used tags.
4992 You can do this globally by configuring the variable @code{org-tag-alist} in
4993 your Emacs init file. For example, you may find the need to tag many items
4994 in different files with @samp{:@@home:}. In this case you can set something
4998 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
5001 @noindent If the tag is only relevant to the file you are working on, then you
5002 can instead set the TAGS option line as:
5005 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
5008 @noindent The tags interface will show the available tags in a splash
5009 window. If you want to start a new line after a specific tag, insert
5010 @samp{\n} into the tag list
5013 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p)
5016 @noindent or write them in two lines:
5019 #+TAGS: @@work(w) @@home(h) @@tennisclub(t)
5020 #+TAGS: laptop(l) pc(p)
5024 You can also group together tags that are mutually exclusive by using
5028 #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)
5031 @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
5032 and @samp{@@tennisclub} should be selected. Multiple such groups are allowed.
5034 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
5035 these lines to activate any changes.
5038 To set these mutually exclusive groups in the variable @code{org-tag-alist},
5039 you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
5040 of the braces. Similarly, you can use @code{:newline} to indicate a line
5041 break. The previous example would be set globally by the following
5045 (setq org-tag-alist '((:startgroup . nil)
5046 ("@@work" . ?w) ("@@home" . ?h)
5047 ("@@tennisclub" . ?t)
5049 ("laptop" . ?l) ("pc" . ?p)))
5052 If at least one tag has a selection key then pressing @kbd{C-c C-c} will
5053 automatically present you with a special interface, listing inherited tags,
5054 the tags of the current headline, and a list of all valid tags with
5055 corresponding keys@footnote{Keys will automatically be assigned to tags which
5056 have no configured keys.}.
5058 Pressing keys assigned to tags will add or remove them from the list of tags
5059 in the current line. Selecting a tag in a group of mutually exclusive tags
5060 will turn off any other tags from that group.
5062 In this interface, you can also use the following special keys:
5067 Enter a tag in the minibuffer, even if the tag is not in the predefined
5068 list. You will be able to complete on all tags present in the buffer.
5069 You can also add several tags: just separate them with a comma.
5073 Clear all tags for this line.
5077 Accept the modified set.
5080 Abort without installing changes.
5083 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
5086 Turn off groups of mutually exclusive tags. Use this to (as an
5087 exception) assign several tags from such a group.
5090 Toggle auto-exit after the next change (see below).
5091 If you are using expert mode, the first @kbd{C-c} will display the
5096 This method lets you assign tags to a headline with very few keys. With
5097 the above setup, you could clear the current tags and set @samp{@@home},
5098 @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
5099 C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to
5100 @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
5101 alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
5102 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
5103 @key{RET} @key{RET}}.
5105 @vindex org-fast-tag-selection-single-key
5106 If you find that most of the time you need only a single key press to
5107 modify your list of tags, set @code{org-fast-tag-selection-single-key}.
5108 Then you no longer have to press @key{RET} to exit fast tag selection---it
5109 will immediately exit after the first change. If you then occasionally
5110 need more keys, press @kbd{C-c} to turn off auto-exit for the current tag
5111 selection process (in effect: start selection with @kbd{C-c C-c C-c}
5112 instead of @kbd{C-c C-c}). If you set the variable to the value
5113 @code{expert}, the special window is not even shown for single-key tag
5114 selection, it comes up only when you press an extra @kbd{C-c}.
5117 @section Tag hierarchy
5120 @cindex tags, groups
5121 @cindex tag hierarchy
5122 Tags can be defined in hierarchies. A tag can be defined as a @emph{group
5123 tag} for a set of other tags. The group tag can be seen as the ``broader
5124 term'' for its set of tags. Defining multiple @emph{group tags} and nesting
5125 them creates a tag hierarchy.
5127 One use-case is to create a taxonomy of terms (tags) that can be used to
5128 classify nodes in a document or set of documents.
5130 When you search for a group tag, it will return matches for all members in
5131 the group and its subgroups. In an agenda view, filtering by a group tag
5132 will display or hide headlines tagged with at least one of the members of the
5133 group or any of its subgroups. This makes tag searches and filters even more
5136 You can set group tags by using brackets and inserting a colon between the
5137 group tag and its related tags---beware that all whitespaces are mandatory so
5138 that Org can parse this line correctly:
5141 #+TAGS: [ GTD : Control Persp ]
5144 In this example, @samp{GTD} is the @emph{group tag} and it is related to two
5145 other tags: @samp{Control}, @samp{Persp}. Defining @samp{Control} and
5146 @samp{Persp} as group tags creates an hierarchy of tags:
5149 #+TAGS: [ Control : Context Task ]
5150 #+TAGS: [ Persp : Vision Goal AOF Project ]
5153 That can conceptually be seen as a hierarchy of tags:
5167 You can use the @code{:startgrouptag}, @code{:grouptags} and
5168 @code{:endgrouptag} keyword directly when setting @code{org-tag-alist}
5172 (setq org-tag-alist '((:startgrouptag)
5186 The tags in a group can be mutually exclusive if using the same group syntax
5187 as is used for grouping mutually exclusive tags together; using curly
5191 #+TAGS: @{ Context : @@Home @@Work @@Call @}
5194 When setting @code{org-tag-alist} you can use @code{:startgroup} &
5195 @code{:endgroup} instead of @code{:startgrouptag} & @code{:endgrouptag} to
5196 make the tags mutually exclusive.
5198 Furthermore, the members of a @emph{group tag} can also be regular
5199 expressions, creating the possibility of a more dynamic and rule-based
5200 tag structure. The regular expressions in the group must be specified
5201 within @{ @}. Here is an expanded example:
5204 #+TAGS: [ Vision : @{V@@@.+@} ]
5205 #+TAGS: [ Goal : @{G@@@.+@} ]
5206 #+TAGS: [ AOF : @{AOF@@@.+@} ]
5207 #+TAGS: [ Project : @{P@@@.+@} ]
5210 Searching for the tag @samp{Project} will now list all tags also including
5211 regular expression matches for @samp{P@@@.+}, and similarly for tag searches on
5212 @samp{Vision}, @samp{Goal} and @samp{AOF}. For example, this would work well
5213 for a project tagged with a common project-identifier, e.g. @samp{P@@2014_OrgTags}.
5216 @vindex org-group-tags
5217 If you want to ignore group tags temporarily, toggle group tags support
5218 with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you
5219 want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
5222 @section Tag searches
5223 @cindex tag searches
5224 @cindex searching for tags
5226 Once a system of tags has been set up, it can be used to collect related
5227 information into special lists.
5230 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5231 Create a sparse tree with all headlines matching a tags/property/TODO search.
5232 With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5233 @xref{Matching tags and properties}.
5234 @orgcmd{C-c a m,org-tags-view}
5235 Create a global list of tag matches from all agenda files. @xref{Matching
5236 tags and properties}.
5237 @orgcmd{C-c a M,org-tags-view}
5238 @vindex org-tags-match-list-sublevels
5239 Create a global list of tag matches from all agenda files, but check
5240 only TODO items and force checking subitems (see the option
5241 @code{org-tags-match-list-sublevels}).
5244 These commands all prompt for a match string which allows basic Boolean logic
5245 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
5246 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
5247 tagged as @samp{Kathy} or @samp{Sally}. The full syntax of the search string
5248 is rich and allows also matching against TODO keywords, entry levels and
5249 properties. For a complete description with many examples, see @ref{Matching
5250 tags and properties}.
5253 @node Properties and columns
5254 @chapter Properties and columns
5257 A property is a key-value pair associated with an entry. Properties can be
5258 set so they are associated with a single entry, with every entry in a tree,
5259 or with every entry in an Org mode file.
5261 There are two main applications for properties in Org mode. First,
5262 properties are like tags, but with a value. Imagine maintaining a file where
5263 you document bugs and plan releases for a piece of software. Instead of
5264 using tags like @code{:release_1:}, @code{:release_2:}, you can use a
5265 property, say @code{:Release:}, that in different subtrees has different
5266 values, such as @code{1.0} or @code{2.0}. Second, you can use properties to
5267 implement (very basic) database capabilities in an Org buffer. Imagine
5268 keeping track of your music CDs, where properties could be things such as the
5269 album, artist, date of release, number of tracks, and so on.
5271 Properties can be conveniently edited and viewed in column view
5272 (@pxref{Column view}).
5275 * Property syntax:: How properties are spelled out
5276 * Special properties:: Access to other Org mode features
5277 * Property searches:: Matching property values
5278 * Property inheritance:: Passing values down the tree
5279 * Column view:: Tabular viewing and editing
5280 * Property API:: Properties for Lisp programmers
5283 @node Property syntax
5284 @section Property syntax
5285 @cindex property syntax
5286 @cindex drawer, for properties
5288 Properties are key-value pairs. When they are associated with a single entry
5289 or with a tree they need to be inserted into a special drawer
5290 (@pxref{Drawers}) with the name @code{PROPERTIES}, which has to be located
5291 right below a headline, and its planning line (@pxref{Deadlines and
5292 scheduling}) when applicable. Each property is specified on a single line,
5293 with the key (surrounded by colons) first, and the value after it. Keys are
5294 case-insensitives. Here is an example:
5299 *** Goldberg Variations
5301 :Title: Goldberg Variations
5302 :Composer: J.S. Bach
5304 :Publisher: Deutsche Grammophon
5309 Depending on the value of @code{org-use-property-inheritance}, a property set
5310 this way will either be associated with a single entry, or the subtree
5311 defined by the entry, see @ref{Property inheritance}.
5313 You may define the allowed values for a particular property @samp{:Xyz:}
5314 by setting a property @samp{:Xyz_ALL:}. This special property is
5315 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
5316 the entire tree. When allowed values are defined, setting the
5317 corresponding property becomes easier and is less prone to typing
5318 errors. For the example with the CD collection, we can predefine
5319 publishers and the number of disks in a box like this:
5324 :NDisks_ALL: 1 2 3 4
5325 :Publisher_ALL: "Deutsche Grammophon" Philips EMI
5329 If you want to set properties that can be inherited by any entry in a
5330 file, use a line like
5331 @cindex property, _ALL
5334 #+PROPERTY: NDisks_ALL 1 2 3 4
5337 Contrary to properties set from a special drawer, you have to refresh the
5338 buffer with @kbd{C-c C-c} to activate this change.
5340 If you want to add to the value of an existing property, append a @code{+} to
5341 the property name. The following results in the property @code{var} having
5342 the value ``foo=1 bar=2''.
5345 #+PROPERTY: var foo=1
5346 #+PROPERTY: var+ bar=2
5349 It is also possible to add to the values of inherited properties. The
5350 following results in the @code{genres} property having the value ``Classic
5351 Baroque'' under the @code{Goldberg Variations} subtree.
5359 *** Goldberg Variations
5361 :Title: Goldberg Variations
5362 :Composer: J.S. Bach
5364 :Publisher: Deutsche Grammophon
5369 Note that a property can only have one entry per Drawer.
5371 @vindex org-global-properties
5372 Property values set with the global variable
5373 @code{org-global-properties} can be inherited by all entries in all
5377 The following commands help to work with properties:
5380 @orgcmd{M-@key{TAB},pcomplete}
5381 After an initial colon in a line, complete property keys. All keys used
5382 in the current file will be offered as possible completions.
5383 @orgcmd{C-c C-x p,org-set-property}
5384 Set a property. This prompts for a property name and a value. If
5385 necessary, the property drawer is created as well.
5386 @item C-u M-x org-insert-drawer RET
5387 @cindex org-insert-drawer
5388 Insert a property drawer into the current entry. The drawer will be
5389 inserted early in the entry, but after the lines with planning
5390 information like deadlines.
5391 @orgcmd{C-c C-c,org-property-action}
5392 With the cursor in a property drawer, this executes property commands.
5393 @orgcmd{C-c C-c s,org-set-property}
5394 Set a property in the current entry. Both the property and the value
5395 can be inserted using completion.
5396 @orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
5397 Switch property at point to the next/previous allowed value.
5398 @orgcmd{C-c C-c d,org-delete-property}
5399 Remove a property from the current entry.
5400 @orgcmd{C-c C-c D,org-delete-property-globally}
5401 Globally remove a property, from all entries in the current file.
5402 @orgcmd{C-c C-c c,org-compute-property-at-point}
5403 Compute the property at point, using the operator and scope from the
5404 nearest column format definition.
5407 @node Special properties
5408 @section Special properties
5409 @cindex properties, special
5411 Special properties provide an alternative access method to Org mode features,
5412 like the TODO state or the priority of an entry, discussed in the previous
5413 chapters. This interface exists so that you can include these states in
5414 a column view (@pxref{Column view}), or to use them in queries. The
5415 following property names are special and should not be used as keys in the
5418 @cindex property, special, ALLTAGS
5419 @cindex property, special, BLOCKED
5420 @cindex property, special, CLOCKSUM
5421 @cindex property, special, CLOCKSUM_T
5422 @cindex property, special, CLOSED
5423 @cindex property, special, DEADLINE
5424 @cindex property, special, FILE
5425 @cindex property, special, ITEM
5426 @cindex property, special, PRIORITY
5427 @cindex property, special, SCHEDULED
5428 @cindex property, special, TAGS
5429 @cindex property, special, TIMESTAMP
5430 @cindex property, special, TIMESTAMP_IA
5431 @cindex property, special, TODO
5433 ALLTAGS @r{All tags, including inherited ones.}
5434 BLOCKED @r{"t" if task is currently blocked by children or siblings.}
5435 CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}}
5436 @r{must be run first to compute the values in the current buffer.}
5437 CLOCKSUM_T @r{The sum of CLOCK intervals in the subtree for today.}
5438 @r{@code{org-clock-sum-today} must be run first to compute the}
5439 @r{values in the current buffer.}
5440 CLOSED @r{When was this entry closed?}
5441 DEADLINE @r{The deadline time string, without the angular brackets.}
5442 FILE @r{The filename the entry is located in.}
5443 ITEM @r{The headline of the entry.}
5444 PRIORITY @r{The priority of the entry, a string with a single letter.}
5445 SCHEDULED @r{The scheduling timestamp, without the angular brackets.}
5446 TAGS @r{The tags defined directly in the headline.}
5447 TIMESTAMP @r{The first keyword-less timestamp in the entry.}
5448 TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
5449 TODO @r{The TODO keyword of the entry.}
5452 @node Property searches
5453 @section Property searches
5454 @cindex properties, searching
5455 @cindex searching, of properties
5457 To create sparse trees and special lists with selection based on properties,
5458 the same commands are used as for tag searches (@pxref{Tag searches}).
5461 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5462 Create a sparse tree with all matching entries. With a
5463 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5464 @orgcmd{C-c a m,org-tags-view}
5465 Create a global list of tag/property matches from all agenda files.
5466 @xref{Matching tags and properties}.
5467 @orgcmd{C-c a M,org-tags-view}
5468 @vindex org-tags-match-list-sublevels
5469 Create a global list of tag matches from all agenda files, but check
5470 only TODO items and force checking of subitems (see the option
5471 @code{org-tags-match-list-sublevels}).
5474 The syntax for the search string is described in @ref{Matching tags and
5477 There is also a special command for creating sparse trees based on a
5482 Create a sparse tree based on the value of a property. This first
5483 prompts for the name of a property, and then for a value. A sparse tree
5484 is created with all entries that define this property with the given
5485 value. If you enclose the value in curly braces, it is interpreted as
5486 a regular expression and matched against the property values.
5489 @node Property inheritance
5490 @section Property Inheritance
5491 @cindex properties, inheritance
5492 @cindex inheritance, of properties
5494 @vindex org-use-property-inheritance
5495 The outline structure of Org mode documents lends itself to an
5496 inheritance model of properties: if the parent in a tree has a certain
5497 property, the children can inherit this property. Org mode does not
5498 turn this on by default, because it can slow down property searches
5499 significantly and is often not needed. However, if you find inheritance
5500 useful, you can turn it on by setting the variable
5501 @code{org-use-property-inheritance}. It may be set to @code{t} to make
5502 all properties inherited from the parent, to a list of properties
5503 that should be inherited, or to a regular expression that matches
5504 inherited properties. If a property has the value @code{nil}, this is
5505 interpreted as an explicit undefine of the property, so that inheritance
5506 search will stop at this value and return @code{nil}.
5508 Org mode has a few properties for which inheritance is hard-coded, at
5509 least for the special applications for which they are used:
5511 @cindex property, COLUMNS
5514 The @code{:COLUMNS:} property defines the format of column view
5515 (@pxref{Column view}). It is inherited in the sense that the level
5516 where a @code{:COLUMNS:} property is defined is used as the starting
5517 point for a column view table, independently of the location in the
5518 subtree from where columns view is turned on.
5520 @cindex property, CATEGORY
5521 For agenda view, a category set through a @code{:CATEGORY:} property
5522 applies to the entire subtree.
5524 @cindex property, ARCHIVE
5525 For archiving, the @code{:ARCHIVE:} property may define the archive
5526 location for the entire subtree (@pxref{Moving subtrees}).
5528 @cindex property, LOGGING
5529 The LOGGING property may define logging settings for an entry or a
5530 subtree (@pxref{Tracking TODO state changes}).
5534 @section Column view
5536 A great way to view and edit properties in an outline tree is
5537 @emph{column view}. In column view, each outline node is turned into a
5538 table row. Columns in this table provide access to properties of the
5539 entries. Org mode implements columns by overlaying a tabular structure
5540 over the headline of each item. While the headlines have been turned
5541 into a table row, you can still change the visibility of the outline
5542 tree. For example, you get a compact table by switching to CONTENTS
5543 view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
5544 is active), but you can still open, read, and edit the entry below each
5545 headline. Or, you can switch to column view after executing a sparse
5546 tree command and in this way get a table only for the selected items.
5547 Column view also works in agenda buffers (@pxref{Agenda views}) where
5548 queries have collected selected items, possibly from a number of files.
5551 * Defining columns:: The COLUMNS format property
5552 * Using column view:: How to create and use column view
5553 * Capturing column view:: A dynamic block for column view
5556 @node Defining columns
5557 @subsection Defining columns
5558 @cindex column view, for properties
5559 @cindex properties, column view
5561 Setting up a column view first requires defining the columns. This is
5562 done by defining a column format line.
5565 * Scope of column definitions:: Where defined, where valid?
5566 * Column attributes:: Appearance and content of a column
5569 @node Scope of column definitions
5570 @subsubsection Scope of column definitions
5572 To define a column format for an entire file, use a line like
5576 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5579 To specify a format that only applies to a specific tree, add a
5580 @code{:COLUMNS:} property to the top node of that tree, for example:
5583 ** Top node for columns view
5585 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5589 If a @code{:COLUMNS:} property is present in an entry, it defines columns
5590 for the entry itself, and for the entire subtree below it. Since the
5591 column definition is part of the hierarchical structure of the document,
5592 you can define columns on level 1 that are general enough for all
5593 sublevels, and more specific columns further down, when you edit a
5594 deeper part of the tree.
5596 @node Column attributes
5597 @subsubsection Column attributes
5598 A column definition sets the attributes of a column. The general
5599 definition looks like this:
5602 %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]
5606 Except for the percent sign and the property name, all items are
5607 optional. The individual parts have the following meaning:
5610 @var{width} @r{An integer specifying the width of the column in characters.}
5611 @r{If omitted, the width will be determined automatically.}
5612 @var{property} @r{The property that should be edited in this column.}
5613 @r{Special properties representing meta data are allowed here}
5614 @r{as well (@pxref{Special properties})}
5615 @var{title} @r{The header text for the column. If omitted, the property}
5617 @{@var{summary-type}@} @r{The summary type. If specified, the column values for}
5618 @r{parent nodes are computed from the children@footnote{If
5619 more than one summary type apply to the property, the parent
5620 values are computed according to the first of them.}.}
5621 @r{Supported summary types are:}
5622 @{+@} @r{Sum numbers in this column.}
5623 @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.}
5624 @{$@} @r{Currency, short for @samp{+;%.2f}.}
5625 @{min@} @r{Smallest number in column.}
5626 @{max@} @r{Largest number.}
5627 @{mean@} @r{Arithmetic mean of numbers.}
5628 @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
5629 @{X/@} @r{Checkbox status, @samp{[n/m]}.}
5630 @{X%@} @r{Checkbox status, @samp{[n%]}.}
5631 @{:@} @r{Sum times, HH:MM, plain numbers are
5632 hours@footnote{A time can also be a duration, using effort
5633 modifiers defined in @code{org-effort-durations}, e.g.,
5634 @samp{3d 1h}. If any value in the column is as such, the
5635 summary will also be an effort duration.}.}
5636 @{:min@} @r{Smallest time value in column.}
5637 @{:max@} @r{Largest time value.}
5638 @{:mean@} @r{Arithmetic mean of time values.}
5639 @{@@min@} @r{Minimum age@footnote{An age is defined as
5640 a duration since a given time-stamp (@pxref{Timestamps}). It
5641 can also be expressed as days, hours, minutes and seconds,
5642 identified by @samp{d}, @samp{h}, @samp{m} and @samp{s}
5643 suffixes, all mandatory, e.g., @samp{0d 13h 0m 10s}.} (in
5644 days/hours/mins/seconds).}
5645 @{@@max@} @r{Maximum age (in days/hours/mins/seconds).}
5646 @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
5647 @{est+@} @r{Add @samp{low-high} estimates.}
5650 The @code{est+} summary type requires further explanation. It is used for
5651 combining estimates, expressed as @samp{low-high} ranges or plain numbers.
5652 For example, instead of estimating a particular task will take 5 days, you
5653 might estimate it as 5--6 days if you're fairly confident you know how much
5654 work is required, or 1--10 days if you don't really know what needs to be
5655 done. Both ranges average at 5.5 days, but the first represents a more
5656 predictable delivery.
5658 When combining a set of such estimates, simply adding the lows and highs
5659 produces an unrealistically wide result. Instead, @code{est+} adds the
5660 statistical mean and variance of the sub-tasks, generating a final estimate
5661 from the sum. For example, suppose you had ten tasks, each of which was
5662 estimated at 0.5 to 2 days of work. Straight addition produces an estimate
5663 of 5 to 20 days, representing what to expect if everything goes either
5664 extremely well or extremely poorly. In contrast, @code{est+} estimates the
5665 full job more realistically, at 10--15 days.
5667 Numbers are right-aligned when a format specifier with an explicit width like
5668 @code{%5d} or @code{%5.1f} is used.
5670 @vindex org-columns-summary-types
5671 You can also define custom summary types by setting
5672 @code{org-columns-summary-types}, which see.
5674 Here is an example for a complete columns definition, along with allowed
5678 :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.}
5679 %10Time_Estimate@{:@} %CLOCKSUM %CLOCKSUM_T
5680 :Owner_ALL: Tammy Mark Karl Lisa Don
5681 :Status_ALL: "In progress" "Not started yet" "Finished" ""
5682 :Approved_ALL: "[ ]" "[X]"
5686 The first column, @samp{%25ITEM}, means the first 25 characters of the
5687 item itself, i.e., of the headline. You probably always should start the
5688 column definition with the @samp{ITEM} specifier. The other specifiers
5689 create columns @samp{Owner} with a list of names as allowed values, for
5690 @samp{Status} with four different possible values, and for a checkbox
5691 field @samp{Approved}. When no width is given after the @samp{%}
5692 character, the column will be exactly as wide as it needs to be in order
5693 to fully display all values. The @samp{Approved} column does have a
5694 modified title (@samp{Approved?}, with a question mark). Summaries will
5695 be created for the @samp{Time_Estimate} column by adding time duration
5696 expressions like HH:MM, and for the @samp{Approved} column, by providing
5697 an @samp{[X]} status if all children have been checked. The
5698 @samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns are special, they lists the
5699 sums of CLOCK intervals in the subtree, either for all clocks or just for
5702 @node Using column view
5703 @subsection Using column view
5706 @tsubheading{Turning column view on and off}
5707 @orgcmd{C-c C-x C-c,org-columns}
5708 @vindex org-columns-default-format
5709 Turn on column view. If the cursor is before the first headline in the file,
5710 or the function called with the universal prefix argument, column view is
5711 turned on for the entire file, using the @code{#+COLUMNS} definition. If the
5712 cursor is somewhere inside the outline, this command searches the hierarchy,
5713 up from point, for a @code{:COLUMNS:} property that defines a format. When
5714 one is found, the column view table is established for the tree starting at
5715 the entry that contains the @code{:COLUMNS:} property. If no such property
5716 is found, the format is taken from the @code{#+COLUMNS} line or from the
5717 variable @code{org-columns-default-format}, and column view is established
5718 for the current entry and its subtree.
5719 @orgcmd{r,org-columns-redo}
5720 Recreate the column view, to include recent changes made in the buffer.
5721 @orgcmd{g,org-columns-redo}
5723 @orgcmd{q,org-columns-quit}
5725 @tsubheading{Editing values}
5726 @item @key{left} @key{right} @key{up} @key{down}
5727 Move through the column view from field to field.
5728 @kindex S-@key{left}
5729 @kindex S-@key{right}
5730 @item S-@key{left}/@key{right}
5731 Switch to the next/previous allowed value of the field. For this, you
5732 have to have specified allowed values for a property.
5734 Directly select the Nth allowed value, @kbd{0} selects the 10th value.
5735 @orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value}
5736 Same as @kbd{S-@key{left}/@key{right}}
5737 @orgcmd{e,org-columns-edit-value}
5738 Edit the property at point. For the special properties, this will
5739 invoke the same interface that you normally use to change that
5740 property. For example, when editing a TAGS property, the tag completion
5741 or fast selection interface will pop up.
5742 @orgcmd{C-c C-c,org-columns-set-tags-or-toggle}
5743 When there is a checkbox at point, toggle it.
5744 @orgcmd{v,org-columns-show-value}
5745 View the full value of this property. This is useful if the width of
5746 the column is smaller than that of the value.
5747 @orgcmd{a,org-columns-edit-allowed}
5748 Edit the list of allowed values for this property. If the list is found
5749 in the hierarchy, the modified value is stored there. If no list is
5750 found, the new value is stored in the first entry that is part of the
5751 current column view.
5752 @tsubheading{Modifying the table structure}
5753 @orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen}
5754 Make the column narrower/wider by one character.
5755 @orgcmd{S-M-@key{right},org-columns-new}
5756 Insert a new column, to the left of the current column.
5757 @orgcmd{S-M-@key{left},org-columns-delete}
5758 Delete the current column.
5761 @node Capturing column view
5762 @subsection Capturing column view
5764 Since column view is just an overlay over a buffer, it cannot be
5765 exported or printed directly. If you want to capture a column view, use
5766 a @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
5767 of this block looks like this:
5769 @cindex #+BEGIN, columnview
5772 #+BEGIN: columnview :hlines 1 :id "label"
5777 @noindent This dynamic block has the following parameters:
5781 This is the most important parameter. Column view is a feature that is
5782 often localized to a certain (sub)tree, and the capture block might be
5783 at a different location in the file. To identify the tree whose view to
5784 capture, you can use 4 values:
5785 @cindex property, ID
5787 local @r{use the tree in which the capture block is located}
5788 global @r{make a global view, including all headings in the file}
5789 "file:@var{path-to-file}"
5790 @r{run column view at the top of this file}
5791 "@var{ID}" @r{call column view in the tree that has an @code{:ID:}}
5792 @r{property with the value @i{label}. You can use}
5793 @r{@kbd{M-x org-id-copy RET} to create a globally unique ID for}
5794 @r{the current entry and copy it to the kill-ring.}
5797 When @code{t}, insert an hline after every line. When a number @var{N}, insert
5798 an hline before each headline with level @code{<= @var{N}}.
5800 When set to @code{t}, force column groups to get vertical lines.
5802 When set to a number, don't capture entries below this level.
5803 @item :skip-empty-rows
5804 When set to @code{t}, skip rows where the only non-empty specifier of the
5805 column view is @code{ITEM}.
5807 When non-@code{nil}, indent each @code{ITEM} field according to its level.
5812 The following commands insert or update the dynamic block:
5815 @orgcmd{C-c C-x i,org-insert-columns-dblock}
5816 Insert a dynamic block capturing a column view. You will be prompted
5817 for the scope or ID of the view.
5818 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
5819 Update dynamic block at point. The cursor needs to be in the
5820 @code{#+BEGIN} line of the dynamic block.
5821 @orgcmd{C-u C-c C-x C-u,org-update-all-dblocks}
5822 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
5823 you have several clock table blocks, column-capturing blocks or other dynamic
5827 You can add formulas to the column view table and you may add plotting
5828 instructions in front of the table---these will survive an update of the
5829 block. If there is a @code{#+TBLFM:} after the table, the table will
5830 actually be recalculated automatically after an update.
5832 An alternative way to capture and process property values into a table is
5833 provided by Eric Schulte's @file{org-collector.el} which is a contributed
5834 package@footnote{Contributed packages are not part of Emacs, but are
5835 distributed with the main distribution of Org (visit
5836 @uref{http://orgmode.org}).}. It provides a general API to collect
5837 properties from entries in a certain scope, and arbitrary Lisp expressions to
5838 process these values before inserting them into a table or a dynamic block.
5841 @section The Property API
5842 @cindex properties, API
5843 @cindex API, for properties
5845 There is a full API for accessing and changing properties. This API can
5846 be used by Emacs Lisp programs to work with properties and to implement
5847 features based on them. For more information see @ref{Using the
5850 @node Dates and times
5851 @chapter Dates and times
5857 To assist project planning, TODO items can be labeled with a date and/or
5858 a time. The specially formatted string carrying the date and time
5859 information is called a @emph{timestamp} in Org mode. This may be a
5860 little confusing because timestamp is often used to indicate when
5861 something was created or last changed. However, in Org mode this term
5862 is used in a much wider sense.
5865 * Timestamps:: Assigning a time to a tree entry
5866 * Creating timestamps:: Commands which insert timestamps
5867 * Deadlines and scheduling:: Planning your work
5868 * Clocking work time:: Tracking how long you spend on a task
5869 * Effort estimates:: Planning work effort in advance
5870 * Timers:: Notes with a running timer
5875 @section Timestamps, deadlines, and scheduling
5877 @cindex ranges, time
5882 A timestamp is a specification of a date (possibly with a time or a range of
5883 times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this
5884 simplest form, the day name is optional when you type the date yourself.
5885 However, any dates inserted or modified by Org will add that day name, for
5886 reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16
5887 Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601
5888 date/time format. To use an alternative format, see @ref{Custom time
5889 format}.}. A timestamp can appear anywhere in the headline or body of an Org
5890 tree entry. Its presence causes entries to be shown on specific dates in the
5891 agenda (@pxref{Weekly/daily agenda}). We distinguish:
5894 @item Plain timestamp; Event; Appointment
5897 A simple timestamp just assigns a date/time to an item. This is just
5898 like writing down an appointment or event in a paper agenda. In the
5899 timeline and agenda displays, the headline of an entry associated with a
5900 plain timestamp will be shown exactly on that date.
5903 * Meet Peter at the movies
5904 <2006-11-01 Wed 19:15>
5905 * Discussion on climate change
5906 <2006-11-02 Thu 20:00-22:00>
5909 @item Timestamp with repeater interval
5910 @cindex timestamp, with repeater interval
5911 A timestamp may contain a @emph{repeater interval}, indicating that it
5912 applies not only on the given date, but again and again after a certain
5913 interval of N days (d), weeks (w), months (m), or years (y). The
5914 following will show up in the agenda every Wednesday:
5917 * Pick up Sam at school
5918 <2007-05-16 Wed 12:30 +1w>
5921 @item Diary-style sexp entries
5922 For more complex date specifications, Org mode supports using the special
5923 sexp diary entries implemented in the Emacs calendar/diary
5924 package@footnote{When working with the standard diary sexp functions, you
5925 need to be very careful with the order of the arguments. That order depends
5926 evilly on the variable @code{calendar-date-style} (or, for older Emacs
5927 versions, @code{european-calendar-style}). For example, to specify a date
5928 December 1, 2005, the call might look like @code{(diary-date 12 1 2005)} or
5929 @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
5930 the settings. This has been the source of much confusion. Org mode users
5931 can resort to special versions of these functions like @code{org-date} or
5932 @code{org-anniversary}. These work just like the corresponding @code{diary-}
5933 functions, but with stable ISO order of arguments (year, month, day) wherever
5934 applicable, independent of the value of @code{calendar-date-style}.}. For
5935 example with optional time
5938 * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
5939 <%%(diary-float t 4 2)>
5942 @item Time/Date range
5945 Two timestamps connected by @samp{--} denote a range. The headline
5946 will be shown on the first and last day of the range, and on any dates
5947 that are displayed and fall in the range. Here is an example:
5950 ** Meeting in Amsterdam
5951 <2004-08-23 Mon>--<2004-08-26 Thu>
5954 @item Inactive timestamp
5955 @cindex timestamp, inactive
5956 @cindex inactive timestamp
5957 Just like a plain timestamp, but with square brackets instead of
5958 angular ones. These timestamps are inactive in the sense that they do
5959 @emph{not} trigger an entry to show up in the agenda.
5962 * Gillian comes late for the fifth time
5968 @node Creating timestamps
5969 @section Creating timestamps
5970 @cindex creating timestamps
5971 @cindex timestamps, creating
5973 For Org mode to recognize timestamps, they need to be in the specific
5974 format. All commands listed below produce timestamps in the correct
5978 @orgcmd{C-c .,org-time-stamp}
5979 Prompt for a date and insert a corresponding timestamp. When the cursor is
5980 at an existing timestamp in the buffer, the command is used to modify this
5981 timestamp instead of inserting a new one. When this command is used twice in
5982 succession, a time range is inserted.
5984 @orgcmd{C-c !,org-time-stamp-inactive}
5985 Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
5992 @vindex org-time-stamp-rounding-minutes
5993 Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which
5994 contains date and time. The default time can be rounded to multiples of 5
5995 minutes, see the option @code{org-time-stamp-rounding-minutes}.
5998 Normalize timestamp, insert/fix day name if missing or wrong.
6000 @orgcmd{C-c <,org-date-from-calendar}
6001 Insert a timestamp corresponding to the cursor date in the Calendar.
6003 @orgcmd{C-c >,org-goto-calendar}
6004 Access the Emacs calendar for the current date. If there is a
6005 timestamp in the current line, go to the corresponding date
6008 @orgcmd{C-c C-o,org-open-at-point}
6009 Access the agenda for the date given by the timestamp or -range at
6010 point (@pxref{Weekly/daily agenda}).
6012 @orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day}
6013 Change date at cursor by one day. These key bindings conflict with
6014 shift-selection and related modes (@pxref{Conflicts}).
6016 @orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down}
6017 Change the item under the cursor in a timestamp. The cursor can be on a
6018 year, month, day, hour or minute. When the timestamp contains a time range
6019 like @samp{15:30-16:30}, modifying the first time will also shift the second,
6020 shifting the time block with constant length. To change the length, modify
6021 the second time. Note that if the cursor is in a headline and not at a
6022 timestamp, these same keys modify the priority of an item.
6023 (@pxref{Priorities}). The key bindings also conflict with shift-selection and
6024 related modes (@pxref{Conflicts}).
6026 @orgcmd{C-c C-y,org-evaluate-time-range}
6027 @cindex evaluate time range
6028 Evaluate a time range by computing the difference between start and end.
6029 With a prefix argument, insert result after the time range (in a table: into
6030 the following column).
6035 * The date/time prompt:: How Org mode helps you entering date and time
6036 * Custom time format:: Making dates look different
6039 @node The date/time prompt
6040 @subsection The date/time prompt
6041 @cindex date, reading in minibuffer
6042 @cindex time, reading in minibuffer
6044 @vindex org-read-date-prefer-future
6045 When Org mode prompts for a date/time, the default is shown in default
6046 date/time format, and the prompt therefore seems to ask for a specific
6047 format. But it will in fact accept date/time information in a variety of
6048 formats. Generally, the information should start at the beginning of the
6049 string. Org mode will find whatever information is in
6050 there and derive anything you have not specified from the @emph{default date
6051 and time}. The default is usually the current date and time, but when
6052 modifying an existing timestamp, or when entering the second stamp of a
6053 range, it is taken from the stamp in the buffer. When filling in
6054 information, Org mode assumes that most of the time you will want to enter a
6055 date in the future: if you omit the month/year and the given day/month is
6056 @i{before} today, it will assume that you mean a future date@footnote{See the
6057 variable @code{org-read-date-prefer-future}. You may set that variable to
6058 the symbol @code{time} to even make a time before now shift the date to
6059 tomorrow.}. If the date has been automatically shifted into the future, the
6060 time prompt will show this with @samp{(=>F).}
6062 For example, let's assume that today is @b{June 13, 2006}. Here is how
6063 various inputs will be interpreted, the items filled in by Org mode are
6067 3-2-5 @result{} 2003-02-05
6068 2/5/3 @result{} 2003-02-05
6069 14 @result{} @b{2006}-@b{06}-14
6070 12 @result{} @b{2006}-@b{07}-12
6071 2/5 @result{} @b{2007}-02-05
6072 Fri @result{} nearest Friday after the default date
6073 sep 15 @result{} @b{2006}-09-15
6074 feb 15 @result{} @b{2007}-02-15
6075 sep 12 9 @result{} 2009-09-12
6076 12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45
6077 22 sept 0:34 @result{} @b{2006}-09-22 00:34
6078 w4 @result{} ISO week four of the current year @b{2006}
6079 2012 w4 fri @result{} Friday of ISO week 4 in 2012
6080 2012-w04-5 @result{} Same as above
6083 Furthermore you can specify a relative date by giving, as the @emph{first}
6084 thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to
6085 indicate change in hours, days, weeks, months, or years. With a single plus
6086 or minus, the date is always relative to today. With a double plus or minus,
6087 it is relative to the default date. If instead of a single letter, you use
6088 the abbreviation of day name, the date will be the Nth such day, e.g.:
6093 +4d @result{} four days from today
6094 +4 @result{} same as above
6095 +2w @result{} two weeks from today
6096 ++5 @result{} five days from default date
6097 +2tue @result{} second Tuesday from now
6098 -wed @result{} last Wednesday
6101 @vindex parse-time-months
6102 @vindex parse-time-weekdays
6103 The function understands English month and weekday abbreviations. If
6104 you want to use unabbreviated names and/or other languages, configure
6105 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
6107 @vindex org-read-date-force-compatible-dates
6108 Not all dates can be represented in a given Emacs implementation. By default
6109 Org mode forces dates into the compatibility range 1970--2037 which works on
6110 all Emacs implementations. If you want to use dates outside of this range,
6111 read the docstring of the variable
6112 @code{org-read-date-force-compatible-dates}.
6114 You can specify a time range by giving start and end times or by giving a
6115 start time and a duration (in HH:MM format). Use one or two dash(es) as the
6116 separator in the former case and use '+' as the separator in the latter
6120 11am-1:15pm @result{} 11:00-13:15
6121 11am--1:15pm @result{} same as above
6122 11am+2:15 @result{} same as above
6125 @cindex calendar, for selecting date
6126 @vindex org-popup-calendar-for-date-prompt
6127 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
6128 you don't need/want the calendar, configure the variable
6129 @code{org-popup-calendar-for-date-prompt}.}. When you exit the date
6130 prompt, either by clicking on a date in the calendar, or by pressing
6131 @key{RET}, the date selected in the calendar will be combined with the
6132 information entered at the prompt. You can control the calendar fully
6133 from the minibuffer:
6140 @kindex S-@key{right}
6141 @kindex S-@key{left}
6142 @kindex S-@key{down}
6144 @kindex M-S-@key{right}
6145 @kindex M-S-@key{left}
6147 @kindex M-S-@key{down}
6148 @kindex M-S-@key{up}
6151 @key{RET} @r{Choose date at cursor in calendar.}
6152 mouse-1 @r{Select date by clicking on it.}
6153 S-@key{right}/@key{left} @r{One day forward/backward.}
6154 S-@key{down}/@key{up} @r{One week forward/backward.}
6155 M-S-@key{right}/@key{left} @r{One month forward/backward.}
6156 > / < @r{Scroll calendar forward/backward by one month.}
6157 M-v / C-v @r{Scroll calendar forward/backward by 3 months.}
6158 M-S-@key{down}/@key{up} @r{Scroll calendar forward/backward by one year.}
6161 @vindex org-read-date-display-live
6162 The actions of the date/time prompt may seem complex, but I assure you they
6163 will grow on you, and you will start getting annoyed by pretty much any other
6164 way of entering a date/time out there. To help you understand what is going
6165 on, the current interpretation of your input will be displayed live in the
6166 minibuffer@footnote{If you find this distracting, turn the display off with
6167 @code{org-read-date-display-live}.}.
6169 @node Custom time format
6170 @subsection Custom time format
6171 @cindex custom date/time format
6172 @cindex time format, custom
6173 @cindex date format, custom
6175 @vindex org-display-custom-times
6176 @vindex org-time-stamp-custom-formats
6177 Org mode uses the standard ISO notation for dates and times as it is
6178 defined in ISO 8601. If you cannot get used to this and require another
6179 representation of date and time to keep you happy, you can get it by
6180 customizing the options @code{org-display-custom-times} and
6181 @code{org-time-stamp-custom-formats}.
6184 @orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays}
6185 Toggle the display of custom formats for dates and times.
6189 Org mode needs the default format for scanning, so the custom date/time
6190 format does not @emph{replace} the default format---instead it is put
6191 @emph{over} the default format using text properties. This has the
6192 following consequences:
6195 You cannot place the cursor onto a timestamp anymore, only before or
6198 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
6199 each component of a timestamp. If the cursor is at the beginning of
6200 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
6201 just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the
6202 time will be changed by one minute.
6204 If the timestamp contains a range of clock times or a repeater, these
6205 will not be overlaid, but remain in the buffer as they were.
6207 When you delete a timestamp character-by-character, it will only
6208 disappear from the buffer after @emph{all} (invisible) characters
6209 belonging to the ISO timestamp have been removed.
6211 If the custom timestamp format is longer than the default and you are
6212 using dates in tables, table alignment will be messed up. If the custom
6213 format is shorter, things do work as expected.
6217 @node Deadlines and scheduling
6218 @section Deadlines and scheduling
6220 A timestamp may be preceded by special keywords to facilitate planning. Both
6221 the timestamp and the keyword have to be positioned immediatly after the task
6226 @cindex DEADLINE keyword
6228 Meaning: the task (most likely a TODO item, though not necessarily) is supposed
6229 to be finished on that date.
6231 @vindex org-deadline-warning-days
6232 @vindex org-agenda-skip-deadline-prewarning-if-scheduled
6233 On the deadline date, the task will be listed in the agenda. In
6234 addition, the agenda for @emph{today} will carry a warning about the
6235 approaching or missed deadline, starting
6236 @code{org-deadline-warning-days} before the due date, and continuing
6237 until the entry is marked DONE@. An example:
6240 *** TODO write article about the Earth for the Guide
6241 DEADLINE: <2004-02-29 Sun>
6242 The editor in charge is [[bbdb:Ford Prefect]]
6245 You can specify a different lead time for warnings for a specific
6246 deadline using the following syntax. Here is an example with a warning
6247 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. This warning is
6248 deactivated if the task gets scheduled and you set
6249 @code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}.
6252 @cindex SCHEDULED keyword
6254 Meaning: you are planning to start working on that task on the given
6257 @vindex org-agenda-skip-scheduled-if-done
6258 The headline will be listed under the given date@footnote{It will still
6259 be listed on that date after it has been marked DONE@. If you don't like
6260 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
6261 addition, a reminder that the scheduled date has passed will be present
6262 in the compilation for @emph{today}, until the entry is marked DONE, i.e.,
6263 the task will automatically be forwarded until completed.
6266 *** TODO Call Trillian for a date on New Years Eve.
6267 SCHEDULED: <2004-12-25 Sat>
6270 @vindex org-scheduled-delay-days
6271 @vindex org-agenda-skip-scheduled-delay-if-deadline
6272 If you want to @emph{delay} the display of this task in the agenda, use
6273 @code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the
6274 25th but will appear two days later. In case the task contains a repeater,
6275 the delay is considered to affect all occurrences; if you want the delay to
6276 only affect the first scheduled occurrence of the task, use @code{--2d}
6277 instead. See @code{org-scheduled-delay-days} and
6278 @code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to
6279 control this globally or per agenda.
6282 @b{Important:} Scheduling an item in Org mode should @i{not} be
6283 understood in the same way that we understand @i{scheduling a meeting}.
6284 Setting a date for a meeting is just a simple appointment, you should
6285 mark this entry with a simple plain timestamp, to get this item shown
6286 on the date where it applies. This is a frequent misunderstanding by
6287 Org users. In Org mode, @i{scheduling} means setting a date when you
6288 want to start working on an action item.
6291 You may use timestamps with repeaters in scheduling and deadline
6292 entries. Org mode will issue early and late warnings based on the
6293 assumption that the timestamp represents the @i{nearest instance} of
6294 the repeater. However, the use of diary sexp entries like
6296 @code{<%%(diary-float t 42)>}
6298 in scheduling and deadline timestamps is limited. Org mode does not
6299 know enough about the internals of each sexp function to issue early and
6300 late warnings. However, it will show the item on each day where the
6304 * Inserting deadline/schedule:: Planning items
6305 * Repeated tasks:: Items that show up again and again
6308 @node Inserting deadline/schedule
6309 @subsection Inserting deadlines or schedules
6311 The following commands allow you to quickly insert a deadline or to schedule
6316 @orgcmd{C-c C-d,org-deadline}
6317 Insert @samp{DEADLINE} keyword along with a stamp. Any CLOSED timestamp will
6318 be removed. When called with a prefix arg, an existing deadline will be
6319 removed from the entry. Depending on the variable
6320 @code{org-log-redeadline}@footnote{with corresponding @code{#+STARTUP}
6321 keywords @code{logredeadline}, @code{lognoteredeadline}, and
6322 @code{nologredeadline}}, a note will be taken when changing an existing
6325 @orgcmd{C-c C-s,org-schedule}
6326 Insert @samp{SCHEDULED} keyword along with a stamp. Any CLOSED timestamp
6327 will be removed. When called with a prefix argument, remove the scheduling
6328 date from the entry. Depending on the variable
6329 @code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}
6330 keywords @code{logreschedule}, @code{lognotereschedule}, and
6331 @code{nologreschedule}}, a note will be taken when changing an existing
6334 @orgcmd{C-c / d,org-check-deadlines}
6335 @cindex sparse tree, for deadlines
6336 @vindex org-deadline-warning-days
6337 Create a sparse tree with all deadlines that are either past-due, or
6338 which will become due within @code{org-deadline-warning-days}.
6339 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
6340 prefix, check that many days. For example, @kbd{C-1 C-c / d} shows
6341 all deadlines due tomorrow.
6343 @orgcmd{C-c / b,org-check-before-date}
6344 Sparse tree for deadlines and scheduled items before a given date.
6346 @orgcmd{C-c / a,org-check-after-date}
6347 Sparse tree for deadlines and scheduled items after a given date.
6350 Note that @code{org-schedule} and @code{org-deadline} supports
6351 setting the date by indicating a relative time: e.g., +1d will set
6352 the date to the next day after today, and --1w will set the date
6353 to the previous week before any current timestamp.
6355 @node Repeated tasks
6356 @subsection Repeated tasks
6357 @cindex tasks, repeated
6358 @cindex repeated tasks
6360 Some tasks need to be repeated again and again. Org mode helps to
6361 organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
6362 or plain timestamp. In the following example
6364 ** TODO Pay the rent
6365 DEADLINE: <2005-10-01 Sat +1m>
6368 the @code{+1m} is a repeater; the intended interpretation is that the task
6369 has a deadline on <2005-10-01> and repeats itself every (one) month starting
6370 from that time. You can use yearly, monthly, weekly, daily and hourly repeat
6371 cookies by using the @code{y/w/m/d/h} letters. If you need both a repeater
6372 and a special warning period in a deadline entry, the repeater should come
6373 first and the warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
6375 @vindex org-todo-repeat-to-state
6376 Deadlines and scheduled items produce entries in the agenda when they are
6377 over-due, so it is important to be able to mark such an entry as completed
6378 once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO
6379 keyword DONE, it will no longer produce entries in the agenda. The problem
6380 with this is, however, that then also the @emph{next} instance of the
6381 repeated entry will not be active. Org mode deals with this in the following
6382 way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
6383 shift the base date of the repeating timestamp by the repeater interval, and
6384 immediately set the entry state back to TODO@footnote{In fact, the target
6385 state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or
6386 the variable @code{org-todo-repeat-to-state}. If neither of these is
6387 specified, the target state defaults to the first state of the TODO state
6388 sequence.}. In the example above, setting the state to DONE would actually
6389 switch the date like this:
6392 ** TODO Pay the rent
6393 DEADLINE: <2005-11-01 Tue +1m>
6396 To mark a task with a repeater as @code{DONE}, use @kbd{C-- 1 C-c C-t}
6397 (i.e., @code{org-todo} with a numeric prefix argument of -1.)
6399 @vindex org-log-repeat
6400 A timestamp@footnote{You can change this using the option
6401 @code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},
6402 @code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you
6403 will also be prompted for a note.} will be added under the deadline, to keep
6404 a record that you actually acted on the previous instance of this deadline.
6406 As a consequence of shifting the base date, this entry will no longer be
6407 visible in the agenda when checking past dates, but all future instances
6410 With the @samp{+1m} cookie, the date shift will always be exactly one
6411 month. So if you have not paid the rent for three months, marking this
6412 entry DONE will still keep it as an overdue deadline. Depending on the
6413 task, this may not be the best way to handle it. For example, if you
6414 forgot to call your father for 3 weeks, it does not make sense to call
6415 him 3 times in a single day to make up for it. Finally, there are tasks
6416 like changing batteries which should always repeat a certain time
6417 @i{after} the last time you did it. For these tasks, Org mode has
6418 special repeaters @samp{++} and @samp{.+}. For example:
6422 DEADLINE: <2008-02-10 Sun ++1w>
6423 Marking this DONE will shift the date by at least one week,
6424 but also by as many weeks as it takes to get this date into
6425 the future. However, it stays on a Sunday, even if you called
6426 and marked it done on Saturday.
6427 ** TODO Empty kitchen trash
6428 DEADLINE: <2008-02-08 Fri 20:00 ++1d>
6429 Marking this DONE will shift the date by at least one day, and
6430 also by as many days as it takes to get the timestamp into the
6431 future. Since there is a time in the timestamp, the next
6432 deadline in the future will be on today's date if you
6433 complete the task before 20:00.
6434 ** TODO Check the batteries in the smoke detectors
6435 DEADLINE: <2005-11-01 Tue .+1m>
6436 Marking this DONE will shift the date to one month after
6440 @vindex org-agenda-skip-scheduled-if-deadline-is-shown
6441 You may have both scheduling and deadline information for a specific task.
6442 If the repeater is set for the scheduling information only, you probably want
6443 the repeater to be ignored after the deadline. If so, set the variable
6444 @code{org-agenda-skip-scheduled-if-deadline-is-shown} to
6445 @code{repeated-after-deadline}. However, any scheduling information without
6446 a repeater is no longer relevant once the task is done, and thus, removed
6447 upon repeating the task. If you want both scheduling and deadline
6448 information to repeat after the same interval, set the same repeater for both
6451 An alternative to using a repeater is to create a number of copies of a task
6452 subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was
6453 created for this purpose, it is described in @ref{Structure editing}.
6456 @node Clocking work time
6457 @section Clocking work time
6458 @cindex clocking time
6459 @cindex time clocking
6461 Org mode allows you to clock the time you spend on specific tasks in a
6462 project. When you start working on an item, you can start the clock. When
6463 you stop working on that task, or when you mark the task done, the clock is
6464 stopped and the corresponding time interval is recorded. It also computes
6465 the total time spent on each subtree@footnote{Clocking only works if all
6466 headings are indented with less than 30 stars. This is a hardcoded
6467 limitation of @code{lmax} in @code{org-clock-sum}.} of a project.
6468 And it remembers a history or tasks recently clocked, so that you can jump
6469 quickly between a number of tasks absorbing your time.
6471 To save the clock history across Emacs sessions, use
6473 (setq org-clock-persist 'history)
6474 (org-clock-persistence-insinuate)
6476 When you clock into a new task after resuming Emacs, the incomplete
6477 clock@footnote{To resume the clock under the assumption that you have worked
6478 on this task while outside Emacs, use @code{(setq org-clock-persist t)}.}
6479 will be found (@pxref{Resolving idle time}) and you will be prompted about
6483 * Clocking commands:: Starting and stopping a clock
6484 * The clock table:: Detailed reports
6485 * Resolving idle time:: Resolving time when you've been idle
6488 @node Clocking commands
6489 @subsection Clocking commands
6492 @orgcmd{C-c C-x C-i,org-clock-in}
6493 @vindex org-clock-into-drawer
6494 @vindex org-clock-continuously
6495 @cindex property, LOG_INTO_DRAWER
6496 Start the clock on the current item (clock-in). This inserts the CLOCK
6497 keyword together with a timestamp. If this is not the first clocking of
6498 this item, the multiple CLOCK lines will be wrapped into a
6499 @code{:LOGBOOK:} drawer (see also the variable
6500 @code{org-clock-into-drawer}). You can also overrule
6501 the setting of this variable for a subtree by setting a
6502 @code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
6503 When called with a @kbd{C-u} prefix argument,
6504 select the task from a list of recently clocked tasks. With two @kbd{C-u
6505 C-u} prefixes, clock into the task at point and mark it as the default task;
6506 the default task will then always be available with letter @kbd{d} when
6507 selecting a clocking task. With three @kbd{C-u C-u C-u} prefixes, force
6508 continuous clocking by starting the clock when the last clock stopped.@*
6509 @cindex property: CLOCK_MODELINE_TOTAL
6510 @cindex property: LAST_REPEAT
6511 @vindex org-clock-modeline-total
6512 While the clock is running, the current clocking time is shown in the mode
6513 line, along with the title of the task. The clock time shown will be all
6514 time ever clocked for this task and its children. If the task has an effort
6515 estimate (@pxref{Effort estimates}), the mode line displays the current
6516 clocking time against it@footnote{To add an effort estimate ``on the fly'',
6517 hook a function doing this to @code{org-clock-in-prepare-hook}.} If the task
6518 is a repeating one (@pxref{Repeated tasks}), only the time since the last
6519 reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}
6520 will be shown. More control over what time is shown can be exercised with
6521 the @code{CLOCK_MODELINE_TOTAL} property. It may have the values
6522 @code{current} to show only the current clocking instance, @code{today} to
6523 show all time clocked on this task today (see also the variable
6524 @code{org-extend-today-until}), @code{all} to include all time, or
6525 @code{auto} which is the default@footnote{See also the variable
6526 @code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
6527 mode line entry will pop up a menu with clocking options.
6529 @orgcmd{C-c C-x C-o,org-clock-out}
6530 @vindex org-log-note-clock-out
6531 Stop the clock (clock-out). This inserts another timestamp at the same
6532 location where the clock was last started. It also directly computes
6533 the resulting time and inserts it after the time range as @samp{=>
6534 HH:MM}. See the variable @code{org-log-note-clock-out} for the
6535 possibility to record an additional note together with the clock-out
6536 timestamp@footnote{The corresponding in-buffer setting is:
6537 @code{#+STARTUP: lognoteclock-out}}.
6538 @orgcmd{C-c C-x C-x,org-clock-in-last}
6539 @vindex org-clock-continuously
6540 Reclock the last clocked task. With one @kbd{C-u} prefix argument,
6541 select the task from the clock history. With two @kbd{C-u} prefixes,
6542 force continuous clocking by starting the clock when the last clock
6544 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6545 Update the effort estimate for the current clock task.
6548 @orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range}
6549 Recompute the time interval after changing one of the timestamps. This
6550 is only necessary if you edit the timestamps directly. If you change
6551 them with @kbd{S-@key{cursor}} keys, the update is automatic.
6552 @orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
6553 On @code{CLOCK} log lines, increase/decrease both timestamps so that the
6554 clock duration keeps the same.
6555 @orgcmd{S-M-@key{up/down},org-timestamp-up/down}
6556 On @code{CLOCK} log lines, increase/decrease the timestamp at point and
6557 the one of the previous (or the next clock) timestamp by the same duration.
6558 For example, if you hit @kbd{S-M-@key{up}} to increase a clocked-out timestamp
6559 by five minutes, then the clocked-in timestamp of the next clock will be
6560 increased by five minutes.
6561 @orgcmd{C-c C-t,org-todo}
6562 Changing the TODO state of an item to DONE automatically stops the clock
6563 if it is running in this same item.
6564 @orgcmd{C-c C-x C-q,org-clock-cancel}
6565 Cancel the current clock. This is useful if a clock was started by
6566 mistake, or if you ended up working on something else.
6567 @orgcmd{C-c C-x C-j,org-clock-goto}
6568 Jump to the headline of the currently clocked in task. With a @kbd{C-u}
6569 prefix arg, select the target task from a list of recently clocked tasks.
6570 @orgcmd{C-c C-x C-d,org-clock-display}
6571 @vindex org-remove-highlights-with-change
6572 Display time summaries for each subtree in the current buffer. This puts
6573 overlays at the end of each headline, showing the total time recorded under
6574 that heading, including the time of any subheadings. You can use visibility
6575 cycling to study the tree, but the overlays disappear when you change the
6576 buffer (see variable @code{org-remove-highlights-with-change}) or press
6580 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
6581 the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
6582 worked on or closed during a day.
6584 @strong{Important:} note that both @code{org-clock-out} and
6585 @code{org-clock-in-last} can have a global key binding and will not
6586 modify the window disposition.
6588 @node The clock table
6589 @subsection The clock table
6590 @cindex clocktable, dynamic block
6591 @cindex report, of clocked time
6593 Org mode can produce quite complex reports based on the time clocking
6594 information. Such a report is called a @emph{clock table}, because it is
6595 formatted as one or several Org tables.
6598 @orgcmd{C-c C-x C-r,org-clock-report}
6599 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
6600 report as an Org mode table into the current file. When the cursor is
6601 at an existing clock table, just update it. When called with a prefix
6602 argument, jump to the first clock report in the current document and
6603 update it. The clock table always includes also trees with
6604 @code{:ARCHIVE:} tag.
6605 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
6606 Update dynamic block at point. The cursor needs to be in the
6607 @code{#+BEGIN} line of the dynamic block.
6608 @orgkey{C-u C-c C-x C-u}
6609 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
6610 you have several clock table blocks in a buffer.
6611 @orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift}
6612 Shift the current @code{:block} interval and update the table. The cursor
6613 needs to be in the @code{#+BEGIN: clocktable} line for this command. If
6614 @code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
6618 Here is an example of the frame for a clock table as it is inserted into the
6619 buffer with the @kbd{C-c C-x C-r} command:
6621 @cindex #+BEGIN, clocktable
6623 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
6627 @vindex org-clocktable-defaults
6628 The @samp{BEGIN} line specifies a number of options to define the scope,
6629 structure, and formatting of the report. Defaults for all these options can
6630 be configured in the variable @code{org-clocktable-defaults}.
6632 @noindent First there are options that determine which clock entries are to
6635 :maxlevel @r{Maximum level depth to which times are listed in the table.}
6636 @r{Clocks at deeper levels will be summed into the upper level.}
6637 :scope @r{The scope to consider. This can be any of the following:}
6638 nil @r{the current buffer or narrowed region}
6639 file @r{the full current buffer}
6640 subtree @r{the subtree where the clocktable is located}
6641 tree@var{N} @r{the surrounding level @var{N} tree, for example @code{tree3}}
6642 tree @r{the surrounding level 1 tree}
6643 agenda @r{all agenda files}
6644 ("file"..) @r{scan these files}
6645 file-with-archives @r{current file and its archives}
6646 agenda-with-archives @r{all agenda files, including archives}
6647 :block @r{The time block to consider. This block is specified either}
6648 @r{absolutely, or relative to the current time and may be any of}
6650 2007-12-31 @r{New year eve 2007}
6651 2007-12 @r{December 2007}
6652 2007-W50 @r{ISO-week 50 in 2007}
6653 2007-Q2 @r{2nd quarter in 2007}
6654 2007 @r{the year 2007}
6655 today, yesterday, today-@var{N} @r{a relative day}
6656 thisweek, lastweek, thisweek-@var{N} @r{a relative week}
6657 thismonth, lastmonth, thismonth-@var{N} @r{a relative month}
6658 thisyear, lastyear, thisyear-@var{N} @r{a relative year}
6660 @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}
6661 :tstart @r{A time string specifying when to start considering times.}
6662 @r{Relative times like @code{"<-2w>"} can also be used. See}
6663 @r{@ref{Matching tags and properties} for relative time syntax.}
6664 :tend @r{A time string specifying when to stop considering times.}
6665 @r{Relative times like @code{"<now>"} can also be used. See}
6666 @r{@ref{Matching tags and properties} for relative time syntax.}
6667 :wstart @r{The starting day of the week. The default is 1 for monday.}
6668 :mstart @r{The starting day of the month. The default 1 is for the first}
6669 @r{day of the month.}
6670 :step @r{@code{week} or @code{day}, to split the table into chunks.}
6671 @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}
6672 :stepskip0 @r{Do not show steps that have zero time.}
6673 :fileskip0 @r{Do not show table sections from files which did not contribute.}
6674 :tags @r{A tags match to select entries that should contribute. See}
6675 @r{@ref{Matching tags and properties} for the match syntax.}
6678 Then there are options which determine the formatting of the table. These
6679 options are interpreted by the function @code{org-clocktable-write-default},
6680 but you can specify your own function using the @code{:formatter} parameter.
6682 :emphasize @r{When @code{t}, emphasize level one and level two items.}
6683 :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".}
6684 :link @r{Link the item headlines in the table to their origins.}
6685 :narrow @r{An integer to limit the width of the headline column in}
6686 @r{the org table. If you write it like @samp{50!}, then the}
6687 @r{headline will also be shortened in export.}
6688 :indent @r{Indent each headline field according to its level.}
6689 :tcolumns @r{Number of columns to be used for times. If this is smaller}
6690 @r{than @code{:maxlevel}, lower levels will be lumped into one column.}
6691 :level @r{Should a level number column be included?}
6692 :sort @r{A cons cell like containing the column to sort and a sorting type.}
6693 @r{E.g., @code{:sort (1 . ?a)} sorts the first column alphabetically.}
6694 :compact @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}}
6695 @r{All are overwritten except if there is an explicit @code{:narrow}}
6696 :timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,}
6697 @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}
6698 :properties @r{List of properties that should be shown in the table. Each}
6699 @r{property will get its own column.}
6700 :inherit-props @r{When this flag is @code{t}, the values for @code{:properties} will be inherited.}
6701 :formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.}
6702 @r{As a special case, @samp{:formula %} adds a column with % time.}
6703 @r{If you do not specify a formula here, any existing formula}
6704 @r{below the clock table will survive updates and be evaluated.}
6705 :formatter @r{A function to format clock data and insert it into the buffer.}
6707 To get a clock summary of the current level 1 tree, for the current
6708 day, you could write
6710 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
6714 and to use a specific time range you could write@footnote{Note that all
6715 parameters must be specified in a single line---the line is broken here
6716 only to fit it into the manual.}
6718 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
6719 :tend "<2006-08-10 Thu 12:00>"
6722 A range starting a week ago and ending right now could be written as
6724 #+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
6727 A summary of the current subtree with % times would be
6729 #+BEGIN: clocktable :scope subtree :link t :formula %
6732 A horizontally compact representation of everything clocked during last week
6735 #+BEGIN: clocktable :scope agenda :block lastweek :compact t
6739 @node Resolving idle time
6740 @subsection Resolving idle time and continuous clocking
6742 @subsubheading Resolving idle time
6743 @cindex resolve idle time
6744 @vindex org-clock-x11idle-program-name
6746 @cindex idle, resolve, dangling
6747 If you clock in on a work item, and then walk away from your
6748 computer---perhaps to take a phone call---you often need to ``resolve'' the
6749 time you were away by either subtracting it from the current clock, or
6750 applying it to another one.
6752 @vindex org-clock-idle-time
6753 By customizing the variable @code{org-clock-idle-time} to some integer, such
6754 as 10 or 15, Emacs can alert you when you get back to your computer after
6755 being idle for that many minutes@footnote{On computers using Mac OS X,
6756 idleness is based on actual user idleness, not just Emacs' idle time. For
6757 X11, you can install a utility program @file{x11idle.c}, available in the
6758 @code{contrib/scripts} directory of the Org git distribution, or install the
6759 @file{xprintidle} package and set it to the variable
6760 @code{org-clock-x11idle-program-name} if you are running Debian, to get the
6761 same general treatment of idleness. On other systems, idle time refers to
6762 Emacs idle time only.}, and ask what you want to do with the idle time.
6763 There will be a question waiting for you when you get back, indicating how
6764 much idle time has passed (constantly updated with the current amount), as
6765 well as a set of choices to correct the discrepancy:
6769 To keep some or all of the minutes and stay clocked in, press @kbd{k}. Org
6770 will ask how many of the minutes to keep. Press @key{RET} to keep them all,
6771 effectively changing nothing, or enter a number to keep that many minutes.
6773 If you use the shift key and press @kbd{K}, it will keep however many minutes
6774 you request and then immediately clock out of that task. If you keep all of
6775 the minutes, this is the same as just clocking out of the current task.
6777 To keep none of the minutes, use @kbd{s} to subtract all the away time from
6778 the clock, and then check back in from the moment you returned.
6780 To keep none of the minutes and just clock out at the start of the away time,
6781 use the shift key and press @kbd{S}. Remember that using shift will always
6782 leave you clocked out, no matter which option you choose.
6784 To cancel the clock altogether, use @kbd{C}. Note that if instead of
6785 canceling you subtract the away time, and the resulting clock amount is less
6786 than a minute, the clock will still be canceled rather than clutter up the
6787 log with an empty entry.
6790 What if you subtracted those away minutes from the current clock, and now
6791 want to apply them to a new clock? Simply clock in to any task immediately
6792 after the subtraction. Org will notice that you have subtracted time ``on
6793 the books'', so to speak, and will ask if you want to apply those minutes to
6794 the next task you clock in on.
6796 There is one other instance when this clock resolution magic occurs. Say you
6797 were clocked in and hacking away, and suddenly your cat chased a mouse who
6798 scared a hamster that crashed into your UPS's power button! You suddenly
6799 lose all your buffers, but thanks to auto-save you still have your recent Org
6800 mode changes, including your last clock in.
6802 If you restart Emacs and clock into any task, Org will notice that you have a
6803 dangling clock which was never clocked out from your last session. Using
6804 that clock's starting time as the beginning of the unaccounted-for period,
6805 Org will ask how you want to resolve that time. The logic and behavior is
6806 identical to dealing with away time due to idleness; it is just happening due
6807 to a recovery event rather than a set amount of idle time.
6809 You can also check all the files visited by your Org agenda for dangling
6810 clocks at any time using @kbd{M-x org-resolve-clocks RET} (or @kbd{C-c C-x C-z}).
6812 @subsubheading Continuous clocking
6813 @cindex continuous clocking
6814 @vindex org-clock-continuously
6816 You may want to start clocking from the time when you clocked out the
6817 previous task. To enable this systematically, set @code{org-clock-continuously}
6818 to @code{t}. Each time you clock in, Org retrieves the clock-out time of the
6819 last clocked entry for this session, and start the new clock from there.
6821 If you only want this from time to time, use three universal prefix arguments
6822 with @code{org-clock-in} and two @kbd{C-u C-u} with @code{org-clock-in-last}.
6824 @node Effort estimates
6825 @section Effort estimates
6826 @cindex effort estimates
6828 @cindex property, Effort
6829 If you want to plan your work in a very detailed way, or if you need to
6830 produce offers with quotations of the estimated work effort, you may want to
6831 assign effort estimates to entries. If you are also clocking your work, you
6832 may later want to compare the planned effort with the actual working time,
6833 a great way to improve planning estimates. Effort estimates are stored in
6834 a special property @code{EFFORT}. You can set the effort for an entry with
6835 the following commands:
6838 @orgcmd{C-c C-x e,org-set-effort}
6839 Set the effort estimate for the current entry. With a numeric prefix
6840 argument, set it to the Nth allowed value (see below). This command is also
6841 accessible from the agenda with the @kbd{e} key.
6842 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6843 Modify the effort estimate of the item currently being clocked.
6846 Clearly the best way to work with effort estimates is through column view
6847 (@pxref{Column view}). You should start by setting up discrete values for
6848 effort estimates, and a @code{COLUMNS} format that displays these values
6849 together with clock sums (if you want to clock your time). For a specific
6853 #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
6854 #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM
6858 @vindex org-global-properties
6859 @vindex org-columns-default-format
6860 or, even better, you can set up these values globally by customizing the
6861 variables @code{org-global-properties} and @code{org-columns-default-format}.
6862 In particular if you want to use this setup also in the agenda, a global
6863 setup may be advised.
6865 The way to assign estimates to individual items is then to switch to column
6866 mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the
6867 value. The values you enter will immediately be summed up in the hierarchy.
6868 In the column next to it, any clocked time will be displayed.
6870 @vindex org-agenda-columns-add-appointments-to-effort-sum
6871 If you switch to column view in the daily/weekly agenda, the effort column
6872 will summarize the estimated work effort for each day@footnote{Please note
6873 the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda
6874 column view}).}, and you can use this to find space in your schedule. To get
6875 an overview of the entire part of the day that is committed, you can set the
6876 option @code{org-agenda-columns-add-appointments-to-effort-sum}. The
6877 appointments on a day that take place over a specified time interval will
6878 then also be added to the load estimate of the day.
6880 Effort estimates can be used in secondary agenda filtering that is triggered
6881 with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have
6882 these estimates defined consistently, two or three key presses will narrow
6883 down the list to stuff that fits into an available time slot.
6886 @section Taking notes with a timer
6887 @cindex relative timer
6888 @cindex countdown timer
6891 Org provides two types of timers. There is a relative timer that counts up,
6892 which can be useful when taking notes during, for example, a meeting or
6893 a video viewing. There is also a countdown timer.
6895 The relative and countdown are started with separate commands.
6898 @orgcmd{C-c C-x 0,org-timer-start}
6899 Start or reset the relative timer. By default, the timer is set to 0. When
6900 called with a @kbd{C-u} prefix, prompt the user for a starting offset. If
6901 there is a timer string at point, this is taken as the default, providing a
6902 convenient way to restart taking notes after a break in the process. When
6903 called with a double prefix argument @kbd{C-u C-u}, change all timer strings
6904 in the active region by a certain amount. This can be used to fix timer
6905 strings if the timer was not started at exactly the right moment.
6906 @orgcmd{C-c C-x ;,org-timer-set-timer}
6907 Start a countdown timer. The user is prompted for a duration.
6908 @code{org-timer-default-timer} sets the default countdown value. Giving
6909 a numeric prefix argument overrides this default value. This command is
6910 available as @kbd{;} in agenda buffers.
6913 Once started, relative and countdown timers are controlled with the same
6917 @orgcmd{C-c C-x .,org-timer}
6918 Insert the value of the current relative or countdown timer into the buffer.
6919 If no timer is running, the relative timer will be started. When called with
6920 a prefix argument, the relative timer is restarted.
6921 @orgcmd{C-c C-x -,org-timer-item}
6922 Insert a description list item with the value of the current relative or
6923 countdown timer. With a prefix argument, first reset the relative timer to
6925 @orgcmd{M-@key{RET},org-insert-heading}
6926 Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert
6928 @orgcmd{C-c C-x @comma{},org-timer-pause-or-continue}
6929 Pause the timer, or continue it if it is already paused.
6930 @orgcmd{C-c C-x _,org-timer-stop}
6931 Stop the timer. After this, you can only start a new timer, not continue the
6932 old one. This command also removes the timer from the mode line.
6935 @node Capture - Refile - Archive
6936 @chapter Capture - Refile - Archive
6939 An important part of any organization system is the ability to quickly
6940 capture new ideas and tasks, and to associate reference material with them.
6941 Org does this using a process called @i{capture}. It also can store files
6942 related to a task (@i{attachments}) in a special directory. Once in the
6943 system, tasks and projects need to be moved around. Moving completed project
6944 trees to an archive file keeps the system compact and fast.
6947 * Capture:: Capturing new stuff
6948 * Attachments:: Add files to tasks
6949 * RSS feeds:: Getting input from RSS feeds
6950 * Protocols:: External (e.g., Browser) access to Emacs and Org
6951 * Refile and copy:: Moving/copying a tree from one place to another
6952 * Archiving:: What to do with finished projects
6959 Capture lets you quickly store notes with little interruption of your work
6960 flow. Org's method for capturing new items is heavily inspired by John
6961 Wiegley excellent @file{remember.el} package. Up to version 6.36, Org
6962 used a special setup for @file{remember.el}, then replaced it with
6963 @file{org-remember.el}. As of version 8.0, @file{org-remember.el} has
6964 been completely replaced by @file{org-capture.el}.
6966 If your configuration depends on @file{org-remember.el}, you need to update
6967 it and use the setup described below. To convert your
6968 @code{org-remember-templates}, run the command
6970 @kbd{M-x org-capture-import-remember-templates RET}
6972 @noindent and then customize the new variable with @kbd{M-x
6973 customize-variable org-capture-templates}, check the result, and save the
6977 * Setting up capture:: Where notes will be stored
6978 * Using capture:: Commands to invoke and terminate capture
6979 * Capture templates:: Define the outline of different note types
6982 @node Setting up capture
6983 @subsection Setting up capture
6985 The following customization sets a default target file for notes, and defines
6986 a global key@footnote{Please select your own key, @kbd{C-c c} is only a
6987 suggestion.} for capturing new material.
6989 @vindex org-default-notes-file
6992 (setq org-default-notes-file (concat org-directory "/notes.org"))
6993 (define-key global-map "\C-cc" 'org-capture)
6998 @subsection Using capture
7001 @orgcmd{C-c c,org-capture}
7002 Call the command @code{org-capture}. Note that this key binding is global and
7003 not active by default: you need to install it. If you have templates
7005 defined @pxref{Capture templates}, it will offer these templates for
7006 selection or use a new Org outline node as the default template. It will
7007 insert the template into the target file and switch to an indirect buffer
7008 narrowed to this new node. You may then insert the information you want.
7010 @orgcmd{C-c C-c,org-capture-finalize}
7011 Once you have finished entering information into the capture buffer, @kbd{C-c
7012 C-c} will return you to the window configuration before the capture process,
7013 so that you can resume your work without further distraction. When called
7014 with a prefix arg, finalize and then jump to the captured item.
7016 @orgcmd{C-c C-w,org-capture-refile}
7017 Finalize the capture process by refiling (@pxref{Refile and copy}) the note to
7018 a different place. Please realize that this is a normal refiling command
7019 that will be executed---so the cursor position at the moment you run this
7020 command is important. If you have inserted a tree with a parent and
7021 children, first move the cursor back to the parent. Any prefix argument
7022 given to this command will be passed on to the @code{org-refile} command.
7024 @orgcmd{C-c C-k,org-capture-kill}
7025 Abort the capture process and return to the previous state.
7029 You can also call @code{org-capture} in a special way from the agenda, using
7030 the @kbd{k c} key combination. With this access, any timestamps inserted by
7031 the selected capture template will default to the cursor date in the agenda,
7032 rather than to the current date.
7034 To find the locations of the last stored capture, use @code{org-capture} with
7039 Visit the target location of a capture template. You get to select the
7040 template in the usual way.
7041 @orgkey{C-u C-u C-c c}
7042 Visit the last stored capture item in its buffer.
7045 @vindex org-capture-bookmark
7046 @cindex org-capture-last-stored
7047 You can also jump to the bookmark @code{org-capture-last-stored}, which will
7048 automatically be created unless you set @code{org-capture-bookmark} to
7051 To insert the capture at point in an Org buffer, call @code{org-capture} with
7052 a @code{C-0} prefix argument.
7054 @node Capture templates
7055 @subsection Capture templates
7056 @cindex templates, for Capture
7058 You can use templates for different types of capture items, and
7059 for different target locations. The easiest way to create such templates is
7060 through the customize interface.
7064 Customize the variable @code{org-capture-templates}.
7067 Before we give the formal description of template definitions, let's look at
7068 an example. Say you would like to use one template to create general TODO
7069 entries, and you want to put these entries under the heading @samp{Tasks} in
7070 your file @file{~/org/gtd.org}. Also, a date tree in the file
7071 @file{journal.org} should capture journal entries. A possible configuration
7076 (setq org-capture-templates
7077 '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
7078 "* TODO %?\n %i\n %a")
7079 ("j" "Journal" entry (file+datetree "~/org/journal.org")
7080 "* %?\nEntered on %U\n %i\n %a")))
7084 @noindent If you then press @kbd{C-c c t}, Org will prepare the template
7088 [[file:@var{link to where you initiated capture}]]
7092 During expansion of the template, @code{%a} has been replaced by a link to
7093 the location from where you called the capture command. This can be
7094 extremely useful for deriving tasks from emails, for example. You fill in
7095 the task definition, press @kbd{C-c C-c} and Org returns you to the same
7096 place where you started the capture process.
7098 To define special keys to capture to a particular template without going
7099 through the interactive template selection, you can create your key binding
7103 (define-key global-map "\C-cx"
7104 (lambda () (interactive) (org-capture nil "x")))
7108 * Template elements:: What is needed for a complete template entry
7109 * Template expansion:: Filling in information about time and context
7110 * Templates in contexts:: Only show a template in a specific context
7113 @node Template elements
7114 @subsubsection Template elements
7116 Now lets look at the elements of a template definition. Each entry in
7117 @code{org-capture-templates} is a list with the following items:
7121 The keys that will select the template, as a string, characters
7122 only, for example @code{"a"} for a template to be selected with a
7123 single key, or @code{"bt"} for selection with two keys. When using
7124 several keys, keys using the same prefix key must be sequential
7125 in the list and preceded by a 2-element entry explaining the
7126 prefix key, for example
7128 ("b" "Templates for marking stuff to buy")
7130 @noindent If you do not define a template for the @kbd{C} key, this key will
7131 be used to open the customize buffer for this complex variable.
7134 A short string describing the template, which will be shown during
7138 The type of entry, a symbol. Valid values are:
7142 An Org mode node, with a headline. Will be filed as the child of the target
7143 entry or as a top-level entry. The target file should be an Org mode file.
7145 A plain list item, placed in the first plain list at the target
7146 location. Again the target file should be an Org file.
7148 A checkbox item. This only differs from the plain list item by the
7151 a new line in the first table at the target location. Where exactly the
7152 line will be inserted depends on the properties @code{:prepend} and
7153 @code{:table-line-pos} (see below).
7155 Text to be inserted as it is.
7159 @vindex org-default-notes-file
7160 Specification of where the captured item should be placed. In Org mode
7161 files, targets usually define a node. Entries will become children of this
7162 node. Other types will be added to the table or list in the body of this
7163 node. Most target specifications contain a file name. If that file name is
7164 the empty string, it defaults to @code{org-default-notes-file}. A file can
7165 also be given as a variable or as a function called with no argument. When
7166 an absolute path is not specified for a target, it is taken as relative to
7167 @code{org-directory}.
7172 @item (file "path/to/file")
7173 Text will be placed at the beginning or end of that file.
7175 @item (id "id of existing org entry")
7176 Filing as child of this entry, or in the body of the entry.
7178 @item (file+headline "path/to/file" "node headline")
7179 Fast configuration if the target heading is unique in the file.
7181 @item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
7182 For non-unique headings, the full path is safer.
7184 @item (file+regexp "path/to/file" "regexp to find location")
7185 Use a regular expression to position the cursor.
7187 @item (file+datetree "path/to/file")
7188 Will create a heading in a date tree for today's date@footnote{Datetree
7189 headlines for years accept tags, so if you use both @code{* 2013 :noexport:}
7190 and @code{* 2013} in your file, the capture will refile the note to the first
7193 @item (file+datetree+prompt "path/to/file")
7194 Will create a heading in a date tree, but will prompt for the date.
7196 @item (file+weektree "path/to/file")
7197 Will create a heading in a week tree for today's date. Week trees are sorted
7198 by week and not by month unlike datetrees.
7200 @item (file+weektree+prompt "path/to/file")
7201 Will create a heading in a week tree, but will prompt for the date.
7203 @item (file+function "path/to/file" function-finding-location)
7204 A function to find the right location in the file.
7207 File to the entry that is currently being clocked.
7209 @item (function function-finding-location)
7210 Most general way: write your own function which both visits
7211 the file and moves point to the right location.
7215 The template for creating the capture item. If you leave this empty, an
7216 appropriate default template will be used. Otherwise this is a string with
7217 escape codes, which will be replaced depending on time and context of the
7218 capture call. The string with escapes may be loaded from a template file,
7219 using the special syntax @code{(file "path/to/template")}. See below for
7223 The rest of the entry is a property list of additional options.
7224 Recognized properties are:
7228 Normally new captured information will be appended at
7229 the target location (last child, last table line, last list item...).
7230 Setting this property will change that.
7232 @item :immediate-finish
7233 When set, do not offer to edit the information, just
7234 file it away immediately. This makes sense if the template only needs
7235 information that can be added automatically.
7238 Set this to the number of lines to insert
7239 before and after the new item. Default 0, only common other value is 1.
7242 Start the clock in this item.
7245 Keep the clock running when filing the captured entry.
7248 If starting the capture interrupted a clock, restart that clock when finished
7249 with the capture. Note that @code{:clock-keep} has precedence over
7250 @code{:clock-resume}. When setting both to @code{t}, the current clock will
7251 run and the previous one will not be resumed.
7254 Do not narrow the target buffer, simply show the full buffer. Default is to
7255 narrow it so that you only see the new material.
7257 @item :table-line-pos
7258 Specification of the location in the table where the new line should be
7259 inserted. It can be a string, a variable holding a string or a function
7260 returning a string. The string should look like @code{"II-3"} meaning that
7261 the new line should become the third line before the second horizontal
7265 If the target file was not yet visited when capture was invoked, kill the
7266 buffer again after capture is completed.
7270 @node Template expansion
7271 @subsubsection Template expansion
7273 In the template itself, special @kbd{%}-escapes@footnote{If you need one of
7274 these sequences literally, escape the @kbd{%} with a backslash.} allow
7275 dynamic insertion of content. The templates are expanded in the order given here:
7278 %[@var{file}] @r{Insert the contents of the file given by @var{file}.}
7279 %(@var{sexp}) @r{Evaluate Elisp @var{sexp} and replace with the result.}
7280 @r{For convenience, %:keyword (see below) placeholders}
7281 @r{within the expression will be expanded prior to this.}
7282 @r{The sexp must return a string.}
7283 %<...> @r{The result of format-time-string on the ... format specification.}
7284 %t @r{Timestamp, date only.}
7285 %T @r{Timestamp, with date and time.}
7286 %u, %U @r{Like the above, but inactive timestamps.}
7287 %i @r{Initial content, the region when capture is called while the}
7288 @r{region is active.}
7289 @r{The entire text will be indented like @code{%i} itself.}
7290 %a @r{Annotation, normally the link created with @code{org-store-link}.}
7291 %A @r{Like @code{%a}, but prompt for the description part.}
7292 %l @r{Like %a, but only insert the literal link.}
7293 %c @r{Current kill ring head.}
7294 %x @r{Content of the X clipboard.}
7295 %k @r{Title of the currently clocked task.}
7296 %K @r{Link to the currently clocked task.}
7297 %n @r{User name (taken from @code{user-full-name}).}
7298 %f @r{File visited by current buffer when org-capture was called.}
7299 %F @r{Full path of the file or directory visited by current buffer.}
7300 %:keyword @r{Specific information for certain link types, see below.}
7301 %^g @r{Prompt for tags, with completion on tags in target file.}
7302 %^G @r{Prompt for tags, with completion all tags in all agenda files.}
7303 %^t @r{Like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}.}
7304 @r{You may define a prompt like @code{%^@{Birthday@}t}.}
7305 %^C @r{Interactive selection of which kill or clip to use.}
7306 %^L @r{Like @code{%^C}, but insert as link.}
7307 %^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}.}
7308 %^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.}
7309 @r{You may specify a default value and a completion table with}
7310 @r{%^@{prompt|default|completion2|completion3...@}.}
7311 @r{The arrow keys access a prompt-specific history.}
7312 %\1 @dots{} %\N @r{Insert the text entered at the Nth %^@{@var{prompt}@}, where @code{N} is}
7313 @r{a number, starting from 1.}
7314 %? @r{After completing the template, position cursor here.}
7318 For specific link types, the following keywords will be
7319 defined@footnote{If you define your own link types (@pxref{Adding
7320 hyperlink types}), any property you store with
7321 @code{org-store-link-props} can be accessed in capture templates in a
7324 @vindex org-from-is-user-regexp
7326 Link type | Available keywords
7327 ---------------------------------+----------------------------------------------
7328 bbdb | %:name %:company
7329 irc | %:server %:port %:nick
7330 vm, vm-imap, wl, mh, mew, rmail, | %:type %:subject %:message-id
7331 gnus, notmuch | %:from %:fromname %:fromaddress
7332 | %:to %:toname %:toaddress
7333 | %:date @r{(message date header field)}
7334 | %:date-timestamp @r{(date as active timestamp)}
7335 | %:date-timestamp-inactive @r{(date as inactive timestamp)}
7336 | %: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}.}}
7337 gnus | %:group, @r{for messages also all email fields}
7338 eww, w3, w3m | %:url
7339 info | %:file %:node
7344 To place the cursor after template expansion use:
7347 %? @r{After completing the template, position cursor here.}
7350 @node Templates in contexts
7351 @subsubsection Templates in contexts
7353 @vindex org-capture-templates-contexts
7354 To control whether a capture template should be accessible from a specific
7355 context, you can customize @code{org-capture-templates-contexts}. Let's say
7356 for example that you have a capture template @code{"p"} for storing Gnus
7357 emails containing patches. Then you would configure this option like this:
7360 (setq org-capture-templates-contexts
7361 '(("p" (in-mode . "message-mode"))))
7364 You can also tell that the command key @code{"p"} should refer to another
7365 template. In that case, add this command key like this:
7368 (setq org-capture-templates-contexts
7369 '(("p" "q" (in-mode . "message-mode"))))
7372 See the docstring of the variable for more information.
7375 @section Attachments
7378 @vindex org-attach-directory
7379 It is often useful to associate reference material with an outline node/task.
7380 Small chunks of plain text can simply be stored in the subtree of a project.
7381 Hyperlinks (@pxref{Hyperlinks}) can establish associations with
7382 files that live elsewhere on your computer or in the cloud, like emails or
7383 source code files belonging to a project. Another method is @i{attachments},
7384 which are files located in a directory belonging to an outline node. Org
7385 uses directories named by the unique ID of each entry. These directories are
7386 located in the @file{data} directory which lives in the same directory where
7387 your Org file lives@footnote{If you move entries or Org files from one
7388 directory to another, you may want to configure @code{org-attach-directory}
7389 to contain an absolute path.}. If you initialize this directory with
7390 @code{git init}, Org will automatically commit changes when it sees them.
7391 The attachment system has been contributed to Org by John Wiegley.
7393 In cases where it seems better to do so, you can also attach a directory of your
7394 choice to an entry. You can also make children inherit the attachment
7395 directory from a parent, so that an entire subtree uses the same attached
7398 @noindent The following commands deal with attachments:
7401 @orgcmd{C-c C-a,org-attach}
7402 The dispatcher for commands related to the attachment system. After these
7403 keys, a list of commands is displayed and you must press an additional key
7404 to select a command:
7407 @orgcmdtkc{a,C-c C-a a,org-attach-attach}
7408 @vindex org-attach-method
7409 Select a file and move it into the task's attachment directory. The file
7410 will be copied, moved, or linked, depending on @code{org-attach-method}.
7411 Note that hard links are not supported on all systems.
7417 Attach a file using the copy/move/link method.
7418 Note that hard links are not supported on all systems.
7420 @orgcmdtkc{n,C-c C-a n,org-attach-new}
7421 Create a new attachment as an Emacs buffer.
7423 @orgcmdtkc{z,C-c C-a z,org-attach-sync}
7424 Synchronize the current task with its attachment directory, in case you added
7425 attachments yourself.
7427 @orgcmdtkc{o,C-c C-a o,org-attach-open}
7428 @vindex org-file-apps
7429 Open current task's attachment. If there is more than one, prompt for a
7430 file name first. Opening will follow the rules set by @code{org-file-apps}.
7431 For more details, see the information on following hyperlinks
7432 (@pxref{Handling links}).
7434 @orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs}
7435 Also open the attachment, but force opening the file in Emacs.
7437 @orgcmdtkc{f,C-c C-a f,org-attach-reveal}
7438 Open the current task's attachment directory.
7440 @orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs}
7441 Also open the directory, but force using @command{dired} in Emacs.
7443 @orgcmdtkc{d,C-c C-a d,org-attach-delete-one}
7444 Select and delete a single attachment.
7446 @orgcmdtkc{D,C-c C-a D,org-attach-delete-all}
7447 Delete all of a task's attachments. A safer way is to open the directory in
7448 @command{dired} and delete from there.
7450 @orgcmdtkc{s,C-c C-a s,org-attach-set-directory}
7451 @cindex property, ATTACH_DIR
7452 Set a specific directory as the entry's attachment directory. This works by
7453 putting the directory path into the @code{ATTACH_DIR} property.
7455 @orgcmdtkc{i,C-c C-a i,org-attach-set-inherit}
7456 @cindex property, ATTACH_DIR_INHERIT
7457 Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the
7458 same directory for attachments as the parent does.
7467 Org can add and change entries based on information found in RSS feeds and
7468 Atom feeds. You could use this to make a task out of each new podcast in a
7469 podcast feed. Or you could use a phone-based note-creating service on the
7470 web to import tasks into Org. To access feeds, configure the variable
7471 @code{org-feed-alist}. The docstring of this variable has detailed
7472 information. Here is just an example:
7476 (setq org-feed-alist
7478 "http://rss.slashdot.org/Slashdot/slashdot"
7479 "~/txt/org/feeds.org" "Slashdot Entries")))
7484 will configure that new items from the feed provided by
7485 @code{rss.slashdot.org} will result in new entries in the file
7486 @file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
7487 the following command is used:
7490 @orgcmd{C-c C-x g,org-feed-update-all}
7492 Collect items from the feeds configured in @code{org-feed-alist} and act upon
7494 @orgcmd{C-c C-x G,org-feed-goto-inbox}
7495 Prompt for a feed name and go to the inbox configured for this feed.
7498 Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which
7499 it will store information about the status of items in the feed, to avoid
7500 adding the same item several times.
7502 For more information, including how to read atom feeds, see
7503 @file{org-feed.el} and the docstring of @code{org-feed-alist}.
7506 @section Protocols for external access
7507 @cindex protocols, for external access
7510 You can set up Org for handling protocol calls from outside applications that
7511 are passed to Emacs through the @file{emacsserver}. For example, you can
7512 configure bookmarks in your web browser to send a link to the current page to
7513 Org and create a note from it using capture (@pxref{Capture}). Or you
7514 could create a bookmark that will tell Emacs to open the local source file of
7515 a remote website you are looking at with the browser. See
7516 @uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed
7517 documentation and setup instructions.
7519 @node Refile and copy
7520 @section Refile and copy
7521 @cindex refiling notes
7522 @cindex copying notes
7524 When reviewing the captured data, you may want to refile or to copy some of
7525 the entries into a different list, for example into a project. Cutting,
7526 finding the right location, and then pasting the note is cumbersome. To
7527 simplify this process, you can use the following special command:
7530 @orgcmd{C-c M-w,org-copy}
7532 Copying works like refiling, except that the original note is not deleted.
7533 @orgcmd{C-c C-w,org-refile}
7535 @vindex org-reverse-note-order
7536 @vindex org-refile-targets
7537 @vindex org-refile-use-outline-path
7538 @vindex org-outline-path-complete-in-steps
7539 @vindex org-refile-allow-creating-parent-nodes
7540 @vindex org-log-refile
7541 @vindex org-refile-use-cache
7542 @vindex org-refile-keep
7543 Refile the entry or region at point. This command offers possible locations
7544 for refiling the entry and lets you select one with completion. The item (or
7545 all items in the region) is filed below the target heading as a subitem.
7546 Depending on @code{org-reverse-note-order}, it will be either the first or
7548 By default, all level 1 headlines in the current buffer are considered to be
7549 targets, but you can have more complex definitions across a number of files.
7550 See the variable @code{org-refile-targets} for details. If you would like to
7551 select a location via a file-path-like completion along the outline path, see
7552 the variables @code{org-refile-use-outline-path} and
7553 @code{org-outline-path-complete-in-steps}. If you would like to be able to
7554 create new nodes as new parents for refiling on the fly, check the
7555 variable @code{org-refile-allow-creating-parent-nodes}.
7556 When the variable @code{org-log-refile}@footnote{with corresponding
7557 @code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},
7558 and @code{nologrefile}} is set, a timestamp or a note will be
7559 recorded when an entry has been refiled.
7560 @orgkey{C-u C-c C-w}
7561 Use the refile interface to jump to a heading.
7562 @orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored}
7563 Jump to the location where @code{org-refile} last moved a tree to.
7565 Refile as the child of the item currently being clocked.
7567 Refile and keep the entry in place. Also see @code{org-refile-keep} to make
7568 this the default behavior, and beware that this may result in duplicated
7569 @code{ID} properties.
7570 @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}
7571 Clear the target cache. Caching of refile targets can be turned on by
7572 setting @code{org-refile-use-cache}. To make the command see new possible
7573 targets, you have to clear the cache with this command.
7580 When a project represented by a (sub)tree is finished, you may want
7581 to move the tree out of the way and to stop it from contributing to the
7582 agenda. Archiving is important to keep your working files compact and global
7583 searches like the construction of agenda views fast.
7586 @orgcmd{C-c C-x C-a,org-archive-subtree-default}
7587 @vindex org-archive-default-command
7588 Archive the current entry using the command specified in the variable
7589 @code{org-archive-default-command}.
7593 * Moving subtrees:: Moving a tree to an archive file
7594 * Internal archiving:: Switch off a tree but keep it in the file
7597 @node Moving subtrees
7598 @subsection Moving a tree to the archive file
7599 @cindex external archiving
7601 The most common archiving action is to move a project tree to another file,
7605 @orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
7606 @vindex org-archive-location
7607 Archive the subtree starting at the cursor position to the location
7608 given by @code{org-archive-location}.
7609 @orgkey{C-u C-c C-x C-s}
7610 Check if any direct children of the current headline could be moved to
7611 the archive. To do this, each subtree is checked for open TODO entries.
7612 If none are found, the command offers to move it to the archive
7613 location. If the cursor is @emph{not} on a headline when this command
7614 is invoked, the level 1 trees will be checked.
7615 @orgkey{C-u C-u C-c C-x C-s}
7616 As above, but check subtree for timestamps instead of TODO entries. The
7617 command will offer to archive the subtree if it @emph{does} contain a
7618 timestamp, and that timestamp is in the past.
7621 @cindex archive locations
7622 The default archive location is a file in the same directory as the
7623 current file, with the name derived by appending @file{_archive} to the
7624 current file name. You can also choose what heading to file archived
7625 items under, with the possibility to add them to a datetree in a file.
7626 For information and examples on how to specify the file and the heading,
7627 see the documentation string of the variable
7628 @code{org-archive-location}.
7630 There is also an in-buffer option for setting this variable, for example:
7634 #+ARCHIVE: %s_done::
7637 @cindex property, ARCHIVE
7639 If you would like to have a special ARCHIVE location for a single entry
7640 or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
7641 location as the value (@pxref{Properties and columns}).
7643 @vindex org-archive-save-context-info
7644 When a subtree is moved, it receives a number of special properties that
7645 record context information like the file from where the entry came, its
7646 outline path the archiving time etc. Configure the variable
7647 @code{org-archive-save-context-info} to adjust the amount of information
7651 @node Internal archiving
7652 @subsection Internal archiving
7655 If you want to just switch off---for agenda views---certain subtrees without
7656 moving them to a different file, you can use the archive tag.
7658 A headline that is marked with the @samp{:ARCHIVE:} tag (@pxref{Tags}) stays
7659 at its location in the outline tree, but behaves in the following way:
7662 @vindex org-cycle-open-archived-trees
7663 It does not open when you attempt to do so with a visibility cycling
7664 command (@pxref{Visibility cycling}). You can force cycling archived
7665 subtrees with @kbd{C-@key{TAB}}, or by setting the option
7666 @code{org-cycle-open-archived-trees}. Also normal outline commands like
7667 @code{show-all} will open archived subtrees.
7669 @vindex org-sparse-tree-open-archived-trees
7670 During sparse tree construction (@pxref{Sparse trees}), matches in
7671 archived subtrees are not exposed, unless you configure the option
7672 @code{org-sparse-tree-open-archived-trees}.
7674 @vindex org-agenda-skip-archived-trees
7675 During agenda view construction (@pxref{Agenda views}), the content of
7676 archived trees is ignored unless you configure the option
7677 @code{org-agenda-skip-archived-trees}, in which case these trees will always
7678 be included. In the agenda you can press @kbd{v a} to get archives
7679 temporarily included.
7681 @vindex org-export-with-archived-trees
7682 Archived trees are not exported (@pxref{Exporting}), only the headline
7683 is. Configure the details using the variable
7684 @code{org-export-with-archived-trees}.
7686 @vindex org-columns-skip-archived-trees
7687 Archived trees are excluded from column view unless the variable
7688 @code{org-columns-skip-archived-trees} is configured to @code{nil}.
7691 The following commands help manage the ARCHIVE tag:
7694 @orgcmd{C-c C-x a,org-toggle-archive-tag}
7695 Toggle the ARCHIVE tag for the current headline. When the tag is set,
7696 the headline changes to a shadowed face, and the subtree below it is
7698 @orgkey{C-u C-c C-x a}
7699 Check if any direct children of the current headline should be archived.
7700 To do this, each subtree is checked for open TODO entries. If none are
7701 found, the command offers to set the ARCHIVE tag for the child. If the
7702 cursor is @emph{not} on a headline when this command is invoked, the
7703 level 1 trees will be checked.
7704 @orgcmd{C-@kbd{TAB},org-force-cycle-archived}
7705 Cycle a tree even if it is tagged with ARCHIVE.
7706 @orgcmd{C-c C-x A,org-archive-to-archive-sibling}
7707 Move the current entry to the @emph{Archive Sibling}. This is a sibling of
7708 the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The
7709 entry becomes a child of that sibling and in this way retains a lot of its
7710 original context, including inherited tags and approximate position in the
7716 @chapter Agenda views
7717 @cindex agenda views
7719 Due to the way Org works, TODO items, time-stamped items, and
7720 tagged headlines can be scattered throughout a file or even a number of
7721 files. To get an overview of open action items, or of events that are
7722 important for a particular date, this information must be collected,
7723 sorted and displayed in an organized way.
7725 Org can select items based on various criteria and display them
7726 in a separate buffer. Seven different view types are provided:
7730 an @emph{agenda} that is like a calendar and shows information
7733 a @emph{TODO list} that covers all unfinished
7736 a @emph{match view}, showings headlines based on the tags, properties, and
7737 TODO state associated with them,
7739 a @emph{timeline view} that shows all events in a single Org file,
7740 in time-sorted view,
7742 a @emph{text search view} that shows all entries from multiple files
7743 that contain specified keywords,
7745 a @emph{stuck projects view} showing projects that currently don't move
7748 @emph{custom views} that are special searches and combinations of different
7753 The extracted information is displayed in a special @emph{agenda
7754 buffer}. This buffer is read-only, but provides commands to visit the
7755 corresponding locations in the original Org files, and even to
7756 edit these files remotely.
7758 @vindex org-agenda-skip-comment-trees
7759 @vindex org-agenda-skip-archived-trees
7760 @cindex commented entries, in agenda views
7761 @cindex archived entries, in agenda views
7762 By default, the report ignores commented (@pxref{Comment lines}) and archived
7763 (@pxref{Internal archiving}) entries. You can override this by setting
7764 @code{org-agenda-skip-comment-trees} and
7765 @code{org-agenda-skip-archived-trees} to @code{nil}.
7767 @vindex org-agenda-window-setup
7768 @vindex org-agenda-restore-windows-after-quit
7769 Two variables control how the agenda buffer is displayed and whether the
7770 window configuration is restored when the agenda exits:
7771 @code{org-agenda-window-setup} and
7772 @code{org-agenda-restore-windows-after-quit}.
7775 * Agenda files:: Files being searched for agenda information
7776 * Agenda dispatcher:: Keyboard access to agenda views
7777 * Built-in agenda views:: What is available out of the box?
7778 * Presentation and sorting:: How agenda items are prepared for display
7779 * Agenda commands:: Remote editing of Org trees
7780 * Custom agenda views:: Defining special searches and views
7781 * Exporting agenda views:: Writing a view to a file
7782 * Agenda column view:: Using column view for collected entries
7786 @section Agenda files
7787 @cindex agenda files
7788 @cindex files for agenda
7790 @vindex org-agenda-files
7791 The information to be shown is normally collected from all @emph{agenda
7792 files}, the files listed in the variable
7793 @code{org-agenda-files}@footnote{If the value of that variable is not a
7794 list, but a single file name, then the list of agenda files will be
7795 maintained in that external file.}. If a directory is part of this list,
7796 all files with the extension @file{.org} in this directory will be part
7799 Thus, even if you only work with a single Org file, that file should
7800 be put into the list@footnote{When using the dispatcher, pressing
7801 @kbd{<} before selecting a command will actually limit the command to
7802 the current file, and ignore @code{org-agenda-files} until the next
7803 dispatcher command.}. You can customize @code{org-agenda-files}, but
7804 the easiest way to maintain it is through the following commands
7806 @cindex files, adding to agenda list
7808 @orgcmd{C-c [,org-agenda-file-to-front}
7809 Add current file to the list of agenda files. The file is added to
7810 the front of the list. If it was already in the list, it is moved to
7811 the front. With a prefix argument, file is added/moved to the end.
7812 @orgcmd{C-c ],org-remove-file}
7813 Remove current file from the list of agenda files.
7815 @cindex cycling, of agenda files
7816 @orgcmd{C-',org-cycle-agenda-files}
7818 Cycle through agenda file list, visiting one file after the other.
7819 @kindex M-x org-iswitchb
7820 @item M-x org-iswitchb RET
7821 Command to use an @code{iswitchb}-like interface to switch to and between Org
7826 The Org menu contains the current list of files and can be used
7827 to visit any of them.
7829 If you would like to focus the agenda temporarily on a file not in
7830 this list, or on just one file in the list, or even on only a subtree in a
7831 file, then this can be done in different ways. For a single agenda command,
7832 you may press @kbd{<} once or several times in the dispatcher
7833 (@pxref{Agenda dispatcher}). To restrict the agenda scope for an
7834 extended period, use the following commands:
7837 @orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
7838 Permanently restrict the agenda to the current subtree. When with a
7839 prefix argument, or with the cursor before the first headline in a file,
7840 the agenda scope is set to the entire file. This restriction remains in
7841 effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
7842 or @kbd{>} in the agenda dispatcher. If there is a window displaying an
7843 agenda view, the new restriction takes effect immediately.
7844 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
7845 Remove the permanent restriction created by @kbd{C-c C-x <}.
7849 When working with @file{speedbar.el}, you can use the following commands in
7853 @orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
7854 Permanently restrict the agenda to the item---either an Org file or a subtree
7855 in such a file---at the cursor in the Speedbar frame.
7856 If there is a window displaying an agenda view, the new restriction takes
7858 @orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
7859 Lift the restriction.
7862 @node Agenda dispatcher
7863 @section The agenda dispatcher
7864 @cindex agenda dispatcher
7865 @cindex dispatching agenda commands
7866 The views are created through a dispatcher, which should be bound to a
7867 global key---for example @kbd{C-c a} (@pxref{Activation}). In the
7868 following we will assume that @kbd{C-c a} is indeed how the dispatcher
7869 is accessed and list keyboard access to commands accordingly. After
7870 pressing @kbd{C-c a}, an additional letter is required to execute a
7871 command. The dispatcher offers the following default commands:
7875 Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
7877 Create a list of all TODO items (@pxref{Global TODO list}).
7879 Create a list of headlines matching a TAGS expression (@pxref{Matching
7880 tags and properties}).
7882 Create the timeline view for the current buffer (@pxref{Timeline}).
7884 Create a list of entries selected by a boolean expression of keywords
7885 and/or regular expressions that must or must not occur in the entry.
7887 @vindex org-agenda-text-search-extra-files
7888 Search for a regular expression in all agenda files and additionally in
7889 the files listed in @code{org-agenda-text-search-extra-files}. This
7890 uses the Emacs command @code{multi-occur}. A prefix argument can be
7891 used to specify the number of context lines for each match, default is
7894 Create a list of stuck projects (@pxref{Stuck projects}).
7896 Restrict an agenda command to the current buffer@footnote{For backward
7897 compatibility, you can also press @kbd{1} to restrict to the current
7898 buffer.}. After pressing @kbd{<}, you still need to press the character
7899 selecting the command.
7901 If there is an active region, restrict the following agenda command to
7902 the region. Otherwise, restrict it to the current subtree@footnote{For
7903 backward compatibility, you can also press @kbd{0} to restrict to the
7904 current region/subtree.}. After pressing @kbd{< <}, you still need to press the
7905 character selecting the command.
7908 @cindex agenda, sticky
7909 @vindex org-agenda-sticky
7910 Toggle sticky agenda views. By default, Org maintains only a single agenda
7911 buffer and rebuilds it each time you change the view, to make sure everything
7912 is always up to date. If you often switch between agenda views and the build
7913 time bothers you, you can turn on sticky agenda buffers or make this the
7914 default by customizing the variable @code{org-agenda-sticky}. With sticky
7915 agendas, the agenda dispatcher will not recreate agenda views from scratch,
7916 it will only switch to the selected one, and you need to update the agenda by
7917 hand with @kbd{r} or @kbd{g} when needed. You can toggle sticky agenda view
7918 any time with @code{org-toggle-sticky-agenda}.
7921 You can also define custom commands that will be accessible through the
7922 dispatcher, just like the default commands. This includes the
7923 possibility to create extended agenda buffers that contain several
7924 blocks together, for example the weekly agenda, the global TODO list and
7925 a number of special tags matches. @xref{Custom agenda views}.
7927 @node Built-in agenda views
7928 @section The built-in agenda views
7930 In this section we describe the built-in views.
7933 * Weekly/daily agenda:: The calendar page with current tasks
7934 * Global TODO list:: All unfinished action items
7935 * Matching tags and properties:: Structured information with fine-tuned search
7936 * Timeline:: Time-sorted view for single file
7937 * Search view:: Find entries by searching for text
7938 * Stuck projects:: Find projects you need to review
7941 @node Weekly/daily agenda
7942 @subsection The weekly/daily agenda
7944 @cindex weekly agenda
7945 @cindex daily agenda
7947 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
7948 paper agenda, showing all the tasks for the current week or day.
7951 @cindex org-agenda, command
7952 @orgcmd{C-c a a,org-agenda-list}
7953 Compile an agenda for the current week from a list of Org files. The agenda
7954 shows the entries for each day. With a numeric prefix@footnote{For backward
7955 compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be
7956 listed before the agenda. This feature is deprecated, use the dedicated TODO
7957 list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1
7958 C-c a a}) you may set the number of days to be displayed.
7961 @vindex org-agenda-span
7962 @vindex org-agenda-ndays
7963 @vindex org-agenda-start-day
7964 @vindex org-agenda-start-on-weekday
7965 The default number of days displayed in the agenda is set by the variable
7966 @code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This
7967 variable can be set to any number of days you want to see by default in the
7968 agenda, or to a span name, such as @code{day}, @code{week}, @code{month} or
7969 @code{year}. For weekly agendas, the default is to start on the previous
7970 monday (see @code{org-agenda-start-on-weekday}). You can also set the start
7971 date using a date shift: @code{(setq org-agenda-start-day "+10d")} will
7972 start the agenda ten days from today in the future.
7974 Remote editing from the agenda buffer means, for example, that you can
7975 change the dates of deadlines and appointments from the agenda buffer.
7976 The commands available in the Agenda buffer are listed in @ref{Agenda
7979 @subsubheading Calendar/Diary integration
7980 @cindex calendar integration
7981 @cindex diary integration
7983 Emacs contains the calendar and diary by Edward M. Reingold. The
7984 calendar displays a three-month calendar with holidays from different
7985 countries and cultures. The diary allows you to keep track of
7986 anniversaries, lunar phases, sunrise/set, recurrent appointments
7987 (weekly, monthly) and more. In this way, it is quite complementary to
7988 Org. It can be very useful to combine output from Org with
7991 In order to include entries from the Emacs diary into Org mode's
7992 agenda, you only need to customize the variable
7995 (setq org-agenda-include-diary t)
7998 @noindent After that, everything will happen automatically. All diary
7999 entries including holidays, anniversaries, etc., will be included in the
8000 agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and
8001 @key{RET} can be used from the agenda buffer to jump to the diary
8002 file in order to edit existing diary entries. The @kbd{i} command to
8003 insert new entries for the current date works in the agenda buffer, as
8004 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
8005 Sunrise/Sunset times, show lunar phases and to convert to other
8006 calendars, respectively. @kbd{c} can be used to switch back and forth
8007 between calendar and agenda.
8009 If you are using the diary only for sexp entries and holidays, it is
8010 faster to not use the above setting, but instead to copy or even move
8011 the entries into an Org file. Org mode evaluates diary-style sexp
8012 entries, and does it faster because there is no overhead for first
8013 creating the diary display. Note that the sexp entries must start at
8014 the left margin, no whitespace is allowed before them. For example,
8015 the following segment of an Org file will be processed and entries
8016 will be made in the agenda:
8023 %%(org-calendar-holiday) ; special function for holiday names
8029 %%(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
8030 %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
8033 @subsubheading Anniversaries from BBDB
8034 @cindex BBDB, anniversaries
8035 @cindex anniversaries, from BBDB
8037 If you are using the Big Brothers Database to store your contacts, you will
8038 very likely prefer to store anniversaries in BBDB rather than in a
8039 separate Org or diary file. Org supports this and will show BBDB
8040 anniversaries as part of the agenda. All you need to do is to add the
8041 following to one of your agenda files:
8048 %%(org-bbdb-anniversaries)
8051 You can then go ahead and define anniversaries for a BBDB record. Basically,
8052 you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
8053 record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
8054 followed by a space and the class of the anniversary (@samp{birthday} or
8055 @samp{wedding}, or a format string). If you omit the class, it will default to
8056 @samp{birthday}. Here are a few examples, the header for the file
8057 @file{org-bbdb.el} contains more detailed information.
8063 2008-04-14 %s released version 6.01 of org mode, %d years ago
8066 After a change to BBDB, or for the first agenda display during an Emacs
8067 session, the agenda display will suffer a short delay as Org updates its
8068 hash with anniversaries. However, from then on things will be very fast---much
8069 faster in fact than a long list of @samp{%%(diary-anniversary)} entries
8070 in an Org or Diary file.
8072 If you would like to see upcoming anniversaries with a bit of forewarning,
8073 you can use the following instead:
8080 %%(org-bbdb-anniversaries-future 3)
8083 That will give you three days' warning: on the anniversary date itself and the
8084 two days prior. The argument is optional: if omitted, it defaults to 7.
8086 @subsubheading Appointment reminders
8087 @cindex @file{appt.el}
8088 @cindex appointment reminders
8092 Org can interact with Emacs appointments notification facility. To add the
8093 appointments of your agenda files, use the command @code{org-agenda-to-appt}.
8094 This command lets you filter through the list of your appointments and add
8095 only those belonging to a specific category or matching a regular expression.
8096 It also reads a @code{APPT_WARNTIME} property which will then override the
8097 value of @code{appt-message-warning-time} for this appointment. See the
8098 docstring for details.
8100 @node Global TODO list
8101 @subsection The global TODO list
8102 @cindex global TODO list
8103 @cindex TODO list, global
8105 The global TODO list contains all unfinished TODO items formatted and
8106 collected into a single place.
8109 @orgcmd{C-c a t,org-todo-list}
8110 Show the global TODO list. This collects the TODO items from all agenda
8111 files (@pxref{Agenda views}) into a single buffer. By default, this lists
8112 items with a state the is not a DONE state. The buffer is in
8113 @code{agenda-mode}, so there are commands to examine and manipulate the TODO
8114 entries directly from that buffer (@pxref{Agenda commands}).
8115 @orgcmd{C-c a T,org-todo-list}
8116 @cindex TODO keyword matching
8117 @vindex org-todo-keywords
8118 Like the above, but allows selection of a specific TODO keyword. You can
8119 also do this by specifying a prefix argument to @kbd{C-c a t}. You are
8120 prompted for a keyword, and you may also specify several keywords by
8121 separating them with @samp{|} as the boolean OR operator. With a numeric
8122 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
8124 The @kbd{r} key in the agenda buffer regenerates it, and you can give
8125 a prefix argument to this command to change the selected TODO keyword,
8126 for example @kbd{3 r}. If you often need a search for a specific
8127 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
8128 Matching specific TODO keywords can also be done as part of a tags
8129 search (@pxref{Tag searches}).
8132 Remote editing of TODO items means that you can change the state of a
8133 TODO entry with a single key press. The commands available in the
8134 TODO list are described in @ref{Agenda commands}.
8136 @cindex sublevels, inclusion into TODO list
8137 Normally the global TODO list simply shows all headlines with TODO
8138 keywords. This list can become very long. There are two ways to keep
8142 @vindex org-agenda-todo-ignore-scheduled
8143 @vindex org-agenda-todo-ignore-deadlines
8144 @vindex org-agenda-todo-ignore-timestamp
8145 @vindex org-agenda-todo-ignore-with-date
8146 Some people view a TODO item that has been @emph{scheduled} for execution or
8147 have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.
8148 Configure the variables @code{org-agenda-todo-ignore-scheduled},
8149 @code{org-agenda-todo-ignore-deadlines},
8150 @code{org-agenda-todo-ignore-timestamp} and/or
8151 @code{org-agenda-todo-ignore-with-date} to exclude such items from the global
8154 @vindex org-agenda-todo-list-sublevels
8155 TODO items may have sublevels to break up the task into subtasks. In
8156 such cases it may be enough to list only the highest level TODO headline
8157 and omit the sublevels from the global list. Configure the variable
8158 @code{org-agenda-todo-list-sublevels} to get this behavior.
8161 @node Matching tags and properties
8162 @subsection Matching tags and properties
8163 @cindex matching, of tags
8164 @cindex matching, of properties
8168 If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
8169 or have properties (@pxref{Properties and columns}), you can select headlines
8170 based on this metadata and collect them into an agenda buffer. The match
8171 syntax described here also applies when creating sparse trees with @kbd{C-c /
8175 @orgcmd{C-c a m,org-tags-view}
8176 Produce a list of all headlines that match a given set of tags. The
8177 command prompts for a selection criterion, which is a boolean logic
8178 expression with tags, like @samp{+work+urgent-withboss} or
8179 @samp{work|home} (@pxref{Tags}). If you often need a specific search,
8180 define a custom command for it (@pxref{Agenda dispatcher}).
8181 @orgcmd{C-c a M,org-tags-view}
8182 @vindex org-tags-match-list-sublevels
8183 @vindex org-agenda-tags-todo-honor-ignore-options
8184 Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
8185 not-DONE state and force checking subitems (see variable
8186 @code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items,
8187 see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching
8188 specific TODO keywords together with a tags match is also possible, see
8192 The commands available in the tags list are described in @ref{Agenda
8195 @subsubheading Match syntax
8197 @cindex Boolean logic, for tag/property searches
8198 A search string can use Boolean operators @samp{&} for @code{AND} and
8199 @samp{|} for @code{OR}@. @samp{&} binds more strongly than @samp{|}.
8200 Parentheses are not implemented. Each element in the search is either a
8201 tag, a regular expression matching tags, or an expression like
8202 @code{PROPERTY OPERATOR VALUE} with a comparison operator, accessing a
8203 property value. Each element may be preceded by @samp{-}, to select
8204 against it, and @samp{+} is syntactic sugar for positive selection. The
8205 @code{AND} operator @samp{&} is optional when @samp{+} or @samp{-} is
8206 present. Here are some examples, using only tags.
8210 Select headlines tagged @samp{:work:}.
8212 Select headlines tagged @samp{:work:} and @samp{:boss:}.
8214 Select headlines tagged @samp{:work:}, but discard those also tagged
8217 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
8218 @item work|laptop+night
8219 Like before, but require the @samp{:laptop:} lines to be tagged also
8223 @cindex regular expressions, with tags search
8224 Instead of a tag, you may also specify a regular expression enclosed in curly
8225 braces. For example,
8226 @samp{work+@{^boss.*@}} matches headlines that contain the tag
8227 @samp{:work:} and any tag @i{starting} with @samp{boss}.
8229 @cindex group tags, as regular expressions
8230 Group tags (@pxref{Tag hierarchy}) are expanded as regular expressions. E.g.,
8231 if @samp{:work:} is a group tag for the group @samp{:work:lab:conf:}, then
8232 searching for @samp{work} will search for @samp{@{\(?:work\|lab\|conf\)@}}
8233 and searching for @samp{-work} will search for all headlines but those with
8234 one of the tags in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}).
8236 @cindex TODO keyword matching, with tags search
8237 @cindex level, require for tags/property match
8238 @cindex category, require for tags/property match
8239 @vindex org-odd-levels-only
8240 You may also test for properties (@pxref{Properties and columns}) at the same
8241 time as matching tags. The properties may be real properties, or special
8242 properties that represent other metadata (@pxref{Special properties}). For
8243 example, the ``property'' @code{TODO} represents the TODO keyword of the
8244 entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of
8247 In addition to the properties mentioned above, @code{LEVEL} represents the
8248 level of an entry. So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all
8249 level three headlines that have the tag @samp{boss} and are @emph{not} marked
8250 with the TODO keyword DONE@. In buffers with @code{org-odd-levels-only} set,
8251 @samp{LEVEL} does not count the number of stars, but @samp{LEVEL=2} will
8252 correspond to 3 stars etc.
8254 Here are more examples:
8257 @item work+TODO="WAITING"
8258 Select @samp{:work:}-tagged TODO lines with the specific TODO
8259 keyword @samp{WAITING}.
8260 @item work+TODO="WAITING"|home+TODO="WAITING"
8261 Waiting tasks both at work and at home.
8264 When matching properties, a number of different operators can be used to test
8265 the value of a property. Here is a complex example:
8268 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \
8269 +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
8273 The type of comparison will depend on how the comparison value is written:
8276 If the comparison value is a plain number, a numerical comparison is done,
8277 and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
8278 @samp{>=}, and @samp{<>}.
8280 If the comparison value is enclosed in double-quotes,
8281 a string comparison is done, and the same operators are allowed.
8283 If the comparison value is enclosed in double-quotes @emph{and} angular
8284 brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
8285 assumed to be date/time specifications in the standard Org way, and the
8286 comparison will be done accordingly. Special values that will be recognized
8287 are @code{"<now>"} for now (including time), and @code{"<today>"}, and
8288 @code{"<tomorrow>"} for these days at 00:00 hours, i.e., without a time
8289 specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
8290 @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
8291 respectively, can be used.
8293 If the comparison value is enclosed
8294 in curly braces, a regexp match is performed, with @samp{=} meaning that the
8295 regexp matches the property value, and @samp{<>} meaning that it does not
8299 So the search string in the example finds entries tagged @samp{:work:} but
8300 not @samp{:boss:}, which also have a priority value @samp{A}, a
8301 @samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
8302 property that is numerically smaller than 2, a @samp{:With:} property that is
8303 matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
8304 on or after October 11, 2008.
8306 You can configure Org mode to use property inheritance during a search, but
8307 beware that this can slow down searches considerably. See @ref{Property
8308 inheritance}, for details.
8310 For backward compatibility, and also for typing speed, there is also a
8311 different way to test TODO states in a search. For this, terminate the
8312 tags/property part of the search string (which may include several terms
8313 connected with @samp{|}) with a @samp{/} and then specify a Boolean
8314 expression just for TODO keywords. The syntax is then similar to that for
8315 tags, but should be applied with care: for example, a positive selection on
8316 several TODO keywords cannot meaningfully be combined with boolean AND@.
8317 However, @emph{negative selection} combined with AND can be meaningful. To
8318 make sure that only lines are checked that actually have any TODO keyword
8319 (resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
8320 part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will
8321 not match TODO keywords in a DONE state. Examples:
8325 Same as @samp{work+TODO="WAITING"}
8326 @item work/!-WAITING-NEXT
8327 Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
8329 @item work/!+WAITING|+NEXT
8330 Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
8335 @subsection Timeline for a single file
8336 @cindex timeline, single file
8337 @cindex time-sorted view
8339 The timeline summarizes all time-stamped items from a single Org mode
8340 file in a @emph{time-sorted view}. The main purpose of this command is
8341 to give an overview over events in a project.
8344 @orgcmd{C-c a L,org-timeline}
8345 Show a time-sorted view of the Org file, with all time-stamped items.
8346 When called with a @kbd{C-u} prefix, all unfinished TODO entries
8347 (scheduled or not) are also listed under the current date.
8351 The commands available in the timeline buffer are listed in
8352 @ref{Agenda commands}.
8355 @subsection Search view
8358 @cindex searching, for text
8360 This agenda view is a general text search facility for Org mode entries.
8361 It is particularly useful to find notes.
8364 @orgcmd{C-c a s,org-search-view}
8365 This is a special search that lets you select entries by matching a substring
8366 or specific words using a boolean logic.
8368 For example, the search string @samp{computer equipment} will find entries
8369 that contain @samp{computer equipment} as a substring. If the two words are
8370 separated by more space or a line break, the search will still match.
8371 Search view can also search for specific keywords in the entry, using Boolean
8372 logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
8373 will search for note entries that contain the keywords @code{computer}
8374 and @code{wifi}, but not the keyword @code{ethernet}, and which are also
8375 not matched by the regular expression @code{8\.11[bg]}, meaning to
8376 exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on
8377 word search, other @samp{+} characters are optional. For more details, see
8378 the docstring of the command @code{org-search-view}.
8380 @vindex org-agenda-text-search-extra-files
8381 Note that in addition to the agenda files, this command will also search
8382 the files listed in @code{org-agenda-text-search-extra-files}.
8384 @node Stuck projects
8385 @subsection Stuck projects
8386 @pindex GTD, Getting Things Done
8388 If you are following a system like David Allen's GTD to organize your
8389 work, one of the ``duties'' you have is a regular review to make sure
8390 that all projects move along. A @emph{stuck} project is a project that
8391 has no defined next actions, so it will never show up in the TODO lists
8392 Org mode produces. During the review, you need to identify such
8393 projects and define next actions for them.
8396 @orgcmd{C-c a #,org-agenda-list-stuck-projects}
8397 List projects that are stuck.
8400 @vindex org-stuck-projects
8401 Customize the variable @code{org-stuck-projects} to define what a stuck
8402 project is and how to find it.
8405 You almost certainly will have to configure this view before it will
8406 work for you. The built-in default assumes that all your projects are
8407 level-2 headlines, and that a project is not stuck if it has at least
8408 one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
8410 Let's assume that you, in your own way of using Org mode, identify
8411 projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
8412 indicate a project that should not be considered yet. Let's further
8413 assume that the TODO keyword DONE marks finished projects, and that NEXT
8414 and TODO indicate next actions. The tag @@SHOP indicates shopping and
8415 is a next action even without the NEXT tag. Finally, if the project
8416 contains the special word IGNORE anywhere, it should not be listed
8417 either. In this case you would start by identifying eligible projects
8418 with a tags/todo match@footnote{@xref{Tag searches}.}
8419 @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, and
8420 IGNORE in the subtree to identify projects that are not stuck. The
8421 correct customization for this is
8424 (setq org-stuck-projects
8425 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
8429 Note that if a project is identified as non-stuck, the subtree of this entry
8430 will still be searched for stuck projects.
8432 @node Presentation and sorting
8433 @section Presentation and sorting
8434 @cindex presentation, of agenda items
8436 @vindex org-agenda-prefix-format
8437 @vindex org-agenda-tags-column
8438 Before displaying items in an agenda view, Org mode visually prepares the
8439 items and sorts them. Each item occupies a single line. The line starts
8440 with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
8441 of the item and other important information. You can customize in which
8442 column tags will be displayed through @code{org-agenda-tags-column}. You can
8443 also customize the prefix using the option @code{org-agenda-prefix-format}.
8444 This prefix is followed by a cleaned-up version of the outline headline
8445 associated with the item.
8448 * Categories:: Not all tasks are equal
8449 * Time-of-day specifications:: How the agenda knows the time
8450 * Sorting agenda items:: The order of things
8451 * Filtering/limiting agenda items:: Dynamically narrow the agenda
8455 @subsection Categories
8459 The category is a broad label assigned to each agenda item. By default, the
8460 category is simply derived from the file name, but you can also specify it
8461 with a special line in the buffer, like this:
8468 @cindex property, CATEGORY
8469 If you would like to have a special CATEGORY for a single entry or a
8470 (sub)tree, give the entry a @code{:CATEGORY:} property with the
8471 special category you want to apply as the value.
8474 The display in the agenda buffer looks best if the category is not
8475 longer than 10 characters.
8478 You can set up icons for category by customizing the
8479 @code{org-agenda-category-icon-alist} variable.
8481 @node Time-of-day specifications
8482 @subsection Time-of-day specifications
8483 @cindex time-of-day specification
8485 Org mode checks each agenda item for a time-of-day specification. The
8486 time can be part of the timestamp that triggered inclusion into the
8487 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
8488 ranges can be specified with two timestamps, like
8490 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
8492 In the headline of the entry itself, a time(range) may also appear as
8493 plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda
8494 integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
8495 specifications in diary entries are recognized as well.
8497 For agenda display, Org mode extracts the time and displays it in a
8498 standard 24 hour format as part of the prefix. The example times in
8499 the previous paragraphs would end up in the agenda like this:
8502 8:30-13:00 Arthur Dent lies in front of the bulldozer
8503 12:45...... Ford Prefect arrives and takes Arthur to the pub
8504 19:00...... The Vogon reads his poem
8505 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8509 If the agenda is in single-day mode, or for the display of today, the
8510 timed entries are embedded in a time grid, like
8513 8:00...... ------------------
8514 8:30-13:00 Arthur Dent lies in front of the bulldozer
8515 10:00...... ------------------
8516 12:00...... ------------------
8517 12:45...... Ford Prefect arrives and takes Arthur to the pub
8518 14:00...... ------------------
8519 16:00...... ------------------
8520 18:00...... ------------------
8521 19:00...... The Vogon reads his poem
8522 20:00...... ------------------
8523 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8526 @vindex org-agenda-use-time-grid
8527 @vindex org-agenda-time-grid
8528 The time grid can be turned on and off with the variable
8529 @code{org-agenda-use-time-grid}, and can be configured with
8530 @code{org-agenda-time-grid}.
8532 @node Sorting agenda items
8533 @subsection Sorting agenda items
8534 @cindex sorting, of agenda items
8535 @cindex priorities, of agenda items
8536 Before being inserted into a view, the items are sorted. How this is
8537 done depends on the type of view.
8540 @vindex org-agenda-files
8541 For the daily/weekly agenda, the items for each day are sorted. The
8542 default order is to first collect all items containing an explicit
8543 time-of-day specification. These entries will be shown at the beginning
8544 of the list, as a @emph{schedule} for the day. After that, items remain
8545 grouped in categories, in the sequence given by @code{org-agenda-files}.
8546 Within each category, items are sorted by priority (@pxref{Priorities}),
8547 which is composed of the base priority (2000 for priority @samp{A}, 1000
8548 for @samp{B}, and 0 for @samp{C}), plus additional increments for
8549 overdue scheduled or deadline items.
8551 For the TODO list, items remain in the order of categories, but within
8552 each category, sorting takes place according to priority
8553 (@pxref{Priorities}). The priority used for sorting derives from the
8554 priority cookie, with additions depending on how close an item is to its due
8557 For tags matches, items are not sorted at all, but just appear in the
8558 sequence in which they are found in the agenda files.
8561 @vindex org-agenda-sorting-strategy
8562 Sorting can be customized using the variable
8563 @code{org-agenda-sorting-strategy}, and may also include criteria based on
8564 the estimated effort of an entry (@pxref{Effort estimates}).
8566 @node Filtering/limiting agenda items
8567 @subsection Filtering/limiting agenda items
8569 Agenda built-in or customized commands are statically defined. Agenda
8570 filters and limits provide two ways of dynamically narrowing down the list of
8571 agenda entries: @emph{filters} and @emph{limits}. Filters only act on the
8572 display of the items, while limits take effect before the list of agenda
8573 entries is built. Filters are more often used interactively, while limits are
8574 mostly useful when defined as local variables within custom agenda commands.
8576 @subsubheading Filtering in the agenda
8577 @cindex filtering, by tag, category, top headline and effort, in agenda
8578 @cindex tag filtering, in agenda
8579 @cindex category filtering, in agenda
8580 @cindex top headline filtering, in agenda
8581 @cindex effort filtering, in agenda
8582 @cindex query editing, in agenda
8585 @orgcmd{/,org-agenda-filter-by-tag}
8586 @vindex org-agenda-tag-filter-preset
8587 Filter the agenda view with respect to a tag and/or effort estimates. The
8588 difference between this and a custom agenda command is that filtering is very
8589 fast, so that you can switch quickly between different filters without having
8590 to recreate the agenda.@footnote{Custom commands can preset a filter by
8591 binding the variable @code{org-agenda-tag-filter-preset} as an option. This
8592 filter will then be applied to the view and persist as a basic filter through
8593 refreshes and more secondary filtering. The filter is a global property of
8594 the entire agenda view---in a block agenda, you should only set this in the
8595 global options section, not in the section of an individual block.}
8597 You will be prompted for a tag selection letter; @key{SPC} will mean any tag
8598 at all. Pressing @key{TAB} at that prompt will offer use completion to
8599 select a tag (including any tags that do not have a selection character).
8600 The command then hides all entries that do not contain or inherit this tag.
8601 When called with prefix arg, remove the entries that @emph{do} have the tag.
8602 A second @kbd{/} at the prompt will turn off the filter and unhide any hidden
8603 entries. Pressing @kbd{+} or @kbd{-} switches between filtering and
8604 excluding the next tag.
8606 Org also supports automatic, context-aware tag filtering. If the variable
8607 @code{org-agenda-auto-exclude-function} is set to a user-defined function,
8608 that function can decide which tags should be excluded from the agenda
8609 automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
8610 as a sub-option key and runs the auto exclusion logic. For example, let's
8611 say you use a @code{Net} tag to identify tasks which need network access, an
8612 @code{Errand} tag for errands in town, and a @code{Call} tag for making phone
8613 calls. You could auto-exclude these tags based on the availability of the
8614 Internet, and outside of business hours, with something like this:
8618 (defun org-my-auto-exclude-function (tag)
8620 ((string= tag "Net")
8621 (/= 0 (call-process "/sbin/ping" nil nil nil
8622 "-c1" "-q" "-t1" "mail.gnu.org")))
8623 ((or (string= tag "Errand") (string= tag "Call"))
8624 (let ((hour (nth 2 (decode-time))))
8625 (or (< hour 8) (> hour 21)))))
8628 (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
8639 @item @r{in} search view
8640 add new search words (@kbd{[} and @kbd{]}) or new regular expressions
8641 (@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
8642 add a positive search term prefixed by @samp{+}, indicating that this search
8643 term @i{must} occur/match in the entry. The closing bracket/brace will add a
8644 negative search term which @i{must not} occur/match in the entry for it to be
8648 @orgcmd{<,org-agenda-filter-by-category}
8649 @vindex org-agenda-category-filter-preset
8651 Filter the current agenda view with respect to the category of the item at
8652 point. Pressing @code{<} another time will remove this filter. When called
8653 with a prefix argument exclude the category of the item at point from the
8656 You can add a filter preset in custom agenda commands through the option
8657 @code{org-agenda-category-filter-preset}. @xref{Setting options}.
8659 @orgcmd{^,org-agenda-filter-by-top-headline}
8660 Filter the current agenda view and only display the siblings and the parent
8661 headline of the one at point.
8663 @orgcmd{=,org-agenda-filter-by-regexp}
8664 @vindex org-agenda-regexp-filter-preset
8666 Filter the agenda view by a regular expression: only show agenda entries
8667 matching the regular expression the user entered. When called with a prefix
8668 argument, it will filter @emph{out} entries matching the regexp. With two
8669 universal prefix arguments, it will remove all the regexp filters, which can
8672 You can add a filter preset in custom agenda commands through the option
8673 @code{org-agenda-regexp-filter-preset}. @xref{Setting options}.
8675 @orgcmd{_,org-agenda-filter-by-effort}
8676 @vindex org-agenda-effort-filter-preset
8677 @vindex org-sort-agenda-noeffort-is-high
8678 Filter the agenda view with respect to effort estimates.
8679 You first need to set up allowed efforts globally, for example
8681 (setq org-global-properties
8682 '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
8684 You can then filter for an effort by first typing an operator, one of
8685 @kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
8686 estimate in your array of allowed values, where @kbd{0} means the 10th value.
8687 The filter will then restrict to entries with effort smaller-or-equal, equal,
8688 or larger-or-equal than the selected value. For application of the operator,
8689 entries without a defined effort will be treated according to the value of
8690 @code{org-sort-agenda-noeffort-is-high}.
8692 When called with a prefix argument, it will remove entries matching the
8693 condition. With two universal prefix arguments, it will clear effort
8694 filters, which can be accumulated.
8696 You can add a filter preset in custom agenda commands through the option
8697 @code{org-agenda-effort-filter-preset}. @xref{Setting options}.
8699 @orgcmd{|,org-agenda-filter-remove-all}
8700 Remove all filters in the current agenda view.
8703 @subsubheading Setting limits for the agenda
8704 @cindex limits, in agenda
8705 @vindex org-agenda-max-entries
8706 @vindex org-agenda-max-effort
8707 @vindex org-agenda-max-todos
8708 @vindex org-agenda-max-tags
8710 Here is a list of options that you can set, either globally, or locally in
8711 your custom agenda views (@pxref{Custom agenda views}).
8714 @item org-agenda-max-entries
8715 Limit the number of entries.
8716 @item org-agenda-max-effort
8717 Limit the duration of accumulated efforts (as minutes).
8718 @item org-agenda-max-todos
8719 Limit the number of entries with TODO keywords.
8720 @item org-agenda-max-tags
8721 Limit the number of tagged entries.
8724 When set to a positive integer, each option will exclude entries from other
8725 categories: for example, @code{(setq org-agenda-max-effort 100)} will limit
8726 the agenda to 100 minutes of effort and exclude any entry that has no effort
8727 property. If you want to include entries with no effort property, use a
8728 negative value for @code{org-agenda-max-effort}.
8730 One useful setup is to use @code{org-agenda-max-entries} locally in a custom
8731 command. For example, this custom command will display the next five entries
8732 with a @code{NEXT} TODO keyword.
8735 (setq org-agenda-custom-commands
8737 ((org-agenda-max-entries 5)))))
8740 Once you mark one of these five entry as @code{DONE}, rebuilding the agenda
8741 will again the next five entries again, including the first entry that was
8744 You can also dynamically set temporary limits, which will be lost when
8745 rebuilding the agenda:
8748 @orgcmd{~,org-agenda-limit-interactively}
8749 This prompts for the type of limit to apply and its value.
8752 @node Agenda commands
8753 @section Commands in the agenda buffer
8754 @cindex commands, in agenda buffer
8756 Entries in the agenda buffer are linked back to the Org file or diary
8757 file where they originate. You are not allowed to edit the agenda
8758 buffer itself, but commands are provided to show and jump to the
8759 original entry location, and to edit the Org files ``remotely'' from
8760 the agenda buffer. In this way, all information is stored only once,
8761 removing the risk that your agenda and note files may diverge.
8763 Some commands can be executed with mouse clicks on agenda lines. For
8764 the other commands, the cursor needs to be in the desired line.
8767 @tsubheading{Motion}
8768 @cindex motion commands in agenda
8769 @orgcmd{n,org-agenda-next-line}
8770 Next line (same as @key{down} and @kbd{C-n}).
8771 @orgcmd{p,org-agenda-previous-line}
8772 Previous line (same as @key{up} and @kbd{C-p}).
8773 @orgcmd{N,org-agenda-next-item}
8774 Next item: same as next line, but only consider items.
8775 @orgcmd{P,org-agenda-previous-item}
8776 Previous item: same as previous line, but only consider items.
8777 @tsubheading{View/Go to Org file}
8778 @orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
8779 Display the original location of the item in another window. With prefix
8780 arg, make sure that drawers stay folded.
8782 @orgcmd{L,org-agenda-recenter}
8783 Display original location and recenter that window.
8785 @orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
8786 Go to the original location of the item in another window.
8788 @orgcmd{@key{RET},org-agenda-switch-to}
8789 Go to the original location of the item and delete other windows.
8791 @orgcmd{F,org-agenda-follow-mode}
8792 @vindex org-agenda-start-with-follow-mode
8793 Toggle Follow mode. In Follow mode, as you move the cursor through
8794 the agenda buffer, the other window always shows the corresponding
8795 location in the Org file. The initial setting for this mode in new
8796 agenda buffers can be set with the variable
8797 @code{org-agenda-start-with-follow-mode}.
8799 @orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
8800 Display the entire subtree of the current item in an indirect buffer. With a
8801 numeric prefix argument N, go up to level N and then take that tree. If N is
8802 negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the
8803 previously used indirect buffer.
8805 @orgcmd{C-c C-o,org-agenda-open-link}
8806 Follow a link in the entry. This will offer a selection of any links in the
8807 text belonging to the referenced Org node. If there is only one link, it
8808 will be followed without a selection prompt.
8810 @tsubheading{Change display}
8811 @cindex display changing, in agenda
8814 Interactively select another agenda view and append it to the current view.
8818 Delete other windows.
8820 @orgcmdkskc{v d,d,org-agenda-day-view}
8821 @xorgcmdkskc{v w,w,org-agenda-week-view}
8822 @xorgcmd{v t,org-agenda-fortnight-view}
8823 @xorgcmd{v m,org-agenda-month-view}
8824 @xorgcmd{v y,org-agenda-year-view}
8825 @xorgcmd{v SPC,org-agenda-reset-view}
8826 @vindex org-agenda-span
8827 Switch to day/week/month/year view. When switching to day or week view, this
8828 setting becomes the default for subsequent agenda refreshes. Since month and
8829 year views are slow to create, they do not become the default. A numeric
8830 prefix argument may be used to jump directly to a specific day of the year,
8831 ISO week, month, or year, respectively. For example, @kbd{32 d} jumps to
8832 February 1st, @kbd{9 w} to ISO week number 9. When setting day, week, or
8833 month view, a year may be encoded in the prefix argument as well. For
8834 example, @kbd{200712 w} will jump to week 12 in 2007. If such a year
8835 specification has only one or two digits, it will be mapped to the interval
8836 1938--2037. @kbd{v @key{SPC}} will reset to what is set in
8837 @code{org-agenda-span}.
8839 @orgcmd{f,org-agenda-later}
8840 Go forward in time to display the following @code{org-agenda-current-span} days.
8841 For example, if the display covers a week, switch to the following week.
8842 With prefix arg, go forward that many times @code{org-agenda-current-span} days.
8844 @orgcmd{b,org-agenda-earlier}
8845 Go backward in time to display earlier dates.
8847 @orgcmd{.,org-agenda-goto-today}
8850 @orgcmd{j,org-agenda-goto-date}
8851 Prompt for a date and go there.
8853 @orgcmd{J,org-agenda-clock-goto}
8854 Go to the currently clocked-in task @i{in the agenda buffer}.
8856 @orgcmd{D,org-agenda-toggle-diary}
8857 Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}.
8859 @orgcmdkskc{v l,l,org-agenda-log-mode}
8861 @vindex org-log-done
8862 @vindex org-agenda-log-mode-items
8863 Toggle Logbook mode. In Logbook mode, entries that were marked DONE while
8864 logging was on (variable @code{org-log-done}) are shown in the agenda, as are
8865 entries that have been clocked on that day. You can configure the entry
8866 types that should be included in log mode using the variable
8867 @code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show
8868 all possible logbook entries, including state changes. When called with two
8869 prefix arguments @kbd{C-u C-u}, show only logging information, nothing else.
8870 @kbd{v L} is equivalent to @kbd{C-u v l}.
8872 @orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
8873 Include inactive timestamps into the current view. Only for weekly/daily
8874 agenda and timeline views.
8876 @orgcmd{v a,org-agenda-archives-mode}
8877 @xorgcmd{v A,org-agenda-archives-mode 'files}
8878 @cindex Archives mode
8879 Toggle Archives mode. In Archives mode, trees that are marked
8880 @code{ARCHIVED} are also scanned when producing the agenda. When you use the
8881 capital @kbd{A}, even all archive files are included. To exit archives mode,
8882 press @kbd{v a} again.
8884 @orgcmdkskc{v R,R,org-agenda-clockreport-mode}
8885 @vindex org-agenda-start-with-clockreport-mode
8886 @vindex org-clock-report-include-clocking-task
8887 Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will
8888 always show a table with the clocked times for the time span and file scope
8889 covered by the current agenda view. The initial setting for this mode in new
8890 agenda buffers can be set with the variable
8891 @code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
8892 when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
8893 contributions from entries that are hidden by agenda filtering@footnote{Only
8894 tags filtering will be respected here, effort filtering is ignored.}. See
8895 also the variable @code{org-clock-report-include-clocking-task}.
8898 @vindex org-agenda-clock-consistency-checks
8899 Show overlapping clock entries, clocking gaps, and other clocking problems in
8900 the current agenda range. You can then visit clocking lines and fix them
8901 manually. See the variable @code{org-agenda-clock-consistency-checks} for
8902 information on how to customize the definition of what constituted a clocking
8903 problem. To return to normal agenda display, press @kbd{l} to exit Logbook
8906 @orgcmdkskc{v E,E,org-agenda-entry-text-mode}
8907 @vindex org-agenda-start-with-entry-text-mode
8908 @vindex org-agenda-entry-text-maxlines
8909 Toggle entry text mode. In entry text mode, a number of lines from the Org
8910 outline node referenced by an agenda line will be displayed below the line.
8911 The maximum number of lines is given by the variable
8912 @code{org-agenda-entry-text-maxlines}. Calling this command with a numeric
8913 prefix argument will temporarily modify that number to the prefix value.
8915 @orgcmd{G,org-agenda-toggle-time-grid}
8916 @vindex org-agenda-use-time-grid
8917 @vindex org-agenda-time-grid
8918 Toggle the time grid on and off. See also the variables
8919 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
8921 @orgcmd{r,org-agenda-redo}
8922 Recreate the agenda buffer, for example to reflect the changes after
8923 modification of the timestamps of items with @kbd{S-@key{left}} and
8924 @kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix
8925 argument is interpreted to create a selective list for a specific TODO
8927 @orgcmd{g,org-agenda-redo}
8930 @orgcmdkskc{C-x C-s,s,org-save-all-org-buffers}
8931 Save all Org buffers in the current Emacs session, and also the locations of
8934 @orgcmd{C-c C-x C-c,org-agenda-columns}
8935 @vindex org-columns-default-format
8936 Invoke column view (@pxref{Column view}) in the agenda buffer. The column
8937 view format is taken from the entry at point, or (if there is no entry at
8938 point), from the first entry in the agenda view. So whatever the format for
8939 that entry would be in the original buffer (taken from a property, from a
8940 @code{#+COLUMNS} line, or from the default variable
8941 @code{org-columns-default-format}), will be used in the agenda.
8943 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
8944 Remove the restriction lock on the agenda, if it is currently restricted to a
8945 file or subtree (@pxref{Agenda files}).
8947 @tsubheading{Secondary filtering and query editing}
8949 For a detailed description of these commands, @pxref{Filtering/limiting
8952 @orgcmd{/,org-agenda-filter-by-tag}
8953 Filter the agenda view with respect to a tag and/or effort estimates.
8955 @orgcmd{<,org-agenda-filter-by-category}
8956 Filter the current agenda view with respect to the category of the item at
8959 @orgcmd{^,org-agenda-filter-by-top-headline}
8960 Filter the current agenda view and only display the siblings and the parent
8961 headline of the one at point.
8963 @orgcmd{=,org-agenda-filter-by-regexp}
8964 Filter the agenda view by a regular expression.
8966 @orgcmd{_,org-agenda-filter-by-effort}
8967 Filter the agenda view with respect to effort estimates.
8969 @orgcmd{|,org-agenda-filter-remove-all}
8970 Remove all filters in the current agenda view.
8972 @tsubheading{Remote editing}
8973 @cindex remote editing, from agenda
8978 @cindex undoing remote-editing events
8979 @cindex remote editing, undo
8980 @orgcmd{C-_,org-agenda-undo}
8981 Undo a change due to a remote editing command. The change is undone
8982 both in the agenda buffer and in the remote buffer.
8984 @orgcmd{t,org-agenda-todo}
8985 Change the TODO state of the item, both in the agenda and in the
8988 @orgcmd{C-S-@key{right},org-agenda-todo-nextset}
8989 @orgcmd{C-S-@key{left},org-agenda-todo-previousset}
8990 Switch to the next/previous set of TODO keywords.
8992 @orgcmd{C-k,org-agenda-kill}
8993 @vindex org-agenda-confirm-kill
8994 Delete the current agenda item along with the entire subtree belonging
8995 to it in the original Org file. If the text to be deleted remotely
8996 is longer than one line, the kill needs to be confirmed by the user. See
8997 variable @code{org-agenda-confirm-kill}.
8999 @orgcmd{C-c C-w,org-agenda-refile}
9000 Refile the entry at point.
9002 @orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation}
9003 @vindex org-archive-default-command
9004 Archive the subtree corresponding to the entry at point using the default
9005 archiving command set in @code{org-archive-default-command}. When using the
9006 @code{a} key, confirmation will be required.
9008 @orgcmd{C-c C-x a,org-agenda-toggle-archive-tag}
9009 Toggle the ARCHIVE tag for the current headline.
9011 @orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling}
9012 Move the subtree corresponding to the current entry to its @emph{archive
9015 @orgcmdkskc{C-c C-x C-s,$,org-agenda-archive}
9016 Archive the subtree corresponding to the current headline. This means the
9017 entry will be moved to the configured archive location, most likely a
9020 @orgcmd{T,org-agenda-show-tags}
9021 @vindex org-agenda-show-inherited-tags
9022 Show all tags associated with the current item. This is useful if you have
9023 turned off @code{org-agenda-show-inherited-tags}, but still want to see all
9024 tags of a headline occasionally.
9026 @orgcmd{:,org-agenda-set-tags}
9027 Set tags for the current headline. If there is an active region in the
9028 agenda, change a tag for all headings in the region.
9032 Set the priority for the current item (@command{org-agenda-priority}).
9033 Org mode prompts for the priority character. If you reply with @key{SPC},
9034 the priority cookie is removed from the entry.
9036 @orgcmd{P,org-agenda-show-priority}
9037 Display weighted priority of current item.
9039 @orgcmdkkc{+,S-@key{up},org-agenda-priority-up}
9040 Increase the priority of the current item. The priority is changed in
9041 the original buffer, but the agenda is not resorted. Use the @kbd{r}
9044 @orgcmdkkc{-,S-@key{down},org-agenda-priority-down}
9045 Decrease the priority of the current item.
9047 @orgcmdkkc{z,C-c C-z,org-agenda-add-note}
9048 @vindex org-log-into-drawer
9049 Add a note to the entry. This note will be recorded, and then filed to the
9050 same location where state change notes are put. Depending on
9051 @code{org-log-into-drawer}, this may be inside a drawer.
9053 @orgcmd{C-c C-a,org-attach}
9054 Dispatcher for all command related to attachments.
9056 @orgcmd{C-c C-s,org-agenda-schedule}
9057 Schedule this item. With prefix arg remove the scheduling timestamp
9059 @orgcmd{C-c C-d,org-agenda-deadline}
9060 Set a deadline for this item. With prefix arg remove the deadline.
9062 @orgcmd{S-@key{right},org-agenda-do-date-later}
9063 Change the timestamp associated with the current line by one day into the
9064 future. If the date is in the past, the first call to this command will move
9066 With a numeric prefix argument, change it by that many days. For example,
9067 @kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix,
9068 change the time by one hour. If you immediately repeat the command, it will
9069 continue to change hours even without the prefix arg. With a double @kbd{C-u
9070 C-u} prefix, do the same for changing minutes.@*
9071 The stamp is changed in the original Org file, but the change is not directly
9072 reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
9074 @orgcmd{S-@key{left},org-agenda-do-date-earlier}
9075 Change the timestamp associated with the current line by one day
9078 @orgcmd{>,org-agenda-date-prompt}
9079 Change the timestamp associated with the current line. The key @kbd{>} has
9080 been chosen, because it is the same as @kbd{S-.} on my keyboard.
9082 @orgcmd{I,org-agenda-clock-in}
9083 Start the clock on the current item. If a clock is running already, it
9086 @orgcmd{O,org-agenda-clock-out}
9087 Stop the previously started clock.
9089 @orgcmd{X,org-agenda-clock-cancel}
9090 Cancel the currently running clock.
9092 @orgcmd{J,org-agenda-clock-goto}
9093 Jump to the running clock in another window.
9095 @orgcmd{k,org-agenda-capture}
9096 Like @code{org-capture}, but use the date at point as the default date for
9097 the capture template. See @code{org-capture-use-agenda-date} to make this
9098 the default behavior of @code{org-capture}.
9099 @cindex capturing, from agenda
9100 @vindex org-capture-use-agenda-date
9102 @tsubheading{Dragging agenda lines forward/backward}
9103 @cindex dragging, agenda lines
9105 @orgcmd{M-<up>,org-agenda-drag-line-backward}
9106 Drag the line at point backward one line@footnote{Moving agenda lines does
9107 not persist after an agenda refresh and does not modify the contributing
9108 @file{.org} files}. With a numeric prefix argument, drag backward by that
9111 @orgcmd{M-<down>,org-agenda-drag-line-forward}
9112 Drag the line at point forward one line. With a numeric prefix argument,
9113 drag forward by that many lines.
9115 @tsubheading{Bulk remote editing selected entries}
9116 @cindex remote editing, bulk, from agenda
9117 @vindex org-agenda-bulk-custom-functions
9119 @orgcmd{m,org-agenda-bulk-mark}
9120 Mark the entry at point for bulk action. With numeric prefix argument, mark
9121 that many successive entries.
9123 @orgcmd{*,org-agenda-bulk-mark-all}
9124 Mark all visible agenda entries for bulk action.
9126 @orgcmd{u,org-agenda-bulk-unmark}
9127 Unmark entry at point for bulk action.
9129 @orgcmd{U,org-agenda-bulk-remove-all-marks}
9130 Unmark all marked entries for bulk action.
9132 @orgcmd{M-m,org-agenda-bulk-toggle}
9133 Toggle mark of the entry at point for bulk action.
9135 @orgcmd{M-*,org-agenda-bulk-toggle-all}
9136 Toggle marks of all visible entries for bulk action.
9138 @orgcmd{%,org-agenda-bulk-mark-regexp}
9139 Mark entries matching a regular expression for bulk action.
9141 @orgcmd{B,org-agenda-bulk-action}
9142 Bulk action: act on all marked entries in the agenda. This will prompt for
9143 another key to select the action to be applied. The prefix arg to @kbd{B}
9144 will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove
9145 these special timestamps. By default, marks are removed after the bulk. If
9146 you want them to persist, set @code{org-agenda-persistent-marks} to @code{t}
9147 or hit @kbd{p} at the prompt.
9151 Toggle persistent marks.
9153 Archive all selected entries.
9155 Archive entries by moving them to their respective archive siblings.
9157 Change TODO state. This prompts for a single TODO keyword and changes the
9158 state of all selected entries, bypassing blocking and suppressing logging
9159 notes (but not timestamps).
9161 Add a tag to all selected entries.
9163 Remove a tag from all selected entries.
9165 Schedule all items to a new date. To shift existing schedule dates by a
9166 fixed number of days, use something starting with double plus at the prompt,
9167 for example @samp{++8d} or @samp{++2w}.
9169 Set deadline to a specific date.
9171 Prompt for a single refile target and move all entries. The entries will no
9172 longer be in the agenda; refresh (@kbd{g}) to bring them back.
9174 Reschedule randomly into the coming N days. N will be prompted for. With
9175 prefix arg (@kbd{C-u B S}), scatter only across weekdays.
9177 Apply a function@footnote{You can also create persistent custom functions
9178 through @code{org-agenda-bulk-custom-functions}.} to marked entries. For
9179 example, the function below sets the CATEGORY property of the entries to web.
9183 (defun set-category ()
9185 (let* ((marker (or (org-get-at-bol 'org-hd-marker)
9186 (org-agenda-error)))
9187 (buffer (marker-buffer marker)))
9188 (with-current-buffer buffer
9193 (org-back-to-heading t)
9194 (org-set-property "CATEGORY" "web"))))))
9199 @tsubheading{Calendar commands}
9200 @cindex calendar commands, from agenda
9202 @orgcmd{c,org-agenda-goto-calendar}
9203 Open the Emacs calendar and move to the date at the agenda cursor.
9205 @orgcmd{c,org-calendar-goto-agenda}
9206 When in the calendar, compute and show the Org mode agenda for the
9209 @cindex diary entries, creating from agenda
9210 @orgcmd{i,org-agenda-diary-entry}
9211 @vindex org-agenda-diary-file
9212 Insert a new entry into the diary, using the date at the cursor and (for
9213 block entries) the date at the mark. This will add to the Emacs diary
9214 file@footnote{This file is parsed for the agenda when
9215 @code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
9216 command in the calendar. The diary file will pop up in another window, where
9217 you can add the entry.
9219 If you configure @code{org-agenda-diary-file} to point to an Org mode file,
9220 Org will create entries (in Org mode syntax) in that file instead. Most
9221 entries will be stored in a date-based outline tree that will later make it
9222 easy to archive appointments from previous months/years. The tree will be
9223 built under an entry with a @code{DATE_TREE} property, or else with years as
9224 top-level entries. Emacs will prompt you for the entry text---if you specify
9225 it, the entry will be created in @code{org-agenda-diary-file} without further
9226 interaction. If you directly press @key{RET} at the prompt without typing
9227 text, the target file will be shown in another window for you to finish the
9228 entry there. See also the @kbd{k r} command.
9230 @orgcmd{M,org-agenda-phases-of-moon}
9231 Show the phases of the moon for the three months around current date.
9233 @orgcmd{S,org-agenda-sunrise-sunset}
9234 Show sunrise and sunset times. The geographical location must be set
9235 with calendar variables, see the documentation for the Emacs calendar.
9237 @orgcmd{C,org-agenda-convert-date}
9238 Convert the date at cursor into many other cultural and historic
9241 @orgcmd{H,org-agenda-holidays}
9242 Show holidays for three months around the cursor date.
9244 @item M-x org-icalendar-combine-agenda-files RET
9245 Export a single iCalendar file containing entries from all agenda files.
9246 This is a globally available command, and also available in the agenda menu.
9248 @tsubheading{Exporting to a file}
9249 @orgcmd{C-x C-w,org-agenda-write}
9250 @cindex exporting agenda views
9251 @cindex agenda views, exporting
9252 @vindex org-agenda-exporter-settings
9253 Write the agenda view to a file. Depending on the extension of the selected
9254 file name, the view will be exported as HTML (@file{.html} or @file{.htm}),
9255 Postscript (@file{.ps}), PDF (@file{.pdf}), Org (@file{.org}) and plain text
9256 (any other extension). When exporting to Org, only the body of original
9257 headlines are exported, not subtrees or inherited tags. When called with a
9258 @kbd{C-u} prefix argument, immediately open the newly created file. Use the
9259 variable @code{org-agenda-exporter-settings} to set options for
9260 @file{ps-print} and for @file{htmlize} to be used during export.
9262 @tsubheading{Quit and Exit}
9263 @orgcmd{q,org-agenda-quit}
9264 Quit agenda, remove the agenda buffer.
9266 @cindex agenda files, removing buffers
9267 @orgcmd{x,org-agenda-exit}
9268 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
9269 for the compilation of the agenda. Buffers created by the user to
9270 visit Org files will not be removed.
9274 @node Custom agenda views
9275 @section Custom agenda views
9276 @cindex custom agenda views
9277 @cindex agenda views, custom
9279 Custom agenda commands serve two purposes: to store and quickly access
9280 frequently used TODO and tags searches, and to create special composite
9281 agenda buffers. Custom agenda commands will be accessible through the
9282 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
9285 * Storing searches:: Type once, use often
9286 * Block agenda:: All the stuff you need in a single buffer
9287 * Setting options:: Changing the rules
9290 @node Storing searches
9291 @subsection Storing searches
9293 The first application of custom searches is the definition of keyboard
9294 shortcuts for frequently used searches, either creating an agenda
9295 buffer, or a sparse tree (the latter covering of course only the current
9298 @vindex org-agenda-custom-commands
9299 @cindex agenda views, main example
9300 @cindex agenda, as an agenda views
9301 @cindex agenda*, as an agenda views
9302 @cindex tags, as an agenda view
9303 @cindex todo, as an agenda view
9309 Custom commands are configured in the variable
9310 @code{org-agenda-custom-commands}. You can customize this variable, for
9311 example by pressing @kbd{C-c a C}. You can also directly set it with Emacs
9312 Lisp in the Emacs init file. The following example contains all valid agenda
9317 (setq org-agenda-custom-commands
9320 ("w" todo "WAITING")
9321 ("W" todo-tree "WAITING")
9322 ("u" tags "+boss-urgent")
9323 ("v" tags-todo "+boss-urgent")
9324 ("U" tags-tree "+boss-urgent")
9325 ("f" occur-tree "\\<FIXME\\>")
9326 ("h" . "HOME+Name tags searches") ; description for "h" prefix
9327 ("hl" tags "+home+Lisa")
9328 ("hp" tags "+home+Peter")
9329 ("hk" tags "+home+Kim")))
9334 The initial string in each entry defines the keys you have to press
9335 after the dispatcher command @kbd{C-c a} in order to access the command.
9336 Usually this will be just a single character, but if you have many
9337 similar commands, you can also define two-letter combinations where the
9338 first character is the same in several combinations and serves as a
9339 prefix key@footnote{You can provide a description for a prefix key by
9340 inserting a cons cell with the prefix and the description.}. The second
9341 parameter is the search type, followed by the string or regular
9342 expression to be used for the matching. The example above will
9347 as a global search for agenda entries planned@footnote{@emph{Planned} means
9348 here that these entries have some planning information attached to them, like
9349 a time-stamp, a scheduled or a deadline string. See
9350 @code{org-agenda-entry-types} on how to set what planning information will be
9351 taken into account.} this week/day.
9353 as a global search for agenda entries planned this week/day, but only those
9354 with an hour specification like @code{[h]h:mm}---think of them as appointments.
9356 as a global search for TODO entries with @samp{WAITING} as the TODO
9359 as the same search, but only in the current buffer and displaying the
9360 results as a sparse tree
9362 as a global tags search for headlines marked @samp{:boss:} but not
9365 as the same search as @kbd{C-c a u}, but limiting the search to
9366 headlines that are also TODO items
9368 as the same search as @kbd{C-c a u}, but only in the current buffer and
9369 displaying the result as a sparse tree
9371 to create a sparse tree (again: current buffer only) with all entries
9372 containing the word @samp{FIXME}
9374 as a prefix command for a HOME tags search where you have to press an
9375 additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,
9376 Peter, or Kim) as additional tag to match.
9379 Note that the @code{*-tree} agenda views need to be called from an
9380 Org buffer as they operate on the current buffer only.
9383 @subsection Block agenda
9384 @cindex block agenda
9385 @cindex agenda, with block views
9387 Another possibility is the construction of agenda views that comprise
9388 the results of @emph{several} commands, each of which creates a block in
9389 the agenda buffer. The available commands include @code{agenda} for the
9390 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
9391 for the global TODO list (as constructed with @kbd{C-c a t}), and the
9392 matching commands discussed above: @code{todo}, @code{tags}, and
9393 @code{tags-todo}. Here are two examples:
9397 (setq org-agenda-custom-commands
9398 '(("h" "Agenda and Home-related tasks"
9402 ("o" "Agenda and Office-related tasks"
9410 This will define @kbd{C-c a h} to create a multi-block view for stuff
9411 you need to attend to at home. The resulting agenda buffer will contain
9412 your agenda for the current week, all TODO items that carry the tag
9413 @samp{home}, and also all lines tagged with @samp{garden}. Finally the
9414 command @kbd{C-c a o} provides a similar view for office tasks.
9416 @node Setting options
9417 @subsection Setting options for custom commands
9418 @cindex options, for custom agenda views
9420 @vindex org-agenda-custom-commands
9421 Org mode contains a number of variables regulating agenda construction
9422 and display. The global variables define the behavior for all agenda
9423 commands, including the custom commands. However, if you want to change
9424 some settings just for a single custom view, you can do so. Setting
9425 options requires inserting a list of variable names and values at the
9426 right spot in @code{org-agenda-custom-commands}. For example:
9430 (setq org-agenda-custom-commands
9431 '(("w" todo "WAITING"
9432 ((org-agenda-sorting-strategy '(priority-down))
9433 (org-agenda-prefix-format " Mixed: ")))
9434 ("U" tags-tree "+boss-urgent"
9435 ((org-show-context-detail 'minimal)))
9437 ((org-agenda-files '("~org/notes.org"))
9438 (org-agenda-text-search-extra-files nil)))))
9443 Now the @kbd{C-c a w} command will sort the collected entries only by
9444 priority, and the prefix format is modified to just say @samp{ Mixed: }
9445 instead of giving the category of the entry. The sparse tags tree of
9446 @kbd{C-c a U} will now turn out ultra-compact, because neither the
9447 headline hierarchy above the match, nor the headline following the match
9448 will be shown. The command @kbd{C-c a N} will do a text search limited
9449 to only a single file.
9451 @vindex org-agenda-custom-commands
9452 For command sets creating a block agenda,
9453 @code{org-agenda-custom-commands} has two separate spots for setting
9454 options. You can add options that should be valid for just a single
9455 command in the set, and options that should be valid for all commands in
9456 the set. The former are just added to the command entry; the latter
9457 must come after the list of command entries. Going back to the block
9458 agenda example (@pxref{Block agenda}), let's change the sorting strategy
9459 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
9460 the results for GARDEN tags query in the opposite order,
9461 @code{priority-up}. This would look like this:
9465 (setq org-agenda-custom-commands
9466 '(("h" "Agenda and Home-related tasks"
9470 ((org-agenda-sorting-strategy '(priority-up)))))
9471 ((org-agenda-sorting-strategy '(priority-down))))
9472 ("o" "Agenda and Office-related tasks"
9479 As you see, the values and parentheses setting is a little complex.
9480 When in doubt, use the customize interface to set this variable---it
9481 fully supports its structure. Just one caveat: when setting options in
9482 this interface, the @emph{values} are just Lisp expressions. So if the
9483 value is a string, you need to add the double-quotes around the value
9486 @vindex org-agenda-custom-commands-contexts
9487 To control whether an agenda command should be accessible from a specific
9488 context, you can customize @code{org-agenda-custom-commands-contexts}. Let's
9489 say for example that you have an agenda command @code{"o"} displaying a view
9490 that you only need when reading emails. Then you would configure this option
9494 (setq org-agenda-custom-commands-contexts
9495 '(("o" (in-mode . "message-mode"))))
9498 You can also tell that the command key @code{"o"} should refer to another
9499 command key @code{"r"}. In that case, add this command key like this:
9502 (setq org-agenda-custom-commands-contexts
9503 '(("o" "r" (in-mode . "message-mode"))))
9506 See the docstring of the variable for more information.
9508 @node Exporting agenda views
9509 @section Exporting agenda views
9510 @cindex agenda views, exporting
9512 If you are away from your computer, it can be very useful to have a printed
9513 version of some agenda views to carry around. Org mode can export custom
9514 agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's
9515 @file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the
9516 ghostscript @file{ps2pdf} utility must be installed on the system. Selecting
9517 a PDF file will also create the postscript file.}, and iCalendar files. If
9518 you want to do this only occasionally, use the command
9521 @orgcmd{C-x C-w,org-agenda-write}
9522 @cindex exporting agenda views
9523 @cindex agenda views, exporting
9524 @vindex org-agenda-exporter-settings
9525 Write the agenda view to a file. Depending on the extension of the selected
9526 file name, the view will be exported as HTML (extension @file{.html} or
9527 @file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension
9528 @file{.ics}), or plain text (any other extension). Use the variable
9529 @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
9530 for @file{htmlize} to be used during export, for example
9532 @vindex org-agenda-add-entry-text-maxlines
9533 @vindex htmlize-output-type
9534 @vindex ps-number-of-columns
9535 @vindex ps-landscape-mode
9537 (setq org-agenda-exporter-settings
9538 '((ps-number-of-columns 2)
9539 (ps-landscape-mode t)
9540 (org-agenda-add-entry-text-maxlines 5)
9541 (htmlize-output-type 'css)))
9545 If you need to export certain agenda views frequently, you can associate
9546 any custom agenda command with a list of output file names
9547 @footnote{If you want to store standard views like the weekly agenda
9548 or the global TODO list as well, you need to define custom commands for
9549 them in order to be able to specify file names.}. Here is an example
9550 that first defines custom commands for the agenda and the global
9551 TODO list, together with a number of files to which to export them.
9552 Then we define two block agenda commands and specify file names for them
9553 as well. File names can be relative to the current working directory,
9558 (setq org-agenda-custom-commands
9559 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
9560 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
9561 ("h" "Agenda and Home-related tasks"
9566 ("~/views/home.html"))
9567 ("o" "Agenda and Office-related tasks"
9572 ("~/views/office.ps" "~/calendars/office.ics"))))
9576 The extension of the file name determines the type of export. If it is
9577 @file{.html}, Org mode will use the @file{htmlize.el} package to convert
9578 the buffer to HTML and save it to this file name. If the extension is
9579 @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
9580 Postscript output. If the extension is @file{.ics}, iCalendar export is
9581 run export over all files that were used to construct the agenda, and
9582 limit the export to entries listed in the agenda. Any other
9583 extension produces a plain ASCII file.
9585 The export files are @emph{not} created when you use one of those
9586 commands interactively because this might use too much overhead.
9587 Instead, there is a special command to produce @emph{all} specified
9591 @orgcmd{C-c a e,org-store-agenda-views}
9592 Export all agenda views that have export file names associated with
9596 You can use the options section of the custom agenda commands to also
9597 set options for the export commands. For example:
9600 (setq org-agenda-custom-commands
9602 ((ps-number-of-columns 2)
9603 (ps-landscape-mode t)
9604 (org-agenda-prefix-format " [ ] ")
9605 (org-agenda-with-colors nil)
9606 (org-agenda-remove-tags t))
9611 This command sets two options for the Postscript exporter, to make it
9612 print in two columns in landscape format---the resulting page can be cut
9613 in two and then used in a paper agenda. The remaining settings modify
9614 the agenda prefix to omit category and scheduling information, and
9615 instead include a checkbox to check off items. We also remove the tags
9616 to make the lines compact, and we don't want to use colors for the
9617 black-and-white printer. Settings specified in
9618 @code{org-agenda-exporter-settings} will also apply, but the settings
9619 in @code{org-agenda-custom-commands} take precedence.
9622 From the command line you may also use
9624 emacs -eval (org-batch-store-agenda-views) -kill
9627 or, if you need to modify some parameters@footnote{Quoting depends on the
9628 system you use, please check the FAQ for examples.}
9630 emacs -eval '(org-batch-store-agenda-views \
9631 org-agenda-span (quote month) \
9632 org-agenda-start-day "2007-11-01" \
9633 org-agenda-include-diary nil \
9634 org-agenda-files (quote ("~/org/project.org")))' \
9638 which will create the agenda views restricted to the file
9639 @file{~/org/project.org}, without diary entries and with a 30-day
9642 You can also extract agenda information in a way that allows further
9643 processing by other programs. See @ref{Extracting agenda information}, for
9647 @node Agenda column view
9648 @section Using column view in the agenda
9649 @cindex column view, in agenda
9650 @cindex agenda, column view
9652 Column view (@pxref{Column view}) is normally used to view and edit
9653 properties embedded in the hierarchical structure of an Org file. It can be
9654 quite useful to use column view also from the agenda, where entries are
9655 collected by certain criteria.
9658 @orgcmd{C-c C-x C-c,org-agenda-columns}
9659 Turn on column view in the agenda.
9662 To understand how to use this properly, it is important to realize that the
9663 entries in the agenda are no longer in their proper outline environment.
9664 This causes the following issues:
9668 @vindex org-columns-default-format
9669 @vindex org-overriding-columns-format
9670 Org needs to make a decision which @code{COLUMNS} format to use. Since the
9671 entries in the agenda are collected from different files, and different files
9672 may have different @code{COLUMNS} formats, this is a non-trivial problem.
9673 Org first checks if the variable @code{org-agenda-overriding-columns-format}
9674 is currently set, and if so, takes the format from there. Otherwise it takes
9675 the format associated with the first item in the agenda, or, if that item
9676 does not have a specific format---defined in a property, or in its file---it
9677 uses @code{org-columns-default-format}.
9680 @cindex property, special, CLOCKSUM
9681 If any of the columns has a summary type defined (@pxref{Column attributes}),
9682 turning on column view in the agenda will visit all relevant agenda files and
9683 make sure that the computations of this property are up to date. This is
9684 also true for the special @code{CLOCKSUM} property. Org will then sum the
9685 values displayed in the agenda. In the daily/weekly agenda, the sums will
9686 cover a single day; in all other views they cover the entire block. It is
9687 vital to realize that the agenda may show the same entry @emph{twice}---for
9688 example as scheduled and as a deadline---and it may show two entries from the
9689 same hierarchy---for example a @emph{parent} and its @emph{child}. In these
9690 cases, the summation in the agenda will lead to incorrect results because
9691 some values will count double.
9694 When the column view in the agenda shows the @code{CLOCKSUM}, that is always
9695 the entire clocked time for this item. So even in the daily/weekly agenda,
9696 the clocksum listed in column view may originate from times outside the
9697 current view. This has the advantage that you can compare these values with
9698 a column listing the planned total effort for a task---one of the major
9699 applications for column view in the agenda. If you want information about
9700 clocked time in the displayed period use clock table mode (press @kbd{R} in
9704 @cindex property, special, CLOCKSUM_T
9705 When the column view in the agenda shows the @code{CLOCKSUM_T}, that is
9706 always today's clocked time for this item. So even in the weekly agenda, the
9707 clocksum listed in column view only originates from today. This lets you
9708 compare the time you spent on a task for today, with the time already
9709 spent ---via @code{CLOCKSUM}---and with the planned total effort for it.
9714 @chapter Markup for rich export
9716 When exporting Org mode documents, the exporter tries to reflect the
9717 structure of the document as accurately as possible in the back-end. Since
9718 export targets like HTML and @LaTeX{} allow much richer formatting, Org mode has
9719 rules on how to prepare text for rich export. This section summarizes the
9720 markup rules used in an Org mode buffer.
9723 * Paragraphs:: The basic unit of text
9724 * Emphasis and monospace:: Bold, italic, etc.
9725 * Horizontal rules:: Make a line
9726 * Images and tables:: Images, tables and caption mechanism
9727 * Literal examples:: Source code examples with special formatting
9728 * Special symbols:: Greek letters and other symbols
9729 * Subscripts and superscripts:: Simple syntax for raising/lowering text
9730 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
9734 @section Paragraphs, line breaks, and quoting
9735 @cindex paragraphs, markup rules
9737 Paragraphs are separated by at least one empty line. If you need to enforce
9738 a line break within a paragraph, use @samp{\\} at the end of a line.
9740 To preserve the line breaks, indentation and blank lines in a region, but
9741 otherwise use normal formatting, you can use this construct, which can also
9742 be used to format poetry.
9744 @cindex #+BEGIN_VERSE
9745 @cindex verse blocks
9748 Great clouds overhead
9749 Tiny black birds rise and fall
9756 When quoting a passage from another document, it is customary to format this
9757 as a paragraph that is indented on both the left and the right margin. You
9758 can include quotations in Org mode documents like this:
9760 @cindex #+BEGIN_QUOTE
9761 @cindex quote blocks
9764 Everything should be made as simple as possible,
9765 but not any simpler -- Albert Einstein
9769 If you would like to center some text, do it like this:
9770 @cindex #+BEGIN_CENTER
9771 @cindex center blocks
9774 Everything should be made as simple as possible, \\
9779 @node Emphasis and monospace
9780 @section Emphasis and monospace
9782 @cindex underlined text, markup rules
9783 @cindex bold text, markup rules
9784 @cindex italic text, markup rules
9785 @cindex verbatim text, markup rules
9786 @cindex code text, markup rules
9787 @cindex strike-through text, markup rules
9788 @vindex org-fontify-emphasized-text
9789 @vindex org-emphasis-regexp-components
9790 @vindex org-emphasis-alist
9791 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=verbatim=}
9792 and @code{~code~}, and, if you must, @samp{+strike-through+}. Text
9793 in the code and verbatim string is not processed for Org mode specific
9794 syntax, it is exported verbatim.
9796 To turn off fontification for marked up text, you can set
9797 @code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of
9798 available markup syntax, you can customize @code{org-emphasis-alist}. To fine
9799 tune what characters are allowed before and after the markup characters, you
9800 can tweak @code{org-emphasis-regexp-components}. Beware that changing one of
9801 the above variables will no take effect until you reload Org, for which you
9802 may need to restart Emacs.
9804 @node Horizontal rules
9805 @section Horizontal rules
9806 @cindex horizontal rules, markup rules
9807 A line consisting of only dashes, and at least 5 of them, will be exported as
9810 @node Images and tables
9811 @section Images and Tables
9813 @cindex tables, markup rules
9816 Both the native Org mode tables (@pxref{Tables}) and tables formatted with
9817 the @file{table.el} package will be exported properly. For Org mode tables,
9818 the lines before the first horizontal separator line will become table header
9819 lines. You can use the following lines somewhere before the table to assign
9820 a caption and a label for cross references, and in the text you can refer to
9821 the object with @code{[[tab:basic-data]]} (@pxref{Internal links}):
9824 #+CAPTION: This is the caption for the next table (or link)
9825 #+NAME: tab:basic-data
9830 Optionally, the caption can take the form:
9832 #+CAPTION[Caption for list of tables]: Caption for table.
9835 @cindex inlined images, markup rules
9836 Some back-ends allow you to directly include images into the exported
9837 document. Org does this, if a link to an image files does not have
9838 a description part, for example @code{[[./img/a.jpg]]}. If you wish to
9839 define a caption for the image and maybe a label for internal cross
9840 references, make sure that the link is on a line by itself and precede it
9841 with @code{#+CAPTION} and @code{#+NAME} as follows:
9844 #+CAPTION: This is the caption for the next figure link (or table)
9845 #+NAME: fig:SED-HR4049
9850 Such images can be displayed within the buffer. @xref{Handling links,the
9851 discussion of image links}.
9853 Even though images and tables are prominent examples of captioned structures,
9854 the same caption mechanism can apply to many others (e.g., @LaTeX{}
9855 equations, source code blocks). Depending on the export back-end, those may
9856 or may not be handled.
9858 @node Literal examples
9859 @section Literal examples
9860 @cindex literal examples, markup rules
9861 @cindex code line references, markup rules
9863 You can include literal examples that should not be subjected to
9864 markup. Such examples will be typeset in monospace, so this is well suited
9865 for source code and similar examples.
9866 @cindex #+BEGIN_EXAMPLE
9870 Some example from a text file.
9874 Note that such blocks may be @i{indented} in order to align nicely with
9875 indented text and in particular with plain list structure (@pxref{Plain
9876 lists}). For simplicity when using small examples, you can also start the
9877 example lines with a colon followed by a space. There may also be additional
9878 whitespace before the colon:
9882 : Some example from a text file.
9885 @cindex formatting source code, markup rules
9886 @vindex org-latex-listings
9887 If the example is source code from a programming language, or any other text
9888 that can be marked up by font-lock in Emacs, you can ask for the example to
9889 look like the fontified Emacs buffer@footnote{This works automatically for
9890 the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package,
9891 which is distributed with Org). Fontified code chunks in @LaTeX{} can be
9892 achieved using either the
9893 @url{https://www.ctan.org/tex-archive/macros/latex/contrib/listings/?lang=en, listings,}
9895 @url{https://github.com/gpoore/minted, minted,} package.
9896 If you use minted or listing, you must load the packages manually, for
9897 example by adding the desired package to
9898 @code{org-latex-packages-alist}. Refer to @code{org-latex-listings}
9899 for details.}. This is done with the @samp{src} block, where you also need
9900 to specify the name of the major mode that should be used to fontify the
9901 example@footnote{Code in @samp{src} blocks may also be evaluated either
9902 interactively or on export. @xref{Working with source code}, for more
9903 information on evaluating code blocks.}, see @ref{Easy templates} for
9904 shortcuts to easily insert code blocks.
9908 #+BEGIN_SRC emacs-lisp
9909 (defun org-xor (a b)
9915 Both in @code{example} and in @code{src} snippets, you can add a @code{-n}
9916 switch to the end of the @code{BEGIN} line, to get the lines of the example
9917 numbered. The @code{-n} takes an optional numeric argument specifying the
9918 starting line number of the block. If you use a @code{+n} switch, the
9919 numbering from the previous numbered snippet will be continued in the current
9920 one. The @code{+n} can also take a numeric argument. The value of the
9921 argument will be added to the last line of the previous block to determine
9922 the starting line number.
9925 #+BEGIN_SRC emacs-lisp -n 20
9926 ;; this will export with line number 20
9927 (message "This is line 21")
9929 #+BEGIN_SRC emacs-lisp +n 10
9930 ;; This will be listed as line 31
9931 (message "This is line 32")
9935 In literal examples, Org will interpret strings like @samp{(ref:name)} as
9936 labels, and use them as targets for special hyperlinks like @code{[[(name)]]}
9937 (i.e., the reference name enclosed in single parenthesis). In HTML, hovering
9938 the mouse over such a link will remote-highlight the corresponding code line,
9939 which is kind of cool.
9941 You can also add a @code{-r} switch which @i{removes} the labels from the
9942 source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
9943 labels in the source code while using line numbers for the links, which might
9944 be useful to explain those in an Org mode example code.}. With the @code{-n}
9945 switch, links to these references will be labeled by the line numbers from
9946 the code listing, otherwise links will use the labels with no parentheses.
9950 #+BEGIN_SRC emacs-lisp -n -r
9951 (save-excursion (ref:sc)
9952 (goto-char (point-min))) (ref:jump)
9954 In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
9958 @cindex indentation, in source blocks
9959 Finally, you can use @code{-i} to preserve the indentation of a specific code
9960 block (@pxref{Editing source code}).
9962 @vindex org-coderef-label-format
9963 If the syntax for the label format conflicts with the language syntax, use a
9964 @code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
9965 -n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}.
9967 HTML export also allows examples to be published as text areas (@pxref{Text
9968 areas in HTML export}).
9970 Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
9971 so often, shortcuts are provided using the Easy templates facility
9972 (@pxref{Easy templates}).
9977 Edit the source code example at point in its native mode. This works by
9978 switching to a temporary buffer with the source code. You need to exit by
9979 pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*},
9980 @samp{,*}, @samp{#+} and @samp{,#+} will get a comma prepended, to keep them
9981 from being interpreted by Org as outline nodes or special syntax. These
9982 commas will be stripped for editing with @kbd{C-c '}, and also for export.}.
9983 The edited version will then replace the old version in the Org buffer.
9984 Fixed-width regions (where each line starts with a colon followed by a space)
9985 will be edited using @code{artist-mode}@footnote{You may select
9986 a different-mode with the variable @code{org-edit-fixed-width-region-mode}.}
9987 to allow creating ASCII drawings easily. Using this command in an empty line
9988 will create a new fixed-width region.
9991 Calling @code{org-store-link} while editing a source code example in a
9992 temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure
9993 that it is unique in the current buffer, and insert it with the proper
9994 formatting like @samp{(ref:label)} at the end of the current line. Then the
9995 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
9998 @node Special symbols
9999 @section Special symbols
10000 @cindex Org entities
10001 @cindex math symbols
10002 @cindex special symbols
10003 @cindex HTML entities
10004 @cindex @LaTeX{} entities
10006 You can use @LaTeX{}-like syntax to insert special symbols---named
10007 entities---like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to
10008 indicate an arrow. Completion for these symbols is available, just type
10009 @samp{\} and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible
10010 completions. If you need such a symbol inside a word, terminate it with
10011 a pair of curly brackets. For example
10014 Protip: Given a circle \Gamma of diameter d, the length of its circumference
10018 @findex org-entities-help
10019 @vindex org-entities-user
10020 A large number of entities is provided, with names taken from both HTML and
10021 @LaTeX{}; you can comfortably browse the complete list from a dedicated
10022 buffer using the command @code{org-entities-help}. It is also possible to
10023 provide your own special symbols in the variable @code{org-entities-user}.
10025 During export, these symbols are transformed into the native format of the
10026 exporter back-end. Strings like @code{\alpha} are exported as @code{α}
10027 in the HTML output, and as @code{\(\alpha\)} in the @LaTeX{} output.
10028 Similarly, @code{\nbsp} becomes @code{ } in HTML and @code{~} in
10031 @cindex escaping characters
10032 Entities may also be used as a may to escape markup in an Org document, e.g.,
10033 @samp{\under@{@}not underlined\under} exports as @samp{_not underlined_}.
10035 @cindex special symbols, in-buffer display
10036 If you would like to see entities displayed as UTF-8 characters, use the
10037 following command@footnote{You can turn this on by default by setting the
10038 variable @code{org-pretty-entities}, or on a per-file base with the
10039 @code{#+STARTUP} option @code{entitiespretty}.}:
10042 @cindex @code{entitiespretty}, STARTUP keyword
10045 Toggle display of entities as UTF-8 characters. This does not change the
10046 buffer content which remains plain ASCII, but it overlays the UTF-8 character
10047 for display purposes only.
10050 @cindex shy hyphen, special symbol
10051 @cindex dash, special symbol
10052 @cindex ellipsis, special symbol
10053 In addition to regular entities defined above, Org exports in a special
10054 way@footnote{This behaviour can be disabled with @code{-} export setting
10055 (@pxref{Export settings}).} the following commonly used character
10056 combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---}
10057 are converted into dashes, and @samp{...} becomes a compact set of dots.
10059 @node Subscripts and superscripts
10060 @section Subscripts and superscripts
10062 @cindex superscript
10064 @samp{^} and @samp{_} are used to indicate super- and subscripts. To
10065 increase the readability of ASCII text, it is not necessary---but OK---to
10066 surround multi-character sub- and superscripts with curly braces. Those are,
10067 however, mandatory, when more than one word is involved. For example
10070 The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, the
10071 radius of Alpha Centauri is R_@{Alpha Centauri@} = 1.28 x R_@{sun@}.
10074 @vindex org-use-sub-superscripts
10075 If you write a text where the underscore is often used in a different
10076 context, Org's convention to always interpret these as subscripts can get in
10077 your way. Configure the variable @code{org-use-sub-superscripts} to change
10078 this convention. For example, when setting this variable to @code{@{@}},
10079 @samp{a_b} will not be interpreted as a subscript, but @samp{a_@{b@}} will.
10084 In addition to showing entities as UTF-8 characters, this command will also
10085 format sub- and superscripts in a WYSIWYM way.
10088 @node Embedded @LaTeX{}
10089 @section Embedded @LaTeX{}
10090 @cindex @TeX{} interpretation
10091 @cindex @LaTeX{} interpretation
10093 Plain ASCII is normally sufficient for almost all note taking. Exceptions
10094 include scientific notes, which often require mathematical symbols and the
10095 occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on
10096 Donald E. Knuth's @TeX{} system. Many of the features described here as
10097 ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
10098 distinction.} is widely used to typeset scientific documents. Org mode
10099 supports embedding @LaTeX{} code into its files, because many academics are
10100 used to writing and reading @LaTeX{} source code, and because it can be
10101 readily processed to produce pretty output for a number of export back-ends.
10104 * @LaTeX{} fragments:: Complex formulas made easy
10105 * Previewing @LaTeX{} fragments:: What will this snippet look like?
10106 * CDLaTeX mode:: Speed up entering of formulas
10109 @node @LaTeX{} fragments
10110 @subsection @LaTeX{} fragments
10111 @cindex @LaTeX{} fragments
10113 @vindex org-format-latex-header
10114 Org mode can contain @LaTeX{} math fragments, and it supports ways to process
10115 these for several export back-ends. When exporting to @LaTeX{}, the code is
10116 left as it is. When exporting to HTML, Org can use either
10117 @uref{http://www.mathjax.org, MathJax} (@pxref{Math formatting in HTML
10118 export}) or transcode the math into images (see @pxref{Previewing @LaTeX{}
10121 @LaTeX{} fragments don't need any special marking at all. The following
10122 snippets will be identified as @LaTeX{} source code:
10125 Environments of any kind@footnote{When MathJax is used, only the
10126 environments recognized by MathJax will be processed. When
10127 @file{dvipng} program, @file{dvisvgm} program or @file{imagemagick} suite is
10128 used to create images, any @LaTeX{} environment will be handled.}. The only
10129 requirement is that the @code{\begin} statement appears on a new line, at the
10130 beginning of the line or after whitespaces only.
10132 Text within the usual @LaTeX{} math delimiters. To avoid conflicts with
10133 currency specifications, single @samp{$} characters are only recognized as
10134 math delimiters if the enclosed text contains at most two line breaks, is
10135 directly attached to the @samp{$} characters with no whitespace in between,
10136 and if the closing @samp{$} is followed by whitespace or punctuation
10137 (parentheses and quotes are considered to be punctuation in this
10138 context). For the other delimiters, there is no such restriction, so when in
10139 doubt, use @samp{\(...\)} as inline math delimiters.
10142 @noindent For example:
10149 If $a^2=b$ and \( b=2 \), then the solution must be
10150 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
10155 @c @vindex org-format-latex-options
10156 @c If you need any of the delimiter ASCII sequences for other purposes, you
10157 @c can configure the option @code{org-format-latex-options} to deselect the
10158 @c ones you do not wish to have interpreted by the @LaTeX{} converter.
10160 @vindex org-export-with-latex
10161 @LaTeX{} processing can be configured with the variable
10162 @code{org-export-with-latex}. The default setting is @code{t} which means
10163 MathJax for HTML, and no processing for ASCII and @LaTeX{} back-ends.
10164 You can also set this variable on a per-file basis using one of these
10168 #+OPTIONS: tex:t @r{Do the right thing automatically (MathJax)}
10169 #+OPTIONS: tex:nil @r{Do not process @LaTeX{} fragments at all}
10170 #+OPTIONS: tex:verbatim @r{Verbatim export, for jsMath or so}
10173 @node Previewing @LaTeX{} fragments
10174 @subsection Previewing @LaTeX{} fragments
10175 @cindex @LaTeX{} fragments, preview
10177 @vindex org-preview-latex-default-process
10178 If you have a working @LaTeX{} installation and @file{dvipng}, @file{dvisvgm}
10179 or @file{convert} installed@footnote{These are respectively available at
10180 @url{http://sourceforge.net/projects/dvipng/}, @url{http://dvisvgm.bplaced.net/}
10181 and from the @file{imagemagick} suite. Choose the converter by setting the
10182 variable @code{org-preview-latex-default-process} accordingly.}, @LaTeX{}
10183 fragments can be processed to produce images of the typeset expressions to be
10184 used for inclusion while exporting to HTML (see @pxref{@LaTeX{} fragments}),
10185 or for inline previewing within Org mode.
10187 @vindex org-format-latex-options
10188 @vindex org-format-latex-header
10189 You can customize the variables @code{org-format-latex-options} and
10190 @code{org-format-latex-header} to influence some aspects of the preview. In
10191 particular, the @code{:scale} (and for HTML export, @code{:html-scale})
10192 property of the former can be used to adjust the size of the preview images.
10195 @kindex C-c C-x C-l
10197 Produce a preview image of the @LaTeX{} fragment at point and overlay it
10198 over the source code. If there is no fragment at point, process all
10199 fragments in the current entry (between two headlines). When called
10200 with a prefix argument, process the entire subtree. When called with
10201 two prefix arguments, or when the cursor is before the first headline,
10202 process the entire buffer.
10205 Remove the overlay preview images.
10208 @vindex org-startup-with-latex-preview
10209 You can turn on the previewing of all @LaTeX{} fragments in a file with
10212 #+STARTUP: latexpreview
10215 To disable it, simply use
10218 #+STARTUP: nolatexpreview
10222 @subsection Using CD@LaTeX{} to enter math
10225 CD@LaTeX{} mode is a minor mode that is normally used in combination with a
10226 major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
10227 environments and math templates. Inside Org mode, you can make use of
10228 some of the features of CD@LaTeX{} mode. You need to install
10229 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
10230 AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
10231 Don't use CD@LaTeX{} mode itself under Org mode, but use the light
10232 version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it
10233 on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all
10237 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
10240 When this mode is enabled, the following features are present (for more
10241 details see the documentation of CD@LaTeX{} mode):
10245 Environment templates can be inserted with @kbd{C-c @{}.
10248 The @key{TAB} key will do template expansion if the cursor is inside a
10249 @LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is
10250 inside such a fragment, see the documentation of the function
10251 @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
10252 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
10253 correctly inside the first brace. Another @key{TAB} will get you into
10254 the second brace. Even outside fragments, @key{TAB} will expand
10255 environment abbreviations at the beginning of a line. For example, if
10256 you write @samp{equ} at the beginning of a line and press @key{TAB},
10257 this abbreviation will be expanded to an @code{equation} environment.
10258 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help RET}.
10262 @vindex cdlatex-simplify-sub-super-scripts
10263 Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these
10264 characters together with a pair of braces. If you use @key{TAB} to move
10265 out of the braces, and if the braces surround only a single character or
10266 macro, they are removed again (depending on the variable
10267 @code{cdlatex-simplify-sub-super-scripts}).
10270 Pressing the grave accent @kbd{`} followed by a character inserts math
10271 macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds
10272 after the grave accent, a help window will pop up.
10275 Pressing the apostrophe @kbd{'} followed by another character modifies
10276 the symbol before point with an accent or a font. If you wait more than
10277 1.5 seconds after the apostrophe, a help window will pop up. Character
10278 modification will work only inside @LaTeX{} fragments; outside the quote
10286 Sometimes, you may want to pretty print your notes, publish them on the web
10287 or even share them with people not using Org. In these cases, the Org export
10288 facilities can be used to convert your documents to a variety of other
10289 formats, while retaining as much structure (@pxref{Document structure}) and
10290 markup (@pxref{Markup}) as possible.
10292 @cindex export back-end
10293 Libraries responsible for such translation are called back-ends. Org ships
10294 with the following ones
10297 @item ascii (ASCII format)
10298 @item beamer (@LaTeX{} Beamer format)
10299 @item html (HTML format)
10300 @item icalendar (iCalendar format)
10301 @item latex (@LaTeX{} format)
10302 @item md (Markdown format)
10303 @item odt (OpenDocument Text format)
10304 @item org (Org format)
10305 @item texinfo (Texinfo format)
10306 @item man (Man page format)
10309 @noindent Org also uses additional libraries located in @code{contrib/}
10310 directory (@pxref{Installation}). Users can install additional export
10311 libraries for additional formats from the Emacs packaging system. For easy
10312 discovery, these packages have a common naming scheme: @file{ox-NAME}, where
10313 NAME is one of the formats. For example, @file{ox-koma-letter} for
10314 @code{koma-letter} back-end.
10316 @vindex org-export-backends
10317 Org loads back-ends for the following formats by default: @code{ascii},
10318 @code{html}, @code{icalendar}, @code{latex} and @code{odt}.
10320 Org can load additional back-ends either of two ways: through the
10321 @code{org-export-backends} variable configuration; or, by requiring the
10322 library in the Emacs init file like this:
10329 * The export dispatcher:: The main interface
10330 * Export settings:: Common export settings
10331 * Table of contents:: The if and where of the table of contents
10332 * Include files:: Include additional files into a document
10333 * Macro replacement:: Use macros to create templates
10334 * Comment lines:: What will not be exported
10335 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
10336 * Beamer export:: Exporting as a Beamer presentation
10337 * HTML export:: Exporting to HTML
10338 * @LaTeX{} export:: Exporting to @LaTeX{}, and processing to PDF
10339 * Markdown export:: Exporting to Markdown
10340 * OpenDocument Text export:: Exporting to OpenDocument Text
10341 * Org export:: Exporting to Org
10342 * Texinfo export:: Exporting to Texinfo
10343 * iCalendar export:: Exporting to iCalendar
10344 * Other built-in back-ends:: Exporting to a man page
10345 * Advanced configuration:: Fine-tuning the export output
10346 * Export in foreign buffers:: Author tables and lists in Org syntax
10349 @node The export dispatcher
10350 @section The export dispatcher
10351 @vindex org-export-dispatch-use-expert-ui
10352 @cindex Export, dispatcher
10354 The export dispatcher is the main interface for Org's exports. A
10355 hierarchical menu presents the currently configured export formats. Options
10356 are shown as easy toggle switches on the same screen.
10358 Org also has a minimal prompt interface for the export dispatcher. When the
10359 variable @code{org-export-dispatch-use-expert-ui} is set to a non-@code{nil}
10360 value, Org prompts in the minibuffer. To switch back to the hierarchical
10361 menu, press @key{?}.
10364 @orgcmd{C-c C-e,org-export-dispatch}
10366 Invokes the export dispatcher interface. The options show default settings.
10367 The @kbd{C-u} prefix argument preserves options from the previous export,
10368 including any sub-tree selections.
10372 Org exports the entire buffer by default. If the Org buffer has an active
10373 region, then Org exports just that region.
10375 These are the export options, the key combinations that toggle them
10376 (@pxref{Export settings}):
10380 @vindex org-export-async-init-file
10381 Toggles asynchronous export. Asynchronous export uses an external Emacs
10382 process with a specially configured initialization file to complete the
10383 exporting process in the background thereby releasing the current interface.
10384 This is particularly useful when exporting long documents.
10386 Output from an asynchronous export is saved on the ``the export stack''. To
10387 view this stack, call the export dispatcher with a double @kbd{C-u} prefix
10388 argument. If already in the export dispatcher menu, @kbd{&} displays the
10391 @vindex org-export-in-background
10392 To make the background export process the default, customize the variable,
10393 @code{org-export-in-background}.
10396 Toggle body-only export. Useful for excluding headers and footers in the
10397 export. Affects only those back-end formats that have such sections---like
10398 @code{<head>...</head>} in HTML.
10401 @vindex org-export-initial-scope
10402 Toggle sub-tree export. When turned on, Org exports only the sub-tree starting
10403 from the cursor position at the time the export dispatcher was invoked. Org
10404 uses the top heading of this sub-tree as the document's title. If the cursor
10405 is not on a heading, Org uses the nearest enclosing header. If the cursor is
10406 in the document preamble, Org signals an error and aborts export.
10408 To make the sub-tree export the default, customize the variable,
10409 @code{org-export-initial-scope}.
10412 Toggle visible-only export. Useful for exporting only visible parts of an
10413 Org document by adjusting outline visibility settings.
10416 @node Export settings
10417 @section Export settings
10418 @cindex Export, settings
10421 Export options can be set: globally with variables; for an individual file by
10422 making variables buffer-local with in-buffer settings (@pxref{In-buffer
10423 settings}), by setting individual keywords, or by specifying them in a
10424 compact form with the @code{#+OPTIONS} keyword; or for a tree by setting
10425 properties (@pxref{Properties and columns}). Options set at a specific level
10426 override options set at a more general level.
10428 @cindex #+SETUPFILE
10429 In-buffer settings may appear anywhere in the file, either directly or
10430 indirectly through a file included using @samp{#+SETUPFILE: filename} syntax.
10431 Option keyword sets tailored to a particular back-end can be inserted from
10432 the export dispatcher (@pxref{The export dispatcher}) using the @code{Insert
10433 template} command by pressing @key{#}. To insert keywords individually,
10434 a good way to make sure the keyword is correct is to type @code{#+} and then
10435 to use @kbd{M-@key{TAB}}@footnote{Many desktops intercept @kbd{M-TAB} to
10436 switch windows. Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} instead.} for
10439 The export keywords available for every back-end, and their equivalent global
10440 variables, include:
10445 @vindex user-full-name
10446 The document author (@code{user-full-name}).
10450 @vindex org-export-creator-string
10451 Entity responsible for output generation (@code{org-export-creator-string}).
10455 @vindex org-export-date-timestamp-format
10456 A date or a time-stamp@footnote{The variable
10457 @code{org-export-date-timestamp-format} defines how this time-stamp will be
10462 @vindex user-mail-address
10463 The email address (@code{user-mail-address}).
10467 @vindex org-export-default-language
10468 Language to use for translating certain strings
10469 (@code{org-export-default-language}). With @samp{#+LANGUAGE: fr}, for
10470 example, Org translates @emph{Table of contents} to the French @emph{Table
10474 @cindex #+SELECT_TAGS
10475 @vindex org-export-select-tags
10476 The default value is @code{:export:}. When a tree is tagged with
10477 @code{:export:} (@code{org-export-select-tags}), Org selects that tree and
10478 its sub-trees for export. Org excludes trees with @code{:noexport:} tags,
10479 see below. When selectively exporting files with @code{:export:} tags set,
10480 Org does not export any text that appears before the first headline.
10483 @cindex #+EXCLUDE_TAGS
10484 @vindex org-export-exclude-tags
10485 The default value is @code{:noexport:}. When a tree is tagged with
10486 @code{:noexport:} (@code{org-export-exclude-tags}), Org excludes that tree
10487 and its sub-trees from export. Entries tagged with @code{:noexport:} will be
10488 unconditionally excluded from the export, even if they have an
10489 @code{:export:} tag. Even if a sub-tree is not exported, Org will execute any
10490 code blocks contained in them.
10494 @cindex document title
10495 Org displays this title. For long titles, use multiple @code{#+TITLE} lines.
10498 The @code{#+OPTIONS} keyword is a compact form. To configure multiple
10499 options, use several @code{#+OPTIONS} lines. @code{#+OPTIONS} recognizes the
10500 following arguments.
10504 @vindex org-export-with-smart-quotes
10505 Toggle smart quotes (@code{org-export-with-smart-quotes}). Depending on the
10506 language used, when activated, Org treats pairs of double quotes as primary
10507 quotes, pairs of single quotes as secondary quotes, and single quote marks as
10511 Toggle emphasized text (@code{org-export-with-emphasize}).
10514 @vindex org-export-with-special-strings
10515 Toggle conversion of special strings
10516 (@code{org-export-with-special-strings}).
10519 @vindex org-export-with-fixed-width
10520 Toggle fixed-width sections
10521 (@code{org-export-with-fixed-width}).
10524 @vindex org-export-with-timestamps
10525 Toggle inclusion of time/date active/inactive stamps
10526 (@code{org-export-with-timestamps}).
10529 @vindex org-export-preserve-breaks
10530 Toggles whether to preserve line breaks (@code{org-export-preserve-breaks}).
10533 @vindex org-export-with-sub-superscripts
10534 Toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}",
10535 @samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as
10536 it is (@code{org-export-with-sub-superscripts}).
10539 @vindex org-export-with-archived-trees
10540 Configure how archived trees are exported. When set to @code{headline}, the
10541 export process skips the contents and processes only the headlines
10542 (@code{org-export-with-archived-trees}).
10545 @vindex org-export-with-author
10546 Toggle inclusion of author name into exported file
10547 (@code{org-export-with-author}).
10549 @item broken-links:
10550 @vindex org-export-with-broken-links
10551 Toggles if Org should continue exporting upon finding a broken internal link.
10552 When set to @code{mark}, Org clearly marks the problem link in the output
10553 (@code{org-export-with-broken-links}).
10556 @vindex org-export-with-clocks
10557 Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}).
10560 @vindex org-export-with-creator
10561 Toggle inclusion of creator information in the exported file
10562 (@code{org-export-with-creator}).
10565 @vindex org-export-with-drawers
10566 Toggles inclusion of drawers, or list of drawers to include, or list of
10567 drawers to exclude (@code{org-export-with-drawers}).
10570 @vindex org-export-with-date
10571 Toggle inclusion of a date into exported file (@code{org-export-with-date}).
10574 @vindex org-export-with-entities
10575 Toggle inclusion of entities (@code{org-export-with-entities}).
10578 @vindex org-export-with-email
10579 Toggle inclusion of the author's e-mail into exported file
10580 (@code{org-export-with-email}).
10583 @vindex org-export-with-footnotes
10584 Toggle the inclusion of footnotes (@code{org-export-with-footnotes}).
10587 @vindex org-export-headline-levels
10588 Set the number of headline levels for export
10589 (@code{org-export-headline-levels}). Below that level, headlines are treated
10590 differently. In most back-ends, they become list items.
10593 @vindex org-export-with-inlinetasks
10594 Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
10597 @vindex org-export-with-section-numbers
10598 @cindex property, UNNUMBERED
10599 Toggle section-numbers (@code{org-export-with-section-numbers}). When set to
10600 number @samp{n}, Org numbers only those headlines at level @samp{n} or above.
10601 Set @code{UNNUMBERED} property to non-@code{nil} to disable numbering of
10602 heading and subheadings entirely.
10605 @vindex org-export-with-planning
10606 Toggle export of planning information (@code{org-export-with-planning}).
10607 ``Planning information'' comes from lines located right after the headline
10608 and contain any combination of these cookies: @code{SCHEDULED:},
10609 @code{DEADLINE:}, or @code{CLOSED:}.
10612 @vindex org-export-with-priority
10613 Toggle inclusion of priority cookies (@code{org-export-with-priority}).
10616 @vindex org-export-with-properties
10617 Toggle inclusion of property drawers, or list the properties to include
10618 (@code{org-export-with-properties}).
10621 @vindex org-export-with-statistics-cookies
10622 Toggle inclusion of statistics cookies
10623 (@code{org-export-with-statistics-cookies}).
10626 @vindex org-export-with-tags
10627 Toggle inclusion of tags, may also be @code{not-in-toc}
10628 (@code{org-export-with-tags}).
10631 @vindex org-export-with-tasks
10632 Toggle inclusion of tasks (TODO items); or @code{nil} to remove all tasks; or
10633 @code{todo} to remove DONE tasks; or list the keywords to keep
10634 (@code{org-export-with-tasks}).
10637 @vindex org-export-with-latex
10638 @code{nil} does not export; @code{t} exports; @code{verbatim} keeps
10639 everything in verbatim (@code{org-export-with-latex}).
10642 @vindex org-export-time-stamp-file
10643 Toggle inclusion of the creation time in the exported file
10644 (@code{org-export-time-stamp-file}).
10647 @vindex org-export-with-title
10648 Toggle inclusion of title (@code{org-export-with-title}).
10651 @vindex org-export-with-toc
10652 Toggle inclusion of the table of contents, or set the level limit
10653 (@code{org-export-with-toc}).
10656 @vindex org-export-with-todo-keywords
10657 Toggle inclusion of TODO keywords into exported text
10658 (@code{org-export-with-todo-keywords}).
10661 @vindex org-export-with-tables
10662 Toggle inclusion of tables (@code{org-export-with-tables}).
10666 When exporting sub-trees, special node properties in them can override the
10667 above keywords. They are special because they have an @samp{EXPORT_} prefix.
10668 For example, @samp{DATE} and @samp{OPTIONS} keywords become, respectively,
10669 @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS}. Except for @samp{SETUPFILE},
10670 all other keywords listed above have an @samp{EXPORT_} equivalent.
10673 @vindex org-export-allow-bind-keywords
10674 If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables
10675 can become buffer-local during export by using the BIND keyword. Its syntax
10676 is @samp{#+BIND: variable value}. This is particularly useful for in-buffer
10677 settings that cannot be changed using keywords.
10679 @cindex property, EXPORT_FILE_NAME
10680 Normally Org generates the file name based on the buffer name and the
10681 extension based on the back-end format. For sub-trees, Org can export to a
10682 file name as specified in the @code{EXPORT_FILE_NAME} property.
10684 @node Table of contents
10685 @section Table of contents
10686 @cindex table of contents
10687 @cindex list of tables
10688 @cindex list of listings
10691 @vindex org-export-with-toc
10692 Org normally inserts the table of contents directly before the first headline
10693 of the file. Org sets the TOC depth the same as the headline levels in the
10694 file. Use a lower number for lower TOC depth. To turn off TOC entirely, use
10695 @code{nil}. This is configured in the @code{org-export-with-toc} variable or
10696 as keywords in an Org file as:
10699 #+OPTIONS: toc:2 @r{only include two levels in TOC}
10700 #+OPTIONS: toc:nil @r{no default TOC at all}
10703 To move the table of contents to a different location, first turn off the
10704 default with @code{org-export-with-toc} variable or with @code{#+OPTIONS:
10705 toc:nil}. Then insert @code{#+TOC: headlines N} at the desired location(s).
10708 #+OPTIONS: toc:nil @r{no default TOC}
10710 #+TOC: headlines 2 @r{insert TOC here, with two headline levels}
10713 To adjust the TOC depth for a specific section of the Org document, append an
10714 additional @samp{local} parameter. This parameter becomes a relative depth
10715 for the current level.
10717 Note that for this feature to work properly in @LaTeX{} export, the Org file
10718 requires the inclusion of the @code{titletoc} package. Because of
10719 compatibility issues, @code{titletoc} has to be loaded @emph{before}
10720 @code{hyperref}. Customize the @code{org-latex-default-packages-alist}
10724 * Section #+TOC: headlines 1 local @r{insert local TOC, with direct children
10728 Use the @code{TOC} keyword to generate list of tables (resp.@: all listings)
10732 #+TOC: listings @r{build a list of listings}
10733 #+TOC: tables @r{build a list of tables}
10736 @cindex property, ALT_TITLE
10737 Normally Org uses the headline for its entry in the table of contents. But
10738 with @code{ALT_TITLE} property, a different entry can be specified for the
10741 @node Include files
10742 @section Include files
10743 @cindex include files, during export
10744 Include other files during export. For example, to include your @file{.emacs}
10745 file, you could use:
10749 #+INCLUDE: "~/.emacs" src emacs-lisp
10753 The first parameter is the file name to include. The optional second
10754 parameter specifies the block type: @samp{example}, @samp{export} or
10755 @samp{src}. The optional third parameter specifies the source code language
10756 to use for formatting the contents. This is relevant to both @samp{export}
10757 and @samp{src} block types.
10759 If an include file is specified as having a markup language, Org neither
10760 checks for valid syntax nor changes the contents in any way. For
10761 @samp{example} and @samp{src} blocks, Org code-escapes the contents before
10764 If an include file is not specified as having any markup language, Org
10765 assumes it be in Org format and proceeds as usual with a few exceptions. Org
10766 makes the footnote labels (@pxref{Footnotes}) in the included file local to
10767 that file. The contents of the included file will belong to the same
10768 structure---headline, item---containing the @code{INCLUDE} keyword. In
10769 particular, headlines within the file will become children of the current
10770 section. That behavior can be changed by providing an additional keyword
10771 parameter, @code{:minlevel}. It shifts the headlines in the included file to
10772 become the lowest level. For example, this syntax makes the included file
10773 a sibling of the current top-level headline:
10776 #+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
10779 Inclusion of only portions of files are specified using ranges parameter with
10780 @code{:lines} keyword. The line at the upper end of the range will not be
10781 included. The start and/or the end of the range may be omitted to use the
10785 #+INCLUDE: "~/.emacs" :lines "5-10" @r{Include lines 5 to 10, 10 excluded}
10786 #+INCLUDE: "~/.emacs" :lines "-10" @r{Include lines 1 to 10, 10 excluded}
10787 #+INCLUDE: "~/.emacs" :lines "10-" @r{Include lines from 10 to EOF}
10790 Inclusions may specify a file-link to extract an object matched by
10791 @code{org-link-search}@footnote{Note that
10792 @code{org-link-search-must-match-exact-headline} is locally bound to
10793 non-@code{nil}. Therefore, @code{org-link-search} only matches headlines and
10794 named elements.} (@pxref{Search options}).
10796 To extract only the contents of the matched object, set @code{:only-contents}
10797 property to non-@code{nil}. This will omit any planning lines or property
10798 drawers. The ranges for @code{:lines} keyword are relative to the requested
10799 element. Some examples:
10802 #+INCLUDE: "./paper.org::#theory" :only-contents t
10803 @r{Include the body of the heading with the custom id @samp{theory}}
10804 #+INCLUDE: "./paper.org::mytable" @r{Include named element.}
10805 #+INCLUDE: "./paper.org::*conclusion" :lines 1-20
10806 @r{Include the first 20 lines of the headline named @samp{conclusion}.}
10812 Visit the include file at point.
10815 @node Macro replacement
10816 @section Macro replacement
10817 @cindex macro replacement, during export
10820 Macros replace text snippets during export. This is a macro definition in
10824 #+MACRO: name replacement text $1, $2 are arguments
10827 @noindent which can be referenced using
10828 @code{@{@{@{name(arg1, arg2)@}@}@}}@footnote{Since commas separate the
10829 arguments, commas within arguments have to be escaped with the backslash
10830 character. So only those backslash characters before a comma need escaping
10831 with another backslash character.}.
10833 Org recognizes macro references in following Org markup areas: paragraphs,
10834 headlines, verse blocks, tables cells and lists. Org also recognizes macro
10835 references in keywords, such as @code{#+CAPTION}, @code{#+TITLE},
10836 @code{#+AUTHOR}, @code{#+DATE}, and for some back-end specific export
10839 Org comes with following pre-defined macros:
10842 @item @{@{@{title@}@}@}
10843 @itemx @{@{@{author@}@}@}
10844 @itemx @{@{@{email@}@}@}
10845 @cindex title, macro
10846 @cindex author, macro
10847 @cindex email, macro
10848 Org replaces these macro references with available information at the time of
10851 @item @{@{@{date@}@}@}
10852 @itemx @{@{@{date(@var{FORMAT})@}@}@}
10853 @cindex date, macro
10854 This macro refers to the @code{#+DATE} keyword. @var{FORMAT} is an optional
10855 argument to the @code{@{@{@{date@}@}@}} macro that will be used only if
10856 @code{#+DATE} is a single timestamp. @var{FORMAT} should be a format string
10857 understood by @code{format-time-string}.
10859 @item @{@{@{time(@var{FORMAT})@}@}@}
10860 @itemx @{@{@{modification-time(@var{FORMAT}, @var{VC})@}@}@}
10861 @cindex time, macro
10862 @cindex modification time, macro
10863 These macros refer to the document's date and time of export and date and
10864 time of modification. @var{FORMAT} is a string understood by
10865 @code{format-time-string}. If the second argument to the
10866 @code{modification-time} macro is non-@code{nil}, Org uses @file{vc.el} to
10867 retrieve the document's modification time from the version control
10868 system. Otherwise Org reads the file attributes.
10870 @item @{@{@{input-file@}@}@}
10871 @cindex input file, macro
10872 This macro refers to the filename of the exported file.
10874 @item @{@{@{property(@var{PROPERTY-NAME})@}@}@}
10875 @itemx @{@{@{property(@var{PROPERTY-NAME},@var{SEARCH-OPTION})@}@}@}
10876 @cindex property, macro
10877 This macro returns the value of property @var{PROPERTY-NAME} in the current
10878 entry. If @var{SEARCH-OPTION} (@pxref{Search options}) refers to a remote
10879 entry, that will be used instead.
10882 The surrounding brackets can be made invisible by setting
10883 @code{org-hide-macro-markers} non-@code{nil}.
10885 Org expands macros at the very beginning of the export process.
10887 @node Comment lines
10888 @section Comment lines
10889 @cindex exporting, not
10891 @cindex comment lines
10892 Lines starting with zero or more whitespace characters followed by one
10893 @samp{#} and a whitespace are treated as comments and, as such, are not
10896 @cindex #+BEGIN_COMMENT
10897 Likewise, regions surrounded by @samp{#+BEGIN_COMMENT}
10898 ... @samp{#+END_COMMENT} are not exported.
10900 @cindex comment trees
10901 Finally, a @samp{COMMENT} keyword at the beginning of an entry, but after any
10902 other keyword or priority cookie, comments out the entire subtree. In this
10903 case, the subtree is not exported and no code block within it is executed
10904 either@footnote{For a less drastic behavior, consider using a select tag
10905 (@pxref{Export settings}) instead.}. The command below helps changing the
10906 comment status of a headline.
10911 Toggle the @samp{COMMENT} keyword at the beginning of an entry.
10914 @node ASCII/Latin-1/UTF-8 export
10915 @section ASCII/Latin-1/UTF-8 export
10916 @cindex ASCII export
10917 @cindex Latin-1 export
10918 @cindex UTF-8 export
10920 ASCII export produces an output file containing only plain ASCII characters.
10921 This is the most simplest and direct text output. It does not contain any
10922 Org markup either. Latin-1 and UTF-8 export use additional characters and
10923 symbols available in these encoding standards. All three of these export
10924 formats offer the most basic of text output for maximum portability.
10926 @vindex org-ascii-text-width
10927 On export, Org fills and justifies text according to the text width set in
10928 @code{org-ascii-text-width}.
10930 @vindex org-ascii-links-to-notes
10931 Org exports links using a footnote-like style where the descriptive part is
10932 in the text and the link is in a note before the next heading. See the
10933 variable @code{org-ascii-links-to-notes} for details.
10935 @subheading ASCII export commands
10938 @orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii}
10939 Export as an ASCII file with a @file{.txt} extension. For @file{myfile.org},
10940 Org exports to @file{myfile.txt}, overwriting without warning. For
10941 @file{myfile.txt}, Org exports to @file{myfile.txt.txt} in order to prevent
10943 @orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii}
10944 Export to a temporary buffer. Does not create a file.
10947 @subheading ASCII specific export settings
10948 The ASCII export back-end has one extra keyword for customizing ASCII output.
10949 Setting this keyword works similar to the general options (@pxref{Export
10954 @cindex #+SUBTITLE (ASCII)
10955 The document subtitle. For long subtitles, use multiple @code{#+SUBTITLE}
10956 lines in the Org file. Org prints them on one continuous line, wrapping into
10957 multiple lines if necessary.
10960 @subheading Header and sectioning structure
10962 Org converts the first three outline levels into headlines for ASCII export.
10963 The remaining levels are turned into lists. To change this cut-off point
10964 where levels become lists, @pxref{Export settings}.
10966 @subheading Quoting ASCII text
10968 To insert text within the Org file by the ASCII back-end, use one the
10969 following constructs, inline, keyword, or export block:
10972 @cindex #+BEGIN_EXPORT ascii
10974 Inline text @@@@ascii:and additional text@@@@ within a paragraph.
10978 #+BEGIN_EXPORT ascii
10979 Org exports text in this block only when using ASCII back-end.
10983 @subheading ASCII specific attributes
10984 @cindex #+ATTR_ASCII
10985 @cindex horizontal rules, in ASCII export
10987 ASCII back-end recognizes only one attribute, @code{:width}, which specifies
10988 the width of an horizontal rule in number of characters. The keyword and
10989 syntax for specifying widths is:
10992 #+ATTR_ASCII: :width 10
10996 @subheading ASCII special blocks
10997 @cindex special blocks, in ASCII export
10998 @cindex #+BEGIN_JUSTIFYLEFT
10999 @cindex #+BEGIN_JUSTIFYRIGHT
11001 Besides @code{#+BEGIN_CENTER} blocks (@pxref{Paragraphs}), ASCII back-end has
11002 these two left and right justification blocks:
11005 #+BEGIN_JUSTIFYLEFT
11006 It's just a jump to the left...
11009 #+BEGIN_JUSTIFYRIGHT
11010 ...and then a step to the right.
11014 @node Beamer export
11015 @section Beamer export
11016 @cindex Beamer export
11018 Org uses @emph{Beamer} export to convert an Org file tree structure into a
11019 high-quality interactive slides for presentations. @emph{Beamer} is a
11020 @LaTeX{} document class for creating presentations in PDF, HTML, and other
11021 popular display formats.
11024 * Beamer export commands:: For creating Beamer documents.
11025 * Beamer specific export settings:: For customizing Beamer export.
11026 * Sectioning Frames and Blocks in Beamer:: For composing Beamer slides.
11027 * Beamer specific syntax:: For using in Org documents.
11028 * Editing support:: For using helper functions.
11029 * A Beamer example:: A complete presentation.
11032 @node Beamer export commands
11033 @subsection Beamer export commands
11036 @orgcmd{C-c C-e l b,org-beamer-export-to-latex}
11037 Export as @LaTeX{} file with a @file{.tex} extension. For @file{myfile.org},
11038 Org exports to @file{myfile.tex}, overwriting without warning.
11039 @orgcmd{C-c C-e l B,org-beamer-export-as-latex}
11040 Export to a temporary buffer. Does not create a file.
11041 @orgcmd{C-c C-e l P,org-beamer-export-to-pdf}
11042 Export as @LaTeX{} file and then convert it to PDF format.
11044 Export as @LaTeX{} file, convert it to PDF format, and then open the PDF
11048 @node Beamer specific export settings
11049 @subsection Beamer specific export settings
11051 Beamer export back-end has several additional keywords for customizing Beamer
11052 output. These keywords work similar to the general options settings
11053 (@pxref{Export settings}).
11057 @cindex #+BEAMER_THEME
11058 @vindex org-beamer-theme
11059 The Beamer layout theme (@code{org-beamer-theme}). Use square brackets for
11060 options. For example:
11062 #+BEAMER_THEME: Rochester [height=20pt]
11065 @item BEAMER_FONT_THEME
11066 @cindex #+BEAMER_FONT_THEME
11067 The Beamer font theme.
11069 @item BEAMER_INNER_THEME
11070 @cindex #+BEAMER_INNER_THEME
11071 The Beamer inner theme.
11073 @item BEAMER_OUTER_THEME
11074 @cindex #+BEAMER_OUTER_THEME
11075 The Beamer outer theme.
11077 @item BEAMER_HEADER
11078 @cindex #+BEAMER_HEADER
11079 Arbitrary lines inserted in the preamble, just before the @samp{hyperref}
11083 @cindex #+DESCRIPTION (Beamer)
11084 The document description. For long descriptions, use multiple
11085 @code{#+DESCRIPTION} keywords. By default, @samp{hyperref} inserts
11086 @code{#+DESCRIPTION} as metadata. Use @code{org-latex-hyperref-template} to
11087 configure document metadata. Use @code{org-latex-title-command} to configure
11088 typesetting of description as part of front matter.
11091 @cindex #+KEYWORDS (Beamer)
11092 The keywords for defining the contents of the document. Use multiple
11093 @code{#+KEYWORDS} lines if necessary. By default, @samp{hyperref} inserts
11094 @code{#+KEYWORDS} as metadata. Use @code{org-latex-hyperref-template} to
11095 configure document metadata. Use @code{org-latex-title-command} to configure
11096 typesetting of keywords as part of front matter.
11099 @cindex #+SUBTITLE (Beamer)
11100 @vindex org-beamer-subtitle-format
11101 Document's subtitle. For typesetting, use @code{org-beamer-subtitle-format}
11102 string. Use @code{org-latex-hyperref-template} to configure document
11103 metadata. Use @code{org-latex-title-command} to configure typesetting of
11104 subtitle as part of front matter.
11107 @node Sectioning Frames and Blocks in Beamer
11108 @subsection Sectioning, Frames and Blocks in Beamer
11110 Org transforms heading levels into Beamer's sectioning elements, frames and
11111 blocks. Any Org tree with a not-too-deep-level nesting should in principle
11112 be exportable as a Beamer presentation.
11116 @vindex org-beamer-frame-level
11117 Org headlines become Beamer frames when the heading level in Org is equal to
11118 @code{org-beamer-frame-level} or @code{H} value in an @code{OPTIONS} line
11119 (@pxref{Export settings}).
11121 @cindex property, BEAMER_ENV
11122 Org overrides headlines to frames conversion for the current tree of an Org
11123 file if it encounters the @code{BEAMER_ENV} property set to @code{frame} or
11124 @code{fullframe}. Org ignores whatever @code{org-beamer-frame-level} happens
11125 to be for that headline level in the Org tree. In Beamer terminology, a
11126 @code{fullframe} is a frame without its title.
11129 @vindex org-beamer-environments-default
11130 @vindex org-beamer-environments-extra
11131 Org exports a Beamer frame's objects as @code{block} environments. Org can
11132 enforce wrapping in special block types when @code{BEAMER_ENV} property is
11133 set@footnote{If @code{BEAMER_ENV} is set, Org export adds
11134 @code{:B_environment:} tag to make it visible. The tag serves as a visual
11135 aid and has no semantic relevance.}. For valid values see
11136 @code{org-beamer-environments-default}. To add more values, see
11137 @code{org-beamer-environments-extra}.
11140 @cindex property, BEAMER_REF
11141 If @code{BEAMER_ENV} is set to @code{appendix}, Org exports the entry as an
11142 appendix. When set to @code{note}, Org exports the entry as a note within
11143 the frame or between frames, depending on the entry's heading level. When
11144 set to @code{noteNH}, Org exports the entry as a note without its title.
11145 When set to @code{againframe}, Org exports the entry with @code{\againframe}
11146 command, which makes setting the @code{BEAMER_REF} property mandatory because
11147 @code{\againframe} needs frame to resume.
11149 When @code{ignoreheading} is set, Org export ignores the entry's headline but
11150 not its content. This is useful for inserting content between frames. It is
11151 also useful for properly closing a @code{column} environment.
11154 @cindex property, BEAMER_ACT
11155 @cindex property, BEAMER_OPT
11156 When @code{BEAMER_ACT} is set for a headline, Org export translates that
11157 headline as an overlay or action specification. When enclosed in square
11158 brackets, Org export makes the overlay specification a default. Use
11159 @code{BEAMER_OPT} to set any options applicable to the current Beamer frame
11160 or block. The Beamer export back-end wraps with appropriate angular or
11161 square brackets. It also adds the @code{fragile} option for any code that may
11162 require a verbatim block.
11164 @cindex property, BEAMER_COL
11165 To create a column on the Beamer slide, use the @code{BEAMER_COL} property
11166 for its headline in the Org file. Set the value of @code{BEAMER_COL} to a
11167 decimal number representing the fraction of the total text width. Beamer
11168 export uses this value to set the column's width and fills the column with
11169 the contents of the Org entry. If the Org entry has no specific environment
11170 defined, Beamer export ignores the heading. If the Org entry has a defined
11171 environment, Beamer export uses the heading as title. Behind the scenes,
11172 Beamer export automatically handles @LaTeX{} column separations for
11173 contiguous headlines. To manually adjust them for any unique configurations
11174 needs, use the @code{BEAMER_ENV} property.
11176 @node Beamer specific syntax
11177 @subsection Beamer specific syntax
11178 Since Org's Beamer export back-end is an extension of the @LaTeX{} back-end,
11179 it recognizes other @LaTeX{} specific syntax---for example, @samp{#+LATEX:}
11180 or @samp{#+ATTR_LATEX:}. @xref{@LaTeX{} export}, for details.
11182 Beamer export wraps the table of contents generated with @code{toc:t}
11183 @code{OPTION} keyword in a @code{frame} environment. Beamer export does not
11184 wrap the table of contents generated with @code{TOC} keyword (@pxref{Table of
11185 contents}). Use square brackets for specifying options.
11188 #+TOC: headlines [currentsection]
11191 Insert Beamer-specific code using the following constructs:
11194 @cindex #+BEGIN_EXPORT beamer
11198 #+BEGIN_EXPORT beamer
11199 Only Beamer export back-end will export this line.
11202 Text @@@@beamer:some code@@@@ within a paragraph.
11205 Inline constructs, such as the last one above, are useful for adding overlay
11206 specifications to objects with @code{bold}, @code{item}, @code{link},
11207 @code{radio-target} and @code{target} types. Enclose the value in angular
11208 brackets and place the specification at the beginning the object as shown in
11212 A *@@@@beamer:<2->@@@@useful* feature
11215 @cindex #+ATTR_BEAMER
11216 Beamer export recognizes the @code{ATTR_BEAMER} keyword with the following
11217 attributes from Beamer configurations: @code{:environment} for changing local
11218 Beamer environment, @code{:overlay} for specifying Beamer overlays in angular
11219 or square brackets, and @code{:options} for inserting optional arguments.
11222 #+ATTR_BEAMER: :environment nonindentlist
11223 - item 1, not indented
11224 - item 2, not indented
11225 - item 3, not indented
11229 #+ATTR_BEAMER: :overlay <+->
11235 #+ATTR_BEAMER: :options [Lagrange]
11236 Let $G$ be a finite group, and let $H$ be
11237 a subgroup of $G$. Then the order of $H$ divides the order of $G$.
11240 @node Editing support
11241 @subsection Editing support
11244 The @code{org-beamer-mode} is a special minor mode for faster editing of
11252 @orgcmd{C-c C-b,org-beamer-select-environment}
11253 The @code{org-beamer-mode} provides this key for quicker selections in Beamer
11254 normal environments, and for selecting the @code{BEAMER_COL} property.
11257 @node A Beamer example
11258 @subsection A Beamer example
11260 Here is an example of an Org document ready for Beamer export.
11263 #+TITLE: Example Presentation
11264 #+AUTHOR: Carsten Dominik
11265 #+OPTIONS: H:2 toc:t num:t
11266 #+LATEX_CLASS: beamer
11267 #+LATEX_CLASS_OPTIONS: [presentation]
11268 #+BEAMER_THEME: Madrid
11269 #+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) %8BEAMER_OPT(Opt)
11271 * This is the first structural section
11274 *** Thanks to Eric Fraga :B_block:
11279 for the first viable Beamer setup in Org
11280 *** Thanks to everyone else :B_block:
11286 for contributing to the discussion
11287 **** This will be formatted as a beamer note :B_note:
11291 ** Frame 2 (where we will not use columns)
11293 Please test this stuff!
11297 @section HTML export
11298 @cindex HTML export
11300 Org mode contains an HTML exporter with extensive HTML formatting compatible
11301 with XHTML 1.0 strict standard.
11304 * HTML Export commands:: Invoking HTML export
11305 * HTML Specific export settings:: Settings for HTML export
11306 * HTML doctypes:: Exporting various (X)HTML flavors
11307 * HTML preamble and postamble:: Inserting preamble and postamble
11308 * Quoting HTML tags:: Using direct HTML in Org files
11309 * Links in HTML export:: Interpreting and formatting links
11310 * Tables in HTML export:: Formatting and modifying tables
11311 * Images in HTML export:: Inserting figures with HTML output
11312 * Math formatting in HTML export:: Handling math equations
11313 * Text areas in HTML export:: Showing an alternate approach, an example
11314 * CSS support:: Styling HTML output
11315 * JavaScript support:: Folding scripting in the web browser
11319 @node HTML Export commands
11320 @subsection HTML export commands
11323 @orgcmd{C-c C-e h h,org-html-export-to-html}
11324 Export as HTML file with a @file{.html} extension. For @file{myfile.org},
11325 Org exports to @file{myfile.html}, overwriting without warning. @kbd{C-c C-e
11326 h o} Exports to HTML and opens it in a web browser.
11328 @orgcmd{C-c C-e h H,org-html-export-as-html}
11329 Exports to a temporary buffer. Does not create a file.
11332 @node HTML Specific export settings
11333 @subsection HTML Specific export settings
11334 HTML export has a number of keywords, similar to the general options settings
11335 described in @ref{Export settings}.
11339 @cindex #+DESCRIPTION (HTML)
11340 This is the document's description, which the HTML exporter inserts it as a
11341 HTML meta tag in the HTML file. For long descriptions, use multiple
11342 @code{#+DESCRIPTION} lines. The exporter takes care of wrapping the lines
11346 @cindex #+HTML_DOCTYPE
11347 @vindex org-html-doctype
11348 Specify the document type, for example: HTML5 (@code{org-html-doctype}).
11350 @item HTML_CONTAINER
11351 @cindex #+HTML_CONTAINER
11352 @vindex org-html-container-element
11353 Specify the HTML container, such as @samp{div}, for wrapping sections and
11354 elements (@code{org-html-container-element}).
11356 @item HTML_LINK_HOME
11357 @cindex #+HTML_LINK_HOME
11358 @vindex org-html-link-home
11359 The URL for home link (@code{org-html-link-home}).
11362 @cindex #+HTML_LINK_UP
11363 @vindex org-html-link-up
11364 The URL for the up link of exported HTML pages (@code{org-html-link-up}).
11367 @cindex #+HTML_MATHJAX
11368 @vindex org-html-mathjax-options
11369 Options for MathJax (@code{org-html-mathjax-options}). MathJax is used to
11370 typeset @LaTeX{} math in HTML documents. @xref{Math formatting in HTML
11371 export}, for an example.
11374 @cindex #+HTML_HEAD
11375 @vindex org-html-head
11376 Arbitrary lines for appending to the HTML document's head
11377 (@code{org-html-head}).
11379 @item HTML_HEAD_EXTRA
11380 @cindex #+HTML_HEAD_EXTRA
11381 @vindex org-html-head-extra
11382 More arbitrary lines for appending to the HTML document's head
11383 (@code{org-html-head-extra}).
11386 @cindex #+KEYWORDS (HTML)
11387 Keywords to describe the document's content. HTML exporter inserts these
11388 keywords as HTML meta tags. For long keywords, use multiple
11389 @code{#+KEYWORDS} lines.
11392 @cindex #+LATEX_HEADER (HTML)
11393 Arbitrary lines for appending to the preamble; HTML exporter appends when
11394 transcoding @LaTeX{} fragments to images (@pxref{Math formatting in HTML
11398 @cindex #+SUBTILE (HTML)
11399 The document's subtitle. HTML exporter formats subtitle if document type is
11400 @samp{HTML5} and the CSS has a @samp{subtitle} class.
11403 Some of these keywords are explained in more detail in the following sections
11406 @node HTML doctypes
11407 @subsection HTML doctypes
11409 Org can export to various (X)HTML flavors.
11411 @vindex org-html-doctype
11412 @vindex org-html-doctype-alist
11413 Set the @code{org-html-doctype} variable for different (X)HTML variants.
11414 Depending on the variant, the HTML exporter adjusts the syntax of HTML
11415 conversion accordingly. Org includes the following ready-made variants:
11421 ``html4-transitional''
11427 ``xhtml-transitional''
11438 @noindent See the variable @code{org-html-doctype-alist} for details.
11439 The default is ``xhtml-strict''.
11441 @vindex org-html-html5-fancy
11442 @cindex HTML5, export new elements
11443 Org's HTML exporter does not by default enable new block elements introduced
11444 with the HTML5 standard. To enable them, set @code{org-html-html5-fancy} to
11445 non-@code{nil}. Or use an @code{OPTIONS} line in the file to set
11446 @code{html5-fancy}. HTML5 documents can now have arbitrary #+BEGIN and #+END
11447 blocks. For example:
11466 #+ATTR_HTML: :controls controls :width 350
11468 #+HTML: <source src="movie.mp4" type="video/mp4">
11469 #+HTML: <source src="movie.ogg" type="video/ogg">
11470 Your browser does not support the video tag.
11477 <video controls="controls" width="350">
11478 <source src="movie.mp4" type="video/mp4">
11479 <source src="movie.ogg" type="video/ogg">
11480 <p>Your browser does not support the video tag.</p>
11484 @vindex org-html-html5-elements
11485 When special blocks do not have a corresponding HTML5 element, the HTML
11486 exporter reverts to standard translation (see
11487 @code{org-html-html5-elements}). For example, @code{#+BEGIN_lederhosen}
11488 exports to @samp{<div class="lederhosen">}.
11490 Special blocks cannot have headlines. For the HTML exporter to wrap the
11491 headline and its contents in @samp{<section>} or @samp{<article>} tags, set
11492 the @code{HTML_CONTAINER} property for the headline.
11494 @node HTML preamble and postamble
11495 @subsection HTML preamble and postamble
11496 @vindex org-html-preamble
11497 @vindex org-html-postamble
11498 @vindex org-html-preamble-format
11499 @vindex org-html-postamble-format
11500 @vindex org-html-validation-link
11501 @vindex org-export-creator-string
11502 @vindex org-export-time-stamp-file
11504 The HTML exporter has delineations for preamble and postamble. The default
11505 value for @code{org-html-preamble} is @code{t}, which makes the HTML exporter
11506 insert the preamble. See the variable @code{org-html-preamble-format} for
11509 Set @code{org-html-preamble} to a string to override the default format
11510 string. If the string is a function, the HTML exporter expects the function
11511 to return a string upon execution. The HTML exporter inserts this string in
11512 the preamble. The HTML exporter will not insert a preamble if
11513 @code{org-html-preamble} is set @code{nil}.
11515 The default value for @code{org-html-postamble} is @code{auto}, which makes
11516 the HTML exporter build a postamble from looking up author's name, email
11517 address, creator's name, and date. Set @code{org-html-postamble} to @code{t}
11518 to insert the postamble in the format specified in the
11519 @code{org-html-postamble-format} variable. The HTML exporter will not insert
11520 a postamble if @code{org-html-postamble} is set to @code{nil}.
11522 @node Quoting HTML tags
11523 @subsection Quoting HTML tags
11525 The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and
11526 @samp{>}. To include raw HTML code in the Org file so the HTML export
11527 back-end can insert that HTML code in the output, use this inline syntax:
11528 @samp{@@@@html:}. For example: @samp{@@@@html:<b>@@@@bold
11529 text@@@@html:</b>@@@@}. For larger raw HTML code blocks, use these HTML
11530 export code blocks:
11533 @cindex #+BEGIN_EXPORT html
11535 #+HTML: Literal HTML code for export
11539 @cindex #+BEGIN_EXPORT html
11542 #+BEGIN_EXPORT html
11543 All lines between these markers are exported literally
11548 @node Links in HTML export
11549 @subsection Links in HTML export
11551 @cindex links, in HTML export
11552 @cindex internal links, in HTML export
11553 @cindex external links, in HTML export
11554 @vindex org-html-link-org-files-as-html
11555 The HTML export back-end transforms Org's internal links (@pxref{Internal
11556 links}) to equivalent HTML links in the output. The back-end similarly
11557 handles Org's automatic links created by radio targets (@pxref{Radio
11558 targets}) similarly. For Org links to external files, the back-end
11559 transforms the links to @emph{relative} paths.
11561 For Org links to other @file{.org} files, the back-end automatically changes
11562 the file extension to @file{.html} and makes file paths relative. If the
11563 @file{.org} files have an equivalent @file{.html} version at the same
11564 location, then the converted links should work without any further manual
11565 intervention. However, to disable this automatic path translation, set
11566 @code{org-html-link-org-files-as-html} to @code{nil}. When disabled, the
11567 HTML export back-end substitutes the @samp{id:}-based links in the HTML
11568 output. For more about linking files when publishing to a directory,
11569 @pxref{Publishing links}.
11571 Org files can also have special directives to the HTML export back-end. For
11572 example, by using @code{#+ATTR_HTML} lines to specify new format attributes
11573 to @code{<a>} or @code{<img>} tags. This example shows changing the link's
11574 @code{title} and @code{style}:
11576 @cindex #+ATTR_HTML
11578 #+ATTR_HTML: :title The Org mode homepage :style color:red;
11579 [[http://orgmode.org]]
11582 @node Tables in HTML export
11583 @subsection Tables in HTML export
11584 @cindex tables, in HTML
11585 @vindex org-html-table-default-attributes
11587 The HTML export back-end uses @code{org-html-table-default-attributes} when
11588 exporting Org tables to HTML. By default, the exporter does not draw frames
11589 and cell borders. To change for this for a table, use the following lines
11590 before the table in the Org file:
11593 @cindex #+ATTR_HTML
11595 #+CAPTION: This is a table with lines around and between cells
11596 #+ATTR_HTML: :border 2 :rules all :frame border
11599 The HTML export back-end preserves column groupings in Org tables
11600 (@pxref{Column groups}) when exporting to HTML.
11602 Additional options for customizing tables for HTML export.
11605 @vindex org-html-table-align-individual-fields
11606 @item org-html-table-align-individual-fields
11607 Non-@code{nil} attaches style attributes for alignment to each table field.
11609 @vindex org-html-table-caption-above
11610 @item org-html-table-caption-above
11611 Non-@code{nil} places caption string at the beginning of the table.
11613 @vindex org-html-table-data-tags
11614 @item org-html-table-data-tags
11615 Opening and ending tags for table data fields.
11617 @vindex org-html-table-default-attributes
11618 @item org-html-table-default-attributes
11619 Default attributes and values for table tags.
11621 @vindex org-html-table-header-tags
11622 @item org-html-table-header-tags
11623 Opening and ending tags for table's header fields.
11625 @vindex org-html-table-row-tags
11626 @item org-html-table-row-tags
11627 Opening and ending tags for table rows.
11629 @vindex org-html-table-use-header-tags-for-first-column
11630 @item org-html-table-use-header-tags-for-first-column
11631 Non-@code{nil} formats column one in tables with header tags.
11634 @node Images in HTML export
11635 @subsection Images in HTML export
11637 @cindex images, inline in HTML
11638 @cindex inlining images in HTML
11639 @vindex org-html-inline-images
11641 The HTML export back-end has features to convert Org image links to HTML
11642 inline images and HTML clickable image links.
11644 When the link in the Org file has no description, the HTML export back-end by
11645 default in-lines that image. For example: @samp{[[file:myimg.jpg]]} is
11646 in-lined, while @samp{[[file:myimg.jpg][the image]]} links to the text,
11649 For more details, see the variable @code{org-html-inline-images}.
11651 On the other hand, if the description part of the Org link is itself another
11652 link, such as @code{file:} or @code{http:} URL pointing to an image, the HTML
11653 export back-end in-lines this image and links to the main image. This Org
11654 syntax enables the back-end to link low-resolution thumbnail to the
11655 high-resolution version of the image, as shown in this example:
11658 [[file:highres.jpg][file:thumb.jpg]]
11661 To change attributes of in-lined images, use @code{#+ATTR_HTML} lines in the
11662 Org file. This example shows realignment to right, and adds @code{alt} and
11663 @code{title} attributes in support of text viewers and modern web accessibility
11667 @cindex #+ATTR_HTML
11669 #+CAPTION: A black cat stalking a spider
11670 #+ATTR_HTML: :alt cat/spider image :title Action! :align right
11675 The HTML export back-end copies the @code{http} links from the Org file as
11678 @node Math formatting in HTML export
11679 @subsection Math formatting in HTML export
11683 @cindex imagemagick
11685 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two
11686 different ways on HTML pages. The default is to use
11687 @uref{http://www.mathjax.org, MathJax} which should work out of the box with
11688 Org@footnote{By default Org loads MathJax from @uref{https://cdnjs.com, cdnjs.com} as
11689 recommended by @uref{http://www.mathjax.org, MathJax}.}. Some MathJax display
11690 options can be configured via @code{org-html-mathjax-options}, or in the
11691 buffer. For example, with the following settings,
11693 #+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
11695 equation labels will be displayed on the left marign and equations will be
11696 five ems from the left margin.
11698 @noindent See the docstring of
11699 @code{org-html-mathjax-options} for all supported variables. The MathJax
11700 template can be configure via @code{org-html-mathjax-template}.
11702 If you prefer, you can also request that @LaTeX{} fragments are processed
11703 into small images that will be inserted into the browser page. Before the
11704 availability of MathJax, this was the default method for Org files. This
11705 method requires that the @file{dvipng} program, @file{dvisvgm} or
11706 @file{imagemagick} suite is available on your system. You can still get
11707 this processing with
11710 #+OPTIONS: tex:dvipng
11714 #+OPTIONS: tex:dvisvgm
11720 #+OPTIONS: tex:imagemagick
11723 @node Text areas in HTML export
11724 @subsection Text areas in HTML export
11726 @cindex text areas, in HTML
11727 Before Org mode's Babel, one popular approach to publishing code in HTML was
11728 by using @code{:textarea}. The advantage of this approach was that copying
11729 and pasting was built into browsers with simple JavaScript commands. Even
11730 editing before pasting was made simple.
11732 The HTML export back-end can create such text areas. It requires an
11733 @code{#+ATTR_HTML:} line as shown in the example below with the
11734 @code{:textarea} option. This must be followed by either an
11735 @code{example} or a @code{src} code block. Other Org block types will not
11736 honor the @code{:textarea} option.
11738 By default, the HTML export back-end creates a text area 80 characters wide
11739 and height just enough to fit the content. Override these defaults with
11740 @code{:width} and @code{:height} options on the @code{#+ATTR_HTML:} line.
11743 #+ATTR_HTML: :textarea t :width 40
11745 (defun org-xor (a b)
11753 @subsection CSS support
11754 @cindex CSS, for HTML export
11755 @cindex HTML export, CSS
11757 @vindex org-html-todo-kwd-class-prefix
11758 @vindex org-html-tag-class-prefix
11759 You can modify the CSS style definitions for the exported file. The HTML
11760 exporter assigns the following special CSS classes@footnote{If the classes on
11761 TODO keywords and tags lead to conflicts, use the variables
11762 @code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to
11763 make them unique.} to appropriate parts of the document---your style
11764 specifications may change these, in addition to any of the standard classes
11765 like for headlines, tables, etc.
11767 p.author @r{author information, including email}
11768 p.date @r{publishing date}
11769 p.creator @r{creator info, about org mode version}
11770 .title @r{document title}
11771 .subtitle @r{document subtitle}
11772 .todo @r{TODO keywords, all not-done states}
11773 .done @r{the DONE keywords, all states that count as done}
11774 .WAITING @r{each TODO keyword also uses a class named after itself}
11775 .timestamp @r{timestamp}
11776 .timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED}
11777 .timestamp-wrapper @r{span around keyword plus timestamp}
11778 .tag @r{tag in a headline}
11779 ._HOME @r{each tag uses itself as a class, "@@" replaced by "_"}
11780 .target @r{target for links}
11781 .linenr @r{the line number in a code example}
11782 .code-highlighted @r{for highlighting referenced code lines}
11783 div.outline-N @r{div for outline level N (headline plus text))}
11784 div.outline-text-N @r{extra div for text at outline level N}
11785 .section-number-N @r{section number in headlines, different for each level}
11786 .figure-number @r{label like "Figure 1:"}
11787 .table-number @r{label like "Table 1:"}
11788 .listing-number @r{label like "Listing 1:"}
11789 div.figure @r{how to format an in-lined image}
11790 pre.src @r{formatted source code}
11791 pre.example @r{normal example}
11792 p.verse @r{verse paragraph}
11793 div.footnotes @r{footnote section headline}
11794 p.footnote @r{footnote definition paragraph, containing a footnote}
11795 .footref @r{a footnote reference number (always a <sup>)}
11796 .footnum @r{footnote number in footnote definition (always <sup>)}
11797 .org-svg @r{default class for a linked @file{.svg} image}
11800 @vindex org-html-style-default
11801 @vindex org-html-head-include-default-style
11802 @vindex org-html-head
11803 @vindex org-html-head-extra
11804 @cindex #+HTML_INCLUDE_STYLE
11805 The HTML export back-end includes a compact default style in each exported
11806 HTML file. To override the default style with another style, use these
11807 keywords in the Org file. They will replace the global defaults the HTML
11810 @cindex #+HTML_HEAD
11811 @cindex #+HTML_HEAD_EXTRA
11813 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
11814 #+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
11817 To just turn off the default style, customize
11818 @code{org-html-head-include-default-style} variable, or use this option line in
11822 #+OPTIONS: html-style:nil
11826 For longer style definitions, either use several @code{#+HTML_HEAD} and
11827 @code{#+HTML_HEAD_EXTRA} lines, or use @code{<style>} @code{</style>} blocks
11828 around them. Both of these approaches can avoid referring to an external
11831 In order to add styles to a sub-tree, use the @code{:HTML_CONTAINER_CLASS:}
11832 property to assign a class to the tree. In order to specify CSS styles for a
11833 particular headline, you can use the id specified in a @code{:CUSTOM_ID:}
11836 Never change the @code{org-html-style-default} constant. Instead use other
11837 simpler ways of customizing as described above.
11840 @c FIXME: More about header and footer styles
11841 @c FIXME: Talk about links and targets.
11843 @node JavaScript support
11844 @subsection JavaScript supported display of web pages
11846 @cindex Rose, Sebastian
11847 Sebastian Rose has written a JavaScript program especially designed to
11848 enhance the web viewing experience of HTML files created with Org. This
11849 program enhances large files in two different ways of viewing. One is an
11850 @emph{Info}-like mode where each section is displayed separately and
11851 navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys
11852 as well, press @kbd{?} for an overview of the available keys). The second
11853 one has a @emph{folding} view, much like Org provides inside Emacs. The
11854 script is available at @url{http://orgmode.org/org-info.js} and the
11855 documentation at @url{http://orgmode.org/worg/code/org-info-js/}. The script
11856 is hosted on @url{http://orgmode.org}, but for reliability, prefer installing
11857 it on your own web server.
11859 To use this program, just add this line to the Org file:
11861 @cindex #+INFOJS_OPT
11863 #+INFOJS_OPT: view:info toc:nil
11867 The HTML header now has the code needed to automatically invoke the script.
11868 For setting options, use the syntax from the above line for options described
11872 path: @r{The path to the script. The default grabs the script from}
11873 @r{@url{http://orgmode.org/org-info.js}, but you might want to have}
11874 @r{a local copy and use a path like @samp{../scripts/org-info.js}.}
11875 view: @r{Initial view when the website is first shown. Possible values are:}
11876 info @r{Info-like interface with one section per page.}
11877 overview @r{Folding interface, initially showing only top-level.}
11878 content @r{Folding interface, starting with all headlines visible.}
11879 showall @r{Folding interface, all headlines and text visible.}
11880 sdepth: @r{Maximum headline level that will still become an independent}
11881 @r{section for info and folding modes. The default is taken from}
11882 @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).}
11883 @r{If this is smaller than in @code{org-export-headline-levels}, each}
11884 @r{info/folding section can still contain child headlines.}
11885 toc: @r{Should the table of contents @emph{initially} be visible?}
11886 @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}
11887 tdepth: @r{The depth of the table of contents. The defaults are taken from}
11888 @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}
11889 ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?}
11890 @r{If yes, the toc will never be displayed as a section.}
11891 ltoc: @r{Should there be short contents (children) in each section?}
11892 @r{Make this @code{above} if the section should be above initial text.}
11893 mouse: @r{Headings are highlighted when the mouse is over them. Should be}
11894 @r{@samp{underline} (default) or a background color like @samp{#cccccc}.}
11895 buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the}
11896 @r{default), only one such button will be present.}
11899 @vindex org-html-infojs-options
11900 @vindex org-html-use-infojs
11901 You can choose default values for these options by customizing the variable
11902 @code{org-html-infojs-options}. If you want the script to always apply to
11903 your pages, configure the variable @code{org-html-use-infojs}.
11905 @node @LaTeX{} export
11906 @section @LaTeX{} export
11907 @cindex @LaTeX{} export
11910 The @LaTeX{} export back-end can handle complex documents, incorporate
11911 standard or custom @LaTeX{} document classes, generate documents using
11912 alternate @LaTeX{} engines, and produce fully linked PDF files with indexes,
11913 bibliographies, and tables of contents, destined for interactive online
11914 viewing or high-quality print publication.
11916 While the details are covered in-depth in this section, here are some quick
11917 references to variables for the impatient: for engines, see
11918 @code{org-latex-compiler}; for build sequences, see
11919 @code{org-latex-pdf-process}; for packages, see
11920 @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.
11922 An important note about the @LaTeX{} export back-end: it is sensitive to
11923 blank lines in the Org document. That's because @LaTeX{} itself depends on
11924 blank lines to tell apart syntactical elements, such as paragraphs.
11927 * @LaTeX{} export commands:: For producing @LaTeX{} and PDF documents.
11928 * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end.
11929 * @LaTeX{} header and sectioning:: For file structure.
11930 * Quoting @LaTeX{} code:: Directly in the Org document.
11931 * Tables in @LaTeX{} export:: Attributes specific to tables.
11932 * Images in @LaTeX{} export:: Attributes specific to images.
11933 * Plain lists in @LaTeX{} export:: Attributes specific to lists.
11934 * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks.
11935 * Example blocks in @LaTeX{} export:: Attributes specific to example blocks.
11936 * Special blocks in @LaTeX{} export:: Attributes specific to special blocks.
11937 * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules.
11940 @node @LaTeX{} export commands
11941 @subsection @LaTeX{} export commands
11944 @orgcmd{C-c C-e l l,org-latex-export-to-latex}
11945 Export as @LaTeX{} file with a @file{.tex} extension. For @file{myfile.org},
11946 Org exports to @file{myfile.tex}, overwriting without warning. @kbd{C-c C-e
11947 l l} Exports to @LaTeX{} file.
11949 @orgcmd{C-c C-e l L,org-latex-export-as-latex}
11950 Export to a temporary buffer. Do not create a file.
11951 @orgcmd{C-c C-e l p,org-latex-export-to-pdf}
11952 Export as @LaTeX{} file and convert it to PDF file.
11954 Export as @LaTeX{} file and convert it to PDF, then open the PDF using the default viewer.
11957 @vindex org-latex-compiler
11958 @vindex org-latex-bibtex-compiler
11959 @vindex org-latex-default-packages-alist
11960 The @LaTeX{} export back-end can use any of these @LaTeX{} engines:
11961 @samp{pdflatex}, @samp{xelatex}, and @samp{lualatex}. These engines compile
11962 @LaTeX{} files with different compilers, packages, and output options. The
11963 @LaTeX{} export back-end finds the compiler version to use from
11964 @code{org-latex-compiler} variable or the @code{#+LATEX_COMPILER} keyword in
11965 the Org file. See the docstring for the
11966 @code{org-latex-default-packages-alist} for loading packages with certain
11967 compilers. Also see @code{org-latex-bibtex-compiler} to set the bibliography
11968 compiler@footnote{This does not allow setting different bibliography
11969 compilers for different files. However, ``smart'' @LaTeX{} compilation
11970 systems, such as @samp{latexmk}, can select the correct bibliography
11973 @node @LaTeX{} specific export settings
11974 @subsection @LaTeX{} specific export settings
11976 The @LaTeX{} export back-end has several additional keywords for customizing
11977 @LaTeX{} output. Setting these keywords works similar to the general options
11978 (@pxref{Export settings}).
11982 @cindex #+DESCRIPTION (@LaTeX{})
11983 The document's description. The description along with author name,
11984 keywords, and related file metadata are inserted in the output file by the
11985 @samp{hyperref} package. See @code{org-latex-hyperref-template} for
11986 customizing metadata items. See @code{org-latex-title-command} for
11987 typesetting description into the document's front matter. Use multiple
11988 @code{#+DESCRIPTION} lines for long descriptions.
11991 @cindex #+LATEX_CLASS
11992 @vindex org-latex-default-class
11993 @vindex org-latex-classes
11994 This is @LaTeX{} document class, such as @code{article}, @code{report},
11995 @code{book}, and so on, which contain predefined preamble and headline level
11996 mapping that the @LaTeX{} export back-end needs. The back-end reads the
11997 default class name from the @code{org-latex-default-class} variable. Org has
11998 @code{article} as the default class. A valid default class must be an
11999 element of @code{org-latex-classes}.
12001 @item LATEX_CLASS_OPTIONS
12002 @cindex #+LATEX_CLASS_OPTIONS
12003 Options the @LaTeX{} export back-end uses when calling the @LaTeX{} document
12006 @item LATEX_COMPILER
12007 @cindex #+LATEX_COMPILER
12008 @vindex org-latex-compiler
12009 The compiler, such as @samp{pdflatex}, @samp{xelatex}, @samp{lualatex}, for
12010 producing the PDF (@code{org-latex-compiler}).
12013 @cindex #+LATEX_HEADER
12014 @vindex org-latex-classes
12015 Arbitrary lines to add to the document's preamble, before the @samp{hyperref}
12016 settings. See @code{org-latex-classes} for adjusting the structure and order
12017 of the @LaTeX{} headers.
12019 @item LATEX_HEADER_EXTRA
12020 @cindex #+LATEX_HEADER_EXTRA
12021 @vindex org-latex-classes
12022 Arbitrary lines to add to the document's preamble, before the @samp{hyperref}
12023 settings. See @code{org-latex-classes} for adjusting the structure and order
12024 of the @LaTeX{} headers.
12027 @cindex #+KEYWORDS (@LaTeX{})
12028 The keywords for the document. The description along with author name,
12029 keywords, and related file metadata are inserted in the output file by the
12030 @samp{hyperref} package. See @code{org-latex-hyperref-template} for
12031 customizing metadata items. See @code{org-latex-title-command} for
12032 typesetting description into the document's front matter. Use multiple
12033 @code{#+KEYWORDS} lines if necessary.
12036 @cindex #+SUBTITLE (@LaTeX{})
12037 @vindex org-latex-subtitle-separate
12038 @vindex org-latex-subtitle-format
12039 The document's subtitle. It is typeset as per
12040 @code{org-latex-subtitle-format}. If @code{org-latex-subtitle-separate} is
12041 non-@code{nil}, it is typed as part of the @samp{\title}-macro. See
12042 @code{org-latex-hyperref-template} for customizing metadata items. See
12043 @code{org-latex-title-command} for typesetting description into the
12044 document's front matter.
12047 The following sections have further details.
12049 @node @LaTeX{} header and sectioning
12050 @subsection @LaTeX{} header and sectioning structure
12051 @cindex @LaTeX{} class
12052 @cindex @LaTeX{} sectioning structure
12053 @cindex @LaTeX{} header
12054 @cindex header, for @LaTeX{} files
12055 @cindex sectioning structure, for @LaTeX{} export
12057 The @LaTeX{} export back-end converts the first three of Org's outline levels
12058 into @LaTeX{} headlines. The remaining Org levels are exported as
12059 @code{itemize} or @code{enumerate} lists. To change this globally for the
12060 cut-off point between levels and lists, (@pxref{Export settings}).
12062 By default, the @LaTeX{} export back-end uses the @code{article} class.
12064 @vindex org-latex-default-class
12065 @vindex org-latex-classes
12066 @vindex org-latex-default-packages-alist
12067 @vindex org-latex-packages-alist
12068 To change the default class globally, edit @code{org-latex-default-class}.
12069 To change the default class locally in an Org file, add option lines
12070 @code{#+LATEX_CLASS: myclass}. To change the default class for just a part
12071 of the Org file, set a sub-tree property, @code{EXPORT_LATEX_CLASS}. The
12072 class name entered here must be valid member of @code{org-latex-classes}.
12073 This variable defines a header template for each class into which the
12074 exporter splices the values of @code{org-latex-default-packages-alist} and
12075 @code{org-latex-packages-alist}. Use the same three variables to define
12076 custom sectioning or custom classes.
12078 @cindex #+LATEX_CLASS
12079 @cindex #+LATEX_CLASS_OPTIONS
12080 @cindex property, EXPORT_LATEX_CLASS
12081 @cindex property, EXPORT_LATEX_CLASS_OPTIONS
12082 The @LaTeX{} export back-end sends the @code{LATEX_CLASS_OPTIONS} keyword and
12083 @code{EXPORT_LATEX_CLASS_OPTIONS} property as options to the @LaTeX{}
12084 @code{\documentclass} macro. The options and the syntax for specifying them,
12085 including enclosing them in square brackets, follow @LaTeX{} conventions.
12088 #+LATEX_CLASS_OPTIONS: [a4paper,11pt,twoside,twocolumn]
12091 @cindex #+LATEX_HEADER
12092 @cindex #+LATEX_HEADER_EXTRA
12093 The @LaTeX{} export back-end appends values from @code{LATEX_HEADER} and
12094 @code{LATEX_HEADER_EXTRA} keywords to the @LaTeX{} header. The docstring for
12095 @code{org-latex-classes} explains in more detail. Also note that @LaTeX{}
12096 export back-end does not append @code{LATEX_HEADER_EXTRA} to the header when
12097 previewing @LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).
12099 A sample Org file with the above headers:
12102 #+LATEX_CLASS: article
12103 #+LATEX_CLASS_OPTIONS: [a4paper]
12104 #+LATEX_HEADER: \usepackage@{xyz@}
12112 @node Quoting @LaTeX{} code
12113 @subsection Quoting @LaTeX{} code
12115 The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code,
12116 @pxref{Embedded @LaTeX{}}. There are three ways to embed such code in the
12117 Org file and they all use different quoting syntax.
12119 Inserting in-line quoted with @ symbols:
12120 @cindex inline, in @LaTeX{} export
12122 Code embedded in-line @@@@latex:any arbitrary LaTeX code@@@@ in a paragraph.
12125 Inserting as one or more keyword lines in the Org file:
12128 #+LATEX: any arbitrary LaTeX code
12131 Inserting as an export block in the Org file, where the back-end exports any
12132 code between begin and end markers:
12133 @cindex #+BEGIN_EXPORT latex
12135 #+BEGIN_EXPORT latex
12136 any arbitrary LaTeX code
12140 @node Tables in @LaTeX{} export
12141 @subsection Tables in @LaTeX{} export
12142 @cindex tables, in @LaTeX{} export
12143 @cindex #+ATTR_LATEX, in tables
12145 The @LaTeX{} export back-end can pass several @LaTeX{} attributes for table
12146 contents and layout. Besides specifying label and caption (@pxref{Images and
12147 tables}), the other valid @LaTeX{} attributes include:
12151 @vindex org-latex-default-table-mode
12152 The @LaTeX{} export back-end wraps the table differently depending on the
12153 mode for accurate rendering of math symbols. Mode is either @code{table},
12154 @code{math}, @code{inline-math} or @code{verbatim}. For @code{math} or
12155 @code{inline-math} mode, @LaTeX{} export back-end wraps the table in a math
12156 environment, but every cell in it is exported as-is. The @LaTeX{} export
12157 back-end determines the default mode from
12158 @code{org-latex-default-table-mode}. For , The @LaTeX{} export back-end
12159 merges contiguous tables in the same mode into a single environment.
12161 @vindex org-latex-default-table-environment
12162 Set the default @LaTeX{} table environment for the @LaTeX{} export back-end
12163 to use when exporting Org tables. Common @LaTeX{} table environments are
12164 provided by these packages: @code{tabularx}, @code{longtable}, @code{array},
12165 @code{tabu}, and @code{bmatrix}. For packages, such as @code{tabularx} and
12166 @code{tabu}, or any newer replacements, include them in the
12167 @code{org-latex-packages-alist} variable so the @LaTeX{} export back-end can
12168 insert the appropriate load package headers in the converted @LaTeX{} file.
12169 Look in the docstring for the @code{org-latex-packages-alist} variable for
12170 configuring these packages for @LaTeX{} snippet previews, if any.
12172 Use @code{#+CAPTION} keyword to set a simple caption for a table
12173 (@pxref{Images and tables}). For custom captions, use @code{:caption}
12174 attribute, which accepts raw @LaTeX{} code. @code{:caption} value overrides
12175 @code{#+CAPTION} value.
12178 The table environments by default are not floats in @LaTeX{}. To make them
12179 floating objects use @code{:float} with one of the following options:
12180 @code{sideways}, @code{multicolumn}, @code{t}, and @code{nil}. Note that
12181 @code{sidewaystable} has been deprecated since Org 8.3. @LaTeX{} floats can
12182 also have additional layout @code{:placement} attributes. These are the
12183 usual @code{[h t b p ! H]} permissions specified in square brackets. Note
12184 that for @code{:float sideways} tables, the @LaTeX{} export back-end ignores
12185 @code{:placement} attributes.
12189 The @LaTeX{} export back-end uses these attributes for regular tables to set
12190 their alignments, fonts, and widths.
12192 When @code{:spread} is non-@code{nil}, the @LaTeX{} export back-end spreads
12193 or shrinks the table by the @code{:width} for @code{tabu} and @code{longtabu}
12194 environments. @code{:spread} has no effect if @code{:width} is not set.
12198 @vindex org-latex-tables-booktabs
12199 @vindex org-latex-tables-centered
12200 All three commands are toggles. @code{:booktabs} brings in modern
12201 typesetting enhancements to regular tables. The @code{booktabs} package has
12202 to be loaded through @code{org-latex-packages-alist}. @code{:center} is for
12203 centering the table. @code{:rmlines} removes all but the very first
12204 horizontal line made of ASCII characters from "table.el" tables only.
12206 @itemx :math-suffix
12207 @itemx :math-arguments
12208 The @LaTeX{} export back-end inserts @code{:math-prefix} string value in a
12209 math environment before the table. The @LaTeX{} export back-end inserts
12210 @code{:math-suffix} string value in a math environment after the table. The
12211 @LaTeX{} export back-end inserts @code{:math-arguments} string value between
12212 the macro name and the table's contents. @code{:math-arguments} comes in use
12213 for matrix macros that require more than one argument, such as
12214 @code{qbordermatrix}.
12217 @LaTeX{} table attributes help formatting tables for a wide range of
12218 situations, such as matrix product or spanning multiple pages:
12221 #+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l
12225 #+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
12228 #+ATTR_LATEX: :mode math :environment bmatrix
12233 Set the caption with the @LaTeX{} command
12234 @code{\bicaption@{HeadingA@}@{HeadingB@}}:
12237 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
12243 @node Images in @LaTeX{} export
12244 @subsection Images in @LaTeX{} export
12245 @cindex images, inline in @LaTeX{}
12246 @cindex inlining images in @LaTeX{}
12247 @cindex #+ATTR_LATEX, in images
12249 The @LaTeX{} export back-end processes image links in Org files that do not
12250 have descriptions, such as these links @samp{[[file:img.jpg]]} or
12251 @samp{[[./img.jpg]]}, as direct image insertions in the final PDF output. In
12252 the PDF, they are no longer links but actual images embedded on the page.
12253 The @LaTeX{} export back-end uses @code{\includegraphics} macro to insert the
12254 image. But for TikZ@footnote{@url{http://sourceforge.net/projects/pgf/}}
12255 images, the back-end uses an @code{\input} macro wrapped within
12256 a @code{tikzpicture} environment.
12258 For specifying image @code{:width}, @code{:height}, and other
12259 @code{:options}, use this syntax:
12262 #+ATTR_LATEX: :width 5cm :options angle=90
12263 [[./img/sed-hr4049.pdf]]
12266 For custom commands for captions, use the @code{:caption} attribute. It will
12267 override the default @code{#+CAPTION} value:
12270 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
12271 [[./img/sed-hr4049.pdf]]
12274 When captions follow the method as described in @ref{Images and tables}, the
12275 @LaTeX{} export back-end wraps the picture in a floating @code{figure}
12276 environment. To float an image without specifying a caption, set the
12277 @code{:float} attribute to one of the following:
12280 @code{t}: for a standard @samp{figure} environment; used by default whenever
12281 an image has a caption.
12283 @code{multicolumn}: to span the image across multiple columns of a page; the
12284 back-end wraps the image in a @code{figure*} environment.
12286 @code{wrap}: for text to flow around the image on the right; the figure
12287 occupies the left half of the page.
12289 @code{sideways}: for a new page with the image sideways, rotated ninety
12290 degrees, in a @code{sidewaysfigure} environment; overrides @code{:placement}
12293 @code{nil}: to avoid a @code{:float} even if using a caption.
12296 Use the @code{placement} attribute to modify a floating environment's placement.
12299 #+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement
12300 @{r@}@{0.4\textwidth@} [[./img/hst.png]]
12303 @vindex org-latex-images-centered
12304 @cindex center image (@LaTeX{} export)
12305 @cindex image, centering (@LaTeX{} export)
12307 The @LaTeX{} export back-end centers all images by default. Setting
12308 @code{:center} attribute to @code{nil} disables centering. To disable
12309 centering globally, set @code{org-latex-images-centered} to @code{t}.
12311 Set the @code{:comment-include} attribute to non-@code{nil} value for the
12312 @LaTeX{} export back-end to comment out the @code{\includegraphics} macro.
12314 @node Plain lists in @LaTeX{} export
12315 @subsection Plain lists in @LaTeX{} export
12316 @cindex plain lists, in @LaTeX{} export
12317 @cindex #+ATTR_LATEX, in plain lists
12319 The @LaTeX{} export back-end accepts the @code{:environment} and
12320 @code{:options} attributes for plain lists. Both attributes work together
12321 for customizing lists, as shown in the examples:
12324 #+LATEX_HEADER: \usepackage[inline]@{enumitem@}
12325 Some ways to say "Hello":
12326 #+ATTR_LATEX: :environment itemize*
12327 #+ATTR_LATEX: :options [label=@{@}, itemjoin=@{,@}, itemjoin*=@{, and@}]
12333 Since @LaTeX{} supports only four levels of nesting for lists, use an
12334 external package, such as @samp{enumitem} in @LaTeX{}, for levels deeper than
12338 #+LATEX_HEADER: \usepackage@{enumitem@}
12339 #+LATEX_HEADER: \renewlist@{itemize@}@{itemize@}@{9@}
12340 #+LATEX_HEADER: \setlist[itemize]@{label=$\circ$@}
12348 @node Source blocks in @LaTeX{} export
12349 @subsection Source blocks in @LaTeX{} export
12350 @cindex source blocks, in @LaTeX{} export
12351 @cindex #+ATTR_LATEX, in source blocks
12353 The @LaTeX{} export back-end can make source code blocks into floating
12354 objects through the attributes @code{:float} and @code{:options}. For
12359 @code{t}: makes a source block float; by default floats any source block with
12362 @code{multicolumn}: spans the source block across multiple columns of a page.
12364 @code{nil}: avoids a @code{:float} even if using a caption; useful for
12365 source code blocks that may not fit on a page.
12369 #+ATTR_LATEX: :float nil
12370 #+BEGIN_SRC emacs-lisp
12371 Lisp code that may not fit in a single page.
12375 @vindex org-latex-listings-options
12376 @vindex org-latex-minted-options
12377 The @LaTeX{} export back-end passes string values in @code{:options} to
12378 @LaTeX{} packages for customization of that specific source block. In the
12379 example below, the @code{:options} are set for Minted. Minted is a source
12380 code highlighting @LaTeX{}package with many configurable options.
12383 #+ATTR_LATEX: :options commentstyle=\bfseries
12384 #+BEGIN_SRC emacs-lisp
12386 (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2)))))
12390 To apply similar configuration options for all source blocks in a file, use
12391 the @code{org-latex-listings-options} and @code{org-latex-minted-options}
12394 @node Example blocks in @LaTeX{} export
12395 @subsection Example blocks in @LaTeX{} export
12396 @cindex example blocks, in @LaTeX{} export
12397 @cindex verbatim blocks, in @LaTeX{} export
12398 @cindex #+ATTR_LATEX, in example blocks
12400 The @LaTeX{} export back-end wraps the contents of example blocks in a
12401 @samp{verbatim} environment. To change this behavior to use another
12402 environment globally, specify an appropriate export filter (@pxref{Advanced
12403 configuration}). To change this behavior to use another environment for each
12404 block, use the @code{:environment} parameter to specify a custom environment.
12407 #+ATTR_LATEX: :environment myverbatim
12409 This sentence is false.
12413 @node Special blocks in @LaTeX{} export
12414 @subsection Special blocks in @LaTeX{} export
12415 @cindex special blocks, in @LaTeX{} export
12416 @cindex abstract, in @LaTeX{} export
12417 @cindex proof, in @LaTeX{} export
12418 @cindex #+ATTR_LATEX, in special blocks
12421 For other special blocks in the Org file, the @LaTeX{} export back-end makes
12422 a special environment of the same name. The back-end also takes
12423 @code{:options}, if any, and appends as-is to that environment's opening
12424 string. For example:
12428 We demonstrate how to solve the Syracuse problem.
12431 #+ATTR_LATEX: :options [Proof of important theorem]
12434 Therefore, any even number greater than 2 is the sum of two primes.
12443 We demonstrate how to solve the Syracuse problem.
12446 \begin@{proof@}[Proof of important theorem]
12448 Therefore, any even number greater than 2 is the sum of two primes.
12452 If you need to insert a specific caption command, use @code{:caption}
12453 attribute. It will override standard @code{#+CAPTION} value, if any. For
12457 #+ATTR_LATEX: :caption \MyCaption@{HeadingA@}
12463 @node Horizontal rules in @LaTeX{} export
12464 @subsection Horizontal rules in @LaTeX{} export
12465 @cindex horizontal rules, in @LaTeX{} export
12466 @cindex #+ATTR_LATEX, in horizontal rules
12468 The @LaTeX{} export back-end converts horizontal rules by the specified
12469 @code{:width} and @code{:thickness} attributes. For example:
12472 #+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
12476 @node Markdown export
12477 @section Markdown export
12478 @cindex Markdown export
12480 The Markdown export back-end, @code{md}, converts an Org file to a Markdown
12481 format, as defined at @url{http://daringfireball.net/projects/markdown/}.
12483 Since @code{md} is built on top of the HTML back-end, any Org constructs not
12484 supported by Markdown, such as tables, the underlying @code{html} back-end
12485 (@pxref{HTML export}) converts them.
12487 @subheading Markdown export commands
12490 @orgcmd{C-c C-e m m,org-md-export-to-markdown}
12491 Export to a text file with Markdown syntax. For @file{myfile.org}, Org
12492 exports to @file{myfile.md}, overwritten without warning.
12493 @orgcmd{C-c C-e m M,org-md-export-as-markdown}
12494 Export to a temporary buffer. Does not create a file.
12496 Export as a text file with Markdown syntax, then open it.
12499 @subheading Header and sectioning structure
12501 @vindex org-md-headline-style
12502 Based on @code{org-md-headline-style}, markdown export can generate headlines
12503 of both @code{atx} and @code{setext} types. @code{atx} limits headline
12504 levels to two. @code{setext} limits headline levels to six. Beyond these
12505 limits, the export back-end converts headlines to lists. To set a limit to a
12506 level before the absolute limit (@pxref{Export settings}).
12508 @c begin opendocument
12510 @node OpenDocument Text export
12511 @section OpenDocument Text export
12513 @cindex OpenDocument
12514 @cindex export, OpenDocument
12515 @cindex LibreOffice
12517 The ODT export back-end handles creating of OpenDocument Text (ODT) format
12518 files. The format complies with @cite{OpenDocument-v1.2
12519 specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
12520 Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
12521 is compatible with LibreOffice 3.4.
12524 * Pre-requisites for ODT export:: Required packages.
12525 * ODT export commands:: Invoking export.
12526 * ODT specific export settings:: Configuration options.
12527 * Extending ODT export:: Producing @file{.doc}, @file{.pdf} files.
12528 * Applying custom styles:: Styling the output.
12529 * Links in ODT export:: Handling and formatting links.
12530 * Tables in ODT export:: Org table conversions.
12531 * Images in ODT export:: Inserting images.
12532 * Math formatting in ODT export:: Formatting @LaTeX{} fragments.
12533 * Labels and captions in ODT export:: Rendering objects.
12534 * Literal examples in ODT export:: For source code and example blocks.
12535 * Advanced topics in ODT export:: For power users.
12538 @node Pre-requisites for ODT export
12539 @subsection Pre-requisites for ODT export
12541 The ODT export back-end relies on the @file{zip} program to create the final
12542 compressed ODT output. Check if @file{zip} is locally available and
12543 executable. Without @file{zip}, export cannot finish.
12545 @node ODT export commands
12546 @subsection ODT export commands
12547 @anchor{x-export-to-odt}
12548 @cindex region, active
12549 @cindex active region
12550 @cindex transient-mark-mode
12552 @orgcmd{C-c C-e o o,org-odt-export-to-odt}
12553 @cindex property EXPORT_FILE_NAME
12555 Export as OpenDocument Text file.
12557 @vindex org-odt-preferred-output-format
12558 If @code{org-odt-preferred-output-format} is specified, the ODT export
12559 back-end automatically converts the exported file to that format.
12560 @xref{x-export-to-other-formats, , Automatically exporting to other formats}.
12562 For @file{myfile.org}, Org exports to @file{myfile.odt}, overwriting without
12563 warning. The ODT export back-end exports a region only if a region was
12564 active. Note for exporting active regions, the @code{transient-mark-mode}
12565 has to be turned on.
12567 If the selected region is a single tree, the ODT export back-end makes the
12568 tree head the document title. Incidentally, @kbd{C-c @@} selects the current
12569 sub-tree. If the tree head entry has, or inherits, an
12570 @code{EXPORT_FILE_NAME} property, the ODT export back-end uses that for file
12574 Export to an OpenDocument Text file format and open it.
12576 @vindex org-odt-preferred-output-format
12577 When @code{org-odt-preferred-output-format} is specified, open the converted
12578 file instead. @xref{x-export-to-other-formats, , Automatically exporting to
12582 @node ODT specific export settings
12583 @subsection ODT specific export settings
12584 The ODT export back-end has several additional keywords for customizing ODT
12585 output. Setting these keywords works similar to the general options
12586 (@pxref{Export settings}).
12590 @cindex #+DESCRIPTION (ODT)
12591 This is the document's description, which the ODT export back-end inserts as
12592 document metadata. For long descriptions, use multiple @code{#+DESCRIPTION}
12596 @cindex #+KEYWORDS (ODT)
12597 The keywords for the document. The ODT export back-end inserts the
12598 description along with author name, keywords, and related file metadata as
12599 metadata in the output file. Use multiple @code{#+KEYWORDS} lines if
12602 @item ODT_STYLES_FILE
12603 @cindex ODT_STYLES_FILE
12604 @vindex org-odt-styles-file
12605 The ODT export back-end uses the @code{org-odt-styles-file} by default. See
12606 @ref{Applying custom styles} for details.
12609 @cindex SUBTITLE (ODT)
12610 The document subtitle.
12613 @node Extending ODT export
12614 @subsection Extending ODT export
12616 The ODT export back-end can produce documents in other formats besides ODT
12617 using a specialized ODT converter process. Its common interface works with
12618 popular converters to produce formats such as @samp{doc}, or convert a
12619 document from one format, say @samp{csv}, to another format, say @samp{xls}.
12621 @cindex @file{unoconv}
12622 @cindex LibreOffice
12624 Customize @code{org-odt-convert-process} variable to point to @code{unoconv},
12625 which is the ODT's preferred converter. Working installations of LibreOffice
12626 would already have @code{unoconv} installed. Alternatively, other converters
12627 may be substituted here. @xref{Configuring a document converter}.
12629 @subsubheading Automatically exporting to other formats
12630 @anchor{x-export-to-other-formats}
12632 @vindex org-odt-preferred-output-format
12633 If ODT format is just an intermediate step to get to other formats, such as
12634 @samp{doc}, @samp{docx}, @samp{rtf}, or @samp{pdf}, etc., then extend the ODT
12635 export back-end to directly produce that format. Specify the final format in
12636 the @code{org-odt-preferred-output-format} variable. This is one way to
12637 extend (@pxref{x-export-to-odt,,Exporting to ODT}).
12639 @subsubheading Converting between document formats
12640 @anchor{x-convert-to-other-formats}
12642 The Org export back-end is made to be inter-operable with a wide range of text
12643 document format converters. Newer generation converters, such as LibreOffice
12644 and Pandoc, can handle hundreds of formats at once. Org provides a
12645 consistent interaction with whatever converter is installed. Here are some
12648 @vindex org-odt-convert
12651 @item M-x org-odt-convert RET
12652 Convert an existing document from one format to another. With a prefix
12653 argument, opens the newly produced file.
12656 @node Applying custom styles
12657 @subsection Applying custom styles
12658 @cindex styles, custom
12659 @cindex template, custom
12661 The ODT export back-end comes with many OpenDocument styles (@pxref{Working
12662 with OpenDocument style files}). To expand or further customize these
12663 built-in style sheets, either edit the style sheets directly or generate them
12664 using an application such as LibreOffice. The example here shows creating a
12665 style using LibreOffice.
12667 @subsubheading Applying custom styles: the easy way
12671 Create a sample @file{example.org} file with settings as shown below, and
12672 export it to ODT format.
12675 #+OPTIONS: H:10 num:t
12679 Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist}
12680 to locate the target styles, which typically have the @samp{Org} prefix.
12681 Open one, modify, and save as either OpenDocument Text (@file{.odt}) or
12682 OpenDocument Template (@file{.ott}) file.
12685 @cindex #+ODT_STYLES_FILE
12686 @vindex org-odt-styles-file
12687 Customize the variable @code{org-odt-styles-file} and point it to the
12688 newly created file. For additional configuration options
12689 @pxref{x-overriding-factory-styles,,Overriding factory styles}.
12691 To apply and ODT style to a particular file, use the @code{#+ODT_STYLES_FILE}
12692 option as shown in the example below:
12695 #+ODT_STYLES_FILE: "/path/to/example.ott"
12701 #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
12706 @subsubheading Using third-party styles and templates
12708 The ODT export back-end relies on many templates and style names. Using
12709 third-party styles and templates can lead to mismatches. Templates derived
12710 from built in ODT templates and styles seem to have fewer problems.
12712 @node Links in ODT export
12713 @subsection Links in ODT export
12714 @cindex links, in ODT export
12716 ODT export back-end creates native cross-references for internal links and
12717 Internet-style links for all other link types.
12719 A link with no description and pointing to a regular---un-itemized---outline
12720 heading is replaced with a cross-reference and section number of the heading.
12722 A @samp{\ref@{label@}}-style reference to an image, table etc.@: is replaced
12723 with a cross-reference and sequence number of the labeled entity.
12724 @xref{Labels and captions in ODT export}.
12726 @node Tables in ODT export
12727 @subsection Tables in ODT export
12728 @cindex tables, in ODT export
12730 The ODT export back-end handles native Org mode tables (@pxref{Tables}) and
12731 simple @file{table.el} tables. Complex @file{table.el} tables having column
12732 or row spans are not supported. Such tables are stripped from the exported
12735 By default, the ODT export back-end exports a table with top and bottom
12736 frames and with ruled lines separating row and column groups (@pxref{Column
12737 groups}). All tables are typeset to occupy the same width. The ODT export
12738 back-end honors any table alignments and relative widths for columns
12739 (@pxref{Column width and alignment}).
12741 Note that the ODT export back-end interprets column widths as weighted
12742 ratios, the default weight being 1.
12746 Specifying @code{:rel-width} property on an @code{#+ATTR_ODT} line controls
12747 the width of the table. For example:
12750 #+ATTR_ODT: :rel-width 50
12751 | Area/Month | Jan | Feb | Mar | Sum |
12752 |---------------+-------+-------+-------+-------|
12754 | <l13> | <r5> | <r5> | <r5> | <r6> |
12755 | North America | 1 | 21 | 926 | 948 |
12756 | Middle East | 6 | 75 | 844 | 925 |
12757 | Asia Pacific | 9 | 27 | 790 | 826 |
12758 |---------------+-------+-------+-------+-------|
12759 | Sum | 16 | 123 | 2560 | 2699 |
12762 On export, the above table takes 50% of text width area. The exporter sizes
12763 the columns in the ratio: 13:5:5:5:6. The first column is left-aligned and
12764 rest of the columns, right-aligned. Vertical rules separate the header and
12765 the last column. Horizontal rules separate the header and the last row.
12767 For even more customization, create custom table styles and associate them
12768 with a table using the @code{#+ATTR_ODT} line. @xref{Customizing tables in
12771 @node Images in ODT export
12772 @subsection Images in ODT export
12773 @cindex images, embedding in ODT
12774 @cindex embedding images in ODT
12776 @subsubheading Embedding images
12777 The ODT export back-end processes image links in Org files that do not have
12778 descriptions, such as these links @samp{[[file:img.jpg]]} or
12779 @samp{[[./img.jpg]]}, as direct image insertions in the final output. Either
12780 of these examples works:
12790 @subsubheading Embedding clickable images
12791 For clickable images, provide a link whose description is another link to an
12792 image file. For example, to embed a image @file{org-mode-unicorn.png} which
12793 when clicked jumps to @uref{http://Orgmode.org} website, do the following
12796 [[http://orgmode.org][./org-mode-unicorn.png]]
12799 @subsubheading Sizing and scaling of embedded images
12802 Control the size and scale of the embedded images with the @code{#+ATTR_ODT}
12805 @cindex identify, ImageMagick
12806 @vindex org-odt-pixels-per-inch
12807 The ODT export back-end starts with establishing the size of the image in the
12808 final document. The dimensions of this size is measured in centimeters. The
12809 back-end then queries the image file for its dimensions measured in pixels.
12810 For this measurement, the back-end relies on ImageMagick's @file{identify}
12811 program or Emacs @code{create-image} and @code{image-size} API. ImageMagick
12812 is the preferred choice for large file sizes or frequent batch operations.
12813 The back-end then converts the pixel dimensions using
12814 @code{org-odt-pixels-per-inch} into the familiar 72 dpi or 96 dpi. The
12815 default value for this is in @code{display-pixels-per-inch}, which can be
12816 tweaked for better results based on the capabilities of the output device.
12817 Here are some common image scaling operations:
12820 @item Explicitly size the image
12821 To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
12824 #+ATTR_ODT: :width 10 :height 10
12828 @item Scale the image
12829 To embed @file{img.png} at half its size, do the following:
12832 #+ATTR_ODT: :scale 0.5
12836 @item Scale the image to a specific width
12837 To embed @file{img.png} with a width of 10 cm while retaining the original
12838 height:width ratio, do the following:
12841 #+ATTR_ODT: :width 10
12845 @item Scale the image to a specific height
12846 To embed @file{img.png} with a height of 10 cm while retaining the original
12847 height:width ratio, do the following
12850 #+ATTR_ODT: :height 10
12855 @subsubheading Anchoring of images
12858 The ODT export back-end can anchor images to @samp{"as-char"},
12859 @samp{"paragraph"}, or @samp{"page"}. Set the preferred anchor using the
12860 @code{:anchor} property of the @code{#+ATTR_ODT} line.
12862 To create an image that is anchored to a page:
12864 #+ATTR_ODT: :anchor "page"
12868 @node Math formatting in ODT export
12869 @subsection Math formatting in ODT export
12871 The ODT export back-end has special support built-in for handling math.
12874 * Working with @LaTeX{} math snippets:: Embedding in @LaTeX{} format.
12875 * Working with MathML or OpenDocument formula files:: Embedding in native format.
12878 @node Working with @LaTeX{} math snippets
12879 @subsubheading Working with @LaTeX{} math snippets
12881 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in an ODT
12882 document in one of the following ways:
12888 Add this line to the Org file. This option is activated on a per-file basis.
12894 With this option, @LaTeX{} fragments are first converted into MathML
12895 fragments using an external @LaTeX{}-to-MathML converter program. The
12896 resulting MathML fragments are then embedded as an OpenDocument Formula in
12897 the exported document.
12899 @vindex org-latex-to-mathml-convert-command
12900 @vindex org-latex-to-mathml-jar-file
12902 To specify the @LaTeX{}-to-MathML converter, customize the variables
12903 @code{org-latex-to-mathml-convert-command} and
12904 @code{org-latex-to-mathml-jar-file}.
12906 To use MathToWeb@footnote{See
12907 @uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}.} as the
12908 preferred converter, configure the above variables as
12911 (setq org-latex-to-mathml-convert-command
12912 "java -jar %j -unicode -force -df %o %I"
12913 org-latex-to-mathml-jar-file
12914 "/path/to/mathtoweb.jar")
12916 To use @LaTeX{}ML@footnote{See @uref{http://dlmf.nist.gov/LaTeXML/}.} use
12918 (setq org-latex-to-mathml-convert-command
12919 "latexmlmath \"%i\" --presentationmathml=%o")
12922 To quickly verify the reliability of the @LaTeX{}-to-MathML converter, use
12923 the following commands:
12926 @item M-x org-odt-export-as-odf RET
12927 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file.
12929 @item M-x org-odt-export-as-odf-and-open RET
12930 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file
12931 and open the formula file with the system-registered application.
12936 @cindex imagemagick
12939 Add this line to the Org file. This option is activated on a per-file basis.
12942 #+OPTIONS: tex:dvipng
12946 #+OPTIONS: tex:dvisvgm
12952 #+OPTIONS: tex:imagemagick
12955 Under this option, @LaTeX{} fragments are processed into PNG or SVG images
12956 and the resulting images are embedded in the exported document. This method
12957 requires @file{dvipng} program, @file{dvisvgm} or @file{imagemagick}
12961 @node Working with MathML or OpenDocument formula files
12962 @subsubheading Working with MathML or OpenDocument formula files
12964 When embedding @LaTeX{} math snippets in ODT documents is not reliable, there
12965 is one more option to try. Embed an equation by linking to its MathML
12966 (@file{.mml}) source or its OpenDocument formula (@file{.odf}) file as shown
12979 @node Labels and captions in ODT export
12980 @subsection Labels and captions in ODT export
12982 ODT format handles labeling and captioning of objects based on their
12983 types. Inline images, tables, @LaTeX{} fragments, and Math formulas are
12984 numbered and captioned separately. Each object also gets a unique sequence
12985 number based on its order of first appearance in the Org file. Each category
12986 has its own sequence. A caption is just a label applied to these objects.
12989 #+CAPTION: Bell curve
12990 #+LABEL: fig:SED-HR4049
12994 When rendered, it may show as follows in the exported document:
12997 Figure 2: Bell curve
13000 @vindex org-odt-category-map-alist
13001 To modify the category component of the caption, customize the option
13002 @code{org-odt-category-map-alist}. For example, to tag embedded images with
13003 the string @samp{Illustration} instead of the default string @samp{Figure},
13004 use the following setting:
13007 (setq org-odt-category-map-alist
13008 '(("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
13011 With the above modification, the previous example changes to:
13014 Illustration 2: Bell curve
13017 @node Literal examples in ODT export
13018 @subsection Literal examples in ODT export
13020 The ODT export back-end supports literal examples (@pxref{Literal examples})
13021 with full fontification. Internally, the ODT export back-end relies on
13022 @file{htmlfontify.el} to generate the style definitions needed for fancy
13023 listings. The auto-generated styles get @samp{OrgSrc} prefix and inherit
13024 colors from the faces used by Emacs @code{font-lock} library for that source
13027 @vindex org-odt-fontify-srcblocks
13028 For custom fontification styles, customize the
13029 @code{org-odt-create-custom-styles-for-srcblocks} option.
13031 @vindex org-odt-create-custom-styles-for-srcblocks
13032 To turn off fontification of literal examples, customize the
13033 @code{org-odt-fontify-srcblocks} option.
13035 @node Advanced topics in ODT export
13036 @subsection Advanced topics in ODT export
13038 The ODT export back-end has extensive features useful for power users and
13039 frequent uses of ODT formats.
13042 * Configuring a document converter:: Registering a document converter.
13043 * Working with OpenDocument style files:: Exploring internals.
13044 * Creating one-off styles:: Customizing styles, highlighting.
13045 * Customizing tables in ODT export:: Defining table templates.
13046 * Validating OpenDocument XML:: Debugging corrupted OpenDocument files.
13049 @node Configuring a document converter
13050 @subsubheading Configuring a document converter
13052 @cindex doc, docx, rtf
13055 The ODT export back-end works with popular converters with little or no extra
13056 configuration. @xref{Extending ODT export}. The following is for unsupported
13057 converters or tweaking existing defaults.
13060 @item Register the converter
13062 @vindex org-odt-convert-processes
13063 Add the name of the converter to the @code{org-odt-convert-processes}
13064 variable. Note that it also requires how the converter is invoked on the
13065 command line. See the variable's docstring for details.
13067 @item Configure its capabilities
13069 @vindex org-odt-convert-capabilities
13070 @anchor{x-odt-converter-capabilities} Specify which formats the converter can
13071 handle by customizing the variable @code{org-odt-convert-capabilities}. Use
13072 the entry for the default values in this variable for configuring the new
13073 converter. Also see its docstring for details.
13075 @item Choose the converter
13077 @vindex org-odt-convert-process
13078 Select the newly added converter as the preferred one by customizing the
13079 option @code{org-odt-convert-process}.
13082 @node Working with OpenDocument style files
13083 @subsubheading Working with OpenDocument style files
13084 @cindex styles, custom
13085 @cindex template, custom
13087 This section explores the internals of the ODT exporter; the means by which
13088 it produces styled documents; the use of automatic and custom OpenDocument
13091 @anchor{x-factory-styles}
13092 @subsubheading a) Factory styles
13094 The ODT exporter relies on two files for generating its output.
13095 These files are bundled with the distribution under the directory pointed to
13096 by the variable @code{org-odt-styles-dir}. The two files are:
13099 @anchor{x-orgodtstyles-xml}
13101 @file{OrgOdtStyles.xml}
13103 This file contributes to the @file{styles.xml} file of the final @samp{ODT}
13104 document. This file gets modified for the following purposes:
13108 To control outline numbering based on user settings.
13111 To add styles generated by @file{htmlfontify.el} for fontification of code
13115 @anchor{x-orgodtcontenttemplate-xml}
13117 @file{OrgOdtContentTemplate.xml}
13119 This file contributes to the @file{content.xml} file of the final @samp{ODT}
13120 document. The contents of the Org outline are inserted between the
13121 @samp{<office:text>}@dots{}@samp{</office:text>} elements of this file.
13123 Apart from serving as a template file for the final @file{content.xml}, the
13124 file serves the following purposes:
13128 It contains automatic styles for formatting of tables which are referenced by
13132 It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
13133 elements that control numbering of tables, images, equations, and similar
13138 @anchor{x-overriding-factory-styles}
13139 @subsubheading b) Overriding factory styles
13140 The following two variables control the location from where the ODT exporter
13141 picks up the custom styles and content template files. Customize these
13142 variables to override the factory styles used by the exporter.
13145 @anchor{x-org-odt-styles-file}
13147 @code{org-odt-styles-file}
13149 The ODT export back-end uses the file pointed to by this variable, such as
13150 @file{styles.xml}, for the final output. It can take one of the following
13154 @item A @file{styles.xml} file
13156 Use this file instead of the default @file{styles.xml}
13158 @item A @file{.odt} or @file{.ott} file
13160 Use the @file{styles.xml} contained in the specified OpenDocument Text or
13163 @item A @file{.odt} or @file{.ott} file and a subset of files contained within them
13165 Use the @file{styles.xml} contained in the specified OpenDocument Text or
13166 Template file. Additionally extract the specified member files and embed
13167 those within the final @samp{ODT} document.
13169 Use this option if the @file{styles.xml} file references additional files
13170 like header and footer images.
13174 Use the default @file{styles.xml}
13177 @anchor{x-org-odt-content-template-file}
13179 @code{org-odt-content-template-file}
13181 Use this variable to specify the blank @file{content.xml} that will be used
13182 in the final output.
13185 @node Creating one-off styles
13186 @subsubheading Creating one-off styles
13188 The ODT export back-end can read embedded raw OpenDocument XML from the Org
13189 file. Such direct formatting are useful for one-off instances.
13192 @item Embedding ODT tags as part of regular text
13194 Enclose OpenDocument syntax in @samp{@@@@odt:...@@@@} for inline markup. For
13195 example, to highlight a region of text do the following:
13198 @@@@odt:<text:span text:style-name="Highlight">This is highlighted
13199 text</text:span>@@@@. But this is regular text.
13202 @strong{Hint:} To see the above example in action, edit the @file{styles.xml}
13203 (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a custom
13204 @samp{Highlight} style as shown below:
13207 <style:style style:name="Highlight" style:family="text">
13208 <style:text-properties fo:background-color="#ff0000"/>
13212 @item Embedding a one-line OpenDocument XML
13214 The ODT export back-end can read one-liner options with @code{#+ODT:}
13215 in the Org file. For example, to force a page break:
13218 #+ODT: <text:p text:style-name="PageBreak"/>
13221 @strong{Hint:} To see the above example in action, edit your
13222 @file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
13223 custom @samp{PageBreak} style as shown below.
13226 <style:style style:name="PageBreak" style:family="paragraph"
13227 style:parent-style-name="Text_20_body">
13228 <style:paragraph-properties fo:break-before="page"/>
13232 @item Embedding a block of OpenDocument XML
13234 The ODT export back-end can also read ODT export blocks for OpenDocument XML.
13235 Such blocks use the @code{#+BEGIN_EXPORT odt}@dots{}@code{#+END_EXPORT}
13238 For example, to create a one-off paragraph that uses bold text, do the
13243 <text:p text:style-name="Text_20_body_20_bold">
13244 This paragraph is specially formatted and uses bold text.
13251 @node Customizing tables in ODT export
13252 @subsubheading Customizing tables in ODT export
13253 @cindex tables, in ODT export
13256 Override the default table format by specifying a custom table style with the
13257 @code{#+ATTR_ODT} line. For a discussion on default formatting of tables
13258 @pxref{Tables in ODT export}.
13260 This feature closely mimics the way table templates are defined in the
13262 specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
13263 OpenDocument-v1.2 Specification}}
13265 @vindex org-odt-table-styles
13266 For quick preview of this feature, install the settings below and export the
13267 table that follows:
13270 (setq org-odt-table-styles
13271 (append org-odt-table-styles
13272 '(("TableWithHeaderRowAndColumn" "Custom"
13273 ((use-first-row-styles . t)
13274 (use-first-column-styles . t)))
13275 ("TableWithFirstRowandLastRow" "Custom"
13276 ((use-first-row-styles . t)
13277 (use-last-row-styles . t))))))
13281 #+ATTR_ODT: :style TableWithHeaderRowAndColumn
13282 | Name | Phone | Age |
13283 | Peter | 1234 | 17 |
13284 | Anna | 4321 | 25 |
13287 The example above used @samp{Custom} template and installed two table styles
13288 @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}.
13289 @strong{Important:} The OpenDocument styles needed for producing the above
13290 template were pre-defined. They are available in the section marked
13291 @samp{Custom Table Template} in @file{OrgOdtContentTemplate.xml}
13292 (@pxref{x-orgodtcontenttemplate-xml,,Factory styles}. For adding new
13293 templates, define new styles here.
13295 To use this feature proceed as follows:
13299 Create a table template@footnote{See the @code{<table:table-template>}
13300 element of the OpenDocument-v1.2 specification}
13302 A table template is set of @samp{table-cell} and @samp{paragraph} styles for
13303 each of the following table cell categories:
13317 The names for the above styles must be chosen based on the name of the table
13318 template using a well-defined convention.
13320 The naming convention is better illustrated with an example. For a table
13321 template with the name @samp{Custom}, the needed style names are listed in
13322 the following table.
13324 @multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph}
13325 @headitem Table cell type
13326 @tab @code{table-cell} style
13327 @tab @code{paragraph} style
13332 @tab @samp{CustomTableCell}
13333 @tab @samp{CustomTableParagraph}
13335 @tab @samp{CustomFirstColumnTableCell}
13336 @tab @samp{CustomFirstColumnTableParagraph}
13338 @tab @samp{CustomLastColumnTableCell}
13339 @tab @samp{CustomLastColumnTableParagraph}
13341 @tab @samp{CustomFirstRowTableCell}
13342 @tab @samp{CustomFirstRowTableParagraph}
13344 @tab @samp{CustomLastRowTableCell}
13345 @tab @samp{CustomLastRowTableParagraph}
13347 @tab @samp{CustomEvenRowTableCell}
13348 @tab @samp{CustomEvenRowTableParagraph}
13350 @tab @samp{CustomOddRowTableCell}
13351 @tab @samp{CustomOddRowTableParagraph}
13353 @tab @samp{CustomEvenColumnTableCell}
13354 @tab @samp{CustomEvenColumnTableParagraph}
13356 @tab @samp{CustomOddColumnTableCell}
13357 @tab @samp{CustomOddColumnTableParagraph}
13360 To create a table template with the name @samp{Custom}, define the above
13362 @code{<office:automatic-styles>}...@code{</office:automatic-styles>} element
13363 of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory
13367 Define a table style@footnote{See the attributes @code{table:template-name},
13368 @code{table:use-first-row-styles}, @code{table:use-last-row-styles},
13369 @code{table:use-first-column-styles}, @code{table:use-last-column-styles},
13370 @code{table:use-banding-rows-styles}, and
13371 @code{table:use-banding-column-styles} of the @code{<table:table>} element in
13372 the OpenDocument-v1.2 specification}
13374 @vindex org-odt-table-styles
13375 To define a table style, create an entry for the style in the variable
13376 @code{org-odt-table-styles} and specify the following:
13379 @item the name of the table template created in step (1)
13380 @item the set of cell styles in that template that are to be activated
13383 For example, the entry below defines two different table styles
13384 @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
13385 based on the same template @samp{Custom}. The styles achieve their intended
13386 effect by selectively activating the individual cell styles in that template.
13389 (setq org-odt-table-styles
13390 (append org-odt-table-styles
13391 '(("TableWithHeaderRowAndColumn" "Custom"
13392 ((use-first-row-styles . t)
13393 (use-first-column-styles . t)))
13394 ("TableWithFirstRowandLastRow" "Custom"
13395 ((use-first-row-styles . t)
13396 (use-last-row-styles . t))))))
13400 Associate a table with the table style
13402 To do this, specify the table style created in step (2) as part of
13403 the @code{ATTR_ODT} line as shown below.
13406 #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
13407 | Name | Phone | Age |
13408 | Peter | 1234 | 17 |
13409 | Anna | 4321 | 25 |
13413 @node Validating OpenDocument XML
13414 @subsubheading Validating OpenDocument XML
13416 Sometimes ODT format files may not open due to @file{.odt} file corruption.
13417 To verify if the @file{.odt} file is corrupt, validate it against the
13418 OpenDocument RELAX NG Compact Syntax---RNC---schema. But first the
13419 @file{.odt} files have to be decompressed using @samp{zip}. Note that
13420 @file{.odt} files are @samp{zip} archives: @inforef{File Archives,,emacs}.
13421 The contents of @file{.odt} files are in @file{.xml}. For general help with
13422 validation---and schema-sensitive editing---of XML files:
13423 @inforef{Introduction,,nxml-mode}.
13425 @vindex org-odt-schema-dir
13426 Customize @code{org-odt-schema-dir} to point to a directory with OpenDocument
13427 @file{.rnc} files and the needed schema-locating rules. The ODT export
13428 back-end takes care of updating the @code{rng-schema-locating-files}.
13430 @c end opendocument
13433 @section Org export
13436 @code{org} export back-end creates a normalized version of the Org document
13437 in current buffer. The exporter evaluates Babel code (@pxref{Evaluating code
13438 blocks}) and removes content specific to other back-ends.
13440 @subheading Org export commands
13443 @orgcmd{C-c C-e O o,org-org-export-to-org}
13444 Export as an Org file with a @file{.org} extension. For @file{myfile.org},
13445 Org exports to @file{myfile.org.org}, overwriting without warning.
13447 @orgcmd{C-c C-e O O,org-org-export-as-org}
13448 Export to a temporary buffer. Does not create a file.
13450 Export to an Org file, then open it.
13453 @node Texinfo export
13454 @section Texinfo export
13455 @cindex Texinfo export
13457 The @samp{texinfo} export back-end generates documents with Texinfo code that
13458 can compile to Info format.
13461 * Texinfo export commands:: Invoking commands.
13462 * Texinfo specific export settings:: Setting the environment.
13463 * Texinfo file header:: Generating the header.
13464 * Texinfo title and copyright page:: Creating preamble pages.
13465 * Texinfo @samp{Top} node:: Installing a manual in Info Top node.
13466 * Headings and sectioning structure:: Building document structure.
13467 * Indices:: Creating indices.
13468 * Quoting Texinfo code:: Incorporating literal Texinfo code.
13469 * Plain lists in Texinfo export:: List attributes.
13470 * Tables in Texinfo export:: Table attributes.
13471 * Images in Texinfo export:: Image attributes.
13472 * Special blocks in Texinfo export:: Special block attributes.
13473 * A Texinfo example:: Processing Org to Texinfo.
13476 @node Texinfo export commands
13477 @subsection Texinfo export commands
13479 @vindex org-texinfo-info-process
13481 @orgcmd{C-c C-e i t,org-texinfo-export-to-texinfo}
13482 Export as a Texinfo file with @file{.texi} extension. For @file{myfile.org},
13483 Org exports to @file{myfile.texi}, overwriting without warning.
13484 @orgcmd{C-c C-e i i,org-texinfo-export-to-info}
13485 Export to Texinfo format first and then process it to make an Info file. To
13486 generate other formats, such as DocBook, customize the
13487 @code{org-texinfo-info-process} variable.
13490 @node Texinfo specific export settings
13491 @subsection Texinfo specific export settings
13492 The Texinfo export back-end has several additional keywords for customizing
13493 Texinfo output. Setting these keywords works similar to the general options
13494 (@pxref{Export settings}).
13499 @cindex #+SUBTITLE (Texinfo)
13500 The document subtitle.
13503 @cindex #+SUBAUTHOR
13504 The document subauthor.
13506 @item TEXINFO_FILENAME
13507 @cindex #+TEXINFO_FILENAME
13508 The Texinfo filename.
13510 @item TEXINFO_CLASS
13511 @cindex #+TEXINFO_CLASS
13512 @vindex org-texinfo-default-class
13513 The default document class (@code{org-texinfo-default-class}), which must be
13514 a member of @code{org-texinfo-classes}.
13516 @item TEXINFO_HEADER
13517 @cindex #+TEXINFO_HEADER
13518 Arbitrary lines inserted at the end of the header.
13520 @item TEXINFO_POST_HEADER
13521 @cindex #+TEXINFO_POST_HEADER
13522 Arbitrary lines inserted after the end of the header.
13524 @item TEXINFO_DIR_CATEGORY
13525 @cindex #+TEXINFO_DIR_CATEGORY
13526 The directory category of the document.
13528 @item TEXINFO_DIR_TITLE
13529 @cindex #+TEXINFO_DIR_TITLE
13530 The directory title of the document.
13532 @item TEXINFO_DIR_DESC
13533 @cindex #+TEXINFO_DIR_DESC
13534 The directory description of the document.
13536 @item TEXINFO_PRINTED_TITLE
13537 @cindex #+TEXINFO_PRINTED_TITLE
13538 The printed title of the document.
13541 @node Texinfo file header
13542 @subsection Texinfo file header
13544 @cindex #+TEXINFO_FILENAME
13545 After creating the header for a Texinfo file, the Texinfo back-end
13546 automatically generates a name and destination path for the Info file. To
13547 override this default with a more sensible path and name, specify the
13548 @code{#+TEXINFO_FILENAME} keyword.
13550 @vindex org-texinfo-coding-system
13551 @vindex org-texinfo-classes
13552 @cindex #+TEXINFO_HEADER
13553 @cindex #+TEXINFO_CLASS
13554 Along with the output's file name, the Texinfo header also contains language
13555 details (@pxref{Export settings}) and encoding system as set in the
13556 @code{org-texinfo-coding-system} variable. Insert @code{#+TEXINFO_HEADER}
13557 keywords for each additional command in the header, for example:
13558 @@code@{@@synindex@}.
13560 Instead of repeatedly installing the same set of commands, define a class in
13561 @code{org-texinfo-classes} once, and then activate it in the document by
13562 setting the @code{#+TEXINFO_CLASS} keyword to that class.
13564 @node Texinfo title and copyright page
13565 @subsection Texinfo title and copyright page
13567 @cindex #+TEXINFO_PRINTED_TITLE
13568 The default template for hard copy output has a title page with
13569 @code{#+TITLE} and @code{#+AUTHOR} (@pxref{Export settings}). To replace the
13570 regular @code{#+TITLE} with something different for the printed version, use
13571 the @code{#+TEXINFO_PRINTED_TITLE} and @code{#+SUBTITLE} keywords. Both
13572 expect raw Texinfo code for setting their values.
13574 @cindex #+SUBAUTHOR
13575 If one @code{#+AUTHOR} is not sufficient, add multiple @code{#+SUBAUTHOR}
13576 keywords. They have to be set in raw Texinfo code.
13579 #+AUTHOR: Jane Smith
13580 #+SUBAUTHOR: John Doe
13581 #+TEXINFO_PRINTED_TITLE: This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@}
13584 @cindex property, COPYING
13585 Copying material is defined in a dedicated headline with a non-@code{nil}
13586 @code{:COPYING:} property. The back-end inserts the contents within a
13587 @code{@@copying} command at the beginning of the document. The heading
13588 itself does not appear in the structure of the document.
13590 Copyright information is printed on the back of the title page.
13598 This is a short example of a complete Texinfo file, version 1.0.
13600 Copyright \copy 2016 Free Software Foundation, Inc.
13603 @node Texinfo @samp{Top} node
13604 @subsection Texinfo @samp{Top} node
13606 @cindex #+TEXINFO_DIR_CATEGORY
13607 @cindex #+TEXINFO_DIR_TITLE
13608 @cindex #+TEXINFO_DIR_DESC
13609 The end result of the Texinfo export process is the creation of an Info file.
13610 This Info file's metadata has variables for category, title, and description:
13611 @code{#+TEXINFO_DIR_CATEGORY}, @code{#+TEXINFO_DIR_TITLE}, and
13612 @code{#+TEXINFO_DIR_DESC} that establish where in the Info hierarchy the file
13615 Here's an example that writes to the @samp{Top} node:
13618 #+TEXINFO_DIR_CATEGORY: Emacs
13619 #+TEXINFO_DIR_TITLE: Org Mode: (org)
13620 #+TEXINFO_DIR_DESC: Outline-based notes management and organizer
13623 @node Headings and sectioning structure
13624 @subsection Headings and sectioning structure
13626 @vindex org-texinfo-classes
13627 @vindex org-texinfo-default-class
13628 @cindex #+TEXINFO_CLASS
13629 The Texinfo export back-end uses a pre-defined scheme to convert Org
13630 headlines to an equivalent Texinfo structuring commands. A scheme like this
13631 maps top-level headlines to numbered chapters tagged as @code{@@chapter} and
13632 lower-level headlines to unnumbered chapters tagged as @code{@@unnumbered}.
13633 To override such mappings to introduce @code{@@part} or other Texinfo
13634 structuring commands, define a new class in @code{org-texinfo-classes}.
13635 Activate the new class with the @code{#+TEXINFO_CLASS} keyword. When no new
13636 class is defined and activated, the Texinfo export back-end defaults to the
13637 @code{org-texinfo-default-class}.
13639 If an Org headline's level has no associated Texinfo structuring command, or
13640 is below a certain threshold (@pxref{Export settings}), then the Texinfo
13641 export back-end makes it into a list item.
13643 @cindex property, APPENDIX
13644 The Texinfo export back-end makes any headline with a non-@code{nil}
13645 @code{:APPENDIX:} property into an appendix. This happens independent of the
13646 Org headline level or the @code{#+TEXINFO_CLASS}.
13648 @cindex property, DESCRIPTION
13649 The Texinfo export back-end creates a menu entry after the Org headline for
13650 each regular sectioning structure. To override this with a shorter menu
13651 entry, use the @code{:ALT_TITLE:} property (@pxref{Table of contents}).
13652 Texinfo menu entries also have an option for a longer @code{:DESCRIPTION:}
13653 property. Here's an example that uses both to override the default menu
13657 * Controlling Screen Display
13659 :ALT_TITLE: Display
13660 :DESCRIPTION: Controlling Screen Display
13665 @subsection Indices
13668 @cindex concept index, in Texinfo export
13669 @cindex Texinfo export, index, concept
13671 @cindex function index, in Texinfo export
13672 @cindex Texinfo export, index, function
13674 @cindex keystroke index, in Texinfo export
13675 @cindex Texinfo export, keystroke index
13677 @cindex program index, in Texinfo export
13678 @cindex Texinfo export, program index
13680 @cindex data type index, in Texinfo export
13681 @cindex Texinfo export, data type index
13683 @cindex variable index, in Texinfo export
13684 @cindex Texinfo export, variable index
13685 The Texinfo export back-end recognizes these indexing keywords if used in the
13686 Org file: @code{#+CINDEX}, @code{#+FINDEX}, @code{#+KINDEX}, @code{#+PINDEX},
13687 @code{#+TINDEX}, and @code{#+VINDEX}. Write their value as verbatim Texinfo
13688 code; in particular, @samp{@{}, @samp{@}} and @samp{@@} characters need to be
13689 escaped with @samp{@@} if they not belong to a Texinfo command.
13692 #+CINDEX: Defining indexing entries
13695 @cindex property, INDEX
13696 For the back-end to generate an index entry for a headline, set the
13697 @code{:INDEX:} property to @samp{cp} or @samp{vr}. These abbreviations come
13698 from Texinfo that stand for concept index and variable index. The Texinfo
13699 manual has abbreviations for all other kinds of indexes. The back-end
13700 exports the headline as an unnumbered chapter or section command, and then
13701 inserts the index after its contents.
13710 @node Quoting Texinfo code
13711 @subsection Quoting Texinfo code
13713 Use any of the following three methods to insert or escape raw Texinfo code:
13716 @cindex #+BEGIN_EXPORT texinfo
13718 Richard @@@@texinfo:@@sc@{@@@@Stallman@@@@texinfo:@}@@@@ commence' GNU.
13720 #+TEXINFO: @@need800
13721 This paragraph is preceded by...
13723 #+BEGIN_EXPORT texinfo
13724 @@auindex Johnson, Mark
13725 @@auindex Lakoff, George
13729 @node Plain lists in Texinfo export
13730 @subsection Plain lists in Texinfo export
13731 @cindex #+ATTR_TEXINFO, in plain lists
13732 The Texinfo export back-end by default converts description lists in the Org
13733 file using the default command @code{@@table}, which results in a table with
13734 two columns. To change this behavior, specify @code{:table-type} with
13735 @code{@@ftable} or @code{@@vtable} attributes. For more information,
13736 @inforef{Two-column Tables,,texinfo}.
13738 @vindex org-texinfo-def-table-markup
13739 The Texinfo export back-end by default also applies a text highlight based on
13740 the defaults stored in @code{org-texinfo-def-table-markup}. To override the
13741 default highlight command, specify another one with the @code{:indic}
13742 attribute as shown in this example:
13745 #+ATTR_TEXINFO: :indic @@asis
13746 - foo :: This is the text for /foo/, with no highlighting.
13749 @node Tables in Texinfo export
13750 @subsection Tables in Texinfo export
13751 @cindex #+ATTR_TEXINFO, in tables
13753 When exporting tables, the Texinfo export back-end uses the widest cell width
13754 in each column. To override this and instead specify as fractions of line
13755 length, use the @code{:columns} attribute. See example below.
13758 #+ATTR_TEXINFO: :columns .5 .5
13759 | a cell | another cell |
13762 @node Images in Texinfo export
13763 @subsection Images in Texinfo export
13764 @cindex #+ATTR_TEXINFO, in images
13766 Insert a file link to the image in the Org file, and the Texinfo export
13767 back-end inserts the image. These links must have the usual supported image
13768 extensions and no descriptions. To scale the image, use @code{:width} and
13769 @code{:height} attributes. For alternate text, use @code{:alt} and specify
13770 the text using Texinfo code, as shown in the example:
13773 #+ATTR_TEXINFO: :width 1in :alt Alternate @@i@{text@}
13777 @node Special blocks in Texinfo export
13778 @subsection Special blocks
13779 @cindex #+ATTR_TEXINFO, in special blocks
13781 The Texinfo export back-end converts special blocks to commands with the same
13782 name. It also adds any @code{:options} attributes to the end of the command,
13783 as shown in this example:
13786 #+ATTR_TEXINFO: :options org-org-export-to-org ...
13788 A somewhat obsessive function.
13796 @@defun org-org-export-to-org ...
13797 A somewhat obsessive function.
13801 @node A Texinfo example
13802 @subsection A Texinfo example
13804 Here is a more detailed example Org file. @inforef{GNU Sample
13805 Texts,,texinfo} for an equivalent example using Texinfo code.
13808 #+MACRO: version 2.0
13809 #+MACRO: updated last updated 4 March 2014
13811 #+OPTIONS: ':t toc:t author:t email:t
13812 #+TITLE: GNU Sample @{@{@{version@}@}@}
13813 #+AUTHOR: A.U. Thor
13814 #+EMAIL: bug-sample@@gnu.org
13817 #+TEXINFO_FILENAME: sample.info
13818 #+TEXINFO_HEADER: @@syncodeindex pg cp
13820 #+TEXINFO_DIR_CATEGORY: Texinfo documentation system
13821 #+TEXINFO_DIR_TITLE: sample: (sample)
13822 #+TEXINFO_DIR_DESC: Invoking sample
13824 #+TEXINFO_PRINTED_TITLE: GNU Sample
13825 #+SUBTITLE: for version @{@{@{version@}@}@}, @{@{@{updated@}@}@}
13832 This manual is for GNU Sample (version @{@{@{version@}@}@},
13833 @{@{@{updated@}@}@}), which is an example in the Texinfo documentation.
13835 Copyright @@@@texinfo:@@copyright@{@}@@@@ 2013 Free Software Foundation,
13839 Permission is granted to copy, distribute and/or modify this
13840 document under the terms of the GNU Free Documentation License,
13841 Version 1.3 or any later version published by the Free Software
13842 Foundation; with no Invariant Sections, with no Front-Cover Texts,
13843 and with no Back-Cover Texts. A copy of the license is included in
13844 the section entitled "GNU Free Documentation License".
13850 #+CINDEX: invoking @@command@{sample@}
13852 This is a sample manual. There is no sample program to invoke, but
13853 if there were, you could see its basic usage and command line
13856 * GNU Free Documentation License
13861 #+TEXINFO: @@include fdl.texi
13869 @node iCalendar export
13870 @section iCalendar export
13871 @cindex iCalendar export
13873 @vindex org-icalendar-include-todo
13874 @vindex org-icalendar-use-deadline
13875 @vindex org-icalendar-use-scheduled
13876 @vindex org-icalendar-categories
13877 @vindex org-icalendar-alarm-time
13878 A large part of Org mode's inter-operability success is its ability to easily
13879 export to or import from external applications. The iCalendar export
13880 back-end takes calendar data from Org files and exports to the standard
13883 The iCalendar export back-end can also incorporate TODO entries based on the
13884 configuration of the @code{org-icalendar-include-todo} variable. The
13885 back-end exports plain timestamps as VEVENT, TODO items as VTODO, and also
13886 create events from deadlines that are in non-TODO items. The back-end uses
13887 the deadlines and scheduling dates in Org TODO items for setting the start
13888 and due dates for the iCalendar TODO entry. Consult the
13889 @code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}
13890 variables for more details.
13892 For tags on the headline, the iCalendar export back-end makes them into
13893 iCalendar categories. To tweak the inheritance of tags and TODO states,
13894 configure the variable @code{org-icalendar-categories}. To assign clock
13895 alarms based on time, configure the @code{org-icalendar-alarm-time} variable.
13897 @vindex org-icalendar-store-UID
13898 @cindex property, ID
13899 The iCalendar format standard requires globally unique identifier---UID---for
13900 each entry. The iCalendar export back-end creates UIDs during export. To
13901 save a copy of the UID in the Org file set the variable
13902 @code{org-icalendar-store-UID}. The back-end looks for the @code{:ID:}
13903 property of the entry for re-using the same UID for subsequent exports.
13905 Since a single Org entry can result in multiple iCalendar entries---as
13906 timestamp, deadline, scheduled item, or TODO item---Org adds prefixes to the
13907 UID, depending on which part of the Org entry triggered the creation of the
13908 iCalendar entry. Prefixing ensures UIDs remains unique, yet enable
13909 synchronization programs trace the connections.
13912 @orgcmd{C-c C-e c f,org-icalendar-export-to-ics}
13913 Create iCalendar entries from the current Org buffer and store them in the
13914 same directory, using a file extension @file{.ics}.
13915 @orgcmd{C-c C-e c a, org-icalendar-export-agenda-files}
13916 @vindex org-agenda-files
13917 Create iCalendar entries from Org files in @code{org-agenda-files} and store
13918 in a separate iCalendar file for each Org file.
13919 @orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files}
13920 @vindex org-icalendar-combined-agenda-file
13921 Create a combined iCalendar file from Org files in @code{org-agenda-files}
13922 and write it to @code{org-icalendar-combined-agenda-file} file name.
13925 @vindex org-use-property-inheritance
13926 @vindex org-icalendar-include-body
13927 @cindex property, SUMMARY
13928 @cindex property, DESCRIPTION
13929 @cindex property, LOCATION
13930 The iCalendar export back-end includes SUMMARY, DESCRIPTION and LOCATION
13931 properties from the Org entries when exporting. To force the back-end to
13932 inherit the LOCATION property, configure the
13933 @code{org-use-property-inheritance} variable.
13935 When Org entries do not have SUMMARY, DESCRIPTION and LOCATION properties,
13936 the iCalendar export back-end derives the summary from the headline, and
13937 derives the description from the body of the Org item. The
13938 @code{org-icalendar-include-body} variable limits the maximum number of
13939 characters of the content are turned into its description.
13941 Exporting to iCalendar format depends in large part on the capabilities of
13942 the destination application. Some are more lenient than others. Consult the
13943 Org mode FAQ for advice on specific applications.
13945 @node Other built-in back-ends
13946 @section Other built-in back-ends
13947 @cindex export back-ends, built-in
13948 @vindex org-export-backends
13950 Other export back-ends included with Org are:
13953 @item @file{ox-man.el}: export to a man page.
13956 To activate such back-ends, either customize @code{org-export-backends} or
13957 load directly with @code{(require 'ox-man)}. On successful load, the
13958 back-end adds new keys in the export dispatcher (@pxref{The export
13961 Follow the comment section of such files, for example, @file{ox-man.el}, for
13962 usage and configuration details.
13964 @node Advanced configuration
13965 @section Advanced configuration
13969 @vindex org-export-before-processing-hook
13970 @vindex org-export-before-parsing-hook
13971 The export process executes two hooks before the actual exporting begins.
13972 The first hook, @code{org-export-before-processing-hook}, runs before any
13973 expansions of macros, Babel code, and include keywords in the buffer. The
13974 second hook, @code{org-export-before-parsing-hook}, runs before the buffer is
13975 parsed. Both hooks are specified as functions, see example below. Their main
13976 use is for heavy duty structural modifications of the Org content. For
13977 example, removing every headline in the buffer during export:
13981 (defun my-headline-removal (backend)
13982 "Remove all headlines in the current buffer.
13983 BACKEND is the export back-end being used, as a symbol."
13985 (lambda () (delete-region (point) (progn (forward-line) (point))))))
13987 (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
13991 Note that the hook function must have a mandatory argument that is a symbol
13994 @subheading Filters
13996 @cindex Filters, exporting
13997 The Org export process relies on filters to process specific parts of
13998 conversion process. Filters are just lists of functions to be applied to
13999 certain parts for a given back-end. The output from the first function in
14000 the filter is passed on to the next function in the filter. The final output
14001 is the output from the final function in the filter.
14003 The Org export process has many filter sets applicable to different types of
14004 objects, plain text, parse trees, export options, and final output formats.
14005 The filters are named after the element type or object type:
14006 @code{org-export-filter-TYPE-functions}, where @code{TYPE} is the type
14007 targeted by the filter. Valid types are:
14009 @multitable @columnfractions .33 .33 .33
14022 @item export-snippet
14025 @item footnote-definition
14026 @tab footnote-reference
14028 @item horizontal-rule
14029 @tab inline-babel-call
14030 @tab inline-src-block
14035 @tab latex-environment
14036 @tab latex-fragment
14046 @item property-drawer
14052 @item statistics-cookie
14053 @tab strike-through
14066 Here is an example filter that replaces non-breaking spaces @code{~} in the
14067 Org buffer with @code{_} for the @LaTeX{} back-end.
14071 (defun my-latex-filter-nobreaks (text backend info)
14072 "Ensure \"_\" are properly handled in LaTeX export."
14073 (when (org-export-derived-backend-p backend 'latex)
14074 (replace-regexp-in-string "_" "~" text)))
14076 (add-to-list 'org-export-filter-plain-text-functions
14077 'my-latex-filter-nobreaks)
14081 A filter requires three arguments: the code to be transformed, the name of
14082 the back-end, and some optional information about the export process. The
14083 third argument can be safely ignored. Note the use of
14084 @code{org-export-derived-backend-p} predicate that tests for @code{latex}
14085 back-end or any other back-end, such as @code{beamer}, derived from
14088 @subheading Defining filters for individual files
14090 The Org export can filter not just for back-ends, but also for specific files
14091 through the @code{#+BIND} keyword. Here is an example with two filters; one
14092 removes brackets from time stamps, and the other removes strike-through text.
14093 The filter functions are defined in a @samp{src} code block in the same Org
14094 file, which is a handy location for debugging.
14097 #+BIND: org-export-filter-timestamp-functions (tmp-f-timestamp)
14098 #+BIND: org-export-filter-strike-through-functions (tmp-f-strike-through)
14099 #+begin_src emacs-lisp :exports results :results none
14100 (defun tmp-f-timestamp (s backend info)
14101 (replace-regexp-in-string "&[lg]t;\\|[][]" "" s))
14102 (defun tmp-f-strike-through (s backend info) "")
14106 @subheading Extending an existing back-end
14108 Some parts of the conversion process can be extended for certain elements so
14109 as to introduce a new or revised translation. That is how the HTML export
14110 back-end was extended to handle Markdown format. The extensions work
14111 seamlessly so any aspect of filtering not done by the extended back-end is
14112 handled by the original back-end. Of all the export customization in Org,
14113 extending is very powerful as it operates at the parser level.
14115 For this example, make the @code{ascii} back-end display the language used in
14116 a source code block. Also make it display only when some attribute is
14117 non-@code{nil}, like the following:
14120 #+ATTR_ASCII: :language t
14123 Then extend @code{ascii} back-end with a custom @code{my-ascii} back-end.
14127 (defun my-ascii-src-block (src-block contents info)
14128 "Transcode a SRC-BLOCK element from Org to ASCII.
14129 CONTENTS is nil. INFO is a plist used as a communication
14131 (if (not (org-export-read-attribute :attr_ascii src-block :language))
14132 (org-export-with-backend 'ascii src-block contents info)
14134 (format ",--[ %s ]--\n%s`----"
14135 (org-element-property :language src-block)
14136 (replace-regexp-in-string
14138 (org-element-normalize-string
14139 (org-export-format-code-default src-block info)))))))
14141 (org-export-define-derived-backend 'my-ascii 'ascii
14142 :translate-alist '((src-block . my-ascii-src-block)))
14146 The @code{my-ascii-src-block} function looks at the attribute above the
14147 current element. If not true, hands over to @code{ascii} back-end. If true,
14148 which it is in this example, it creates a box around the code and leaves room
14149 for the inserting a string for language. The last form creates the new
14150 back-end that springs to action only when translating @code{src-block} type
14153 To use the newly defined back-end, call the following from an Org buffer:
14156 (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
14159 Further steps to consider would be an interactive function, self-installing
14160 an item in the export dispatcher menu, and other user-friendly improvements.
14162 @node Export in foreign buffers
14163 @section Export in foreign buffers
14165 The export back-ends in Org often include commands to convert selected
14166 regions. A convenient feature of this in-place conversion is that the
14167 exported output replaces the original source. Here are such functions:
14170 @item org-html-convert-region-to-html
14171 Convert the selected region into HTML.
14172 @item org-latex-convert-region-to-latex
14173 Convert the selected region into @LaTeX{}.
14174 @item org-texinfo-convert-region-to-texinfo
14175 Convert the selected region into @code{Texinfo}.
14176 @item org-md-convert-region-to-md
14177 Convert the selected region into @code{MarkDown}.
14180 In-place conversions are particularly handy for quick conversion of tables
14181 and lists in foreign buffers. For example, turn on the minor mode @code{M-x
14182 orgstruct-mode} in an HTML buffer, then use the convenient Org keyboard
14183 commands to create a list, select it, and covert it to HTML with @code{M-x
14184 org-html-convert-region-to-html RET}.
14188 @chapter Publishing
14191 Org includes a publishing management system that allows you to configure
14192 automatic HTML conversion of @emph{projects} composed of interlinked org
14193 files. You can also configure Org to automatically upload your exported HTML
14194 pages and related attachments, such as images and source code files, to a web
14197 You can also use Org to convert files into PDF, or even combine HTML and PDF
14198 conversion so that files are available in both formats on the server.
14200 Publishing has been contributed to Org by David O'Toole.
14203 * Configuration:: Defining projects
14204 * Uploading files:: How to get files up on the server
14205 * Sample configuration:: Example projects
14206 * Triggering publication:: Publication commands
14209 @node Configuration
14210 @section Configuration
14212 Publishing needs significant configuration to specify files, destination
14213 and many other properties of a project.
14216 * Project alist:: The central configuration variable
14217 * Sources and destinations:: From here to there
14218 * Selecting files:: What files are part of the project?
14219 * Publishing action:: Setting the function doing the publishing
14220 * Publishing options:: Tweaking HTML/@LaTeX{} export
14221 * Publishing links:: Which links keep working after publishing?
14222 * Sitemap:: Generating a list of all pages
14223 * Generating an index:: An index that reaches across pages
14226 @node Project alist
14227 @subsection The variable @code{org-publish-project-alist}
14228 @cindex org-publish-project-alist
14229 @cindex projects, for publishing
14231 @vindex org-publish-project-alist
14232 Publishing is configured almost entirely through setting the value of one
14233 variable, called @code{org-publish-project-alist}. Each element of the list
14234 configures one project, and may be in one of the two following forms:
14237 ("project-name" :property value :property value ...)
14238 @r{i.e., a well-formed property list with alternating keys and values}
14240 ("project-name" :components ("project-name" "project-name" ...))
14244 In both cases, projects are configured by specifying property values. A
14245 project defines the set of files that will be published, as well as the
14246 publishing configuration to use when publishing those files. When a project
14247 takes the second form listed above, the individual members of the
14248 @code{:components} property are taken to be sub-projects, which group
14249 together files requiring different publishing options. When you publish such
14250 a ``meta-project'', all the components will also be published, in the
14253 @node Sources and destinations
14254 @subsection Sources and destinations for files
14255 @cindex directories, for publishing
14257 Most properties are optional, but some should always be set. In
14258 particular, Org needs to know where to look for source files,
14259 and where to put published files.
14261 @multitable @columnfractions 0.3 0.7
14262 @item @code{:base-directory}
14263 @tab Directory containing publishing source files
14264 @item @code{:publishing-directory}
14265 @tab Directory where output files will be published. You can directly
14266 publish to a web server using a file name syntax appropriate for
14267 the Emacs @file{tramp} package. Or you can publish to a local directory and
14268 use external tools to upload your website (@pxref{Uploading files}).
14269 @item @code{:preparation-function}
14270 @tab Function or list of functions to be called before starting the
14271 publishing process, for example, to run @code{make} for updating files to be
14272 published. Each preparation function is called with a single argument, the
14273 project property list.
14274 @item @code{:completion-function}
14275 @tab Function or list of functions called after finishing the publishing
14276 process, for example, to change permissions of the resulting files. Each
14277 completion function is called with a single argument, the project property
14282 @node Selecting files
14283 @subsection Selecting files
14284 @cindex files, selecting for publishing
14286 By default, all files with extension @file{.org} in the base directory
14287 are considered part of the project. This can be modified by setting the
14289 @multitable @columnfractions 0.25 0.75
14290 @item @code{:base-extension}
14291 @tab Extension (without the dot!) of source files. This actually is a
14292 regular expression. Set this to the symbol @code{any} if you want to get all
14293 files in @code{:base-directory}, even without extension.
14295 @item @code{:exclude}
14296 @tab Regular expression to match file names that should not be
14297 published, even though they have been selected on the basis of their
14300 @item @code{:include}
14301 @tab List of files to be included regardless of @code{:base-extension}
14302 and @code{:exclude}.
14304 @item @code{:recursive}
14305 @tab non-@code{nil} means, check base-directory recursively for files to publish.
14308 @node Publishing action
14309 @subsection Publishing action
14310 @cindex action, for publishing
14312 Publishing means that a file is copied to the destination directory and
14313 possibly transformed in the process. The default transformation is to export
14314 Org files as HTML files, and this is done by the function
14315 @code{org-html-publish-to-html}, which calls the HTML exporter (@pxref{HTML
14316 export}). But you also can publish your content as PDF files using
14317 @code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc.,
14318 using the corresponding functions.
14320 If you want to publish the Org file as an @code{.org} file but with the
14321 @i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the
14322 function @code{org-org-publish-to-org}. This will produce @file{file.org}
14323 and put it in the publishing directory. If you want a htmlized version of
14324 this file, set the parameter @code{:htmlized-source} to @code{t}, it will
14325 produce @file{file.org.html} in the publishing directory@footnote{If the
14326 publishing directory is the same than the source directory, @file{file.org}
14327 will be exported as @file{file.org.org}, so probably don't want to do this.}.
14329 Other files like images only need to be copied to the publishing destination.
14330 For this you can use @code{org-publish-attachment}. For non-org files, you
14331 always need to specify the publishing function:
14333 @multitable @columnfractions 0.3 0.7
14334 @item @code{:publishing-function}
14335 @tab Function executing the publication of a file. This may also be a
14336 list of functions, which will all be called in turn.
14337 @item @code{:htmlized-source}
14338 @tab non-@code{nil} means, publish htmlized source.
14341 The function must accept three arguments: a property list containing at least
14342 a @code{:publishing-directory} property, the name of the file to be published
14343 and the path to the publishing directory of the output file. It should take
14344 the specified file, make the necessary transformation (if any) and place the
14345 result into the destination folder.
14347 @node Publishing options
14348 @subsection Options for the exporters
14349 @cindex options, for publishing
14351 The property list can be used to set export options during the publishing
14352 process. In most cases, these properties correspond to user variables in
14353 Org. While some properties are available for all export back-ends, most of
14354 them are back-end specific. The following sections list properties along
14355 with the variable they belong to. See the documentation string of these
14356 options for details.
14358 @vindex org-publish-project-alist
14359 When a property is given a value in @code{org-publish-project-alist}, its
14360 setting overrides the value of the corresponding user variable (if any)
14361 during publishing. Options set within a file (@pxref{Export settings}),
14362 however, override everything.
14364 @subsubheading Generic properties
14366 @multitable {@code{:with-sub-superscript}} {@code{org-export-with-sub-superscripts}}
14367 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
14368 @item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
14369 @item @code{:headline-levels} @tab @code{org-export-headline-levels}
14370 @item @code{:language} @tab @code{org-export-default-language}
14371 @item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}
14372 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
14373 @item @code{:select-tags} @tab @code{org-export-select-tags}
14374 @item @code{:with-author} @tab @code{org-export-with-author}
14375 @item @code{:with-broken-links} @tab @code{org-export-with-broken-links}
14376 @item @code{:with-clocks} @tab @code{org-export-with-clocks}
14377 @item @code{:with-creator} @tab @code{org-export-with-creator}
14378 @item @code{:with-date} @tab @code{org-export-with-date}
14379 @item @code{:with-drawers} @tab @code{org-export-with-drawers}
14380 @item @code{:with-email} @tab @code{org-export-with-email}
14381 @item @code{:with-emphasize} @tab @code{org-export-with-emphasize}
14382 @item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width}
14383 @item @code{:with-footnotes} @tab @code{org-export-with-footnotes}
14384 @item @code{:with-latex} @tab @code{org-export-with-latex}
14385 @item @code{:with-planning} @tab @code{org-export-with-planning}
14386 @item @code{:with-priority} @tab @code{org-export-with-priority}
14387 @item @code{:with-properties} @tab @code{org-export-with-properties}
14388 @item @code{:with-special-strings} @tab @code{org-export-with-special-strings}
14389 @item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts}
14390 @item @code{:with-tables} @tab @code{org-export-with-tables}
14391 @item @code{:with-tags} @tab @code{org-export-with-tags}
14392 @item @code{:with-tasks} @tab @code{org-export-with-tasks}
14393 @item @code{:with-timestamps} @tab @code{org-export-with-timestamps}
14394 @item @code{:with-title} @tab @code{org-export-with-title}
14395 @item @code{:with-toc} @tab @code{org-export-with-toc}
14396 @item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords}
14399 @subsubheading ASCII specific properties
14401 @multitable {@code{:ascii-table-keep-all-vertical-lines}} {@code{org-ascii-table-keep-all-vertical-lines}}
14402 @item @code{:ascii-bullets} @tab @code{org-ascii-bullets}
14403 @item @code{:ascii-caption-above} @tab @code{org-ascii-caption-above}
14404 @item @code{:ascii-charset} @tab @code{org-ascii-charset}
14405 @item @code{:ascii-global-margin} @tab @code{org-ascii-global-margin}
14406 @item @code{:ascii-format-drawer-function} @tab @code{org-ascii-format-drawer-function}
14407 @item @code{:ascii-format-inlinetask-function} @tab @code{org-ascii-format-inlinetask-function}
14408 @item @code{:ascii-headline-spacing} @tab @code{org-ascii-headline-spacing}
14409 @item @code{:ascii-indented-line-width} @tab @code{org-ascii-indented-line-width}
14410 @item @code{:ascii-inlinetask-width} @tab @code{org-ascii-inlinetask-width}
14411 @item @code{:ascii-inner-margin} @tab @code{org-ascii-inner-margin}
14412 @item @code{:ascii-links-to-notes} @tab @code{org-ascii-links-to-notes}
14413 @item @code{:ascii-list-margin} @tab @code{org-ascii-list-margin}
14414 @item @code{:ascii-paragraph-spacing} @tab @code{org-ascii-paragraph-spacing}
14415 @item @code{:ascii-quote-margin} @tab @code{org-ascii-quote-margin}
14416 @item @code{:ascii-table-keep-all-vertical-lines} @tab @code{org-ascii-table-keep-all-vertical-lines}
14417 @item @code{:ascii-table-use-ascii-art} @tab @code{org-ascii-table-use-ascii-art}
14418 @item @code{:ascii-table-widen-columns} @tab @code{org-ascii-table-widen-columns}
14419 @item @code{:ascii-text-width} @tab @code{org-ascii-text-width}
14420 @item @code{:ascii-underline} @tab @code{org-ascii-underline}
14421 @item @code{:ascii-verbatim-format} @tab @code{org-ascii-verbatim-format}
14424 @subsubheading Beamer specific properties
14426 @multitable {@code{:beamer-frame-default-options}} {@code{org-beamer-frame-default-options}}
14427 @item @code{:beamer-theme} @tab @code{org-beamer-theme}
14428 @item @code{:beamer-column-view-format} @tab @code{org-beamer-column-view-format}
14429 @item @code{:beamer-environments-extra} @tab @code{org-beamer-environments-extra}
14430 @item @code{:beamer-frame-default-options} @tab @code{org-beamer-frame-default-options}
14431 @item @code{:beamer-outline-frame-options} @tab @code{org-beamer-outline-frame-options}
14432 @item @code{:beamer-outline-frame-title} @tab @code{org-beamer-outline-frame-title}
14433 @item @code{:beamer-subtitle-format} @tab @code{org-beamer-subtitle-format}
14436 @subsubheading HTML specific properties
14438 @multitable {@code{:html-table-use-header-tags-for-first-column}} {@code{org-html-table-use-header-tags-for-first-column}}
14439 @item @code{:html-allow-name-attribute-in-anchors} @tab @code{org-html-allow-name-attribute-in-anchors}
14440 @item @code{:html-checkbox-type} @tab @code{org-html-checkbox-type}
14441 @item @code{:html-container} @tab @code{org-html-container-element}
14442 @item @code{:html-divs} @tab @code{org-html-divs}
14443 @item @code{:html-doctype} @tab @code{org-html-doctype}
14444 @item @code{:html-extension} @tab @code{org-html-extension}
14445 @item @code{:html-footnote-format} @tab @code{org-html-footnote-format}
14446 @item @code{:html-footnote-separator} @tab @code{org-html-footnote-separator}
14447 @item @code{:html-footnotes-section} @tab @code{org-html-footnotes-section}
14448 @item @code{:html-format-drawer-function} @tab @code{org-html-format-drawer-function}
14449 @item @code{:html-format-headline-function} @tab @code{org-html-format-headline-function}
14450 @item @code{:html-format-inlinetask-function} @tab @code{org-html-format-inlinetask-function}
14451 @item @code{:html-head-extra} @tab @code{org-html-head-extra}
14452 @item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style}
14453 @item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts}
14454 @item @code{:html-head} @tab @code{org-html-head}
14455 @item @code{:html-home/up-format} @tab @code{org-html-home/up-format}
14456 @item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy}
14457 @item @code{:html-indent} @tab @code{org-html-indent}
14458 @item @code{:html-infojs-options} @tab @code{org-html-infojs-options}
14459 @item @code{:html-infojs-template} @tab @code{org-html-infojs-template}
14460 @item @code{:html-inline-image-rules} @tab @code{org-html-inline-image-rules}
14461 @item @code{:html-inline-images} @tab @code{org-html-inline-images}
14462 @item @code{:html-link-home} @tab @code{org-html-link-home}
14463 @item @code{:html-link-org-files-as-html} @tab @code{org-html-link-org-files-as-html}
14464 @item @code{:html-link-up} @tab @code{org-html-link-up}
14465 @item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url}
14466 @item @code{:html-mathjax-options} @tab @code{org-html-mathjax-options}
14467 @item @code{:html-mathjax-template} @tab @code{org-html-mathjax-template}
14468 @item @code{:html-metadata-timestamp-format} @tab @code{org-html-metadata-timestamp-format}
14469 @item @code{:html-postamble-format} @tab @code{org-html-postamble-format}
14470 @item @code{:html-postamble} @tab @code{org-html-postamble}
14471 @item @code{:html-preamble-format} @tab @code{org-html-preamble-format}
14472 @item @code{:html-preamble} @tab @code{org-html-preamble}
14473 @item @code{:html-table-align-individual-fields} @tab @code{org-html-table-align-individual-fields}
14474 @item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
14475 @item @code{:html-table-caption-above} @tab @code{org-html-table-caption-above}
14476 @item @code{:html-table-data-tags} @tab @code{org-html-table-data-tags}
14477 @item @code{:html-table-header-tags} @tab @code{org-html-table-header-tags}
14478 @item @code{:html-table-row-tags} @tab @code{org-html-table-row-tags}
14479 @item @code{:html-table-use-header-tags-for-first-column} @tab @code{org-html-table-use-header-tags-for-first-column}
14480 @item @code{:html-tag-class-prefix} @tab @code{org-html-tag-class-prefix}
14481 @item @code{:html-text-markup-alist} @tab @code{org-html-text-markup-alist}
14482 @item @code{:html-todo-kwd-class-prefix} @tab @code{org-html-todo-kwd-class-prefix}
14483 @item @code{:html-toplevel-hlevel} @tab @code{org-html-toplevel-hlevel}
14484 @item @code{:html-use-infojs} @tab @code{org-html-use-infojs}
14485 @item @code{:html-validation-link} @tab @code{org-html-validation-link}
14486 @item @code{:html-viewport} @tab @code{org-html-viewport}
14487 @item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration}
14490 @subsubheading @LaTeX{} specific properties
14492 @multitable {@code{:latex-link-with-unknown-path-format}} {@code{org-latex-link-with-unknown-path-format}}
14493 @item @code{:latex-active-timestamp-format} @tab @code{org-latex-active-timestamp-format}
14494 @item @code{:latex-caption-above} @tab @code{org-latex-caption-above}
14495 @item @code{:latex-classes} @tab @code{org-latex-classes}
14496 @item @code{:latex-class} @tab @code{org-latex-default-class}
14497 @item @code{:latex-compiler} @tab @code{org-latex-compiler}
14498 @item @code{:latex-default-figure-position} @tab @code{org-latex-default-figure-position}
14499 @item @code{:latex-default-table-environment} @tab @code{org-latex-default-table-environment}
14500 @item @code{:latex-default-table-mode} @tab @code{org-latex-default-table-mode}
14501 @item @code{:latex-diary-timestamp-format} @tab @code{org-latex-diary-timestamp-format}
14502 @item @code{:latex-footnote-defined-format} @tab @code{org-latex-footnote-defined-format}
14503 @item @code{:latex-footnote-separator} @tab @code{org-latex-footnote-separator}
14504 @item @code{:latex-format-drawer-function} @tab @code{org-latex-format-drawer-function}
14505 @item @code{:latex-format-headline-function} @tab @code{org-latex-format-headline-function}
14506 @item @code{:latex-format-inlinetask-function} @tab @code{org-latex-format-inlinetask-function}
14507 @item @code{:latex-hyperref-template} @tab @code{org-latex-hyperref-template}
14508 @item @code{:latex-image-default-height} @tab @code{org-latex-image-default-height}
14509 @item @code{:latex-image-default-option} @tab @code{org-latex-image-default-option}
14510 @item @code{:latex-image-default-width} @tab @code{org-latex-image-default-width}
14511 @item @code{:latex-images-centered} @tab @code{org-latex-images-centered}
14512 @item @code{:latex-inactive-timestamp-format} @tab @code{org-latex-inactive-timestamp-format}
14513 @item @code{:latex-inline-image-rules} @tab @code{org-latex-inline-image-rules}
14514 @item @code{:latex-link-with-unknown-path-format} @tab @code{org-latex-link-with-unknown-path-format}
14515 @item @code{:latex-listings-langs} @tab @code{org-latex-listings-langs}
14516 @item @code{:latex-listings-options} @tab @code{org-latex-listings-options}
14517 @item @code{:latex-listings} @tab @code{org-latex-listings}
14518 @item @code{:latex-minted-langs} @tab @code{org-latex-minted-langs}
14519 @item @code{:latex-minted-options} @tab @code{org-latex-minted-options}
14520 @item @code{:latex-prefer-user-labels} @tab @code{org-latex-prefer-user-labels}
14521 @item @code{:latex-subtitle-format} @tab @code{org-latex-subtitle-format}
14522 @item @code{:latex-subtitle-separate} @tab @code{org-latex-subtitle-separate}
14523 @item @code{:latex-table-scientific-notation} @tab @code{org-latex-table-scientific-notation}
14524 @item @code{:latex-tables-booktabs} @tab @code{org-latex-tables-booktabs}
14525 @item @code{:latex-tables-centered} @tab @code{org-latex-tables-centered}
14526 @item @code{:latex-text-markup-alist} @tab @code{org-latex-text-markup-alist}
14527 @item @code{:latex-title-command} @tab @code{org-latex-title-command}
14528 @item @code{:latex-toc-command} @tab @code{org-latex-toc-command}
14531 @subsubheading Markdown specific properties
14533 @multitable {@code{:md-footnotes-section}} {@code{org-md-footnotes-section}}
14534 @item @code{:md-footnote-format} @tab @code{org-md-footnote-format}
14535 @item @code{:md-footnotes-section} @tab @code{org-md-footnotes-section}
14536 @item @code{:md-headline-style} @tab @code{org-md-headline-style}
14539 @subsubheading ODT specific properties
14541 @multitable {@code{:odt-format-inlinetask-function}} {@code{org-odt-format-inlinetask-function}}
14542 @item @code{:odt-content-template-file} @tab @code{org-odt-content-template-file}
14543 @item @code{:odt-display-outline-level} @tab @code{org-odt-display-outline-level}
14544 @item @code{:odt-fontify-srcblocks} @tab @code{org-odt-fontify-srcblocks}
14545 @item @code{:odt-format-drawer-function} @tab @code{org-odt-format-drawer-function}
14546 @item @code{:odt-format-headline-function} @tab @code{org-odt-format-headline-function}
14547 @item @code{:odt-format-inlinetask-function} @tab @code{org-odt-format-inlinetask-function}
14548 @item @code{:odt-inline-formula-rules} @tab @code{org-odt-inline-formula-rules}
14549 @item @code{:odt-inline-image-rules} @tab @code{org-odt-inline-image-rules}
14550 @item @code{:odt-pixels-per-inch} @tab @code{org-odt-pixels-per-inch}
14551 @item @code{:odt-styles-file} @tab @code{org-odt-styles-file}
14552 @item @code{:odt-table-styles} @tab @code{org-odt-table-styles}
14553 @item @code{:odt-use-date-fields} @tab @code{org-odt-use-date-fields}
14556 @subsubheading Texinfo specific properties
14558 @multitable {@code{:texinfo-link-with-unknown-path-format}} {@code{org-texinfo-link-with-unknown-path-format}}
14559 @item @code{:texinfo-active-timestamp-format} @tab @code{org-texinfo-active-timestamp-format}
14560 @item @code{:texinfo-classes} @tab @code{org-texinfo-classes}
14561 @item @code{:texinfo-class} @tab @code{org-texinfo-default-class}
14562 @item @code{:texinfo-def-table-markup} @tab @code{org-texinfo-def-table-markup}
14563 @item @code{:texinfo-diary-timestamp-format} @tab @code{org-texinfo-diary-timestamp-format}
14564 @item @code{:texinfo-filename} @tab @code{org-texinfo-filename}
14565 @item @code{:texinfo-format-drawer-function} @tab @code{org-texinfo-format-drawer-function}
14566 @item @code{:texinfo-format-headline-function} @tab @code{org-texinfo-format-headline-function}
14567 @item @code{:texinfo-format-inlinetask-function} @tab @code{org-texinfo-format-inlinetask-function}
14568 @item @code{:texinfo-inactive-timestamp-format} @tab @code{org-texinfo-inactive-timestamp-format}
14569 @item @code{:texinfo-link-with-unknown-path-format} @tab @code{org-texinfo-link-with-unknown-path-format}
14570 @item @code{:texinfo-node-description-column} @tab @code{org-texinfo-node-description-column}
14571 @item @code{:texinfo-table-scientific-notation} @tab @code{org-texinfo-table-scientific-notation}
14572 @item @code{:texinfo-tables-verbatim} @tab @code{org-texinfo-tables-verbatim}
14573 @item @code{:texinfo-text-markup-alist} @tab @code{org-texinfo-text-markup-alist}
14576 @node Publishing links
14577 @subsection Links between published files
14578 @cindex links, publishing
14580 To create a link from one Org file to another, you would use something like
14581 @samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org}
14582 (@pxref{External links}). When published, this link becomes a link to
14583 @file{foo.html}. You can thus interlink the pages of your ``org web''
14584 project and the links will work as expected when you publish them to HTML.
14585 If you also publish the Org source file and want to link to it, use an
14586 @code{http:} link instead of a @code{file:} link, because @code{file:} links
14587 are converted to link to the corresponding @file{html} file.
14589 You may also link to related files, such as images. Provided you are careful
14590 with relative file names, and provided you have also configured Org to upload
14591 the related files, these links will work too. See @ref{Complex example}, for
14592 an example of this usage.
14594 Eventually, links between published documents can contain some search options
14595 (@pxref{Search options}), which will be resolved to the appropriate location
14596 in the linked file. For example, once published to HTML, the following links
14597 all point to a dedicated anchor in @file{foo.html}.
14600 [[file:foo.org::*heading]]
14601 [[file:foo.org::#custom-id]]
14602 [[file:foo.org::target]]
14606 @subsection Generating a sitemap
14607 @cindex sitemap, of published pages
14609 The following properties may be used to control publishing of
14610 a map of files for a given project.
14612 @multitable @columnfractions 0.35 0.65
14613 @item @code{:auto-sitemap}
14614 @tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project}
14615 or @code{org-publish-all}.
14617 @item @code{:sitemap-filename}
14618 @tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which
14619 becomes @file{sitemap.html}).
14621 @item @code{:sitemap-title}
14622 @tab Title of sitemap page. Defaults to name of file.
14624 @item @code{:sitemap-function}
14625 @tab Plug-in function to use for generation of the sitemap.
14626 Defaults to @code{org-publish-org-sitemap}, which generates a plain list
14627 of links to all files in the project.
14629 @item @code{:sitemap-sort-folders}
14630 @tab Where folders should appear in the sitemap. Set this to @code{first}
14631 (default) or @code{last} to display folders first or last,
14632 respectively. Any other value will mix files and folders.
14634 @item @code{:sitemap-sort-files}
14635 @tab How the files are sorted in the site map. Set this to
14636 @code{alphabetically} (default), @code{chronologically} or
14637 @code{anti-chronologically}. @code{chronologically} sorts the files with
14638 older date first while @code{anti-chronologically} sorts the files with newer
14639 date first. @code{alphabetically} sorts the files alphabetically. The date of
14640 a file is retrieved with @code{org-publish-find-date}.
14642 @item @code{:sitemap-ignore-case}
14643 @tab Should sorting be case-sensitive? Default @code{nil}.
14645 @item @code{:sitemap-file-entry-format}
14646 @tab With this option one can tell how a sitemap's entry is formatted in the
14647 sitemap. This is a format string with some escape sequences: @code{%t} stands
14648 for the title of the file, @code{%a} stands for the author of the file and
14649 @code{%d} stands for the date of the file. The date is retrieved with the
14650 @code{org-publish-find-date} function and formatted with
14651 @code{org-publish-sitemap-date-format}. Default @code{%t}.
14653 @item @code{:sitemap-date-format}
14654 @tab Format string for the @code{format-time-string} function that tells how
14655 a sitemap entry's date is to be formatted. This property bypasses
14656 @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
14658 @item @code{:sitemap-sans-extension}
14659 @tab When non-@code{nil}, remove filenames' extensions from the generated sitemap.
14660 Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}).
14661 Defaults to @code{nil}.
14665 @node Generating an index
14666 @subsection Generating an index
14667 @cindex index, in a publishing project
14669 Org mode can generate an index across the files of a publishing project.
14671 @multitable @columnfractions 0.25 0.75
14672 @item @code{:makeindex}
14673 @tab When non-@code{nil}, generate in index in the file @file{theindex.org} and
14674 publish it as @file{theindex.html}.
14677 The file will be created when first publishing a project with the
14678 @code{:makeindex} set. The file only contains a statement @code{#+INCLUDE:
14679 "theindex.inc"}. You can then build around this include statement by adding
14680 a title, style information, etc.
14683 Index entries are specified with @code{#+INDEX} keyword. An entry that
14684 contains an exclamation mark will create a sub item.
14689 #+INDEX: Application!CV
14692 @node Uploading files
14693 @section Uploading files
14697 For those people already utilizing third party sync tools such as
14698 @command{rsync} or @command{unison}, it might be preferable not to use the built in
14699 @i{remote} publishing facilities of Org mode which rely heavily on
14700 Tramp. Tramp, while very useful and powerful, tends not to be
14701 so efficient for multiple file transfer and has been known to cause problems
14704 Specialized synchronization utilities offer several advantages. In addition
14705 to timestamp comparison, they also do content and permissions/attribute
14706 checks. For this reason you might prefer to publish your web to a local
14707 directory (possibly even @i{in place} with your Org files) and then use
14708 @file{unison} or @file{rsync} to do the synchronization with the remote host.
14710 Since Unison (for example) can be configured as to which files to transfer to
14711 a certain remote destination, it can greatly simplify the project publishing
14712 definition. Simply keep all files in the correct location, process your Org
14713 files with @code{org-publish} and let the synchronization tool do the rest.
14714 You do not need, in this scenario, to include attachments such as @file{jpg},
14715 @file{css} or @file{gif} files in the project definition since the 3rd party
14718 Publishing to a local directory is also much faster than to a remote one, so
14719 that you can afford more easily to republish entire projects. If you set
14720 @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
14721 benefit of re-including any changed external files such as source example
14722 files you might include with @code{#+INCLUDE:}. The timestamp mechanism in
14723 Org is not smart enough to detect if included files have been modified.
14725 @node Sample configuration
14726 @section Sample configuration
14728 Below we provide two example configurations. The first one is a simple
14729 project publishing only a set of Org files. The second example is
14730 more complex, with a multi-component project.
14733 * Simple example:: One-component publishing
14734 * Complex example:: A multi-component publishing example
14737 @node Simple example
14738 @subsection Example: simple publishing configuration
14740 This example publishes a set of Org files to the @file{public_html}
14741 directory on the local machine.
14744 (setq org-publish-project-alist
14746 :base-directory "~/org/"
14747 :publishing-directory "~/public_html"
14748 :section-numbers nil
14750 :html-head "<link rel=\"stylesheet\"
14751 href=\"../other/mystyle.css\"
14752 type=\"text/css\"/>")))
14755 @node Complex example
14756 @subsection Example: complex publishing configuration
14758 This more complicated example publishes an entire website, including
14759 Org files converted to HTML, image files, Emacs Lisp source code, and
14760 style sheets. The publishing directory is remote and private files are
14763 To ensure that links are preserved, care should be taken to replicate
14764 your directory structure on the web server, and to use relative file
14765 paths. For example, if your Org files are kept in @file{~/org} and your
14766 publishable images in @file{~/images}, you would link to an image with
14769 file:../images/myimage.png
14772 On the web server, the relative path to the image should be the
14773 same. You can accomplish this by setting up an "images" folder in the
14774 right place on the web server, and publishing images to it.
14777 (setq org-publish-project-alist
14779 :base-directory "~/org/"
14780 :base-extension "org"
14781 :publishing-directory "/ssh:user@@host:~/html/notebook/"
14782 :publishing-function org-html-publish-to-html
14783 :exclude "PrivatePage.org" ;; regexp
14785 :section-numbers nil
14787 :html-head "<link rel=\"stylesheet\"
14788 href=\"../other/mystyle.css\" type=\"text/css\"/>"
14792 :base-directory "~/images/"
14793 :base-extension "jpg\\|gif\\|png"
14794 :publishing-directory "/ssh:user@@host:~/html/images/"
14795 :publishing-function org-publish-attachment)
14798 :base-directory "~/other/"
14799 :base-extension "css\\|el"
14800 :publishing-directory "/ssh:user@@host:~/html/other/"
14801 :publishing-function org-publish-attachment)
14802 ("website" :components ("orgfiles" "images" "other"))))
14805 @node Triggering publication
14806 @section Triggering publication
14808 Once properly configured, Org can publish with the following commands:
14811 @orgcmd{C-c C-e P x,org-publish}
14812 Prompt for a specific project and publish all files that belong to it.
14813 @orgcmd{C-c C-e P p,org-publish-current-project}
14814 Publish the project containing the current file.
14815 @orgcmd{C-c C-e P f,org-publish-current-file}
14816 Publish only the current file.
14817 @orgcmd{C-c C-e P a,org-publish-all}
14818 Publish every project.
14821 @vindex org-publish-use-timestamps-flag
14822 Org uses timestamps to track when a file has changed. The above functions
14823 normally only publish changed files. You can override this and force
14824 publishing of all files by giving a prefix argument to any of the commands
14825 above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
14826 This may be necessary in particular if files include other files via
14827 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
14830 @node Working with source code
14831 @chapter Working with source code
14832 @cindex Schulte, Eric
14833 @cindex Davison, Dan
14834 @cindex source code, working with
14836 Source code here refers to any code typed in Org mode documents. Org can
14837 manage source code in any Org file once such code is tagged with begin and
14838 end markers. Working with source code begins with tagging source code
14839 blocks. Tagged @samp{src} code blocks are not restricted to the preamble or
14840 the end of an Org document; they can go anywhere---with a few exceptions,
14841 such as not inside comments and fixed width areas. Here's a sample
14842 @samp{src} code block in emacs-lisp:
14845 #+BEGIN_SRC emacs-lisp
14846 (defun org-xor (a b)
14852 Org can take the code in the block between the @samp{#+BEGIN_SRC} and
14853 @samp{#+END_SRC} tags, and format, compile, execute, and show the results.
14854 Org can simplify many housekeeping tasks essential to modern code
14855 maintenance. That's why these blocks in Org mode literature are sometimes
14856 referred to as @samp{live code} blocks (as compared to the static text and
14857 documentation around it). Users can control how @samp{live} they want each
14858 block by tweaking the headers for compiling, execution, extraction.
14860 Org's @samp{src} code block type is one of many block types, such as quote,
14861 export, verse, latex, example, and verbatim. This section pertains to
14862 @samp{src} code blocks between @samp{#+BEGIN_SRC} and @samp{#+END_SRC}
14864 For editing @samp{src} code blocks, Org provides native Emacs major-modes.
14865 That leverages the latest Emacs features for that source code language mode.
14867 For exporting, Org can then extract @samp{src} code blocks into compilable
14868 source files (in a conversion process known as @dfn{tangling} in literate
14869 programming terminology).
14871 For publishing, Org's back-ends can handle the @samp{src} code blocks and the
14872 text for output to a variety of formats with native syntax highlighting.
14874 For executing the source code in the @samp{src} code blocks, Org provides
14875 facilities that glue the tasks of compiling, collecting the results of the
14876 execution, and inserting them back to the Org file. Besides text output,
14877 results may include links to other data types that Emacs can handle: audio,
14878 video, and graphics.
14880 An important feature of Org's execution of the @samp{src} code blocks is
14881 passing variables, functions, and results between @samp{src} blocks. Such
14882 interoperability uses a common syntax even if these @samp{src} blocks are in
14883 different source code languages. The integration extends to linking the
14884 debugger's error messages to the line in the @samp{src} code block in the Org
14885 file. That should partly explain why this functionality by the original
14886 contributors, Eric Schulte and Dan Davison, was called @samp{Org Babel}.
14888 In literate programming, the main appeal is code and documentation
14889 co-existing in one file. Org mode takes this several steps further. First
14890 by enabling execution, and then by inserting results of that execution back
14891 into the Org file. Along the way, Org provides extensive formatting
14892 features, including handling tables. Org handles multiple source code
14893 languages in one file, and provides a common syntax for passing variables,
14894 functions, and results between @samp{src} code blocks.
14896 Org mode fulfills the promise of easy verification and maintenance of
14897 publishing reproducible research by keeping all these in the same file: text,
14898 data, code, configuration settings of the execution environment, the results
14899 of the execution, and associated narratives, claims, references, and internal
14900 and external links.
14902 Details of Org's facilities for working with source code are shown next.
14905 * Structure of code blocks:: Code block syntax described
14906 * Editing source code:: Language major-mode editing
14907 * Exporting code blocks:: Export contents and/or results
14908 * Extracting source code:: Create pure source code files
14909 * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
14910 * Library of Babel:: Use and contribute to a library of useful code blocks
14911 * Languages:: List of supported code block languages
14912 * Header arguments:: Configure code block functionality
14913 * Results of evaluation:: How evaluation results are handled
14914 * Noweb reference syntax:: Literate programming in Org mode
14915 * Key bindings and useful functions:: Work quickly with code blocks
14916 * Batch execution:: Call functions from the command line
14920 @node Structure of code blocks
14921 @section Structure of code blocks
14922 @cindex code block, structure
14923 @cindex source code, block structure
14925 @cindex #+BEGIN_SRC
14927 Org offers two ways to structure source code in Org documents: in a
14928 @samp{src} block, and directly inline. Both specifications are shown below.
14930 A @samp{src} block conforms to this structure:
14934 #+BEGIN_SRC <language> <switches> <header arguments>
14939 Org mode's templates system (@pxref{Easy templates}) speeds up creating
14940 @samp{src} code blocks with just three keystrokes. Do not be put-off by
14941 having to remember the source block syntax. Org also works with other
14942 completion systems in Emacs, some of which predate Org and have custom
14943 domain-specific languages for defining templates. Regular use of templates
14944 reduces errors, increases accuracy, and maintains consistency.
14946 @cindex source code, inline
14947 An inline code block conforms to this structure:
14950 src_<language>@{<body>@}
14956 src_<language>[<header arguments>]@{<body>@}
14960 @item #+NAME: <name>
14961 Optional. Names the @samp{src} block so it can be called, like a function,
14962 from other @samp{src} blocks or inline blocks to evaluate or to capture the
14963 results. Code from other blocks, other files, and from table formulas
14964 (@pxref{The spreadsheet}) can use the name to reference a @samp{src} block.
14965 This naming serves the same purpose as naming Org tables. Org mode requires
14966 unique names. For duplicate names, Org mode's behavior is undefined.
14970 Mandatory. They mark the start and end of a block that Org requires. The
14971 @code{#+BEGIN_SRC} line takes additional arguments, as described next.
14972 @cindex begin block, end block
14974 Mandatory for live code blocks. It is the identifier of the source code
14975 language in the block. @xref{Languages}, for identifiers of supported
14977 @cindex source code, language
14979 Optional. Switches provide finer control of the code execution, export, and
14980 format (see the discussion of switches in @ref{Literal examples})
14981 @cindex source code, switches
14982 @item <header arguments>
14983 Optional. Heading arguments control many aspects of evaluation, export and
14984 tangling of code blocks (@pxref{Header arguments}). Using Org's properties
14985 feature, header arguments can be selectively applied to the entire buffer or
14986 specific sub-trees of the Org document.
14987 @item source code, header arguments
14989 Source code in the dialect of the specified language identifier.
14992 @node Editing source code
14993 @section Editing source code
14994 @cindex code block, editing
14995 @cindex source code, editing
14997 @vindex org-edit-src-auto-save-idle-delay
14998 @vindex org-edit-src-turn-on-auto-save
15000 @kbd{C-c '} for editing the current code block. It opens a new major-mode
15001 edit buffer containing the body of the @samp{src} code block, ready for any
15002 edits. @kbd{C-c '} again to close the buffer and return to the Org buffer.
15004 @key{C-x C-s} saves the buffer and updates the contents of the Org buffer.
15006 Set @code{org-edit-src-auto-save-idle-delay} to save the base buffer after
15007 a certain idle delay time.
15009 Set @code{org-edit-src-turn-on-auto-save} to auto-save this buffer into a
15010 separate file using @code{auto-save-mode}.
15012 @kbd{C-c '} to close the major-mode buffer and return back to the Org buffer.
15014 While editing the source code in the major-mode, the @code{org-src-mode}
15015 minor mode remains active. It provides these customization variables as
15016 described below. For even more variables, look in the customization
15017 group @code{org-edit-structure}.
15020 @item org-src-lang-modes
15021 If an Emacs major-mode named @code{<lang>-mode} exists, where @code{<lang>}
15022 is the language identifier from code block's header line, then the edit
15023 buffer uses that major-mode. Use this variable to arbitrarily map language
15024 identifiers to major modes.
15025 @item org-src-window-setup
15026 For specifying Emacs window arrangement when the new edit buffer is created.
15027 @item org-src-preserve-indentation
15028 @cindex indentation, in source blocks
15029 Default is @code{nil}. Source code is indented. This indentation applies
15030 during export or tangling, and depending on the context, may alter leading
15031 spaces and tabs. When non-@code{nil}, source code is aligned with the
15032 leftmost column. No lines are modified during export or tangling, which is
15033 very useful for white-space sensitive languages, such as Python.
15034 @item org-src-ask-before-returning-to-edit-buffer
15035 When @code{nil}, Org returns to the edit buffer without further prompts. The
15036 default prompts for a confirmation.
15039 Set @code{org-src-fontify-natively} to non-@code{nil} to turn on native code
15040 fontification in the @emph{Org} buffer. Fontification of @samp{src} code
15041 blocks can give visual separation of text and code on the display page. To
15042 further customize the appearance of @code{org-block} for specific languages,
15043 customize @code{org-src-block-faces}. The following example shades the
15044 background of regular blocks, and colors source blocks only for Python and
15045 Emacs-Lisp languages.
15048 (set-face-attribute 'org-block nil :background
15050 (face-attribute 'default :background) 3))
15052 (setq org-src-block-faces '(("emacs-lisp" (:background "#EEE2FF"))
15053 ("python" (:background "#E5FFB8"))))
15056 @node Exporting code blocks
15057 @section Exporting code blocks
15058 @cindex code block, exporting
15059 @cindex source code, exporting
15061 Org can flexibly export just the @emph{code} from the code blocks, just the
15062 @emph{results} of evaluation of the code block, @emph{both} the code and the
15063 results of the code block evaluation, or @emph{none}. Org defaults to
15064 exporting @emph{code} for most languages. For some languages, such as
15065 @code{ditaa}, Org defaults to @emph{results}. To export just the body of
15066 code blocks, @pxref{Literal examples}. To selectively export sub-trees of
15067 an Org document, @pxref{Exporting}.
15069 The @code{:exports} header arguments control exporting code blocks only and
15072 @subsubheading Header arguments:
15075 @cindex @code{:exports}, src header argument
15076 @item :exports code
15077 This is the default for most languages where the body of the code block is
15078 exported. See @ref{Literal examples} for more.
15079 @item :exports results
15080 On export, Org includes only the results and not the code block. After each
15081 evaluation, Org inserts the results after the end of code block in the Org
15082 buffer. By default, Org replaces any previous results. Org can also append
15084 @item :exports both
15085 Org exports both the code block and the results.
15086 @item :exports none
15087 Org does not export the code block nor the results.
15090 @vindex org-export-babel-evaluate
15091 To stop Org from evaluating code blocks during export, set
15092 @code{org-export-babel-evaluate} variable to @code{nil}.
15094 Turning off evaluation comes in handy when batch processing. For example,
15095 markup languages for wikis, which have a high risk of untrusted code.
15096 Stopping code block evaluation also stops evaluation of all header arguments
15097 of the code block. This may not be desirable in some circumstances. So
15098 during export, to allow evaluation of just the header arguments but not any
15099 code evaluation in the source block, set @code{:eval never-export}
15102 To evaluate just the inline code blocks, set @code{org-export-babel-evaluate}
15103 to @code{inline-only}. Isolating the option to allow inline evaluations
15104 separate from @samp{src} code block evaluations during exports is not for
15105 security but for avoiding any delays due to recalculations, such as calls to
15108 Org never evaluates code blocks in commented sub-trees when exporting
15109 (@pxref{Comment lines}). On the other hand, Org does evaluate code blocks in
15110 sub-trees excluded from export (@pxref{Export settings}).
15112 @node Extracting source code
15113 @section Extracting source code
15115 @cindex source code, extracting
15116 @cindex code block, extracting source code
15118 Extracting source code from code blocks is a basic task in literate
15119 programming. Org has features to make this easy. In literate programming
15120 parlance, documents on creation are @emph{woven} with code and documentation,
15121 and on export, the code is @emph{tangled} for execution by a computer. Org
15122 facilitates weaving and tangling for producing, maintaining, sharing, and
15123 exporting literate programming documents. Org provides extensive
15124 customization options for extracting source code.
15126 When Org tangles @samp{src} code blocks, it expands, merges, and transforms
15127 them. Then Org recomposes them into one or more separate files, as
15128 configured through the options. During this @emph{tangling} process, Org
15129 expands variables in the source code, and resolves any ``noweb'' style
15130 references (@pxref{Noweb reference syntax}).
15132 @subsubheading Header arguments
15135 @cindex @code{:tangle}, src header argument
15137 By default, Org does not tangle the @samp{src} code block on export.
15139 Org extracts the contents of the code block for the tangled output. By
15140 default, the output file name is the same as the Org file but with a file
15141 extension derived from the language identifier of the @samp{src} code block.
15142 @item :tangle filename
15143 Override the default file name with this one for the tangled output.
15147 @subsubheading Functions
15150 @item org-babel-tangle
15151 Tangle the current file. Bound to @kbd{C-c C-v t}.
15153 With prefix argument only tangle the current @samp{src} code block.
15154 @item org-babel-tangle-file
15155 Choose a file to tangle. Bound to @kbd{C-c C-v f}.
15158 @subsubheading Hooks
15161 @item org-babel-post-tangle-hook
15162 This hook runs from within code tangled by @code{org-babel-tangle}, making it
15163 suitable for post-processing, compilation, and evaluation of code in the
15167 @subsubheading Jumping between code and Org
15169 Debuggers normally link errors and messages back to the source code. But for
15170 tangled files, we want to link back to the Org file, not to the tangled
15171 source file. To make this extra jump, Org uses
15172 @code{org-babel-tangle-jump-to-org} function with two additional source code
15173 block header arguments: One, set @code{padline} (@pxref{padline}) to true
15174 (the default setting). Two, set @code{comments} (@pxref{comments}) to
15175 @code{link}, which makes Org insert links to the Org file.
15177 @node Evaluating code blocks
15178 @section Evaluating code blocks
15179 @cindex code block, evaluating
15180 @cindex source code, evaluating
15183 A note about security: With code evaluation comes the risk of harm. Org
15184 safeguards by prompting for user's permission before executing any code in
15185 the source block. To customize this safeguard (or disable it) see @ref{Code
15186 evaluation security}.
15188 Org captures the results of the @samp{src} code block evaluation and inserts
15189 them in the Org file, right after the @samp{src} code block. The insertion
15190 point is after a newline and the @code{#+RESULTS} label. Org creates the
15191 @code{#+RESULTS} label if one is not already there.
15193 By default, Org enables only @code{emacs-lisp} @samp{src} code blocks for
15194 execution. See @ref{Languages} for identifiers to enable other languages.
15197 Org provides many ways to execute @samp{src} code blocks. @kbd{C-c C-c} or
15198 @kbd{C-c C-v e} with the point on a @samp{src} code block@footnote{The option
15199 @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used to remove code
15200 evaluation from the @kbd{C-c C-c} key binding.} calls the
15201 @code{org-babel-execute-src-block} function, which executes the code in the
15202 block, collects the results, and inserts them in the buffer.
15205 By calling a named code block@footnote{Actually, the constructs call_<name>()
15206 and src_<lang>@{@} are not evaluated when they appear in a keyword line
15207 (i.e. lines starting with @code{#+KEYWORD:}, @pxref{In-buffer settings}).}
15208 from an Org mode buffer or a table. Org can call the named @samp{src} code
15209 blocks from the current Org mode buffer or from the ``Library of Babel''
15210 (@pxref{Library of Babel}). Whether inline syntax or the @code{#+CALL:}
15211 syntax is used, the result is wrapped based on the variable
15212 @code{org-babel-inline-result-wrap}, which by default is set to @code{"=%s="}
15213 to produce verbatim text suitable for markup.
15215 The syntax for @code{#+CALL:} is
15218 #+CALL: <name>(<arguments>)
15219 #+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
15222 The syntax for inline named code block is
15225 ... call_<name>(<arguments>) ...
15226 ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
15231 This is the name of the code block to be evaluated (@pxref{Structure of
15234 Org passes arguments to the code block using standard function call syntax.
15235 For example, a @code{#+CALL:} line that passes @samp{4} to a code block named
15236 @code{double}, which declares the header argument @code{:var n=2}, would be
15237 written as @code{#+CALL: double(n=4)}. Note how this function call syntax is
15238 different from the header argument syntax.
15239 @item <inside header arguments>
15240 Org passes inside header arguments to the named @samp{src} code block using
15241 the header argument syntax. Inside header arguments apply to code block
15242 evaluation. For example, @code{[:results output]} collects results printed
15243 to @code{STDOUT} during code execution of that block. Note how this header
15244 argument syntax is different from the function call syntax.
15245 @item <end header arguments>
15246 End header arguments affect the results returned by the code block. For
15247 example, @code{:results html} wraps the results in a @code{BEGIN_EXPORT html}
15248 block before inserting the results in the Org buffer.
15250 For more examples of header arguments for @code{#+CALL:} lines,
15251 @pxref{Arguments in function calls}.
15254 @node Library of Babel
15255 @section Library of Babel
15256 @cindex babel, library of
15257 @cindex source code, library
15258 @cindex code block, library
15260 The ``Library of Babel'' is a collection of code blocks. Like a function
15261 library, these code blocks can be called from other Org files. This
15262 collection is in a repository file in Org mode format in the @samp{doc}
15263 directory of Org mode installation. For remote code block evaluation syntax,
15264 @pxref{Evaluating code blocks}.
15267 For any user to add code to the library, first save the code in regular
15268 @samp{src} code blocks of an Org file, and then load the Org file with
15269 @code{org-babel-lob-ingest}, which is bound to @kbd{C-c C-v i}.
15273 @cindex babel, languages
15274 @cindex source code, languages
15275 @cindex code block, languages
15277 Org supports the following languages for the @samp{src} code blocks:
15279 @multitable @columnfractions 0.25 0.25 0.25 0.25
15280 @headitem @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}
15281 @item Asymptote @tab asymptote @tab Awk @tab awk
15282 @item C @tab C @tab C++ @tab C++
15283 @item Clojure @tab clojure @tab CSS @tab css
15284 @item D @tab d @tab ditaa @tab ditaa
15285 @item Graphviz @tab dot @tab Emacs Calc @tab calc
15286 @item Emacs Lisp @tab emacs-lisp @tab Fortran @tab fortran
15287 @item gnuplot @tab gnuplot @tab Haskell @tab haskell
15288 @item Java @tab java @tab Javascript @tab js
15289 @item LaTeX @tab latex @tab Ledger @tab ledger
15290 @item Lisp @tab lisp @tab Lilypond @tab lilypond
15291 @item Lua @tab lua @tab MATLAB @tab matlab
15292 @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
15293 @item Octave @tab octave @tab Org mode @tab org
15294 @item Oz @tab oz @tab Perl @tab perl
15295 @item Plantuml @tab plantuml @tab Processing.js @tab processing
15296 @item Python @tab python @tab R @tab R
15297 @item Ruby @tab ruby @tab Sass @tab sass
15298 @item Scheme @tab scheme @tab GNU Screen @tab screen
15299 @item Sed @tab sed @tab shell @tab sh
15300 @item SQL @tab sql @tab SQLite @tab sqlite
15303 Additional documentation for some languages are at
15304 @uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
15306 By default, only @code{emacs-lisp} is enabled for evaluation. To enable or
15307 disable other languages, customize the @code{org-babel-load-languages}
15308 variable either through the Emacs customization interface, or by adding code
15309 to the init file as shown next:
15311 In this example, evaluation is disabled for @code{emacs-lisp}, and enabled
15315 (org-babel-do-load-languages
15316 'org-babel-load-languages
15317 '((emacs-lisp . nil)
15321 Note that this is not the only way to enable a language. Org also enables
15322 languages when loaded with @code{require} statement. For example, the
15323 following enables execution of @code{clojure} code blocks:
15326 (require 'ob-clojure)
15329 @node Header arguments
15330 @section Header arguments
15331 @cindex code block, header arguments
15332 @cindex source code, block header arguments
15334 Details of configuring header arguments are shown here.
15337 * Using header arguments:: Different ways to set header arguments
15338 * Specific header arguments:: List of header arguments
15341 @node Using header arguments
15342 @subsection Using header arguments
15344 Since header arguments can be set in several ways, Org prioritizes them in
15345 case of overlaps or conflicts by giving local settings a higher priority.
15346 Header values in function calls, for example, override header values from
15349 * System-wide header arguments:: Set globally, language-specific
15350 * Language-specific header arguments:: Set in the Org file's headers
15351 * Header arguments in Org mode properties:: Set in the Org file
15352 * Language-specific mode properties::
15353 * Code block specific header arguments:: The most commonly used method
15354 * Arguments in function calls:: The most specific level, takes highest priority
15358 @node System-wide header arguments
15359 @subsubheading System-wide header arguments
15360 @vindex org-babel-default-header-args
15361 System-wide values of header arguments can be specified by adapting the
15362 @code{org-babel-default-header-args} variable:
15364 @cindex @code{:session}, src header argument
15365 @cindex @code{:results}, src header argument
15366 @cindex @code{:exports}, src header argument
15367 @cindex @code{:cache}, src header argument
15368 @cindex @code{:noweb}, src header argument
15371 :results => "replace"
15377 This example sets @code{:noweb} header arguments to @code{yes}, which makes
15378 Org expand @code{:noweb} references by default.
15381 (setq org-babel-default-header-args
15382 (cons '(:noweb . "yes")
15383 (assq-delete-all :noweb org-babel-default-header-args)))
15386 @node Language-specific header arguments
15387 @subsubheading Language-specific header arguments
15388 Each language can have separate default header arguments by customizing the
15389 variable @code{org-babel-default-header-args:<lang>}, where @code{<lang>} is
15390 the name of the language. For details, see the language-specific online
15391 documentation at @uref{http://orgmode.org/worg/org-contrib/babel}.
15393 @node Header arguments in Org mode properties
15394 @subsubheading Header arguments in Org mode properties
15396 For header arguments applicable to the buffer, use @code{#+PROPERTY:} lines
15397 anywhere in the Org mode file (@pxref{Property syntax}).
15399 The following example sets only for @samp{R} code blocks to @code{session},
15400 making all the @samp{R} code blocks execute in the same session. Setting
15401 @code{results} to @code{silent} ignores the results of executions for all
15402 blocks, not just @samp{R} code blocks; no results inserted for any block.
15405 #+PROPERTY: header-args:R :session *R*
15406 #+PROPERTY: header-args :results silent
15409 @vindex org-use-property-inheritance
15410 Header arguments set through Org's property drawers (@pxref{Property syntax})
15411 apply at the sub-tree level on down. Since these property drawers can appear
15412 anywhere in the file hierarchy, Org uses outermost call or source block to
15413 resolve the values. Org ignores @code{org-use-property-inheritance} setting.
15415 In this example, @code{:cache} defaults to @code{yes} for all code blocks in
15416 the sub-tree starting with @samp{sample header}.
15421 :header-args: :cache yes
15426 @vindex org-babel-default-header-args
15427 Properties defined through @code{org-set-property} function, bound to
15428 @kbd{C-c C-x p}, apply to all active languages. They override properties set
15429 in @code{org-babel-default-header-args}.
15431 @node Language-specific mode properties
15432 @subsubheading Language-specific mode properties
15434 Language-specific header arguments are also read from properties
15435 @code{header-args:<lang>} where @code{<lang>} is the language identifier.
15441 :header-args:clojure: :session *clojure-1*
15442 :header-args:R: :session *R*
15446 :header-args:clojure: :session *clojure-2*
15450 would force separate sessions for clojure blocks in Heading and Subheading,
15451 but use the same session for all @samp{R} blocks. Blocks in Subheading
15452 inherit settings from Heading.
15454 @node Code block specific header arguments
15455 @subsubheading Code block specific header arguments
15457 Header arguments are most commonly set at the @samp{src} code block level, on
15458 the @code{#+BEGIN_SRC} line. Arguments set at this level take precedence
15459 over those set in the @code{org-babel-default-header-args} variable, and also
15460 those set as header properties.
15462 In the following example, setting @code{results} to @code{silent} makes it
15463 ignore results of the code execution. Setting @code{:exports} to @code{code}
15464 exports only the body of the @samp{src} code block to HTML or @LaTeX{}.:
15468 #+BEGIN_SRC haskell :results silent :exports code :var n=0
15470 fac n = n * fac (n-1)
15474 The same header arguments in an inline @samp{src} code block:
15477 src_haskell[:exports both]@{fac 5@}
15480 Code block header arguments can span multiple lines using @code{#+HEADER:} on
15481 each line. Note that Org currently accepts the plural spelling of
15482 @code{#+HEADER:} only as a convenience for backward-compatibility. It may be
15483 removed at some point.
15487 Multi-line header arguments on an unnamed @samp{src} code block:
15490 #+HEADER: :var data1=1
15491 #+BEGIN_SRC emacs-lisp :var data2=2
15492 (message "data1:%S, data2:%S" data1 data2)
15499 Multi-line header arguments on a named @samp{src} code block:
15502 #+NAME: named-block
15503 #+HEADER: :var data=2
15504 #+BEGIN_SRC emacs-lisp
15505 (message "data:%S" data)
15508 #+RESULTS: named-block
15512 @node Arguments in function calls
15513 @subsubheading Arguments in function calls
15515 Header arguments in function calls are the most specific and override all
15516 other settings in case of an overlap. They get the highest priority. Two
15517 @code{#+CALL:} examples are shown below. For the complete syntax of
15518 @code{#+CALL:} lines, see @ref{Evaluating code blocks}.
15520 In this example, @code{:exports results} header argument is applied to the
15521 evaluation of the @code{#+CALL:} line.
15524 #+CALL: factorial(n=5) :exports results
15527 In this example, @code{:session special} header argument is applied to the
15528 evaluation of @code{factorial} code block.
15531 #+CALL: factorial[:session special](n=5)
15534 @node Specific header arguments
15535 @subsection Specific header arguments
15536 Org comes with many header arguments common to all languages. New header
15537 arguments are added for specific languages as they become available for use
15538 in @samp{src} code blocks. A header argument is specified with an initial
15539 colon followed by the argument's name in lowercase. Common header arguments
15543 * var:: Pass arguments to @samp{src} code blocks
15544 * results:: Specify results type; how to collect
15545 * file:: Specify a path for output file
15546 * file-desc:: Specify a description for file results
15547 * file-ext:: Specify an extension for file output
15548 * output-dir:: Specify a directory for output file
15549 * dir:: Specify the default directory for code block execution
15550 * exports:: Specify exporting code, results, both, none
15551 * tangle:: Toggle tangling; or specify file name
15552 * mkdirp:: Toggle for parent directory creation for target files during tangling
15553 * comments:: Toggle insertion of comments in tangled code files
15554 * padline:: Control insertion of padding lines in tangled code files
15555 * no-expand:: Turn off variable assignment and noweb expansion during tangling
15556 * session:: Preserve the state of code evaluation
15557 * noweb:: Toggle expansion of noweb references
15558 * noweb-ref:: Specify block's noweb reference resolution target
15559 * noweb-sep:: String to separate noweb references
15560 * cache:: Avoid re-evaluating unchanged code blocks
15561 * sep:: Delimiter for writing tabular results outside Org
15562 * hlines:: Handle horizontal lines in tables
15563 * colnames:: Handle column names in tables
15564 * rownames:: Handle row names in tables
15565 * shebang:: Make tangled files executable
15566 * tangle-mode:: Set permission of tangled files
15567 * eval:: Limit evaluation of specific code blocks
15568 * wrap:: Mark source block evaluation results
15569 * post:: Post processing of results of code block evaluation
15570 * prologue:: Text to prepend to body of code block
15571 * epilogue:: Text to append to body of code block
15574 For language-specific header arguments, see @ref{Languages}.
15577 @subsubsection @code{:var}
15578 @cindex @code{:var}, src header argument
15579 Use @code{:var} for passing arguments to @samp{src} code blocks. The
15580 specifics of variables in @samp{src} code blocks vary by the source language
15581 and are covered in the language-specific documentation. The syntax for
15582 @code{:var}, however, is the same for all languages. This includes declaring
15583 a variable, and assigning a default value.
15585 Arguments can take values as literals, or as references, or even as Emacs
15586 Lisp code (@pxref{var, Emacs Lisp evaluation of variables}). References are
15587 names from the Org file from the lines @code{#+NAME:} or @code{#+RESULTS:}.
15588 References can also refer to tables, lists, @code{#+BEGIN_EXAMPLE} blocks,
15589 other types of @samp{src} code blocks, or the results of execution of
15590 @samp{src} code blocks.
15592 For better performance, Org can cache results of evaluations. But caching
15593 comes with severe limitations (@pxref{cache}).
15595 Argument values are indexed like arrays (@pxref{var, Indexable variable
15598 The following syntax is used to pass arguments to @samp{src} code blocks
15599 using the @code{:var} header argument.
15605 The @code{assign} is a literal value, such as a string @samp{"string"}, a
15606 number @samp{9}, a reference to a table, a list, a literal example, another
15607 code block (with or without arguments), or the results from evaluating a code
15610 Here are examples of passing values by reference:
15615 an Org mode table named with either a @code{#+NAME:} line
15618 #+NAME: example-table
15624 #+NAME: table-length
15625 #+BEGIN_SRC emacs-lisp :var table=example-table
15629 #+RESULTS: table-length
15634 a simple list named with a @code{#+NAME:} line. Note that only the top level
15635 list items are passed along. Nested list items are ignored.
15638 #+NAME: example-list
15644 #+BEGIN_SRC emacs-lisp :var x=example-list
15652 @item code block without arguments
15653 a code block name (from the example above), as assigned by @code{#+NAME:},
15654 optionally followed by parentheses
15657 #+BEGIN_SRC emacs-lisp :var length=table-length()
15665 @item code block with arguments
15666 a @samp{src} code block name, as assigned by @code{#+NAME:}, followed by
15667 parentheses and optional arguments passed within the parentheses following
15668 the @samp{src} code block name using standard function call syntax
15672 #+BEGIN_SRC emacs-lisp :var input=8
15680 #+BEGIN_SRC emacs-lisp :var input=double(input=2)
15688 @item literal example
15689 a literal example block named with a @code{#+NAME:} line
15692 #+NAME: literal-example
15698 #+NAME: read-literal-example
15699 #+BEGIN_SRC emacs-lisp :var x=literal-example
15700 (concatenate 'string x " for you.")
15703 #+RESULTS: read-literal-example
15704 : A literal example
15705 : on two lines for you.
15711 @subsubheading Indexable variable values
15712 Indexing variable values enables referencing portions of a variable. Indexes
15713 are 0 based with negative values counting backwards from the end. If an
15714 index is separated by @code{,}s then each subsequent section will index as
15715 the next dimension. Note that this indexing occurs @emph{before} other
15716 table-related header arguments are applied, such as @code{:hlines},
15717 @code{:colnames} and @code{:rownames}. The following example assigns the
15718 last cell of the first row the table @code{example-table} to the variable
15722 #+NAME: example-table
15728 #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
15736 Ranges of variable values can be referenced using two integers separated by a
15737 @code{:}, in which case the entire inclusive range is referenced. For
15738 example the following assigns the middle three rows of @code{example-table}
15742 #+NAME: example-table
15749 #+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
15759 To pick the entire range, use an empty index, or the single character
15760 @code{*}. @code{0:-1} does the same thing. Example below shows how to
15761 reference the first column only.
15764 #+NAME: example-table
15770 #+BEGIN_SRC emacs-lisp :var data=example-table[,0]
15778 Index referencing can be used for tables and code blocks. Index referencing
15779 can handle any number of dimensions. Commas delimit multiple dimensions, as
15784 #+BEGIN_SRC emacs-lisp
15785 '(((1 2 3) (4 5 6) (7 8 9))
15786 ((10 11 12) (13 14 15) (16 17 18))
15787 ((19 20 21) (22 23 24) (25 26 27)))
15790 #+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
15798 @subsubheading Emacs Lisp evaluation of variables
15800 Emacs lisp code can set the values for variables. To differentiate a value
15801 from lisp code, Org interprets any value starting with @code{(}, @code{[},
15802 @code{'} or @code{`} as Emacs Lisp code. The result of evaluating that code
15803 is then assigned to the value of that variable. The following example shows
15804 how to reliably query and pass file name of the Org mode buffer to a code
15805 block using headers. We need reliability here because the file's name could
15806 change once the code in the block starts executing.
15809 #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
15814 Note that values read from tables and lists will not be mistakenly evaluated
15815 as Emacs Lisp code, as illustrated in the following example.
15821 #+HEADER: :var data=table[0,0]
15831 @subsubsection @code{:results}
15832 @cindex @code{:results}, src header argument
15834 There are four classes of @code{:results} header arguments. Each @samp{src}
15835 code block can take only one option per class.
15839 @b{collection} for how the results should be collected from the @samp{src}
15842 @b{type} for which type of result the code block will return; affects how Org
15843 processes and inserts results in the Org buffer
15845 @b{format} for the result; affects how Org processes and inserts results in
15848 @b{handling} for processing results after evaluation of the @samp{src} code
15852 @subsubheading Collection
15853 Collection options specify the results. Choose one of the options; they are
15854 mutually exclusive.
15858 Default. Functional mode. Result is the value returned by the last
15859 statement in the @samp{src} code block. Languages like Python may require an
15860 explicit @code{return} statement in the @samp{src} code block. Usage
15861 example: @code{:results value}.
15862 @item @code{output}
15863 Scripting mode. Result is collected from STDOUT during execution of the code
15864 in the @samp{src} code block. Usage example: @code{:results output}.
15867 @subsubheading Type
15868 Type tells what result types to expect from the execution of the code
15869 block. Choose one of the options; they are mutually exclusive. The default
15870 behavior is to automatically determine the result type.
15873 @item @code{table}, @code{vector}
15874 Interpret the results as an Org table. If the result is a single value,
15875 create a table with one row and one column. Usage example: @code{:results
15878 Interpret the results as an Org list. If the result is a single value,
15879 create a list of one element.
15880 @item @code{scalar}, @code{verbatim}
15881 Interpret literally and insert as quoted text. Do not create a table. Usage
15882 example: @code{:results value verbatim}.
15884 Interpret as path to a file. Inserts a link to the file. Usage example:
15885 @code{:results value file}.
15888 @subsubheading Format
15889 Format pertains to the type of the result returned by the @samp{src} code
15890 block. Choose one of the options; they are mutually exclusive. The default
15891 follows from the type specified above.
15895 Interpreted as raw Org mode. Inserted directly into the buffer. Aligned if
15896 it is a table. Usage example: @code{:results value raw}.
15898 Results enclosed in a @code{BEGIN_SRC org} block. For comma-escape, either
15899 @kbd{TAB} in the block, or export the file. Usage example: @code{:results
15902 Results enclosed in a @code{BEGIN_EXPORT html} block. Usage example:
15903 @code{:results value html}.
15905 Results enclosed in a @code{BEGIN_EXPORT latex} block. Usage example:
15906 @code{:results value latex}.
15908 Result enclosed in a @samp{src} code block. Useful for parsing. Usage
15909 example: @code{:results value code}.
15911 Result converted to pretty-print source code. Enclosed in a @samp{src} code
15912 block. Languages supported: Emacs Lisp, Python, and Ruby. Usage example:
15913 @code{:results value pp}.
15914 @item @code{drawer}
15915 Result wrapped in a RESULTS drawer. Useful for containing @code{raw} or
15916 @code{org} results for later scripting and automated processing. Usage
15917 example: @code{:results value drawer}.
15920 @subsubheading Handling
15921 Handling options after collecting the results.
15924 @item @code{silent}
15925 Do not insert results in the Org mode buffer, but echo them in the
15926 minibuffer. Usage example: @code{:results output silent}.
15927 @item @code{replace}
15928 Default. Insert results in the Org buffer. Remove previous results. Usage
15929 example: @code{:results output replace}.
15930 @item @code{append}
15931 Append results to the Org buffer. Latest results are at the bottom. Does
15932 not remove previous results. Usage example: @code{:results output append}.
15933 @item @code{prepend}
15934 Prepend results to the Org buffer. Latest results are at the top. Does not
15935 remove previous results. Usage example: @code{:results output prepend}.
15939 @subsubsection @code{:file}
15940 @cindex @code{:file}, src header argument
15942 An external @code{:file} that saves the results of execution of the code
15943 block. The @code{:file} is either a file name or two strings, where the
15944 first is the file name and the second is the description. A link to the file
15945 is inserted. It uses an Org mode style @code{[[file:]]} link (@pxref{Link
15946 format}). Some languages, such as @samp{R}, @samp{dot}, @samp{ditaa}, and
15947 @samp{gnuplot}, automatically wrap the source code in additional boilerplate
15948 code. Such code wrapping helps recreate the output, especially graphics
15949 output, by executing just the @code{:file} contents.
15952 @subsubsection @code{:file-desc}
15954 A description of the results file. Org uses this description for the link
15955 (see @ref{Link format}) it inserts in the Org file. If the @code{:file-desc}
15956 has no value, Org will use file name for both the ``link'' and the
15957 ``description'' portion of the Org mode link.
15960 @subsubsection @code{:file-ext}
15961 @cindex @code{:file-ext}, src header argument
15963 File name extension for the output file. Org generates the file's complete
15964 name, and extension by combining @code{:file-ext}, @code{#+NAME:} of the
15965 source block, and the @ref{output-dir} header argument. To override this
15966 auto generated file name, use the @code{:file} header argument.
15969 @subsubsection @code{:output-dir}
15970 @cindex @code{:output-dir}, src header argument
15972 Specifies the @code{:output-dir} for the results file. Org accepts an
15973 absolute path (beginning with @code{/}) or a relative directory (without
15974 @code{/}). The value can be combined with @code{#+NAME:} of the source block
15975 and @ref{file} or @ref{file-ext} header arguments.
15978 @subsubsection @code{:dir} and remote execution
15979 @cindex @code{:dir}, src header argument
15981 While the @code{:file} header argument can be used to specify the path to the
15982 output file, @code{:dir} specifies the default directory during @samp{src}
15983 code block execution. If it is absent, then the directory associated with
15984 the current buffer is used. In other words, supplying @code{:dir path}
15985 temporarily has the same effect as changing the current directory with
15986 @kbd{M-x cd path RET}, and then not supplying @code{:dir}. Under the
15987 surface, @code{:dir} simply sets the value of the Emacs variable
15988 @code{default-directory}.
15990 When using @code{:dir}, relative paths (for example, @code{:file myfile.jpg}
15991 or @code{:file results/myfile.jpg}) become relative to the default directory.
15993 For example, to save the plot file in the @samp{Work} folder of the home
15994 directory (notice tilde is expanded):
15997 #+BEGIN_SRC R :file myplot.png :dir ~/Work
15998 matplot(matrix(rnorm(100), 10), type="l")
16002 @subsubheading Remote execution
16003 To evaluate the @samp{src} code block on a remote machine, supply a remote s
16004 directory name using @samp{Tramp} syntax. For example:
16007 #+BEGIN_SRC R :file plot.png :dir /scp:dand@@yakuba.princeton.edu:
16008 plot(1:10, main=system("hostname", intern=TRUE))
16012 Org first captures the text results as usual for insertion in the Org file.
16013 Then Org also inserts a link to the remote file, thanks to Emacs
16014 @samp{Tramp}. Org constructs the remote path to the file name from
16015 @code{:dir} and @code{default-directory}, as illustrated here:
16018 [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
16022 @subsubheading Some more warnings
16026 When @code{:dir} is used with @code{:session}, Org sets the starting
16027 directory for a new session. But Org will not alter the directory of an
16028 already existing session.
16030 Do not use @code{:dir} with @code{:exports results} or with @code{:exports
16031 both} to avoid Org inserting incorrect links to remote files. That is because
16032 Org does not expand @code{default directory} to avoid some underlying
16033 portability issues.
16037 @subsubsection @code{:exports}
16038 @cindex @code{:exports}, src header argument
16040 The @code{:exports} header argument is to specify if that part of the Org
16041 file is exported to, say, HTML or @LaTeX{} formats. Note that
16042 @code{:exports} affects only @samp{src} code blocks and not inline code.
16046 The default. The body of code is included into the exported file. Example:
16047 @code{:exports code}.
16048 @item @code{results}
16049 The results of evaluation of the code is included in the exported file.
16050 Example: @code{:exports results}.
16052 Both the code and results of evaluation are included in the exported file.
16053 Example: @code{:exports both}.
16055 Neither the code nor the results of evaluation is included in the exported
16056 file. Whether the code is evaluated at all depends on other
16057 options. Example: @code{:exports none}.
16061 @subsubsection @code{:tangle}
16062 @cindex @code{:tangle}, src header argument
16064 The @code{:tangle} header argument specifies if the @samp{src} code block is
16065 exported to source file(s).
16068 @item @code{tangle}
16069 Export the @samp{src} code block to source file. The file name for the
16070 source file is derived from the name of the Org file, and the file extension
16071 is derived from the source code language identifier. Example: @code{:tangle
16074 The default. Do not extract the code a source code file. Example:
16077 Export the @samp{src} code block to source file whose file name is derived
16078 from any string passed to the @code{:tangle} header argument. Org derives
16079 the file name as being relative to the directory of the Org file's location.
16080 Example: @code{:tangle path}.
16084 @subsubsection @code{:mkdirp}
16085 @cindex @code{:mkdirp}, src header argument
16087 The @code{:mkdirp} header argument creates parent directories for tangled
16088 files if the directory does not exist. @code{yes} enables directory creation
16089 and @code{no} inhibits directory creation.
16092 @subsubsection @code{:comments}
16093 @cindex @code{:comments}, src header argument
16094 Controls inserting comments into tangled files. These are above and beyond
16095 whatever comments may already exist in the @samp{src} code block.
16099 The default. Do not insert any extra comments during tangling.
16101 Wrap the @samp{src} code block in comments. Include links pointing back to
16102 the place in the Org file from where the code was tangled.
16104 Kept for backward compatibility; same as ``link''.
16106 Nearest headline text from Org file is inserted as comment. The exact text
16107 that is inserted is picked from the leading context of the source block.
16109 Includes both ``link'' and ``org'' comment options.
16111 Includes ``link'' comment option, expands noweb references, and wraps them in
16112 link comments inside the body of the @samp{src} code block.
16116 @subsubsection @code{:padline}
16117 @cindex @code{:padline}, src header argument
16118 Control insertion of newlines to pad @samp{src} code blocks in the tangled
16122 Default. Insert a newline before and after each @samp{src} code block in the
16125 Do not insert newlines to pad the tangled @samp{src} code blocks.
16129 @subsubsection @code{:no-expand}
16130 @cindex @code{:no-expand}, src header argument
16132 By default Org expands @samp{src} code blocks during tangling. The
16133 @code{:no-expand} header argument turns off such expansions. Note that one
16134 side-effect of expansion by @code{org-babel-expand-src-block} also assigns
16135 values to @code{:var} (@pxref{var}) variables. Expansions also replace
16136 ``noweb'' references with their targets (@pxref{Noweb reference syntax}).
16137 Some of these expansions may cause premature assignment, hence this option.
16138 This option makes a difference only for tangling. It has no effect when
16139 exporting since @samp{src} code blocks for execution have to be expanded
16143 @subsubsection @code{:session}
16144 @cindex @code{:session}, src header argument
16146 The @code{:session} header argument is for running multiple source code
16147 blocks under one session. Org runs @samp{src} code blocks with the same
16148 session name in the same interpreter process.
16152 Default. Each @samp{src} code block gets a new interpreter process to
16153 execute. The process terminates once the block is evaluated.
16155 Any string besides @code{none} turns that string into the name of that
16156 session. For example, @code{:session mysession} names it @samp{mysession}.
16157 If @code{:session} has no argument, then the session name is derived from the
16158 source language identifier. Subsequent blocks with the same source code
16159 language use the same session. Depending on the language, state variables,
16160 code from other blocks, and the overall interpreted environment may be
16161 shared. Some interpreted languages support concurrent sessions when
16162 subsequent source code language blocks change session names.
16166 @subsubsection @code{:noweb}
16167 @cindex @code{:noweb}, src header argument
16169 The @code{:noweb} header argument controls expansion of ``noweb'' syntax
16170 references (@pxref{Noweb reference syntax}). Expansions occur when source
16171 code blocks are evaluated, tangled, or exported.
16175 Default. No expansion of ``Noweb'' syntax references in the body of the code
16176 when evaluating, tangling, or exporting.
16178 Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
16179 block when evaluating, tangling, or exporting.
16180 @item @code{tangle}
16181 Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
16182 block when tangling. No expansion when evaluating or exporting.
16183 @item @code{no-export}
16184 Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
16185 block when evaluating or tangling. No expansion when exporting.
16186 @item @code{strip-export}
16187 Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
16188 block when expanding prior to evaluating or tangling. Removes ``noweb''
16189 syntax references when exporting.
16191 Expansion of ``Noweb'' syntax references in the body of the @samp{src} code
16192 block only before evaluating.
16195 @subsubheading Noweb prefix lines
16196 Noweb insertions now honor prefix characters that appear before
16197 @code{<<reference>>}. This behavior is illustrated in the following example.
16198 Because the @code{<<example>>} noweb reference appears behind the SQL comment
16199 syntax, each line of the expanded noweb reference will be commented.
16201 This @samp{src} code block:
16211 -- multi-line body of example
16214 Since this change will not affect noweb replacement text without newlines in
16215 them, inline noweb references are acceptable.
16218 @subsubsection @code{:noweb-ref}
16219 @cindex @code{:noweb-ref}, src header argument
16221 When expanding ``noweb'' style references, Org concatenates @samp{src} code
16222 blocks by matching the reference name to either the block name or the
16223 @code{:noweb-ref} header argument.
16225 For simple concatenation, set this @code{:noweb-ref} header argument at the
16226 sub-tree or file level. In the example Org file shown next, the body of the
16227 source code in each block is extracted for concatenation to a pure code file.
16230 #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
16233 * the mount point of the fullest disk
16235 :header-args: :noweb-ref fullest-disk
16238 ** query all mounted disks
16243 ** strip the header row
16248 ** output mount point of fullest disk
16250 |awk '@{if (u < +$5) @{u = +$5; m = $6@}@} END @{print m@}'
16255 @subsubsection @code{:noweb-sep}
16256 @cindex @code{:noweb-sep}, src header argument
16258 By default a newline separates each noweb reference concatenation. To change
16259 this newline separator, edit the @code{:noweb-sep} (@pxref{noweb-sep}) header
16263 @subsubsection @code{:cache}
16264 @cindex @code{:cache}, src header argument
16266 The @code{:cache} header argument is for caching results of evaluating code
16267 blocks. Caching results can avoid re-evaluating @samp{src} code blocks that
16268 have not changed since the previous run. To benefit from the cache and avoid
16269 redundant evaluations, the source block must have a result already present in
16270 the buffer, and neither the header arguments (including the value of
16271 @code{:var} references) nor the text of the block itself has changed since
16272 the result was last computed. This feature greatly helps avoid long-running
16273 calculations. For some edge cases, however, the cached results may not be
16276 The caching feature is best for when @samp{src} blocks are pure functions,
16277 that is functions that return the same value for the same input arguments
16278 (@pxref{var}), and that do not have side effects, and do not rely on external
16279 variables other than the input arguments. Functions that depend on a timer,
16280 file system objects, and random number generators are clearly unsuitable for
16283 A note of warning: when @code{:cache} is used for a @code{:session}, caching
16284 may cause unexpected results.
16286 When the caching mechanism tests for any source code changes, it will not
16287 expand ``noweb'' style references (@pxref{Noweb reference syntax}). For
16288 reasons why, see @uref{http://thread.gmane.org/gmane.emacs.orgmode/79046}.
16290 The @code{:cache} header argument can have one of two values: @code{yes} or
16295 Default. No caching of results; @samp{src} code block evaluated every time.
16297 Whether to run the code or return the cached results is determined by
16298 comparing the SHA1 hash value of the combined @samp{src} code block and
16299 arguments passed to it. This hash value is packed on the @code{#+RESULTS:}
16300 line from previous evaluation. When hash values match, Org does not evaluate
16301 the @samp{src} code block. When hash values mismatch, Org evaluates the
16302 @samp{src} code block, inserts the results, recalculates the hash value, and
16303 updates @code{#+RESULTS:} line.
16306 In this example, both functions are cached. But @code{caller} runs only if
16307 the result from @code{random} has changed since the last run.
16311 #+BEGIN_SRC R :cache yes
16315 #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
16319 #+BEGIN_SRC emacs-lisp :var x=random :cache yes
16323 #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
16328 @subsubsection @code{:sep}
16329 @cindex @code{:sep}, src header argument
16331 The @code{:sep} header argument is the delimiter for saving results as tables
16332 to files (@pxref{file}) external to Org mode. Org defaults to tab delimited
16333 output. The function, @code{org-open-at-point}, which is bound to @kbd{C-c
16334 C-o}, also uses @code{:sep} for opening tabular results.
16337 @subsubsection @code{:hlines}
16338 @cindex @code{:hlines}, src header argument
16340 In-between each table row or below the table headings, sometimes results have
16341 horizontal lines, which are also known as hlines. The @code{:hlines}
16342 argument with the value @code{yes} accepts such lines. The default is
16347 Strips horizontal lines from the input table. For most code, this is
16348 desirable, or else those @code{hline} symbols raise unbound variable errors.
16350 The default is @code{:hlines no}. The example shows hlines removed from the
16362 #+BEGIN_SRC python :var tab=many-cols
16366 #+RESULTS: echo-table
16373 For @code{:hlines yes}, the example shows hlines unchanged.
16384 #+BEGIN_SRC python :var tab=many-cols :hlines yes
16388 #+RESULTS: echo-table
16398 @subsubsection @code{:colnames}
16399 @cindex @code{:colnames}, src header argument
16401 The @code{:colnames} header argument accepts @code{yes}, @code{no}, or
16402 @code{nil} values. The default value is @code{nil}, which is unassigned.
16403 But this header argument behaves differently depending on the source code
16408 If an input table has column names (because the second row is an hline), then
16409 Org removes the column names, processes the table, puts back the column
16410 names, and then writes the table to the results block.
16419 #+NAME: echo-table-again
16420 #+BEGIN_SRC python :var tab=less-cols
16421 return [[val + '*' for val in row] for row in tab]
16424 #+RESULTS: echo-table-again
16431 Note that column names have to accounted for when using variable indexing
16432 (@pxref{var, Indexable variable values}) because column names are not removed
16436 Do not pre-process column names.
16439 For an input table that has no hlines, process it like the @code{nil}
16440 value. That is, Org removes the column names, processes the table, puts back
16441 the column names, and then writes the table to the results block.
16445 @subsubsection @code{:rownames}
16446 @cindex @code{:rownames}, src header argument
16448 The @code{:rownames} header argument can take on values @code{yes} or
16449 @code{no} values. The default is @code{no}. Note that @code{emacs-lisp}
16450 code blocks ignore @code{:rownames} header argument because of the ease of
16451 table-handling in Emacs.
16455 Org will not pre-process row names.
16458 If an input table has row names, then Org removes the row names, processes
16459 the table, puts back the row names, and then writes the table to the results
16463 #+NAME: with-rownames
16464 | one | 1 | 2 | 3 | 4 | 5 |
16465 | two | 6 | 7 | 8 | 9 | 10 |
16467 #+NAME: echo-table-once-again
16468 #+BEGIN_SRC python :var tab=with-rownames :rownames yes
16469 return [[val + 10 for val in row] for row in tab]
16472 #+RESULTS: echo-table-once-again
16473 | one | 11 | 12 | 13 | 14 | 15 |
16474 | two | 16 | 17 | 18 | 19 | 20 |
16477 Note that row names have to accounted for when using variable indexing
16478 (@pxref{var, Indexable variable values}) because row names are not removed
16484 @subsubsection @code{:shebang}
16485 @cindex @code{:shebang}, src header argument
16487 This header argument can turn results into executable script files. By
16488 setting the @code{:shebang} header argument to a string value (for example,
16489 @code{:shebang "#!/bin/bash"}), Org inserts that string as the first line of
16490 the tangled file that the @samp{src} code block is extracted to. Org then
16491 turns on the tangled file's executable permission.
16494 @subsubsection @code{:tangle-mode}
16495 @cindex @code{:tangle-mode}, src header argument
16497 The @code{tangle-mode} header argument specifies what permissions to set for
16498 tangled files by @code{set-file-modes}. For example, to make read-only
16499 tangled file, use @code{:tangle-mode (identity #o444)}. To make it
16500 executable, use @code{:tangle-mode (identity #o755)}.
16502 On @samp{src} code blocks with @code{shebang} (@pxref{shebang}) header
16503 argument, Org will automatically set the tangled file to executable
16504 permissions. But this can be overridden with custom permissions using
16505 @code{tangle-mode} header argument.
16507 When multiple @samp{src} code blocks tangle to a single file with different
16508 and conflicting @code{tangle-mode} header arguments, Org's behavior is
16512 @subsubsection @code{:eval}
16513 @cindex @code{:eval}, src header argument
16514 The @code{:eval} header argument can limit evaluation of specific code
16515 blocks. It is useful for protection against evaluating untrusted @samp{src}
16516 code blocks by prompting for a confirmation. This protection is independent
16517 of the @code{org-confirm-babel-evaluate} setting.
16521 Org will never evaluate this @samp{src} code block.
16523 Org prompts the user for permission to evaluate this @samp{src} code block.
16524 @item never-export or no-export
16525 Org will not evaluate this @samp{src} code block when exporting, yet the user
16526 can evaluate this source block interactively.
16528 Org prompts the user for permission to export this @samp{src} code block.
16531 If @code{:eval} header argument is not set for a source block, then Org
16532 determines whether to evaluate from the @code{org-confirm-babel-evaluate}
16533 variable (@pxref{Code evaluation security}).
16536 @subsubsection @code{:wrap}
16537 @cindex @code{:wrap}, src header argument
16538 The @code{:wrap} header argument marks the results block by appending strings
16539 to @code{#+BEGIN_} and @code{#+END_}. If no string is specified, Org wraps
16540 the results in a @code{#+BEGIN/END_RESULTS} block.
16543 @subsubsection @code{:post}
16544 @cindex @code{:post}, src header argument
16545 The @code{:post} header argument is for post-processing results from
16546 @samp{src} block evaluation. When @code{:post} has any value, Org binds the
16547 results to @code{*this*} variable for easy passing to @ref{var} header
16548 argument specifications. That makes results available to other @samp{src}
16549 code blocks, or for even direct Emacs Lisp code execution.
16551 The following two examples illustrate @code{:post} header argument in action.
16552 The first one shows how to attach @code{#+ATTR_LATEX:} line using
16557 #+begin_src sh :var data="" :var width="\\textwidth" :results output
16558 echo "#+ATTR_LATEX: :width $width"
16562 #+header: :file /tmp/it.png
16563 #+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer
16573 #+ATTR_LATEX :width 5cm
16574 [[file:/tmp/it.png]]
16578 The second example shows use of @code{:colnames} in @code{:post} to pass
16579 data between @samp{src} code blocks.
16583 #+begin_src emacs-lisp :var tbl="" fmt="%.3f"
16584 (mapcar (lambda (row)
16585 (mapcar (lambda (cell)
16593 #+begin_src R :colnames yes :post round-tbl[:colnames yes](*this*)
16595 data.frame(foo=rnorm(1))
16605 @subsubsection @code{:prologue}
16606 @cindex @code{:prologue}, src header argument
16607 The @code{prologue} header argument is for appending to the top of the code
16608 block for execution. For example, a clear or reset code at the start of new
16609 execution of a @samp{src} code block. A @code{reset} for @samp{gnuplot}:
16610 @code{:prologue "reset"}. See also @ref{epilogue}.
16613 (add-to-list 'org-babel-default-header-args:gnuplot
16614 '((:prologue . "reset")))
16618 @subsubsection @code{:epilogue}
16619 @cindex @code{:epilogue}, src header argument
16620 The value of the @code{epilogue} header argument is for appending to the end
16621 of the code block for execution. See also @ref{prologue}.
16623 @node Results of evaluation
16624 @section Results of evaluation
16625 @cindex code block, results of evaluation
16626 @cindex source code, results of evaluation
16628 How Org handles results of a code block execution depends on many header
16629 arguments working together. Here is only a summary of these. For an
16630 enumeration of all the header arguments that affect results, see
16633 The primary determinant is the execution context. Is it in a @code{:session}
16634 or not? Orthogonal to that is if the expected result is a @code{:results
16635 value} or @code{:results output}, which is a concatenation of output from
16636 start to finish of the @samp{src} code block's evaluation.
16638 @multitable @columnfractions 0.26 0.33 0.41
16639 @item @tab @b{Non-session} @tab @b{Session}
16640 @item @code{:results value} @tab value of last expression @tab value of last expression
16641 @item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output
16644 For @code{:session} and non-session, the @code{:results value} turns the
16645 results into an Org mode table format. Single values are wrapped in a one
16646 dimensional vector. Rows and columns of a table are wrapped in a
16647 two-dimensional vector.
16649 @subsection Non-session
16650 @subsubsection @code{:results value}
16651 @cindex @code{:results}, src header argument
16652 Default. Org gets the value by wrapping the code in a function definition in
16653 the language of the @samp{src} block. That is why when using @code{:results
16654 value}, code should execute like a function and return a value. For
16655 languages like Python, an explicit @code{return} statement is mandatory when
16656 using @code{:results value}.
16658 This is one of four evaluation contexts where Org automatically wraps the
16659 code in a function definition.
16661 @subsubsection @code{:results output}
16662 @cindex @code{:results}, src header argument
16663 For @code{:results output}, the code is passed to an external process running
16664 the interpreter. Org returns the contents of the standard output stream as
16667 @subsection Session
16668 @subsubsection @code{:results value}
16669 @cindex @code{:results}, src header argument
16670 For @code{:results value} from a @code{:session}, Org passes the code to an
16671 interpreter running as an interactive Emacs inferior process. So only
16672 languages that provide interactive evaluation can have session support. Not
16673 all languages provide this support, such as @samp{C} and @samp{ditaa}. Even
16674 those that do support, such as @samp{Python} and @samp{Haskell}, they impose
16675 limitations on allowable language constructs that can run interactively. Org
16676 inherits those limitations for those @samp{src} code blocks running in a
16679 Org gets the value from the source code interpreter's last statement
16680 output. Org has to use language-specific methods to obtain the value. For
16681 example, from the variable @code{_} in @samp{Python} and @samp{Ruby}, and the
16682 value of @code{.Last.value} in @samp{R}).
16684 @subsubsection @code{:results output}
16685 @cindex @code{:results}, src header argument
16686 For @code{:results output}, Org passes the code to the interpreter running as
16687 an interactive Emacs inferior process. Org concatenates whatever text output
16688 emitted by the interpreter to return the collection as a result. Note that
16689 this collection is not the same as collected from @code{STDOUT} of a
16690 non-interactive interpreter running as an external process. Compare for
16691 example these two blocks:
16694 #+BEGIN_SRC python :results output
16705 In the above non-session mode, the ``2'' is not printed; so does not appear
16709 #+BEGIN_SRC python :results output :session
16721 In the above @code{:session} mode, the interactive interpreter receives and
16722 prints ``2''. Results show that.
16724 @node Noweb reference syntax
16725 @section Noweb reference syntax
16726 @cindex code block, noweb reference
16727 @cindex syntax, noweb
16728 @cindex source code, noweb reference
16730 Org supports named blocks in ``noweb'' style syntax. For ``noweb'' literate
16731 programming details, see @uref{http://www.cs.tufts.edu/~nr/noweb/}).
16734 <<code-block-name>>
16737 For the header argument @code{:noweb yes}, Org expands ``noweb'' style
16738 references in the @samp{src} code block before evaluation.
16740 For the header argument @code{:noweb no}, Org does not expand ``noweb'' style
16741 references in the @samp{src} code block before evaluation.
16743 The default is @code{:noweb no}.
16745 Org offers a more flexible way to resolve ``noweb'' style references
16746 (@pxref{noweb-ref}).
16748 Org can handle naming of @emph{results} block, rather than the body of the
16749 @samp{src} code block, using ``noweb'' style references.
16751 For ``noweb'' style reference, append parenthesis to the code block name for
16752 arguments, as shown in this example:
16755 <<code-block-name(optional arguments)>>
16758 Note: Org defaults to @code{:noweb no} so as not to cause errors in languages
16759 such as @samp{Ruby} where ``noweb'' syntax is equally valid characters. For
16760 example, @code{<<arg>>}. Change Org's default to @code{:noweb yes} for
16761 languages where there is no risk of confusion.
16763 For faster tangling of large Org mode files, set
16764 @code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}.
16765 The speedup comes at the expense of not correctly resolving inherited values
16766 of the @code{:noweb-ref} header argument.
16769 @node Key bindings and useful functions
16770 @section Key bindings and useful functions
16771 @cindex code block, key bindings
16773 Many common Org mode key sequences are re-bound depending on the context.
16775 Active key bindings in code blocks:
16777 @multitable @columnfractions 0.25 0.75
16779 @item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block}
16781 @item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result}
16783 @item @kbd{M-@key{up}} @tab @code{org-babel-load-in-session}
16785 @item @kbd{M-@key{down}} @tab @code{org-babel-switch-to-session}
16788 Active key bindings in Org mode buffer:
16790 @multitable @columnfractions 0.5 0.5
16792 @kindex C-c C-v C-p
16793 @item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block}
16795 @kindex C-c C-v C-n
16796 @item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block}
16798 @kindex C-c C-v C-e
16799 @item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe}
16801 @kindex C-c C-v C-o
16802 @item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result}
16804 @kindex C-c C-v C-v
16805 @item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block}
16807 @kindex C-c C-v C-u
16808 @item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head}
16810 @kindex C-c C-v C-g
16811 @item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block}
16813 @kindex C-c C-v C-r
16814 @item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result}
16816 @kindex C-c C-v C-b
16817 @item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
16819 @kindex C-c C-v C-s
16820 @item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
16822 @kindex C-c C-v C-d
16823 @item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block}
16825 @kindex C-c C-v C-t
16826 @item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
16828 @kindex C-c C-v C-f
16829 @item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
16831 @kindex C-c C-v C-c
16832 @item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block}
16834 @kindex C-c C-v C-j
16835 @item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg}
16837 @kindex C-c C-v C-l
16838 @item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session}
16840 @kindex C-c C-v C-i
16841 @item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest}
16843 @kindex C-c C-v C-I
16844 @item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info}
16846 @kindex C-c C-v C-z
16847 @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}
16849 @kindex C-c C-v C-a
16850 @item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
16852 @kindex C-c C-v C-h
16853 @item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings}
16855 @kindex C-c C-v C-x
16856 @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}
16859 @c Extended key bindings when control key is kept pressed:
16861 @c @multitable @columnfractions 0.25 0.75
16862 @c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
16863 @c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
16864 @c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
16865 @c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
16866 @c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
16867 @c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
16868 @c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
16869 @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
16872 @node Batch execution
16873 @section Batch execution
16874 @cindex code block, batch execution
16875 @cindex source code, batch execution
16877 Org mode features, including working with source code facilities can be
16878 invoked from the command line. This enables building shell scripts for batch
16879 processing, running automated system tasks, and expanding Org mode's
16882 The sample script shows batch processing of multiple files using
16883 @code{org-babel-tangle}.
16887 # -*- mode: shell-script -*-
16889 # tangle files with org-mode
16894 # wrap each argument in the code required to call tangle on it
16896 FILES="$FILES \"$i\""
16901 (require 'org)(require 'ob)(require 'ob-tangle)
16902 (mapc (lambda (file)
16903 (find-file (expand-file-name file \"$DIR\"))
16905 (kill-buffer)) '($FILES)))" 2>&1 |grep -i tangled
16908 @node Miscellaneous
16909 @chapter Miscellaneous
16912 * Completion:: M-TAB guesses completions
16913 * Easy templates:: Quick insertion of structural elements
16914 * Speed keys:: Electric commands at the beginning of a headline
16915 * Code evaluation security:: Org mode files evaluate inline code
16916 * Customization:: Adapting Org to changing tastes
16917 * In-buffer settings:: Overview of the #+KEYWORDS
16918 * The very busy C-c C-c key:: When in doubt, press C-c C-c
16919 * Clean view:: Getting rid of leading stars in the outline
16920 * TTY keys:: Using Org on a tty
16921 * Interaction:: With other Emacs packages
16922 * org-crypt:: Encrypting Org files
16927 @section Completion
16928 @cindex completion, of @TeX{} symbols
16929 @cindex completion, of TODO keywords
16930 @cindex completion, of dictionary words
16931 @cindex completion, of option keywords
16932 @cindex completion, of tags
16933 @cindex completion, of property keys
16934 @cindex completion, of link abbreviations
16935 @cindex @TeX{} symbol completion
16936 @cindex TODO keywords completion
16937 @cindex dictionary word completion
16938 @cindex option keyword completion
16939 @cindex tag completion
16940 @cindex link abbreviations, completion of
16942 Org has in-buffer completions. Unlike minibuffer completions, which are
16943 useful for quick command interactions, Org's in-buffer completions are more
16944 suitable for content creation in Org documents. Type one or more letters and
16945 invoke the hot key to complete the text in-place. Depending on the context
16946 and the keys, Org will offer different types of completions. No minibuffer
16947 is involved. Such mode-specific hot keys have become an integral part of
16948 Emacs and Org provides several shortcuts.
16951 @kindex M-@key{TAB}
16953 Complete word at point
16956 At the beginning of a headline, complete TODO keywords.
16958 After @samp{\}, complete @TeX{} symbols supported by the exporter.
16960 After @samp{*}, complete headlines in the current buffer so that they
16961 can be used in search links like @samp{[[*find this headline]]}.
16963 After @samp{:} in a headline, complete tags. The list of tags is taken
16964 from the variable @code{org-tag-alist} (possibly set through the
16965 @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
16966 dynamically from all tags used in the current buffer.
16968 After @samp{:} and not in a headline, complete property keys. The list
16969 of keys is constructed dynamically from all keys used in the current
16972 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
16974 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
16975 file-specific @samp{OPTIONS}. After option keyword is complete, pressing
16976 @kbd{M-@key{TAB}} again will insert example settings for that option.
16978 After @samp{#+STARTUP: }, complete startup keywords.
16980 When the point is anywhere else, complete dictionary words using Ispell.
16983 If your desktop intercepts the combo @kbd{M-@key{TAB}} to switch windows, use
16984 @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} as an alternative or customize your
16988 @node Easy templates
16989 @section Easy templates
16990 @cindex template insertion
16991 @cindex insertion, of templates
16993 With just a few keystrokes, Org's easy templates inserts empty pairs of
16994 structural elements, such as @code{#+BEGIN_SRC} and @code{#+END_SRC}. Easy
16995 templates use an expansion mechanism, which is native to Org, in a process
16996 similar to @file{yasnippet} and other Emacs template expansion packages.
16998 @kbd{@key{<}} @kbd{@key{s}} @kbd{@key{TAB}} completes the @samp{src} code
17001 @kbd{<} @kbd{l} @kbd{@key{TAB}}
17005 #+BEGIN_EXPORT latex
17009 Org comes with these pre-defined easy templates:
17011 @multitable @columnfractions 0.1 0.9
17012 @item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC}
17013 @item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
17014 @item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE}
17015 @item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE}
17016 @item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER}
17017 @item @kbd{l} @tab @code{#+BEGIN_EXPORT latex ... #+END_EXPORT}
17018 @item @kbd{L} @tab @code{#+LATEX:}
17019 @item @kbd{h} @tab @code{#+BEGIN_EXPORT html ... #+END_EXPORT}
17020 @item @kbd{H} @tab @code{#+HTML:}
17021 @item @kbd{a} @tab @code{#+BEGIN_EXPORT ascii ... #+END_EXPORT}
17022 @item @kbd{A} @tab @code{#+ASCII:}
17023 @item @kbd{i} @tab @code{#+INDEX:} line
17024 @item @kbd{I} @tab @code{#+INCLUDE:} line
17027 More templates can added by customizing the variable
17028 @code{org-structure-template-alist}, whose docstring has additional details.
17031 @section Speed keys
17034 Single keystrokes can execute custom commands in an Org file when the cursor
17035 is on a headline. Without the extra burden of a meta or modifier key, Speed
17036 Keys can speed navigation or execute custom commands. Besides faster
17037 navigation, Speed Keys may come in handy on small mobile devices that do not
17038 have full keyboards. Speed Keys may also work on TTY devices known for their
17039 problems when entering Emacs keychords.
17041 @vindex org-use-speed-commands
17042 By default, Org has Speed Keys disabled. To activate Speed Keys, set the
17043 variable @code{org-use-speed-commands} to a non-@code{nil} value. To trigger
17044 a Speed Key, the cursor must be at the beginning of an Org headline, before
17047 @vindex org-speed-commands-user
17048 @findex org-speed-command-help
17049 Org comes with a pre-defined list of Speed Keys. To add or modify Speed
17050 Keys, customize the variable, @code{org-speed-commands-user}. For more
17051 details, see the variable's docstring. With Speed Keys activated, @kbd{M-x
17052 org-speed-command-help}, or @kbd{?} when cursor is at the beginning of an Org
17053 headline, shows currently active Speed Keys, including the user-defined ones.
17056 @node Code evaluation security
17057 @section Code evaluation and security issues
17059 Unlike plain text, running code comes with risk. Each @samp{src} code block,
17060 in terms of risk, is equivalent to an executable file. Org therefore puts a
17061 few confirmation prompts by default. This is to alert the casual user from
17062 accidentally running untrusted code.
17064 For users who do not run code blocks or write code regularly, Org's default
17065 settings should suffice. However, some users may want to tweak the prompts
17066 for fewer interruptions. To weigh the risks of automatic execution of code
17067 blocks, here are some details about code evaluation.
17069 Org evaluates code in the following circumstances:
17072 @item Source code blocks
17073 Org evaluates @samp{src} code blocks in an Org file during export. Org also
17074 evaluates a @samp{src} code block with the @kbd{C-c C-c} key chord. Users
17075 exporting or running code blocks must load files only from trusted sources.
17076 Be weary of customizing variables that remove or alter default security
17079 @defopt org-confirm-babel-evaluate
17080 When @code{t}, Org prompts the user for confirmation before executing each
17081 code block. When @code{nil}, Org executes code blocks without prompting the
17082 user for confirmation. When this option is set to a custom function, Org
17083 invokes the function with these two arguments: the source code language and
17084 the body of the code block. The custom function must return either a
17085 @code{t} or @code{nil}, which determines if the user is prompted. Each
17086 source code language can be handled separately through this function
17090 For example, this function enables execution of @samp{ditaa} code +blocks
17094 (defun my-org-confirm-babel-evaluate (lang body)
17095 (not (string= lang "ditaa"))) ; don't ask for ditaa
17096 (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
17099 @item Following @code{shell} and @code{elisp} links
17100 Org has two link types that can also directly evaluate code (@pxref{External
17101 links}). Because such code is not visible, these links have a potential
17102 risk. Org therefore prompts the user when it encounters such links. The
17103 customization variables are:
17105 @defopt org-confirm-shell-link-function
17106 Function that prompts the user before executing a shell link.
17108 @defopt org-confirm-elisp-link-function
17109 Function that prompts the user before executing an Emacs Lisp link.
17112 @item Formulas in tables
17113 Org executes formulas in tables (@pxref{The spreadsheet}) either through the
17114 @emph{calc} or the @emph{Emacs Lisp} interpreters.
17117 @node Customization
17118 @section Customization
17119 @cindex customization
17120 @cindex options, for customization
17121 @cindex variables, for customization
17123 Org has more than 500 variables for customization. They can be accessed
17124 through the usual @kbd{M-x org-customize RET} command. Or through the Org
17125 menu, @code{Org->Customization->Browse Org Group}. Org also has per-file
17126 settings for some variables (@pxref{In-buffer settings}).
17128 @node In-buffer settings
17129 @section Summary of in-buffer settings
17130 @cindex in-buffer settings
17131 @cindex special keywords
17132 In-buffer settings start with @samp{#+}, followed by a keyword, a colon, and
17133 then a word for each setting. Org accepts multiple settings on the same
17134 line. Org also accepts multiple lines for a keyword. This manual describes
17135 these settings throughout. A summary follows here.
17137 @kbd{C-c C-c} activates any changes to the in-buffer settings. Closing and
17138 reopening the Org file in Emacs also activates the changes.
17140 @vindex org-archive-location
17142 @item #+ARCHIVE: %s_done::
17143 Sets the archive location of the agenda file. This location applies to the
17144 lines until the next @samp{#+ARCHIVE} line, if any, in the Org file. The
17145 first archive location in the Org file also applies to any entries before it.
17146 The corresponding variable is @code{org-archive-location}.
17148 Sets the category of the agenda file, which applies to the entire document.
17149 @item #+COLUMNS: %25ITEM ...
17150 @cindex property, COLUMNS
17151 Sets the default format for columns view. Org uses this format for column
17152 views where there is no @code{COLUMNS} property.
17153 @item #+CONSTANTS: name1=value1 ...
17154 @vindex org-table-formula-constants
17155 @vindex org-table-formula
17156 Set file-local values for constants that table formulas can use. This line
17157 sets the local variable @code{org-table-formula-constants-local}. The global
17158 version of this variable is @code{org-table-formula-constants}.
17159 @item #+FILETAGS: :tag1:tag2:tag3:
17160 Set tags that all entries in the file will inherit from here, including the
17162 @item #+LINK: linkword replace
17163 @vindex org-link-abbrev-alist
17164 Each line specifies one abbreviation for one link. Use multiple
17165 @code{#+LINK:} lines for more, @pxref{Link abbreviations}. The corresponding
17166 variable is @code{org-link-abbrev-alist}.
17167 @item #+PRIORITIES: highest lowest default
17168 @vindex org-highest-priority
17169 @vindex org-lowest-priority
17170 @vindex org-default-priority
17171 This line sets the limits and the default for the priorities. All three
17172 must be either letters A--Z or numbers 0--9. The highest priority must
17173 have a lower ASCII number than the lowest priority.
17174 @item #+PROPERTY: Property_Name Value
17175 This line sets a default inheritance value for entries in the current
17176 buffer, most useful for specifying the allowed values of a property.
17177 @cindex #+SETUPFILE
17178 @item #+SETUPFILE: file
17179 The setup file is for additional in-buffer settings. Org loads this file and
17180 parses it for any settings in it only when Org opens the main file. @kbd{C-c
17181 C-c} on the settings line will also parse and load. Org also parses and
17182 loads the file during normal exporting process. Org parses the contents of
17183 this file as if it was included in the buffer. It can be another Org file.
17184 To visit the file, @kbd{C-c '} while the cursor is on the line with the file
17188 Startup options Org uses when first visiting a file.
17190 The first set of options deals with the initial visibility of the outline
17191 tree. The corresponding variable for global default settings is
17192 @code{org-startup-folded} with a default value of @code{t}, which is the same
17193 as @code{overview}.
17195 @vindex org-startup-folded
17196 @cindex @code{overview}, STARTUP keyword
17197 @cindex @code{content}, STARTUP keyword
17198 @cindex @code{showall}, STARTUP keyword
17199 @cindex @code{showeverything}, STARTUP keyword
17201 overview @r{top-level headlines only}
17202 content @r{all headlines}
17203 showall @r{no folding of any entries}
17204 showeverything @r{show even drawer contents}
17207 @vindex org-startup-indented
17208 @cindex @code{indent}, STARTUP keyword
17209 @cindex @code{noindent}, STARTUP keyword
17210 Dynamic virtual indentation is controlled by the variable
17211 @code{org-startup-indented}
17213 indent @r{start with @code{org-indent-mode} turned on}
17214 noindent @r{start with @code{org-indent-mode} turned off}
17217 @vindex org-startup-align-all-tables
17218 Aligns tables consistently upon visiting a file; useful for restoring
17219 narrowed table columns. The corresponding variable is
17220 @code{org-startup-align-all-tables} with @code{nil} as default value.
17222 @cindex @code{align}, STARTUP keyword
17223 @cindex @code{noalign}, STARTUP keyword
17225 align @r{align all tables}
17226 noalign @r{don't align tables on startup}
17229 @vindex org-startup-with-inline-images
17230 Whether Org should automatically display inline images. The corresponding
17231 variable is @code{org-startup-with-inline-images}, with a default value
17232 @code{nil} to avoid delays when visiting a file.
17233 @cindex @code{inlineimages}, STARTUP keyword
17234 @cindex @code{noinlineimages}, STARTUP keyword
17236 inlineimages @r{show inline images}
17237 noinlineimages @r{don't show inline images on startup}
17240 @vindex org-startup-with-latex-preview
17241 Whether Org should automatically convert @LaTeX{} fragments to images. The
17242 variable @code{org-startup-with-latex-preview}, which controls this setting,
17243 is set to @code{nil} by default to avoid startup delays.
17244 @cindex @code{latexpreview}, STARTUP keyword
17245 @cindex @code{nolatexpreview}, STARTUP keyword
17247 latexpreview @r{preview @LaTeX{} fragments}
17248 nolatexpreview @r{don't preview @LaTeX{} fragments}
17251 @vindex org-log-done
17252 @vindex org-log-note-clock-out
17253 @vindex org-log-repeat
17254 Logging the closing and reopening of TODO items and clock intervals can be
17255 configured using these options (see variables @code{org-log-done},
17256 @code{org-log-note-clock-out} and @code{org-log-repeat})
17257 @cindex @code{logdone}, STARTUP keyword
17258 @cindex @code{lognotedone}, STARTUP keyword
17259 @cindex @code{nologdone}, STARTUP keyword
17260 @cindex @code{lognoteclock-out}, STARTUP keyword
17261 @cindex @code{nolognoteclock-out}, STARTUP keyword
17262 @cindex @code{logrepeat}, STARTUP keyword
17263 @cindex @code{lognoterepeat}, STARTUP keyword
17264 @cindex @code{nologrepeat}, STARTUP keyword
17265 @cindex @code{logreschedule}, STARTUP keyword
17266 @cindex @code{lognotereschedule}, STARTUP keyword
17267 @cindex @code{nologreschedule}, STARTUP keyword
17268 @cindex @code{logredeadline}, STARTUP keyword
17269 @cindex @code{lognoteredeadline}, STARTUP keyword
17270 @cindex @code{nologredeadline}, STARTUP keyword
17271 @cindex @code{logrefile}, STARTUP keyword
17272 @cindex @code{lognoterefile}, STARTUP keyword
17273 @cindex @code{nologrefile}, STARTUP keyword
17274 @cindex @code{logdrawer}, STARTUP keyword
17275 @cindex @code{nologdrawer}, STARTUP keyword
17276 @cindex @code{logstatesreversed}, STARTUP keyword
17277 @cindex @code{nologstatesreversed}, STARTUP keyword
17279 logdone @r{record a timestamp when an item is marked DONE}
17280 lognotedone @r{record timestamp and a note when DONE}
17281 nologdone @r{don't record when items are marked DONE}
17282 logrepeat @r{record a time when reinstating a repeating item}
17283 lognoterepeat @r{record a note when reinstating a repeating item}
17284 nologrepeat @r{do not record when reinstating repeating item}
17285 lognoteclock-out @r{record a note when clocking out}
17286 nolognoteclock-out @r{don't record a note when clocking out}
17287 logreschedule @r{record a timestamp when scheduling time changes}
17288 lognotereschedule @r{record a note when scheduling time changes}
17289 nologreschedule @r{do not record when a scheduling date changes}
17290 logredeadline @r{record a timestamp when deadline changes}
17291 lognoteredeadline @r{record a note when deadline changes}
17292 nologredeadline @r{do not record when a deadline date changes}
17293 logrefile @r{record a timestamp when refiling}
17294 lognoterefile @r{record a note when refiling}
17295 nologrefile @r{do not record when refiling}
17296 logdrawer @r{store log into drawer}
17297 nologdrawer @r{store log outside of drawer}
17298 logstatesreversed @r{reverse the order of states notes}
17299 nologstatesreversed @r{do not reverse the order of states notes}
17302 @vindex org-hide-leading-stars
17303 @vindex org-odd-levels-only
17304 These options hide leading stars in outline headings, and indent outlines.
17305 The corresponding variables are @code{org-hide-leading-stars} and
17306 @code{org-odd-levels-only}, both with a default setting of @code{nil}
17307 (meaning @code{showstars} and @code{oddeven}).
17308 @cindex @code{hidestars}, STARTUP keyword
17309 @cindex @code{showstars}, STARTUP keyword
17310 @cindex @code{odd}, STARTUP keyword
17311 @cindex @code{even}, STARTUP keyword
17313 hidestars @r{hide all stars on the headline except one.}
17314 showstars @r{show all stars on the headline}
17315 indent @r{virtual indents according to the outline level}
17316 noindent @r{no virtual indents}
17317 odd @r{show odd outline levels only (1,3,...)}
17318 oddeven @r{show all outline levels}
17321 @vindex org-put-time-stamp-overlays
17322 @vindex org-time-stamp-overlay-formats
17323 To turn on custom format overlays over timestamps (variables
17324 @code{org-put-time-stamp-overlays} and
17325 @code{org-time-stamp-overlay-formats}), use
17326 @cindex @code{customtime}, STARTUP keyword
17328 customtime @r{overlay custom time format}
17331 @vindex constants-unit-system
17332 The following options influence the table spreadsheet (variable
17333 @code{constants-unit-system}).
17334 @cindex @code{constcgs}, STARTUP keyword
17335 @cindex @code{constSI}, STARTUP keyword
17337 constcgs @r{@file{constants.el} should use the c-g-s unit system}
17338 constSI @r{@file{constants.el} should use the SI unit system}
17341 @vindex org-footnote-define-inline
17342 @vindex org-footnote-auto-label
17343 @vindex org-footnote-auto-adjust
17344 For footnote settings, use the following keywords. The corresponding
17345 variables are @code{org-footnote-define-inline},
17346 @code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.
17347 @cindex @code{fninline}, STARTUP keyword
17348 @cindex @code{nofninline}, STARTUP keyword
17349 @cindex @code{fnlocal}, STARTUP keyword
17350 @cindex @code{fnprompt}, STARTUP keyword
17351 @cindex @code{fnauto}, STARTUP keyword
17352 @cindex @code{fnconfirm}, STARTUP keyword
17353 @cindex @code{fnplain}, STARTUP keyword
17354 @cindex @code{fnadjust}, STARTUP keyword
17355 @cindex @code{nofnadjust}, STARTUP keyword
17357 fninline @r{define footnotes inline}
17358 fnnoinline @r{define footnotes in separate section}
17359 fnlocal @r{define footnotes near first reference, but not inline}
17360 fnprompt @r{prompt for footnote labels}
17361 fnauto @r{create @code{[fn:1]}-like labels automatically (default)}
17362 fnconfirm @r{offer automatic label for editing or confirmation}
17363 fnplain @r{create @code{[1]}-like labels automatically}
17364 fnadjust @r{automatically renumber and sort footnotes}
17365 nofnadjust @r{do not renumber and sort automatically}
17368 @cindex org-hide-block-startup
17369 To hide blocks on startup, use these keywords. The corresponding variable is
17370 @code{org-hide-block-startup}.
17371 @cindex @code{hideblocks}, STARTUP keyword
17372 @cindex @code{nohideblocks}, STARTUP keyword
17374 hideblocks @r{Hide all begin/end blocks on startup}
17375 nohideblocks @r{Do not hide blocks on startup}
17378 @cindex org-pretty-entities
17379 The display of entities as UTF-8 characters is governed by the variable
17380 @code{org-pretty-entities} and the keywords
17381 @cindex @code{entitiespretty}, STARTUP keyword
17382 @cindex @code{entitiesplain}, STARTUP keyword
17384 entitiespretty @r{Show entities as UTF-8 characters where possible}
17385 entitiesplain @r{Leave entities plain}
17388 @item #+TAGS: TAG1(c1) TAG2(c2)
17389 @vindex org-tag-alist
17390 These lines specify valid tags for this file. Org accepts multiple tags
17391 lines. Tags could correspond to the @emph{fast tag selection} keys. The
17392 corresponding variable is @code{org-tag-alist}.
17395 This line is for formulas for the table directly above. A table can have
17396 multiple @samp{#+TBLFM:} lines. On table recalculation, Org applies only the
17397 first @samp{#+TBLFM:} line. For details see @ref{Using multiple #+TBLFM
17398 lines} in @ref{Editing and debugging formulas}.
17399 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:,
17400 @itemx #+OPTIONS:, #+BIND:,
17401 @itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
17402 These lines provide settings for exporting files. For more details see
17403 @ref{Export settings}.
17404 @item #+TODO: #+SEQ_TODO: #+TYP_TODO:
17405 @vindex org-todo-keywords
17406 These lines set the TODO keywords and their significance to the current file.
17407 The corresponding variable is @code{org-todo-keywords}.
17410 @node The very busy C-c C-c key
17411 @section The very busy C-c C-c key
17413 @cindex C-c C-c, overview
17415 The @kbd{C-c C-c} key in Org serves many purposes depending on the context.
17416 It is probably the most over-worked, multi-purpose key combination in Org.
17417 Its uses are well-documented through out this manual, but here is a
17418 consolidated list for easy reference.
17422 If any highlights shown in the buffer from the creation of a sparse tree, or
17423 from clock display, remove such highlights.
17425 If the cursor is in one of the special @code{#+KEYWORD} lines, scan the
17426 buffer for these lines and update the information.
17428 If the cursor is inside a table, realign the table. The table realigns even
17429 if automatic table editor is turned off.
17431 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
17434 If the current buffer is a capture buffer, close the note and file it. With
17435 a prefix argument, also jump to the target location after saving the note.
17437 If the cursor is on a @code{<<<target>>>}, update radio targets and
17438 corresponding links in this buffer.
17440 If the cursor is on a property line or at the start or end of a property
17441 drawer, offer property commands.
17443 If the cursor is at a footnote reference, go to the corresponding
17444 definition, and @emph{vice versa}.
17446 If the cursor is on a statistics cookie, update it.
17448 If the cursor is in a plain list item with a checkbox, toggle the status
17451 If the cursor is on a numbered item in a plain list, renumber the
17454 If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
17457 If the cursor is at a timestamp, fix the day name in the timestamp.
17461 @section A cleaner outline view
17462 @cindex hiding leading stars
17463 @cindex dynamic indentation
17464 @cindex odd-levels-only outlines
17465 @cindex clean outline view
17467 Org's default outline with stars and no indents can become too cluttered for
17468 short documents. For @emph{book-like} long documents, the effect is not as
17469 noticeable. Org provides an alternate stars and indentation scheme, as shown
17470 on the right in the following table. It uses only one star and indents text
17471 to line with the heading:
17475 * Top level headline | * Top level headline
17476 ** Second level | * Second level
17477 *** 3rd level | * 3rd level
17478 some text | some text
17479 *** 3rd level | * 3rd level
17480 more text | more text
17481 * Another top level headline | * Another top level headline
17487 To turn this mode on, use the minor mode, @code{org-indent-mode}. Text lines
17488 that are not headlines are prefixed with spaces to vertically align with the
17489 headline text@footnote{The @code{org-indent-mode} also sets the
17490 @code{wrap-prefix} correctly for indenting and wrapping long lines of
17491 headlines or text. This minor mode handles @code{visual-line-mode} and
17492 directly applied settings through @code{word-wrap}.}.
17494 To make more horizontal space, the headlines are shifted by two stars. This
17495 can be configured by the @code{org-indent-indentation-per-level} variable.
17496 Only one star on each headline is visible, the rest are masked with the same
17497 font color as the background. This font face can be configured with the
17498 @code{org-hide} variable.
17500 Note that turning on @code{org-indent-mode} sets
17501 @code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
17502 @code{nil}; @samp{2.} below shows how this works.
17504 To globally turn on @code{org-indent-mode} for all files, customize the
17505 variable @code{org-startup-indented}.
17507 To turn on indenting for individual files, use @code{#+STARTUP} option as
17514 Indent on startup makes Org use hard spaces to align text with headings as
17515 shown in examples below.
17519 @emph{Indentation of text below headlines}@*
17520 Indent text to align with the headline.
17524 more text, now indented
17527 @vindex org-adapt-indentation
17528 Org adapts indentations with paragraph filling, line wrapping, and structure
17529 editing@footnote{Also see the variable @code{org-adapt-indentation}.}.
17532 @vindex org-hide-leading-stars
17533 @emph{Hiding leading stars}@* Org can make leading stars invisible. For
17534 global preference, configure the variable @code{org-hide-leading-stars}. For
17535 per-file preference, use these file @code{#+STARTUP} options:
17538 #+STARTUP: hidestars
17539 #+STARTUP: showstars
17542 With stars hidden, the tree is shown as:
17546 * Top level headline
17554 @vindex org-hide @r{(face)}
17555 Because Org makes the font color same as the background color to hide to
17556 stars, sometimes @code{org-hide} face may need tweaking to get the effect
17557 right. For some black and white combinations, @code{grey90} on a white
17558 background might mask the stars better.
17561 @vindex org-odd-levels-only
17562 Using stars for only odd levels, 1, 3, 5, @dots{}, can also clean up the
17563 clutter. This removes two stars from each level@footnote{Because
17564 @samp{LEVEL=2} has 3 stars, @samp{LEVEL=3} has 4 stars, and so on}. For Org
17565 to properly handle this cleaner structure during edits and exports, configure
17566 the variable @code{org-odd-levels-only}. To set this per-file, use either
17567 one of the following lines:
17574 To switch between single and double stars layouts, use @kbd{M-x
17575 org-convert-to-odd-levels RET} and @kbd{M-x org-convert-to-oddeven-levels}.
17579 @section Using Org on a tty
17580 @cindex tty key bindings
17582 Org provides alternative key bindings for TTY and modern mobile devices that
17583 cannot handle cursor keys and complex modifier key chords. Some of these
17584 workarounds may be more cumbersome than necessary. Users should look into
17585 customizing these further based on their usage needs. For example, the
17586 normal @kbd{S-@key{cursor}} for editing timestamp might be better with
17589 @multitable @columnfractions 0.15 0.2 0.1 0.2
17590 @item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
17591 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab
17592 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
17593 @item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab
17594 @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
17595 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab
17596 @item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
17597 @item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab
17598 @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
17599 @item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab
17600 @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab
17601 @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
17602 @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab
17603 @item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab
17604 @item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab
17605 @item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab
17606 @item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab
17607 @item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab
17608 @item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab
17613 @section Interaction with other packages
17614 @cindex packages, interaction with other
17615 Org's compatibility and the level of interaction with other Emacs packages
17616 are documented here.
17620 * Cooperation:: Packages Org cooperates with
17621 * Conflicts:: Packages that lead to conflicts
17625 @subsection Packages that Org cooperates with
17628 @cindex @file{calc.el}
17629 @cindex Gillespie, Dave
17630 @item @file{calc.el} by Dave Gillespie
17631 Org uses the Calc package for tables to implement spreadsheet functionality
17632 (@pxref{The spreadsheet}). Org also uses Calc for embedded calculations.
17633 @xref{Embedded Mode, , Embedded Mode, calc, GNU Emacs Calc Manual}.
17634 @item @file{constants.el} by Carsten Dominik
17635 @cindex @file{constants.el}
17636 @cindex Dominik, Carsten
17637 @vindex org-table-formula-constants
17638 Org can use names for constants in formulas in tables. Org can also use
17639 calculation suffixes for units, such as @samp{M} for @samp{Mega}. For a
17640 standard collection of such constants, install the @file{constants} package.
17641 Install version 2.0 of this package, available at
17642 @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks if the function
17643 @code{constants-get} has been autoloaded. Installation instructions are in
17644 the file, @file{constants.el}.
17645 @item @file{cdlatex.el} by Carsten Dominik
17646 @cindex @file{cdlatex.el}
17647 @cindex Dominik, Carsten
17648 Org mode can use CD@LaTeX{} package to efficiently enter @LaTeX{} fragments
17649 into Org files (@pxref{CDLaTeX mode}).
17650 @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
17651 @cindex @file{imenu.el}
17652 Imenu creates dynamic menus based on an index of items in a file. Org mode
17653 supports Imenu menus. Enable it with a mode hook as follows:
17655 (add-hook 'org-mode-hook
17656 (lambda () (imenu-add-to-menubar "Imenu")))
17658 @vindex org-imenu-depth
17659 By default the Imenu index is two levels deep. Change the index depth using
17660 thes variable, @code{org-imenu-depth}.
17661 @item @file{speedbar.el} by Eric M. Ludlam
17662 @cindex @file{speedbar.el}
17663 @cindex Ludlam, Eric M.
17664 Speedbar package creates a special Emacs frame for displaying files and index
17665 items in files. Org mode supports Speedbar; users can drill into Org files
17666 directly from the Speedbar. The @kbd{<} in the Speedbar frame tweeks the
17667 agenda commands to that file or to a subtree.
17668 @cindex @file{table.el}
17669 @item @file{table.el} by Takaaki Ota
17671 @cindex table editor, @file{table.el}
17672 @cindex @file{table.el}
17673 @cindex Ota, Takaaki
17675 Complex ASCII tables with automatic line wrapping, column- and row-spanning,
17676 and alignment can be created using the Emacs table package by Takaaki Ota.
17677 Org mode recognizes such tables and export them properly. @kbd{C-c '} to
17678 edit these tables in a special buffer, much like Org's @samp{src} code
17679 blocks. Because of interference with other Org mode functionality, Takaaki
17680 Ota tables cannot be edited directly in the Org buffer.
17682 @orgcmd{C-c ',org-edit-special}
17683 Edit a @file{table.el} table. Works when the cursor is in a table.el table.
17685 @orgcmd{C-c ~,org-table-create-with-table.el}
17686 Insert a @file{table.el} table. If there is already a table at point, this
17687 command converts it between the @file{table.el} format and the Org mode
17688 format. See the documentation string of the command @code{org-convert-table}
17694 @subsection Packages that conflict with Org mode
17698 @cindex @code{shift-selection-mode}
17699 @vindex org-support-shift-select
17700 In Emacs, @code{shift-selection-mode} combines cursor motions with shift key
17701 to enlarge regions. Emacs sets this mode by default. This conflicts with
17702 Org's use of @kbd{S-@key{cursor}} commands to change timestamps, TODO
17703 keywords, priorities, and item bullet types, etc. Since @kbd{S-@key{cursor}}
17704 commands outside of specific contexts don't do anything, Org offers the
17705 variable @code{org-support-shift-select} for customization. Org mode
17706 accommodates shift selection by (i) making it available outside of the
17707 special contexts where special commands apply, and (ii) extending an
17708 existing active region even if the cursor moves across a special context.
17710 @item @file{CUA.el} by Kim. F. Storm
17711 @cindex @file{CUA.el}
17712 @cindex Storm, Kim. F.
17713 @vindex org-replace-disputed-keys
17714 Org key bindings conflict with @kbd{S-<cursor>} keys used by CUA mode. For
17715 Org to relinquish these bindings to CUA mode, configure the variable
17716 @code{org-replace-disputed-keys}. When set, Org moves the following key
17717 bindings in Org files, and in the agenda buffer (but not during date
17721 S-UP @result{} M-p S-DOWN @result{} M-n
17722 S-LEFT @result{} M-- S-RIGHT @result{} M-+
17723 C-S-LEFT @result{} M-S-- C-S-RIGHT @result{} M-S-+
17726 @vindex org-disputed-keys
17727 Yes, these are unfortunately more difficult to remember. To define a
17728 different replacement keys, look at the variable @code{org-disputed-keys}.
17730 @item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org}
17731 @cindex @file{ecomplete.el}
17733 Ecomplete provides ``electric'' address completion in address header
17734 lines in message buffers. Sadly Orgtbl mode cuts ecompletes power
17735 supply: No completion happens when Orgtbl mode is enabled in message
17736 buffers while entering text in address header lines. If one wants to
17737 use ecomplete one should @emph{not} follow the advice to automagically
17738 turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but
17739 instead---after filling in the message headers---turn on Orgtbl mode
17740 manually when needed in the messages body.
17742 @item @file{filladapt.el} by Kyle Jones
17743 @cindex @file{filladapt.el}
17745 Org mode tries to do the right thing when filling paragraphs, list items and
17746 other elements. Many users reported problems using both @file{filladapt.el}
17747 and Org mode, so a safe thing to do is to disable filladapt like this:
17750 (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
17753 @item @file{yasnippet.el}
17754 @cindex @file{yasnippet.el}
17755 The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of
17756 @code{"\t"}) overrules YASnippet's access to this key. The following code
17757 fixed this problem:
17760 (add-hook 'org-mode-hook
17762 (setq-local yas/trigger-key [tab])
17763 (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
17766 The latest version of yasnippet doesn't play well with Org mode. If the
17767 above code does not fix the conflict, first define the following function:
17770 (defun yas/org-very-safe-expand ()
17771 (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
17774 Then tell Org mode to use that function:
17777 (add-hook 'org-mode-hook
17779 (make-variable-buffer-local 'yas/trigger-key)
17780 (setq yas/trigger-key [tab])
17781 (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
17782 (define-key yas/keymap [tab] 'yas/next-field)))
17785 @item @file{windmove.el} by Hovav Shacham
17786 @cindex @file{windmove.el}
17787 This package also uses the @kbd{S-<cursor>} keys, so everything written
17788 in the paragraph above about CUA mode also applies here. If you want make
17789 the windmove function active in locations where Org mode does not have
17790 special functionality on @kbd{S-@key{cursor}}, add this to your
17794 ;; Make windmove work in org-mode:
17795 (add-hook 'org-shiftup-final-hook 'windmove-up)
17796 (add-hook 'org-shiftleft-final-hook 'windmove-left)
17797 (add-hook 'org-shiftdown-final-hook 'windmove-down)
17798 (add-hook 'org-shiftright-final-hook 'windmove-right)
17801 @item @file{viper.el} by Michael Kifer
17802 @cindex @file{viper.el}
17804 Viper uses @kbd{C-c /} and therefore makes this key not access the
17805 corresponding Org mode command @code{org-sparse-tree}. You need to find
17806 another key for this command, or override the key in
17807 @code{viper-vi-global-user-map} with
17810 (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
17818 @section org-crypt.el
17819 @cindex @file{org-crypt.el}
17820 @cindex @code{org-decrypt-entry}
17822 Org crypt encrypts the text of an Org entry, but not the headline, or
17823 properties. Org crypt uses the Emacs EasyPG library to encrypt and decrypt.
17825 Any text below a headline that has a @samp{:crypt:} tag will be automatically
17826 be encrypted when the file is saved. To use a different tag, customize the
17827 @code{org-crypt-tag-matcher} variable.
17829 Suggested Org crypt settings in Emacs init file:
17832 (require 'org-crypt)
17833 (org-crypt-use-before-save-magic)
17834 (setq org-tags-exclude-from-inheritance (quote ("crypt")))
17836 (setq org-crypt-key nil)
17837 ;; GPG key to use for encryption
17838 ;; Either the Key ID or set to nil to use symmetric encryption.
17840 (setq auto-save-default nil)
17841 ;; Auto-saving does not cooperate with org-crypt.el: so you need
17842 ;; to turn it off if you plan to use org-crypt.el quite often.
17843 ;; Otherwise, you'll get an (annoying) message each time you
17846 ;; To turn it off only locally, you can insert this:
17848 ;; # -*- buffer-auto-save-file-name: nil; -*-
17851 Excluding the crypt tag from inheritance prevents encrypting previously
17858 This appendix covers some areas where users can extend the functionality of
17862 * Hooks:: How to reach into Org's internals
17863 * Add-on packages:: Available extensions
17864 * Adding hyperlink types:: New custom link types
17865 * Adding export back-ends:: How to write new export back-ends
17866 * Context-sensitive commands:: How to add functionality to such commands
17867 * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
17868 * Dynamic blocks:: Automatically filled blocks
17869 * Special agenda views:: Customized views
17870 * Speeding up your agendas:: Tips on how to speed up your agendas
17871 * Extracting agenda information:: Post-processing of agenda information
17872 * Using the property API:: Writing programs that use entry properties
17873 * Using the mapping API:: Mapping over all or selected entries
17880 Org has a large number of hook variables for adding functionality. This
17881 appendix illustrates using a few. A complete list of hooks with
17882 documentation is maintained by the Worg project at
17883 @uref{http://orgmode.org/worg/doc.html#hooks}.
17885 @node Add-on packages
17886 @section Add-on packages
17887 @cindex add-on packages
17889 Various authors wrote a large number of add-on packages for Org.
17891 These packages are not part of Emacs, but they are distributed as contributed
17892 packages with the separate release available at @uref{http://orgmode.org}.
17893 See the @file{contrib/README} file in the source code directory for a list of
17894 contributed files. Worg page with more information is at:
17895 @uref{http://orgmode.org/worg/org-contrib/}.
17897 @node Adding hyperlink types
17898 @section Adding hyperlink types
17899 @cindex hyperlinks, adding new types
17901 Org has many built-in hyperlink types (@pxref{Hyperlinks}), and an interface
17902 for adding new link types. The example file, @file{org-man.el}, shows the
17903 process of adding Org links to Unix man pages, which look like this:
17904 @samp{[[man:printf][The printf manpage]]}:
17907 ;;; org-man.el - Support for links to manpages in Org
17911 (org-add-link-type "man" 'org-man-open)
17912 (add-hook 'org-store-link-functions 'org-man-store-link)
17914 (defcustom org-man-command 'man
17915 "The Emacs command to be used to display a man page."
17917 :type '(choice (const man) (const woman)))
17919 (defun org-man-open (path)
17920 "Visit the manpage on PATH.
17921 PATH should be a topic that can be thrown at the man command."
17922 (funcall org-man-command path))
17924 (defun org-man-store-link ()
17925 "Store a link to a manpage."
17926 (when (memq major-mode '(Man-mode woman-mode))
17927 ;; This is a man page, we do make this link
17928 (let* ((page (org-man-get-page-name))
17929 (link (concat "man:" page))
17930 (description (format "Manpage for %s" page)))
17931 (org-store-link-props
17934 :description description))))
17936 (defun org-man-get-page-name ()
17937 "Extract the page name from the buffer name."
17938 ;; This works for both `Man-mode' and `woman-mode'.
17939 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
17940 (match-string 1 (buffer-name))
17941 (error "Cannot create link to this man page")))
17945 ;;; org-man.el ends here
17949 To activate links to man pages in Org, enter this in the init file:
17956 A review of @file{org-man.el}:
17959 First, @code{(require 'org)} ensures @file{org.el} is loaded.
17961 The @code{org-add-link-type} defines a new link type with @samp{man} prefix.
17962 The call contains the function to call that follows the link type.
17964 @vindex org-store-link-functions
17965 The next line adds a function to @code{org-store-link-functions} that records
17966 a useful link with the command @kbd{C-c l} in a buffer displaying a man page.
17969 The rest of the file defines necessary variables and functions. First is the
17970 customization variable @code{org-man-command}. It has two options,
17971 @code{man} and @code{woman}. Next is a function whose argument is the link
17972 path, which for man pages is the topic of the man command. To follow the
17973 link, the function calls the @code{org-man-command} to display the man page.
17976 @kbd{C-c l} constructs and stores the link.
17978 @kbd{C-c l} calls the function @code{org-man-store-link}, which first checks
17979 if the @code{major-mode} is appropriate. If check fails, the function
17980 returns @code{nil}. Otherwise the function makes a link string by combining
17981 the @samp{man:} prefix with the man topic. The function then calls
17982 @code{org-store-link-props} with @code{:type} and @code{:link} properties. A
17983 @code{:description} property is an optional string that is displayed when the
17984 function inserts the link in the Org buffer.
17986 @kbd{C-c C-l} inserts the stored link.
17988 To define new link types, define a function that implements completion
17989 support with @kbd{C-c C-l}. This function should not accept any arguments
17990 but return the appropriate prefix and complete link string.
17992 @node Adding export back-ends
17993 @section Adding export back-ends
17994 @cindex Export, writing back-ends
17996 Org's export engine makes it easy for writing new back-ends. The framework
17997 on which the engine was built makes it easy to derive new back-ends from
18000 The two main entry points to the export engine are:
18001 @code{org-export-define-backend} and
18002 @code{org-export-define-derived-backend}. To grok these functions, see
18003 @file{ox-latex.el} for an example of defining a new back-end from scratch,
18004 and @file{ox-beamer.el} for an example of deriving from an existing engine.
18006 For creating a new back-end from scratch, first set its name as a symbol in
18007 an alist consisting of elements and export functions. To make the back-end
18008 visible to the export dispatcher, set @code{:menu-entry} keyword. For export
18009 options specific to this back-end, set the @code{:options-alist}.
18011 For creating a new back-end from an existing one, set @code{:translate-alist}
18012 to an alist of export functions. This alist replaces the parent back-end
18015 For complete documentation, see
18016 @url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
18017 Reference on Worg}.
18019 @node Context-sensitive commands
18020 @section Context-sensitive commands
18021 @cindex context-sensitive commands, hooks
18022 @cindex add-ons, context-sensitive commands
18023 @vindex org-ctrl-c-ctrl-c-hook
18025 Org has facilities for building context sensitive commands. Authors of Org
18026 add-ons can tap into this functionality.
18028 Some Org commands change depending on the context. The most important
18029 example of this behavior is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c
18030 key}). Other examples are @kbd{M-cursor} and @kbd{M-S-cursor}.
18032 These context sensitive commands work by providing a function that detects
18033 special context for that add-on and executes functionality appropriate for
18036 @node Tables in arbitrary syntax
18037 @section Tables and lists in arbitrary syntax
18038 @cindex tables, in other modes
18039 @cindex lists, in other modes
18040 @cindex Orgtbl mode
18042 Because of Org's success in handling tables with Orgtbl, a frequently asked
18043 feature is to Org's usability functions to other table formats native to
18044 other modem's, such as @LaTeX{}. This would be hard to do in a general way
18045 without complicated customization nightmares. Moreover, that would take Org
18046 away from its simplicity roots that Orgtbl has proven. There is, however, an
18047 alternate approach to accomplishing the same.
18049 This approach involves implementing a custom @emph{translate} function that
18050 operates on a native Org @emph{source table} to produce a table in another
18051 format. This strategy would keep the excellently working Orgtbl simple and
18052 isolate complications, if any, confined to the translate function. To add
18053 more alien table formats, we just add more translate functions. Also the
18054 burden of developing custom translate functions for new table formats will be
18055 in the hands of those who know those formats best.
18057 For an example of how this strategy works, see Orgstruct mode. In that mode,
18058 Bastien added the ability to use Org's facilities to edit and re-structure
18059 lists. He did by turning @code{orgstruct-mode} on, and then exporting the
18060 list locally to another format, such as HTML, @LaTeX{} or Texinfo.
18063 * Radio tables:: Sending and receiving radio tables
18064 * A @LaTeX{} example:: Step by step, almost a tutorial
18065 * Translator functions:: Copy and modify
18066 * Radio lists:: Sending and receiving lists
18070 @subsection Radio tables
18071 @cindex radio tables
18073 Radio tables are target locations for translated tables that are not near
18074 their source. Org finds the target location and inserts the translated
18077 The key to finding the target location are the magic words @code{BEGIN/END
18078 RECEIVE ORGTBL}. They have to appear as comments in the current mode. If
18079 the mode is C, then:
18082 /* BEGIN RECEIVE ORGTBL table_name */
18083 /* END RECEIVE ORGTBL table_name */
18087 At the location of source, Org needs a special line to direct Orgtbl to
18088 translate and to find the target for inserting the translated table. For
18092 #+ORGTBL: SEND table_name translation_function arguments...
18096 @code{table_name} is the table's reference name, which is also used in the
18097 receiver lines, and the @code{translation_function} is the Lisp function that
18098 translates. This line, in addition, may also contain alternating key and
18099 value arguments at the end. The translation function gets these values as a
18100 property list. A few standard parameters are already recognized and acted
18101 upon before the translation function is called:
18105 Skip the first N lines of the table. Hlines do count; include them if they
18108 @item :skipcols (n1 n2 ...)
18109 List of columns to be skipped. First Org automatically discards columns with
18110 calculation marks and then sends the table to the translator function, which
18111 then skips columns as specified in @samp{skipcols}.
18115 To keep the source table intact in the buffer without being disturbed when
18116 the source file is compiled or otherwise being worked on, use one of these
18121 Place the table in a block comment. For example, in C mode you could wrap
18122 the table between @samp{/*} and @samp{*/} lines.
18124 Put the table after an @samp{END} statement. For example @samp{\bye} in
18125 @TeX{} and @samp{\end@{document@}} in @LaTeX{}.
18127 Comment and uncomment each line of the table during edits. The @kbd{M-x
18128 orgtbl-toggle-comment RET} command makes toggling easy.
18131 @node A @LaTeX{} example
18132 @subsection A @LaTeX{} example of radio tables
18133 @cindex @LaTeX{}, and Orgtbl mode
18135 To wrap a source table in @LaTeX{}, use the @code{comment} environment
18136 provided by @file{comment.sty}. To activate it, put
18137 @code{\usepackage@{comment@}} in the document header. Orgtbl mode inserts a
18138 radio table skeleton@footnote{By default this works only for @LaTeX{}, HTML,
18139 and Texinfo. Configure the variable @code{orgtbl-radio-table-templates} to
18140 install templates for other export formats.} with the command @kbd{M-x
18141 orgtbl-insert-radio-table RET}, which prompts for a table name. For example,
18142 if @samp{salesfigures} is the name, the template inserts:
18144 @cindex #+ORGTBL, SEND
18146 % BEGIN RECEIVE ORGTBL salesfigures
18147 % END RECEIVE ORGTBL salesfigures
18149 #+ORGTBL: SEND salesfigures orgtbl-to-latex
18155 @vindex @LaTeX{}-verbatim-environments
18156 The line @code{#+ORGTBL: SEND} tells Orgtbl mode to use the function
18157 @code{orgtbl-to-latex} to convert the table to @LaTeX{} format, then insert
18158 the table at the target (receive) location named @code{salesfigures}. Now
18159 the table is ready for data entry. It can even use spreadsheet
18160 features@footnote{If the @samp{#+TBLFM} line contains an odd number of dollar
18161 characters, this may cause problems with font-lock in @LaTeX{} mode. As
18162 shown in the example you can fix this by adding an extra line inside the
18163 @code{comment} environment that is used to balance the dollar expressions.
18164 If you are using AUC@TeX{} with the font-latex library, a much better
18165 solution is to add the @code{comment} environment to the variable
18166 @code{LaTeX-verbatim-environments}.}:
18169 % BEGIN RECEIVE ORGTBL salesfigures
18170 % END RECEIVE ORGTBL salesfigures
18172 #+ORGTBL: SEND salesfigures orgtbl-to-latex
18173 | Month | Days | Nr sold | per day |
18174 |-------+------+---------+---------|
18175 | Jan | 23 | 55 | 2.4 |
18176 | Feb | 21 | 16 | 0.8 |
18177 | March | 22 | 278 | 12.6 |
18178 #+TBLFM: $4=$3/$2;%.1f
18179 % $ (optional extra dollar to keep font-lock happy, see footnote)
18184 After editing, @kbd{C-c C-c} inserts translated table at the target location,
18185 between the two marker lines.
18187 For hand-made custom tables, note that the translator needs to skip the first
18188 two lines of the source table. Also the command has to @emph{splice} out the
18189 target table without the header and footer.
18192 \begin@{tabular@}@{lrrr@}
18193 Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
18194 % BEGIN RECEIVE ORGTBL salesfigures
18195 % END RECEIVE ORGTBL salesfigures
18199 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
18200 | Month | Days | Nr sold | per day |
18201 |-------+------+---------+---------|
18202 | Jan | 23 | 55 | 2.4 |
18203 | Feb | 21 | 16 | 0.8 |
18204 | March | 22 | 278 | 12.6 |
18205 #+TBLFM: $4=$3/$2;%.1f
18209 The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
18210 Orgtbl mode and uses @code{tabular} environment by default to typeset the
18211 table and mark the horizontal lines with @code{\hline}. For additional
18212 parameters to control output, @pxref{Translator functions}:
18215 @item :splice nil/t
18216 When non-@code{nil}, returns only table body lines; not wrapped in tabular
18217 environment. Default is @code{nil}.
18220 Format to warp each field. It should contain @code{%s} for the original
18221 field value. For example, to wrap each field value in dollar symbol, you
18222 could use @code{:fmt "$%s$"}. Format can also wrap a property list with
18223 column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
18224 In place of a string, a function of one argument can be used; the function
18225 must return a formatted string.
18228 Format numbers as exponentials. The spec should have @code{%s} twice for
18229 inserting mantissa and exponent, for example @code{"%s\\times10^@{%s@}"}.
18230 This may also be a property list with column numbers and formats, for example
18231 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
18232 @code{efmt} has been applied to a value, @code{fmt} will also be applied.
18233 Functions with two arguments can be supplied instead of strings. By default,
18234 no special formatting is applied.
18237 @node Translator functions
18238 @subsection Translator functions
18239 @cindex HTML, and Orgtbl mode
18240 @cindex translator function
18242 Orgtbl mode has built-in translator functions: @code{orgtbl-to-csv}
18243 (comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values),
18244 @code{orgtbl-to-latex}, @code{orgtbl-to-html}, @code{orgtbl-to-texinfo},
18245 @code{orgtbl-to-unicode} and @code{orgtbl-to-orgtbl}. They use the generic
18246 translator, @code{orgtbl-to-generic}, which delegates translations to various
18249 Properties passed to the function through the @samp{ORGTBL SEND} line take
18250 precedence over properties defined inside the function. For example, this
18251 overrides the default @LaTeX{} line endings, @samp{\\}, with @samp{\\[2mm]}:
18254 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
18257 For a new language translator, define a converter function. It can be a
18258 generic function, such as shown in this example. It marks a beginning and
18259 ending of a table with @samp{!BTBL!} and @samp{!ETBL!}; a beginning and
18260 ending of lines with @samp{!BL!} and @samp{!EL!}; and uses a TAB for a field
18264 (defun orgtbl-to-language (table params)
18265 "Convert the orgtbl-mode TABLE to language."
18268 (org-combine-plists
18269 '(:tstart "!BTBL!" :tend "!ETBL!" :lstart "!BL!" :lend "!EL!" :sep "\t")
18274 The documentation for the @code{orgtbl-to-generic} function shows a complete
18275 list of parameters, each of which can be passed through to
18276 @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
18277 using that generic function.
18279 For complicated translations the generic translator function could be
18280 replaced by a custom translator function. Such a custom function must take
18281 two arguments and return a single string containing the formatted table. The
18282 first argument is the table whose lines are a list of fields or the symbol
18283 @code{hline}. The second argument is the property list consisting of
18284 parameters specified in the @samp{#+ORGTBL: SEND} line. Please share your
18285 translator functions by posting them to the Org users mailing list,
18286 @email{emacs-orgmode@@gnu.org}.
18289 @subsection Radio lists
18290 @cindex radio lists
18291 @cindex org-list-insert-radio-list
18293 Call the @code{org-list-insert-radio-list} function to insert a radio list
18294 template in HTML, @LaTeX{}, and Texinfo mode documents. Sending and
18295 receiving radio lists works is the same as for radio tables (@pxref{Radio
18296 tables}) except for these differences:
18301 Orgstruct mode must be active.
18303 Use @code{ORGLST} keyword instead of @code{ORGTBL}.
18305 @kbd{C-c C-c} works only on the first list item.
18308 Built-in translators functions are: @code{org-list-to-latex},
18309 @code{org-list-to-html} and @code{org-list-to-texinfo}. They use the
18310 @code{org-list-to-generic} translator function. See its documentation for
18311 parameters for accurate customizations of lists. Here is a @LaTeX{} example:
18314 % BEGIN RECEIVE ORGLST to-buy
18315 % END RECEIVE ORGLST to-buy
18317 #+ORGLST: SEND to-buy org-list-to-latex
18326 @kbd{C-c C-c} on @samp{a new house} inserts the translated @LaTeX{} list
18327 in-between the BEGIN and END marker lines.
18329 @node Dynamic blocks
18330 @section Dynamic blocks
18331 @cindex dynamic blocks
18333 Org supports @emph{dynamic blocks} in Org documents. They are inserted with
18334 begin and end markers like any other @samp{src} code block, but the contents
18335 are updated automatically by a user function. For example, @kbd{C-c C-x C-r}
18336 inserts a dynamic table that updates the work time (@pxref{Clocking work
18339 Dynamic blocks can have names and function parameters. The syntax is similar
18340 to @samp{src} code block specifications:
18342 @cindex #+BEGIN:dynamic block
18344 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
18349 These command update dynamic blocks:
18352 @orgcmd{C-c C-x C-u,org-dblock-update}
18353 Update dynamic block at point.
18354 @orgkey{C-u C-c C-x C-u}
18355 Update all dynamic blocks in the current file.
18358 Before updating a dynamic block, Org removes content between the BEGIN and
18359 END markers. Org then reads the parameters on the BEGIN line for passing to
18360 the writer function. If the function expects to access the removed content,
18361 then Org expects an extra parameter, @code{:content}, on the BEGIN line.
18363 To syntax for calling a writer function with a named block, @code{myblock}
18364 is: @code{org-dblock-write:myblock}. Parameters come from the BEGIN line.
18366 The following is an example of a dynamic block and a block writer function
18367 that updates the time when the function was last run:
18370 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
18376 The dynamic block's writer function:
18379 (defun org-dblock-write:block-update-time (params)
18380 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
18381 (insert "Last block update at: "
18382 (format-time-string fmt))))
18385 To keep dynamic blocks up-to-date in an Org file, use the function,
18386 @code{org-update-all-dblocks} in hook, such as @code{before-save-hook}. The
18387 @code{org-update-all-dblocks} function does not run if the file is not in
18390 Dynamic blocks, like any other block, can be narrowed with
18391 @code{org-narrow-to-block}.
18393 @node Special agenda views
18394 @section Special agenda views
18395 @cindex agenda views, user-defined
18397 @vindex org-agenda-skip-function
18398 @vindex org-agenda-skip-function-global
18399 Org provides a special hook to further limit items in agenda views:
18400 @code{agenda}, @code{agenda*}@footnote{The @code{agenda*} view is the same as
18401 @code{agenda} except that it only considers @emph{appointments}, i.e.,
18402 scheduled and deadline items that have a time specification @samp{[h]h:mm} in
18403 their time-stamps.}, @code{todo}, @code{alltodo}, @code{tags},
18404 @code{tags-todo}, @code{tags-tree}. Specify a custom function that tests
18405 inclusion of every matched item in the view. This function can also
18406 skip as much as is needed.
18408 For a global condition applicable to agenda views, use the
18409 @code{org-agenda-skip-function-global} variable. Org uses a global condition
18410 with @code{org-agenda-skip-function} for custom searching.
18412 This example defines a function for a custom view showing TODO items with
18413 WAITING status. Manually this is a multi step search process, but with a
18414 custom view, this can be automated as follows:
18416 The custom function searches the subtree for the WAITING tag and returns
18417 @code{nil} on match. Otherwise it gives the location from where the search
18421 (defun my-skip-unless-waiting ()
18422 "Skip trees that are not waiting"
18423 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
18424 (if (re-search-forward ":waiting:" subtree-end t)
18425 nil ; tag found, do not skip
18426 subtree-end))) ; tag not found, continue after end of subtree
18429 To use this custom function in a custom agenda command:
18432 (org-add-agenda-custom-command
18433 '("b" todo "PROJECT"
18434 ((org-agenda-skip-function 'my-skip-unless-waiting)
18435 (org-agenda-overriding-header "Projects waiting for something: "))))
18438 @vindex org-agenda-overriding-header
18439 Note that this also binds @code{org-agenda-overriding-header} to a more
18440 meaningful string suitable for the agenda view.
18442 @vindex org-odd-levels-only
18443 @vindex org-agenda-skip-function
18445 Search for entries with a limit set on levels for the custom search. This is
18446 a general appraoch to creating custom searches in Org. To include all
18447 levels, use @samp{LEVEL>0}@footnote{Note that, for
18448 @code{org-odd-levels-only}, a level number corresponds to order in the
18449 hierarchy, not to the number of stars.}. Then to selectively pick the
18450 matched entries, use @code{org-agenda-skip-function}, which also accepts Lisp
18451 forms, such as @code{org-agenda-skip-entry-if} and
18452 @code{org-agenda-skip-subtree-if}. For example:
18455 @item (org-agenda-skip-entry-if 'scheduled)
18456 Skip current entry if it has been scheduled.
18457 @item (org-agenda-skip-entry-if 'notscheduled)
18458 Skip current entry if it has not been scheduled.
18459 @item (org-agenda-skip-entry-if 'deadline)
18460 Skip current entry if it has a deadline.
18461 @item (org-agenda-skip-entry-if 'scheduled 'deadline)
18462 Skip current entry if it has a deadline, or if it is scheduled.
18463 @item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
18464 Skip current entry if the TODO keyword is TODO or WAITING.
18465 @item (org-agenda-skip-entry-if 'todo 'done)
18466 Skip current entry if the TODO keyword marks a DONE state.
18467 @item (org-agenda-skip-entry-if 'timestamp)
18468 Skip current entry if it has any timestamp, may also be deadline or scheduled.
18469 @anchor{x-agenda-skip-entry-regexp}
18470 @item (org-agenda-skip-entry-if 'regexp "regular expression")
18471 Skip current entry if the regular expression matches in the entry.
18472 @item (org-agenda-skip-entry-if 'notregexp "regular expression")
18473 Skip current entry unless the regular expression matches.
18474 @item (org-agenda-skip-subtree-if 'regexp "regular expression")
18475 Same as above, but check and skip the entire subtree.
18478 The following is an example of a search for @samp{WAITING} without the
18482 (org-add-agenda-custom-command
18483 '("b" todo "PROJECT"
18484 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
18485 'regexp ":waiting:"))
18486 (org-agenda-overriding-header "Projects waiting for something: "))))
18489 @node Speeding up your agendas
18490 @section Speeding up your agendas
18491 @cindex agenda views, optimization
18493 Some agenda commands slow down when the Org files grow in size or number.
18494 Here are tips to speed up:
18498 Reduce the number of Org agenda files to avoid slowdowns due to hard drive
18501 Reduce the number of @samp{DONE} and archived headlines so agenda operations
18502 that skip over these can finish faster.
18504 @vindex org-agenda-dim-blocked-tasks
18505 Do not dim blocked tasks:
18507 (setq org-agenda-dim-blocked-tasks nil)
18510 @vindex org-startup-folded
18511 @vindex org-agenda-inhibit-startup
18512 Stop preparing agenda buffers on startup:
18514 (setq org-agenda-inhibit-startup nil)
18517 @vindex org-agenda-show-inherited-tags
18518 @vindex org-agenda-use-tag-inheritance
18519 Disable tag inheritance for agendas:
18521 (setq org-agenda-use-tag-inheritance nil)
18525 These options can be applied to selected agenda views. For more details
18526 about generation of agenda views, see the docstrings for the relevant
18527 variables, and this @uref{http://orgmode.org/worg/agenda-optimization.html,
18528 dedicated Worg page} for agenda optimization.
18530 @node Extracting agenda information
18531 @section Extracting agenda information
18532 @cindex agenda, pipe
18533 @cindex Scripts, for agenda processing
18535 @vindex org-agenda-custom-commands
18536 Org provides commands to access agendas through Emacs batch mode. Through
18537 this command-line interface, agendas are automated for further processing or
18540 @code{org-batch-agenda} creates an agenda view in ASCII and outputs to
18541 STDOUT. This command takes one string parameter. When string length=1, Org
18542 uses it as a key to @code{org-agenda-custom-commands}. These are the same
18543 ones available through @kbd{C-c a}.
18545 This example command line directly prints the TODO list to the printer:
18548 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
18551 When the string parameter length is two or more characters, Org matches it
18552 with tags/TODO strings. For example, this example command line prints items
18553 tagged with @samp{shop}, but excludes items tagged with @samp{NewYork}:
18556 emacs -batch -l ~/.emacs \
18557 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
18561 An example showing on-the-fly parameter modifications:
18564 emacs -batch -l ~/.emacs \
18565 -eval '(org-batch-agenda "a" \
18566 org-agenda-span (quote month) \
18567 org-agenda-include-diary nil \
18568 org-agenda-files (quote ("~/org/project.org")))' \
18573 which will produce an agenda for the next 30 days from just the
18574 @file{~/org/projects.org} file.
18576 For structured processing of agenda output, use @code{org-batch-agenda-csv}
18577 with the following fields:
18580 category @r{The category of the item}
18581 head @r{The headline, without TODO keyword, TAGS and PRIORITY}
18582 type @r{The type of the agenda entry, can be}
18583 todo @r{selected in TODO match}
18584 tagsmatch @r{selected in tags match}
18585 diary @r{imported from diary}
18586 deadline @r{a deadline}
18587 scheduled @r{scheduled}
18588 timestamp @r{appointment, selected by timestamp}
18589 closed @r{entry was closed on date}
18590 upcoming-deadline @r{warning about nearing deadline}
18591 past-scheduled @r{forwarded scheduled item}
18592 block @r{entry has date block including date}
18593 todo @r{The TODO keyword, if any}
18594 tags @r{All tags including inherited ones, separated by colons}
18595 date @r{The relevant date, like 2007-2-14}
18596 time @r{The time, like 15:00-16:50}
18597 extra @r{String with extra planning info}
18598 priority-l @r{The priority letter if any was given}
18599 priority-n @r{The computed numerical priority}
18603 If the selection of the agenda item was based on a timestamp, including those
18604 items with @samp{DEADLINE} and @samp{SCHEDULED} keywords, then Org includes
18605 date and time in the output.
18607 If the selection of the agenda item was based on a timestamp (or
18608 deadline/scheduled), then Org includes date and time in the output.
18610 Here is an example of a post-processing script in Perl. It takes the CSV
18611 output from Emacs and prints with a checkbox:
18616 # define the Emacs command to run
18617 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
18619 # run it and capture the output
18620 $agenda = qx@{$cmd 2>/dev/null@};
18622 # loop over all lines
18623 foreach $line (split(/\n/,$agenda)) @{
18624 # get the individual values
18625 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
18626 $priority_l,$priority_n) = split(/,/,$line);
18627 # process and print
18628 print "[ ] $head\n";
18632 @node Using the property API
18633 @section Using the property API
18634 @cindex API, for properties
18635 @cindex properties, API
18637 Functions for working with properties.
18639 @defun org-entry-properties &optional pom which
18640 Get all properties of the entry at point-or-marker POM.@*
18641 This includes the TODO keyword, the tags, time strings for deadline,
18642 scheduled, and clocking, and any additional properties defined in the
18643 entry. The return value is an alist. Keys may occur multiple times
18644 if the property key was used several times.@*
18645 POM may also be @code{nil}, in which case the current entry is used.
18646 If WHICH is @code{nil} or @code{all}, get all properties. If WHICH is
18647 @code{special} or @code{standard}, only get that subclass.
18650 @vindex org-use-property-inheritance
18651 @findex org-insert-property-drawer
18652 @defun org-entry-get pom property &optional inherit
18653 Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@. By
18654 default, this only looks at properties defined locally in the entry. If
18655 @code{INHERIT} is non-@code{nil} and the entry does not have the property,
18656 then also check higher levels of the hierarchy. If @code{INHERIT} is the
18657 symbol @code{selective}, use inheritance if and only if the setting of
18658 @code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance.
18661 @defun org-entry-delete pom property
18662 Delete the property @code{PROPERTY} from entry at point-or-marker POM.
18665 @defun org-entry-put pom property value
18666 Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM.
18669 @defun org-buffer-property-keys &optional include-specials
18670 Get all property keys in the current buffer.
18673 @defun org-insert-property-drawer
18674 Insert a property drawer for the current entry.
18677 @defun org-entry-put-multivalued-property pom property &rest values
18678 Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@.
18679 @code{VALUES} should be a list of strings. They will be concatenated, with
18680 spaces as separators.
18683 @defun org-entry-get-multivalued-property pom property
18684 Treat the value of the property @code{PROPERTY} as a whitespace-separated
18685 list of values and return the values as a list of strings.
18688 @defun org-entry-add-to-multivalued-property pom property value
18689 Treat the value of the property @code{PROPERTY} as a whitespace-separated
18690 list of values and make sure that @code{VALUE} is in this list.
18693 @defun org-entry-remove-from-multivalued-property pom property value
18694 Treat the value of the property @code{PROPERTY} as a whitespace-separated
18695 list of values and make sure that @code{VALUE} is @emph{not} in this list.
18698 @defun org-entry-member-in-multivalued-property pom property value
18699 Treat the value of the property @code{PROPERTY} as a whitespace-separated
18700 list of values and check if @code{VALUE} is in this list.
18703 @defopt org-property-allowed-value-functions
18704 Hook for functions supplying allowed values for a specific property.
18705 The functions must take a single argument, the name of the property, and
18706 return a flat list of allowed values. If @samp{:ETC} is one of
18707 the values, use the values as completion help, but allow also other values
18708 to be entered. The functions must return @code{nil} if they are not
18709 responsible for this property.
18712 @node Using the mapping API
18713 @section Using the mapping API
18714 @cindex API, for mapping
18715 @cindex mapping entries, API
18717 Org has sophisticated mapping capabilities for finding entries. Org uses
18718 this functionality internally for generating agenda views. Org also exposes
18719 an API for executing arbitrary functions for each selected entry. The API's
18720 main entry point is:
18722 @defun org-map-entries func &optional match scope &rest skip
18723 Call @samp{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}.
18725 @samp{FUNC} is a function or a Lisp form. With the cursor positioned at the
18726 beginning of the headline, call the function without arguments. Org returns
18727 an alist of return values of calls to the function.
18729 To avoid preserving point, Org wraps the call to @code{FUNC} in
18730 save-excursion form. After evaluation, Org moves the cursor to the end of
18731 the line that was just processed. Search continues from that point forward.
18732 This may not always work as expected under some conditions, such as if the
18733 current sub-tree was removed by a previous archiving operation. In such rare
18734 circumstances, Org skips the next entry entirely when it should not. To stop
18735 Org from such skips, make @samp{FUNC} set the variable
18736 @code{org-map-continue-from} to a specific buffer position.
18738 @samp{MATCH} is a tags/property/TODO match. Org iterates only matched
18739 headlines. Org iterates over all headlines when @code{MATCH} is @code{nil}
18742 @samp{SCOPE} determines the scope of this command. It can be any of:
18745 nil @r{the current buffer, respecting the restriction if any}
18746 tree @r{the subtree started with the entry at point}
18747 region @r{The entries within the active region, if any}
18748 file @r{the current buffer, without restriction}
18750 @r{the current buffer, and any archives associated with it}
18751 agenda @r{all agenda files}
18752 agenda-with-archives
18753 @r{all agenda files with any archive files associated with them}
18755 @r{if this is a list, all files in the list will be scanned}
18758 The remaining args are treated as settings for the scanner's skipping
18759 facilities. Valid args are:
18761 @vindex org-agenda-skip-function
18763 archive @r{skip trees with the archive tag}
18764 comment @r{skip trees with the COMMENT keyword}
18765 function or Lisp form
18766 @r{will be used as value for @code{org-agenda-skip-function},}
18767 @r{so whenever the function returns t, FUNC}
18768 @r{will not be called for that entry and search will}
18769 @r{continue from the point where the function leaves it}
18773 The mapping routine can call any arbitrary function, even functions that
18774 change meta data or query the property API (@pxref{Using the property API}).
18775 Here are some handy functions:
18777 @defun org-todo &optional arg
18778 Change the TODO state of the entry. See the docstring of the functions for
18779 the many possible values for the argument @code{ARG}.
18782 @defun org-priority &optional action
18783 Change the priority of the entry. See the docstring of this function for the
18784 possible values for @code{ACTION}.
18787 @defun org-toggle-tag tag &optional onoff
18788 Toggle the tag @code{TAG} in the current entry. Setting @code{ONOFF} to
18789 either @code{on} or @code{off} will not toggle tag, but ensure that it is
18794 Promote the current entry.
18798 Demote the current entry.
18801 This example turns all entries tagged with @code{TOMORROW} into TODO entries
18802 with keyword @code{UPCOMING}. Org ignores entries in comment trees and
18807 '(org-todo "UPCOMING")
18808 "+TOMORROW" 'file 'archive 'comment)
18811 The following example counts the number of entries with TODO keyword
18812 @code{WAITING}, in all agenda files.
18815 (length (org-map-entries t "/+WAITING" 'agenda))
18819 @appendix MobileOrg
18823 MobileOrg is a companion mobile app that runs on iOS and Android devices.
18824 MobileOrg enables offline-views and capture support for an Org mode system
18825 that is rooted on a ``real'' computer. MobileOrg can record changes to
18828 The @uref{https://github.com/MobileOrg/, iOS implementation} for the
18829 @emph{iPhone/iPod Touch/iPad} series of devices, was started by Richard
18830 Moreland and is now in the hands Sean Escriva. Android users should check
18831 out @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg
18832 Android} by Matt Jones. Though the two implementations are not identical,
18833 they offer similar features.
18835 This appendix describes Org's support for agenda view formats compatible with
18836 MobileOrg. It also describes synchronizing changes, such as to notes,
18837 between MobileOrg and the computer.
18839 To change tags and TODO states in MobileOrg, first customize the variables
18840 @code{org-todo-keywords} and @code{org-tag-alist}. These should cover all
18841 the important tags and TODO keywords, even if Org files use only some of
18842 them. Though MobileOrg has in-buffer settings, it understands TODO states
18843 @emph{sets} (@pxref{Per-file keywords}) and @emph{mutually exclusive} tags
18844 (@pxref{Setting tags}) only for those set in these variables.
18847 * Setting up the staging area:: For the mobile device
18848 * Pushing to MobileOrg:: Uploading Org files and agendas
18849 * Pulling from MobileOrg:: Integrating captured and flagged items
18852 @node Setting up the staging area
18853 @section Setting up the staging area
18855 MobileOrg needs access to a file directory on a server to interact with
18856 Emacs. With a public server, consider encrypting the files. MobileOrg
18857 version 1.5 supports encryption for the iPhone. Org also requires
18858 @file{openssl} installed on the local computer. To turn on encryption, set
18859 the same password in MobileOrg and in Emacs. Set the password in the
18860 variable @code{org-mobile-use-encryption}@footnote{If Emacs is configured for
18861 safe storing of passwords, then configure the variable,
18862 @code{org-mobile-encryption-password}; please read the docstring of that
18863 variable.}. Note that even after MobileOrg encrypts the file contents, the
18864 file names will remain visible on the file systems of the local computer, the
18865 server, and the mobile device.
18867 For a server to host files, consider options like
18868 @uref{http://dropbox.com,Dropbox.com} account@footnote{An alternative is to
18869 use webdav server. MobileOrg documentation has details of webdav server
18870 configuration. Additional help is at
18871 @uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
18872 On first connection, MobileOrg creates a directory @file{MobileOrg/} on
18873 Dropbox. Pass its location to Emacs through an init file variable as
18877 (setq org-mobile-directory "~/Dropbox/MobileOrg")
18880 Org copies files to the above directory for MobileOrg. Org also uses the
18881 same directory for sharing notes between Org and MobileOrg.
18883 @node Pushing to MobileOrg
18884 @section Pushing to MobileOrg
18886 Org pushes files listed in @code{org-mobile-files} to
18887 @code{org-mobile-directory}. Files include agenda files (as listed in
18888 @code{org-agenda-files}). Customize @code{org-mobile-files} to add other
18889 files. File names will be staged with paths relative to
18890 @code{org-directory}, so all files should be inside this
18891 directory@footnote{Symbolic links in @code{org-directory} should have the
18892 same name as their targets.}.
18894 Push creates a special Org file @file{agendas.org} with custom agenda views
18895 defined by the user@footnote{While creating the agendas, Org mode will force
18896 ID properties on all referenced entries, so that these entries can be
18897 uniquely identified if MobileOrg flags them for further action. To avoid
18898 setting properties configure the variable
18899 @code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then
18900 rely on outline paths, assuming they are unique.}.
18902 Org writes the file @file{index.org}, containing links to other files.
18903 MobileOrg reads this file first from the server to determine what other files
18904 to download for agendas. For faster downloads, MobileOrg will read only
18905 those files whose checksums@footnote{Checksums are stored automatically in
18906 the file @file{checksums.dat}.} have changed.
18908 @node Pulling from MobileOrg
18909 @section Pulling from MobileOrg
18911 When MobileOrg synchronizes with the server, it pulls the Org files for
18912 viewing. It then appends to the file @file{mobileorg.org} on the server the
18913 captured entries, pointers to flagged and changed entries. Org integrates
18914 its data in an inbox file format.
18918 Org moves all entries found in
18919 @file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this
18920 operation.} and appends them to the file pointed to by the variable
18921 @code{org-mobile-inbox-for-pull}. Each captured entry and each editing event
18922 is a top-level entry in the inbox file.
18924 After moving the entries, Org attempts changes to MobileOrg. Some changes
18925 are applied directly and without user interaction. Examples include changes
18926 to tags, TODO state, headline and body text. Entries for further action are
18927 tagged as @code{:FLAGGED:}. Org marks entries with problems with an error
18928 message in the inbox. They have to be resolved manually.
18930 Org generates an agenda view for flagged entries for user intervention to
18931 clean up. For notes stored in flagged entries, MobileOrg displays them in
18932 the echo area when the cursor is on the corresponding agenda item.
18937 Pressing @kbd{?} displays the entire flagged note in another window. Org
18938 also pushes it to the kill ring. To store flagged note as a normal note, use
18939 @kbd{? z C-y C-c C-c}. Pressing @kbd{?} twice does these things: first it
18940 removes the @code{:FLAGGED:} tag; second, it removes the flagged note from
18941 the property drawer; third, it signals that manual editing of the flagged
18942 entry is now finished.
18947 @kbd{C-c a ?} returns to the agenda view to finish processing flagged
18948 entries. Note that these entries may not be the most recent since MobileOrg
18949 searches files that were last pulled. To get an updated agenda view with
18950 changes since the last pull, pull again.
18952 @node History and acknowledgments
18953 @appendix History and acknowledgments
18954 @cindex acknowledgments
18958 @section From Carsten
18960 Org was born in 2003, out of frustration over the user interface of the Emacs
18961 Outline mode. I was trying to organize my notes and projects, and using
18962 Emacs seemed to be the natural way to go. However, having to remember eleven
18963 different commands with two or three keys per command, only to hide and show
18964 parts of the outline tree, that seemed entirely unacceptable. Also, when
18965 using outlines to take notes, I constantly wanted to restructure the tree,
18966 organizing it paralleling my thoughts and plans. @emph{Visibility cycling}
18967 and @emph{structure editing} were originally implemented in the package
18968 @file{outline-magic.el}, but quickly moved to the more general @file{org.el}.
18969 As this environment became comfortable for project planning, the next step
18970 was adding @emph{TODO entries}, basic @emph{timestamps}, and @emph{table
18971 support}. These areas highlighted the two main goals that Org still has
18972 today: to be a new, outline-based, plain text mode with innovative and
18973 intuitive editing features, and to incorporate project planning functionality
18974 directly into a notes file.
18976 Since the first release, literally thousands of emails to me or to
18977 @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug
18978 reports, feedback, new ideas, and sometimes patches and add-on code.
18979 Many thanks to everyone who has helped to improve this package. I am
18980 trying to keep here a list of the people who had significant influence
18981 in shaping one or more aspects of Org. The list may not be
18982 complete, if I have forgotten someone, please accept my apologies and
18985 Before I get to this list, a few special mentions are in order:
18988 @item Bastien Guerry
18989 Bastien has written a large number of extensions to Org (most of them
18990 integrated into the core by now), including the @LaTeX{} exporter and the
18991 plain list parser. His support during the early days was central to the
18992 success of this project. Bastien also invented Worg, helped establishing the
18993 Web presence of Org, and sponsored hosting costs for the orgmode.org website.
18994 Bastien stepped in as maintainer of Org between 2011 and 2013, at a time when
18995 I desperately needed a break.
18996 @item Eric Schulte and Dan Davison
18997 Eric and Dan are jointly responsible for the Org-babel system, which turns
18998 Org into a multi-language environment for evaluating code and doing literate
18999 programming and reproducible research. This has become one of Org's killer
19000 features that define what Org is today.
19002 John has contributed a number of great ideas and patches directly to Org,
19003 including the attachment system (@file{org-attach.el}), integration with
19004 Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO
19005 items, habit tracking (@file{org-habits.el}), and encryption
19006 (@file{org-crypt.el}). Also, the capture system is really an extended copy
19007 of his great @file{remember.el}.
19008 @item Sebastian Rose
19009 Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
19010 of an ignorant amateur. Sebastian has pushed this part of Org onto a much
19011 higher level. He also wrote @file{org-info.js}, a Java script for displaying
19012 web pages derived from Org using an Info-like or a folding interface with
19013 single-key navigation.
19016 @noindent See below for the full list of contributions! Again, please
19017 let me know what I am missing here!
19019 @section From Bastien
19021 I (Bastien) have been maintaining Org between 2011 and 2013. This appendix
19022 would not be complete without adding a few more acknowledgments and thanks.
19024 I am first grateful to Carsten for his trust while handing me over the
19025 maintainership of Org. His unremitting support is what really helped me
19026 getting more confident over time, with both the community and the code.
19028 When I took over maintainership, I knew I would have to make Org more
19029 collaborative than ever, as I would have to rely on people that are more
19030 knowledgeable than I am on many parts of the code. Here is a list of the
19031 persons I could rely on, they should really be considered co-maintainers,
19032 either of the code or the community:
19036 Eric is maintaining the Babel parts of Org. His reactivity here kept me away
19037 from worrying about possible bugs here and let me focus on other parts.
19039 @item Nicolas Goaziou
19040 Nicolas is maintaining the consistency of the deepest parts of Org. His work
19041 on @file{org-element.el} and @file{ox.el} has been outstanding, and it opened
19042 the doors for many new ideas and features. He rewrote many of the old
19043 exporters to use the new export engine, and helped with documenting this
19044 major change. More importantly (if that's possible), he has been more than
19045 reliable during all the work done for Org 8.0, and always very reactive on
19049 Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
19050 into a flexible and conceptually clean process. He patiently coped with the
19051 many hiccups that such a change can create for users.
19054 The Org mode mailing list would not be such a nice place without Nick, who
19055 patiently helped users so many times. It is impossible to overestimate such
19056 a great help, and the list would not be so active without him.
19059 I received support from so many users that it is clearly impossible to be
19060 fair when shortlisting a few of them, but Org's history would not be
19061 complete if the ones above were not mentioned in this manual.
19063 @section List of contributions
19068 @i{Russel Adams} came up with the idea for drawers.
19070 @i{Suvayu Ali} has steadily helped on the mailing list, providing useful
19071 feedback on many features and several patches.
19073 @i{Luis Anaya} wrote @file{ox-man.el}.
19075 @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
19077 @i{Michael Brand} helped by reporting many bugs and testing many features.
19078 He also implemented the distinction between empty fields and 0-value fields
19079 in Org's spreadsheets.
19081 @i{Christophe Bataillon} created the great unicorn logo that we use on the
19084 @i{Alex Bochannek} provided a patch for rounding timestamps.
19086 @i{Jan Böcker} wrote @file{org-docview.el}.
19088 @i{Brad Bozarth} showed how to pull RSS feed data into Org mode files.
19090 @i{Tom Breton} wrote @file{org-choose.el}.
19092 @i{Charles Cave}'s suggestion sparked the implementation of templates
19093 for Remember, which are now templates for capture.
19095 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
19098 @i{Gregory Chernov} patched support for Lisp forms into table
19099 calculations and improved XEmacs compatibility, in particular by porting
19100 @file{nouline.el} to XEmacs.
19102 @i{Sacha Chua} suggested copying some linking code from Planner, and helped
19103 make Org pupular through her blog.
19105 @i{Toby S. Cubitt} contributed to the code for clock formats.
19107 @i{Baoqiu Cui} contributed the first DocBook exporter. In Org 8.0, we go a
19108 different route: you can now export to Texinfo and export the @file{.texi}
19109 file to DocBook using @code{makeinfo}.
19111 @i{Eddward DeVilla} proposed and tested checkbox statistics. He also
19112 came up with the idea of properties, and that there should be an API for
19115 @i{Nick Dokos} tracked down several nasty bugs.
19117 @i{Kees Dullemond} used to edit projects lists directly in HTML and so
19118 inspired some of the early development, including HTML export. He also
19119 asked for a way to narrow wide table columns.
19121 @i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for
19122 several years now. He also sponsored the hosting costs until Rackspace
19123 started to host us for free.
19125 @i{Thomas S. Dye} contributed documentation on Worg and helped integrating
19126 the Org-Babel documentation into the manual.
19128 @i{Christian Egli} converted the documentation into Texinfo format, inspired
19129 the agenda, patched CSS formatting into the HTML exporter, and wrote
19130 @file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as
19131 @file{ox-taskjuggler.el} for Org 8.0.
19133 @i{David Emery} provided a patch for custom CSS support in exported
19136 @i{Sean Escriva} took over MobileOrg development on the iPhone platform.
19138 @i{Nic Ferrier} contributed mailcap and XOXO support.
19140 @i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
19142 @i{John Foerch} figured out how to make incremental search show context
19143 around a match in a hidden outline tree.
19145 @i{Raimar Finken} wrote @file{org-git-line.el}.
19147 @i{Mikael Fornius} works as a mailing list moderator.
19149 @i{Austin Frank} works as a mailing list moderator.
19151 @i{Eric Fraga} drove the development of BEAMER export with ideas and
19154 @i{Barry Gidden} did proofreading the manual in preparation for the book
19155 publication through Network Theory Ltd.
19157 @i{Niels Giesen} had the idea to automatically archive DONE trees.
19159 @i{Nicolas Goaziou} rewrote much of the plain list code. He also wrote
19160 @file{org-element.el} and @file{org-export.el}, which was a huge step forward
19161 in implementing a clean framework for Org exporters.
19163 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
19165 @i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a
19168 @i{Bernt Hansen} has driven much of the support for auto-repeating tasks,
19169 task state change logging, and the clocktable. His clear explanations have
19170 been critical when we started to adopt the Git version control system.
19172 @i{Manuel Hermenegildo} has contributed various ideas, small fixes and
19175 @i{Phil Jackson} wrote @file{org-irc.el}.
19177 @i{Scott Jaderholm} proposed footnotes, control over whitespace between
19178 folded entries, and column view for properties.
19180 @i{Matt Jones} wrote @i{MobileOrg Android}.
19182 @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
19184 @i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}.
19186 @i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also
19187 provided frequent feedback and some patches.
19189 @i{Matt Lundin} has proposed last-row references for table formulas and named
19190 invisible anchors. He has also worked a lot on the FAQ.
19192 @i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,
19193 and is a prolific contributor on the mailing list with competent replies,
19194 small fixes and patches.
19196 @i{Jason F. McBrayer} suggested agenda export to CSV format.
19198 @i{Max Mikhanosha} came up with the idea of refiling and sticky agendas.
19200 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file
19203 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
19206 @i{Richard Moreland} wrote MobileOrg for the iPhone.
19208 @i{Rick Moynihan} proposed allowing multiple TODO sequences in a file
19209 and being able to quickly restrict the agenda to a subtree.
19211 @i{Todd Neal} provided patches for links to Info files and Elisp forms.
19213 @i{Greg Newman} refreshed the unicorn logo into its current form.
19215 @i{Tim O'Callaghan} suggested in-file links, search options for general
19216 file links, and TAGS.
19218 @i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text
19219 version of the reference card.
19221 @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
19224 @i{Oliver Oppitz} suggested multi-state TODO items.
19226 @i{Scott Otterson} sparked the introduction of descriptive text for
19227 links, among other things.
19229 @i{Pete Phillips} helped during the development of the TAGS feature, and
19230 provided frequent feedback.
19232 @i{Francesco Pizzolante} provided patches that helped speeding up the agenda
19235 @i{Martin Pohlack} provided the code snippet to bundle character insertion
19236 into bundles of 20 for undo.
19238 @i{Rackspace.com} is hosting our website for free. Thank you Rackspace!
19240 @i{T.V. Raman} reported bugs and suggested improvements.
19242 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
19245 @i{Paul Rivier} provided the basic implementation of named footnotes. He
19246 also acted as mailing list moderator for some time.
19248 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
19250 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
19251 conflict with @file{allout.el}.
19253 @i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with
19256 @i{Philip Rooke} created the Org reference card, provided lots
19257 of feedback, developed and applied standards to the Org documentation.
19259 @i{Christian Schlauer} proposed angular brackets around links, among
19262 @i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can
19263 enjoy folding in non-org buffers by using Org headlines in comments.
19265 @i{Paul Sexton} wrote @file{org-ctags.el}.
19267 Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
19268 @file{organizer-mode.el}.
19270 @i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal
19271 examples, and remote highlighting for referenced code lines.
19273 @i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is
19274 now packaged into Org's @file{contrib} directory.
19276 @i{Daniel Sinder} came up with the idea of internal archiving by locking
19279 @i{Dale Smith} proposed link abbreviations.
19281 @i{James TD Smith} has contributed a large number of patches for useful
19282 tweaks and features.
19284 @i{Adam Spiers} asked for global linking commands, inspired the link
19285 extension system, added support for mairix, and proposed the mapping API.
19287 @i{Ulf Stegemann} created the table to translate special symbols to HTML,
19288 @LaTeX{}, UTF-8, Latin-1 and ASCII.
19290 @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
19291 with links transformation to Org syntax.
19293 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
19294 chapter about publishing.
19296 @i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter.
19298 @i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
19299 enabled source code highlighting in Gnus.
19301 @i{Stefan Vollmar} organized a video-recorded talk at the
19302 Max-Planck-Institute for Neurology. He also inspired the creation of a
19303 concept index for HTML export.
19305 @i{Jürgen Vollmer} contributed code generating the table of contents
19308 @i{Samuel Wales} has provided important feedback and bug reports.
19310 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
19313 @i{David Wainberg} suggested archiving, and improvements to the linking
19316 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
19319 @i{Roland Winkler} requested additional key bindings to make Org
19322 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
19323 and contributed various ideas and code snippets.
19325 @i{Marco Wahl} wrote @file{org-eww.el}.
19329 @node GNU Free Documentation License
19330 @appendix GNU Free Documentation License
19331 @include doclicense.texi
19335 @unnumbered Concept index
19340 @unnumbered Key index
19344 @node Command and Function Index
19345 @unnumbered Command and function index
19349 @node Variable Index
19350 @unnumbered Variable index
19352 This is not a complete index of variables and faces, only the ones that are
19353 mentioned in the manual. For a complete list, use @kbd{M-x org-customize
19360 @c Local variables:
19362 @c indent-tabs-mode: nil
19363 @c paragraph-start: "
\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$"
19364 @c paragraph-separate: "
\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$"
19368 @c LocalWords: webdavhost pre