1 \input texinfo @c -*- coding: utf-8 -*-
3 @setfilename ../../info/org.info
4 @settitle The Org Manual
10 @c Version and Contact Info
11 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page}
12 @set AUTHOR Carsten Dominik
13 @set MAINTAINER Carsten Dominik
14 @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
15 @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
20 @c -----------------------------------------------------------------------------
22 @c Macro definitions for commands and keys
23 @c =======================================
25 @c The behavior of the key/command macros will depend on the flag cmdnames
26 @c When set, commands names are shown. When clear, they are not shown.
30 @c Below we define the following macros for Org key tables:
32 @c orgkey{key} A key item
33 @c orgcmd{key,cmd} Key with command name
34 @c xorgcmd{key,cmd} Key with command name as @itemx
35 @c orgcmdnki{key,cmd} Like orgcmd, but do not index the key
36 @c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key
37 @c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or"
38 @c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but
39 @c different functions, so format as @itemx
40 @c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short"
41 @c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx
42 @c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands
44 @c a key but no command
56 @c one key with a command
57 @c Inserts: @item KEY COMMAND
58 @macro orgcmd{key,command}
63 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
66 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
75 @c One key with one command, formatted using @itemx
76 @c Inserts: @itemx KEY COMMAND
77 @macro xorgcmd{key,command}
82 @itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
85 @itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
94 @c one key with a command, bit do not index the key
95 @c Inserts: @item KEY COMMAND
96 @macro orgcmdnki{key,command}
100 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
103 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
111 @c one key with a command, and special text to replace key in item
112 @c Inserts: @item TEXT COMMAND
113 @macro orgcmdtkc{text,key,command}
118 @item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
121 @item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
130 @c two keys with one command
131 @c Inserts: @item KEY1 or KEY2 COMMAND
132 @macro orgcmdkkc{key1,key2,command}
138 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
141 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
147 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
151 @c Two keys with one command name, but different functions, so format as
153 @c Inserts: @item KEY1
154 @c @itemx KEY2 COMMAND
155 @macro orgcmdkxkc{key1,key2,command}
162 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
166 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
177 @c Same as previous, but use "or short"
178 @c Inserts: @item KEY1 or short KEY2 COMMAND
179 @macro orgcmdkskc{key1,key2,command}
185 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
188 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
194 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
198 @c Same as previous, but use @itemx
199 @c Inserts: @itemx KEY1 or short KEY2 COMMAND
200 @macro xorgcmdkskc{key1,key2,command}
206 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
209 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
215 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
219 @c two keys with two commands
220 @c Inserts: @item KEY1 COMMAND1
221 @c @itemx KEY2 COMMAND2
222 @macro orgcmdkkcc{key1,key2,command1,command2}
229 @item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
230 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
233 @item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
234 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
244 @c -----------------------------------------------------------------------------
247 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
250 @c Subheadings inside a table.
251 @macro tsubheading{text}
253 @subsubheading \text\
261 This manual is for Org version @value{VERSION}.
263 Copyright @copyright{} 2004--2017 Free Software Foundation, Inc.
266 Permission is granted to copy, distribute and/or modify this document
267 under the terms of the GNU Free Documentation License, Version 1.3 or
268 any later version published by the Free Software Foundation; with no
269 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
270 and with the Back-Cover Texts as in (a) below. A copy of the license
271 is included in the section entitled ``GNU Free Documentation License.''
273 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
274 modify this GNU manual.''
278 @dircategory Emacs editing modes
280 * Org Mode: (org). Outline-based notes management and organizer
284 @title The Org Manual
286 @subtitle Release @value{VERSION}
287 @author by Carsten Dominik
288 with contributions by Bastien Guerry, Nicolas Goaziou, Eric Schulte,
289 Jambunathan K, Dan Davison, Thomas Dye, David O'Toole, and Philip Rooke.
291 @c The following two commands start the copyright page.
293 @vskip 0pt plus 1filll
297 @c Output the short table of contents at the beginning.
300 @c Output the table of contents at the beginning.
305 @node Top, Introduction, (dir), (dir)
312 * Introduction:: Getting started
313 * Document structure:: A tree works like your brain
314 * Tables:: Pure magic for quick formatting
315 * Hyperlinks:: Notes in context
316 * TODO items:: Every tree branch can be a TODO item
317 * Tags:: Tagging headlines and matching sets of tags
318 * Properties and columns:: Storing information about an entry
319 * Dates and times:: Making items useful for planning
320 * Capture - Refile - Archive:: The ins and outs for projects
321 * Agenda views:: Collecting information into views
322 * Markup:: Prepare text for rich export
323 * Exporting:: Sharing and publishing notes
324 * Publishing:: Create a web site of linked Org files
325 * Working with source code:: Export, evaluate, and tangle code blocks
326 * Miscellaneous:: All the rest which did not fit elsewhere
327 * Hacking:: How to hack your way around
328 * MobileOrg:: Viewing and capture on a mobile device
329 * History and acknowledgments:: How Org came into being
330 * GNU Free Documentation License:: The license for this documentation.
331 * Main Index:: An index of Org's concepts and features
332 * Key Index:: Key bindings and where they are described
333 * Command and Function Index:: Command names and some internal functions
334 * Variable Index:: Variables mentioned in the manual
337 --- The Detailed Node Listing ---
341 * Summary:: Brief summary of what Org does
342 * Installation:: Installing Org
343 * Activation:: How to activate Org for certain buffers
344 * Feedback:: Bug reports, ideas, patches etc.
345 * Conventions:: Typesetting conventions in the manual
349 * Outlines:: Org is based on Outline mode
350 * Headlines:: How to typeset Org tree headlines
351 * Visibility cycling:: Show and hide, much simplified
352 * Motion:: Jumping to other headlines
353 * Structure editing:: Changing sequence and level of headlines
354 * Sparse trees:: Matches embedded in context
355 * Plain lists:: Additional structure within an entry
356 * Drawers:: Tucking stuff away
357 * Blocks:: Folding blocks
358 * Footnotes:: How footnotes are defined in Org's syntax
359 * Orgstruct mode:: Structure editing outside Org
360 * Org syntax:: Formal description of Org's syntax
364 * Global and local cycling:: Cycling through various visibility states
365 * Initial visibility:: Setting the initial visibility state
366 * Catching invisible edits:: Preventing mistakes when editing invisible parts
370 * Built-in table editor:: Simple tables
371 * Column width and alignment:: Overrule the automatic settings
372 * Column groups:: Grouping to trigger vertical lines
373 * Orgtbl mode:: The table editor as minor mode
374 * The spreadsheet:: The table editor has spreadsheet capabilities
375 * Org-Plot:: Plotting from org tables
379 * References:: How to refer to another field or range
380 * Formula syntax for Calc:: Using Calc to compute stuff
381 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
382 * Durations and time values:: How to compute durations and time values
383 * Field and range formulas:: Formula for specific (ranges of) fields
384 * Column formulas:: Formulas valid for an entire column
385 * Lookup functions:: Lookup functions for searching tables
386 * Editing and debugging formulas:: Fixing formulas
387 * Updating the table:: Recomputing all dependent fields
388 * Advanced features:: Field and column names, parameters and automatic recalc
392 * Link format:: How links in Org are formatted
393 * Internal links:: Links to other places in the current file
394 * External links:: URL-like links to the world
395 * Handling links:: Creating, inserting and following
396 * Using links outside Org:: Linking from my C source code?
397 * Link abbreviations:: Shortcuts for writing complex links
398 * Search options:: Linking to a specific location
399 * Custom searches:: When the default search is not enough
403 * Radio targets:: Make targets trigger links in plain text
407 * TODO basics:: Marking and displaying TODO entries
408 * TODO extensions:: Workflow and assignments
409 * Progress logging:: Dates and notes for progress
410 * Priorities:: Some things are more important than others
411 * Breaking down tasks:: Splitting a task into manageable pieces
412 * Checkboxes:: Tick-off lists
414 Extended use of TODO keywords
416 * Workflow states:: From TODO to DONE in steps
417 * TODO types:: I do this, Fred does the rest
418 * Multiple sets in one file:: Mixing it all, and still finding your way
419 * Fast access to TODO states:: Single letter selection of a state
420 * Per-file keywords:: Different files, different requirements
421 * Faces for TODO keywords:: Highlighting states
422 * TODO dependencies:: When one task needs to wait for others
426 * Closing items:: When was this entry marked DONE?
427 * Tracking TODO state changes:: When did the status change?
428 * Tracking your habits:: How consistent have you been?
432 * Tag inheritance:: Tags use the tree structure of the outline
433 * Setting tags:: How to assign tags to a headline
434 * Tag hierarchy:: Create a hierarchy of tags
435 * Tag searches:: Searching for combinations of tags
437 Properties and columns
439 * Property syntax:: How properties are spelled out
440 * Special properties:: Access to other Org mode features
441 * Property searches:: Matching property values
442 * Property inheritance:: Passing values down the tree
443 * Column view:: Tabular viewing and editing
444 * Property API:: Properties for Lisp programmers
448 * Defining columns:: The COLUMNS format property
449 * Using column view:: How to create and use column view
450 * Capturing column view:: A dynamic block for column view
454 * Scope of column definitions:: Where defined, where valid?
455 * Column attributes:: Appearance and content of a column
459 * Timestamps:: Assigning a time to a tree entry
460 * Creating timestamps:: Commands which insert timestamps
461 * Deadlines and scheduling:: Planning your work
462 * Clocking work time:: Tracking how long you spend on a task
463 * Effort estimates:: Planning work effort in advance
464 * Timers:: Notes with a running timer
468 * The date/time prompt:: How Org mode helps you entering date and time
469 * Custom time format:: Making dates look different
471 Deadlines and scheduling
473 * Inserting deadline/schedule:: Planning items
474 * Repeated tasks:: Items that show up again and again
478 * Clocking commands:: Starting and stopping a clock
479 * The clock table:: Detailed reports
480 * Resolving idle time:: Resolving time when you've been idle
482 Capture - Refile - Archive
484 * Capture:: Capturing new stuff
485 * Attachments:: Add files to tasks
486 * RSS feeds:: Getting input from RSS feeds
487 * Protocols:: External (e.g., Browser) access to Emacs and Org
488 * Refile and copy:: Moving/copying a tree from one place to another
489 * Archiving:: What to do with finished projects
493 * Setting up capture:: Where notes will be stored
494 * Using capture:: Commands to invoke and terminate capture
495 * Capture templates:: Define the outline of different note types
499 * Template elements:: What is needed for a complete template entry
500 * Template expansion:: Filling in information about time and context
501 * Templates in contexts:: Only show a template in a specific context
503 Protocols for external access
505 * @code{store-link} protocol:: Store a link, push URL to kill-ring.
506 * @code{capture} protocol:: Fill a buffer with external information.
507 * @code{open-source} protocol:: Edit published contents.
511 * Moving subtrees:: Moving a tree to an archive file
512 * Internal archiving:: Switch off a tree but keep it in the file
516 * Agenda files:: Files being searched for agenda information
517 * Agenda dispatcher:: Keyboard access to agenda views
518 * Built-in agenda views:: What is available out of the box?
519 * Presentation and sorting:: How agenda items are prepared for display
520 * Agenda commands:: Remote editing of Org trees
521 * Custom agenda views:: Defining special searches and views
522 * Exporting agenda views:: Writing a view to a file
523 * Agenda column view:: Using column view for collected entries
525 The built-in agenda views
527 * Weekly/daily agenda:: The calendar page with current tasks
528 * Global TODO list:: All unfinished action items
529 * Matching tags and properties:: Structured information with fine-tuned search
530 * Search view:: Find entries by searching for text
531 * Stuck projects:: Find projects you need to review
533 Presentation and sorting
535 * Categories:: Not all tasks are equal
536 * Time-of-day specifications:: How the agenda knows the time
537 * Sorting agenda items:: The order of things
538 * Filtering/limiting agenda items:: Dynamically narrow the agenda
542 * Storing searches:: Type once, use often
543 * Block agenda:: All the stuff you need in a single buffer
544 * Setting options:: Changing the rules
546 Markup for rich export
548 * Paragraphs:: The basic unit of text
549 * Emphasis and monospace:: Bold, italic, etc.
550 * Horizontal rules:: Make a line
551 * Images and tables:: Images, tables and caption mechanism
552 * Literal examples:: Source code examples with special formatting
553 * Special symbols:: Greek letters and other symbols
554 * Subscripts and superscripts:: Simple syntax for raising/lowering text
555 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
559 * @LaTeX{} fragments:: Complex formulas made easy
560 * Previewing @LaTeX{} fragments:: What will this snippet look like?
561 * CDLaTeX mode:: Speed up entering of formulas
565 * The export dispatcher:: The main interface
566 * Export settings:: Common export settings
567 * Table of contents:: The if and where of the table of contents
568 * Include files:: Include additional files into a document
569 * Macro replacement:: Use macros to create templates
570 * Comment lines:: What will not be exported
571 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
572 * Beamer export:: Exporting as a Beamer presentation
573 * HTML export:: Exporting to HTML
574 * @LaTeX{} export:: Exporting to @LaTeX{}, and processing to PDF
575 * Markdown export:: Exporting to Markdown
576 * OpenDocument Text export:: Exporting to OpenDocument Text
577 * Org export:: Exporting to Org
578 * Texinfo export:: Exporting to Texinfo
579 * iCalendar export:: Exporting to iCalendar
580 * Other built-in back-ends:: Exporting to a man page
581 * Advanced configuration:: Fine-tuning the export output
582 * Export in foreign buffers:: Author tables and lists in Org syntax
586 * Beamer export commands:: For creating Beamer documents.
587 * Beamer specific export settings:: For customizing Beamer export.
588 * Sectioning Frames and Blocks in Beamer:: For composing Beamer slides.
589 * Beamer specific syntax:: For using in Org documents.
590 * Editing support:: For using helper functions.
591 * A Beamer example:: A complete presentation.
595 * HTML Export commands:: Invoking HTML export
596 * HTML Specific export settings:: Settings for HTML export
597 * HTML doctypes:: Exporting various (X)HTML flavors
598 * HTML preamble and postamble:: Inserting preamble and postamble
599 * Quoting HTML tags:: Using direct HTML in Org files
600 * Links in HTML export:: Interpreting and formatting links
601 * Tables in HTML export:: Formatting and modifying tables
602 * Images in HTML export:: Inserting figures with HTML output
603 * Math formatting in HTML export:: Handling math equations
604 * Text areas in HTML export:: Showing an alternate approach, an example
605 * CSS support:: Styling HTML output
606 * JavaScript support:: Folding scripting in the web browser
610 * @LaTeX{} export commands:: For producing @LaTeX{} and PDF documents.
611 * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end.
612 * @LaTeX{} header and sectioning:: For file structure.
613 * Quoting @LaTeX{} code:: Directly in the Org document.
614 * Tables in @LaTeX{} export:: Attributes specific to tables.
615 * Images in @LaTeX{} export:: Attributes specific to images.
616 * Plain lists in @LaTeX{} export:: Attributes specific to lists.
617 * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks.
618 * Example blocks in @LaTeX{} export:: Attributes specific to example blocks.
619 * Special blocks in @LaTeX{} export:: Attributes specific to special blocks.
620 * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules.
622 OpenDocument Text export
624 * Pre-requisites for ODT export:: Required packages.
625 * ODT export commands:: Invoking export.
626 * ODT specific export settings:: Configuration options.
627 * Extending ODT export:: Producing @file{.doc}, @file{.pdf} files.
628 * Applying custom styles:: Styling the output.
629 * Links in ODT export:: Handling and formatting links.
630 * Tables in ODT export:: Org table conversions.
631 * Images in ODT export:: Inserting images.
632 * Math formatting in ODT export:: Formatting @LaTeX{} fragments.
633 * Labels and captions in ODT export:: Rendering objects.
634 * Literal examples in ODT export:: For source code and example blocks.
635 * Advanced topics in ODT export:: For power users.
637 Math formatting in ODT export
639 * Working with @LaTeX{} math snippets:: Embedding in @LaTeX{} format.
640 * Working with MathML or OpenDocument formula files:: Embedding in native format.
642 Advanced topics in ODT export
644 * Configuring a document converter:: Registering a document converter.
645 * Working with OpenDocument style files:: Exploring internals.
646 * Creating one-off styles:: Customizing styles, highlighting.
647 * Customizing tables in ODT export:: Defining table templates.
648 * Validating OpenDocument XML:: Debugging corrupted OpenDocument files.
652 * Texinfo export commands:: Invoking commands.
653 * Texinfo specific export settings:: Setting the environment.
654 * Texinfo file header:: Generating the header.
655 * Texinfo title and copyright page:: Creating preamble pages.
656 * Info directory file:: Installing a manual in Info file hierarchy.
657 * Headings and sectioning structure:: Building document structure.
658 * Indices:: Creating indices.
659 * Quoting Texinfo code:: Incorporating literal Texinfo code.
660 * Plain lists in Texinfo export:: List attributes.
661 * Tables in Texinfo export:: Table attributes.
662 * Images in Texinfo export:: Image attributes.
663 * Special blocks in Texinfo export:: Special block attributes.
664 * A Texinfo example:: Processing Org to Texinfo.
668 * Configuration:: Defining projects
669 * Uploading files:: How to get files up on the server
670 * Sample configuration:: Example projects
671 * Triggering publication:: Publication commands
675 * Project alist:: The central configuration variable
676 * Sources and destinations:: From here to there
677 * Selecting files:: What files are part of the project?
678 * Publishing action:: Setting the function doing the publishing
679 * Publishing options:: Tweaking HTML/@LaTeX{} export
680 * Publishing links:: Which links keep working after publishing?
681 * Sitemap:: Generating a list of all pages
682 * Generating an index:: An index that reaches across pages
686 * Simple example:: One-component publishing
687 * Complex example:: A multi-component publishing example
689 Working with source code
691 * Structure of code blocks:: Code block syntax described
692 * Editing source code:: Language major-mode editing
693 * Exporting code blocks:: Export contents and/or results
694 * Extracting source code:: Create pure source code files
695 * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
696 * Library of Babel:: Use and contribute to a library of useful code blocks
697 * Languages:: List of supported code block languages
698 * Header arguments:: Configure code block functionality
699 * Results of evaluation:: How evaluation results are handled
700 * Noweb reference syntax:: Literate programming in Org mode
701 * Key bindings and useful functions:: Work quickly with code blocks
702 * Batch execution:: Call functions from the command line
706 * Using header arguments:: Different ways to set header arguments
707 * Specific header arguments:: List of header arguments
709 Using header arguments
711 * System-wide header arguments:: Set globally, language-specific
712 * Language-specific header arguments:: Set in the Org file's headers
713 * Header arguments in Org mode properties:: Set in the Org file
714 * Language-specific mode properties::
715 * Code block specific header arguments:: The most commonly used method
716 * Arguments in function calls:: The most specific level, takes highest priority
718 Specific header arguments
720 * var:: Pass arguments to @samp{src} code blocks
721 * results:: Specify results type; how to collect
722 * file:: Specify a path for output file
723 * file-desc:: Specify a description for file results
724 * file-ext:: Specify an extension for file output
725 * output-dir:: Specify a directory for output file
726 * dir:: Specify the default directory for code block execution
727 * exports:: Specify exporting code, results, both, none
728 * tangle:: Toggle tangling; or specify file name
729 * mkdirp:: Toggle for parent directory creation for target files during tangling
730 * comments:: Toggle insertion of comments in tangled code files
731 * padline:: Control insertion of padding lines in tangled code files
732 * no-expand:: Turn off variable assignment and noweb expansion during tangling
733 * session:: Preserve the state of code evaluation
734 * noweb:: Toggle expansion of noweb references
735 * noweb-ref:: Specify block's noweb reference resolution target
736 * noweb-sep:: String to separate noweb references
737 * cache:: Avoid re-evaluating unchanged code blocks
738 * sep:: Delimiter for writing tabular results outside Org
739 * hlines:: Handle horizontal lines in tables
740 * colnames:: Handle column names in tables
741 * rownames:: Handle row names in tables
742 * shebang:: Make tangled files executable
743 * tangle-mode:: Set permission of tangled files
744 * eval:: Limit evaluation of specific code blocks
745 * wrap:: Mark source block evaluation results
746 * post:: Post processing of results of code block evaluation
747 * prologue:: Text to prepend to body of code block
748 * epilogue:: Text to append to body of code block
752 * Completion:: M-TAB guesses completions
753 * Easy templates:: Quick insertion of structural elements
754 * Speed keys:: Electric commands at the beginning of a headline
755 * Code evaluation security:: Org mode files evaluate inline code
756 * Customization:: Adapting Org to changing tastes
757 * In-buffer settings:: Overview of the #+KEYWORDS
758 * The very busy C-c C-c key:: When in doubt, press C-c C-c
759 * Clean view:: Getting rid of leading stars in the outline
760 * TTY keys:: Using Org on a tty
761 * Interaction:: With other Emacs packages
762 * org-crypt:: Encrypting Org files
764 Interaction with other packages
766 * Cooperation:: Packages Org cooperates with
767 * Conflicts:: Packages that lead to conflicts
771 * Hooks:: How to reach into Org's internals
772 * Add-on packages:: Available extensions
773 * Adding hyperlink types:: New custom link types
774 * Adding export back-ends:: How to write new export back-ends
775 * Context-sensitive commands:: How to add functionality to such commands
776 * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
777 * Dynamic blocks:: Automatically filled blocks
778 * Special agenda views:: Customized views
779 * Speeding up your agendas:: Tips on how to speed up your agendas
780 * Extracting agenda information:: Post-processing of agenda information
781 * Using the property API:: Writing programs that use entry properties
782 * Using the mapping API:: Mapping over all or selected entries
784 Tables and lists in arbitrary syntax
786 * Radio tables:: Sending and receiving radio tables
787 * A @LaTeX{} example:: Step by step, almost a tutorial
788 * Translator functions:: Copy and modify
789 * Radio lists:: Sending and receiving lists
793 * Setting up the staging area:: For the mobile device
794 * Pushing to MobileOrg:: Uploading Org files and agendas
795 * Pulling from MobileOrg:: Integrating captured and flagged items
801 @chapter Introduction
805 * Summary:: Brief summary of what Org does
806 * Installation:: Installing Org
807 * Activation:: How to activate Org for certain buffers
808 * Feedback:: Bug reports, ideas, patches etc.
809 * Conventions:: Typesetting conventions in the manual
816 Org is a mode for keeping notes, maintaining TODO lists, and project planning
817 with a fast and effective plain-text system. It also is an authoring system
818 with unique support for literate programming and reproducible research.
820 Org is implemented on top of Outline mode, which makes it possible to keep
821 the content of large files well structured. Visibility cycling and structure
822 editing help to work with the tree. Tables are easily created with a
823 built-in table editor. Plain text URL-like links connect to websites,
824 emails, Usenet messages, BBDB entries, and any files related to the projects.
826 Org develops organizational tasks around notes files that contain lists or
827 information about projects as plain text. Project planning and task
828 management makes use of metadata which is part of an outline node. Based on
829 this data, specific entries can be extracted in queries and create dynamic
830 @i{agenda views} that also integrate the Emacs calendar and diary. Org can
831 be used to implement many different project planning schemes, such as David
834 Org files can serve as a single source authoring system with export to many
835 different formats such as HTML, @LaTeX{}, Open Document, and Markdown. New
836 export backends can be derived from existing ones, or defined from scratch.
838 Org files can include source code blocks, which makes Org uniquely suited for
839 authoring technical documents with code examples. Org source code blocks are
840 fully functional; they can be evaluated in place and their results can be
841 captured in the file. This makes it possible to create a single file
842 reproducible research compendium.
844 Org keeps simple things simple. When first fired up, it should feel like a
845 straightforward, easy to use outliner. Complexity is not imposed, but a
846 large amount of functionality is available when needed. Org is a toolbox.
847 Many users actually run only a (very personal) fraction of Org's capabilities, and
848 know that there is more whenever they need it.
850 All of this is achieved with strictly plain text files, the most portable and
851 future-proof file format. Org runs in Emacs. Emacs is one of the most
852 widely ported programs, so that Org mode is available on every major
856 There is a website for Org which provides links to the newest
857 version of Org, as well as additional information, frequently asked
858 questions (FAQ), links to tutorials, etc. This page is located at
859 @uref{http://orgmode.org}.
860 @cindex print edition
862 An earlier version (7.3) of this manual is available as a
863 @uref{http://www.network-theory.co.uk/org/manual/, paperback book from
869 @section Installation
872 Org is part of recent distributions of GNU Emacs, so you normally don't need
873 to install it. If, for one reason or another, you want to install Org on top
874 of this pre-packaged version, there are three ways to do it:
877 @item By using Emacs package system.
878 @item By downloading Org as an archive.
879 @item By using Org's git repository.
882 We @b{strongly recommend} to stick to a single installation method.
884 @subsubheading Using Emacs packaging system
886 Recent Emacs distributions include a packaging system which lets you install
887 Elisp libraries. You can install Org with @kbd{M-x package-install RET org}.
889 @noindent @b{Important}: you need to do this in a session where no @code{.org} file has
890 been visited, i.e., where no Org built-in function have been loaded.
891 Otherwise autoload Org functions will mess up the installation.
893 Then, to make sure your Org configuration is taken into account, initialize
894 the package system with @code{(package-initialize)} in your Emacs init file
895 before setting any Org option. If you want to use Org's package repository,
896 check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
898 @subsubheading Downloading Org as an archive
900 You can download Org latest release from @uref{http://orgmode.org/, Org's
901 website}. In this case, make sure you set the load-path correctly in your
905 (add-to-list 'load-path "~/path/to/orgdir/lisp")
908 The downloaded archive contains contributed libraries that are not included
909 in Emacs. If you want to use them, add the @file{contrib} directory to your
913 (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
916 Optionally, you can compile the files and/or install them in your system.
917 Run @code{make help} to list compilation and installation options.
919 @subsubheading Using Org's git repository
921 You can clone Org's repository and install Org like this:
925 $ git clone git://orgmode.org/org-mode.git
929 Note that in this case, @code{make autoloads} is mandatory: it defines Org's
930 version in @file{org-version.el} and Org's autoloads in
931 @file{org-loaddefs.el}.
933 Remember to add the correct load-path as described in the method above.
935 You can also compile with @code{make}, generate the documentation with
936 @code{make doc}, create a local configuration with @code{make config} and
937 install Org with @code{make install}. Please run @code{make help} to get
938 the list of compilation/installation options.
940 For more detailed explanations on Org's build system, please check the Org
941 Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
949 @cindex global key bindings
950 @cindex key bindings, global
953 @findex org-store-link
956 Org mode buffers need font-lock to be turned on: this is the default in
957 Emacs@footnote{If you don't use font-lock globally, turn it on in Org buffer
958 with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
960 There are compatibility issues between Org mode and some other Elisp
961 packages, please take the time to check the list (@pxref{Conflicts}).
963 The four Org commands @command{org-store-link}, @command{org-capture},
964 @command{org-agenda}, and @command{org-iswitchb} should be accessible through
965 global keys (i.e., anywhere in Emacs, not just in Org buffers). Here are
966 suggested bindings for these keys, please modify the keys to your own
969 (global-set-key "\C-cl" 'org-store-link)
970 (global-set-key "\C-ca" 'org-agenda)
971 (global-set-key "\C-cc" 'org-capture)
972 (global-set-key "\C-cb" 'org-iswitchb)
975 @cindex Org mode, turning on
976 Files with the @file{.org} extension use Org mode by default. To turn on Org
977 mode in a file that does not have the extension @file{.org}, make the first
978 line of a file look like this:
981 MY PROJECTS -*- mode: org; -*-
984 @vindex org-insert-mode-line-in-empty-file
985 @noindent which will select Org mode for this buffer no matter what
986 the file's name is. See also the variable
987 @code{org-insert-mode-line-in-empty-file}.
989 Many commands in Org work on the region if the region is @i{active}. To make
990 use of this, you need to have @code{transient-mark-mode} turned on, which is
991 the default. If you do not like @code{transient-mark-mode}, you can create
992 an active region by using the mouse to select a region, or pressing
993 @kbd{C-@key{SPC}} twice before moving the cursor.
1002 If you find problems with Org, or if you have questions, remarks, or ideas
1003 about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
1004 You can subscribe to the list
1005 @uref{https://lists.gnu.org/mailman/listinfo/emacs-orgmode, on this web page}.
1006 If you are not a member of the mailing list, your mail will be passed to the
1007 list after a moderator has approved it@footnote{Please consider subscribing
1008 to the mailing list, in order to minimize the work the mailing list
1009 moderators have to do.}.
1011 For bug reports, please first try to reproduce the bug with the latest
1012 version of Org available---if you are running an outdated version, it is
1013 quite possible that the bug has been fixed already. If the bug persists,
1014 prepare a report and provide as much information as possible, including the
1015 version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
1016 (@kbd{M-x org-version RET}), as well as the Org related setup in the Emacs
1017 init file. The easiest way to do this is to use the command
1019 @kbd{M-x org-submit-bug-report RET}
1021 @noindent which will put all this information into an Emacs mail buffer so
1022 that you only need to add your description. If you are not sending the Email
1023 from within Emacs, please copy and paste the content into your Email program.
1025 Sometimes you might face a problem due to an error in your Emacs or Org mode
1026 setup. Before reporting a bug, it is very helpful to start Emacs with minimal
1027 customizations and reproduce the problem. Doing so often helps you determine
1028 if the problem is with your customization or with Org mode itself. You can
1029 start a typical minimal session with a command like the example below.
1032 $ emacs -Q -l /path/to/minimal-org.el
1035 However if you are using Org mode as distributed with Emacs, a minimal setup
1036 is not necessary. In that case it is sufficient to start Emacs as
1037 @code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
1041 ;;; Minimal setup to load latest 'org-mode'
1043 ;; activate debugging
1044 (setq debug-on-error t
1048 ;; add latest org-mode to load path
1049 (add-to-list 'load-path "/path/to/org-mode/lisp")
1050 (add-to-list 'load-path "/path/to/org-mode/contrib/lisp" t)
1053 If an error occurs, a backtrace can be very useful (see below on how to
1054 create one). Often a small example file helps, along with clear information
1058 @item What exactly did you do?
1059 @item What did you expect to happen?
1060 @item What happened instead?
1062 @noindent Thank you for helping to improve this program.
1064 @subsubheading How to create a useful backtrace
1066 @cindex backtrace of an error
1067 If working with Org produces an error with a message you don't
1068 understand, you may have hit a bug. The best way to report this is by
1069 providing, in addition to what was mentioned above, a @emph{backtrace}.
1070 This is information from the built-in debugger about where and how the
1071 error occurred. Here is how to produce a useful backtrace:
1075 Reload uncompiled versions of all Org mode Lisp files. The backtrace
1076 contains much more information if it is produced with uncompiled code.
1079 @kbd{C-u M-x org-reload RET}
1082 or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
1085 Go to the @code{Options} menu and select @code{Enter Debugger on Error}.
1087 Do whatever you have to do to hit the error. Don't forget to
1088 document the steps you take.
1090 When you hit the error, a @file{*Backtrace*} buffer will appear on the
1091 screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
1092 attach it to your bug report.
1096 @section Typesetting conventions used in this manual
1098 @subsubheading TODO keywords, tags, properties, etc.
1100 Org mainly uses three types of keywords: TODO keywords, tags and property
1101 names. In this manual we use the following conventions:
1106 TODO keywords are written with all capitals, even if they are
1110 User-defined tags are written in lowercase; built-in tags with special
1111 meaning are written with all capitals.
1114 User-defined properties are capitalized; built-in properties with
1115 special meaning are written with all capitals.
1118 Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
1119 and @i{environment keywords} (like @code{#+BEGIN_EXPORT html} to start
1120 a @code{HTML} environment). They are written in uppercase in the manual to
1121 enhance its readability, but you can use lowercase in your Org file.
1123 @subsubheading Key bindings and commands
1129 The manual suggests a few global key bindings, in particular @kbd{C-c a} for
1130 @code{org-agenda} and @kbd{C-c c} for @code{org-capture}. These are only
1131 suggestions, but the rest of the manual assumes that these key bindings are in
1132 place in order to list commands by key access.
1134 Also, the manual lists both the keys and the corresponding commands for
1135 accessing a functionality. Org mode often uses the same key for different
1136 functions, depending on context. The command that is bound to such keys has
1137 a generic name, like @code{org-metaright}. In the manual we will, wherever
1138 possible, give the function that is internally called by the generic command.
1139 For example, in the chapter on document structure, @kbd{M-@key{right}} will
1140 be listed to call @code{org-do-demote}, while in the chapter on tables, it
1141 will be listed to call @code{org-table-move-column-right}. If you prefer,
1142 you can compile the manual without the command names by unsetting the flag
1143 @code{cmdnames} in @file{org.texi}.
1145 @node Document structure
1146 @chapter Document structure
1147 @cindex document structure
1148 @cindex structure of document
1150 Org is based on Outline mode and provides flexible commands to
1151 edit the structure of the document.
1154 * Outlines:: Org is based on Outline mode
1155 * Headlines:: How to typeset Org tree headlines
1156 * Visibility cycling:: Show and hide, much simplified
1157 * Motion:: Jumping to other headlines
1158 * Structure editing:: Changing sequence and level of headlines
1159 * Sparse trees:: Matches embedded in context
1160 * Plain lists:: Additional structure within an entry
1161 * Drawers:: Tucking stuff away
1162 * Blocks:: Folding blocks
1163 * Footnotes:: How footnotes are defined in Org's syntax
1164 * Orgstruct mode:: Structure editing outside Org
1165 * Org syntax:: Formal description of Org's syntax
1171 @cindex Outline mode
1173 Org is implemented on top of Outline mode. Outlines allow a
1174 document to be organized in a hierarchical structure, which (at least
1175 for me) is the best representation of notes and thoughts. An overview
1176 of this structure is achieved by folding (hiding) large parts of the
1177 document to show only the general document structure and the parts
1178 currently being worked on. Org greatly simplifies the use of
1179 outlines by compressing the entire show/hide functionality into a single
1180 command, @command{org-cycle}, which is bound to the @key{TAB} key.
1185 @cindex outline tree
1186 @vindex org-special-ctrl-a/e
1187 @vindex org-special-ctrl-k
1188 @vindex org-ctrl-k-protect-subtree
1190 Headlines define the structure of an outline tree. The headlines in Org
1191 start with one or more stars, on the left margin@footnote{See the variables
1192 @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
1193 @code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
1194 @kbd{C-e}, and @kbd{C-k} in headlines.} @footnote{Clocking only works with
1195 headings indented less than 30 stars.}. For example:
1198 * Top level headline
1205 * Another top level headline
1208 @vindex org-footnote-section
1209 @noindent Note that a headline named after @code{org-footnote-section},
1210 which defaults to @samp{Footnotes}, is considered as special. A subtree with
1211 this headline will be silently ignored by exporting functions.
1213 Some people find the many stars too noisy and would prefer an
1214 outline that has whitespace followed by a single star as headline
1215 starters. @ref{Clean view}, describes a setup to realize this.
1217 @vindex org-cycle-separator-lines
1218 An empty line after the end of a subtree is considered part of it and
1219 will be hidden when the subtree is folded. However, if you leave at
1220 least two empty lines, one empty line will remain visible after folding
1221 the subtree, in order to structure the collapsed view. See the
1222 variable @code{org-cycle-separator-lines} to modify this behavior.
1224 @node Visibility cycling
1225 @section Visibility cycling
1226 @cindex cycling, visibility
1227 @cindex visibility cycling
1228 @cindex trees, visibility
1229 @cindex show hidden text
1233 * Global and local cycling:: Cycling through various visibility states
1234 * Initial visibility:: Setting the initial visibility state
1235 * Catching invisible edits:: Preventing mistakes when editing invisible parts
1238 @node Global and local cycling
1239 @subsection Global and local cycling
1241 Outlines make it possible to hide parts of the text in the buffer.
1242 Org uses just two commands, bound to @key{TAB} and
1243 @kbd{S-@key{TAB}} to change the visibility in the buffer.
1245 @cindex subtree visibility states
1246 @cindex subtree cycling
1247 @cindex folded, subtree visibility state
1248 @cindex children, subtree visibility state
1249 @cindex subtree, subtree visibility state
1251 @orgcmd{@key{TAB},org-cycle}
1252 @emph{Subtree cycling}: Rotate current subtree among the states
1255 ,-> FOLDED -> CHILDREN -> SUBTREE --.
1256 '-----------------------------------'
1259 @vindex org-cycle-emulate-tab
1260 The cursor must be on a headline for this to work@footnote{see, however,
1261 the option @code{org-cycle-emulate-tab}.}.
1263 @cindex global visibility states
1264 @cindex global cycling
1265 @cindex overview, global visibility state
1266 @cindex contents, global visibility state
1267 @cindex show all, global visibility state
1268 @orgcmd{S-@key{TAB},org-global-cycle}
1269 @itemx C-u @key{TAB}
1270 @emph{Global cycling}: Rotate the entire buffer among the states
1273 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
1274 '--------------------------------------'
1277 When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the
1278 CONTENTS view up to headlines of level N will be shown. Note that inside
1279 tables, @kbd{S-@key{TAB}} jumps to the previous field.
1281 @vindex org-cycle-global-at-bob
1282 You can run global cycling using @key{TAB} only if point is at the very
1283 beginning of the buffer, but not on a headline, and
1284 @code{org-cycle-global-at-bob} is set to a non-@code{nil} value.
1286 @cindex set startup visibility, command
1287 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1288 Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
1289 @cindex show all, command
1290 @orgcmd{C-u C-u C-u @key{TAB},outline-show-all}
1291 Show all, including drawers.
1292 @cindex revealing context
1293 @orgcmd{C-c C-r,org-reveal}
1294 Reveal context around point, showing the current entry, the following heading
1295 and the hierarchy above. Useful for working near a location that has been
1296 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
1297 (@pxref{Agenda commands}). With a prefix argument show, on each
1298 level, all sibling headings. With a double prefix argument, also show the
1299 entire subtree of the parent.
1300 @cindex show branches, command
1301 @orgcmd{C-c C-k,outline-show-branches}
1302 Expose all the headings of the subtree, CONTENTS view for just one subtree.
1303 @cindex show children, command
1304 @orgcmd{C-c @key{TAB},outline-show-children}
1305 Expose all direct children of the subtree. With a numeric prefix argument N,
1306 expose all children down to level N@.
1307 @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
1308 Show the current subtree in an indirect buffer@footnote{The indirect buffer
1309 (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) will contain the entire
1310 buffer, but will be narrowed to the current tree. Editing the indirect
1311 buffer will also change the original buffer, but without affecting visibility
1312 in that buffer.}. With a numeric prefix argument N, go up to level N and
1313 then take that tree. If N is negative then go up that many levels. With
1314 a @kbd{C-u} prefix, do not remove the previously used indirect buffer.
1315 @orgcmd{C-c C-x v,org-copy-visible}
1316 Copy the @i{visible} text in the region into the kill ring.
1319 @node Initial visibility
1320 @subsection Initial visibility
1322 @cindex visibility, initialize
1323 @vindex org-startup-folded
1324 @vindex org-agenda-inhibit-startup
1325 @cindex @code{overview}, STARTUP keyword
1326 @cindex @code{content}, STARTUP keyword
1327 @cindex @code{showall}, STARTUP keyword
1328 @cindex @code{showeverything}, STARTUP keyword
1330 When Emacs first visits an Org file, the global state is set to OVERVIEW,
1331 i.e., only the top level headlines are visible@footnote{When
1332 @code{org-agenda-inhibit-startup} is non-@code{nil}, Org will not honor the default
1333 visibility state when first opening a file for the agenda (@pxref{Speeding up
1334 your agendas}).}. This can be configured through the variable
1335 @code{org-startup-folded}, or on a per-file basis by adding one of the
1336 following lines anywhere in the buffer:
1342 #+STARTUP: showeverything
1345 @cindex property, VISIBILITY
1347 Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
1348 and columns}) will get their visibility adapted accordingly. Allowed values
1349 for this property are @code{folded}, @code{children}, @code{content}, and
1353 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1354 Switch back to the startup visibility of the buffer, i.e., whatever is
1355 requested by startup options and @samp{VISIBILITY} properties in individual
1359 @node Catching invisible edits
1360 @subsection Catching invisible edits
1362 @vindex org-catch-invisible-edits
1363 @cindex edits, catching invisible
1364 Sometimes you may inadvertently edit an invisible part of the buffer and be
1365 confused on what has been edited and how to undo the mistake. Setting
1366 @code{org-catch-invisible-edits} to non-@code{nil} will help prevent this. See the
1367 docstring of this option on how Org should catch invisible edits and process
1372 @cindex motion, between headlines
1373 @cindex jumping, to headlines
1374 @cindex headline navigation
1375 The following commands jump to other headlines in the buffer.
1378 @orgcmd{C-c C-n,org-next-visible-heading}
1380 @orgcmd{C-c C-p,org-previous-visible-heading}
1382 @orgcmd{C-c C-f,org-forward-same-level}
1383 Next heading same level.
1384 @orgcmd{C-c C-b,org-backward-same-level}
1385 Previous heading same level.
1386 @orgcmd{C-c C-u,outline-up-heading}
1387 Backward to higher level heading.
1388 @orgcmd{C-c C-j,org-goto}
1389 Jump to a different place without changing the current outline
1390 visibility. Shows the document structure in a temporary buffer, where
1391 you can use the following keys to find your destination:
1392 @vindex org-goto-auto-isearch
1394 @key{TAB} @r{Cycle visibility.}
1395 @key{down} / @key{up} @r{Next/previous visible headline.}
1396 @key{RET} @r{Select this location.}
1397 @kbd{/} @r{Do a Sparse-tree search}
1398 @r{The following keys work if you turn off @code{org-goto-auto-isearch}}
1399 n / p @r{Next/previous visible headline.}
1400 f / b @r{Next/previous headline same level.}
1402 0-9 @r{Digit argument.}
1405 @vindex org-goto-interface
1407 See also the option @code{org-goto-interface}.
1410 @node Structure editing
1411 @section Structure editing
1412 @cindex structure editing
1413 @cindex headline, promotion and demotion
1414 @cindex promotion, of subtrees
1415 @cindex demotion, of subtrees
1416 @cindex subtree, cut and paste
1417 @cindex pasting, of subtrees
1418 @cindex cutting, of subtrees
1419 @cindex copying, of subtrees
1420 @cindex sorting, of subtrees
1421 @cindex subtrees, cut and paste
1424 @orgcmd{M-@key{RET},org-meta-return}
1425 @vindex org-M-RET-may-split-line
1426 Insert a new heading, item or row.
1428 If the command is used at the @emph{beginning} of a line, and if there is
1429 a heading or a plain list item (@pxref{Plain lists}) at point, the new
1430 heading/item is created @emph{before} the current line. When used at the
1431 beginning of a regular line of text, turn that line into a heading.
1433 When this command is used in the middle of a line, the line is split and the
1434 rest of the line becomes the new item or headline. If you do not want the
1435 line to be split, customize @code{org-M-RET-may-split-line}.
1437 Calling the command with a @kbd{C-u} prefix unconditionally inserts a new
1438 heading at the end of the current subtree, thus preserving its contents.
1439 With a double @kbd{C-u C-u} prefix, the new heading is created at the end of
1440 the parent subtree instead.
1441 @orgcmd{C-@key{RET},org-insert-heading-respect-content}
1442 Insert a new heading at the end of the current subtree.
1443 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
1444 @vindex org-treat-insert-todo-heading-as-state-change
1445 Insert new TODO entry with same level as current heading. See also the
1446 variable @code{org-treat-insert-todo-heading-as-state-change}.
1447 @orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
1448 Insert new TODO entry with same level as current heading. Like
1449 @kbd{C-@key{RET}}, the new headline will be inserted after the current
1451 @orgcmd{@key{TAB},org-cycle}
1452 In a new entry with no text yet, the first @key{TAB} demotes the entry to
1453 become a child of the previous one. The next @key{TAB} makes it a parent,
1454 and so on, all the way to top level. Yet another @key{TAB}, and you are back
1455 to the initial level.
1456 @orgcmd{M-@key{left},org-do-promote}
1457 Promote current heading by one level.
1458 @orgcmd{M-@key{right},org-do-demote}
1459 Demote current heading by one level.
1460 @orgcmd{M-S-@key{left},org-promote-subtree}
1461 Promote the current subtree by one level.
1462 @orgcmd{M-S-@key{right},org-demote-subtree}
1463 Demote the current subtree by one level.
1464 @orgcmd{M-@key{up},org-move-subtree-up}
1465 Move subtree up (swap with previous subtree of same
1467 @orgcmd{M-@key{down},org-move-subtree-down}
1468 Move subtree down (swap with next subtree of same level).
1469 @orgcmd{M-h,org-mark-element}
1470 Mark the element at point. Hitting repeatedly will mark subsequent elements
1471 of the one just marked. E.g., hitting @key{M-h} on a paragraph will mark it,
1472 hitting @key{M-h} immediately again will mark the next one.
1473 @orgcmd{C-c @@,org-mark-subtree}
1474 Mark the subtree at point. Hitting repeatedly will mark subsequent subtrees
1475 of the same level than the marked subtree.
1476 @orgcmd{C-c C-x C-w,org-cut-subtree}
1477 Kill subtree, i.e., remove it from buffer but save in kill ring.
1478 With a numeric prefix argument N, kill N sequential subtrees.
1479 @orgcmd{C-c C-x M-w,org-copy-subtree}
1480 Copy subtree to kill ring. With a numeric prefix argument N, copy the N
1481 sequential subtrees.
1482 @orgcmd{C-c C-x C-y,org-paste-subtree}
1483 Yank subtree from kill ring. This does modify the level of the subtree to
1484 make sure the tree fits in nicely at the yank position. The yank level can
1485 also be specified with a numeric prefix argument, or by yanking after a
1486 headline marker like @samp{****}.
1487 @orgcmd{C-y,org-yank}
1488 @vindex org-yank-adjusted-subtrees
1489 @vindex org-yank-folded-subtrees
1490 Depending on the options @code{org-yank-adjusted-subtrees} and
1491 @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
1492 paste subtrees folded and in a clever way, using the same command as @kbd{C-c
1493 C-x C-y}. With the default settings, no level adjustment will take place,
1494 but the yanked tree will be folded unless doing so would swallow text
1495 previously visible. Any prefix argument to this command will force a normal
1496 @code{yank} to be executed, with the prefix passed along. A good way to
1497 force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a
1498 yank, it will yank previous kill items plainly, without adjustment and
1500 @orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
1501 Clone a subtree by making a number of sibling copies of it. You will be
1502 prompted for the number of copies to make, and you can also specify if any
1503 timestamps in the entry should be shifted. This can be useful, for example,
1504 to create a number of tasks related to a series of lectures to prepare. For
1505 more details, see the docstring of the command
1506 @code{org-clone-subtree-with-time-shift}.
1507 @orgcmd{C-c C-w,org-refile}
1508 Refile entry or region to a different location. @xref{Refile and copy}.
1509 @orgcmd{C-c ^,org-sort}
1510 Sort same-level entries. When there is an active region, all entries in the
1511 region will be sorted. Otherwise the children of the current headline are
1512 sorted. The command prompts for the sorting method, which can be
1513 alphabetically, numerically, by time (first timestamp with active preferred,
1514 creation time, scheduled time, deadline time), by priority, by TODO keyword
1515 (in the sequence the keywords have been defined in the setup) or by the value
1516 of a property. Reverse sorting is possible as well. You can also supply
1517 your own function to extract the sorting key. With a @kbd{C-u} prefix,
1518 sorting will be case-sensitive.
1519 @orgcmd{C-x n s,org-narrow-to-subtree}
1520 Narrow buffer to current subtree.
1521 @orgcmd{C-x n b,org-narrow-to-block}
1522 Narrow buffer to current block.
1523 @orgcmd{C-x n w,widen}
1524 Widen buffer to remove narrowing.
1525 @orgcmd{C-c *,org-toggle-heading}
1526 Turn a normal line or plain list item into a headline (so that it becomes a
1527 subheading at its location). Also turn a headline into a normal line by
1528 removing the stars. If there is an active region, turn all lines in the
1529 region into headlines. If the first line in the region was an item, turn
1530 only the item lines into headlines. Finally, if the first line is a
1531 headline, remove the stars from all headlines in the region.
1534 @cindex region, active
1535 @cindex active region
1536 @cindex transient mark mode
1537 When there is an active region (Transient Mark mode), promotion and
1538 demotion work on all headlines in the region. To select a region of
1539 headlines, it is best to place both point and mark at the beginning of a
1540 line, mark at the beginning of the first headline, and point at the line
1541 just after the last headline to change. Note that when the cursor is
1542 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
1547 @section Sparse trees
1548 @cindex sparse trees
1549 @cindex trees, sparse
1550 @cindex folding, sparse trees
1551 @cindex occur, command
1553 @vindex org-show-context-detail
1554 An important feature of Org mode is the ability to construct @emph{sparse
1555 trees} for selected information in an outline tree, so that the entire
1556 document is folded as much as possible, but the selected information is made
1557 visible along with the headline structure above it@footnote{See also the
1558 variable @code{org-show-context-detail} to decide how much context is shown
1559 around each match.}. Just try it out and you will see immediately how it
1562 Org mode contains several commands for creating such trees, all these
1563 commands can be accessed through a dispatcher:
1566 @orgcmd{C-c /,org-sparse-tree}
1567 This prompts for an extra key to select a sparse-tree creating command.
1568 @orgcmdkkc{C-c / r,C-c / /,org-occur}
1569 @vindex org-remove-highlights-with-change
1570 Prompts for a regexp and shows a sparse tree with all matches. If
1571 the match is in a headline, the headline is made visible. If the match is in
1572 the body of an entry, headline and body are made visible. In order to
1573 provide minimal context, also the full hierarchy of headlines above the match
1574 is shown, as well as the headline following the match. Each match is also
1575 highlighted; the highlights disappear when the buffer is changed by an
1576 editing command@footnote{This depends on the option
1577 @code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
1578 When called with a @kbd{C-u} prefix argument, previous highlights are kept,
1579 so several calls to this command can be stacked.
1580 @orgcmdkkc{M-g n,M-g M-n,next-error}
1581 Jump to the next sparse tree match in this buffer.
1582 @orgcmdkkc{M-g p,M-g M-p,previous-error}
1583 Jump to the previous sparse tree match in this buffer.
1587 @vindex org-agenda-custom-commands
1588 For frequently used sparse trees of specific search strings, you can
1589 use the option @code{org-agenda-custom-commands} to define fast
1590 keyboard access to specific sparse trees. These commands will then be
1591 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
1595 (setq org-agenda-custom-commands
1596 '(("f" occur-tree "FIXME")))
1599 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
1600 a sparse tree matching the string @samp{FIXME}.
1602 The other sparse tree commands select headings based on TODO keywords,
1603 tags, or properties and will be discussed later in this manual.
1606 @cindex printing sparse trees
1607 @cindex visible text, printing
1608 To print a sparse tree, you can use the Emacs command
1609 @code{ps-print-buffer-with-faces} which does not print invisible parts of the
1610 document. Or you can use @kbd{C-c C-e C-v} to export only the visible part
1611 of the document and print the resulting file.
1614 @section Plain lists
1616 @cindex lists, plain
1617 @cindex lists, ordered
1618 @cindex ordered lists
1620 Within an entry of the outline tree, hand-formatted lists can provide
1621 additional structure. They also provide a way to create lists of checkboxes
1622 (@pxref{Checkboxes}). Org supports editing such lists, and every exporter
1623 (@pxref{Exporting}) can parse and format them.
1625 Org knows ordered lists, unordered lists, and description lists.
1628 @emph{Unordered} list items start with @samp{-}, @samp{+}, or
1629 @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
1630 they will be seen as top-level headlines. Also, when you are hiding leading
1631 stars to get a clean outline view, plain list items starting with a star may
1632 be hard to distinguish from true headlines. In short: even though @samp{*}
1633 is supported, it may be better to not use it for plain list items.} as
1636 @vindex org-plain-list-ordered-item-terminator
1637 @vindex org-list-allow-alphabetical
1638 @emph{Ordered} list items start with a numeral followed by either a period or
1639 a right parenthesis@footnote{You can filter out any of them by configuring
1640 @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
1641 @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
1642 @samp{A)} by configuring @code{org-list-allow-alphabetical}. To minimize
1643 confusion with normal text, those are limited to one character only. Beyond
1644 that limit, bullets will automatically fallback to numbers.}. If you want a
1645 list to start with a different value (e.g., 20), start the text of the item
1646 with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
1647 must be put @emph{before} the checkbox. If you have activated alphabetical
1648 lists, you can also use counters like @code{[@@b]}.}. Those constructs can
1649 be used in any item of the list in order to enforce a particular numbering.
1651 @emph{Description} list items are unordered list items, and contain the
1652 separator @samp{ :: } to distinguish the description @emph{term} from the
1656 Items belonging to the same list must have the same indentation on the first
1657 line. In particular, if an ordered list reaches number @samp{10.}, then the
1658 2--digit numbers must be written left-aligned with the other numbers in the
1659 list. An item ends before the next line that is less or equally indented
1660 than its bullet/number.
1662 A list ends whenever every item has ended, which means before any line less
1663 or equally indented than items at top level. It also ends before two blank
1664 lines. In that case, all items are closed. Here is an example:
1668 ** Lord of the Rings
1669 My favorite scenes are (in this order)
1670 1. The attack of the Rohirrim
1671 2. Eowyn's fight with the witch king
1672 + this was already my favorite scene in the book
1673 + I really like Miranda Otto.
1674 3. Peter Jackson being shot by Legolas
1676 He makes a really funny face when it happens.
1677 But in the end, no individual scenes matter but the film as a whole.
1678 Important actors in this film are:
1679 - @b{Elijah Wood} :: He plays Frodo
1680 - @b{Sean Astin} :: He plays Sam, Frodo's friend. I still remember
1681 him very well from his role as Mikey Walsh in @i{The Goonies}.
1685 Org supports these lists by tuning filling and wrapping commands to deal with
1686 them correctly, and by exporting them properly (@pxref{Exporting}). Since
1687 indentation is what governs the structure of these lists, many structural
1688 constructs like @code{#+BEGIN_...} blocks can be indented to signal that they
1689 belong to a particular item.
1691 @vindex org-list-demote-modify-bullet
1692 @vindex org-list-indent-offset
1693 If you find that using a different bullet for a sub-list (than that used for
1694 the current list-level) improves readability, customize the variable
1695 @code{org-list-demote-modify-bullet}. To get a greater difference of
1696 indentation between items and their sub-items, customize
1697 @code{org-list-indent-offset}.
1699 @vindex org-list-automatic-rules
1700 The following commands act on items when the cursor is in the first line of
1701 an item (the line with the bullet or number). Some of them imply the
1702 application of automatic rules to keep list structure intact. If some of
1703 these actions get in your way, configure @code{org-list-automatic-rules}
1704 to disable them individually.
1707 @orgcmd{@key{TAB},org-cycle}
1708 @cindex cycling, in plain lists
1709 @vindex org-cycle-include-plain-lists
1710 Items can be folded just like headline levels. Normally this works only if
1711 the cursor is on a plain list item. For more details, see the variable
1712 @code{org-cycle-include-plain-lists}. If this variable is set to
1713 @code{integrate}, plain list items will be treated like low-level
1714 headlines. The level of an item is then given by the indentation of the
1715 bullet/number. Items are always subordinate to real headlines, however; the
1716 hierarchies remain completely separated. In a new item with no text yet, the
1717 first @key{TAB} demotes the item to become a child of the previous
1718 one. Subsequent @key{TAB}s move the item to meaningful levels in the list
1719 and eventually get it back to its initial position.
1720 @orgcmd{M-@key{RET},org-insert-heading}
1721 @vindex org-M-RET-may-split-line
1722 @vindex org-list-automatic-rules
1723 Insert new item at current level. With a prefix argument, force a new
1724 heading (@pxref{Structure editing}). If this command is used in the middle
1725 of an item, that item is @emph{split} in two, and the second part becomes the
1726 new item@footnote{If you do not want the item to be split, customize the
1727 variable @code{org-M-RET-may-split-line}.}. If this command is executed
1728 @emph{before item's body}, the new item is created @emph{before} the current
1733 @kindex M-S-@key{RET}
1735 Insert a new item with a checkbox (@pxref{Checkboxes}).
1736 @kindex S-@key{down}
1739 @cindex shift-selection-mode
1740 @vindex org-support-shift-select
1741 @vindex org-list-use-circular-motion
1742 Jump to the previous/next item in the current list@footnote{If you want to
1743 cycle around items that way, you may customize
1744 @code{org-list-use-circular-motion}.}, but only if
1745 @code{org-support-shift-select} is off. If not, you can still use paragraph
1746 jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
1749 @kindex M-@key{down}
1752 Move the item including subitems up/down@footnote{See
1753 @code{org-list-use-circular-motion} for a cyclic behavior.} (swap with
1754 previous/next item of same indentation). If the list is ordered, renumbering
1756 @kindex M-@key{left}
1757 @kindex M-@key{right}
1760 Decrease/increase the indentation of an item, leaving children alone.
1761 @kindex M-S-@key{left}
1762 @kindex M-S-@key{right}
1763 @item M-S-@key{left}
1764 @itemx M-S-@key{right}
1765 Decrease/increase the indentation of the item, including subitems.
1766 Initially, the item tree is selected based on current indentation. When
1767 these commands are executed several times in direct succession, the initially
1768 selected region is used, even if the new indentation would imply a different
1769 hierarchy. To use the new hierarchy, break the command chain with a cursor
1772 As a special case, using this command on the very first item of a list will
1773 move the whole list. This behavior can be disabled by configuring
1774 @code{org-list-automatic-rules}. The global indentation of a list has no
1775 influence on the text @emph{after} the list.
1778 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1779 state of the checkbox. In any case, verify bullets and indentation
1780 consistency in the whole list.
1782 @vindex org-plain-list-ordered-item-terminator
1784 Cycle the entire list level through the different itemize/enumerate bullets
1785 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
1786 depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
1787 and its indentation. With a numeric prefix argument N, select the Nth bullet
1788 from this list. If there is an active region when calling this, all selected
1789 lines are converted to list items. With a prefix argument, selected text is
1790 changed into a single item. If the first line already was a list item, any
1791 item marker will be removed from the list. Finally, even without an active
1792 region, a normal line will be converted into a list item.
1795 Turn a plain list item into a headline (so that it becomes a subheading at
1796 its location). @xref{Structure editing}, for a detailed explanation.
1799 Turn the whole plain list into a subtree of the current heading. Checkboxes
1800 (@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
1802 @kindex S-@key{left}
1803 @kindex S-@key{right}
1805 @vindex org-support-shift-select
1806 This command also cycles bullet styles when the cursor in on the bullet or
1807 anywhere in an item line, details depending on
1808 @code{org-support-shift-select}.
1810 @cindex sorting, of plain list
1812 Sort the plain list. You will be prompted for the sorting method:
1813 numerically, alphabetically, by time, by checked status for check lists,
1814 or by a custom function.
1820 @cindex visibility cycling, drawers
1822 @cindex org-insert-drawer
1824 Sometimes you want to keep information associated with an entry, but you
1825 normally don't want to see it. For this, Org mode has @emph{drawers}. They
1826 can contain anything but a headline and another drawer. Drawers look like
1830 ** This is a headline
1831 Still outside the drawer
1833 This is inside the drawer.
1838 You can interactively insert drawers at point by calling
1839 @code{org-insert-drawer}, which is bound to @key{C-c C-x d}. With an active
1840 region, this command will put the region inside the drawer. With a prefix
1841 argument, this command calls @code{org-insert-property-drawer} and add
1842 a property drawer right below the current headline. Completion over drawer
1843 keywords is also possible using @kbd{M-@key{TAB}}@footnote{Many desktops
1844 intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
1845 @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}.
1847 Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
1848 show the entry, but keep the drawer collapsed to a single line. In order to
1849 look inside the drawer, you need to move the cursor to the drawer line and
1850 press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
1851 storing properties (@pxref{Properties and columns}), and you can also arrange
1852 for state change notes (@pxref{Tracking TODO state changes}) and clock times
1853 (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
1854 want to store a quick note in the LOGBOOK drawer, in a similar way to state
1860 Add a time-stamped note to the LOGBOOK drawer.
1863 @vindex org-export-with-drawers
1864 @vindex org-export-with-properties
1865 You can select the name of the drawers which should be exported with
1866 @code{org-export-with-drawers}. In that case, drawer contents will appear in
1867 export output. Property drawers are not affected by this variable: configure
1868 @code{org-export-with-properties} instead.
1873 @vindex org-hide-block-startup
1874 @cindex blocks, folding
1875 Org mode uses begin...end blocks for various purposes from including source
1876 code examples (@pxref{Literal examples}) to capturing time logging
1877 information (@pxref{Clocking work time}). These blocks can be folded and
1878 unfolded by pressing TAB in the begin line. You can also get all blocks
1879 folded at startup by configuring the option @code{org-hide-block-startup}
1880 or on a per-file basis by using
1882 @cindex @code{hideblocks}, STARTUP keyword
1883 @cindex @code{nohideblocks}, STARTUP keyword
1885 #+STARTUP: hideblocks
1886 #+STARTUP: nohideblocks
1893 Org mode supports the creation of footnotes.
1895 A footnote is started by a footnote marker in square brackets in column 0, no
1896 indentation allowed. It ends at the next footnote definition, headline, or
1897 after two consecutive empty lines. The footnote reference is simply the
1898 marker in square brackets, inside text. Markers always start with
1899 @code{fn:}. For example:
1902 The Org homepage[fn:1] now looks a lot better than it used to.
1904 [fn:1] The link is: http://orgmode.org
1907 Org mode extends the number-based syntax to @emph{named} footnotes and
1908 optional inline definition. Here are the valid references:
1912 A named footnote reference, where @code{name} is a unique label word, or, for
1913 simplicity of automatic creation, a number.
1914 @item [fn::This is the inline definition of this footnote]
1915 A @LaTeX{}-like anonymous footnote where the definition is given directly at the
1917 @item [fn:name:a definition]
1918 An inline definition of a footnote, which also specifies a name for the note.
1919 Since Org allows multiple references to the same note, you can then use
1920 @code{[fn:name]} to create additional references.
1923 @vindex org-footnote-auto-label
1924 Footnote labels can be created automatically, or you can create names yourself.
1925 This is handled by the variable @code{org-footnote-auto-label} and its
1926 corresponding @code{#+STARTUP} keywords. See the docstring of that variable
1929 @noindent The following command handles footnotes:
1934 The footnote action command.
1936 When the cursor is on a footnote reference, jump to the definition. When it
1937 is at a definition, jump to the (first) reference.
1939 @vindex org-footnote-define-inline
1940 @vindex org-footnote-section
1941 @vindex org-footnote-auto-adjust
1942 Otherwise, create a new footnote. Depending on the option
1943 @code{org-footnote-define-inline}@footnote{The corresponding in-buffer
1944 setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
1945 definition will be placed right into the text as part of the reference, or
1946 separately into the location determined by the option
1947 @code{org-footnote-section}.
1949 When this command is called with a prefix argument, a menu of additional
1952 s @r{Sort the footnote definitions by reference sequence. During editing,}
1953 @r{Org makes no effort to sort footnote definitions into a particular}
1954 @r{sequence. If you want them sorted, use this command, which will}
1955 @r{also move entries according to @code{org-footnote-section}. Automatic}
1956 @r{sorting after each insertion/deletion can be configured using the}
1957 @r{option @code{org-footnote-auto-adjust}.}
1958 r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering}
1959 @r{after each insertion/deletion can be configured using the option}
1960 @r{@code{org-footnote-auto-adjust}.}
1961 S @r{Short for first @code{r}, then @code{s} action.}
1962 n @r{Normalize the footnotes by collecting all definitions (including}
1963 @r{inline definitions) into a special section, and then numbering them}
1964 @r{in sequence. The references will then also be numbers.}
1965 d @r{Delete the footnote at point, and all definitions of and references}
1968 Depending on the variable @code{org-footnote-auto-adjust}@footnote{the
1969 corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},
1970 renumbering and sorting footnotes can be automatic after each insertion or
1975 If the cursor is on a footnote reference, jump to the definition. If it is a
1976 the definition, jump back to the reference. When called at a footnote
1977 location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
1981 @item C-c C-o @r{or} mouse-1/2
1982 Footnote labels are also links to the corresponding definition/reference, and
1983 you can use the usual commands to follow these links.
1985 @vindex org-edit-footnote-reference
1989 Edit the footnote definition corresponding to the reference at point in
1990 a separate window. The window can be closed by pressing @kbd{C-c '}.
1994 @node Orgstruct mode
1995 @section The Orgstruct minor mode
1996 @cindex Orgstruct mode
1997 @cindex minor mode for structure editing
1999 If you like the intuitive way the Org mode structure editing and list
2000 formatting works, you might want to use these commands in other modes like
2001 Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes
2002 this possible. Toggle the mode with @kbd{M-x orgstruct-mode RET}, or
2003 turn it on by default, for example in Message mode, with one of:
2006 (add-hook 'message-mode-hook 'turn-on-orgstruct)
2007 (add-hook 'message-mode-hook 'turn-on-orgstruct++)
2010 When this mode is active and the cursor is on a line that looks to Org like a
2011 headline or the first line of a list item, most structure editing commands
2012 will work, even if the same keys normally have different functionality in the
2013 major mode you are using. If the cursor is not in one of those special
2014 lines, Orgstruct mode lurks silently in the shadows.
2016 When you use @code{orgstruct++-mode}, Org will also export indentation and
2017 autofill settings into that mode, and detect item context after the first
2020 @vindex orgstruct-heading-prefix-regexp
2021 You can also use Org structure editing to fold and unfold headlines in
2022 @emph{any} file, provided you defined @code{orgstruct-heading-prefix-regexp}:
2023 the regular expression must match the local prefix to use before Org's
2024 headlines. For example, if you set this variable to @code{";; "} in Emacs
2025 Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
2026 commented lines. Some commands like @code{org-demote} are disabled when the
2027 prefix is set, but folding/unfolding will work correctly.
2033 A reference document providing a formal description of Org's syntax is
2034 available as @uref{http://orgmode.org/worg/dev/org-syntax.html, a draft on
2035 Worg}, written and maintained by Nicolas Goaziou. It defines Org's core
2036 internal concepts such as @code{headlines}, @code{sections}, @code{affiliated
2037 keywords}, @code{(greater) elements} and @code{objects}. Each part of an Org
2038 file falls into one of the categories above.
2040 To explore the abstract structure of an Org buffer, run this in a buffer:
2043 M-: (org-element-parse-buffer) RET
2046 It will output a list containing the buffer's content represented as an
2047 abstract structure. The export engine relies on the information stored in
2048 this list. Most interactive commands (e.g., for structure editing) also
2049 rely on the syntactic meaning of the surrounding context.
2051 @cindex syntax checker
2053 You can check syntax in your documents using @code{org-lint} command.
2058 @cindex editing tables
2060 Org comes with a fast and intuitive table editor. Spreadsheet-like
2061 calculations are supported using the Emacs @file{calc} package
2062 (@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}).
2065 * Built-in table editor:: Simple tables
2066 * Column width and alignment:: Overrule the automatic settings
2067 * Column groups:: Grouping to trigger vertical lines
2068 * Orgtbl mode:: The table editor as minor mode
2069 * The spreadsheet:: The table editor has spreadsheet capabilities
2070 * Org-Plot:: Plotting from org tables
2073 @node Built-in table editor
2074 @section The built-in table editor
2075 @cindex table editor, built-in
2077 Org makes it easy to format tables in plain ASCII@. Any line with @samp{|} as
2078 the first non-whitespace character is considered part of a table. @samp{|}
2079 is also the column separator@footnote{To insert a vertical bar into a table
2080 field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table
2081 might look like this:
2084 | Name | Phone | Age |
2085 |-------+-------+-----|
2086 | Peter | 1234 | 17 |
2087 | Anna | 4321 | 25 |
2090 A table is re-aligned automatically each time you press @key{TAB} or
2091 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
2092 the next field (@key{RET} to the next row) and creates new table rows
2093 at the end of the table or before horizontal lines. The indentation
2094 of the table is set by the first line. Any line starting with
2095 @samp{|-} is considered as a horizontal separator line and will be
2096 expanded on the next re-align to span the whole table width. So, to
2097 create the above table, you would only type
2104 @noindent and then press @key{TAB} to align the table and start filling in
2105 fields. Even faster would be to type @code{|Name|Phone|Age} followed by
2106 @kbd{C-c @key{RET}}.
2108 @vindex org-table-auto-blank-field
2109 When typing text into a field, Org treats @key{DEL}, @key{Backspace}, and all
2110 character keys in a special way, so that inserting and deleting avoids
2111 shifting other fields. Also, when typing @emph{immediately after the cursor
2112 was moved into a new field with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or
2113 @kbd{@key{RET}}}, the field is automatically made blank. If this behavior is
2114 too unpredictable for you, configure the option
2115 @code{org-table-auto-blank-field}.
2118 @tsubheading{Creation and conversion}
2119 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2120 Convert the active region to a table. If every line contains at least one
2121 TAB character, the function assumes that the material is tab separated.
2122 If every line contains a comma, comma-separated values (CSV) are assumed.
2123 If not, lines are split at whitespace into fields. You can use a prefix
2124 argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
2125 C-u} forces TAB, @kbd{C-u C-u C-u} will prompt for a regular expression to
2126 match the separator, and a numeric argument N indicates that at least N
2127 consecutive spaces, or alternatively a TAB will be the separator.
2129 If there is no active region, this command creates an empty Org
2130 table. But it is easier just to start typing, like
2131 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
2133 @tsubheading{Re-aligning and field motion}
2134 @orgcmd{C-c C-c,org-table-align}
2135 Re-align the table and don't move to another field.
2137 @orgcmd{C-c SPC,org-table-blank-field}
2138 Blank the field at point.
2140 @orgcmd{TAB,org-table-next-field}
2141 Re-align the table, move to the next field. Creates a new row if
2144 @orgcmd{S-@key{TAB},org-table-previous-field}
2145 Re-align, move to previous field.
2147 @orgcmd{@key{RET},org-table-next-row}
2148 Re-align the table and move down to next row. Creates a new row if
2149 necessary. At the beginning or end of a line, @key{RET} still does
2150 NEWLINE, so it can be used to split a table.
2152 @orgcmd{M-a,org-table-beginning-of-field}
2153 Move to beginning of the current table field, or on to the previous field.
2154 @orgcmd{M-e,org-table-end-of-field}
2155 Move to end of the current table field, or on to the next field.
2157 @tsubheading{Column and row editing}
2158 @orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
2159 Move the current column left/right.
2161 @orgcmd{M-S-@key{left},org-table-delete-column}
2162 Kill the current column.
2164 @orgcmd{M-S-@key{right},org-table-insert-column}
2165 Insert a new column to the left of the cursor position.
2167 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
2168 Move the current row up/down.
2170 @orgcmd{M-S-@key{up},org-table-kill-row}
2171 Kill the current row or horizontal line.
2173 @orgcmd{M-S-@key{down},org-table-insert-row}
2174 Insert a new row above the current row. With a prefix argument, the line is
2175 created below the current one.
2177 @orgcmd{C-c -,org-table-insert-hline}
2178 Insert a horizontal line below current row. With a prefix argument, the line
2179 is created above the current line.
2181 @orgcmd{C-c @key{RET},org-table-hline-and-move}
2182 Insert a horizontal line below current row, and move the cursor into the row
2185 @orgcmd{C-c ^,org-table-sort-lines}
2186 Sort the table lines in the region. The position of point indicates the
2187 column to be used for sorting, and the range of lines is the range
2188 between the nearest horizontal separator lines, or the entire table. If
2189 point is before the first column, you will be prompted for the sorting
2190 column. If there is an active region, the mark specifies the first line
2191 and the sorting column, while point should be in the last line to be
2192 included into the sorting. The command prompts for the sorting type
2193 (alphabetically, numerically, or by time). You can sort in normal or
2194 reverse order. You can also supply your own key extraction and comparison
2195 functions. When called with a prefix argument, alphabetic sorting will be
2198 @tsubheading{Regions}
2199 @orgcmd{C-c C-x M-w,org-table-copy-region}
2200 Copy a rectangular region from a table to a special clipboard. Point and
2201 mark determine edge fields of the rectangle. If there is no active region,
2202 copy just the current field. The process ignores horizontal separator lines.
2204 @orgcmd{C-c C-x C-w,org-table-cut-region}
2205 Copy a rectangular region from a table to a special clipboard, and
2206 blank all fields in the rectangle. So this is the ``cut'' operation.
2208 @orgcmd{C-c C-x C-y,org-table-paste-rectangle}
2209 Paste a rectangular region into a table.
2210 The upper left corner ends up in the current field. All involved fields
2211 will be overwritten. If the rectangle does not fit into the present table,
2212 the table is enlarged as needed. The process ignores horizontal separator
2215 @orgcmd{M-@key{RET},org-table-wrap-region}
2216 Split the current field at the cursor position and move the rest to the line
2217 below. If there is an active region, and both point and mark are in the same
2218 column, the text in the column is wrapped to minimum width for the given
2219 number of lines. A numeric prefix argument may be used to change the number
2220 of desired lines. If there is no region, but you specify a prefix argument,
2221 the current field is made blank, and the content is appended to the field
2224 @tsubheading{Calculations}
2225 @cindex formula, in tables
2226 @cindex calculations, in tables
2227 @cindex region, active
2228 @cindex active region
2229 @cindex transient mark mode
2230 @orgcmd{C-c +,org-table-sum}
2231 Sum the numbers in the current column, or in the rectangle defined by
2232 the active region. The result is shown in the echo area and can
2233 be inserted with @kbd{C-y}.
2235 @orgcmd{S-@key{RET},org-table-copy-down}
2236 @vindex org-table-copy-increment
2237 When current field is empty, copy from first non-empty field above. When not
2238 empty, copy current field down to next row and move cursor along with it.
2239 Depending on the option @code{org-table-copy-increment}, integer field
2240 values will be incremented during copy. Integers that are too large will not
2241 be incremented. Also, a @code{0} prefix argument temporarily disables the
2242 increment. This key is also used by shift-selection and related modes
2243 (@pxref{Conflicts}).
2245 @tsubheading{Miscellaneous}
2246 @orgcmd{C-c `,org-table-edit-field}
2247 Edit the current field in a separate window. This is useful for fields that
2248 are not fully visible (@pxref{Column width and alignment}). When called with
2249 a @kbd{C-u} prefix, just make the full field visible, so that it can be
2250 edited in place. When called with two @kbd{C-u} prefixes, make the editor
2251 window follow the cursor through the table and always show the current
2252 field. The follow mode exits automatically when the cursor leaves the table,
2253 or when you repeat this command with @kbd{C-u C-u C-c `}.
2255 @item M-x org-table-import RET
2256 Import a file as a table. The table should be TAB or whitespace
2257 separated. Use, for example, to import a spreadsheet table or data
2258 from a database, because these programs generally can write
2259 TAB-separated text files. This command works by inserting the file into
2260 the buffer and then converting the region to a table. Any prefix
2261 argument is passed on to the converter, which uses it to determine the
2263 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2264 Tables can also be imported by pasting tabular text into the Org
2265 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
2266 @kbd{C-c |} command (see above under @i{Creation and conversion}).
2268 @item M-x org-table-export RET
2269 @findex org-table-export
2270 @vindex org-table-export-default-format
2271 Export the table, by default as a TAB-separated file. Use for data
2272 exchange with, for example, spreadsheet or database programs. The format
2273 used to export the file can be configured in the option
2274 @code{org-table-export-default-format}. You may also use properties
2275 @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
2276 name and the format for table export in a subtree. Org supports quite
2277 general formats for exported tables. The exporter format is the same as the
2278 format used by Orgtbl radio tables, see @ref{Translator functions}, for a
2279 detailed description.
2282 If you don't like the automatic table editor because it gets in your
2283 way on lines which you would like to start with @samp{|}, you can turn
2287 (setq org-enable-table-editor nil)
2290 @noindent Then the only table command that still works is
2291 @kbd{C-c C-c} to do a manual re-align.
2293 @node Column width and alignment
2294 @section Column width and alignment
2295 @cindex narrow columns in tables
2296 @cindex alignment in tables
2298 The width of columns is automatically determined by the table editor. And
2299 also the alignment of a column is determined automatically from the fraction
2300 of number-like versus non-number fields in the column.
2302 Sometimes a single field or a few fields need to carry more text, leading to
2303 inconveniently wide columns. Or maybe you want to make a table with several
2304 columns having a fixed width, regardless of content. To set the width of
2305 a column, one field anywhere in the column may contain just the string
2306 @samp{<N>} where @samp{N} is an integer specifying the width of the column in
2307 characters. The next re-align will then set the width of this column to this
2312 |---+------------------------------| |---+--------|
2314 | 1 | one | | 1 | one |
2315 | 2 | two | ----\ | 2 | two |
2316 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
2317 | 4 | four | | 4 | four |
2318 |---+------------------------------| |---+--------|
2323 Fields that are wider become clipped and end in the string @samp{=>}.
2324 Note that the full text is still in the buffer but is hidden.
2325 To see the full text, hold the mouse over the field---a tool-tip window
2326 will show the full content. To edit such a field, use the command
2327 @kbd{C-c `} (that is @kbd{C-c} followed by the grave accent). This will
2328 open a new window with the full field. Edit it and finish with @kbd{C-c
2331 @vindex org-startup-align-all-tables
2332 When visiting a file containing a table with narrowed columns, the
2333 necessary character hiding has not yet happened, and the table needs to
2334 be aligned before it looks nice. Setting the option
2335 @code{org-startup-align-all-tables} will realign all tables in a file
2336 upon visiting, but also slow down startup. You can also set this option
2337 on a per-file basis with:
2344 If you would like to overrule the automatic alignment of number-rich columns
2345 to the right and of string-rich columns to the left, you can use @samp{<r>},
2346 @samp{<c>}@footnote{Centering does not work inside Emacs, but it does have an
2347 effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may
2348 also combine alignment and field width like this: @samp{<r10>}.
2350 Lines which only contain these formatting cookies will be removed
2351 automatically when exporting the document.
2354 @section Column groups
2355 @cindex grouping columns in tables
2357 When Org exports tables, it does so by default without vertical lines because
2358 that is visually more satisfying in general. Occasionally however, vertical
2359 lines can be useful to structure a table into groups of columns, much like
2360 horizontal lines can do for groups of rows. In order to specify column
2361 groups, you can use a special row where the first field contains only
2362 @samp{/}. The further fields can either contain @samp{<} to indicate that
2363 this column should start a group, @samp{>} to indicate the end of a group, or
2364 @samp{<>} (no space between @samp{<} and @samp{>}) to make a column a group
2365 of its own. Boundaries between column groups will upon export be marked with
2366 vertical lines. Here is an example:
2369 | N | N^2 | N^3 | N^4 | ~sqrt(n)~ | ~sqrt[4](N)~ |
2370 |---+-----+-----+-----+-----------+--------------|
2371 | / | < | | > | < | > |
2372 | 1 | 1 | 1 | 1 | 1 | 1 |
2373 | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
2374 | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
2375 |---+-----+-----+-----+-----------+--------------|
2376 #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
2379 It is also sufficient to just insert the column group starters after
2380 every vertical line you would like to have:
2383 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2384 |----+-----+-----+-----+---------+------------|
2389 @section The Orgtbl minor mode
2391 @cindex minor mode for tables
2393 If you like the intuitive way the Org table editor works, you
2394 might also want to use it in other modes like Text mode or Mail mode.
2395 The minor mode Orgtbl mode makes this possible. You can always toggle
2396 the mode with @kbd{M-x orgtbl-mode RET}. To turn it on by default, for
2397 example in Message mode, use
2400 (add-hook 'message-mode-hook 'turn-on-orgtbl)
2403 Furthermore, with some special setup, it is possible to maintain tables
2404 in arbitrary syntax with Orgtbl mode. For example, it is possible to
2405 construct @LaTeX{} tables with the underlying ease and power of
2406 Orgtbl mode, including spreadsheet capabilities. For details, see
2407 @ref{Tables in arbitrary syntax}.
2409 @node The spreadsheet
2410 @section The spreadsheet
2411 @cindex calculations, in tables
2412 @cindex spreadsheet capabilities
2413 @cindex @file{calc} package
2415 The table editor makes use of the Emacs @file{calc} package to implement
2416 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
2417 derive fields from other fields. While fully featured, Org's implementation
2418 is not identical to other spreadsheets. For example, Org knows the concept
2419 of a @emph{column formula} that will be applied to all non-header fields in a
2420 column without having to copy the formula to each relevant field. There is
2421 also a formula debugger, and a formula editor with features for highlighting
2422 fields in the table corresponding to the references at the point in the
2423 formula, moving these references by arrow keys
2426 * References:: How to refer to another field or range
2427 * Formula syntax for Calc:: Using Calc to compute stuff
2428 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
2429 * Durations and time values:: How to compute durations and time values
2430 * Field and range formulas:: Formula for specific (ranges of) fields
2431 * Column formulas:: Formulas valid for an entire column
2432 * Lookup functions:: Lookup functions for searching tables
2433 * Editing and debugging formulas:: Fixing formulas
2434 * Updating the table:: Recomputing all dependent fields
2435 * Advanced features:: Field and column names, parameters and automatic recalc
2439 @subsection References
2442 To compute fields in the table from other fields, formulas must
2443 reference other fields or ranges. In Org, fields can be referenced
2444 by name, by absolute coordinates, and by relative coordinates. To find
2445 out what the coordinates of a field are, press @kbd{C-c ?} in that
2446 field, or press @kbd{C-c @}} to toggle the display of a grid.
2448 @subsubheading Field references
2449 @cindex field references
2450 @cindex references, to fields
2452 Formulas can reference the value of another field in two ways. Like in
2453 any other spreadsheet, you may reference fields with a letter/number
2454 combination like @code{B3}, meaning the 2nd field in the 3rd row.
2455 @vindex org-table-use-standard-references
2456 However, Org prefers@footnote{Org will understand references typed by the
2457 user as @samp{B4}, but it will not use this syntax when offering a formula
2458 for editing. You can customize this behavior using the option
2459 @code{org-table-use-standard-references}.} to use another, more general
2460 representation that looks like this:
2462 @@@var{row}$@var{column}
2465 Column specifications can be absolute like @code{$1},
2466 @code{$2},...@code{$@var{N}}, or relative to the current column (i.e., the
2467 column of the field which is being computed) like @code{$+1} or @code{$-2}.
2468 @code{$<} and @code{$>} are immutable references to the first and last
2469 column, respectively, and you can use @code{$>>>} to indicate the third
2470 column from the right.
2472 The row specification only counts data lines and ignores horizontal separator
2473 lines (hlines). Like with columns, you can use absolute row numbers
2474 @code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
2475 current row like @code{@@+3} or @code{@@-1}. @code{@@<} and @code{@@>} are
2476 immutable references the first and last@footnote{For backward compatibility
2477 you can also use special names like @code{$LR5} and @code{$LR12} to refer in
2478 a stable way to the 5th and 12th field in the last row of the table.
2479 However, this syntax is deprecated, it should not be used for new documents.
2480 Use @code{@@>$} instead.} row in the table, respectively. You may also
2481 specify the row relative to one of the hlines: @code{@@I} refers to the first
2482 hline, @code{@@II} to the second, etc. @code{@@-I} refers to the first such
2483 line above the current line, @code{@@+I} to the first such line below the
2484 current line. You can also write @code{@@III+2} which is the second data line
2485 after the third hline in the table.
2487 @code{@@0} and @code{$0} refer to the current row and column, respectively,
2488 i.e., to the row/column for the field being computed. Also, if you omit
2489 either the column or the row part of the reference, the current row/column is
2492 Org's references with @emph{unsigned} numbers are fixed references
2493 in the sense that if you use the same reference in the formula for two
2494 different fields, the same field will be referenced each time.
2495 Org's references with @emph{signed} numbers are floating
2496 references because the same reference operator can reference different
2497 fields depending on the field being calculated by the formula.
2499 Here are a few examples:
2502 @@2$3 @r{2nd row, 3rd column (same as @code{C2})}
2503 $5 @r{column 5 in the current row (same as @code{E&})}
2504 @@2 @r{current column, row 2}
2505 @@-1$-3 @r{the field one row up, three columns to the left}
2506 @@-I$2 @r{field just under hline above current row, column 2}
2507 @@>$5 @r{field in the last row, in column 5}
2510 @subsubheading Range references
2511 @cindex range references
2512 @cindex references, to ranges
2514 You may reference a rectangular range of fields by specifying two field
2515 references connected by two dots @samp{..}. If both fields are in the
2516 current row, you may simply use @samp{$2..$7}, but if at least one field
2517 is in a different row, you need to use the general @code{@@row$column}
2518 format at least for the first field (i.e the reference must start with
2519 @samp{@@} in order to be interpreted correctly). Examples:
2522 $1..$3 @r{first three fields in the current row}
2523 $P..$Q @r{range, using column names (see under Advanced)}
2524 $<<<..$>> @r{start in third column, continue to the last but one}
2525 @@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
2526 @@-1$-2..@@-1 @r{3 fields in the row above, starting from 2 columns on the left}
2527 @@I..II @r{between first and second hline, short for @code{@@I..@@II}}
2530 @noindent Range references return a vector of values that can be fed
2531 into Calc vector functions. Empty fields in ranges are normally suppressed,
2532 so that the vector contains only the non-empty fields. For other options
2533 with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax
2536 @subsubheading Field coordinates in formulas
2537 @cindex field coordinates
2538 @cindex coordinates, of field
2539 @cindex row, of field coordinates
2540 @cindex column, of field coordinates
2542 One of the very first actions during evaluation of Calc formulas and Lisp
2543 formulas is to substitute @code{@@#} and @code{$#} in the formula with the
2544 row or column number of the field where the current result will go to. The
2545 traditional Lisp formula equivalents are @code{org-table-current-dline} and
2546 @code{org-table-current-column}. Examples:
2549 @item if(@@# % 2, $#, string(""))
2550 Insert column number on odd rows, set field to empty on even rows.
2551 @item $2 = '(identity remote(FOO, @@@@#$1))
2552 Copy text or values of each row of column 1 of the table named @code{FOO}
2553 into column 2 of the current table.
2554 @item @@3 = 2 * remote(FOO, @@1$$#)
2555 Insert the doubled value of each column of row 1 of the table named
2556 @code{FOO} into row 3 of the current table.
2559 @noindent For the second/third example, the table named @code{FOO} must have
2560 at least as many rows/columns as the current table. Note that this is
2561 inefficient@footnote{The computation time scales as O(N^2) because the table
2562 named @code{FOO} is parsed for each field to be read.} for large number of
2565 @subsubheading Named references
2566 @cindex named references
2567 @cindex references, named
2568 @cindex name, of column or field
2569 @cindex constants, in calculations
2572 @vindex org-table-formula-constants
2573 @samp{$name} is interpreted as the name of a column, parameter or
2574 constant. Constants are defined globally through the option
2575 @code{org-table-formula-constants}, and locally (for the file) through a
2579 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
2583 @vindex constants-unit-system
2584 @pindex constants.el
2585 Also properties (@pxref{Properties and columns}) can be used as
2586 constants in table formulas: for a property @samp{:Xyz:} use the name
2587 @samp{$PROP_Xyz}, and the property will be searched in the current
2588 outline entry and in the hierarchy above it. If you have the
2589 @file{constants.el} package, it will also be used to resolve constants,
2590 including natural constants like @samp{$h} for Planck's constant, and
2591 units like @samp{$km} for kilometers@footnote{@file{constants.el} can
2592 supply the values of constants in two different unit systems, @code{SI}
2593 and @code{cgs}. Which one is used depends on the value of the variable
2594 @code{constants-unit-system}. You can use the @code{#+STARTUP} options
2595 @code{constSI} and @code{constcgs} to set this value for the current
2596 buffer.}. Column names and parameters can be specified in special table
2597 lines. These are described below, see @ref{Advanced features}. All
2598 names must start with a letter, and further consist of letters and
2601 @subsubheading Remote references
2602 @cindex remote references
2603 @cindex references, remote
2604 @cindex references, to a different table
2605 @cindex name, of column or field
2606 @cindex constants, in calculations
2607 @cindex #+NAME, for table
2609 You may also reference constants, fields and ranges from a different table,
2610 either in the current file or even in a different file. The syntax is
2613 remote(NAME-OR-ID,REF)
2617 where NAME can be the name of a table in the current file as set by a
2618 @code{#+NAME: Name} line before the table. It can also be the ID of an
2619 entry, even in a different file, and the reference then refers to the first
2620 table in that entry. REF is an absolute field or range reference as
2621 described above for example @code{@@3$3} or @code{$somename}, valid in the
2624 Indirection of NAME-OR-ID: When NAME-OR-ID has the format @code{@@ROW$COLUMN}
2625 it will be substituted with the name or ID found in this field of the current
2626 table. For example @code{remote($1, @@>$2)} => @code{remote(year_2013,
2627 @@>$1)}. The format @code{B3} is not supported because it can not be
2628 distinguished from a plain table name or ID.
2630 @node Formula syntax for Calc
2631 @subsection Formula syntax for Calc
2632 @cindex formula syntax, Calc
2633 @cindex syntax, of formulas
2635 A formula can be any algebraic expression understood by the Emacs @file{Calc}
2636 package. Note that @file{calc} has the non-standard convention that @samp{/}
2637 has lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as
2638 @samp{a/(b*c)}. Before evaluation by @code{calc-eval} (@pxref{Calling Calc
2639 from Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc,
2640 GNU Emacs Calc Manual}), variable substitution takes place according to the
2641 rules described above.
2642 @cindex vectors, in table calculations
2643 The range vectors can be directly fed into the Calc vector functions
2644 like @samp{vmean} and @samp{vsum}.
2646 @cindex format specifier
2647 @cindex mode, for @file{calc}
2648 @vindex org-calc-default-modes
2649 A formula can contain an optional mode string after a semicolon. This
2650 string consists of flags to influence Calc and other modes during
2651 execution. By default, Org uses the standard Calc modes (precision
2652 12, angular units degrees, fraction and symbolic modes off). The display
2653 format, however, has been changed to @code{(float 8)} to keep tables
2654 compact. The default settings can be configured using the option
2655 @code{org-calc-default-modes}.
2657 @noindent List of modes:
2661 Set the internal Calc calculation precision to 20 digits.
2662 @item @code{n3}, @code{s3}, @code{e2}, @code{f4}
2663 Normal, scientific, engineering or fixed format of the result of Calc passed
2664 back to Org. Calc formatting is unlimited in precision as long as the Calc
2665 calculation precision is greater.
2666 @item @code{D}, @code{R}
2667 Degree and radian angle modes of Calc.
2668 @item @code{F}, @code{S}
2669 Fraction and symbolic modes of Calc.
2670 @item @code{T}, @code{t}, @code{U}
2671 Duration computations in Calc or Lisp, @pxref{Durations and time values}.
2673 If and how to consider empty fields. Without @samp{E} empty fields in range
2674 references are suppressed so that the Calc vector or Lisp list contains only
2675 the non-empty fields. With @samp{E} the empty fields are kept. For empty
2676 fields in ranges or empty field references the value @samp{nan} (not a
2677 number) is used in Calc formulas and the empty string is used for Lisp
2678 formulas. Add @samp{N} to use 0 instead for both formula types. For the
2679 value of a field the mode @samp{N} has higher precedence than @samp{E}.
2681 Interpret all fields as numbers, use 0 for non-numbers. See the next section
2682 to see how this is essential for computations with Lisp formulas. In Calc
2683 formulas it is used only occasionally because there number strings are
2684 already interpreted as numbers without @samp{N}.
2686 Literal, for Lisp formulas only. See the next section.
2690 Unless you use large integer numbers or high-precision-calculation and
2691 -display for floating point numbers you may alternatively provide a
2692 @samp{printf} format specifier to reformat the Calc result after it has been
2693 passed back to Org instead of letting Calc already do the
2694 formatting@footnote{The @samp{printf} reformatting is limited in precision
2695 because the value passed to it is converted into an @samp{integer} or
2696 @samp{double}. The @samp{integer} is limited in size by truncating the
2697 signed value to 32 bits. The @samp{double} is limited in precision to 64
2698 bits overall which leaves approximately 16 significant decimal digits.}. A
2702 $1+$2 @r{Sum of first and second field}
2703 $1+$2;%.2f @r{Same, format result to two decimals}
2704 exp($2)+exp($1) @r{Math functions can be used}
2705 $0;%.1f @r{Reformat current cell to 1 decimal}
2706 ($3-32)*5/9 @r{Degrees F -> C conversion}
2707 $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
2708 tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
2709 sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
2710 taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree}
2713 Calc also contains a complete set of logical operations, (@pxref{Logical
2714 Operations, , Logical Operations, calc, GNU Emacs Calc Manual}). For example
2717 @item if($1 < 20, teen, string(""))
2718 "teen" if age $1 is less than 20, else the Org table result field is set to
2719 empty with the empty string.
2720 @item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1
2721 Sum of the first two columns. When at least one of the input fields is empty
2722 the Org table result field is set to empty. @samp{E} is required to not
2723 convert empty fields to 0. @samp{f-1} is an optional Calc format string
2724 similar to @samp{%.1f} but leaves empty results empty.
2725 @item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E
2726 Mean value of a range unless there is any empty field. Every field in the
2727 range that is empty is replaced by @samp{nan} which lets @samp{vmean} result
2728 in @samp{nan}. Then @samp{typeof == 12} detects the @samp{nan} from
2729 @samp{vmean} and the Org table result field is set to empty. Use this when
2730 the sample set is expected to never have missing values.
2731 @item if("$1..$7" == "[]", string(""), vmean($1..$7))
2732 Mean value of a range with empty fields skipped. Every field in the range
2733 that is empty is skipped. When all fields in the range are empty the mean
2734 value is not defined and the Org table result field is set to empty. Use
2735 this when the sample set can have a variable size.
2736 @item vmean($1..$7); EN
2737 To complete the example before: Mean value of a range with empty fields
2738 counting as samples with value 0. Use this only when incomplete sample sets
2739 should be padded with 0 to the full size.
2742 You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
2743 and use them in formula syntax for Calc.
2745 @node Formula syntax for Lisp
2746 @subsection Emacs Lisp forms as formulas
2747 @cindex Lisp forms, as table formulas
2749 It is also possible to write a formula in Emacs Lisp. This can be useful
2750 for string manipulation and control structures, if Calc's functionality is
2753 If a formula starts with an apostrophe followed by an opening parenthesis,
2754 then it is evaluated as a Lisp form. The evaluation should return either a
2755 string or a number. Just as with @file{calc} formulas, you can specify modes
2756 and a printf format after a semicolon.
2758 With Emacs Lisp forms, you need to be conscious about the way field
2759 references are interpolated into the form. By default, a reference will be
2760 interpolated as a Lisp string (in double-quotes) containing the field. If
2761 you provide the @samp{N} mode switch, all referenced elements will be numbers
2762 (non-number fields will be zero) and interpolated as Lisp numbers, without
2763 quotes. If you provide the @samp{L} flag, all fields will be interpolated
2764 literally, without quotes. I.e., if you want a reference to be interpreted
2765 as a string by the Lisp form, enclose the reference operator itself in
2766 double-quotes, like @code{"$3"}. Ranges are inserted as space-separated
2767 fields, so you can embed them in list or vector syntax.
2769 Here are a few examples---note how the @samp{N} mode is used when we do
2770 computations in Lisp:
2773 @item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
2774 Swap the first two characters of the content of column 1.
2776 Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
2777 @item '(apply '+ '($1..$4));N
2778 Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
2781 @node Durations and time values
2782 @subsection Durations and time values
2783 @cindex Duration, computing
2784 @cindex Time, computing
2785 @vindex org-table-duration-custom-format
2787 If you want to compute time values use the @code{T}, @code{t}, or @code{U}
2788 flag, either in Calc formulas or Elisp formulas:
2792 | Task 1 | Task 2 | Total |
2793 |---------+----------+----------|
2794 | 2:12 | 1:47 | 03:59:00 |
2795 | 2:12 | 1:47 | 03:59 |
2796 | 3:02:20 | -2:07:00 | 0.92 |
2797 #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;U::@@4$3=$1+$2;t
2801 Input duration values must be of the form @code{HH:MM[:SS]}, where seconds
2802 are optional. With the @code{T} flag, computed durations will be displayed
2803 as @code{HH:MM:SS} (see the first formula above). With the @code{U} flag,
2804 seconds will be omitted so that the result will be only @code{HH:MM} (see
2805 second formula above). Zero-padding of the hours field will depend upon the
2806 value of the variable @code{org-table-duration-hour-zero-padding}.
2808 With the @code{t} flag, computed durations will be displayed according to the
2809 value of the option @code{org-table-duration-custom-format}, which defaults
2810 to @code{'hours} and will display the result as a fraction of hours (see the
2811 third formula in the example above).
2813 Negative duration values can be manipulated as well, and integers will be
2814 considered as seconds in addition and subtraction.
2816 @node Field and range formulas
2817 @subsection Field and range formulas
2818 @cindex field formula
2819 @cindex range formula
2820 @cindex formula, for individual table field
2821 @cindex formula, for range of fields
2823 To assign a formula to a particular field, type it directly into the field,
2824 preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press
2825 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2826 the formula will be stored as the formula for this field, evaluated, and the
2827 current field will be replaced with the result.
2830 Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
2831 below the table. If you type the equation in the 4th field of the 3rd data
2832 line in the table, the formula will look like @samp{@@3$4=$1+$2}. When
2833 inserting/deleting/swapping columns and rows with the appropriate commands,
2834 @i{absolute references} (but not relative ones) in stored formulas are
2835 modified in order to still reference the same field. To avoid this, in
2836 particular in range references, anchor ranges at the table borders (using
2837 @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines using the
2838 @code{@@I} notation. Automatic adaptation of field references does of course
2839 not happen if you edit the table structure with normal editing
2840 commands---then you must fix the equations yourself.
2842 Instead of typing an equation into the field, you may also use the following
2846 @orgcmd{C-u C-c =,org-table-eval-formula}
2847 Install a new formula for the current field. The command prompts for a
2848 formula with default taken from the @samp{#+TBLFM:} line, applies
2849 it to the current field, and stores it.
2852 The left-hand side of a formula can also be a special expression in order to
2853 assign the formula to a number of different fields. There is no keyboard
2854 shortcut to enter such range formulas. To add them, use the formula editor
2855 (@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
2860 Column formula, valid for the entire column. This is so common that Org
2861 treats these formulas in a special way, see @ref{Column formulas}.
2863 Row formula, applies to all fields in the specified row. @code{@@>=} means
2866 Range formula, applies to all fields in the given rectangular range. This
2867 can also be used to assign a formula to some but not all fields in a row.
2869 Named field, see @ref{Advanced features}.
2872 @node Column formulas
2873 @subsection Column formulas
2874 @cindex column formula
2875 @cindex formula, for table column
2877 When you assign a formula to a simple column reference like @code{$3=}, the
2878 same formula will be used in all fields of that column, with the following
2879 very convenient exceptions: (i) If the table contains horizontal separator
2880 hlines with rows above and below, everything before the first such hline is
2881 considered part of the table @emph{header} and will not be modified by column
2882 formulas. Therefore a header is mandatory when you use column formulas and
2883 want to add hlines to group rows, like for example to separate a total row at
2884 the bottom from the summand rows above. (ii) Fields that already get a value
2885 from a field/range formula will be left alone by column formulas. These
2886 conditions make column formulas very easy to use.
2888 To assign a formula to a column, type it directly into any field in the
2889 column, preceded by an equal sign, like @samp{=$1+$2}. When you press
2890 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2891 the formula will be stored as the formula for the current column, evaluated
2892 and the current field replaced with the result. If the field contains only
2893 @samp{=}, the previously stored formula for this column is used. For each
2894 column, Org will only remember the most recently used formula. In the
2895 @samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The
2896 left-hand side of a column formula cannot be the name of column, it must be
2897 the numeric column reference or @code{$>}.
2899 Instead of typing an equation into the field, you may also use the
2903 @orgcmd{C-c =,org-table-eval-formula}
2904 Install a new formula for the current column and replace current field with
2905 the result of the formula. The command prompts for a formula, with default
2906 taken from the @samp{#+TBLFM} line, applies it to the current field and
2907 stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
2908 will apply it to that many consecutive fields in the current column.
2911 @node Lookup functions
2912 @subsection Lookup functions
2913 @cindex lookup functions in tables
2914 @cindex table lookup functions
2916 Org has three predefined Emacs Lisp functions for lookups in tables.
2918 @item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)
2919 @findex org-lookup-first
2920 Searches for the first element @code{S} in list @code{S-LIST} for which
2924 is @code{t}; returns the value from the corresponding position in list
2925 @code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the
2926 parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same
2927 order as the corresponding parameters are in the call to
2928 @code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If
2929 @code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST}
2931 @item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)
2932 @findex org-lookup-last
2933 Similar to @code{org-lookup-first} above, but searches for the @i{last}
2934 element for which @code{PREDICATE} is @code{t}.
2935 @item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)
2936 @findex org-lookup-all
2937 Similar to @code{org-lookup-first}, but searches for @i{all} elements for
2938 which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding
2939 values. This function can not be used by itself in a formula, because it
2940 returns a list of values. However, powerful lookups can be built when this
2941 function is combined with other Emacs Lisp functions.
2944 If the ranges used in these functions contain empty fields, the @code{E} mode
2945 for the formula should usually be specified: otherwise empty fields will not be
2946 included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result
2947 in an incorrect mapping from an element of @code{S-LIST} to the corresponding
2948 element of @code{R-LIST}.
2950 These three functions can be used to implement associative arrays, count
2951 matching cells, rank results, group data etc. For practical examples
2952 see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
2955 @node Editing and debugging formulas
2956 @subsection Editing and debugging formulas
2957 @cindex formula editing
2958 @cindex editing, of table formulas
2960 @vindex org-table-use-standard-references
2961 You can edit individual formulas in the minibuffer or directly in the field.
2962 Org can also prepare a special buffer with all active formulas of a table.
2963 When offering a formula for editing, Org converts references to the standard
2964 format (like @code{B3} or @code{D&}) if possible. If you prefer to only work
2965 with the internal format (like @code{@@3$2} or @code{$4}), configure the
2966 option @code{org-table-use-standard-references}.
2969 @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
2970 Edit the formula associated with the current column/field in the
2971 minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}.
2972 @orgcmd{C-u C-u C-c =,org-table-eval-formula}
2973 Re-insert the active formula (either a
2974 field formula, or a column formula) into the current field, so that you
2975 can edit it directly in the field. The advantage over editing in the
2976 minibuffer is that you can use the command @kbd{C-c ?}.
2977 @orgcmd{C-c ?,org-table-field-info}
2978 While editing a formula in a table field, highlight the field(s)
2979 referenced by the reference at the cursor position in the formula.
2981 @findex org-table-toggle-coordinate-overlays
2983 Toggle the display of row and column numbers for a table, using overlays
2984 (@command{org-table-toggle-coordinate-overlays}). These are updated each
2985 time the table is aligned; you can force it with @kbd{C-c C-c}.
2987 @findex org-table-toggle-formula-debugger
2989 Toggle the formula debugger on and off
2990 (@command{org-table-toggle-formula-debugger}). See below.
2991 @orgcmd{C-c ',org-table-edit-formulas}
2992 Edit all formulas for the current table in a special buffer, where the
2993 formulas will be displayed one per line. If the current field has an
2994 active formula, the cursor in the formula editor will mark it.
2995 While inside the special buffer, Org will automatically highlight
2996 any field or range reference at the cursor position. You may edit,
2997 remove and add formulas, and use the following commands:
3000 @orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
3001 Exit the formula editor and store the modified formulas. With @kbd{C-u}
3002 prefix, also apply the new formulas to the entire table.
3003 @orgcmd{C-c C-q,org-table-fedit-abort}
3004 Exit the formula editor without installing changes.
3005 @orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
3006 Toggle all references in the formula editor between standard (like
3007 @code{B3}) and internal (like @code{@@3$2}).
3008 @orgcmd{@key{TAB},org-table-fedit-lisp-indent}
3009 Pretty-print or indent Lisp formula at point. When in a line containing
3010 a Lisp formula, format the formula according to Emacs Lisp rules.
3011 Another @key{TAB} collapses the formula back again. In the open
3012 formula, @key{TAB} re-indents just like in Emacs Lisp mode.
3013 @orgcmd{M-@key{TAB},lisp-complete-symbol}
3014 Complete Lisp symbols, just like in Emacs Lisp mode.@footnote{Many desktops
3015 intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
3016 @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}
3018 @kindex S-@key{down}
3019 @kindex S-@key{left}
3020 @kindex S-@key{right}
3021 @findex org-table-fedit-ref-up
3022 @findex org-table-fedit-ref-down
3023 @findex org-table-fedit-ref-left
3024 @findex org-table-fedit-ref-right
3025 @item S-@key{up}/@key{down}/@key{left}/@key{right}
3026 Shift the reference at point. For example, if the reference is
3027 @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
3028 This also works for relative references and for hline references.
3029 @orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
3030 Move the test line for column formulas in the Org buffer up and
3032 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
3033 Scroll the window displaying the table.
3035 @findex org-table-toggle-coordinate-overlays
3037 Turn the coordinate grid in the table on and off.
3041 Making a table field blank does not remove the formula associated with
3042 the field, because that is stored in a different line (the @samp{#+TBLFM}
3043 line)---during the next recalculation the field will be filled again.
3044 To remove a formula from a field, you have to give an empty reply when
3045 prompted for the formula, or to edit the @samp{#+TBLFM} line.
3048 You may edit the @samp{#+TBLFM} directly and re-apply the changed
3049 equations with @kbd{C-c C-c} in that line or with the normal
3050 recalculation commands in the table.
3052 @anchor{Using multiple #+TBLFM lines}
3053 @subsubheading Using multiple #+TBLFM lines
3054 @cindex #+TBLFM line, multiple
3056 @cindex #+TBLFM, switching
3059 You may apply the formula temporarily. This is useful when you
3060 switch the formula. Place multiple @samp{#+TBLFM} lines right
3061 after the table, and then press @kbd{C-c C-c} on the formula to
3062 apply. Here is an example:
3074 Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
3086 Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
3087 will get the following result of applying only the first @samp{#+TBLFM} line.
3098 @subsubheading Debugging formulas
3099 @cindex formula debugging
3100 @cindex debugging, of table formulas
3101 When the evaluation of a formula leads to an error, the field content
3102 becomes the string @samp{#ERROR}. If you would like see what is going
3103 on during variable substitution and calculation in order to find a bug,
3104 turn on formula debugging in the @code{Tbl} menu and repeat the
3105 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
3106 field. Detailed information will be displayed.
3108 @node Updating the table
3109 @subsection Updating the table
3110 @cindex recomputing table fields
3111 @cindex updating, table
3113 Recalculation of a table is normally not automatic, but needs to be
3114 triggered by a command. See @ref{Advanced features}, for a way to make
3115 recalculation at least semi-automatic.
3117 In order to recalculate a line of a table or the entire table, use the
3121 @orgcmd{C-c *,org-table-recalculate}
3122 Recalculate the current row by first applying the stored column formulas
3123 from left to right, and all field/range formulas in the current row.
3129 Recompute the entire table, line by line. Any lines before the first
3130 hline are left alone, assuming that these are part of the table header.
3132 @orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
3133 Iterate the table by recomputing it until no further changes occur.
3134 This may be necessary if some computed fields use the value of other
3135 fields that are computed @i{later} in the calculation sequence.
3136 @item M-x org-table-recalculate-buffer-tables RET
3137 @findex org-table-recalculate-buffer-tables
3138 Recompute all tables in the current buffer.
3139 @item M-x org-table-iterate-buffer-tables RET
3140 @findex org-table-iterate-buffer-tables
3141 Iterate all tables in the current buffer, in order to converge table-to-table
3145 @node Advanced features
3146 @subsection Advanced features
3148 If you want the recalculation of fields to happen automatically, or if you
3149 want to be able to assign @i{names}@footnote{Such names must start by an
3150 alphabetic character and use only alphanumeric/underscore characters.} to
3151 fields and columns, you need to reserve the first column of the table for
3152 special marking characters.
3155 @orgcmd{C-#,org-table-rotate-recalc-marks}
3156 Rotate the calculation mark in first column through the states @samp{ },
3157 @samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,
3158 change all marks in the region.
3161 Here is an example of a table that collects exam results of students and
3162 makes use of these features:
3166 |---+---------+--------+--------+--------+-------+------|
3167 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
3168 |---+---------+--------+--------+--------+-------+------|
3169 | ! | | P1 | P2 | P3 | Tot | |
3170 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
3171 | ^ | | m1 | m2 | m3 | mt | |
3172 |---+---------+--------+--------+--------+-------+------|
3173 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
3174 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
3175 |---+---------+--------+--------+--------+-------+------|
3176 | | Average | | | | 25.0 | |
3177 | ^ | | | | | at | |
3178 | $ | max=50 | | | | | |
3179 |---+---------+--------+--------+--------+-------+------|
3180 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
3184 @noindent @b{Important}: please note that for these special tables,
3185 recalculating the table with @kbd{C-u C-c *} will only affect rows that
3186 are marked @samp{#} or @samp{*}, and fields that have a formula assigned
3187 to the field itself. The column formulas are not applied in rows with
3190 @cindex marking characters, tables
3191 The marking characters have the following meaning:
3195 The fields in this line define names for the columns, so that you may
3196 refer to a column as @samp{$Tot} instead of @samp{$6}.
3198 This row defines names for the fields @emph{above} the row. With such
3199 a definition, any formula in the table may use @samp{$m1} to refer to
3200 the value @samp{10}. Also, if you assign a formula to a names field, it
3201 will be stored as @samp{$name=...}.
3203 Similar to @samp{^}, but defines names for the fields in the row
3206 Fields in this row can define @emph{parameters} for formulas. For
3207 example, if a field in a @samp{$} row contains @samp{max=50}, then
3208 formulas in this table can refer to the value 50 using @samp{$max}.
3209 Parameters work exactly like constants, only that they can be defined on
3212 Fields in this row are automatically recalculated when pressing
3213 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
3214 is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
3215 lines will be left alone by this command.
3217 Selects this line for global recalculation with @kbd{C-u C-c *}, but
3218 not for automatic recalculation. Use this when automatic
3219 recalculation slows down editing too much.
3221 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
3222 All lines that should be recalculated should be marked with @samp{#}
3225 Do not export this line. Useful for lines that contain the narrowing
3226 @samp{<N>} markers or column group markers.
3229 Finally, just to whet your appetite for what can be done with the
3230 fantastic @file{calc.el} package, here is a table that computes the Taylor
3231 series of degree @code{n} at location @code{x} for a couple of
3236 |---+-------------+---+-----+--------------------------------------|
3237 | | Func | n | x | Result |
3238 |---+-------------+---+-----+--------------------------------------|
3239 | # | exp(x) | 1 | x | 1 + x |
3240 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
3241 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
3242 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
3243 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
3244 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
3245 |---+-------------+---+-----+--------------------------------------|
3246 #+TBLFM: $5=taylor($2,$4,$3);n3
3252 @cindex graph, in tables
3253 @cindex plot tables using Gnuplot
3256 Org-Plot can produce graphs of information stored in org tables, either
3257 graphically or in ASCII-art.
3259 @subheading Graphical plots using @file{Gnuplot}
3261 Org-Plot produces 2D and 3D graphs using @file{Gnuplot}
3262 @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
3263 @uref{http://xafs.org/BruceRavel/GnuplotMode}. To see this in action, ensure
3264 that you have both Gnuplot and Gnuplot mode installed on your system, then
3265 call @kbd{C-c " g} or @kbd{M-x org-plot/gnuplot @key{RET}} on the following
3270 #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
3271 | Sede | Max cites | H-index |
3272 |-----------+-----------+---------|
3273 | Chile | 257.72 | 21.39 |
3274 | Leeds | 165.77 | 19.68 |
3275 | Sao Paolo | 71.00 | 11.50 |
3276 | Stockholm | 134.19 | 14.33 |
3277 | Morelia | 257.56 | 17.67 |
3281 Notice that Org Plot is smart enough to apply the table's headers as labels.
3282 Further control over the labels, type, content, and appearance of plots can
3283 be exercised through the @code{#+PLOT:} lines preceding a table. See below
3284 for a complete list of Org-plot options. The @code{#+PLOT:} lines are
3285 optional. For more information and examples see the Org-plot tutorial at
3286 @uref{http://orgmode.org/worg/org-tutorials/org-plot.html}.
3288 @subsubheading Plot Options
3292 Specify any @command{gnuplot} option to be set when graphing.
3295 Specify the title of the plot.
3298 Specify which column of the table to use as the @code{x} axis.
3301 Specify the columns to graph as a Lisp style list, surrounded by parentheses
3302 and separated by spaces for example @code{dep:(3 4)} to graph the third and
3303 fourth columns (defaults to graphing all other columns aside from the @code{ind}
3307 Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
3310 Specify a @code{with} option to be inserted for every col being plotted
3311 (e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
3312 Defaults to @code{lines}.
3315 If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
3318 List of labels to be used for the @code{deps} (defaults to the column headers
3322 Specify an entire line to be inserted in the Gnuplot script.
3325 When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
3326 flat mapping rather than a @code{3d} slope.
3329 Specify format of Org mode timestamps as they will be parsed by Gnuplot.
3330 Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
3333 If you want total control, you can specify a script file (place the file name
3334 between double-quotes) which will be used to plot. Before plotting, every
3335 instance of @code{$datafile} in the specified script will be replaced with
3336 the path to the generated data file. Note: even if you set this option, you
3337 may still want to specify the plot type, as that can impact the content of
3341 @subheading ASCII bar plots
3343 While the cursor is on a column, typing @kbd{C-c " a} or
3344 @kbd{M-x orgtbl-ascii-plot @key{RET}} create a new column containing an
3345 ASCII-art bars plot. The plot is implemented through a regular column
3346 formula. When the source column changes, the bar plot may be updated by
3347 refreshing the table, for example typing @kbd{C-u C-c *}.
3351 | Sede | Max cites | |
3352 |---------------+-----------+--------------|
3353 | Chile | 257.72 | WWWWWWWWWWWW |
3354 | Leeds | 165.77 | WWWWWWWh |
3355 | Sao Paolo | 71.00 | WWW; |
3356 | Stockholm | 134.19 | WWWWWW: |
3357 | Morelia | 257.56 | WWWWWWWWWWWH |
3358 | Rochefourchat | 0.00 | |
3359 #+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12)
3363 The formula is an elisp call:
3365 (orgtbl-ascii-draw COLUMN MIN MAX WIDTH)
3370 is a reference to the source column.
3373 are the minimal and maximal values displayed. Sources values
3374 outside this range are displayed as @samp{too small}
3375 or @samp{too large}.
3378 is the width in characters of the bar-plot. It defaults to @samp{12}.
3386 Like HTML, Org provides links inside a file, external links to
3387 other files, Usenet articles, emails, and much more.
3390 * Link format:: How links in Org are formatted
3391 * Internal links:: Links to other places in the current file
3392 * External links:: URL-like links to the world
3393 * Handling links:: Creating, inserting and following
3394 * Using links outside Org:: Linking from my C source code?
3395 * Link abbreviations:: Shortcuts for writing complex links
3396 * Search options:: Linking to a specific location
3397 * Custom searches:: When the default search is not enough
3401 @section Link format
3403 @cindex format, of links
3405 Org will recognize plain URL-like links and activate them as
3406 clickable links. The general link format, however, looks like this:
3409 [[link][description]] @r{or alternatively} [[link]]
3413 Once a link in the buffer is complete (all brackets present), Org
3414 will change the display so that @samp{description} is displayed instead
3415 of @samp{[[link][description]]} and @samp{link} is displayed instead of
3416 @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
3417 which by default is an underlined face. You can directly edit the
3418 visible part of a link. Note that this can be either the @samp{link}
3419 part (if there is no description) or the @samp{description} part. To
3420 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
3423 If you place the cursor at the beginning or just behind the end of the
3424 displayed text and press @key{BACKSPACE}, you will remove the
3425 (invisible) bracket at that location. This makes the link incomplete
3426 and the internals are again displayed as plain text. Inserting the
3427 missing bracket hides the link internals again. To show the
3428 internal structure of all links, use the menu entry
3429 @code{Org->Hyperlinks->Literal links}.
3431 @node Internal links
3432 @section Internal links
3433 @cindex internal links
3434 @cindex links, internal
3435 @cindex targets, for links
3437 @cindex property, CUSTOM_ID
3438 If the link does not look like a URL, it is considered to be internal in the
3439 current file. The most important case is a link like
3440 @samp{[[#my-custom-id]]} which will link to the entry with the
3441 @code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself
3442 to make sure these custom IDs are unique in a file.
3444 Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
3445 lead to a text search in the current file.
3447 The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
3448 or with a mouse click (@pxref{Handling links}). Links to custom IDs will
3449 point to the corresponding headline. The preferred match for a text link is
3450 a @i{dedicated target}: the same string in double angular brackets, like
3451 @samp{<<My Target>>}.
3454 If no dedicated target exists, the link will then try to match the exact name
3455 of an element within the buffer. Naming is done with the @code{#+NAME}
3456 keyword, which has to be put in the line before the element it refers to, as
3457 in the following example
3466 If none of the above succeeds, Org will search for a headline that is exactly
3467 the link text but may also include a TODO keyword and tags@footnote{To insert
3468 a link targeting a headline, in-buffer completion can be used. Just type
3469 a star followed by a few optional letters into the buffer and press
3470 @kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as
3473 During export, internal links will be used to mark objects and assign them
3474 a number. Marked objects will then be referenced by links pointing to them.
3475 In particular, links without a description will appear as the number assigned
3476 to the marked object@footnote{When targeting a @code{#+NAME} keyword,
3477 @code{#+CAPTION} keyword is mandatory in order to get proper numbering
3478 (@pxref{Images and tables}).}. In the following excerpt from an Org buffer
3482 - <<target>>another item
3483 Here we refer to item [[target]].
3487 The last sentence will appear as @samp{Here we refer to item 2} when
3490 In non-Org files, the search will look for the words in the link text. In
3491 the above example the search would be for @samp{my target}.
3493 Following a link pushes a mark onto Org's own mark ring. You can
3494 return to the previous position with @kbd{C-c &}. Using this command
3495 several times in direct succession goes back to positions recorded
3499 * Radio targets:: Make targets trigger links in plain text
3503 @subsection Radio targets
3504 @cindex radio targets
3505 @cindex targets, radio
3506 @cindex links, radio targets
3508 Org can automatically turn any occurrences of certain target names
3509 in normal text into a link. So without explicitly creating a link, the
3510 text connects to the target radioing its position. Radio targets are
3511 enclosed by triple angular brackets. For example, a target @samp{<<<My
3512 Target>>>} causes each occurrence of @samp{my target} in normal text to
3513 become activated as a link. The Org file is scanned automatically
3514 for radio targets only when the file is first loaded into Emacs. To
3515 update the target list during editing, press @kbd{C-c C-c} with the
3516 cursor on or at a target.
3518 @node External links
3519 @section External links
3520 @cindex links, external
3521 @cindex external links
3529 @cindex USENET links
3534 Org supports links to files, websites, Usenet and email messages, BBDB
3535 database entries and links to both IRC conversations and their logs.
3536 External links are URL-like locators. They start with a short identifying
3537 string followed by a colon. There can be no space after the colon. The
3538 following list shows examples for each link type.
3541 http://www.astro.uva.nl/~dominik @r{on the web}
3542 doi:10.1000/182 @r{DOI for an electronic resource}
3543 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
3544 /home/dominik/images/jupiter.jpg @r{same as above}
3545 file:papers/last.pdf @r{file, relative path}
3546 ./papers/last.pdf @r{same as above}
3547 file:/ssh:myself@@some.where:papers/last.pdf @r{file, path on remote machine}
3548 /ssh:myself@@some.where:papers/last.pdf @r{same as above}
3549 file:sometextfile::NNN @r{file, jump to line number}
3550 file:projects.org @r{another Org file}
3551 file:projects.org::some words @r{text search in Org file}@footnote{
3552 The actual behavior of the search will depend on the value of
3553 the option @code{org-link-search-must-match-exact-headline}. If its value
3554 is @code{nil}, then a fuzzy text search will be done. If it is @code{t}, then only
3555 the exact headline will be matched, ignoring spaces and cookies. If the
3556 value is @code{query-to-create}, then an exact headline will be searched; if
3557 it is not found, then the user will be queried to create it.}
3558 file:projects.org::*task title @r{heading search in Org file}@footnote{
3559 Headline searches always match the exact headline, ignoring
3560 spaces and cookies. If the headline is not found and the value of the option
3561 @code{org-link-search-must-match-exact-headline} is @code{query-to-create},
3562 then the user will be queried to create it.}
3563 docview:papers/last.pdf::NNN @r{open in doc-view mode at page}
3564 id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
3565 news:comp.emacs @r{Usenet link}
3566 mailto:adent@@galaxy.net @r{Mail link}
3567 mhe:folder @r{MH-E folder link}
3568 mhe:folder#id @r{MH-E message link}
3569 rmail:folder @r{RMAIL folder link}
3570 rmail:folder#id @r{RMAIL message link}
3571 gnus:group @r{Gnus group link}
3572 gnus:group#id @r{Gnus article link}
3573 bbdb:R.*Stallman @r{BBDB link (with regexp)}
3574 irc:/irc.com/#emacs/bob @r{IRC link}
3575 info:org#External links @r{Info node or index link}
3576 shell:ls *.org @r{A shell command}
3577 elisp:org-agenda @r{Interactive Elisp command}
3578 elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
3582 @cindex WANDERLUST links
3583 On top of these built-in link types, some are available through the
3584 @code{contrib/} directory (@pxref{Installation}). For example, these links
3585 to VM or Wanderlust messages are available when you load the corresponding
3586 libraries from the @code{contrib/} directory:
3589 vm:folder @r{VM folder link}
3590 vm:folder#id @r{VM message link}
3591 vm://myself@@some.where.org/folder#id @r{VM on remote machine}
3592 vm-imap:account:folder @r{VM IMAP folder link}
3593 vm-imap:account:folder#id @r{VM IMAP message link}
3594 wl:folder @r{WANDERLUST folder link}
3595 wl:folder#id @r{WANDERLUST message link}
3598 For customizing Org to add new link types @ref{Adding hyperlink types}.
3600 A link should be enclosed in double brackets and may contain a descriptive
3601 text to be displayed instead of the URL (@pxref{Link format}), for example:
3604 [[https://www.gnu.org/software/emacs/][GNU Emacs]]
3608 If the description is a file name or URL that points to an image, HTML
3609 export (@pxref{HTML export}) will inline the image as a clickable
3610 button. If there is no description at all and the link points to an
3612 that image will be inlined into the exported HTML file.
3614 @cindex square brackets, around links
3615 @cindex plain text external links
3616 Org also finds external links in the normal text and activates them
3617 as links. If spaces must be part of the link (for example in
3618 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
3619 about the end of the link, enclose them in square brackets.
3621 @node Handling links
3622 @section Handling links
3623 @cindex links, handling
3625 Org provides methods to create a link in the correct syntax, to
3626 insert it into an Org file, and to follow the link.
3629 @orgcmd{C-c l,org-store-link}
3630 @cindex storing links
3631 Store a link to the current location. This is a @emph{global} command (you
3632 must create the key binding yourself) which can be used in any buffer to
3633 create a link. The link will be stored for later insertion into an Org
3634 buffer (see below). What kind of link will be created depends on the current
3637 @b{Org mode buffers}@*
3638 For Org files, if there is a @samp{<<target>>} at the cursor, the link points
3639 to the target. Otherwise it points to the current headline, which will also
3640 be the description@footnote{If the headline contains a timestamp, it will be
3641 removed from the link and result in a wrong link---you should avoid putting
3642 timestamp in the headline.}.
3644 @vindex org-id-link-to-org-use-id
3645 @cindex property, CUSTOM_ID
3646 @cindex property, ID
3647 If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
3648 will be stored. In addition or alternatively (depending on the value of
3649 @code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
3650 be created and/or used to construct a link@footnote{The library
3651 @file{org-id.el} must first be loaded, either through @code{org-customize} by
3652 enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
3653 'org-id)} in your Emacs init file.}. So using this command in Org buffers
3654 will potentially create two links: a human-readable from the custom ID, and
3655 one that is globally unique and works even if the entry is moved from file to
3656 file. Later, when inserting the link, you need to decide which one to use.
3658 @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
3659 Pretty much all Emacs mail clients are supported. The link will point to the
3660 current article, or, in some GNUS buffers, to the group. The description is
3661 constructed from the author and the subject.
3663 @b{Web browsers: Eww, W3 and W3M}@*
3664 Here the link will be the current URL, with the page title as description.
3666 @b{Contacts: BBDB}@*
3667 Links created in a BBDB buffer will point to the current entry.
3670 @vindex org-irc-link-to-logs
3671 For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t},
3672 a @samp{file:/} style link to the relevant point in the logs for the current
3673 conversation is created. Otherwise an @samp{irc:/} style link to the
3674 user/channel/server under the point will be stored.
3677 For any other files, the link will point to the file, with a search string
3678 (@pxref{Search options}) pointing to the contents of the current line. If
3679 there is an active region, the selected words will form the basis of the
3680 search string. If the automatically created link is not working correctly or
3681 accurately enough, you can write custom functions to select the search string
3682 and to do the search for particular file types---see @ref{Custom searches}.
3683 The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
3686 When the cursor is in an agenda view, the created link points to the
3687 entry referenced by the current line.
3690 @orgcmd{C-c C-l,org-insert-link}
3691 @cindex link completion
3692 @cindex completion, of links
3693 @cindex inserting links
3694 @vindex org-keep-stored-link-after-insertion
3695 @vindex org-link-parameters
3696 Insert a link@footnote{Note that you don't have to use this command to
3697 insert a link. Links in Org are plain text, and you can type or paste them
3698 straight into the buffer. By using this command, the links are automatically
3699 enclosed in double brackets, and you will be asked for the optional
3700 descriptive text.}. This prompts for a link to be inserted into the buffer.
3701 You can just type a link, using text for an internal link, or one of the link
3702 type prefixes mentioned in the examples above. The link will be inserted
3703 into the buffer@footnote{After insertion of a stored link, the link will be
3704 removed from the list of stored links. To keep it in the list later use, use
3705 a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
3706 @code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
3707 If some text was selected when this command is called, the selected text
3708 becomes the default description.
3710 @b{Inserting stored links}@*
3711 All links stored during the
3712 current session are part of the history for this prompt, so you can access
3713 them with @key{up} and @key{down} (or @kbd{M-p/n}).
3715 @b{Completion support}@* Completion with @key{TAB} will help you to insert
3716 valid link prefixes like @samp{https:}, including the prefixes
3717 defined through link abbreviations (@pxref{Link abbreviations}). If you
3718 press @key{RET} after inserting only the @var{prefix}, Org will offer
3719 specific completion support for some link types@footnote{This works if
3720 a completion function is defined in the @samp{:complete} property of a link
3721 in @code{org-link-parameters}.} For example, if you type @kbd{file
3722 @key{RET}}, file name completion (alternative access: @kbd{C-u C-c C-l}, see
3723 below) will be offered, and after @kbd{bbdb @key{RET}} you can complete
3726 @cindex file name completion
3727 @cindex completion, of file names
3728 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
3729 a file will be inserted and you may use file name completion to select
3730 the name of the file. The path to the file is inserted relative to the
3731 directory of the current Org file, if the linked file is in the current
3732 directory or in a sub-directory of it, or if the path is written relative
3733 to the current directory using @samp{../}. Otherwise an absolute path
3734 is used, if possible with @samp{~/} for your home directory. You can
3735 force an absolute path with two @kbd{C-u} prefixes.
3737 @item C-c C-l @ @r{(with cursor on existing link)}
3738 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
3739 link and description parts of the link.
3741 @cindex following links
3742 @orgcmd{C-c C-o,org-open-at-point}
3743 @vindex org-file-apps
3744 @vindex org-link-frame-setup
3745 Open link at point. This will launch a web browser for URLs (using
3746 @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
3747 the corresponding links, and execute the command in a shell link. When the
3748 cursor is on an internal link, this command runs the corresponding search.
3749 When the cursor is on a TAG list in a headline, it creates the corresponding
3750 TAGS view. If the cursor is on a timestamp, it compiles the agenda for that
3751 date. Furthermore, it will visit text and remote files in @samp{file:} links
3752 with Emacs and select a suitable application for local non-text files.
3753 Classification of files is based on file extension only. See option
3754 @code{org-file-apps}. If you want to override the default application and
3755 visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
3756 opening in Emacs, use a @kbd{C-u C-u} prefix.@*
3757 If the cursor is on a headline, but not on a link, offer all links in the
3758 headline and entry text. If you want to setup the frame configuration for
3759 following links, customize @code{org-link-frame-setup}.
3762 @vindex org-return-follows-link
3763 When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
3770 On links, @kbd{mouse-1} and @kbd{mouse-2} will open the link just as @kbd{C-c
3775 @vindex org-display-internal-link-with-indirect-buffer
3776 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
3777 internal links to be displayed in another window@footnote{See the
3778 option @code{org-display-internal-link-with-indirect-buffer}}.
3780 @orgcmd{C-c C-x C-v,org-toggle-inline-images}
3781 @cindex inlining images
3782 @cindex images, inlining
3783 @vindex org-startup-with-inline-images
3784 @cindex @code{inlineimages}, STARTUP keyword
3785 @cindex @code{noinlineimages}, STARTUP keyword
3786 Toggle the inline display of linked images. Normally this will only inline
3787 images that have no description part in the link, i.e., images that will also
3788 be inlined during export. When called with a prefix argument, also display
3789 images that do have a link description. You can ask for inline images to be
3790 displayed at startup by configuring the variable
3791 @code{org-startup-with-inline-images}@footnote{with corresponding
3792 @code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
3793 @orgcmd{C-c %,org-mark-ring-push}
3795 Push the current position onto the mark ring, to be able to return
3796 easily. Commands following an internal link do this automatically.
3798 @orgcmd{C-c &,org-mark-ring-goto}
3799 @cindex links, returning to
3800 Jump back to a recorded position. A position is recorded by the
3801 commands following internal links, and by @kbd{C-c %}. Using this
3802 command several times in direct succession moves through a ring of
3803 previously recorded positions.
3805 @orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
3806 @cindex links, finding next/previous
3807 Move forward/backward to the next link in the buffer. At the limit of
3808 the buffer, the search fails once, and then wraps around. The key
3809 bindings for this are really too long; you might want to bind this also
3810 to @kbd{C-n} and @kbd{C-p}
3812 (add-hook 'org-load-hook
3814 (define-key org-mode-map "\C-n" 'org-next-link)
3815 (define-key org-mode-map "\C-p" 'org-previous-link)))
3819 @node Using links outside Org
3820 @section Using links outside Org
3822 You can insert and follow links that have Org syntax not only in
3823 Org, but in any Emacs buffer. For this, you should create two
3824 global commands, like this (please select suitable global keys
3828 (global-set-key "\C-c L" 'org-insert-link-global)
3829 (global-set-key "\C-c o" 'org-open-at-point-global)
3832 @node Link abbreviations
3833 @section Link abbreviations
3834 @cindex link abbreviations
3835 @cindex abbreviation, links
3837 Long URLs can be cumbersome to type, and often many similar links are
3838 needed in a document. For this you can use link abbreviations. An
3839 abbreviated link looks like this
3842 [[linkword:tag][description]]
3846 @vindex org-link-abbrev-alist
3847 where the tag is optional.
3848 The @i{linkword} must be a word, starting with a letter, followed by
3849 letters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolved
3850 according to the information in the variable @code{org-link-abbrev-alist}
3851 that relates the linkwords to replacement text. Here is an example:
3855 (setq org-link-abbrev-alist
3856 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
3857 ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
3858 ("google" . "http://www.google.com/search?q=")
3859 ("gmap" . "http://maps.google.com/maps?q=%s")
3860 ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
3861 ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
3865 If the replacement text contains the string @samp{%s}, it will be
3866 replaced with the tag. Using @samp{%h} instead of @samp{%s} will
3867 url-encode the tag (see the example above, where we need to encode
3868 the URL parameter.) Using @samp{%(my-function)} will pass the tag
3869 to a custom function, and replace it by the resulting string.
3871 If the replacement text doesn't contain any specifier, the tag will simply be
3872 appended in order to create the link.
3874 Instead of a string, you may also specify a function that will be
3875 called with the tag as the only argument to create the link.
3877 With the above setting, you could link to a specific bug with
3878 @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
3879 @code{[[google:OrgMode]]}, show the map location of the Free Software
3880 Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
3881 @code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
3882 what the Org author is doing besides Emacs hacking with
3883 @code{[[ads:Dominik,C]]}.
3885 If you need special abbreviations just for a single Org buffer, you
3886 can define them in the file with
3890 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
3891 #+LINK: google http://www.google.com/search?q=%s
3895 In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
3896 complete link abbreviations. You may also define a function that implements
3897 special (e.g., completion) support for inserting such a link with @kbd{C-c
3898 C-l}. Such a function should not accept any arguments, and return the full
3899 link with prefix. You can add a completion function to a link like this:
3902 (org-link-set-parameters ``type'' :complete #'some-function)
3906 @node Search options
3907 @section Search options in file links
3908 @cindex search option in file links
3909 @cindex file links, searching
3911 File links can contain additional information to make Emacs jump to a
3912 particular location in the file when following a link. This can be a
3913 line number or a search option after a double@footnote{For backward
3914 compatibility, line numbers can also follow a single colon.} colon. For
3915 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
3916 links}) to a file, it encodes the words in the current line as a search
3917 string that can be used to find this line back later when following the
3918 link with @kbd{C-c C-o}.
3920 Here is the syntax of the different ways to attach a search to a file
3921 link, together with an explanation:
3924 [[file:~/code/main.c::255]]
3925 [[file:~/xx.org::My Target]]
3926 [[file:~/xx.org::*My Target]]
3927 [[file:~/xx.org::#my-custom-id]]
3928 [[file:~/xx.org::/regexp/]]
3935 Search for a link target @samp{<<My Target>>}, or do a text search for
3936 @samp{my target}, similar to the search in internal links, see
3937 @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
3938 link will become an HTML reference to the corresponding named anchor in
3941 In an Org file, restrict search to headlines.
3943 Link to a heading with a @code{CUSTOM_ID} property
3945 Do a regular expression search for @code{regexp}. This uses the Emacs
3946 command @code{occur} to list all matches in a separate window. If the
3947 target file is in Org mode, @code{org-occur} is used to create a
3948 sparse tree with the matches.
3949 @c If the target file is a directory,
3950 @c @code{grep} will be used to search all files in the directory.
3953 As a degenerate case, a file link with an empty file name can be used
3954 to search the current file. For example, @code{[[file:::find me]]} does
3955 a search for @samp{find me} in the current file, just as
3956 @samp{[[find me]]} would.
3958 @node Custom searches
3959 @section Custom Searches
3960 @cindex custom search strings
3961 @cindex search strings, custom
3963 The default mechanism for creating search strings and for doing the
3964 actual search related to a file link may not work correctly in all
3965 cases. For example, Bib@TeX{} database files have many entries like
3966 @samp{year="1993"} which would not result in good search strings,
3967 because the only unique identification for a Bib@TeX{} entry is the
3970 @vindex org-create-file-search-functions
3971 @vindex org-execute-file-search-functions
3972 If you come across such a problem, you can write custom functions to set
3973 the right search string for a particular file type, and to do the search
3974 for the string in the file. Using @code{add-hook}, these functions need
3975 to be added to the hook variables
3976 @code{org-create-file-search-functions} and
3977 @code{org-execute-file-search-functions}. See the docstring for these
3978 variables for more information. Org actually uses this mechanism
3979 for Bib@TeX{} database files, and you can use the corresponding code as
3980 an implementation example. See the file @file{org-bibtex.el}.
3986 Org mode does not maintain TODO lists as separate documents@footnote{Of
3987 course, you can make a document that contains only long lists of TODO items,
3988 but this is not required.}. Instead, TODO items are an integral part of the
3989 notes file, because TODO items usually come up while taking notes! With Org
3990 mode, simply mark any entry in a tree as being a TODO item. In this way,
3991 information is not duplicated, and the entire context from which the TODO
3992 item emerged is always present.
3994 Of course, this technique for managing TODO items scatters them
3995 throughout your notes file. Org mode compensates for this by providing
3996 methods to give you an overview of all the things that you have to do.
3999 * TODO basics:: Marking and displaying TODO entries
4000 * TODO extensions:: Workflow and assignments
4001 * Progress logging:: Dates and notes for progress
4002 * Priorities:: Some things are more important than others
4003 * Breaking down tasks:: Splitting a task into manageable pieces
4004 * Checkboxes:: Tick-off lists
4008 @section Basic TODO functionality
4010 Any headline becomes a TODO item when it starts with the word
4011 @samp{TODO}, for example:
4014 *** TODO Write letter to Sam Fortune
4018 The most important commands to work with TODO entries are:
4021 @orgcmd{C-c C-t,org-todo}
4022 @cindex cycling, of TODO states
4023 @vindex org-use-fast-todo-selection
4025 Rotate the TODO state of the current item among
4028 ,-> (unmarked) -> TODO -> DONE --.
4029 '--------------------------------'
4032 If TODO keywords have fast access keys (see @ref{Fast access to TODO
4033 states}), you will be prompted for a TODO keyword through the fast selection
4034 interface; this is the default behavior when
4035 @code{org-use-fast-todo-selection} is non-@code{nil}.
4037 The same rotation can also be done ``remotely'' from agenda buffers with the
4038 @kbd{t} command key (@pxref{Agenda commands}).
4040 @orgkey{C-u C-c C-t}
4041 When TODO keywords have no selection keys, select a specific keyword using
4042 completion; otherwise force cycling through TODO states with no prompt. When
4043 @code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
4044 selection interface.
4046 @kindex S-@key{right}
4047 @kindex S-@key{left}
4048 @item S-@key{right} @ @r{/} @ S-@key{left}
4049 @vindex org-treat-S-cursor-todo-selection-as-state-change
4050 Select the following/preceding TODO state, similar to cycling. Useful
4051 mostly if more than two TODO states are possible (@pxref{TODO
4052 extensions}). See also @ref{Conflicts}, for a discussion of the interaction
4053 with @code{shift-selection-mode}. See also the variable
4054 @code{org-treat-S-cursor-todo-selection-as-state-change}.
4055 @orgcmd{C-c / t,org-show-todo-tree}
4056 @cindex sparse tree, for TODO
4057 @vindex org-todo-keywords
4058 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
4059 entire buffer, but shows all TODO items (with not-DONE state) and the
4060 headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
4061 / T}), search for a specific TODO@. You will be prompted for the keyword,
4062 and you can also give a list of keywords like @code{KWD1|KWD2|...} to list
4063 entries that match any one of these keywords. With a numeric prefix argument
4064 N, show the tree for the Nth keyword in the option @code{org-todo-keywords}.
4065 With two prefix arguments, find all TODO states, both un-done and done.
4066 @orgcmd{C-c a t,org-todo-list}
4067 Show the global TODO list. Collects the TODO items (with not-DONE states)
4068 from all agenda files (@pxref{Agenda views}) into a single buffer. The new
4069 buffer will be in @code{agenda-mode}, which provides commands to examine and
4070 manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
4071 @xref{Global TODO list}, for more information.
4072 @orgcmd{S-M-@key{RET},org-insert-todo-heading}
4073 Insert a new TODO entry below the current one.
4077 @vindex org-todo-state-tags-triggers
4078 Changing a TODO state can also trigger tag changes. See the docstring of the
4079 option @code{org-todo-state-tags-triggers} for details.
4081 @node TODO extensions
4082 @section Extended use of TODO keywords
4083 @cindex extended TODO keywords
4085 @vindex org-todo-keywords
4086 By default, marked TODO entries have one of only two states: TODO and
4087 DONE@. Org mode allows you to classify TODO items in more complex ways
4088 with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
4089 special setup, the TODO keyword system can work differently in different
4092 Note that @i{tags} are another way to classify headlines in general and
4093 TODO items in particular (@pxref{Tags}).
4096 * Workflow states:: From TODO to DONE in steps
4097 * TODO types:: I do this, Fred does the rest
4098 * Multiple sets in one file:: Mixing it all, and still finding your way
4099 * Fast access to TODO states:: Single letter selection of a state
4100 * Per-file keywords:: Different files, different requirements
4101 * Faces for TODO keywords:: Highlighting states
4102 * TODO dependencies:: When one task needs to wait for others
4105 @node Workflow states
4106 @subsection TODO keywords as workflow states
4107 @cindex TODO workflow
4108 @cindex workflow states as TODO keywords
4110 You can use TODO keywords to indicate different @emph{sequential} states
4111 in the process of working on an item, for example@footnote{Changing
4112 this variable only becomes effective after restarting Org mode in a
4116 (setq org-todo-keywords
4117 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
4120 The vertical bar separates the TODO keywords (states that @emph{need
4121 action}) from the DONE states (which need @emph{no further action}). If
4122 you don't provide the separator bar, the last state is used as the DONE
4124 @cindex completion, of TODO keywords
4125 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
4126 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@. You may
4127 also use a numeric prefix argument to quickly select a specific state. For
4128 example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
4129 Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
4130 define many keywords, you can use in-buffer completion
4131 (@pxref{Completion}) or even a special one-key selection scheme
4132 (@pxref{Fast access to TODO states}) to insert these words into the
4133 buffer. Changing a TODO state can be logged with a timestamp, see
4134 @ref{Tracking TODO state changes}, for more information.
4137 @subsection TODO keywords as types
4139 @cindex names as TODO keywords
4140 @cindex types as TODO keywords
4142 The second possibility is to use TODO keywords to indicate different
4143 @emph{types} of action items. For example, you might want to indicate
4144 that items are for ``work'' or ``home''. Or, when you work with several
4145 people on a single project, you might want to assign action items
4146 directly to persons, by using their names as TODO keywords. This would
4147 be set up like this:
4150 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
4153 In this case, different keywords do not indicate a sequence, but rather
4154 different types. So the normal work flow would be to assign a task to
4155 a person, and later to mark it DONE@. Org mode supports this style by
4156 adapting the workings of the command @kbd{C-c C-t}@footnote{This is also true
4157 for the @kbd{t} command in the agenda buffers.}. When used several times in
4158 succession, it will still cycle through all names, in order to first select
4159 the right type for a task. But when you return to the item after some time
4160 and execute @kbd{C-c C-t} again, it will switch from any name directly to
4161 DONE@. Use prefix arguments or completion to quickly select a specific name.
4162 You can also review the items of a specific TODO type in a sparse tree by
4163 using a numeric prefix to @kbd{C-c / t}. For example, to see all things Lucy
4164 has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items from all
4165 agenda files into a single buffer, you would use the numeric prefix argument
4166 as well when creating the global TODO list: @kbd{C-3 C-c a t}.
4168 @node Multiple sets in one file
4169 @subsection Multiple keyword sets in one file
4170 @cindex TODO keyword sets
4172 Sometimes you may want to use different sets of TODO keywords in
4173 parallel. For example, you may want to have the basic
4174 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
4175 separate state indicating that an item has been canceled (so it is not
4176 DONE, but also does not require action). Your setup would then look
4180 (setq org-todo-keywords
4181 '((sequence "TODO" "|" "DONE")
4182 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
4183 (sequence "|" "CANCELED")))
4186 The keywords should all be different, this helps Org mode to keep track
4187 of which subsequence should be used for a given entry. In this setup,
4188 @kbd{C-c C-t} only operates within a subsequence, so it switches from
4189 @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
4190 (nothing) to @code{REPORT}. Therefore you need a mechanism to initially
4191 select the correct sequence. Besides the obvious ways like typing a
4192 keyword or using completion, you may also apply the following commands:
4195 @kindex C-S-@key{right}
4196 @kindex C-S-@key{left}
4197 @kindex C-u C-u C-c C-t
4198 @item C-u C-u C-c C-t
4199 @itemx C-S-@key{right}
4200 @itemx C-S-@key{left}
4201 These keys jump from one TODO subset to the next. In the above example,
4202 @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or
4203 @code{DONE} to @code{REPORT}, and any of the words in the second row to
4204 @code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with
4205 @code{shift-selection-mode} (@pxref{Conflicts}).
4206 @kindex S-@key{right}
4207 @kindex S-@key{left}
4210 @kbd{S-@key{left}} and @kbd{S-@key{right}} and walk through @emph{all}
4211 keywords from all sets, so for example @kbd{S-@key{right}} would switch
4212 from @code{DONE} to @code{REPORT} in the example above. See also
4213 @ref{Conflicts}, for a discussion of the interaction with
4214 @code{shift-selection-mode}.
4217 @node Fast access to TODO states
4218 @subsection Fast access to TODO states
4220 If you would like to quickly change an entry to an arbitrary TODO state
4221 instead of cycling through the states, you can set up keys for single-letter
4222 access to the states. This is done by adding the selection character after
4223 each keyword, in parentheses@footnote{All characters are allowed except
4224 @code{@@^!}, which have a special meaning here.}. For example:
4227 (setq org-todo-keywords
4228 '((sequence "TODO(t)" "|" "DONE(d)")
4229 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
4230 (sequence "|" "CANCELED(c)")))
4233 @vindex org-fast-tag-selection-include-todo
4234 If you then press @kbd{C-c C-t} followed by the selection key, the entry
4235 will be switched to this state. @kbd{SPC} can be used to remove any TODO
4236 keyword from an entry.@footnote{Check also the option
4237 @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
4238 state through the tags interface (@pxref{Setting tags}), in case you like to
4239 mingle the two concepts. Note that this means you need to come up with
4240 unique keys across both sets of keywords.}
4242 @node Per-file keywords
4243 @subsection Setting up keywords for individual files
4244 @cindex keyword options
4245 @cindex per-file keywords
4250 It can be very useful to use different aspects of the TODO mechanism in
4251 different files. For file-local settings, you need to add special lines to
4252 the file which set the keywords and interpretation for that file only. For
4253 example, to set one of the two examples discussed above, you need one of the
4254 following lines anywhere in the file:
4257 #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
4259 @noindent (you may also write @code{#+SEQ_TODO} to be explicit about the
4260 interpretation, but it means the same as @code{#+TODO}), or
4262 #+TYP_TODO: Fred Sara Lucy Mike | DONE
4265 A setup for using several sets in parallel would be:
4269 #+TODO: REPORT BUG KNOWNCAUSE | FIXED
4273 @cindex completion, of option keywords
4275 @noindent To make sure you are using the correct keyword, type
4276 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
4278 @cindex DONE, final TODO keyword
4279 Remember that the keywords after the vertical bar (or the last keyword
4280 if no bar is there) must always mean that the item is DONE (although you
4281 may use a different word). After changing one of these lines, use
4282 @kbd{C-c C-c} with the cursor still in the line to make the changes
4283 known to Org mode@footnote{Org mode parses these lines only when
4284 Org mode is activated after visiting a file. @kbd{C-c C-c} with the
4285 cursor in a line starting with @samp{#+} is simply restarting Org mode
4286 for the current buffer.}.
4288 @node Faces for TODO keywords
4289 @subsection Faces for TODO keywords
4290 @cindex faces, for TODO keywords
4292 @vindex org-todo @r{(face)}
4293 @vindex org-done @r{(face)}
4294 @vindex org-todo-keyword-faces
4295 Org mode highlights TODO keywords with special faces: @code{org-todo}
4296 for keywords indicating that an item still has to be acted upon, and
4297 @code{org-done} for keywords indicating that an item is finished. If
4298 you are using more than 2 different states, you might want to use
4299 special faces for some of them. This can be done using the option
4300 @code{org-todo-keyword-faces}. For example:
4304 (setq org-todo-keyword-faces
4305 '(("TODO" . org-warning) ("STARTED" . "yellow")
4306 ("CANCELED" . (:foreground "blue" :weight bold))))
4310 While using a list with face properties as shown for CANCELED @emph{should}
4311 work, this does not always seem to be the case. If necessary, define a
4312 special face and use that. A string is interpreted as a color. The option
4313 @code{org-faces-easy-properties} determines if that color is interpreted as a
4314 foreground or a background color.
4316 @node TODO dependencies
4317 @subsection TODO dependencies
4318 @cindex TODO dependencies
4319 @cindex dependencies, of TODO states
4320 @cindex TODO dependencies, NOBLOCKING
4322 @vindex org-enforce-todo-dependencies
4323 @cindex property, ORDERED
4324 The structure of Org files (hierarchy and lists) makes it easy to define TODO
4325 dependencies. Usually, a parent TODO task should not be marked DONE until
4326 all subtasks (defined as children tasks) are marked as DONE@. And sometimes
4327 there is a logical sequence to a number of (sub)tasks, so that one task
4328 cannot be acted upon before all siblings above it are done. If you customize
4329 the option @code{org-enforce-todo-dependencies}, Org will block entries
4330 from changing state to DONE while they have children that are not DONE@.
4331 Furthermore, if an entry has a property @code{ORDERED}, each of its children
4332 will be blocked until all earlier siblings are marked DONE@. Here is an
4336 * TODO Blocked until (two) is done
4345 ** TODO b, needs to wait for (a)
4346 ** TODO c, needs to wait for (a) and (b)
4349 You can ensure an entry is never blocked by using the @code{NOBLOCKING}
4353 * This entry is never blocked
4360 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4361 @vindex org-track-ordered-property-with-tag
4362 @cindex property, ORDERED
4363 Toggle the @code{ORDERED} property of the current entry. A property is used
4364 for this behavior because this should be local to the current entry, not
4365 inherited like a tag. However, if you would like to @i{track} the value of
4366 this property with a tag for better visibility, customize the option
4367 @code{org-track-ordered-property-with-tag}.
4368 @orgkey{C-u C-u C-u C-c C-t}
4369 Change TODO state, circumventing any state blocking.
4372 @vindex org-agenda-dim-blocked-tasks
4373 If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries
4374 that cannot be closed because of such dependencies will be shown in a dimmed
4375 font or even made invisible in agenda views (@pxref{Agenda views}).
4377 @cindex checkboxes and TODO dependencies
4378 @vindex org-enforce-todo-dependencies
4379 You can also block changes of TODO states by looking at checkboxes
4380 (@pxref{Checkboxes}). If you set the option
4381 @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
4382 checkboxes will be blocked from switching to DONE.
4384 If you need more complex dependency structures, for example dependencies
4385 between entries in different trees or files, check out the contributed
4386 module @file{org-depend.el}.
4389 @node Progress logging
4390 @section Progress logging
4391 @cindex progress logging
4392 @cindex logging, of progress
4394 Org mode can automatically record a timestamp and possibly a note when
4395 you mark a TODO item as DONE, or even each time you change the state of
4396 a TODO item. This system is highly configurable; settings can be on a
4397 per-keyword basis and can be localized to a file or even a subtree. For
4398 information on how to clock working time for a task, see @ref{Clocking
4402 * Closing items:: When was this entry marked DONE?
4403 * Tracking TODO state changes:: When did the status change?
4404 * Tracking your habits:: How consistent have you been?
4408 @subsection Closing items
4410 The most basic logging is to keep track of @emph{when} a certain TODO
4411 item was finished. This is achieved with@footnote{The corresponding
4412 in-buffer setting is: @code{#+STARTUP: logdone}}
4415 (setq org-log-done 'time)
4418 @vindex org-closed-keep-when-no-todo
4420 Then each time you turn an entry from a TODO (not-done) state into any of the
4421 DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
4422 the headline. If you turn the entry back into a TODO item through further
4423 state cycling, that line will be removed again. If you turn the entry back
4424 to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line
4425 will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
4426 non-@code{nil}. If you want to record a note along with the timestamp,
4427 use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
4431 (setq org-log-done 'note)
4435 You will then be prompted for a note, and that note will be stored below
4436 the entry with a @samp{Closing Note} heading.
4438 @node Tracking TODO state changes
4439 @subsection Tracking TODO state changes
4440 @cindex drawer, for state change recording
4442 @vindex org-log-states-order-reversed
4443 @vindex org-log-into-drawer
4444 @cindex property, LOG_INTO_DRAWER
4445 When TODO keywords are used as workflow states (@pxref{Workflow states}), you
4446 might want to keep track of when a state change occurred and maybe take a
4447 note about this change. You can either record just a timestamp, or a
4448 time-stamped note for a change. These records will be inserted after the
4449 headline as an itemized list, newest first@footnote{See the option
4450 @code{org-log-states-order-reversed}}. When taking a lot of notes, you might
4451 want to get the notes out of the way into a drawer (@pxref{Drawers}).
4452 Customize @code{org-log-into-drawer} to get this behavior---the recommended
4453 drawer for this is called @code{LOGBOOK}@footnote{Note that the
4454 @code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to
4455 show an entry---use @key{C-u SPC} to keep it folded here}. You can also
4456 overrule the setting of this variable for a subtree by setting a
4457 @code{LOG_INTO_DRAWER} property.
4459 Since it is normally too much to record a note for every state, Org mode
4460 expects configuration on a per-keyword basis for this. This is achieved by
4461 adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note
4462 with timestamp) in parentheses after each keyword. For example, with the
4466 (setq org-todo-keywords
4467 '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
4470 To record a timestamp without a note for TODO keywords configured with
4471 @samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
4474 @vindex org-log-done
4475 You not only define global TODO keywords and fast access keys, but also
4476 request that a time is recorded when the entry is set to
4477 DONE@footnote{It is possible that Org mode will record two timestamps
4478 when you are using both @code{org-log-done} and state change logging.
4479 However, it will never prompt for two notes---if you have configured
4480 both, the state change recording note will take precedence and cancel
4481 the @samp{Closing Note}.}, and that a note is recorded when switching to
4482 WAIT or CANCELED@. The setting for WAIT is even more special: the
4483 @samp{!} after the slash means that in addition to the note taken when
4484 entering the state, a timestamp should be recorded when @i{leaving} the
4485 WAIT state, if and only if the @i{target} state does not configure
4486 logging for entering it. So it has no effect when switching from WAIT
4487 to DONE, because DONE is configured to record a timestamp only. But
4488 when switching from WAIT back to TODO, the @samp{/!} in the WAIT
4489 setting now triggers a timestamp even though TODO has no logging
4492 You can use the exact same syntax for setting logging preferences local
4495 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
4498 @cindex property, LOGGING
4499 In order to define logging settings that are local to a subtree or a
4500 single item, define a LOGGING property in this entry. Any non-empty
4501 LOGGING property resets all logging settings to @code{nil}. You may then turn
4502 on logging for this specific tree using STARTUP keywords like
4503 @code{lognotedone} or @code{logrepeat}, as well as adding state specific
4504 settings like @code{TODO(!)}. For example
4507 * TODO Log each state with only a time
4509 :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
4511 * TODO Only log when switching to WAIT, and when repeating
4513 :LOGGING: WAIT(@@) logrepeat
4515 * TODO No logging at all
4521 @node Tracking your habits
4522 @subsection Tracking your habits
4525 Org has the ability to track the consistency of a special category of TODOs,
4526 called ``habits''. A habit has the following properties:
4530 You have enabled the @code{habits} module by customizing @code{org-modules}.
4532 The habit is a TODO item, with a TODO keyword representing an open state.
4534 The property @code{STYLE} is set to the value @code{habit}.
4536 The TODO has a scheduled date, usually with a @code{.+} style repeat
4537 interval. A @code{++} style may be appropriate for habits with time
4538 constraints, e.g., must be done on weekends, or a @code{+} style for an
4539 unusual habit that can have a backlog, e.g., weekly reports.
4541 The TODO may also have minimum and maximum ranges specified by using the
4542 syntax @samp{.+2d/3d}, which says that you want to do the task at least every
4543 three days, but at most every two days.
4545 You must also have state logging for the @code{DONE} state enabled
4546 (@pxref{Tracking TODO state changes}), in order for historical data to be
4547 represented in the consistency graph. If it is not enabled it is not an
4548 error, but the consistency graphs will be largely meaningless.
4551 To give you an idea of what the above rules look like in action, here's an
4552 actual habit with some history:
4556 SCHEDULED: <2009-10-17 Sat .+2d/4d>
4559 :LAST_REPEAT: [2009-10-19 Mon 00:36]
4561 - State "DONE" from "TODO" [2009-10-15 Thu]
4562 - State "DONE" from "TODO" [2009-10-12 Mon]
4563 - State "DONE" from "TODO" [2009-10-10 Sat]
4564 - State "DONE" from "TODO" [2009-10-04 Sun]
4565 - State "DONE" from "TODO" [2009-10-02 Fri]
4566 - State "DONE" from "TODO" [2009-09-29 Tue]
4567 - State "DONE" from "TODO" [2009-09-25 Fri]
4568 - State "DONE" from "TODO" [2009-09-19 Sat]
4569 - State "DONE" from "TODO" [2009-09-16 Wed]
4570 - State "DONE" from "TODO" [2009-09-12 Sat]
4573 What this habit says is: I want to shave at most every 2 days (given by the
4574 @code{SCHEDULED} date and repeat interval) and at least every 4 days. If
4575 today is the 15th, then the habit first appears in the agenda on Oct 17,
4576 after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
4577 after four days have elapsed.
4579 What's really useful about habits is that they are displayed along with a
4580 consistency graph, to show how consistent you've been at getting that task
4581 done in the past. This graph shows every day that the task was done over the
4582 past three weeks, with colors for each day. The colors used are:
4586 If the task wasn't to be done yet on that day.
4588 If the task could have been done on that day.
4590 If the task was going to be overdue the next day.
4592 If the task was overdue on that day.
4595 In addition to coloring each day, the day is also marked with an asterisk if
4596 the task was actually done that day, and an exclamation mark to show where
4597 the current day falls in the graph.
4599 There are several configuration variables that can be used to change the way
4600 habits are displayed in the agenda.
4603 @item org-habit-graph-column
4604 The buffer column at which the consistency graph should be drawn. This will
4605 overwrite any text in that column, so it is a good idea to keep your habits'
4606 titles brief and to the point.
4607 @item org-habit-preceding-days
4608 The amount of history, in days before today, to appear in consistency graphs.
4609 @item org-habit-following-days
4610 The number of days after today that will appear in consistency graphs.
4611 @item org-habit-show-habits-only-for-today
4612 If non-@code{nil}, only show habits in today's agenda view. This is set to true by
4616 Lastly, pressing @kbd{K} in the agenda buffer will cause habits to
4617 temporarily be disabled and they won't appear at all. Press @kbd{K} again to
4618 bring them back. They are also subject to tag filtering, if you have habits
4619 which should only be done in certain contexts, for example.
4625 If you use Org mode extensively, you may end up with enough TODO items that
4626 it starts to make sense to prioritize them. Prioritizing can be done by
4627 placing a @emph{priority cookie} into the headline of a TODO item, like this
4630 *** TODO [#A] Write letter to Sam Fortune
4634 @vindex org-priority-faces
4635 By default, Org mode supports three priorities: @samp{A}, @samp{B}, and
4636 @samp{C}. @samp{A} is the highest priority. An entry without a cookie is
4637 treated just like priority @samp{B}. Priorities make a difference only for
4638 sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
4639 have no inherent meaning to Org mode. The cookies can be highlighted with
4640 special faces by customizing @code{org-priority-faces}.
4642 Priorities can be attached to any outline node; they do not need to be TODO
4648 @findex org-priority
4649 Set the priority of the current headline (@command{org-priority}). The
4650 command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
4651 When you press @key{SPC} instead, the priority cookie is removed from the
4652 headline. The priorities can also be changed ``remotely'' from the agenda
4653 buffer with the @kbd{,} command (@pxref{Agenda commands}).
4655 @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
4656 @vindex org-priority-start-cycle-with-default
4657 Increase/decrease priority of current headline@footnote{See also the option
4658 @code{org-priority-start-cycle-with-default}.}. Note that these keys are
4659 also used to modify timestamps (@pxref{Creating timestamps}). See also
4660 @ref{Conflicts}, for a discussion of the interaction with
4661 @code{shift-selection-mode}.
4664 @vindex org-highest-priority
4665 @vindex org-lowest-priority
4666 @vindex org-default-priority
4667 You can change the range of allowed priorities by setting the options
4668 @code{org-highest-priority}, @code{org-lowest-priority}, and
4669 @code{org-default-priority}. For an individual buffer, you may set
4670 these values (highest, lowest, default) like this (please make sure that
4671 the highest priority is earlier in the alphabet than the lowest
4674 @cindex #+PRIORITIES
4679 @node Breaking down tasks
4680 @section Breaking tasks down into subtasks
4681 @cindex tasks, breaking down
4682 @cindex statistics, for TODO items
4684 @vindex org-agenda-todo-list-sublevels
4685 It is often advisable to break down large tasks into smaller, manageable
4686 subtasks. You can do this by creating an outline tree below a TODO item,
4687 with detailed subtasks on the tree@footnote{To keep subtasks out of the
4688 global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep
4689 the overview over the fraction of subtasks that are already completed, insert
4690 either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will
4691 be updated each time the TODO status of a child changes, or when pressing
4692 @kbd{C-c C-c} on the cookie. For example:
4695 * Organize Party [33%]
4696 ** TODO Call people [1/2]
4700 ** DONE Talk to neighbor
4703 @cindex property, COOKIE_DATA
4704 If a heading has both checkboxes and TODO children below it, the meaning of
4705 the statistics cookie become ambiguous. Set the property
4706 @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
4709 @vindex org-hierarchical-todo-statistics
4710 If you would like to have the statistics cookie count any TODO entries in the
4711 subtree (not just direct children), configure
4712 @code{org-hierarchical-todo-statistics}. To do this for a single subtree,
4713 include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
4717 * Parent capturing statistics [2/20]
4719 :COOKIE_DATA: todo recursive
4723 If you would like a TODO entry to automatically change to DONE
4724 when all children are done, you can use the following setup:
4727 (defun org-summary-todo (n-done n-not-done)
4728 "Switch entry to DONE when all subentries are done, to TODO otherwise."
4729 (let (org-log-done org-log-states) ; turn off logging
4730 (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
4732 (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
4736 Another possibility is the use of checkboxes to identify (a hierarchy of) a
4737 large number of subtasks (@pxref{Checkboxes}).
4744 @vindex org-list-automatic-rules
4745 Every item in a plain list@footnote{With the exception of description
4746 lists. But you can allow it by modifying @code{org-list-automatic-rules}
4747 accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
4748 it with the string @samp{[ ]}. This feature is similar to TODO items
4749 (@pxref{TODO items}), but is more lightweight. Checkboxes are not included
4750 in the global TODO list, so they are often great to split a task into a
4751 number of simple steps. Or you can use them in a shopping list. To toggle a
4752 checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
4753 @file{org-mouse.el}).
4755 Here is an example of a checkbox list.
4758 * TODO Organize party [2/4]
4759 - [-] call people [1/3]
4764 - [ ] think about what music to play
4765 - [X] talk to the neighbors
4768 Checkboxes work hierarchically, so if a checkbox item has children that
4769 are checkboxes, toggling one of the children checkboxes will make the
4770 parent checkbox reflect if none, some, or all of the children are
4773 @cindex statistics, for checkboxes
4774 @cindex checkbox statistics
4775 @cindex property, COOKIE_DATA
4776 @vindex org-checkbox-hierarchical-statistics
4777 The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
4778 indicating how many checkboxes present in this entry have been checked off,
4779 and the total number of checkboxes present. This can give you an idea on how
4780 many checkboxes remain, even without opening a folded entry. The cookies can
4781 be placed into a headline or into (the first line of) a plain list item.
4782 Each cookie covers checkboxes of direct children structurally below the
4783 headline/item on which the cookie appears@footnote{Set the option
4784 @code{org-checkbox-hierarchical-statistics} if you want such cookies to
4785 count all checkboxes below the cookie, not just those belonging to direct
4786 children.}. You have to insert the cookie yourself by typing either
4787 @samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}
4788 result, as in the examples above. With @samp{[%]} you get information about
4789 the percentage of checkboxes checked (in the above example, this would be
4790 @samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie can
4791 count either checkboxes below the heading or TODO states of children, and it
4792 will display whatever was changed last. Set the property @code{COOKIE_DATA}
4793 to either @samp{checkbox} or @samp{todo} to resolve this issue.
4795 @cindex blocking, of checkboxes
4796 @cindex checkbox blocking
4797 @cindex property, ORDERED
4798 If the current outline node has an @code{ORDERED} property, checkboxes must
4799 be checked off in sequence, and an error will be thrown if you try to check
4800 off a box while there are unchecked boxes above it.
4802 @noindent The following commands work with checkboxes:
4805 @orgcmd{C-c C-c,org-toggle-checkbox}
4806 Toggle checkbox status or (with prefix arg) checkbox presence at point. With
4807 a single prefix argument, add an empty checkbox or remove the current
4808 one@footnote{@kbd{C-u C-c C-c} before the @emph{first} bullet in a list with
4809 no checkbox will add checkboxes to the rest of the list.}. With a double
4810 prefix argument, set it to @samp{[-]}, which is considered to be an
4812 @orgcmd{C-c C-x C-b,org-toggle-checkbox}
4813 Toggle checkbox status or (with prefix arg) checkbox presence at point. With
4814 double prefix argument, set it to @samp{[-]}, which is considered to be an
4818 If there is an active region, toggle the first checkbox in the region
4819 and set all remaining boxes to the same status as the first. With a prefix
4820 arg, add or remove the checkbox for all items in the region.
4822 If the cursor is in a headline, toggle the state of the first checkbox in the
4823 region between this headline and the next---so @emph{not} the entire
4824 subtree---and propagate this new state to all other checkboxes in the same
4827 If there is no active region, just toggle the checkbox at point.
4829 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
4830 Insert a new item with a checkbox. This works only if the cursor is already
4831 in a plain list item (@pxref{Plain lists}).
4832 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4833 @vindex org-track-ordered-property-with-tag
4834 @cindex property, ORDERED
4835 Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
4836 be checked off in sequence. A property is used for this behavior because
4837 this should be local to the current entry, not inherited like a tag.
4838 However, if you would like to @i{track} the value of this property with a tag
4839 for better visibility, customize @code{org-track-ordered-property-with-tag}.
4840 @orgcmd{C-c #,org-update-statistics-cookies}
4841 Update the statistics cookie in the current outline entry. When called with
4842 a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are
4843 updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
4844 new ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update when
4845 changing TODO states. If you delete boxes/entries or add/change them by
4846 hand, use this command to get things back into sync.
4852 @cindex headline tagging
4853 @cindex matching, tags
4854 @cindex sparse tree, tag based
4856 An excellent way to implement labels and contexts for cross-correlating
4857 information is to assign @i{tags} to headlines. Org mode has extensive
4860 @vindex org-tag-faces
4861 Every headline can contain a list of tags; they occur at the end of the
4862 headline. Tags are normal words containing letters, numbers, @samp{_}, and
4863 @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
4864 @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
4865 Tags will by default be in bold face with the same color as the headline.
4866 You may specify special faces for specific tags using the option
4867 @code{org-tag-faces}, in much the same way as you can for TODO keywords
4868 (@pxref{Faces for TODO keywords}).
4871 * Tag inheritance:: Tags use the tree structure of the outline
4872 * Setting tags:: How to assign tags to a headline
4873 * Tag hierarchy:: Create a hierarchy of tags
4874 * Tag searches:: Searching for combinations of tags
4877 @node Tag inheritance
4878 @section Tag inheritance
4879 @cindex tag inheritance
4880 @cindex inheritance, of tags
4881 @cindex sublevels, inclusion into tags match
4883 @i{Tags} make use of the hierarchical structure of outline trees. If a
4884 heading has a certain tag, all subheadings will inherit the tag as
4885 well. For example, in the list
4888 * Meeting with the French group :work:
4889 ** Summary by Frank :boss:notes:
4890 *** TODO Prepare slides for him :action:
4894 the final heading will have the tags @samp{:work:}, @samp{:boss:},
4895 @samp{:notes:}, and @samp{:action:} even though the final heading is not
4896 explicitly marked with all those tags. You can also set tags that all
4897 entries in a file should inherit just as if these tags were defined in
4898 a hypothetical level zero that surrounds the entire file. Use a line like
4899 this@footnote{As with all these in-buffer settings, pressing @kbd{C-c C-c}
4900 activates any changes in the line.}:
4904 #+FILETAGS: :Peter:Boss:Secret:
4908 @vindex org-use-tag-inheritance
4909 @vindex org-tags-exclude-from-inheritance
4910 To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
4911 To turn it off entirely, use @code{org-use-tag-inheritance}.
4913 @vindex org-tags-match-list-sublevels
4914 When a headline matches during a tags search while tag inheritance is turned
4915 on, all the sublevels in the same tree will (for a simple match form) match
4916 as well@footnote{This is only true if the search does not involve more
4917 complex tests including properties (@pxref{Property searches}).}. The list
4918 of matches may then become very long. If you only want to see the first tags
4919 match in a subtree, configure @code{org-tags-match-list-sublevels} (not
4922 @vindex org-agenda-use-tag-inheritance
4923 Tag inheritance is relevant when the agenda search tries to match a tag,
4924 either in the @code{tags} or @code{tags-todo} agenda types. In other agenda
4925 types, @code{org-use-tag-inheritance} has no effect. Still, you may want to
4926 have your tags correctly set in the agenda, so that tag filtering works fine,
4927 with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control
4928 this: the default value includes all agenda types, but setting this to @code{nil}
4929 can really speed up agenda generation.
4932 @section Setting tags
4933 @cindex setting tags
4934 @cindex tags, setting
4937 Tags can simply be typed into the buffer at the end of a headline.
4938 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
4939 also a special command for inserting tags:
4942 @orgcmd{C-c C-q,org-set-tags-command}
4943 @cindex completion, of tags
4944 @vindex org-tags-column
4945 Enter new tags for the current headline. Org mode will either offer
4946 completion or a special single-key interface for setting tags, see
4947 below. After pressing @key{RET}, the tags will be inserted and aligned
4948 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
4949 tags in the current buffer will be aligned to that column, just to make
4950 things look nice. TAGS are automatically realigned after promotion,
4951 demotion, and TODO state changes (@pxref{TODO basics}).
4953 @orgcmd{C-c C-c,org-set-tags-command}
4954 When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
4957 @vindex org-tag-alist
4958 Org supports tag insertion based on a @emph{list of tags}. By
4959 default this list is constructed dynamically, containing all tags
4960 currently used in the buffer. You may also globally specify a hard list
4961 of tags with the variable @code{org-tag-alist}. Finally you can set
4962 the default tags for a given file with lines like
4966 #+TAGS: @@work @@home @@tennisclub
4967 #+TAGS: laptop car pc sailboat
4970 If you have globally defined your preferred set of tags using the
4971 variable @code{org-tag-alist}, but would like to use a dynamic tag list
4972 in a specific file, add an empty TAGS option line to that file:
4978 @vindex org-tag-persistent-alist
4979 If you have a preferred set of tags that you would like to use in every file,
4980 in addition to those defined on a per-file basis by TAGS option lines, then
4981 you may specify a list of tags with the variable
4982 @code{org-tag-persistent-alist}. You may turn this off on a per-file basis
4983 by adding a STARTUP option line to that file:
4989 By default Org mode uses the standard minibuffer completion facilities for
4990 entering tags. However, it also implements another, quicker, tag selection
4991 method called @emph{fast tag selection}. This allows you to select and
4992 deselect tags with just a single key press. For this to work well you should
4993 assign unique, case-sensitive, letters to most of your commonly used tags.
4994 You can do this globally by configuring the variable @code{org-tag-alist} in
4995 your Emacs init file. For example, you may find the need to tag many items
4996 in different files with @samp{:@@home:}. In this case you can set something
5000 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
5003 @noindent If the tag is only relevant to the file you are working on, then you
5004 can instead set the TAGS option line as:
5007 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
5010 @noindent The tags interface will show the available tags in a splash
5011 window. If you want to start a new line after a specific tag, insert
5012 @samp{\n} into the tag list
5015 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p)
5018 @noindent or write them in two lines:
5021 #+TAGS: @@work(w) @@home(h) @@tennisclub(t)
5022 #+TAGS: laptop(l) pc(p)
5026 You can also group together tags that are mutually exclusive by using
5030 #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)
5033 @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
5034 and @samp{@@tennisclub} should be selected. Multiple such groups are allowed.
5036 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
5037 these lines to activate any changes.
5040 To set these mutually exclusive groups in the variable @code{org-tag-alist},
5041 you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
5042 of the braces. Similarly, you can use @code{:newline} to indicate a line
5043 break. The previous example would be set globally by the following
5047 (setq org-tag-alist '((:startgroup . nil)
5048 ("@@work" . ?w) ("@@home" . ?h)
5049 ("@@tennisclub" . ?t)
5051 ("laptop" . ?l) ("pc" . ?p)))
5054 If at least one tag has a selection key then pressing @kbd{C-c C-c} will
5055 automatically present you with a special interface, listing inherited tags,
5056 the tags of the current headline, and a list of all valid tags with
5057 corresponding keys@footnote{Keys will automatically be assigned to tags which
5058 have no configured keys.}.
5060 Pressing keys assigned to tags will add or remove them from the list of tags
5061 in the current line. Selecting a tag in a group of mutually exclusive tags
5062 will turn off any other tags from that group.
5064 In this interface, you can also use the following special keys:
5069 Enter a tag in the minibuffer, even if the tag is not in the predefined
5070 list. You will be able to complete on all tags present in the buffer.
5071 You can also add several tags: just separate them with a comma.
5075 Clear all tags for this line.
5079 Accept the modified set.
5082 Abort without installing changes.
5085 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
5088 Turn off groups of mutually exclusive tags. Use this to (as an
5089 exception) assign several tags from such a group.
5092 Toggle auto-exit after the next change (see below).
5093 If you are using expert mode, the first @kbd{C-c} will display the
5098 This method lets you assign tags to a headline with very few keys. With
5099 the above setup, you could clear the current tags and set @samp{@@home},
5100 @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
5101 C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to
5102 @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
5103 alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
5104 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
5105 @key{RET} @key{RET}}.
5107 @vindex org-fast-tag-selection-single-key
5108 If you find that most of the time you need only a single key press to
5109 modify your list of tags, set @code{org-fast-tag-selection-single-key}.
5110 Then you no longer have to press @key{RET} to exit fast tag selection---it
5111 will immediately exit after the first change. If you then occasionally
5112 need more keys, press @kbd{C-c} to turn off auto-exit for the current tag
5113 selection process (in effect: start selection with @kbd{C-c C-c C-c}
5114 instead of @kbd{C-c C-c}). If you set the variable to the value
5115 @code{expert}, the special window is not even shown for single-key tag
5116 selection, it comes up only when you press an extra @kbd{C-c}.
5119 @section Tag hierarchy
5122 @cindex tags, groups
5123 @cindex tag hierarchy
5124 Tags can be defined in hierarchies. A tag can be defined as a @emph{group
5125 tag} for a set of other tags. The group tag can be seen as the ``broader
5126 term'' for its set of tags. Defining multiple @emph{group tags} and nesting
5127 them creates a tag hierarchy.
5129 One use-case is to create a taxonomy of terms (tags) that can be used to
5130 classify nodes in a document or set of documents.
5132 When you search for a group tag, it will return matches for all members in
5133 the group and its subgroups. In an agenda view, filtering by a group tag
5134 will display or hide headlines tagged with at least one of the members of the
5135 group or any of its subgroups. This makes tag searches and filters even more
5138 You can set group tags by using brackets and inserting a colon between the
5139 group tag and its related tags---beware that all whitespaces are mandatory so
5140 that Org can parse this line correctly:
5143 #+TAGS: [ GTD : Control Persp ]
5146 In this example, @samp{GTD} is the @emph{group tag} and it is related to two
5147 other tags: @samp{Control}, @samp{Persp}. Defining @samp{Control} and
5148 @samp{Persp} as group tags creates an hierarchy of tags:
5151 #+TAGS: [ Control : Context Task ]
5152 #+TAGS: [ Persp : Vision Goal AOF Project ]
5155 That can conceptually be seen as a hierarchy of tags:
5169 You can use the @code{:startgrouptag}, @code{:grouptags} and
5170 @code{:endgrouptag} keyword directly when setting @code{org-tag-alist}
5174 (setq org-tag-alist '((:startgrouptag)
5188 The tags in a group can be mutually exclusive if using the same group syntax
5189 as is used for grouping mutually exclusive tags together; using curly
5193 #+TAGS: @{ Context : @@Home @@Work @@Call @}
5196 When setting @code{org-tag-alist} you can use @code{:startgroup} &
5197 @code{:endgroup} instead of @code{:startgrouptag} & @code{:endgrouptag} to
5198 make the tags mutually exclusive.
5200 Furthermore, the members of a @emph{group tag} can also be regular
5201 expressions, creating the possibility of a more dynamic and rule-based
5202 tag structure. The regular expressions in the group must be specified
5203 within @{ @}. Here is an expanded example:
5206 #+TAGS: [ Vision : @{V@@@.+@} ]
5207 #+TAGS: [ Goal : @{G@@@.+@} ]
5208 #+TAGS: [ AOF : @{AOF@@@.+@} ]
5209 #+TAGS: [ Project : @{P@@@.+@} ]
5212 Searching for the tag @samp{Project} will now list all tags also including
5213 regular expression matches for @samp{P@@@.+}, and similarly for tag searches on
5214 @samp{Vision}, @samp{Goal} and @samp{AOF}. For example, this would work well
5215 for a project tagged with a common project-identifier, e.g. @samp{P@@2014_OrgTags}.
5218 @vindex org-group-tags
5219 If you want to ignore group tags temporarily, toggle group tags support
5220 with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you
5221 want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
5224 @section Tag searches
5225 @cindex tag searches
5226 @cindex searching for tags
5228 Once a system of tags has been set up, it can be used to collect related
5229 information into special lists.
5232 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5233 Create a sparse tree with all headlines matching a tags/property/TODO search.
5234 With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5235 @xref{Matching tags and properties}.
5236 @orgcmd{C-c a m,org-tags-view}
5237 Create a global list of tag matches from all agenda files. @xref{Matching
5238 tags and properties}.
5239 @orgcmd{C-c a M,org-tags-view}
5240 @vindex org-tags-match-list-sublevels
5241 Create a global list of tag matches from all agenda files, but check
5242 only TODO items and force checking subitems (see the option
5243 @code{org-tags-match-list-sublevels}).
5246 These commands all prompt for a match string which allows basic Boolean logic
5247 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
5248 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
5249 tagged as @samp{Kathy} or @samp{Sally}. The full syntax of the search string
5250 is rich and allows also matching against TODO keywords, entry levels and
5251 properties. For a complete description with many examples, see @ref{Matching
5252 tags and properties}.
5255 @node Properties and columns
5256 @chapter Properties and columns
5259 A property is a key-value pair associated with an entry. Properties can be
5260 set so they are associated with a single entry, with every entry in a tree,
5261 or with every entry in an Org mode file.
5263 There are two main applications for properties in Org mode. First,
5264 properties are like tags, but with a value. Imagine maintaining a file where
5265 you document bugs and plan releases for a piece of software. Instead of
5266 using tags like @code{:release_1:}, @code{:release_2:}, you can use a
5267 property, say @code{:Release:}, that in different subtrees has different
5268 values, such as @code{1.0} or @code{2.0}. Second, you can use properties to
5269 implement (very basic) database capabilities in an Org buffer. Imagine
5270 keeping track of your music CDs, where properties could be things such as the
5271 album, artist, date of release, number of tracks, and so on.
5273 Properties can be conveniently edited and viewed in column view
5274 (@pxref{Column view}).
5277 * Property syntax:: How properties are spelled out
5278 * Special properties:: Access to other Org mode features
5279 * Property searches:: Matching property values
5280 * Property inheritance:: Passing values down the tree
5281 * Column view:: Tabular viewing and editing
5282 * Property API:: Properties for Lisp programmers
5285 @node Property syntax
5286 @section Property syntax
5287 @cindex property syntax
5288 @cindex drawer, for properties
5290 Properties are key-value pairs. When they are associated with a single entry
5291 or with a tree they need to be inserted into a special drawer
5292 (@pxref{Drawers}) with the name @code{PROPERTIES}, which has to be located
5293 right below a headline, and its planning line (@pxref{Deadlines and
5294 scheduling}) when applicable. Each property is specified on a single line,
5295 with the key (surrounded by colons) first, and the value after it. Keys are
5296 case-insensitive. Here is an example:
5301 *** Goldberg Variations
5303 :Title: Goldberg Variations
5304 :Composer: J.S. Bach
5306 :Publisher: Deutsche Grammophon
5311 Depending on the value of @code{org-use-property-inheritance}, a property set
5312 this way will either be associated with a single entry, or the subtree
5313 defined by the entry, see @ref{Property inheritance}.
5315 You may define the allowed values for a particular property @samp{:Xyz:}
5316 by setting a property @samp{:Xyz_ALL:}. This special property is
5317 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
5318 the entire tree. When allowed values are defined, setting the
5319 corresponding property becomes easier and is less prone to typing
5320 errors. For the example with the CD collection, we can predefine
5321 publishers and the number of disks in a box like this:
5326 :NDisks_ALL: 1 2 3 4
5327 :Publisher_ALL: "Deutsche Grammophon" Philips EMI
5331 If you want to set properties that can be inherited by any entry in a
5332 file, use a line like
5333 @cindex property, _ALL
5336 #+PROPERTY: NDisks_ALL 1 2 3 4
5339 Contrary to properties set from a special drawer, you have to refresh the
5340 buffer with @kbd{C-c C-c} to activate this change.
5342 If you want to add to the value of an existing property, append a @code{+} to
5343 the property name. The following results in the property @code{var} having
5344 the value ``foo=1 bar=2''.
5347 #+PROPERTY: var foo=1
5348 #+PROPERTY: var+ bar=2
5351 It is also possible to add to the values of inherited properties. The
5352 following results in the @code{genres} property having the value ``Classic
5353 Baroque'' under the @code{Goldberg Variations} subtree.
5361 *** Goldberg Variations
5363 :Title: Goldberg Variations
5364 :Composer: J.S. Bach
5366 :Publisher: Deutsche Grammophon
5371 Note that a property can only have one entry per Drawer.
5373 @vindex org-global-properties
5374 Property values set with the global variable
5375 @code{org-global-properties} can be inherited by all entries in all
5379 The following commands help to work with properties:
5382 @orgcmd{M-@key{TAB},pcomplete}
5383 After an initial colon in a line, complete property keys. All keys used
5384 in the current file will be offered as possible completions.
5385 @orgcmd{C-c C-x p,org-set-property}
5386 Set a property. This prompts for a property name and a value. If
5387 necessary, the property drawer is created as well.
5388 @item C-u M-x org-insert-drawer RET
5389 @cindex org-insert-drawer
5390 Insert a property drawer into the current entry. The drawer will be
5391 inserted early in the entry, but after the lines with planning
5392 information like deadlines.
5393 @orgcmd{C-c C-c,org-property-action}
5394 With the cursor in a property drawer, this executes property commands.
5395 @orgcmd{C-c C-c s,org-set-property}
5396 Set a property in the current entry. Both the property and the value
5397 can be inserted using completion.
5398 @orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
5399 Switch property at point to the next/previous allowed value.
5400 @orgcmd{C-c C-c d,org-delete-property}
5401 Remove a property from the current entry.
5402 @orgcmd{C-c C-c D,org-delete-property-globally}
5403 Globally remove a property, from all entries in the current file.
5404 @orgcmd{C-c C-c c,org-compute-property-at-point}
5405 Compute the property at point, using the operator and scope from the
5406 nearest column format definition.
5409 @node Special properties
5410 @section Special properties
5411 @cindex properties, special
5413 Special properties provide an alternative access method to Org mode features,
5414 like the TODO state or the priority of an entry, discussed in the previous
5415 chapters. This interface exists so that you can include these states in
5416 a column view (@pxref{Column view}), or to use them in queries. The
5417 following property names are special and should not be used as keys in the
5420 @cindex property, special, ALLTAGS
5421 @cindex property, special, BLOCKED
5422 @cindex property, special, CLOCKSUM
5423 @cindex property, special, CLOCKSUM_T
5424 @cindex property, special, CLOSED
5425 @cindex property, special, DEADLINE
5426 @cindex property, special, FILE
5427 @cindex property, special, ITEM
5428 @cindex property, special, PRIORITY
5429 @cindex property, special, SCHEDULED
5430 @cindex property, special, TAGS
5431 @cindex property, special, TIMESTAMP
5432 @cindex property, special, TIMESTAMP_IA
5433 @cindex property, special, TODO
5435 ALLTAGS @r{All tags, including inherited ones.}
5436 BLOCKED @r{"t" if task is currently blocked by children or siblings.}
5437 CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}}
5438 @r{must be run first to compute the values in the current buffer.}
5439 CLOCKSUM_T @r{The sum of CLOCK intervals in the subtree for today.}
5440 @r{@code{org-clock-sum-today} must be run first to compute the}
5441 @r{values in the current buffer.}
5442 CLOSED @r{When was this entry closed?}
5443 DEADLINE @r{The deadline time string, without the angular brackets.}
5444 FILE @r{The filename the entry is located in.}
5445 ITEM @r{The headline of the entry.}
5446 PRIORITY @r{The priority of the entry, a string with a single letter.}
5447 SCHEDULED @r{The scheduling timestamp, without the angular brackets.}
5448 TAGS @r{The tags defined directly in the headline.}
5449 TIMESTAMP @r{The first keyword-less timestamp in the entry.}
5450 TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
5451 TODO @r{The TODO keyword of the entry.}
5454 @node Property searches
5455 @section Property searches
5456 @cindex properties, searching
5457 @cindex searching, of properties
5459 To create sparse trees and special lists with selection based on properties,
5460 the same commands are used as for tag searches (@pxref{Tag searches}).
5463 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5464 Create a sparse tree with all matching entries. With a
5465 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5466 @orgcmd{C-c a m,org-tags-view}
5467 Create a global list of tag/property matches from all agenda files.
5468 @xref{Matching tags and properties}.
5469 @orgcmd{C-c a M,org-tags-view}
5470 @vindex org-tags-match-list-sublevels
5471 Create a global list of tag matches from all agenda files, but check
5472 only TODO items and force checking of subitems (see the option
5473 @code{org-tags-match-list-sublevels}).
5476 The syntax for the search string is described in @ref{Matching tags and
5479 There is also a special command for creating sparse trees based on a
5484 Create a sparse tree based on the value of a property. This first
5485 prompts for the name of a property, and then for a value. A sparse tree
5486 is created with all entries that define this property with the given
5487 value. If you enclose the value in curly braces, it is interpreted as
5488 a regular expression and matched against the property values.
5491 @node Property inheritance
5492 @section Property Inheritance
5493 @cindex properties, inheritance
5494 @cindex inheritance, of properties
5496 @vindex org-use-property-inheritance
5497 The outline structure of Org mode documents lends itself to an
5498 inheritance model of properties: if the parent in a tree has a certain
5499 property, the children can inherit this property. Org mode does not
5500 turn this on by default, because it can slow down property searches
5501 significantly and is often not needed. However, if you find inheritance
5502 useful, you can turn it on by setting the variable
5503 @code{org-use-property-inheritance}. It may be set to @code{t} to make
5504 all properties inherited from the parent, to a list of properties
5505 that should be inherited, or to a regular expression that matches
5506 inherited properties. If a property has the value @code{nil}, this is
5507 interpreted as an explicit undefine of the property, so that inheritance
5508 search will stop at this value and return @code{nil}.
5510 Org mode has a few properties for which inheritance is hard-coded, at
5511 least for the special applications for which they are used:
5513 @cindex property, COLUMNS
5516 The @code{:COLUMNS:} property defines the format of column view
5517 (@pxref{Column view}). It is inherited in the sense that the level
5518 where a @code{:COLUMNS:} property is defined is used as the starting
5519 point for a column view table, independently of the location in the
5520 subtree from where columns view is turned on.
5522 @cindex property, CATEGORY
5523 For agenda view, a category set through a @code{:CATEGORY:} property
5524 applies to the entire subtree.
5526 @cindex property, ARCHIVE
5527 For archiving, the @code{:ARCHIVE:} property may define the archive
5528 location for the entire subtree (@pxref{Moving subtrees}).
5530 @cindex property, LOGGING
5531 The LOGGING property may define logging settings for an entry or a
5532 subtree (@pxref{Tracking TODO state changes}).
5536 @section Column view
5538 A great way to view and edit properties in an outline tree is
5539 @emph{column view}. In column view, each outline node is turned into a
5540 table row. Columns in this table provide access to properties of the
5541 entries. Org mode implements columns by overlaying a tabular structure
5542 over the headline of each item. While the headlines have been turned
5543 into a table row, you can still change the visibility of the outline
5544 tree. For example, you get a compact table by switching to CONTENTS
5545 view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
5546 is active), but you can still open, read, and edit the entry below each
5547 headline. Or, you can switch to column view after executing a sparse
5548 tree command and in this way get a table only for the selected items.
5549 Column view also works in agenda buffers (@pxref{Agenda views}) where
5550 queries have collected selected items, possibly from a number of files.
5553 * Defining columns:: The COLUMNS format property
5554 * Using column view:: How to create and use column view
5555 * Capturing column view:: A dynamic block for column view
5558 @node Defining columns
5559 @subsection Defining columns
5560 @cindex column view, for properties
5561 @cindex properties, column view
5563 Setting up a column view first requires defining the columns. This is
5564 done by defining a column format line.
5567 * Scope of column definitions:: Where defined, where valid?
5568 * Column attributes:: Appearance and content of a column
5571 @node Scope of column definitions
5572 @subsubsection Scope of column definitions
5574 To define a column format for an entire file, use a line like
5578 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5581 To specify a format that only applies to a specific tree, add a
5582 @code{:COLUMNS:} property to the top node of that tree, for example:
5585 ** Top node for columns view
5587 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5591 If a @code{:COLUMNS:} property is present in an entry, it defines columns
5592 for the entry itself, and for the entire subtree below it. Since the
5593 column definition is part of the hierarchical structure of the document,
5594 you can define columns on level 1 that are general enough for all
5595 sublevels, and more specific columns further down, when you edit a
5596 deeper part of the tree.
5598 @node Column attributes
5599 @subsubsection Column attributes
5600 A column definition sets the attributes of a column. The general
5601 definition looks like this:
5604 %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]
5608 Except for the percent sign and the property name, all items are
5609 optional. The individual parts have the following meaning:
5612 @var{width} @r{An integer specifying the width of the column in characters.}
5613 @r{If omitted, the width will be determined automatically.}
5614 @var{property} @r{The property that should be edited in this column.}
5615 @r{Special properties representing meta data are allowed here}
5616 @r{as well (@pxref{Special properties})}
5617 @var{title} @r{The header text for the column. If omitted, the property}
5619 @{@var{summary-type}@} @r{The summary type. If specified, the column values for}
5620 @r{parent nodes are computed from the children@footnote{If
5621 more than one summary type apply to the property, the parent
5622 values are computed according to the first of them.}.}
5623 @r{Supported summary types are:}
5624 @{+@} @r{Sum numbers in this column.}
5625 @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.}
5626 @{$@} @r{Currency, short for @samp{+;%.2f}.}
5627 @{min@} @r{Smallest number in column.}
5628 @{max@} @r{Largest number.}
5629 @{mean@} @r{Arithmetic mean of numbers.}
5630 @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
5631 @{X/@} @r{Checkbox status, @samp{[n/m]}.}
5632 @{X%@} @r{Checkbox status, @samp{[n%]}.}
5633 @{:@} @r{Sum times, HH:MM, plain numbers are
5634 hours@footnote{A time can also be a duration, using effort
5635 modifiers defined in @code{org-effort-durations}, e.g.,
5636 @samp{3d 1h}. If any value in the column is as such, the
5637 summary will also be an effort duration.}.}
5638 @{:min@} @r{Smallest time value in column.}
5639 @{:max@} @r{Largest time value.}
5640 @{:mean@} @r{Arithmetic mean of time values.}
5641 @{@@min@} @r{Minimum age@footnote{An age is defined as
5642 a duration since a given time-stamp (@pxref{Timestamps}). It
5643 can also be expressed as days, hours, minutes and seconds,
5644 identified by @samp{d}, @samp{h}, @samp{m} and @samp{s}
5645 suffixes, all mandatory, e.g., @samp{0d 13h 0m 10s}.} (in
5646 days/hours/mins/seconds).}
5647 @{@@max@} @r{Maximum age (in days/hours/mins/seconds).}
5648 @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
5649 @{est+@} @r{Add @samp{low-high} estimates.}
5652 The @code{est+} summary type requires further explanation. It is used for
5653 combining estimates, expressed as @samp{low-high} ranges or plain numbers.
5654 For example, instead of estimating a particular task will take 5 days, you
5655 might estimate it as 5--6 days if you're fairly confident you know how much
5656 work is required, or 1--10 days if you don't really know what needs to be
5657 done. Both ranges average at 5.5 days, but the first represents a more
5658 predictable delivery.
5660 When combining a set of such estimates, simply adding the lows and highs
5661 produces an unrealistically wide result. Instead, @code{est+} adds the
5662 statistical mean and variance of the sub-tasks, generating a final estimate
5663 from the sum. For example, suppose you had ten tasks, each of which was
5664 estimated at 0.5 to 2 days of work. Straight addition produces an estimate
5665 of 5 to 20 days, representing what to expect if everything goes either
5666 extremely well or extremely poorly. In contrast, @code{est+} estimates the
5667 full job more realistically, at 10--15 days.
5669 Numbers are right-aligned when a format specifier with an explicit width like
5670 @code{%5d} or @code{%5.1f} is used.
5672 @vindex org-columns-summary-types
5673 You can also define custom summary types by setting
5674 @code{org-columns-summary-types}, which see.
5676 Here is an example for a complete columns definition, along with allowed
5680 :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.}
5681 %10Time_Estimate@{:@} %CLOCKSUM %CLOCKSUM_T
5682 :Owner_ALL: Tammy Mark Karl Lisa Don
5683 :Status_ALL: "In progress" "Not started yet" "Finished" ""
5684 :Approved_ALL: "[ ]" "[X]"
5688 The first column, @samp{%25ITEM}, means the first 25 characters of the
5689 item itself, i.e., of the headline. You probably always should start the
5690 column definition with the @samp{ITEM} specifier. The other specifiers
5691 create columns @samp{Owner} with a list of names as allowed values, for
5692 @samp{Status} with four different possible values, and for a checkbox
5693 field @samp{Approved}. When no width is given after the @samp{%}
5694 character, the column will be exactly as wide as it needs to be in order
5695 to fully display all values. The @samp{Approved} column does have a
5696 modified title (@samp{Approved?}, with a question mark). Summaries will
5697 be created for the @samp{Time_Estimate} column by adding time duration
5698 expressions like HH:MM, and for the @samp{Approved} column, by providing
5699 an @samp{[X]} status if all children have been checked. The
5700 @samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns are special, they lists the
5701 sums of CLOCK intervals in the subtree, either for all clocks or just for
5704 @node Using column view
5705 @subsection Using column view
5708 @tsubheading{Turning column view on and off}
5709 @orgcmd{C-c C-x C-c,org-columns}
5710 @vindex org-columns-default-format
5711 Turn on column view. If the cursor is before the first headline in the file,
5712 or the function called with the universal prefix argument, column view is
5713 turned on for the entire file, using the @code{#+COLUMNS} definition. If the
5714 cursor is somewhere inside the outline, this command searches the hierarchy,
5715 up from point, for a @code{:COLUMNS:} property that defines a format. When
5716 one is found, the column view table is established for the tree starting at
5717 the entry that contains the @code{:COLUMNS:} property. If no such property
5718 is found, the format is taken from the @code{#+COLUMNS} line or from the
5719 variable @code{org-columns-default-format}, and column view is established
5720 for the current entry and its subtree.
5721 @orgcmd{r,org-columns-redo}
5722 Recreate the column view, to include recent changes made in the buffer.
5723 @orgcmd{g,org-columns-redo}
5725 @orgcmd{q,org-columns-quit}
5727 @tsubheading{Editing values}
5728 @item @key{left} @key{right} @key{up} @key{down}
5729 Move through the column view from field to field.
5730 @kindex S-@key{left}
5731 @kindex S-@key{right}
5732 @item S-@key{left}/@key{right}
5733 Switch to the next/previous allowed value of the field. For this, you
5734 have to have specified allowed values for a property.
5736 Directly select the Nth allowed value, @kbd{0} selects the 10th value.
5737 @orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value}
5738 Same as @kbd{S-@key{left}/@key{right}}
5739 @orgcmd{e,org-columns-edit-value}
5740 Edit the property at point. For the special properties, this will
5741 invoke the same interface that you normally use to change that
5742 property. For example, when editing a TAGS property, the tag completion
5743 or fast selection interface will pop up.
5744 @orgcmd{C-c C-c,org-columns-set-tags-or-toggle}
5745 When there is a checkbox at point, toggle it.
5746 @orgcmd{v,org-columns-show-value}
5747 View the full value of this property. This is useful if the width of
5748 the column is smaller than that of the value.
5749 @orgcmd{a,org-columns-edit-allowed}
5750 Edit the list of allowed values for this property. If the list is found
5751 in the hierarchy, the modified value is stored there. If no list is
5752 found, the new value is stored in the first entry that is part of the
5753 current column view.
5754 @tsubheading{Modifying the table structure}
5755 @orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen}
5756 Make the column narrower/wider by one character.
5757 @orgcmd{S-M-@key{right},org-columns-new}
5758 Insert a new column, to the left of the current column.
5759 @orgcmd{S-M-@key{left},org-columns-delete}
5760 Delete the current column.
5763 @node Capturing column view
5764 @subsection Capturing column view
5766 Since column view is just an overlay over a buffer, it cannot be
5767 exported or printed directly. If you want to capture a column view, use
5768 a @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
5769 of this block looks like this:
5771 @cindex #+BEGIN, columnview
5774 #+BEGIN: columnview :hlines 1 :id "label"
5779 @noindent This dynamic block has the following parameters:
5783 This is the most important parameter. Column view is a feature that is
5784 often localized to a certain (sub)tree, and the capture block might be
5785 at a different location in the file. To identify the tree whose view to
5786 capture, you can use 4 values:
5787 @cindex property, ID
5789 local @r{use the tree in which the capture block is located}
5790 global @r{make a global view, including all headings in the file}
5791 "file:@var{path-to-file}"
5792 @r{run column view at the top of this file}
5793 "@var{ID}" @r{call column view in the tree that has an @code{:ID:}}
5794 @r{property with the value @i{label}. You can use}
5795 @r{@kbd{M-x org-id-copy RET} to create a globally unique ID for}
5796 @r{the current entry and copy it to the kill-ring.}
5799 When @code{t}, insert an hline after every line. When a number @var{N}, insert
5800 an hline before each headline with level @code{<= @var{N}}.
5802 When set to @code{t}, force column groups to get vertical lines.
5804 When set to a number, don't capture entries below this level.
5805 @item :skip-empty-rows
5806 When set to @code{t}, skip rows where the only non-empty specifier of the
5807 column view is @code{ITEM}.
5809 When non-@code{nil}, indent each @code{ITEM} field according to its level.
5814 The following commands insert or update the dynamic block:
5817 @orgcmd{C-c C-x i,org-insert-columns-dblock}
5818 Insert a dynamic block capturing a column view. You will be prompted
5819 for the scope or ID of the view.
5820 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
5821 Update dynamic block at point.
5822 @orgcmd{C-u C-c C-x C-u,org-update-all-dblocks}
5823 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
5824 you have several clock table blocks, column-capturing blocks or other dynamic
5828 You can add formulas to the column view table and you may add plotting
5829 instructions in front of the table---these will survive an update of the
5830 block. If there is a @code{#+TBLFM:} after the table, the table will
5831 actually be recalculated automatically after an update.
5833 An alternative way to capture and process property values into a table is
5834 provided by Eric Schulte's @file{org-collector.el} which is a contributed
5835 package@footnote{Contributed packages are not part of Emacs, but are
5836 distributed with the main distribution of Org (visit
5837 @uref{http://orgmode.org}).}. It provides a general API to collect
5838 properties from entries in a certain scope, and arbitrary Lisp expressions to
5839 process these values before inserting them into a table or a dynamic block.
5842 @section The Property API
5843 @cindex properties, API
5844 @cindex API, for properties
5846 There is a full API for accessing and changing properties. This API can
5847 be used by Emacs Lisp programs to work with properties and to implement
5848 features based on them. For more information see @ref{Using the
5851 @node Dates and times
5852 @chapter Dates and times
5858 To assist project planning, TODO items can be labeled with a date and/or
5859 a time. The specially formatted string carrying the date and time
5860 information is called a @emph{timestamp} in Org mode. This may be a
5861 little confusing because timestamp is often used to indicate when
5862 something was created or last changed. However, in Org mode this term
5863 is used in a much wider sense.
5866 * Timestamps:: Assigning a time to a tree entry
5867 * Creating timestamps:: Commands which insert timestamps
5868 * Deadlines and scheduling:: Planning your work
5869 * Clocking work time:: Tracking how long you spend on a task
5870 * Effort estimates:: Planning work effort in advance
5871 * Timers:: Notes with a running timer
5876 @section Timestamps, deadlines, and scheduling
5878 @cindex ranges, time
5883 A timestamp is a specification of a date (possibly with a time or a range of
5884 times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this
5885 simplest form, the day name is optional when you type the date yourself.
5886 However, any dates inserted or modified by Org will add that day name, for
5887 reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16
5888 Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601
5889 date/time format. To use an alternative format, see @ref{Custom time
5890 format}.}. A timestamp can appear anywhere in the headline or body of an Org
5891 tree entry. Its presence causes entries to be shown on specific dates in the
5892 agenda (@pxref{Weekly/daily agenda}). We distinguish:
5895 @item Plain timestamp; Event; Appointment
5898 A simple timestamp just assigns a date/time to an item. This is just like
5899 writing down an appointment or event in a paper agenda. In the agenda
5900 display, the headline of an entry associated with a plain timestamp will be
5901 shown exactly on that date.
5904 * Meet Peter at the movies
5905 <2006-11-01 Wed 19:15>
5906 * Discussion on climate change
5907 <2006-11-02 Thu 20:00-22:00>
5910 @item Timestamp with repeater interval
5911 @cindex timestamp, with repeater interval
5912 A timestamp may contain a @emph{repeater interval}, indicating that it
5913 applies not only on the given date, but again and again after a certain
5914 interval of N days (d), weeks (w), months (m), or years (y). The
5915 following will show up in the agenda every Wednesday:
5918 * Pick up Sam at school
5919 <2007-05-16 Wed 12:30 +1w>
5922 @item Diary-style sexp entries
5923 For more complex date specifications, Org mode supports using the special
5924 sexp diary entries implemented in the Emacs calendar/diary
5925 package@footnote{When working with the standard diary sexp functions, you
5926 need to be very careful with the order of the arguments. That order depends
5927 evilly on the variable @code{calendar-date-style} (or, for older Emacs
5928 versions, @code{european-calendar-style}). For example, to specify a date
5929 December 1, 2005, the call might look like @code{(diary-date 12 1 2005)} or
5930 @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
5931 the settings. This has been the source of much confusion. Org mode users
5932 can resort to special versions of these functions like @code{org-date} or
5933 @code{org-anniversary}. These work just like the corresponding @code{diary-}
5934 functions, but with stable ISO order of arguments (year, month, day) wherever
5935 applicable, independent of the value of @code{calendar-date-style}.}. For
5936 example with optional time
5939 * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
5940 <%%(diary-float t 4 2)>
5943 @item Time/Date range
5946 Two timestamps connected by @samp{--} denote a range. The headline
5947 will be shown on the first and last day of the range, and on any dates
5948 that are displayed and fall in the range. Here is an example:
5951 ** Meeting in Amsterdam
5952 <2004-08-23 Mon>--<2004-08-26 Thu>
5955 @item Inactive timestamp
5956 @cindex timestamp, inactive
5957 @cindex inactive timestamp
5958 Just like a plain timestamp, but with square brackets instead of
5959 angular ones. These timestamps are inactive in the sense that they do
5960 @emph{not} trigger an entry to show up in the agenda.
5963 * Gillian comes late for the fifth time
5969 @node Creating timestamps
5970 @section Creating timestamps
5971 @cindex creating timestamps
5972 @cindex timestamps, creating
5974 For Org mode to recognize timestamps, they need to be in the specific
5975 format. All commands listed below produce timestamps in the correct
5979 @orgcmd{C-c .,org-time-stamp}
5980 Prompt for a date and insert a corresponding timestamp. When the cursor is
5981 at an existing timestamp in the buffer, the command is used to modify this
5982 timestamp instead of inserting a new one. When this command is used twice in
5983 succession, a time range is inserted.
5985 @orgcmd{C-c !,org-time-stamp-inactive}
5986 Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
5993 @vindex org-time-stamp-rounding-minutes
5994 Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which
5995 contains date and time. The default time can be rounded to multiples of 5
5996 minutes, see the option @code{org-time-stamp-rounding-minutes}.
5999 Normalize timestamp, insert/fix day name if missing or wrong.
6001 @orgcmd{C-c <,org-date-from-calendar}
6002 Insert a timestamp corresponding to the cursor date in the Calendar.
6004 @orgcmd{C-c >,org-goto-calendar}
6005 Access the Emacs calendar for the current date. If there is a
6006 timestamp in the current line, go to the corresponding date
6009 @orgcmd{C-c C-o,org-open-at-point}
6010 Access the agenda for the date given by the timestamp or -range at
6011 point (@pxref{Weekly/daily agenda}).
6013 @orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day}
6014 Change date at cursor by one day. These key bindings conflict with
6015 shift-selection and related modes (@pxref{Conflicts}).
6017 @orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down}
6018 Change the item under the cursor in a timestamp. The cursor can be on a
6019 year, month, day, hour or minute. When the timestamp contains a time range
6020 like @samp{15:30-16:30}, modifying the first time will also shift the second,
6021 shifting the time block with constant length. To change the length, modify
6022 the second time. Note that if the cursor is in a headline and not at a
6023 timestamp, these same keys modify the priority of an item.
6024 (@pxref{Priorities}). The key bindings also conflict with shift-selection and
6025 related modes (@pxref{Conflicts}).
6027 @orgcmd{C-c C-y,org-evaluate-time-range}
6028 @cindex evaluate time range
6029 Evaluate a time range by computing the difference between start and end.
6030 With a prefix argument, insert result after the time range (in a table: into
6031 the following column).
6036 * The date/time prompt:: How Org mode helps you entering date and time
6037 * Custom time format:: Making dates look different
6040 @node The date/time prompt
6041 @subsection The date/time prompt
6042 @cindex date, reading in minibuffer
6043 @cindex time, reading in minibuffer
6045 @vindex org-read-date-prefer-future
6046 When Org mode prompts for a date/time, the default is shown in default
6047 date/time format, and the prompt therefore seems to ask for a specific
6048 format. But it will in fact accept date/time information in a variety of
6049 formats. Generally, the information should start at the beginning of the
6050 string. Org mode will find whatever information is in
6051 there and derive anything you have not specified from the @emph{default date
6052 and time}. The default is usually the current date and time, but when
6053 modifying an existing timestamp, or when entering the second stamp of a
6054 range, it is taken from the stamp in the buffer. When filling in
6055 information, Org mode assumes that most of the time you will want to enter a
6056 date in the future: if you omit the month/year and the given day/month is
6057 @i{before} today, it will assume that you mean a future date@footnote{See the
6058 variable @code{org-read-date-prefer-future}. You may set that variable to
6059 the symbol @code{time} to even make a time before now shift the date to
6060 tomorrow.}. If the date has been automatically shifted into the future, the
6061 time prompt will show this with @samp{(=>F).}
6063 For example, let's assume that today is @b{June 13, 2006}. Here is how
6064 various inputs will be interpreted, the items filled in by Org mode are
6068 3-2-5 @result{} 2003-02-05
6069 2/5/3 @result{} 2003-02-05
6070 14 @result{} @b{2006}-@b{06}-14
6071 12 @result{} @b{2006}-@b{07}-12
6072 2/5 @result{} @b{2007}-02-05
6073 Fri @result{} nearest Friday after the default date
6074 sep 15 @result{} @b{2006}-09-15
6075 feb 15 @result{} @b{2007}-02-15
6076 sep 12 9 @result{} 2009-09-12
6077 12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45
6078 22 sept 0:34 @result{} @b{2006}-09-22 00:34
6079 w4 @result{} ISO week four of the current year @b{2006}
6080 2012 w4 fri @result{} Friday of ISO week 4 in 2012
6081 2012-w04-5 @result{} Same as above
6084 Furthermore you can specify a relative date by giving, as the @emph{first}
6085 thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to
6086 indicate change in hours, days, weeks, months, or years. With a single plus
6087 or minus, the date is always relative to today. With a double plus or minus,
6088 it is relative to the default date. If instead of a single letter, you use
6089 the abbreviation of day name, the date will be the Nth such day, e.g.:
6094 +4d @result{} four days from today
6095 +4 @result{} same as above
6096 +2w @result{} two weeks from today
6097 ++5 @result{} five days from default date
6098 +2tue @result{} second Tuesday from now
6099 -wed @result{} last Wednesday
6102 @vindex parse-time-months
6103 @vindex parse-time-weekdays
6104 The function understands English month and weekday abbreviations. If
6105 you want to use unabbreviated names and/or other languages, configure
6106 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
6108 @vindex org-read-date-force-compatible-dates
6109 Not all dates can be represented in a given Emacs implementation. By default
6110 Org mode forces dates into the compatibility range 1970--2037 which works on
6111 all Emacs implementations. If you want to use dates outside of this range,
6112 read the docstring of the variable
6113 @code{org-read-date-force-compatible-dates}.
6115 You can specify a time range by giving start and end times or by giving a
6116 start time and a duration (in HH:MM format). Use one or two dash(es) as the
6117 separator in the former case and use '+' as the separator in the latter
6121 11am-1:15pm @result{} 11:00-13:15
6122 11am--1:15pm @result{} same as above
6123 11am+2:15 @result{} same as above
6126 @cindex calendar, for selecting date
6127 @vindex org-popup-calendar-for-date-prompt
6128 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
6129 you don't need/want the calendar, configure the variable
6130 @code{org-popup-calendar-for-date-prompt}.}. When you exit the date
6131 prompt, either by clicking on a date in the calendar, or by pressing
6132 @key{RET}, the date selected in the calendar will be combined with the
6133 information entered at the prompt. You can control the calendar fully
6134 from the minibuffer:
6141 @kindex S-@key{right}
6142 @kindex S-@key{left}
6143 @kindex S-@key{down}
6145 @kindex M-S-@key{right}
6146 @kindex M-S-@key{left}
6148 @kindex M-S-@key{down}
6149 @kindex M-S-@key{up}
6152 @key{RET} @r{Choose date at cursor in calendar.}
6153 mouse-1 @r{Select date by clicking on it.}
6154 S-@key{right}/@key{left} @r{One day forward/backward.}
6155 S-@key{down}/@key{up} @r{One week forward/backward.}
6156 M-S-@key{right}/@key{left} @r{One month forward/backward.}
6157 > / < @r{Scroll calendar forward/backward by one month.}
6158 M-v / C-v @r{Scroll calendar forward/backward by 3 months.}
6159 M-S-@key{down}/@key{up} @r{Scroll calendar forward/backward by one year.}
6162 @vindex org-read-date-display-live
6163 The actions of the date/time prompt may seem complex, but I assure you they
6164 will grow on you, and you will start getting annoyed by pretty much any other
6165 way of entering a date/time out there. To help you understand what is going
6166 on, the current interpretation of your input will be displayed live in the
6167 minibuffer@footnote{If you find this distracting, turn the display off with
6168 @code{org-read-date-display-live}.}.
6170 @node Custom time format
6171 @subsection Custom time format
6172 @cindex custom date/time format
6173 @cindex time format, custom
6174 @cindex date format, custom
6176 @vindex org-display-custom-times
6177 @vindex org-time-stamp-custom-formats
6178 Org mode uses the standard ISO notation for dates and times as it is
6179 defined in ISO 8601. If you cannot get used to this and require another
6180 representation of date and time to keep you happy, you can get it by
6181 customizing the options @code{org-display-custom-times} and
6182 @code{org-time-stamp-custom-formats}.
6185 @orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays}
6186 Toggle the display of custom formats for dates and times.
6190 Org mode needs the default format for scanning, so the custom date/time
6191 format does not @emph{replace} the default format---instead it is put
6192 @emph{over} the default format using text properties. This has the
6193 following consequences:
6196 You cannot place the cursor onto a timestamp anymore, only before or
6199 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
6200 each component of a timestamp. If the cursor is at the beginning of
6201 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
6202 just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the
6203 time will be changed by one minute.
6205 If the timestamp contains a range of clock times or a repeater, these
6206 will not be overlaid, but remain in the buffer as they were.
6208 When you delete a timestamp character-by-character, it will only
6209 disappear from the buffer after @emph{all} (invisible) characters
6210 belonging to the ISO timestamp have been removed.
6212 If the custom timestamp format is longer than the default and you are
6213 using dates in tables, table alignment will be messed up. If the custom
6214 format is shorter, things do work as expected.
6218 @node Deadlines and scheduling
6219 @section Deadlines and scheduling
6221 A timestamp may be preceded by special keywords to facilitate planning. Both
6222 the timestamp and the keyword have to be positioned immediately after the task
6227 @cindex DEADLINE keyword
6229 Meaning: the task (most likely a TODO item, though not necessarily) is supposed
6230 to be finished on that date.
6232 @vindex org-deadline-warning-days
6233 @vindex org-agenda-skip-deadline-prewarning-if-scheduled
6234 On the deadline date, the task will be listed in the agenda. In
6235 addition, the agenda for @emph{today} will carry a warning about the
6236 approaching or missed deadline, starting
6237 @code{org-deadline-warning-days} before the due date, and continuing
6238 until the entry is marked DONE@. An example:
6241 *** TODO write article about the Earth for the Guide
6242 DEADLINE: <2004-02-29 Sun>
6243 The editor in charge is [[bbdb:Ford Prefect]]
6246 You can specify a different lead time for warnings for a specific
6247 deadline using the following syntax. Here is an example with a warning
6248 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. This warning is
6249 deactivated if the task gets scheduled and you set
6250 @code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}.
6253 @cindex SCHEDULED keyword
6255 Meaning: you are planning to start working on that task on the given
6258 @vindex org-agenda-skip-scheduled-if-done
6259 The headline will be listed under the given date@footnote{It will still
6260 be listed on that date after it has been marked DONE@. If you don't like
6261 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
6262 addition, a reminder that the scheduled date has passed will be present
6263 in the compilation for @emph{today}, until the entry is marked DONE, i.e.,
6264 the task will automatically be forwarded until completed.
6267 *** TODO Call Trillian for a date on New Years Eve.
6268 SCHEDULED: <2004-12-25 Sat>
6271 @vindex org-scheduled-delay-days
6272 @vindex org-agenda-skip-scheduled-delay-if-deadline
6273 If you want to @emph{delay} the display of this task in the agenda, use
6274 @code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the
6275 25th but will appear two days later. In case the task contains a repeater,
6276 the delay is considered to affect all occurrences; if you want the delay to
6277 only affect the first scheduled occurrence of the task, use @code{--2d}
6278 instead. See @code{org-scheduled-delay-days} and
6279 @code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to
6280 control this globally or per agenda.
6283 @b{Important:} Scheduling an item in Org mode should @i{not} be
6284 understood in the same way that we understand @i{scheduling a meeting}.
6285 Setting a date for a meeting is just a simple appointment, you should
6286 mark this entry with a simple plain timestamp, to get this item shown
6287 on the date where it applies. This is a frequent misunderstanding by
6288 Org users. In Org mode, @i{scheduling} means setting a date when you
6289 want to start working on an action item.
6292 You may use timestamps with repeaters in scheduling and deadline
6293 entries. Org mode will issue early and late warnings based on the
6294 assumption that the timestamp represents the @i{nearest instance} of
6295 the repeater. However, the use of diary sexp entries like
6297 @code{<%%(diary-float t 42)>}
6299 in scheduling and deadline timestamps is limited. Org mode does not
6300 know enough about the internals of each sexp function to issue early and
6301 late warnings. However, it will show the item on each day where the
6305 * Inserting deadline/schedule:: Planning items
6306 * Repeated tasks:: Items that show up again and again
6309 @node Inserting deadline/schedule
6310 @subsection Inserting deadlines or schedules
6312 The following commands allow you to quickly insert a deadline or to schedule
6317 @orgcmd{C-c C-d,org-deadline}
6318 Insert @samp{DEADLINE} keyword along with a stamp. Any CLOSED timestamp will
6319 be removed. When called with a prefix arg, an existing deadline will be
6320 removed from the entry. Depending on the variable
6321 @code{org-log-redeadline}@footnote{with corresponding @code{#+STARTUP}
6322 keywords @code{logredeadline}, @code{lognoteredeadline}, and
6323 @code{nologredeadline}}, a note will be taken when changing an existing
6326 @orgcmd{C-c C-s,org-schedule}
6327 Insert @samp{SCHEDULED} keyword along with a stamp. Any CLOSED timestamp
6328 will be removed. When called with a prefix argument, remove the scheduling
6329 date from the entry. Depending on the variable
6330 @code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}
6331 keywords @code{logreschedule}, @code{lognotereschedule}, and
6332 @code{nologreschedule}}, a note will be taken when changing an existing
6335 @orgcmd{C-c / d,org-check-deadlines}
6336 @cindex sparse tree, for deadlines
6337 @vindex org-deadline-warning-days
6338 Create a sparse tree with all deadlines that are either past-due, or
6339 which will become due within @code{org-deadline-warning-days}.
6340 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
6341 prefix, check that many days. For example, @kbd{C-1 C-c / d} shows
6342 all deadlines due tomorrow.
6344 @orgcmd{C-c / b,org-check-before-date}
6345 Sparse tree for deadlines and scheduled items before a given date.
6347 @orgcmd{C-c / a,org-check-after-date}
6348 Sparse tree for deadlines and scheduled items after a given date.
6351 Note that @code{org-schedule} and @code{org-deadline} supports
6352 setting the date by indicating a relative time: e.g., +1d will set
6353 the date to the next day after today, and --1w will set the date
6354 to the previous week before any current timestamp.
6356 @node Repeated tasks
6357 @subsection Repeated tasks
6358 @cindex tasks, repeated
6359 @cindex repeated tasks
6361 Some tasks need to be repeated again and again. Org mode helps to
6362 organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
6363 or plain timestamp. In the following example
6365 ** TODO Pay the rent
6366 DEADLINE: <2005-10-01 Sat +1m>
6369 the @code{+1m} is a repeater; the intended interpretation is that the task
6370 has a deadline on <2005-10-01> and repeats itself every (one) month starting
6371 from that time. You can use yearly, monthly, weekly, daily and hourly repeat
6372 cookies by using the @code{y/w/m/d/h} letters. If you need both a repeater
6373 and a special warning period in a deadline entry, the repeater should come
6374 first and the warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
6376 @vindex org-todo-repeat-to-state
6377 Deadlines and scheduled items produce entries in the agenda when they are
6378 over-due, so it is important to be able to mark such an entry as completed
6379 once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO
6380 keyword DONE, it will no longer produce entries in the agenda. The problem
6381 with this is, however, that then also the @emph{next} instance of the
6382 repeated entry will not be active. Org mode deals with this in the following
6383 way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
6384 shift the base date of the repeating timestamp by the repeater interval, and
6385 immediately set the entry state back to TODO@footnote{In fact, the target
6386 state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or
6387 the variable @code{org-todo-repeat-to-state}. If neither of these is
6388 specified, the target state defaults to the first state of the TODO state
6389 sequence.}. In the example above, setting the state to DONE would actually
6390 switch the date like this:
6393 ** TODO Pay the rent
6394 DEADLINE: <2005-11-01 Tue +1m>
6397 To mark a task with a repeater as @code{DONE}, use @kbd{C-- 1 C-c C-t}
6398 (i.e., @code{org-todo} with a numeric prefix argument of -1.)
6400 @vindex org-log-repeat
6401 A timestamp@footnote{You can change this using the option
6402 @code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},
6403 @code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you
6404 will also be prompted for a note.} will be added under the deadline, to keep
6405 a record that you actually acted on the previous instance of this deadline.
6407 As a consequence of shifting the base date, this entry will no longer be
6408 visible in the agenda when checking past dates, but all future instances
6411 With the @samp{+1m} cookie, the date shift will always be exactly one
6412 month. So if you have not paid the rent for three months, marking this
6413 entry DONE will still keep it as an overdue deadline. Depending on the
6414 task, this may not be the best way to handle it. For example, if you
6415 forgot to call your father for 3 weeks, it does not make sense to call
6416 him 3 times in a single day to make up for it. Finally, there are tasks
6417 like changing batteries which should always repeat a certain time
6418 @i{after} the last time you did it. For these tasks, Org mode has
6419 special repeaters @samp{++} and @samp{.+}. For example:
6423 DEADLINE: <2008-02-10 Sun ++1w>
6424 Marking this DONE will shift the date by at least one week,
6425 but also by as many weeks as it takes to get this date into
6426 the future. However, it stays on a Sunday, even if you called
6427 and marked it done on Saturday.
6428 ** TODO Empty kitchen trash
6429 DEADLINE: <2008-02-08 Fri 20:00 ++1d>
6430 Marking this DONE will shift the date by at least one day, and
6431 also by as many days as it takes to get the timestamp into the
6432 future. Since there is a time in the timestamp, the next
6433 deadline in the future will be on today's date if you
6434 complete the task before 20:00.
6435 ** TODO Check the batteries in the smoke detectors
6436 DEADLINE: <2005-11-01 Tue .+1m>
6437 Marking this DONE will shift the date to one month after
6441 @vindex org-agenda-skip-scheduled-if-deadline-is-shown
6442 You may have both scheduling and deadline information for a specific task.
6443 If the repeater is set for the scheduling information only, you probably want
6444 the repeater to be ignored after the deadline. If so, set the variable
6445 @code{org-agenda-skip-scheduled-if-deadline-is-shown} to
6446 @code{repeated-after-deadline}. However, any scheduling information without
6447 a repeater is no longer relevant once the task is done, and thus, removed
6448 upon repeating the task. If you want both scheduling and deadline
6449 information to repeat after the same interval, set the same repeater for both
6452 An alternative to using a repeater is to create a number of copies of a task
6453 subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was
6454 created for this purpose, it is described in @ref{Structure editing}.
6457 @node Clocking work time
6458 @section Clocking work time
6459 @cindex clocking time
6460 @cindex time clocking
6462 Org mode allows you to clock the time you spend on specific tasks in a
6463 project. When you start working on an item, you can start the clock. When
6464 you stop working on that task, or when you mark the task done, the clock is
6465 stopped and the corresponding time interval is recorded. It also computes
6466 the total time spent on each subtree@footnote{Clocking only works if all
6467 headings are indented with less than 30 stars. This is a hardcoded
6468 limitation of @code{lmax} in @code{org-clock-sum}.} of a project.
6469 And it remembers a history or tasks recently clocked, so that you can jump
6470 quickly between a number of tasks absorbing your time.
6472 To save the clock history across Emacs sessions, use
6474 (setq org-clock-persist 'history)
6475 (org-clock-persistence-insinuate)
6477 When you clock into a new task after resuming Emacs, the incomplete
6478 clock@footnote{To resume the clock under the assumption that you have worked
6479 on this task while outside Emacs, use @code{(setq org-clock-persist t)}.}
6480 will be found (@pxref{Resolving idle time}) and you will be prompted about
6484 * Clocking commands:: Starting and stopping a clock
6485 * The clock table:: Detailed reports
6486 * Resolving idle time:: Resolving time when you've been idle
6489 @node Clocking commands
6490 @subsection Clocking commands
6493 @orgcmd{C-c C-x C-i,org-clock-in}
6494 @vindex org-clock-into-drawer
6495 @vindex org-clock-continuously
6496 @cindex property, LOG_INTO_DRAWER
6497 Start the clock on the current item (clock-in). This inserts the CLOCK
6498 keyword together with a timestamp. If this is not the first clocking of
6499 this item, the multiple CLOCK lines will be wrapped into a
6500 @code{:LOGBOOK:} drawer (see also the variable
6501 @code{org-clock-into-drawer}). You can also overrule
6502 the setting of this variable for a subtree by setting a
6503 @code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
6504 When called with a @kbd{C-u} prefix argument,
6505 select the task from a list of recently clocked tasks. With two @kbd{C-u
6506 C-u} prefixes, clock into the task at point and mark it as the default task;
6507 the default task will then always be available with letter @kbd{d} when
6508 selecting a clocking task. With three @kbd{C-u C-u C-u} prefixes, force
6509 continuous clocking by starting the clock when the last clock stopped.@*
6510 @cindex property: CLOCK_MODELINE_TOTAL
6511 @cindex property: LAST_REPEAT
6512 @vindex org-clock-modeline-total
6513 While the clock is running, the current clocking time is shown in the mode
6514 line, along with the title of the task. The clock time shown will be all
6515 time ever clocked for this task and its children. If the task has an effort
6516 estimate (@pxref{Effort estimates}), the mode line displays the current
6517 clocking time against it@footnote{To add an effort estimate ``on the fly'',
6518 hook a function doing this to @code{org-clock-in-prepare-hook}.} If the task
6519 is a repeating one (@pxref{Repeated tasks}), only the time since the last
6520 reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}
6521 will be shown. More control over what time is shown can be exercised with
6522 the @code{CLOCK_MODELINE_TOTAL} property. It may have the values
6523 @code{current} to show only the current clocking instance, @code{today} to
6524 show all time clocked on this task today (see also the variable
6525 @code{org-extend-today-until}), @code{all} to include all time, or
6526 @code{auto} which is the default@footnote{See also the variable
6527 @code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
6528 mode line entry will pop up a menu with clocking options.
6530 @orgcmd{C-c C-x C-o,org-clock-out}
6531 @vindex org-log-note-clock-out
6532 Stop the clock (clock-out). This inserts another timestamp at the same
6533 location where the clock was last started. It also directly computes
6534 the resulting time and inserts it after the time range as @samp{=>
6535 HH:MM}. See the variable @code{org-log-note-clock-out} for the
6536 possibility to record an additional note together with the clock-out
6537 timestamp@footnote{The corresponding in-buffer setting is:
6538 @code{#+STARTUP: lognoteclock-out}}.
6539 @orgcmd{C-c C-x C-x,org-clock-in-last}
6540 @vindex org-clock-continuously
6541 Reclock the last clocked task. With one @kbd{C-u} prefix argument,
6542 select the task from the clock history. With two @kbd{C-u} prefixes,
6543 force continuous clocking by starting the clock when the last clock
6545 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6546 Update the effort estimate for the current clock task.
6549 @orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range}
6550 Recompute the time interval after changing one of the timestamps. This
6551 is only necessary if you edit the timestamps directly. If you change
6552 them with @kbd{S-@key{cursor}} keys, the update is automatic.
6553 @orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
6554 On @code{CLOCK} log lines, increase/decrease both timestamps so that the
6555 clock duration keeps the same.
6556 @orgcmd{S-M-@key{up/down},org-timestamp-up/down}
6557 On @code{CLOCK} log lines, increase/decrease the timestamp at point and
6558 the one of the previous (or the next clock) timestamp by the same duration.
6559 For example, if you hit @kbd{S-M-@key{up}} to increase a clocked-out timestamp
6560 by five minutes, then the clocked-in timestamp of the next clock will be
6561 increased by five minutes.
6562 @orgcmd{C-c C-t,org-todo}
6563 Changing the TODO state of an item to DONE automatically stops the clock
6564 if it is running in this same item.
6565 @orgcmd{C-c C-x C-q,org-clock-cancel}
6566 Cancel the current clock. This is useful if a clock was started by
6567 mistake, or if you ended up working on something else.
6568 @orgcmd{C-c C-x C-j,org-clock-goto}
6569 Jump to the headline of the currently clocked in task. With a @kbd{C-u}
6570 prefix arg, select the target task from a list of recently clocked tasks.
6571 @orgcmd{C-c C-x C-d,org-clock-display}
6572 @vindex org-remove-highlights-with-change
6573 Display time summaries for each subtree in the current buffer. This puts
6574 overlays at the end of each headline, showing the total time recorded under
6575 that heading, including the time of any subheadings. You can use visibility
6576 cycling to study the tree, but the overlays disappear when you change the
6577 buffer (see variable @code{org-remove-highlights-with-change}) or press
6581 The @kbd{l} key may be used the agenda (@pxref{Weekly/daily agenda}) to show
6582 which tasks have been 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.
6607 @orgkey{C-u C-c C-x C-u}
6608 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
6609 you have several clock table blocks in a buffer.
6610 @orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift}
6611 Shift the current @code{:block} interval and update the table. The cursor
6612 needs to be in the @code{#+BEGIN: clocktable} line for this command. If
6613 @code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
6617 Here is an example of the frame for a clock table as it is inserted into the
6618 buffer with the @kbd{C-c C-x C-r} command:
6620 @cindex #+BEGIN, clocktable
6622 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
6626 @vindex org-clocktable-defaults
6627 The @samp{BEGIN} line specifies a number of options to define the scope,
6628 structure, and formatting of the report. Defaults for all these options can
6629 be configured in the variable @code{org-clocktable-defaults}.
6631 @noindent First there are options that determine which clock entries are to
6634 :maxlevel @r{Maximum level depth to which times are listed in the table.}
6635 @r{Clocks at deeper levels will be summed into the upper level.}
6636 :scope @r{The scope to consider. This can be any of the following:}
6637 nil @r{the current buffer or narrowed region}
6638 file @r{the full current buffer}
6639 subtree @r{the subtree where the clocktable is located}
6640 tree@var{N} @r{the surrounding level @var{N} tree, for example @code{tree3}}
6641 tree @r{the surrounding level 1 tree}
6642 agenda @r{all agenda files}
6643 ("file"..) @r{scan these files}
6644 function @r{the list of files returned by a function of no argument}
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+olp+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+olp+datetree "path/to/file" [ "Level 1 heading" ....])
7188 This target@footnote{Org used to offer four different targets for date/week
7189 tree capture. Now, Org automatically translates these to use
7190 @code{file+olp+datetree}, applying the @code{:time-prompt} and
7191 @code{:tree-type} properties. Please rewrite your date/week-tree targets
7192 using @code{file+olp+datetree} since the older targets are now deprecated.}
7193 will create a heading in a date tree@footnote{A date tree is an outline
7194 structure with years on the highest level, months or ISO-weeks as sublevels
7195 and then dates on the lowest level. Tags are allowed in the tree structure.}
7196 for today's date. If the optional outline path is given, the tree will be
7197 built under the node it is pointing to, instead of at top level. Check out
7198 the @code{:time-prompt} and @code{:tree-type} properties below for additional
7201 @item (file+function "path/to/file" function-finding-location)
7202 A function to find the right location in the file.
7205 File to the entry that is currently being clocked.
7207 @item (function function-finding-location)
7208 Most general way: write your own function which both visits
7209 the file and moves point to the right location.
7213 The template for creating the capture item. If you leave this empty, an
7214 appropriate default template will be used. Otherwise this is a string with
7215 escape codes, which will be replaced depending on time and context of the
7216 capture call. The string with escapes may be loaded from a template file,
7217 using the special syntax @code{(file "path/to/template")}. See below for
7221 The rest of the entry is a property list of additional options.
7222 Recognized properties are:
7226 Normally new captured information will be appended at
7227 the target location (last child, last table line, last list item...).
7228 Setting this property will change that.
7230 @item :immediate-finish
7231 When set, do not offer to edit the information, just
7232 file it away immediately. This makes sense if the template only needs
7233 information that can be added automatically.
7236 Set this to the number of lines to insert
7237 before and after the new item. Default 0, only common other value is 1.
7240 Start the clock in this item.
7243 Keep the clock running when filing the captured entry.
7246 If starting the capture interrupted a clock, restart that clock when finished
7247 with the capture. Note that @code{:clock-keep} has precedence over
7248 @code{:clock-resume}. When setting both to @code{t}, the current clock will
7249 run and the previous one will not be resumed.
7252 Prompt for a date/time to be used for date/week trees and when filling the
7253 template. Without this property, capture uses the current date and time.
7254 Even if this property has not been set, you can force the same behavior by
7255 calling @code{org-capture} with a @kbd{C-1} prefix argument.
7258 When `week', make a week tree instead of the month tree, i.e. place the
7259 headings for each day under a heading with the current iso week.
7262 Do not narrow the target buffer, simply show the full buffer. Default is to
7263 narrow it so that you only see the new material.
7265 @item :table-line-pos
7266 Specification of the location in the table where the new line should be
7267 inserted. It can be a string, a variable holding a string or a function
7268 returning a string. The string should look like @code{"II-3"} meaning that
7269 the new line should become the third line before the second horizontal
7273 If the target file was not yet visited when capture was invoked, kill the
7274 buffer again after capture is completed.
7278 @node Template expansion
7279 @subsubsection Template expansion
7281 In the template itself, special @kbd{%}-escapes@footnote{If you need one of
7282 these sequences literally, escape the @kbd{%} with a backslash.} allow
7283 dynamic insertion of content. The templates are expanded in the order given here:
7286 %[@var{file}] @r{Insert the contents of the file given by @var{file}.}
7287 %(@var{sexp}) @r{Evaluate Elisp @var{sexp} and replace with the result.}
7288 @r{For convenience, %:keyword (see below) placeholders}
7289 @r{within the expression will be expanded prior to this.}
7290 @r{The sexp must return a string.}
7291 %<...> @r{The result of format-time-string on the ... format specification.}
7292 %t @r{Timestamp, date only.}
7293 %T @r{Timestamp, with date and time.}
7294 %u, %U @r{Like the above, but inactive timestamps.}
7295 %i @r{Initial content, the region when capture is called while the}
7296 @r{region is active.}
7297 @r{The entire text will be indented like @code{%i} itself.}
7298 %a @r{Annotation, normally the link created with @code{org-store-link}.}
7299 %A @r{Like @code{%a}, but prompt for the description part.}
7300 %l @r{Like %a, but only insert the literal link.}
7301 %c @r{Current kill ring head.}
7302 %x @r{Content of the X clipboard.}
7303 %k @r{Title of the currently clocked task.}
7304 %K @r{Link to the currently clocked task.}
7305 %n @r{User name (taken from @code{user-full-name}).}
7306 %f @r{File visited by current buffer when org-capture was called.}
7307 %F @r{Full path of the file or directory visited by current buffer.}
7308 %:keyword @r{Specific information for certain link types, see below.}
7309 %^g @r{Prompt for tags, with completion on tags in target file.}
7310 %^G @r{Prompt for tags, with completion all tags in all agenda files.}
7311 %^t @r{Like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}.}
7312 @r{You may define a prompt like @code{%^@{Birthday@}t}.}
7313 %^C @r{Interactive selection of which kill or clip to use.}
7314 %^L @r{Like @code{%^C}, but insert as link.}
7315 %^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}.}
7316 %^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.}
7317 @r{You may specify a default value and a completion table with}
7318 @r{%^@{prompt|default|completion2|completion3...@}.}
7319 @r{The arrow keys access a prompt-specific history.}
7320 %\1 @dots{} %\N @r{Insert the text entered at the Nth %^@{@var{prompt}@}, where @code{N} is}
7321 @r{a number, starting from 1.@footnote{As required in Emacs
7322 Lisp, it is necessary to escape any backslash character in
7323 a string with another backslash. So, in order to use
7324 @samp{%\1} placeholder, you need to write @samp{%\\1} in
7326 %? @r{After completing the template, position cursor here.}
7330 For specific link types, the following keywords will be
7331 defined@footnote{If you define your own link types (@pxref{Adding
7332 hyperlink types}), any property you store with
7333 @code{org-store-link-props} can be accessed in capture templates in a
7336 @vindex org-from-is-user-regexp
7338 Link type | Available keywords
7339 ---------------------------------+----------------------------------------------
7340 bbdb | %:name %:company
7341 irc | %:server %:port %:nick
7342 vm, vm-imap, wl, mh, mew, rmail, | %:type %:subject %:message-id
7343 gnus, notmuch | %:from %:fromname %:fromaddress
7344 | %:to %:toname %:toaddress
7345 | %:date @r{(message date header field)}
7346 | %:date-timestamp @r{(date as active timestamp)}
7347 | %:date-timestamp-inactive @r{(date as inactive timestamp)}
7348 | %: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}.}}
7349 gnus | %:group, @r{for messages also all email fields}
7350 eww, w3, w3m | %:url
7351 info | %:file %:node
7353 org-protocol | %:link %:description %:annotation
7357 To place the cursor after template expansion use:
7360 %? @r{After completing the template, position cursor here.}
7363 @node Templates in contexts
7364 @subsubsection Templates in contexts
7366 @vindex org-capture-templates-contexts
7367 To control whether a capture template should be accessible from a specific
7368 context, you can customize @code{org-capture-templates-contexts}. Let's say
7369 for example that you have a capture template @code{"p"} for storing Gnus
7370 emails containing patches. Then you would configure this option like this:
7373 (setq org-capture-templates-contexts
7374 '(("p" (in-mode . "message-mode"))))
7377 You can also tell that the command key @code{"p"} should refer to another
7378 template. In that case, add this command key like this:
7381 (setq org-capture-templates-contexts
7382 '(("p" "q" (in-mode . "message-mode"))))
7385 See the docstring of the variable for more information.
7388 @section Attachments
7391 @vindex org-attach-directory
7392 It is often useful to associate reference material with an outline node/task.
7393 Small chunks of plain text can simply be stored in the subtree of a project.
7394 Hyperlinks (@pxref{Hyperlinks}) can establish associations with
7395 files that live elsewhere on your computer or in the cloud, like emails or
7396 source code files belonging to a project. Another method is @i{attachments},
7397 which are files located in a directory belonging to an outline node. Org
7398 uses directories named by the unique ID of each entry. These directories are
7399 located in the @file{data} directory which lives in the same directory where
7400 your Org file lives@footnote{If you move entries or Org files from one
7401 directory to another, you may want to configure @code{org-attach-directory}
7402 to contain an absolute path.}. If you initialize this directory with
7403 @code{git init}, Org will automatically commit changes when it sees them.
7404 The attachment system has been contributed to Org by John Wiegley.
7406 In cases where it seems better to do so, you can also attach a directory of your
7407 choice to an entry. You can also make children inherit the attachment
7408 directory from a parent, so that an entire subtree uses the same attached
7411 @noindent The following commands deal with attachments:
7414 @orgcmd{C-c C-a,org-attach}
7415 The dispatcher for commands related to the attachment system. After these
7416 keys, a list of commands is displayed and you must press an additional key
7417 to select a command:
7420 @orgcmdtkc{a,C-c C-a a,org-attach-attach}
7421 @vindex org-attach-method
7422 Select a file and move it into the task's attachment directory. The file
7423 will be copied, moved, or linked, depending on @code{org-attach-method}.
7424 Note that hard links are not supported on all systems.
7430 Attach a file using the copy/move/link method.
7431 Note that hard links are not supported on all systems.
7433 @orgcmdtkc{u,C-c C-a u,org-attach-url}
7434 Attach a file from URL
7436 @orgcmdtkc{n,C-c C-a n,org-attach-new}
7437 Create a new attachment as an Emacs buffer.
7439 @orgcmdtkc{z,C-c C-a z,org-attach-sync}
7440 Synchronize the current task with its attachment directory, in case you added
7441 attachments yourself.
7443 @orgcmdtkc{o,C-c C-a o,org-attach-open}
7444 @vindex org-file-apps
7445 Open current task's attachment. If there is more than one, prompt for a
7446 file name first. Opening will follow the rules set by @code{org-file-apps}.
7447 For more details, see the information on following hyperlinks
7448 (@pxref{Handling links}).
7450 @orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs}
7451 Also open the attachment, but force opening the file in Emacs.
7453 @orgcmdtkc{f,C-c C-a f,org-attach-reveal}
7454 Open the current task's attachment directory.
7456 @orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs}
7457 Also open the directory, but force using @command{dired} in Emacs.
7459 @orgcmdtkc{d,C-c C-a d,org-attach-delete-one}
7460 Select and delete a single attachment.
7462 @orgcmdtkc{D,C-c C-a D,org-attach-delete-all}
7463 Delete all of a task's attachments. A safer way is to open the directory in
7464 @command{dired} and delete from there.
7466 @orgcmdtkc{s,C-c C-a s,org-attach-set-directory}
7467 @cindex property, ATTACH_DIR
7468 Set a specific directory as the entry's attachment directory. This works by
7469 putting the directory path into the @code{ATTACH_DIR} property.
7471 @orgcmdtkc{i,C-c C-a i,org-attach-set-inherit}
7472 @cindex property, ATTACH_DIR_INHERIT
7473 Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the
7474 same directory for attachments as the parent does.
7483 Org can add and change entries based on information found in RSS feeds and
7484 Atom feeds. You could use this to make a task out of each new podcast in a
7485 podcast feed. Or you could use a phone-based note-creating service on the
7486 web to import tasks into Org. To access feeds, configure the variable
7487 @code{org-feed-alist}. The docstring of this variable has detailed
7488 information. Here is just an example:
7492 (setq org-feed-alist
7494 "http://rss.slashdot.org/Slashdot/slashdot"
7495 "~/txt/org/feeds.org" "Slashdot Entries")))
7500 will configure that new items from the feed provided by
7501 @code{rss.slashdot.org} will result in new entries in the file
7502 @file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
7503 the following command is used:
7506 @orgcmd{C-c C-x g,org-feed-update-all}
7508 Collect items from the feeds configured in @code{org-feed-alist} and act upon
7510 @orgcmd{C-c C-x G,org-feed-goto-inbox}
7511 Prompt for a feed name and go to the inbox configured for this feed.
7514 Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which
7515 it will store information about the status of items in the feed, to avoid
7516 adding the same item several times.
7518 For more information, including how to read atom feeds, see
7519 @file{org-feed.el} and the docstring of @code{org-feed-alist}.
7522 @section Protocols for external access
7523 @cindex protocols, for external access
7525 Org protocol is a mean to trigger custom actions in Emacs from external
7526 applications. Any application that supports calling external programs with
7527 an URL as argument may be used with this functionality. For example, you can
7528 configure bookmarks in your web browser to send a link to the current page to
7529 Org and create a note from it using capture (@pxref{Capture}). You can also
7530 create a bookmark that tells Emacs to open the local source file of a remote
7531 website you are browsing.
7533 @cindex Org protocol, set-up
7534 @cindex Installing Org protocol
7535 In order to use Org protocol from an application, you need to register
7536 @samp{org-protocol://} as a valid scheme-handler. External calls are passed
7537 to Emacs through the @code{emacsclient} command, so you also need to ensure
7538 an Emacs server is running. More precisely, when the application calls
7541 emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2
7545 Emacs calls the handler associated to @samp{PROTOCOL} with argument
7546 @samp{(:key1 val1 :key2 val2)}.
7548 @cindex protocol, new protocol
7549 @cindex defining new protocols
7550 Org protocol comes with three predefined protocols, detailed in the following
7551 sections. Configure @code{org-protocol-protocol-alist} to define your own.
7554 * @code{store-link} protocol:: Store a link, push URL to kill-ring.
7555 * @code{capture} protocol:: Fill a buffer with external information.
7556 * @code{open-source} protocol:: Edit published contents.
7559 @node @code{store-link} protocol
7560 @subsection @code{store-link} protocol
7561 @cindex store-link protocol
7562 @cindex protocol, store-link
7564 Using @code{store-link} handler, you can copy links, insertable through
7565 @kbd{M-x org-insert-link} or yanking thereafter. More precisely, the command
7568 emacsclient org-protocol://store-link?url=URL&title=TITLE
7572 stores the following link:
7578 In addition, @samp{URL} is pushed on the kill-ring for yanking. You need to
7579 encode @samp{URL} and @samp{TITLE} if they contain slashes, and probably
7580 quote those for the shell.
7582 To use this feature from a browser, add a bookmark with an arbitrary name,
7583 e.g., @samp{Org: store-link} and enter this as @emph{Location}:
7586 javascript:location.href='org-protocol://store-link?url='+
7587 encodeURIComponent(location.href);
7590 @node @code{capture} protocol
7591 @subsection @code{capture} protocol
7592 @cindex capture protocol
7593 @cindex protocol, capture
7595 Activating @code{capture} handler pops up a @samp{Capture} buffer and fills
7596 the capture template associated to the @samp{X} key with them.
7599 emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY
7602 To use this feature, add a bookmark with an arbitrary name, e.g. @samp{Org:
7603 capture} and enter this as @samp{Location}:
7606 javascript:location.href='org-protocol://template=x'+
7607 '&url='+encodeURIComponent(window.location.href)+
7608 '&title='+encodeURIComponent(document.title)+
7609 '&body='+encodeURIComponent(window.getSelection());
7612 @vindex org-protocol-default-template-key
7613 The result depends on the capture template used, which is set in the bookmark
7614 itself, as in the example above, or in
7615 @code{org-protocol-default-template-key}.
7617 @cindex capture, %:link placeholder
7618 @cindex %:link template expansion in capture
7619 @cindex capture, %:description placeholder
7620 @cindex %:description template expansion in capture
7621 @cindex capture, %:annotation placeholder
7622 @cindex %:annotation template expansion in capture
7623 The following template placeholders are available:
7627 %:description The webpage title
7628 %:annotation Equivalent to [[%:link][%:description]]
7629 %i The selected text
7632 @node @code{open-source} protocol
7633 @subsection @code{open-source} protocol
7634 @cindex open-source protocol
7635 @cindex protocol, open-source
7637 The @code{open-source} handler is designed to help with editing local sources
7638 when reading a document. To that effect, you can use a bookmark with the
7642 javascript:location.href='org-protocol://open-source?&url='+
7643 encodeURIComponent(location.href)
7646 @cindex protocol, open-source, :base-url property
7647 @cindex :base-url property in open-source protocol
7648 @cindex protocol, open-source, :working-directory property
7649 @cindex :working-directory property in open-source protocol
7650 @cindex protocol, open-source, :online-suffix property
7651 @cindex :online-suffix property in open-source protocol
7652 @cindex protocol, open-source, :working-suffix property
7653 @cindex :working-suffix property in open-source protocol
7654 @vindex org-protocol-project-alist
7655 The variable @code{org-protocol-project-alist} maps URLs to local file names,
7656 by stripping URL parameters from the end and replacing the @code{:base-url}
7657 with @code{:working-directory} and @code{:online-suffix} with
7658 @code{:working-suffix}. For example, assuming you own a local copy of
7659 @url{http://orgmode.org/worg/} contents at @file{/home/user/worg}, you can
7660 set @code{org-protocol-project-alist} to the following
7663 (setq org-protocol-project-alist
7665 :base-url "http://orgmode.org/worg/"
7666 :working-directory "/home/user/worg/"
7667 :online-suffix ".html"
7668 :working-suffix ".org")))
7672 If you are now browsing
7673 @url{http://orgmode.org/worg/org-contrib/org-protocol.html} and find a typo
7674 or have an idea about how to enhance the documentation, simply click the
7675 bookmark and start editing.
7677 @cindex handle rewritten URL in open-source protocol
7678 @cindex protocol, open-source rewritten URL
7679 However, such mapping may not yield the desired results. Suppose you
7680 maintain an online store located at @url{http://example.com/}. The local
7681 sources reside in @file{/home/user/example/}. It is common practice to serve
7682 all products in such a store through one file and rewrite URLs that do not
7683 match an existing file on the server. That way, a request to
7684 @url{http://example.com/print/posters.html} might be rewritten on the server
7686 @url{http://example.com/shop/products.php/posters.html.php}. The
7687 @code{open-source} handler probably cannot find a file named
7688 @file{/home/user/example/print/posters.html.php} and fails.
7690 @cindex protocol, open-source, :rewrites property
7691 @cindex :rewrites property in open-source protocol
7692 Such an entry in @code{org-protocol-project-alist} may hold an additional
7693 property @code{:rewrites}. This property is a list of cons cells, each of
7694 which maps a regular expression to a path relative to the
7695 @code{:working-directory}.
7697 Now map the URL to the path @file{/home/user/example/products.php} by adding
7698 @code{:rewrites} rules like this:
7701 (setq org-protocol-project-alist
7703 :base-url "http://example.com/"
7704 :working-directory "/home/user/example/"
7705 :online-suffix ".php"
7706 :working-suffix ".php"
7707 :rewrites (("example.com/print/" . "products.php")
7708 ("example.com/$" . "index.php")))))
7712 Since @samp{example.com/$} is used as a regular expression, it maps
7713 @url{http://example.com/}, @url{https://example.com},
7714 @url{http://www.example.com/} and similar to
7715 @file{/home/user/example/index.php}.
7717 The @code{:rewrites} rules are searched as a last resort if and only if no
7718 existing file name is matched.
7720 @cindex protocol, open-source, set-up mapping
7721 @cindex set-up mappings in open-source protocol
7722 @findex org-protocol-create
7723 @findex org-protocol-create-for-org
7724 Two functions can help you filling @code{org-protocol-project-alist} with
7725 valid contents: @code{org-protocol-create} and
7726 @code{org-protocol-create-for-org}. The latter is of use if you're editing
7727 an Org file that is part of a publishing project.
7729 @node Refile and copy
7730 @section Refile and copy
7731 @cindex refiling notes
7732 @cindex copying notes
7734 When reviewing the captured data, you may want to refile or to copy some of
7735 the entries into a different list, for example into a project. Cutting,
7736 finding the right location, and then pasting the note is cumbersome. To
7737 simplify this process, you can use the following special command:
7740 @orgcmd{C-c M-w,org-copy}
7742 Copying works like refiling, except that the original note is not deleted.
7743 @orgcmd{C-c C-w,org-refile}
7745 @vindex org-reverse-note-order
7746 @vindex org-refile-targets
7747 @vindex org-refile-use-outline-path
7748 @vindex org-outline-path-complete-in-steps
7749 @vindex org-refile-allow-creating-parent-nodes
7750 @vindex org-log-refile
7751 @vindex org-refile-use-cache
7752 @vindex org-refile-keep
7753 Refile the entry or region at point. This command offers possible locations
7754 for refiling the entry and lets you select one with completion. The item (or
7755 all items in the region) is filed below the target heading as a subitem.
7756 Depending on @code{org-reverse-note-order}, it will be either the first or
7758 By default, all level 1 headlines in the current buffer are considered to be
7759 targets, but you can have more complex definitions across a number of files.
7760 See the variable @code{org-refile-targets} for details. If you would like to
7761 select a location via a file-path-like completion along the outline path, see
7762 the variables @code{org-refile-use-outline-path} and
7763 @code{org-outline-path-complete-in-steps}. If you would like to be able to
7764 create new nodes as new parents for refiling on the fly, check the
7765 variable @code{org-refile-allow-creating-parent-nodes}.
7766 When the variable @code{org-log-refile}@footnote{with corresponding
7767 @code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},
7768 and @code{nologrefile}} is set, a timestamp or a note will be
7769 recorded when an entry has been refiled.
7770 @orgkey{C-u C-c C-w}
7771 Use the refile interface to jump to a heading.
7772 @orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored}
7773 Jump to the location where @code{org-refile} last moved a tree to.
7775 Refile as the child of the item currently being clocked.
7777 Refile and keep the entry in place. Also see @code{org-refile-keep} to make
7778 this the default behavior, and beware that this may result in duplicated
7779 @code{ID} properties.
7780 @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}
7781 Clear the target cache. Caching of refile targets can be turned on by
7782 setting @code{org-refile-use-cache}. To make the command see new possible
7783 targets, you have to clear the cache with this command.
7790 When a project represented by a (sub)tree is finished, you may want
7791 to move the tree out of the way and to stop it from contributing to the
7792 agenda. Archiving is important to keep your working files compact and global
7793 searches like the construction of agenda views fast.
7796 @orgcmd{C-c C-x C-a,org-archive-subtree-default}
7797 @vindex org-archive-default-command
7798 Archive the current entry using the command specified in the variable
7799 @code{org-archive-default-command}.
7803 * Moving subtrees:: Moving a tree to an archive file
7804 * Internal archiving:: Switch off a tree but keep it in the file
7807 @node Moving subtrees
7808 @subsection Moving a tree to the archive file
7809 @cindex external archiving
7811 The most common archiving action is to move a project tree to another file,
7815 @orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
7816 @vindex org-archive-location
7817 Archive the subtree starting at the cursor position to the location
7818 given by @code{org-archive-location}.
7819 @orgkey{C-u C-c C-x C-s}
7820 Check if any direct children of the current headline could be moved to
7821 the archive. To do this, each subtree is checked for open TODO entries.
7822 If none are found, the command offers to move it to the archive
7823 location. If the cursor is @emph{not} on a headline when this command
7824 is invoked, the level 1 trees will be checked.
7825 @orgkey{C-u C-u C-c C-x C-s}
7826 As above, but check subtree for timestamps instead of TODO entries. The
7827 command will offer to archive the subtree if it @emph{does} contain a
7828 timestamp, and that timestamp is in the past.
7831 @cindex archive locations
7832 The default archive location is a file in the same directory as the
7833 current file, with the name derived by appending @file{_archive} to the
7834 current file name. You can also choose what heading to file archived
7835 items under, with the possibility to add them to a datetree in a file.
7836 For information and examples on how to specify the file and the heading,
7837 see the documentation string of the variable
7838 @code{org-archive-location}.
7840 There is also an in-buffer option for setting this variable, for example:
7844 #+ARCHIVE: %s_done::
7847 @cindex property, ARCHIVE
7849 If you would like to have a special ARCHIVE location for a single entry
7850 or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
7851 location as the value (@pxref{Properties and columns}).
7853 @vindex org-archive-save-context-info
7854 When a subtree is moved, it receives a number of special properties that
7855 record context information like the file from where the entry came, its
7856 outline path the archiving time etc. Configure the variable
7857 @code{org-archive-save-context-info} to adjust the amount of information
7861 @node Internal archiving
7862 @subsection Internal archiving
7865 If you want to just switch off---for agenda views---certain subtrees without
7866 moving them to a different file, you can use the archive tag.
7868 A headline that is marked with the @samp{:ARCHIVE:} tag (@pxref{Tags}) stays
7869 at its location in the outline tree, but behaves in the following way:
7872 @vindex org-cycle-open-archived-trees
7873 It does not open when you attempt to do so with a visibility cycling
7874 command (@pxref{Visibility cycling}). You can force cycling archived
7875 subtrees with @kbd{C-@key{TAB}}, or by setting the option
7876 @code{org-cycle-open-archived-trees}. Also normal outline commands like
7877 @code{show-all} will open archived subtrees.
7879 @vindex org-sparse-tree-open-archived-trees
7880 During sparse tree construction (@pxref{Sparse trees}), matches in
7881 archived subtrees are not exposed, unless you configure the option
7882 @code{org-sparse-tree-open-archived-trees}.
7884 @vindex org-agenda-skip-archived-trees
7885 During agenda view construction (@pxref{Agenda views}), the content of
7886 archived trees is ignored unless you configure the option
7887 @code{org-agenda-skip-archived-trees}, in which case these trees will always
7888 be included. In the agenda you can press @kbd{v a} to get archives
7889 temporarily included.
7891 @vindex org-export-with-archived-trees
7892 Archived trees are not exported (@pxref{Exporting}), only the headline
7893 is. Configure the details using the variable
7894 @code{org-export-with-archived-trees}.
7896 @vindex org-columns-skip-archived-trees
7897 Archived trees are excluded from column view unless the variable
7898 @code{org-columns-skip-archived-trees} is configured to @code{nil}.
7901 The following commands help manage the ARCHIVE tag:
7904 @orgcmd{C-c C-x a,org-toggle-archive-tag}
7905 Toggle the ARCHIVE tag for the current headline. When the tag is set,
7906 the headline changes to a shadowed face, and the subtree below it is
7908 @orgkey{C-u C-c C-x a}
7909 Check if any direct children of the current headline should be archived.
7910 To do this, each subtree is checked for open TODO entries. If none are
7911 found, the command offers to set the ARCHIVE tag for the child. If the
7912 cursor is @emph{not} on a headline when this command is invoked, the
7913 level 1 trees will be checked.
7914 @orgcmd{C-@kbd{TAB},org-force-cycle-archived}
7915 Cycle a tree even if it is tagged with ARCHIVE.
7916 @orgcmd{C-c C-x A,org-archive-to-archive-sibling}
7917 Move the current entry to the @emph{Archive Sibling}. This is a sibling of
7918 the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The
7919 entry becomes a child of that sibling and in this way retains a lot of its
7920 original context, including inherited tags and approximate position in the
7926 @chapter Agenda views
7927 @cindex agenda views
7929 Due to the way Org works, TODO items, time-stamped items, and
7930 tagged headlines can be scattered throughout a file or even a number of
7931 files. To get an overview of open action items, or of events that are
7932 important for a particular date, this information must be collected,
7933 sorted and displayed in an organized way.
7935 Org can select items based on various criteria and display them
7936 in a separate buffer. Six different view types are provided:
7940 an @emph{agenda} that is like a calendar and shows information
7943 a @emph{TODO list} that covers all unfinished
7946 a @emph{match view}, showings headlines based on the tags, properties, and
7947 TODO state associated with them,
7949 a @emph{text search view} that shows all entries from multiple files
7950 that contain specified keywords,
7952 a @emph{stuck projects view} showing projects that currently don't move
7955 @emph{custom views} that are special searches and combinations of different
7960 The extracted information is displayed in a special @emph{agenda
7961 buffer}. This buffer is read-only, but provides commands to visit the
7962 corresponding locations in the original Org files, and even to
7963 edit these files remotely.
7965 @vindex org-agenda-skip-comment-trees
7966 @vindex org-agenda-skip-archived-trees
7967 @cindex commented entries, in agenda views
7968 @cindex archived entries, in agenda views
7969 By default, the report ignores commented (@pxref{Comment lines}) and archived
7970 (@pxref{Internal archiving}) entries. You can override this by setting
7971 @code{org-agenda-skip-comment-trees} and
7972 @code{org-agenda-skip-archived-trees} to @code{nil}.
7974 @vindex org-agenda-window-setup
7975 @vindex org-agenda-restore-windows-after-quit
7976 Two variables control how the agenda buffer is displayed and whether the
7977 window configuration is restored when the agenda exits:
7978 @code{org-agenda-window-setup} and
7979 @code{org-agenda-restore-windows-after-quit}.
7982 * Agenda files:: Files being searched for agenda information
7983 * Agenda dispatcher:: Keyboard access to agenda views
7984 * Built-in agenda views:: What is available out of the box?
7985 * Presentation and sorting:: How agenda items are prepared for display
7986 * Agenda commands:: Remote editing of Org trees
7987 * Custom agenda views:: Defining special searches and views
7988 * Exporting agenda views:: Writing a view to a file
7989 * Agenda column view:: Using column view for collected entries
7993 @section Agenda files
7994 @cindex agenda files
7995 @cindex files for agenda
7997 @vindex org-agenda-files
7998 The information to be shown is normally collected from all @emph{agenda
7999 files}, the files listed in the variable
8000 @code{org-agenda-files}@footnote{If the value of that variable is not a
8001 list, but a single file name, then the list of agenda files will be
8002 maintained in that external file.}. If a directory is part of this list,
8003 all files with the extension @file{.org} in this directory will be part
8006 Thus, even if you only work with a single Org file, that file should
8007 be put into the list@footnote{When using the dispatcher, pressing
8008 @kbd{<} before selecting a command will actually limit the command to
8009 the current file, and ignore @code{org-agenda-files} until the next
8010 dispatcher command.}. You can customize @code{org-agenda-files}, but
8011 the easiest way to maintain it is through the following commands
8013 @cindex files, adding to agenda list
8015 @orgcmd{C-c [,org-agenda-file-to-front}
8016 Add current file to the list of agenda files. The file is added to
8017 the front of the list. If it was already in the list, it is moved to
8018 the front. With a prefix argument, file is added/moved to the end.
8019 @orgcmd{C-c ],org-remove-file}
8020 Remove current file from the list of agenda files.
8022 @cindex cycling, of agenda files
8023 @orgcmd{C-',org-cycle-agenda-files}
8025 Cycle through agenda file list, visiting one file after the other.
8026 @kindex M-x org-iswitchb
8027 @item M-x org-iswitchb RET
8028 Command to use an @code{iswitchb}-like interface to switch to and between Org
8033 The Org menu contains the current list of files and can be used
8034 to visit any of them.
8036 If you would like to focus the agenda temporarily on a file not in
8037 this list, or on just one file in the list, or even on only a subtree in a
8038 file, then this can be done in different ways. For a single agenda command,
8039 you may press @kbd{<} once or several times in the dispatcher
8040 (@pxref{Agenda dispatcher}). To restrict the agenda scope for an
8041 extended period, use the following commands:
8044 @orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
8045 Permanently restrict the agenda to the current subtree. When with a
8046 prefix argument, or with the cursor before the first headline in a file,
8047 the agenda scope is set to the entire file. This restriction remains in
8048 effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
8049 or @kbd{>} in the agenda dispatcher. If there is a window displaying an
8050 agenda view, the new restriction takes effect immediately.
8051 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
8052 Remove the permanent restriction created by @kbd{C-c C-x <}.
8056 When working with @file{speedbar.el}, you can use the following commands in
8060 @orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
8061 Permanently restrict the agenda to the item---either an Org file or a subtree
8062 in such a file---at the cursor in the Speedbar frame.
8063 If there is a window displaying an agenda view, the new restriction takes
8065 @orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
8066 Lift the restriction.
8069 @node Agenda dispatcher
8070 @section The agenda dispatcher
8071 @cindex agenda dispatcher
8072 @cindex dispatching agenda commands
8073 The views are created through a dispatcher, which should be bound to a
8074 global key---for example @kbd{C-c a} (@pxref{Activation}). In the
8075 following we will assume that @kbd{C-c a} is indeed how the dispatcher
8076 is accessed and list keyboard access to commands accordingly. After
8077 pressing @kbd{C-c a}, an additional letter is required to execute a
8078 command. The dispatcher offers the following default commands:
8082 Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
8084 Create a list of all TODO items (@pxref{Global TODO list}).
8086 Create a list of headlines matching a TAGS expression (@pxref{Matching
8087 tags and properties}).
8089 Create a list of entries selected by a boolean expression of keywords
8090 and/or regular expressions that must or must not occur in the entry.
8092 @vindex org-agenda-text-search-extra-files
8093 Search for a regular expression in all agenda files and additionally in
8094 the files listed in @code{org-agenda-text-search-extra-files}. This
8095 uses the Emacs command @code{multi-occur}. A prefix argument can be
8096 used to specify the number of context lines for each match, default is
8099 Create a list of stuck projects (@pxref{Stuck projects}).
8101 Restrict an agenda command to the current buffer@footnote{For backward
8102 compatibility, you can also press @kbd{1} to restrict to the current
8103 buffer.}. After pressing @kbd{<}, you still need to press the character
8104 selecting the command.
8106 If there is an active region, restrict the following agenda command to
8107 the region. Otherwise, restrict it to the current subtree@footnote{For
8108 backward compatibility, you can also press @kbd{0} to restrict to the
8109 current region/subtree.}. After pressing @kbd{< <}, you still need to press the
8110 character selecting the command.
8113 @cindex agenda, sticky
8114 @vindex org-agenda-sticky
8115 Toggle sticky agenda views. By default, Org maintains only a single agenda
8116 buffer and rebuilds it each time you change the view, to make sure everything
8117 is always up to date. If you often switch between agenda views and the build
8118 time bothers you, you can turn on sticky agenda buffers or make this the
8119 default by customizing the variable @code{org-agenda-sticky}. With sticky
8120 agendas, the agenda dispatcher will not recreate agenda views from scratch,
8121 it will only switch to the selected one, and you need to update the agenda by
8122 hand with @kbd{r} or @kbd{g} when needed. You can toggle sticky agenda view
8123 any time with @code{org-toggle-sticky-agenda}.
8126 You can also define custom commands that will be accessible through the
8127 dispatcher, just like the default commands. This includes the
8128 possibility to create extended agenda buffers that contain several
8129 blocks together, for example the weekly agenda, the global TODO list and
8130 a number of special tags matches. @xref{Custom agenda views}.
8132 @node Built-in agenda views
8133 @section The built-in agenda views
8135 In this section we describe the built-in views.
8138 * Weekly/daily agenda:: The calendar page with current tasks
8139 * Global TODO list:: All unfinished action items
8140 * Matching tags and properties:: Structured information with fine-tuned search
8141 * Search view:: Find entries by searching for text
8142 * Stuck projects:: Find projects you need to review
8145 @node Weekly/daily agenda
8146 @subsection The weekly/daily agenda
8148 @cindex weekly agenda
8149 @cindex daily agenda
8151 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
8152 paper agenda, showing all the tasks for the current week or day.
8155 @cindex org-agenda, command
8156 @orgcmd{C-c a a,org-agenda-list}
8157 Compile an agenda for the current week from a list of Org files. The agenda
8158 shows the entries for each day. With a numeric prefix@footnote{For backward
8159 compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be
8160 listed before the agenda. This feature is deprecated, use the dedicated TODO
8161 list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1
8162 C-c a a}) you may set the number of days to be displayed.
8165 @vindex org-agenda-span
8166 @vindex org-agenda-ndays
8167 @vindex org-agenda-start-day
8168 @vindex org-agenda-start-on-weekday
8169 The default number of days displayed in the agenda is set by the variable
8170 @code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This
8171 variable can be set to any number of days you want to see by default in the
8172 agenda, or to a span name, such as @code{day}, @code{week}, @code{month} or
8173 @code{year}. For weekly agendas, the default is to start on the previous
8174 monday (see @code{org-agenda-start-on-weekday}). You can also set the start
8175 date using a date shift: @code{(setq org-agenda-start-day "+10d")} will
8176 start the agenda ten days from today in the future.
8178 Remote editing from the agenda buffer means, for example, that you can
8179 change the dates of deadlines and appointments from the agenda buffer.
8180 The commands available in the Agenda buffer are listed in @ref{Agenda
8183 @subsubheading Calendar/Diary integration
8184 @cindex calendar integration
8185 @cindex diary integration
8187 Emacs contains the calendar and diary by Edward M. Reingold. The
8188 calendar displays a three-month calendar with holidays from different
8189 countries and cultures. The diary allows you to keep track of
8190 anniversaries, lunar phases, sunrise/set, recurrent appointments
8191 (weekly, monthly) and more. In this way, it is quite complementary to
8192 Org. It can be very useful to combine output from Org with
8195 In order to include entries from the Emacs diary into Org mode's
8196 agenda, you only need to customize the variable
8199 (setq org-agenda-include-diary t)
8202 @noindent After that, everything will happen automatically. All diary
8203 entries including holidays, anniversaries, etc., will be included in the
8204 agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and
8205 @key{RET} can be used from the agenda buffer to jump to the diary
8206 file in order to edit existing diary entries. The @kbd{i} command to
8207 insert new entries for the current date works in the agenda buffer, as
8208 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
8209 Sunrise/Sunset times, show lunar phases and to convert to other
8210 calendars, respectively. @kbd{c} can be used to switch back and forth
8211 between calendar and agenda.
8213 If you are using the diary only for sexp entries and holidays, it is
8214 faster to not use the above setting, but instead to copy or even move
8215 the entries into an Org file. Org mode evaluates diary-style sexp
8216 entries, and does it faster because there is no overhead for first
8217 creating the diary display. Note that the sexp entries must start at
8218 the left margin, no whitespace is allowed before them. For example,
8219 the following segment of an Org file will be processed and entries
8220 will be made in the agenda:
8227 %%(org-calendar-holiday) ; special function for holiday names
8233 %%(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
8234 %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
8237 @subsubheading Anniversaries from BBDB
8238 @cindex BBDB, anniversaries
8239 @cindex anniversaries, from BBDB
8241 If you are using the Big Brothers Database to store your contacts, you will
8242 very likely prefer to store anniversaries in BBDB rather than in a
8243 separate Org or diary file. Org supports this and will show BBDB
8244 anniversaries as part of the agenda. All you need to do is to add the
8245 following to one of your agenda files:
8252 %%(org-bbdb-anniversaries)
8255 You can then go ahead and define anniversaries for a BBDB record. Basically,
8256 you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
8257 record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
8258 followed by a space and the class of the anniversary (@samp{birthday} or
8259 @samp{wedding}, or a format string). If you omit the class, it will default to
8260 @samp{birthday}. Here are a few examples, the header for the file
8261 @file{org-bbdb.el} contains more detailed information.
8267 2008-04-14 %s released version 6.01 of org mode, %d years ago
8270 After a change to BBDB, or for the first agenda display during an Emacs
8271 session, the agenda display will suffer a short delay as Org updates its
8272 hash with anniversaries. However, from then on things will be very fast---much
8273 faster in fact than a long list of @samp{%%(diary-anniversary)} entries
8274 in an Org or Diary file.
8276 If you would like to see upcoming anniversaries with a bit of forewarning,
8277 you can use the following instead:
8284 %%(org-bbdb-anniversaries-future 3)
8287 That will give you three days' warning: on the anniversary date itself and the
8288 two days prior. The argument is optional: if omitted, it defaults to 7.
8290 @subsubheading Appointment reminders
8291 @cindex @file{appt.el}
8292 @cindex appointment reminders
8296 Org can interact with Emacs appointments notification facility. To add the
8297 appointments of your agenda files, use the command @code{org-agenda-to-appt}.
8298 This command lets you filter through the list of your appointments and add
8299 only those belonging to a specific category or matching a regular expression.
8300 It also reads a @code{APPT_WARNTIME} property which will then override the
8301 value of @code{appt-message-warning-time} for this appointment. See the
8302 docstring for details.
8304 @node Global TODO list
8305 @subsection The global TODO list
8306 @cindex global TODO list
8307 @cindex TODO list, global
8309 The global TODO list contains all unfinished TODO items formatted and
8310 collected into a single place.
8313 @orgcmd{C-c a t,org-todo-list}
8314 Show the global TODO list. This collects the TODO items from all agenda
8315 files (@pxref{Agenda views}) into a single buffer. By default, this lists
8316 items with a state the is not a DONE state. The buffer is in
8317 @code{agenda-mode}, so there are commands to examine and manipulate the TODO
8318 entries directly from that buffer (@pxref{Agenda commands}).
8319 @orgcmd{C-c a T,org-todo-list}
8320 @cindex TODO keyword matching
8321 @vindex org-todo-keywords
8322 Like the above, but allows selection of a specific TODO keyword. You can
8323 also do this by specifying a prefix argument to @kbd{C-c a t}. You are
8324 prompted for a keyword, and you may also specify several keywords by
8325 separating them with @samp{|} as the boolean OR operator. With a numeric
8326 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
8328 The @kbd{r} key in the agenda buffer regenerates it, and you can give
8329 a prefix argument to this command to change the selected TODO keyword,
8330 for example @kbd{3 r}. If you often need a search for a specific
8331 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
8332 Matching specific TODO keywords can also be done as part of a tags
8333 search (@pxref{Tag searches}).
8336 Remote editing of TODO items means that you can change the state of a
8337 TODO entry with a single key press. The commands available in the
8338 TODO list are described in @ref{Agenda commands}.
8340 @cindex sublevels, inclusion into TODO list
8341 Normally the global TODO list simply shows all headlines with TODO
8342 keywords. This list can become very long. There are two ways to keep
8346 @vindex org-agenda-todo-ignore-scheduled
8347 @vindex org-agenda-todo-ignore-deadlines
8348 @vindex org-agenda-todo-ignore-timestamp
8349 @vindex org-agenda-todo-ignore-with-date
8350 Some people view a TODO item that has been @emph{scheduled} for execution or
8351 have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.
8352 Configure the variables @code{org-agenda-todo-ignore-scheduled},
8353 @code{org-agenda-todo-ignore-deadlines},
8354 @code{org-agenda-todo-ignore-timestamp} and/or
8355 @code{org-agenda-todo-ignore-with-date} to exclude such items from the global
8358 @vindex org-agenda-todo-list-sublevels
8359 TODO items may have sublevels to break up the task into subtasks. In
8360 such cases it may be enough to list only the highest level TODO headline
8361 and omit the sublevels from the global list. Configure the variable
8362 @code{org-agenda-todo-list-sublevels} to get this behavior.
8365 @node Matching tags and properties
8366 @subsection Matching tags and properties
8367 @cindex matching, of tags
8368 @cindex matching, of properties
8372 If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
8373 or have properties (@pxref{Properties and columns}), you can select headlines
8374 based on this metadata and collect them into an agenda buffer. The match
8375 syntax described here also applies when creating sparse trees with @kbd{C-c /
8379 @orgcmd{C-c a m,org-tags-view}
8380 Produce a list of all headlines that match a given set of tags. The
8381 command prompts for a selection criterion, which is a boolean logic
8382 expression with tags, like @samp{+work+urgent-withboss} or
8383 @samp{work|home} (@pxref{Tags}). If you often need a specific search,
8384 define a custom command for it (@pxref{Agenda dispatcher}).
8385 @orgcmd{C-c a M,org-tags-view}
8386 @vindex org-tags-match-list-sublevels
8387 @vindex org-agenda-tags-todo-honor-ignore-options
8388 Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
8389 not-DONE state and force checking subitems (see variable
8390 @code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items,
8391 see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching
8392 specific TODO keywords together with a tags match is also possible, see
8396 The commands available in the tags list are described in @ref{Agenda
8399 @subsubheading Match syntax
8401 @cindex Boolean logic, for tag/property searches
8402 A search string can use Boolean operators @samp{&} for @code{AND} and
8403 @samp{|} for @code{OR}@. @samp{&} binds more strongly than @samp{|}.
8404 Parentheses are not implemented. Each element in the search is either a
8405 tag, a regular expression matching tags, or an expression like
8406 @code{PROPERTY OPERATOR VALUE} with a comparison operator, accessing a
8407 property value. Each element may be preceded by @samp{-}, to select
8408 against it, and @samp{+} is syntactic sugar for positive selection. The
8409 @code{AND} operator @samp{&} is optional when @samp{+} or @samp{-} is
8410 present. Here are some examples, using only tags.
8414 Select headlines tagged @samp{:work:}.
8416 Select headlines tagged @samp{:work:} and @samp{:boss:}.
8418 Select headlines tagged @samp{:work:}, but discard those also tagged
8421 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
8422 @item work|laptop+night
8423 Like before, but require the @samp{:laptop:} lines to be tagged also
8427 @cindex regular expressions, with tags search
8428 Instead of a tag, you may also specify a regular expression enclosed in curly
8429 braces. For example,
8430 @samp{work+@{^boss.*@}} matches headlines that contain the tag
8431 @samp{:work:} and any tag @i{starting} with @samp{boss}.
8433 @cindex group tags, as regular expressions
8434 Group tags (@pxref{Tag hierarchy}) are expanded as regular expressions. E.g.,
8435 if @samp{:work:} is a group tag for the group @samp{:work:lab:conf:}, then
8436 searching for @samp{work} will search for @samp{@{\(?:work\|lab\|conf\)@}}
8437 and searching for @samp{-work} will search for all headlines but those with
8438 one of the tags in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}).
8440 @cindex TODO keyword matching, with tags search
8441 @cindex level, require for tags/property match
8442 @cindex category, require for tags/property match
8443 @vindex org-odd-levels-only
8444 You may also test for properties (@pxref{Properties and columns}) at the same
8445 time as matching tags. The properties may be real properties, or special
8446 properties that represent other metadata (@pxref{Special properties}). For
8447 example, the ``property'' @code{TODO} represents the TODO keyword of the
8448 entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of
8451 In addition to the properties mentioned above, @code{LEVEL} represents the
8452 level of an entry. So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all
8453 level three headlines that have the tag @samp{boss} and are @emph{not} marked
8454 with the TODO keyword DONE@. In buffers with @code{org-odd-levels-only} set,
8455 @samp{LEVEL} does not count the number of stars, but @samp{LEVEL=2} will
8456 correspond to 3 stars etc.
8458 Here are more examples:
8461 @item work+TODO="WAITING"
8462 Select @samp{:work:}-tagged TODO lines with the specific TODO
8463 keyword @samp{WAITING}.
8464 @item work+TODO="WAITING"|home+TODO="WAITING"
8465 Waiting tasks both at work and at home.
8468 When matching properties, a number of different operators can be used to test
8469 the value of a property. Here is a complex example:
8472 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \
8473 +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
8477 The type of comparison will depend on how the comparison value is written:
8480 If the comparison value is a plain number, a numerical comparison is done,
8481 and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
8482 @samp{>=}, and @samp{<>}.
8484 If the comparison value is enclosed in double-quotes,
8485 a string comparison is done, and the same operators are allowed.
8487 If the comparison value is enclosed in double-quotes @emph{and} angular
8488 brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
8489 assumed to be date/time specifications in the standard Org way, and the
8490 comparison will be done accordingly. Special values that will be recognized
8491 are @code{"<now>"} for now (including time), and @code{"<today>"}, and
8492 @code{"<tomorrow>"} for these days at 00:00 hours, i.e., without a time
8493 specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
8494 @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
8495 respectively, can be used.
8497 If the comparison value is enclosed
8498 in curly braces, a regexp match is performed, with @samp{=} meaning that the
8499 regexp matches the property value, and @samp{<>} meaning that it does not
8503 So the search string in the example finds entries tagged @samp{:work:} but
8504 not @samp{:boss:}, which also have a priority value @samp{A}, a
8505 @samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
8506 property that is numerically smaller than 2, a @samp{:With:} property that is
8507 matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
8508 on or after October 11, 2008.
8510 You can configure Org mode to use property inheritance during a search, but
8511 beware that this can slow down searches considerably. See @ref{Property
8512 inheritance}, for details.
8514 For backward compatibility, and also for typing speed, there is also a
8515 different way to test TODO states in a search. For this, terminate the
8516 tags/property part of the search string (which may include several terms
8517 connected with @samp{|}) with a @samp{/} and then specify a Boolean
8518 expression just for TODO keywords. The syntax is then similar to that for
8519 tags, but should be applied with care: for example, a positive selection on
8520 several TODO keywords cannot meaningfully be combined with boolean AND@.
8521 However, @emph{negative selection} combined with AND can be meaningful. To
8522 make sure that only lines are checked that actually have any TODO keyword
8523 (resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
8524 part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will
8525 not match TODO keywords in a DONE state. Examples:
8529 Same as @samp{work+TODO="WAITING"}
8530 @item work/!-WAITING-NEXT
8531 Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
8533 @item work/!+WAITING|+NEXT
8534 Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
8539 @subsection Search view
8542 @cindex searching, for text
8544 This agenda view is a general text search facility for Org mode entries.
8545 It is particularly useful to find notes.
8548 @orgcmd{C-c a s,org-search-view}
8549 This is a special search that lets you select entries by matching a substring
8550 or specific words using a boolean logic.
8552 For example, the search string @samp{computer equipment} will find entries
8553 that contain @samp{computer equipment} as a substring. If the two words are
8554 separated by more space or a line break, the search will still match.
8555 Search view can also search for specific keywords in the entry, using Boolean
8556 logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
8557 will search for note entries that contain the keywords @code{computer}
8558 and @code{wifi}, but not the keyword @code{ethernet}, and which are also
8559 not matched by the regular expression @code{8\.11[bg]}, meaning to
8560 exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on
8561 word search, other @samp{+} characters are optional. For more details, see
8562 the docstring of the command @code{org-search-view}.
8564 @vindex org-agenda-text-search-extra-files
8565 Note that in addition to the agenda files, this command will also search
8566 the files listed in @code{org-agenda-text-search-extra-files}.
8568 @node Stuck projects
8569 @subsection Stuck projects
8570 @pindex GTD, Getting Things Done
8572 If you are following a system like David Allen's GTD to organize your
8573 work, one of the ``duties'' you have is a regular review to make sure
8574 that all projects move along. A @emph{stuck} project is a project that
8575 has no defined next actions, so it will never show up in the TODO lists
8576 Org mode produces. During the review, you need to identify such
8577 projects and define next actions for them.
8580 @orgcmd{C-c a #,org-agenda-list-stuck-projects}
8581 List projects that are stuck.
8584 @vindex org-stuck-projects
8585 Customize the variable @code{org-stuck-projects} to define what a stuck
8586 project is and how to find it.
8589 You almost certainly will have to configure this view before it will
8590 work for you. The built-in default assumes that all your projects are
8591 level-2 headlines, and that a project is not stuck if it has at least
8592 one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
8594 Let's assume that you, in your own way of using Org mode, identify
8595 projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
8596 indicate a project that should not be considered yet. Let's further
8597 assume that the TODO keyword DONE marks finished projects, and that NEXT
8598 and TODO indicate next actions. The tag @@SHOP indicates shopping and
8599 is a next action even without the NEXT tag. Finally, if the project
8600 contains the special word IGNORE anywhere, it should not be listed
8601 either. In this case you would start by identifying eligible projects
8602 with a tags/todo match@footnote{@xref{Tag searches}.}
8603 @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, and
8604 IGNORE in the subtree to identify projects that are not stuck. The
8605 correct customization for this is
8608 (setq org-stuck-projects
8609 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
8613 Note that if a project is identified as non-stuck, the subtree of this entry
8614 will still be searched for stuck projects.
8616 @node Presentation and sorting
8617 @section Presentation and sorting
8618 @cindex presentation, of agenda items
8620 @vindex org-agenda-prefix-format
8621 @vindex org-agenda-tags-column
8622 Before displaying items in an agenda view, Org mode visually prepares the
8623 items and sorts them. Each item occupies a single line. The line starts
8624 with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
8625 of the item and other important information. You can customize in which
8626 column tags will be displayed through @code{org-agenda-tags-column}. You can
8627 also customize the prefix using the option @code{org-agenda-prefix-format}.
8628 This prefix is followed by a cleaned-up version of the outline headline
8629 associated with the item.
8632 * Categories:: Not all tasks are equal
8633 * Time-of-day specifications:: How the agenda knows the time
8634 * Sorting agenda items:: The order of things
8635 * Filtering/limiting agenda items:: Dynamically narrow the agenda
8639 @subsection Categories
8643 The category is a broad label assigned to each agenda item. By default, the
8644 category is simply derived from the file name, but you can also specify it
8645 with a special line in the buffer, like this:
8652 @cindex property, CATEGORY
8653 If you would like to have a special CATEGORY for a single entry or a
8654 (sub)tree, give the entry a @code{:CATEGORY:} property with the
8655 special category you want to apply as the value.
8658 The display in the agenda buffer looks best if the category is not
8659 longer than 10 characters.
8662 You can set up icons for category by customizing the
8663 @code{org-agenda-category-icon-alist} variable.
8665 @node Time-of-day specifications
8666 @subsection Time-of-day specifications
8667 @cindex time-of-day specification
8669 Org mode checks each agenda item for a time-of-day specification. The
8670 time can be part of the timestamp that triggered inclusion into the
8671 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
8672 ranges can be specified with two timestamps, like
8674 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
8676 In the headline of the entry itself, a time(range) may also appear as
8677 plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda
8678 integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
8679 specifications in diary entries are recognized as well.
8681 For agenda display, Org mode extracts the time and displays it in a
8682 standard 24 hour format as part of the prefix. The example times in
8683 the previous paragraphs would end up in the agenda like this:
8686 8:30-13:00 Arthur Dent lies in front of the bulldozer
8687 12:45...... Ford Prefect arrives and takes Arthur to the pub
8688 19:00...... The Vogon reads his poem
8689 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8693 If the agenda is in single-day mode, or for the display of today, the
8694 timed entries are embedded in a time grid, like
8697 8:00...... ------------------
8698 8:30-13:00 Arthur Dent lies in front of the bulldozer
8699 10:00...... ------------------
8700 12:00...... ------------------
8701 12:45...... Ford Prefect arrives and takes Arthur to the pub
8702 14:00...... ------------------
8703 16:00...... ------------------
8704 18:00...... ------------------
8705 19:00...... The Vogon reads his poem
8706 20:00...... ------------------
8707 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8710 @vindex org-agenda-use-time-grid
8711 @vindex org-agenda-time-grid
8712 The time grid can be turned on and off with the variable
8713 @code{org-agenda-use-time-grid}, and can be configured with
8714 @code{org-agenda-time-grid}.
8716 @node Sorting agenda items
8717 @subsection Sorting agenda items
8718 @cindex sorting, of agenda items
8719 @cindex priorities, of agenda items
8720 Before being inserted into a view, the items are sorted. How this is
8721 done depends on the type of view.
8724 @vindex org-agenda-files
8725 For the daily/weekly agenda, the items for each day are sorted. The
8726 default order is to first collect all items containing an explicit
8727 time-of-day specification. These entries will be shown at the beginning
8728 of the list, as a @emph{schedule} for the day. After that, items remain
8729 grouped in categories, in the sequence given by @code{org-agenda-files}.
8730 Within each category, items are sorted by priority (@pxref{Priorities}),
8731 which is composed of the base priority (2000 for priority @samp{A}, 1000
8732 for @samp{B}, and 0 for @samp{C}), plus additional increments for
8733 overdue scheduled or deadline items.
8735 For the TODO list, items remain in the order of categories, but within
8736 each category, sorting takes place according to priority
8737 (@pxref{Priorities}). The priority used for sorting derives from the
8738 priority cookie, with additions depending on how close an item is to its due
8741 For tags matches, items are not sorted at all, but just appear in the
8742 sequence in which they are found in the agenda files.
8745 @vindex org-agenda-sorting-strategy
8746 Sorting can be customized using the variable
8747 @code{org-agenda-sorting-strategy}, and may also include criteria based on
8748 the estimated effort of an entry (@pxref{Effort estimates}).
8750 @node Filtering/limiting agenda items
8751 @subsection Filtering/limiting agenda items
8753 Agenda built-in or customized commands are statically defined. Agenda
8754 filters and limits provide two ways of dynamically narrowing down the list of
8755 agenda entries: @emph{filters} and @emph{limits}. Filters only act on the
8756 display of the items, while limits take effect before the list of agenda
8757 entries is built. Filters are more often used interactively, while limits are
8758 mostly useful when defined as local variables within custom agenda commands.
8760 @subsubheading Filtering in the agenda
8761 @cindex filtering, by tag, category, top headline and effort, in agenda
8762 @cindex tag filtering, in agenda
8763 @cindex category filtering, in agenda
8764 @cindex top headline filtering, in agenda
8765 @cindex effort filtering, in agenda
8766 @cindex query editing, in agenda
8769 @orgcmd{/,org-agenda-filter-by-tag}
8770 @vindex org-agenda-tag-filter-preset
8771 Filter the agenda view with respect to a tag and/or effort estimates. The
8772 difference between this and a custom agenda command is that filtering is very
8773 fast, so that you can switch quickly between different filters without having
8774 to recreate the agenda.@footnote{Custom commands can preset a filter by
8775 binding the variable @code{org-agenda-tag-filter-preset} as an option. This
8776 filter will then be applied to the view and persist as a basic filter through
8777 refreshes and more secondary filtering. The filter is a global property of
8778 the entire agenda view---in a block agenda, you should only set this in the
8779 global options section, not in the section of an individual block.}
8781 You will be prompted for a tag selection letter; @key{SPC} will mean any tag
8782 at all. Pressing @key{TAB} at that prompt will offer use completion to
8783 select a tag (including any tags that do not have a selection character).
8784 The command then hides all entries that do not contain or inherit this tag.
8785 When called with prefix arg, remove the entries that @emph{do} have the tag.
8786 A second @kbd{/} at the prompt will turn off the filter and unhide any hidden
8787 entries. Pressing @kbd{+} or @kbd{-} switches between filtering and
8788 excluding the next tag.
8790 Org also supports automatic, context-aware tag filtering. If the variable
8791 @code{org-agenda-auto-exclude-function} is set to a user-defined function,
8792 that function can decide which tags should be excluded from the agenda
8793 automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
8794 as a sub-option key and runs the auto exclusion logic. For example, let's
8795 say you use a @code{Net} tag to identify tasks which need network access, an
8796 @code{Errand} tag for errands in town, and a @code{Call} tag for making phone
8797 calls. You could auto-exclude these tags based on the availability of the
8798 Internet, and outside of business hours, with something like this:
8802 (defun org-my-auto-exclude-function (tag)
8804 ((string= tag "Net")
8805 (/= 0 (call-process "/sbin/ping" nil nil nil
8806 "-c1" "-q" "-t1" "mail.gnu.org")))
8807 ((or (string= tag "Errand") (string= tag "Call"))
8808 (let ((hour (nth 2 (decode-time))))
8809 (or (< hour 8) (> hour 21)))))
8812 (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
8823 @item @r{in} search view
8824 add new search words (@kbd{[} and @kbd{]}) or new regular expressions
8825 (@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
8826 add a positive search term prefixed by @samp{+}, indicating that this search
8827 term @i{must} occur/match in the entry. The closing bracket/brace will add a
8828 negative search term which @i{must not} occur/match in the entry for it to be
8832 @orgcmd{<,org-agenda-filter-by-category}
8833 @vindex org-agenda-category-filter-preset
8835 Filter the current agenda view with respect to the category of the item at
8836 point. Pressing @code{<} another time will remove this filter. When called
8837 with a prefix argument exclude the category of the item at point from the
8840 You can add a filter preset in custom agenda commands through the option
8841 @code{org-agenda-category-filter-preset}. @xref{Setting options}.
8843 @orgcmd{^,org-agenda-filter-by-top-headline}
8844 Filter the current agenda view and only display the siblings and the parent
8845 headline of the one at point.
8847 @orgcmd{=,org-agenda-filter-by-regexp}
8848 @vindex org-agenda-regexp-filter-preset
8850 Filter the agenda view by a regular expression: only show agenda entries
8851 matching the regular expression the user entered. When called with a prefix
8852 argument, it will filter @emph{out} entries matching the regexp. With two
8853 universal prefix arguments, it will remove all the regexp filters, which can
8856 You can add a filter preset in custom agenda commands through the option
8857 @code{org-agenda-regexp-filter-preset}. @xref{Setting options}.
8859 @orgcmd{_,org-agenda-filter-by-effort}
8860 @vindex org-agenda-effort-filter-preset
8861 @vindex org-sort-agenda-noeffort-is-high
8862 Filter the agenda view with respect to effort estimates.
8863 You first need to set up allowed efforts globally, for example
8865 (setq org-global-properties
8866 '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
8868 You can then filter for an effort by first typing an operator, one of
8869 @kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
8870 estimate in your array of allowed values, where @kbd{0} means the 10th value.
8871 The filter will then restrict to entries with effort smaller-or-equal, equal,
8872 or larger-or-equal than the selected value. For application of the operator,
8873 entries without a defined effort will be treated according to the value of
8874 @code{org-sort-agenda-noeffort-is-high}.
8876 When called with a prefix argument, it will remove entries matching the
8877 condition. With two universal prefix arguments, it will clear effort
8878 filters, which can be accumulated.
8880 You can add a filter preset in custom agenda commands through the option
8881 @code{org-agenda-effort-filter-preset}. @xref{Setting options}.
8883 @orgcmd{|,org-agenda-filter-remove-all}
8884 Remove all filters in the current agenda view.
8887 @subsubheading Setting limits for the agenda
8888 @cindex limits, in agenda
8889 @vindex org-agenda-max-entries
8890 @vindex org-agenda-max-effort
8891 @vindex org-agenda-max-todos
8892 @vindex org-agenda-max-tags
8894 Here is a list of options that you can set, either globally, or locally in
8895 your custom agenda views (@pxref{Custom agenda views}).
8898 @item org-agenda-max-entries
8899 Limit the number of entries.
8900 @item org-agenda-max-effort
8901 Limit the duration of accumulated efforts (as minutes).
8902 @item org-agenda-max-todos
8903 Limit the number of entries with TODO keywords.
8904 @item org-agenda-max-tags
8905 Limit the number of tagged entries.
8908 When set to a positive integer, each option will exclude entries from other
8909 categories: for example, @code{(setq org-agenda-max-effort 100)} will limit
8910 the agenda to 100 minutes of effort and exclude any entry that has no effort
8911 property. If you want to include entries with no effort property, use a
8912 negative value for @code{org-agenda-max-effort}.
8914 One useful setup is to use @code{org-agenda-max-entries} locally in a custom
8915 command. For example, this custom command will display the next five entries
8916 with a @code{NEXT} TODO keyword.
8919 (setq org-agenda-custom-commands
8921 ((org-agenda-max-entries 5)))))
8924 Once you mark one of these five entry as @code{DONE}, rebuilding the agenda
8925 will again the next five entries again, including the first entry that was
8928 You can also dynamically set temporary limits, which will be lost when
8929 rebuilding the agenda:
8932 @orgcmd{~,org-agenda-limit-interactively}
8933 This prompts for the type of limit to apply and its value.
8936 @node Agenda commands
8937 @section Commands in the agenda buffer
8938 @cindex commands, in agenda buffer
8940 Entries in the agenda buffer are linked back to the Org file or diary
8941 file where they originate. You are not allowed to edit the agenda
8942 buffer itself, but commands are provided to show and jump to the
8943 original entry location, and to edit the Org files ``remotely'' from
8944 the agenda buffer. In this way, all information is stored only once,
8945 removing the risk that your agenda and note files may diverge.
8947 Some commands can be executed with mouse clicks on agenda lines. For
8948 the other commands, the cursor needs to be in the desired line.
8951 @tsubheading{Motion}
8952 @cindex motion commands in agenda
8953 @orgcmd{n,org-agenda-next-line}
8954 Next line (same as @key{down} and @kbd{C-n}).
8955 @orgcmd{p,org-agenda-previous-line}
8956 Previous line (same as @key{up} and @kbd{C-p}).
8957 @orgcmd{N,org-agenda-next-item}
8958 Next item: same as next line, but only consider items.
8959 @orgcmd{P,org-agenda-previous-item}
8960 Previous item: same as previous line, but only consider items.
8961 @tsubheading{View/Go to Org file}
8962 @orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
8963 Display the original location of the item in another window. With prefix
8964 arg, make sure that drawers stay folded.
8966 @orgcmd{L,org-agenda-recenter}
8967 Display original location and recenter that window.
8969 @orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
8970 Go to the original location of the item in another window.
8972 @orgcmd{@key{RET},org-agenda-switch-to}
8973 Go to the original location of the item and delete other windows.
8975 @orgcmd{F,org-agenda-follow-mode}
8976 @vindex org-agenda-start-with-follow-mode
8977 Toggle Follow mode. In Follow mode, as you move the cursor through
8978 the agenda buffer, the other window always shows the corresponding
8979 location in the Org file. The initial setting for this mode in new
8980 agenda buffers can be set with the variable
8981 @code{org-agenda-start-with-follow-mode}.
8983 @orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
8984 Display the entire subtree of the current item in an indirect buffer. With a
8985 numeric prefix argument N, go up to level N and then take that tree. If N is
8986 negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the
8987 previously used indirect buffer.
8989 @orgcmd{C-c C-o,org-agenda-open-link}
8990 Follow a link in the entry. This will offer a selection of any links in the
8991 text belonging to the referenced Org node. If there is only one link, it
8992 will be followed without a selection prompt.
8994 @tsubheading{Change display}
8995 @cindex display changing, in agenda
8998 Interactively select another agenda view and append it to the current view.
9002 Delete other windows.
9004 @orgcmdkskc{v d,d,org-agenda-day-view}
9005 @xorgcmdkskc{v w,w,org-agenda-week-view}
9006 @xorgcmd{v t,org-agenda-fortnight-view}
9007 @xorgcmd{v m,org-agenda-month-view}
9008 @xorgcmd{v y,org-agenda-year-view}
9009 @xorgcmd{v SPC,org-agenda-reset-view}
9010 @vindex org-agenda-span
9011 Switch to day/week/month/year view. When switching to day or week view, this
9012 setting becomes the default for subsequent agenda refreshes. Since month and
9013 year views are slow to create, they do not become the default. A numeric
9014 prefix argument may be used to jump directly to a specific day of the year,
9015 ISO week, month, or year, respectively. For example, @kbd{32 d} jumps to
9016 February 1st, @kbd{9 w} to ISO week number 9. When setting day, week, or
9017 month view, a year may be encoded in the prefix argument as well. For
9018 example, @kbd{200712 w} will jump to week 12 in 2007. If such a year
9019 specification has only one or two digits, it will be mapped to the interval
9020 1938--2037. @kbd{v @key{SPC}} will reset to what is set in
9021 @code{org-agenda-span}.
9023 @orgcmd{f,org-agenda-later}
9024 Go forward in time to display the following @code{org-agenda-current-span} days.
9025 For example, if the display covers a week, switch to the following week.
9026 With prefix arg, go forward that many times @code{org-agenda-current-span} days.
9028 @orgcmd{b,org-agenda-earlier}
9029 Go backward in time to display earlier dates.
9031 @orgcmd{.,org-agenda-goto-today}
9034 @orgcmd{j,org-agenda-goto-date}
9035 Prompt for a date and go there.
9037 @orgcmd{J,org-agenda-clock-goto}
9038 Go to the currently clocked-in task @i{in the agenda buffer}.
9040 @orgcmd{D,org-agenda-toggle-diary}
9041 Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}.
9043 @orgcmdkskc{v l,l,org-agenda-log-mode}
9045 @vindex org-log-done
9046 @vindex org-agenda-log-mode-items
9047 Toggle Logbook mode. In Logbook mode, entries that were marked DONE while
9048 logging was on (variable @code{org-log-done}) are shown in the agenda, as are
9049 entries that have been clocked on that day. You can configure the entry
9050 types that should be included in log mode using the variable
9051 @code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show
9052 all possible logbook entries, including state changes. When called with two
9053 prefix arguments @kbd{C-u C-u}, show only logging information, nothing else.
9054 @kbd{v L} is equivalent to @kbd{C-u v l}.
9056 @orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
9057 Include inactive timestamps into the current view. Only for weekly/daily
9060 @orgcmd{v a,org-agenda-archives-mode}
9061 @xorgcmd{v A,org-agenda-archives-mode 'files}
9062 @cindex Archives mode
9063 Toggle Archives mode. In Archives mode, trees that are marked
9064 @code{ARCHIVED} are also scanned when producing the agenda. When you use the
9065 capital @kbd{A}, even all archive files are included. To exit archives mode,
9066 press @kbd{v a} again.
9068 @orgcmdkskc{v R,R,org-agenda-clockreport-mode}
9069 @vindex org-agenda-start-with-clockreport-mode
9070 @vindex org-clock-report-include-clocking-task
9071 Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will
9072 always show a table with the clocked times for the time span and file scope
9073 covered by the current agenda view. The initial setting for this mode in new
9074 agenda buffers can be set with the variable
9075 @code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
9076 when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
9077 contributions from entries that are hidden by agenda filtering@footnote{Only
9078 tags filtering will be respected here, effort filtering is ignored.}. See
9079 also the variable @code{org-clock-report-include-clocking-task}.
9082 @vindex org-agenda-clock-consistency-checks
9083 Show overlapping clock entries, clocking gaps, and other clocking problems in
9084 the current agenda range. You can then visit clocking lines and fix them
9085 manually. See the variable @code{org-agenda-clock-consistency-checks} for
9086 information on how to customize the definition of what constituted a clocking
9087 problem. To return to normal agenda display, press @kbd{l} to exit Logbook
9090 @orgcmdkskc{v E,E,org-agenda-entry-text-mode}
9091 @vindex org-agenda-start-with-entry-text-mode
9092 @vindex org-agenda-entry-text-maxlines
9093 Toggle entry text mode. In entry text mode, a number of lines from the Org
9094 outline node referenced by an agenda line will be displayed below the line.
9095 The maximum number of lines is given by the variable
9096 @code{org-agenda-entry-text-maxlines}. Calling this command with a numeric
9097 prefix argument will temporarily modify that number to the prefix value.
9099 @orgcmd{G,org-agenda-toggle-time-grid}
9100 @vindex org-agenda-use-time-grid
9101 @vindex org-agenda-time-grid
9102 Toggle the time grid on and off. See also the variables
9103 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
9105 @orgcmd{r,org-agenda-redo}
9106 Recreate the agenda buffer, for example to reflect the changes after
9107 modification of the timestamps of items with @kbd{S-@key{left}} and
9108 @kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix
9109 argument is interpreted to create a selective list for a specific TODO
9111 @orgcmd{g,org-agenda-redo}
9114 @orgcmdkskc{C-x C-s,s,org-save-all-org-buffers}
9115 Save all Org buffers in the current Emacs session, and also the locations of
9118 @orgcmd{C-c C-x C-c,org-agenda-columns}
9119 @vindex org-columns-default-format
9120 Invoke column view (@pxref{Column view}) in the agenda buffer. The column
9121 view format is taken from the entry at point, or (if there is no entry at
9122 point), from the first entry in the agenda view. So whatever the format for
9123 that entry would be in the original buffer (taken from a property, from a
9124 @code{#+COLUMNS} line, or from the default variable
9125 @code{org-columns-default-format}), will be used in the agenda.
9127 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
9128 Remove the restriction lock on the agenda, if it is currently restricted to a
9129 file or subtree (@pxref{Agenda files}).
9131 @tsubheading{Secondary filtering and query editing}
9133 For a detailed description of these commands, @pxref{Filtering/limiting
9136 @orgcmd{/,org-agenda-filter-by-tag}
9137 Filter the agenda view with respect to a tag and/or effort estimates.
9139 @orgcmd{<,org-agenda-filter-by-category}
9140 Filter the current agenda view with respect to the category of the item at
9143 @orgcmd{^,org-agenda-filter-by-top-headline}
9144 Filter the current agenda view and only display the siblings and the parent
9145 headline of the one at point.
9147 @orgcmd{=,org-agenda-filter-by-regexp}
9148 Filter the agenda view by a regular expression.
9150 @orgcmd{_,org-agenda-filter-by-effort}
9151 Filter the agenda view with respect to effort estimates.
9153 @orgcmd{|,org-agenda-filter-remove-all}
9154 Remove all filters in the current agenda view.
9156 @tsubheading{Remote editing}
9157 @cindex remote editing, from agenda
9162 @cindex undoing remote-editing events
9163 @cindex remote editing, undo
9164 @orgcmd{C-_,org-agenda-undo}
9165 Undo a change due to a remote editing command. The change is undone
9166 both in the agenda buffer and in the remote buffer.
9168 @orgcmd{t,org-agenda-todo}
9169 Change the TODO state of the item, both in the agenda and in the
9172 @orgcmd{C-S-@key{right},org-agenda-todo-nextset}
9173 @orgcmd{C-S-@key{left},org-agenda-todo-previousset}
9174 Switch to the next/previous set of TODO keywords.
9176 @orgcmd{C-k,org-agenda-kill}
9177 @vindex org-agenda-confirm-kill
9178 Delete the current agenda item along with the entire subtree belonging
9179 to it in the original Org file. If the text to be deleted remotely
9180 is longer than one line, the kill needs to be confirmed by the user. See
9181 variable @code{org-agenda-confirm-kill}.
9183 @orgcmd{C-c C-w,org-agenda-refile}
9184 Refile the entry at point.
9186 @orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation}
9187 @vindex org-archive-default-command
9188 Archive the subtree corresponding to the entry at point using the default
9189 archiving command set in @code{org-archive-default-command}. When using the
9190 @code{a} key, confirmation will be required.
9192 @orgcmd{C-c C-x a,org-agenda-toggle-archive-tag}
9193 Toggle the ARCHIVE tag for the current headline.
9195 @orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling}
9196 Move the subtree corresponding to the current entry to its @emph{archive
9199 @orgcmdkskc{C-c C-x C-s,$,org-agenda-archive}
9200 Archive the subtree corresponding to the current headline. This means the
9201 entry will be moved to the configured archive location, most likely a
9204 @orgcmd{T,org-agenda-show-tags}
9205 @vindex org-agenda-show-inherited-tags
9206 Show all tags associated with the current item. This is useful if you have
9207 turned off @code{org-agenda-show-inherited-tags}, but still want to see all
9208 tags of a headline occasionally.
9210 @orgcmd{:,org-agenda-set-tags}
9211 Set tags for the current headline. If there is an active region in the
9212 agenda, change a tag for all headings in the region.
9216 Set the priority for the current item (@command{org-agenda-priority}).
9217 Org mode prompts for the priority character. If you reply with @key{SPC},
9218 the priority cookie is removed from the entry.
9220 @orgcmd{P,org-agenda-show-priority}
9221 Display weighted priority of current item.
9223 @orgcmdkkc{+,S-@key{up},org-agenda-priority-up}
9224 Increase the priority of the current item. The priority is changed in
9225 the original buffer, but the agenda is not resorted. Use the @kbd{r}
9228 @orgcmdkkc{-,S-@key{down},org-agenda-priority-down}
9229 Decrease the priority of the current item.
9231 @orgcmdkkc{z,C-c C-z,org-agenda-add-note}
9232 @vindex org-log-into-drawer
9233 Add a note to the entry. This note will be recorded, and then filed to the
9234 same location where state change notes are put. Depending on
9235 @code{org-log-into-drawer}, this may be inside a drawer.
9237 @orgcmd{C-c C-a,org-attach}
9238 Dispatcher for all command related to attachments.
9240 @orgcmd{C-c C-s,org-agenda-schedule}
9241 Schedule this item. With prefix arg remove the scheduling timestamp
9243 @orgcmd{C-c C-d,org-agenda-deadline}
9244 Set a deadline for this item. With prefix arg remove the deadline.
9246 @orgcmd{S-@key{right},org-agenda-do-date-later}
9247 Change the timestamp associated with the current line by one day into the
9248 future. If the date is in the past, the first call to this command will move
9250 With a numeric prefix argument, change it by that many days. For example,
9251 @kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix,
9252 change the time by one hour. If you immediately repeat the command, it will
9253 continue to change hours even without the prefix arg. With a double @kbd{C-u
9254 C-u} prefix, do the same for changing minutes.@*
9255 The stamp is changed in the original Org file, but the change is not directly
9256 reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
9258 @orgcmd{S-@key{left},org-agenda-do-date-earlier}
9259 Change the timestamp associated with the current line by one day
9262 @orgcmd{>,org-agenda-date-prompt}
9263 Change the timestamp associated with the current line. The key @kbd{>} has
9264 been chosen, because it is the same as @kbd{S-.} on my keyboard.
9266 @orgcmd{I,org-agenda-clock-in}
9267 Start the clock on the current item. If a clock is running already, it
9270 @orgcmd{O,org-agenda-clock-out}
9271 Stop the previously started clock.
9273 @orgcmd{X,org-agenda-clock-cancel}
9274 Cancel the currently running clock.
9276 @orgcmd{J,org-agenda-clock-goto}
9277 Jump to the running clock in another window.
9279 @orgcmd{k,org-agenda-capture}
9280 Like @code{org-capture}, but use the date at point as the default date for
9281 the capture template. See @code{org-capture-use-agenda-date} to make this
9282 the default behavior of @code{org-capture}.
9283 @cindex capturing, from agenda
9284 @vindex org-capture-use-agenda-date
9286 @tsubheading{Dragging agenda lines forward/backward}
9287 @cindex dragging, agenda lines
9289 @orgcmd{M-<up>,org-agenda-drag-line-backward}
9290 Drag the line at point backward one line@footnote{Moving agenda lines does
9291 not persist after an agenda refresh and does not modify the contributing
9292 @file{.org} files}. With a numeric prefix argument, drag backward by that
9295 @orgcmd{M-<down>,org-agenda-drag-line-forward}
9296 Drag the line at point forward one line. With a numeric prefix argument,
9297 drag forward by that many lines.
9299 @tsubheading{Bulk remote editing selected entries}
9300 @cindex remote editing, bulk, from agenda
9301 @vindex org-agenda-bulk-custom-functions
9303 @orgcmd{m,org-agenda-bulk-mark}
9304 Mark the entry at point for bulk action. With numeric prefix argument, mark
9305 that many successive entries.
9307 @orgcmd{*,org-agenda-bulk-mark-all}
9308 Mark all visible agenda entries for bulk action.
9310 @orgcmd{u,org-agenda-bulk-unmark}
9311 Unmark entry at point for bulk action.
9313 @orgcmd{U,org-agenda-bulk-remove-all-marks}
9314 Unmark all marked entries for bulk action.
9316 @orgcmd{M-m,org-agenda-bulk-toggle}
9317 Toggle mark of the entry at point for bulk action.
9319 @orgcmd{M-*,org-agenda-bulk-toggle-all}
9320 Toggle marks of all visible entries for bulk action.
9322 @orgcmd{%,org-agenda-bulk-mark-regexp}
9323 Mark entries matching a regular expression for bulk action.
9325 @orgcmd{B,org-agenda-bulk-action}
9326 Bulk action: act on all marked entries in the agenda. This will prompt for
9327 another key to select the action to be applied. The prefix arg to @kbd{B}
9328 will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove
9329 these special timestamps. By default, marks are removed after the bulk. If
9330 you want them to persist, set @code{org-agenda-persistent-marks} to @code{t}
9331 or hit @kbd{p} at the prompt.
9335 Toggle persistent marks.
9337 Archive all selected entries.
9339 Archive entries by moving them to their respective archive siblings.
9341 Change TODO state. This prompts for a single TODO keyword and changes the
9342 state of all selected entries, bypassing blocking and suppressing logging
9343 notes (but not timestamps).
9345 Add a tag to all selected entries.
9347 Remove a tag from all selected entries.
9349 Schedule all items to a new date. To shift existing schedule dates by a
9350 fixed number of days, use something starting with double plus at the prompt,
9351 for example @samp{++8d} or @samp{++2w}.
9353 Set deadline to a specific date.
9355 Prompt for a single refile target and move all entries. The entries will no
9356 longer be in the agenda; refresh (@kbd{g}) to bring them back.
9358 Reschedule randomly into the coming N days. N will be prompted for. With
9359 prefix arg (@kbd{C-u B S}), scatter only across weekdays.
9361 Apply a function@footnote{You can also create persistent custom functions
9362 through @code{org-agenda-bulk-custom-functions}.} to marked entries. For
9363 example, the function below sets the CATEGORY property of the entries to web.
9367 (defun set-category ()
9369 (let* ((marker (or (org-get-at-bol 'org-hd-marker)
9370 (org-agenda-error)))
9371 (buffer (marker-buffer marker)))
9372 (with-current-buffer buffer
9377 (org-back-to-heading t)
9378 (org-set-property "CATEGORY" "web"))))))
9383 @tsubheading{Calendar commands}
9384 @cindex calendar commands, from agenda
9386 @orgcmd{c,org-agenda-goto-calendar}
9387 Open the Emacs calendar and move to the date at the agenda cursor.
9389 @orgcmd{c,org-calendar-goto-agenda}
9390 When in the calendar, compute and show the Org mode agenda for the
9393 @cindex diary entries, creating from agenda
9394 @orgcmd{i,org-agenda-diary-entry}
9395 @vindex org-agenda-diary-file
9396 Insert a new entry into the diary, using the date at the cursor and (for
9397 block entries) the date at the mark. This will add to the Emacs diary
9398 file@footnote{This file is parsed for the agenda when
9399 @code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
9400 command in the calendar. The diary file will pop up in another window, where
9401 you can add the entry.
9403 If you configure @code{org-agenda-diary-file} to point to an Org mode file,
9404 Org will create entries (in Org mode syntax) in that file instead. Most
9405 entries will be stored in a date-based outline tree that will later make it
9406 easy to archive appointments from previous months/years. The tree will be
9407 built under an entry with a @code{DATE_TREE} property, or else with years as
9408 top-level entries. Emacs will prompt you for the entry text---if you specify
9409 it, the entry will be created in @code{org-agenda-diary-file} without further
9410 interaction. If you directly press @key{RET} at the prompt without typing
9411 text, the target file will be shown in another window for you to finish the
9412 entry there. See also the @kbd{k r} command.
9414 @orgcmd{M,org-agenda-phases-of-moon}
9415 Show the phases of the moon for the three months around current date.
9417 @orgcmd{S,org-agenda-sunrise-sunset}
9418 Show sunrise and sunset times. The geographical location must be set
9419 with calendar variables, see the documentation for the Emacs calendar.
9421 @orgcmd{C,org-agenda-convert-date}
9422 Convert the date at cursor into many other cultural and historic
9425 @orgcmd{H,org-agenda-holidays}
9426 Show holidays for three months around the cursor date.
9428 @item M-x org-icalendar-combine-agenda-files RET
9429 Export a single iCalendar file containing entries from all agenda files.
9430 This is a globally available command, and also available in the agenda menu.
9432 @tsubheading{Exporting to a file}
9433 @orgcmd{C-x C-w,org-agenda-write}
9434 @cindex exporting agenda views
9435 @cindex agenda views, exporting
9436 @vindex org-agenda-exporter-settings
9437 Write the agenda view to a file. Depending on the extension of the selected
9438 file name, the view will be exported as HTML (@file{.html} or @file{.htm}),
9439 Postscript (@file{.ps}), PDF (@file{.pdf}), Org (@file{.org}) and plain text
9440 (any other extension). When exporting to Org, only the body of original
9441 headlines are exported, not subtrees or inherited tags. When called with a
9442 @kbd{C-u} prefix argument, immediately open the newly created file. Use the
9443 variable @code{org-agenda-exporter-settings} to set options for
9444 @file{ps-print} and for @file{htmlize} to be used during export.
9446 @tsubheading{Quit and Exit}
9447 @orgcmd{q,org-agenda-quit}
9448 Quit agenda, remove the agenda buffer.
9450 @cindex agenda files, removing buffers
9451 @orgcmd{x,org-agenda-exit}
9452 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
9453 for the compilation of the agenda. Buffers created by the user to
9454 visit Org files will not be removed.
9458 @node Custom agenda views
9459 @section Custom agenda views
9460 @cindex custom agenda views
9461 @cindex agenda views, custom
9463 Custom agenda commands serve two purposes: to store and quickly access
9464 frequently used TODO and tags searches, and to create special composite
9465 agenda buffers. Custom agenda commands will be accessible through the
9466 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
9469 * Storing searches:: Type once, use often
9470 * Block agenda:: All the stuff you need in a single buffer
9471 * Setting options:: Changing the rules
9474 @node Storing searches
9475 @subsection Storing searches
9477 The first application of custom searches is the definition of keyboard
9478 shortcuts for frequently used searches, either creating an agenda
9479 buffer, or a sparse tree (the latter covering of course only the current
9482 @vindex org-agenda-custom-commands
9483 @cindex agenda views, main example
9484 @cindex agenda, as an agenda views
9485 @cindex agenda*, as an agenda views
9486 @cindex tags, as an agenda view
9487 @cindex todo, as an agenda view
9493 Custom commands are configured in the variable
9494 @code{org-agenda-custom-commands}. You can customize this variable, for
9495 example by pressing @kbd{C-c a C}. You can also directly set it with Emacs
9496 Lisp in the Emacs init file. The following example contains all valid agenda
9501 (setq org-agenda-custom-commands
9504 ("w" todo "WAITING")
9505 ("W" todo-tree "WAITING")
9506 ("u" tags "+boss-urgent")
9507 ("v" tags-todo "+boss-urgent")
9508 ("U" tags-tree "+boss-urgent")
9509 ("f" occur-tree "\\<FIXME\\>")
9510 ("h" . "HOME+Name tags searches") ; description for "h" prefix
9511 ("hl" tags "+home+Lisa")
9512 ("hp" tags "+home+Peter")
9513 ("hk" tags "+home+Kim")))
9518 The initial string in each entry defines the keys you have to press
9519 after the dispatcher command @kbd{C-c a} in order to access the command.
9520 Usually this will be just a single character, but if you have many
9521 similar commands, you can also define two-letter combinations where the
9522 first character is the same in several combinations and serves as a
9523 prefix key@footnote{You can provide a description for a prefix key by
9524 inserting a cons cell with the prefix and the description.}. The second
9525 parameter is the search type, followed by the string or regular
9526 expression to be used for the matching. The example above will
9531 as a global search for agenda entries planned@footnote{@emph{Planned} means
9532 here that these entries have some planning information attached to them, like
9533 a time-stamp, a scheduled or a deadline string. See
9534 @code{org-agenda-entry-types} on how to set what planning information will be
9535 taken into account.} this week/day.
9537 as a global search for agenda entries planned this week/day, but only those
9538 with an hour specification like @code{[h]h:mm}---think of them as appointments.
9540 as a global search for TODO entries with @samp{WAITING} as the TODO
9543 as the same search, but only in the current buffer and displaying the
9544 results as a sparse tree
9546 as a global tags search for headlines marked @samp{:boss:} but not
9549 as the same search as @kbd{C-c a u}, but limiting the search to
9550 headlines that are also TODO items
9552 as the same search as @kbd{C-c a u}, but only in the current buffer and
9553 displaying the result as a sparse tree
9555 to create a sparse tree (again: current buffer only) with all entries
9556 containing the word @samp{FIXME}
9558 as a prefix command for a HOME tags search where you have to press an
9559 additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,
9560 Peter, or Kim) as additional tag to match.
9563 Note that the @code{*-tree} agenda views need to be called from an
9564 Org buffer as they operate on the current buffer only.
9567 @subsection Block agenda
9568 @cindex block agenda
9569 @cindex agenda, with block views
9571 Another possibility is the construction of agenda views that comprise
9572 the results of @emph{several} commands, each of which creates a block in
9573 the agenda buffer. The available commands include @code{agenda} for the
9574 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
9575 for the global TODO list (as constructed with @kbd{C-c a t}), and the
9576 matching commands discussed above: @code{todo}, @code{tags}, and
9577 @code{tags-todo}. Here are two examples:
9581 (setq org-agenda-custom-commands
9582 '(("h" "Agenda and Home-related tasks"
9586 ("o" "Agenda and Office-related tasks"
9594 This will define @kbd{C-c a h} to create a multi-block view for stuff
9595 you need to attend to at home. The resulting agenda buffer will contain
9596 your agenda for the current week, all TODO items that carry the tag
9597 @samp{home}, and also all lines tagged with @samp{garden}. Finally the
9598 command @kbd{C-c a o} provides a similar view for office tasks.
9600 @node Setting options
9601 @subsection Setting options for custom commands
9602 @cindex options, for custom agenda views
9604 @vindex org-agenda-custom-commands
9605 Org mode contains a number of variables regulating agenda construction
9606 and display. The global variables define the behavior for all agenda
9607 commands, including the custom commands. However, if you want to change
9608 some settings just for a single custom view, you can do so. Setting
9609 options requires inserting a list of variable names and values at the
9610 right spot in @code{org-agenda-custom-commands}. For example:
9614 (setq org-agenda-custom-commands
9615 '(("w" todo "WAITING"
9616 ((org-agenda-sorting-strategy '(priority-down))
9617 (org-agenda-prefix-format " Mixed: ")))
9618 ("U" tags-tree "+boss-urgent"
9619 ((org-show-context-detail 'minimal)))
9621 ((org-agenda-files '("~org/notes.org"))
9622 (org-agenda-text-search-extra-files nil)))))
9627 Now the @kbd{C-c a w} command will sort the collected entries only by
9628 priority, and the prefix format is modified to just say @samp{ Mixed: }
9629 instead of giving the category of the entry. The sparse tags tree of
9630 @kbd{C-c a U} will now turn out ultra-compact, because neither the
9631 headline hierarchy above the match, nor the headline following the match
9632 will be shown. The command @kbd{C-c a N} will do a text search limited
9633 to only a single file.
9635 @vindex org-agenda-custom-commands
9636 For command sets creating a block agenda,
9637 @code{org-agenda-custom-commands} has two separate spots for setting
9638 options. You can add options that should be valid for just a single
9639 command in the set, and options that should be valid for all commands in
9640 the set. The former are just added to the command entry; the latter
9641 must come after the list of command entries. Going back to the block
9642 agenda example (@pxref{Block agenda}), let's change the sorting strategy
9643 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
9644 the results for GARDEN tags query in the opposite order,
9645 @code{priority-up}. This would look like this:
9649 (setq org-agenda-custom-commands
9650 '(("h" "Agenda and Home-related tasks"
9654 ((org-agenda-sorting-strategy '(priority-up)))))
9655 ((org-agenda-sorting-strategy '(priority-down))))
9656 ("o" "Agenda and Office-related tasks"
9663 As you see, the values and parentheses setting is a little complex.
9664 When in doubt, use the customize interface to set this variable---it
9665 fully supports its structure. Just one caveat: when setting options in
9666 this interface, the @emph{values} are just Lisp expressions. So if the
9667 value is a string, you need to add the double-quotes around the value
9670 @vindex org-agenda-custom-commands-contexts
9671 To control whether an agenda command should be accessible from a specific
9672 context, you can customize @code{org-agenda-custom-commands-contexts}. Let's
9673 say for example that you have an agenda command @code{"o"} displaying a view
9674 that you only need when reading emails. Then you would configure this option
9678 (setq org-agenda-custom-commands-contexts
9679 '(("o" (in-mode . "message-mode"))))
9682 You can also tell that the command key @code{"o"} should refer to another
9683 command key @code{"r"}. In that case, add this command key like this:
9686 (setq org-agenda-custom-commands-contexts
9687 '(("o" "r" (in-mode . "message-mode"))))
9690 See the docstring of the variable for more information.
9692 @node Exporting agenda views
9693 @section Exporting agenda views
9694 @cindex agenda views, exporting
9696 If you are away from your computer, it can be very useful to have a printed
9697 version of some agenda views to carry around. Org mode can export custom
9698 agenda views as plain text, HTML@footnote{You need to install
9699 @file{htmlize.el} from @uref{https://github.com/hniksic/emacs-htmlize,Hrvoje
9700 Niksic's repository.}}, Postscript, PDF@footnote{To create PDF output, the
9701 ghostscript @file{ps2pdf} utility must be installed on the system. Selecting
9702 a PDF file will also create the postscript file.}, and iCalendar files. If
9703 you want to do this only occasionally, use the command
9706 @orgcmd{C-x C-w,org-agenda-write}
9707 @cindex exporting agenda views
9708 @cindex agenda views, exporting
9709 @vindex org-agenda-exporter-settings
9710 Write the agenda view to a file. Depending on the extension of the selected
9711 file name, the view will be exported as HTML (extension @file{.html} or
9712 @file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension
9713 @file{.ics}), or plain text (any other extension). Use the variable
9714 @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
9715 for @file{htmlize} to be used during export, for example
9717 @vindex org-agenda-add-entry-text-maxlines
9718 @vindex htmlize-output-type
9719 @vindex ps-number-of-columns
9720 @vindex ps-landscape-mode
9722 (setq org-agenda-exporter-settings
9723 '((ps-number-of-columns 2)
9724 (ps-landscape-mode t)
9725 (org-agenda-add-entry-text-maxlines 5)
9726 (htmlize-output-type 'css)))
9730 If you need to export certain agenda views frequently, you can associate
9731 any custom agenda command with a list of output file names
9732 @footnote{If you want to store standard views like the weekly agenda
9733 or the global TODO list as well, you need to define custom commands for
9734 them in order to be able to specify file names.}. Here is an example
9735 that first defines custom commands for the agenda and the global
9736 TODO list, together with a number of files to which to export them.
9737 Then we define two block agenda commands and specify file names for them
9738 as well. File names can be relative to the current working directory,
9743 (setq org-agenda-custom-commands
9744 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
9745 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
9746 ("h" "Agenda and Home-related tasks"
9751 ("~/views/home.html"))
9752 ("o" "Agenda and Office-related tasks"
9757 ("~/views/office.ps" "~/calendars/office.ics"))))
9761 The extension of the file name determines the type of export. If it is
9762 @file{.html}, Org mode will try to use the @file{htmlize.el} package to
9763 convert the buffer to HTML and save it to this file name. If the extension
9764 is @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
9765 Postscript output. If the extension is @file{.ics}, iCalendar export is run
9766 export over all files that were used to construct the agenda, and limit the
9767 export to entries listed in the agenda. Any other extension produces a plain
9770 The export files are @emph{not} created when you use one of those
9771 commands interactively because this might use too much overhead.
9772 Instead, there is a special command to produce @emph{all} specified
9776 @orgcmd{C-c a e,org-store-agenda-views}
9777 Export all agenda views that have export file names associated with
9781 You can use the options section of the custom agenda commands to also
9782 set options for the export commands. For example:
9785 (setq org-agenda-custom-commands
9787 ((ps-number-of-columns 2)
9788 (ps-landscape-mode t)
9789 (org-agenda-prefix-format " [ ] ")
9790 (org-agenda-with-colors nil)
9791 (org-agenda-remove-tags t))
9796 This command sets two options for the Postscript exporter, to make it
9797 print in two columns in landscape format---the resulting page can be cut
9798 in two and then used in a paper agenda. The remaining settings modify
9799 the agenda prefix to omit category and scheduling information, and
9800 instead include a checkbox to check off items. We also remove the tags
9801 to make the lines compact, and we don't want to use colors for the
9802 black-and-white printer. Settings specified in
9803 @code{org-agenda-exporter-settings} will also apply, but the settings
9804 in @code{org-agenda-custom-commands} take precedence.
9807 From the command line you may also use
9809 emacs -eval (org-batch-store-agenda-views) -kill
9812 or, if you need to modify some parameters@footnote{Quoting depends on the
9813 system you use, please check the FAQ for examples.}
9815 emacs -eval '(org-batch-store-agenda-views \
9816 org-agenda-span (quote month) \
9817 org-agenda-start-day "2007-11-01" \
9818 org-agenda-include-diary nil \
9819 org-agenda-files (quote ("~/org/project.org")))' \
9823 which will create the agenda views restricted to the file
9824 @file{~/org/project.org}, without diary entries and with a 30-day
9827 You can also extract agenda information in a way that allows further
9828 processing by other programs. See @ref{Extracting agenda information}, for
9832 @node Agenda column view
9833 @section Using column view in the agenda
9834 @cindex column view, in agenda
9835 @cindex agenda, column view
9837 Column view (@pxref{Column view}) is normally used to view and edit
9838 properties embedded in the hierarchical structure of an Org file. It can be
9839 quite useful to use column view also from the agenda, where entries are
9840 collected by certain criteria.
9843 @orgcmd{C-c C-x C-c,org-agenda-columns}
9844 Turn on column view in the agenda.
9847 To understand how to use this properly, it is important to realize that the
9848 entries in the agenda are no longer in their proper outline environment.
9849 This causes the following issues:
9853 @vindex org-columns-default-format
9854 @vindex org-overriding-columns-format
9855 Org needs to make a decision which @code{COLUMNS} format to use. Since the
9856 entries in the agenda are collected from different files, and different files
9857 may have different @code{COLUMNS} formats, this is a non-trivial problem.
9858 Org first checks if the variable @code{org-agenda-overriding-columns-format}
9859 is currently set, and if so, takes the format from there. Otherwise it takes
9860 the format associated with the first item in the agenda, or, if that item
9861 does not have a specific format---defined in a property, or in its file---it
9862 uses @code{org-columns-default-format}.
9865 @cindex property, special, CLOCKSUM
9866 If any of the columns has a summary type defined (@pxref{Column attributes}),
9867 turning on column view in the agenda will visit all relevant agenda files and
9868 make sure that the computations of this property are up to date. This is
9869 also true for the special @code{CLOCKSUM} property. Org will then sum the
9870 values displayed in the agenda. In the daily/weekly agenda, the sums will
9871 cover a single day; in all other views they cover the entire block. It is
9872 vital to realize that the agenda may show the same entry @emph{twice}---for
9873 example as scheduled and as a deadline---and it may show two entries from the
9874 same hierarchy---for example a @emph{parent} and its @emph{child}. In these
9875 cases, the summation in the agenda will lead to incorrect results because
9876 some values will count double.
9879 When the column view in the agenda shows the @code{CLOCKSUM}, that is always
9880 the entire clocked time for this item. So even in the daily/weekly agenda,
9881 the clocksum listed in column view may originate from times outside the
9882 current view. This has the advantage that you can compare these values with
9883 a column listing the planned total effort for a task---one of the major
9884 applications for column view in the agenda. If you want information about
9885 clocked time in the displayed period use clock table mode (press @kbd{R} in
9889 @cindex property, special, CLOCKSUM_T
9890 When the column view in the agenda shows the @code{CLOCKSUM_T}, that is
9891 always today's clocked time for this item. So even in the weekly agenda, the
9892 clocksum listed in column view only originates from today. This lets you
9893 compare the time you spent on a task for today, with the time already
9894 spent ---via @code{CLOCKSUM}---and with the planned total effort for it.
9899 @chapter Markup for rich export
9901 When exporting Org mode documents, the exporter tries to reflect the
9902 structure of the document as accurately as possible in the back-end. Since
9903 export targets like HTML and @LaTeX{} allow much richer formatting, Org mode has
9904 rules on how to prepare text for rich export. This section summarizes the
9905 markup rules used in an Org mode buffer.
9908 * Paragraphs:: The basic unit of text
9909 * Emphasis and monospace:: Bold, italic, etc.
9910 * Horizontal rules:: Make a line
9911 * Images and tables:: Images, tables and caption mechanism
9912 * Literal examples:: Source code examples with special formatting
9913 * Special symbols:: Greek letters and other symbols
9914 * Subscripts and superscripts:: Simple syntax for raising/lowering text
9915 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
9919 @section Paragraphs, line breaks, and quoting
9920 @cindex paragraphs, markup rules
9922 Paragraphs are separated by at least one empty line. If you need to enforce
9923 a line break within a paragraph, use @samp{\\} at the end of a line.
9925 To preserve the line breaks, indentation and blank lines in a region, but
9926 otherwise use normal formatting, you can use this construct, which can also
9927 be used to format poetry.
9929 @cindex #+BEGIN_VERSE
9930 @cindex verse blocks
9933 Great clouds overhead
9934 Tiny black birds rise and fall
9941 When quoting a passage from another document, it is customary to format this
9942 as a paragraph that is indented on both the left and the right margin. You
9943 can include quotations in Org mode documents like this:
9945 @cindex #+BEGIN_QUOTE
9946 @cindex quote blocks
9949 Everything should be made as simple as possible,
9950 but not any simpler -- Albert Einstein
9954 If you would like to center some text, do it like this:
9955 @cindex #+BEGIN_CENTER
9956 @cindex center blocks
9959 Everything should be made as simple as possible, \\
9964 @node Emphasis and monospace
9965 @section Emphasis and monospace
9967 @cindex underlined text, markup rules
9968 @cindex bold text, markup rules
9969 @cindex italic text, markup rules
9970 @cindex verbatim text, markup rules
9971 @cindex code text, markup rules
9972 @cindex strike-through text, markup rules
9973 @vindex org-fontify-emphasized-text
9974 @vindex org-emphasis-regexp-components
9975 @vindex org-emphasis-alist
9976 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=verbatim=}
9977 and @code{~code~}, and, if you must, @samp{+strike-through+}. Text
9978 in the code and verbatim string is not processed for Org mode specific
9979 syntax, it is exported verbatim.
9981 To turn off fontification for marked up text, you can set
9982 @code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of
9983 available markup syntax, you can customize @code{org-emphasis-alist}. To fine
9984 tune what characters are allowed before and after the markup characters, you
9985 can tweak @code{org-emphasis-regexp-components}. Beware that changing one of
9986 the above variables will no take effect until you reload Org, for which you
9987 may need to restart Emacs.
9989 @node Horizontal rules
9990 @section Horizontal rules
9991 @cindex horizontal rules, markup rules
9992 A line consisting of only dashes, and at least 5 of them, will be exported as
9995 @node Images and tables
9996 @section Images and Tables
9998 @cindex tables, markup rules
10001 Both the native Org mode tables (@pxref{Tables}) and tables formatted with
10002 the @file{table.el} package will be exported properly. For Org mode tables,
10003 the lines before the first horizontal separator line will become table header
10004 lines. You can use the following lines somewhere before the table to assign
10005 a caption and a label for cross references, and in the text you can refer to
10006 the object with @code{[[tab:basic-data]]} (@pxref{Internal links}):
10009 #+CAPTION: This is the caption for the next table (or link)
10010 #+NAME: tab:basic-data
10015 Optionally, the caption can take the form:
10017 #+CAPTION[Caption for list of tables]: Caption for table.
10020 @cindex inlined images, markup rules
10021 Some back-ends allow you to directly include images into the exported
10022 document. Org does this, if a link to an image files does not have
10023 a description part, for example @code{[[./img/a.jpg]]}. If you wish to
10024 define a caption for the image and maybe a label for internal cross
10025 references, make sure that the link is on a line by itself and precede it
10026 with @code{#+CAPTION} and @code{#+NAME} as follows:
10029 #+CAPTION: This is the caption for the next figure link (or table)
10030 #+NAME: fig:SED-HR4049
10035 Such images can be displayed within the buffer. @xref{Handling links,the
10036 discussion of image links}.
10038 Even though images and tables are prominent examples of captioned structures,
10039 the same caption mechanism can apply to many others (e.g., @LaTeX{}
10040 equations, source code blocks). Depending on the export back-end, those may
10041 or may not be handled.
10043 @node Literal examples
10044 @section Literal examples
10045 @cindex literal examples, markup rules
10046 @cindex code line references, markup rules
10048 You can include literal examples that should not be subjected to
10049 markup. Such examples will be typeset in monospace, so this is well suited
10050 for source code and similar examples.
10051 @cindex #+BEGIN_EXAMPLE
10055 Some example from a text file.
10059 Note that such blocks may be @i{indented} in order to align nicely with
10060 indented text and in particular with plain list structure (@pxref{Plain
10061 lists}). For simplicity when using small examples, you can also start the
10062 example lines with a colon followed by a space. There may also be additional
10063 whitespace before the colon:
10067 : Some example from a text file.
10070 @cindex formatting source code, markup rules
10071 @vindex org-latex-listings
10072 If the example is source code from a programming language, or any other text
10073 that can be marked up by font-lock in Emacs, you can ask for the example to
10074 look like the fontified Emacs buffer@footnote{This works automatically for
10075 the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package,
10076 which you need to install). Fontified code chunks in @LaTeX{} can be
10077 achieved using either the
10078 @url{https://www.ctan.org/tex-archive/macros/latex/contrib/listings/?lang=en, listings,}
10080 @url{https://github.com/gpoore/minted, minted,} package.
10081 If you use minted or listing, you must load the packages manually, for
10082 example by adding the desired package to
10083 @code{org-latex-packages-alist}. Refer to @code{org-latex-listings}
10084 for details.}. This is done with the @samp{src} block, where you also need
10085 to specify the name of the major mode that should be used to fontify the
10086 example@footnote{Code in @samp{src} blocks may also be evaluated either
10087 interactively or on export. @xref{Working with source code}, for more
10088 information on evaluating code blocks.}, see @ref{Easy templates} for
10089 shortcuts to easily insert code blocks.
10090 @cindex #+BEGIN_SRC
10093 #+BEGIN_SRC emacs-lisp
10094 (defun org-xor (a b)
10100 Both in @code{example} and in @code{src} snippets, you can add a @code{-n}
10101 switch to the end of the @code{BEGIN} line, to get the lines of the example
10102 numbered. The @code{-n} takes an optional numeric argument specifying the
10103 starting line number of the block. If you use a @code{+n} switch, the
10104 numbering from the previous numbered snippet will be continued in the current
10105 one. The @code{+n} can also take a numeric argument. The value of the
10106 argument will be added to the last line of the previous block to determine
10107 the starting line number.
10110 #+BEGIN_SRC emacs-lisp -n 20
10111 ;; this will export with line number 20
10112 (message "This is line 21")
10114 #+BEGIN_SRC emacs-lisp +n 10
10115 ;; This will be listed as line 31
10116 (message "This is line 32")
10120 In literal examples, Org will interpret strings like @samp{(ref:name)} as
10121 labels, and use them as targets for special hyperlinks like @code{[[(name)]]}
10122 (i.e., the reference name enclosed in single parenthesis). In HTML, hovering
10123 the mouse over such a link will remote-highlight the corresponding code line,
10124 which is kind of cool.
10126 You can also add a @code{-r} switch which @i{removes} the labels from the
10127 source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
10128 labels in the source code while using line numbers for the links, which might
10129 be useful to explain those in an Org mode example code.}. With the @code{-n}
10130 switch, links to these references will be labeled by the line numbers from
10131 the code listing, otherwise links will use the labels with no parentheses.
10132 Here is an example:
10135 #+BEGIN_SRC emacs-lisp -n -r
10136 (save-excursion (ref:sc)
10137 (goto-char (point-min))) (ref:jump)
10139 In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
10140 jumps to point-min.
10143 @cindex indentation, in source blocks
10144 Finally, you can use @code{-i} to preserve the indentation of a specific code
10145 block (@pxref{Editing source code}).
10147 @vindex org-coderef-label-format
10148 If the syntax for the label format conflicts with the language syntax, use a
10149 @code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
10150 -n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}.
10152 HTML export also allows examples to be published as text areas (@pxref{Text
10153 areas in HTML export}).
10155 Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
10156 so often, shortcuts are provided using the Easy templates facility
10157 (@pxref{Easy templates}).
10162 Edit the source code example at point in its native mode. This works by
10163 switching to a temporary buffer with the source code. You need to exit by
10164 pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*},
10165 @samp{,*}, @samp{#+} and @samp{,#+} will get a comma prepended, to keep them
10166 from being interpreted by Org as outline nodes or special syntax. These
10167 commas will be stripped for editing with @kbd{C-c '}, and also for export.}.
10168 The edited version will then replace the old version in the Org buffer.
10169 Fixed-width regions (where each line starts with a colon followed by a space)
10170 will be edited using @code{artist-mode}@footnote{You may select
10171 a different-mode with the variable @code{org-edit-fixed-width-region-mode}.}
10172 to allow creating ASCII drawings easily. Using this command in an empty line
10173 will create a new fixed-width region.
10176 Calling @code{org-store-link} while editing a source code example in a
10177 temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure
10178 that it is unique in the current buffer, and insert it with the proper
10179 formatting like @samp{(ref:label)} at the end of the current line. Then the
10180 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
10183 @node Special symbols
10184 @section Special symbols
10185 @cindex Org entities
10186 @cindex math symbols
10187 @cindex special symbols
10188 @cindex HTML entities
10189 @cindex @LaTeX{} entities
10191 You can use @LaTeX{}-like syntax to insert special symbols---named
10192 entities---like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to
10193 indicate an arrow. Completion for these symbols is available, just type
10194 @samp{\} and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible
10195 completions. If you need such a symbol inside a word, terminate it with
10196 a pair of curly brackets. For example
10199 Pro tip: Given a circle \Gamma of diameter d, the length of its circumference
10203 @findex org-entities-help
10204 @vindex org-entities-user
10205 A large number of entities is provided, with names taken from both HTML and
10206 @LaTeX{}; you can comfortably browse the complete list from a dedicated
10207 buffer using the command @code{org-entities-help}. It is also possible to
10208 provide your own special symbols in the variable @code{org-entities-user}.
10210 During export, these symbols are transformed into the native format of the
10211 exporter back-end. Strings like @code{\alpha} are exported as @code{α}
10212 in the HTML output, and as @code{\(\alpha\)} in the @LaTeX{} output.
10213 Similarly, @code{\nbsp} becomes @code{ } in HTML and @code{~} in
10216 @cindex escaping characters
10217 Entities may also be used as a may to escape markup in an Org document, e.g.,
10218 @samp{\under@{@}not underlined\under} exports as @samp{_not underlined_}.
10220 @cindex special symbols, in-buffer display
10221 If you would like to see entities displayed as UTF-8 characters, use the
10222 following command@footnote{You can turn this on by default by setting the
10223 variable @code{org-pretty-entities}, or on a per-file base with the
10224 @code{#+STARTUP} option @code{entitiespretty}.}:
10227 @cindex @code{entitiespretty}, STARTUP keyword
10230 Toggle display of entities as UTF-8 characters. This does not change the
10231 buffer content which remains plain ASCII, but it overlays the UTF-8 character
10232 for display purposes only.
10235 @cindex shy hyphen, special symbol
10236 @cindex dash, special symbol
10237 @cindex ellipsis, special symbol
10238 In addition to regular entities defined above, Org exports in a special
10239 way@footnote{This behaviour can be disabled with @code{-} export setting
10240 (@pxref{Export settings}).} the following commonly used character
10241 combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---}
10242 are converted into dashes, and @samp{...} becomes a compact set of dots.
10244 @node Subscripts and superscripts
10245 @section Subscripts and superscripts
10247 @cindex superscript
10249 @samp{^} and @samp{_} are used to indicate super- and subscripts. To
10250 increase the readability of ASCII text, it is not necessary---but OK---to
10251 surround multi-character sub- and superscripts with curly braces. Those are,
10252 however, mandatory, when more than one word is involved. For example
10255 The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, the
10256 radius of Alpha Centauri is R_@{Alpha Centauri@} = 1.28 x R_@{sun@}.
10259 @vindex org-use-sub-superscripts
10260 If you write a text where the underscore is often used in a different
10261 context, Org's convention to always interpret these as subscripts can get in
10262 your way. Configure the variable @code{org-use-sub-superscripts} to change
10263 this convention. For example, when setting this variable to @code{@{@}},
10264 @samp{a_b} will not be interpreted as a subscript, but @samp{a_@{b@}} will.
10269 In addition to showing entities as UTF-8 characters, this command will also
10270 format sub- and superscripts in a WYSIWYM way.
10273 @node Embedded @LaTeX{}
10274 @section Embedded @LaTeX{}
10275 @cindex @TeX{} interpretation
10276 @cindex @LaTeX{} interpretation
10278 Plain ASCII is normally sufficient for almost all note taking. Exceptions
10279 include scientific notes, which often require mathematical symbols and the
10280 occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on
10281 Donald E. Knuth's @TeX{} system. Many of the features described here as
10282 ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
10283 distinction.} is widely used to typeset scientific documents. Org mode
10284 supports embedding @LaTeX{} code into its files, because many academics are
10285 used to writing and reading @LaTeX{} source code, and because it can be
10286 readily processed to produce pretty output for a number of export back-ends.
10289 * @LaTeX{} fragments:: Complex formulas made easy
10290 * Previewing @LaTeX{} fragments:: What will this snippet look like?
10291 * CDLaTeX mode:: Speed up entering of formulas
10294 @node @LaTeX{} fragments
10295 @subsection @LaTeX{} fragments
10296 @cindex @LaTeX{} fragments
10298 @vindex org-format-latex-header
10299 Org mode can contain @LaTeX{} math fragments, and it supports ways to process
10300 these for several export back-ends. When exporting to @LaTeX{}, the code is
10301 left as it is. When exporting to HTML, Org can use either
10302 @uref{http://www.mathjax.org, MathJax} (@pxref{Math formatting in HTML
10303 export}) or transcode the math into images (see @pxref{Previewing @LaTeX{}
10306 @LaTeX{} fragments don't need any special marking at all. The following
10307 snippets will be identified as @LaTeX{} source code:
10310 Environments of any kind@footnote{When MathJax is used, only the
10311 environments recognized by MathJax will be processed. When
10312 @file{dvipng} program, @file{dvisvgm} program or @file{imagemagick} suite is
10313 used to create images, any @LaTeX{} environment will be handled.}. The only
10314 requirement is that the @code{\begin} statement appears on a new line, at the
10315 beginning of the line or after whitespaces only.
10317 Text within the usual @LaTeX{} math delimiters. To avoid conflicts with
10318 currency specifications, single @samp{$} characters are only recognized as
10319 math delimiters if the enclosed text contains at most two line breaks, is
10320 directly attached to the @samp{$} characters with no whitespace in between,
10321 and if the closing @samp{$} is followed by whitespace or punctuation
10322 (parentheses and quotes are considered to be punctuation in this
10323 context). For the other delimiters, there is no such restriction, so when in
10324 doubt, use @samp{\(...\)} as inline math delimiters.
10327 @noindent For example:
10334 If $a^2=b$ and \( b=2 \), then the solution must be
10335 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
10340 @c @vindex org-format-latex-options
10341 @c If you need any of the delimiter ASCII sequences for other purposes, you
10342 @c can configure the option @code{org-format-latex-options} to deselect the
10343 @c ones you do not wish to have interpreted by the @LaTeX{} converter.
10345 @vindex org-export-with-latex
10346 @LaTeX{} processing can be configured with the variable
10347 @code{org-export-with-latex}. The default setting is @code{t} which means
10348 MathJax for HTML, and no processing for ASCII and @LaTeX{} back-ends.
10349 You can also set this variable on a per-file basis using one of these
10353 #+OPTIONS: tex:t @r{Do the right thing automatically (MathJax)}
10354 #+OPTIONS: tex:nil @r{Do not process @LaTeX{} fragments at all}
10355 #+OPTIONS: tex:verbatim @r{Verbatim export, for jsMath or so}
10358 @node Previewing @LaTeX{} fragments
10359 @subsection Previewing @LaTeX{} fragments
10360 @cindex @LaTeX{} fragments, preview
10362 @vindex org-preview-latex-default-process
10363 If you have a working @LaTeX{} installation and @file{dvipng}, @file{dvisvgm}
10364 or @file{convert} installed@footnote{These are respectively available at
10365 @url{http://sourceforge.net/projects/dvipng/}, @url{http://dvisvgm.bplaced.net/}
10366 and from the @file{imagemagick} suite. Choose the converter by setting the
10367 variable @code{org-preview-latex-default-process} accordingly.}, @LaTeX{}
10368 fragments can be processed to produce images of the typeset expressions to be
10369 used for inclusion while exporting to HTML (see @pxref{@LaTeX{} fragments}),
10370 or for inline previewing within Org mode.
10372 @vindex org-format-latex-options
10373 @vindex org-format-latex-header
10374 You can customize the variables @code{org-format-latex-options} and
10375 @code{org-format-latex-header} to influence some aspects of the preview. In
10376 particular, the @code{:scale} (and for HTML export, @code{:html-scale})
10377 property of the former can be used to adjust the size of the preview images.
10380 @kindex C-c C-x C-l
10382 Produce a preview image of the @LaTeX{} fragment at point and overlay it
10383 over the source code. If there is no fragment at point, process all
10384 fragments in the current entry (between two headlines). When called
10385 with a prefix argument, process the entire subtree. When called with
10386 two prefix arguments, or when the cursor is before the first headline,
10387 process the entire buffer.
10390 Remove the overlay preview images.
10393 @vindex org-startup-with-latex-preview
10394 You can turn on the previewing of all @LaTeX{} fragments in a file with
10397 #+STARTUP: latexpreview
10400 To disable it, simply use
10403 #+STARTUP: nolatexpreview
10407 @subsection Using CD@LaTeX{} to enter math
10410 CD@LaTeX{} mode is a minor mode that is normally used in combination with a
10411 major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
10412 environments and math templates. Inside Org mode, you can make use of
10413 some of the features of CD@LaTeX{} mode. You need to install
10414 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
10415 AUC@TeX{}) from @url{https://staff.fnwi.uva.nl/c.dominik/Tools/cdlatex}.
10416 Don't use CD@LaTeX{} mode itself under Org mode, but use the light
10417 version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it
10418 on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all
10422 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
10425 When this mode is enabled, the following features are present (for more
10426 details see the documentation of CD@LaTeX{} mode):
10430 Environment templates can be inserted with @kbd{C-c @{}.
10433 The @key{TAB} key will do template expansion if the cursor is inside a
10434 @LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is
10435 inside such a fragment, see the documentation of the function
10436 @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
10437 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
10438 correctly inside the first brace. Another @key{TAB} will get you into
10439 the second brace. Even outside fragments, @key{TAB} will expand
10440 environment abbreviations at the beginning of a line. For example, if
10441 you write @samp{equ} at the beginning of a line and press @key{TAB},
10442 this abbreviation will be expanded to an @code{equation} environment.
10443 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help RET}.
10447 @vindex cdlatex-simplify-sub-super-scripts
10448 Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these
10449 characters together with a pair of braces. If you use @key{TAB} to move
10450 out of the braces, and if the braces surround only a single character or
10451 macro, they are removed again (depending on the variable
10452 @code{cdlatex-simplify-sub-super-scripts}).
10455 Pressing the grave accent @kbd{`} followed by a character inserts math
10456 macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds
10457 after the grave accent, a help window will pop up.
10460 Pressing the apostrophe @kbd{'} followed by another character modifies
10461 the symbol before point with an accent or a font. If you wait more than
10462 1.5 seconds after the apostrophe, a help window will pop up. Character
10463 modification will work only inside @LaTeX{} fragments; outside the quote
10471 Sometimes, you may want to pretty print your notes, publish them on the web
10472 or even share them with people not using Org. In these cases, the Org export
10473 facilities can be used to convert your documents to a variety of other
10474 formats, while retaining as much structure (@pxref{Document structure}) and
10475 markup (@pxref{Markup}) as possible.
10477 @cindex export back-end
10478 Libraries responsible for such translation are called back-ends. Org ships
10479 with the following ones
10482 @item ascii (ASCII format)
10483 @item beamer (@LaTeX{} Beamer format)
10484 @item html (HTML format)
10485 @item icalendar (iCalendar format)
10486 @item latex (@LaTeX{} format)
10487 @item md (Markdown format)
10488 @item odt (OpenDocument Text format)
10489 @item org (Org format)
10490 @item texinfo (Texinfo format)
10491 @item man (Man page format)
10494 @noindent Org also uses additional libraries located in @code{contrib/}
10495 directory (@pxref{Installation}). Users can install additional export
10496 libraries for additional formats from the Emacs packaging system. For easy
10497 discovery, these packages have a common naming scheme: @file{ox-NAME}, where
10498 NAME is one of the formats. For example, @file{ox-koma-letter} for
10499 @code{koma-letter} back-end.
10501 @vindex org-export-backends
10502 Org loads back-ends for the following formats by default: @code{ascii},
10503 @code{html}, @code{icalendar}, @code{latex} and @code{odt}.
10505 Org can load additional back-ends either of two ways: through the
10506 @code{org-export-backends} variable configuration; or, by requiring the
10507 library in the Emacs init file like this:
10514 * The export dispatcher:: The main interface
10515 * Export settings:: Common export settings
10516 * Table of contents:: The if and where of the table of contents
10517 * Include files:: Include additional files into a document
10518 * Macro replacement:: Use macros to create templates
10519 * Comment lines:: What will not be exported
10520 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
10521 * Beamer export:: Exporting as a Beamer presentation
10522 * HTML export:: Exporting to HTML
10523 * @LaTeX{} export:: Exporting to @LaTeX{}, and processing to PDF
10524 * Markdown export:: Exporting to Markdown
10525 * OpenDocument Text export:: Exporting to OpenDocument Text
10526 * Org export:: Exporting to Org
10527 * Texinfo export:: Exporting to Texinfo
10528 * iCalendar export:: Exporting to iCalendar
10529 * Other built-in back-ends:: Exporting to a man page
10530 * Advanced configuration:: Fine-tuning the export output
10531 * Export in foreign buffers:: Author tables and lists in Org syntax
10534 @node The export dispatcher
10535 @section The export dispatcher
10536 @vindex org-export-dispatch-use-expert-ui
10537 @cindex Export, dispatcher
10539 The export dispatcher is the main interface for Org's exports. A
10540 hierarchical menu presents the currently configured export formats. Options
10541 are shown as easy toggle switches on the same screen.
10543 Org also has a minimal prompt interface for the export dispatcher. When the
10544 variable @code{org-export-dispatch-use-expert-ui} is set to a non-@code{nil}
10545 value, Org prompts in the minibuffer. To switch back to the hierarchical
10546 menu, press @key{?}.
10549 @orgcmd{C-c C-e,org-export-dispatch}
10551 Invokes the export dispatcher interface. The options show default settings.
10552 The @kbd{C-u} prefix argument preserves options from the previous export,
10553 including any sub-tree selections.
10557 Org exports the entire buffer by default. If the Org buffer has an active
10558 region, then Org exports just that region.
10560 These are the export options, the key combinations that toggle them
10561 (@pxref{Export settings}):
10565 @vindex org-export-async-init-file
10566 Toggles asynchronous export. Asynchronous export uses an external Emacs
10567 process with a specially configured initialization file to complete the
10568 exporting process in the background thereby releasing the current interface.
10569 This is particularly useful when exporting long documents.
10571 Output from an asynchronous export is saved on the ``the export stack''. To
10572 view this stack, call the export dispatcher with a double @kbd{C-u} prefix
10573 argument. If already in the export dispatcher menu, @kbd{&} displays the
10576 @vindex org-export-in-background
10577 To make the background export process the default, customize the variable,
10578 @code{org-export-in-background}.
10581 Toggle body-only export. Useful for excluding headers and footers in the
10582 export. Affects only those back-end formats that have such sections---like
10583 @code{<head>...</head>} in HTML.
10586 @vindex org-export-initial-scope
10587 Toggle sub-tree export. When turned on, Org exports only the sub-tree starting
10588 from the cursor position at the time the export dispatcher was invoked. Org
10589 uses the top heading of this sub-tree as the document's title. If the cursor
10590 is not on a heading, Org uses the nearest enclosing header. If the cursor is
10591 in the document preamble, Org signals an error and aborts export.
10593 To make the sub-tree export the default, customize the variable,
10594 @code{org-export-initial-scope}.
10597 Toggle visible-only export. Useful for exporting only visible parts of an
10598 Org document by adjusting outline visibility settings.
10601 @node Export settings
10602 @section Export settings
10603 @cindex Export, settings
10606 Export options can be set: globally with variables; for an individual file by
10607 making variables buffer-local with in-buffer settings (@pxref{In-buffer
10608 settings}), by setting individual keywords, or by specifying them in a
10609 compact form with the @code{#+OPTIONS} keyword; or for a tree by setting
10610 properties (@pxref{Properties and columns}). Options set at a specific level
10611 override options set at a more general level.
10613 @cindex #+SETUPFILE
10614 In-buffer settings may appear anywhere in the file, either directly or
10615 indirectly through a file included using @samp{#+SETUPFILE: filename or URL}
10616 syntax. Option keyword sets tailored to a particular back-end can be
10617 inserted from the export dispatcher (@pxref{The export dispatcher}) using the
10618 @code{Insert template} command by pressing @key{#}. To insert keywords
10619 individually, a good way to make sure the keyword is correct is to type
10620 @code{#+} and then to use @kbd{M-@key{TAB}}@footnote{Many desktops intercept
10621 @kbd{M-TAB} to switch windows. Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}}
10622 instead.} for completion.
10624 The export keywords available for every back-end, and their equivalent global
10625 variables, include:
10630 @vindex user-full-name
10631 The document author (@code{user-full-name}).
10635 @vindex org-export-creator-string
10636 Entity responsible for output generation (@code{org-export-creator-string}).
10640 @vindex org-export-date-timestamp-format
10641 A date or a time-stamp@footnote{The variable
10642 @code{org-export-date-timestamp-format} defines how this time-stamp will be
10647 @vindex user-mail-address
10648 The email address (@code{user-mail-address}).
10652 @vindex org-export-default-language
10653 Language to use for translating certain strings
10654 (@code{org-export-default-language}). With @samp{#+LANGUAGE: fr}, for
10655 example, Org translates @emph{Table of contents} to the French @emph{Table
10659 @cindex #+SELECT_TAGS
10660 @vindex org-export-select-tags
10661 The default value is @code{:export:}. When a tree is tagged with
10662 @code{:export:} (@code{org-export-select-tags}), Org selects that tree and
10663 its sub-trees for export. Org excludes trees with @code{:noexport:} tags,
10664 see below. When selectively exporting files with @code{:export:} tags set,
10665 Org does not export any text that appears before the first headline.
10668 @cindex #+EXCLUDE_TAGS
10669 @vindex org-export-exclude-tags
10670 The default value is @code{:noexport:}. When a tree is tagged with
10671 @code{:noexport:} (@code{org-export-exclude-tags}), Org excludes that tree
10672 and its sub-trees from export. Entries tagged with @code{:noexport:} will be
10673 unconditionally excluded from the export, even if they have an
10674 @code{:export:} tag. Even if a sub-tree is not exported, Org will execute any
10675 code blocks contained in them.
10679 @cindex document title
10680 Org displays this title. For long titles, use multiple @code{#+TITLE} lines.
10682 @item EXPORT_FILE_NAME
10683 @cindex #+EXPORT_FILE_NAME
10684 The name of the output file to be generated. Otherwise, Org generates the
10685 file name based on the buffer name and the extension based on the back-end
10689 The @code{#+OPTIONS} keyword is a compact form. To configure multiple
10690 options, use several @code{#+OPTIONS} lines. @code{#+OPTIONS} recognizes the
10691 following arguments.
10695 @vindex org-export-with-smart-quotes
10696 Toggle smart quotes (@code{org-export-with-smart-quotes}). Depending on the
10697 language used, when activated, Org treats pairs of double quotes as primary
10698 quotes, pairs of single quotes as secondary quotes, and single quote marks as
10702 Toggle emphasized text (@code{org-export-with-emphasize}).
10705 @vindex org-export-with-special-strings
10706 Toggle conversion of special strings
10707 (@code{org-export-with-special-strings}).
10710 @vindex org-export-with-fixed-width
10711 Toggle fixed-width sections
10712 (@code{org-export-with-fixed-width}).
10715 @vindex org-export-with-timestamps
10716 Toggle inclusion of time/date active/inactive stamps
10717 (@code{org-export-with-timestamps}).
10720 @vindex org-export-preserve-breaks
10721 Toggles whether to preserve line breaks (@code{org-export-preserve-breaks}).
10724 @vindex org-export-with-sub-superscripts
10725 Toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}",
10726 @samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as
10727 it is (@code{org-export-with-sub-superscripts}).
10730 @vindex org-export-with-archived-trees
10731 Configure how archived trees are exported. When set to @code{headline}, the
10732 export process skips the contents and processes only the headlines
10733 (@code{org-export-with-archived-trees}).
10736 @vindex org-export-with-author
10737 Toggle inclusion of author name into exported file
10738 (@code{org-export-with-author}).
10740 @item broken-links:
10741 @vindex org-export-with-broken-links
10742 Toggles if Org should continue exporting upon finding a broken internal link.
10743 When set to @code{mark}, Org clearly marks the problem link in the output
10744 (@code{org-export-with-broken-links}).
10747 @vindex org-export-with-clocks
10748 Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}).
10751 @vindex org-export-with-creator
10752 Toggle inclusion of creator information in the exported file
10753 (@code{org-export-with-creator}).
10756 @vindex org-export-with-drawers
10757 Toggles inclusion of drawers, or list of drawers to include, or list of
10758 drawers to exclude (@code{org-export-with-drawers}).
10761 @vindex org-export-with-date
10762 Toggle inclusion of a date into exported file (@code{org-export-with-date}).
10765 @vindex org-export-with-entities
10766 Toggle inclusion of entities (@code{org-export-with-entities}).
10769 @vindex org-export-with-email
10770 Toggle inclusion of the author's e-mail into exported file
10771 (@code{org-export-with-email}).
10774 @vindex org-export-with-footnotes
10775 Toggle the inclusion of footnotes (@code{org-export-with-footnotes}).
10778 @vindex org-export-headline-levels
10779 Set the number of headline levels for export
10780 (@code{org-export-headline-levels}). Below that level, headlines are treated
10781 differently. In most back-ends, they become list items.
10784 @vindex org-export-with-inlinetasks
10785 Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
10788 @vindex org-export-with-section-numbers
10789 @cindex property, UNNUMBERED
10790 Toggle section-numbers (@code{org-export-with-section-numbers}). When set to
10791 number @samp{n}, Org numbers only those headlines at level @samp{n} or above.
10792 Setting @code{UNNUMBERED} property to non-@code{nil} disables numbering of
10793 a heading. Since subheadings inherit from this property, it affects their
10797 @vindex org-export-with-planning
10798 Toggle export of planning information (@code{org-export-with-planning}).
10799 ``Planning information'' comes from lines located right after the headline
10800 and contain any combination of these cookies: @code{SCHEDULED:},
10801 @code{DEADLINE:}, or @code{CLOSED:}.
10804 @vindex org-export-with-priority
10805 Toggle inclusion of priority cookies (@code{org-export-with-priority}).
10808 @vindex org-export-with-properties
10809 Toggle inclusion of property drawers, or list the properties to include
10810 (@code{org-export-with-properties}).
10813 @vindex org-export-with-statistics-cookies
10814 Toggle inclusion of statistics cookies
10815 (@code{org-export-with-statistics-cookies}).
10818 @vindex org-export-with-tags
10819 Toggle inclusion of tags, may also be @code{not-in-toc}
10820 (@code{org-export-with-tags}).
10823 @vindex org-export-with-tasks
10824 Toggle inclusion of tasks (TODO items); or @code{nil} to remove all tasks; or
10825 @code{todo} to remove DONE tasks; or list the keywords to keep
10826 (@code{org-export-with-tasks}).
10829 @vindex org-export-with-latex
10830 @code{nil} does not export; @code{t} exports; @code{verbatim} keeps
10831 everything in verbatim (@code{org-export-with-latex}).
10834 @vindex org-export-time-stamp-file
10835 Toggle inclusion of the creation time in the exported file
10836 (@code{org-export-time-stamp-file}).
10839 @vindex org-export-with-title
10840 Toggle inclusion of title (@code{org-export-with-title}).
10843 @vindex org-export-with-toc
10844 Toggle inclusion of the table of contents, or set the level limit
10845 (@code{org-export-with-toc}).
10848 @vindex org-export-with-todo-keywords
10849 Toggle inclusion of TODO keywords into exported text
10850 (@code{org-export-with-todo-keywords}).
10853 @vindex org-export-with-tables
10854 Toggle inclusion of tables (@code{org-export-with-tables}).
10858 When exporting sub-trees, special node properties in them can override the
10859 above keywords. They are special because they have an @samp{EXPORT_} prefix.
10860 For example, @samp{DATE} and @samp{EXPORT_FILE_NAME} keywords become,
10861 respectively, @samp{EXPORT_DATE} and @samp{EXPORT_FILE_NAME}. Except for
10862 @samp{SETUPFILE}, all other keywords listed above have an @samp{EXPORT_}
10866 @vindex org-export-allow-bind-keywords
10867 If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables
10868 can become buffer-local during export by using the BIND keyword. Its syntax
10869 is @samp{#+BIND: variable value}. This is particularly useful for in-buffer
10870 settings that cannot be changed using keywords.
10872 @node Table of contents
10873 @section Table of contents
10874 @cindex table of contents
10875 @cindex list of tables
10876 @cindex list of listings
10879 @vindex org-export-with-toc
10880 Org normally inserts the table of contents directly before the first headline
10881 of the file. Org sets the TOC depth the same as the headline levels in the
10882 file. Use a lower number for lower TOC depth. To turn off TOC entirely, use
10883 @code{nil}. This is configured in the @code{org-export-with-toc} variable or
10884 as keywords in an Org file as:
10887 #+OPTIONS: toc:2 @r{only include two levels in TOC}
10888 #+OPTIONS: toc:nil @r{no default TOC at all}
10891 To move the table of contents to a different location, first turn off the
10892 default with @code{org-export-with-toc} variable or with @code{#+OPTIONS:
10893 toc:nil}. Then insert @code{#+TOC: headlines N} at the desired location(s).
10896 #+OPTIONS: toc:nil @r{no default TOC}
10898 #+TOC: headlines 2 @r{insert TOC here, with two headline levels}
10901 To adjust the TOC depth for a specific section of the Org document, append an
10902 additional @samp{local} parameter. This parameter becomes a relative depth
10903 for the current level.
10905 Note that for this feature to work properly in @LaTeX{} export, the Org file
10906 requires the inclusion of the @code{titletoc} package. Because of
10907 compatibility issues, @code{titletoc} has to be loaded @emph{before}
10908 @code{hyperref}. Customize the @code{org-latex-default-packages-alist}
10912 * Section #+TOC: headlines 1 local @r{insert local TOC, with direct children
10916 Use the @code{TOC} keyword to generate list of tables (resp.@: all listings)
10920 #+TOC: listings @r{build a list of listings}
10921 #+TOC: tables @r{build a list of tables}
10924 @cindex property, ALT_TITLE
10925 Normally Org uses the headline for its entry in the table of contents. But
10926 with @code{ALT_TITLE} property, a different entry can be specified for the
10929 @node Include files
10930 @section Include files
10931 @cindex include files, during export
10932 Include other files during export. For example, to include your @file{.emacs}
10933 file, you could use:
10937 #+INCLUDE: "~/.emacs" src emacs-lisp
10941 The first parameter is the file name to include. The optional second
10942 parameter specifies the block type: @samp{example}, @samp{export} or
10943 @samp{src}. The optional third parameter specifies the source code language
10944 to use for formatting the contents. This is relevant to both @samp{export}
10945 and @samp{src} block types.
10947 If an include file is specified as having a markup language, Org neither
10948 checks for valid syntax nor changes the contents in any way. For
10949 @samp{example} and @samp{src} blocks, Org code-escapes the contents before
10952 If an include file is not specified as having any markup language, Org
10953 assumes it be in Org format and proceeds as usual with a few exceptions. Org
10954 makes the footnote labels (@pxref{Footnotes}) in the included file local to
10955 that file. The contents of the included file will belong to the same
10956 structure---headline, item---containing the @code{INCLUDE} keyword. In
10957 particular, headlines within the file will become children of the current
10958 section. That behavior can be changed by providing an additional keyword
10959 parameter, @code{:minlevel}. It shifts the headlines in the included file to
10960 become the lowest level. For example, this syntax makes the included file
10961 a sibling of the current top-level headline:
10964 #+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
10967 Inclusion of only portions of files are specified using ranges parameter with
10968 @code{:lines} keyword. The line at the upper end of the range will not be
10969 included. The start and/or the end of the range may be omitted to use the
10973 #+INCLUDE: "~/.emacs" :lines "5-10" @r{Include lines 5 to 10, 10 excluded}
10974 #+INCLUDE: "~/.emacs" :lines "-10" @r{Include lines 1 to 10, 10 excluded}
10975 #+INCLUDE: "~/.emacs" :lines "10-" @r{Include lines from 10 to EOF}
10978 Inclusions may specify a file-link to extract an object matched by
10979 @code{org-link-search}@footnote{Note that
10980 @code{org-link-search-must-match-exact-headline} is locally bound to
10981 non-@code{nil}. Therefore, @code{org-link-search} only matches headlines and
10982 named elements.} (@pxref{Search options}).
10984 To extract only the contents of the matched object, set @code{:only-contents}
10985 property to non-@code{nil}. This will omit any planning lines or property
10986 drawers. The ranges for @code{:lines} keyword are relative to the requested
10987 element. Some examples:
10990 #+INCLUDE: "./paper.org::#theory" :only-contents t
10991 @r{Include the body of the heading with the custom id @samp{theory}}
10992 #+INCLUDE: "./paper.org::mytable" @r{Include named element.}
10993 #+INCLUDE: "./paper.org::*conclusion" :lines 1-20
10994 @r{Include the first 20 lines of the headline named @samp{conclusion}.}
11000 Visit the include file at point.
11003 @node Macro replacement
11004 @section Macro replacement
11005 @cindex macro replacement, during export
11008 @vindex org-export-global-macros
11009 Macros replace text snippets during export. Macros are defined globally in
11010 @code{org-export-global-macros}, or document-wise with the following syntax:
11013 #+MACRO: name replacement text $1, $2 are arguments
11016 @noindent which can be referenced using
11017 @code{@{@{@{name(arg1, arg2)@}@}@}}@footnote{Since commas separate the
11018 arguments, commas within arguments have to be escaped with the backslash
11019 character. So only those backslash characters before a comma need escaping
11020 with another backslash character.}.
11022 Org recognizes macro references in following Org markup areas: paragraphs,
11023 headlines, verse blocks, tables cells and lists. Org also recognizes macro
11024 references in keywords, such as @code{#+CAPTION}, @code{#+TITLE},
11025 @code{#+AUTHOR}, @code{#+DATE}, and for some back-end specific export
11028 Org comes with following pre-defined macros:
11031 @item @{@{@{title@}@}@}
11032 @itemx @{@{@{author@}@}@}
11033 @itemx @{@{@{email@}@}@}
11034 @cindex title, macro
11035 @cindex author, macro
11036 @cindex email, macro
11037 Org replaces these macro references with available information at the time of
11040 @item @{@{@{date@}@}@}
11041 @itemx @{@{@{date(@var{FORMAT})@}@}@}
11042 @cindex date, macro
11043 This macro refers to the @code{#+DATE} keyword. @var{FORMAT} is an optional
11044 argument to the @code{@{@{@{date@}@}@}} macro that will be used only if
11045 @code{#+DATE} is a single timestamp. @var{FORMAT} should be a format string
11046 understood by @code{format-time-string}.
11048 @item @{@{@{time(@var{FORMAT})@}@}@}
11049 @itemx @{@{@{modification-time(@var{FORMAT}, @var{VC})@}@}@}
11050 @cindex time, macro
11051 @cindex modification time, macro
11052 These macros refer to the document's date and time of export and date and
11053 time of modification. @var{FORMAT} is a string understood by
11054 @code{format-time-string}. If the second argument to the
11055 @code{modification-time} macro is non-@code{nil}, Org uses @file{vc.el} to
11056 retrieve the document's modification time from the version control
11057 system. Otherwise Org reads the file attributes.
11059 @item @{@{@{input-file@}@}@}
11060 @cindex input file, macro
11061 This macro refers to the filename of the exported file.
11063 @item @{@{@{property(@var{PROPERTY-NAME})@}@}@}
11064 @itemx @{@{@{property(@var{PROPERTY-NAME},@var{SEARCH-OPTION})@}@}@}
11065 @cindex property, macro
11066 This macro returns the value of property @var{PROPERTY-NAME} in the current
11067 entry. If @var{SEARCH-OPTION} (@pxref{Search options}) refers to a remote
11068 entry, that will be used instead.
11070 @item @{@{@{n@}@}@}
11071 @itemx @{@{@{n(@var{NAME})@}@}@}
11072 @itemx @{@{@{n(@var{NAME},@var{ACTION})@}@}@}
11074 @cindex counter, macro
11075 This macro implements custom counters by returning the number of times the
11076 macro has been expanded so far while exporting the buffer. You can create
11077 more than one counter using different @var{NAME} values. If @var{ACTION} is
11078 @code{-}, previous value of the counter is held, i.e. the specified counter
11079 is not incremented. If the value is a number, the specified counter is set
11080 to that value. If it is any other non-empty string, the specified counter is
11081 reset to 1. You may leave @var{NAME} empty to reset the default counter.
11084 The surrounding brackets can be made invisible by setting
11085 @code{org-hide-macro-markers} non-@code{nil}.
11087 Org expands macros at the very beginning of the export process.
11089 @node Comment lines
11090 @section Comment lines
11091 @cindex exporting, not
11093 @cindex comment lines
11094 Lines starting with zero or more whitespace characters followed by one
11095 @samp{#} and a whitespace are treated as comments and, as such, are not
11098 @cindex #+BEGIN_COMMENT
11099 Likewise, regions surrounded by @samp{#+BEGIN_COMMENT}
11100 ... @samp{#+END_COMMENT} are not exported.
11102 @cindex comment trees
11103 Finally, a @samp{COMMENT} keyword at the beginning of an entry, but after any
11104 other keyword or priority cookie, comments out the entire subtree. In this
11105 case, the subtree is not exported and no code block within it is executed
11106 either@footnote{For a less drastic behavior, consider using a select tag
11107 (@pxref{Export settings}) instead.}. The command below helps changing the
11108 comment status of a headline.
11113 Toggle the @samp{COMMENT} keyword at the beginning of an entry.
11116 @node ASCII/Latin-1/UTF-8 export
11117 @section ASCII/Latin-1/UTF-8 export
11118 @cindex ASCII export
11119 @cindex Latin-1 export
11120 @cindex UTF-8 export
11122 ASCII export produces an output file containing only plain ASCII characters.
11123 This is the most simplest and direct text output. It does not contain any
11124 Org markup either. Latin-1 and UTF-8 export use additional characters and
11125 symbols available in these encoding standards. All three of these export
11126 formats offer the most basic of text output for maximum portability.
11128 @vindex org-ascii-text-width
11129 On export, Org fills and justifies text according to the text width set in
11130 @code{org-ascii-text-width}.
11132 @vindex org-ascii-links-to-notes
11133 Org exports links using a footnote-like style where the descriptive part is
11134 in the text and the link is in a note before the next heading. See the
11135 variable @code{org-ascii-links-to-notes} for details.
11137 @subheading ASCII export commands
11140 @orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii}
11141 Export as an ASCII file with a @file{.txt} extension. For @file{myfile.org},
11142 Org exports to @file{myfile.txt}, overwriting without warning. For
11143 @file{myfile.txt}, Org exports to @file{myfile.txt.txt} in order to prevent
11145 @orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii}
11146 Export to a temporary buffer. Does not create a file.
11149 @subheading ASCII specific export settings
11150 The ASCII export back-end has one extra keyword for customizing ASCII output.
11151 Setting this keyword works similar to the general options (@pxref{Export
11156 @cindex #+SUBTITLE (ASCII)
11157 The document subtitle. For long subtitles, use multiple @code{#+SUBTITLE}
11158 lines in the Org file. Org prints them on one continuous line, wrapping into
11159 multiple lines if necessary.
11162 @subheading Header and sectioning structure
11164 Org converts the first three outline levels into headlines for ASCII export.
11165 The remaining levels are turned into lists. To change this cut-off point
11166 where levels become lists, @pxref{Export settings}.
11168 @subheading Quoting ASCII text
11170 To insert text within the Org file by the ASCII back-end, use one the
11171 following constructs, inline, keyword, or export block:
11174 @cindex #+BEGIN_EXPORT ascii
11176 Inline text @@@@ascii:and additional text@@@@ within a paragraph.
11180 #+BEGIN_EXPORT ascii
11181 Org exports text in this block only when using ASCII back-end.
11185 @subheading ASCII specific attributes
11186 @cindex #+ATTR_ASCII
11187 @cindex horizontal rules, in ASCII export
11189 ASCII back-end recognizes only one attribute, @code{:width}, which specifies
11190 the width of an horizontal rule in number of characters. The keyword and
11191 syntax for specifying widths is:
11194 #+ATTR_ASCII: :width 10
11198 @subheading ASCII special blocks
11199 @cindex special blocks, in ASCII export
11200 @cindex #+BEGIN_JUSTIFYLEFT
11201 @cindex #+BEGIN_JUSTIFYRIGHT
11203 Besides @code{#+BEGIN_CENTER} blocks (@pxref{Paragraphs}), ASCII back-end has
11204 these two left and right justification blocks:
11207 #+BEGIN_JUSTIFYLEFT
11208 It's just a jump to the left...
11211 #+BEGIN_JUSTIFYRIGHT
11212 ...and then a step to the right.
11216 @node Beamer export
11217 @section Beamer export
11218 @cindex Beamer export
11220 Org uses @emph{Beamer} export to convert an Org file tree structure into a
11221 high-quality interactive slides for presentations. @emph{Beamer} is a
11222 @LaTeX{} document class for creating presentations in PDF, HTML, and other
11223 popular display formats.
11226 * Beamer export commands:: For creating Beamer documents.
11227 * Beamer specific export settings:: For customizing Beamer export.
11228 * Sectioning Frames and Blocks in Beamer:: For composing Beamer slides.
11229 * Beamer specific syntax:: For using in Org documents.
11230 * Editing support:: For using helper functions.
11231 * A Beamer example:: A complete presentation.
11234 @node Beamer export commands
11235 @subsection Beamer export commands
11238 @orgcmd{C-c C-e l b,org-beamer-export-to-latex}
11239 Export as @LaTeX{} file with a @file{.tex} extension. For @file{myfile.org},
11240 Org exports to @file{myfile.tex}, overwriting without warning.
11241 @orgcmd{C-c C-e l B,org-beamer-export-as-latex}
11242 Export to a temporary buffer. Does not create a file.
11243 @orgcmd{C-c C-e l P,org-beamer-export-to-pdf}
11244 Export as @LaTeX{} file and then convert it to PDF format.
11246 Export as @LaTeX{} file, convert it to PDF format, and then open the PDF
11250 @node Beamer specific export settings
11251 @subsection Beamer specific export settings
11253 Beamer export back-end has several additional keywords for customizing Beamer
11254 output. These keywords work similar to the general options settings
11255 (@pxref{Export settings}).
11259 @cindex #+BEAMER_THEME
11260 @vindex org-beamer-theme
11261 The Beamer layout theme (@code{org-beamer-theme}). Use square brackets for
11262 options. For example:
11264 #+BEAMER_THEME: Rochester [height=20pt]
11267 @item BEAMER_FONT_THEME
11268 @cindex #+BEAMER_FONT_THEME
11269 The Beamer font theme.
11271 @item BEAMER_INNER_THEME
11272 @cindex #+BEAMER_INNER_THEME
11273 The Beamer inner theme.
11275 @item BEAMER_OUTER_THEME
11276 @cindex #+BEAMER_OUTER_THEME
11277 The Beamer outer theme.
11279 @item BEAMER_HEADER
11280 @cindex #+BEAMER_HEADER
11281 Arbitrary lines inserted in the preamble, just before the @samp{hyperref}
11285 @cindex #+DESCRIPTION (Beamer)
11286 The document description. For long descriptions, use multiple
11287 @code{#+DESCRIPTION} keywords. By default, @samp{hyperref} inserts
11288 @code{#+DESCRIPTION} as metadata. Use @code{org-latex-hyperref-template} to
11289 configure document metadata. Use @code{org-latex-title-command} to configure
11290 typesetting of description as part of front matter.
11293 @cindex #+KEYWORDS (Beamer)
11294 The keywords for defining the contents of the document. Use multiple
11295 @code{#+KEYWORDS} lines if necessary. By default, @samp{hyperref} inserts
11296 @code{#+KEYWORDS} as metadata. Use @code{org-latex-hyperref-template} to
11297 configure document metadata. Use @code{org-latex-title-command} to configure
11298 typesetting of keywords as part of front matter.
11301 @cindex #+SUBTITLE (Beamer)
11302 @vindex org-beamer-subtitle-format
11303 Document's subtitle. For typesetting, use @code{org-beamer-subtitle-format}
11304 string. Use @code{org-latex-hyperref-template} to configure document
11305 metadata. Use @code{org-latex-title-command} to configure typesetting of
11306 subtitle as part of front matter.
11309 @node Sectioning Frames and Blocks in Beamer
11310 @subsection Sectioning, Frames and Blocks in Beamer
11312 Org transforms heading levels into Beamer's sectioning elements, frames and
11313 blocks. Any Org tree with a not-too-deep-level nesting should in principle
11314 be exportable as a Beamer presentation.
11318 @vindex org-beamer-frame-level
11319 Org headlines become Beamer frames when the heading level in Org is equal to
11320 @code{org-beamer-frame-level} or @code{H} value in an @code{OPTIONS} line
11321 (@pxref{Export settings}).
11323 @cindex property, BEAMER_ENV
11324 Org overrides headlines to frames conversion for the current tree of an Org
11325 file if it encounters the @code{BEAMER_ENV} property set to @code{frame} or
11326 @code{fullframe}. Org ignores whatever @code{org-beamer-frame-level} happens
11327 to be for that headline level in the Org tree. In Beamer terminology, a
11328 @code{fullframe} is a frame without its title.
11331 @vindex org-beamer-environments-default
11332 @vindex org-beamer-environments-extra
11333 Org exports a Beamer frame's objects as @code{block} environments. Org can
11334 enforce wrapping in special block types when @code{BEAMER_ENV} property is
11335 set@footnote{If @code{BEAMER_ENV} is set, Org export adds
11336 @code{:B_environment:} tag to make it visible. The tag serves as a visual
11337 aid and has no semantic relevance.}. For valid values see
11338 @code{org-beamer-environments-default}. To add more values, see
11339 @code{org-beamer-environments-extra}.
11342 @cindex property, BEAMER_REF
11343 If @code{BEAMER_ENV} is set to @code{appendix}, Org exports the entry as an
11344 appendix. When set to @code{note}, Org exports the entry as a note within
11345 the frame or between frames, depending on the entry's heading level. When
11346 set to @code{noteNH}, Org exports the entry as a note without its title.
11347 When set to @code{againframe}, Org exports the entry with @code{\againframe}
11348 command, which makes setting the @code{BEAMER_REF} property mandatory because
11349 @code{\againframe} needs frame to resume.
11351 When @code{ignoreheading} is set, Org export ignores the entry's headline but
11352 not its content. This is useful for inserting content between frames. It is
11353 also useful for properly closing a @code{column} environment.
11356 @cindex property, BEAMER_ACT
11357 @cindex property, BEAMER_OPT
11358 When @code{BEAMER_ACT} is set for a headline, Org export translates that
11359 headline as an overlay or action specification. When enclosed in square
11360 brackets, Org export makes the overlay specification a default. Use
11361 @code{BEAMER_OPT} to set any options applicable to the current Beamer frame
11362 or block. The Beamer export back-end wraps with appropriate angular or
11363 square brackets. It also adds the @code{fragile} option for any code that may
11364 require a verbatim block.
11366 @cindex property, BEAMER_COL
11367 To create a column on the Beamer slide, use the @code{BEAMER_COL} property
11368 for its headline in the Org file. Set the value of @code{BEAMER_COL} to a
11369 decimal number representing the fraction of the total text width. Beamer
11370 export uses this value to set the column's width and fills the column with
11371 the contents of the Org entry. If the Org entry has no specific environment
11372 defined, Beamer export ignores the heading. If the Org entry has a defined
11373 environment, Beamer export uses the heading as title. Behind the scenes,
11374 Beamer export automatically handles @LaTeX{} column separations for
11375 contiguous headlines. To manually adjust them for any unique configurations
11376 needs, use the @code{BEAMER_ENV} property.
11378 @node Beamer specific syntax
11379 @subsection Beamer specific syntax
11380 Since Org's Beamer export back-end is an extension of the @LaTeX{} back-end,
11381 it recognizes other @LaTeX{} specific syntax---for example, @samp{#+LATEX:}
11382 or @samp{#+ATTR_LATEX:}. @xref{@LaTeX{} export}, for details.
11384 Beamer export wraps the table of contents generated with @code{toc:t}
11385 @code{OPTION} keyword in a @code{frame} environment. Beamer export does not
11386 wrap the table of contents generated with @code{TOC} keyword (@pxref{Table of
11387 contents}). Use square brackets for specifying options.
11390 #+TOC: headlines [currentsection]
11393 Insert Beamer-specific code using the following constructs:
11396 @cindex #+BEGIN_EXPORT beamer
11400 #+BEGIN_EXPORT beamer
11401 Only Beamer export back-end will export this line.
11404 Text @@@@beamer:some code@@@@ within a paragraph.
11407 Inline constructs, such as the last one above, are useful for adding overlay
11408 specifications to objects with @code{bold}, @code{item}, @code{link},
11409 @code{radio-target} and @code{target} types. Enclose the value in angular
11410 brackets and place the specification at the beginning the object as shown in
11414 A *@@@@beamer:<2->@@@@useful* feature
11417 @cindex #+ATTR_BEAMER
11418 Beamer export recognizes the @code{ATTR_BEAMER} keyword with the following
11419 attributes from Beamer configurations: @code{:environment} for changing local
11420 Beamer environment, @code{:overlay} for specifying Beamer overlays in angular
11421 or square brackets, and @code{:options} for inserting optional arguments.
11424 #+ATTR_BEAMER: :environment nonindentlist
11425 - item 1, not indented
11426 - item 2, not indented
11427 - item 3, not indented
11431 #+ATTR_BEAMER: :overlay <+->
11437 #+ATTR_BEAMER: :options [Lagrange]
11438 Let $G$ be a finite group, and let $H$ be
11439 a subgroup of $G$. Then the order of $H$ divides the order of $G$.
11442 @node Editing support
11443 @subsection Editing support
11446 The @code{org-beamer-mode} is a special minor mode for faster editing of
11454 @orgcmd{C-c C-b,org-beamer-select-environment}
11455 The @code{org-beamer-mode} provides this key for quicker selections in Beamer
11456 normal environments, and for selecting the @code{BEAMER_COL} property.
11459 @node A Beamer example
11460 @subsection A Beamer example
11462 Here is an example of an Org document ready for Beamer export.
11465 #+TITLE: Example Presentation
11466 #+AUTHOR: Carsten Dominik
11467 #+OPTIONS: H:2 toc:t num:t
11468 #+LATEX_CLASS: beamer
11469 #+LATEX_CLASS_OPTIONS: [presentation]
11470 #+BEAMER_THEME: Madrid
11471 #+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) %8BEAMER_OPT(Opt)
11473 * This is the first structural section
11476 *** Thanks to Eric Fraga :B_block:
11481 for the first viable Beamer setup in Org
11482 *** Thanks to everyone else :B_block:
11488 for contributing to the discussion
11489 **** This will be formatted as a beamer note :B_note:
11493 ** Frame 2 (where we will not use columns)
11495 Please test this stuff!
11499 @section HTML export
11500 @cindex HTML export
11502 Org mode contains an HTML exporter with extensive HTML formatting compatible
11503 with XHTML 1.0 strict standard.
11506 * HTML Export commands:: Invoking HTML export
11507 * HTML Specific export settings:: Settings for HTML export
11508 * HTML doctypes:: Exporting various (X)HTML flavors
11509 * HTML preamble and postamble:: Inserting preamble and postamble
11510 * Quoting HTML tags:: Using direct HTML in Org files
11511 * Links in HTML export:: Interpreting and formatting links
11512 * Tables in HTML export:: Formatting and modifying tables
11513 * Images in HTML export:: Inserting figures with HTML output
11514 * Math formatting in HTML export:: Handling math equations
11515 * Text areas in HTML export:: Showing an alternate approach, an example
11516 * CSS support:: Styling HTML output
11517 * JavaScript support:: Folding scripting in the web browser
11521 @node HTML Export commands
11522 @subsection HTML export commands
11525 @orgcmd{C-c C-e h h,org-html-export-to-html}
11526 Export as HTML file with a @file{.html} extension. For @file{myfile.org},
11527 Org exports to @file{myfile.html}, overwriting without warning. @kbd{C-c C-e
11528 h o} Exports to HTML and opens it in a web browser.
11530 @orgcmd{C-c C-e h H,org-html-export-as-html}
11531 Exports to a temporary buffer. Does not create a file.
11534 @node HTML Specific export settings
11535 @subsection HTML Specific export settings
11536 HTML export has a number of keywords, similar to the general options settings
11537 described in @ref{Export settings}.
11541 @cindex #+DESCRIPTION (HTML)
11542 This is the document's description, which the HTML exporter inserts it as a
11543 HTML meta tag in the HTML file. For long descriptions, use multiple
11544 @code{#+DESCRIPTION} lines. The exporter takes care of wrapping the lines
11548 @cindex #+HTML_DOCTYPE
11549 @vindex org-html-doctype
11550 Specify the document type, for example: HTML5 (@code{org-html-doctype}).
11552 @item HTML_CONTAINER
11553 @cindex #+HTML_CONTAINER
11554 @vindex org-html-container-element
11555 Specify the HTML container, such as @samp{div}, for wrapping sections and
11556 elements (@code{org-html-container-element}).
11558 @item HTML_LINK_HOME
11559 @cindex #+HTML_LINK_HOME
11560 @vindex org-html-link-home
11561 The URL for home link (@code{org-html-link-home}).
11564 @cindex #+HTML_LINK_UP
11565 @vindex org-html-link-up
11566 The URL for the up link of exported HTML pages (@code{org-html-link-up}).
11569 @cindex #+HTML_MATHJAX
11570 @vindex org-html-mathjax-options
11571 Options for MathJax (@code{org-html-mathjax-options}). MathJax is used to
11572 typeset @LaTeX{} math in HTML documents. @xref{Math formatting in HTML
11573 export}, for an example.
11576 @cindex #+HTML_HEAD
11577 @vindex org-html-head
11578 Arbitrary lines for appending to the HTML document's head
11579 (@code{org-html-head}).
11581 @item HTML_HEAD_EXTRA
11582 @cindex #+HTML_HEAD_EXTRA
11583 @vindex org-html-head-extra
11584 More arbitrary lines for appending to the HTML document's head
11585 (@code{org-html-head-extra}).
11588 @cindex #+KEYWORDS (HTML)
11589 Keywords to describe the document's content. HTML exporter inserts these
11590 keywords as HTML meta tags. For long keywords, use multiple
11591 @code{#+KEYWORDS} lines.
11594 @cindex #+LATEX_HEADER (HTML)
11595 Arbitrary lines for appending to the preamble; HTML exporter appends when
11596 transcoding @LaTeX{} fragments to images (@pxref{Math formatting in HTML
11600 @cindex #+SUBTITLE (HTML)
11601 The document's subtitle. HTML exporter formats subtitle if document type is
11602 @samp{HTML5} and the CSS has a @samp{subtitle} class.
11605 Some of these keywords are explained in more detail in the following sections
11608 @node HTML doctypes
11609 @subsection HTML doctypes
11611 Org can export to various (X)HTML flavors.
11613 @vindex org-html-doctype
11614 @vindex org-html-doctype-alist
11615 Set the @code{org-html-doctype} variable for different (X)HTML variants.
11616 Depending on the variant, the HTML exporter adjusts the syntax of HTML
11617 conversion accordingly. Org includes the following ready-made variants:
11623 ``html4-transitional''
11629 ``xhtml-transitional''
11640 @noindent See the variable @code{org-html-doctype-alist} for details.
11641 The default is ``xhtml-strict''.
11643 @vindex org-html-html5-fancy
11644 @cindex HTML5, export new elements
11645 Org's HTML exporter does not by default enable new block elements introduced
11646 with the HTML5 standard. To enable them, set @code{org-html-html5-fancy} to
11647 non-@code{nil}. Or use an @code{OPTIONS} line in the file to set
11648 @code{html5-fancy}. HTML5 documents can now have arbitrary @code{#+BEGIN}
11649 and @code{#+END} blocks. For example:
11668 #+ATTR_HTML: :controls controls :width 350
11670 #+HTML: <source src="movie.mp4" type="video/mp4">
11671 #+HTML: <source src="movie.ogg" type="video/ogg">
11672 Your browser does not support the video tag.
11679 <video controls="controls" width="350">
11680 <source src="movie.mp4" type="video/mp4">
11681 <source src="movie.ogg" type="video/ogg">
11682 <p>Your browser does not support the video tag.</p>
11686 @vindex org-html-html5-elements
11687 When special blocks do not have a corresponding HTML5 element, the HTML
11688 exporter reverts to standard translation (see
11689 @code{org-html-html5-elements}). For example, @code{#+BEGIN_lederhosen}
11690 exports to @samp{<div class="lederhosen">}.
11692 Special blocks cannot have headlines. For the HTML exporter to wrap the
11693 headline and its contents in @samp{<section>} or @samp{<article>} tags, set
11694 the @code{HTML_CONTAINER} property for the headline.
11696 @node HTML preamble and postamble
11697 @subsection HTML preamble and postamble
11698 @vindex org-html-preamble
11699 @vindex org-html-postamble
11700 @vindex org-html-preamble-format
11701 @vindex org-html-postamble-format
11702 @vindex org-html-validation-link
11703 @vindex org-export-creator-string
11704 @vindex org-export-time-stamp-file
11706 The HTML exporter has delineations for preamble and postamble. The default
11707 value for @code{org-html-preamble} is @code{t}, which makes the HTML exporter
11708 insert the preamble. See the variable @code{org-html-preamble-format} for
11711 Set @code{org-html-preamble} to a string to override the default format
11712 string. If the string is a function, the HTML exporter expects the function
11713 to return a string upon execution. The HTML exporter inserts this string in
11714 the preamble. The HTML exporter will not insert a preamble if
11715 @code{org-html-preamble} is set @code{nil}.
11717 The default value for @code{org-html-postamble} is @code{auto}, which makes
11718 the HTML exporter build a postamble from looking up author's name, email
11719 address, creator's name, and date. Set @code{org-html-postamble} to @code{t}
11720 to insert the postamble in the format specified in the
11721 @code{org-html-postamble-format} variable. The HTML exporter will not insert
11722 a postamble if @code{org-html-postamble} is set to @code{nil}.
11724 @node Quoting HTML tags
11725 @subsection Quoting HTML tags
11727 The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and
11728 @samp{>}. To include raw HTML code in the Org file so the HTML export
11729 back-end can insert that HTML code in the output, use this inline syntax:
11730 @samp{@@@@html:}. For example: @samp{@@@@html:<b>@@@@bold
11731 text@@@@html:</b>@@@@}. For larger raw HTML code blocks, use these HTML
11732 export code blocks:
11735 @cindex #+BEGIN_EXPORT html
11737 #+HTML: Literal HTML code for export
11741 @cindex #+BEGIN_EXPORT html
11744 #+BEGIN_EXPORT html
11745 All lines between these markers are exported literally
11750 @node Links in HTML export
11751 @subsection Links in HTML export
11753 @cindex links, in HTML export
11754 @cindex internal links, in HTML export
11755 @cindex external links, in HTML export
11756 @vindex org-html-link-org-files-as-html
11757 The HTML export back-end transforms Org's internal links (@pxref{Internal
11758 links}) to equivalent HTML links in the output. The back-end similarly
11759 handles Org's automatic links created by radio targets (@pxref{Radio
11760 targets}) similarly. For Org links to external files, the back-end
11761 transforms the links to @emph{relative} paths.
11763 For Org links to other @file{.org} files, the back-end automatically changes
11764 the file extension to @file{.html} and makes file paths relative. If the
11765 @file{.org} files have an equivalent @file{.html} version at the same
11766 location, then the converted links should work without any further manual
11767 intervention. However, to disable this automatic path translation, set
11768 @code{org-html-link-org-files-as-html} to @code{nil}. When disabled, the
11769 HTML export back-end substitutes the @samp{id:}-based links in the HTML
11770 output. For more about linking files when publishing to a directory,
11771 @pxref{Publishing links}.
11773 Org files can also have special directives to the HTML export back-end. For
11774 example, by using @code{#+ATTR_HTML} lines to specify new format attributes
11775 to @code{<a>} or @code{<img>} tags. This example shows changing the link's
11776 @code{title} and @code{style}:
11778 @cindex #+ATTR_HTML
11780 #+ATTR_HTML: :title The Org mode homepage :style color:red;
11781 [[http://orgmode.org]]
11784 @node Tables in HTML export
11785 @subsection Tables in HTML export
11786 @cindex tables, in HTML
11787 @vindex org-html-table-default-attributes
11789 The HTML export back-end uses @code{org-html-table-default-attributes} when
11790 exporting Org tables to HTML. By default, the exporter does not draw frames
11791 and cell borders. To change for this for a table, use the following lines
11792 before the table in the Org file:
11795 @cindex #+ATTR_HTML
11797 #+CAPTION: This is a table with lines around and between cells
11798 #+ATTR_HTML: :border 2 :rules all :frame border
11801 The HTML export back-end preserves column groupings in Org tables
11802 (@pxref{Column groups}) when exporting to HTML.
11804 Additional options for customizing tables for HTML export.
11807 @vindex org-html-table-align-individual-fields
11808 @item org-html-table-align-individual-fields
11809 Non-@code{nil} attaches style attributes for alignment to each table field.
11811 @vindex org-html-table-caption-above
11812 @item org-html-table-caption-above
11813 Non-@code{nil} places caption string at the beginning of the table.
11815 @vindex org-html-table-data-tags
11816 @item org-html-table-data-tags
11817 Opening and ending tags for table data fields.
11819 @vindex org-html-table-default-attributes
11820 @item org-html-table-default-attributes
11821 Default attributes and values for table tags.
11823 @vindex org-html-table-header-tags
11824 @item org-html-table-header-tags
11825 Opening and ending tags for table's header fields.
11827 @vindex org-html-table-row-tags
11828 @item org-html-table-row-tags
11829 Opening and ending tags for table rows.
11831 @vindex org-html-table-use-header-tags-for-first-column
11832 @item org-html-table-use-header-tags-for-first-column
11833 Non-@code{nil} formats column one in tables with header tags.
11836 @node Images in HTML export
11837 @subsection Images in HTML export
11839 @cindex images, inline in HTML
11840 @cindex inlining images in HTML
11841 @vindex org-html-inline-images
11843 The HTML export back-end has features to convert Org image links to HTML
11844 inline images and HTML clickable image links.
11846 When the link in the Org file has no description, the HTML export back-end by
11847 default in-lines that image. For example: @samp{[[file:myimg.jpg]]} is
11848 in-lined, while @samp{[[file:myimg.jpg][the image]]} links to the text,
11851 For more details, see the variable @code{org-html-inline-images}.
11853 On the other hand, if the description part of the Org link is itself another
11854 link, such as @code{file:} or @code{http:} URL pointing to an image, the HTML
11855 export back-end in-lines this image and links to the main image. This Org
11856 syntax enables the back-end to link low-resolution thumbnail to the
11857 high-resolution version of the image, as shown in this example:
11860 [[file:highres.jpg][file:thumb.jpg]]
11863 To change attributes of in-lined images, use @code{#+ATTR_HTML} lines in the
11864 Org file. This example shows realignment to right, and adds @code{alt} and
11865 @code{title} attributes in support of text viewers and modern web accessibility
11869 @cindex #+ATTR_HTML
11871 #+CAPTION: A black cat stalking a spider
11872 #+ATTR_HTML: :alt cat/spider image :title Action! :align right
11877 The HTML export back-end copies the @code{http} links from the Org file as
11880 @node Math formatting in HTML export
11881 @subsection Math formatting in HTML export
11885 @cindex imagemagick
11887 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two
11888 different ways on HTML pages. The default is to use
11889 @uref{http://www.mathjax.org, MathJax} which should work out of the box with
11890 Org@footnote{By default Org loads MathJax from @uref{https://cdnjs.com, cdnjs.com} as
11891 recommended by @uref{http://www.mathjax.org, MathJax}.}. Some MathJax display
11892 options can be configured via @code{org-html-mathjax-options}, or in the
11893 buffer. For example, with the following settings,
11895 #+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
11897 equation labels will be displayed on the left margin and equations will be
11898 five ems from the left margin.
11900 @noindent See the docstring of
11901 @code{org-html-mathjax-options} for all supported variables. The MathJax
11902 template can be configure via @code{org-html-mathjax-template}.
11904 If you prefer, you can also request that @LaTeX{} fragments are processed
11905 into small images that will be inserted into the browser page. Before the
11906 availability of MathJax, this was the default method for Org files. This
11907 method requires that the @file{dvipng} program, @file{dvisvgm} or
11908 @file{imagemagick} suite is available on your system. You can still get
11909 this processing with
11912 #+OPTIONS: tex:dvipng
11916 #+OPTIONS: tex:dvisvgm
11922 #+OPTIONS: tex:imagemagick
11925 @node Text areas in HTML export
11926 @subsection Text areas in HTML export
11928 @cindex text areas, in HTML
11929 Before Org mode's Babel, one popular approach to publishing code in HTML was
11930 by using @code{:textarea}. The advantage of this approach was that copying
11931 and pasting was built into browsers with simple JavaScript commands. Even
11932 editing before pasting was made simple.
11934 The HTML export back-end can create such text areas. It requires an
11935 @code{#+ATTR_HTML:} line as shown in the example below with the
11936 @code{:textarea} option. This must be followed by either an
11937 @code{example} or a @code{src} code block. Other Org block types will not
11938 honor the @code{:textarea} option.
11940 By default, the HTML export back-end creates a text area 80 characters wide
11941 and height just enough to fit the content. Override these defaults with
11942 @code{:width} and @code{:height} options on the @code{#+ATTR_HTML:} line.
11945 #+ATTR_HTML: :textarea t :width 40
11947 (defun org-xor (a b)
11955 @subsection CSS support
11956 @cindex CSS, for HTML export
11957 @cindex HTML export, CSS
11959 @vindex org-html-todo-kwd-class-prefix
11960 @vindex org-html-tag-class-prefix
11961 You can modify the CSS style definitions for the exported file. The HTML
11962 exporter assigns the following special CSS classes@footnote{If the classes on
11963 TODO keywords and tags lead to conflicts, use the variables
11964 @code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to
11965 make them unique.} to appropriate parts of the document---your style
11966 specifications may change these, in addition to any of the standard classes
11967 like for headlines, tables, etc.
11969 p.author @r{author information, including email}
11970 p.date @r{publishing date}
11971 p.creator @r{creator info, about org mode version}
11972 .title @r{document title}
11973 .subtitle @r{document subtitle}
11974 .todo @r{TODO keywords, all not-done states}
11975 .done @r{the DONE keywords, all states that count as done}
11976 .WAITING @r{each TODO keyword also uses a class named after itself}
11977 .timestamp @r{timestamp}
11978 .timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED}
11979 .timestamp-wrapper @r{span around keyword plus timestamp}
11980 .tag @r{tag in a headline}
11981 ._HOME @r{each tag uses itself as a class, "@@" replaced by "_"}
11982 .target @r{target for links}
11983 .linenr @r{the line number in a code example}
11984 .code-highlighted @r{for highlighting referenced code lines}
11985 div.outline-N @r{div for outline level N (headline plus text))}
11986 div.outline-text-N @r{extra div for text at outline level N}
11987 .section-number-N @r{section number in headlines, different for each level}
11988 .figure-number @r{label like "Figure 1:"}
11989 .table-number @r{label like "Table 1:"}
11990 .listing-number @r{label like "Listing 1:"}
11991 div.figure @r{how to format an in-lined image}
11992 pre.src @r{formatted source code}
11993 pre.example @r{normal example}
11994 p.verse @r{verse paragraph}
11995 div.footnotes @r{footnote section headline}
11996 p.footnote @r{footnote definition paragraph, containing a footnote}
11997 .footref @r{a footnote reference number (always a <sup>)}
11998 .footnum @r{footnote number in footnote definition (always <sup>)}
11999 .org-svg @r{default class for a linked @file{.svg} image}
12002 @vindex org-html-style-default
12003 @vindex org-html-head-include-default-style
12004 @vindex org-html-head
12005 @vindex org-html-head-extra
12006 @cindex #+HTML_INCLUDE_STYLE
12007 The HTML export back-end includes a compact default style in each exported
12008 HTML file. To override the default style with another style, use these
12009 keywords in the Org file. They will replace the global defaults the HTML
12012 @cindex #+HTML_HEAD
12013 @cindex #+HTML_HEAD_EXTRA
12015 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
12016 #+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
12019 To just turn off the default style, customize
12020 @code{org-html-head-include-default-style} variable, or use this option line in
12024 #+OPTIONS: html-style:nil
12028 For longer style definitions, either use several @code{#+HTML_HEAD} and
12029 @code{#+HTML_HEAD_EXTRA} lines, or use @code{<style>} @code{</style>} blocks
12030 around them. Both of these approaches can avoid referring to an external
12033 In order to add styles to a sub-tree, use the @code{:HTML_CONTAINER_CLASS:}
12034 property to assign a class to the tree. In order to specify CSS styles for a
12035 particular headline, you can use the id specified in a @code{:CUSTOM_ID:}
12038 Never change the @code{org-html-style-default} constant. Instead use other
12039 simpler ways of customizing as described above.
12042 @c FIXME: More about header and footer styles
12043 @c FIXME: Talk about links and targets.
12045 @node JavaScript support
12046 @subsection JavaScript supported display of web pages
12048 @cindex Rose, Sebastian
12049 Sebastian Rose has written a JavaScript program especially designed to
12050 enhance the web viewing experience of HTML files created with Org. This
12051 program enhances large files in two different ways of viewing. One is an
12052 @emph{Info}-like mode where each section is displayed separately and
12053 navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys
12054 as well, press @kbd{?} for an overview of the available keys). The second
12055 one has a @emph{folding} view, much like Org provides inside Emacs. The
12056 script is available at @url{http://orgmode.org/org-info.js} and the
12057 documentation at @url{http://orgmode.org/worg/code/org-info-js/}. The script
12058 is hosted on @url{http://orgmode.org}, but for reliability, prefer installing
12059 it on your own web server.
12061 To use this program, just add this line to the Org file:
12063 @cindex #+INFOJS_OPT
12065 #+INFOJS_OPT: view:info toc:nil
12069 The HTML header now has the code needed to automatically invoke the script.
12070 For setting options, use the syntax from the above line for options described
12074 path: @r{The path to the script. The default grabs the script from}
12075 @r{@url{http://orgmode.org/org-info.js}, but you might want to have}
12076 @r{a local copy and use a path like @samp{../scripts/org-info.js}.}
12077 view: @r{Initial view when the website is first shown. Possible values are:}
12078 info @r{Info-like interface with one section per page.}
12079 overview @r{Folding interface, initially showing only top-level.}
12080 content @r{Folding interface, starting with all headlines visible.}
12081 showall @r{Folding interface, all headlines and text visible.}
12082 sdepth: @r{Maximum headline level that will still become an independent}
12083 @r{section for info and folding modes. The default is taken from}
12084 @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).}
12085 @r{If this is smaller than in @code{org-export-headline-levels}, each}
12086 @r{info/folding section can still contain child headlines.}
12087 toc: @r{Should the table of contents @emph{initially} be visible?}
12088 @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}
12089 tdepth: @r{The depth of the table of contents. The defaults are taken from}
12090 @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}
12091 ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?}
12092 @r{If yes, the toc will never be displayed as a section.}
12093 ltoc: @r{Should there be short contents (children) in each section?}
12094 @r{Make this @code{above} if the section should be above initial text.}
12095 mouse: @r{Headings are highlighted when the mouse is over them. Should be}
12096 @r{@samp{underline} (default) or a background color like @samp{#cccccc}.}
12097 buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the}
12098 @r{default), only one such button will be present.}
12101 @vindex org-html-infojs-options
12102 @vindex org-html-use-infojs
12103 You can choose default values for these options by customizing the variable
12104 @code{org-html-infojs-options}. If you want the script to always apply to
12105 your pages, configure the variable @code{org-html-use-infojs}.
12107 @node @LaTeX{} export
12108 @section @LaTeX{} export
12109 @cindex @LaTeX{} export
12112 The @LaTeX{} export back-end can handle complex documents, incorporate
12113 standard or custom @LaTeX{} document classes, generate documents using
12114 alternate @LaTeX{} engines, and produce fully linked PDF files with indexes,
12115 bibliographies, and tables of contents, destined for interactive online
12116 viewing or high-quality print publication.
12118 While the details are covered in-depth in this section, here are some quick
12119 references to variables for the impatient: for engines, see
12120 @code{org-latex-compiler}; for build sequences, see
12121 @code{org-latex-pdf-process}; for packages, see
12122 @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.
12124 An important note about the @LaTeX{} export back-end: it is sensitive to
12125 blank lines in the Org document. That's because @LaTeX{} itself depends on
12126 blank lines to tell apart syntactical elements, such as paragraphs.
12129 * @LaTeX{} export commands:: For producing @LaTeX{} and PDF documents.
12130 * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end.
12131 * @LaTeX{} header and sectioning:: For file structure.
12132 * Quoting @LaTeX{} code:: Directly in the Org document.
12133 * Tables in @LaTeX{} export:: Attributes specific to tables.
12134 * Images in @LaTeX{} export:: Attributes specific to images.
12135 * Plain lists in @LaTeX{} export:: Attributes specific to lists.
12136 * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks.
12137 * Example blocks in @LaTeX{} export:: Attributes specific to example blocks.
12138 * Special blocks in @LaTeX{} export:: Attributes specific to special blocks.
12139 * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules.
12142 @node @LaTeX{} export commands
12143 @subsection @LaTeX{} export commands
12146 @orgcmd{C-c C-e l l,org-latex-export-to-latex}
12147 Export as @LaTeX{} file with a @file{.tex} extension. For @file{myfile.org},
12148 Org exports to @file{myfile.tex}, overwriting without warning. @kbd{C-c C-e
12149 l l} Exports to @LaTeX{} file.
12151 @orgcmd{C-c C-e l L,org-latex-export-as-latex}
12152 Export to a temporary buffer. Do not create a file.
12153 @orgcmd{C-c C-e l p,org-latex-export-to-pdf}
12154 Export as @LaTeX{} file and convert it to PDF file.
12156 Export as @LaTeX{} file and convert it to PDF, then open the PDF using the default viewer.
12159 @vindex org-latex-compiler
12160 @vindex org-latex-bibtex-compiler
12161 @vindex org-latex-default-packages-alist
12162 The @LaTeX{} export back-end can use any of these @LaTeX{} engines:
12163 @samp{pdflatex}, @samp{xelatex}, and @samp{lualatex}. These engines compile
12164 @LaTeX{} files with different compilers, packages, and output options. The
12165 @LaTeX{} export back-end finds the compiler version to use from
12166 @code{org-latex-compiler} variable or the @code{#+LATEX_COMPILER} keyword in
12167 the Org file. See the docstring for the
12168 @code{org-latex-default-packages-alist} for loading packages with certain
12169 compilers. Also see @code{org-latex-bibtex-compiler} to set the bibliography
12170 compiler@footnote{This does not allow setting different bibliography
12171 compilers for different files. However, ``smart'' @LaTeX{} compilation
12172 systems, such as @samp{latexmk}, can select the correct bibliography
12175 @node @LaTeX{} specific export settings
12176 @subsection @LaTeX{} specific export settings
12178 The @LaTeX{} export back-end has several additional keywords for customizing
12179 @LaTeX{} output. Setting these keywords works similar to the general options
12180 (@pxref{Export settings}).
12184 @cindex #+DESCRIPTION (@LaTeX{})
12185 The document's description. The description along with author name,
12186 keywords, and related file metadata are inserted in the output file by the
12187 @samp{hyperref} package. See @code{org-latex-hyperref-template} for
12188 customizing metadata items. See @code{org-latex-title-command} for
12189 typesetting description into the document's front matter. Use multiple
12190 @code{#+DESCRIPTION} lines for long descriptions.
12193 @cindex #+LATEX_CLASS
12194 @vindex org-latex-default-class
12195 @vindex org-latex-classes
12196 This is @LaTeX{} document class, such as @code{article}, @code{report},
12197 @code{book}, and so on, which contain predefined preamble and headline level
12198 mapping that the @LaTeX{} export back-end needs. The back-end reads the
12199 default class name from the @code{org-latex-default-class} variable. Org has
12200 @code{article} as the default class. A valid default class must be an
12201 element of @code{org-latex-classes}.
12203 @item LATEX_CLASS_OPTIONS
12204 @cindex #+LATEX_CLASS_OPTIONS
12205 Options the @LaTeX{} export back-end uses when calling the @LaTeX{} document
12208 @item LATEX_COMPILER
12209 @cindex #+LATEX_COMPILER
12210 @vindex org-latex-compiler
12211 The compiler, such as @samp{pdflatex}, @samp{xelatex}, @samp{lualatex}, for
12212 producing the PDF (@code{org-latex-compiler}).
12215 @cindex #+LATEX_HEADER
12216 @vindex org-latex-classes
12217 Arbitrary lines to add to the document's preamble, before the @samp{hyperref}
12218 settings. See @code{org-latex-classes} for adjusting the structure and order
12219 of the @LaTeX{} headers.
12221 @item LATEX_HEADER_EXTRA
12222 @cindex #+LATEX_HEADER_EXTRA
12223 @vindex org-latex-classes
12224 Arbitrary lines to add to the document's preamble, before the @samp{hyperref}
12225 settings. See @code{org-latex-classes} for adjusting the structure and order
12226 of the @LaTeX{} headers.
12229 @cindex #+KEYWORDS (@LaTeX{})
12230 The keywords for the document. The description along with author name,
12231 keywords, and related file metadata are inserted in the output file by the
12232 @samp{hyperref} package. See @code{org-latex-hyperref-template} for
12233 customizing metadata items. See @code{org-latex-title-command} for
12234 typesetting description into the document's front matter. Use multiple
12235 @code{#+KEYWORDS} lines if necessary.
12238 @cindex #+SUBTITLE (@LaTeX{})
12239 @vindex org-latex-subtitle-separate
12240 @vindex org-latex-subtitle-format
12241 The document's subtitle. It is typeset as per
12242 @code{org-latex-subtitle-format}. If @code{org-latex-subtitle-separate} is
12243 non-@code{nil}, it is typed as part of the @samp{\title}-macro. See
12244 @code{org-latex-hyperref-template} for customizing metadata items. See
12245 @code{org-latex-title-command} for typesetting description into the
12246 document's front matter.
12249 The following sections have further details.
12251 @node @LaTeX{} header and sectioning
12252 @subsection @LaTeX{} header and sectioning structure
12253 @cindex @LaTeX{} class
12254 @cindex @LaTeX{} sectioning structure
12255 @cindex @LaTeX{} header
12256 @cindex header, for @LaTeX{} files
12257 @cindex sectioning structure, for @LaTeX{} export
12259 The @LaTeX{} export back-end converts the first three of Org's outline levels
12260 into @LaTeX{} headlines. The remaining Org levels are exported as
12261 @code{itemize} or @code{enumerate} lists. To change this globally for the
12262 cut-off point between levels and lists, (@pxref{Export settings}).
12264 By default, the @LaTeX{} export back-end uses the @code{article} class.
12266 @vindex org-latex-default-class
12267 @vindex org-latex-classes
12268 @vindex org-latex-default-packages-alist
12269 @vindex org-latex-packages-alist
12270 To change the default class globally, edit @code{org-latex-default-class}.
12271 To change the default class locally in an Org file, add option lines
12272 @code{#+LATEX_CLASS: myclass}. To change the default class for just a part
12273 of the Org file, set a sub-tree property, @code{EXPORT_LATEX_CLASS}. The
12274 class name entered here must be valid member of @code{org-latex-classes}.
12275 This variable defines a header template for each class into which the
12276 exporter splices the values of @code{org-latex-default-packages-alist} and
12277 @code{org-latex-packages-alist}. Use the same three variables to define
12278 custom sectioning or custom classes.
12280 @cindex #+LATEX_CLASS
12281 @cindex #+LATEX_CLASS_OPTIONS
12282 @cindex property, EXPORT_LATEX_CLASS
12283 @cindex property, EXPORT_LATEX_CLASS_OPTIONS
12284 The @LaTeX{} export back-end sends the @code{LATEX_CLASS_OPTIONS} keyword and
12285 @code{EXPORT_LATEX_CLASS_OPTIONS} property as options to the @LaTeX{}
12286 @code{\documentclass} macro. The options and the syntax for specifying them,
12287 including enclosing them in square brackets, follow @LaTeX{} conventions.
12290 #+LATEX_CLASS_OPTIONS: [a4paper,11pt,twoside,twocolumn]
12293 @cindex #+LATEX_HEADER
12294 @cindex #+LATEX_HEADER_EXTRA
12295 The @LaTeX{} export back-end appends values from @code{LATEX_HEADER} and
12296 @code{LATEX_HEADER_EXTRA} keywords to the @LaTeX{} header. The docstring for
12297 @code{org-latex-classes} explains in more detail. Also note that @LaTeX{}
12298 export back-end does not append @code{LATEX_HEADER_EXTRA} to the header when
12299 previewing @LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).
12301 A sample Org file with the above headers:
12304 #+LATEX_CLASS: article
12305 #+LATEX_CLASS_OPTIONS: [a4paper]
12306 #+LATEX_HEADER: \usepackage@{xyz@}
12314 @node Quoting @LaTeX{} code
12315 @subsection Quoting @LaTeX{} code
12317 The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code,
12318 @pxref{Embedded @LaTeX{}}. There are three ways to embed such code in the
12319 Org file and they all use different quoting syntax.
12321 Inserting in-line quoted with @ symbols:
12322 @cindex inline, in @LaTeX{} export
12324 Code embedded in-line @@@@latex:any arbitrary LaTeX code@@@@ in a paragraph.
12327 Inserting as one or more keyword lines in the Org file:
12330 #+LATEX: any arbitrary LaTeX code
12333 Inserting as an export block in the Org file, where the back-end exports any
12334 code between begin and end markers:
12335 @cindex #+BEGIN_EXPORT latex
12337 #+BEGIN_EXPORT latex
12338 any arbitrary LaTeX code
12342 @node Tables in @LaTeX{} export
12343 @subsection Tables in @LaTeX{} export
12344 @cindex tables, in @LaTeX{} export
12345 @cindex #+ATTR_LATEX, in tables
12347 The @LaTeX{} export back-end can pass several @LaTeX{} attributes for table
12348 contents and layout. Besides specifying label and caption (@pxref{Images and
12349 tables}), the other valid @LaTeX{} attributes include:
12353 @vindex org-latex-default-table-mode
12354 The @LaTeX{} export back-end wraps the table differently depending on the
12355 mode for accurate rendering of math symbols. Mode is either @code{table},
12356 @code{math}, @code{inline-math} or @code{verbatim}. For @code{math} or
12357 @code{inline-math} mode, @LaTeX{} export back-end wraps the table in a math
12358 environment, but every cell in it is exported as-is. The @LaTeX{} export
12359 back-end determines the default mode from
12360 @code{org-latex-default-table-mode}. For , The @LaTeX{} export back-end
12361 merges contiguous tables in the same mode into a single environment.
12363 @vindex org-latex-default-table-environment
12364 Set the default @LaTeX{} table environment for the @LaTeX{} export back-end
12365 to use when exporting Org tables. Common @LaTeX{} table environments are
12366 provided by these packages: @code{tabularx}, @code{longtable}, @code{array},
12367 @code{tabu}, and @code{bmatrix}. For packages, such as @code{tabularx} and
12368 @code{tabu}, or any newer replacements, include them in the
12369 @code{org-latex-packages-alist} variable so the @LaTeX{} export back-end can
12370 insert the appropriate load package headers in the converted @LaTeX{} file.
12371 Look in the docstring for the @code{org-latex-packages-alist} variable for
12372 configuring these packages for @LaTeX{} snippet previews, if any.
12374 Use @code{#+CAPTION} keyword to set a simple caption for a table
12375 (@pxref{Images and tables}). For custom captions, use @code{:caption}
12376 attribute, which accepts raw @LaTeX{} code. @code{:caption} value overrides
12377 @code{#+CAPTION} value.
12380 The table environments by default are not floats in @LaTeX{}. To make them
12381 floating objects use @code{:float} with one of the following options:
12382 @code{sideways}, @code{multicolumn}, @code{t}, and @code{nil}. Note that
12383 @code{sidewaystable} has been deprecated since Org 8.3. @LaTeX{} floats can
12384 also have additional layout @code{:placement} attributes. These are the
12385 usual @code{[h t b p ! H]} permissions specified in square brackets. Note
12386 that for @code{:float sideways} tables, the @LaTeX{} export back-end ignores
12387 @code{:placement} attributes.
12391 The @LaTeX{} export back-end uses these attributes for regular tables to set
12392 their alignments, fonts, and widths.
12394 When @code{:spread} is non-@code{nil}, the @LaTeX{} export back-end spreads
12395 or shrinks the table by the @code{:width} for @code{tabu} and @code{longtabu}
12396 environments. @code{:spread} has no effect if @code{:width} is not set.
12400 @vindex org-latex-tables-booktabs
12401 @vindex org-latex-tables-centered
12402 All three commands are toggles. @code{:booktabs} brings in modern
12403 typesetting enhancements to regular tables. The @code{booktabs} package has
12404 to be loaded through @code{org-latex-packages-alist}. @code{:center} is for
12405 centering the table. @code{:rmlines} removes all but the very first
12406 horizontal line made of ASCII characters from "table.el" tables only.
12408 @itemx :math-suffix
12409 @itemx :math-arguments
12410 The @LaTeX{} export back-end inserts @code{:math-prefix} string value in a
12411 math environment before the table. The @LaTeX{} export back-end inserts
12412 @code{:math-suffix} string value in a math environment after the table. The
12413 @LaTeX{} export back-end inserts @code{:math-arguments} string value between
12414 the macro name and the table's contents. @code{:math-arguments} comes in use
12415 for matrix macros that require more than one argument, such as
12416 @code{qbordermatrix}.
12419 @LaTeX{} table attributes help formatting tables for a wide range of
12420 situations, such as matrix product or spanning multiple pages:
12423 #+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l
12427 #+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
12430 #+ATTR_LATEX: :mode math :environment bmatrix
12435 Set the caption with the @LaTeX{} command
12436 @code{\bicaption@{HeadingA@}@{HeadingB@}}:
12439 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
12445 @node Images in @LaTeX{} export
12446 @subsection Images in @LaTeX{} export
12447 @cindex images, inline in @LaTeX{}
12448 @cindex inlining images in @LaTeX{}
12449 @cindex #+ATTR_LATEX, in images
12451 The @LaTeX{} export back-end processes image links in Org files that do not
12452 have descriptions, such as these links @samp{[[file:img.jpg]]} or
12453 @samp{[[./img.jpg]]}, as direct image insertions in the final PDF output. In
12454 the PDF, they are no longer links but actual images embedded on the page.
12455 The @LaTeX{} export back-end uses @code{\includegraphics} macro to insert the
12456 image. But for TikZ@footnote{@url{http://sourceforge.net/projects/pgf/}}
12457 images, the back-end uses an @code{\input} macro wrapped within
12458 a @code{tikzpicture} environment.
12460 For specifying image @code{:width}, @code{:height}, and other
12461 @code{:options}, use this syntax:
12464 #+ATTR_LATEX: :width 5cm :options angle=90
12465 [[./img/sed-hr4049.pdf]]
12468 For custom commands for captions, use the @code{:caption} attribute. It will
12469 override the default @code{#+CAPTION} value:
12472 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
12473 [[./img/sed-hr4049.pdf]]
12476 When captions follow the method as described in @ref{Images and tables}, the
12477 @LaTeX{} export back-end wraps the picture in a floating @code{figure}
12478 environment. To float an image without specifying a caption, set the
12479 @code{:float} attribute to one of the following:
12482 @code{t}: for a standard @samp{figure} environment; used by default whenever
12483 an image has a caption.
12485 @code{multicolumn}: to span the image across multiple columns of a page; the
12486 back-end wraps the image in a @code{figure*} environment.
12488 @code{wrap}: for text to flow around the image on the right; the figure
12489 occupies the left half of the page.
12491 @code{sideways}: for a new page with the image sideways, rotated ninety
12492 degrees, in a @code{sidewaysfigure} environment; overrides @code{:placement}
12495 @code{nil}: to avoid a @code{:float} even if using a caption.
12498 Use the @code{placement} attribute to modify a floating environment's placement.
12501 #+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement
12502 @{r@}@{0.4\textwidth@} [[./img/hst.png]]
12505 @vindex org-latex-images-centered
12506 @cindex center image (@LaTeX{} export)
12507 @cindex image, centering (@LaTeX{} export)
12509 The @LaTeX{} export back-end centers all images by default. Setting
12510 @code{:center} attribute to @code{nil} disables centering. To disable
12511 centering globally, set @code{org-latex-images-centered} to @code{t}.
12513 Set the @code{:comment-include} attribute to non-@code{nil} value for the
12514 @LaTeX{} export back-end to comment out the @code{\includegraphics} macro.
12516 @node Plain lists in @LaTeX{} export
12517 @subsection Plain lists in @LaTeX{} export
12518 @cindex plain lists, in @LaTeX{} export
12519 @cindex #+ATTR_LATEX, in plain lists
12521 The @LaTeX{} export back-end accepts the @code{:environment} and
12522 @code{:options} attributes for plain lists. Both attributes work together
12523 for customizing lists, as shown in the examples:
12526 #+LATEX_HEADER: \usepackage[inline]@{enumitem@}
12527 Some ways to say "Hello":
12528 #+ATTR_LATEX: :environment itemize*
12529 #+ATTR_LATEX: :options [label=@{@}, itemjoin=@{,@}, itemjoin*=@{, and@}]
12535 Since @LaTeX{} supports only four levels of nesting for lists, use an
12536 external package, such as @samp{enumitem} in @LaTeX{}, for levels deeper than
12540 #+LATEX_HEADER: \usepackage@{enumitem@}
12541 #+LATEX_HEADER: \renewlist@{itemize@}@{itemize@}@{9@}
12542 #+LATEX_HEADER: \setlist[itemize]@{label=$\circ$@}
12550 @node Source blocks in @LaTeX{} export
12551 @subsection Source blocks in @LaTeX{} export
12552 @cindex source blocks, in @LaTeX{} export
12553 @cindex #+ATTR_LATEX, in source blocks
12555 The @LaTeX{} export back-end can make source code blocks into floating
12556 objects through the attributes @code{:float} and @code{:options}. For
12561 @code{t}: makes a source block float; by default floats any source block with
12564 @code{multicolumn}: spans the source block across multiple columns of a page.
12566 @code{nil}: avoids a @code{:float} even if using a caption; useful for
12567 source code blocks that may not fit on a page.
12571 #+ATTR_LATEX: :float nil
12572 #+BEGIN_SRC emacs-lisp
12573 Lisp code that may not fit in a single page.
12577 @vindex org-latex-listings-options
12578 @vindex org-latex-minted-options
12579 The @LaTeX{} export back-end passes string values in @code{:options} to
12580 @LaTeX{} packages for customization of that specific source block. In the
12581 example below, the @code{:options} are set for Minted. Minted is a source
12582 code highlighting @LaTeX{}package with many configurable options.
12585 #+ATTR_LATEX: :options commentstyle=\bfseries
12586 #+BEGIN_SRC emacs-lisp
12588 (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2)))))
12592 To apply similar configuration options for all source blocks in a file, use
12593 the @code{org-latex-listings-options} and @code{org-latex-minted-options}
12596 @node Example blocks in @LaTeX{} export
12597 @subsection Example blocks in @LaTeX{} export
12598 @cindex example blocks, in @LaTeX{} export
12599 @cindex verbatim blocks, in @LaTeX{} export
12600 @cindex #+ATTR_LATEX, in example blocks
12602 The @LaTeX{} export back-end wraps the contents of example blocks in a
12603 @samp{verbatim} environment. To change this behavior to use another
12604 environment globally, specify an appropriate export filter (@pxref{Advanced
12605 configuration}). To change this behavior to use another environment for each
12606 block, use the @code{:environment} parameter to specify a custom environment.
12609 #+ATTR_LATEX: :environment myverbatim
12611 This sentence is false.
12615 @node Special blocks in @LaTeX{} export
12616 @subsection Special blocks in @LaTeX{} export
12617 @cindex special blocks, in @LaTeX{} export
12618 @cindex abstract, in @LaTeX{} export
12619 @cindex proof, in @LaTeX{} export
12620 @cindex #+ATTR_LATEX, in special blocks
12623 For other special blocks in the Org file, the @LaTeX{} export back-end makes
12624 a special environment of the same name. The back-end also takes
12625 @code{:options}, if any, and appends as-is to that environment's opening
12626 string. For example:
12630 We demonstrate how to solve the Syracuse problem.
12633 #+ATTR_LATEX: :options [Proof of important theorem]
12636 Therefore, any even number greater than 2 is the sum of two primes.
12645 We demonstrate how to solve the Syracuse problem.
12648 \begin@{proof@}[Proof of important theorem]
12650 Therefore, any even number greater than 2 is the sum of two primes.
12654 If you need to insert a specific caption command, use @code{:caption}
12655 attribute. It will override standard @code{#+CAPTION} value, if any. For
12659 #+ATTR_LATEX: :caption \MyCaption@{HeadingA@}
12665 @node Horizontal rules in @LaTeX{} export
12666 @subsection Horizontal rules in @LaTeX{} export
12667 @cindex horizontal rules, in @LaTeX{} export
12668 @cindex #+ATTR_LATEX, in horizontal rules
12670 The @LaTeX{} export back-end converts horizontal rules by the specified
12671 @code{:width} and @code{:thickness} attributes. For example:
12674 #+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
12678 @node Markdown export
12679 @section Markdown export
12680 @cindex Markdown export
12682 The Markdown export back-end, @code{md}, converts an Org file to a Markdown
12683 format, as defined at @url{http://daringfireball.net/projects/markdown/}.
12685 Since @code{md} is built on top of the HTML back-end, any Org constructs not
12686 supported by Markdown, such as tables, the underlying @code{html} back-end
12687 (@pxref{HTML export}) converts them.
12689 @subheading Markdown export commands
12692 @orgcmd{C-c C-e m m,org-md-export-to-markdown}
12693 Export to a text file with Markdown syntax. For @file{myfile.org}, Org
12694 exports to @file{myfile.md}, overwritten without warning.
12695 @orgcmd{C-c C-e m M,org-md-export-as-markdown}
12696 Export to a temporary buffer. Does not create a file.
12698 Export as a text file with Markdown syntax, then open it.
12701 @subheading Header and sectioning structure
12703 @vindex org-md-headline-style
12704 Based on @code{org-md-headline-style}, markdown export can generate headlines
12705 of both @code{atx} and @code{setext} types. @code{atx} limits headline
12706 levels to two. @code{setext} limits headline levels to six. Beyond these
12707 limits, the export back-end converts headlines to lists. To set a limit to a
12708 level before the absolute limit (@pxref{Export settings}).
12710 @c begin opendocument
12712 @node OpenDocument Text export
12713 @section OpenDocument Text export
12715 @cindex OpenDocument
12716 @cindex export, OpenDocument
12717 @cindex LibreOffice
12719 The ODT export back-end handles creating of OpenDocument Text (ODT) format
12720 files. The format complies with @cite{OpenDocument-v1.2
12721 specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
12722 Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
12723 is compatible with LibreOffice 3.4.
12726 * Pre-requisites for ODT export:: Required packages.
12727 * ODT export commands:: Invoking export.
12728 * ODT specific export settings:: Configuration options.
12729 * Extending ODT export:: Producing @file{.doc}, @file{.pdf} files.
12730 * Applying custom styles:: Styling the output.
12731 * Links in ODT export:: Handling and formatting links.
12732 * Tables in ODT export:: Org table conversions.
12733 * Images in ODT export:: Inserting images.
12734 * Math formatting in ODT export:: Formatting @LaTeX{} fragments.
12735 * Labels and captions in ODT export:: Rendering objects.
12736 * Literal examples in ODT export:: For source code and example blocks.
12737 * Advanced topics in ODT export:: For power users.
12740 @node Pre-requisites for ODT export
12741 @subsection Pre-requisites for ODT export
12743 The ODT export back-end relies on the @file{zip} program to create the final
12744 compressed ODT output. Check if @file{zip} is locally available and
12745 executable. Without @file{zip}, export cannot finish.
12747 @node ODT export commands
12748 @subsection ODT export commands
12749 @anchor{x-export-to-odt}
12750 @cindex region, active
12751 @cindex active region
12752 @cindex transient-mark-mode
12754 @orgcmd{C-c C-e o o,org-odt-export-to-odt}
12755 @cindex property EXPORT_FILE_NAME
12757 Export as OpenDocument Text file.
12759 @vindex org-odt-preferred-output-format
12760 If @code{org-odt-preferred-output-format} is specified, the ODT export
12761 back-end automatically converts the exported file to that format.
12762 @xref{x-export-to-other-formats, , Automatically exporting to other formats}.
12764 For @file{myfile.org}, Org exports to @file{myfile.odt}, overwriting without
12765 warning. The ODT export back-end exports a region only if a region was
12766 active. Note for exporting active regions, the @code{transient-mark-mode}
12767 has to be turned on.
12769 If the selected region is a single tree, the ODT export back-end makes the
12770 tree head the document title. Incidentally, @kbd{C-c @@} selects the current
12771 sub-tree. If the tree head entry has, or inherits, an
12772 @code{EXPORT_FILE_NAME} property, the ODT export back-end uses that for file
12776 Export to an OpenDocument Text file format and open it.
12778 @vindex org-odt-preferred-output-format
12779 When @code{org-odt-preferred-output-format} is specified, open the converted
12780 file instead. @xref{x-export-to-other-formats, , Automatically exporting to
12784 @node ODT specific export settings
12785 @subsection ODT specific export settings
12786 The ODT export back-end has several additional keywords for customizing ODT
12787 output. Setting these keywords works similar to the general options
12788 (@pxref{Export settings}).
12792 @cindex #+DESCRIPTION (ODT)
12793 This is the document's description, which the ODT export back-end inserts as
12794 document metadata. For long descriptions, use multiple @code{#+DESCRIPTION}
12798 @cindex #+KEYWORDS (ODT)
12799 The keywords for the document. The ODT export back-end inserts the
12800 description along with author name, keywords, and related file metadata as
12801 metadata in the output file. Use multiple @code{#+KEYWORDS} lines if
12804 @item ODT_STYLES_FILE
12805 @cindex ODT_STYLES_FILE
12806 @vindex org-odt-styles-file
12807 The ODT export back-end uses the @code{org-odt-styles-file} by default. See
12808 @ref{Applying custom styles} for details.
12811 @cindex SUBTITLE (ODT)
12812 The document subtitle.
12815 @node Extending ODT export
12816 @subsection Extending ODT export
12818 The ODT export back-end can produce documents in other formats besides ODT
12819 using a specialized ODT converter process. Its common interface works with
12820 popular converters to produce formats such as @samp{doc}, or convert a
12821 document from one format, say @samp{csv}, to another format, say @samp{xls}.
12823 @cindex @file{unoconv}
12824 @cindex LibreOffice
12826 Customize @code{org-odt-convert-process} variable to point to @code{unoconv},
12827 which is the ODT's preferred converter. Working installations of LibreOffice
12828 would already have @code{unoconv} installed. Alternatively, other converters
12829 may be substituted here. @xref{Configuring a document converter}.
12831 @subsubheading Automatically exporting to other formats
12832 @anchor{x-export-to-other-formats}
12834 @vindex org-odt-preferred-output-format
12835 If ODT format is just an intermediate step to get to other formats, such as
12836 @samp{doc}, @samp{docx}, @samp{rtf}, or @samp{pdf}, etc., then extend the ODT
12837 export back-end to directly produce that format. Specify the final format in
12838 the @code{org-odt-preferred-output-format} variable. This is one way to
12839 extend (@pxref{x-export-to-odt,,Exporting to ODT}).
12841 @subsubheading Converting between document formats
12842 @anchor{x-convert-to-other-formats}
12844 The Org export back-end is made to be inter-operable with a wide range of text
12845 document format converters. Newer generation converters, such as LibreOffice
12846 and Pandoc, can handle hundreds of formats at once. Org provides a
12847 consistent interaction with whatever converter is installed. Here are some
12850 @vindex org-odt-convert
12853 @item M-x org-odt-convert RET
12854 Convert an existing document from one format to another. With a prefix
12855 argument, opens the newly produced file.
12858 @node Applying custom styles
12859 @subsection Applying custom styles
12860 @cindex styles, custom
12861 @cindex template, custom
12863 The ODT export back-end comes with many OpenDocument styles (@pxref{Working
12864 with OpenDocument style files}). To expand or further customize these
12865 built-in style sheets, either edit the style sheets directly or generate them
12866 using an application such as LibreOffice. The example here shows creating a
12867 style using LibreOffice.
12869 @subsubheading Applying custom styles: the easy way
12873 Create a sample @file{example.org} file with settings as shown below, and
12874 export it to ODT format.
12877 #+OPTIONS: H:10 num:t
12881 Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist}
12882 to locate the target styles, which typically have the @samp{Org} prefix.
12883 Open one, modify, and save as either OpenDocument Text (@file{.odt}) or
12884 OpenDocument Template (@file{.ott}) file.
12887 @cindex #+ODT_STYLES_FILE
12888 @vindex org-odt-styles-file
12889 Customize the variable @code{org-odt-styles-file} and point it to the
12890 newly created file. For additional configuration options
12891 @pxref{x-overriding-factory-styles,,Overriding factory styles}.
12893 To apply and ODT style to a particular file, use the @code{#+ODT_STYLES_FILE}
12894 option as shown in the example below:
12897 #+ODT_STYLES_FILE: "/path/to/example.ott"
12903 #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
12908 @subsubheading Using third-party styles and templates
12910 The ODT export back-end relies on many templates and style names. Using
12911 third-party styles and templates can lead to mismatches. Templates derived
12912 from built in ODT templates and styles seem to have fewer problems.
12914 @node Links in ODT export
12915 @subsection Links in ODT export
12916 @cindex links, in ODT export
12918 ODT export back-end creates native cross-references for internal links and
12919 Internet-style links for all other link types.
12921 A link with no description and pointing to a regular---un-itemized---outline
12922 heading is replaced with a cross-reference and section number of the heading.
12924 A @samp{\ref@{label@}}-style reference to an image, table etc.@: is replaced
12925 with a cross-reference and sequence number of the labeled entity.
12926 @xref{Labels and captions in ODT export}.
12928 @node Tables in ODT export
12929 @subsection Tables in ODT export
12930 @cindex tables, in ODT export
12932 The ODT export back-end handles native Org mode tables (@pxref{Tables}) and
12933 simple @file{table.el} tables. Complex @file{table.el} tables having column
12934 or row spans are not supported. Such tables are stripped from the exported
12937 By default, the ODT export back-end exports a table with top and bottom
12938 frames and with ruled lines separating row and column groups (@pxref{Column
12939 groups}). All tables are typeset to occupy the same width. The ODT export
12940 back-end honors any table alignments and relative widths for columns
12941 (@pxref{Column width and alignment}).
12943 Note that the ODT export back-end interprets column widths as weighted
12944 ratios, the default weight being 1.
12948 Specifying @code{:rel-width} property on an @code{#+ATTR_ODT} line controls
12949 the width of the table. For example:
12952 #+ATTR_ODT: :rel-width 50
12953 | Area/Month | Jan | Feb | Mar | Sum |
12954 |---------------+-------+-------+-------+-------|
12956 | <l13> | <r5> | <r5> | <r5> | <r6> |
12957 | North America | 1 | 21 | 926 | 948 |
12958 | Middle East | 6 | 75 | 844 | 925 |
12959 | Asia Pacific | 9 | 27 | 790 | 826 |
12960 |---------------+-------+-------+-------+-------|
12961 | Sum | 16 | 123 | 2560 | 2699 |
12964 On export, the above table takes 50% of text width area. The exporter sizes
12965 the columns in the ratio: 13:5:5:5:6. The first column is left-aligned and
12966 rest of the columns, right-aligned. Vertical rules separate the header and
12967 the last column. Horizontal rules separate the header and the last row.
12969 For even more customization, create custom table styles and associate them
12970 with a table using the @code{#+ATTR_ODT} line. @xref{Customizing tables in
12973 @node Images in ODT export
12974 @subsection Images in ODT export
12975 @cindex images, embedding in ODT
12976 @cindex embedding images in ODT
12978 @subsubheading Embedding images
12979 The ODT export back-end processes image links in Org files that do not have
12980 descriptions, such as these links @samp{[[file:img.jpg]]} or
12981 @samp{[[./img.jpg]]}, as direct image insertions in the final output. Either
12982 of these examples works:
12992 @subsubheading Embedding clickable images
12993 For clickable images, provide a link whose description is another link to an
12994 image file. For example, to embed a image @file{org-mode-unicorn.png} which
12995 when clicked jumps to @uref{http://Orgmode.org} website, do the following
12998 [[http://orgmode.org][./org-mode-unicorn.png]]
13001 @subsubheading Sizing and scaling of embedded images
13004 Control the size and scale of the embedded images with the @code{#+ATTR_ODT}
13007 @cindex identify, ImageMagick
13008 @vindex org-odt-pixels-per-inch
13009 The ODT export back-end starts with establishing the size of the image in the
13010 final document. The dimensions of this size is measured in centimeters. The
13011 back-end then queries the image file for its dimensions measured in pixels.
13012 For this measurement, the back-end relies on ImageMagick's @file{identify}
13013 program or Emacs @code{create-image} and @code{image-size} API. ImageMagick
13014 is the preferred choice for large file sizes or frequent batch operations.
13015 The back-end then converts the pixel dimensions using
13016 @code{org-odt-pixels-per-inch} into the familiar 72 dpi or 96 dpi. The
13017 default value for this is in @code{display-pixels-per-inch}, which can be
13018 tweaked for better results based on the capabilities of the output device.
13019 Here are some common image scaling operations:
13022 @item Explicitly size the image
13023 To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
13026 #+ATTR_ODT: :width 10 :height 10
13030 @item Scale the image
13031 To embed @file{img.png} at half its size, do the following:
13034 #+ATTR_ODT: :scale 0.5
13038 @item Scale the image to a specific width
13039 To embed @file{img.png} with a width of 10 cm while retaining the original
13040 height:width ratio, do the following:
13043 #+ATTR_ODT: :width 10
13047 @item Scale the image to a specific height
13048 To embed @file{img.png} with a height of 10 cm while retaining the original
13049 height:width ratio, do the following
13052 #+ATTR_ODT: :height 10
13057 @subsubheading Anchoring of images
13060 The ODT export back-end can anchor images to @samp{"as-char"},
13061 @samp{"paragraph"}, or @samp{"page"}. Set the preferred anchor using the
13062 @code{:anchor} property of the @code{#+ATTR_ODT} line.
13064 To create an image that is anchored to a page:
13066 #+ATTR_ODT: :anchor "page"
13070 @node Math formatting in ODT export
13071 @subsection Math formatting in ODT export
13073 The ODT export back-end has special support built-in for handling math.
13076 * Working with @LaTeX{} math snippets:: Embedding in @LaTeX{} format.
13077 * Working with MathML or OpenDocument formula files:: Embedding in native format.
13080 @node Working with @LaTeX{} math snippets
13081 @subsubheading Working with @LaTeX{} math snippets
13083 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in an ODT
13084 document in one of the following ways:
13090 Add this line to the Org file. This option is activated on a per-file basis.
13096 With this option, @LaTeX{} fragments are first converted into MathML
13097 fragments using an external @LaTeX{}-to-MathML converter program. The
13098 resulting MathML fragments are then embedded as an OpenDocument Formula in
13099 the exported document.
13101 @vindex org-latex-to-mathml-convert-command
13102 @vindex org-latex-to-mathml-jar-file
13104 To specify the @LaTeX{}-to-MathML converter, customize the variables
13105 @code{org-latex-to-mathml-convert-command} and
13106 @code{org-latex-to-mathml-jar-file}.
13108 To use MathToWeb@footnote{See
13109 @uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}.} as the
13110 preferred converter, configure the above variables as
13113 (setq org-latex-to-mathml-convert-command
13114 "java -jar %j -unicode -force -df %o %I"
13115 org-latex-to-mathml-jar-file
13116 "/path/to/mathtoweb.jar")
13118 To use @LaTeX{}ML@footnote{See @uref{http://dlmf.nist.gov/LaTeXML/}.} use
13120 (setq org-latex-to-mathml-convert-command
13121 "latexmlmath \"%i\" --presentationmathml=%o")
13124 To quickly verify the reliability of the @LaTeX{}-to-MathML converter, use
13125 the following commands:
13128 @item M-x org-odt-export-as-odf RET
13129 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file.
13131 @item M-x org-odt-export-as-odf-and-open RET
13132 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file
13133 and open the formula file with the system-registered application.
13138 @cindex imagemagick
13141 Add this line to the Org file. This option is activated on a per-file basis.
13144 #+OPTIONS: tex:dvipng
13148 #+OPTIONS: tex:dvisvgm
13154 #+OPTIONS: tex:imagemagick
13157 Under this option, @LaTeX{} fragments are processed into PNG or SVG images
13158 and the resulting images are embedded in the exported document. This method
13159 requires @file{dvipng} program, @file{dvisvgm} or @file{imagemagick}
13163 @node Working with MathML or OpenDocument formula files
13164 @subsubheading Working with MathML or OpenDocument formula files
13166 When embedding @LaTeX{} math snippets in ODT documents is not reliable, there
13167 is one more option to try. Embed an equation by linking to its MathML
13168 (@file{.mml}) source or its OpenDocument formula (@file{.odf}) file as shown
13181 @node Labels and captions in ODT export
13182 @subsection Labels and captions in ODT export
13184 ODT format handles labeling and captioning of objects based on their
13185 types. Inline images, tables, @LaTeX{} fragments, and Math formulas are
13186 numbered and captioned separately. Each object also gets a unique sequence
13187 number based on its order of first appearance in the Org file. Each category
13188 has its own sequence. A caption is just a label applied to these objects.
13191 #+CAPTION: Bell curve
13192 #+LABEL: fig:SED-HR4049
13196 When rendered, it may show as follows in the exported document:
13199 Figure 2: Bell curve
13202 @vindex org-odt-category-map-alist
13203 To modify the category component of the caption, customize the option
13204 @code{org-odt-category-map-alist}. For example, to tag embedded images with
13205 the string @samp{Illustration} instead of the default string @samp{Figure},
13206 use the following setting:
13209 (setq org-odt-category-map-alist
13210 '(("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
13213 With the above modification, the previous example changes to:
13216 Illustration 2: Bell curve
13219 @node Literal examples in ODT export
13220 @subsection Literal examples in ODT export
13222 The ODT export back-end supports literal examples (@pxref{Literal examples})
13223 with full fontification. Internally, the ODT export back-end relies on
13224 @file{htmlfontify.el} to generate the style definitions needed for fancy
13225 listings. The auto-generated styles get @samp{OrgSrc} prefix and inherit
13226 colors from the faces used by Emacs @code{font-lock} library for that source
13229 @vindex org-odt-fontify-srcblocks
13230 For custom fontification styles, customize the
13231 @code{org-odt-create-custom-styles-for-srcblocks} option.
13233 @vindex org-odt-create-custom-styles-for-srcblocks
13234 To turn off fontification of literal examples, customize the
13235 @code{org-odt-fontify-srcblocks} option.
13237 @node Advanced topics in ODT export
13238 @subsection Advanced topics in ODT export
13240 The ODT export back-end has extensive features useful for power users and
13241 frequent uses of ODT formats.
13244 * Configuring a document converter:: Registering a document converter.
13245 * Working with OpenDocument style files:: Exploring internals.
13246 * Creating one-off styles:: Customizing styles, highlighting.
13247 * Customizing tables in ODT export:: Defining table templates.
13248 * Validating OpenDocument XML:: Debugging corrupted OpenDocument files.
13251 @node Configuring a document converter
13252 @subsubheading Configuring a document converter
13254 @cindex doc, docx, rtf
13257 The ODT export back-end works with popular converters with little or no extra
13258 configuration. @xref{Extending ODT export}. The following is for unsupported
13259 converters or tweaking existing defaults.
13262 @item Register the converter
13264 @vindex org-odt-convert-processes
13265 Add the name of the converter to the @code{org-odt-convert-processes}
13266 variable. Note that it also requires how the converter is invoked on the
13267 command line. See the variable's docstring for details.
13269 @item Configure its capabilities
13271 @vindex org-odt-convert-capabilities
13272 @anchor{x-odt-converter-capabilities} Specify which formats the converter can
13273 handle by customizing the variable @code{org-odt-convert-capabilities}. Use
13274 the entry for the default values in this variable for configuring the new
13275 converter. Also see its docstring for details.
13277 @item Choose the converter
13279 @vindex org-odt-convert-process
13280 Select the newly added converter as the preferred one by customizing the
13281 option @code{org-odt-convert-process}.
13284 @node Working with OpenDocument style files
13285 @subsubheading Working with OpenDocument style files
13286 @cindex styles, custom
13287 @cindex template, custom
13289 This section explores the internals of the ODT exporter; the means by which
13290 it produces styled documents; the use of automatic and custom OpenDocument
13293 @anchor{x-factory-styles}
13294 @subsubheading a) Factory styles
13296 The ODT exporter relies on two files for generating its output.
13297 These files are bundled with the distribution under the directory pointed to
13298 by the variable @code{org-odt-styles-dir}. The two files are:
13301 @anchor{x-orgodtstyles-xml}
13303 @file{OrgOdtStyles.xml}
13305 This file contributes to the @file{styles.xml} file of the final @samp{ODT}
13306 document. This file gets modified for the following purposes:
13310 To control outline numbering based on user settings.
13313 To add styles generated by @file{htmlfontify.el} for fontification of code
13317 @anchor{x-orgodtcontenttemplate-xml}
13319 @file{OrgOdtContentTemplate.xml}
13321 This file contributes to the @file{content.xml} file of the final @samp{ODT}
13322 document. The contents of the Org outline are inserted between the
13323 @samp{<office:text>}@dots{}@samp{</office:text>} elements of this file.
13325 Apart from serving as a template file for the final @file{content.xml}, the
13326 file serves the following purposes:
13330 It contains automatic styles for formatting of tables which are referenced by
13334 It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
13335 elements that control numbering of tables, images, equations, and similar
13340 @anchor{x-overriding-factory-styles}
13341 @subsubheading b) Overriding factory styles
13342 The following two variables control the location from where the ODT exporter
13343 picks up the custom styles and content template files. Customize these
13344 variables to override the factory styles used by the exporter.
13347 @anchor{x-org-odt-styles-file}
13349 @code{org-odt-styles-file}
13351 The ODT export back-end uses the file pointed to by this variable, such as
13352 @file{styles.xml}, for the final output. It can take one of the following
13356 @item A @file{styles.xml} file
13358 Use this file instead of the default @file{styles.xml}
13360 @item A @file{.odt} or @file{.ott} file
13362 Use the @file{styles.xml} contained in the specified OpenDocument Text or
13365 @item A @file{.odt} or @file{.ott} file and a subset of files contained within them
13367 Use the @file{styles.xml} contained in the specified OpenDocument Text or
13368 Template file. Additionally extract the specified member files and embed
13369 those within the final @samp{ODT} document.
13371 Use this option if the @file{styles.xml} file references additional files
13372 like header and footer images.
13376 Use the default @file{styles.xml}
13379 @anchor{x-org-odt-content-template-file}
13381 @code{org-odt-content-template-file}
13383 Use this variable to specify the blank @file{content.xml} that will be used
13384 in the final output.
13387 @node Creating one-off styles
13388 @subsubheading Creating one-off styles
13390 The ODT export back-end can read embedded raw OpenDocument XML from the Org
13391 file. Such direct formatting are useful for one-off instances.
13394 @item Embedding ODT tags as part of regular text
13396 Enclose OpenDocument syntax in @samp{@@@@odt:...@@@@} for inline markup. For
13397 example, to highlight a region of text do the following:
13400 @@@@odt:<text:span text:style-name="Highlight">This is highlighted
13401 text</text:span>@@@@. But this is regular text.
13404 @strong{Hint:} To see the above example in action, edit the @file{styles.xml}
13405 (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a custom
13406 @samp{Highlight} style as shown below:
13409 <style:style style:name="Highlight" style:family="text">
13410 <style:text-properties fo:background-color="#ff0000"/>
13414 @item Embedding a one-line OpenDocument XML
13416 The ODT export back-end can read one-liner options with @code{#+ODT:}
13417 in the Org file. For example, to force a page break:
13420 #+ODT: <text:p text:style-name="PageBreak"/>
13423 @strong{Hint:} To see the above example in action, edit your
13424 @file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
13425 custom @samp{PageBreak} style as shown below.
13428 <style:style style:name="PageBreak" style:family="paragraph"
13429 style:parent-style-name="Text_20_body">
13430 <style:paragraph-properties fo:break-before="page"/>
13434 @item Embedding a block of OpenDocument XML
13436 The ODT export back-end can also read ODT export blocks for OpenDocument XML.
13437 Such blocks use the @code{#+BEGIN_EXPORT odt}@dots{}@code{#+END_EXPORT}
13440 For example, to create a one-off paragraph that uses bold text, do the
13445 <text:p text:style-name="Text_20_body_20_bold">
13446 This paragraph is specially formatted and uses bold text.
13453 @node Customizing tables in ODT export
13454 @subsubheading Customizing tables in ODT export
13455 @cindex tables, in ODT export
13458 Override the default table format by specifying a custom table style with the
13459 @code{#+ATTR_ODT} line. For a discussion on default formatting of tables
13460 @pxref{Tables in ODT export}.
13462 This feature closely mimics the way table templates are defined in the
13464 specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
13465 OpenDocument-v1.2 Specification}}
13467 @vindex org-odt-table-styles
13468 For quick preview of this feature, install the settings below and export the
13469 table that follows:
13472 (setq org-odt-table-styles
13473 (append org-odt-table-styles
13474 '(("TableWithHeaderRowAndColumn" "Custom"
13475 ((use-first-row-styles . t)
13476 (use-first-column-styles . t)))
13477 ("TableWithFirstRowandLastRow" "Custom"
13478 ((use-first-row-styles . t)
13479 (use-last-row-styles . t))))))
13483 #+ATTR_ODT: :style TableWithHeaderRowAndColumn
13484 | Name | Phone | Age |
13485 | Peter | 1234 | 17 |
13486 | Anna | 4321 | 25 |
13489 The example above used @samp{Custom} template and installed two table styles
13490 @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}.
13491 @strong{Important:} The OpenDocument styles needed for producing the above
13492 template were pre-defined. They are available in the section marked
13493 @samp{Custom Table Template} in @file{OrgOdtContentTemplate.xml}
13494 (@pxref{x-orgodtcontenttemplate-xml,,Factory styles}. For adding new
13495 templates, define new styles here.
13497 To use this feature proceed as follows:
13501 Create a table template@footnote{See the @code{<table:table-template>}
13502 element of the OpenDocument-v1.2 specification}
13504 A table template is set of @samp{table-cell} and @samp{paragraph} styles for
13505 each of the following table cell categories:
13519 The names for the above styles must be chosen based on the name of the table
13520 template using a well-defined convention.
13522 The naming convention is better illustrated with an example. For a table
13523 template with the name @samp{Custom}, the needed style names are listed in
13524 the following table.
13526 @multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph}
13527 @headitem Table cell type
13528 @tab @code{table-cell} style
13529 @tab @code{paragraph} style
13534 @tab @samp{CustomTableCell}
13535 @tab @samp{CustomTableParagraph}
13537 @tab @samp{CustomFirstColumnTableCell}
13538 @tab @samp{CustomFirstColumnTableParagraph}
13540 @tab @samp{CustomLastColumnTableCell}
13541 @tab @samp{CustomLastColumnTableParagraph}
13543 @tab @samp{CustomFirstRowTableCell}
13544 @tab @samp{CustomFirstRowTableParagraph}
13546 @tab @samp{CustomLastRowTableCell}
13547 @tab @samp{CustomLastRowTableParagraph}
13549 @tab @samp{CustomEvenRowTableCell}
13550 @tab @samp{CustomEvenRowTableParagraph}
13552 @tab @samp{CustomOddRowTableCell}
13553 @tab @samp{CustomOddRowTableParagraph}
13555 @tab @samp{CustomEvenColumnTableCell}
13556 @tab @samp{CustomEvenColumnTableParagraph}
13558 @tab @samp{CustomOddColumnTableCell}
13559 @tab @samp{CustomOddColumnTableParagraph}
13562 To create a table template with the name @samp{Custom}, define the above
13564 @code{<office:automatic-styles>}...@code{</office:automatic-styles>} element
13565 of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory
13569 Define a table style@footnote{See the attributes @code{table:template-name},
13570 @code{table:use-first-row-styles}, @code{table:use-last-row-styles},
13571 @code{table:use-first-column-styles}, @code{table:use-last-column-styles},
13572 @code{table:use-banding-rows-styles}, and
13573 @code{table:use-banding-column-styles} of the @code{<table:table>} element in
13574 the OpenDocument-v1.2 specification}
13576 @vindex org-odt-table-styles
13577 To define a table style, create an entry for the style in the variable
13578 @code{org-odt-table-styles} and specify the following:
13581 @item the name of the table template created in step (1)
13582 @item the set of cell styles in that template that are to be activated
13585 For example, the entry below defines two different table styles
13586 @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
13587 based on the same template @samp{Custom}. The styles achieve their intended
13588 effect by selectively activating the individual cell styles in that template.
13591 (setq org-odt-table-styles
13592 (append org-odt-table-styles
13593 '(("TableWithHeaderRowAndColumn" "Custom"
13594 ((use-first-row-styles . t)
13595 (use-first-column-styles . t)))
13596 ("TableWithFirstRowandLastRow" "Custom"
13597 ((use-first-row-styles . t)
13598 (use-last-row-styles . t))))))
13602 Associate a table with the table style
13604 To do this, specify the table style created in step (2) as part of
13605 the @code{ATTR_ODT} line as shown below.
13608 #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
13609 | Name | Phone | Age |
13610 | Peter | 1234 | 17 |
13611 | Anna | 4321 | 25 |
13615 @node Validating OpenDocument XML
13616 @subsubheading Validating OpenDocument XML
13618 Sometimes ODT format files may not open due to @file{.odt} file corruption.
13619 To verify if the @file{.odt} file is corrupt, validate it against the
13620 OpenDocument RELAX NG Compact Syntax---RNC---schema. But first the
13621 @file{.odt} files have to be decompressed using @samp{zip}. Note that
13622 @file{.odt} files are @samp{zip} archives: @inforef{File Archives,,emacs}.
13623 The contents of @file{.odt} files are in @file{.xml}. For general help with
13624 validation---and schema-sensitive editing---of XML files:
13625 @inforef{Introduction,,nxml-mode}.
13627 @vindex org-odt-schema-dir
13628 Customize @code{org-odt-schema-dir} to point to a directory with OpenDocument
13629 @file{.rnc} files and the needed schema-locating rules. The ODT export
13630 back-end takes care of updating the @code{rng-schema-locating-files}.
13632 @c end opendocument
13635 @section Org export
13638 @code{org} export back-end creates a normalized version of the Org document
13639 in current buffer. The exporter evaluates Babel code (@pxref{Evaluating code
13640 blocks}) and removes content specific to other back-ends.
13642 @subheading Org export commands
13645 @orgcmd{C-c C-e O o,org-org-export-to-org}
13646 Export as an Org file with a @file{.org} extension. For @file{myfile.org},
13647 Org exports to @file{myfile.org.org}, overwriting without warning.
13649 @orgcmd{C-c C-e O O,org-org-export-as-org}
13650 Export to a temporary buffer. Does not create a file.
13652 Export to an Org file, then open it.
13655 @node Texinfo export
13656 @section Texinfo export
13657 @cindex Texinfo export
13659 The @samp{texinfo} export back-end generates documents with Texinfo code that
13660 can compile to Info format.
13663 * Texinfo export commands:: Invoking commands.
13664 * Texinfo specific export settings:: Setting the environment.
13665 * Texinfo file header:: Generating the header.
13666 * Texinfo title and copyright page:: Creating preamble pages.
13667 * Info directory file:: Installing a manual in Info file hierarchy.
13668 * Headings and sectioning structure:: Building document structure.
13669 * Indices:: Creating indices.
13670 * Quoting Texinfo code:: Incorporating literal Texinfo code.
13671 * Plain lists in Texinfo export:: List attributes.
13672 * Tables in Texinfo export:: Table attributes.
13673 * Images in Texinfo export:: Image attributes.
13674 * Special blocks in Texinfo export:: Special block attributes.
13675 * A Texinfo example:: Processing Org to Texinfo.
13678 @node Texinfo export commands
13679 @subsection Texinfo export commands
13681 @vindex org-texinfo-info-process
13683 @orgcmd{C-c C-e i t,org-texinfo-export-to-texinfo}
13684 Export as a Texinfo file with @file{.texi} extension. For @file{myfile.org},
13685 Org exports to @file{myfile.texi}, overwriting without warning.
13686 @orgcmd{C-c C-e i i,org-texinfo-export-to-info}
13687 Export to Texinfo format first and then process it to make an Info file. To
13688 generate other formats, such as DocBook, customize the
13689 @code{org-texinfo-info-process} variable.
13692 @node Texinfo specific export settings
13693 @subsection Texinfo specific export settings
13694 The Texinfo export back-end has several additional keywords for customizing
13695 Texinfo output. Setting these keywords works similar to the general options
13696 (@pxref{Export settings}).
13701 @cindex #+SUBTITLE (Texinfo)
13702 The document subtitle.
13705 @cindex #+SUBAUTHOR
13706 The document subauthor.
13708 @item TEXINFO_FILENAME
13709 @cindex #+TEXINFO_FILENAME
13710 The Texinfo filename.
13712 @item TEXINFO_CLASS
13713 @cindex #+TEXINFO_CLASS
13714 @vindex org-texinfo-default-class
13715 The default document class (@code{org-texinfo-default-class}), which must be
13716 a member of @code{org-texinfo-classes}.
13718 @item TEXINFO_HEADER
13719 @cindex #+TEXINFO_HEADER
13720 Arbitrary lines inserted at the end of the header.
13722 @item TEXINFO_POST_HEADER
13723 @cindex #+TEXINFO_POST_HEADER
13724 Arbitrary lines inserted after the end of the header.
13726 @item TEXINFO_DIR_CATEGORY
13727 @cindex #+TEXINFO_DIR_CATEGORY
13728 The directory category of the document.
13730 @item TEXINFO_DIR_TITLE
13731 @cindex #+TEXINFO_DIR_TITLE
13732 The directory title of the document.
13734 @item TEXINFO_DIR_DESC
13735 @cindex #+TEXINFO_DIR_DESC
13736 The directory description of the document.
13738 @item TEXINFO_PRINTED_TITLE
13739 @cindex #+TEXINFO_PRINTED_TITLE
13740 The printed title of the document.
13743 @node Texinfo file header
13744 @subsection Texinfo file header
13746 @cindex #+TEXINFO_FILENAME
13747 After creating the header for a Texinfo file, the Texinfo back-end
13748 automatically generates a name and destination path for the Info file. To
13749 override this default with a more sensible path and name, specify the
13750 @code{#+TEXINFO_FILENAME} keyword.
13752 @vindex org-texinfo-coding-system
13753 @vindex org-texinfo-classes
13754 @cindex #+TEXINFO_HEADER
13755 @cindex #+TEXINFO_CLASS
13756 Along with the output's file name, the Texinfo header also contains language
13757 details (@pxref{Export settings}) and encoding system as set in the
13758 @code{org-texinfo-coding-system} variable. Insert @code{#+TEXINFO_HEADER}
13759 keywords for each additional command in the header, for example:
13760 @@code@{@@synindex@}.
13762 Instead of repeatedly installing the same set of commands, define a class in
13763 @code{org-texinfo-classes} once, and then activate it in the document by
13764 setting the @code{#+TEXINFO_CLASS} keyword to that class.
13766 @node Texinfo title and copyright page
13767 @subsection Texinfo title and copyright page
13769 @cindex #+TEXINFO_PRINTED_TITLE
13770 The default template for hard copy output has a title page with
13771 @code{#+TITLE} and @code{#+AUTHOR} (@pxref{Export settings}). To replace the
13772 regular @code{#+TITLE} with something different for the printed version, use
13773 the @code{#+TEXINFO_PRINTED_TITLE} and @code{#+SUBTITLE} keywords. Both
13774 expect raw Texinfo code for setting their values.
13776 @cindex #+SUBAUTHOR
13777 If one @code{#+AUTHOR} is not sufficient, add multiple @code{#+SUBAUTHOR}
13778 keywords. They have to be set in raw Texinfo code.
13781 #+AUTHOR: Jane Smith
13782 #+SUBAUTHOR: John Doe
13783 #+TEXINFO_PRINTED_TITLE: This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@}
13786 @cindex property, COPYING
13787 Copying material is defined in a dedicated headline with a non-@code{nil}
13788 @code{:COPYING:} property. The back-end inserts the contents within a
13789 @code{@@copying} command at the beginning of the document. The heading
13790 itself does not appear in the structure of the document.
13792 Copyright information is printed on the back of the title page.
13800 This is a short example of a complete Texinfo file, version 1.0.
13802 Copyright \copy 2016 Free Software Foundation, Inc.
13805 @node Info directory file
13806 @subsection Info directory file
13807 @cindex @samp{dir} file, in Texinfo export
13808 @cindex Texinfo export, @samp{dir} file
13809 @cindex Info directory file, in Texinfo export
13810 @cindex Texinfo export, Info directory file
13811 @cindex @code{install-info} parameters, in Texinfo export
13812 @cindex Texinfo export, @code{install-info} parameters
13814 @cindex #+TEXINFO_DIR_CATEGORY
13815 @cindex #+TEXINFO_DIR_TITLE
13816 @cindex #+TEXINFO_DIR_DESC
13817 The end result of the Texinfo export process is the creation of an Info file.
13818 This Info file's metadata has variables for category, title, and description:
13819 @code{#+TEXINFO_DIR_CATEGORY}, @code{#+TEXINFO_DIR_TITLE}, and
13820 @code{#+TEXINFO_DIR_DESC} that establish where in the Info hierarchy the file
13823 Here is an example that writes to the Info directory file:
13826 #+TEXINFO_DIR_CATEGORY: Emacs
13827 #+TEXINFO_DIR_TITLE: Org Mode: (org)
13828 #+TEXINFO_DIR_DESC: Outline-based notes management and organizer
13831 @node Headings and sectioning structure
13832 @subsection Headings and sectioning structure
13834 @vindex org-texinfo-classes
13835 @vindex org-texinfo-default-class
13836 @cindex #+TEXINFO_CLASS
13837 The Texinfo export back-end uses a pre-defined scheme to convert Org
13838 headlines to an equivalent Texinfo structuring commands. A scheme like this
13839 maps top-level headlines to numbered chapters tagged as @code{@@chapter} and
13840 lower-level headlines to unnumbered chapters tagged as @code{@@unnumbered}.
13841 To override such mappings to introduce @code{@@part} or other Texinfo
13842 structuring commands, define a new class in @code{org-texinfo-classes}.
13843 Activate the new class with the @code{#+TEXINFO_CLASS} keyword. When no new
13844 class is defined and activated, the Texinfo export back-end defaults to the
13845 @code{org-texinfo-default-class}.
13847 If an Org headline's level has no associated Texinfo structuring command, or
13848 is below a certain threshold (@pxref{Export settings}), then the Texinfo
13849 export back-end makes it into a list item.
13851 @cindex property, APPENDIX
13852 The Texinfo export back-end makes any headline with a non-@code{nil}
13853 @code{:APPENDIX:} property into an appendix. This happens independent of the
13854 Org headline level or the @code{#+TEXINFO_CLASS}.
13856 @cindex property, DESCRIPTION
13857 The Texinfo export back-end creates a menu entry after the Org headline for
13858 each regular sectioning structure. To override this with a shorter menu
13859 entry, use the @code{:ALT_TITLE:} property (@pxref{Table of contents}).
13860 Texinfo menu entries also have an option for a longer @code{:DESCRIPTION:}
13861 property. Here's an example that uses both to override the default menu
13865 * Controlling Screen Display
13867 :ALT_TITLE: Display
13868 :DESCRIPTION: Controlling Screen Display
13872 @cindex The Top node, in Texinfo export
13873 @cindex Texinfo export, Top node
13874 The text before the first headline belongs to the @samp{Top} node, i.e., the
13875 node in which a reader enters an Info manual. As such, it is expected not to
13876 appear in printed output generated from the @file{.texi} file. @inforef{The
13877 Top Node,,texinfo}, for more information.
13880 @subsection Indices
13883 @cindex concept index, in Texinfo export
13884 @cindex Texinfo export, index, concept
13886 @cindex function index, in Texinfo export
13887 @cindex Texinfo export, index, function
13889 @cindex keystroke index, in Texinfo export
13890 @cindex Texinfo export, keystroke index
13892 @cindex program index, in Texinfo export
13893 @cindex Texinfo export, program index
13895 @cindex data type index, in Texinfo export
13896 @cindex Texinfo export, data type index
13898 @cindex variable index, in Texinfo export
13899 @cindex Texinfo export, variable index
13900 The Texinfo export back-end recognizes these indexing keywords if used in the
13901 Org file: @code{#+CINDEX}, @code{#+FINDEX}, @code{#+KINDEX}, @code{#+PINDEX},
13902 @code{#+TINDEX}, and @code{#+VINDEX}. Write their value as verbatim Texinfo
13903 code; in particular, @samp{@{}, @samp{@}} and @samp{@@} characters need to be
13904 escaped with @samp{@@} if they not belong to a Texinfo command.
13907 #+CINDEX: Defining indexing entries
13910 @cindex property, INDEX
13911 For the back-end to generate an index entry for a headline, set the
13912 @code{:INDEX:} property to @samp{cp} or @samp{vr}. These abbreviations come
13913 from Texinfo that stand for concept index and variable index. The Texinfo
13914 manual has abbreviations for all other kinds of indexes. The back-end
13915 exports the headline as an unnumbered chapter or section command, and then
13916 inserts the index after its contents.
13925 @node Quoting Texinfo code
13926 @subsection Quoting Texinfo code
13928 Use any of the following three methods to insert or escape raw Texinfo code:
13931 @cindex #+BEGIN_EXPORT texinfo
13933 Richard @@@@texinfo:@@sc@{@@@@Stallman@@@@texinfo:@}@@@@ commence' GNU.
13935 #+TEXINFO: @@need800
13936 This paragraph is preceded by...
13938 #+BEGIN_EXPORT texinfo
13939 @@auindex Johnson, Mark
13940 @@auindex Lakoff, George
13944 @node Plain lists in Texinfo export
13945 @subsection Plain lists in Texinfo export
13946 @cindex #+ATTR_TEXINFO, in plain lists
13947 @cindex Two-column tables, in Texinfo export
13949 @cindex :table-type attribute, in Texinfo export
13950 The Texinfo export back-end by default converts description lists in the Org
13951 file using the default command @code{@@table}, which results in a table with
13952 two columns. To change this behavior, specify @code{:table-type} with
13953 @code{ftable} or @code{vtable} attributes. For more information,
13954 @inforef{Two-column Tables,,texinfo}.
13956 @vindex org-texinfo-table-default-markup
13957 @cindex :indic attribute, in Texinfo export
13958 The Texinfo export back-end by default also applies a text highlight based on
13959 the defaults stored in @code{org-texinfo-table-default-markup}. To override
13960 the default highlight command, specify another one with the @code{:indic}
13963 @cindex Multiple entries in two-column tables, in Texinfo export
13964 @cindex :sep attribute, in Texinfo export
13965 Org syntax is limited to one entry per list item. Nevertheless, the Texinfo
13966 export back-end can split that entry according to any text provided through
13967 the @code{:sep} attribute. Each part then becomes a new entry in the first
13968 column of the table.
13970 The following example illustrates all the attributes above:
13973 #+ATTR_TEXINFO: :table-type vtable :sep , :indic asis
13974 - foo, bar :: This is the common text for variables foo and bar.
13984 This is the common text for variables foo and bar.
13988 @node Tables in Texinfo export
13989 @subsection Tables in Texinfo export
13990 @cindex #+ATTR_TEXINFO, in tables
13992 When exporting tables, the Texinfo export back-end uses the widest cell width
13993 in each column. To override this and instead specify as fractions of line
13994 length, use the @code{:columns} attribute. See example below.
13997 #+ATTR_TEXINFO: :columns .5 .5
13998 | a cell | another cell |
14001 @node Images in Texinfo export
14002 @subsection Images in Texinfo export
14003 @cindex #+ATTR_TEXINFO, in images
14005 Insert a file link to the image in the Org file, and the Texinfo export
14006 back-end inserts the image. These links must have the usual supported image
14007 extensions and no descriptions. To scale the image, use @code{:width} and
14008 @code{:height} attributes. For alternate text, use @code{:alt} and specify
14009 the text using Texinfo code, as shown in the example:
14012 #+ATTR_TEXINFO: :width 1in :alt Alternate @@i@{text@}
14016 @node Special blocks in Texinfo export
14017 @subsection Special blocks
14018 @cindex #+ATTR_TEXINFO, in special blocks
14020 The Texinfo export back-end converts special blocks to commands with the same
14021 name. It also adds any @code{:options} attributes to the end of the command,
14022 as shown in this example:
14025 #+ATTR_TEXINFO: :options org-org-export-to-org ...
14027 A somewhat obsessive function.
14035 @@defun org-org-export-to-org ...
14036 A somewhat obsessive function.
14040 @node A Texinfo example
14041 @subsection A Texinfo example
14043 Here is a more detailed example Org file. See @ref{GNU Sample
14044 Texts,,,texinfo,GNU Texinfo Manual} for an equivalent example using Texinfo
14048 #+TITLE: GNU Sample @{@{@{version@}@}@}
14049 #+SUBTITLE: for version @{@{@{version@}@}@}, @{@{@{updated@}@}@}
14050 #+AUTHOR: A.U. Thor
14051 #+EMAIL: bug-sample@@gnu.org
14053 #+OPTIONS: ':t toc:t author:t email:t
14056 #+MACRO: version 2.0
14057 #+MACRO: updated last updated 4 March 2014
14059 #+TEXINFO_FILENAME: sample.info
14060 #+TEXINFO_HEADER: @@syncodeindex pg cp
14062 #+TEXINFO_DIR_CATEGORY: Texinfo documentation system
14063 #+TEXINFO_DIR_TITLE: sample: (sample)
14064 #+TEXINFO_DIR_DESC: Invoking sample
14066 #+TEXINFO_PRINTED_TITLE: GNU Sample
14068 This manual is for GNU Sample (version @{@{@{version@}@}@},
14069 @{@{@{updated@}@}@}).
14076 This manual is for GNU Sample (version @{@{@{version@}@}@},
14077 @{@{@{updated@}@}@}), which is an example in the Texinfo documentation.
14079 Copyright \copy 2016 Free Software Foundation, Inc.
14082 Permission is granted to copy, distribute and/or modify this
14083 document under the terms of the GNU Free Documentation License,
14084 Version 1.3 or any later version published by the Free Software
14085 Foundation; with no Invariant Sections, with no Front-Cover Texts,
14086 and with no Back-Cover Texts. A copy of the license is included in
14087 the section entitled "GNU Free Documentation License".
14093 #+CINDEX: invoking @@command@{sample@}
14095 This is a sample manual. There is no sample program to invoke, but
14096 if there were, you could see its basic usage and command line
14099 * GNU Free Documentation License
14104 #+TEXINFO: @@include fdl.texi
14112 @node iCalendar export
14113 @section iCalendar export
14114 @cindex iCalendar export
14116 @vindex org-icalendar-include-todo
14117 @vindex org-icalendar-use-deadline
14118 @vindex org-icalendar-use-scheduled
14119 @vindex org-icalendar-categories
14120 @vindex org-icalendar-alarm-time
14121 A large part of Org mode's inter-operability success is its ability to easily
14122 export to or import from external applications. The iCalendar export
14123 back-end takes calendar data from Org files and exports to the standard
14126 The iCalendar export back-end can also incorporate TODO entries based on the
14127 configuration of the @code{org-icalendar-include-todo} variable. The
14128 back-end exports plain timestamps as VEVENT, TODO items as VTODO, and also
14129 create events from deadlines that are in non-TODO items. The back-end uses
14130 the deadlines and scheduling dates in Org TODO items for setting the start
14131 and due dates for the iCalendar TODO entry. Consult the
14132 @code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}
14133 variables for more details.
14135 For tags on the headline, the iCalendar export back-end makes them into
14136 iCalendar categories. To tweak the inheritance of tags and TODO states,
14137 configure the variable @code{org-icalendar-categories}. To assign clock
14138 alarms based on time, configure the @code{org-icalendar-alarm-time} variable.
14140 @vindex org-icalendar-store-UID
14141 @cindex property, ID
14142 The iCalendar format standard requires globally unique identifier---UID---for
14143 each entry. The iCalendar export back-end creates UIDs during export. To
14144 save a copy of the UID in the Org file set the variable
14145 @code{org-icalendar-store-UID}. The back-end looks for the @code{:ID:}
14146 property of the entry for re-using the same UID for subsequent exports.
14148 Since a single Org entry can result in multiple iCalendar entries---as
14149 timestamp, deadline, scheduled item, or TODO item---Org adds prefixes to the
14150 UID, depending on which part of the Org entry triggered the creation of the
14151 iCalendar entry. Prefixing ensures UIDs remains unique, yet enable
14152 synchronization programs trace the connections.
14155 @orgcmd{C-c C-e c f,org-icalendar-export-to-ics}
14156 Create iCalendar entries from the current Org buffer and store them in the
14157 same directory, using a file extension @file{.ics}.
14158 @orgcmd{C-c C-e c a, org-icalendar-export-agenda-files}
14159 @vindex org-agenda-files
14160 Create iCalendar entries from Org files in @code{org-agenda-files} and store
14161 in a separate iCalendar file for each Org file.
14162 @orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files}
14163 @vindex org-icalendar-combined-agenda-file
14164 Create a combined iCalendar file from Org files in @code{org-agenda-files}
14165 and write it to @code{org-icalendar-combined-agenda-file} file name.
14168 @vindex org-use-property-inheritance
14169 @vindex org-icalendar-include-body
14170 @cindex property, SUMMARY
14171 @cindex property, DESCRIPTION
14172 @cindex property, LOCATION
14173 @cindex property, TIMEZONE
14174 The iCalendar export back-end includes SUMMARY, DESCRIPTION, LOCATION and
14175 TIMEZONE properties from the Org entries when exporting. To force the
14176 back-end to inherit the LOCATION and TIMEZONE properties, configure the
14177 @code{org-use-property-inheritance} variable.
14179 When Org entries do not have SUMMARY, DESCRIPTION and LOCATION properties,
14180 the iCalendar export back-end derives the summary from the headline, and
14181 derives the description from the body of the Org item. The
14182 @code{org-icalendar-include-body} variable limits the maximum number of
14183 characters of the content are turned into its description.
14185 The TIMEZONE property can be used to specify a per-entry time zone, and will
14186 be applied to any entry with timestamp information. Time zones should be
14187 specified as per the IANA time zone database format, e.g.@: ``Asia/Almaty''.
14188 Alternately, the property value can be ``UTC'', to force UTC time for this
14191 Exporting to iCalendar format depends in large part on the capabilities of
14192 the destination application. Some are more lenient than others. Consult the
14193 Org mode FAQ for advice on specific applications.
14195 @node Other built-in back-ends
14196 @section Other built-in back-ends
14197 @cindex export back-ends, built-in
14198 @vindex org-export-backends
14200 Other export back-ends included with Org are:
14203 @item @file{ox-man.el}: export to a man page.
14206 To activate such back-ends, either customize @code{org-export-backends} or
14207 load directly with @code{(require 'ox-man)}. On successful load, the
14208 back-end adds new keys in the export dispatcher (@pxref{The export
14211 Follow the comment section of such files, for example, @file{ox-man.el}, for
14212 usage and configuration details.
14214 @node Advanced configuration
14215 @section Advanced configuration
14219 @vindex org-export-before-processing-hook
14220 @vindex org-export-before-parsing-hook
14221 The export process executes two hooks before the actual exporting begins.
14222 The first hook, @code{org-export-before-processing-hook}, runs before any
14223 expansions of macros, Babel code, and include keywords in the buffer. The
14224 second hook, @code{org-export-before-parsing-hook}, runs before the buffer is
14225 parsed. Both hooks are specified as functions, see example below. Their main
14226 use is for heavy duty structural modifications of the Org content. For
14227 example, removing every headline in the buffer during export:
14231 (defun my-headline-removal (backend)
14232 "Remove all headlines in the current buffer.
14233 BACKEND is the export back-end being used, as a symbol."
14235 (lambda () (delete-region (point) (progn (forward-line) (point))))))
14237 (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
14241 Note that the hook function must have a mandatory argument that is a symbol
14244 @subheading Filters
14246 @cindex Filters, exporting
14247 The Org export process relies on filters to process specific parts of
14248 conversion process. Filters are just lists of functions to be applied to
14249 certain parts for a given back-end. The output from the first function in
14250 the filter is passed on to the next function in the filter. The final output
14251 is the output from the final function in the filter.
14253 The Org export process has many filter sets applicable to different types of
14254 objects, plain text, parse trees, export options, and final output formats.
14255 The filters are named after the element type or object type:
14256 @code{org-export-filter-TYPE-functions}, where @code{TYPE} is the type
14257 targeted by the filter. Valid types are:
14259 @multitable @columnfractions .33 .33 .33
14272 @item export-snippet
14275 @item footnote-definition
14276 @tab footnote-reference
14278 @item horizontal-rule
14279 @tab inline-babel-call
14280 @tab inline-src-block
14285 @tab latex-environment
14286 @tab latex-fragment
14296 @item property-drawer
14302 @item statistics-cookie
14303 @tab strike-through
14316 Here is an example filter that replaces non-breaking spaces @code{~} in the
14317 Org buffer with @code{_} for the @LaTeX{} back-end.
14321 (defun my-latex-filter-nobreaks (text backend info)
14322 "Ensure \"_\" are properly handled in LaTeX export."
14323 (when (org-export-derived-backend-p backend 'latex)
14324 (replace-regexp-in-string "_" "~" text)))
14326 (add-to-list 'org-export-filter-plain-text-functions
14327 'my-latex-filter-nobreaks)
14331 A filter requires three arguments: the code to be transformed, the name of
14332 the back-end, and some optional information about the export process. The
14333 third argument can be safely ignored. Note the use of
14334 @code{org-export-derived-backend-p} predicate that tests for @code{latex}
14335 back-end or any other back-end, such as @code{beamer}, derived from
14338 @subheading Defining filters for individual files
14340 The Org export can filter not just for back-ends, but also for specific files
14341 through the @code{#+BIND} keyword. Here is an example with two filters; one
14342 removes brackets from time stamps, and the other removes strike-through text.
14343 The filter functions are defined in a @samp{src} code block in the same Org
14344 file, which is a handy location for debugging.
14347 #+BIND: org-export-filter-timestamp-functions (tmp-f-timestamp)
14348 #+BIND: org-export-filter-strike-through-functions (tmp-f-strike-through)
14349 #+begin_src emacs-lisp :exports results :results none
14350 (defun tmp-f-timestamp (s backend info)
14351 (replace-regexp-in-string "&[lg]t;\\|[][]" "" s))
14352 (defun tmp-f-strike-through (s backend info) "")
14356 @subheading Extending an existing back-end
14358 Some parts of the conversion process can be extended for certain elements so
14359 as to introduce a new or revised translation. That is how the HTML export
14360 back-end was extended to handle Markdown format. The extensions work
14361 seamlessly so any aspect of filtering not done by the extended back-end is
14362 handled by the original back-end. Of all the export customization in Org,
14363 extending is very powerful as it operates at the parser level.
14365 For this example, make the @code{ascii} back-end display the language used in
14366 a source code block. Also make it display only when some attribute is
14367 non-@code{nil}, like the following:
14370 #+ATTR_ASCII: :language t
14373 Then extend @code{ascii} back-end with a custom @code{my-ascii} back-end.
14377 (defun my-ascii-src-block (src-block contents info)
14378 "Transcode a SRC-BLOCK element from Org to ASCII.
14379 CONTENTS is nil. INFO is a plist used as a communication
14381 (if (not (org-export-read-attribute :attr_ascii src-block :language))
14382 (org-export-with-backend 'ascii src-block contents info)
14384 (format ",--[ %s ]--\n%s`----"
14385 (org-element-property :language src-block)
14386 (replace-regexp-in-string
14388 (org-element-normalize-string
14389 (org-export-format-code-default src-block info)))))))
14391 (org-export-define-derived-backend 'my-ascii 'ascii
14392 :translate-alist '((src-block . my-ascii-src-block)))
14396 The @code{my-ascii-src-block} function looks at the attribute above the
14397 current element. If not true, hands over to @code{ascii} back-end. If true,
14398 which it is in this example, it creates a box around the code and leaves room
14399 for the inserting a string for language. The last form creates the new
14400 back-end that springs to action only when translating @code{src-block} type
14403 To use the newly defined back-end, call the following from an Org buffer:
14406 (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
14409 Further steps to consider would be an interactive function, self-installing
14410 an item in the export dispatcher menu, and other user-friendly improvements.
14412 @node Export in foreign buffers
14413 @section Export in foreign buffers
14415 The export back-ends in Org often include commands to convert selected
14416 regions. A convenient feature of this in-place conversion is that the
14417 exported output replaces the original source. Here are such functions:
14420 @item org-html-convert-region-to-html
14421 Convert the selected region into HTML.
14422 @item org-latex-convert-region-to-latex
14423 Convert the selected region into @LaTeX{}.
14424 @item org-texinfo-convert-region-to-texinfo
14425 Convert the selected region into @code{Texinfo}.
14426 @item org-md-convert-region-to-md
14427 Convert the selected region into @code{MarkDown}.
14430 In-place conversions are particularly handy for quick conversion of tables
14431 and lists in foreign buffers. For example, turn on the minor mode @code{M-x
14432 orgstruct-mode} in an HTML buffer, then use the convenient Org keyboard
14433 commands to create a list, select it, and covert it to HTML with @code{M-x
14434 org-html-convert-region-to-html RET}.
14438 @chapter Publishing
14441 Org includes a publishing management system that allows you to configure
14442 automatic HTML conversion of @emph{projects} composed of interlinked org
14443 files. You can also configure Org to automatically upload your exported HTML
14444 pages and related attachments, such as images and source code files, to a web
14447 You can also use Org to convert files into PDF, or even combine HTML and PDF
14448 conversion so that files are available in both formats on the server.
14450 Publishing has been contributed to Org by David O'Toole.
14453 * Configuration:: Defining projects
14454 * Uploading files:: How to get files up on the server
14455 * Sample configuration:: Example projects
14456 * Triggering publication:: Publication commands
14459 @node Configuration
14460 @section Configuration
14462 Publishing needs significant configuration to specify files, destination
14463 and many other properties of a project.
14466 * Project alist:: The central configuration variable
14467 * Sources and destinations:: From here to there
14468 * Selecting files:: What files are part of the project?
14469 * Publishing action:: Setting the function doing the publishing
14470 * Publishing options:: Tweaking HTML/@LaTeX{} export
14471 * Publishing links:: Which links keep working after publishing?
14472 * Sitemap:: Generating a list of all pages
14473 * Generating an index:: An index that reaches across pages
14476 @node Project alist
14477 @subsection The variable @code{org-publish-project-alist}
14478 @cindex org-publish-project-alist
14479 @cindex projects, for publishing
14481 @vindex org-publish-project-alist
14482 Publishing is configured almost entirely through setting the value of one
14483 variable, called @code{org-publish-project-alist}. Each element of the list
14484 configures one project, and may be in one of the two following forms:
14487 ("project-name" :property value :property value ...)
14488 @r{i.e., a well-formed property list with alternating keys and values}
14490 ("project-name" :components ("project-name" "project-name" ...))
14494 In both cases, projects are configured by specifying property values. A
14495 project defines the set of files that will be published, as well as the
14496 publishing configuration to use when publishing those files. When a project
14497 takes the second form listed above, the individual members of the
14498 @code{:components} property are taken to be sub-projects, which group
14499 together files requiring different publishing options. When you publish such
14500 a ``meta-project'', all the components will also be published, in the
14503 @node Sources and destinations
14504 @subsection Sources and destinations for files
14505 @cindex directories, for publishing
14507 Most properties are optional, but some should always be set. In
14508 particular, Org needs to know where to look for source files,
14509 and where to put published files.
14511 @multitable @columnfractions 0.3 0.7
14512 @item @code{:base-directory}
14513 @tab Directory containing publishing source files
14514 @item @code{:publishing-directory}
14515 @tab Directory where output files will be published. You can directly
14516 publish to a web server using a file name syntax appropriate for
14517 the Emacs @file{tramp} package. Or you can publish to a local directory and
14518 use external tools to upload your website (@pxref{Uploading files}).
14519 @item @code{:preparation-function}
14520 @tab Function or list of functions to be called before starting the
14521 publishing process, for example, to run @code{make} for updating files to be
14522 published. Each preparation function is called with a single argument, the
14523 project property list.
14524 @item @code{:completion-function}
14525 @tab Function or list of functions called after finishing the publishing
14526 process, for example, to change permissions of the resulting files. Each
14527 completion function is called with a single argument, the project property
14532 @node Selecting files
14533 @subsection Selecting files
14534 @cindex files, selecting for publishing
14536 By default, all files with extension @file{.org} in the base directory
14537 are considered part of the project. This can be modified by setting the
14539 @multitable @columnfractions 0.25 0.75
14540 @item @code{:base-extension}
14541 @tab Extension (without the dot!) of source files. This actually is a
14542 regular expression. Set this to the symbol @code{any} if you want to get all
14543 files in @code{:base-directory}, even without extension.
14545 @item @code{:exclude}
14546 @tab Regular expression to match file names that should not be
14547 published, even though they have been selected on the basis of their
14550 @item @code{:include}
14551 @tab List of files to be included regardless of @code{:base-extension}
14552 and @code{:exclude}.
14554 @item @code{:recursive}
14555 @tab non-@code{nil} means, check base-directory recursively for files to publish.
14558 @node Publishing action
14559 @subsection Publishing action
14560 @cindex action, for publishing
14562 Publishing means that a file is copied to the destination directory and
14563 possibly transformed in the process. The default transformation is to export
14564 Org files as HTML files, and this is done by the function
14565 @code{org-html-publish-to-html}, which calls the HTML exporter (@pxref{HTML
14566 export}). But you also can publish your content as PDF files using
14567 @code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc.,
14568 using the corresponding functions.
14570 If you want to publish the Org file as an @code{.org} file but with the
14571 @i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the
14572 function @code{org-org-publish-to-org}. This will produce @file{file.org}
14573 and put it in the publishing directory. If you want a htmlized version of
14574 this file, set the parameter @code{:htmlized-source} to @code{t}, it will
14575 produce @file{file.org.html} in the publishing directory@footnote{If the
14576 publishing directory is the same than the source directory, @file{file.org}
14577 will be exported as @file{file.org.org}, so probably don't want to do this.}.
14579 Other files like images only need to be copied to the publishing destination.
14580 For this you can use @code{org-publish-attachment}. For non-org files, you
14581 always need to specify the publishing function:
14583 @multitable @columnfractions 0.3 0.7
14584 @item @code{:publishing-function}
14585 @tab Function executing the publication of a file. This may also be a
14586 list of functions, which will all be called in turn.
14587 @item @code{:htmlized-source}
14588 @tab non-@code{nil} means, publish htmlized source.
14591 The function must accept three arguments: a property list containing at least
14592 a @code{:publishing-directory} property, the name of the file to be published
14593 and the path to the publishing directory of the output file. It should take
14594 the specified file, make the necessary transformation (if any) and place the
14595 result into the destination folder.
14597 @node Publishing options
14598 @subsection Options for the exporters
14599 @cindex options, for publishing
14601 The property list can be used to set export options during the publishing
14602 process. In most cases, these properties correspond to user variables in
14603 Org. While some properties are available for all export back-ends, most of
14604 them are back-end specific. The following sections list properties along
14605 with the variable they belong to. See the documentation string of these
14606 options for details.
14608 @vindex org-publish-project-alist
14609 When a property is given a value in @code{org-publish-project-alist}, its
14610 setting overrides the value of the corresponding user variable (if any)
14611 during publishing. Options set within a file (@pxref{Export settings}),
14612 however, override everything.
14614 @subsubheading Generic properties
14616 @multitable {@code{:with-sub-superscript}} {@code{org-export-with-sub-superscripts}}
14617 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
14618 @item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
14619 @item @code{:headline-levels} @tab @code{org-export-headline-levels}
14620 @item @code{:language} @tab @code{org-export-default-language}
14621 @item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}
14622 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
14623 @item @code{:select-tags} @tab @code{org-export-select-tags}
14624 @item @code{:with-author} @tab @code{org-export-with-author}
14625 @item @code{:with-broken-links} @tab @code{org-export-with-broken-links}
14626 @item @code{:with-clocks} @tab @code{org-export-with-clocks}
14627 @item @code{:with-creator} @tab @code{org-export-with-creator}
14628 @item @code{:with-date} @tab @code{org-export-with-date}
14629 @item @code{:with-drawers} @tab @code{org-export-with-drawers}
14630 @item @code{:with-email} @tab @code{org-export-with-email}
14631 @item @code{:with-emphasize} @tab @code{org-export-with-emphasize}
14632 @item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width}
14633 @item @code{:with-footnotes} @tab @code{org-export-with-footnotes}
14634 @item @code{:with-latex} @tab @code{org-export-with-latex}
14635 @item @code{:with-planning} @tab @code{org-export-with-planning}
14636 @item @code{:with-priority} @tab @code{org-export-with-priority}
14637 @item @code{:with-properties} @tab @code{org-export-with-properties}
14638 @item @code{:with-special-strings} @tab @code{org-export-with-special-strings}
14639 @item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts}
14640 @item @code{:with-tables} @tab @code{org-export-with-tables}
14641 @item @code{:with-tags} @tab @code{org-export-with-tags}
14642 @item @code{:with-tasks} @tab @code{org-export-with-tasks}
14643 @item @code{:with-timestamps} @tab @code{org-export-with-timestamps}
14644 @item @code{:with-title} @tab @code{org-export-with-title}
14645 @item @code{:with-toc} @tab @code{org-export-with-toc}
14646 @item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords}
14649 @subsubheading ASCII specific properties
14651 @multitable {@code{:ascii-table-keep-all-vertical-lines}} {@code{org-ascii-table-keep-all-vertical-lines}}
14652 @item @code{:ascii-bullets} @tab @code{org-ascii-bullets}
14653 @item @code{:ascii-caption-above} @tab @code{org-ascii-caption-above}
14654 @item @code{:ascii-charset} @tab @code{org-ascii-charset}
14655 @item @code{:ascii-global-margin} @tab @code{org-ascii-global-margin}
14656 @item @code{:ascii-format-drawer-function} @tab @code{org-ascii-format-drawer-function}
14657 @item @code{:ascii-format-inlinetask-function} @tab @code{org-ascii-format-inlinetask-function}
14658 @item @code{:ascii-headline-spacing} @tab @code{org-ascii-headline-spacing}
14659 @item @code{:ascii-indented-line-width} @tab @code{org-ascii-indented-line-width}
14660 @item @code{:ascii-inlinetask-width} @tab @code{org-ascii-inlinetask-width}
14661 @item @code{:ascii-inner-margin} @tab @code{org-ascii-inner-margin}
14662 @item @code{:ascii-links-to-notes} @tab @code{org-ascii-links-to-notes}
14663 @item @code{:ascii-list-margin} @tab @code{org-ascii-list-margin}
14664 @item @code{:ascii-paragraph-spacing} @tab @code{org-ascii-paragraph-spacing}
14665 @item @code{:ascii-quote-margin} @tab @code{org-ascii-quote-margin}
14666 @item @code{:ascii-table-keep-all-vertical-lines} @tab @code{org-ascii-table-keep-all-vertical-lines}
14667 @item @code{:ascii-table-use-ascii-art} @tab @code{org-ascii-table-use-ascii-art}
14668 @item @code{:ascii-table-widen-columns} @tab @code{org-ascii-table-widen-columns}
14669 @item @code{:ascii-text-width} @tab @code{org-ascii-text-width}
14670 @item @code{:ascii-underline} @tab @code{org-ascii-underline}
14671 @item @code{:ascii-verbatim-format} @tab @code{org-ascii-verbatim-format}
14674 @subsubheading Beamer specific properties
14676 @multitable {@code{:beamer-frame-default-options}} {@code{org-beamer-frame-default-options}}
14677 @item @code{:beamer-theme} @tab @code{org-beamer-theme}
14678 @item @code{:beamer-column-view-format} @tab @code{org-beamer-column-view-format}
14679 @item @code{:beamer-environments-extra} @tab @code{org-beamer-environments-extra}
14680 @item @code{:beamer-frame-default-options} @tab @code{org-beamer-frame-default-options}
14681 @item @code{:beamer-outline-frame-options} @tab @code{org-beamer-outline-frame-options}
14682 @item @code{:beamer-outline-frame-title} @tab @code{org-beamer-outline-frame-title}
14683 @item @code{:beamer-subtitle-format} @tab @code{org-beamer-subtitle-format}
14686 @subsubheading HTML specific properties
14688 @multitable {@code{:html-table-use-header-tags-for-first-column}} {@code{org-html-table-use-header-tags-for-first-column}}
14689 @item @code{:html-allow-name-attribute-in-anchors} @tab @code{org-html-allow-name-attribute-in-anchors}
14690 @item @code{:html-checkbox-type} @tab @code{org-html-checkbox-type}
14691 @item @code{:html-container} @tab @code{org-html-container-element}
14692 @item @code{:html-divs} @tab @code{org-html-divs}
14693 @item @code{:html-doctype} @tab @code{org-html-doctype}
14694 @item @code{:html-extension} @tab @code{org-html-extension}
14695 @item @code{:html-footnote-format} @tab @code{org-html-footnote-format}
14696 @item @code{:html-footnote-separator} @tab @code{org-html-footnote-separator}
14697 @item @code{:html-footnotes-section} @tab @code{org-html-footnotes-section}
14698 @item @code{:html-format-drawer-function} @tab @code{org-html-format-drawer-function}
14699 @item @code{:html-format-headline-function} @tab @code{org-html-format-headline-function}
14700 @item @code{:html-format-inlinetask-function} @tab @code{org-html-format-inlinetask-function}
14701 @item @code{:html-head-extra} @tab @code{org-html-head-extra}
14702 @item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style}
14703 @item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts}
14704 @item @code{:html-head} @tab @code{org-html-head}
14705 @item @code{:html-home/up-format} @tab @code{org-html-home/up-format}
14706 @item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy}
14707 @item @code{:html-indent} @tab @code{org-html-indent}
14708 @item @code{:html-infojs-options} @tab @code{org-html-infojs-options}
14709 @item @code{:html-infojs-template} @tab @code{org-html-infojs-template}
14710 @item @code{:html-inline-image-rules} @tab @code{org-html-inline-image-rules}
14711 @item @code{:html-inline-images} @tab @code{org-html-inline-images}
14712 @item @code{:html-link-home} @tab @code{org-html-link-home}
14713 @item @code{:html-link-org-files-as-html} @tab @code{org-html-link-org-files-as-html}
14714 @item @code{:html-link-up} @tab @code{org-html-link-up}
14715 @item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url}
14716 @item @code{:html-mathjax-options} @tab @code{org-html-mathjax-options}
14717 @item @code{:html-mathjax-template} @tab @code{org-html-mathjax-template}
14718 @item @code{:html-metadata-timestamp-format} @tab @code{org-html-metadata-timestamp-format}
14719 @item @code{:html-postamble-format} @tab @code{org-html-postamble-format}
14720 @item @code{:html-postamble} @tab @code{org-html-postamble}
14721 @item @code{:html-preamble-format} @tab @code{org-html-preamble-format}
14722 @item @code{:html-preamble} @tab @code{org-html-preamble}
14723 @item @code{:html-table-align-individual-fields} @tab @code{org-html-table-align-individual-fields}
14724 @item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
14725 @item @code{:html-table-caption-above} @tab @code{org-html-table-caption-above}
14726 @item @code{:html-table-data-tags} @tab @code{org-html-table-data-tags}
14727 @item @code{:html-table-header-tags} @tab @code{org-html-table-header-tags}
14728 @item @code{:html-table-row-tags} @tab @code{org-html-table-row-tags}
14729 @item @code{:html-table-use-header-tags-for-first-column} @tab @code{org-html-table-use-header-tags-for-first-column}
14730 @item @code{:html-tag-class-prefix} @tab @code{org-html-tag-class-prefix}
14731 @item @code{:html-text-markup-alist} @tab @code{org-html-text-markup-alist}
14732 @item @code{:html-todo-kwd-class-prefix} @tab @code{org-html-todo-kwd-class-prefix}
14733 @item @code{:html-toplevel-hlevel} @tab @code{org-html-toplevel-hlevel}
14734 @item @code{:html-use-infojs} @tab @code{org-html-use-infojs}
14735 @item @code{:html-validation-link} @tab @code{org-html-validation-link}
14736 @item @code{:html-viewport} @tab @code{org-html-viewport}
14737 @item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration}
14740 @subsubheading @LaTeX{} specific properties
14742 @multitable {@code{:latex-link-with-unknown-path-format}} {@code{org-latex-link-with-unknown-path-format}}
14743 @item @code{:latex-active-timestamp-format} @tab @code{org-latex-active-timestamp-format}
14744 @item @code{:latex-caption-above} @tab @code{org-latex-caption-above}
14745 @item @code{:latex-classes} @tab @code{org-latex-classes}
14746 @item @code{:latex-class} @tab @code{org-latex-default-class}
14747 @item @code{:latex-compiler} @tab @code{org-latex-compiler}
14748 @item @code{:latex-default-figure-position} @tab @code{org-latex-default-figure-position}
14749 @item @code{:latex-default-table-environment} @tab @code{org-latex-default-table-environment}
14750 @item @code{:latex-default-table-mode} @tab @code{org-latex-default-table-mode}
14751 @item @code{:latex-diary-timestamp-format} @tab @code{org-latex-diary-timestamp-format}
14752 @item @code{:latex-footnote-defined-format} @tab @code{org-latex-footnote-defined-format}
14753 @item @code{:latex-footnote-separator} @tab @code{org-latex-footnote-separator}
14754 @item @code{:latex-format-drawer-function} @tab @code{org-latex-format-drawer-function}
14755 @item @code{:latex-format-headline-function} @tab @code{org-latex-format-headline-function}
14756 @item @code{:latex-format-inlinetask-function} @tab @code{org-latex-format-inlinetask-function}
14757 @item @code{:latex-hyperref-template} @tab @code{org-latex-hyperref-template}
14758 @item @code{:latex-image-default-height} @tab @code{org-latex-image-default-height}
14759 @item @code{:latex-image-default-option} @tab @code{org-latex-image-default-option}
14760 @item @code{:latex-image-default-width} @tab @code{org-latex-image-default-width}
14761 @item @code{:latex-images-centered} @tab @code{org-latex-images-centered}
14762 @item @code{:latex-inactive-timestamp-format} @tab @code{org-latex-inactive-timestamp-format}
14763 @item @code{:latex-inline-image-rules} @tab @code{org-latex-inline-image-rules}
14764 @item @code{:latex-link-with-unknown-path-format} @tab @code{org-latex-link-with-unknown-path-format}
14765 @item @code{:latex-listings-langs} @tab @code{org-latex-listings-langs}
14766 @item @code{:latex-listings-options} @tab @code{org-latex-listings-options}
14767 @item @code{:latex-listings} @tab @code{org-latex-listings}
14768 @item @code{:latex-minted-langs} @tab @code{org-latex-minted-langs}
14769 @item @code{:latex-minted-options} @tab @code{org-latex-minted-options}
14770 @item @code{:latex-prefer-user-labels} @tab @code{org-latex-prefer-user-labels}
14771 @item @code{:latex-subtitle-format} @tab @code{org-latex-subtitle-format}
14772 @item @code{:latex-subtitle-separate} @tab @code{org-latex-subtitle-separate}
14773 @item @code{:latex-table-scientific-notation} @tab @code{org-latex-table-scientific-notation}
14774 @item @code{:latex-tables-booktabs} @tab @code{org-latex-tables-booktabs}
14775 @item @code{:latex-tables-centered} @tab @code{org-latex-tables-centered}
14776 @item @code{:latex-text-markup-alist} @tab @code{org-latex-text-markup-alist}
14777 @item @code{:latex-title-command} @tab @code{org-latex-title-command}
14778 @item @code{:latex-toc-command} @tab @code{org-latex-toc-command}
14781 @subsubheading Markdown specific properties
14783 @multitable {@code{:md-footnotes-section}} {@code{org-md-footnotes-section}}
14784 @item @code{:md-footnote-format} @tab @code{org-md-footnote-format}
14785 @item @code{:md-footnotes-section} @tab @code{org-md-footnotes-section}
14786 @item @code{:md-headline-style} @tab @code{org-md-headline-style}
14789 @subsubheading ODT specific properties
14791 @multitable {@code{:odt-format-inlinetask-function}} {@code{org-odt-format-inlinetask-function}}
14792 @item @code{:odt-content-template-file} @tab @code{org-odt-content-template-file}
14793 @item @code{:odt-display-outline-level} @tab @code{org-odt-display-outline-level}
14794 @item @code{:odt-fontify-srcblocks} @tab @code{org-odt-fontify-srcblocks}
14795 @item @code{:odt-format-drawer-function} @tab @code{org-odt-format-drawer-function}
14796 @item @code{:odt-format-headline-function} @tab @code{org-odt-format-headline-function}
14797 @item @code{:odt-format-inlinetask-function} @tab @code{org-odt-format-inlinetask-function}
14798 @item @code{:odt-inline-formula-rules} @tab @code{org-odt-inline-formula-rules}
14799 @item @code{:odt-inline-image-rules} @tab @code{org-odt-inline-image-rules}
14800 @item @code{:odt-pixels-per-inch} @tab @code{org-odt-pixels-per-inch}
14801 @item @code{:odt-styles-file} @tab @code{org-odt-styles-file}
14802 @item @code{:odt-table-styles} @tab @code{org-odt-table-styles}
14803 @item @code{:odt-use-date-fields} @tab @code{org-odt-use-date-fields}
14806 @subsubheading Texinfo specific properties
14808 @multitable {@code{:texinfo-link-with-unknown-path-format}} {@code{org-texinfo-link-with-unknown-path-format}}
14809 @item @code{:texinfo-active-timestamp-format} @tab @code{org-texinfo-active-timestamp-format}
14810 @item @code{:texinfo-classes} @tab @code{org-texinfo-classes}
14811 @item @code{:texinfo-class} @tab @code{org-texinfo-default-class}
14812 @item @code{:texinfo-table-default-markup} @tab @code{org-texinfo-table-default-markup}
14813 @item @code{:texinfo-diary-timestamp-format} @tab @code{org-texinfo-diary-timestamp-format}
14814 @item @code{:texinfo-filename} @tab @code{org-texinfo-filename}
14815 @item @code{:texinfo-format-drawer-function} @tab @code{org-texinfo-format-drawer-function}
14816 @item @code{:texinfo-format-headline-function} @tab @code{org-texinfo-format-headline-function}
14817 @item @code{:texinfo-format-inlinetask-function} @tab @code{org-texinfo-format-inlinetask-function}
14818 @item @code{:texinfo-inactive-timestamp-format} @tab @code{org-texinfo-inactive-timestamp-format}
14819 @item @code{:texinfo-link-with-unknown-path-format} @tab @code{org-texinfo-link-with-unknown-path-format}
14820 @item @code{:texinfo-node-description-column} @tab @code{org-texinfo-node-description-column}
14821 @item @code{:texinfo-table-scientific-notation} @tab @code{org-texinfo-table-scientific-notation}
14822 @item @code{:texinfo-tables-verbatim} @tab @code{org-texinfo-tables-verbatim}
14823 @item @code{:texinfo-text-markup-alist} @tab @code{org-texinfo-text-markup-alist}
14826 @node Publishing links
14827 @subsection Links between published files
14828 @cindex links, publishing
14830 To create a link from one Org file to another, you would use something like
14831 @samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org}
14832 (@pxref{External links}). When published, this link becomes a link to
14833 @file{foo.html}. You can thus interlink the pages of your ``org web''
14834 project and the links will work as expected when you publish them to HTML.
14835 If you also publish the Org source file and want to link to it, use an
14836 @code{http:} link instead of a @code{file:} link, because @code{file:} links
14837 are converted to link to the corresponding @file{html} file.
14839 You may also link to related files, such as images. Provided you are careful
14840 with relative file names, and provided you have also configured Org to upload
14841 the related files, these links will work too. See @ref{Complex example}, for
14842 an example of this usage.
14844 Eventually, links between published documents can contain some search options
14845 (@pxref{Search options}), which will be resolved to the appropriate location
14846 in the linked file. For example, once published to HTML, the following links
14847 all point to a dedicated anchor in @file{foo.html}.
14850 [[file:foo.org::*heading]]
14851 [[file:foo.org::#custom-id]]
14852 [[file:foo.org::target]]
14856 @subsection Generating a sitemap
14857 @cindex sitemap, of published pages
14859 The following properties may be used to control publishing of
14860 a map of files for a given project.
14862 @multitable @columnfractions 0.35 0.65
14863 @item @code{:auto-sitemap}
14864 @tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project}
14865 or @code{org-publish-all}.
14867 @item @code{:sitemap-filename}
14868 @tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which
14869 becomes @file{sitemap.html}).
14871 @item @code{:sitemap-title}
14872 @tab Title of sitemap page. Defaults to name of file.
14874 @item @code{:sitemap-format-entry}
14875 @tab With this option one can tell how a site-map entry is formatted in the
14876 site-map. It is a function called with three arguments: the file or
14877 directory name relative to base directory of the project, the site-map style
14878 and the current project. It is expected to return a string. Default value
14879 turns file names into links and use document titles as descriptions. For
14880 specific formatting needs, one can use @code{org-publish-find-date},
14881 @code{org-publish-find-title} and @code{org-publish-find-property}, to
14882 retrieve additional information about published documents.
14884 @item @code{:sitemap-function}
14885 @tab Plug-in function to use for generation of the sitemap. It is called
14886 with two arguments: the title of the site-map and a representation of the
14887 files and directories involved in the project as a radio list (@pxref{Radio
14888 lists}). The latter can further be transformed using
14889 @code{org-list-to-generic}, @code{org-list-to-subtree} and alike. Default
14890 value generates a plain list of links to all files in the project.
14892 @item @code{:sitemap-sort-folders}
14893 @tab Where folders should appear in the sitemap. Set this to @code{first}
14894 (default) or @code{last} to display folders first or last, respectively.
14895 When set to @code{ignore}, folders are ignored altogether. Any other value
14896 will mix files and folders. This variable has no effect when site-map style
14899 @item @code{:sitemap-sort-files}
14900 @tab How the files are sorted in the site map. Set this to
14901 @code{alphabetically} (default), @code{chronologically} or
14902 @code{anti-chronologically}. @code{chronologically} sorts the files with
14903 older date first while @code{anti-chronologically} sorts the files with newer
14904 date first. @code{alphabetically} sorts the files alphabetically. The date of
14905 a file is retrieved with @code{org-publish-find-date}.
14907 @item @code{:sitemap-ignore-case}
14908 @tab Should sorting be case-sensitive? Default @code{nil}.
14910 @item @code{:sitemap-date-format}
14911 @tab Format string for the @code{format-time-string} function that tells how
14912 a sitemap entry's date is to be formatted. This property bypasses
14913 @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
14917 @node Generating an index
14918 @subsection Generating an index
14919 @cindex index, in a publishing project
14921 Org mode can generate an index across the files of a publishing project.
14923 @multitable @columnfractions 0.25 0.75
14924 @item @code{:makeindex}
14925 @tab When non-@code{nil}, generate in index in the file @file{theindex.org} and
14926 publish it as @file{theindex.html}.
14929 The file will be created when first publishing a project with the
14930 @code{:makeindex} set. The file only contains a statement @code{#+INCLUDE:
14931 "theindex.inc"}. You can then build around this include statement by adding
14932 a title, style information, etc.
14935 Index entries are specified with @code{#+INDEX} keyword. An entry that
14936 contains an exclamation mark will create a sub item.
14941 #+INDEX: Application!CV
14944 @node Uploading files
14945 @section Uploading files
14949 For those people already utilizing third party sync tools such as
14950 @command{rsync} or @command{unison}, it might be preferable not to use the built in
14951 @i{remote} publishing facilities of Org mode which rely heavily on
14952 Tramp. Tramp, while very useful and powerful, tends not to be
14953 so efficient for multiple file transfer and has been known to cause problems
14956 Specialized synchronization utilities offer several advantages. In addition
14957 to timestamp comparison, they also do content and permissions/attribute
14958 checks. For this reason you might prefer to publish your web to a local
14959 directory (possibly even @i{in place} with your Org files) and then use
14960 @file{unison} or @file{rsync} to do the synchronization with the remote host.
14962 Since Unison (for example) can be configured as to which files to transfer to
14963 a certain remote destination, it can greatly simplify the project publishing
14964 definition. Simply keep all files in the correct location, process your Org
14965 files with @code{org-publish} and let the synchronization tool do the rest.
14966 You do not need, in this scenario, to include attachments such as @file{jpg},
14967 @file{css} or @file{gif} files in the project definition since the 3rd party
14970 Publishing to a local directory is also much faster than to a remote one, so
14971 that you can afford more easily to republish entire projects. If you set
14972 @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
14973 benefit of re-including any changed external files such as source example
14974 files you might include with @code{#+INCLUDE:}. The timestamp mechanism in
14975 Org is not smart enough to detect if included files have been modified.
14977 @node Sample configuration
14978 @section Sample configuration
14980 Below we provide two example configurations. The first one is a simple
14981 project publishing only a set of Org files. The second example is
14982 more complex, with a multi-component project.
14985 * Simple example:: One-component publishing
14986 * Complex example:: A multi-component publishing example
14989 @node Simple example
14990 @subsection Example: simple publishing configuration
14992 This example publishes a set of Org files to the @file{public_html}
14993 directory on the local machine.
14996 (setq org-publish-project-alist
14998 :base-directory "~/org/"
14999 :publishing-directory "~/public_html"
15000 :publishing-function org-html-publish-to-html
15001 :section-numbers nil
15003 :html-head "<link rel=\"stylesheet\"
15004 href=\"../other/mystyle.css\"
15005 type=\"text/css\"/>")))
15008 @node Complex example
15009 @subsection Example: complex publishing configuration
15011 This more complicated example publishes an entire website, including
15012 Org files converted to HTML, image files, Emacs Lisp source code, and
15013 style sheets. The publishing directory is remote and private files are
15016 To ensure that links are preserved, care should be taken to replicate
15017 your directory structure on the web server, and to use relative file
15018 paths. For example, if your Org files are kept in @file{~/org} and your
15019 publishable images in @file{~/images}, you would link to an image with
15022 file:../images/myimage.png
15025 On the web server, the relative path to the image should be the
15026 same. You can accomplish this by setting up an "images" folder in the
15027 right place on the web server, and publishing images to it.
15030 (setq org-publish-project-alist
15032 :base-directory "~/org/"
15033 :base-extension "org"
15034 :publishing-directory "/ssh:user@@host:~/html/notebook/"
15035 :publishing-function org-html-publish-to-html
15036 :exclude "PrivatePage.org" ;; regexp
15038 :section-numbers nil
15040 :html-head "<link rel=\"stylesheet\"
15041 href=\"../other/mystyle.css\" type=\"text/css\"/>"
15045 :base-directory "~/images/"
15046 :base-extension "jpg\\|gif\\|png"
15047 :publishing-directory "/ssh:user@@host:~/html/images/"
15048 :publishing-function org-publish-attachment)
15051 :base-directory "~/other/"
15052 :base-extension "css\\|el"
15053 :publishing-directory "/ssh:user@@host:~/html/other/"
15054 :publishing-function org-publish-attachment)
15055 ("website" :components ("orgfiles" "images" "other"))))
15058 @node Triggering publication
15059 @section Triggering publication
15061 Once properly configured, Org can publish with the following commands:
15064 @orgcmd{C-c C-e P x,org-publish}
15065 Prompt for a specific project and publish all files that belong to it.
15066 @orgcmd{C-c C-e P p,org-publish-current-project}
15067 Publish the project containing the current file.
15068 @orgcmd{C-c C-e P f,org-publish-current-file}
15069 Publish only the current file.
15070 @orgcmd{C-c C-e P a,org-publish-all}
15071 Publish every project.
15074 @vindex org-publish-use-timestamps-flag
15075 Org uses timestamps to track when a file has changed. The above functions
15076 normally only publish changed files. You can override this and force
15077 publishing of all files by giving a prefix argument to any of the commands
15078 above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
15079 This may be necessary in particular if files include other files via
15080 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
15083 @node Working with source code
15084 @chapter Working with source code
15085 @cindex Schulte, Eric
15086 @cindex Davison, Dan
15087 @cindex source code, working with
15089 Source code here refers to any code typed in Org mode documents. Org can
15090 manage source code in any Org file once such code is tagged with begin and
15091 end markers. Working with source code begins with tagging source code
15092 blocks. Tagged @samp{src} code blocks are not restricted to the preamble or
15093 the end of an Org document; they can go anywhere---with a few exceptions,
15094 such as not inside comments and fixed width areas. Here's a sample
15095 @samp{src} code block in emacs-lisp:
15098 #+BEGIN_SRC emacs-lisp
15099 (defun org-xor (a b)
15105 Org can take the code in the block between the @samp{#+BEGIN_SRC} and
15106 @samp{#+END_SRC} tags, and format, compile, execute, and show the results.
15107 Org can simplify many housekeeping tasks essential to modern code
15108 maintenance. That's why these blocks in Org mode literature are sometimes
15109 referred to as @samp{live code} blocks (as compared to the static text and
15110 documentation around it). Users can control how @samp{live} they want each
15111 block by tweaking the headers for compiling, execution, extraction.
15113 Org's @samp{src} code block type is one of many block types, such as quote,
15114 export, verse, latex, example, and verbatim. This section pertains to
15115 @samp{src} code blocks between @samp{#+BEGIN_SRC} and @samp{#+END_SRC}
15117 For editing @samp{src} code blocks, Org provides native Emacs major-modes.
15118 That leverages the latest Emacs features for that source code language mode.
15120 For exporting, Org can then extract @samp{src} code blocks into compilable
15121 source files (in a conversion process known as @dfn{tangling} in literate
15122 programming terminology).
15124 For publishing, Org's back-ends can handle the @samp{src} code blocks and the
15125 text for output to a variety of formats with native syntax highlighting.
15127 For executing the source code in the @samp{src} code blocks, Org provides
15128 facilities that glue the tasks of compiling, collecting the results of the
15129 execution, and inserting them back to the Org file. Besides text output,
15130 results may include links to other data types that Emacs can handle: audio,
15131 video, and graphics.
15133 An important feature of Org's execution of the @samp{src} code blocks is
15134 passing variables, functions, and results between @samp{src} blocks. Such
15135 interoperability uses a common syntax even if these @samp{src} blocks are in
15136 different source code languages. The integration extends to linking the
15137 debugger's error messages to the line in the @samp{src} code block in the Org
15138 file. That should partly explain why this functionality by the original
15139 contributors, Eric Schulte and Dan Davison, was called @samp{Org Babel}.
15141 In literate programming, the main appeal is code and documentation
15142 co-existing in one file. Org mode takes this several steps further. First
15143 by enabling execution, and then by inserting results of that execution back
15144 into the Org file. Along the way, Org provides extensive formatting
15145 features, including handling tables. Org handles multiple source code
15146 languages in one file, and provides a common syntax for passing variables,
15147 functions, and results between @samp{src} code blocks.
15149 Org mode fulfills the promise of easy verification and maintenance of
15150 publishing reproducible research by keeping all these in the same file: text,
15151 data, code, configuration settings of the execution environment, the results
15152 of the execution, and associated narratives, claims, references, and internal
15153 and external links.
15155 Details of Org's facilities for working with source code are shown next.
15158 * Structure of code blocks:: Code block syntax described
15159 * Editing source code:: Language major-mode editing
15160 * Exporting code blocks:: Export contents and/or results
15161 * Extracting source code:: Create pure source code files
15162 * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
15163 * Library of Babel:: Use and contribute to a library of useful code blocks
15164 * Languages:: List of supported code block languages
15165 * Header arguments:: Configure code block functionality
15166 * Results of evaluation:: How evaluation results are handled
15167 * Noweb reference syntax:: Literate programming in Org mode
15168 * Key bindings and useful functions:: Work quickly with code blocks
15169 * Batch execution:: Call functions from the command line
15173 @node Structure of code blocks
15174 @section Structure of code blocks
15175 @cindex code block, structure
15176 @cindex source code, block structure
15178 @cindex #+BEGIN_SRC
15180 Org offers two ways to structure source code in Org documents: in a
15181 @samp{src} block, and directly inline. Both specifications are shown below.
15183 A @samp{src} block conforms to this structure:
15187 #+BEGIN_SRC <language> <switches> <header arguments>
15192 Org mode's templates system (@pxref{Easy templates}) speeds up creating
15193 @samp{src} code blocks with just three keystrokes. Do not be put-off by
15194 having to remember the source block syntax. Org also works with other
15195 completion systems in Emacs, some of which predate Org and have custom
15196 domain-specific languages for defining templates. Regular use of templates
15197 reduces errors, increases accuracy, and maintains consistency.
15199 @cindex source code, inline
15200 An inline code block conforms to this structure:
15203 src_<language>@{<body>@}
15209 src_<language>[<header arguments>]@{<body>@}
15213 @item #+NAME: <name>
15214 Optional. Names the @samp{src} block so it can be called, like a function,
15215 from other @samp{src} blocks or inline blocks to evaluate or to capture the
15216 results. Code from other blocks, other files, and from table formulas
15217 (@pxref{The spreadsheet}) can use the name to reference a @samp{src} block.
15218 This naming serves the same purpose as naming Org tables. Org mode requires
15219 unique names. For duplicate names, Org mode's behavior is undefined.
15223 Mandatory. They mark the start and end of a block that Org requires. The
15224 @code{#+BEGIN_SRC} line takes additional arguments, as described next.
15225 @cindex begin block, end block
15227 Mandatory for live code blocks. It is the identifier of the source code
15228 language in the block. @xref{Languages}, for identifiers of supported
15230 @cindex source code, language
15232 Optional. Switches provide finer control of the code execution, export, and
15233 format (see the discussion of switches in @ref{Literal examples})
15234 @cindex source code, switches
15235 @item <header arguments>
15236 Optional. Heading arguments control many aspects of evaluation, export and
15237 tangling of code blocks (@pxref{Header arguments}). Using Org's properties
15238 feature, header arguments can be selectively applied to the entire buffer or
15239 specific sub-trees of the Org document.
15240 @item source code, header arguments
15242 Source code in the dialect of the specified language identifier.
15245 @node Editing source code
15246 @section Editing source code
15247 @cindex code block, editing
15248 @cindex source code, editing
15250 @vindex org-edit-src-auto-save-idle-delay
15251 @vindex org-edit-src-turn-on-auto-save
15253 @kbd{C-c '} for editing the current code block. It opens a new major-mode
15254 edit buffer containing the body of the @samp{src} code block, ready for any
15255 edits. @kbd{C-c '} again to close the buffer and return to the Org buffer.
15257 @key{C-x C-s} saves the buffer and updates the contents of the Org buffer.
15259 Set @code{org-edit-src-auto-save-idle-delay} to save the base buffer after
15260 a certain idle delay time.
15262 Set @code{org-edit-src-turn-on-auto-save} to auto-save this buffer into a
15263 separate file using @code{auto-save-mode}.
15265 @kbd{C-c '} to close the major-mode buffer and return back to the Org buffer.
15267 While editing the source code in the major-mode, the @code{org-src-mode}
15268 minor mode remains active. It provides these customization variables as
15269 described below. For even more variables, look in the customization
15270 group @code{org-edit-structure}.
15273 @item org-src-lang-modes
15274 If an Emacs major-mode named @code{<lang>-mode} exists, where @code{<lang>}
15275 is the language identifier from code block's header line, then the edit
15276 buffer uses that major-mode. Use this variable to arbitrarily map language
15277 identifiers to major modes.
15278 @item org-src-window-setup
15279 For specifying Emacs window arrangement when the new edit buffer is created.
15280 @item org-src-preserve-indentation
15281 @cindex indentation, in source blocks
15282 Default is @code{nil}. Source code is indented. This indentation applies
15283 during export or tangling, and depending on the context, may alter leading
15284 spaces and tabs. When non-@code{nil}, source code is aligned with the
15285 leftmost column. No lines are modified during export or tangling, which is
15286 very useful for white-space sensitive languages, such as Python.
15287 @item org-src-ask-before-returning-to-edit-buffer
15288 When @code{nil}, Org returns to the edit buffer without further prompts. The
15289 default prompts for a confirmation.
15292 Set @code{org-src-fontify-natively} to non-@code{nil} to turn on native code
15293 fontification in the @emph{Org} buffer. Fontification of @samp{src} code
15294 blocks can give visual separation of text and code on the display page. To
15295 further customize the appearance of @code{org-block} for specific languages,
15296 customize @code{org-src-block-faces}. The following example shades the
15297 background of regular blocks, and colors source blocks only for Python and
15298 Emacs-Lisp languages.
15301 (set-face-attribute 'org-block nil :background
15303 (face-attribute 'default :background) 3))
15305 (setq org-src-block-faces '(("emacs-lisp" (:background "#EEE2FF"))
15306 ("python" (:background "#E5FFB8"))))
15309 @node Exporting code blocks
15310 @section Exporting code blocks
15311 @cindex code block, exporting
15312 @cindex source code, exporting
15314 Org can flexibly export just the @emph{code} from the code blocks, just the
15315 @emph{results} of evaluation of the code block, @emph{both} the code and the
15316 results of the code block evaluation, or @emph{none}. Org defaults to
15317 exporting @emph{code} for most languages. For some languages, such as
15318 @code{ditaa}, Org defaults to @emph{results}. To export just the body of
15319 code blocks, @pxref{Literal examples}. To selectively export sub-trees of
15320 an Org document, @pxref{Exporting}.
15322 The @code{:exports} header arguments control exporting code blocks only and
15325 @subsubheading Header arguments:
15328 @cindex @code{:exports}, src header argument
15329 @item :exports code
15330 This is the default for most languages where the body of the code block is
15331 exported. See @ref{Literal examples} for more.
15332 @item :exports results
15333 On export, Org includes only the results and not the code block. After each
15334 evaluation, Org inserts the results after the end of code block in the Org
15335 buffer. By default, Org replaces any previous results. Org can also append
15337 @item :exports both
15338 Org exports both the code block and the results.
15339 @item :exports none
15340 Org does not export the code block nor the results.
15343 @vindex org-export-use-babel
15344 To stop Org from evaluating code blocks to speed exports, use the header
15345 argument @code{:eval never-export} (@pxref{eval}). To stop Org from
15346 evaluating code blocks for greater security, set the
15347 @code{org-export-use-babel} variable to @code{nil}, but understand that
15348 header arguments will have no effect.
15350 Turning off evaluation comes in handy when batch processing. For example,
15351 markup languages for wikis, which have a high risk of untrusted code.
15352 Stopping code block evaluation also stops evaluation of all header arguments
15353 of the code block. This may not be desirable in some circumstances. So
15354 during export, to allow evaluation of just the header arguments but not any
15355 code evaluation in the source block, set @code{:eval never-export}
15358 Org never evaluates code blocks in commented sub-trees when exporting
15359 (@pxref{Comment lines}). On the other hand, Org does evaluate code blocks in
15360 sub-trees excluded from export (@pxref{Export settings}).
15362 @node Extracting source code
15363 @section Extracting source code
15365 @cindex source code, extracting
15366 @cindex code block, extracting source code
15368 Extracting source code from code blocks is a basic task in literate
15369 programming. Org has features to make this easy. In literate programming
15370 parlance, documents on creation are @emph{woven} with code and documentation,
15371 and on export, the code is @emph{tangled} for execution by a computer. Org
15372 facilitates weaving and tangling for producing, maintaining, sharing, and
15373 exporting literate programming documents. Org provides extensive
15374 customization options for extracting source code.
15376 When Org tangles @samp{src} code blocks, it expands, merges, and transforms
15377 them. Then Org recomposes them into one or more separate files, as
15378 configured through the options. During this @emph{tangling} process, Org
15379 expands variables in the source code, and resolves any Noweb style references
15380 (@pxref{Noweb reference syntax}).
15382 @subsubheading Header arguments
15385 @cindex @code{:tangle}, src header argument
15387 By default, Org does not tangle the @samp{src} code block on export.
15389 Org extracts the contents of the code block for the tangled output. By
15390 default, the output file name is the same as the Org file but with a file
15391 extension derived from the language identifier of the @samp{src} code block.
15392 @item :tangle filename
15393 Override the default file name with this one for the tangled output.
15397 @subsubheading Functions
15400 @item org-babel-tangle
15401 Tangle the current file. Bound to @kbd{C-c C-v t}.
15403 With prefix argument only tangle the current @samp{src} code block.
15404 @item org-babel-tangle-file
15405 Choose a file to tangle. Bound to @kbd{C-c C-v f}.
15408 @subsubheading Hooks
15411 @item org-babel-post-tangle-hook
15412 This hook runs from within code tangled by @code{org-babel-tangle}, making it
15413 suitable for post-processing, compilation, and evaluation of code in the
15417 @subsubheading Jumping between code and Org
15419 Debuggers normally link errors and messages back to the source code. But for
15420 tangled files, we want to link back to the Org file, not to the tangled
15421 source file. To make this extra jump, Org uses
15422 @code{org-babel-tangle-jump-to-org} function with two additional source code
15423 block header arguments: One, set @code{padline} (@pxref{padline}) to true
15424 (the default setting). Two, set @code{comments} (@pxref{comments}) to
15425 @code{link}, which makes Org insert links to the Org file.
15427 @node Evaluating code blocks
15428 @section Evaluating code blocks
15429 @cindex code block, evaluating
15430 @cindex source code, evaluating
15433 A note about security: With code evaluation comes the risk of harm. Org
15434 safeguards by prompting for user's permission before executing any code in
15435 the source block. To customize this safeguard (or disable it) see @ref{Code
15436 evaluation security}.
15438 Org captures the results of the @samp{src} code block evaluation and inserts
15439 them in the Org file, right after the @samp{src} code block. The insertion
15440 point is after a newline and the @code{#+RESULTS} label. Org creates the
15441 @code{#+RESULTS} label if one is not already there.
15443 By default, Org enables only @code{emacs-lisp} @samp{src} code blocks for
15444 execution. See @ref{Languages} for identifiers to enable other languages.
15447 Org provides many ways to execute @samp{src} code blocks. @kbd{C-c C-c} or
15448 @kbd{C-c C-v e} with the point on a @samp{src} code block@footnote{The option
15449 @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used to remove code
15450 evaluation from the @kbd{C-c C-c} key binding.} calls the
15451 @code{org-babel-execute-src-block} function, which executes the code in the
15452 block, collects the results, and inserts them in the buffer.
15455 By calling a named code block@footnote{Actually, the constructs call_<name>()
15456 and src_<lang>@{@} are not evaluated when they appear in a keyword line
15457 (i.e. lines starting with @code{#+KEYWORD:}, @pxref{In-buffer settings}).}
15458 from an Org mode buffer or a table. Org can call the named @samp{src} code
15459 blocks from the current Org mode buffer or from the ``Library of Babel''
15460 (@pxref{Library of Babel}). Whether inline syntax or the @code{#+CALL:}
15461 syntax is used, the result is wrapped based on the variable
15462 @code{org-babel-inline-result-wrap}, which by default is set to @code{"=%s="}
15463 to produce verbatim text suitable for markup.
15465 The syntax for @code{#+CALL:} is
15468 #+CALL: <name>(<arguments>)
15469 #+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
15472 The syntax for inline named code block is
15475 ... call_<name>(<arguments>) ...
15476 ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
15481 This is the name of the code block to be evaluated (@pxref{Structure of
15484 Org passes arguments to the code block using standard function call syntax.
15485 For example, a @code{#+CALL:} line that passes @samp{4} to a code block named
15486 @code{double}, which declares the header argument @code{:var n=2}, would be
15487 written as @code{#+CALL: double(n=4)}. Note how this function call syntax is
15488 different from the header argument syntax.
15489 @item <inside header arguments>
15490 Org passes inside header arguments to the named @samp{src} code block using
15491 the header argument syntax. Inside header arguments apply to code block
15492 evaluation. For example, @code{[:results output]} collects results printed
15493 to @code{STDOUT} during code execution of that block. Note how this header
15494 argument syntax is different from the function call syntax.
15495 @item <end header arguments>
15496 End header arguments affect the results returned by the code block. For
15497 example, @code{:results html} wraps the results in a @code{BEGIN_EXPORT html}
15498 block before inserting the results in the Org buffer.
15500 For more examples of header arguments for @code{#+CALL:} lines,
15501 @pxref{Arguments in function calls}.
15504 @node Library of Babel
15505 @section Library of Babel
15506 @cindex babel, library of
15507 @cindex source code, library
15508 @cindex code block, library
15510 The ``Library of Babel'' is a collection of code blocks. Like a function
15511 library, these code blocks can be called from other Org files. A collection
15512 of useful code blocks is available on
15513 @uref{http://orgmode.org/worg/library-of-babel.html,Worg}. For remote code
15514 block evaluation syntax, @pxref{Evaluating code blocks}.
15517 For any user to add code to the library, first save the code in regular
15518 @samp{src} code blocks of an Org file, and then load the Org file with
15519 @code{org-babel-lob-ingest}, which is bound to @kbd{C-c C-v i}.
15523 @cindex babel, languages
15524 @cindex source code, languages
15525 @cindex code block, languages
15527 Org supports the following languages for the @samp{src} code blocks:
15529 @multitable @columnfractions 0.25 0.25 0.25 0.25
15530 @headitem @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}
15531 @item Asymptote @tab asymptote @tab Awk @tab awk
15532 @item C @tab C @tab C++ @tab C++
15533 @item Clojure @tab clojure @tab CSS @tab css
15534 @item D @tab d @tab ditaa @tab ditaa
15535 @item Graphviz @tab dot @tab Emacs Calc @tab calc
15536 @item Emacs Lisp @tab emacs-lisp @tab Fortran @tab fortran
15537 @item gnuplot @tab gnuplot @tab Haskell @tab haskell
15538 @item Java @tab java @tab Javascript @tab js
15539 @item LaTeX @tab latex @tab Ledger @tab ledger
15540 @item Lisp @tab lisp @tab Lilypond @tab lilypond
15541 @item Lua @tab lua @tab MATLAB @tab matlab
15542 @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
15543 @item Octave @tab octave @tab Org mode @tab org
15544 @item Oz @tab oz @tab Perl @tab perl
15545 @item Plantuml @tab plantuml @tab Processing.js @tab processing
15546 @item Python @tab python @tab R @tab R
15547 @item Ruby @tab ruby @tab Sass @tab sass
15548 @item Scheme @tab scheme @tab GNU Screen @tab screen
15549 @item Sed @tab sed @tab shell @tab sh
15550 @item SQL @tab sql @tab SQLite @tab sqlite
15551 @item Vala @tab vala
15554 Additional documentation for some languages are at
15555 @uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
15557 @vindex org-babel-load-languages
15558 By default, only @code{emacs-lisp} is enabled for evaluation. To enable or
15559 disable other languages, customize the @code{org-babel-load-languages}
15560 variable either through the Emacs customization interface, or by adding code
15561 to the init file as shown next:
15563 In this example, evaluation is disabled for @code{emacs-lisp}, and enabled
15567 (org-babel-do-load-languages
15568 'org-babel-load-languages
15569 '((emacs-lisp . nil)
15573 Note that this is not the only way to enable a language. Org also enables
15574 languages when loaded with @code{require} statement. For example, the
15575 following enables execution of @code{clojure} code blocks:
15578 (require 'ob-clojure)
15581 @node Header arguments
15582 @section Header arguments
15583 @cindex code block, header arguments
15584 @cindex source code, block header arguments
15586 Details of configuring header arguments are shown here.
15589 * Using header arguments:: Different ways to set header arguments
15590 * Specific header arguments:: List of header arguments
15593 @node Using header arguments
15594 @subsection Using header arguments
15596 Since header arguments can be set in several ways, Org prioritizes them in
15597 case of overlaps or conflicts by giving local settings a higher priority.
15598 Header values in function calls, for example, override header values from
15601 * System-wide header arguments:: Set globally, language-specific
15602 * Language-specific header arguments:: Set in the Org file's headers
15603 * Header arguments in Org mode properties:: Set in the Org file
15604 * Language-specific mode properties::
15605 * Code block specific header arguments:: The most commonly used method
15606 * Arguments in function calls:: The most specific level, takes highest priority
15610 @node System-wide header arguments
15611 @subsubheading System-wide header arguments
15612 @vindex org-babel-default-header-args
15613 System-wide values of header arguments can be specified by adapting the
15614 @code{org-babel-default-header-args} variable:
15616 @cindex @code{:session}, src header argument
15617 @cindex @code{:results}, src header argument
15618 @cindex @code{:exports}, src header argument
15619 @cindex @code{:cache}, src header argument
15620 @cindex @code{:noweb}, src header argument
15623 :results => "replace"
15629 This example sets @code{:noweb} header arguments to @code{yes}, which makes
15630 Org expand @code{:noweb} references by default.
15633 (setq org-babel-default-header-args
15634 (cons '(:noweb . "yes")
15635 (assq-delete-all :noweb org-babel-default-header-args)))
15638 @node Language-specific header arguments
15639 @subsubheading Language-specific header arguments
15640 Each language can have separate default header arguments by customizing the
15641 variable @code{org-babel-default-header-args:<lang>}, where @code{<lang>} is
15642 the name of the language. For details, see the language-specific online
15643 documentation at @uref{http://orgmode.org/worg/org-contrib/babel}.
15645 @node Header arguments in Org mode properties
15646 @subsubheading Header arguments in Org mode properties
15648 For header arguments applicable to the buffer, use @code{#+PROPERTY:} lines
15649 anywhere in the Org mode file (@pxref{Property syntax}).
15651 The following example sets only for @samp{R} code blocks to @code{session},
15652 making all the @samp{R} code blocks execute in the same session. Setting
15653 @code{results} to @code{silent} ignores the results of executions for all
15654 blocks, not just @samp{R} code blocks; no results inserted for any block.
15657 #+PROPERTY: header-args:R :session *R*
15658 #+PROPERTY: header-args :results silent
15661 @vindex org-use-property-inheritance
15662 Header arguments set through Org's property drawers (@pxref{Property syntax})
15663 apply at the sub-tree level on down. Since these property drawers can appear
15664 anywhere in the file hierarchy, Org uses outermost call or source block to
15665 resolve the values. Org ignores @code{org-use-property-inheritance} setting.
15667 In this example, @code{:cache} defaults to @code{yes} for all code blocks in
15668 the sub-tree starting with @samp{sample header}.
15673 :header-args: :cache yes
15678 @vindex org-babel-default-header-args
15679 Properties defined through @code{org-set-property} function, bound to
15680 @kbd{C-c C-x p}, apply to all active languages. They override properties set
15681 in @code{org-babel-default-header-args}.
15683 @node Language-specific mode properties
15684 @subsubheading Language-specific mode properties
15686 Language-specific header arguments are also read from properties
15687 @code{header-args:<lang>} where @code{<lang>} is the language identifier.
15693 :header-args:clojure: :session *clojure-1*
15694 :header-args:R: :session *R*
15698 :header-args:clojure: :session *clojure-2*
15702 would force separate sessions for clojure blocks in Heading and Subheading,
15703 but use the same session for all @samp{R} blocks. Blocks in Subheading
15704 inherit settings from Heading.
15706 @node Code block specific header arguments
15707 @subsubheading Code block specific header arguments
15709 Header arguments are most commonly set at the @samp{src} code block level, on
15710 the @code{#+BEGIN_SRC} line. Arguments set at this level take precedence
15711 over those set in the @code{org-babel-default-header-args} variable, and also
15712 those set as header properties.
15714 In the following example, setting @code{results} to @code{silent} makes it
15715 ignore results of the code execution. Setting @code{:exports} to @code{code}
15716 exports only the body of the @samp{src} code block to HTML or @LaTeX{}.:
15720 #+BEGIN_SRC haskell :results silent :exports code :var n=0
15722 fac n = n * fac (n-1)
15726 The same header arguments in an inline @samp{src} code block:
15729 src_haskell[:exports both]@{fac 5@}
15732 Code block header arguments can span multiple lines using @code{#+HEADER:} on
15733 each line. Note that Org currently accepts the plural spelling of
15734 @code{#+HEADER:} only as a convenience for backward-compatibility. It may be
15735 removed at some point.
15739 Multi-line header arguments on an unnamed @samp{src} code block:
15742 #+HEADER: :var data1=1
15743 #+BEGIN_SRC emacs-lisp :var data2=2
15744 (message "data1:%S, data2:%S" data1 data2)
15751 Multi-line header arguments on a named @samp{src} code block:
15754 #+NAME: named-block
15755 #+HEADER: :var data=2
15756 #+BEGIN_SRC emacs-lisp
15757 (message "data:%S" data)
15760 #+RESULTS: named-block
15764 @node Arguments in function calls
15765 @subsubheading Arguments in function calls
15767 Header arguments in function calls are the most specific and override all
15768 other settings in case of an overlap. They get the highest priority. Two
15769 @code{#+CALL:} examples are shown below. For the complete syntax of
15770 @code{#+CALL:} lines, see @ref{Evaluating code blocks}.
15772 In this example, @code{:exports results} header argument is applied to the
15773 evaluation of the @code{#+CALL:} line.
15776 #+CALL: factorial(n=5) :exports results
15779 In this example, @code{:session special} header argument is applied to the
15780 evaluation of @code{factorial} code block.
15783 #+CALL: factorial[:session special](n=5)
15786 @node Specific header arguments
15787 @subsection Specific header arguments
15788 Org comes with many header arguments common to all languages. New header
15789 arguments are added for specific languages as they become available for use
15790 in @samp{src} code blocks. A header argument is specified with an initial
15791 colon followed by the argument's name in lowercase. Common header arguments
15795 * var:: Pass arguments to @samp{src} code blocks
15796 * results:: Specify results type; how to collect
15797 * file:: Specify a path for output file
15798 * file-desc:: Specify a description for file results
15799 * file-ext:: Specify an extension for file output
15800 * output-dir:: Specify a directory for output file
15801 * dir:: Specify the default directory for code block execution
15802 * exports:: Specify exporting code, results, both, none
15803 * tangle:: Toggle tangling; or specify file name
15804 * mkdirp:: Toggle for parent directory creation for target files during tangling
15805 * comments:: Toggle insertion of comments in tangled code files
15806 * padline:: Control insertion of padding lines in tangled code files
15807 * no-expand:: Turn off variable assignment and noweb expansion during tangling
15808 * session:: Preserve the state of code evaluation
15809 * noweb:: Toggle expansion of noweb references
15810 * noweb-ref:: Specify block's noweb reference resolution target
15811 * noweb-sep:: String to separate noweb references
15812 * cache:: Avoid re-evaluating unchanged code blocks
15813 * sep:: Delimiter for writing tabular results outside Org
15814 * hlines:: Handle horizontal lines in tables
15815 * colnames:: Handle column names in tables
15816 * rownames:: Handle row names in tables
15817 * shebang:: Make tangled files executable
15818 * tangle-mode:: Set permission of tangled files
15819 * eval:: Limit evaluation of specific code blocks
15820 * wrap:: Mark source block evaluation results
15821 * post:: Post processing of results of code block evaluation
15822 * prologue:: Text to prepend to body of code block
15823 * epilogue:: Text to append to body of code block
15826 For language-specific header arguments, see @ref{Languages}.
15829 @subsubsection @code{:var}
15830 @cindex @code{:var}, src header argument
15831 Use @code{:var} for passing arguments to @samp{src} code blocks. The
15832 specifics of variables in @samp{src} code blocks vary by the source language
15833 and are covered in the language-specific documentation. The syntax for
15834 @code{:var}, however, is the same for all languages. This includes declaring
15835 a variable, and assigning a default value.
15837 Arguments can take values as literals, or as references, or even as Emacs
15838 Lisp code (@pxref{var, Emacs Lisp evaluation of variables}). References are
15839 names from the Org file from the lines @code{#+NAME:} or @code{#+RESULTS:}.
15840 References can also refer to tables, lists, @code{#+BEGIN_EXAMPLE} blocks,
15841 other types of @samp{src} code blocks, or the results of execution of
15842 @samp{src} code blocks.
15844 For better performance, Org can cache results of evaluations. But caching
15845 comes with severe limitations (@pxref{cache}).
15847 Argument values are indexed like arrays (@pxref{var, Indexable variable
15850 The following syntax is used to pass arguments to @samp{src} code blocks
15851 using the @code{:var} header argument.
15857 The @code{assign} is a literal value, such as a string @samp{"string"}, a
15858 number @samp{9}, a reference to a table, a list, a literal example, another
15859 code block (with or without arguments), or the results from evaluating a code
15862 Here are examples of passing values by reference:
15867 an Org mode table named with either a @code{#+NAME:} line
15870 #+NAME: example-table
15876 #+NAME: table-length
15877 #+BEGIN_SRC emacs-lisp :var table=example-table
15881 #+RESULTS: table-length
15886 a simple list named with a @code{#+NAME:} line. Note that only the top level
15887 list items are passed along. Nested list items are ignored.
15890 #+NAME: example-list
15896 #+BEGIN_SRC emacs-lisp :var x=example-list
15904 @item code block without arguments
15905 a code block name (from the example above), as assigned by @code{#+NAME:},
15906 optionally followed by parentheses
15909 #+BEGIN_SRC emacs-lisp :var length=table-length()
15917 @item code block with arguments
15918 a @samp{src} code block name, as assigned by @code{#+NAME:}, followed by
15919 parentheses and optional arguments passed within the parentheses following
15920 the @samp{src} code block name using standard function call syntax
15924 #+BEGIN_SRC emacs-lisp :var input=8
15932 #+BEGIN_SRC emacs-lisp :var input=double(input=2)
15940 @item literal example
15941 a literal example block named with a @code{#+NAME:} line
15944 #+NAME: literal-example
15950 #+NAME: read-literal-example
15951 #+BEGIN_SRC emacs-lisp :var x=literal-example
15952 (concatenate 'string x " for you.")
15955 #+RESULTS: read-literal-example
15956 : A literal example
15957 : on two lines for you.
15963 @subsubheading Indexable variable values
15964 Indexing variable values enables referencing portions of a variable. Indexes
15965 are 0 based with negative values counting backwards from the end. If an
15966 index is separated by @code{,}s then each subsequent section will index as
15967 the next dimension. Note that this indexing occurs @emph{before} other
15968 table-related header arguments are applied, such as @code{:hlines},
15969 @code{:colnames} and @code{:rownames}. The following example assigns the
15970 last cell of the first row the table @code{example-table} to the variable
15974 #+NAME: example-table
15980 #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
15988 Ranges of variable values can be referenced using two integers separated by a
15989 @code{:}, in which case the entire inclusive range is referenced. For
15990 example the following assigns the middle three rows of @code{example-table}
15994 #+NAME: example-table
16001 #+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
16011 To pick the entire range, use an empty index, or the single character
16012 @code{*}. @code{0:-1} does the same thing. Example below shows how to
16013 reference the first column only.
16016 #+NAME: example-table
16022 #+BEGIN_SRC emacs-lisp :var data=example-table[,0]
16030 Index referencing can be used for tables and code blocks. Index referencing
16031 can handle any number of dimensions. Commas delimit multiple dimensions, as
16036 #+BEGIN_SRC emacs-lisp
16037 '(((1 2 3) (4 5 6) (7 8 9))
16038 ((10 11 12) (13 14 15) (16 17 18))
16039 ((19 20 21) (22 23 24) (25 26 27)))
16042 #+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
16050 @subsubheading Emacs Lisp evaluation of variables
16052 Emacs lisp code can set the values for variables. To differentiate a value
16053 from lisp code, Org interprets any value starting with @code{(}, @code{[},
16054 @code{'} or @code{`} as Emacs Lisp code. The result of evaluating that code
16055 is then assigned to the value of that variable. The following example shows
16056 how to reliably query and pass file name of the Org mode buffer to a code
16057 block using headers. We need reliability here because the file's name could
16058 change once the code in the block starts executing.
16061 #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
16066 Note that values read from tables and lists will not be mistakenly evaluated
16067 as Emacs Lisp code, as illustrated in the following example.
16073 #+HEADER: :var data=table[0,0]
16083 @subsubsection @code{:results}
16084 @cindex @code{:results}, src header argument
16086 There are four classes of @code{:results} header arguments. Each @samp{src}
16087 code block can take only one option per class.
16091 @b{collection} for how the results should be collected from the @samp{src}
16094 @b{type} for which type of result the code block will return; affects how Org
16095 processes and inserts results in the Org buffer
16097 @b{format} for the result; affects how Org processes and inserts results in
16100 @b{handling} for processing results after evaluation of the @samp{src} code
16104 @subsubheading Collection
16105 Collection options specify the results. Choose one of the options; they are
16106 mutually exclusive.
16110 Default. Functional mode. Result is the value returned by the last
16111 statement in the @samp{src} code block. Languages like Python may require an
16112 explicit @code{return} statement in the @samp{src} code block. Usage
16113 example: @code{:results value}.
16114 @item @code{output}
16115 Scripting mode. Result is collected from STDOUT during execution of the code
16116 in the @samp{src} code block. Usage example: @code{:results output}.
16119 @subsubheading Type
16120 Type tells what result types to expect from the execution of the code
16121 block. Choose one of the options; they are mutually exclusive. The default
16122 behavior is to automatically determine the result type.
16125 @item @code{table}, @code{vector}
16126 Interpret the results as an Org table. If the result is a single value,
16127 create a table with one row and one column. Usage example: @code{:results
16130 Interpret the results as an Org list. If the result is a single value,
16131 create a list of one element.
16132 @item @code{scalar}, @code{verbatim}
16133 Interpret literally and insert as quoted text. Do not create a table. Usage
16134 example: @code{:results value verbatim}.
16136 Interpret as path to a file. Inserts a link to the file. Usage example:
16137 @code{:results value file}.
16140 @subsubheading Format
16141 Format pertains to the type of the result returned by the @samp{src} code
16142 block. Choose one of the options; they are mutually exclusive. The default
16143 follows from the type specified above.
16147 Interpreted as raw Org mode. Inserted directly into the buffer. Aligned if
16148 it is a table. Usage example: @code{:results value raw}.
16150 Results enclosed in a @code{BEGIN_SRC org} block. For comma-escape, either
16151 @kbd{TAB} in the block, or export the file. Usage example: @code{:results
16154 Results enclosed in a @code{BEGIN_EXPORT html} block. Usage example:
16155 @code{:results value html}.
16157 Results enclosed in a @code{BEGIN_EXPORT latex} block. Usage example:
16158 @code{:results value latex}.
16160 Result enclosed in a @samp{src} code block. Useful for parsing. Usage
16161 example: @code{:results value code}.
16163 Result converted to pretty-print source code. Enclosed in a @samp{src} code
16164 block. Languages supported: Emacs Lisp, Python, and Ruby. Usage example:
16165 @code{:results value pp}.
16166 @item @code{drawer}
16167 Result wrapped in a RESULTS drawer. Useful for containing @code{raw} or
16168 @code{org} results for later scripting and automated processing. Usage
16169 example: @code{:results value drawer}.
16172 @subsubheading Handling
16173 Handling options after collecting the results.
16176 @item @code{silent}
16177 Do not insert results in the Org mode buffer, but echo them in the
16178 minibuffer. Usage example: @code{:results output silent}.
16179 @item @code{replace}
16180 Default. Insert results in the Org buffer. Remove previous results. Usage
16181 example: @code{:results output replace}.
16182 @item @code{append}
16183 Append results to the Org buffer. Latest results are at the bottom. Does
16184 not remove previous results. Usage example: @code{:results output append}.
16185 @item @code{prepend}
16186 Prepend results to the Org buffer. Latest results are at the top. Does not
16187 remove previous results. Usage example: @code{:results output prepend}.
16191 @subsubsection @code{:file}
16192 @cindex @code{:file}, src header argument
16194 An external @code{:file} that saves the results of execution of the code
16195 block. The @code{:file} is either a file name or two strings, where the
16196 first is the file name and the second is the description. A link to the file
16197 is inserted. It uses an Org mode style @code{[[file:]]} link (@pxref{Link
16198 format}). Some languages, such as @samp{R}, @samp{dot}, @samp{ditaa}, and
16199 @samp{gnuplot}, automatically wrap the source code in additional boilerplate
16200 code. Such code wrapping helps recreate the output, especially graphics
16201 output, by executing just the @code{:file} contents.
16204 @subsubsection @code{:file-desc}
16206 A description of the results file. Org uses this description for the link
16207 (see @ref{Link format}) it inserts in the Org file. If the @code{:file-desc}
16208 has no value, Org will use file name for both the ``link'' and the
16209 ``description'' portion of the Org mode link.
16212 @subsubsection @code{:file-ext}
16213 @cindex @code{:file-ext}, src header argument
16215 File name extension for the output file. Org generates the file's complete
16216 name, and extension by combining @code{:file-ext}, @code{#+NAME:} of the
16217 source block, and the @ref{output-dir} header argument. To override this
16218 auto generated file name, use the @code{:file} header argument.
16221 @subsubsection @code{:output-dir}
16222 @cindex @code{:output-dir}, src header argument
16224 Specifies the @code{:output-dir} for the results file. Org accepts an
16225 absolute path (beginning with @code{/}) or a relative directory (without
16226 @code{/}). The value can be combined with @code{#+NAME:} of the source block
16227 and @ref{file} or @ref{file-ext} header arguments.
16230 @subsubsection @code{:dir} and remote execution
16231 @cindex @code{:dir}, src header argument
16233 While the @code{:file} header argument can be used to specify the path to the
16234 output file, @code{:dir} specifies the default directory during @samp{src}
16235 code block execution. If it is absent, then the directory associated with
16236 the current buffer is used. In other words, supplying @code{:dir path}
16237 temporarily has the same effect as changing the current directory with
16238 @kbd{M-x cd path RET}, and then not supplying @code{:dir}. Under the
16239 surface, @code{:dir} simply sets the value of the Emacs variable
16240 @code{default-directory}.
16242 When using @code{:dir}, relative paths (for example, @code{:file myfile.jpg}
16243 or @code{:file results/myfile.jpg}) become relative to the default directory.
16245 For example, to save the plot file in the @samp{Work} folder of the home
16246 directory (notice tilde is expanded):
16249 #+BEGIN_SRC R :file myplot.png :dir ~/Work
16250 matplot(matrix(rnorm(100), 10), type="l")
16254 @subsubheading Remote execution
16255 To evaluate the @samp{src} code block on a remote machine, supply a remote s
16256 directory name using @samp{Tramp} syntax. For example:
16259 #+BEGIN_SRC R :file plot.png :dir /scp:dand@@yakuba.princeton.edu:
16260 plot(1:10, main=system("hostname", intern=TRUE))
16264 Org first captures the text results as usual for insertion in the Org file.
16265 Then Org also inserts a link to the remote file, thanks to Emacs
16266 @samp{Tramp}. Org constructs the remote path to the file name from
16267 @code{:dir} and @code{default-directory}, as illustrated here:
16270 [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
16274 @subsubheading Some more warnings
16278 When @code{:dir} is used with @code{:session}, Org sets the starting
16279 directory for a new session. But Org will not alter the directory of an
16280 already existing session.
16282 Do not use @code{:dir} with @code{:exports results} or with @code{:exports
16283 both} to avoid Org inserting incorrect links to remote files. That is because
16284 Org does not expand @code{default directory} to avoid some underlying
16285 portability issues.
16289 @subsubsection @code{:exports}
16290 @cindex @code{:exports}, src header argument
16292 The @code{:exports} header argument is to specify if that part of the Org
16293 file is exported to, say, HTML or @LaTeX{} formats. Note that
16294 @code{:exports} affects only @samp{src} code blocks and not inline code.
16298 The default. The body of code is included into the exported file. Example:
16299 @code{:exports code}.
16300 @item @code{results}
16301 The results of evaluation of the code is included in the exported file.
16302 Example: @code{:exports results}.
16304 Both the code and results of evaluation are included in the exported file.
16305 Example: @code{:exports both}.
16307 Neither the code nor the results of evaluation is included in the exported
16308 file. Whether the code is evaluated at all depends on other
16309 options. Example: @code{:exports none}.
16313 @subsubsection @code{:tangle}
16314 @cindex @code{:tangle}, src header argument
16316 The @code{:tangle} header argument specifies if the @samp{src} code block is
16317 exported to source file(s).
16320 @item @code{tangle}
16321 Export the @samp{src} code block to source file. The file name for the
16322 source file is derived from the name of the Org file, and the file extension
16323 is derived from the source code language identifier. Example: @code{:tangle
16326 The default. Do not extract the code a source code file. Example:
16329 Export the @samp{src} code block to source file whose file name is derived
16330 from any string passed to the @code{:tangle} header argument. Org derives
16331 the file name as being relative to the directory of the Org file's location.
16332 Example: @code{:tangle path}.
16336 @subsubsection @code{:mkdirp}
16337 @cindex @code{:mkdirp}, src header argument
16339 The @code{:mkdirp} header argument creates parent directories for tangled
16340 files if the directory does not exist. @code{yes} enables directory creation
16341 and @code{no} inhibits directory creation.
16344 @subsubsection @code{:comments}
16345 @cindex @code{:comments}, src header argument
16346 Controls inserting comments into tangled files. These are above and beyond
16347 whatever comments may already exist in the @samp{src} code block.
16351 The default. Do not insert any extra comments during tangling.
16353 Wrap the @samp{src} code block in comments. Include links pointing back to
16354 the place in the Org file from where the code was tangled.
16356 Kept for backward compatibility; same as ``link''.
16358 Nearest headline text from Org file is inserted as comment. The exact text
16359 that is inserted is picked from the leading context of the source block.
16361 Includes both ``link'' and ``org'' comment options.
16363 Includes ``link'' comment option, expands noweb references, and wraps them in
16364 link comments inside the body of the @samp{src} code block.
16368 @subsubsection @code{:padline}
16369 @cindex @code{:padline}, src header argument
16370 Control insertion of newlines to pad @samp{src} code blocks in the tangled
16374 Default. Insert a newline before and after each @samp{src} code block in the
16377 Do not insert newlines to pad the tangled @samp{src} code blocks.
16381 @subsubsection @code{:no-expand}
16382 @cindex @code{:no-expand}, src header argument
16384 By default Org expands @samp{src} code blocks during tangling. The
16385 @code{:no-expand} header argument turns off such expansions. Note that one
16386 side-effect of expansion by @code{org-babel-expand-src-block} also assigns
16387 values to @code{:var} (@pxref{var}) variables. Expansions also replace Noweb
16388 references with their targets (@pxref{Noweb reference syntax}). Some of
16389 these expansions may cause premature assignment, hence this option. This
16390 option makes a difference only for tangling. It has no effect when exporting
16391 since @samp{src} code blocks for execution have to be expanded anyway.
16394 @subsubsection @code{:session}
16395 @cindex @code{:session}, src header argument
16397 The @code{:session} header argument is for running multiple source code
16398 blocks under one session. Org runs @samp{src} code blocks with the same
16399 session name in the same interpreter process.
16403 Default. Each @samp{src} code block gets a new interpreter process to
16404 execute. The process terminates once the block is evaluated.
16406 Any string besides @code{none} turns that string into the name of that
16407 session. For example, @code{:session mysession} names it @samp{mysession}.
16408 If @code{:session} has no argument, then the session name is derived from the
16409 source language identifier. Subsequent blocks with the same source code
16410 language use the same session. Depending on the language, state variables,
16411 code from other blocks, and the overall interpreted environment may be
16412 shared. Some interpreted languages support concurrent sessions when
16413 subsequent source code language blocks change session names.
16417 @subsubsection @code{:noweb}
16418 @cindex @code{:noweb}, src header argument
16420 The @code{:noweb} header argument controls expansion of Noweb syntax
16421 references (@pxref{Noweb reference syntax}). Expansions occur when source
16422 code blocks are evaluated, tangled, or exported.
16426 Default. No expansion of Noweb syntax references in the body of the code
16427 when evaluating, tangling, or exporting.
16429 Expansion of Noweb syntax references in the body of the @samp{src} code block
16430 when evaluating, tangling, or exporting.
16431 @item @code{tangle}
16432 Expansion of Noweb syntax references in the body of the @samp{src} code block
16433 when tangling. No expansion when evaluating or exporting.
16434 @item @code{no-export}
16435 Expansion of Noweb syntax references in the body of the @samp{src} code block
16436 when evaluating or tangling. No expansion when exporting.
16437 @item @code{strip-export}
16438 Expansion of Noweb syntax references in the body of the @samp{src} code block
16439 when expanding prior to evaluating or tangling. Removes Noweb syntax
16440 references when exporting.
16442 Expansion of Noweb syntax references in the body of the @samp{src} code block
16443 only before evaluating.
16446 @subsubheading Noweb prefix lines
16447 Noweb insertions now honor prefix characters that appear before the Noweb
16450 This behavior is illustrated in the following example. Because the
16451 @code{<<example>>} noweb reference appears behind the SQL comment syntax,
16452 each line of the expanded noweb reference will be commented.
16460 multi-line body of example
16464 this @samp{src} code block:
16467 #+BEGIN_SRC sql :noweb yes
16476 -- multi-line body of example
16479 Since this change will not affect noweb replacement text without newlines in
16480 them, inline noweb references are acceptable.
16482 This feature can also be used for management of indentation in exported code snippets.
16488 #+BEGIN_SRC python :exports none
16489 print('Do things when True')
16493 #+BEGIN_SRC python :exports none
16494 print('Do things when False')
16498 this @samp{src} code block:
16501 #+BEGIN_SRC python :noweb yes :results output
16513 print('Do things when True')
16515 print('Do things when False')
16521 Do things when True
16525 @subsubsection @code{:noweb-ref}
16526 @cindex @code{:noweb-ref}, src header argument
16528 When expanding Noweb style references, Org concatenates @samp{src} code
16529 blocks by matching the reference name to either the code block name or the
16530 @code{:noweb-ref} header argument.
16532 For simple concatenation, set this @code{:noweb-ref} header argument at the
16533 sub-tree or file level. In the example Org file shown next, the body of the
16534 source code in each block is extracted for concatenation to a pure code file
16538 #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
16541 * the mount point of the fullest disk
16543 :header-args: :noweb-ref fullest-disk
16546 ** query all mounted disks
16551 ** strip the header row
16556 ** output mount point of fullest disk
16558 |awk '@{if (u < +$5) @{u = +$5; m = $6@}@} END @{print m@}'
16563 @subsubsection @code{:noweb-sep}
16564 @cindex @code{:noweb-sep}, src header argument
16566 By default a newline separates each noweb reference concatenation. To change
16567 this newline separator, edit the @code{:noweb-sep} (@pxref{noweb-sep}) header
16571 @subsubsection @code{:cache}
16572 @cindex @code{:cache}, src header argument
16574 The @code{:cache} header argument is for caching results of evaluating code
16575 blocks. Caching results can avoid re-evaluating @samp{src} code blocks that
16576 have not changed since the previous run. To benefit from the cache and avoid
16577 redundant evaluations, the source block must have a result already present in
16578 the buffer, and neither the header arguments (including the value of
16579 @code{:var} references) nor the text of the block itself has changed since
16580 the result was last computed. This feature greatly helps avoid long-running
16581 calculations. For some edge cases, however, the cached results may not be
16584 The caching feature is best for when @samp{src} blocks are pure functions,
16585 that is functions that return the same value for the same input arguments
16586 (@pxref{var}), and that do not have side effects, and do not rely on external
16587 variables other than the input arguments. Functions that depend on a timer,
16588 file system objects, and random number generators are clearly unsuitable for
16591 A note of warning: when @code{:cache} is used for a @code{:session}, caching
16592 may cause unexpected results.
16594 When the caching mechanism tests for any source code changes, it will not
16595 expand Noweb style references (@pxref{Noweb reference syntax}). For reasons
16596 why, see @uref{http://thread.gmane.org/gmane.emacs.orgmode/79046}.
16598 The @code{:cache} header argument can have one of two values: @code{yes} or
16603 Default. No caching of results; @samp{src} code block evaluated every time.
16605 Whether to run the code or return the cached results is determined by
16606 comparing the SHA1 hash value of the combined @samp{src} code block and
16607 arguments passed to it. This hash value is packed on the @code{#+RESULTS:}
16608 line from previous evaluation. When hash values match, Org does not evaluate
16609 the @samp{src} code block. When hash values mismatch, Org evaluates the
16610 @samp{src} code block, inserts the results, recalculates the hash value, and
16611 updates @code{#+RESULTS:} line.
16614 In this example, both functions are cached. But @code{caller} runs only if
16615 the result from @code{random} has changed since the last run.
16619 #+BEGIN_SRC R :cache yes
16623 #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
16627 #+BEGIN_SRC emacs-lisp :var x=random :cache yes
16631 #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
16636 @subsubsection @code{:sep}
16637 @cindex @code{:sep}, src header argument
16639 The @code{:sep} header argument is the delimiter for saving results as tables
16640 to files (@pxref{file}) external to Org mode. Org defaults to tab delimited
16641 output. The function, @code{org-open-at-point}, which is bound to @kbd{C-c
16642 C-o}, also uses @code{:sep} for opening tabular results.
16645 @subsubsection @code{:hlines}
16646 @cindex @code{:hlines}, src header argument
16648 In-between each table row or below the table headings, sometimes results have
16649 horizontal lines, which are also known as hlines. The @code{:hlines}
16650 argument with the value @code{yes} accepts such lines. The default is
16655 Strips horizontal lines from the input table. For most code, this is
16656 desirable, or else those @code{hline} symbols raise unbound variable errors.
16658 The default is @code{:hlines no}. The example shows hlines removed from the
16670 #+BEGIN_SRC python :var tab=many-cols
16674 #+RESULTS: echo-table
16681 For @code{:hlines yes}, the example shows hlines unchanged.
16692 #+BEGIN_SRC python :var tab=many-cols :hlines yes
16696 #+RESULTS: echo-table
16706 @subsubsection @code{:colnames}
16707 @cindex @code{:colnames}, src header argument
16709 The @code{:colnames} header argument accepts @code{yes}, @code{no}, or
16710 @code{nil} values. The default value is @code{nil}, which is unassigned.
16711 But this header argument behaves differently depending on the source code
16716 If an input table has column names (because the second row is an hline), then
16717 Org removes the column names, processes the table, puts back the column
16718 names, and then writes the table to the results block.
16727 #+NAME: echo-table-again
16728 #+BEGIN_SRC python :var tab=less-cols
16729 return [[val + '*' for val in row] for row in tab]
16732 #+RESULTS: echo-table-again
16739 Note that column names have to accounted for when using variable indexing
16740 (@pxref{var, Indexable variable values}) because column names are not removed
16744 Do not pre-process column names.
16747 For an input table that has no hlines, process it like the @code{nil}
16748 value. That is, Org removes the column names, processes the table, puts back
16749 the column names, and then writes the table to the results block.
16753 @subsubsection @code{:rownames}
16754 @cindex @code{:rownames}, src header argument
16756 The @code{:rownames} header argument can take on values @code{yes} or
16757 @code{no} values. The default is @code{no}. Note that @code{emacs-lisp}
16758 code blocks ignore @code{:rownames} header argument because of the ease of
16759 table-handling in Emacs.
16763 Org will not pre-process row names.
16766 If an input table has row names, then Org removes the row names, processes
16767 the table, puts back the row names, and then writes the table to the results
16771 #+NAME: with-rownames
16772 | one | 1 | 2 | 3 | 4 | 5 |
16773 | two | 6 | 7 | 8 | 9 | 10 |
16775 #+NAME: echo-table-once-again
16776 #+BEGIN_SRC python :var tab=with-rownames :rownames yes
16777 return [[val + 10 for val in row] for row in tab]
16780 #+RESULTS: echo-table-once-again
16781 | one | 11 | 12 | 13 | 14 | 15 |
16782 | two | 16 | 17 | 18 | 19 | 20 |
16785 Note that row names have to accounted for when using variable indexing
16786 (@pxref{var, Indexable variable values}) because row names are not removed
16792 @subsubsection @code{:shebang}
16793 @cindex @code{:shebang}, src header argument
16795 This header argument can turn results into executable script files. By
16796 setting the @code{:shebang} header argument to a string value (for example,
16797 @code{:shebang "#!/bin/bash"}), Org inserts that string as the first line of
16798 the tangled file that the @samp{src} code block is extracted to. Org then
16799 turns on the tangled file's executable permission.
16802 @subsubsection @code{:tangle-mode}
16803 @cindex @code{:tangle-mode}, src header argument
16805 The @code{tangle-mode} header argument specifies what permissions to set for
16806 tangled files by @code{set-file-modes}. For example, to make read-only
16807 tangled file, use @code{:tangle-mode (identity #o444)}. To make it
16808 executable, use @code{:tangle-mode (identity #o755)}.
16810 On @samp{src} code blocks with @code{shebang} (@pxref{shebang}) header
16811 argument, Org will automatically set the tangled file to executable
16812 permissions. But this can be overridden with custom permissions using
16813 @code{tangle-mode} header argument.
16815 When multiple @samp{src} code blocks tangle to a single file with different
16816 and conflicting @code{tangle-mode} header arguments, Org's behavior is
16820 @subsubsection @code{:eval}
16821 @cindex @code{:eval}, src header argument
16822 The @code{:eval} header argument can limit evaluation of specific code
16823 blocks. It is useful for protection against evaluating untrusted @samp{src}
16824 code blocks by prompting for a confirmation. This protection is independent
16825 of the @code{org-confirm-babel-evaluate} setting.
16829 Org will never evaluate this @samp{src} code block.
16831 Org prompts the user for permission to evaluate this @samp{src} code block.
16832 @item never-export or no-export
16833 Org will not evaluate this @samp{src} code block when exporting, yet the user
16834 can evaluate this source block interactively.
16836 Org prompts the user for permission to export this @samp{src} code block.
16839 If @code{:eval} header argument is not set for a source block, then Org
16840 determines whether to evaluate from the @code{org-confirm-babel-evaluate}
16841 variable (@pxref{Code evaluation security}).
16844 @subsubsection @code{:wrap}
16845 @cindex @code{:wrap}, src header argument
16846 The @code{:wrap} header argument marks the results block by appending strings
16847 to @code{#+BEGIN_} and @code{#+END_}. If no string is specified, Org wraps
16848 the results in a @code{#+BEGIN/END_RESULTS} block.
16851 @subsubsection @code{:post}
16852 @cindex @code{:post}, src header argument
16853 The @code{:post} header argument is for post-processing results from
16854 @samp{src} block evaluation. When @code{:post} has any value, Org binds the
16855 results to @code{*this*} variable for easy passing to @ref{var} header
16856 argument specifications. That makes results available to other @samp{src}
16857 code blocks, or for even direct Emacs Lisp code execution.
16859 The following two examples illustrate @code{:post} header argument in action.
16860 The first one shows how to attach @code{#+ATTR_LATEX:} line using
16865 #+begin_src sh :var data="" :var width="\\textwidth" :results output
16866 echo "#+ATTR_LATEX: :width $width"
16870 #+header: :file /tmp/it.png
16871 #+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer
16881 #+ATTR_LATEX :width 5cm
16882 [[file:/tmp/it.png]]
16886 The second example shows use of @code{:colnames} in @code{:post} to pass
16887 data between @samp{src} code blocks.
16891 #+begin_src emacs-lisp :var tbl="" fmt="%.3f"
16892 (mapcar (lambda (row)
16893 (mapcar (lambda (cell)
16901 #+begin_src R :colnames yes :post round-tbl[:colnames yes](*this*)
16903 data.frame(foo=rnorm(1))
16913 @subsubsection @code{:prologue}
16914 @cindex @code{:prologue}, src header argument
16915 The @code{prologue} header argument is for appending to the top of the code
16916 block for execution. For example, a clear or reset code at the start of new
16917 execution of a @samp{src} code block. A @code{reset} for @samp{gnuplot}:
16918 @code{:prologue "reset"}. See also @ref{epilogue}.
16921 (add-to-list 'org-babel-default-header-args:gnuplot
16922 '((:prologue . "reset")))
16926 @subsubsection @code{:epilogue}
16927 @cindex @code{:epilogue}, src header argument
16928 The value of the @code{epilogue} header argument is for appending to the end
16929 of the code block for execution. See also @ref{prologue}.
16931 @node Results of evaluation
16932 @section Results of evaluation
16933 @cindex code block, results of evaluation
16934 @cindex source code, results of evaluation
16936 How Org handles results of a code block execution depends on many header
16937 arguments working together. Here is only a summary of these. For an
16938 enumeration of all the header arguments that affect results, see
16941 The primary determinant is the execution context. Is it in a @code{:session}
16942 or not? Orthogonal to that is if the expected result is a @code{:results
16943 value} or @code{:results output}, which is a concatenation of output from
16944 start to finish of the @samp{src} code block's evaluation.
16946 @multitable @columnfractions 0.26 0.33 0.41
16947 @item @tab @b{Non-session} @tab @b{Session}
16948 @item @code{:results value} @tab value of last expression @tab value of last expression
16949 @item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output
16952 For @code{:session} and non-session, the @code{:results value} turns the
16953 results into an Org mode table format. Single values are wrapped in a one
16954 dimensional vector. Rows and columns of a table are wrapped in a
16955 two-dimensional vector.
16957 @subsection Non-session
16958 @subsubsection @code{:results value}
16959 @cindex @code{:results}, src header argument
16960 Default. Org gets the value by wrapping the code in a function definition in
16961 the language of the @samp{src} block. That is why when using @code{:results
16962 value}, code should execute like a function and return a value. For
16963 languages like Python, an explicit @code{return} statement is mandatory when
16964 using @code{:results value}.
16966 This is one of four evaluation contexts where Org automatically wraps the
16967 code in a function definition.
16969 @subsubsection @code{:results output}
16970 @cindex @code{:results}, src header argument
16971 For @code{:results output}, the code is passed to an external process running
16972 the interpreter. Org returns the contents of the standard output stream as
16975 @subsection Session
16976 @subsubsection @code{:results value}
16977 @cindex @code{:results}, src header argument
16978 For @code{:results value} from a @code{:session}, Org passes the code to an
16979 interpreter running as an interactive Emacs inferior process. So only
16980 languages that provide interactive evaluation can have session support. Not
16981 all languages provide this support, such as @samp{C} and @samp{ditaa}. Even
16982 those that do support, such as @samp{Python} and @samp{Haskell}, they impose
16983 limitations on allowable language constructs that can run interactively. Org
16984 inherits those limitations for those @samp{src} code blocks running in a
16987 Org gets the value from the source code interpreter's last statement
16988 output. Org has to use language-specific methods to obtain the value. For
16989 example, from the variable @code{_} in @samp{Python} and @samp{Ruby}, and the
16990 value of @code{.Last.value} in @samp{R}).
16992 @subsubsection @code{:results output}
16993 @cindex @code{:results}, src header argument
16994 For @code{:results output}, Org passes the code to the interpreter running as
16995 an interactive Emacs inferior process. Org concatenates whatever text output
16996 emitted by the interpreter to return the collection as a result. Note that
16997 this collection is not the same as collected from @code{STDOUT} of a
16998 non-interactive interpreter running as an external process. Compare for
16999 example these two blocks:
17002 #+BEGIN_SRC python :results output
17013 In the above non-session mode, the ``2'' is not printed; so does not appear
17017 #+BEGIN_SRC python :results output :session
17029 In the above @code{:session} mode, the interactive interpreter receives and
17030 prints ``2''. Results show that.
17032 @node Noweb reference syntax
17033 @section Noweb reference syntax
17034 @cindex code block, noweb reference
17035 @cindex syntax, noweb
17036 @cindex source code, noweb reference
17038 Org supports named blocks in Noweb style syntax. For Noweb literate
17039 programming details, see @uref{http://www.cs.tufts.edu/~nr/noweb/}).
17042 <<code-block-name>>
17045 For the header argument @code{:noweb yes}, Org expands Noweb style references
17046 in the @samp{src} code block before evaluation.
17048 For the header argument @code{:noweb no}, Org does not expand Noweb style
17049 references in the @samp{src} code block before evaluation.
17051 The default is @code{:noweb no}. Org defaults to @code{:noweb no} so as not
17052 to cause errors in languages where Noweb syntax is ambiguous. Change Org's
17053 default to @code{:noweb yes} for languages where there is no risk of
17056 Org offers a more flexible way to resolve Noweb style references
17057 (@pxref{noweb-ref}).
17059 Org can include the @emph{results} of a code block rather than its body. To
17060 that effect, append parentheses, possibly including arguments, to the code
17061 block name, as show below.
17064 <<code-block-name(optional arguments)>>
17067 Note that when using the above approach to a code block's results, the code
17068 block name set by @code{#+NAME} keyword is required; the reference set by
17069 @code{:noweb-ref} will not work.
17071 Here is an example that demonstrates how the exported content changes when
17072 Noweb style references are used with parentheses versus without.
17078 #+BEGIN_SRC python :var num=0 :results output :exports none
17086 #+BEGIN_SRC text :noweb yes
17097 Below, a similar Noweb style reference is used, but with parentheses, while
17098 setting a variable @code{num} to 10:
17101 #+BEGIN_SRC text :noweb yes
17102 <<some-code(num=10)>>
17106 Note that now the expansion contains the @emph{results} of the code block
17107 @code{some-code}, not the code block itself:
17113 For faster tangling of large Org mode files, set
17114 @code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}.
17115 The speedup comes at the expense of not correctly resolving inherited values
17116 of the @code{:noweb-ref} header argument.
17119 @node Key bindings and useful functions
17120 @section Key bindings and useful functions
17121 @cindex code block, key bindings
17123 Many common Org mode key sequences are re-bound depending on the context.
17125 Active key bindings in code blocks:
17127 @multitable @columnfractions 0.25 0.75
17129 @item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block}
17131 @item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result}
17133 @item @kbd{M-@key{up}} @tab @code{org-babel-load-in-session}
17135 @item @kbd{M-@key{down}} @tab @code{org-babel-switch-to-session}
17138 Active key bindings in Org mode buffer:
17140 @multitable @columnfractions 0.5 0.5
17142 @kindex C-c C-v C-p
17143 @item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block}
17145 @kindex C-c C-v C-n
17146 @item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block}
17148 @kindex C-c C-v C-e
17149 @item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe}
17151 @kindex C-c C-v C-o
17152 @item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result}
17154 @kindex C-c C-v C-v
17155 @item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block}
17157 @kindex C-c C-v C-u
17158 @item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head}
17160 @kindex C-c C-v C-g
17161 @item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block}
17163 @kindex C-c C-v C-r
17164 @item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result}
17166 @kindex C-c C-v C-b
17167 @item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
17169 @kindex C-c C-v C-s
17170 @item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
17172 @kindex C-c C-v C-d
17173 @item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block}
17175 @kindex C-c C-v C-t
17176 @item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
17178 @kindex C-c C-v C-f
17179 @item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
17181 @kindex C-c C-v C-c
17182 @item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block}
17184 @kindex C-c C-v C-j
17185 @item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg}
17187 @kindex C-c C-v C-l
17188 @item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session}
17190 @kindex C-c C-v C-i
17191 @item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest}
17193 @kindex C-c C-v C-I
17194 @item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info}
17196 @kindex C-c C-v C-z
17197 @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}
17199 @kindex C-c C-v C-a
17200 @item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
17202 @kindex C-c C-v C-h
17203 @item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings}
17205 @kindex C-c C-v C-x
17206 @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}
17209 @c Extended key bindings when control key is kept pressed:
17211 @c @multitable @columnfractions 0.25 0.75
17212 @c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
17213 @c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
17214 @c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
17215 @c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
17216 @c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
17217 @c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
17218 @c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
17219 @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
17222 @node Batch execution
17223 @section Batch execution
17224 @cindex code block, batch execution
17225 @cindex source code, batch execution
17227 Org mode features, including working with source code facilities can be
17228 invoked from the command line. This enables building shell scripts for batch
17229 processing, running automated system tasks, and expanding Org mode's
17232 The sample script shows batch processing of multiple files using
17233 @code{org-babel-tangle}.
17237 # tangle files with org-mode
17239 emacs -Q --batch --eval "
17241 (require 'ob-tangle)
17242 (dolist (file command-line-args-left)
17243 (with-current-buffer (find-file-noselect file)
17244 (org-babel-tangle))))
17248 @node Miscellaneous
17249 @chapter Miscellaneous
17252 * Completion:: M-TAB guesses completions
17253 * Easy templates:: Quick insertion of structural elements
17254 * Speed keys:: Electric commands at the beginning of a headline
17255 * Code evaluation security:: Org mode files evaluate inline code
17256 * Customization:: Adapting Org to changing tastes
17257 * In-buffer settings:: Overview of the #+KEYWORDS
17258 * The very busy C-c C-c key:: When in doubt, press C-c C-c
17259 * Clean view:: Getting rid of leading stars in the outline
17260 * TTY keys:: Using Org on a tty
17261 * Interaction:: With other Emacs packages
17262 * org-crypt:: Encrypting Org files
17267 @section Completion
17268 @cindex completion, of @TeX{} symbols
17269 @cindex completion, of TODO keywords
17270 @cindex completion, of dictionary words
17271 @cindex completion, of option keywords
17272 @cindex completion, of tags
17273 @cindex completion, of property keys
17274 @cindex completion, of link abbreviations
17275 @cindex @TeX{} symbol completion
17276 @cindex TODO keywords completion
17277 @cindex dictionary word completion
17278 @cindex option keyword completion
17279 @cindex tag completion
17280 @cindex link abbreviations, completion of
17282 Org has in-buffer completions. Unlike minibuffer completions, which are
17283 useful for quick command interactions, Org's in-buffer completions are more
17284 suitable for content creation in Org documents. Type one or more letters and
17285 invoke the hot key to complete the text in-place. Depending on the context
17286 and the keys, Org will offer different types of completions. No minibuffer
17287 is involved. Such mode-specific hot keys have become an integral part of
17288 Emacs and Org provides several shortcuts.
17291 @kindex M-@key{TAB}
17293 Complete word at point
17296 At the beginning of a headline, complete TODO keywords.
17298 After @samp{\}, complete @TeX{} symbols supported by the exporter.
17300 After @samp{*}, complete headlines in the current buffer so that they
17301 can be used in search links like @samp{[[*find this headline]]}.
17303 After @samp{:} in a headline, complete tags. The list of tags is taken
17304 from the variable @code{org-tag-alist} (possibly set through the
17305 @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
17306 dynamically from all tags used in the current buffer.
17308 After @samp{:} and not in a headline, complete property keys. The list
17309 of keys is constructed dynamically from all keys used in the current
17312 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
17314 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
17315 file-specific @samp{OPTIONS}. After option keyword is complete, pressing
17316 @kbd{M-@key{TAB}} again will insert example settings for that option.
17318 After @samp{#+STARTUP: }, complete startup keywords.
17320 When the point is anywhere else, complete dictionary words using Ispell.
17323 If your desktop intercepts the combo @kbd{M-@key{TAB}} to switch windows, use
17324 @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} as an alternative or customize your
17328 @node Easy templates
17329 @section Easy templates
17330 @cindex template insertion
17331 @cindex insertion, of templates
17333 With just a few keystrokes, Org's easy templates inserts empty pairs of
17334 structural elements, such as @code{#+BEGIN_SRC} and @code{#+END_SRC}. Easy
17335 templates use an expansion mechanism, which is native to Org, in a process
17336 similar to @file{yasnippet} and other Emacs template expansion packages.
17338 @kbd{<} @kbd{s} @kbd{@key{TAB}} expands to a @samp{src} code block.
17340 @kbd{<} @kbd{l} @kbd{@key{TAB}} expands to:
17342 #+BEGIN_EXPORT latex
17346 Org comes with these pre-defined easy templates:
17348 @multitable @columnfractions 0.1 0.9
17349 @item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC}
17350 @item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
17351 @item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE}
17352 @item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE}
17353 @item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER}
17354 @item @kbd{C} @tab @code{#+BEGIN_COMMENT ... #+END_COMMENT}
17355 @item @kbd{l} @tab @code{#+BEGIN_EXPORT latex ... #+END_EXPORT}
17356 @item @kbd{L} @tab @code{#+LATEX:}
17357 @item @kbd{h} @tab @code{#+BEGIN_EXPORT html ... #+END_EXPORT}
17358 @item @kbd{H} @tab @code{#+HTML:}
17359 @item @kbd{a} @tab @code{#+BEGIN_EXPORT ascii ... #+END_EXPORT}
17360 @item @kbd{A} @tab @code{#+ASCII:}
17361 @item @kbd{i} @tab @code{#+INDEX:} line
17362 @item @kbd{I} @tab @code{#+INCLUDE:} line
17365 More templates can added by customizing the variable
17366 @code{org-structure-template-alist}, whose docstring has additional details.
17369 @section Speed keys
17372 Single keystrokes can execute custom commands in an Org file when the cursor
17373 is on a headline. Without the extra burden of a meta or modifier key, Speed
17374 Keys can speed navigation or execute custom commands. Besides faster
17375 navigation, Speed Keys may come in handy on small mobile devices that do not
17376 have full keyboards. Speed Keys may also work on TTY devices known for their
17377 problems when entering Emacs keychords.
17379 @vindex org-use-speed-commands
17380 By default, Org has Speed Keys disabled. To activate Speed Keys, set the
17381 variable @code{org-use-speed-commands} to a non-@code{nil} value. To trigger
17382 a Speed Key, the cursor must be at the beginning of an Org headline, before
17385 @vindex org-speed-commands-user
17386 @findex org-speed-command-help
17387 Org comes with a pre-defined list of Speed Keys. To add or modify Speed
17388 Keys, customize the variable, @code{org-speed-commands-user}. For more
17389 details, see the variable's docstring. With Speed Keys activated, @kbd{M-x
17390 org-speed-command-help}, or @kbd{?} when cursor is at the beginning of an Org
17391 headline, shows currently active Speed Keys, including the user-defined ones.
17394 @node Code evaluation security
17395 @section Code evaluation and security issues
17397 Unlike plain text, running code comes with risk. Each @samp{src} code block,
17398 in terms of risk, is equivalent to an executable file. Org therefore puts a
17399 few confirmation prompts by default. This is to alert the casual user from
17400 accidentally running untrusted code.
17402 For users who do not run code blocks or write code regularly, Org's default
17403 settings should suffice. However, some users may want to tweak the prompts
17404 for fewer interruptions. To weigh the risks of automatic execution of code
17405 blocks, here are some details about code evaluation.
17407 Org evaluates code in the following circumstances:
17410 @item Source code blocks
17411 Org evaluates @samp{src} code blocks in an Org file during export. Org also
17412 evaluates a @samp{src} code block with the @kbd{C-c C-c} key chord. Users
17413 exporting or running code blocks must load files only from trusted sources.
17414 Be wary of customizing variables that remove or alter default security
17417 @defopt org-confirm-babel-evaluate
17418 When @code{t}, Org prompts the user for confirmation before executing each
17419 code block. When @code{nil}, Org executes code blocks without prompting the
17420 user for confirmation. When this option is set to a custom function, Org
17421 invokes the function with these two arguments: the source code language and
17422 the body of the code block. The custom function must return either a
17423 @code{t} or @code{nil}, which determines if the user is prompted. Each
17424 source code language can be handled separately through this function
17428 For example, this function enables execution of @samp{ditaa} code +blocks
17432 (defun my-org-confirm-babel-evaluate (lang body)
17433 (not (string= lang "ditaa"))) ; don't ask for ditaa
17434 (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
17437 @item Following @code{shell} and @code{elisp} links
17438 Org has two link types that can also directly evaluate code (@pxref{External
17439 links}). Because such code is not visible, these links have a potential
17440 risk. Org therefore prompts the user when it encounters such links. The
17441 customization variables are:
17443 @defopt org-confirm-shell-link-function
17444 Function that prompts the user before executing a shell link.
17446 @defopt org-confirm-elisp-link-function
17447 Function that prompts the user before executing an Emacs Lisp link.
17450 @item Formulas in tables
17451 Org executes formulas in tables (@pxref{The spreadsheet}) either through the
17452 @emph{calc} or the @emph{Emacs Lisp} interpreters.
17455 @node Customization
17456 @section Customization
17457 @cindex customization
17458 @cindex options, for customization
17459 @cindex variables, for customization
17461 Org has more than 500 variables for customization. They can be accessed
17462 through the usual @kbd{M-x org-customize RET} command. Or through the Org
17463 menu, @code{Org->Customization->Browse Org Group}. Org also has per-file
17464 settings for some variables (@pxref{In-buffer settings}).
17466 @node In-buffer settings
17467 @section Summary of in-buffer settings
17468 @cindex in-buffer settings
17469 @cindex special keywords
17470 In-buffer settings start with @samp{#+}, followed by a keyword, a colon, and
17471 then a word for each setting. Org accepts multiple settings on the same
17472 line. Org also accepts multiple lines for a keyword. This manual describes
17473 these settings throughout. A summary follows here.
17475 @kbd{C-c C-c} activates any changes to the in-buffer settings. Closing and
17476 reopening the Org file in Emacs also activates the changes.
17478 @vindex org-archive-location
17480 @item #+ARCHIVE: %s_done::
17481 Sets the archive location of the agenda file. This location applies to the
17482 lines until the next @samp{#+ARCHIVE} line, if any, in the Org file. The
17483 first archive location in the Org file also applies to any entries before it.
17484 The corresponding variable is @code{org-archive-location}.
17486 Sets the category of the agenda file, which applies to the entire document.
17487 @item #+COLUMNS: %25ITEM ...
17488 @cindex property, COLUMNS
17489 Sets the default format for columns view. Org uses this format for column
17490 views where there is no @code{COLUMNS} property.
17491 @item #+CONSTANTS: name1=value1 ...
17492 @vindex org-table-formula-constants
17493 @vindex org-table-formula
17494 Set file-local values for constants that table formulas can use. This line
17495 sets the local variable @code{org-table-formula-constants-local}. The global
17496 version of this variable is @code{org-table-formula-constants}.
17497 @item #+FILETAGS: :tag1:tag2:tag3:
17498 Set tags that all entries in the file will inherit from here, including the
17500 @item #+LINK: linkword replace
17501 @vindex org-link-abbrev-alist
17502 Each line specifies one abbreviation for one link. Use multiple
17503 @code{#+LINK:} lines for more, @pxref{Link abbreviations}. The corresponding
17504 variable is @code{org-link-abbrev-alist}.
17505 @item #+PRIORITIES: highest lowest default
17506 @vindex org-highest-priority
17507 @vindex org-lowest-priority
17508 @vindex org-default-priority
17509 This line sets the limits and the default for the priorities. All three
17510 must be either letters A--Z or numbers 0--9. The highest priority must
17511 have a lower ASCII number than the lowest priority.
17512 @item #+PROPERTY: Property_Name Value
17513 This line sets a default inheritance value for entries in the current
17514 buffer, most useful for specifying the allowed values of a property.
17515 @cindex #+SETUPFILE
17516 @item #+SETUPFILE: file or URL
17517 The setup file or a URL pointing to such file is for additional in-buffer
17518 settings. Org loads this file and parses it for any settings in it only when
17519 Org opens the main file. If URL is specified, the contents are downloaded
17520 and stored in a temporary file cache. @kbd{C-c C-c} on the settings line
17521 will parse and load the file, and also reset the temporary file cache. Org
17522 also parses and loads the document during normal exporting process. Org
17523 parses the contents of this document as if it was included in the buffer. It
17524 can be another Org file. To visit the file (not a URL), @kbd{C-c '} while
17525 the cursor is on the line with the file name.
17528 Startup options Org uses when first visiting a file.
17530 The first set of options deals with the initial visibility of the outline
17531 tree. The corresponding variable for global default settings is
17532 @code{org-startup-folded} with a default value of @code{t}, which is the same
17533 as @code{overview}.
17535 @vindex org-startup-folded
17536 @cindex @code{overview}, STARTUP keyword
17537 @cindex @code{content}, STARTUP keyword
17538 @cindex @code{showall}, STARTUP keyword
17539 @cindex @code{showeverything}, STARTUP keyword
17541 overview @r{top-level headlines only}
17542 content @r{all headlines}
17543 showall @r{no folding of any entries}
17544 showeverything @r{show even drawer contents}
17547 @vindex org-startup-indented
17548 @cindex @code{indent}, STARTUP keyword
17549 @cindex @code{noindent}, STARTUP keyword
17550 Dynamic virtual indentation is controlled by the variable
17551 @code{org-startup-indented}
17553 indent @r{start with @code{org-indent-mode} turned on}
17554 noindent @r{start with @code{org-indent-mode} turned off}
17557 @vindex org-startup-align-all-tables
17558 Aligns tables consistently upon visiting a file; useful for restoring
17559 narrowed table columns. The corresponding variable is
17560 @code{org-startup-align-all-tables} with @code{nil} as default value.
17562 @cindex @code{align}, STARTUP keyword
17563 @cindex @code{noalign}, STARTUP keyword
17565 align @r{align all tables}
17566 noalign @r{don't align tables on startup}
17569 @vindex org-startup-with-inline-images
17570 Whether Org should automatically display inline images. The corresponding
17571 variable is @code{org-startup-with-inline-images}, with a default value
17572 @code{nil} to avoid delays when visiting a file.
17573 @cindex @code{inlineimages}, STARTUP keyword
17574 @cindex @code{noinlineimages}, STARTUP keyword
17576 inlineimages @r{show inline images}
17577 noinlineimages @r{don't show inline images on startup}
17580 @vindex org-startup-with-latex-preview
17581 Whether Org should automatically convert @LaTeX{} fragments to images. The
17582 variable @code{org-startup-with-latex-preview}, which controls this setting,
17583 is set to @code{nil} by default to avoid startup delays.
17584 @cindex @code{latexpreview}, STARTUP keyword
17585 @cindex @code{nolatexpreview}, STARTUP keyword
17587 latexpreview @r{preview @LaTeX{} fragments}
17588 nolatexpreview @r{don't preview @LaTeX{} fragments}
17591 @vindex org-log-done
17592 @vindex org-log-note-clock-out
17593 @vindex org-log-repeat
17594 Logging the closing and reopening of TODO items and clock intervals can be
17595 configured using these options (see variables @code{org-log-done},
17596 @code{org-log-note-clock-out} and @code{org-log-repeat})
17597 @cindex @code{logdone}, STARTUP keyword
17598 @cindex @code{lognotedone}, STARTUP keyword
17599 @cindex @code{nologdone}, STARTUP keyword
17600 @cindex @code{lognoteclock-out}, STARTUP keyword
17601 @cindex @code{nolognoteclock-out}, STARTUP keyword
17602 @cindex @code{logrepeat}, STARTUP keyword
17603 @cindex @code{lognoterepeat}, STARTUP keyword
17604 @cindex @code{nologrepeat}, STARTUP keyword
17605 @cindex @code{logreschedule}, STARTUP keyword
17606 @cindex @code{lognotereschedule}, STARTUP keyword
17607 @cindex @code{nologreschedule}, STARTUP keyword
17608 @cindex @code{logredeadline}, STARTUP keyword
17609 @cindex @code{lognoteredeadline}, STARTUP keyword
17610 @cindex @code{nologredeadline}, STARTUP keyword
17611 @cindex @code{logrefile}, STARTUP keyword
17612 @cindex @code{lognoterefile}, STARTUP keyword
17613 @cindex @code{nologrefile}, STARTUP keyword
17614 @cindex @code{logdrawer}, STARTUP keyword
17615 @cindex @code{nologdrawer}, STARTUP keyword
17616 @cindex @code{logstatesreversed}, STARTUP keyword
17617 @cindex @code{nologstatesreversed}, STARTUP keyword
17619 logdone @r{record a timestamp when an item is marked DONE}
17620 lognotedone @r{record timestamp and a note when DONE}
17621 nologdone @r{don't record when items are marked DONE}
17622 logrepeat @r{record a time when reinstating a repeating item}
17623 lognoterepeat @r{record a note when reinstating a repeating item}
17624 nologrepeat @r{do not record when reinstating repeating item}
17625 lognoteclock-out @r{record a note when clocking out}
17626 nolognoteclock-out @r{don't record a note when clocking out}
17627 logreschedule @r{record a timestamp when scheduling time changes}
17628 lognotereschedule @r{record a note when scheduling time changes}
17629 nologreschedule @r{do not record when a scheduling date changes}
17630 logredeadline @r{record a timestamp when deadline changes}
17631 lognoteredeadline @r{record a note when deadline changes}
17632 nologredeadline @r{do not record when a deadline date changes}
17633 logrefile @r{record a timestamp when refiling}
17634 lognoterefile @r{record a note when refiling}
17635 nologrefile @r{do not record when refiling}
17636 logdrawer @r{store log into drawer}
17637 nologdrawer @r{store log outside of drawer}
17638 logstatesreversed @r{reverse the order of states notes}
17639 nologstatesreversed @r{do not reverse the order of states notes}
17642 @vindex org-hide-leading-stars
17643 @vindex org-odd-levels-only
17644 These options hide leading stars in outline headings, and indent outlines.
17645 The corresponding variables are @code{org-hide-leading-stars} and
17646 @code{org-odd-levels-only}, both with a default setting of @code{nil}
17647 (meaning @code{showstars} and @code{oddeven}).
17648 @cindex @code{hidestars}, STARTUP keyword
17649 @cindex @code{showstars}, STARTUP keyword
17650 @cindex @code{odd}, STARTUP keyword
17651 @cindex @code{even}, STARTUP keyword
17653 hidestars @r{hide all stars on the headline except one.}
17654 showstars @r{show all stars on the headline}
17655 indent @r{virtual indents according to the outline level}
17656 noindent @r{no virtual indents}
17657 odd @r{show odd outline levels only (1,3,...)}
17658 oddeven @r{show all outline levels}
17661 @vindex org-put-time-stamp-overlays
17662 @vindex org-time-stamp-overlay-formats
17663 To turn on custom format overlays over timestamps (variables
17664 @code{org-put-time-stamp-overlays} and
17665 @code{org-time-stamp-overlay-formats}), use
17666 @cindex @code{customtime}, STARTUP keyword
17668 customtime @r{overlay custom time format}
17671 @vindex constants-unit-system
17672 The following options influence the table spreadsheet (variable
17673 @code{constants-unit-system}).
17674 @cindex @code{constcgs}, STARTUP keyword
17675 @cindex @code{constSI}, STARTUP keyword
17677 constcgs @r{@file{constants.el} should use the c-g-s unit system}
17678 constSI @r{@file{constants.el} should use the SI unit system}
17681 @vindex org-footnote-define-inline
17682 @vindex org-footnote-auto-label
17683 @vindex org-footnote-auto-adjust
17684 For footnote settings, use the following keywords. The corresponding
17685 variables are @code{org-footnote-define-inline},
17686 @code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.
17687 @cindex @code{fninline}, STARTUP keyword
17688 @cindex @code{nofninline}, STARTUP keyword
17689 @cindex @code{fnlocal}, STARTUP keyword
17690 @cindex @code{fnprompt}, STARTUP keyword
17691 @cindex @code{fnauto}, STARTUP keyword
17692 @cindex @code{fnconfirm}, STARTUP keyword
17693 @cindex @code{fnplain}, STARTUP keyword
17694 @cindex @code{fnadjust}, STARTUP keyword
17695 @cindex @code{nofnadjust}, STARTUP keyword
17697 fninline @r{define footnotes inline}
17698 fnnoinline @r{define footnotes in separate section}
17699 fnlocal @r{define footnotes near first reference, but not inline}
17700 fnprompt @r{prompt for footnote labels}
17701 fnauto @r{create @code{[fn:1]}-like labels automatically (default)}
17702 fnconfirm @r{offer automatic label for editing or confirmation}
17703 fnplain @r{create @code{[1]}-like labels automatically}
17704 fnadjust @r{automatically renumber and sort footnotes}
17705 nofnadjust @r{do not renumber and sort automatically}
17708 @cindex org-hide-block-startup
17709 To hide blocks on startup, use these keywords. The corresponding variable is
17710 @code{org-hide-block-startup}.
17711 @cindex @code{hideblocks}, STARTUP keyword
17712 @cindex @code{nohideblocks}, STARTUP keyword
17714 hideblocks @r{Hide all begin/end blocks on startup}
17715 nohideblocks @r{Do not hide blocks on startup}
17718 @cindex org-pretty-entities
17719 The display of entities as UTF-8 characters is governed by the variable
17720 @code{org-pretty-entities} and the keywords
17721 @cindex @code{entitiespretty}, STARTUP keyword
17722 @cindex @code{entitiesplain}, STARTUP keyword
17724 entitiespretty @r{Show entities as UTF-8 characters where possible}
17725 entitiesplain @r{Leave entities plain}
17728 @item #+TAGS: TAG1(c1) TAG2(c2)
17729 @vindex org-tag-alist
17730 These lines specify valid tags for this file. Org accepts multiple tags
17731 lines. Tags could correspond to the @emph{fast tag selection} keys. The
17732 corresponding variable is @code{org-tag-alist}.
17735 This line is for formulas for the table directly above. A table can have
17736 multiple @samp{#+TBLFM:} lines. On table recalculation, Org applies only the
17737 first @samp{#+TBLFM:} line. For details see @ref{Using multiple #+TBLFM
17738 lines} in @ref{Editing and debugging formulas}.
17739 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:,
17740 @itemx #+OPTIONS:, #+BIND:,
17741 @itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
17742 These lines provide settings for exporting files. For more details see
17743 @ref{Export settings}.
17744 @item #+TODO: #+SEQ_TODO: #+TYP_TODO:
17745 @vindex org-todo-keywords
17746 These lines set the TODO keywords and their significance to the current file.
17747 The corresponding variable is @code{org-todo-keywords}.
17750 @node The very busy C-c C-c key
17751 @section The very busy C-c C-c key
17753 @cindex C-c C-c, overview
17755 The @kbd{C-c C-c} key in Org serves many purposes depending on the context.
17756 It is probably the most over-worked, multi-purpose key combination in Org.
17757 Its uses are well-documented through out this manual, but here is a
17758 consolidated list for easy reference.
17762 If any highlights shown in the buffer from the creation of a sparse tree, or
17763 from clock display, remove such highlights.
17765 If the cursor is in one of the special @code{#+KEYWORD} lines, scan the
17766 buffer for these lines and update the information. Also reset the Org file
17767 cache used to temporary store the contents of URLs used as values for
17768 keywords like @code{#+SETUPFILE}.
17770 If the cursor is inside a table, realign the table. The table realigns even
17771 if automatic table editor is turned off.
17773 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
17776 If the current buffer is a capture buffer, close the note and file it. With
17777 a prefix argument, also jump to the target location after saving the note.
17779 If the cursor is on a @code{<<<target>>>}, update radio targets and
17780 corresponding links in this buffer.
17782 If the cursor is on a property line or at the start or end of a property
17783 drawer, offer property commands.
17785 If the cursor is at a footnote reference, go to the corresponding
17786 definition, and @emph{vice versa}.
17788 If the cursor is on a statistics cookie, update it.
17790 If the cursor is in a plain list item with a checkbox, toggle the status
17793 If the cursor is on a numbered item in a plain list, renumber the
17796 If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
17799 If the cursor is at a timestamp, fix the day name in the timestamp.
17803 @section A cleaner outline view
17804 @cindex hiding leading stars
17805 @cindex dynamic indentation
17806 @cindex odd-levels-only outlines
17807 @cindex clean outline view
17809 Org's default outline with stars and no indents can become too cluttered for
17810 short documents. For @emph{book-like} long documents, the effect is not as
17811 noticeable. Org provides an alternate stars and indentation scheme, as shown
17812 on the right in the following table. It uses only one star and indents text
17813 to line with the heading:
17817 * Top level headline | * Top level headline
17818 ** Second level | * Second level
17819 *** 3rd level | * 3rd level
17820 some text | some text
17821 *** 3rd level | * 3rd level
17822 more text | more text
17823 * Another top level headline | * Another top level headline
17829 To turn this mode on, use the minor mode, @code{org-indent-mode}. Text lines
17830 that are not headlines are prefixed with spaces to vertically align with the
17831 headline text@footnote{The @code{org-indent-mode} also sets the
17832 @code{wrap-prefix} correctly for indenting and wrapping long lines of
17833 headlines or text. This minor mode handles @code{visual-line-mode} and
17834 directly applied settings through @code{word-wrap}.}.
17836 To make more horizontal space, the headlines are shifted by two stars. This
17837 can be configured by the @code{org-indent-indentation-per-level} variable.
17838 Only one star on each headline is visible, the rest are masked with the same
17839 font color as the background. This font face can be configured with the
17840 @code{org-hide} variable.
17842 Note that turning on @code{org-indent-mode} sets
17843 @code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
17844 @code{nil}; @samp{2.} below shows how this works.
17846 To globally turn on @code{org-indent-mode} for all files, customize the
17847 variable @code{org-startup-indented}.
17849 To turn on indenting for individual files, use @code{#+STARTUP} option as
17856 Indent on startup makes Org use hard spaces to align text with headings as
17857 shown in examples below.
17861 @emph{Indentation of text below headlines}@*
17862 Indent text to align with the headline.
17866 more text, now indented
17869 @vindex org-adapt-indentation
17870 Org adapts indentations with paragraph filling, line wrapping, and structure
17871 editing@footnote{Also see the variable @code{org-adapt-indentation}.}.
17874 @vindex org-hide-leading-stars
17875 @emph{Hiding leading stars}@* Org can make leading stars invisible. For
17876 global preference, configure the variable @code{org-hide-leading-stars}. For
17877 per-file preference, use these file @code{#+STARTUP} options:
17880 #+STARTUP: hidestars
17881 #+STARTUP: showstars
17884 With stars hidden, the tree is shown as:
17888 * Top level headline
17896 @vindex org-hide @r{(face)}
17897 Because Org makes the font color same as the background color to hide to
17898 stars, sometimes @code{org-hide} face may need tweaking to get the effect
17899 right. For some black and white combinations, @code{grey90} on a white
17900 background might mask the stars better.
17903 @vindex org-odd-levels-only
17904 Using stars for only odd levels, 1, 3, 5, @dots{}, can also clean up the
17905 clutter. This removes two stars from each level@footnote{Because
17906 @samp{LEVEL=2} has 3 stars, @samp{LEVEL=3} has 4 stars, and so on}. For Org
17907 to properly handle this cleaner structure during edits and exports, configure
17908 the variable @code{org-odd-levels-only}. To set this per-file, use either
17909 one of the following lines:
17916 To switch between single and double stars layouts, use @kbd{M-x
17917 org-convert-to-odd-levels RET} and @kbd{M-x org-convert-to-oddeven-levels}.
17921 @section Using Org on a tty
17922 @cindex tty key bindings
17924 Org provides alternative key bindings for TTY and modern mobile devices that
17925 cannot handle cursor keys and complex modifier key chords. Some of these
17926 workarounds may be more cumbersome than necessary. Users should look into
17927 customizing these further based on their usage needs. For example, the
17928 normal @kbd{S-@key{cursor}} for editing timestamp might be better with
17931 @multitable @columnfractions 0.15 0.2 0.1 0.2
17932 @item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
17933 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab
17934 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
17935 @item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab
17936 @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
17937 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab
17938 @item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
17939 @item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab
17940 @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
17941 @item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab
17942 @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab
17943 @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
17944 @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab
17945 @item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab
17946 @item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab
17947 @item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab
17948 @item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab
17949 @item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab
17950 @item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab
17955 @section Interaction with other packages
17956 @cindex packages, interaction with other
17957 Org's compatibility and the level of interaction with other Emacs packages
17958 are documented here.
17962 * Cooperation:: Packages Org cooperates with
17963 * Conflicts:: Packages that lead to conflicts
17967 @subsection Packages that Org cooperates with
17970 @cindex @file{calc.el}
17971 @cindex Gillespie, Dave
17972 @item @file{calc.el} by Dave Gillespie
17973 Org uses the Calc package for tables to implement spreadsheet functionality
17974 (@pxref{The spreadsheet}). Org also uses Calc for embedded calculations.
17975 @xref{Embedded Mode, , Embedded Mode, calc, GNU Emacs Calc Manual}.
17976 @item @file{constants.el} by Carsten Dominik
17977 @cindex @file{constants.el}
17978 @cindex Dominik, Carsten
17979 @vindex org-table-formula-constants
17980 Org can use names for constants in formulas in tables. Org can also use
17981 calculation suffixes for units, such as @samp{M} for @samp{Mega}. For a
17982 standard collection of such constants, install the @file{constants} package.
17983 Install version 2.0 of this package, available at
17984 @url{https://staff.fnwi.uva.nl/c.dominik/Tools/}. Org checks if the function
17985 @code{constants-get} has been autoloaded. Installation instructions are in
17986 the file, @file{constants.el}.
17987 @item @file{cdlatex.el} by Carsten Dominik
17988 @cindex @file{cdlatex.el}
17989 @cindex Dominik, Carsten
17990 Org mode can use CD@LaTeX{} package to efficiently enter @LaTeX{} fragments
17991 into Org files (@pxref{CDLaTeX mode}).
17992 @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
17993 @cindex @file{imenu.el}
17994 Imenu creates dynamic menus based on an index of items in a file. Org mode
17995 supports Imenu menus. Enable it with a mode hook as follows:
17997 (add-hook 'org-mode-hook
17998 (lambda () (imenu-add-to-menubar "Imenu")))
18000 @vindex org-imenu-depth
18001 By default the Imenu index is two levels deep. Change the index depth using
18002 thes variable, @code{org-imenu-depth}.
18003 @item @file{speedbar.el} by Eric M. Ludlam
18004 @cindex @file{speedbar.el}
18005 @cindex Ludlam, Eric M.
18006 Speedbar package creates a special Emacs frame for displaying files and index
18007 items in files. Org mode supports Speedbar; users can drill into Org files
18008 directly from the Speedbar. The @kbd{<} in the Speedbar frame tweaks the
18009 agenda commands to that file or to a subtree.
18010 @cindex @file{table.el}
18011 @item @file{table.el} by Takaaki Ota
18013 @cindex table editor, @file{table.el}
18014 @cindex @file{table.el}
18015 @cindex Ota, Takaaki
18017 Complex ASCII tables with automatic line wrapping, column- and row-spanning,
18018 and alignment can be created using the Emacs table package by Takaaki Ota.
18019 Org mode recognizes such tables and export them properly. @kbd{C-c '} to
18020 edit these tables in a special buffer, much like Org's @samp{src} code
18021 blocks. Because of interference with other Org mode functionality, Takaaki
18022 Ota tables cannot be edited directly in the Org buffer.
18024 @orgcmd{C-c ',org-edit-special}
18025 Edit a @file{table.el} table. Works when the cursor is in a table.el table.
18027 @orgcmd{C-c ~,org-table-create-with-table.el}
18028 Insert a @file{table.el} table. If there is already a table at point, this
18029 command converts it between the @file{table.el} format and the Org mode
18030 format. See the documentation string of the command @code{org-convert-table}
18036 @subsection Packages that conflict with Org mode
18040 @cindex @code{shift-selection-mode}
18041 @vindex org-support-shift-select
18042 In Emacs, @code{shift-selection-mode} combines cursor motions with shift key
18043 to enlarge regions. Emacs sets this mode by default. This conflicts with
18044 Org's use of @kbd{S-@key{cursor}} commands to change timestamps, TODO
18045 keywords, priorities, and item bullet types, etc. Since @kbd{S-@key{cursor}}
18046 commands outside of specific contexts don't do anything, Org offers the
18047 variable @code{org-support-shift-select} for customization. Org mode
18048 accommodates shift selection by (i) making it available outside of the
18049 special contexts where special commands apply, and (ii) extending an
18050 existing active region even if the cursor moves across a special context.
18052 @item @file{CUA.el} by Kim. F. Storm
18053 @cindex @file{CUA.el}
18054 @cindex Storm, Kim. F.
18055 @vindex org-replace-disputed-keys
18056 Org key bindings conflict with @kbd{S-<cursor>} keys used by CUA mode. For
18057 Org to relinquish these bindings to CUA mode, configure the variable
18058 @code{org-replace-disputed-keys}. When set, Org moves the following key
18059 bindings in Org files, and in the agenda buffer (but not during date
18063 S-UP @result{} M-p S-DOWN @result{} M-n
18064 S-LEFT @result{} M-- S-RIGHT @result{} M-+
18065 C-S-LEFT @result{} M-S-- C-S-RIGHT @result{} M-S-+
18068 @vindex org-disputed-keys
18069 Yes, these are unfortunately more difficult to remember. To define a
18070 different replacement keys, look at the variable @code{org-disputed-keys}.
18072 @item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org}
18073 @cindex @file{ecomplete.el}
18075 Ecomplete provides ``electric'' address completion in address header
18076 lines in message buffers. Sadly Orgtbl mode cuts ecompletes power
18077 supply: No completion happens when Orgtbl mode is enabled in message
18078 buffers while entering text in address header lines. If one wants to
18079 use ecomplete one should @emph{not} follow the advice to automagically
18080 turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but
18081 instead---after filling in the message headers---turn on Orgtbl mode
18082 manually when needed in the messages body.
18084 @item @file{filladapt.el} by Kyle Jones
18085 @cindex @file{filladapt.el}
18087 Org mode tries to do the right thing when filling paragraphs, list items and
18088 other elements. Many users reported problems using both @file{filladapt.el}
18089 and Org mode, so a safe thing to do is to disable filladapt like this:
18092 (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
18095 @item @file{yasnippet.el}
18096 @cindex @file{yasnippet.el}
18097 The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of
18098 @code{"\t"}) overrules YASnippet's access to this key. The following code
18099 fixed this problem:
18102 (add-hook 'org-mode-hook
18104 (setq-local yas/trigger-key [tab])
18105 (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
18108 The latest version of yasnippet doesn't play well with Org mode. If the
18109 above code does not fix the conflict, first define the following function:
18112 (defun yas/org-very-safe-expand ()
18113 (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
18116 Then tell Org mode to use that function:
18119 (add-hook 'org-mode-hook
18121 (make-variable-buffer-local 'yas/trigger-key)
18122 (setq yas/trigger-key [tab])
18123 (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
18124 (define-key yas/keymap [tab] 'yas/next-field)))
18127 @item @file{windmove.el} by Hovav Shacham
18128 @cindex @file{windmove.el}
18129 This package also uses the @kbd{S-<cursor>} keys, so everything written
18130 in the paragraph above about CUA mode also applies here. If you want make
18131 the windmove function active in locations where Org mode does not have
18132 special functionality on @kbd{S-@key{cursor}}, add this to your
18136 ;; Make windmove work in org-mode:
18137 (add-hook 'org-shiftup-final-hook 'windmove-up)
18138 (add-hook 'org-shiftleft-final-hook 'windmove-left)
18139 (add-hook 'org-shiftdown-final-hook 'windmove-down)
18140 (add-hook 'org-shiftright-final-hook 'windmove-right)
18143 @item @file{viper.el} by Michael Kifer
18144 @cindex @file{viper.el}
18146 Viper uses @kbd{C-c /} and therefore makes this key not access the
18147 corresponding Org mode command @code{org-sparse-tree}. You need to find
18148 another key for this command, or override the key in
18149 @code{viper-vi-global-user-map} with
18152 (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
18160 @section org-crypt.el
18161 @cindex @file{org-crypt.el}
18162 @cindex @code{org-decrypt-entry}
18164 Org crypt encrypts the text of an Org entry, but not the headline, or
18165 properties. Org crypt uses the Emacs EasyPG library to encrypt and decrypt.
18167 Any text below a headline that has a @samp{:crypt:} tag will be automatically
18168 be encrypted when the file is saved. To use a different tag, customize the
18169 @code{org-crypt-tag-matcher} variable.
18171 Suggested Org crypt settings in Emacs init file:
18174 (require 'org-crypt)
18175 (org-crypt-use-before-save-magic)
18176 (setq org-tags-exclude-from-inheritance (quote ("crypt")))
18178 (setq org-crypt-key nil)
18179 ;; GPG key to use for encryption
18180 ;; Either the Key ID or set to nil to use symmetric encryption.
18182 (setq auto-save-default nil)
18183 ;; Auto-saving does not cooperate with org-crypt.el: so you need
18184 ;; to turn it off if you plan to use org-crypt.el quite often.
18185 ;; Otherwise, you'll get an (annoying) message each time you
18188 ;; To turn it off only locally, you can insert this:
18190 ;; # -*- buffer-auto-save-file-name: nil; -*-
18193 Excluding the crypt tag from inheritance prevents encrypting previously
18200 This appendix covers some areas where users can extend the functionality of
18204 * Hooks:: How to reach into Org's internals
18205 * Add-on packages:: Available extensions
18206 * Adding hyperlink types:: New custom link types
18207 * Adding export back-ends:: How to write new export back-ends
18208 * Context-sensitive commands:: How to add functionality to such commands
18209 * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
18210 * Dynamic blocks:: Automatically filled blocks
18211 * Special agenda views:: Customized views
18212 * Speeding up your agendas:: Tips on how to speed up your agendas
18213 * Extracting agenda information:: Post-processing of agenda information
18214 * Using the property API:: Writing programs that use entry properties
18215 * Using the mapping API:: Mapping over all or selected entries
18222 Org has a large number of hook variables for adding functionality. This
18223 appendix illustrates using a few. A complete list of hooks with
18224 documentation is maintained by the Worg project at
18225 @uref{http://orgmode.org/worg/doc.html#hooks}.
18227 @node Add-on packages
18228 @section Add-on packages
18229 @cindex add-on packages
18231 Various authors wrote a large number of add-on packages for Org.
18233 These packages are not part of Emacs, but they are distributed as contributed
18234 packages with the separate release available at @uref{http://orgmode.org}.
18235 See the @file{contrib/README} file in the source code directory for a list of
18236 contributed files. Worg page with more information is at:
18237 @uref{http://orgmode.org/worg/org-contrib/}.
18239 @node Adding hyperlink types
18240 @section Adding hyperlink types
18241 @cindex hyperlinks, adding new types
18243 Org has many built-in hyperlink types (@pxref{Hyperlinks}), and an interface
18244 for adding new link types. The example file, @file{org-man.el}, shows the
18245 process of adding Org links to Unix man pages, which look like this:
18246 @samp{[[man:printf][The printf manpage]]}:
18249 ;;; org-man.el - Support for links to manpages in Org
18253 (org-add-link-type "man" 'org-man-open)
18254 (add-hook 'org-store-link-functions 'org-man-store-link)
18256 (defcustom org-man-command 'man
18257 "The Emacs command to be used to display a man page."
18259 :type '(choice (const man) (const woman)))
18261 (defun org-man-open (path)
18262 "Visit the manpage on PATH.
18263 PATH should be a topic that can be thrown at the man command."
18264 (funcall org-man-command path))
18266 (defun org-man-store-link ()
18267 "Store a link to a manpage."
18268 (when (memq major-mode '(Man-mode woman-mode))
18269 ;; This is a man page, we do make this link
18270 (let* ((page (org-man-get-page-name))
18271 (link (concat "man:" page))
18272 (description (format "Manpage for %s" page)))
18273 (org-store-link-props
18276 :description description))))
18278 (defun org-man-get-page-name ()
18279 "Extract the page name from the buffer name."
18280 ;; This works for both `Man-mode' and `woman-mode'.
18281 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
18282 (match-string 1 (buffer-name))
18283 (error "Cannot create link to this man page")))
18287 ;;; org-man.el ends here
18291 To activate links to man pages in Org, enter this in the init file:
18298 A review of @file{org-man.el}:
18301 First, @code{(require 'org)} ensures @file{org.el} is loaded.
18303 The @code{org-add-link-type} defines a new link type with @samp{man} prefix.
18304 The call contains the function to call that follows the link type.
18306 @vindex org-store-link-functions
18307 The next line adds a function to @code{org-store-link-functions} that records
18308 a useful link with the command @kbd{C-c l} in a buffer displaying a man page.
18311 The rest of the file defines necessary variables and functions. First is the
18312 customization variable @code{org-man-command}. It has two options,
18313 @code{man} and @code{woman}. Next is a function whose argument is the link
18314 path, which for man pages is the topic of the man command. To follow the
18315 link, the function calls the @code{org-man-command} to display the man page.
18318 @kbd{C-c l} constructs and stores the link.
18320 @kbd{C-c l} calls the function @code{org-man-store-link}, which first checks
18321 if the @code{major-mode} is appropriate. If check fails, the function
18322 returns @code{nil}. Otherwise the function makes a link string by combining
18323 the @samp{man:} prefix with the man topic. The function then calls
18324 @code{org-store-link-props} with @code{:type} and @code{:link} properties. A
18325 @code{:description} property is an optional string that is displayed when the
18326 function inserts the link in the Org buffer.
18328 @kbd{C-c C-l} inserts the stored link.
18330 To define new link types, define a function that implements completion
18331 support with @kbd{C-c C-l}. This function should not accept any arguments
18332 but return the appropriate prefix and complete link string.
18334 @node Adding export back-ends
18335 @section Adding export back-ends
18336 @cindex Export, writing back-ends
18338 Org's export engine makes it easy for writing new back-ends. The framework
18339 on which the engine was built makes it easy to derive new back-ends from
18342 The two main entry points to the export engine are:
18343 @code{org-export-define-backend} and
18344 @code{org-export-define-derived-backend}. To grok these functions, see
18345 @file{ox-latex.el} for an example of defining a new back-end from scratch,
18346 and @file{ox-beamer.el} for an example of deriving from an existing engine.
18348 For creating a new back-end from scratch, first set its name as a symbol in
18349 an alist consisting of elements and export functions. To make the back-end
18350 visible to the export dispatcher, set @code{:menu-entry} keyword. For export
18351 options specific to this back-end, set the @code{:options-alist}.
18353 For creating a new back-end from an existing one, set @code{:translate-alist}
18354 to an alist of export functions. This alist replaces the parent back-end
18357 For complete documentation, see
18358 @url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
18359 Reference on Worg}.
18361 @node Context-sensitive commands
18362 @section Context-sensitive commands
18363 @cindex context-sensitive commands, hooks
18364 @cindex add-ons, context-sensitive commands
18365 @vindex org-ctrl-c-ctrl-c-hook
18367 Org has facilities for building context sensitive commands. Authors of Org
18368 add-ons can tap into this functionality.
18370 Some Org commands change depending on the context. The most important
18371 example of this behavior is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c
18372 key}). Other examples are @kbd{M-cursor} and @kbd{M-S-cursor}.
18374 These context sensitive commands work by providing a function that detects
18375 special context for that add-on and executes functionality appropriate for
18378 @node Tables in arbitrary syntax
18379 @section Tables and lists in arbitrary syntax
18380 @cindex tables, in other modes
18381 @cindex lists, in other modes
18382 @cindex Orgtbl mode
18384 Because of Org's success in handling tables with Orgtbl, a frequently asked
18385 feature is to Org's usability functions to other table formats native to
18386 other modem's, such as @LaTeX{}. This would be hard to do in a general way
18387 without complicated customization nightmares. Moreover, that would take Org
18388 away from its simplicity roots that Orgtbl has proven. There is, however, an
18389 alternate approach to accomplishing the same.
18391 This approach involves implementing a custom @emph{translate} function that
18392 operates on a native Org @emph{source table} to produce a table in another
18393 format. This strategy would keep the excellently working Orgtbl simple and
18394 isolate complications, if any, confined to the translate function. To add
18395 more alien table formats, we just add more translate functions. Also the
18396 burden of developing custom translate functions for new table formats will be
18397 in the hands of those who know those formats best.
18399 For an example of how this strategy works, see Orgstruct mode. In that mode,
18400 Bastien added the ability to use Org's facilities to edit and re-structure
18401 lists. He did by turning @code{orgstruct-mode} on, and then exporting the
18402 list locally to another format, such as HTML, @LaTeX{} or Texinfo.
18405 * Radio tables:: Sending and receiving radio tables
18406 * A @LaTeX{} example:: Step by step, almost a tutorial
18407 * Translator functions:: Copy and modify
18408 * Radio lists:: Sending and receiving lists
18412 @subsection Radio tables
18413 @cindex radio tables
18415 Radio tables are target locations for translated tables that are not near
18416 their source. Org finds the target location and inserts the translated
18419 The key to finding the target location are the magic words @code{BEGIN/END
18420 RECEIVE ORGTBL}. They have to appear as comments in the current mode. If
18421 the mode is C, then:
18424 /* BEGIN RECEIVE ORGTBL table_name */
18425 /* END RECEIVE ORGTBL table_name */
18429 At the location of source, Org needs a special line to direct Orgtbl to
18430 translate and to find the target for inserting the translated table. For
18434 #+ORGTBL: SEND table_name translation_function arguments...
18438 @code{table_name} is the table's reference name, which is also used in the
18439 receiver lines, and the @code{translation_function} is the Lisp function that
18440 translates. This line, in addition, may also contain alternating key and
18441 value arguments at the end. The translation function gets these values as a
18442 property list. A few standard parameters are already recognized and acted
18443 upon before the translation function is called:
18447 Skip the first N lines of the table. Hlines do count; include them if they
18450 @item :skipcols (n1 n2 ...)
18451 List of columns to be skipped. First Org automatically discards columns with
18452 calculation marks and then sends the table to the translator function, which
18453 then skips columns as specified in @samp{skipcols}.
18457 To keep the source table intact in the buffer without being disturbed when
18458 the source file is compiled or otherwise being worked on, use one of these
18463 Place the table in a block comment. For example, in C mode you could wrap
18464 the table between @samp{/*} and @samp{*/} lines.
18466 Put the table after an @samp{END} statement. For example @samp{\bye} in
18467 @TeX{} and @samp{\end@{document@}} in @LaTeX{}.
18469 Comment and uncomment each line of the table during edits. The @kbd{M-x
18470 orgtbl-toggle-comment RET} command makes toggling easy.
18473 @node A @LaTeX{} example
18474 @subsection A @LaTeX{} example of radio tables
18475 @cindex @LaTeX{}, and Orgtbl mode
18477 To wrap a source table in @LaTeX{}, use the @code{comment} environment
18478 provided by @file{comment.sty}. To activate it, put
18479 @code{\usepackage@{comment@}} in the document header. Orgtbl mode inserts a
18480 radio table skeleton@footnote{By default this works only for @LaTeX{}, HTML,
18481 and Texinfo. Configure the variable @code{orgtbl-radio-table-templates} to
18482 install templates for other export formats.} with the command @kbd{M-x
18483 orgtbl-insert-radio-table RET}, which prompts for a table name. For example,
18484 if @samp{salesfigures} is the name, the template inserts:
18486 @cindex #+ORGTBL, SEND
18488 % BEGIN RECEIVE ORGTBL salesfigures
18489 % END RECEIVE ORGTBL salesfigures
18491 #+ORGTBL: SEND salesfigures orgtbl-to-latex
18497 @vindex @LaTeX{}-verbatim-environments
18498 The line @code{#+ORGTBL: SEND} tells Orgtbl mode to use the function
18499 @code{orgtbl-to-latex} to convert the table to @LaTeX{} format, then insert
18500 the table at the target (receive) location named @code{salesfigures}. Now
18501 the table is ready for data entry. It can even use spreadsheet
18502 features@footnote{If the @samp{#+TBLFM} line contains an odd number of dollar
18503 characters, this may cause problems with font-lock in @LaTeX{} mode. As
18504 shown in the example you can fix this by adding an extra line inside the
18505 @code{comment} environment that is used to balance the dollar expressions.
18506 If you are using AUC@TeX{} with the font-latex library, a much better
18507 solution is to add the @code{comment} environment to the variable
18508 @code{LaTeX-verbatim-environments}.}:
18511 % BEGIN RECEIVE ORGTBL salesfigures
18512 % END RECEIVE ORGTBL salesfigures
18514 #+ORGTBL: SEND salesfigures orgtbl-to-latex
18515 | Month | Days | Nr sold | per day |
18516 |-------+------+---------+---------|
18517 | Jan | 23 | 55 | 2.4 |
18518 | Feb | 21 | 16 | 0.8 |
18519 | March | 22 | 278 | 12.6 |
18520 #+TBLFM: $4=$3/$2;%.1f
18521 % $ (optional extra dollar to keep font-lock happy, see footnote)
18526 After editing, @kbd{C-c C-c} inserts translated table at the target location,
18527 between the two marker lines.
18529 For hand-made custom tables, note that the translator needs to skip the first
18530 two lines of the source table. Also the command has to @emph{splice} out the
18531 target table without the header and footer.
18534 \begin@{tabular@}@{lrrr@}
18535 Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
18536 % BEGIN RECEIVE ORGTBL salesfigures
18537 % END RECEIVE ORGTBL salesfigures
18541 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
18542 | Month | Days | Nr sold | per day |
18543 |-------+------+---------+---------|
18544 | Jan | 23 | 55 | 2.4 |
18545 | Feb | 21 | 16 | 0.8 |
18546 | March | 22 | 278 | 12.6 |
18547 #+TBLFM: $4=$3/$2;%.1f
18551 The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
18552 Orgtbl mode and uses @code{tabular} environment by default to typeset the
18553 table and mark the horizontal lines with @code{\hline}. For additional
18554 parameters to control output, @pxref{Translator functions}:
18557 @item :splice nil/t
18558 When non-@code{nil}, returns only table body lines; not wrapped in tabular
18559 environment. Default is @code{nil}.
18562 Format to warp each field. It should contain @code{%s} for the original
18563 field value. For example, to wrap each field value in dollar symbol, you
18564 could use @code{:fmt "$%s$"}. Format can also wrap a property list with
18565 column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
18566 In place of a string, a function of one argument can be used; the function
18567 must return a formatted string.
18570 Format numbers as exponentials. The spec should have @code{%s} twice for
18571 inserting mantissa and exponent, for example @code{"%s\\times10^@{%s@}"}.
18572 This may also be a property list with column numbers and formats, for example
18573 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
18574 @code{efmt} has been applied to a value, @code{fmt} will also be applied.
18575 Functions with two arguments can be supplied instead of strings. By default,
18576 no special formatting is applied.
18579 @node Translator functions
18580 @subsection Translator functions
18581 @cindex HTML, and Orgtbl mode
18582 @cindex translator function
18584 Orgtbl mode has built-in translator functions: @code{orgtbl-to-csv}
18585 (comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values),
18586 @code{orgtbl-to-latex}, @code{orgtbl-to-html}, @code{orgtbl-to-texinfo},
18587 @code{orgtbl-to-unicode} and @code{orgtbl-to-orgtbl}. They use the generic
18588 translator, @code{orgtbl-to-generic}, which delegates translations to various
18591 Properties passed to the function through the @samp{ORGTBL SEND} line take
18592 precedence over properties defined inside the function. For example, this
18593 overrides the default @LaTeX{} line endings, @samp{\\}, with @samp{\\[2mm]}:
18596 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
18599 For a new language translator, define a converter function. It can be a
18600 generic function, such as shown in this example. It marks a beginning and
18601 ending of a table with @samp{!BTBL!} and @samp{!ETBL!}; a beginning and
18602 ending of lines with @samp{!BL!} and @samp{!EL!}; and uses a TAB for a field
18606 (defun orgtbl-to-language (table params)
18607 "Convert the orgtbl-mode TABLE to language."
18610 (org-combine-plists
18611 '(:tstart "!BTBL!" :tend "!ETBL!" :lstart "!BL!" :lend "!EL!" :sep "\t")
18616 The documentation for the @code{orgtbl-to-generic} function shows a complete
18617 list of parameters, each of which can be passed through to
18618 @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
18619 using that generic function.
18621 For complicated translations the generic translator function could be
18622 replaced by a custom translator function. Such a custom function must take
18623 two arguments and return a single string containing the formatted table. The
18624 first argument is the table whose lines are a list of fields or the symbol
18625 @code{hline}. The second argument is the property list consisting of
18626 parameters specified in the @samp{#+ORGTBL: SEND} line. Please share your
18627 translator functions by posting them to the Org users mailing list,
18628 @email{emacs-orgmode@@gnu.org}.
18631 @subsection Radio lists
18632 @cindex radio lists
18633 @cindex org-list-insert-radio-list
18635 Call the @code{org-list-insert-radio-list} function to insert a radio list
18636 template in HTML, @LaTeX{}, and Texinfo mode documents. Sending and
18637 receiving radio lists works is the same as for radio tables (@pxref{Radio
18638 tables}) except for these differences:
18643 Orgstruct mode must be active.
18645 Use @code{ORGLST} keyword instead of @code{ORGTBL}.
18647 @kbd{C-c C-c} works only on the first list item.
18650 Built-in translators functions are: @code{org-list-to-latex},
18651 @code{org-list-to-html} and @code{org-list-to-texinfo}. They use the
18652 @code{org-list-to-generic} translator function. See its documentation for
18653 parameters for accurate customizations of lists. Here is a @LaTeX{} example:
18656 % BEGIN RECEIVE ORGLST to-buy
18657 % END RECEIVE ORGLST to-buy
18659 #+ORGLST: SEND to-buy org-list-to-latex
18668 @kbd{C-c C-c} on @samp{a new house} inserts the translated @LaTeX{} list
18669 in-between the BEGIN and END marker lines.
18671 @node Dynamic blocks
18672 @section Dynamic blocks
18673 @cindex dynamic blocks
18675 Org supports @emph{dynamic blocks} in Org documents. They are inserted with
18676 begin and end markers like any other @samp{src} code block, but the contents
18677 are updated automatically by a user function. For example, @kbd{C-c C-x C-r}
18678 inserts a dynamic table that updates the work time (@pxref{Clocking work
18681 Dynamic blocks can have names and function parameters. The syntax is similar
18682 to @samp{src} code block specifications:
18684 @cindex #+BEGIN:dynamic block
18686 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
18691 These command update dynamic blocks:
18694 @orgcmd{C-c C-x C-u,org-dblock-update}
18695 Update dynamic block at point.
18696 @orgkey{C-u C-c C-x C-u}
18697 Update all dynamic blocks in the current file.
18700 Before updating a dynamic block, Org removes content between the BEGIN and
18701 END markers. Org then reads the parameters on the BEGIN line for passing to
18702 the writer function. If the function expects to access the removed content,
18703 then Org expects an extra parameter, @code{:content}, on the BEGIN line.
18705 To syntax for calling a writer function with a named block, @code{myblock}
18706 is: @code{org-dblock-write:myblock}. Parameters come from the BEGIN line.
18708 The following is an example of a dynamic block and a block writer function
18709 that updates the time when the function was last run:
18712 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
18718 The dynamic block's writer function:
18721 (defun org-dblock-write:block-update-time (params)
18722 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
18723 (insert "Last block update at: "
18724 (format-time-string fmt))))
18727 To keep dynamic blocks up-to-date in an Org file, use the function,
18728 @code{org-update-all-dblocks} in hook, such as @code{before-save-hook}. The
18729 @code{org-update-all-dblocks} function does not run if the file is not in
18732 Dynamic blocks, like any other block, can be narrowed with
18733 @code{org-narrow-to-block}.
18735 @node Special agenda views
18736 @section Special agenda views
18737 @cindex agenda views, user-defined
18739 @vindex org-agenda-skip-function
18740 @vindex org-agenda-skip-function-global
18741 Org provides a special hook to further limit items in agenda views:
18742 @code{agenda}, @code{agenda*}@footnote{The @code{agenda*} view is the same as
18743 @code{agenda} except that it only considers @emph{appointments}, i.e.,
18744 scheduled and deadline items that have a time specification @samp{[h]h:mm} in
18745 their time-stamps.}, @code{todo}, @code{alltodo}, @code{tags},
18746 @code{tags-todo}, @code{tags-tree}. Specify a custom function that tests
18747 inclusion of every matched item in the view. This function can also
18748 skip as much as is needed.
18750 For a global condition applicable to agenda views, use the
18751 @code{org-agenda-skip-function-global} variable. Org uses a global condition
18752 with @code{org-agenda-skip-function} for custom searching.
18754 This example defines a function for a custom view showing TODO items with
18755 WAITING status. Manually this is a multi step search process, but with a
18756 custom view, this can be automated as follows:
18758 The custom function searches the subtree for the WAITING tag and returns
18759 @code{nil} on match. Otherwise it gives the location from where the search
18763 (defun my-skip-unless-waiting ()
18764 "Skip trees that are not waiting"
18765 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
18766 (if (re-search-forward ":waiting:" subtree-end t)
18767 nil ; tag found, do not skip
18768 subtree-end))) ; tag not found, continue after end of subtree
18771 To use this custom function in a custom agenda command:
18774 (org-add-agenda-custom-command
18775 '("b" todo "PROJECT"
18776 ((org-agenda-skip-function 'my-skip-unless-waiting)
18777 (org-agenda-overriding-header "Projects waiting for something: "))))
18780 @vindex org-agenda-overriding-header
18781 Note that this also binds @code{org-agenda-overriding-header} to a more
18782 meaningful string suitable for the agenda view.
18784 @vindex org-odd-levels-only
18785 @vindex org-agenda-skip-function
18787 Search for entries with a limit set on levels for the custom search. This is
18788 a general approach to creating custom searches in Org. To include all
18789 levels, use @samp{LEVEL>0}@footnote{Note that, for
18790 @code{org-odd-levels-only}, a level number corresponds to order in the
18791 hierarchy, not to the number of stars.}. Then to selectively pick the
18792 matched entries, use @code{org-agenda-skip-function}, which also accepts Lisp
18793 forms, such as @code{org-agenda-skip-entry-if} and
18794 @code{org-agenda-skip-subtree-if}. For example:
18797 @item (org-agenda-skip-entry-if 'scheduled)
18798 Skip current entry if it has been scheduled.
18799 @item (org-agenda-skip-entry-if 'notscheduled)
18800 Skip current entry if it has not been scheduled.
18801 @item (org-agenda-skip-entry-if 'deadline)
18802 Skip current entry if it has a deadline.
18803 @item (org-agenda-skip-entry-if 'scheduled 'deadline)
18804 Skip current entry if it has a deadline, or if it is scheduled.
18805 @item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
18806 Skip current entry if the TODO keyword is TODO or WAITING.
18807 @item (org-agenda-skip-entry-if 'todo 'done)
18808 Skip current entry if the TODO keyword marks a DONE state.
18809 @item (org-agenda-skip-entry-if 'timestamp)
18810 Skip current entry if it has any timestamp, may also be deadline or scheduled.
18811 @anchor{x-agenda-skip-entry-regexp}
18812 @item (org-agenda-skip-entry-if 'regexp "regular expression")
18813 Skip current entry if the regular expression matches in the entry.
18814 @item (org-agenda-skip-entry-if 'notregexp "regular expression")
18815 Skip current entry unless the regular expression matches.
18816 @item (org-agenda-skip-subtree-if 'regexp "regular expression")
18817 Same as above, but check and skip the entire subtree.
18820 The following is an example of a search for @samp{WAITING} without the
18824 (org-add-agenda-custom-command
18825 '("b" todo "PROJECT"
18826 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
18827 'regexp ":waiting:"))
18828 (org-agenda-overriding-header "Projects waiting for something: "))))
18831 @node Speeding up your agendas
18832 @section Speeding up your agendas
18833 @cindex agenda views, optimization
18835 Some agenda commands slow down when the Org files grow in size or number.
18836 Here are tips to speed up:
18840 Reduce the number of Org agenda files to avoid slowdowns due to hard drive
18843 Reduce the number of @samp{DONE} and archived headlines so agenda operations
18844 that skip over these can finish faster.
18846 @vindex org-agenda-dim-blocked-tasks
18847 Do not dim blocked tasks:
18849 (setq org-agenda-dim-blocked-tasks nil)
18852 @vindex org-startup-folded
18853 @vindex org-agenda-inhibit-startup
18854 Stop preparing agenda buffers on startup:
18856 (setq org-agenda-inhibit-startup nil)
18859 @vindex org-agenda-show-inherited-tags
18860 @vindex org-agenda-use-tag-inheritance
18861 Disable tag inheritance for agendas:
18863 (setq org-agenda-use-tag-inheritance nil)
18867 These options can be applied to selected agenda views. For more details
18868 about generation of agenda views, see the docstrings for the relevant
18869 variables, and this @uref{http://orgmode.org/worg/agenda-optimization.html,
18870 dedicated Worg page} for agenda optimization.
18872 @node Extracting agenda information
18873 @section Extracting agenda information
18874 @cindex agenda, pipe
18875 @cindex Scripts, for agenda processing
18877 @vindex org-agenda-custom-commands
18878 Org provides commands to access agendas through Emacs batch mode. Through
18879 this command-line interface, agendas are automated for further processing or
18882 @code{org-batch-agenda} creates an agenda view in ASCII and outputs to
18883 STDOUT. This command takes one string parameter. When string length=1, Org
18884 uses it as a key to @code{org-agenda-custom-commands}. These are the same
18885 ones available through @kbd{C-c a}.
18887 This example command line directly prints the TODO list to the printer:
18890 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
18893 When the string parameter length is two or more characters, Org matches it
18894 with tags/TODO strings. For example, this example command line prints items
18895 tagged with @samp{shop}, but excludes items tagged with @samp{NewYork}:
18898 emacs -batch -l ~/.emacs \
18899 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
18903 An example showing on-the-fly parameter modifications:
18906 emacs -batch -l ~/.emacs \
18907 -eval '(org-batch-agenda "a" \
18908 org-agenda-span (quote month) \
18909 org-agenda-include-diary nil \
18910 org-agenda-files (quote ("~/org/project.org")))' \
18915 which will produce an agenda for the next 30 days from just the
18916 @file{~/org/projects.org} file.
18918 For structured processing of agenda output, use @code{org-batch-agenda-csv}
18919 with the following fields:
18922 category @r{The category of the item}
18923 head @r{The headline, without TODO keyword, TAGS and PRIORITY}
18924 type @r{The type of the agenda entry, can be}
18925 todo @r{selected in TODO match}
18926 tagsmatch @r{selected in tags match}
18927 diary @r{imported from diary}
18928 deadline @r{a deadline}
18929 scheduled @r{scheduled}
18930 timestamp @r{appointment, selected by timestamp}
18931 closed @r{entry was closed on date}
18932 upcoming-deadline @r{warning about nearing deadline}
18933 past-scheduled @r{forwarded scheduled item}
18934 block @r{entry has date block including date}
18935 todo @r{The TODO keyword, if any}
18936 tags @r{All tags including inherited ones, separated by colons}
18937 date @r{The relevant date, like 2007-2-14}
18938 time @r{The time, like 15:00-16:50}
18939 extra @r{String with extra planning info}
18940 priority-l @r{The priority letter if any was given}
18941 priority-n @r{The computed numerical priority}
18945 If the selection of the agenda item was based on a timestamp, including those
18946 items with @samp{DEADLINE} and @samp{SCHEDULED} keywords, then Org includes
18947 date and time in the output.
18949 If the selection of the agenda item was based on a timestamp (or
18950 deadline/scheduled), then Org includes date and time in the output.
18952 Here is an example of a post-processing script in Perl. It takes the CSV
18953 output from Emacs and prints with a checkbox:
18958 # define the Emacs command to run
18959 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
18961 # run it and capture the output
18962 $agenda = qx@{$cmd 2>/dev/null@};
18964 # loop over all lines
18965 foreach $line (split(/\n/,$agenda)) @{
18966 # get the individual values
18967 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
18968 $priority_l,$priority_n) = split(/,/,$line);
18969 # process and print
18970 print "[ ] $head\n";
18974 @node Using the property API
18975 @section Using the property API
18976 @cindex API, for properties
18977 @cindex properties, API
18979 Functions for working with properties.
18981 @defun org-entry-properties &optional pom which
18982 Get all properties of the entry at point-or-marker POM.@*
18983 This includes the TODO keyword, the tags, time strings for deadline,
18984 scheduled, and clocking, and any additional properties defined in the
18985 entry. The return value is an alist. Keys may occur multiple times
18986 if the property key was used several times.@*
18987 POM may also be @code{nil}, in which case the current entry is used.
18988 If WHICH is @code{nil} or @code{all}, get all properties. If WHICH is
18989 @code{special} or @code{standard}, only get that subclass.
18992 @vindex org-use-property-inheritance
18993 @findex org-insert-property-drawer
18994 @defun org-entry-get pom property &optional inherit
18995 Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@. By
18996 default, this only looks at properties defined locally in the entry. If
18997 @code{INHERIT} is non-@code{nil} and the entry does not have the property,
18998 then also check higher levels of the hierarchy. If @code{INHERIT} is the
18999 symbol @code{selective}, use inheritance if and only if the setting of
19000 @code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance.
19003 @defun org-entry-delete pom property
19004 Delete the property @code{PROPERTY} from entry at point-or-marker POM.
19007 @defun org-entry-put pom property value
19008 Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM.
19011 @defun org-buffer-property-keys &optional include-specials
19012 Get all property keys in the current buffer.
19015 @defun org-insert-property-drawer
19016 Insert a property drawer for the current entry.
19019 @defun org-entry-put-multivalued-property pom property &rest values
19020 Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@.
19021 @code{VALUES} should be a list of strings. They will be concatenated, with
19022 spaces as separators.
19025 @defun org-entry-get-multivalued-property pom property
19026 Treat the value of the property @code{PROPERTY} as a whitespace-separated
19027 list of values and return the values as a list of strings.
19030 @defun org-entry-add-to-multivalued-property pom property value
19031 Treat the value of the property @code{PROPERTY} as a whitespace-separated
19032 list of values and make sure that @code{VALUE} is in this list.
19035 @defun org-entry-remove-from-multivalued-property pom property value
19036 Treat the value of the property @code{PROPERTY} as a whitespace-separated
19037 list of values and make sure that @code{VALUE} is @emph{not} in this list.
19040 @defun org-entry-member-in-multivalued-property pom property value
19041 Treat the value of the property @code{PROPERTY} as a whitespace-separated
19042 list of values and check if @code{VALUE} is in this list.
19045 @defopt org-property-allowed-value-functions
19046 Hook for functions supplying allowed values for a specific property.
19047 The functions must take a single argument, the name of the property, and
19048 return a flat list of allowed values. If @samp{:ETC} is one of
19049 the values, use the values as completion help, but allow also other values
19050 to be entered. The functions must return @code{nil} if they are not
19051 responsible for this property.
19054 @node Using the mapping API
19055 @section Using the mapping API
19056 @cindex API, for mapping
19057 @cindex mapping entries, API
19059 Org has sophisticated mapping capabilities for finding entries. Org uses
19060 this functionality internally for generating agenda views. Org also exposes
19061 an API for executing arbitrary functions for each selected entry. The API's
19062 main entry point is:
19064 @defun org-map-entries func &optional match scope &rest skip
19065 Call @samp{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}.
19067 @samp{FUNC} is a function or a Lisp form. With the cursor positioned at the
19068 beginning of the headline, call the function without arguments. Org returns
19069 an alist of return values of calls to the function.
19071 To avoid preserving point, Org wraps the call to @code{FUNC} in
19072 save-excursion form. After evaluation, Org moves the cursor to the end of
19073 the line that was just processed. Search continues from that point forward.
19074 This may not always work as expected under some conditions, such as if the
19075 current sub-tree was removed by a previous archiving operation. In such rare
19076 circumstances, Org skips the next entry entirely when it should not. To stop
19077 Org from such skips, make @samp{FUNC} set the variable
19078 @code{org-map-continue-from} to a specific buffer position.
19080 @samp{MATCH} is a tags/property/TODO match. Org iterates only matched
19081 headlines. Org iterates over all headlines when @code{MATCH} is @code{nil}
19084 @samp{SCOPE} determines the scope of this command. It can be any of:
19087 nil @r{the current buffer, respecting the restriction if any}
19088 tree @r{the subtree started with the entry at point}
19089 region @r{The entries within the active region, if any}
19090 file @r{the current buffer, without restriction}
19092 @r{the current buffer, and any archives associated with it}
19093 agenda @r{all agenda files}
19094 agenda-with-archives
19095 @r{all agenda files with any archive files associated with them}
19097 @r{if this is a list, all files in the list will be scanned}
19100 The remaining args are treated as settings for the scanner's skipping
19101 facilities. Valid args are:
19103 @vindex org-agenda-skip-function
19105 archive @r{skip trees with the archive tag}
19106 comment @r{skip trees with the COMMENT keyword}
19107 function or Lisp form
19108 @r{will be used as value for @code{org-agenda-skip-function},}
19109 @r{so whenever the function returns t, FUNC}
19110 @r{will not be called for that entry and search will}
19111 @r{continue from the point where the function leaves it}
19115 The mapping routine can call any arbitrary function, even functions that
19116 change meta data or query the property API (@pxref{Using the property API}).
19117 Here are some handy functions:
19119 @defun org-todo &optional arg
19120 Change the TODO state of the entry. See the docstring of the functions for
19121 the many possible values for the argument @code{ARG}.
19124 @defun org-priority &optional action
19125 Change the priority of the entry. See the docstring of this function for the
19126 possible values for @code{ACTION}.
19129 @defun org-toggle-tag tag &optional onoff
19130 Toggle the tag @code{TAG} in the current entry. Setting @code{ONOFF} to
19131 either @code{on} or @code{off} will not toggle tag, but ensure that it is
19136 Promote the current entry.
19140 Demote the current entry.
19143 This example turns all entries tagged with @code{TOMORROW} into TODO entries
19144 with keyword @code{UPCOMING}. Org ignores entries in comment trees and
19149 '(org-todo "UPCOMING")
19150 "+TOMORROW" 'file 'archive 'comment)
19153 The following example counts the number of entries with TODO keyword
19154 @code{WAITING}, in all agenda files.
19157 (length (org-map-entries t "/+WAITING" 'agenda))
19161 @appendix MobileOrg
19165 MobileOrg is a companion mobile app that runs on iOS and Android devices.
19166 MobileOrg enables offline-views and capture support for an Org mode system
19167 that is rooted on a ``real'' computer. MobileOrg can record changes to
19170 The @uref{https://github.com/MobileOrg/, iOS implementation} for the
19171 @emph{iPhone/iPod Touch/iPad} series of devices, was started by Richard
19172 Moreland and is now in the hands Sean Escriva. Android users should check
19173 out @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg
19174 Android} by Matt Jones. Though the two implementations are not identical,
19175 they offer similar features.
19177 This appendix describes Org's support for agenda view formats compatible with
19178 MobileOrg. It also describes synchronizing changes, such as to notes,
19179 between MobileOrg and the computer.
19181 To change tags and TODO states in MobileOrg, first customize the variables
19182 @code{org-todo-keywords} and @code{org-tag-alist}. These should cover all
19183 the important tags and TODO keywords, even if Org files use only some of
19184 them. Though MobileOrg has in-buffer settings, it understands TODO states
19185 @emph{sets} (@pxref{Per-file keywords}) and @emph{mutually exclusive} tags
19186 (@pxref{Setting tags}) only for those set in these variables.
19189 * Setting up the staging area:: For the mobile device
19190 * Pushing to MobileOrg:: Uploading Org files and agendas
19191 * Pulling from MobileOrg:: Integrating captured and flagged items
19194 @node Setting up the staging area
19195 @section Setting up the staging area
19197 MobileOrg needs access to a file directory on a server to interact with
19198 Emacs. With a public server, consider encrypting the files. MobileOrg
19199 version 1.5 supports encryption for the iPhone. Org also requires
19200 @file{openssl} installed on the local computer. To turn on encryption, set
19201 the same password in MobileOrg and in Emacs. Set the password in the
19202 variable @code{org-mobile-use-encryption}@footnote{If Emacs is configured for
19203 safe storing of passwords, then configure the variable,
19204 @code{org-mobile-encryption-password}; please read the docstring of that
19205 variable.}. Note that even after MobileOrg encrypts the file contents, the
19206 file names will remain visible on the file systems of the local computer, the
19207 server, and the mobile device.
19209 For a server to host files, consider options like
19210 @uref{http://dropbox.com,Dropbox.com} account@footnote{An alternative is to
19211 use webdav server. MobileOrg documentation has details of webdav server
19212 configuration. Additional help is at
19213 @uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
19214 On first connection, MobileOrg creates a directory @file{MobileOrg/} on
19215 Dropbox. Pass its location to Emacs through an init file variable as
19219 (setq org-mobile-directory "~/Dropbox/MobileOrg")
19222 Org copies files to the above directory for MobileOrg. Org also uses the
19223 same directory for sharing notes between Org and MobileOrg.
19225 @node Pushing to MobileOrg
19226 @section Pushing to MobileOrg
19228 Org pushes files listed in @code{org-mobile-files} to
19229 @code{org-mobile-directory}. Files include agenda files (as listed in
19230 @code{org-agenda-files}). Customize @code{org-mobile-files} to add other
19231 files. File names will be staged with paths relative to
19232 @code{org-directory}, so all files should be inside this
19233 directory@footnote{Symbolic links in @code{org-directory} should have the
19234 same name as their targets.}.
19236 Push creates a special Org file @file{agendas.org} with custom agenda views
19237 defined by the user@footnote{While creating the agendas, Org mode will force
19238 ID properties on all referenced entries, so that these entries can be
19239 uniquely identified if MobileOrg flags them for further action. To avoid
19240 setting properties configure the variable
19241 @code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then
19242 rely on outline paths, assuming they are unique.}.
19244 Org writes the file @file{index.org}, containing links to other files.
19245 MobileOrg reads this file first from the server to determine what other files
19246 to download for agendas. For faster downloads, MobileOrg will read only
19247 those files whose checksums@footnote{Checksums are stored automatically in
19248 the file @file{checksums.dat}.} have changed.
19250 @node Pulling from MobileOrg
19251 @section Pulling from MobileOrg
19253 When MobileOrg synchronizes with the server, it pulls the Org files for
19254 viewing. It then appends to the file @file{mobileorg.org} on the server the
19255 captured entries, pointers to flagged and changed entries. Org integrates
19256 its data in an inbox file format.
19260 Org moves all entries found in
19261 @file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this
19262 operation.} and appends them to the file pointed to by the variable
19263 @code{org-mobile-inbox-for-pull}. Each captured entry and each editing event
19264 is a top-level entry in the inbox file.
19266 After moving the entries, Org attempts changes to MobileOrg. Some changes
19267 are applied directly and without user interaction. Examples include changes
19268 to tags, TODO state, headline and body text. Entries for further action are
19269 tagged as @code{:FLAGGED:}. Org marks entries with problems with an error
19270 message in the inbox. They have to be resolved manually.
19272 Org generates an agenda view for flagged entries for user intervention to
19273 clean up. For notes stored in flagged entries, MobileOrg displays them in
19274 the echo area when the cursor is on the corresponding agenda item.
19279 Pressing @kbd{?} displays the entire flagged note in another window. Org
19280 also pushes it to the kill ring. To store flagged note as a normal note, use
19281 @kbd{? z C-y C-c C-c}. Pressing @kbd{?} twice does these things: first it
19282 removes the @code{:FLAGGED:} tag; second, it removes the flagged note from
19283 the property drawer; third, it signals that manual editing of the flagged
19284 entry is now finished.
19289 @kbd{C-c a ?} returns to the agenda view to finish processing flagged
19290 entries. Note that these entries may not be the most recent since MobileOrg
19291 searches files that were last pulled. To get an updated agenda view with
19292 changes since the last pull, pull again.
19294 @node History and acknowledgments
19295 @appendix History and acknowledgments
19296 @cindex acknowledgments
19300 @section From Carsten
19302 Org was born in 2003, out of frustration over the user interface of the Emacs
19303 Outline mode. I was trying to organize my notes and projects, and using
19304 Emacs seemed to be the natural way to go. However, having to remember eleven
19305 different commands with two or three keys per command, only to hide and show
19306 parts of the outline tree, that seemed entirely unacceptable. Also, when
19307 using outlines to take notes, I constantly wanted to restructure the tree,
19308 organizing it paralleling my thoughts and plans. @emph{Visibility cycling}
19309 and @emph{structure editing} were originally implemented in the package
19310 @file{outline-magic.el}, but quickly moved to the more general @file{org.el}.
19311 As this environment became comfortable for project planning, the next step
19312 was adding @emph{TODO entries}, basic @emph{timestamps}, and @emph{table
19313 support}. These areas highlighted the two main goals that Org still has
19314 today: to be a new, outline-based, plain text mode with innovative and
19315 intuitive editing features, and to incorporate project planning functionality
19316 directly into a notes file.
19318 Since the first release, literally thousands of emails to me or to
19319 @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug
19320 reports, feedback, new ideas, and sometimes patches and add-on code.
19321 Many thanks to everyone who has helped to improve this package. I am
19322 trying to keep here a list of the people who had significant influence
19323 in shaping one or more aspects of Org. The list may not be
19324 complete, if I have forgotten someone, please accept my apologies and
19327 Before I get to this list, a few special mentions are in order:
19330 @item Bastien Guerry
19331 Bastien has written a large number of extensions to Org (most of them
19332 integrated into the core by now), including the @LaTeX{} exporter and the
19333 plain list parser. His support during the early days was central to the
19334 success of this project. Bastien also invented Worg, helped establishing the
19335 Web presence of Org, and sponsored hosting costs for the orgmode.org website.
19336 Bastien stepped in as maintainer of Org between 2011 and 2013, at a time when
19337 I desperately needed a break.
19338 @item Eric Schulte and Dan Davison
19339 Eric and Dan are jointly responsible for the Org-babel system, which turns
19340 Org into a multi-language environment for evaluating code and doing literate
19341 programming and reproducible research. This has become one of Org's killer
19342 features that define what Org is today.
19344 John has contributed a number of great ideas and patches directly to Org,
19345 including the attachment system (@file{org-attach.el}), integration with
19346 Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO
19347 items, habit tracking (@file{org-habits.el}), and encryption
19348 (@file{org-crypt.el}). Also, the capture system is really an extended copy
19349 of his great @file{remember.el}.
19350 @item Sebastian Rose
19351 Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
19352 of an ignorant amateur. Sebastian has pushed this part of Org onto a much
19353 higher level. He also wrote @file{org-info.js}, a Java script for displaying
19354 web pages derived from Org using an Info-like or a folding interface with
19355 single-key navigation.
19358 @noindent See below for the full list of contributions! Again, please
19359 let me know what I am missing here!
19361 @section From Bastien
19363 I (Bastien) have been maintaining Org between 2011 and 2013. This appendix
19364 would not be complete without adding a few more acknowledgments and thanks.
19366 I am first grateful to Carsten for his trust while handing me over the
19367 maintainership of Org. His unremitting support is what really helped me
19368 getting more confident over time, with both the community and the code.
19370 When I took over maintainership, I knew I would have to make Org more
19371 collaborative than ever, as I would have to rely on people that are more
19372 knowledgeable than I am on many parts of the code. Here is a list of the
19373 persons I could rely on, they should really be considered co-maintainers,
19374 either of the code or the community:
19378 Eric is maintaining the Babel parts of Org. His reactivity here kept me away
19379 from worrying about possible bugs here and let me focus on other parts.
19381 @item Nicolas Goaziou
19382 Nicolas is maintaining the consistency of the deepest parts of Org. His work
19383 on @file{org-element.el} and @file{ox.el} has been outstanding, and it opened
19384 the doors for many new ideas and features. He rewrote many of the old
19385 exporters to use the new export engine, and helped with documenting this
19386 major change. More importantly (if that's possible), he has been more than
19387 reliable during all the work done for Org 8.0, and always very reactive on
19391 Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
19392 into a flexible and conceptually clean process. He patiently coped with the
19393 many hiccups that such a change can create for users.
19396 The Org mode mailing list would not be such a nice place without Nick, who
19397 patiently helped users so many times. It is impossible to overestimate such
19398 a great help, and the list would not be so active without him.
19401 I received support from so many users that it is clearly impossible to be
19402 fair when shortlisting a few of them, but Org's history would not be
19403 complete if the ones above were not mentioned in this manual.
19405 @section List of contributions
19410 @i{Russel Adams} came up with the idea for drawers.
19412 @i{Suvayu Ali} has steadily helped on the mailing list, providing useful
19413 feedback on many features and several patches.
19415 @i{Luis Anaya} wrote @file{ox-man.el}.
19417 @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
19419 @i{Michael Brand} helped by reporting many bugs and testing many features.
19420 He also implemented the distinction between empty fields and 0-value fields
19421 in Org's spreadsheets.
19423 @i{Christophe Bataillon} created the great unicorn logo that we use on the
19426 @i{Alex Bochannek} provided a patch for rounding timestamps.
19428 @i{Jan Böcker} wrote @file{org-docview.el}.
19430 @i{Brad Bozarth} showed how to pull RSS feed data into Org mode files.
19432 @i{Tom Breton} wrote @file{org-choose.el}.
19434 @i{Charles Cave}'s suggestion sparked the implementation of templates
19435 for Remember, which are now templates for capture.
19437 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
19440 @i{Gregory Chernov} patched support for Lisp forms into table
19441 calculations and improved XEmacs compatibility, in particular by porting
19442 @file{nouline.el} to XEmacs.
19444 @i{Sacha Chua} suggested copying some linking code from Planner, and helped
19445 make Org popular through her blog.
19447 @i{Toby S. Cubitt} contributed to the code for clock formats.
19449 @i{Baoqiu Cui} contributed the first DocBook exporter. In Org 8.0, we go a
19450 different route: you can now export to Texinfo and export the @file{.texi}
19451 file to DocBook using @code{makeinfo}.
19453 @i{Eddward DeVilla} proposed and tested checkbox statistics. He also
19454 came up with the idea of properties, and that there should be an API for
19457 @i{Nick Dokos} tracked down several nasty bugs.
19459 @i{Kees Dullemond} used to edit projects lists directly in HTML and so
19460 inspired some of the early development, including HTML export. He also
19461 asked for a way to narrow wide table columns.
19463 @i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for
19464 several years now. He also sponsored the hosting costs until Rackspace
19465 started to host us for free.
19467 @i{Thomas S. Dye} contributed documentation on Worg and helped integrating
19468 the Org-Babel documentation into the manual.
19470 @i{Christian Egli} converted the documentation into Texinfo format, inspired
19471 the agenda, patched CSS formatting into the HTML exporter, and wrote
19472 @file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as
19473 @file{ox-taskjuggler.el} for Org 8.0.
19475 @i{David Emery} provided a patch for custom CSS support in exported
19478 @i{Sean Escriva} took over MobileOrg development on the iPhone platform.
19480 @i{Nic Ferrier} contributed mailcap and XOXO support.
19482 @i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
19484 @i{John Foerch} figured out how to make incremental search show context
19485 around a match in a hidden outline tree.
19487 @i{Raimar Finken} wrote @file{org-git-line.el}.
19489 @i{Mikael Fornius} works as a mailing list moderator.
19491 @i{Austin Frank} works as a mailing list moderator.
19493 @i{Eric Fraga} drove the development of BEAMER export with ideas and
19496 @i{Barry Gidden} did proofreading the manual in preparation for the book
19497 publication through Network Theory Ltd.
19499 @i{Niels Giesen} had the idea to automatically archive DONE trees.
19501 @i{Nicolas Goaziou} rewrote much of the plain list code. He also wrote
19502 @file{org-element.el} and @file{org-export.el}, which was a huge step forward
19503 in implementing a clean framework for Org exporters.
19505 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
19507 @i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a
19510 @i{Bernt Hansen} has driven much of the support for auto-repeating tasks,
19511 task state change logging, and the clocktable. His clear explanations have
19512 been critical when we started to adopt the Git version control system.
19514 @i{Manuel Hermenegildo} has contributed various ideas, small fixes and
19517 @i{Phil Jackson} wrote @file{org-irc.el}.
19519 @i{Scott Jaderholm} proposed footnotes, control over whitespace between
19520 folded entries, and column view for properties.
19522 @i{Matt Jones} wrote @i{MobileOrg Android}.
19524 @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
19526 @i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}.
19528 @i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also
19529 provided frequent feedback and some patches.
19531 @i{Matt Lundin} has proposed last-row references for table formulas and named
19532 invisible anchors. He has also worked a lot on the FAQ.
19534 @i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,
19535 and is a prolific contributor on the mailing list with competent replies,
19536 small fixes and patches.
19538 @i{Jason F. McBrayer} suggested agenda export to CSV format.
19540 @i{Max Mikhanosha} came up with the idea of refiling and sticky agendas.
19542 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file
19545 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
19548 @i{Richard Moreland} wrote MobileOrg for the iPhone.
19550 @i{Rick Moynihan} proposed allowing multiple TODO sequences in a file
19551 and being able to quickly restrict the agenda to a subtree.
19553 @i{Todd Neal} provided patches for links to Info files and Elisp forms.
19555 @i{Greg Newman} refreshed the unicorn logo into its current form.
19557 @i{Tim O'Callaghan} suggested in-file links, search options for general
19558 file links, and TAGS.
19560 @i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text
19561 version of the reference card.
19563 @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
19566 @i{Oliver Oppitz} suggested multi-state TODO items.
19568 @i{Scott Otterson} sparked the introduction of descriptive text for
19569 links, among other things.
19571 @i{Pete Phillips} helped during the development of the TAGS feature, and
19572 provided frequent feedback.
19574 @i{Francesco Pizzolante} provided patches that helped speeding up the agenda
19577 @i{Martin Pohlack} provided the code snippet to bundle character insertion
19578 into bundles of 20 for undo.
19580 @i{Rackspace.com} is hosting our website for free. Thank you Rackspace!
19582 @i{T.V. Raman} reported bugs and suggested improvements.
19584 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
19587 @i{Paul Rivier} provided the basic implementation of named footnotes. He
19588 also acted as mailing list moderator for some time.
19590 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
19592 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
19593 conflict with @file{allout.el}.
19595 @i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with
19598 @i{Philip Rooke} created the Org reference card, provided lots
19599 of feedback, developed and applied standards to the Org documentation.
19601 @i{Christian Schlauer} proposed angular brackets around links, among
19604 @i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can
19605 enjoy folding in non-org buffers by using Org headlines in comments.
19607 @i{Paul Sexton} wrote @file{org-ctags.el}.
19609 Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
19610 @file{organizer-mode.el}.
19612 @i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal
19613 examples, and remote highlighting for referenced code lines.
19615 @i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is
19616 now packaged into Org's @file{contrib} directory.
19618 @i{Daniel Sinder} came up with the idea of internal archiving by locking
19621 @i{Dale Smith} proposed link abbreviations.
19623 @i{James TD Smith} has contributed a large number of patches for useful
19624 tweaks and features.
19626 @i{Adam Spiers} asked for global linking commands, inspired the link
19627 extension system, added support for mairix, and proposed the mapping API.
19629 @i{Ulf Stegemann} created the table to translate special symbols to HTML,
19630 @LaTeX{}, UTF-8, Latin-1 and ASCII.
19632 @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
19633 with links transformation to Org syntax.
19635 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
19636 chapter about publishing.
19638 @i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter.
19640 @i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
19641 enabled source code highlighting in Gnus.
19643 @i{Stefan Vollmar} organized a video-recorded talk at the
19644 Max-Planck-Institute for Neurology. He also inspired the creation of a
19645 concept index for HTML export.
19647 @i{Jürgen Vollmer} contributed code generating the table of contents
19650 @i{Samuel Wales} has provided important feedback and bug reports.
19652 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
19655 @i{David Wainberg} suggested archiving, and improvements to the linking
19658 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
19661 @i{Roland Winkler} requested additional key bindings to make Org
19664 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
19665 and contributed various ideas and code snippets.
19667 @i{Marco Wahl} wrote @file{org-eww.el}.
19671 @node GNU Free Documentation License
19672 @appendix GNU Free Documentation License
19673 @include doclicense.texi
19677 @unnumbered Concept index
19682 @unnumbered Key index
19686 @node Command and Function Index
19687 @unnumbered Command and function index
19691 @node Variable Index
19692 @unnumbered Variable index
19694 This is not a complete index of variables and faces, only the ones that are
19695 mentioned in the manual. For a complete list, use @kbd{M-x org-customize
19702 @c Local variables:
19704 @c indent-tabs-mode: nil
19705 @c paragraph-start: "
\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$"
19706 @c paragraph-separate: "
\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$"
19710 @c LocalWords: webdavhost pre