1 \input texinfo @c -*- coding: utf-8 -*-
3 @setfilename ../../info/org.info
4 @settitle The Org Manual
7 @include org-version.inc
9 @c Version and Contact Info
10 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page}
11 @set AUTHOR Carsten Dominik
12 @set MAINTAINER Carsten Dominik
13 @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
14 @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
19 @c -----------------------------------------------------------------------------
21 @c Macro definitions for commands and keys
22 @c =======================================
24 @c The behavior of the key/command macros will depend on the flag cmdnames
25 @c When set, commands names are shown. When clear, they are not shown.
29 @c Below we define the following macros for Org key tables:
31 @c orgkey{key} A key item
32 @c orgcmd{key,cmd} Key with command name
33 @c xorgcmd{key,cmd} Key with command name as @itemx
34 @c orgcmdnki{key,cmd} Like orgcmd, but do not index the key
35 @c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key
36 @c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or"
37 @c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but
38 @c different functions, so format as @itemx
39 @c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short"
40 @c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx
41 @c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands
43 @c a key but no command
55 @c one key with a command
56 @c Inserts: @item KEY COMMAND
57 @macro orgcmd{key,command}
62 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
65 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
74 @c One key with one command, formatted using @itemx
75 @c Inserts: @itemx KEY COMMAND
76 @macro xorgcmd{key,command}
81 @itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
84 @itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
93 @c one key with a command, bit do not index the key
94 @c Inserts: @item KEY COMMAND
95 @macro orgcmdnki{key,command}
99 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
102 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
110 @c one key with a command, and special text to replace key in item
111 @c Inserts: @item TEXT COMMAND
112 @macro orgcmdtkc{text,key,command}
117 @item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
120 @item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
129 @c two keys with one command
130 @c Inserts: @item KEY1 or KEY2 COMMAND
131 @macro orgcmdkkc{key1,key2,command}
137 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
140 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
146 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
150 @c Two keys with one command name, but different functions, so format as
152 @c Inserts: @item KEY1
153 @c @itemx KEY2 COMMAND
154 @macro orgcmdkxkc{key1,key2,command}
161 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
165 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
176 @c Same as previous, but use "or short"
177 @c Inserts: @item KEY1 or short KEY2 COMMAND
178 @macro orgcmdkskc{key1,key2,command}
184 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
187 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
193 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
197 @c Same as previous, but use @itemx
198 @c Inserts: @itemx KEY1 or short KEY2 COMMAND
199 @macro xorgcmdkskc{key1,key2,command}
205 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
208 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
214 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
218 @c two keys with two commands
219 @c Inserts: @item KEY1 COMMAND1
220 @c @itemx KEY2 COMMAND2
221 @macro orgcmdkkcc{key1,key2,command1,command2}
228 @item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
229 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
232 @item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
233 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
243 @c -----------------------------------------------------------------------------
246 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
249 @c Subheadings inside a table.
250 @macro tsubheading{text}
252 @subsubheading \text\
260 This manual is for Org version @value{VERSION}.
262 Copyright @copyright{} 2004--2017 Free Software Foundation, Inc.
265 Permission is granted to copy, distribute and/or modify this document
266 under the terms of the GNU Free Documentation License, Version 1.3 or
267 any later version published by the Free Software Foundation; with no
268 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
269 and with the Back-Cover Texts as in (a) below. A copy of the license
270 is included in the section entitled ``GNU Free Documentation License.''
272 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
273 modify this GNU manual.''
277 @dircategory Emacs editing modes
279 * Org Mode: (org). Outline-based notes management and organizer
283 @title The Org Manual
285 @subtitle Release @value{VERSION}
286 @author by Carsten Dominik
287 with contributions by Bastien Guerry, Nicolas Goaziou, Eric Schulte,
288 Jambunathan K, Dan Davison, Thomas Dye, David O'Toole, and Philip Rooke.
290 @c The following two commands start the copyright page.
292 @vskip 0pt plus 1filll
296 @c Output the short table of contents at the beginning.
299 @c Output the table of contents at the beginning.
304 @node Top, Introduction, (dir), (dir)
311 * Introduction:: Getting started
312 * Document structure:: A tree works like your brain
313 * Tables:: Pure magic for quick formatting
314 * Hyperlinks:: Notes in context
315 * TODO items:: Every tree branch can be a TODO item
316 * Tags:: Tagging headlines and matching sets of tags
317 * Properties and columns:: Storing information about an entry
318 * Dates and times:: Making items useful for planning
319 * Capture - Refile - Archive:: The ins and outs for projects
320 * Agenda views:: Collecting information into views
321 * Markup:: Prepare text for rich export
322 * Exporting:: Sharing and publishing notes
323 * Publishing:: Create a web site of linked Org files
324 * Working with source code:: Export, evaluate, and tangle code blocks
325 * Miscellaneous:: All the rest which did not fit elsewhere
326 * Hacking:: How to hack your way around
327 * MobileOrg:: Viewing and capture on a mobile device
328 * History and acknowledgments:: How Org came into being
329 * GNU Free Documentation License:: The license for this documentation.
330 * Main Index:: An index of Org's concepts and features
331 * Key Index:: Key bindings and where they are described
332 * Command and Function Index:: Command names and some internal functions
333 * Variable Index:: Variables mentioned in the manual
336 --- The Detailed Node Listing ---
340 * Summary:: Brief summary of what Org does
341 * Installation:: Installing Org
342 * Activation:: How to activate Org for certain buffers
343 * Feedback:: Bug reports, ideas, patches etc.
344 * Conventions:: Typesetting conventions in the manual
348 * Outlines:: Org is based on Outline mode
349 * Headlines:: How to typeset Org tree headlines
350 * Visibility cycling:: Show and hide, much simplified
351 * Motion:: Jumping to other headlines
352 * Structure editing:: Changing sequence and level of headlines
353 * Sparse trees:: Matches embedded in context
354 * Plain lists:: Additional structure within an entry
355 * Drawers:: Tucking stuff away
356 * Blocks:: Folding blocks
357 * Footnotes:: How footnotes are defined in Org's syntax
358 * Orgstruct mode:: Structure editing outside Org
359 * Org syntax:: Formal description of Org's syntax
363 * Global and local cycling:: Cycling through various visibility states
364 * Initial visibility:: Setting the initial visibility state
365 * Catching invisible edits:: Preventing mistakes when editing invisible parts
369 * Built-in table editor:: Simple tables
370 * Column width and alignment:: Overrule the automatic settings
371 * Column groups:: Grouping to trigger vertical lines
372 * Orgtbl mode:: The table editor as minor mode
373 * The spreadsheet:: The table editor has spreadsheet capabilities
374 * Org-Plot:: Plotting from org tables
378 * References:: How to refer to another field or range
379 * Formula syntax for Calc:: Using Calc to compute stuff
380 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
381 * Durations and time values:: How to compute durations and time values
382 * Field and range formulas:: Formula for specific (ranges of) fields
383 * Column formulas:: Formulas valid for an entire column
384 * Lookup functions:: Lookup functions for searching tables
385 * Editing and debugging formulas:: Fixing formulas
386 * Updating the table:: Recomputing all dependent fields
387 * Advanced features:: Field and column names, parameters and automatic recalc
391 * Link format:: How links in Org are formatted
392 * Internal links:: Links to other places in the current file
393 * External links:: URL-like links to the world
394 * Handling links:: Creating, inserting and following
395 * Using links outside Org:: Linking from my C source code?
396 * Link abbreviations:: Shortcuts for writing complex links
397 * Search options:: Linking to a specific location
398 * Custom searches:: When the default search is not enough
402 * Radio targets:: Make targets trigger links in plain text
406 * TODO basics:: Marking and displaying TODO entries
407 * TODO extensions:: Workflow and assignments
408 * Progress logging:: Dates and notes for progress
409 * Priorities:: Some things are more important than others
410 * Breaking down tasks:: Splitting a task into manageable pieces
411 * Checkboxes:: Tick-off lists
413 Extended use of TODO keywords
415 * Workflow states:: From TODO to DONE in steps
416 * TODO types:: I do this, Fred does the rest
417 * Multiple sets in one file:: Mixing it all, and still finding your way
418 * Fast access to TODO states:: Single letter selection of a state
419 * Per-file keywords:: Different files, different requirements
420 * Faces for TODO keywords:: Highlighting states
421 * TODO dependencies:: When one task needs to wait for others
425 * Closing items:: When was this entry marked DONE?
426 * Tracking TODO state changes:: When did the status change?
427 * Tracking your habits:: How consistent have you been?
431 * Tag inheritance:: Tags use the tree structure of the outline
432 * Setting tags:: How to assign tags to a headline
433 * Tag hierarchy:: Create a hierarchy of tags
434 * Tag searches:: Searching for combinations of tags
436 Properties and columns
438 * Property syntax:: How properties are spelled out
439 * Special properties:: Access to other Org mode features
440 * Property searches:: Matching property values
441 * Property inheritance:: Passing values down the tree
442 * Column view:: Tabular viewing and editing
443 * Property API:: Properties for Lisp programmers
447 * Defining columns:: The COLUMNS format property
448 * Using column view:: How to create and use column view
449 * Capturing column view:: A dynamic block for column view
453 * Scope of column definitions:: Where defined, where valid?
454 * Column attributes:: Appearance and content of a column
458 * Timestamps:: Assigning a time to a tree entry
459 * Creating timestamps:: Commands which insert timestamps
460 * Deadlines and scheduling:: Planning your work
461 * Clocking work time:: Tracking how long you spend on a task
462 * Effort estimates:: Planning work effort in advance
463 * Timers:: Notes with a running timer
467 * The date/time prompt:: How Org mode helps you entering date and time
468 * Custom time format:: Making dates look different
470 Deadlines and scheduling
472 * Inserting deadline/schedule:: Planning items
473 * Repeated tasks:: Items that show up again and again
477 * Clocking commands:: Starting and stopping a clock
478 * The clock table:: Detailed reports
479 * Resolving idle time:: Resolving time when you've been idle
481 Capture - Refile - Archive
483 * Capture:: Capturing new stuff
484 * Attachments:: Add files to tasks
485 * RSS feeds:: Getting input from RSS feeds
486 * Protocols:: External (e.g., Browser) access to Emacs and Org
487 * Refile and copy:: Moving/copying a tree from one place to another
488 * Archiving:: What to do with finished projects
492 * Setting up capture:: Where notes will be stored
493 * Using capture:: Commands to invoke and terminate capture
494 * Capture templates:: Define the outline of different note types
498 * Template elements:: What is needed for a complete template entry
499 * Template expansion:: Filling in information about time and context
500 * Templates in contexts:: Only show a template in a specific context
502 Protocols for external access
504 * @code{store-link} protocol:: Store a link, push URL to kill-ring.
505 * @code{capture} protocol:: Fill a buffer with external information.
506 * @code{open-source} protocol:: Edit published contents.
510 * Moving subtrees:: Moving a tree to an archive file
511 * Internal archiving:: Switch off a tree but keep it in the file
515 * Agenda files:: Files being searched for agenda information
516 * Agenda dispatcher:: Keyboard access to agenda views
517 * Built-in agenda views:: What is available out of the box?
518 * Presentation and sorting:: How agenda items are prepared for display
519 * Agenda commands:: Remote editing of Org trees
520 * Custom agenda views:: Defining special searches and views
521 * Exporting agenda views:: Writing a view to a file
522 * Agenda column view:: Using column view for collected entries
524 The built-in agenda views
526 * Weekly/daily agenda:: The calendar page with current tasks
527 * Global TODO list:: All unfinished action items
528 * Matching tags and properties:: Structured information with fine-tuned search
529 * Search view:: Find entries by searching for text
530 * Stuck projects:: Find projects you need to review
532 Presentation and sorting
534 * Categories:: Not all tasks are equal
535 * Time-of-day specifications:: How the agenda knows the time
536 * Sorting agenda items:: The order of things
537 * Filtering/limiting agenda items:: Dynamically narrow the agenda
541 * Storing searches:: Type once, use often
542 * Block agenda:: All the stuff you need in a single buffer
543 * Setting options:: Changing the rules
545 Markup for rich export
547 * Paragraphs:: The basic unit of text
548 * Emphasis and monospace:: Bold, italic, etc.
549 * Horizontal rules:: Make a line
550 * Images and tables:: Images, tables and caption mechanism
551 * Literal examples:: Source code examples with special formatting
552 * Special symbols:: Greek letters and other symbols
553 * Subscripts and superscripts:: Simple syntax for raising/lowering text
554 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
558 * @LaTeX{} fragments:: Complex formulas made easy
559 * Previewing @LaTeX{} fragments:: What will this snippet look like?
560 * CDLaTeX mode:: Speed up entering of formulas
564 * The export dispatcher:: The main interface
565 * Export settings:: Common export settings
566 * Table of contents:: The if and where of the table of contents
567 * Include files:: Include additional files into a document
568 * Macro replacement:: Use macros to create templates
569 * Comment lines:: What will not be exported
570 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
571 * Beamer export:: Exporting as a Beamer presentation
572 * HTML export:: Exporting to HTML
573 * @LaTeX{} export:: Exporting to @LaTeX{}, and processing to PDF
574 * Markdown export:: Exporting to Markdown
575 * OpenDocument Text export:: Exporting to OpenDocument Text
576 * Org export:: Exporting to Org
577 * Texinfo export:: Exporting to Texinfo
578 * iCalendar export:: Exporting to iCalendar
579 * Other built-in back-ends:: Exporting to a man page
580 * Advanced configuration:: Fine-tuning the export output
581 * Export in foreign buffers:: Author tables and lists in Org syntax
585 * Beamer export commands:: For creating Beamer documents.
586 * Beamer specific export settings:: For customizing Beamer export.
587 * Sectioning Frames and Blocks in Beamer:: For composing Beamer slides.
588 * Beamer specific syntax:: For using in Org documents.
589 * Editing support:: For using helper functions.
590 * A Beamer example:: A complete presentation.
594 * HTML Export commands:: Invoking HTML export
595 * HTML Specific export settings:: Settings for HTML export
596 * HTML doctypes:: Exporting various (X)HTML flavors
597 * HTML preamble and postamble:: Inserting preamble and postamble
598 * Quoting HTML tags:: Using direct HTML in Org files
599 * Links in HTML export:: Interpreting and formatting links
600 * Tables in HTML export:: Formatting and modifying tables
601 * Images in HTML export:: Inserting figures with HTML output
602 * Math formatting in HTML export:: Handling math equations
603 * Text areas in HTML export:: Showing an alternate approach, an example
604 * CSS support:: Styling HTML output
605 * JavaScript support:: Folding scripting in the web browser
609 * @LaTeX{} export commands:: For producing @LaTeX{} and PDF documents.
610 * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end.
611 * @LaTeX{} header and sectioning:: For file structure.
612 * Quoting @LaTeX{} code:: Directly in the Org document.
613 * Tables in @LaTeX{} export:: Attributes specific to tables.
614 * Images in @LaTeX{} export:: Attributes specific to images.
615 * Plain lists in @LaTeX{} export:: Attributes specific to lists.
616 * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks.
617 * Example blocks in @LaTeX{} export:: Attributes specific to example blocks.
618 * Special blocks in @LaTeX{} export:: Attributes specific to special blocks.
619 * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules.
621 OpenDocument Text export
623 * Pre-requisites for ODT export:: Required packages.
624 * ODT export commands:: Invoking export.
625 * ODT specific export settings:: Configuration options.
626 * Extending ODT export:: Producing @file{.doc}, @file{.pdf} files.
627 * Applying custom styles:: Styling the output.
628 * Links in ODT export:: Handling and formatting links.
629 * Tables in ODT export:: Org table conversions.
630 * Images in ODT export:: Inserting images.
631 * Math formatting in ODT export:: Formatting @LaTeX{} fragments.
632 * Labels and captions in ODT export:: Rendering objects.
633 * Literal examples in ODT export:: For source code and example blocks.
634 * Advanced topics in ODT export:: For power users.
636 Math formatting in ODT export
638 * Working with @LaTeX{} math snippets:: Embedding in @LaTeX{} format.
639 * Working with MathML or OpenDocument formula files:: Embedding in native format.
641 Advanced topics in ODT export
643 * Configuring a document converter:: Registering a document converter.
644 * Working with OpenDocument style files:: Exploring internals.
645 * Creating one-off styles:: Customizing styles, highlighting.
646 * Customizing tables in ODT export:: Defining table templates.
647 * Validating OpenDocument XML:: Debugging corrupted OpenDocument files.
651 * Texinfo export commands:: Invoking commands.
652 * Texinfo specific export settings:: Setting the environment.
653 * Texinfo file header:: Generating the header.
654 * Texinfo title and copyright page:: Creating preamble pages.
655 * Info directory file:: Installing a manual in Info file hierarchy.
656 * Headings and sectioning structure:: Building document structure.
657 * Indices:: Creating indices.
658 * Quoting Texinfo code:: Incorporating literal Texinfo code.
659 * Plain lists in Texinfo export:: List attributes.
660 * Tables in Texinfo export:: Table attributes.
661 * Images in Texinfo export:: Image attributes.
662 * Special blocks in Texinfo export:: Special block attributes.
663 * A Texinfo example:: Processing Org to Texinfo.
667 * Configuration:: Defining projects
668 * Uploading files:: How to get files up on the server
669 * Sample configuration:: Example projects
670 * Triggering publication:: Publication commands
674 * Project alist:: The central configuration variable
675 * Sources and destinations:: From here to there
676 * Selecting files:: What files are part of the project?
677 * Publishing action:: Setting the function doing the publishing
678 * Publishing options:: Tweaking HTML/@LaTeX{} export
679 * Publishing links:: Which links keep working after publishing?
680 * Sitemap:: Generating a list of all pages
681 * Generating an index:: An index that reaches across pages
685 * Simple example:: One-component publishing
686 * Complex example:: A multi-component publishing example
688 Working with source code
690 * Structure of code blocks:: Code block syntax described
691 * Editing source code:: Language major-mode editing
692 * Exporting code blocks:: Export contents and/or results
693 * Extracting source code:: Create pure source code files
694 * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
695 * Library of Babel:: Use and contribute to a library of useful code blocks
696 * Languages:: List of supported code block languages
697 * Header arguments:: Configure code block functionality
698 * Results of evaluation:: How evaluation results are handled
699 * Noweb reference syntax:: Literate programming in Org mode
700 * Key bindings and useful functions:: Work quickly with code blocks
701 * Batch execution:: Call functions from the command line
705 * Using header arguments:: Different ways to set header arguments
706 * Specific header arguments:: List of header arguments
708 Using header arguments
710 * System-wide header arguments:: Set globally, language-specific
711 * Language-specific header arguments:: Set in the Org file's headers
712 * Header arguments in Org mode properties:: Set in the Org file
713 * Language-specific mode properties::
714 * Code block specific header arguments:: The most commonly used method
715 * Arguments in function calls:: The most specific level, takes highest priority
717 Specific header arguments
719 * var:: Pass arguments to @samp{src} code blocks
720 * results:: Specify results type; how to collect
721 * file:: Specify a path for output file
722 * file-desc:: Specify a description for file results
723 * file-ext:: Specify an extension for file output
724 * output-dir:: Specify a directory for output file
725 * dir:: Specify the default directory for code block execution
726 * exports:: Specify exporting code, results, both, none
727 * tangle:: Toggle tangling; or specify file name
728 * mkdirp:: Toggle for parent directory creation for target files during tangling
729 * comments:: Toggle insertion of comments in tangled code files
730 * padline:: Control insertion of padding lines in tangled code files
731 * no-expand:: Turn off variable assignment and noweb expansion during tangling
732 * session:: Preserve the state of code evaluation
733 * noweb:: Toggle expansion of noweb references
734 * noweb-ref:: Specify block's noweb reference resolution target
735 * noweb-sep:: String to separate noweb references
736 * cache:: Avoid re-evaluating unchanged code blocks
737 * sep:: Delimiter for writing tabular results outside Org
738 * hlines:: Handle horizontal lines in tables
739 * colnames:: Handle column names in tables
740 * rownames:: Handle row names in tables
741 * shebang:: Make tangled files executable
742 * tangle-mode:: Set permission of tangled files
743 * eval:: Limit evaluation of specific code blocks
744 * wrap:: Mark source block evaluation results
745 * post:: Post processing of results of code block evaluation
746 * prologue:: Text to prepend to body of code block
747 * epilogue:: Text to append to body of code block
751 * Completion:: M-TAB guesses completions
752 * Structure templates:: Quick insertion of structural elements
753 * Speed keys:: Electric commands at the beginning of a headline
754 * Code evaluation security:: Org mode files evaluate inline code
755 * Customization:: Adapting Org to changing tastes
756 * In-buffer settings:: Overview of the #+KEYWORDS
757 * The very busy C-c C-c key:: When in doubt, press C-c C-c
758 * Clean view:: Getting rid of leading stars in the outline
759 * TTY keys:: Using Org on a tty
760 * Interaction:: With other Emacs packages
761 * org-crypt:: Encrypting Org files
763 Interaction with other packages
765 * Cooperation:: Packages Org cooperates with
766 * Conflicts:: Packages that lead to conflicts
770 * Hooks:: How to reach into Org's internals
771 * Add-on packages:: Available extensions
772 * Adding hyperlink types:: New custom link types
773 * Adding export back-ends:: How to write new export back-ends
774 * Context-sensitive commands:: How to add functionality to such commands
775 * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
776 * Dynamic blocks:: Automatically filled blocks
777 * Special agenda views:: Customized views
778 * Speeding up your agendas:: Tips on how to speed up your agendas
779 * Extracting agenda information:: Post-processing of agenda information
780 * Using the property API:: Writing programs that use entry properties
781 * Using the mapping API:: Mapping over all or selected entries
783 Tables and lists in arbitrary syntax
785 * Radio tables:: Sending and receiving radio tables
786 * A @LaTeX{} example:: Step by step, almost a tutorial
787 * Translator functions:: Copy and modify
788 * Radio lists:: Sending and receiving lists
792 * Setting up the staging area:: For the mobile device
793 * Pushing to MobileOrg:: Uploading Org files and agendas
794 * Pulling from MobileOrg:: Integrating captured and flagged items
800 @chapter Introduction
804 * Summary:: Brief summary of what Org does
805 * Installation:: Installing Org
806 * Activation:: How to activate Org for certain buffers
807 * Feedback:: Bug reports, ideas, patches etc.
808 * Conventions:: Typesetting conventions in the manual
815 Org is a mode for keeping notes, maintaining TODO lists, and project planning
816 with a fast and effective plain-text system. It also is an authoring system
817 with unique support for literate programming and reproducible research.
819 Org is implemented on top of Outline mode, which makes it possible to keep
820 the content of large files well structured. Visibility cycling and structure
821 editing help to work with the tree. Tables are easily created with a
822 built-in table editor. Plain text URL-like links connect to websites,
823 emails, Usenet messages, BBDB entries, and any files related to the projects.
825 Org develops organizational tasks around notes files that contain lists or
826 information about projects as plain text. Project planning and task
827 management makes use of metadata which is part of an outline node. Based on
828 this data, specific entries can be extracted in queries and create dynamic
829 @i{agenda views} that also integrate the Emacs calendar and diary. Org can
830 be used to implement many different project planning schemes, such as David
833 Org files can serve as a single source authoring system with export to many
834 different formats such as HTML, @LaTeX{}, Open Document, and Markdown. New
835 export backends can be derived from existing ones, or defined from scratch.
837 Org files can include source code blocks, which makes Org uniquely suited for
838 authoring technical documents with code examples. Org source code blocks are
839 fully functional; they can be evaluated in place and their results can be
840 captured in the file. This makes it possible to create a single file
841 reproducible research compendium.
843 Org keeps simple things simple. When first fired up, it should feel like a
844 straightforward, easy to use outliner. Complexity is not imposed, but a
845 large amount of functionality is available when needed. Org is a toolbox.
846 Many users actually run only a (very personal) fraction of Org's capabilities, and
847 know that there is more whenever they need it.
849 All of this is achieved with strictly plain text files, the most portable and
850 future-proof file format. Org runs in Emacs. Emacs is one of the most
851 widely ported programs, so that Org mode is available on every major
855 There is a website for Org which provides links to the newest
856 version of Org, as well as additional information, frequently asked
857 questions (FAQ), links to tutorials, etc. This page is located at
858 @uref{http://orgmode.org}.
859 @cindex print edition
861 An earlier version (7.3) of this manual is available as a
862 @uref{http://www.network-theory.co.uk/org/manual/, paperback book from
868 @section Installation
871 Org is part of recent distributions of GNU Emacs, so you normally don't need
872 to install it. If, for one reason or another, you want to install Org on top
873 of this pre-packaged version, there are three ways to do it:
876 @item By using Emacs package system.
877 @item By downloading Org as an archive.
878 @item By using Org's git repository.
881 We @b{strongly recommend} to stick to a single installation method.
883 @subsubheading Using Emacs packaging system
885 Recent Emacs distributions include a packaging system which lets you install
886 Elisp libraries. You can install Org with @kbd{M-x package-install RET org}.
888 @noindent @b{Important}: you need to do this in a session where no @code{.org} file has
889 been visited, i.e., where no Org built-in function have been loaded.
890 Otherwise autoload Org functions will mess up the installation.
892 Then, to make sure your Org configuration is taken into account, initialize
893 the package system with @code{(package-initialize)} in your Emacs init file
894 before setting any Org option. If you want to use Org's package repository,
895 check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
897 @subsubheading Downloading Org as an archive
899 You can download Org latest release from @uref{http://orgmode.org/, Org's
900 website}. In this case, make sure you set the load-path correctly in your
904 (add-to-list 'load-path "~/path/to/orgdir/lisp")
907 The downloaded archive contains contributed libraries that are not included
908 in Emacs. If you want to use them, add the @file{contrib} directory to your
912 (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
915 Optionally, you can compile the files and/or install them in your system.
916 Run @code{make help} to list compilation and installation options.
918 @subsubheading Using Org's git repository
920 You can clone Org's repository and install Org like this:
924 $ git clone git://orgmode.org/org-mode.git
928 Note that in this case, @code{make autoloads} is mandatory: it defines Org's
929 version in @file{org-version.el} and Org's autoloads in
930 @file{org-loaddefs.el}.
932 Remember to add the correct load-path as described in the method above.
934 You can also compile with @code{make}, generate the documentation with
935 @code{make doc}, create a local configuration with @code{make config} and
936 install Org with @code{make install}. Please run @code{make help} to get
937 the list of compilation/installation options.
939 For more detailed explanations on Org's build system, please check the Org
940 Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
948 @cindex global key bindings
949 @cindex key bindings, global
952 @findex org-store-link
955 Org mode buffers need font-lock to be turned on: this is the default in
956 Emacs@footnote{If you don't use font-lock globally, turn it on in Org buffer
957 with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
959 There are compatibility issues between Org mode and some other Elisp
960 packages, please take the time to check the list (@pxref{Conflicts}).
962 The four Org commands @command{org-store-link}, @command{org-capture},
963 @command{org-agenda}, and @command{org-iswitchb} should be accessible through
964 global keys (i.e., anywhere in Emacs, not just in Org buffers). Here are
965 suggested bindings for these keys, please modify the keys to your own
968 (global-set-key "\C-cl" 'org-store-link)
969 (global-set-key "\C-ca" 'org-agenda)
970 (global-set-key "\C-cc" 'org-capture)
971 (global-set-key "\C-cb" 'org-iswitchb)
974 @cindex Org mode, turning on
975 Files with the @file{.org} extension use Org mode by default. To turn on Org
976 mode in a file that does not have the extension @file{.org}, make the first
977 line of a file look like this:
980 MY PROJECTS -*- mode: org; -*-
983 @vindex org-insert-mode-line-in-empty-file
984 @noindent which will select Org mode for this buffer no matter what
985 the file's name is. See also the variable
986 @code{org-insert-mode-line-in-empty-file}.
988 Many commands in Org work on the region if the region is @i{active}. To make
989 use of this, you need to have @code{transient-mark-mode} turned on, which is
990 the default. If you do not like @code{transient-mark-mode}, you can create
991 an active region by using the mouse to select a region, or pressing
992 @kbd{C-@key{SPC}} twice before moving the cursor.
1001 If you find problems with Org, or if you have questions, remarks, or ideas
1002 about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
1003 You can subscribe to the list
1004 @uref{https://lists.gnu.org/mailman/listinfo/emacs-orgmode, on this web page}.
1005 If you are not a member of the mailing list, your mail will be passed to the
1006 list after a moderator has approved it@footnote{Please consider subscribing
1007 to the mailing list, in order to minimize the work the mailing list
1008 moderators have to do.}.
1010 For bug reports, please first try to reproduce the bug with the latest
1011 version of Org available---if you are running an outdated version, it is
1012 quite possible that the bug has been fixed already. If the bug persists,
1013 prepare a report and provide as much information as possible, including the
1014 version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
1015 (@kbd{M-x org-version RET}), as well as the Org related setup in the Emacs
1016 init file. The easiest way to do this is to use the command
1018 @kbd{M-x org-submit-bug-report RET}
1020 @noindent which will put all this information into an Emacs mail buffer so
1021 that you only need to add your description. If you are not sending the Email
1022 from within Emacs, please copy and paste the content into your Email program.
1024 Sometimes you might face a problem due to an error in your Emacs or Org mode
1025 setup. Before reporting a bug, it is very helpful to start Emacs with minimal
1026 customizations and reproduce the problem. Doing so often helps you determine
1027 if the problem is with your customization or with Org mode itself. You can
1028 start a typical minimal session with a command like the example below.
1031 $ emacs -Q -l /path/to/minimal-org.el
1034 However if you are using Org mode as distributed with Emacs, a minimal setup
1035 is not necessary. In that case it is sufficient to start Emacs as
1036 @code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
1040 ;;; Minimal setup to load latest 'org-mode'
1042 ;; activate debugging
1043 (setq debug-on-error t
1047 ;; add latest org-mode to load path
1048 (add-to-list 'load-path "/path/to/org-mode/lisp")
1049 (add-to-list 'load-path "/path/to/org-mode/contrib/lisp" t)
1052 If an error occurs, a backtrace can be very useful (see below on how to
1053 create one). Often a small example file helps, along with clear information
1057 @item What exactly did you do?
1058 @item What did you expect to happen?
1059 @item What happened instead?
1061 @noindent Thank you for helping to improve this program.
1063 @subsubheading How to create a useful backtrace
1065 @cindex backtrace of an error
1066 If working with Org produces an error with a message you don't
1067 understand, you may have hit a bug. The best way to report this is by
1068 providing, in addition to what was mentioned above, a @emph{backtrace}.
1069 This is information from the built-in debugger about where and how the
1070 error occurred. Here is how to produce a useful backtrace:
1074 Reload uncompiled versions of all Org mode Lisp files. The backtrace
1075 contains much more information if it is produced with uncompiled code.
1078 @kbd{C-u M-x org-reload RET}
1081 or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
1084 Go to the @code{Options} menu and select @code{Enter Debugger on Error}.
1086 Do whatever you have to do to hit the error. Don't forget to
1087 document the steps you take.
1089 When you hit the error, a @file{*Backtrace*} buffer will appear on the
1090 screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
1091 attach it to your bug report.
1095 @section Typesetting conventions used in this manual
1097 @subsubheading TODO keywords, tags, properties, etc.
1099 Org mainly uses three types of keywords: TODO keywords, tags and property
1100 names. In this manual we use the following conventions:
1105 TODO keywords are written with all capitals, even if they are
1109 User-defined tags are written in lowercase; built-in tags with special
1110 meaning are written with all capitals.
1113 User-defined properties are capitalized; built-in properties with
1114 special meaning are written with all capitals.
1117 Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
1118 and @i{environment keywords} (like @code{#+BEGIN_EXPORT html} to start
1119 a @code{HTML} environment). They are written in uppercase in the manual to
1120 enhance its readability, but you can use lowercase in your Org file.
1122 @subsubheading Key bindings and commands
1128 The manual suggests a few global key bindings, in particular @kbd{C-c a} for
1129 @code{org-agenda} and @kbd{C-c c} for @code{org-capture}. These are only
1130 suggestions, but the rest of the manual assumes that these key bindings are in
1131 place in order to list commands by key access.
1133 Also, the manual lists both the keys and the corresponding commands for
1134 accessing a functionality. Org mode often uses the same key for different
1135 functions, depending on context. The command that is bound to such keys has
1136 a generic name, like @code{org-metaright}. In the manual we will, wherever
1137 possible, give the function that is internally called by the generic command.
1138 For example, in the chapter on document structure, @kbd{M-@key{right}} will
1139 be listed to call @code{org-do-demote}, while in the chapter on tables, it
1140 will be listed to call @code{org-table-move-column-right}. If you prefer,
1141 you can compile the manual without the command names by unsetting the flag
1142 @code{cmdnames} in @file{org.texi}.
1144 @node Document structure
1145 @chapter Document structure
1146 @cindex document structure
1147 @cindex structure of document
1149 Org is based on Outline mode and provides flexible commands to
1150 edit the structure of the document.
1153 * Outlines:: Org is based on Outline mode
1154 * Headlines:: How to typeset Org tree headlines
1155 * Visibility cycling:: Show and hide, much simplified
1156 * Motion:: Jumping to other headlines
1157 * Structure editing:: Changing sequence and level of headlines
1158 * Sparse trees:: Matches embedded in context
1159 * Plain lists:: Additional structure within an entry
1160 * Drawers:: Tucking stuff away
1161 * Blocks:: Folding blocks
1162 * Footnotes:: How footnotes are defined in Org's syntax
1163 * Orgstruct mode:: Structure editing outside Org
1164 * Org syntax:: Formal description of Org's syntax
1170 @cindex Outline mode
1172 Org is implemented on top of Outline mode. Outlines allow a
1173 document to be organized in a hierarchical structure, which (at least
1174 for me) is the best representation of notes and thoughts. An overview
1175 of this structure is achieved by folding (hiding) large parts of the
1176 document to show only the general document structure and the parts
1177 currently being worked on. Org greatly simplifies the use of
1178 outlines by compressing the entire show/hide functionality into a single
1179 command, @command{org-cycle}, which is bound to the @key{TAB} key.
1184 @cindex outline tree
1185 @vindex org-special-ctrl-a/e
1186 @vindex org-special-ctrl-k
1187 @vindex org-ctrl-k-protect-subtree
1189 Headlines define the structure of an outline tree. The headlines in Org
1190 start with one or more stars, on the left margin@footnote{See the variables
1191 @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
1192 @code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
1193 @kbd{C-e}, and @kbd{C-k} in headlines.} @footnote{Clocking only works with
1194 headings indented less than 30 stars.}. For example:
1197 * Top level headline
1204 * Another top level headline
1207 @vindex org-footnote-section
1208 @noindent Note that a headline named after @code{org-footnote-section},
1209 which defaults to @samp{Footnotes}, is considered as special. A subtree with
1210 this headline will be silently ignored by exporting functions.
1212 Some people find the many stars too noisy and would prefer an
1213 outline that has whitespace followed by a single star as headline
1214 starters. @ref{Clean view}, describes a setup to realize this.
1216 @vindex org-cycle-separator-lines
1217 An empty line after the end of a subtree is considered part of it and
1218 will be hidden when the subtree is folded. However, if you leave at
1219 least two empty lines, one empty line will remain visible after folding
1220 the subtree, in order to structure the collapsed view. See the
1221 variable @code{org-cycle-separator-lines} to modify this behavior.
1223 @node Visibility cycling
1224 @section Visibility cycling
1225 @cindex cycling, visibility
1226 @cindex visibility cycling
1227 @cindex trees, visibility
1228 @cindex show hidden text
1232 * Global and local cycling:: Cycling through various visibility states
1233 * Initial visibility:: Setting the initial visibility state
1234 * Catching invisible edits:: Preventing mistakes when editing invisible parts
1237 @node Global and local cycling
1238 @subsection Global and local cycling
1240 Outlines make it possible to hide parts of the text in the buffer.
1241 Org uses just two commands, bound to @key{TAB} and
1242 @kbd{S-@key{TAB}} to change the visibility in the buffer.
1244 @cindex subtree visibility states
1245 @cindex subtree cycling
1246 @cindex folded, subtree visibility state
1247 @cindex children, subtree visibility state
1248 @cindex subtree, subtree visibility state
1250 @orgcmd{@key{TAB},org-cycle}
1251 @emph{Subtree cycling}: Rotate current subtree among the states
1254 ,-> FOLDED -> CHILDREN -> SUBTREE --.
1255 '-----------------------------------'
1258 @vindex org-cycle-emulate-tab
1259 The cursor must be on a headline for this to work@footnote{see, however,
1260 the option @code{org-cycle-emulate-tab}.}.
1262 @cindex global visibility states
1263 @cindex global cycling
1264 @cindex overview, global visibility state
1265 @cindex contents, global visibility state
1266 @cindex show all, global visibility state
1267 @orgcmd{S-@key{TAB},org-global-cycle}
1268 @itemx C-u @key{TAB}
1269 @emph{Global cycling}: Rotate the entire buffer among the states
1272 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
1273 '--------------------------------------'
1276 When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the
1277 CONTENTS view up to headlines of level N will be shown. Note that inside
1278 tables, @kbd{S-@key{TAB}} jumps to the previous field.
1280 @vindex org-cycle-global-at-bob
1281 You can run global cycling using @key{TAB} only if point is at the very
1282 beginning of the buffer, but not on a headline, and
1283 @code{org-cycle-global-at-bob} is set to a non-@code{nil} value.
1285 @cindex set startup visibility, command
1286 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1287 Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
1288 @cindex show all, command
1289 @orgcmd{C-u C-u C-u @key{TAB},outline-show-all}
1290 Show all, including drawers.
1291 @cindex revealing context
1292 @orgcmd{C-c C-r,org-reveal}
1293 Reveal context around point, showing the current entry, the following heading
1294 and the hierarchy above. Useful for working near a location that has been
1295 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
1296 (@pxref{Agenda commands}). With a prefix argument show, on each
1297 level, all sibling headings. With a double prefix argument, also show the
1298 entire subtree of the parent.
1299 @cindex show branches, command
1300 @orgcmd{C-c C-k,outline-show-branches}
1301 Expose all the headings of the subtree, CONTENTS view for just one subtree.
1302 @cindex show children, command
1303 @orgcmd{C-c @key{TAB},outline-show-children}
1304 Expose all direct children of the subtree. With a numeric prefix argument N,
1305 expose all children down to level N@.
1306 @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
1307 Show the current subtree in an indirect buffer@footnote{The indirect buffer
1308 (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) will contain the entire
1309 buffer, but will be narrowed to the current tree. Editing the indirect
1310 buffer will also change the original buffer, but without affecting visibility
1311 in that buffer.}. With a numeric prefix argument N, go up to level N and
1312 then take that tree. If N is negative then go up that many levels. With
1313 a @kbd{C-u} prefix, do not remove the previously used indirect buffer.
1314 @orgcmd{C-c C-x v,org-copy-visible}
1315 Copy the @i{visible} text in the region into the kill ring.
1318 @node Initial visibility
1319 @subsection Initial visibility
1321 @cindex visibility, initialize
1322 @vindex org-startup-folded
1323 @vindex org-agenda-inhibit-startup
1324 @cindex @code{overview}, STARTUP keyword
1325 @cindex @code{content}, STARTUP keyword
1326 @cindex @code{showall}, STARTUP keyword
1327 @cindex @code{showeverything}, STARTUP keyword
1329 When Emacs first visits an Org file, the global state is set to OVERVIEW,
1330 i.e., only the top level headlines are visible@footnote{When
1331 @code{org-agenda-inhibit-startup} is non-@code{nil}, Org will not honor the default
1332 visibility state when first opening a file for the agenda (@pxref{Speeding up
1333 your agendas}).}. This can be configured through the variable
1334 @code{org-startup-folded}, or on a per-file basis by adding one of the
1335 following lines anywhere in the buffer:
1341 #+STARTUP: showeverything
1344 @cindex property, VISIBILITY
1346 Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
1347 and columns}) will get their visibility adapted accordingly. Allowed values
1348 for this property are @code{folded}, @code{children}, @code{content}, and
1352 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1353 Switch back to the startup visibility of the buffer, i.e., whatever is
1354 requested by startup options and @samp{VISIBILITY} properties in individual
1358 @node Catching invisible edits
1359 @subsection Catching invisible edits
1361 @vindex org-catch-invisible-edits
1362 @cindex edits, catching invisible
1363 Sometimes you may inadvertently edit an invisible part of the buffer and be
1364 confused on what has been edited and how to undo the mistake. Setting
1365 @code{org-catch-invisible-edits} to non-@code{nil} will help prevent this. See the
1366 docstring of this option on how Org should catch invisible edits and process
1371 @cindex motion, between headlines
1372 @cindex jumping, to headlines
1373 @cindex headline navigation
1374 The following commands jump to other headlines in the buffer.
1377 @orgcmd{C-c C-n,org-next-visible-heading}
1379 @orgcmd{C-c C-p,org-previous-visible-heading}
1381 @orgcmd{C-c C-f,org-forward-same-level}
1382 Next heading same level.
1383 @orgcmd{C-c C-b,org-backward-same-level}
1384 Previous heading same level.
1385 @orgcmd{C-c C-u,outline-up-heading}
1386 Backward to higher level heading.
1387 @orgcmd{C-c C-j,org-goto}
1388 Jump to a different place without changing the current outline
1389 visibility. Shows the document structure in a temporary buffer, where
1390 you can use the following keys to find your destination:
1391 @vindex org-goto-auto-isearch
1393 @key{TAB} @r{Cycle visibility.}
1394 @key{down} / @key{up} @r{Next/previous visible headline.}
1395 @key{RET} @r{Select this location.}
1396 @kbd{/} @r{Do a Sparse-tree search}
1397 @r{The following keys work if you turn off @code{org-goto-auto-isearch}}
1398 n / p @r{Next/previous visible headline.}
1399 f / b @r{Next/previous headline same level.}
1401 0-9 @r{Digit argument.}
1404 @vindex org-goto-interface
1406 See also the option @code{org-goto-interface}.
1409 @node Structure editing
1410 @section Structure editing
1411 @cindex structure editing
1412 @cindex headline, promotion and demotion
1413 @cindex promotion, of subtrees
1414 @cindex demotion, of subtrees
1415 @cindex subtree, cut and paste
1416 @cindex pasting, of subtrees
1417 @cindex cutting, of subtrees
1418 @cindex copying, of subtrees
1419 @cindex sorting, of subtrees
1420 @cindex subtrees, cut and paste
1423 @orgcmd{M-@key{RET},org-meta-return}
1424 @vindex org-M-RET-may-split-line
1425 Insert a new heading, item or row.
1427 If the command is used at the @emph{beginning} of a line, and if there is
1428 a heading or a plain list item (@pxref{Plain lists}) at point, the new
1429 heading/item is created @emph{before} the current line. When used at the
1430 beginning of a regular line of text, turn that line into a heading.
1432 When this command is used in the middle of a line, the line is split and the
1433 rest of the line becomes the new item or headline. If you do not want the
1434 line to be split, customize @code{org-M-RET-may-split-line}.
1436 Calling the command with a @kbd{C-u} prefix unconditionally inserts a new
1437 heading at the end of the current subtree, thus preserving its contents.
1438 With a double @kbd{C-u C-u} prefix, the new heading is created at the end of
1439 the parent subtree instead.
1440 @orgcmd{C-@key{RET},org-insert-heading-respect-content}
1441 Insert a new heading at the end of the current subtree.
1442 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
1443 @vindex org-treat-insert-todo-heading-as-state-change
1444 Insert new TODO entry with same level as current heading. See also the
1445 variable @code{org-treat-insert-todo-heading-as-state-change}.
1446 @orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
1447 Insert new TODO entry with same level as current heading. Like
1448 @kbd{C-@key{RET}}, the new headline will be inserted after the current
1450 @orgcmd{@key{TAB},org-cycle}
1451 In a new entry with no text yet, the first @key{TAB} demotes the entry to
1452 become a child of the previous one. The next @key{TAB} makes it a parent,
1453 and so on, all the way to top level. Yet another @key{TAB}, and you are back
1454 to the initial level.
1455 @orgcmd{M-@key{left},org-do-promote}
1456 Promote current heading by one level.
1457 @orgcmd{M-@key{right},org-do-demote}
1458 Demote current heading by one level.
1459 @orgcmd{M-S-@key{left},org-promote-subtree}
1460 Promote the current subtree by one level.
1461 @orgcmd{M-S-@key{right},org-demote-subtree}
1462 Demote the current subtree by one level.
1463 @orgcmd{M-@key{up},org-move-subtree-up}
1464 Move subtree up (swap with previous subtree of same
1466 @orgcmd{M-@key{down},org-move-subtree-down}
1467 Move subtree down (swap with next subtree of same level).
1468 @orgcmd{M-h,org-mark-element}
1469 Mark the element at point. Hitting repeatedly will mark subsequent elements
1470 of the one just marked. E.g., hitting @key{M-h} on a paragraph will mark it,
1471 hitting @key{M-h} immediately again will mark the next one.
1472 @orgcmd{C-c @@,org-mark-subtree}
1473 Mark the subtree at point. Hitting repeatedly will mark subsequent subtrees
1474 of the same level than the marked subtree.
1475 @orgcmd{C-c C-x C-w,org-cut-subtree}
1476 Kill subtree, i.e., remove it from buffer but save in kill ring.
1477 With a numeric prefix argument N, kill N sequential subtrees.
1478 @orgcmd{C-c C-x M-w,org-copy-subtree}
1479 Copy subtree to kill ring. With a numeric prefix argument N, copy the N
1480 sequential subtrees.
1481 @orgcmd{C-c C-x C-y,org-paste-subtree}
1482 Yank subtree from kill ring. This does modify the level of the subtree to
1483 make sure the tree fits in nicely at the yank position. The yank level can
1484 also be specified with a numeric prefix argument, or by yanking after a
1485 headline marker like @samp{****}.
1486 @orgcmd{C-y,org-yank}
1487 @vindex org-yank-adjusted-subtrees
1488 @vindex org-yank-folded-subtrees
1489 Depending on the options @code{org-yank-adjusted-subtrees} and
1490 @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
1491 paste subtrees folded and in a clever way, using the same command as @kbd{C-c
1492 C-x C-y}. With the default settings, no level adjustment will take place,
1493 but the yanked tree will be folded unless doing so would swallow text
1494 previously visible. Any prefix argument to this command will force a normal
1495 @code{yank} to be executed, with the prefix passed along. A good way to
1496 force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a
1497 yank, it will yank previous kill items plainly, without adjustment and
1499 @orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
1500 Clone a subtree by making a number of sibling copies of it. You will be
1501 prompted for the number of copies to make, and you can also specify if any
1502 timestamps in the entry should be shifted. This can be useful, for example,
1503 to create a number of tasks related to a series of lectures to prepare. For
1504 more details, see the docstring of the command
1505 @code{org-clone-subtree-with-time-shift}.
1506 @orgcmd{C-c C-w,org-refile}
1507 Refile entry or region to a different location. @xref{Refile and copy}.
1508 @orgcmd{C-c ^,org-sort}
1509 Sort same-level entries. When there is an active region, all entries in the
1510 region will be sorted. Otherwise the children of the current headline are
1511 sorted. The command prompts for the sorting method, which can be
1512 alphabetically, numerically, by time (first timestamp with active preferred,
1513 creation time, scheduled time, deadline time), by priority, by TODO keyword
1514 (in the sequence the keywords have been defined in the setup) or by the value
1515 of a property. Reverse sorting is possible as well. You can also supply
1516 your own function to extract the sorting key. With a @kbd{C-u} prefix,
1517 sorting will be case-sensitive.
1518 @orgcmd{C-x n s,org-narrow-to-subtree}
1519 Narrow buffer to current subtree.
1520 @orgcmd{C-x n b,org-narrow-to-block}
1521 Narrow buffer to current block.
1522 @orgcmd{C-x n w,widen}
1523 Widen buffer to remove narrowing.
1524 @orgcmd{C-c *,org-toggle-heading}
1525 Turn a normal line or plain list item into a headline (so that it becomes a
1526 subheading at its location). Also turn a headline into a normal line by
1527 removing the stars. If there is an active region, turn all lines in the
1528 region into headlines. If the first line in the region was an item, turn
1529 only the item lines into headlines. Finally, if the first line is a
1530 headline, remove the stars from all headlines in the region.
1533 @cindex region, active
1534 @cindex active region
1535 @cindex transient mark mode
1536 When there is an active region (Transient Mark mode), promotion and
1537 demotion work on all headlines in the region. To select a region of
1538 headlines, it is best to place both point and mark at the beginning of a
1539 line, mark at the beginning of the first headline, and point at the line
1540 just after the last headline to change. Note that when the cursor is
1541 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
1546 @section Sparse trees
1547 @cindex sparse trees
1548 @cindex trees, sparse
1549 @cindex folding, sparse trees
1550 @cindex occur, command
1552 @vindex org-show-context-detail
1553 An important feature of Org mode is the ability to construct @emph{sparse
1554 trees} for selected information in an outline tree, so that the entire
1555 document is folded as much as possible, but the selected information is made
1556 visible along with the headline structure above it@footnote{See also the
1557 variable @code{org-show-context-detail} to decide how much context is shown
1558 around each match.}. Just try it out and you will see immediately how it
1561 Org mode contains several commands for creating such trees, all these
1562 commands can be accessed through a dispatcher:
1565 @orgcmd{C-c /,org-sparse-tree}
1566 This prompts for an extra key to select a sparse-tree creating command.
1567 @orgcmdkkc{C-c / r,C-c / /,org-occur}
1568 @vindex org-remove-highlights-with-change
1569 Prompts for a regexp and shows a sparse tree with all matches. If
1570 the match is in a headline, the headline is made visible. If the match is in
1571 the body of an entry, headline and body are made visible. In order to
1572 provide minimal context, also the full hierarchy of headlines above the match
1573 is shown, as well as the headline following the match. Each match is also
1574 highlighted; the highlights disappear when the buffer is changed by an
1575 editing command@footnote{This depends on the option
1576 @code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
1577 When called with a @kbd{C-u} prefix argument, previous highlights are kept,
1578 so several calls to this command can be stacked.
1579 @orgcmdkkc{M-g n,M-g M-n,next-error}
1580 Jump to the next sparse tree match in this buffer.
1581 @orgcmdkkc{M-g p,M-g M-p,previous-error}
1582 Jump to the previous sparse tree match in this buffer.
1586 @vindex org-agenda-custom-commands
1587 For frequently used sparse trees of specific search strings, you can
1588 use the option @code{org-agenda-custom-commands} to define fast
1589 keyboard access to specific sparse trees. These commands will then be
1590 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
1594 (setq org-agenda-custom-commands
1595 '(("f" occur-tree "FIXME")))
1598 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
1599 a sparse tree matching the string @samp{FIXME}.
1601 The other sparse tree commands select headings based on TODO keywords,
1602 tags, or properties and will be discussed later in this manual.
1605 @cindex printing sparse trees
1606 @cindex visible text, printing
1607 To print a sparse tree, you can use the Emacs command
1608 @code{ps-print-buffer-with-faces} which does not print invisible parts of the
1609 document. Or you can use @kbd{C-c C-e C-v} to export only the visible part
1610 of the document and print the resulting file.
1613 @section Plain lists
1615 @cindex lists, plain
1616 @cindex lists, ordered
1617 @cindex ordered lists
1619 Within an entry of the outline tree, hand-formatted lists can provide
1620 additional structure. They also provide a way to create lists of checkboxes
1621 (@pxref{Checkboxes}). Org supports editing such lists, and every exporter
1622 (@pxref{Exporting}) can parse and format them.
1624 Org knows ordered lists, unordered lists, and description lists.
1627 @emph{Unordered} list items start with @samp{-}, @samp{+}, or
1628 @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
1629 they will be seen as top-level headlines. Also, when you are hiding leading
1630 stars to get a clean outline view, plain list items starting with a star may
1631 be hard to distinguish from true headlines. In short: even though @samp{*}
1632 is supported, it may be better to not use it for plain list items.} as
1635 @vindex org-plain-list-ordered-item-terminator
1636 @vindex org-list-allow-alphabetical
1637 @emph{Ordered} list items start with a numeral followed by either a period or
1638 a right parenthesis@footnote{You can filter out any of them by configuring
1639 @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
1640 @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
1641 @samp{A)} by configuring @code{org-list-allow-alphabetical}. To minimize
1642 confusion with normal text, those are limited to one character only. Beyond
1643 that limit, bullets will automatically fallback to numbers.}. If you want a
1644 list to start with a different value (e.g., 20), start the text of the item
1645 with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
1646 must be put @emph{before} the checkbox. If you have activated alphabetical
1647 lists, you can also use counters like @code{[@@b]}.}. Those constructs can
1648 be used in any item of the list in order to enforce a particular numbering.
1650 @emph{Description} list items are unordered list items, and contain the
1651 separator @samp{ :: } to distinguish the description @emph{term} from the
1655 Items belonging to the same list must have the same indentation on the first
1656 line. In particular, if an ordered list reaches number @samp{10.}, then the
1657 2--digit numbers must be written left-aligned with the other numbers in the
1658 list. An item ends before the next line that is less or equally indented
1659 than its bullet/number.
1661 A list ends whenever every item has ended, which means before any line less
1662 or equally indented than items at top level. It also ends before two blank
1663 lines. In that case, all items are closed. Here is an example:
1667 ** Lord of the Rings
1668 My favorite scenes are (in this order)
1669 1. The attack of the Rohirrim
1670 2. Eowyn's fight with the witch king
1671 + this was already my favorite scene in the book
1672 + I really like Miranda Otto.
1673 3. Peter Jackson being shot by Legolas
1675 He makes a really funny face when it happens.
1676 But in the end, no individual scenes matter but the film as a whole.
1677 Important actors in this film are:
1678 - @b{Elijah Wood} :: He plays Frodo
1679 - @b{Sean Astin} :: He plays Sam, Frodo's friend. I still remember
1680 him very well from his role as Mikey Walsh in @i{The Goonies}.
1684 Org supports these lists by tuning filling and wrapping commands to deal with
1685 them correctly, and by exporting them properly (@pxref{Exporting}). Since
1686 indentation is what governs the structure of these lists, many structural
1687 constructs like @code{#+BEGIN_...} blocks can be indented to signal that they
1688 belong to a particular item.
1690 @vindex org-list-demote-modify-bullet
1691 @vindex org-list-indent-offset
1692 If you find that using a different bullet for a sub-list (than that used for
1693 the current list-level) improves readability, customize the variable
1694 @code{org-list-demote-modify-bullet}. To get a greater difference of
1695 indentation between items and their sub-items, customize
1696 @code{org-list-indent-offset}.
1698 @vindex org-list-automatic-rules
1699 The following commands act on items when the cursor is in the first line of
1700 an item (the line with the bullet or number). Some of them imply the
1701 application of automatic rules to keep list structure intact. If some of
1702 these actions get in your way, configure @code{org-list-automatic-rules}
1703 to disable them individually.
1706 @orgcmd{@key{TAB},org-cycle}
1707 @cindex cycling, in plain lists
1708 @vindex org-cycle-include-plain-lists
1709 Items can be folded just like headline levels. Normally this works only if
1710 the cursor is on a plain list item. For more details, see the variable
1711 @code{org-cycle-include-plain-lists}. If this variable is set to
1712 @code{integrate}, plain list items will be treated like low-level
1713 headlines. The level of an item is then given by the indentation of the
1714 bullet/number. Items are always subordinate to real headlines, however; the
1715 hierarchies remain completely separated. In a new item with no text yet, the
1716 first @key{TAB} demotes the item to become a child of the previous
1717 one. Subsequent @key{TAB}s move the item to meaningful levels in the list
1718 and eventually get it back to its initial position.
1719 @orgcmd{M-@key{RET},org-insert-heading}
1720 @vindex org-M-RET-may-split-line
1721 @vindex org-list-automatic-rules
1722 Insert new item at current level. With a prefix argument, force a new
1723 heading (@pxref{Structure editing}). If this command is used in the middle
1724 of an item, that item is @emph{split} in two, and the second part becomes the
1725 new item@footnote{If you do not want the item to be split, customize the
1726 variable @code{org-M-RET-may-split-line}.}. If this command is executed
1727 @emph{before item's body}, the new item is created @emph{before} the current
1732 @kindex M-S-@key{RET}
1734 Insert a new item with a checkbox (@pxref{Checkboxes}).
1735 @kindex S-@key{down}
1738 @cindex shift-selection-mode
1739 @vindex org-support-shift-select
1740 @vindex org-list-use-circular-motion
1741 Jump to the previous/next item in the current list@footnote{If you want to
1742 cycle around items that way, you may customize
1743 @code{org-list-use-circular-motion}.}, but only if
1744 @code{org-support-shift-select} is off. If not, you can still use paragraph
1745 jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
1748 @kindex M-@key{down}
1751 Move the item including subitems up/down@footnote{See
1752 @code{org-list-use-circular-motion} for a cyclic behavior.} (swap with
1753 previous/next item of same indentation). If the list is ordered, renumbering
1755 @kindex M-@key{left}
1756 @kindex M-@key{right}
1759 Decrease/increase the indentation of an item, leaving children alone.
1760 @kindex M-S-@key{left}
1761 @kindex M-S-@key{right}
1762 @item M-S-@key{left}
1763 @itemx M-S-@key{right}
1764 Decrease/increase the indentation of the item, including subitems.
1765 Initially, the item tree is selected based on current indentation. When
1766 these commands are executed several times in direct succession, the initially
1767 selected region is used, even if the new indentation would imply a different
1768 hierarchy. To use the new hierarchy, break the command chain with a cursor
1771 As a special case, using this command on the very first item of a list will
1772 move the whole list. This behavior can be disabled by configuring
1773 @code{org-list-automatic-rules}. The global indentation of a list has no
1774 influence on the text @emph{after} the list.
1777 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1778 state of the checkbox. In any case, verify bullets and indentation
1779 consistency in the whole list.
1781 @vindex org-plain-list-ordered-item-terminator
1783 Cycle the entire list level through the different itemize/enumerate bullets
1784 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
1785 depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
1786 and its indentation. With a numeric prefix argument N, select the Nth bullet
1787 from this list. If there is an active region when calling this, all selected
1788 lines are converted to list items. With a prefix argument, selected text is
1789 changed into a single item. If the first line already was a list item, any
1790 item marker will be removed from the list. Finally, even without an active
1791 region, a normal line will be converted into a list item.
1794 Turn a plain list item into a headline (so that it becomes a subheading at
1795 its location). @xref{Structure editing}, for a detailed explanation.
1798 Turn the whole plain list into a subtree of the current heading. Checkboxes
1799 (@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
1801 @kindex S-@key{left}
1802 @kindex S-@key{right}
1804 @vindex org-support-shift-select
1805 This command also cycles bullet styles when the cursor in on the bullet or
1806 anywhere in an item line, details depending on
1807 @code{org-support-shift-select}.
1809 @cindex sorting, of plain list
1811 Sort the plain list. You will be prompted for the sorting method:
1812 numerically, alphabetically, by time, by checked status for check lists,
1813 or by a custom function.
1819 @cindex visibility cycling, drawers
1821 @cindex org-insert-drawer
1823 Sometimes you want to keep information associated with an entry, but you
1824 normally don't want to see it. For this, Org mode has @emph{drawers}. They
1825 can contain anything but a headline and another drawer. Drawers look like
1829 ** This is a headline
1830 Still outside the drawer
1832 This is inside the drawer.
1837 You can interactively insert drawers at point by calling
1838 @code{org-insert-drawer}, which is bound to @key{C-c C-x d}. With an active
1839 region, this command will put the region inside the drawer. With a prefix
1840 argument, this command calls @code{org-insert-property-drawer} and add
1841 a property drawer right below the current headline. Completion over drawer
1842 keywords is also possible using @kbd{M-@key{TAB}}@footnote{Many desktops
1843 intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
1844 @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}.
1846 Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
1847 show the entry, but keep the drawer collapsed to a single line. In order to
1848 look inside the drawer, you need to move the cursor to the drawer line and
1849 press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
1850 storing properties (@pxref{Properties and columns}), and you can also arrange
1851 for state change notes (@pxref{Tracking TODO state changes}) and clock times
1852 (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
1853 want to store a quick note in the LOGBOOK drawer, in a similar way to state
1859 Add a time-stamped note to the LOGBOOK drawer.
1862 @vindex org-export-with-drawers
1863 @vindex org-export-with-properties
1864 You can select the name of the drawers which should be exported with
1865 @code{org-export-with-drawers}. In that case, drawer contents will appear in
1866 export output. Property drawers are not affected by this variable: configure
1867 @code{org-export-with-properties} instead.
1872 @vindex org-hide-block-startup
1873 @cindex blocks, folding
1874 Org mode uses begin...end blocks for various purposes from including source
1875 code examples (@pxref{Literal examples}) to capturing time logging
1876 information (@pxref{Clocking work time}). These blocks can be folded and
1877 unfolded by pressing TAB in the begin line. You can also get all blocks
1878 folded at startup by configuring the option @code{org-hide-block-startup}
1879 or on a per-file basis by using
1881 @cindex @code{hideblocks}, STARTUP keyword
1882 @cindex @code{nohideblocks}, STARTUP keyword
1884 #+STARTUP: hideblocks
1885 #+STARTUP: nohideblocks
1892 Org mode supports the creation of footnotes.
1894 A footnote is started by a footnote marker in square brackets in column 0, no
1895 indentation allowed. It ends at the next footnote definition, headline, or
1896 after two consecutive empty lines. The footnote reference is simply the
1897 marker in square brackets, inside text. Markers always start with
1898 @code{fn:}. For example:
1901 The Org homepage[fn:1] now looks a lot better than it used to.
1903 [fn:1] The link is: http://orgmode.org
1906 Org mode extends the number-based syntax to @emph{named} footnotes and
1907 optional inline definition. Here are the valid references:
1911 A named footnote reference, where @code{name} is a unique label word, or, for
1912 simplicity of automatic creation, a number.
1913 @item [fn::This is the inline definition of this footnote]
1914 A @LaTeX{}-like anonymous footnote where the definition is given directly at the
1916 @item [fn:name:a definition]
1917 An inline definition of a footnote, which also specifies a name for the note.
1918 Since Org allows multiple references to the same note, you can then use
1919 @code{[fn:name]} to create additional references.
1922 @vindex org-footnote-auto-label
1923 Footnote labels can be created automatically, or you can create names yourself.
1924 This is handled by the variable @code{org-footnote-auto-label} and its
1925 corresponding @code{#+STARTUP} keywords. See the docstring of that variable
1928 @noindent The following command handles footnotes:
1933 The footnote action command.
1935 When the cursor is on a footnote reference, jump to the definition. When it
1936 is at a definition, jump to the (first) reference.
1938 @vindex org-footnote-define-inline
1939 @vindex org-footnote-section
1940 @vindex org-footnote-auto-adjust
1941 Otherwise, create a new footnote. Depending on the option
1942 @code{org-footnote-define-inline}@footnote{The corresponding in-buffer
1943 setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
1944 definition will be placed right into the text as part of the reference, or
1945 separately into the location determined by the option
1946 @code{org-footnote-section}.
1948 When this command is called with a prefix argument, a menu of additional
1951 s @r{Sort the footnote definitions by reference sequence. During editing,}
1952 @r{Org makes no effort to sort footnote definitions into a particular}
1953 @r{sequence. If you want them sorted, use this command, which will}
1954 @r{also move entries according to @code{org-footnote-section}. Automatic}
1955 @r{sorting after each insertion/deletion can be configured using the}
1956 @r{option @code{org-footnote-auto-adjust}.}
1957 r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering}
1958 @r{after each insertion/deletion can be configured using the option}
1959 @r{@code{org-footnote-auto-adjust}.}
1960 S @r{Short for first @code{r}, then @code{s} action.}
1961 n @r{Normalize the footnotes by collecting all definitions (including}
1962 @r{inline definitions) into a special section, and then numbering them}
1963 @r{in sequence. The references will then also be numbers.}
1964 d @r{Delete the footnote at point, and all definitions of and references}
1967 Depending on the variable @code{org-footnote-auto-adjust}@footnote{the
1968 corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},
1969 renumbering and sorting footnotes can be automatic after each insertion or
1974 If the cursor is on a footnote reference, jump to the definition. If it is a
1975 the definition, jump back to the reference. When called at a footnote
1976 location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
1980 @item C-c C-o @r{or} mouse-1/2
1981 Footnote labels are also links to the corresponding definition/reference, and
1982 you can use the usual commands to follow these links.
1984 @vindex org-edit-footnote-reference
1988 Edit the footnote definition corresponding to the reference at point in
1989 a separate window. The window can be closed by pressing @kbd{C-c '}.
1993 @node Orgstruct mode
1994 @section The Orgstruct minor mode
1995 @cindex Orgstruct mode
1996 @cindex minor mode for structure editing
1998 If you like the intuitive way the Org mode structure editing and list
1999 formatting works, you might want to use these commands in other modes like
2000 Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes
2001 this possible. Toggle the mode with @kbd{M-x orgstruct-mode RET}, or
2002 turn it on by default, for example in Message mode, with one of:
2005 (add-hook 'message-mode-hook 'turn-on-orgstruct)
2006 (add-hook 'message-mode-hook 'turn-on-orgstruct++)
2009 When this mode is active and the cursor is on a line that looks to Org like a
2010 headline or the first line of a list item, most structure editing commands
2011 will work, even if the same keys normally have different functionality in the
2012 major mode you are using. If the cursor is not in one of those special
2013 lines, Orgstruct mode lurks silently in the shadows.
2015 When you use @code{orgstruct++-mode}, Org will also export indentation and
2016 autofill settings into that mode, and detect item context after the first
2019 @vindex orgstruct-heading-prefix-regexp
2020 You can also use Org structure editing to fold and unfold headlines in
2021 @emph{any} file, provided you defined @code{orgstruct-heading-prefix-regexp}:
2022 the regular expression must match the local prefix to use before Org's
2023 headlines. For example, if you set this variable to @code{";; "} in Emacs
2024 Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
2025 commented lines. Some commands like @code{org-demote} are disabled when the
2026 prefix is set, but folding/unfolding will work correctly.
2032 A reference document providing a formal description of Org's syntax is
2033 available as @uref{http://orgmode.org/worg/dev/org-syntax.html, a draft on
2034 Worg}, written and maintained by Nicolas Goaziou. It defines Org's core
2035 internal concepts such as @code{headlines}, @code{sections}, @code{affiliated
2036 keywords}, @code{(greater) elements} and @code{objects}. Each part of an Org
2037 file falls into one of the categories above.
2039 To explore the abstract structure of an Org buffer, run this in a buffer:
2042 M-: (org-element-parse-buffer) RET
2045 It will output a list containing the buffer's content represented as an
2046 abstract structure. The export engine relies on the information stored in
2047 this list. Most interactive commands (e.g., for structure editing) also
2048 rely on the syntactic meaning of the surrounding context.
2050 @cindex syntax checker
2052 You can check syntax in your documents using @code{org-lint} command.
2057 @cindex editing tables
2059 Org comes with a fast and intuitive table editor. Spreadsheet-like
2060 calculations are supported using the Emacs @file{calc} package
2061 (@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}).
2064 * Built-in table editor:: Simple tables
2065 * Column width and alignment:: Overrule the automatic settings
2066 * Column groups:: Grouping to trigger vertical lines
2067 * Orgtbl mode:: The table editor as minor mode
2068 * The spreadsheet:: The table editor has spreadsheet capabilities
2069 * Org-Plot:: Plotting from org tables
2072 @node Built-in table editor
2073 @section The built-in table editor
2074 @cindex table editor, built-in
2076 Org makes it easy to format tables in plain ASCII@. Any line with @samp{|} as
2077 the first non-whitespace character is considered part of a table. @samp{|}
2078 is also the column separator@footnote{To insert a vertical bar into a table
2079 field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table
2080 might look like this:
2083 | Name | Phone | Age |
2084 |-------+-------+-----|
2085 | Peter | 1234 | 17 |
2086 | Anna | 4321 | 25 |
2089 A table is re-aligned automatically each time you press @key{TAB} or
2090 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
2091 the next field (@key{RET} to the next row) and creates new table rows
2092 at the end of the table or before horizontal lines. The indentation
2093 of the table is set by the first line. Any line starting with
2094 @samp{|-} is considered as a horizontal separator line and will be
2095 expanded on the next re-align to span the whole table width. So, to
2096 create the above table, you would only type
2103 @noindent and then press @key{TAB} to align the table and start filling in
2104 fields. Even faster would be to type @code{|Name|Phone|Age} followed by
2105 @kbd{C-c @key{RET}}.
2107 @vindex org-table-auto-blank-field
2108 When typing text into a field, Org treats @key{DEL}, @key{Backspace}, and all
2109 character keys in a special way, so that inserting and deleting avoids
2110 shifting other fields. Also, when typing @emph{immediately after the cursor
2111 was moved into a new field with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or
2112 @kbd{@key{RET}}}, the field is automatically made blank. If this behavior is
2113 too unpredictable for you, configure the option
2114 @code{org-table-auto-blank-field}.
2117 @tsubheading{Creation and conversion}
2118 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2119 Convert the active region to a table. If every line contains at least one
2120 TAB character, the function assumes that the material is tab separated.
2121 If every line contains a comma, comma-separated values (CSV) are assumed.
2122 If not, lines are split at whitespace into fields. You can use a prefix
2123 argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
2124 C-u} forces TAB, @kbd{C-u C-u C-u} will prompt for a regular expression to
2125 match the separator, and a numeric argument N indicates that at least N
2126 consecutive spaces, or alternatively a TAB will be the separator.
2128 If there is no active region, this command creates an empty Org
2129 table. But it is easier just to start typing, like
2130 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
2132 @tsubheading{Re-aligning and field motion}
2133 @orgcmd{C-c C-c,org-table-align}
2134 Re-align the table and don't move to another field.
2136 @orgcmd{C-c SPC,org-table-blank-field}
2137 Blank the field at point.
2139 @orgcmd{TAB,org-table-next-field}
2140 Re-align the table, move to the next field. Creates a new row if
2143 @orgcmd{S-@key{TAB},org-table-previous-field}
2144 Re-align, move to previous field.
2146 @orgcmd{@key{RET},org-table-next-row}
2147 Re-align the table and move down to next row. Creates a new row if
2148 necessary. At the beginning or end of a line, @key{RET} still does
2149 NEWLINE, so it can be used to split a table.
2151 @orgcmd{M-a,org-table-beginning-of-field}
2152 Move to beginning of the current table field, or on to the previous field.
2153 @orgcmd{M-e,org-table-end-of-field}
2154 Move to end of the current table field, or on to the next field.
2156 @tsubheading{Column and row editing}
2157 @orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
2158 Move the current column left/right.
2160 @orgcmd{M-S-@key{left},org-table-delete-column}
2161 Kill the current column.
2163 @orgcmd{M-S-@key{right},org-table-insert-column}
2164 Insert a new column to the left of the cursor position.
2166 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
2167 Move the current row up/down.
2169 @orgcmd{M-S-@key{up},org-table-kill-row}
2170 Kill the current row or horizontal line.
2172 @orgcmd{M-S-@key{down},org-table-insert-row}
2173 Insert a new row above the current row. With a prefix argument, the line is
2174 created below the current one.
2176 @orgcmd{C-c -,org-table-insert-hline}
2177 Insert a horizontal line below current row. With a prefix argument, the line
2178 is created above the current line.
2180 @orgcmd{C-c @key{RET},org-table-hline-and-move}
2181 Insert a horizontal line below current row, and move the cursor into the row
2184 @orgcmd{C-c ^,org-table-sort-lines}
2185 Sort the table lines in the region. The position of point indicates the
2186 column to be used for sorting, and the range of lines is the range
2187 between the nearest horizontal separator lines, or the entire table. If
2188 point is before the first column, you will be prompted for the sorting
2189 column. If there is an active region, the mark specifies the first line
2190 and the sorting column, while point should be in the last line to be
2191 included into the sorting. The command prompts for the sorting type
2192 (alphabetically, numerically, or by time). You can sort in normal or
2193 reverse order. You can also supply your own key extraction and comparison
2194 functions. When called with a prefix argument, alphabetic sorting will be
2197 @tsubheading{Regions}
2198 @orgcmd{C-c C-x M-w,org-table-copy-region}
2199 Copy a rectangular region from a table to a special clipboard. Point and
2200 mark determine edge fields of the rectangle. If there is no active region,
2201 copy just the current field. The process ignores horizontal separator lines.
2203 @orgcmd{C-c C-x C-w,org-table-cut-region}
2204 Copy a rectangular region from a table to a special clipboard, and
2205 blank all fields in the rectangle. So this is the ``cut'' operation.
2207 @orgcmd{C-c C-x C-y,org-table-paste-rectangle}
2208 Paste a rectangular region into a table.
2209 The upper left corner ends up in the current field. All involved fields
2210 will be overwritten. If the rectangle does not fit into the present table,
2211 the table is enlarged as needed. The process ignores horizontal separator
2214 @orgcmd{M-@key{RET},org-table-wrap-region}
2215 Split the current field at the cursor position and move the rest to the line
2216 below. If there is an active region, and both point and mark are in the same
2217 column, the text in the column is wrapped to minimum width for the given
2218 number of lines. A numeric prefix argument may be used to change the number
2219 of desired lines. If there is no region, but you specify a prefix argument,
2220 the current field is made blank, and the content is appended to the field
2223 @tsubheading{Calculations}
2224 @cindex formula, in tables
2225 @cindex calculations, in tables
2226 @cindex region, active
2227 @cindex active region
2228 @cindex transient mark mode
2229 @orgcmd{C-c +,org-table-sum}
2230 Sum the numbers in the current column, or in the rectangle defined by
2231 the active region. The result is shown in the echo area and can
2232 be inserted with @kbd{C-y}.
2234 @orgcmd{S-@key{RET},org-table-copy-down}
2235 @vindex org-table-copy-increment
2236 When current field is empty, copy from first non-empty field above. When not
2237 empty, copy current field down to next row and move cursor along with it.
2238 Depending on the option @code{org-table-copy-increment}, integer field
2239 values will be incremented during copy. Integers that are too large will not
2240 be incremented. Also, a @code{0} prefix argument temporarily disables the
2241 increment. This key is also used by shift-selection and related modes
2242 (@pxref{Conflicts}).
2244 @tsubheading{Miscellaneous}
2245 @orgcmd{C-c `,org-table-edit-field}
2246 Edit the current field in a separate window. This is useful for fields that
2247 are not fully visible (@pxref{Column width and alignment}). When called with
2248 a @kbd{C-u} prefix, just make the full field visible, so that it can be
2249 edited in place. When called with two @kbd{C-u} prefixes, make the editor
2250 window follow the cursor through the table and always show the current
2251 field. The follow mode exits automatically when the cursor leaves the table,
2252 or when you repeat this command with @kbd{C-u C-u C-c `}.
2254 @item M-x org-table-import RET
2255 Import a file as a table. The table should be TAB or whitespace
2256 separated. Use, for example, to import a spreadsheet table or data
2257 from a database, because these programs generally can write
2258 TAB-separated text files. This command works by inserting the file into
2259 the buffer and then converting the region to a table. Any prefix
2260 argument is passed on to the converter, which uses it to determine the
2262 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2263 Tables can also be imported by pasting tabular text into the Org
2264 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
2265 @kbd{C-c |} command (see above under @i{Creation and conversion}).
2267 @item M-x org-table-export RET
2268 @findex org-table-export
2269 @vindex org-table-export-default-format
2270 Export the table, by default as a TAB-separated file. Use for data
2271 exchange with, for example, spreadsheet or database programs. The format
2272 used to export the file can be configured in the option
2273 @code{org-table-export-default-format}. You may also use properties
2274 @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
2275 name and the format for table export in a subtree. Org supports quite
2276 general formats for exported tables. The exporter format is the same as the
2277 format used by Orgtbl radio tables, see @ref{Translator functions}, for a
2278 detailed description.
2281 If you don't like the automatic table editor because it gets in your
2282 way on lines which you would like to start with @samp{|}, you can turn
2286 (setq org-enable-table-editor nil)
2289 @noindent Then the only table command that still works is
2290 @kbd{C-c C-c} to do a manual re-align.
2292 @node Column width and alignment
2293 @section Column width and alignment
2294 @cindex narrow columns in tables
2295 @cindex alignment in tables
2297 The width of columns is automatically determined by the table editor. The
2298 alignment of a column is determined automatically from the fraction of
2299 number-like versus non-number fields in the column.
2301 @vindex org-table-automatic-realign
2302 Editing a field may modify alignment of the table. Moving a contiguous row
2303 or column---i.e., using @kbd{TAB} or @kbd{RET}---automatically re-aligns it.
2304 If you want to disable this behavior, set @code{org-table-automatic-realign}
2305 to @code{nil}. In any case, you can always align manually a table:
2308 @orgcmd{C-c C-c,org-table-align}
2309 Align the current table.
2312 @vindex org-startup-align-all-tables
2314 Setting the option @code{org-startup-align-all-tables} re-aligns all tables
2315 in a file upon visiting it. You can also set this option on a per-file basis
2323 Sometimes a single field or a few fields need to carry more text, leading to
2324 inconveniently wide columns. Maybe you want to hide away several columns or
2325 display them with a fixed width, regardless of content, as shown in the
2330 |---+---------------------+--------| |---+-------@dots{}|@dots{}|
2331 | | <6> | | | | <6> @dots{}|@dots{}|
2332 | 1 | one | some | ----\ | 1 | one @dots{}|@dots{}|
2333 | 2 | two | boring | ----/ | 2 | two @dots{}|@dots{}|
2334 | 3 | This is a long text | column | | 3 | This i@dots{}|@dots{}|
2335 |---+---------------------+--------| |---+-------@dots{}|@dots{}|
2339 To set the width of a column, one field anywhere in the column may contain
2340 just the string @samp{<N>} where @samp{N} specifies the width as a number of
2341 characters. You control displayed width of columns with the following tools:
2344 @orgcmd{C-c @key{TAB},org-table-toggle-column-width}
2345 Shrink or expand current column.
2347 If a width cookie specifies a width W for the column, shrinking it displays
2348 the first W visible characters only. Otherwise, the column is shrunk to
2351 When called before the first column or after the last one, ask for a list of
2352 column ranges to operate on.
2354 @orgcmd{C-u C-c @key{TAB},org-table-shrink}
2355 Shrink all columns with a column width. Expand the others.
2357 @orgcmd{C-u C-u C-c @key{TAB},org-table-expand}
2361 To see the full text of a shrunk field, hold the mouse over it---a tool-tip
2362 window then shows the full content. Alternatively @kbd{C-h .}
2363 (@code{display-local-help}) reveals the full content. For convenience, any
2364 change to a shrunk column expands it.
2366 @vindex org-startup-shrink-all-tables
2367 Setting the option @code{org-startup-shrink-all-tables} shrinks all columns
2368 containing a width cookie in a file the moment it is visited. You can also
2369 set this option on a per-file basis with:
2375 If you would like to overrule the automatic alignment of number-rich columns
2376 to the right and of string-rich columns to the left, you can use @samp{<r>},
2377 @samp{<c>} or @samp{<l>} in a similar fashion. You may also combine
2378 alignment and field width like this: @samp{<r10>}.
2380 Lines which only contain these formatting cookies are removed automatically
2381 upon exporting the document.
2384 @section Column groups
2385 @cindex grouping columns in tables
2387 When Org exports tables, it does so by default without vertical lines because
2388 that is visually more satisfying in general. Occasionally however, vertical
2389 lines can be useful to structure a table into groups of columns, much like
2390 horizontal lines can do for groups of rows. In order to specify column
2391 groups, you can use a special row where the first field contains only
2392 @samp{/}. The further fields can either contain @samp{<} to indicate that
2393 this column should start a group, @samp{>} to indicate the end of a group, or
2394 @samp{<>} (no space between @samp{<} and @samp{>}) to make a column a group
2395 of its own. Boundaries between column groups will upon export be marked with
2396 vertical lines. Here is an example:
2399 | N | N^2 | N^3 | N^4 | ~sqrt(n)~ | ~sqrt[4](N)~ |
2400 |---+-----+-----+-----+-----------+--------------|
2401 | / | < | | > | < | > |
2402 | 1 | 1 | 1 | 1 | 1 | 1 |
2403 | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
2404 | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
2405 |---+-----+-----+-----+-----------+--------------|
2406 #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
2409 It is also sufficient to just insert the column group starters after
2410 every vertical line you would like to have:
2413 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2414 |----+-----+-----+-----+---------+------------|
2419 @section The Orgtbl minor mode
2421 @cindex minor mode for tables
2423 If you like the intuitive way the Org table editor works, you
2424 might also want to use it in other modes like Text mode or Mail mode.
2425 The minor mode Orgtbl mode makes this possible. You can always toggle
2426 the mode with @kbd{M-x orgtbl-mode RET}. To turn it on by default, for
2427 example in Message mode, use
2430 (add-hook 'message-mode-hook 'turn-on-orgtbl)
2433 Furthermore, with some special setup, it is possible to maintain tables
2434 in arbitrary syntax with Orgtbl mode. For example, it is possible to
2435 construct @LaTeX{} tables with the underlying ease and power of
2436 Orgtbl mode, including spreadsheet capabilities. For details, see
2437 @ref{Tables in arbitrary syntax}.
2439 @node The spreadsheet
2440 @section The spreadsheet
2441 @cindex calculations, in tables
2442 @cindex spreadsheet capabilities
2443 @cindex @file{calc} package
2445 The table editor makes use of the Emacs @file{calc} package to implement
2446 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
2447 derive fields from other fields. While fully featured, Org's implementation
2448 is not identical to other spreadsheets. For example, Org knows the concept
2449 of a @emph{column formula} that will be applied to all non-header fields in a
2450 column without having to copy the formula to each relevant field. There is
2451 also a formula debugger, and a formula editor with features for highlighting
2452 fields in the table corresponding to the references at the point in the
2453 formula, moving these references by arrow keys
2456 * References:: How to refer to another field or range
2457 * Formula syntax for Calc:: Using Calc to compute stuff
2458 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
2459 * Durations and time values:: How to compute durations and time values
2460 * Field and range formulas:: Formula for specific (ranges of) fields
2461 * Column formulas:: Formulas valid for an entire column
2462 * Lookup functions:: Lookup functions for searching tables
2463 * Editing and debugging formulas:: Fixing formulas
2464 * Updating the table:: Recomputing all dependent fields
2465 * Advanced features:: Field and column names, parameters and automatic recalc
2469 @subsection References
2472 To compute fields in the table from other fields, formulas must
2473 reference other fields or ranges. In Org, fields can be referenced
2474 by name, by absolute coordinates, and by relative coordinates. To find
2475 out what the coordinates of a field are, press @kbd{C-c ?} in that
2476 field, or press @kbd{C-c @}} to toggle the display of a grid.
2478 @subsubheading Field references
2479 @cindex field references
2480 @cindex references, to fields
2482 Formulas can reference the value of another field in two ways. Like in
2483 any other spreadsheet, you may reference fields with a letter/number
2484 combination like @code{B3}, meaning the 2nd field in the 3rd row.
2485 @vindex org-table-use-standard-references
2486 However, Org prefers@footnote{Org will understand references typed by the
2487 user as @samp{B4}, but it will not use this syntax when offering a formula
2488 for editing. You can customize this behavior using the option
2489 @code{org-table-use-standard-references}.} to use another, more general
2490 representation that looks like this:
2492 @@@var{row}$@var{column}
2495 Column specifications can be absolute like @code{$1},
2496 @code{$2},...@code{$@var{N}}, or relative to the current column (i.e., the
2497 column of the field which is being computed) like @code{$+1} or @code{$-2}.
2498 @code{$<} and @code{$>} are immutable references to the first and last
2499 column, respectively, and you can use @code{$>>>} to indicate the third
2500 column from the right.
2502 The row specification only counts data lines and ignores horizontal separator
2503 lines (hlines). Like with columns, you can use absolute row numbers
2504 @code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
2505 current row like @code{@@+3} or @code{@@-1}. @code{@@<} and @code{@@>} are
2506 immutable references the first and last@footnote{For backward compatibility
2507 you can also use special names like @code{$LR5} and @code{$LR12} to refer in
2508 a stable way to the 5th and 12th field in the last row of the table.
2509 However, this syntax is deprecated, it should not be used for new documents.
2510 Use @code{@@>$} instead.} row in the table, respectively. You may also
2511 specify the row relative to one of the hlines: @code{@@I} refers to the first
2512 hline, @code{@@II} to the second, etc. @code{@@-I} refers to the first such
2513 line above the current line, @code{@@+I} to the first such line below the
2514 current line. You can also write @code{@@III+2} which is the second data line
2515 after the third hline in the table.
2517 @code{@@0} and @code{$0} refer to the current row and column, respectively,
2518 i.e., to the row/column for the field being computed. Also, if you omit
2519 either the column or the row part of the reference, the current row/column is
2522 Org's references with @emph{unsigned} numbers are fixed references
2523 in the sense that if you use the same reference in the formula for two
2524 different fields, the same field will be referenced each time.
2525 Org's references with @emph{signed} numbers are floating
2526 references because the same reference operator can reference different
2527 fields depending on the field being calculated by the formula.
2529 Here are a few examples:
2532 @@2$3 @r{2nd row, 3rd column (same as @code{C2})}
2533 $5 @r{column 5 in the current row (same as @code{E&})}
2534 @@2 @r{current column, row 2}
2535 @@-1$-3 @r{the field one row up, three columns to the left}
2536 @@-I$2 @r{field just under hline above current row, column 2}
2537 @@>$5 @r{field in the last row, in column 5}
2540 @subsubheading Range references
2541 @cindex range references
2542 @cindex references, to ranges
2544 You may reference a rectangular range of fields by specifying two field
2545 references connected by two dots @samp{..}. If both fields are in the
2546 current row, you may simply use @samp{$2..$7}, but if at least one field
2547 is in a different row, you need to use the general @code{@@row$column}
2548 format at least for the first field (i.e the reference must start with
2549 @samp{@@} in order to be interpreted correctly). Examples:
2552 $1..$3 @r{first three fields in the current row}
2553 $P..$Q @r{range, using column names (see under Advanced)}
2554 $<<<..$>> @r{start in third column, continue to the last but one}
2555 @@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
2556 @@-1$-2..@@-1 @r{3 fields in the row above, starting from 2 columns on the left}
2557 @@I..II @r{between first and second hline, short for @code{@@I..@@II}}
2560 @noindent Range references return a vector of values that can be fed
2561 into Calc vector functions. Empty fields in ranges are normally suppressed,
2562 so that the vector contains only the non-empty fields. For other options
2563 with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax
2566 @subsubheading Field coordinates in formulas
2567 @cindex field coordinates
2568 @cindex coordinates, of field
2569 @cindex row, of field coordinates
2570 @cindex column, of field coordinates
2572 One of the very first actions during evaluation of Calc formulas and Lisp
2573 formulas is to substitute @code{@@#} and @code{$#} in the formula with the
2574 row or column number of the field where the current result will go to. The
2575 traditional Lisp formula equivalents are @code{org-table-current-dline} and
2576 @code{org-table-current-column}. Examples:
2579 @item if(@@# % 2, $#, string(""))
2580 Insert column number on odd rows, set field to empty on even rows.
2581 @item $2 = '(identity remote(FOO, @@@@#$1))
2582 Copy text or values of each row of column 1 of the table named @code{FOO}
2583 into column 2 of the current table.
2584 @item @@3 = 2 * remote(FOO, @@1$$#)
2585 Insert the doubled value of each column of row 1 of the table named
2586 @code{FOO} into row 3 of the current table.
2589 @noindent For the second/third example, the table named @code{FOO} must have
2590 at least as many rows/columns as the current table. Note that this is
2591 inefficient@footnote{The computation time scales as O(N^2) because the table
2592 named @code{FOO} is parsed for each field to be read.} for large number of
2595 @subsubheading Named references
2596 @cindex named references
2597 @cindex references, named
2598 @cindex name, of column or field
2599 @cindex constants, in calculations
2602 @vindex org-table-formula-constants
2603 @samp{$name} is interpreted as the name of a column, parameter or
2604 constant. Constants are defined globally through the option
2605 @code{org-table-formula-constants}, and locally (for the file) through a
2609 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
2613 @vindex constants-unit-system
2614 @pindex constants.el
2615 Also properties (@pxref{Properties and columns}) can be used as
2616 constants in table formulas: for a property @samp{:Xyz:} use the name
2617 @samp{$PROP_Xyz}, and the property will be searched in the current
2618 outline entry and in the hierarchy above it. If you have the
2619 @file{constants.el} package, it will also be used to resolve constants,
2620 including natural constants like @samp{$h} for Planck's constant, and
2621 units like @samp{$km} for kilometers@footnote{@file{constants.el} can
2622 supply the values of constants in two different unit systems, @code{SI}
2623 and @code{cgs}. Which one is used depends on the value of the variable
2624 @code{constants-unit-system}. You can use the @code{#+STARTUP} options
2625 @code{constSI} and @code{constcgs} to set this value for the current
2626 buffer.}. Column names and parameters can be specified in special table
2627 lines. These are described below, see @ref{Advanced features}. All
2628 names must start with a letter, and further consist of letters and
2631 @subsubheading Remote references
2632 @cindex remote references
2633 @cindex references, remote
2634 @cindex references, to a different table
2635 @cindex name, of column or field
2636 @cindex constants, in calculations
2637 @cindex #+NAME, for table
2639 You may also reference constants, fields and ranges from a different table,
2640 either in the current file or even in a different file. The syntax is
2643 remote(NAME-OR-ID,REF)
2647 where NAME can be the name of a table in the current file as set by a
2648 @code{#+NAME: Name} line before the table. It can also be the ID of an
2649 entry, even in a different file, and the reference then refers to the first
2650 table in that entry. REF is an absolute field or range reference as
2651 described above for example @code{@@3$3} or @code{$somename}, valid in the
2654 Indirection of NAME-OR-ID: When NAME-OR-ID has the format @code{@@ROW$COLUMN}
2655 it will be substituted with the name or ID found in this field of the current
2656 table. For example @code{remote($1, @@>$2)} => @code{remote(year_2013,
2657 @@>$1)}. The format @code{B3} is not supported because it can not be
2658 distinguished from a plain table name or ID.
2660 @node Formula syntax for Calc
2661 @subsection Formula syntax for Calc
2662 @cindex formula syntax, Calc
2663 @cindex syntax, of formulas
2665 A formula can be any algebraic expression understood by the Emacs @file{Calc}
2666 package. Note that @file{calc} has the non-standard convention that @samp{/}
2667 has lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as
2668 @samp{a/(b*c)}. Before evaluation by @code{calc-eval} (@pxref{Calling Calc
2669 from Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc,
2670 GNU Emacs Calc Manual}), variable substitution takes place according to the
2671 rules described above.
2672 @cindex vectors, in table calculations
2673 The range vectors can be directly fed into the Calc vector functions
2674 like @samp{vmean} and @samp{vsum}.
2676 @cindex format specifier
2677 @cindex mode, for @file{calc}
2678 @vindex org-calc-default-modes
2679 A formula can contain an optional mode string after a semicolon. This
2680 string consists of flags to influence Calc and other modes during
2681 execution. By default, Org uses the standard Calc modes (precision
2682 12, angular units degrees, fraction and symbolic modes off). The display
2683 format, however, has been changed to @code{(float 8)} to keep tables
2684 compact. The default settings can be configured using the option
2685 @code{org-calc-default-modes}.
2687 @noindent List of modes:
2691 Set the internal Calc calculation precision to 20 digits.
2692 @item @code{n3}, @code{s3}, @code{e2}, @code{f4}
2693 Normal, scientific, engineering or fixed format of the result of Calc passed
2694 back to Org. Calc formatting is unlimited in precision as long as the Calc
2695 calculation precision is greater.
2696 @item @code{D}, @code{R}
2697 Degree and radian angle modes of Calc.
2698 @item @code{F}, @code{S}
2699 Fraction and symbolic modes of Calc.
2700 @item @code{T}, @code{t}, @code{U}
2701 Duration computations in Calc or Lisp, @pxref{Durations and time values}.
2703 If and how to consider empty fields. Without @samp{E} empty fields in range
2704 references are suppressed so that the Calc vector or Lisp list contains only
2705 the non-empty fields. With @samp{E} the empty fields are kept. For empty
2706 fields in ranges or empty field references the value @samp{nan} (not a
2707 number) is used in Calc formulas and the empty string is used for Lisp
2708 formulas. Add @samp{N} to use 0 instead for both formula types. For the
2709 value of a field the mode @samp{N} has higher precedence than @samp{E}.
2711 Interpret all fields as numbers, use 0 for non-numbers. See the next section
2712 to see how this is essential for computations with Lisp formulas. In Calc
2713 formulas it is used only occasionally because there number strings are
2714 already interpreted as numbers without @samp{N}.
2716 Literal, for Lisp formulas only. See the next section.
2720 Unless you use large integer numbers or high-precision-calculation and
2721 -display for floating point numbers you may alternatively provide a
2722 @samp{printf} format specifier to reformat the Calc result after it has been
2723 passed back to Org instead of letting Calc already do the
2724 formatting@footnote{The @samp{printf} reformatting is limited in precision
2725 because the value passed to it is converted into an @samp{integer} or
2726 @samp{double}. The @samp{integer} is limited in size by truncating the
2727 signed value to 32 bits. The @samp{double} is limited in precision to 64
2728 bits overall which leaves approximately 16 significant decimal digits.}. A
2732 $1+$2 @r{Sum of first and second field}
2733 $1+$2;%.2f @r{Same, format result to two decimals}
2734 exp($2)+exp($1) @r{Math functions can be used}
2735 $0;%.1f @r{Reformat current cell to 1 decimal}
2736 ($3-32)*5/9 @r{Degrees F -> C conversion}
2737 $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
2738 tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
2739 sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
2740 taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree}
2743 Calc also contains a complete set of logical operations, (@pxref{Logical
2744 Operations, , Logical Operations, calc, GNU Emacs Calc Manual}). For example
2747 @item if($1 < 20, teen, string(""))
2748 "teen" if age $1 is less than 20, else the Org table result field is set to
2749 empty with the empty string.
2750 @item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1
2751 Sum of the first two columns. When at least one of the input fields is empty
2752 the Org table result field is set to empty. @samp{E} is required to not
2753 convert empty fields to 0. @samp{f-1} is an optional Calc format string
2754 similar to @samp{%.1f} but leaves empty results empty.
2755 @item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E
2756 Mean value of a range unless there is any empty field. Every field in the
2757 range that is empty is replaced by @samp{nan} which lets @samp{vmean} result
2758 in @samp{nan}. Then @samp{typeof == 12} detects the @samp{nan} from
2759 @samp{vmean} and the Org table result field is set to empty. Use this when
2760 the sample set is expected to never have missing values.
2761 @item if("$1..$7" == "[]", string(""), vmean($1..$7))
2762 Mean value of a range with empty fields skipped. Every field in the range
2763 that is empty is skipped. When all fields in the range are empty the mean
2764 value is not defined and the Org table result field is set to empty. Use
2765 this when the sample set can have a variable size.
2766 @item vmean($1..$7); EN
2767 To complete the example before: Mean value of a range with empty fields
2768 counting as samples with value 0. Use this only when incomplete sample sets
2769 should be padded with 0 to the full size.
2772 You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
2773 and use them in formula syntax for Calc.
2775 @node Formula syntax for Lisp
2776 @subsection Emacs Lisp forms as formulas
2777 @cindex Lisp forms, as table formulas
2779 It is also possible to write a formula in Emacs Lisp. This can be useful
2780 for string manipulation and control structures, if Calc's functionality is
2783 If a formula starts with an apostrophe followed by an opening parenthesis,
2784 then it is evaluated as a Lisp form. The evaluation should return either a
2785 string or a number. Just as with @file{calc} formulas, you can specify modes
2786 and a printf format after a semicolon.
2788 With Emacs Lisp forms, you need to be conscious about the way field
2789 references are interpolated into the form. By default, a reference will be
2790 interpolated as a Lisp string (in double-quotes) containing the field. If
2791 you provide the @samp{N} mode switch, all referenced elements will be numbers
2792 (non-number fields will be zero) and interpolated as Lisp numbers, without
2793 quotes. If you provide the @samp{L} flag, all fields will be interpolated
2794 literally, without quotes. I.e., if you want a reference to be interpreted
2795 as a string by the Lisp form, enclose the reference operator itself in
2796 double-quotes, like @code{"$3"}. Ranges are inserted as space-separated
2797 fields, so you can embed them in list or vector syntax.
2799 Here are a few examples---note how the @samp{N} mode is used when we do
2800 computations in Lisp:
2803 @item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
2804 Swap the first two characters of the content of column 1.
2806 Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
2807 @item '(apply '+ '($1..$4));N
2808 Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
2811 @node Durations and time values
2812 @subsection Durations and time values
2813 @cindex Duration, computing
2814 @cindex Time, computing
2815 @vindex org-table-duration-custom-format
2817 If you want to compute time values use the @code{T}, @code{t}, or @code{U}
2818 flag, either in Calc formulas or Elisp formulas:
2822 | Task 1 | Task 2 | Total |
2823 |---------+----------+----------|
2824 | 2:12 | 1:47 | 03:59:00 |
2825 | 2:12 | 1:47 | 03:59 |
2826 | 3:02:20 | -2:07:00 | 0.92 |
2827 #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;U::@@4$3=$1+$2;t
2831 Input duration values must be of the form @code{HH:MM[:SS]}, where seconds
2832 are optional. With the @code{T} flag, computed durations will be displayed
2833 as @code{HH:MM:SS} (see the first formula above). With the @code{U} flag,
2834 seconds will be omitted so that the result will be only @code{HH:MM} (see
2835 second formula above). Zero-padding of the hours field will depend upon the
2836 value of the variable @code{org-table-duration-hour-zero-padding}.
2838 With the @code{t} flag, computed durations will be displayed according to the
2839 value of the option @code{org-table-duration-custom-format}, which defaults
2840 to @code{'hours} and will display the result as a fraction of hours (see the
2841 third formula in the example above).
2843 Negative duration values can be manipulated as well, and integers will be
2844 considered as seconds in addition and subtraction.
2846 @node Field and range formulas
2847 @subsection Field and range formulas
2848 @cindex field formula
2849 @cindex range formula
2850 @cindex formula, for individual table field
2851 @cindex formula, for range of fields
2853 To assign a formula to a particular field, type it directly into the field,
2854 preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press
2855 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2856 the formula will be stored as the formula for this field, evaluated, and the
2857 current field will be replaced with the result.
2860 Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
2861 below the table. If you type the equation in the 4th field of the 3rd data
2862 line in the table, the formula will look like @samp{@@3$4=$1+$2}. When
2863 inserting/deleting/swapping columns and rows with the appropriate commands,
2864 @i{absolute references} (but not relative ones) in stored formulas are
2865 modified in order to still reference the same field. To avoid this, in
2866 particular in range references, anchor ranges at the table borders (using
2867 @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines using the
2868 @code{@@I} notation. Automatic adaptation of field references does of course
2869 not happen if you edit the table structure with normal editing
2870 commands---then you must fix the equations yourself.
2872 Instead of typing an equation into the field, you may also use the following
2876 @orgcmd{C-u C-c =,org-table-eval-formula}
2877 Install a new formula for the current field. The command prompts for a
2878 formula with default taken from the @samp{#+TBLFM:} line, applies
2879 it to the current field, and stores it.
2882 The left-hand side of a formula can also be a special expression in order to
2883 assign the formula to a number of different fields. There is no keyboard
2884 shortcut to enter such range formulas. To add them, use the formula editor
2885 (@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
2890 Column formula, valid for the entire column. This is so common that Org
2891 treats these formulas in a special way, see @ref{Column formulas}.
2893 Row formula, applies to all fields in the specified row. @code{@@>=} means
2896 Range formula, applies to all fields in the given rectangular range. This
2897 can also be used to assign a formula to some but not all fields in a row.
2899 Named field, see @ref{Advanced features}.
2902 @node Column formulas
2903 @subsection Column formulas
2904 @cindex column formula
2905 @cindex formula, for table column
2907 When you assign a formula to a simple column reference like @code{$3=}, the
2908 same formula will be used in all fields of that column, with the following
2909 very convenient exceptions: (i) If the table contains horizontal separator
2910 hlines with rows above and below, everything before the first such hline is
2911 considered part of the table @emph{header} and will not be modified by column
2912 formulas. Therefore a header is mandatory when you use column formulas and
2913 want to add hlines to group rows, like for example to separate a total row at
2914 the bottom from the summand rows above. (ii) Fields that already get a value
2915 from a field/range formula will be left alone by column formulas. These
2916 conditions make column formulas very easy to use.
2918 To assign a formula to a column, type it directly into any field in the
2919 column, preceded by an equal sign, like @samp{=$1+$2}. When you press
2920 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2921 the formula will be stored as the formula for the current column, evaluated
2922 and the current field replaced with the result. If the field contains only
2923 @samp{=}, the previously stored formula for this column is used. For each
2924 column, Org will only remember the most recently used formula. In the
2925 @samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The
2926 left-hand side of a column formula cannot be the name of column, it must be
2927 the numeric column reference or @code{$>}.
2929 Instead of typing an equation into the field, you may also use the
2933 @orgcmd{C-c =,org-table-eval-formula}
2934 Install a new formula for the current column and replace current field with
2935 the result of the formula. The command prompts for a formula, with default
2936 taken from the @samp{#+TBLFM} line, applies it to the current field and
2937 stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
2938 will apply it to that many consecutive fields in the current column.
2941 @node Lookup functions
2942 @subsection Lookup functions
2943 @cindex lookup functions in tables
2944 @cindex table lookup functions
2946 Org has three predefined Emacs Lisp functions for lookups in tables.
2948 @item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)
2949 @findex org-lookup-first
2950 Searches for the first element @code{S} in list @code{S-LIST} for which
2954 is @code{t}; returns the value from the corresponding position in list
2955 @code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the
2956 parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same
2957 order as the corresponding parameters are in the call to
2958 @code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If
2959 @code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST}
2961 @item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)
2962 @findex org-lookup-last
2963 Similar to @code{org-lookup-first} above, but searches for the @i{last}
2964 element for which @code{PREDICATE} is @code{t}.
2965 @item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)
2966 @findex org-lookup-all
2967 Similar to @code{org-lookup-first}, but searches for @i{all} elements for
2968 which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding
2969 values. This function can not be used by itself in a formula, because it
2970 returns a list of values. However, powerful lookups can be built when this
2971 function is combined with other Emacs Lisp functions.
2974 If the ranges used in these functions contain empty fields, the @code{E} mode
2975 for the formula should usually be specified: otherwise empty fields will not be
2976 included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result
2977 in an incorrect mapping from an element of @code{S-LIST} to the corresponding
2978 element of @code{R-LIST}.
2980 These three functions can be used to implement associative arrays, count
2981 matching cells, rank results, group data etc. For practical examples
2982 see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
2985 @node Editing and debugging formulas
2986 @subsection Editing and debugging formulas
2987 @cindex formula editing
2988 @cindex editing, of table formulas
2990 @vindex org-table-use-standard-references
2991 You can edit individual formulas in the minibuffer or directly in the field.
2992 Org can also prepare a special buffer with all active formulas of a table.
2993 When offering a formula for editing, Org converts references to the standard
2994 format (like @code{B3} or @code{D&}) if possible. If you prefer to only work
2995 with the internal format (like @code{@@3$2} or @code{$4}), configure the
2996 option @code{org-table-use-standard-references}.
2999 @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
3000 Edit the formula associated with the current column/field in the
3001 minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}.
3002 @orgcmd{C-u C-u C-c =,org-table-eval-formula}
3003 Re-insert the active formula (either a
3004 field formula, or a column formula) into the current field, so that you
3005 can edit it directly in the field. The advantage over editing in the
3006 minibuffer is that you can use the command @kbd{C-c ?}.
3007 @orgcmd{C-c ?,org-table-field-info}
3008 While editing a formula in a table field, highlight the field(s)
3009 referenced by the reference at the cursor position in the formula.
3011 @findex org-table-toggle-coordinate-overlays
3013 Toggle the display of row and column numbers for a table, using overlays
3014 (@command{org-table-toggle-coordinate-overlays}). These are updated each
3015 time the table is aligned; you can force it with @kbd{C-c C-c}.
3017 @findex org-table-toggle-formula-debugger
3019 Toggle the formula debugger on and off
3020 (@command{org-table-toggle-formula-debugger}). See below.
3021 @orgcmd{C-c ',org-table-edit-formulas}
3022 Edit all formulas for the current table in a special buffer, where the
3023 formulas will be displayed one per line. If the current field has an
3024 active formula, the cursor in the formula editor will mark it.
3025 While inside the special buffer, Org will automatically highlight
3026 any field or range reference at the cursor position. You may edit,
3027 remove and add formulas, and use the following commands:
3030 @orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
3031 Exit the formula editor and store the modified formulas. With @kbd{C-u}
3032 prefix, also apply the new formulas to the entire table.
3033 @orgcmd{C-c C-q,org-table-fedit-abort}
3034 Exit the formula editor without installing changes.
3035 @orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
3036 Toggle all references in the formula editor between standard (like
3037 @code{B3}) and internal (like @code{@@3$2}).
3038 @orgcmd{@key{TAB},org-table-fedit-lisp-indent}
3039 Pretty-print or indent Lisp formula at point. When in a line containing
3040 a Lisp formula, format the formula according to Emacs Lisp rules.
3041 Another @key{TAB} collapses the formula back again. In the open
3042 formula, @key{TAB} re-indents just like in Emacs Lisp mode.
3043 @orgcmd{M-@key{TAB},lisp-complete-symbol}
3044 Complete Lisp symbols, just like in Emacs Lisp mode.@footnote{Many desktops
3045 intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
3046 @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}
3048 @kindex S-@key{down}
3049 @kindex S-@key{left}
3050 @kindex S-@key{right}
3051 @findex org-table-fedit-ref-up
3052 @findex org-table-fedit-ref-down
3053 @findex org-table-fedit-ref-left
3054 @findex org-table-fedit-ref-right
3055 @item S-@key{up}/@key{down}/@key{left}/@key{right}
3056 Shift the reference at point. For example, if the reference is
3057 @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
3058 This also works for relative references and for hline references.
3059 @orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
3060 Move the test line for column formulas in the Org buffer up and
3062 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
3063 Scroll the window displaying the table.
3065 @findex org-table-toggle-coordinate-overlays
3067 Turn the coordinate grid in the table on and off.
3071 Making a table field blank does not remove the formula associated with
3072 the field, because that is stored in a different line (the @samp{#+TBLFM}
3073 line)---during the next recalculation the field will be filled again.
3074 To remove a formula from a field, you have to give an empty reply when
3075 prompted for the formula, or to edit the @samp{#+TBLFM} line.
3078 You may edit the @samp{#+TBLFM} directly and re-apply the changed
3079 equations with @kbd{C-c C-c} in that line or with the normal
3080 recalculation commands in the table.
3082 @anchor{Using multiple #+TBLFM lines}
3083 @subsubheading Using multiple #+TBLFM lines
3084 @cindex #+TBLFM line, multiple
3086 @cindex #+TBLFM, switching
3089 You may apply the formula temporarily. This is useful when you
3090 switch the formula. Place multiple @samp{#+TBLFM} lines right
3091 after the table, and then press @kbd{C-c C-c} on the formula to
3092 apply. Here is an example:
3104 Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
3116 Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
3117 will get the following result of applying only the first @samp{#+TBLFM} line.
3128 @subsubheading Debugging formulas
3129 @cindex formula debugging
3130 @cindex debugging, of table formulas
3131 When the evaluation of a formula leads to an error, the field content
3132 becomes the string @samp{#ERROR}. If you would like see what is going
3133 on during variable substitution and calculation in order to find a bug,
3134 turn on formula debugging in the @code{Tbl} menu and repeat the
3135 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
3136 field. Detailed information will be displayed.
3138 @node Updating the table
3139 @subsection Updating the table
3140 @cindex recomputing table fields
3141 @cindex updating, table
3143 Recalculation of a table is normally not automatic, but needs to be
3144 triggered by a command. See @ref{Advanced features}, for a way to make
3145 recalculation at least semi-automatic.
3147 In order to recalculate a line of a table or the entire table, use the
3151 @orgcmd{C-c *,org-table-recalculate}
3152 Recalculate the current row by first applying the stored column formulas
3153 from left to right, and all field/range formulas in the current row.
3159 Recompute the entire table, line by line. Any lines before the first
3160 hline are left alone, assuming that these are part of the table header.
3162 @orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
3163 Iterate the table by recomputing it until no further changes occur.
3164 This may be necessary if some computed fields use the value of other
3165 fields that are computed @i{later} in the calculation sequence.
3166 @item M-x org-table-recalculate-buffer-tables RET
3167 @findex org-table-recalculate-buffer-tables
3168 Recompute all tables in the current buffer.
3169 @item M-x org-table-iterate-buffer-tables RET
3170 @findex org-table-iterate-buffer-tables
3171 Iterate all tables in the current buffer, in order to converge table-to-table
3175 @node Advanced features
3176 @subsection Advanced features
3178 If you want the recalculation of fields to happen automatically, or if you
3179 want to be able to assign @i{names}@footnote{Such names must start by an
3180 alphabetic character and use only alphanumeric/underscore characters.} to
3181 fields and columns, you need to reserve the first column of the table for
3182 special marking characters.
3185 @orgcmd{C-#,org-table-rotate-recalc-marks}
3186 Rotate the calculation mark in first column through the states @samp{ },
3187 @samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,
3188 change all marks in the region.
3191 Here is an example of a table that collects exam results of students and
3192 makes use of these features:
3196 |---+---------+--------+--------+--------+-------+------|
3197 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
3198 |---+---------+--------+--------+--------+-------+------|
3199 | ! | | P1 | P2 | P3 | Tot | |
3200 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
3201 | ^ | | m1 | m2 | m3 | mt | |
3202 |---+---------+--------+--------+--------+-------+------|
3203 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
3204 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
3205 |---+---------+--------+--------+--------+-------+------|
3206 | | Average | | | | 25.0 | |
3207 | ^ | | | | | at | |
3208 | $ | max=50 | | | | | |
3209 |---+---------+--------+--------+--------+-------+------|
3210 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
3214 @noindent @b{Important}: please note that for these special tables,
3215 recalculating the table with @kbd{C-u C-c *} will only affect rows that
3216 are marked @samp{#} or @samp{*}, and fields that have a formula assigned
3217 to the field itself. The column formulas are not applied in rows with
3220 @cindex marking characters, tables
3221 The marking characters have the following meaning:
3225 The fields in this line define names for the columns, so that you may
3226 refer to a column as @samp{$Tot} instead of @samp{$6}.
3228 This row defines names for the fields @emph{above} the row. With such
3229 a definition, any formula in the table may use @samp{$m1} to refer to
3230 the value @samp{10}. Also, if you assign a formula to a names field, it
3231 will be stored as @samp{$name=...}.
3233 Similar to @samp{^}, but defines names for the fields in the row
3236 Fields in this row can define @emph{parameters} for formulas. For
3237 example, if a field in a @samp{$} row contains @samp{max=50}, then
3238 formulas in this table can refer to the value 50 using @samp{$max}.
3239 Parameters work exactly like constants, only that they can be defined on
3242 Fields in this row are automatically recalculated when pressing
3243 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
3244 is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
3245 lines will be left alone by this command.
3247 Selects this line for global recalculation with @kbd{C-u C-c *}, but
3248 not for automatic recalculation. Use this when automatic
3249 recalculation slows down editing too much.
3251 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
3252 All lines that should be recalculated should be marked with @samp{#}
3255 Do not export this line. Useful for lines that contain the narrowing
3256 @samp{<N>} markers or column group markers.
3259 Finally, just to whet your appetite for what can be done with the
3260 fantastic @file{calc.el} package, here is a table that computes the Taylor
3261 series of degree @code{n} at location @code{x} for a couple of
3266 |---+-------------+---+-----+--------------------------------------|
3267 | | Func | n | x | Result |
3268 |---+-------------+---+-----+--------------------------------------|
3269 | # | exp(x) | 1 | x | 1 + x |
3270 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
3271 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
3272 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
3273 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
3274 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
3275 |---+-------------+---+-----+--------------------------------------|
3276 #+TBLFM: $5=taylor($2,$4,$3);n3
3282 @cindex graph, in tables
3283 @cindex plot tables using Gnuplot
3286 Org-Plot can produce graphs of information stored in org tables, either
3287 graphically or in ASCII-art.
3289 @subheading Graphical plots using @file{Gnuplot}
3291 Org-Plot produces 2D and 3D graphs using @file{Gnuplot}
3292 @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
3293 @uref{http://xafs.org/BruceRavel/GnuplotMode}. To see this in action, ensure
3294 that you have both Gnuplot and Gnuplot mode installed on your system, then
3295 call @kbd{C-c " g} or @kbd{M-x org-plot/gnuplot @key{RET}} on the following
3300 #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
3301 | Sede | Max cites | H-index |
3302 |-----------+-----------+---------|
3303 | Chile | 257.72 | 21.39 |
3304 | Leeds | 165.77 | 19.68 |
3305 | Sao Paolo | 71.00 | 11.50 |
3306 | Stockholm | 134.19 | 14.33 |
3307 | Morelia | 257.56 | 17.67 |
3311 Notice that Org Plot is smart enough to apply the table's headers as labels.
3312 Further control over the labels, type, content, and appearance of plots can
3313 be exercised through the @code{#+PLOT:} lines preceding a table. See below
3314 for a complete list of Org-plot options. The @code{#+PLOT:} lines are
3315 optional. For more information and examples see the Org-plot tutorial at
3316 @uref{http://orgmode.org/worg/org-tutorials/org-plot.html}.
3318 @subsubheading Plot Options
3322 Specify any @command{gnuplot} option to be set when graphing.
3325 Specify the title of the plot.
3328 Specify which column of the table to use as the @code{x} axis.
3331 Specify the columns to graph as a Lisp style list, surrounded by parentheses
3332 and separated by spaces for example @code{dep:(3 4)} to graph the third and
3333 fourth columns (defaults to graphing all other columns aside from the @code{ind}
3337 Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
3340 Specify a @code{with} option to be inserted for every col being plotted
3341 (e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
3342 Defaults to @code{lines}.
3345 If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
3348 List of labels to be used for the @code{deps} (defaults to the column headers
3352 Specify an entire line to be inserted in the Gnuplot script.
3355 When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
3356 flat mapping rather than a @code{3d} slope.
3359 Specify format of Org mode timestamps as they will be parsed by Gnuplot.
3360 Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
3363 If you want total control, you can specify a script file (place the file name
3364 between double-quotes) which will be used to plot. Before plotting, every
3365 instance of @code{$datafile} in the specified script will be replaced with
3366 the path to the generated data file. Note: even if you set this option, you
3367 may still want to specify the plot type, as that can impact the content of
3371 @subheading ASCII bar plots
3373 While the cursor is on a column, typing @kbd{C-c " a} or
3374 @kbd{M-x orgtbl-ascii-plot @key{RET}} create a new column containing an
3375 ASCII-art bars plot. The plot is implemented through a regular column
3376 formula. When the source column changes, the bar plot may be updated by
3377 refreshing the table, for example typing @kbd{C-u C-c *}.
3381 | Sede | Max cites | |
3382 |---------------+-----------+--------------|
3383 | Chile | 257.72 | WWWWWWWWWWWW |
3384 | Leeds | 165.77 | WWWWWWWh |
3385 | Sao Paolo | 71.00 | WWW; |
3386 | Stockholm | 134.19 | WWWWWW: |
3387 | Morelia | 257.56 | WWWWWWWWWWWH |
3388 | Rochefourchat | 0.00 | |
3389 #+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12)
3393 The formula is an elisp call:
3395 (orgtbl-ascii-draw COLUMN MIN MAX WIDTH)
3400 is a reference to the source column.
3403 are the minimal and maximal values displayed. Sources values
3404 outside this range are displayed as @samp{too small}
3405 or @samp{too large}.
3408 is the width in characters of the bar-plot. It defaults to @samp{12}.
3416 Like HTML, Org provides links inside a file, external links to
3417 other files, Usenet articles, emails, and much more.
3420 * Link format:: How links in Org are formatted
3421 * Internal links:: Links to other places in the current file
3422 * External links:: URL-like links to the world
3423 * Handling links:: Creating, inserting and following
3424 * Using links outside Org:: Linking from my C source code?
3425 * Link abbreviations:: Shortcuts for writing complex links
3426 * Search options:: Linking to a specific location
3427 * Custom searches:: When the default search is not enough
3431 @section Link format
3433 @cindex format, of links
3435 Org will recognize plain URL-like links and activate them as
3436 clickable links. The general link format, however, looks like this:
3439 [[link][description]] @r{or alternatively} [[link]]
3443 Once a link in the buffer is complete (all brackets present), Org
3444 will change the display so that @samp{description} is displayed instead
3445 of @samp{[[link][description]]} and @samp{link} is displayed instead of
3446 @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
3447 which by default is an underlined face. You can directly edit the
3448 visible part of a link. Note that this can be either the @samp{link}
3449 part (if there is no description) or the @samp{description} part. To
3450 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
3453 If you place the cursor at the beginning or just behind the end of the
3454 displayed text and press @key{BACKSPACE}, you will remove the
3455 (invisible) bracket at that location. This makes the link incomplete
3456 and the internals are again displayed as plain text. Inserting the
3457 missing bracket hides the link internals again. To show the
3458 internal structure of all links, use the menu entry
3459 @code{Org->Hyperlinks->Literal links}.
3461 @node Internal links
3462 @section Internal links
3463 @cindex internal links
3464 @cindex links, internal
3465 @cindex targets, for links
3467 @cindex property, CUSTOM_ID
3468 If the link does not look like a URL, it is considered to be internal in the
3469 current file. The most important case is a link like
3470 @samp{[[#my-custom-id]]} which will link to the entry with the
3471 @code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself
3472 to make sure these custom IDs are unique in a file.
3474 Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
3475 lead to a text search in the current file.
3477 The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
3478 or with a mouse click (@pxref{Handling links}). Links to custom IDs will
3479 point to the corresponding headline. The preferred match for a text link is
3480 a @i{dedicated target}: the same string in double angular brackets, like
3481 @samp{<<My Target>>}.
3484 If no dedicated target exists, the link will then try to match the exact name
3485 of an element within the buffer. Naming is done with the @code{#+NAME}
3486 keyword, which has to be put in the line before the element it refers to, as
3487 in the following example
3496 If none of the above succeeds, Org will search for a headline that is exactly
3497 the link text but may also include a TODO keyword and tags@footnote{To insert
3498 a link targeting a headline, in-buffer completion can be used. Just type
3499 a star followed by a few optional letters into the buffer and press
3500 @kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as
3503 During export, internal links will be used to mark objects and assign them
3504 a number. Marked objects will then be referenced by links pointing to them.
3505 In particular, links without a description will appear as the number assigned
3506 to the marked object@footnote{When targeting a @code{#+NAME} keyword,
3507 @code{#+CAPTION} keyword is mandatory in order to get proper numbering
3508 (@pxref{Images and tables}).}. In the following excerpt from an Org buffer
3512 - <<target>>another item
3513 Here we refer to item [[target]].
3517 The last sentence will appear as @samp{Here we refer to item 2} when
3520 In non-Org files, the search will look for the words in the link text. In
3521 the above example the search would be for @samp{my target}.
3523 Following a link pushes a mark onto Org's own mark ring. You can
3524 return to the previous position with @kbd{C-c &}. Using this command
3525 several times in direct succession goes back to positions recorded
3529 * Radio targets:: Make targets trigger links in plain text
3533 @subsection Radio targets
3534 @cindex radio targets
3535 @cindex targets, radio
3536 @cindex links, radio targets
3538 Org can automatically turn any occurrences of certain target names
3539 in normal text into a link. So without explicitly creating a link, the
3540 text connects to the target radioing its position. Radio targets are
3541 enclosed by triple angular brackets. For example, a target @samp{<<<My
3542 Target>>>} causes each occurrence of @samp{my target} in normal text to
3543 become activated as a link. The Org file is scanned automatically
3544 for radio targets only when the file is first loaded into Emacs. To
3545 update the target list during editing, press @kbd{C-c C-c} with the
3546 cursor on or at a target.
3548 @node External links
3549 @section External links
3550 @cindex links, external
3551 @cindex external links
3559 @cindex USENET links
3564 Org supports links to files, websites, Usenet and email messages, BBDB
3565 database entries and links to both IRC conversations and their logs.
3566 External links are URL-like locators. They start with a short identifying
3567 string followed by a colon. There can be no space after the colon. The
3568 following list shows examples for each link type.
3571 http://www.astro.uva.nl/~dominik @r{on the web}
3572 doi:10.1000/182 @r{DOI for an electronic resource}
3573 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
3574 /home/dominik/images/jupiter.jpg @r{same as above}
3575 file:papers/last.pdf @r{file, relative path}
3576 ./papers/last.pdf @r{same as above}
3577 file:/ssh:myself@@some.where:papers/last.pdf @r{file, path on remote machine}
3578 /ssh:myself@@some.where:papers/last.pdf @r{same as above}
3579 file:sometextfile::NNN @r{file, jump to line number}
3580 file:projects.org @r{another Org file}
3581 file:projects.org::some words @r{text search in Org file}@footnote{
3582 The actual behavior of the search will depend on the value of
3583 the option @code{org-link-search-must-match-exact-headline}. If its value
3584 is @code{nil}, then a fuzzy text search will be done. If it is @code{t}, then only
3585 the exact headline will be matched, ignoring spaces and cookies. If the
3586 value is @code{query-to-create}, then an exact headline will be searched; if
3587 it is not found, then the user will be queried to create it.}
3588 file:projects.org::*task title @r{heading search in Org file}@footnote{
3589 Headline searches always match the exact headline, ignoring
3590 spaces and cookies. If the headline is not found and the value of the option
3591 @code{org-link-search-must-match-exact-headline} is @code{query-to-create},
3592 then the user will be queried to create it.}
3593 docview:papers/last.pdf::NNN @r{open in doc-view mode at page}
3594 id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
3595 news:comp.emacs @r{Usenet link}
3596 mailto:adent@@galaxy.net @r{Mail link}
3597 mhe:folder @r{MH-E folder link}
3598 mhe:folder#id @r{MH-E message link}
3599 rmail:folder @r{RMAIL folder link}
3600 rmail:folder#id @r{RMAIL message link}
3601 gnus:group @r{Gnus group link}
3602 gnus:group#id @r{Gnus article link}
3603 bbdb:R.*Stallman @r{BBDB link (with regexp)}
3604 irc:/irc.com/#emacs/bob @r{IRC link}
3605 info:org#External links @r{Info node or index link}
3606 shell:ls *.org @r{A shell command}
3607 elisp:org-agenda @r{Interactive Elisp command}
3608 elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
3612 @cindex WANDERLUST links
3613 On top of these built-in link types, some are available through the
3614 @code{contrib/} directory (@pxref{Installation}). For example, these links
3615 to VM or Wanderlust messages are available when you load the corresponding
3616 libraries from the @code{contrib/} directory:
3619 vm:folder @r{VM folder link}
3620 vm:folder#id @r{VM message link}
3621 vm://myself@@some.where.org/folder#id @r{VM on remote machine}
3622 vm-imap:account:folder @r{VM IMAP folder link}
3623 vm-imap:account:folder#id @r{VM IMAP message link}
3624 wl:folder @r{WANDERLUST folder link}
3625 wl:folder#id @r{WANDERLUST message link}
3628 For customizing Org to add new link types @ref{Adding hyperlink types}.
3630 A link should be enclosed in double brackets and may contain a descriptive
3631 text to be displayed instead of the URL (@pxref{Link format}), for example:
3634 [[https://www.gnu.org/software/emacs/][GNU Emacs]]
3638 If the description is a file name or URL that points to an image, HTML
3639 export (@pxref{HTML export}) will inline the image as a clickable
3640 button. If there is no description at all and the link points to an
3642 that image will be inlined into the exported HTML file.
3644 @cindex square brackets, around links
3645 @cindex plain text external links
3646 Org also finds external links in the normal text and activates them
3647 as links. If spaces must be part of the link (for example in
3648 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
3649 about the end of the link, enclose them in square brackets.
3651 @node Handling links
3652 @section Handling links
3653 @cindex links, handling
3655 Org provides methods to create a link in the correct syntax, to
3656 insert it into an Org file, and to follow the link.
3659 @orgcmd{C-c l,org-store-link}
3660 @cindex storing links
3661 Store a link to the current location. This is a @emph{global} command (you
3662 must create the key binding yourself) which can be used in any buffer to
3663 create a link. The link will be stored for later insertion into an Org
3664 buffer (see below). What kind of link will be created depends on the current
3667 @b{Org mode buffers}@*
3668 For Org files, if there is a @samp{<<target>>} at the cursor, the link points
3669 to the target. Otherwise it points to the current headline, which will also
3670 be the description@footnote{If the headline contains a timestamp, it will be
3671 removed from the link and result in a wrong link---you should avoid putting
3672 timestamp in the headline.}.
3674 @vindex org-id-link-to-org-use-id
3675 @cindex property, CUSTOM_ID
3676 @cindex property, ID
3677 If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
3678 will be stored. In addition or alternatively (depending on the value of
3679 @code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
3680 be created and/or used to construct a link@footnote{The library
3681 @file{org-id.el} must first be loaded, either through @code{org-customize} by
3682 enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
3683 'org-id)} in your Emacs init file.}. So using this command in Org buffers
3684 will potentially create two links: a human-readable from the custom ID, and
3685 one that is globally unique and works even if the entry is moved from file to
3686 file. Later, when inserting the link, you need to decide which one to use.
3688 @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
3689 Pretty much all Emacs mail clients are supported. The link will point to the
3690 current article, or, in some GNUS buffers, to the group. The description is
3691 constructed from the author and the subject.
3693 @b{Web browsers: Eww, W3 and W3M}@*
3694 Here the link will be the current URL, with the page title as description.
3696 @b{Contacts: BBDB}@*
3697 Links created in a BBDB buffer will point to the current entry.
3700 @vindex org-irc-link-to-logs
3701 For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t},
3702 a @samp{file:/} style link to the relevant point in the logs for the current
3703 conversation is created. Otherwise an @samp{irc:/} style link to the
3704 user/channel/server under the point will be stored.
3707 For any other files, the link will point to the file, with a search string
3708 (@pxref{Search options}) pointing to the contents of the current line. If
3709 there is an active region, the selected words will form the basis of the
3710 search string. If the automatically created link is not working correctly or
3711 accurately enough, you can write custom functions to select the search string
3712 and to do the search for particular file types---see @ref{Custom searches}.
3713 The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
3716 When the cursor is in an agenda view, the created link points to the
3717 entry referenced by the current line.
3720 @orgcmd{C-c C-l,org-insert-link}
3721 @cindex link completion
3722 @cindex completion, of links
3723 @cindex inserting links
3724 @vindex org-keep-stored-link-after-insertion
3725 @vindex org-link-parameters
3726 Insert a link@footnote{Note that you don't have to use this command to
3727 insert a link. Links in Org are plain text, and you can type or paste them
3728 straight into the buffer. By using this command, the links are automatically
3729 enclosed in double brackets, and you will be asked for the optional
3730 descriptive text.}. This prompts for a link to be inserted into the buffer.
3731 You can just type a link, using text for an internal link, or one of the link
3732 type prefixes mentioned in the examples above. The link will be inserted
3733 into the buffer@footnote{After insertion of a stored link, the link will be
3734 removed from the list of stored links. To keep it in the list later use, use
3735 a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
3736 @code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
3737 If some text was selected when this command is called, the selected text
3738 becomes the default description.
3740 @b{Inserting stored links}@*
3741 All links stored during the
3742 current session are part of the history for this prompt, so you can access
3743 them with @key{up} and @key{down} (or @kbd{M-p/n}).
3745 @b{Completion support}@* Completion with @key{TAB} will help you to insert
3746 valid link prefixes like @samp{https:}, including the prefixes
3747 defined through link abbreviations (@pxref{Link abbreviations}). If you
3748 press @key{RET} after inserting only the @var{prefix}, Org will offer
3749 specific completion support for some link types@footnote{This works if
3750 a completion function is defined in the @samp{:complete} property of a link
3751 in @code{org-link-parameters}.} For example, if you type @kbd{file
3752 @key{RET}}, file name completion (alternative access: @kbd{C-u C-c C-l}, see
3753 below) will be offered, and after @kbd{bbdb @key{RET}} you can complete
3756 @cindex file name completion
3757 @cindex completion, of file names
3758 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
3759 a file will be inserted and you may use file name completion to select
3760 the name of the file. The path to the file is inserted relative to the
3761 directory of the current Org file, if the linked file is in the current
3762 directory or in a sub-directory of it, or if the path is written relative
3763 to the current directory using @samp{../}. Otherwise an absolute path
3764 is used, if possible with @samp{~/} for your home directory. You can
3765 force an absolute path with two @kbd{C-u} prefixes.
3767 @item C-c C-l @ @r{(with cursor on existing link)}
3768 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
3769 link and description parts of the link.
3771 @cindex following links
3772 @orgcmd{C-c C-o,org-open-at-point}
3773 @vindex org-file-apps
3774 @vindex org-link-frame-setup
3775 Open link at point. This will launch a web browser for URLs (using
3776 @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
3777 the corresponding links, and execute the command in a shell link. When the
3778 cursor is on an internal link, this command runs the corresponding search.
3779 When the cursor is on a TAG list in a headline, it creates the corresponding
3780 TAGS view. If the cursor is on a timestamp, it compiles the agenda for that
3781 date. Furthermore, it will visit text and remote files in @samp{file:} links
3782 with Emacs and select a suitable application for local non-text files.
3783 Classification of files is based on file extension only. See option
3784 @code{org-file-apps}. If you want to override the default application and
3785 visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
3786 opening in Emacs, use a @kbd{C-u C-u} prefix.@*
3787 If the cursor is on a headline, but not on a link, offer all links in the
3788 headline and entry text. If you want to setup the frame configuration for
3789 following links, customize @code{org-link-frame-setup}.
3792 @vindex org-return-follows-link
3793 When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
3800 On links, @kbd{mouse-1} and @kbd{mouse-2} will open the link just as @kbd{C-c
3805 @vindex org-display-internal-link-with-indirect-buffer
3806 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
3807 internal links to be displayed in another window@footnote{See the
3808 option @code{org-display-internal-link-with-indirect-buffer}}.
3810 @orgcmd{C-c C-x C-v,org-toggle-inline-images}
3811 @cindex inlining images
3812 @cindex images, inlining
3813 @vindex org-startup-with-inline-images
3814 @cindex @code{inlineimages}, STARTUP keyword
3815 @cindex @code{noinlineimages}, STARTUP keyword
3816 Toggle the inline display of linked images. Normally this will only inline
3817 images that have no description part in the link, i.e., images that will also
3818 be inlined during export. When called with a prefix argument, also display
3819 images that do have a link description. You can ask for inline images to be
3820 displayed at startup by configuring the variable
3821 @code{org-startup-with-inline-images}@footnote{with corresponding
3822 @code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
3823 @orgcmd{C-c %,org-mark-ring-push}
3825 Push the current position onto the mark ring, to be able to return
3826 easily. Commands following an internal link do this automatically.
3828 @orgcmd{C-c &,org-mark-ring-goto}
3829 @cindex links, returning to
3830 Jump back to a recorded position. A position is recorded by the
3831 commands following internal links, and by @kbd{C-c %}. Using this
3832 command several times in direct succession moves through a ring of
3833 previously recorded positions.
3835 @orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
3836 @cindex links, finding next/previous
3837 Move forward/backward to the next link in the buffer. At the limit of
3838 the buffer, the search fails once, and then wraps around. The key
3839 bindings for this are really too long; you might want to bind this also
3840 to @kbd{C-n} and @kbd{C-p}
3842 (add-hook 'org-load-hook
3844 (define-key org-mode-map "\C-n" 'org-next-link)
3845 (define-key org-mode-map "\C-p" 'org-previous-link)))
3849 @node Using links outside Org
3850 @section Using links outside Org
3852 You can insert and follow links that have Org syntax not only in
3853 Org, but in any Emacs buffer. For this, you should create two
3854 global commands, like this (please select suitable global keys
3858 (global-set-key "\C-c L" 'org-insert-link-global)
3859 (global-set-key "\C-c o" 'org-open-at-point-global)
3862 @node Link abbreviations
3863 @section Link abbreviations
3864 @cindex link abbreviations
3865 @cindex abbreviation, links
3867 Long URLs can be cumbersome to type, and often many similar links are
3868 needed in a document. For this you can use link abbreviations. An
3869 abbreviated link looks like this
3872 [[linkword:tag][description]]
3876 @vindex org-link-abbrev-alist
3877 where the tag is optional.
3878 The @i{linkword} must be a word, starting with a letter, followed by
3879 letters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolved
3880 according to the information in the variable @code{org-link-abbrev-alist}
3881 that relates the linkwords to replacement text. Here is an example:
3885 (setq org-link-abbrev-alist
3886 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
3887 ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
3888 ("google" . "http://www.google.com/search?q=")
3889 ("gmap" . "http://maps.google.com/maps?q=%s")
3890 ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
3891 ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
3895 If the replacement text contains the string @samp{%s}, it will be
3896 replaced with the tag. Using @samp{%h} instead of @samp{%s} will
3897 url-encode the tag (see the example above, where we need to encode
3898 the URL parameter.) Using @samp{%(my-function)} will pass the tag
3899 to a custom function, and replace it by the resulting string.
3901 If the replacement text doesn't contain any specifier, the tag will simply be
3902 appended in order to create the link.
3904 Instead of a string, you may also specify a function that will be
3905 called with the tag as the only argument to create the link.
3907 With the above setting, you could link to a specific bug with
3908 @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
3909 @code{[[google:OrgMode]]}, show the map location of the Free Software
3910 Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
3911 @code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
3912 what the Org author is doing besides Emacs hacking with
3913 @code{[[ads:Dominik,C]]}.
3915 If you need special abbreviations just for a single Org buffer, you
3916 can define them in the file with
3920 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
3921 #+LINK: google http://www.google.com/search?q=%s
3925 In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
3926 complete link abbreviations. You may also define a function that implements
3927 special (e.g., completion) support for inserting such a link with @kbd{C-c
3928 C-l}. Such a function should not accept any arguments, and return the full
3929 link with prefix. You can add a completion function to a link like this:
3932 (org-link-set-parameters ``type'' :complete #'some-function)
3936 @node Search options
3937 @section Search options in file links
3938 @cindex search option in file links
3939 @cindex file links, searching
3941 File links can contain additional information to make Emacs jump to a
3942 particular location in the file when following a link. This can be a
3943 line number or a search option after a double@footnote{For backward
3944 compatibility, line numbers can also follow a single colon.} colon. For
3945 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
3946 links}) to a file, it encodes the words in the current line as a search
3947 string that can be used to find this line back later when following the
3948 link with @kbd{C-c C-o}.
3950 Here is the syntax of the different ways to attach a search to a file
3951 link, together with an explanation:
3954 [[file:~/code/main.c::255]]
3955 [[file:~/xx.org::My Target]]
3956 [[file:~/xx.org::*My Target]]
3957 [[file:~/xx.org::#my-custom-id]]
3958 [[file:~/xx.org::/regexp/]]
3965 Search for a link target @samp{<<My Target>>}, or do a text search for
3966 @samp{my target}, similar to the search in internal links, see
3967 @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
3968 link will become an HTML reference to the corresponding named anchor in
3971 In an Org file, restrict search to headlines.
3973 Link to a heading with a @code{CUSTOM_ID} property
3975 Do a regular expression search for @code{regexp}. This uses the Emacs
3976 command @code{occur} to list all matches in a separate window. If the
3977 target file is in Org mode, @code{org-occur} is used to create a
3978 sparse tree with the matches.
3979 @c If the target file is a directory,
3980 @c @code{grep} will be used to search all files in the directory.
3983 As a degenerate case, a file link with an empty file name can be used
3984 to search the current file. For example, @code{[[file:::find me]]} does
3985 a search for @samp{find me} in the current file, just as
3986 @samp{[[find me]]} would.
3988 @node Custom searches
3989 @section Custom Searches
3990 @cindex custom search strings
3991 @cindex search strings, custom
3993 The default mechanism for creating search strings and for doing the
3994 actual search related to a file link may not work correctly in all
3995 cases. For example, Bib@TeX{} database files have many entries like
3996 @samp{year="1993"} which would not result in good search strings,
3997 because the only unique identification for a Bib@TeX{} entry is the
4000 @vindex org-create-file-search-functions
4001 @vindex org-execute-file-search-functions
4002 If you come across such a problem, you can write custom functions to set
4003 the right search string for a particular file type, and to do the search
4004 for the string in the file. Using @code{add-hook}, these functions need
4005 to be added to the hook variables
4006 @code{org-create-file-search-functions} and
4007 @code{org-execute-file-search-functions}. See the docstring for these
4008 variables for more information. Org actually uses this mechanism
4009 for Bib@TeX{} database files, and you can use the corresponding code as
4010 an implementation example. See the file @file{org-bibtex.el}.
4016 Org mode does not maintain TODO lists as separate documents@footnote{Of
4017 course, you can make a document that contains only long lists of TODO items,
4018 but this is not required.}. Instead, TODO items are an integral part of the
4019 notes file, because TODO items usually come up while taking notes! With Org
4020 mode, simply mark any entry in a tree as being a TODO item. In this way,
4021 information is not duplicated, and the entire context from which the TODO
4022 item emerged is always present.
4024 Of course, this technique for managing TODO items scatters them
4025 throughout your notes file. Org mode compensates for this by providing
4026 methods to give you an overview of all the things that you have to do.
4029 * TODO basics:: Marking and displaying TODO entries
4030 * TODO extensions:: Workflow and assignments
4031 * Progress logging:: Dates and notes for progress
4032 * Priorities:: Some things are more important than others
4033 * Breaking down tasks:: Splitting a task into manageable pieces
4034 * Checkboxes:: Tick-off lists
4038 @section Basic TODO functionality
4040 Any headline becomes a TODO item when it starts with the word
4041 @samp{TODO}, for example:
4044 *** TODO Write letter to Sam Fortune
4048 The most important commands to work with TODO entries are:
4051 @orgcmd{C-c C-t,org-todo}
4052 @cindex cycling, of TODO states
4053 @vindex org-use-fast-todo-selection
4055 Rotate the TODO state of the current item among
4058 ,-> (unmarked) -> TODO -> DONE --.
4059 '--------------------------------'
4062 If TODO keywords have fast access keys (see @ref{Fast access to TODO
4063 states}), you will be prompted for a TODO keyword through the fast selection
4064 interface; this is the default behavior when
4065 @code{org-use-fast-todo-selection} is non-@code{nil}.
4067 The same rotation can also be done ``remotely'' from agenda buffers with the
4068 @kbd{t} command key (@pxref{Agenda commands}).
4070 @orgkey{C-u C-c C-t}
4071 When TODO keywords have no selection keys, select a specific keyword using
4072 completion; otherwise force cycling through TODO states with no prompt. When
4073 @code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
4074 selection interface.
4076 @kindex S-@key{right}
4077 @kindex S-@key{left}
4078 @item S-@key{right} @ @r{/} @ S-@key{left}
4079 @vindex org-treat-S-cursor-todo-selection-as-state-change
4080 Select the following/preceding TODO state, similar to cycling. Useful
4081 mostly if more than two TODO states are possible (@pxref{TODO
4082 extensions}). See also @ref{Conflicts}, for a discussion of the interaction
4083 with @code{shift-selection-mode}. See also the variable
4084 @code{org-treat-S-cursor-todo-selection-as-state-change}.
4085 @orgcmd{C-c / t,org-show-todo-tree}
4086 @cindex sparse tree, for TODO
4087 @vindex org-todo-keywords
4088 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
4089 entire buffer, but shows all TODO items (with not-DONE state) and the
4090 headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
4091 / T}), search for a specific TODO@. You will be prompted for the keyword,
4092 and you can also give a list of keywords like @code{KWD1|KWD2|...} to list
4093 entries that match any one of these keywords. With a numeric prefix argument
4094 N, show the tree for the Nth keyword in the option @code{org-todo-keywords}.
4095 With two prefix arguments, find all TODO states, both un-done and done.
4096 @orgcmd{C-c a t,org-todo-list}
4097 Show the global TODO list. Collects the TODO items (with not-DONE states)
4098 from all agenda files (@pxref{Agenda views}) into a single buffer. The new
4099 buffer will be in @code{agenda-mode}, which provides commands to examine and
4100 manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
4101 @xref{Global TODO list}, for more information.
4102 @orgcmd{S-M-@key{RET},org-insert-todo-heading}
4103 Insert a new TODO entry below the current one.
4107 @vindex org-todo-state-tags-triggers
4108 Changing a TODO state can also trigger tag changes. See the docstring of the
4109 option @code{org-todo-state-tags-triggers} for details.
4111 @node TODO extensions
4112 @section Extended use of TODO keywords
4113 @cindex extended TODO keywords
4115 @vindex org-todo-keywords
4116 By default, marked TODO entries have one of only two states: TODO and
4117 DONE@. Org mode allows you to classify TODO items in more complex ways
4118 with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
4119 special setup, the TODO keyword system can work differently in different
4122 Note that @i{tags} are another way to classify headlines in general and
4123 TODO items in particular (@pxref{Tags}).
4126 * Workflow states:: From TODO to DONE in steps
4127 * TODO types:: I do this, Fred does the rest
4128 * Multiple sets in one file:: Mixing it all, and still finding your way
4129 * Fast access to TODO states:: Single letter selection of a state
4130 * Per-file keywords:: Different files, different requirements
4131 * Faces for TODO keywords:: Highlighting states
4132 * TODO dependencies:: When one task needs to wait for others
4135 @node Workflow states
4136 @subsection TODO keywords as workflow states
4137 @cindex TODO workflow
4138 @cindex workflow states as TODO keywords
4140 You can use TODO keywords to indicate different @emph{sequential} states
4141 in the process of working on an item, for example@footnote{Changing
4142 this variable only becomes effective after restarting Org mode in a
4146 (setq org-todo-keywords
4147 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
4150 The vertical bar separates the TODO keywords (states that @emph{need
4151 action}) from the DONE states (which need @emph{no further action}). If
4152 you don't provide the separator bar, the last state is used as the DONE
4154 @cindex completion, of TODO keywords
4155 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
4156 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@. You may
4157 also use a numeric prefix argument to quickly select a specific state. For
4158 example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
4159 Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
4160 define many keywords, you can use in-buffer completion
4161 (@pxref{Completion}) or even a special one-key selection scheme
4162 (@pxref{Fast access to TODO states}) to insert these words into the
4163 buffer. Changing a TODO state can be logged with a timestamp, see
4164 @ref{Tracking TODO state changes}, for more information.
4167 @subsection TODO keywords as types
4169 @cindex names as TODO keywords
4170 @cindex types as TODO keywords
4172 The second possibility is to use TODO keywords to indicate different
4173 @emph{types} of action items. For example, you might want to indicate
4174 that items are for ``work'' or ``home''. Or, when you work with several
4175 people on a single project, you might want to assign action items
4176 directly to persons, by using their names as TODO keywords. This would
4177 be set up like this:
4180 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
4183 In this case, different keywords do not indicate a sequence, but rather
4184 different types. So the normal work flow would be to assign a task to
4185 a person, and later to mark it DONE@. Org mode supports this style by
4186 adapting the workings of the command @kbd{C-c C-t}@footnote{This is also true
4187 for the @kbd{t} command in the agenda buffers.}. When used several times in
4188 succession, it will still cycle through all names, in order to first select
4189 the right type for a task. But when you return to the item after some time
4190 and execute @kbd{C-c C-t} again, it will switch from any name directly to
4191 DONE@. Use prefix arguments or completion to quickly select a specific name.
4192 You can also review the items of a specific TODO type in a sparse tree by
4193 using a numeric prefix to @kbd{C-c / t}. For example, to see all things Lucy
4194 has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items from all
4195 agenda files into a single buffer, you would use the numeric prefix argument
4196 as well when creating the global TODO list: @kbd{C-3 C-c a t}.
4198 @node Multiple sets in one file
4199 @subsection Multiple keyword sets in one file
4200 @cindex TODO keyword sets
4202 Sometimes you may want to use different sets of TODO keywords in
4203 parallel. For example, you may want to have the basic
4204 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
4205 separate state indicating that an item has been canceled (so it is not
4206 DONE, but also does not require action). Your setup would then look
4210 (setq org-todo-keywords
4211 '((sequence "TODO" "|" "DONE")
4212 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
4213 (sequence "|" "CANCELED")))
4216 The keywords should all be different, this helps Org mode to keep track
4217 of which subsequence should be used for a given entry. In this setup,
4218 @kbd{C-c C-t} only operates within a subsequence, so it switches from
4219 @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
4220 (nothing) to @code{REPORT}. Therefore you need a mechanism to initially
4221 select the correct sequence. Besides the obvious ways like typing a
4222 keyword or using completion, you may also apply the following commands:
4225 @kindex C-S-@key{right}
4226 @kindex C-S-@key{left}
4227 @kindex C-u C-u C-c C-t
4228 @item C-u C-u C-c C-t
4229 @itemx C-S-@key{right}
4230 @itemx C-S-@key{left}
4231 These keys jump from one TODO subset to the next. In the above example,
4232 @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or
4233 @code{DONE} to @code{REPORT}, and any of the words in the second row to
4234 @code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with
4235 @code{shift-selection-mode} (@pxref{Conflicts}).
4236 @kindex S-@key{right}
4237 @kindex S-@key{left}
4240 @kbd{S-@key{left}} and @kbd{S-@key{right}} and walk through @emph{all}
4241 keywords from all sets, so for example @kbd{S-@key{right}} would switch
4242 from @code{DONE} to @code{REPORT} in the example above. See also
4243 @ref{Conflicts}, for a discussion of the interaction with
4244 @code{shift-selection-mode}.
4247 @node Fast access to TODO states
4248 @subsection Fast access to TODO states
4250 If you would like to quickly change an entry to an arbitrary TODO state
4251 instead of cycling through the states, you can set up keys for single-letter
4252 access to the states. This is done by adding the selection character after
4253 each keyword, in parentheses@footnote{All characters are allowed except
4254 @code{@@^!}, which have a special meaning here.}. For example:
4257 (setq org-todo-keywords
4258 '((sequence "TODO(t)" "|" "DONE(d)")
4259 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
4260 (sequence "|" "CANCELED(c)")))
4263 @vindex org-fast-tag-selection-include-todo
4264 If you then press @kbd{C-c C-t} followed by the selection key, the entry
4265 will be switched to this state. @kbd{SPC} can be used to remove any TODO
4266 keyword from an entry.@footnote{Check also the option
4267 @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
4268 state through the tags interface (@pxref{Setting tags}), in case you like to
4269 mingle the two concepts. Note that this means you need to come up with
4270 unique keys across both sets of keywords.}
4272 @node Per-file keywords
4273 @subsection Setting up keywords for individual files
4274 @cindex keyword options
4275 @cindex per-file keywords
4280 It can be very useful to use different aspects of the TODO mechanism in
4281 different files. For file-local settings, you need to add special lines to
4282 the file which set the keywords and interpretation for that file only. For
4283 example, to set one of the two examples discussed above, you need one of the
4284 following lines anywhere in the file:
4287 #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
4289 @noindent (you may also write @code{#+SEQ_TODO} to be explicit about the
4290 interpretation, but it means the same as @code{#+TODO}), or
4292 #+TYP_TODO: Fred Sara Lucy Mike | DONE
4295 A setup for using several sets in parallel would be:
4299 #+TODO: REPORT BUG KNOWNCAUSE | FIXED
4303 @cindex completion, of option keywords
4305 @noindent To make sure you are using the correct keyword, type
4306 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
4308 @cindex DONE, final TODO keyword
4309 Remember that the keywords after the vertical bar (or the last keyword
4310 if no bar is there) must always mean that the item is DONE (although you
4311 may use a different word). After changing one of these lines, use
4312 @kbd{C-c C-c} with the cursor still in the line to make the changes
4313 known to Org mode@footnote{Org mode parses these lines only when
4314 Org mode is activated after visiting a file. @kbd{C-c C-c} with the
4315 cursor in a line starting with @samp{#+} is simply restarting Org mode
4316 for the current buffer.}.
4318 @node Faces for TODO keywords
4319 @subsection Faces for TODO keywords
4320 @cindex faces, for TODO keywords
4322 @vindex org-todo @r{(face)}
4323 @vindex org-done @r{(face)}
4324 @vindex org-todo-keyword-faces
4325 Org mode highlights TODO keywords with special faces: @code{org-todo}
4326 for keywords indicating that an item still has to be acted upon, and
4327 @code{org-done} for keywords indicating that an item is finished. If
4328 you are using more than 2 different states, you might want to use
4329 special faces for some of them. This can be done using the option
4330 @code{org-todo-keyword-faces}. For example:
4334 (setq org-todo-keyword-faces
4335 '(("TODO" . org-warning) ("STARTED" . "yellow")
4336 ("CANCELED" . (:foreground "blue" :weight bold))))
4340 While using a list with face properties as shown for CANCELED @emph{should}
4341 work, this does not always seem to be the case. If necessary, define a
4342 special face and use that. A string is interpreted as a color. The option
4343 @code{org-faces-easy-properties} determines if that color is interpreted as a
4344 foreground or a background color.
4346 @node TODO dependencies
4347 @subsection TODO dependencies
4348 @cindex TODO dependencies
4349 @cindex dependencies, of TODO states
4350 @cindex TODO dependencies, NOBLOCKING
4352 @vindex org-enforce-todo-dependencies
4353 @cindex property, ORDERED
4354 The structure of Org files (hierarchy and lists) makes it easy to define TODO
4355 dependencies. Usually, a parent TODO task should not be marked DONE until
4356 all subtasks (defined as children tasks) are marked as DONE@. And sometimes
4357 there is a logical sequence to a number of (sub)tasks, so that one task
4358 cannot be acted upon before all siblings above it are done. If you customize
4359 the option @code{org-enforce-todo-dependencies}, Org will block entries
4360 from changing state to DONE while they have children that are not DONE@.
4361 Furthermore, if an entry has a property @code{ORDERED}, each of its children
4362 will be blocked until all earlier siblings are marked DONE@. Here is an
4366 * TODO Blocked until (two) is done
4375 ** TODO b, needs to wait for (a)
4376 ** TODO c, needs to wait for (a) and (b)
4379 You can ensure an entry is never blocked by using the @code{NOBLOCKING}
4383 * This entry is never blocked
4390 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4391 @vindex org-track-ordered-property-with-tag
4392 @cindex property, ORDERED
4393 Toggle the @code{ORDERED} property of the current entry. A property is used
4394 for this behavior because this should be local to the current entry, not
4395 inherited like a tag. However, if you would like to @i{track} the value of
4396 this property with a tag for better visibility, customize the option
4397 @code{org-track-ordered-property-with-tag}.
4398 @orgkey{C-u C-u C-u C-c C-t}
4399 Change TODO state, circumventing any state blocking.
4402 @vindex org-agenda-dim-blocked-tasks
4403 If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries
4404 that cannot be closed because of such dependencies will be shown in a dimmed
4405 font or even made invisible in agenda views (@pxref{Agenda views}).
4407 @cindex checkboxes and TODO dependencies
4408 @vindex org-enforce-todo-dependencies
4409 You can also block changes of TODO states by looking at checkboxes
4410 (@pxref{Checkboxes}). If you set the option
4411 @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
4412 checkboxes will be blocked from switching to DONE.
4414 If you need more complex dependency structures, for example dependencies
4415 between entries in different trees or files, check out the contributed
4416 module @file{org-depend.el}.
4419 @node Progress logging
4420 @section Progress logging
4421 @cindex progress logging
4422 @cindex logging, of progress
4424 Org mode can automatically record a timestamp and possibly a note when
4425 you mark a TODO item as DONE, or even each time you change the state of
4426 a TODO item. This system is highly configurable; settings can be on a
4427 per-keyword basis and can be localized to a file or even a subtree. For
4428 information on how to clock working time for a task, see @ref{Clocking
4432 * Closing items:: When was this entry marked DONE?
4433 * Tracking TODO state changes:: When did the status change?
4434 * Tracking your habits:: How consistent have you been?
4438 @subsection Closing items
4440 The most basic logging is to keep track of @emph{when} a certain TODO
4441 item was finished. This is achieved with@footnote{The corresponding
4442 in-buffer setting is: @code{#+STARTUP: logdone}}
4445 (setq org-log-done 'time)
4448 @vindex org-closed-keep-when-no-todo
4450 Then each time you turn an entry from a TODO (not-done) state into any of the
4451 DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
4452 the headline. If you turn the entry back into a TODO item through further
4453 state cycling, that line will be removed again. If you turn the entry back
4454 to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line
4455 will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
4456 non-@code{nil}. If you want to record a note along with the timestamp,
4457 use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
4461 (setq org-log-done 'note)
4465 You will then be prompted for a note, and that note will be stored below
4466 the entry with a @samp{Closing Note} heading.
4468 @node Tracking TODO state changes
4469 @subsection Tracking TODO state changes
4470 @cindex drawer, for state change recording
4472 @vindex org-log-states-order-reversed
4473 @vindex org-log-into-drawer
4474 @cindex property, LOG_INTO_DRAWER
4475 When TODO keywords are used as workflow states (@pxref{Workflow states}), you
4476 might want to keep track of when a state change occurred and maybe take a
4477 note about this change. You can either record just a timestamp, or a
4478 time-stamped note for a change. These records will be inserted after the
4479 headline as an itemized list, newest first@footnote{See the option
4480 @code{org-log-states-order-reversed}}. When taking a lot of notes, you might
4481 want to get the notes out of the way into a drawer (@pxref{Drawers}).
4482 Customize @code{org-log-into-drawer} to get this behavior---the recommended
4483 drawer for this is called @code{LOGBOOK}@footnote{Note that the
4484 @code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to
4485 show an entry---use @key{C-u SPC} to keep it folded here}. You can also
4486 overrule the setting of this variable for a subtree by setting a
4487 @code{LOG_INTO_DRAWER} property.
4489 Since it is normally too much to record a note for every state, Org mode
4490 expects configuration on a per-keyword basis for this. This is achieved by
4491 adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note
4492 with timestamp) in parentheses after each keyword. For example, with the
4496 (setq org-todo-keywords
4497 '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
4500 To record a timestamp without a note for TODO keywords configured with
4501 @samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
4504 @vindex org-log-done
4505 You not only define global TODO keywords and fast access keys, but also
4506 request that a time is recorded when the entry is set to
4507 DONE@footnote{It is possible that Org mode will record two timestamps
4508 when you are using both @code{org-log-done} and state change logging.
4509 However, it will never prompt for two notes---if you have configured
4510 both, the state change recording note will take precedence and cancel
4511 the @samp{Closing Note}.}, and that a note is recorded when switching to
4512 WAIT or CANCELED@. The setting for WAIT is even more special: the
4513 @samp{!} after the slash means that in addition to the note taken when
4514 entering the state, a timestamp should be recorded when @i{leaving} the
4515 WAIT state, if and only if the @i{target} state does not configure
4516 logging for entering it. So it has no effect when switching from WAIT
4517 to DONE, because DONE is configured to record a timestamp only. But
4518 when switching from WAIT back to TODO, the @samp{/!} in the WAIT
4519 setting now triggers a timestamp even though TODO has no logging
4522 You can use the exact same syntax for setting logging preferences local
4525 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
4528 @cindex property, LOGGING
4529 In order to define logging settings that are local to a subtree or a
4530 single item, define a LOGGING property in this entry. Any non-empty
4531 LOGGING property resets all logging settings to @code{nil}. You may then turn
4532 on logging for this specific tree using STARTUP keywords like
4533 @code{lognotedone} or @code{logrepeat}, as well as adding state specific
4534 settings like @code{TODO(!)}. For example
4537 * TODO Log each state with only a time
4539 :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
4541 * TODO Only log when switching to WAIT, and when repeating
4543 :LOGGING: WAIT(@@) logrepeat
4545 * TODO No logging at all
4551 @node Tracking your habits
4552 @subsection Tracking your habits
4555 Org has the ability to track the consistency of a special category of TODOs,
4556 called ``habits''. A habit has the following properties:
4560 You have enabled the @code{habits} module by customizing @code{org-modules}.
4562 The habit is a TODO item, with a TODO keyword representing an open state.
4564 The property @code{STYLE} is set to the value @code{habit}.
4566 The TODO has a scheduled date, usually with a @code{.+} style repeat
4567 interval. A @code{++} style may be appropriate for habits with time
4568 constraints, e.g., must be done on weekends, or a @code{+} style for an
4569 unusual habit that can have a backlog, e.g., weekly reports.
4571 The TODO may also have minimum and maximum ranges specified by using the
4572 syntax @samp{.+2d/3d}, which says that you want to do the task at least every
4573 three days, but at most every two days.
4575 You must also have state logging for the @code{DONE} state enabled
4576 (@pxref{Tracking TODO state changes}), in order for historical data to be
4577 represented in the consistency graph. If it is not enabled it is not an
4578 error, but the consistency graphs will be largely meaningless.
4581 To give you an idea of what the above rules look like in action, here's an
4582 actual habit with some history:
4586 SCHEDULED: <2009-10-17 Sat .+2d/4d>
4589 :LAST_REPEAT: [2009-10-19 Mon 00:36]
4591 - State "DONE" from "TODO" [2009-10-15 Thu]
4592 - State "DONE" from "TODO" [2009-10-12 Mon]
4593 - State "DONE" from "TODO" [2009-10-10 Sat]
4594 - State "DONE" from "TODO" [2009-10-04 Sun]
4595 - State "DONE" from "TODO" [2009-10-02 Fri]
4596 - State "DONE" from "TODO" [2009-09-29 Tue]
4597 - State "DONE" from "TODO" [2009-09-25 Fri]
4598 - State "DONE" from "TODO" [2009-09-19 Sat]
4599 - State "DONE" from "TODO" [2009-09-16 Wed]
4600 - State "DONE" from "TODO" [2009-09-12 Sat]
4603 What this habit says is: I want to shave at most every 2 days (given by the
4604 @code{SCHEDULED} date and repeat interval) and at least every 4 days. If
4605 today is the 15th, then the habit first appears in the agenda on Oct 17,
4606 after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
4607 after four days have elapsed.
4609 What's really useful about habits is that they are displayed along with a
4610 consistency graph, to show how consistent you've been at getting that task
4611 done in the past. This graph shows every day that the task was done over the
4612 past three weeks, with colors for each day. The colors used are:
4616 If the task wasn't to be done yet on that day.
4618 If the task could have been done on that day.
4620 If the task was going to be overdue the next day.
4622 If the task was overdue on that day.
4625 In addition to coloring each day, the day is also marked with an asterisk if
4626 the task was actually done that day, and an exclamation mark to show where
4627 the current day falls in the graph.
4629 There are several configuration variables that can be used to change the way
4630 habits are displayed in the agenda.
4633 @item org-habit-graph-column
4634 The buffer column at which the consistency graph should be drawn. This will
4635 overwrite any text in that column, so it is a good idea to keep your habits'
4636 titles brief and to the point.
4637 @item org-habit-preceding-days
4638 The amount of history, in days before today, to appear in consistency graphs.
4639 @item org-habit-following-days
4640 The number of days after today that will appear in consistency graphs.
4641 @item org-habit-show-habits-only-for-today
4642 If non-@code{nil}, only show habits in today's agenda view. This is set to true by
4646 Lastly, pressing @kbd{K} in the agenda buffer will cause habits to
4647 temporarily be disabled and they won't appear at all. Press @kbd{K} again to
4648 bring them back. They are also subject to tag filtering, if you have habits
4649 which should only be done in certain contexts, for example.
4655 If you use Org mode extensively, you may end up with enough TODO items that
4656 it starts to make sense to prioritize them. Prioritizing can be done by
4657 placing a @emph{priority cookie} into the headline of a TODO item, like this
4660 *** TODO [#A] Write letter to Sam Fortune
4664 @vindex org-priority-faces
4665 By default, Org mode supports three priorities: @samp{A}, @samp{B}, and
4666 @samp{C}. @samp{A} is the highest priority. An entry without a cookie is
4667 treated just like priority @samp{B}. Priorities make a difference only for
4668 sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
4669 have no inherent meaning to Org mode. The cookies can be highlighted with
4670 special faces by customizing @code{org-priority-faces}.
4672 Priorities can be attached to any outline node; they do not need to be TODO
4678 @findex org-priority
4679 Set the priority of the current headline (@command{org-priority}). The
4680 command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
4681 When you press @key{SPC} instead, the priority cookie is removed from the
4682 headline. The priorities can also be changed ``remotely'' from the agenda
4683 buffer with the @kbd{,} command (@pxref{Agenda commands}).
4685 @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
4686 @vindex org-priority-start-cycle-with-default
4687 Increase/decrease priority of current headline@footnote{See also the option
4688 @code{org-priority-start-cycle-with-default}.}. Note that these keys are
4689 also used to modify timestamps (@pxref{Creating timestamps}). See also
4690 @ref{Conflicts}, for a discussion of the interaction with
4691 @code{shift-selection-mode}.
4694 @vindex org-highest-priority
4695 @vindex org-lowest-priority
4696 @vindex org-default-priority
4697 You can change the range of allowed priorities by setting the options
4698 @code{org-highest-priority}, @code{org-lowest-priority}, and
4699 @code{org-default-priority}. For an individual buffer, you may set
4700 these values (highest, lowest, default) like this (please make sure that
4701 the highest priority is earlier in the alphabet than the lowest
4704 @cindex #+PRIORITIES
4709 @node Breaking down tasks
4710 @section Breaking tasks down into subtasks
4711 @cindex tasks, breaking down
4712 @cindex statistics, for TODO items
4714 @vindex org-agenda-todo-list-sublevels
4715 It is often advisable to break down large tasks into smaller, manageable
4716 subtasks. You can do this by creating an outline tree below a TODO item,
4717 with detailed subtasks on the tree@footnote{To keep subtasks out of the
4718 global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep
4719 the overview over the fraction of subtasks that are already completed, insert
4720 either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will
4721 be updated each time the TODO status of a child changes, or when pressing
4722 @kbd{C-c C-c} on the cookie. For example:
4725 * Organize Party [33%]
4726 ** TODO Call people [1/2]
4730 ** DONE Talk to neighbor
4733 @cindex property, COOKIE_DATA
4734 If a heading has both checkboxes and TODO children below it, the meaning of
4735 the statistics cookie become ambiguous. Set the property
4736 @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
4739 @vindex org-hierarchical-todo-statistics
4740 If you would like to have the statistics cookie count any TODO entries in the
4741 subtree (not just direct children), configure
4742 @code{org-hierarchical-todo-statistics}. To do this for a single subtree,
4743 include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
4747 * Parent capturing statistics [2/20]
4749 :COOKIE_DATA: todo recursive
4753 If you would like a TODO entry to automatically change to DONE
4754 when all children are done, you can use the following setup:
4757 (defun org-summary-todo (n-done n-not-done)
4758 "Switch entry to DONE when all subentries are done, to TODO otherwise."
4759 (let (org-log-done org-log-states) ; turn off logging
4760 (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
4762 (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
4766 Another possibility is the use of checkboxes to identify (a hierarchy of) a
4767 large number of subtasks (@pxref{Checkboxes}).
4774 @vindex org-list-automatic-rules
4775 Every item in a plain list@footnote{With the exception of description
4776 lists. But you can allow it by modifying @code{org-list-automatic-rules}
4777 accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
4778 it with the string @samp{[ ]}. This feature is similar to TODO items
4779 (@pxref{TODO items}), but is more lightweight. Checkboxes are not included
4780 in the global TODO list, so they are often great to split a task into a
4781 number of simple steps. Or you can use them in a shopping list. To toggle a
4782 checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
4783 @file{org-mouse.el}).
4785 Here is an example of a checkbox list.
4788 * TODO Organize party [2/4]
4789 - [-] call people [1/3]
4794 - [ ] think about what music to play
4795 - [X] talk to the neighbors
4798 Checkboxes work hierarchically, so if a checkbox item has children that
4799 are checkboxes, toggling one of the children checkboxes will make the
4800 parent checkbox reflect if none, some, or all of the children are
4803 @cindex statistics, for checkboxes
4804 @cindex checkbox statistics
4805 @cindex property, COOKIE_DATA
4806 @vindex org-checkbox-hierarchical-statistics
4807 The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
4808 indicating how many checkboxes present in this entry have been checked off,
4809 and the total number of checkboxes present. This can give you an idea on how
4810 many checkboxes remain, even without opening a folded entry. The cookies can
4811 be placed into a headline or into (the first line of) a plain list item.
4812 Each cookie covers checkboxes of direct children structurally below the
4813 headline/item on which the cookie appears@footnote{Set the option
4814 @code{org-checkbox-hierarchical-statistics} if you want such cookies to
4815 count all checkboxes below the cookie, not just those belonging to direct
4816 children.}. You have to insert the cookie yourself by typing either
4817 @samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}
4818 result, as in the examples above. With @samp{[%]} you get information about
4819 the percentage of checkboxes checked (in the above example, this would be
4820 @samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie can
4821 count either checkboxes below the heading or TODO states of children, and it
4822 will display whatever was changed last. Set the property @code{COOKIE_DATA}
4823 to either @samp{checkbox} or @samp{todo} to resolve this issue.
4825 @cindex blocking, of checkboxes
4826 @cindex checkbox blocking
4827 @cindex property, ORDERED
4828 If the current outline node has an @code{ORDERED} property, checkboxes must
4829 be checked off in sequence, and an error will be thrown if you try to check
4830 off a box while there are unchecked boxes above it.
4832 @noindent The following commands work with checkboxes:
4835 @orgcmd{C-c C-c,org-toggle-checkbox}
4836 Toggle checkbox status or (with prefix arg) checkbox presence at point. With
4837 a single prefix argument, add an empty checkbox or remove the current
4838 one@footnote{@kbd{C-u C-c C-c} before the @emph{first} bullet in a list with
4839 no checkbox will add checkboxes to the rest of the list.}. With a double
4840 prefix argument, set it to @samp{[-]}, which is considered to be an
4842 @orgcmd{C-c C-x C-b,org-toggle-checkbox}
4843 Toggle checkbox status or (with prefix arg) checkbox presence at point. With
4844 double prefix argument, set it to @samp{[-]}, which is considered to be an
4848 If there is an active region, toggle the first checkbox in the region
4849 and set all remaining boxes to the same status as the first. With a prefix
4850 arg, add or remove the checkbox for all items in the region.
4852 If the cursor is in a headline, toggle the state of the first checkbox in the
4853 region between this headline and the next---so @emph{not} the entire
4854 subtree---and propagate this new state to all other checkboxes in the same
4857 If there is no active region, just toggle the checkbox at point.
4859 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
4860 Insert a new item with a checkbox. This works only if the cursor is already
4861 in a plain list item (@pxref{Plain lists}).
4862 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4863 @vindex org-track-ordered-property-with-tag
4864 @cindex property, ORDERED
4865 Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
4866 be checked off in sequence. A property is used for this behavior because
4867 this should be local to the current entry, not inherited like a tag.
4868 However, if you would like to @i{track} the value of this property with a tag
4869 for better visibility, customize @code{org-track-ordered-property-with-tag}.
4870 @orgcmd{C-c #,org-update-statistics-cookies}
4871 Update the statistics cookie in the current outline entry. When called with
4872 a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are
4873 updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
4874 new ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update when
4875 changing TODO states. If you delete boxes/entries or add/change them by
4876 hand, use this command to get things back into sync.
4882 @cindex headline tagging
4883 @cindex matching, tags
4884 @cindex sparse tree, tag based
4886 An excellent way to implement labels and contexts for cross-correlating
4887 information is to assign @i{tags} to headlines. Org mode has extensive
4890 @vindex org-tag-faces
4891 Every headline can contain a list of tags; they occur at the end of the
4892 headline. Tags are normal words containing letters, numbers, @samp{_}, and
4893 @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
4894 @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
4895 Tags will by default be in bold face with the same color as the headline.
4896 You may specify special faces for specific tags using the option
4897 @code{org-tag-faces}, in much the same way as you can for TODO keywords
4898 (@pxref{Faces for TODO keywords}).
4901 * Tag inheritance:: Tags use the tree structure of the outline
4902 * Setting tags:: How to assign tags to a headline
4903 * Tag hierarchy:: Create a hierarchy of tags
4904 * Tag searches:: Searching for combinations of tags
4907 @node Tag inheritance
4908 @section Tag inheritance
4909 @cindex tag inheritance
4910 @cindex inheritance, of tags
4911 @cindex sublevels, inclusion into tags match
4913 @i{Tags} make use of the hierarchical structure of outline trees. If a
4914 heading has a certain tag, all subheadings will inherit the tag as
4915 well. For example, in the list
4918 * Meeting with the French group :work:
4919 ** Summary by Frank :boss:notes:
4920 *** TODO Prepare slides for him :action:
4924 the final heading will have the tags @samp{:work:}, @samp{:boss:},
4925 @samp{:notes:}, and @samp{:action:} even though the final heading is not
4926 explicitly marked with all those tags. You can also set tags that all
4927 entries in a file should inherit just as if these tags were defined in
4928 a hypothetical level zero that surrounds the entire file. Use a line like
4929 this@footnote{As with all these in-buffer settings, pressing @kbd{C-c C-c}
4930 activates any changes in the line.}:
4934 #+FILETAGS: :Peter:Boss:Secret:
4938 @vindex org-use-tag-inheritance
4939 @vindex org-tags-exclude-from-inheritance
4940 To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
4941 To turn it off entirely, use @code{org-use-tag-inheritance}.
4943 @vindex org-tags-match-list-sublevels
4944 When a headline matches during a tags search while tag inheritance is turned
4945 on, all the sublevels in the same tree will (for a simple match form) match
4946 as well@footnote{This is only true if the search does not involve more
4947 complex tests including properties (@pxref{Property searches}).}. The list
4948 of matches may then become very long. If you only want to see the first tags
4949 match in a subtree, configure @code{org-tags-match-list-sublevels} (not
4952 @vindex org-agenda-use-tag-inheritance
4953 Tag inheritance is relevant when the agenda search tries to match a tag,
4954 either in the @code{tags} or @code{tags-todo} agenda types. In other agenda
4955 types, @code{org-use-tag-inheritance} has no effect. Still, you may want to
4956 have your tags correctly set in the agenda, so that tag filtering works fine,
4957 with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control
4958 this: the default value includes all agenda types, but setting this to @code{nil}
4959 can really speed up agenda generation.
4962 @section Setting tags
4963 @cindex setting tags
4964 @cindex tags, setting
4967 Tags can simply be typed into the buffer at the end of a headline.
4968 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
4969 also a special command for inserting tags:
4972 @orgcmd{C-c C-q,org-set-tags-command}
4973 @cindex completion, of tags
4974 @vindex org-tags-column
4975 Enter new tags for the current headline. Org mode will either offer
4976 completion or a special single-key interface for setting tags, see
4977 below. After pressing @key{RET}, the tags will be inserted and aligned
4978 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
4979 tags in the current buffer will be aligned to that column, just to make
4980 things look nice. TAGS are automatically realigned after promotion,
4981 demotion, and TODO state changes (@pxref{TODO basics}).
4983 @orgcmd{C-c C-c,org-set-tags-command}
4984 When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
4987 @vindex org-tag-alist
4988 Org supports tag insertion based on a @emph{list of tags}. By
4989 default this list is constructed dynamically, containing all tags
4990 currently used in the buffer. You may also globally specify a hard list
4991 of tags with the variable @code{org-tag-alist}. Finally you can set
4992 the default tags for a given file with lines like
4996 #+TAGS: @@work @@home @@tennisclub
4997 #+TAGS: laptop car pc sailboat
5000 If you have globally defined your preferred set of tags using the
5001 variable @code{org-tag-alist}, but would like to use a dynamic tag list
5002 in a specific file, add an empty TAGS option line to that file:
5008 @vindex org-tag-persistent-alist
5009 If you have a preferred set of tags that you would like to use in every file,
5010 in addition to those defined on a per-file basis by TAGS option lines, then
5011 you may specify a list of tags with the variable
5012 @code{org-tag-persistent-alist}. You may turn this off on a per-file basis
5013 by adding a STARTUP option line to that file:
5019 By default Org mode uses the standard minibuffer completion facilities for
5020 entering tags. However, it also implements another, quicker, tag selection
5021 method called @emph{fast tag selection}. This allows you to select and
5022 deselect tags with just a single key press. For this to work well you should
5023 assign unique, case-sensitive, letters to most of your commonly used tags.
5024 You can do this globally by configuring the variable @code{org-tag-alist} in
5025 your Emacs init file. For example, you may find the need to tag many items
5026 in different files with @samp{:@@home:}. In this case you can set something
5030 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
5033 @noindent If the tag is only relevant to the file you are working on, then you
5034 can instead set the TAGS option line as:
5037 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
5040 @noindent The tags interface will show the available tags in a splash
5041 window. If you want to start a new line after a specific tag, insert
5042 @samp{\n} into the tag list
5045 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p)
5048 @noindent or write them in two lines:
5051 #+TAGS: @@work(w) @@home(h) @@tennisclub(t)
5052 #+TAGS: laptop(l) pc(p)
5056 You can also group together tags that are mutually exclusive by using
5060 #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)
5063 @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
5064 and @samp{@@tennisclub} should be selected. Multiple such groups are allowed.
5066 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
5067 these lines to activate any changes.
5070 To set these mutually exclusive groups in the variable @code{org-tag-alist},
5071 you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
5072 of the braces. Similarly, you can use @code{:newline} to indicate a line
5073 break. The previous example would be set globally by the following
5077 (setq org-tag-alist '((:startgroup . nil)
5078 ("@@work" . ?w) ("@@home" . ?h)
5079 ("@@tennisclub" . ?t)
5081 ("laptop" . ?l) ("pc" . ?p)))
5084 If at least one tag has a selection key then pressing @kbd{C-c C-c} will
5085 automatically present you with a special interface, listing inherited tags,
5086 the tags of the current headline, and a list of all valid tags with
5087 corresponding keys@footnote{Keys will automatically be assigned to tags which
5088 have no configured keys.}.
5090 Pressing keys assigned to tags will add or remove them from the list of tags
5091 in the current line. Selecting a tag in a group of mutually exclusive tags
5092 will turn off any other tags from that group.
5094 In this interface, you can also use the following special keys:
5099 Enter a tag in the minibuffer, even if the tag is not in the predefined
5100 list. You will be able to complete on all tags present in the buffer.
5101 You can also add several tags: just separate them with a comma.
5105 Clear all tags for this line.
5109 Accept the modified set.
5112 Abort without installing changes.
5115 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
5118 Turn off groups of mutually exclusive tags. Use this to (as an
5119 exception) assign several tags from such a group.
5122 Toggle auto-exit after the next change (see below).
5123 If you are using expert mode, the first @kbd{C-c} will display the
5128 This method lets you assign tags to a headline with very few keys. With
5129 the above setup, you could clear the current tags and set @samp{@@home},
5130 @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
5131 C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to
5132 @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
5133 alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
5134 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
5135 @key{RET} @key{RET}}.
5137 @vindex org-fast-tag-selection-single-key
5138 If you find that most of the time you need only a single key press to
5139 modify your list of tags, set @code{org-fast-tag-selection-single-key}.
5140 Then you no longer have to press @key{RET} to exit fast tag selection---it
5141 will immediately exit after the first change. If you then occasionally
5142 need more keys, press @kbd{C-c} to turn off auto-exit for the current tag
5143 selection process (in effect: start selection with @kbd{C-c C-c C-c}
5144 instead of @kbd{C-c C-c}). If you set the variable to the value
5145 @code{expert}, the special window is not even shown for single-key tag
5146 selection, it comes up only when you press an extra @kbd{C-c}.
5149 @section Tag hierarchy
5152 @cindex tags, groups
5153 @cindex tag hierarchy
5154 Tags can be defined in hierarchies. A tag can be defined as a @emph{group
5155 tag} for a set of other tags. The group tag can be seen as the ``broader
5156 term'' for its set of tags. Defining multiple @emph{group tags} and nesting
5157 them creates a tag hierarchy.
5159 One use-case is to create a taxonomy of terms (tags) that can be used to
5160 classify nodes in a document or set of documents.
5162 When you search for a group tag, it will return matches for all members in
5163 the group and its subgroups. In an agenda view, filtering by a group tag
5164 will display or hide headlines tagged with at least one of the members of the
5165 group or any of its subgroups. This makes tag searches and filters even more
5168 You can set group tags by using brackets and inserting a colon between the
5169 group tag and its related tags---beware that all whitespaces are mandatory so
5170 that Org can parse this line correctly:
5173 #+TAGS: [ GTD : Control Persp ]
5176 In this example, @samp{GTD} is the @emph{group tag} and it is related to two
5177 other tags: @samp{Control}, @samp{Persp}. Defining @samp{Control} and
5178 @samp{Persp} as group tags creates an hierarchy of tags:
5181 #+TAGS: [ Control : Context Task ]
5182 #+TAGS: [ Persp : Vision Goal AOF Project ]
5185 That can conceptually be seen as a hierarchy of tags:
5199 You can use the @code{:startgrouptag}, @code{:grouptags} and
5200 @code{:endgrouptag} keyword directly when setting @code{org-tag-alist}
5204 (setq org-tag-alist '((:startgrouptag)
5218 The tags in a group can be mutually exclusive if using the same group syntax
5219 as is used for grouping mutually exclusive tags together; using curly
5223 #+TAGS: @{ Context : @@Home @@Work @@Call @}
5226 When setting @code{org-tag-alist} you can use @code{:startgroup} &
5227 @code{:endgroup} instead of @code{:startgrouptag} & @code{:endgrouptag} to
5228 make the tags mutually exclusive.
5230 Furthermore, the members of a @emph{group tag} can also be regular
5231 expressions, creating the possibility of a more dynamic and rule-based
5232 tag structure. The regular expressions in the group must be specified
5233 within @{ @}. Here is an expanded example:
5236 #+TAGS: [ Vision : @{V@@@.+@} ]
5237 #+TAGS: [ Goal : @{G@@@.+@} ]
5238 #+TAGS: [ AOF : @{AOF@@@.+@} ]
5239 #+TAGS: [ Project : @{P@@@.+@} ]
5242 Searching for the tag @samp{Project} will now list all tags also including
5243 regular expression matches for @samp{P@@@.+}, and similarly for tag searches on
5244 @samp{Vision}, @samp{Goal} and @samp{AOF}. For example, this would work well
5245 for a project tagged with a common project-identifier, e.g. @samp{P@@2014_OrgTags}.
5248 @vindex org-group-tags
5249 If you want to ignore group tags temporarily, toggle group tags support
5250 with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you
5251 want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
5254 @section Tag searches
5255 @cindex tag searches
5256 @cindex searching for tags
5258 Once a system of tags has been set up, it can be used to collect related
5259 information into special lists.
5262 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5263 Create a sparse tree with all headlines matching a tags/property/TODO search.
5264 With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5265 @xref{Matching tags and properties}.
5266 @orgcmd{C-c a m,org-tags-view}
5267 Create a global list of tag matches from all agenda files. @xref{Matching
5268 tags and properties}.
5269 @orgcmd{C-c a M,org-tags-view}
5270 @vindex org-tags-match-list-sublevels
5271 Create a global list of tag matches from all agenda files, but check
5272 only TODO items and force checking subitems (see the option
5273 @code{org-tags-match-list-sublevels}).
5276 These commands all prompt for a match string which allows basic Boolean logic
5277 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
5278 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
5279 tagged as @samp{Kathy} or @samp{Sally}. The full syntax of the search string
5280 is rich and allows also matching against TODO keywords, entry levels and
5281 properties. For a complete description with many examples, see @ref{Matching
5282 tags and properties}.
5285 @node Properties and columns
5286 @chapter Properties and columns
5289 A property is a key-value pair associated with an entry. Properties can be
5290 set so they are associated with a single entry, with every entry in a tree,
5291 or with every entry in an Org mode file.
5293 There are two main applications for properties in Org mode. First,
5294 properties are like tags, but with a value. Imagine maintaining a file where
5295 you document bugs and plan releases for a piece of software. Instead of
5296 using tags like @code{:release_1:}, @code{:release_2:}, you can use a
5297 property, say @code{:Release:}, that in different subtrees has different
5298 values, such as @code{1.0} or @code{2.0}. Second, you can use properties to
5299 implement (very basic) database capabilities in an Org buffer. Imagine
5300 keeping track of your music CDs, where properties could be things such as the
5301 album, artist, date of release, number of tracks, and so on.
5303 Properties can be conveniently edited and viewed in column view
5304 (@pxref{Column view}).
5307 * Property syntax:: How properties are spelled out
5308 * Special properties:: Access to other Org mode features
5309 * Property searches:: Matching property values
5310 * Property inheritance:: Passing values down the tree
5311 * Column view:: Tabular viewing and editing
5312 * Property API:: Properties for Lisp programmers
5315 @node Property syntax
5316 @section Property syntax
5317 @cindex property syntax
5318 @cindex drawer, for properties
5320 Properties are key-value pairs. When they are associated with a single entry
5321 or with a tree they need to be inserted into a special drawer
5322 (@pxref{Drawers}) with the name @code{PROPERTIES}, which has to be located
5323 right below a headline, and its planning line (@pxref{Deadlines and
5324 scheduling}) when applicable. Each property is specified on a single line,
5325 with the key (surrounded by colons) first, and the value after it. Keys are
5326 case-insensitive. Here is an example:
5331 *** Goldberg Variations
5333 :Title: Goldberg Variations
5334 :Composer: J.S. Bach
5336 :Publisher: Deutsche Grammophon
5341 Depending on the value of @code{org-use-property-inheritance}, a property set
5342 this way will either be associated with a single entry, or the subtree
5343 defined by the entry, see @ref{Property inheritance}.
5345 You may define the allowed values for a particular property @samp{:Xyz:}
5346 by setting a property @samp{:Xyz_ALL:}. This special property is
5347 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
5348 the entire tree. When allowed values are defined, setting the
5349 corresponding property becomes easier and is less prone to typing
5350 errors. For the example with the CD collection, we can predefine
5351 publishers and the number of disks in a box like this:
5356 :NDisks_ALL: 1 2 3 4
5357 :Publisher_ALL: "Deutsche Grammophon" Philips EMI
5361 If you want to set properties that can be inherited by any entry in a
5362 file, use a line like
5363 @cindex property, _ALL
5366 #+PROPERTY: NDisks_ALL 1 2 3 4
5369 Contrary to properties set from a special drawer, you have to refresh the
5370 buffer with @kbd{C-c C-c} to activate this change.
5372 If you want to add to the value of an existing property, append a @code{+} to
5373 the property name. The following results in the property @code{var} having
5374 the value ``foo=1 bar=2''.
5377 #+PROPERTY: var foo=1
5378 #+PROPERTY: var+ bar=2
5381 It is also possible to add to the values of inherited properties. The
5382 following results in the @code{genres} property having the value ``Classic
5383 Baroque'' under the @code{Goldberg Variations} subtree.
5391 *** Goldberg Variations
5393 :Title: Goldberg Variations
5394 :Composer: J.S. Bach
5396 :Publisher: Deutsche Grammophon
5401 Note that a property can only have one entry per Drawer.
5403 @vindex org-global-properties
5404 Property values set with the global variable
5405 @code{org-global-properties} can be inherited by all entries in all
5409 The following commands help to work with properties:
5412 @orgcmd{M-@key{TAB},pcomplete}
5413 After an initial colon in a line, complete property keys. All keys used
5414 in the current file will be offered as possible completions.
5415 @orgcmd{C-c C-x p,org-set-property}
5416 Set a property. This prompts for a property name and a value. If
5417 necessary, the property drawer is created as well.
5418 @item C-u M-x org-insert-drawer RET
5419 @cindex org-insert-drawer
5420 Insert a property drawer into the current entry. The drawer will be
5421 inserted early in the entry, but after the lines with planning
5422 information like deadlines.
5423 @orgcmd{C-c C-c,org-property-action}
5424 With the cursor in a property drawer, this executes property commands.
5425 @orgcmd{C-c C-c s,org-set-property}
5426 Set a property in the current entry. Both the property and the value
5427 can be inserted using completion.
5428 @orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
5429 Switch property at point to the next/previous allowed value.
5430 @orgcmd{C-c C-c d,org-delete-property}
5431 Remove a property from the current entry.
5432 @orgcmd{C-c C-c D,org-delete-property-globally}
5433 Globally remove a property, from all entries in the current file.
5434 @orgcmd{C-c C-c c,org-compute-property-at-point}
5435 Compute the property at point, using the operator and scope from the
5436 nearest column format definition.
5439 @node Special properties
5440 @section Special properties
5441 @cindex properties, special
5443 Special properties provide an alternative access method to Org mode features,
5444 like the TODO state or the priority of an entry, discussed in the previous
5445 chapters. This interface exists so that you can include these states in
5446 a column view (@pxref{Column view}), or to use them in queries. The
5447 following property names are special and should not be used as keys in the
5450 @cindex property, special, ALLTAGS
5451 @cindex property, special, BLOCKED
5452 @cindex property, special, CLOCKSUM
5453 @cindex property, special, CLOCKSUM_T
5454 @cindex property, special, CLOSED
5455 @cindex property, special, DEADLINE
5456 @cindex property, special, FILE
5457 @cindex property, special, ITEM
5458 @cindex property, special, PRIORITY
5459 @cindex property, special, SCHEDULED
5460 @cindex property, special, TAGS
5461 @cindex property, special, TIMESTAMP
5462 @cindex property, special, TIMESTAMP_IA
5463 @cindex property, special, TODO
5465 ALLTAGS @r{All tags, including inherited ones.}
5466 BLOCKED @r{"t" if task is currently blocked by children or siblings.}
5467 CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}}
5468 @r{must be run first to compute the values in the current buffer.}
5469 CLOCKSUM_T @r{The sum of CLOCK intervals in the subtree for today.}
5470 @r{@code{org-clock-sum-today} must be run first to compute the}
5471 @r{values in the current buffer.}
5472 CLOSED @r{When was this entry closed?}
5473 DEADLINE @r{The deadline time string, without the angular brackets.}
5474 FILE @r{The filename the entry is located in.}
5475 ITEM @r{The headline of the entry.}
5476 PRIORITY @r{The priority of the entry, a string with a single letter.}
5477 SCHEDULED @r{The scheduling timestamp, without the angular brackets.}
5478 TAGS @r{The tags defined directly in the headline.}
5479 TIMESTAMP @r{The first keyword-less timestamp in the entry.}
5480 TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
5481 TODO @r{The TODO keyword of the entry.}
5484 @node Property searches
5485 @section Property searches
5486 @cindex properties, searching
5487 @cindex searching, of properties
5489 To create sparse trees and special lists with selection based on properties,
5490 the same commands are used as for tag searches (@pxref{Tag searches}).
5493 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5494 Create a sparse tree with all matching entries. With a
5495 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5496 @orgcmd{C-c a m,org-tags-view}
5497 Create a global list of tag/property matches from all agenda files.
5498 @xref{Matching tags and properties}.
5499 @orgcmd{C-c a M,org-tags-view}
5500 @vindex org-tags-match-list-sublevels
5501 Create a global list of tag matches from all agenda files, but check
5502 only TODO items and force checking of subitems (see the option
5503 @code{org-tags-match-list-sublevels}).
5506 The syntax for the search string is described in @ref{Matching tags and
5509 There is also a special command for creating sparse trees based on a
5514 Create a sparse tree based on the value of a property. This first
5515 prompts for the name of a property, and then for a value. A sparse tree
5516 is created with all entries that define this property with the given
5517 value. If you enclose the value in curly braces, it is interpreted as
5518 a regular expression and matched against the property values.
5521 @node Property inheritance
5522 @section Property Inheritance
5523 @cindex properties, inheritance
5524 @cindex inheritance, of properties
5526 @vindex org-use-property-inheritance
5527 The outline structure of Org mode documents lends itself to an
5528 inheritance model of properties: if the parent in a tree has a certain
5529 property, the children can inherit this property. Org mode does not
5530 turn this on by default, because it can slow down property searches
5531 significantly and is often not needed. However, if you find inheritance
5532 useful, you can turn it on by setting the variable
5533 @code{org-use-property-inheritance}. It may be set to @code{t} to make
5534 all properties inherited from the parent, to a list of properties
5535 that should be inherited, or to a regular expression that matches
5536 inherited properties. If a property has the value @code{nil}, this is
5537 interpreted as an explicit undefine of the property, so that inheritance
5538 search will stop at this value and return @code{nil}.
5540 Org mode has a few properties for which inheritance is hard-coded, at
5541 least for the special applications for which they are used:
5543 @cindex property, COLUMNS
5546 The @code{:COLUMNS:} property defines the format of column view
5547 (@pxref{Column view}). It is inherited in the sense that the level
5548 where a @code{:COLUMNS:} property is defined is used as the starting
5549 point for a column view table, independently of the location in the
5550 subtree from where columns view is turned on.
5552 @cindex property, CATEGORY
5553 For agenda view, a category set through a @code{:CATEGORY:} property
5554 applies to the entire subtree.
5556 @cindex property, ARCHIVE
5557 For archiving, the @code{:ARCHIVE:} property may define the archive
5558 location for the entire subtree (@pxref{Moving subtrees}).
5560 @cindex property, LOGGING
5561 The LOGGING property may define logging settings for an entry or a
5562 subtree (@pxref{Tracking TODO state changes}).
5566 @section Column view
5568 A great way to view and edit properties in an outline tree is
5569 @emph{column view}. In column view, each outline node is turned into a
5570 table row. Columns in this table provide access to properties of the
5571 entries. Org mode implements columns by overlaying a tabular structure
5572 over the headline of each item. While the headlines have been turned
5573 into a table row, you can still change the visibility of the outline
5574 tree. For example, you get a compact table by switching to CONTENTS
5575 view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
5576 is active), but you can still open, read, and edit the entry below each
5577 headline. Or, you can switch to column view after executing a sparse
5578 tree command and in this way get a table only for the selected items.
5579 Column view also works in agenda buffers (@pxref{Agenda views}) where
5580 queries have collected selected items, possibly from a number of files.
5583 * Defining columns:: The COLUMNS format property
5584 * Using column view:: How to create and use column view
5585 * Capturing column view:: A dynamic block for column view
5588 @node Defining columns
5589 @subsection Defining columns
5590 @cindex column view, for properties
5591 @cindex properties, column view
5593 Setting up a column view first requires defining the columns. This is
5594 done by defining a column format line.
5597 * Scope of column definitions:: Where defined, where valid?
5598 * Column attributes:: Appearance and content of a column
5601 @node Scope of column definitions
5602 @subsubsection Scope of column definitions
5604 To define a column format for an entire file, use a line like
5608 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5611 To specify a format that only applies to a specific tree, add a
5612 @code{:COLUMNS:} property to the top node of that tree, for example:
5615 ** Top node for columns view
5617 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5621 If a @code{:COLUMNS:} property is present in an entry, it defines columns
5622 for the entry itself, and for the entire subtree below it. Since the
5623 column definition is part of the hierarchical structure of the document,
5624 you can define columns on level 1 that are general enough for all
5625 sublevels, and more specific columns further down, when you edit a
5626 deeper part of the tree.
5628 @node Column attributes
5629 @subsubsection Column attributes
5630 A column definition sets the attributes of a column. The general
5631 definition looks like this:
5634 %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]
5638 Except for the percent sign and the property name, all items are
5639 optional. The individual parts have the following meaning:
5642 @var{width} @r{An integer specifying the width of the column in characters.}
5643 @r{If omitted, the width will be determined automatically.}
5644 @var{property} @r{The property that should be edited in this column.}
5645 @r{Special properties representing meta data are allowed here}
5646 @r{as well (@pxref{Special properties})}
5647 @var{title} @r{The header text for the column. If omitted, the property}
5649 @{@var{summary-type}@} @r{The summary type. If specified, the column values for}
5650 @r{parent nodes are computed from the children@footnote{If
5651 more than one summary type apply to the property, the parent
5652 values are computed according to the first of them.}.}
5653 @r{Supported summary types are:}
5654 @{+@} @r{Sum numbers in this column.}
5655 @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.}
5656 @{$@} @r{Currency, short for @samp{+;%.2f}.}
5657 @{min@} @r{Smallest number in column.}
5658 @{max@} @r{Largest number.}
5659 @{mean@} @r{Arithmetic mean of numbers.}
5660 @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
5661 @{X/@} @r{Checkbox status, @samp{[n/m]}.}
5662 @{X%@} @r{Checkbox status, @samp{[n%]}.}
5663 @{:@} @r{Sum times, HH:MM, plain numbers are
5664 hours@footnote{A time can also be a duration, using effort
5665 modifiers defined in @code{org-effort-durations}, e.g.,
5666 @samp{3d 1h}. If any value in the column is as such, the
5667 summary will also be an effort duration.}.}
5668 @{:min@} @r{Smallest time value in column.}
5669 @{:max@} @r{Largest time value.}
5670 @{:mean@} @r{Arithmetic mean of time values.}
5671 @{@@min@} @r{Minimum age@footnote{An age is defined as
5672 a duration since a given time-stamp (@pxref{Timestamps}). It
5673 can also be expressed as days, hours, minutes and seconds,
5674 identified by @samp{d}, @samp{h}, @samp{m} and @samp{s}
5675 suffixes, all mandatory, e.g., @samp{0d 13h 0m 10s}.} (in
5676 days/hours/mins/seconds).}
5677 @{@@max@} @r{Maximum age (in days/hours/mins/seconds).}
5678 @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
5679 @{est+@} @r{Add @samp{low-high} estimates.}
5682 The @code{est+} summary type requires further explanation. It is used for
5683 combining estimates, expressed as @samp{low-high} ranges or plain numbers.
5684 For example, instead of estimating a particular task will take 5 days, you
5685 might estimate it as 5--6 days if you're fairly confident you know how much
5686 work is required, or 1--10 days if you don't really know what needs to be
5687 done. Both ranges average at 5.5 days, but the first represents a more
5688 predictable delivery.
5690 When combining a set of such estimates, simply adding the lows and highs
5691 produces an unrealistically wide result. Instead, @code{est+} adds the
5692 statistical mean and variance of the sub-tasks, generating a final estimate
5693 from the sum. For example, suppose you had ten tasks, each of which was
5694 estimated at 0.5 to 2 days of work. Straight addition produces an estimate
5695 of 5 to 20 days, representing what to expect if everything goes either
5696 extremely well or extremely poorly. In contrast, @code{est+} estimates the
5697 full job more realistically, at 10--15 days.
5699 Numbers are right-aligned when a format specifier with an explicit width like
5700 @code{%5d} or @code{%5.1f} is used.
5702 @vindex org-columns-summary-types
5703 You can also define custom summary types by setting
5704 @code{org-columns-summary-types}, which see.
5706 Here is an example for a complete columns definition, along with allowed
5710 :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.}
5711 %10Time_Estimate@{:@} %CLOCKSUM %CLOCKSUM_T
5712 :Owner_ALL: Tammy Mark Karl Lisa Don
5713 :Status_ALL: "In progress" "Not started yet" "Finished" ""
5714 :Approved_ALL: "[ ]" "[X]"
5718 The first column, @samp{%25ITEM}, means the first 25 characters of the
5719 item itself, i.e., of the headline. You probably always should start the
5720 column definition with the @samp{ITEM} specifier. The other specifiers
5721 create columns @samp{Owner} with a list of names as allowed values, for
5722 @samp{Status} with four different possible values, and for a checkbox
5723 field @samp{Approved}. When no width is given after the @samp{%}
5724 character, the column will be exactly as wide as it needs to be in order
5725 to fully display all values. The @samp{Approved} column does have a
5726 modified title (@samp{Approved?}, with a question mark). Summaries will
5727 be created for the @samp{Time_Estimate} column by adding time duration
5728 expressions like HH:MM, and for the @samp{Approved} column, by providing
5729 an @samp{[X]} status if all children have been checked. The
5730 @samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns are special, they lists the
5731 sums of CLOCK intervals in the subtree, either for all clocks or just for
5734 @node Using column view
5735 @subsection Using column view
5738 @tsubheading{Turning column view on and off}
5739 @orgcmd{C-c C-x C-c,org-columns}
5740 @vindex org-columns-default-format
5741 Turn on column view. If the cursor is before the first headline in the file,
5742 or the function called with the universal prefix argument, column view is
5743 turned on for the entire file, using the @code{#+COLUMNS} definition. If the
5744 cursor is somewhere inside the outline, this command searches the hierarchy,
5745 up from point, for a @code{:COLUMNS:} property that defines a format. When
5746 one is found, the column view table is established for the tree starting at
5747 the entry that contains the @code{:COLUMNS:} property. If no such property
5748 is found, the format is taken from the @code{#+COLUMNS} line or from the
5749 variable @code{org-columns-default-format}, and column view is established
5750 for the current entry and its subtree.
5751 @orgcmd{r,org-columns-redo}
5752 Recreate the column view, to include recent changes made in the buffer.
5753 @orgcmd{g,org-columns-redo}
5755 @orgcmd{q,org-columns-quit}
5757 @tsubheading{Editing values}
5758 @item @key{left} @key{right} @key{up} @key{down}
5759 Move through the column view from field to field.
5760 @kindex S-@key{left}
5761 @kindex S-@key{right}
5762 @item S-@key{left}/@key{right}
5763 Switch to the next/previous allowed value of the field. For this, you
5764 have to have specified allowed values for a property.
5766 Directly select the Nth allowed value, @kbd{0} selects the 10th value.
5767 @orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value}
5768 Same as @kbd{S-@key{left}/@key{right}}
5769 @orgcmd{e,org-columns-edit-value}
5770 Edit the property at point. For the special properties, this will
5771 invoke the same interface that you normally use to change that
5772 property. For example, when editing a TAGS property, the tag completion
5773 or fast selection interface will pop up.
5774 @orgcmd{C-c C-c,org-columns-set-tags-or-toggle}
5775 When there is a checkbox at point, toggle it.
5776 @orgcmd{v,org-columns-show-value}
5777 View the full value of this property. This is useful if the width of
5778 the column is smaller than that of the value.
5779 @orgcmd{a,org-columns-edit-allowed}
5780 Edit the list of allowed values for this property. If the list is found
5781 in the hierarchy, the modified value is stored there. If no list is
5782 found, the new value is stored in the first entry that is part of the
5783 current column view.
5784 @tsubheading{Modifying the table structure}
5785 @orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen}
5786 Make the column narrower/wider by one character.
5787 @orgcmd{S-M-@key{right},org-columns-new}
5788 Insert a new column, to the left of the current column.
5789 @orgcmd{S-M-@key{left},org-columns-delete}
5790 Delete the current column.
5793 @node Capturing column view
5794 @subsection Capturing column view
5796 Since column view is just an overlay over a buffer, it cannot be
5797 exported or printed directly. If you want to capture a column view, use
5798 a @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
5799 of this block looks like this:
5801 @cindex #+BEGIN, columnview
5804 #+BEGIN: columnview :hlines 1 :id "label"
5809 @noindent This dynamic block has the following parameters:
5813 This is the most important parameter. Column view is a feature that is
5814 often localized to a certain (sub)tree, and the capture block might be
5815 at a different location in the file. To identify the tree whose view to
5816 capture, you can use 4 values:
5817 @cindex property, ID
5819 local @r{use the tree in which the capture block is located}
5820 global @r{make a global view, including all headings in the file}
5821 "file:@var{path-to-file}"
5822 @r{run column view at the top of this file}
5823 "@var{ID}" @r{call column view in the tree that has an @code{:ID:}}
5824 @r{property with the value @i{label}. You can use}
5825 @r{@kbd{M-x org-id-copy RET} to create a globally unique ID for}
5826 @r{the current entry and copy it to the kill-ring.}
5829 When @code{t}, insert an hline after every line. When a number @var{N}, insert
5830 an hline before each headline with level @code{<= @var{N}}.
5832 When set to @code{t}, force column groups to get vertical lines.
5834 When set to a number, don't capture entries below this level.
5835 @item :skip-empty-rows
5836 When set to @code{t}, skip rows where the only non-empty specifier of the
5837 column view is @code{ITEM}.
5839 When non-@code{nil}, indent each @code{ITEM} field according to its level.
5844 The following commands insert or update the dynamic block:
5847 @orgcmd{C-c C-x i,org-insert-columns-dblock}
5848 Insert a dynamic block capturing a column view. You will be prompted
5849 for the scope or ID of the view.
5850 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
5851 Update dynamic block at point.
5852 @orgcmd{C-u C-c C-x C-u,org-update-all-dblocks}
5853 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
5854 you have several clock table blocks, column-capturing blocks or other dynamic
5858 You can add formulas to the column view table and you may add plotting
5859 instructions in front of the table---these will survive an update of the
5860 block. If there is a @code{#+TBLFM:} after the table, the table will
5861 actually be recalculated automatically after an update.
5863 An alternative way to capture and process property values into a table is
5864 provided by Eric Schulte's @file{org-collector.el} which is a contributed
5865 package@footnote{Contributed packages are not part of Emacs, but are
5866 distributed with the main distribution of Org (visit
5867 @uref{http://orgmode.org}).}. It provides a general API to collect
5868 properties from entries in a certain scope, and arbitrary Lisp expressions to
5869 process these values before inserting them into a table or a dynamic block.
5872 @section The Property API
5873 @cindex properties, API
5874 @cindex API, for properties
5876 There is a full API for accessing and changing properties. This API can
5877 be used by Emacs Lisp programs to work with properties and to implement
5878 features based on them. For more information see @ref{Using the
5881 @node Dates and times
5882 @chapter Dates and times
5888 To assist project planning, TODO items can be labeled with a date and/or
5889 a time. The specially formatted string carrying the date and time
5890 information is called a @emph{timestamp} in Org mode. This may be a
5891 little confusing because timestamp is often used to indicate when
5892 something was created or last changed. However, in Org mode this term
5893 is used in a much wider sense.
5896 * Timestamps:: Assigning a time to a tree entry
5897 * Creating timestamps:: Commands which insert timestamps
5898 * Deadlines and scheduling:: Planning your work
5899 * Clocking work time:: Tracking how long you spend on a task
5900 * Effort estimates:: Planning work effort in advance
5901 * Timers:: Notes with a running timer
5906 @section Timestamps, deadlines, and scheduling
5908 @cindex ranges, time
5913 A timestamp is a specification of a date (possibly with a time or a range of
5914 times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this
5915 simplest form, the day name is optional when you type the date yourself.
5916 However, any dates inserted or modified by Org will add that day name, for
5917 reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16
5918 Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601
5919 date/time format. To use an alternative format, see @ref{Custom time
5920 format}.}. A timestamp can appear anywhere in the headline or body of an Org
5921 tree entry. Its presence causes entries to be shown on specific dates in the
5922 agenda (@pxref{Weekly/daily agenda}). We distinguish:
5925 @item Plain timestamp; Event; Appointment
5928 A simple timestamp just assigns a date/time to an item. This is just like
5929 writing down an appointment or event in a paper agenda. In the agenda
5930 display, the headline of an entry associated with a plain timestamp will be
5931 shown exactly on that date.
5934 * Meet Peter at the movies
5935 <2006-11-01 Wed 19:15>
5936 * Discussion on climate change
5937 <2006-11-02 Thu 20:00-22:00>
5940 @item Timestamp with repeater interval
5941 @cindex timestamp, with repeater interval
5942 A timestamp may contain a @emph{repeater interval}, indicating that it
5943 applies not only on the given date, but again and again after a certain
5944 interval of N days (d), weeks (w), months (m), or years (y). The
5945 following will show up in the agenda every Wednesday:
5948 * Pick up Sam at school
5949 <2007-05-16 Wed 12:30 +1w>
5952 @item Diary-style sexp entries
5953 For more complex date specifications, Org mode supports using the special
5954 sexp diary entries implemented in the Emacs calendar/diary
5955 package@footnote{When working with the standard diary sexp functions, you
5956 need to be very careful with the order of the arguments. That order depends
5957 evilly on the variable @code{calendar-date-style} (or, for older Emacs
5958 versions, @code{european-calendar-style}). For example, to specify a date
5959 December 1, 2005, the call might look like @code{(diary-date 12 1 2005)} or
5960 @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
5961 the settings. This has been the source of much confusion. Org mode users
5962 can resort to special versions of these functions like @code{org-date} or
5963 @code{org-anniversary}. These work just like the corresponding @code{diary-}
5964 functions, but with stable ISO order of arguments (year, month, day) wherever
5965 applicable, independent of the value of @code{calendar-date-style}.}. For
5966 example with optional time
5969 * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
5970 <%%(diary-float t 4 2)>
5973 @item Time/Date range
5976 Two timestamps connected by @samp{--} denote a range. The headline
5977 will be shown on the first and last day of the range, and on any dates
5978 that are displayed and fall in the range. Here is an example:
5981 ** Meeting in Amsterdam
5982 <2004-08-23 Mon>--<2004-08-26 Thu>
5985 @item Inactive timestamp
5986 @cindex timestamp, inactive
5987 @cindex inactive timestamp
5988 Just like a plain timestamp, but with square brackets instead of
5989 angular ones. These timestamps are inactive in the sense that they do
5990 @emph{not} trigger an entry to show up in the agenda.
5993 * Gillian comes late for the fifth time
5999 @node Creating timestamps
6000 @section Creating timestamps
6001 @cindex creating timestamps
6002 @cindex timestamps, creating
6004 For Org mode to recognize timestamps, they need to be in the specific
6005 format. All commands listed below produce timestamps in the correct
6009 @orgcmd{C-c .,org-time-stamp}
6010 Prompt for a date and insert a corresponding timestamp. When the cursor is
6011 at an existing timestamp in the buffer, the command is used to modify this
6012 timestamp instead of inserting a new one. When this command is used twice in
6013 succession, a time range is inserted.
6015 @orgcmd{C-c !,org-time-stamp-inactive}
6016 Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
6023 @vindex org-time-stamp-rounding-minutes
6024 Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which
6025 contains date and time. The default time can be rounded to multiples of 5
6026 minutes, see the option @code{org-time-stamp-rounding-minutes}.
6029 Normalize timestamp, insert/fix day name if missing or wrong.
6031 @orgcmd{C-c <,org-date-from-calendar}
6032 Insert a timestamp corresponding to the cursor date in the Calendar.
6034 @orgcmd{C-c >,org-goto-calendar}
6035 Access the Emacs calendar for the current date. If there is a
6036 timestamp in the current line, go to the corresponding date
6039 @orgcmd{C-c C-o,org-open-at-point}
6040 Access the agenda for the date given by the timestamp or -range at
6041 point (@pxref{Weekly/daily agenda}).
6043 @orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day}
6044 Change date at cursor by one day. These key bindings conflict with
6045 shift-selection and related modes (@pxref{Conflicts}).
6047 @orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down}
6048 Change the item under the cursor in a timestamp. The cursor can be on a
6049 year, month, day, hour or minute. When the timestamp contains a time range
6050 like @samp{15:30-16:30}, modifying the first time will also shift the second,
6051 shifting the time block with constant length. To change the length, modify
6052 the second time. Note that if the cursor is in a headline and not at a
6053 timestamp, these same keys modify the priority of an item.
6054 (@pxref{Priorities}). The key bindings also conflict with shift-selection and
6055 related modes (@pxref{Conflicts}).
6057 @orgcmd{C-c C-y,org-evaluate-time-range}
6058 @cindex evaluate time range
6059 Evaluate a time range by computing the difference between start and end.
6060 With a prefix argument, insert result after the time range (in a table: into
6061 the following column).
6066 * The date/time prompt:: How Org mode helps you entering date and time
6067 * Custom time format:: Making dates look different
6070 @node The date/time prompt
6071 @subsection The date/time prompt
6072 @cindex date, reading in minibuffer
6073 @cindex time, reading in minibuffer
6075 @vindex org-read-date-prefer-future
6076 When Org mode prompts for a date/time, the default is shown in default
6077 date/time format, and the prompt therefore seems to ask for a specific
6078 format. But it will in fact accept date/time information in a variety of
6079 formats. Generally, the information should start at the beginning of the
6080 string. Org mode will find whatever information is in
6081 there and derive anything you have not specified from the @emph{default date
6082 and time}. The default is usually the current date and time, but when
6083 modifying an existing timestamp, or when entering the second stamp of a
6084 range, it is taken from the stamp in the buffer. When filling in
6085 information, Org mode assumes that most of the time you will want to enter a
6086 date in the future: if you omit the month/year and the given day/month is
6087 @i{before} today, it will assume that you mean a future date@footnote{See the
6088 variable @code{org-read-date-prefer-future}. You may set that variable to
6089 the symbol @code{time} to even make a time before now shift the date to
6090 tomorrow.}. If the date has been automatically shifted into the future, the
6091 time prompt will show this with @samp{(=>F).}
6093 For example, let's assume that today is @b{June 13, 2006}. Here is how
6094 various inputs will be interpreted, the items filled in by Org mode are
6098 3-2-5 @result{} 2003-02-05
6099 2/5/3 @result{} 2003-02-05
6100 14 @result{} @b{2006}-@b{06}-14
6101 12 @result{} @b{2006}-@b{07}-12
6102 2/5 @result{} @b{2007}-02-05
6103 Fri @result{} nearest Friday after the default date
6104 sep 15 @result{} @b{2006}-09-15
6105 feb 15 @result{} @b{2007}-02-15
6106 sep 12 9 @result{} 2009-09-12
6107 12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45
6108 22 sept 0:34 @result{} @b{2006}-09-22 00:34
6109 w4 @result{} ISO week four of the current year @b{2006}
6110 2012 w4 fri @result{} Friday of ISO week 4 in 2012
6111 2012-w04-5 @result{} Same as above
6114 Furthermore you can specify a relative date by giving, as the @emph{first}
6115 thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to
6116 indicate change in hours, days, weeks, months, or years. With a single plus
6117 or minus, the date is always relative to today. With a double plus or minus,
6118 it is relative to the default date. If instead of a single letter, you use
6119 the abbreviation of day name, the date will be the Nth such day, e.g.:
6124 +4d @result{} four days from today
6125 +4 @result{} same as above
6126 +2w @result{} two weeks from today
6127 ++5 @result{} five days from default date
6128 +2tue @result{} second Tuesday from now
6129 -wed @result{} last Wednesday
6132 @vindex parse-time-months
6133 @vindex parse-time-weekdays
6134 The function understands English month and weekday abbreviations. If
6135 you want to use unabbreviated names and/or other languages, configure
6136 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
6138 @vindex org-read-date-force-compatible-dates
6139 Not all dates can be represented in a given Emacs implementation. By default
6140 Org mode forces dates into the compatibility range 1970--2037 which works on
6141 all Emacs implementations. If you want to use dates outside of this range,
6142 read the docstring of the variable
6143 @code{org-read-date-force-compatible-dates}.
6145 You can specify a time range by giving start and end times or by giving a
6146 start time and a duration (in HH:MM format). Use one or two dash(es) as the
6147 separator in the former case and use '+' as the separator in the latter
6151 11am-1:15pm @result{} 11:00-13:15
6152 11am--1:15pm @result{} same as above
6153 11am+2:15 @result{} same as above
6156 @cindex calendar, for selecting date
6157 @vindex org-popup-calendar-for-date-prompt
6158 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
6159 you don't need/want the calendar, configure the variable
6160 @code{org-popup-calendar-for-date-prompt}.}. When you exit the date
6161 prompt, either by clicking on a date in the calendar, or by pressing
6162 @key{RET}, the date selected in the calendar will be combined with the
6163 information entered at the prompt. You can control the calendar fully
6164 from the minibuffer:
6171 @kindex S-@key{right}
6172 @kindex S-@key{left}
6173 @kindex S-@key{down}
6175 @kindex M-S-@key{right}
6176 @kindex M-S-@key{left}
6178 @kindex M-S-@key{down}
6179 @kindex M-S-@key{up}
6182 @key{RET} @r{Choose date at cursor in calendar.}
6183 mouse-1 @r{Select date by clicking on it.}
6184 S-@key{right}/@key{left} @r{One day forward/backward.}
6185 S-@key{down}/@key{up} @r{One week forward/backward.}
6186 M-S-@key{right}/@key{left} @r{One month forward/backward.}
6187 > / < @r{Scroll calendar forward/backward by one month.}
6188 M-v / C-v @r{Scroll calendar forward/backward by 3 months.}
6189 M-S-@key{down}/@key{up} @r{Scroll calendar forward/backward by one year.}
6192 @vindex org-read-date-display-live
6193 The actions of the date/time prompt may seem complex, but I assure you they
6194 will grow on you, and you will start getting annoyed by pretty much any other
6195 way of entering a date/time out there. To help you understand what is going
6196 on, the current interpretation of your input will be displayed live in the
6197 minibuffer@footnote{If you find this distracting, turn the display off with
6198 @code{org-read-date-display-live}.}.
6200 @node Custom time format
6201 @subsection Custom time format
6202 @cindex custom date/time format
6203 @cindex time format, custom
6204 @cindex date format, custom
6206 @vindex org-display-custom-times
6207 @vindex org-time-stamp-custom-formats
6208 Org mode uses the standard ISO notation for dates and times as it is
6209 defined in ISO 8601. If you cannot get used to this and require another
6210 representation of date and time to keep you happy, you can get it by
6211 customizing the options @code{org-display-custom-times} and
6212 @code{org-time-stamp-custom-formats}.
6215 @orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays}
6216 Toggle the display of custom formats for dates and times.
6220 Org mode needs the default format for scanning, so the custom date/time
6221 format does not @emph{replace} the default format---instead it is put
6222 @emph{over} the default format using text properties. This has the
6223 following consequences:
6226 You cannot place the cursor onto a timestamp anymore, only before or
6229 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
6230 each component of a timestamp. If the cursor is at the beginning of
6231 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
6232 just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the
6233 time will be changed by one minute.
6235 If the timestamp contains a range of clock times or a repeater, these
6236 will not be overlaid, but remain in the buffer as they were.
6238 When you delete a timestamp character-by-character, it will only
6239 disappear from the buffer after @emph{all} (invisible) characters
6240 belonging to the ISO timestamp have been removed.
6242 If the custom timestamp format is longer than the default and you are
6243 using dates in tables, table alignment will be messed up. If the custom
6244 format is shorter, things do work as expected.
6248 @node Deadlines and scheduling
6249 @section Deadlines and scheduling
6251 A timestamp may be preceded by special keywords to facilitate planning. Both
6252 the timestamp and the keyword have to be positioned immediately after the task
6257 @cindex DEADLINE keyword
6259 Meaning: the task (most likely a TODO item, though not necessarily) is supposed
6260 to be finished on that date.
6262 @vindex org-deadline-warning-days
6263 @vindex org-agenda-skip-deadline-prewarning-if-scheduled
6264 On the deadline date, the task will be listed in the agenda. In
6265 addition, the agenda for @emph{today} will carry a warning about the
6266 approaching or missed deadline, starting
6267 @code{org-deadline-warning-days} before the due date, and continuing
6268 until the entry is marked DONE@. An example:
6271 *** TODO write article about the Earth for the Guide
6272 DEADLINE: <2004-02-29 Sun>
6273 The editor in charge is [[bbdb:Ford Prefect]]
6276 You can specify a different lead time for warnings for a specific
6277 deadline using the following syntax. Here is an example with a warning
6278 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. This warning is
6279 deactivated if the task gets scheduled and you set
6280 @code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}.
6283 @cindex SCHEDULED keyword
6285 Meaning: you are planning to start working on that task on the given
6288 @vindex org-agenda-skip-scheduled-if-done
6289 The headline will be listed under the given date@footnote{It will still
6290 be listed on that date after it has been marked DONE@. If you don't like
6291 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
6292 addition, a reminder that the scheduled date has passed will be present
6293 in the compilation for @emph{today}, until the entry is marked DONE, i.e.,
6294 the task will automatically be forwarded until completed.
6297 *** TODO Call Trillian for a date on New Years Eve.
6298 SCHEDULED: <2004-12-25 Sat>
6301 @vindex org-scheduled-delay-days
6302 @vindex org-agenda-skip-scheduled-delay-if-deadline
6303 If you want to @emph{delay} the display of this task in the agenda, use
6304 @code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the
6305 25th but will appear two days later. In case the task contains a repeater,
6306 the delay is considered to affect all occurrences; if you want the delay to
6307 only affect the first scheduled occurrence of the task, use @code{--2d}
6308 instead. See @code{org-scheduled-delay-days} and
6309 @code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to
6310 control this globally or per agenda.
6313 @b{Important:} Scheduling an item in Org mode should @i{not} be
6314 understood in the same way that we understand @i{scheduling a meeting}.
6315 Setting a date for a meeting is just a simple appointment, you should
6316 mark this entry with a simple plain timestamp, to get this item shown
6317 on the date where it applies. This is a frequent misunderstanding by
6318 Org users. In Org mode, @i{scheduling} means setting a date when you
6319 want to start working on an action item.
6322 You may use timestamps with repeaters in scheduling and deadline
6323 entries. Org mode will issue early and late warnings based on the
6324 assumption that the timestamp represents the @i{nearest instance} of
6325 the repeater. However, the use of diary sexp entries like
6327 @code{<%%(diary-float t 42)>}
6329 in scheduling and deadline timestamps is limited. Org mode does not
6330 know enough about the internals of each sexp function to issue early and
6331 late warnings. However, it will show the item on each day where the
6335 * Inserting deadline/schedule:: Planning items
6336 * Repeated tasks:: Items that show up again and again
6339 @node Inserting deadline/schedule
6340 @subsection Inserting deadlines or schedules
6342 The following commands allow you to quickly insert a deadline or to schedule
6347 @orgcmd{C-c C-d,org-deadline}
6348 Insert @samp{DEADLINE} keyword along with a stamp. Any CLOSED timestamp will
6349 be removed. When called with a prefix arg, an existing deadline will be
6350 removed from the entry. Depending on the variable
6351 @code{org-log-redeadline}@footnote{with corresponding @code{#+STARTUP}
6352 keywords @code{logredeadline}, @code{lognoteredeadline}, and
6353 @code{nologredeadline}}, a note will be taken when changing an existing
6356 @orgcmd{C-c C-s,org-schedule}
6357 Insert @samp{SCHEDULED} keyword along with a stamp. Any CLOSED timestamp
6358 will be removed. When called with a prefix argument, remove the scheduling
6359 date from the entry. Depending on the variable
6360 @code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}
6361 keywords @code{logreschedule}, @code{lognotereschedule}, and
6362 @code{nologreschedule}}, a note will be taken when changing an existing
6365 @orgcmd{C-c / d,org-check-deadlines}
6366 @cindex sparse tree, for deadlines
6367 @vindex org-deadline-warning-days
6368 Create a sparse tree with all deadlines that are either past-due, or
6369 which will become due within @code{org-deadline-warning-days}.
6370 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
6371 prefix, check that many days. For example, @kbd{C-1 C-c / d} shows
6372 all deadlines due tomorrow.
6374 @orgcmd{C-c / b,org-check-before-date}
6375 Sparse tree for deadlines and scheduled items before a given date.
6377 @orgcmd{C-c / a,org-check-after-date}
6378 Sparse tree for deadlines and scheduled items after a given date.
6381 Note that @code{org-schedule} and @code{org-deadline} supports
6382 setting the date by indicating a relative time: e.g., +1d will set
6383 the date to the next day after today, and --1w will set the date
6384 to the previous week before any current timestamp.
6386 @node Repeated tasks
6387 @subsection Repeated tasks
6388 @cindex tasks, repeated
6389 @cindex repeated tasks
6391 Some tasks need to be repeated again and again. Org mode helps to
6392 organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
6393 or plain timestamp. In the following example
6395 ** TODO Pay the rent
6396 DEADLINE: <2005-10-01 Sat +1m>
6399 the @code{+1m} is a repeater; the intended interpretation is that the task
6400 has a deadline on <2005-10-01> and repeats itself every (one) month starting
6401 from that time. You can use yearly, monthly, weekly, daily and hourly repeat
6402 cookies by using the @code{y/w/m/d/h} letters. If you need both a repeater
6403 and a special warning period in a deadline entry, the repeater should come
6404 first and the warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
6406 @vindex org-todo-repeat-to-state
6407 Deadlines and scheduled items produce entries in the agenda when they are
6408 over-due, so it is important to be able to mark such an entry as completed
6409 once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO
6410 keyword DONE, it will no longer produce entries in the agenda. The problem
6411 with this is, however, that then also the @emph{next} instance of the
6412 repeated entry will not be active. Org mode deals with this in the following
6413 way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
6414 shift the base date of the repeating timestamp by the repeater interval, and
6415 immediately set the entry state back to TODO@footnote{In fact, the target
6416 state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or
6417 the variable @code{org-todo-repeat-to-state}. If neither of these is
6418 specified, the target state defaults to the first state of the TODO state
6419 sequence.}. In the example above, setting the state to DONE would actually
6420 switch the date like this:
6423 ** TODO Pay the rent
6424 DEADLINE: <2005-11-01 Tue +1m>
6427 To mark a task with a repeater as @code{DONE}, use @kbd{C-- 1 C-c C-t}
6428 (i.e., @code{org-todo} with a numeric prefix argument of -1.)
6430 @vindex org-log-repeat
6431 A timestamp@footnote{You can change this using the option
6432 @code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},
6433 @code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you
6434 will also be prompted for a note.} will be added under the deadline, to keep
6435 a record that you actually acted on the previous instance of this deadline.
6437 As a consequence of shifting the base date, this entry will no longer be
6438 visible in the agenda when checking past dates, but all future instances
6441 With the @samp{+1m} cookie, the date shift will always be exactly one
6442 month. So if you have not paid the rent for three months, marking this
6443 entry DONE will still keep it as an overdue deadline. Depending on the
6444 task, this may not be the best way to handle it. For example, if you
6445 forgot to call your father for 3 weeks, it does not make sense to call
6446 him 3 times in a single day to make up for it. Finally, there are tasks
6447 like changing batteries which should always repeat a certain time
6448 @i{after} the last time you did it. For these tasks, Org mode has
6449 special repeaters @samp{++} and @samp{.+}. For example:
6453 DEADLINE: <2008-02-10 Sun ++1w>
6454 Marking this DONE will shift the date by at least one week,
6455 but also by as many weeks as it takes to get this date into
6456 the future. However, it stays on a Sunday, even if you called
6457 and marked it done on Saturday.
6458 ** TODO Empty kitchen trash
6459 DEADLINE: <2008-02-08 Fri 20:00 ++1d>
6460 Marking this DONE will shift the date by at least one day, and
6461 also by as many days as it takes to get the timestamp into the
6462 future. Since there is a time in the timestamp, the next
6463 deadline in the future will be on today's date if you
6464 complete the task before 20:00.
6465 ** TODO Check the batteries in the smoke detectors
6466 DEADLINE: <2005-11-01 Tue .+1m>
6467 Marking this DONE will shift the date to one month after
6471 @vindex org-agenda-skip-scheduled-if-deadline-is-shown
6472 You may have both scheduling and deadline information for a specific task.
6473 If the repeater is set for the scheduling information only, you probably want
6474 the repeater to be ignored after the deadline. If so, set the variable
6475 @code{org-agenda-skip-scheduled-if-deadline-is-shown} to
6476 @code{repeated-after-deadline}. However, any scheduling information without
6477 a repeater is no longer relevant once the task is done, and thus, removed
6478 upon repeating the task. If you want both scheduling and deadline
6479 information to repeat after the same interval, set the same repeater for both
6482 An alternative to using a repeater is to create a number of copies of a task
6483 subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was
6484 created for this purpose, it is described in @ref{Structure editing}.
6487 @node Clocking work time
6488 @section Clocking work time
6489 @cindex clocking time
6490 @cindex time clocking
6492 Org mode allows you to clock the time you spend on specific tasks in a
6493 project. When you start working on an item, you can start the clock. When
6494 you stop working on that task, or when you mark the task done, the clock is
6495 stopped and the corresponding time interval is recorded. It also computes
6496 the total time spent on each subtree@footnote{Clocking only works if all
6497 headings are indented with less than 30 stars. This is a hardcoded
6498 limitation of @code{lmax} in @code{org-clock-sum}.} of a project.
6499 And it remembers a history or tasks recently clocked, so that you can jump
6500 quickly between a number of tasks absorbing your time.
6502 To save the clock history across Emacs sessions, use
6504 (setq org-clock-persist 'history)
6505 (org-clock-persistence-insinuate)
6507 When you clock into a new task after resuming Emacs, the incomplete
6508 clock@footnote{To resume the clock under the assumption that you have worked
6509 on this task while outside Emacs, use @code{(setq org-clock-persist t)}.}
6510 will be found (@pxref{Resolving idle time}) and you will be prompted about
6514 * Clocking commands:: Starting and stopping a clock
6515 * The clock table:: Detailed reports
6516 * Resolving idle time:: Resolving time when you've been idle
6519 @node Clocking commands
6520 @subsection Clocking commands
6523 @orgcmd{C-c C-x C-i,org-clock-in}
6524 @vindex org-clock-into-drawer
6525 @vindex org-clock-continuously
6526 @cindex property, LOG_INTO_DRAWER
6527 Start the clock on the current item (clock-in). This inserts the CLOCK
6528 keyword together with a timestamp. If this is not the first clocking of
6529 this item, the multiple CLOCK lines will be wrapped into a
6530 @code{:LOGBOOK:} drawer (see also the variable
6531 @code{org-clock-into-drawer}). You can also overrule
6532 the setting of this variable for a subtree by setting a
6533 @code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
6534 When called with a @kbd{C-u} prefix argument,
6535 select the task from a list of recently clocked tasks. With two @kbd{C-u
6536 C-u} prefixes, clock into the task at point and mark it as the default task;
6537 the default task will then always be available with letter @kbd{d} when
6538 selecting a clocking task. With three @kbd{C-u C-u C-u} prefixes, force
6539 continuous clocking by starting the clock when the last clock stopped.@*
6540 @cindex property: CLOCK_MODELINE_TOTAL
6541 @cindex property: LAST_REPEAT
6542 @vindex org-clock-modeline-total
6543 While the clock is running, the current clocking time is shown in the mode
6544 line, along with the title of the task. The clock time shown will be all
6545 time ever clocked for this task and its children. If the task has an effort
6546 estimate (@pxref{Effort estimates}), the mode line displays the current
6547 clocking time against it@footnote{To add an effort estimate ``on the fly'',
6548 hook a function doing this to @code{org-clock-in-prepare-hook}.} If the task
6549 is a repeating one (@pxref{Repeated tasks}), only the time since the last
6550 reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}
6551 will be shown. More control over what time is shown can be exercised with
6552 the @code{CLOCK_MODELINE_TOTAL} property. It may have the values
6553 @code{current} to show only the current clocking instance, @code{today} to
6554 show all time clocked on this task today (see also the variable
6555 @code{org-extend-today-until}), @code{all} to include all time, or
6556 @code{auto} which is the default@footnote{See also the variable
6557 @code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
6558 mode line entry will pop up a menu with clocking options.
6560 @orgcmd{C-c C-x C-o,org-clock-out}
6561 @vindex org-log-note-clock-out
6562 Stop the clock (clock-out). This inserts another timestamp at the same
6563 location where the clock was last started. It also directly computes
6564 the resulting time and inserts it after the time range as @samp{=>
6565 HH:MM}. See the variable @code{org-log-note-clock-out} for the
6566 possibility to record an additional note together with the clock-out
6567 timestamp@footnote{The corresponding in-buffer setting is:
6568 @code{#+STARTUP: lognoteclock-out}}.
6569 @orgcmd{C-c C-x C-x,org-clock-in-last}
6570 @vindex org-clock-continuously
6571 Reclock the last clocked task. With one @kbd{C-u} prefix argument,
6572 select the task from the clock history. With two @kbd{C-u} prefixes,
6573 force continuous clocking by starting the clock when the last clock
6575 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6576 Update the effort estimate for the current clock task.
6579 @orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range}
6580 Recompute the time interval after changing one of the timestamps. This
6581 is only necessary if you edit the timestamps directly. If you change
6582 them with @kbd{S-@key{cursor}} keys, the update is automatic.
6583 @orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
6584 On @code{CLOCK} log lines, increase/decrease both timestamps so that the
6585 clock duration keeps the same.
6586 @orgcmd{S-M-@key{up/down},org-timestamp-up/down}
6587 On @code{CLOCK} log lines, increase/decrease the timestamp at point and
6588 the one of the previous (or the next clock) timestamp by the same duration.
6589 For example, if you hit @kbd{S-M-@key{up}} to increase a clocked-out timestamp
6590 by five minutes, then the clocked-in timestamp of the next clock will be
6591 increased by five minutes.
6592 @orgcmd{C-c C-t,org-todo}
6593 Changing the TODO state of an item to DONE automatically stops the clock
6594 if it is running in this same item.
6595 @orgcmd{C-c C-x C-q,org-clock-cancel}
6596 Cancel the current clock. This is useful if a clock was started by
6597 mistake, or if you ended up working on something else.
6598 @orgcmd{C-c C-x C-j,org-clock-goto}
6599 Jump to the headline of the currently clocked in task. With a @kbd{C-u}
6600 prefix arg, select the target task from a list of recently clocked tasks.
6601 @orgcmd{C-c C-x C-d,org-clock-display}
6602 @vindex org-remove-highlights-with-change
6603 Display time summaries for each subtree in the current buffer. This puts
6604 overlays at the end of each headline, showing the total time recorded under
6605 that heading, including the time of any subheadings. You can use visibility
6606 cycling to study the tree, but the overlays disappear when you change the
6607 buffer (see variable @code{org-remove-highlights-with-change}) or press
6611 The @kbd{l} key may be used the agenda (@pxref{Weekly/daily agenda}) to show
6612 which tasks have been worked on or closed during a day.
6614 @strong{Important:} note that both @code{org-clock-out} and
6615 @code{org-clock-in-last} can have a global key binding and will not
6616 modify the window disposition.
6618 @node The clock table
6619 @subsection The clock table
6620 @cindex clocktable, dynamic block
6621 @cindex report, of clocked time
6623 Org mode can produce quite complex reports based on the time clocking
6624 information. Such a report is called a @emph{clock table}, because it is
6625 formatted as one or several Org tables.
6628 @orgcmd{C-c C-x C-r,org-clock-report}
6629 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
6630 report as an Org mode table into the current file. When the cursor is
6631 at an existing clock table, just update it. When called with a prefix
6632 argument, jump to the first clock report in the current document and
6633 update it. The clock table always includes also trees with
6634 @code{:ARCHIVE:} tag.
6635 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
6636 Update dynamic block at point.
6637 @orgkey{C-u C-c C-x C-u}
6638 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
6639 you have several clock table blocks in a buffer.
6640 @orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift}
6641 Shift the current @code{:block} interval and update the table. The cursor
6642 needs to be in the @code{#+BEGIN: clocktable} line for this command. If
6643 @code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
6647 Here is an example of the frame for a clock table as it is inserted into the
6648 buffer with the @kbd{C-c C-x C-r} command:
6650 @cindex #+BEGIN, clocktable
6652 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
6656 @vindex org-clocktable-defaults
6657 The @samp{BEGIN} line specifies a number of options to define the scope,
6658 structure, and formatting of the report. Defaults for all these options can
6659 be configured in the variable @code{org-clocktable-defaults}.
6661 @noindent First there are options that determine which clock entries are to
6664 :maxlevel @r{Maximum level depth to which times are listed in the table.}
6665 @r{Clocks at deeper levels will be summed into the upper level.}
6666 :scope @r{The scope to consider. This can be any of the following:}
6667 nil @r{the current buffer or narrowed region}
6668 file @r{the full current buffer}
6669 subtree @r{the subtree where the clocktable is located}
6670 tree@var{N} @r{the surrounding level @var{N} tree, for example @code{tree3}}
6671 tree @r{the surrounding level 1 tree}
6672 agenda @r{all agenda files}
6673 ("file"..) @r{scan these files}
6674 function @r{the list of files returned by a function of no argument}
6675 file-with-archives @r{current file and its archives}
6676 agenda-with-archives @r{all agenda files, including archives}
6677 :block @r{The time block to consider. This block is specified either}
6678 @r{absolutely, or relative to the current time and may be any of}
6680 2007-12-31 @r{New year eve 2007}
6681 2007-12 @r{December 2007}
6682 2007-W50 @r{ISO-week 50 in 2007}
6683 2007-Q2 @r{2nd quarter in 2007}
6684 2007 @r{the year 2007}
6685 today, yesterday, today-@var{N} @r{a relative day}
6686 thisweek, lastweek, thisweek-@var{N} @r{a relative week}
6687 thismonth, lastmonth, thismonth-@var{N} @r{a relative month}
6688 thisyear, lastyear, thisyear-@var{N} @r{a relative year}
6690 @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}
6691 :tstart @r{A time string specifying when to start considering times.}
6692 @r{Relative times like @code{"<-2w>"} can also be used. See}
6693 @r{@ref{Matching tags and properties} for relative time syntax.}
6694 :tend @r{A time string specifying when to stop considering times.}
6695 @r{Relative times like @code{"<now>"} can also be used. See}
6696 @r{@ref{Matching tags and properties} for relative time syntax.}
6697 :wstart @r{The starting day of the week. The default is 1 for monday.}
6698 :mstart @r{The starting day of the month. The default 1 is for the first}
6699 @r{day of the month.}
6700 :step @r{@code{week} or @code{day}, to split the table into chunks.}
6701 @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}
6702 :stepskip0 @r{Do not show steps that have zero time.}
6703 :fileskip0 @r{Do not show table sections from files which did not contribute.}
6704 :tags @r{A tags match to select entries that should contribute. See}
6705 @r{@ref{Matching tags and properties} for the match syntax.}
6708 Then there are options which determine the formatting of the table. These
6709 options are interpreted by the function @code{org-clocktable-write-default},
6710 but you can specify your own function using the @code{:formatter} parameter.
6712 :emphasize @r{When @code{t}, emphasize level one and level two items.}
6713 :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".}
6714 :link @r{Link the item headlines in the table to their origins.}
6715 :narrow @r{An integer to limit the width of the headline column in}
6716 @r{the org table. If you write it like @samp{50!}, then the}
6717 @r{headline will also be shortened in export.}
6718 :indent @r{Indent each headline field according to its level.}
6719 :tcolumns @r{Number of columns to be used for times. If this is smaller}
6720 @r{than @code{:maxlevel}, lower levels will be lumped into one column.}
6721 :level @r{Should a level number column be included?}
6722 :sort @r{A cons cell like containing the column to sort and a sorting type.}
6723 @r{E.g., @code{:sort (1 . ?a)} sorts the first column alphabetically.}
6724 :compact @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}}
6725 @r{All are overwritten except if there is an explicit @code{:narrow}}
6726 :timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,}
6727 @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}
6728 :properties @r{List of properties that should be shown in the table. Each}
6729 @r{property will get its own column.}
6730 :inherit-props @r{When this flag is @code{t}, the values for @code{:properties} will be inherited.}
6731 :formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.}
6732 @r{As a special case, @samp{:formula %} adds a column with % time.}
6733 @r{If you do not specify a formula here, any existing formula}
6734 @r{below the clock table will survive updates and be evaluated.}
6735 :formatter @r{A function to format clock data and insert it into the buffer.}
6737 To get a clock summary of the current level 1 tree, for the current
6738 day, you could write
6740 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
6744 and to use a specific time range you could write@footnote{Note that all
6745 parameters must be specified in a single line---the line is broken here
6746 only to fit it into the manual.}
6748 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
6749 :tend "<2006-08-10 Thu 12:00>"
6752 A range starting a week ago and ending right now could be written as
6754 #+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
6757 A summary of the current subtree with % times would be
6759 #+BEGIN: clocktable :scope subtree :link t :formula %
6762 A horizontally compact representation of everything clocked during last week
6765 #+BEGIN: clocktable :scope agenda :block lastweek :compact t
6769 @node Resolving idle time
6770 @subsection Resolving idle time and continuous clocking
6772 @subsubheading Resolving idle time
6773 @cindex resolve idle time
6774 @vindex org-clock-x11idle-program-name
6776 @cindex idle, resolve, dangling
6777 If you clock in on a work item, and then walk away from your
6778 computer---perhaps to take a phone call---you often need to ``resolve'' the
6779 time you were away by either subtracting it from the current clock, or
6780 applying it to another one.
6782 @vindex org-clock-idle-time
6783 By customizing the variable @code{org-clock-idle-time} to some integer, such
6784 as 10 or 15, Emacs can alert you when you get back to your computer after
6785 being idle for that many minutes@footnote{On computers using Mac OS X,
6786 idleness is based on actual user idleness, not just Emacs' idle time. For
6787 X11, you can install a utility program @file{x11idle.c}, available in the
6788 @code{contrib/scripts} directory of the Org git distribution, or install the
6789 @file{xprintidle} package and set it to the variable
6790 @code{org-clock-x11idle-program-name} if you are running Debian, to get the
6791 same general treatment of idleness. On other systems, idle time refers to
6792 Emacs idle time only.}, and ask what you want to do with the idle time.
6793 There will be a question waiting for you when you get back, indicating how
6794 much idle time has passed (constantly updated with the current amount), as
6795 well as a set of choices to correct the discrepancy:
6799 To keep some or all of the minutes and stay clocked in, press @kbd{k}. Org
6800 will ask how many of the minutes to keep. Press @key{RET} to keep them all,
6801 effectively changing nothing, or enter a number to keep that many minutes.
6803 If you use the shift key and press @kbd{K}, it will keep however many minutes
6804 you request and then immediately clock out of that task. If you keep all of
6805 the minutes, this is the same as just clocking out of the current task.
6807 To keep none of the minutes, use @kbd{s} to subtract all the away time from
6808 the clock, and then check back in from the moment you returned.
6810 To keep none of the minutes and just clock out at the start of the away time,
6811 use the shift key and press @kbd{S}. Remember that using shift will always
6812 leave you clocked out, no matter which option you choose.
6814 To cancel the clock altogether, use @kbd{C}. Note that if instead of
6815 canceling you subtract the away time, and the resulting clock amount is less
6816 than a minute, the clock will still be canceled rather than clutter up the
6817 log with an empty entry.
6820 What if you subtracted those away minutes from the current clock, and now
6821 want to apply them to a new clock? Simply clock in to any task immediately
6822 after the subtraction. Org will notice that you have subtracted time ``on
6823 the books'', so to speak, and will ask if you want to apply those minutes to
6824 the next task you clock in on.
6826 There is one other instance when this clock resolution magic occurs. Say you
6827 were clocked in and hacking away, and suddenly your cat chased a mouse who
6828 scared a hamster that crashed into your UPS's power button! You suddenly
6829 lose all your buffers, but thanks to auto-save you still have your recent Org
6830 mode changes, including your last clock in.
6832 If you restart Emacs and clock into any task, Org will notice that you have a
6833 dangling clock which was never clocked out from your last session. Using
6834 that clock's starting time as the beginning of the unaccounted-for period,
6835 Org will ask how you want to resolve that time. The logic and behavior is
6836 identical to dealing with away time due to idleness; it is just happening due
6837 to a recovery event rather than a set amount of idle time.
6839 You can also check all the files visited by your Org agenda for dangling
6840 clocks at any time using @kbd{M-x org-resolve-clocks RET} (or @kbd{C-c C-x C-z}).
6842 @subsubheading Continuous clocking
6843 @cindex continuous clocking
6844 @vindex org-clock-continuously
6846 You may want to start clocking from the time when you clocked out the
6847 previous task. To enable this systematically, set @code{org-clock-continuously}
6848 to @code{t}. Each time you clock in, Org retrieves the clock-out time of the
6849 last clocked entry for this session, and start the new clock from there.
6851 If you only want this from time to time, use three universal prefix arguments
6852 with @code{org-clock-in} and two @kbd{C-u C-u} with @code{org-clock-in-last}.
6854 @node Effort estimates
6855 @section Effort estimates
6856 @cindex effort estimates
6858 @cindex property, Effort
6859 If you want to plan your work in a very detailed way, or if you need to
6860 produce offers with quotations of the estimated work effort, you may want to
6861 assign effort estimates to entries. If you are also clocking your work, you
6862 may later want to compare the planned effort with the actual working time,
6863 a great way to improve planning estimates. Effort estimates are stored in
6864 a special property @code{EFFORT}. You can set the effort for an entry with
6865 the following commands:
6868 @orgcmd{C-c C-x e,org-set-effort}
6869 Set the effort estimate for the current entry. With a numeric prefix
6870 argument, set it to the Nth allowed value (see below). This command is also
6871 accessible from the agenda with the @kbd{e} key.
6872 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6873 Modify the effort estimate of the item currently being clocked.
6876 Clearly the best way to work with effort estimates is through column view
6877 (@pxref{Column view}). You should start by setting up discrete values for
6878 effort estimates, and a @code{COLUMNS} format that displays these values
6879 together with clock sums (if you want to clock your time). For a specific
6883 #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
6884 #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM
6888 @vindex org-global-properties
6889 @vindex org-columns-default-format
6890 or, even better, you can set up these values globally by customizing the
6891 variables @code{org-global-properties} and @code{org-columns-default-format}.
6892 In particular if you want to use this setup also in the agenda, a global
6893 setup may be advised.
6895 The way to assign estimates to individual items is then to switch to column
6896 mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the
6897 value. The values you enter will immediately be summed up in the hierarchy.
6898 In the column next to it, any clocked time will be displayed.
6900 @vindex org-agenda-columns-add-appointments-to-effort-sum
6901 If you switch to column view in the daily/weekly agenda, the effort column
6902 will summarize the estimated work effort for each day@footnote{Please note
6903 the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda
6904 column view}).}, and you can use this to find space in your schedule. To get
6905 an overview of the entire part of the day that is committed, you can set the
6906 option @code{org-agenda-columns-add-appointments-to-effort-sum}. The
6907 appointments on a day that take place over a specified time interval will
6908 then also be added to the load estimate of the day.
6910 Effort estimates can be used in secondary agenda filtering that is triggered
6911 with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have
6912 these estimates defined consistently, two or three key presses will narrow
6913 down the list to stuff that fits into an available time slot.
6916 @section Taking notes with a timer
6917 @cindex relative timer
6918 @cindex countdown timer
6921 Org provides two types of timers. There is a relative timer that counts up,
6922 which can be useful when taking notes during, for example, a meeting or
6923 a video viewing. There is also a countdown timer.
6925 The relative and countdown are started with separate commands.
6928 @orgcmd{C-c C-x 0,org-timer-start}
6929 Start or reset the relative timer. By default, the timer is set to 0. When
6930 called with a @kbd{C-u} prefix, prompt the user for a starting offset. If
6931 there is a timer string at point, this is taken as the default, providing a
6932 convenient way to restart taking notes after a break in the process. When
6933 called with a double prefix argument @kbd{C-u C-u}, change all timer strings
6934 in the active region by a certain amount. This can be used to fix timer
6935 strings if the timer was not started at exactly the right moment.
6936 @orgcmd{C-c C-x ;,org-timer-set-timer}
6937 Start a countdown timer. The user is prompted for a duration.
6938 @code{org-timer-default-timer} sets the default countdown value. Giving
6939 a numeric prefix argument overrides this default value. This command is
6940 available as @kbd{;} in agenda buffers.
6943 Once started, relative and countdown timers are controlled with the same
6947 @orgcmd{C-c C-x .,org-timer}
6948 Insert the value of the current relative or countdown timer into the buffer.
6949 If no timer is running, the relative timer will be started. When called with
6950 a prefix argument, the relative timer is restarted.
6951 @orgcmd{C-c C-x -,org-timer-item}
6952 Insert a description list item with the value of the current relative or
6953 countdown timer. With a prefix argument, first reset the relative timer to
6955 @orgcmd{M-@key{RET},org-insert-heading}
6956 Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert
6958 @orgcmd{C-c C-x @comma{},org-timer-pause-or-continue}
6959 Pause the timer, or continue it if it is already paused.
6960 @orgcmd{C-c C-x _,org-timer-stop}
6961 Stop the timer. After this, you can only start a new timer, not continue the
6962 old one. This command also removes the timer from the mode line.
6965 @node Capture - Refile - Archive
6966 @chapter Capture - Refile - Archive
6969 An important part of any organization system is the ability to quickly
6970 capture new ideas and tasks, and to associate reference material with them.
6971 Org does this using a process called @i{capture}. It also can store files
6972 related to a task (@i{attachments}) in a special directory. Once in the
6973 system, tasks and projects need to be moved around. Moving completed project
6974 trees to an archive file keeps the system compact and fast.
6977 * Capture:: Capturing new stuff
6978 * Attachments:: Add files to tasks
6979 * RSS feeds:: Getting input from RSS feeds
6980 * Protocols:: External (e.g., Browser) access to Emacs and Org
6981 * Refile and copy:: Moving/copying a tree from one place to another
6982 * Archiving:: What to do with finished projects
6989 Capture lets you quickly store notes with little interruption of your work
6990 flow. Org's method for capturing new items is heavily inspired by John
6991 Wiegley excellent @file{remember.el} package. Up to version 6.36, Org
6992 used a special setup for @file{remember.el}, then replaced it with
6993 @file{org-remember.el}. As of version 8.0, @file{org-remember.el} has
6994 been completely replaced by @file{org-capture.el}.
6996 If your configuration depends on @file{org-remember.el}, you need to update
6997 it and use the setup described below. To convert your
6998 @code{org-remember-templates}, run the command
7000 @kbd{M-x org-capture-import-remember-templates RET}
7002 @noindent and then customize the new variable with @kbd{M-x
7003 customize-variable org-capture-templates}, check the result, and save the
7007 * Setting up capture:: Where notes will be stored
7008 * Using capture:: Commands to invoke and terminate capture
7009 * Capture templates:: Define the outline of different note types
7012 @node Setting up capture
7013 @subsection Setting up capture
7015 The following customization sets a default target file for notes, and defines
7016 a global key@footnote{Please select your own key, @kbd{C-c c} is only a
7017 suggestion.} for capturing new material.
7019 @vindex org-default-notes-file
7022 (setq org-default-notes-file (concat org-directory "/notes.org"))
7023 (define-key global-map "\C-cc" 'org-capture)
7028 @subsection Using capture
7031 @orgcmd{C-c c,org-capture}
7032 Call the command @code{org-capture}. Note that this key binding is global and
7033 not active by default: you need to install it. If you have templates
7035 defined @pxref{Capture templates}, it will offer these templates for
7036 selection or use a new Org outline node as the default template. It will
7037 insert the template into the target file and switch to an indirect buffer
7038 narrowed to this new node. You may then insert the information you want.
7040 @orgcmd{C-c C-c,org-capture-finalize}
7041 Once you have finished entering information into the capture buffer, @kbd{C-c
7042 C-c} will return you to the window configuration before the capture process,
7043 so that you can resume your work without further distraction. When called
7044 with a prefix arg, finalize and then jump to the captured item.
7046 @orgcmd{C-c C-w,org-capture-refile}
7047 Finalize the capture process by refiling (@pxref{Refile and copy}) the note to
7048 a different place. Please realize that this is a normal refiling command
7049 that will be executed---so the cursor position at the moment you run this
7050 command is important. If you have inserted a tree with a parent and
7051 children, first move the cursor back to the parent. Any prefix argument
7052 given to this command will be passed on to the @code{org-refile} command.
7054 @orgcmd{C-c C-k,org-capture-kill}
7055 Abort the capture process and return to the previous state.
7059 You can also call @code{org-capture} in a special way from the agenda, using
7060 the @kbd{k c} key combination. With this access, any timestamps inserted by
7061 the selected capture template will default to the cursor date in the agenda,
7062 rather than to the current date.
7064 To find the locations of the last stored capture, use @code{org-capture} with
7069 Visit the target location of a capture template. You get to select the
7070 template in the usual way.
7071 @orgkey{C-u C-u C-c c}
7072 Visit the last stored capture item in its buffer.
7075 @vindex org-capture-bookmark
7076 @cindex org-capture-last-stored
7077 You can also jump to the bookmark @code{org-capture-last-stored}, which will
7078 automatically be created unless you set @code{org-capture-bookmark} to
7081 To insert the capture at point in an Org buffer, call @code{org-capture} with
7082 a @code{C-0} prefix argument.
7084 @node Capture templates
7085 @subsection Capture templates
7086 @cindex templates, for Capture
7088 You can use templates for different types of capture items, and
7089 for different target locations. The easiest way to create such templates is
7090 through the customize interface.
7094 Customize the variable @code{org-capture-templates}.
7097 Before we give the formal description of template definitions, let's look at
7098 an example. Say you would like to use one template to create general TODO
7099 entries, and you want to put these entries under the heading @samp{Tasks} in
7100 your file @file{~/org/gtd.org}. Also, a date tree in the file
7101 @file{journal.org} should capture journal entries. A possible configuration
7106 (setq org-capture-templates
7107 '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
7108 "* TODO %?\n %i\n %a")
7109 ("j" "Journal" entry (file+olp+datetree "~/org/journal.org")
7110 "* %?\nEntered on %U\n %i\n %a")))
7114 @noindent If you then press @kbd{C-c c t}, Org will prepare the template
7118 [[file:@var{link to where you initiated capture}]]
7122 During expansion of the template, @code{%a} has been replaced by a link to
7123 the location from where you called the capture command. This can be
7124 extremely useful for deriving tasks from emails, for example. You fill in
7125 the task definition, press @kbd{C-c C-c} and Org returns you to the same
7126 place where you started the capture process.
7128 To define special keys to capture to a particular template without going
7129 through the interactive template selection, you can create your key binding
7133 (define-key global-map "\C-cx"
7134 (lambda () (interactive) (org-capture nil "x")))
7138 * Template elements:: What is needed for a complete template entry
7139 * Template expansion:: Filling in information about time and context
7140 * Templates in contexts:: Only show a template in a specific context
7143 @node Template elements
7144 @subsubsection Template elements
7146 Now lets look at the elements of a template definition. Each entry in
7147 @code{org-capture-templates} is a list with the following items:
7151 The keys that will select the template, as a string, characters
7152 only, for example @code{"a"} for a template to be selected with a
7153 single key, or @code{"bt"} for selection with two keys. When using
7154 several keys, keys using the same prefix key must be sequential
7155 in the list and preceded by a 2-element entry explaining the
7156 prefix key, for example
7158 ("b" "Templates for marking stuff to buy")
7160 @noindent If you do not define a template for the @kbd{C} key, this key will
7161 be used to open the customize buffer for this complex variable.
7164 A short string describing the template, which will be shown during
7168 The type of entry, a symbol. Valid values are:
7172 An Org mode node, with a headline. Will be filed as the child of the target
7173 entry or as a top-level entry. The target file should be an Org mode file.
7175 A plain list item, placed in the first plain list at the target
7176 location. Again the target file should be an Org file.
7178 A checkbox item. This only differs from the plain list item by the
7181 a new line in the first table at the target location. Where exactly the
7182 line will be inserted depends on the properties @code{:prepend} and
7183 @code{:table-line-pos} (see below).
7185 Text to be inserted as it is.
7189 @vindex org-default-notes-file
7190 Specification of where the captured item should be placed. In Org mode
7191 files, targets usually define a node. Entries will become children of this
7192 node. Other types will be added to the table or list in the body of this
7193 node. Most target specifications contain a file name. If that file name is
7194 the empty string, it defaults to @code{org-default-notes-file}. A file can
7195 also be given as a variable or as a function called with no argument. When
7196 an absolute path is not specified for a target, it is taken as relative to
7197 @code{org-directory}.
7202 @item (file "path/to/file")
7203 Text will be placed at the beginning or end of that file.
7205 @item (id "id of existing org entry")
7206 Filing as child of this entry, or in the body of the entry.
7208 @item (file+headline "path/to/file" "node headline")
7209 Fast configuration if the target heading is unique in the file.
7211 @item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
7212 For non-unique headings, the full path is safer.
7214 @item (file+regexp "path/to/file" "regexp to find location")
7215 Use a regular expression to position the cursor.
7217 @item (file+olp+datetree "path/to/file" [ "Level 1 heading" ....])
7218 This target@footnote{Org used to offer four different targets for date/week
7219 tree capture. Now, Org automatically translates these to use
7220 @code{file+olp+datetree}, applying the @code{:time-prompt} and
7221 @code{:tree-type} properties. Please rewrite your date/week-tree targets
7222 using @code{file+olp+datetree} since the older targets are now deprecated.}
7223 will create a heading in a date tree@footnote{A date tree is an outline
7224 structure with years on the highest level, months or ISO-weeks as sublevels
7225 and then dates on the lowest level. Tags are allowed in the tree structure.}
7226 for today's date. If the optional outline path is given, the tree will be
7227 built under the node it is pointing to, instead of at top level. Check out
7228 the @code{:time-prompt} and @code{:tree-type} properties below for additional
7231 @item (file+function "path/to/file" function-finding-location)
7232 A function to find the right location in the file.
7235 File to the entry that is currently being clocked.
7237 @item (function function-finding-location)
7238 Most general way: write your own function which both visits
7239 the file and moves point to the right location.
7243 The template for creating the capture item. If you leave this empty, an
7244 appropriate default template will be used. Otherwise this is a string with
7245 escape codes, which will be replaced depending on time and context of the
7246 capture call. The string with escapes may be loaded from a template file,
7247 using the special syntax @code{(file "path/to/template")}. See below for
7251 The rest of the entry is a property list of additional options.
7252 Recognized properties are:
7256 Normally new captured information will be appended at
7257 the target location (last child, last table line, last list item...).
7258 Setting this property will change that.
7260 @item :immediate-finish
7261 When set, do not offer to edit the information, just
7262 file it away immediately. This makes sense if the template only needs
7263 information that can be added automatically.
7266 Set this to the number of lines to insert
7267 before and after the new item. Default 0, only common other value is 1.
7270 Start the clock in this item.
7273 Keep the clock running when filing the captured entry.
7276 If starting the capture interrupted a clock, restart that clock when finished
7277 with the capture. Note that @code{:clock-keep} has precedence over
7278 @code{:clock-resume}. When setting both to @code{t}, the current clock will
7279 run and the previous one will not be resumed.
7282 Prompt for a date/time to be used for date/week trees and when filling the
7283 template. Without this property, capture uses the current date and time.
7284 Even if this property has not been set, you can force the same behavior by
7285 calling @code{org-capture} with a @kbd{C-1} prefix argument.
7288 When `week', make a week tree instead of the month tree, i.e. place the
7289 headings for each day under a heading with the current iso week.
7292 Do not narrow the target buffer, simply show the full buffer. Default is to
7293 narrow it so that you only see the new material.
7295 @item :table-line-pos
7296 Specification of the location in the table where the new line should be
7297 inserted. It can be a string, a variable holding a string or a function
7298 returning a string. The string should look like @code{"II-3"} meaning that
7299 the new line should become the third line before the second horizontal
7303 If the target file was not yet visited when capture was invoked, kill the
7304 buffer again after capture is completed.
7308 @node Template expansion
7309 @subsubsection Template expansion
7311 In the template itself, special @kbd{%}-escapes@footnote{If you need one of
7312 these sequences literally, escape the @kbd{%} with a backslash.} allow
7313 dynamic insertion of content. The templates are expanded in the order given here:
7316 %[@var{file}] @r{Insert the contents of the file given by @var{file}.}
7317 %(@var{sexp}) @r{Evaluate Elisp @var{sexp} and replace with the result.}
7318 @r{For convenience, %:keyword (see below) placeholders}
7319 @r{within the expression will be expanded prior to this.}
7320 @r{The sexp must return a string.}
7321 %<...> @r{The result of format-time-string on the ... format specification.}
7322 %t @r{Timestamp, date only.}
7323 %T @r{Timestamp, with date and time.}
7324 %u, %U @r{Like the above, but inactive timestamps.}
7325 %i @r{Initial content, the region when capture is called while the}
7326 @r{region is active.}
7327 @r{The entire text will be indented like @code{%i} itself.}
7328 %a @r{Annotation, normally the link created with @code{org-store-link}.}
7329 %A @r{Like @code{%a}, but prompt for the description part.}
7330 %l @r{Like %a, but only insert the literal link.}
7331 %c @r{Current kill ring head.}
7332 %x @r{Content of the X clipboard.}
7333 %k @r{Title of the currently clocked task.}
7334 %K @r{Link to the currently clocked task.}
7335 %n @r{User name (taken from @code{user-full-name}).}
7336 %f @r{File visited by current buffer when org-capture was called.}
7337 %F @r{Full path of the file or directory visited by current buffer.}
7338 %:keyword @r{Specific information for certain link types, see below.}
7339 %^g @r{Prompt for tags, with completion on tags in target file.}
7340 %^G @r{Prompt for tags, with completion all tags in all agenda files.}
7341 %^t @r{Like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}.}
7342 @r{You may define a prompt like @code{%^@{Birthday@}t}.}
7343 %^C @r{Interactive selection of which kill or clip to use.}
7344 %^L @r{Like @code{%^C}, but insert as link.}
7345 %^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}.}
7346 %^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.}
7347 @r{You may specify a default value and a completion table with}
7348 @r{%^@{prompt|default|completion2|completion3...@}.}
7349 @r{The arrow keys access a prompt-specific history.}
7350 %\1 @dots{} %\N @r{Insert the text entered at the Nth %^@{@var{prompt}@}, where @code{N} is}
7351 @r{a number, starting from 1.@footnote{As required in Emacs
7352 Lisp, it is necessary to escape any backslash character in
7353 a string with another backslash. So, in order to use
7354 @samp{%\1} placeholder, you need to write @samp{%\\1} in
7356 %? @r{After completing the template, position cursor here.}
7360 For specific link types, the following keywords will be
7361 defined@footnote{If you define your own link types (@pxref{Adding
7362 hyperlink types}), any property you store with
7363 @code{org-store-link-props} can be accessed in capture templates in a
7366 @vindex org-from-is-user-regexp
7368 Link type | Available keywords
7369 ---------------------------------+----------------------------------------------
7370 bbdb | %:name %:company
7371 irc | %:server %:port %:nick
7372 vm, vm-imap, wl, mh, mew, rmail, | %:type %:subject %:message-id
7373 gnus, notmuch | %:from %:fromname %:fromaddress
7374 | %:to %:toname %:toaddress
7375 | %:date @r{(message date header field)}
7376 | %:date-timestamp @r{(date as active timestamp)}
7377 | %:date-timestamp-inactive @r{(date as inactive timestamp)}
7378 | %: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}.}}
7379 gnus | %:group, @r{for messages also all email fields}
7380 eww, w3, w3m | %:url
7381 info | %:file %:node
7383 org-protocol | %:link %:description %:annotation
7387 To place the cursor after template expansion use:
7390 %? @r{After completing the template, position cursor here.}
7393 @node Templates in contexts
7394 @subsubsection Templates in contexts
7396 @vindex org-capture-templates-contexts
7397 To control whether a capture template should be accessible from a specific
7398 context, you can customize @code{org-capture-templates-contexts}. Let's say
7399 for example that you have a capture template @code{"p"} for storing Gnus
7400 emails containing patches. Then you would configure this option like this:
7403 (setq org-capture-templates-contexts
7404 '(("p" (in-mode . "message-mode"))))
7407 You can also tell that the command key @code{"p"} should refer to another
7408 template. In that case, add this command key like this:
7411 (setq org-capture-templates-contexts
7412 '(("p" "q" (in-mode . "message-mode"))))
7415 See the docstring of the variable for more information.
7418 @section Attachments
7421 @vindex org-attach-directory
7422 It is often useful to associate reference material with an outline node/task.
7423 Small chunks of plain text can simply be stored in the subtree of a project.
7424 Hyperlinks (@pxref{Hyperlinks}) can establish associations with
7425 files that live elsewhere on your computer or in the cloud, like emails or
7426 source code files belonging to a project. Another method is @i{attachments},
7427 which are files located in a directory belonging to an outline node. Org
7428 uses directories named by the unique ID of each entry. These directories are
7429 located in the @file{data} directory which lives in the same directory where
7430 your Org file lives@footnote{If you move entries or Org files from one
7431 directory to another, you may want to configure @code{org-attach-directory}
7432 to contain an absolute path.}. If you initialize this directory with
7433 @code{git init}, Org will automatically commit changes when it sees them.
7434 The attachment system has been contributed to Org by John Wiegley.
7436 In cases where it seems better to do so, you can also attach a directory of your
7437 choice to an entry. You can also make children inherit the attachment
7438 directory from a parent, so that an entire subtree uses the same attached
7441 @noindent The following commands deal with attachments:
7444 @orgcmd{C-c C-a,org-attach}
7445 The dispatcher for commands related to the attachment system. After these
7446 keys, a list of commands is displayed and you must press an additional key
7447 to select a command:
7450 @orgcmdtkc{a,C-c C-a a,org-attach-attach}
7451 @vindex org-attach-method
7452 Select a file and move it into the task's attachment directory. The file
7453 will be copied, moved, or linked, depending on @code{org-attach-method}.
7454 Note that hard links are not supported on all systems.
7460 Attach a file using the copy/move/link method.
7461 Note that hard links are not supported on all systems.
7463 @orgcmdtkc{u,C-c C-a u,org-attach-url}
7464 Attach a file from URL
7466 @orgcmdtkc{n,C-c C-a n,org-attach-new}
7467 Create a new attachment as an Emacs buffer.
7469 @orgcmdtkc{z,C-c C-a z,org-attach-sync}
7470 Synchronize the current task with its attachment directory, in case you added
7471 attachments yourself.
7473 @orgcmdtkc{o,C-c C-a o,org-attach-open}
7474 @vindex org-file-apps
7475 Open current task's attachment. If there is more than one, prompt for a
7476 file name first. Opening will follow the rules set by @code{org-file-apps}.
7477 For more details, see the information on following hyperlinks
7478 (@pxref{Handling links}).
7480 @orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs}
7481 Also open the attachment, but force opening the file in Emacs.
7483 @orgcmdtkc{f,C-c C-a f,org-attach-reveal}
7484 Open the current task's attachment directory.
7486 @orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs}
7487 Also open the directory, but force using @command{dired} in Emacs.
7489 @orgcmdtkc{d,C-c C-a d,org-attach-delete-one}
7490 Select and delete a single attachment.
7492 @orgcmdtkc{D,C-c C-a D,org-attach-delete-all}
7493 Delete all of a task's attachments. A safer way is to open the directory in
7494 @command{dired} and delete from there.
7496 @orgcmdtkc{s,C-c C-a s,org-attach-set-directory}
7497 @cindex property, ATTACH_DIR
7498 Set a specific directory as the entry's attachment directory. This works by
7499 putting the directory path into the @code{ATTACH_DIR} property.
7501 @orgcmdtkc{i,C-c C-a i,org-attach-set-inherit}
7502 @cindex property, ATTACH_DIR_INHERIT
7503 Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the
7504 same directory for attachments as the parent does.
7513 Org can add and change entries based on information found in RSS feeds and
7514 Atom feeds. You could use this to make a task out of each new podcast in a
7515 podcast feed. Or you could use a phone-based note-creating service on the
7516 web to import tasks into Org. To access feeds, configure the variable
7517 @code{org-feed-alist}. The docstring of this variable has detailed
7518 information. Here is just an example:
7522 (setq org-feed-alist
7524 "http://rss.slashdot.org/Slashdot/slashdot"
7525 "~/txt/org/feeds.org" "Slashdot Entries")))
7530 will configure that new items from the feed provided by
7531 @code{rss.slashdot.org} will result in new entries in the file
7532 @file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
7533 the following command is used:
7536 @orgcmd{C-c C-x g,org-feed-update-all}
7538 Collect items from the feeds configured in @code{org-feed-alist} and act upon
7540 @orgcmd{C-c C-x G,org-feed-goto-inbox}
7541 Prompt for a feed name and go to the inbox configured for this feed.
7544 Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which
7545 it will store information about the status of items in the feed, to avoid
7546 adding the same item several times.
7548 For more information, including how to read atom feeds, see
7549 @file{org-feed.el} and the docstring of @code{org-feed-alist}.
7552 @section Protocols for external access
7553 @cindex protocols, for external access
7555 Org protocol is a mean to trigger custom actions in Emacs from external
7556 applications. Any application that supports calling external programs with
7557 an URL as argument may be used with this functionality. For example, you can
7558 configure bookmarks in your web browser to send a link to the current page to
7559 Org and create a note from it using capture (@pxref{Capture}). You can also
7560 create a bookmark that tells Emacs to open the local source file of a remote
7561 website you are browsing.
7563 @cindex Org protocol, set-up
7564 @cindex Installing Org protocol
7565 In order to use Org protocol from an application, you need to register
7566 @samp{org-protocol://} as a valid scheme-handler. External calls are passed
7567 to Emacs through the @code{emacsclient} command, so you also need to ensure
7568 an Emacs server is running. More precisely, when the application calls
7571 emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2
7575 Emacs calls the handler associated to @samp{PROTOCOL} with argument
7576 @samp{(:key1 val1 :key2 val2)}.
7578 @cindex protocol, new protocol
7579 @cindex defining new protocols
7580 Org protocol comes with three predefined protocols, detailed in the following
7581 sections. Configure @code{org-protocol-protocol-alist} to define your own.
7584 * @code{store-link} protocol:: Store a link, push URL to kill-ring.
7585 * @code{capture} protocol:: Fill a buffer with external information.
7586 * @code{open-source} protocol:: Edit published contents.
7589 @node @code{store-link} protocol
7590 @subsection @code{store-link} protocol
7591 @cindex store-link protocol
7592 @cindex protocol, store-link
7594 Using @code{store-link} handler, you can copy links, insertable through
7595 @kbd{M-x org-insert-link} or yanking thereafter. More precisely, the command
7598 emacsclient org-protocol://store-link?url=URL&title=TITLE
7602 stores the following link:
7608 In addition, @samp{URL} is pushed on the kill-ring for yanking. You need to
7609 encode @samp{URL} and @samp{TITLE} if they contain slashes, and probably
7610 quote those for the shell.
7612 To use this feature from a browser, add a bookmark with an arbitrary name,
7613 e.g., @samp{Org: store-link} and enter this as @emph{Location}:
7616 javascript:location.href='org-protocol://store-link?url='+
7617 encodeURIComponent(location.href);
7620 @node @code{capture} protocol
7621 @subsection @code{capture} protocol
7622 @cindex capture protocol
7623 @cindex protocol, capture
7625 Activating @code{capture} handler pops up a @samp{Capture} buffer and fills
7626 the capture template associated to the @samp{X} key with them.
7629 emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY
7632 To use this feature, add a bookmark with an arbitrary name, e.g. @samp{Org:
7633 capture} and enter this as @samp{Location}:
7636 javascript:location.href='org-protocol://template=x'+
7637 '&url='+encodeURIComponent(window.location.href)+
7638 '&title='+encodeURIComponent(document.title)+
7639 '&body='+encodeURIComponent(window.getSelection());
7642 @vindex org-protocol-default-template-key
7643 The result depends on the capture template used, which is set in the bookmark
7644 itself, as in the example above, or in
7645 @code{org-protocol-default-template-key}.
7647 @cindex capture, %:link placeholder
7648 @cindex %:link template expansion in capture
7649 @cindex capture, %:description placeholder
7650 @cindex %:description template expansion in capture
7651 @cindex capture, %:annotation placeholder
7652 @cindex %:annotation template expansion in capture
7653 The following template placeholders are available:
7657 %:description The webpage title
7658 %:annotation Equivalent to [[%:link][%:description]]
7659 %i The selected text
7662 @node @code{open-source} protocol
7663 @subsection @code{open-source} protocol
7664 @cindex open-source protocol
7665 @cindex protocol, open-source
7667 The @code{open-source} handler is designed to help with editing local sources
7668 when reading a document. To that effect, you can use a bookmark with the
7672 javascript:location.href='org-protocol://open-source?&url='+
7673 encodeURIComponent(location.href)
7676 @cindex protocol, open-source, :base-url property
7677 @cindex :base-url property in open-source protocol
7678 @cindex protocol, open-source, :working-directory property
7679 @cindex :working-directory property in open-source protocol
7680 @cindex protocol, open-source, :online-suffix property
7681 @cindex :online-suffix property in open-source protocol
7682 @cindex protocol, open-source, :working-suffix property
7683 @cindex :working-suffix property in open-source protocol
7684 @vindex org-protocol-project-alist
7685 The variable @code{org-protocol-project-alist} maps URLs to local file names,
7686 by stripping URL parameters from the end and replacing the @code{:base-url}
7687 with @code{:working-directory} and @code{:online-suffix} with
7688 @code{:working-suffix}. For example, assuming you own a local copy of
7689 @url{http://orgmode.org/worg/} contents at @file{/home/user/worg}, you can
7690 set @code{org-protocol-project-alist} to the following
7693 (setq org-protocol-project-alist
7695 :base-url "http://orgmode.org/worg/"
7696 :working-directory "/home/user/worg/"
7697 :online-suffix ".html"
7698 :working-suffix ".org")))
7702 If you are now browsing
7703 @url{http://orgmode.org/worg/org-contrib/org-protocol.html} and find a typo
7704 or have an idea about how to enhance the documentation, simply click the
7705 bookmark and start editing.
7707 @cindex handle rewritten URL in open-source protocol
7708 @cindex protocol, open-source rewritten URL
7709 However, such mapping may not yield the desired results. Suppose you
7710 maintain an online store located at @url{http://example.com/}. The local
7711 sources reside in @file{/home/user/example/}. It is common practice to serve
7712 all products in such a store through one file and rewrite URLs that do not
7713 match an existing file on the server. That way, a request to
7714 @url{http://example.com/print/posters.html} might be rewritten on the server
7716 @url{http://example.com/shop/products.php/posters.html.php}. The
7717 @code{open-source} handler probably cannot find a file named
7718 @file{/home/user/example/print/posters.html.php} and fails.
7720 @cindex protocol, open-source, :rewrites property
7721 @cindex :rewrites property in open-source protocol
7722 Such an entry in @code{org-protocol-project-alist} may hold an additional
7723 property @code{:rewrites}. This property is a list of cons cells, each of
7724 which maps a regular expression to a path relative to the
7725 @code{:working-directory}.
7727 Now map the URL to the path @file{/home/user/example/products.php} by adding
7728 @code{:rewrites} rules like this:
7731 (setq org-protocol-project-alist
7733 :base-url "http://example.com/"
7734 :working-directory "/home/user/example/"
7735 :online-suffix ".php"
7736 :working-suffix ".php"
7737 :rewrites (("example.com/print/" . "products.php")
7738 ("example.com/$" . "index.php")))))
7742 Since @samp{example.com/$} is used as a regular expression, it maps
7743 @url{http://example.com/}, @url{https://example.com},
7744 @url{http://www.example.com/} and similar to
7745 @file{/home/user/example/index.php}.
7747 The @code{:rewrites} rules are searched as a last resort if and only if no
7748 existing file name is matched.
7750 @cindex protocol, open-source, set-up mapping
7751 @cindex set-up mappings in open-source protocol
7752 @findex org-protocol-create
7753 @findex org-protocol-create-for-org
7754 Two functions can help you filling @code{org-protocol-project-alist} with
7755 valid contents: @code{org-protocol-create} and
7756 @code{org-protocol-create-for-org}. The latter is of use if you're editing
7757 an Org file that is part of a publishing project.
7759 @node Refile and copy
7760 @section Refile and copy
7761 @cindex refiling notes
7762 @cindex copying notes
7764 When reviewing the captured data, you may want to refile or to copy some of
7765 the entries into a different list, for example into a project. Cutting,
7766 finding the right location, and then pasting the note is cumbersome. To
7767 simplify this process, you can use the following special command:
7770 @orgcmd{C-c M-w,org-copy}
7772 Copying works like refiling, except that the original note is not deleted.
7773 @orgcmd{C-c C-w,org-refile}
7775 @vindex org-reverse-note-order
7776 @vindex org-refile-targets
7777 @vindex org-refile-use-outline-path
7778 @vindex org-outline-path-complete-in-steps
7779 @vindex org-refile-allow-creating-parent-nodes
7780 @vindex org-log-refile
7781 @vindex org-refile-use-cache
7782 @vindex org-refile-keep
7783 Refile the entry or region at point. This command offers possible locations
7784 for refiling the entry and lets you select one with completion. The item (or
7785 all items in the region) is filed below the target heading as a subitem.
7786 Depending on @code{org-reverse-note-order}, it will be either the first or
7788 By default, all level 1 headlines in the current buffer are considered to be
7789 targets, but you can have more complex definitions across a number of files.
7790 See the variable @code{org-refile-targets} for details. If you would like to
7791 select a location via a file-path-like completion along the outline path, see
7792 the variables @code{org-refile-use-outline-path} and
7793 @code{org-outline-path-complete-in-steps}. If you would like to be able to
7794 create new nodes as new parents for refiling on the fly, check the
7795 variable @code{org-refile-allow-creating-parent-nodes}.
7796 When the variable @code{org-log-refile}@footnote{with corresponding
7797 @code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},
7798 and @code{nologrefile}} is set, a timestamp or a note will be
7799 recorded when an entry has been refiled.
7800 @orgkey{C-u C-c C-w}
7801 Use the refile interface to jump to a heading.
7802 @orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored}
7803 Jump to the location where @code{org-refile} last moved a tree to.
7805 Refile as the child of the item currently being clocked.
7807 Refile and keep the entry in place. Also see @code{org-refile-keep} to make
7808 this the default behavior, and beware that this may result in duplicated
7809 @code{ID} properties.
7810 @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}
7811 Clear the target cache. Caching of refile targets can be turned on by
7812 setting @code{org-refile-use-cache}. To make the command see new possible
7813 targets, you have to clear the cache with this command.
7820 When a project represented by a (sub)tree is finished, you may want
7821 to move the tree out of the way and to stop it from contributing to the
7822 agenda. Archiving is important to keep your working files compact and global
7823 searches like the construction of agenda views fast.
7826 @orgcmd{C-c C-x C-a,org-archive-subtree-default}
7827 @vindex org-archive-default-command
7828 Archive the current entry using the command specified in the variable
7829 @code{org-archive-default-command}.
7833 * Moving subtrees:: Moving a tree to an archive file
7834 * Internal archiving:: Switch off a tree but keep it in the file
7837 @node Moving subtrees
7838 @subsection Moving a tree to the archive file
7839 @cindex external archiving
7841 The most common archiving action is to move a project tree to another file,
7845 @orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
7846 @vindex org-archive-location
7847 Archive the subtree starting at the cursor position to the location
7848 given by @code{org-archive-location}.
7849 @orgkey{C-u C-c C-x C-s}
7850 Check if any direct children of the current headline could be moved to
7851 the archive. To do this, each subtree is checked for open TODO entries.
7852 If none are found, the command offers to move it to the archive
7853 location. If the cursor is @emph{not} on a headline when this command
7854 is invoked, the level 1 trees will be checked.
7855 @orgkey{C-u C-u C-c C-x C-s}
7856 As above, but check subtree for timestamps instead of TODO entries. The
7857 command will offer to archive the subtree if it @emph{does} contain a
7858 timestamp, and that timestamp is in the past.
7861 @cindex archive locations
7862 The default archive location is a file in the same directory as the
7863 current file, with the name derived by appending @file{_archive} to the
7864 current file name. You can also choose what heading to file archived
7865 items under, with the possibility to add them to a datetree in a file.
7866 For information and examples on how to specify the file and the heading,
7867 see the documentation string of the variable
7868 @code{org-archive-location}.
7870 There is also an in-buffer option for setting this variable, for example:
7874 #+ARCHIVE: %s_done::
7877 @cindex property, ARCHIVE
7879 If you would like to have a special ARCHIVE location for a single entry
7880 or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
7881 location as the value (@pxref{Properties and columns}).
7883 @vindex org-archive-save-context-info
7884 When a subtree is moved, it receives a number of special properties that
7885 record context information like the file from where the entry came, its
7886 outline path the archiving time etc. Configure the variable
7887 @code{org-archive-save-context-info} to adjust the amount of information
7891 @node Internal archiving
7892 @subsection Internal archiving
7895 If you want to just switch off---for agenda views---certain subtrees without
7896 moving them to a different file, you can use the archive tag.
7898 A headline that is marked with the @samp{:ARCHIVE:} tag (@pxref{Tags}) stays
7899 at its location in the outline tree, but behaves in the following way:
7902 @vindex org-cycle-open-archived-trees
7903 It does not open when you attempt to do so with a visibility cycling
7904 command (@pxref{Visibility cycling}). You can force cycling archived
7905 subtrees with @kbd{C-@key{TAB}}, or by setting the option
7906 @code{org-cycle-open-archived-trees}. Also normal outline commands like
7907 @code{show-all} will open archived subtrees.
7909 @vindex org-sparse-tree-open-archived-trees
7910 During sparse tree construction (@pxref{Sparse trees}), matches in
7911 archived subtrees are not exposed, unless you configure the option
7912 @code{org-sparse-tree-open-archived-trees}.
7914 @vindex org-agenda-skip-archived-trees
7915 During agenda view construction (@pxref{Agenda views}), the content of
7916 archived trees is ignored unless you configure the option
7917 @code{org-agenda-skip-archived-trees}, in which case these trees will always
7918 be included. In the agenda you can press @kbd{v a} to get archives
7919 temporarily included.
7921 @vindex org-export-with-archived-trees
7922 Archived trees are not exported (@pxref{Exporting}), only the headline
7923 is. Configure the details using the variable
7924 @code{org-export-with-archived-trees}.
7926 @vindex org-columns-skip-archived-trees
7927 Archived trees are excluded from column view unless the variable
7928 @code{org-columns-skip-archived-trees} is configured to @code{nil}.
7931 The following commands help manage the ARCHIVE tag:
7934 @orgcmd{C-c C-x a,org-toggle-archive-tag}
7935 Toggle the ARCHIVE tag for the current headline. When the tag is set,
7936 the headline changes to a shadowed face, and the subtree below it is
7938 @orgkey{C-u C-c C-x a}
7939 Check if any direct children of the current headline should be archived.
7940 To do this, each subtree is checked for open TODO entries. If none are
7941 found, the command offers to set the ARCHIVE tag for the child. If the
7942 cursor is @emph{not} on a headline when this command is invoked, the
7943 level 1 trees will be checked.
7944 @orgcmd{C-@kbd{TAB},org-force-cycle-archived}
7945 Cycle a tree even if it is tagged with ARCHIVE.
7946 @orgcmd{C-c C-x A,org-archive-to-archive-sibling}
7947 Move the current entry to the @emph{Archive Sibling}. This is a sibling of
7948 the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The
7949 entry becomes a child of that sibling and in this way retains a lot of its
7950 original context, including inherited tags and approximate position in the
7956 @chapter Agenda views
7957 @cindex agenda views
7959 Due to the way Org works, TODO items, time-stamped items, and
7960 tagged headlines can be scattered throughout a file or even a number of
7961 files. To get an overview of open action items, or of events that are
7962 important for a particular date, this information must be collected,
7963 sorted and displayed in an organized way.
7965 Org can select items based on various criteria and display them
7966 in a separate buffer. Six different view types are provided:
7970 an @emph{agenda} that is like a calendar and shows information
7973 a @emph{TODO list} that covers all unfinished
7976 a @emph{match view}, showings headlines based on the tags, properties, and
7977 TODO state associated with them,
7979 a @emph{text search view} that shows all entries from multiple files
7980 that contain specified keywords,
7982 a @emph{stuck projects view} showing projects that currently don't move
7985 @emph{custom views} that are special searches and combinations of different
7990 The extracted information is displayed in a special @emph{agenda
7991 buffer}. This buffer is read-only, but provides commands to visit the
7992 corresponding locations in the original Org files, and even to
7993 edit these files remotely.
7995 @vindex org-agenda-skip-comment-trees
7996 @vindex org-agenda-skip-archived-trees
7997 @cindex commented entries, in agenda views
7998 @cindex archived entries, in agenda views
7999 By default, the report ignores commented (@pxref{Comment lines}) and archived
8000 (@pxref{Internal archiving}) entries. You can override this by setting
8001 @code{org-agenda-skip-comment-trees} and
8002 @code{org-agenda-skip-archived-trees} to @code{nil}.
8004 @vindex org-agenda-window-setup
8005 @vindex org-agenda-restore-windows-after-quit
8006 Two variables control how the agenda buffer is displayed and whether the
8007 window configuration is restored when the agenda exits:
8008 @code{org-agenda-window-setup} and
8009 @code{org-agenda-restore-windows-after-quit}.
8012 * Agenda files:: Files being searched for agenda information
8013 * Agenda dispatcher:: Keyboard access to agenda views
8014 * Built-in agenda views:: What is available out of the box?
8015 * Presentation and sorting:: How agenda items are prepared for display
8016 * Agenda commands:: Remote editing of Org trees
8017 * Custom agenda views:: Defining special searches and views
8018 * Exporting agenda views:: Writing a view to a file
8019 * Agenda column view:: Using column view for collected entries
8023 @section Agenda files
8024 @cindex agenda files
8025 @cindex files for agenda
8027 @vindex org-agenda-files
8028 The information to be shown is normally collected from all @emph{agenda
8029 files}, the files listed in the variable
8030 @code{org-agenda-files}@footnote{If the value of that variable is not a
8031 list, but a single file name, then the list of agenda files will be
8032 maintained in that external file.}. If a directory is part of this list,
8033 all files with the extension @file{.org} in this directory will be part
8036 Thus, even if you only work with a single Org file, that file should
8037 be put into the list@footnote{When using the dispatcher, pressing
8038 @kbd{<} before selecting a command will actually limit the command to
8039 the current file, and ignore @code{org-agenda-files} until the next
8040 dispatcher command.}. You can customize @code{org-agenda-files}, but
8041 the easiest way to maintain it is through the following commands
8043 @cindex files, adding to agenda list
8045 @orgcmd{C-c [,org-agenda-file-to-front}
8046 Add current file to the list of agenda files. The file is added to
8047 the front of the list. If it was already in the list, it is moved to
8048 the front. With a prefix argument, file is added/moved to the end.
8049 @orgcmd{C-c ],org-remove-file}
8050 Remove current file from the list of agenda files.
8052 @cindex cycling, of agenda files
8053 @orgcmd{C-',org-cycle-agenda-files}
8055 Cycle through agenda file list, visiting one file after the other.
8056 @kindex M-x org-iswitchb
8057 @item M-x org-iswitchb RET
8058 Command to use an @code{iswitchb}-like interface to switch to and between Org
8063 The Org menu contains the current list of files and can be used
8064 to visit any of them.
8066 If you would like to focus the agenda temporarily on a file not in
8067 this list, or on just one file in the list, or even on only a subtree in a
8068 file, then this can be done in different ways. For a single agenda command,
8069 you may press @kbd{<} once or several times in the dispatcher
8070 (@pxref{Agenda dispatcher}). To restrict the agenda scope for an
8071 extended period, use the following commands:
8074 @orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
8075 Permanently restrict the agenda to the current subtree. When with a
8076 prefix argument, or with the cursor before the first headline in a file,
8077 the agenda scope is set to the entire file. This restriction remains in
8078 effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
8079 or @kbd{>} in the agenda dispatcher. If there is a window displaying an
8080 agenda view, the new restriction takes effect immediately.
8081 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
8082 Remove the permanent restriction created by @kbd{C-c C-x <}.
8086 When working with @file{speedbar.el}, you can use the following commands in
8090 @orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
8091 Permanently restrict the agenda to the item---either an Org file or a subtree
8092 in such a file---at the cursor in the Speedbar frame.
8093 If there is a window displaying an agenda view, the new restriction takes
8095 @orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
8096 Lift the restriction.
8099 @node Agenda dispatcher
8100 @section The agenda dispatcher
8101 @cindex agenda dispatcher
8102 @cindex dispatching agenda commands
8103 The views are created through a dispatcher, which should be bound to a
8104 global key---for example @kbd{C-c a} (@pxref{Activation}). In the
8105 following we will assume that @kbd{C-c a} is indeed how the dispatcher
8106 is accessed and list keyboard access to commands accordingly. After
8107 pressing @kbd{C-c a}, an additional letter is required to execute a
8108 command. The dispatcher offers the following default commands:
8112 Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
8114 Create a list of all TODO items (@pxref{Global TODO list}).
8116 Create a list of headlines matching a TAGS expression (@pxref{Matching
8117 tags and properties}).
8119 Create a list of entries selected by a boolean expression of keywords
8120 and/or regular expressions that must or must not occur in the entry.
8122 @vindex org-agenda-text-search-extra-files
8123 Search for a regular expression in all agenda files and additionally in
8124 the files listed in @code{org-agenda-text-search-extra-files}. This
8125 uses the Emacs command @code{multi-occur}. A prefix argument can be
8126 used to specify the number of context lines for each match, default is
8129 Create a list of stuck projects (@pxref{Stuck projects}).
8131 Restrict an agenda command to the current buffer@footnote{For backward
8132 compatibility, you can also press @kbd{1} to restrict to the current
8133 buffer.}. After pressing @kbd{<}, you still need to press the character
8134 selecting the command.
8136 If there is an active region, restrict the following agenda command to
8137 the region. Otherwise, restrict it to the current subtree@footnote{For
8138 backward compatibility, you can also press @kbd{0} to restrict to the
8139 current region/subtree.}. After pressing @kbd{< <}, you still need to press the
8140 character selecting the command.
8143 @cindex agenda, sticky
8144 @vindex org-agenda-sticky
8145 Toggle sticky agenda views. By default, Org maintains only a single agenda
8146 buffer and rebuilds it each time you change the view, to make sure everything
8147 is always up to date. If you often switch between agenda views and the build
8148 time bothers you, you can turn on sticky agenda buffers or make this the
8149 default by customizing the variable @code{org-agenda-sticky}. With sticky
8150 agendas, the agenda dispatcher will not recreate agenda views from scratch,
8151 it will only switch to the selected one, and you need to update the agenda by
8152 hand with @kbd{r} or @kbd{g} when needed. You can toggle sticky agenda view
8153 any time with @code{org-toggle-sticky-agenda}.
8156 You can also define custom commands that will be accessible through the
8157 dispatcher, just like the default commands. This includes the
8158 possibility to create extended agenda buffers that contain several
8159 blocks together, for example the weekly agenda, the global TODO list and
8160 a number of special tags matches. @xref{Custom agenda views}.
8162 @node Built-in agenda views
8163 @section The built-in agenda views
8165 In this section we describe the built-in views.
8168 * Weekly/daily agenda:: The calendar page with current tasks
8169 * Global TODO list:: All unfinished action items
8170 * Matching tags and properties:: Structured information with fine-tuned search
8171 * Search view:: Find entries by searching for text
8172 * Stuck projects:: Find projects you need to review
8175 @node Weekly/daily agenda
8176 @subsection The weekly/daily agenda
8178 @cindex weekly agenda
8179 @cindex daily agenda
8181 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
8182 paper agenda, showing all the tasks for the current week or day.
8185 @cindex org-agenda, command
8186 @orgcmd{C-c a a,org-agenda-list}
8187 Compile an agenda for the current week from a list of Org files. The agenda
8188 shows the entries for each day. With a numeric prefix@footnote{For backward
8189 compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be
8190 listed before the agenda. This feature is deprecated, use the dedicated TODO
8191 list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1
8192 C-c a a}) you may set the number of days to be displayed.
8195 @vindex org-agenda-span
8196 @vindex org-agenda-ndays
8197 @vindex org-agenda-start-day
8198 @vindex org-agenda-start-on-weekday
8199 The default number of days displayed in the agenda is set by the variable
8200 @code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This
8201 variable can be set to any number of days you want to see by default in the
8202 agenda, or to a span name, such as @code{day}, @code{week}, @code{month} or
8203 @code{year}. For weekly agendas, the default is to start on the previous
8204 monday (see @code{org-agenda-start-on-weekday}). You can also set the start
8205 date using a date shift: @code{(setq org-agenda-start-day "+10d")} will
8206 start the agenda ten days from today in the future.
8208 Remote editing from the agenda buffer means, for example, that you can
8209 change the dates of deadlines and appointments from the agenda buffer.
8210 The commands available in the Agenda buffer are listed in @ref{Agenda
8213 @subsubheading Calendar/Diary integration
8214 @cindex calendar integration
8215 @cindex diary integration
8217 Emacs contains the calendar and diary by Edward M. Reingold. The
8218 calendar displays a three-month calendar with holidays from different
8219 countries and cultures. The diary allows you to keep track of
8220 anniversaries, lunar phases, sunrise/set, recurrent appointments
8221 (weekly, monthly) and more. In this way, it is quite complementary to
8222 Org. It can be very useful to combine output from Org with
8225 In order to include entries from the Emacs diary into Org mode's
8226 agenda, you only need to customize the variable
8229 (setq org-agenda-include-diary t)
8232 @noindent After that, everything will happen automatically. All diary
8233 entries including holidays, anniversaries, etc., will be included in the
8234 agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and
8235 @key{RET} can be used from the agenda buffer to jump to the diary
8236 file in order to edit existing diary entries. The @kbd{i} command to
8237 insert new entries for the current date works in the agenda buffer, as
8238 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
8239 Sunrise/Sunset times, show lunar phases and to convert to other
8240 calendars, respectively. @kbd{c} can be used to switch back and forth
8241 between calendar and agenda.
8243 If you are using the diary only for sexp entries and holidays, it is
8244 faster to not use the above setting, but instead to copy or even move
8245 the entries into an Org file. Org mode evaluates diary-style sexp
8246 entries, and does it faster because there is no overhead for first
8247 creating the diary display. Note that the sexp entries must start at
8248 the left margin, no whitespace is allowed before them. For example,
8249 the following segment of an Org file will be processed and entries
8250 will be made in the agenda:
8257 %%(org-calendar-holiday) ; special function for holiday names
8263 %%(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
8264 %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
8267 @subsubheading Anniversaries from BBDB
8268 @cindex BBDB, anniversaries
8269 @cindex anniversaries, from BBDB
8271 If you are using the Big Brothers Database to store your contacts, you will
8272 very likely prefer to store anniversaries in BBDB rather than in a
8273 separate Org or diary file. Org supports this and will show BBDB
8274 anniversaries as part of the agenda. All you need to do is to add the
8275 following to one of your agenda files:
8282 %%(org-bbdb-anniversaries)
8285 You can then go ahead and define anniversaries for a BBDB record. Basically,
8286 you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
8287 record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
8288 followed by a space and the class of the anniversary (@samp{birthday} or
8289 @samp{wedding}, or a format string). If you omit the class, it will default to
8290 @samp{birthday}. Here are a few examples, the header for the file
8291 @file{org-bbdb.el} contains more detailed information.
8297 2008-04-14 %s released version 6.01 of org mode, %d years ago
8300 After a change to BBDB, or for the first agenda display during an Emacs
8301 session, the agenda display will suffer a short delay as Org updates its
8302 hash with anniversaries. However, from then on things will be very fast---much
8303 faster in fact than a long list of @samp{%%(diary-anniversary)} entries
8304 in an Org or Diary file.
8306 If you would like to see upcoming anniversaries with a bit of forewarning,
8307 you can use the following instead:
8314 %%(org-bbdb-anniversaries-future 3)
8317 That will give you three days' warning: on the anniversary date itself and the
8318 two days prior. The argument is optional: if omitted, it defaults to 7.
8320 @subsubheading Appointment reminders
8321 @cindex @file{appt.el}
8322 @cindex appointment reminders
8326 Org can interact with Emacs appointments notification facility. To add the
8327 appointments of your agenda files, use the command @code{org-agenda-to-appt}.
8328 This command lets you filter through the list of your appointments and add
8329 only those belonging to a specific category or matching a regular expression.
8330 It also reads a @code{APPT_WARNTIME} property which will then override the
8331 value of @code{appt-message-warning-time} for this appointment. See the
8332 docstring for details.
8334 @node Global TODO list
8335 @subsection The global TODO list
8336 @cindex global TODO list
8337 @cindex TODO list, global
8339 The global TODO list contains all unfinished TODO items formatted and
8340 collected into a single place.
8343 @orgcmd{C-c a t,org-todo-list}
8344 Show the global TODO list. This collects the TODO items from all agenda
8345 files (@pxref{Agenda views}) into a single buffer. By default, this lists
8346 items with a state the is not a DONE state. The buffer is in
8347 @code{agenda-mode}, so there are commands to examine and manipulate the TODO
8348 entries directly from that buffer (@pxref{Agenda commands}).
8349 @orgcmd{C-c a T,org-todo-list}
8350 @cindex TODO keyword matching
8351 @vindex org-todo-keywords
8352 Like the above, but allows selection of a specific TODO keyword. You can
8353 also do this by specifying a prefix argument to @kbd{C-c a t}. You are
8354 prompted for a keyword, and you may also specify several keywords by
8355 separating them with @samp{|} as the boolean OR operator. With a numeric
8356 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
8358 The @kbd{r} key in the agenda buffer regenerates it, and you can give
8359 a prefix argument to this command to change the selected TODO keyword,
8360 for example @kbd{3 r}. If you often need a search for a specific
8361 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
8362 Matching specific TODO keywords can also be done as part of a tags
8363 search (@pxref{Tag searches}).
8366 Remote editing of TODO items means that you can change the state of a
8367 TODO entry with a single key press. The commands available in the
8368 TODO list are described in @ref{Agenda commands}.
8370 @cindex sublevels, inclusion into TODO list
8371 Normally the global TODO list simply shows all headlines with TODO
8372 keywords. This list can become very long. There are two ways to keep
8376 @vindex org-agenda-todo-ignore-scheduled
8377 @vindex org-agenda-todo-ignore-deadlines
8378 @vindex org-agenda-todo-ignore-timestamp
8379 @vindex org-agenda-todo-ignore-with-date
8380 Some people view a TODO item that has been @emph{scheduled} for execution or
8381 have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.
8382 Configure the variables @code{org-agenda-todo-ignore-scheduled},
8383 @code{org-agenda-todo-ignore-deadlines},
8384 @code{org-agenda-todo-ignore-timestamp} and/or
8385 @code{org-agenda-todo-ignore-with-date} to exclude such items from the global
8388 @vindex org-agenda-todo-list-sublevels
8389 TODO items may have sublevels to break up the task into subtasks. In
8390 such cases it may be enough to list only the highest level TODO headline
8391 and omit the sublevels from the global list. Configure the variable
8392 @code{org-agenda-todo-list-sublevels} to get this behavior.
8395 @node Matching tags and properties
8396 @subsection Matching tags and properties
8397 @cindex matching, of tags
8398 @cindex matching, of properties
8402 If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
8403 or have properties (@pxref{Properties and columns}), you can select headlines
8404 based on this metadata and collect them into an agenda buffer. The match
8405 syntax described here also applies when creating sparse trees with @kbd{C-c /
8409 @orgcmd{C-c a m,org-tags-view}
8410 Produce a list of all headlines that match a given set of tags. The
8411 command prompts for a selection criterion, which is a boolean logic
8412 expression with tags, like @samp{+work+urgent-withboss} or
8413 @samp{work|home} (@pxref{Tags}). If you often need a specific search,
8414 define a custom command for it (@pxref{Agenda dispatcher}).
8415 @orgcmd{C-c a M,org-tags-view}
8416 @vindex org-tags-match-list-sublevels
8417 @vindex org-agenda-tags-todo-honor-ignore-options
8418 Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
8419 not-DONE state and force checking subitems (see variable
8420 @code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items,
8421 see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching
8422 specific TODO keywords together with a tags match is also possible, see
8426 The commands available in the tags list are described in @ref{Agenda
8429 @subsubheading Match syntax
8431 @cindex Boolean logic, for tag/property searches
8432 A search string can use Boolean operators @samp{&} for @code{AND} and
8433 @samp{|} for @code{OR}@. @samp{&} binds more strongly than @samp{|}.
8434 Parentheses are not implemented. Each element in the search is either a
8435 tag, a regular expression matching tags, or an expression like
8436 @code{PROPERTY OPERATOR VALUE} with a comparison operator, accessing a
8437 property value. Each element may be preceded by @samp{-}, to select
8438 against it, and @samp{+} is syntactic sugar for positive selection. The
8439 @code{AND} operator @samp{&} is optional when @samp{+} or @samp{-} is
8440 present. Here are some examples, using only tags.
8444 Select headlines tagged @samp{:work:}.
8446 Select headlines tagged @samp{:work:} and @samp{:boss:}.
8448 Select headlines tagged @samp{:work:}, but discard those also tagged
8451 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
8452 @item work|laptop+night
8453 Like before, but require the @samp{:laptop:} lines to be tagged also
8457 @cindex regular expressions, with tags search
8458 Instead of a tag, you may also specify a regular expression enclosed in curly
8459 braces. For example,
8460 @samp{work+@{^boss.*@}} matches headlines that contain the tag
8461 @samp{:work:} and any tag @i{starting} with @samp{boss}.
8463 @cindex group tags, as regular expressions
8464 Group tags (@pxref{Tag hierarchy}) are expanded as regular expressions. E.g.,
8465 if @samp{:work:} is a group tag for the group @samp{:work:lab:conf:}, then
8466 searching for @samp{work} will search for @samp{@{\(?:work\|lab\|conf\)@}}
8467 and searching for @samp{-work} will search for all headlines but those with
8468 one of the tags in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}).
8470 @cindex TODO keyword matching, with tags search
8471 @cindex level, require for tags/property match
8472 @cindex category, require for tags/property match
8473 @vindex org-odd-levels-only
8474 You may also test for properties (@pxref{Properties and columns}) at the same
8475 time as matching tags. The properties may be real properties, or special
8476 properties that represent other metadata (@pxref{Special properties}). For
8477 example, the ``property'' @code{TODO} represents the TODO keyword of the
8478 entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of
8481 In addition to the properties mentioned above, @code{LEVEL} represents the
8482 level of an entry. So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all
8483 level three headlines that have the tag @samp{boss} and are @emph{not} marked
8484 with the TODO keyword DONE@. In buffers with @code{org-odd-levels-only} set,
8485 @samp{LEVEL} does not count the number of stars, but @samp{LEVEL=2} will
8486 correspond to 3 stars etc.
8488 Here are more examples:
8491 @item work+TODO="WAITING"
8492 Select @samp{:work:}-tagged TODO lines with the specific TODO
8493 keyword @samp{WAITING}.
8494 @item work+TODO="WAITING"|home+TODO="WAITING"
8495 Waiting tasks both at work and at home.
8498 When matching properties, a number of different operators can be used to test
8499 the value of a property. Here is a complex example:
8502 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \
8503 +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
8507 The type of comparison will depend on how the comparison value is written:
8510 If the comparison value is a plain number, a numerical comparison is done,
8511 and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
8512 @samp{>=}, and @samp{<>}.
8514 If the comparison value is enclosed in double-quotes,
8515 a string comparison is done, and the same operators are allowed.
8517 If the comparison value is enclosed in double-quotes @emph{and} angular
8518 brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
8519 assumed to be date/time specifications in the standard Org way, and the
8520 comparison will be done accordingly. Special values that will be recognized
8521 are @code{"<now>"} for now (including time), and @code{"<today>"}, and
8522 @code{"<tomorrow>"} for these days at 00:00 hours, i.e., without a time
8523 specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
8524 @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
8525 respectively, can be used.
8527 If the comparison value is enclosed
8528 in curly braces, a regexp match is performed, with @samp{=} meaning that the
8529 regexp matches the property value, and @samp{<>} meaning that it does not
8533 So the search string in the example finds entries tagged @samp{:work:} but
8534 not @samp{:boss:}, which also have a priority value @samp{A}, a
8535 @samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
8536 property that is numerically smaller than 2, a @samp{:With:} property that is
8537 matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
8538 on or after October 11, 2008.
8540 You can configure Org mode to use property inheritance during a search, but
8541 beware that this can slow down searches considerably. See @ref{Property
8542 inheritance}, for details.
8544 For backward compatibility, and also for typing speed, there is also a
8545 different way to test TODO states in a search. For this, terminate the
8546 tags/property part of the search string (which may include several terms
8547 connected with @samp{|}) with a @samp{/} and then specify a Boolean
8548 expression just for TODO keywords. The syntax is then similar to that for
8549 tags, but should be applied with care: for example, a positive selection on
8550 several TODO keywords cannot meaningfully be combined with boolean AND@.
8551 However, @emph{negative selection} combined with AND can be meaningful. To
8552 make sure that only lines are checked that actually have any TODO keyword
8553 (resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
8554 part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will
8555 not match TODO keywords in a DONE state. Examples:
8559 Same as @samp{work+TODO="WAITING"}
8560 @item work/!-WAITING-NEXT
8561 Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
8563 @item work/!+WAITING|+NEXT
8564 Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
8569 @subsection Search view
8572 @cindex searching, for text
8574 This agenda view is a general text search facility for Org mode entries.
8575 It is particularly useful to find notes.
8578 @orgcmd{C-c a s,org-search-view}
8579 This is a special search that lets you select entries by matching a substring
8580 or specific words using a boolean logic.
8582 For example, the search string @samp{computer equipment} will find entries
8583 that contain @samp{computer equipment} as a substring. If the two words are
8584 separated by more space or a line break, the search will still match.
8585 Search view can also search for specific keywords in the entry, using Boolean
8586 logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
8587 will search for note entries that contain the keywords @code{computer}
8588 and @code{wifi}, but not the keyword @code{ethernet}, and which are also
8589 not matched by the regular expression @code{8\.11[bg]}, meaning to
8590 exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on
8591 word search, other @samp{+} characters are optional. For more details, see
8592 the docstring of the command @code{org-search-view}.
8594 @vindex org-agenda-text-search-extra-files
8595 Note that in addition to the agenda files, this command will also search
8596 the files listed in @code{org-agenda-text-search-extra-files}.
8598 @node Stuck projects
8599 @subsection Stuck projects
8600 @pindex GTD, Getting Things Done
8602 If you are following a system like David Allen's GTD to organize your
8603 work, one of the ``duties'' you have is a regular review to make sure
8604 that all projects move along. A @emph{stuck} project is a project that
8605 has no defined next actions, so it will never show up in the TODO lists
8606 Org mode produces. During the review, you need to identify such
8607 projects and define next actions for them.
8610 @orgcmd{C-c a #,org-agenda-list-stuck-projects}
8611 List projects that are stuck.
8614 @vindex org-stuck-projects
8615 Customize the variable @code{org-stuck-projects} to define what a stuck
8616 project is and how to find it.
8619 You almost certainly will have to configure this view before it will
8620 work for you. The built-in default assumes that all your projects are
8621 level-2 headlines, and that a project is not stuck if it has at least
8622 one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
8624 Let's assume that you, in your own way of using Org mode, identify
8625 projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
8626 indicate a project that should not be considered yet. Let's further
8627 assume that the TODO keyword DONE marks finished projects, and that NEXT
8628 and TODO indicate next actions. The tag @@SHOP indicates shopping and
8629 is a next action even without the NEXT tag. Finally, if the project
8630 contains the special word IGNORE anywhere, it should not be listed
8631 either. In this case you would start by identifying eligible projects
8632 with a tags/todo match@footnote{@xref{Tag searches}.}
8633 @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, and
8634 IGNORE in the subtree to identify projects that are not stuck. The
8635 correct customization for this is
8638 (setq org-stuck-projects
8639 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
8643 Note that if a project is identified as non-stuck, the subtree of this entry
8644 will still be searched for stuck projects.
8646 @node Presentation and sorting
8647 @section Presentation and sorting
8648 @cindex presentation, of agenda items
8650 @vindex org-agenda-prefix-format
8651 @vindex org-agenda-tags-column
8652 Before displaying items in an agenda view, Org mode visually prepares the
8653 items and sorts them. Each item occupies a single line. The line starts
8654 with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
8655 of the item and other important information. You can customize in which
8656 column tags will be displayed through @code{org-agenda-tags-column}. You can
8657 also customize the prefix using the option @code{org-agenda-prefix-format}.
8658 This prefix is followed by a cleaned-up version of the outline headline
8659 associated with the item.
8662 * Categories:: Not all tasks are equal
8663 * Time-of-day specifications:: How the agenda knows the time
8664 * Sorting agenda items:: The order of things
8665 * Filtering/limiting agenda items:: Dynamically narrow the agenda
8669 @subsection Categories
8673 The category is a broad label assigned to each agenda item. By default, the
8674 category is simply derived from the file name, but you can also specify it
8675 with a special line in the buffer, like this:
8682 @cindex property, CATEGORY
8683 If you would like to have a special CATEGORY for a single entry or a
8684 (sub)tree, give the entry a @code{:CATEGORY:} property with the
8685 special category you want to apply as the value.
8688 The display in the agenda buffer looks best if the category is not
8689 longer than 10 characters.
8692 You can set up icons for category by customizing the
8693 @code{org-agenda-category-icon-alist} variable.
8695 @node Time-of-day specifications
8696 @subsection Time-of-day specifications
8697 @cindex time-of-day specification
8699 Org mode checks each agenda item for a time-of-day specification. The
8700 time can be part of the timestamp that triggered inclusion into the
8701 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
8702 ranges can be specified with two timestamps, like
8704 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
8706 In the headline of the entry itself, a time(range) may also appear as
8707 plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda
8708 integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
8709 specifications in diary entries are recognized as well.
8711 For agenda display, Org mode extracts the time and displays it in a
8712 standard 24 hour format as part of the prefix. The example times in
8713 the previous paragraphs would end up in the agenda like this:
8716 8:30-13:00 Arthur Dent lies in front of the bulldozer
8717 12:45...... Ford Prefect arrives and takes Arthur to the pub
8718 19:00...... The Vogon reads his poem
8719 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8723 If the agenda is in single-day mode, or for the display of today, the
8724 timed entries are embedded in a time grid, like
8727 8:00...... ------------------
8728 8:30-13:00 Arthur Dent lies in front of the bulldozer
8729 10:00...... ------------------
8730 12:00...... ------------------
8731 12:45...... Ford Prefect arrives and takes Arthur to the pub
8732 14:00...... ------------------
8733 16:00...... ------------------
8734 18:00...... ------------------
8735 19:00...... The Vogon reads his poem
8736 20:00...... ------------------
8737 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8740 @vindex org-agenda-use-time-grid
8741 @vindex org-agenda-time-grid
8742 The time grid can be turned on and off with the variable
8743 @code{org-agenda-use-time-grid}, and can be configured with
8744 @code{org-agenda-time-grid}.
8746 @node Sorting agenda items
8747 @subsection Sorting agenda items
8748 @cindex sorting, of agenda items
8749 @cindex priorities, of agenda items
8750 Before being inserted into a view, the items are sorted. How this is
8751 done depends on the type of view.
8754 @vindex org-agenda-files
8755 For the daily/weekly agenda, the items for each day are sorted. The
8756 default order is to first collect all items containing an explicit
8757 time-of-day specification. These entries will be shown at the beginning
8758 of the list, as a @emph{schedule} for the day. After that, items remain
8759 grouped in categories, in the sequence given by @code{org-agenda-files}.
8760 Within each category, items are sorted by priority (@pxref{Priorities}),
8761 which is composed of the base priority (2000 for priority @samp{A}, 1000
8762 for @samp{B}, and 0 for @samp{C}), plus additional increments for
8763 overdue scheduled or deadline items.
8765 For the TODO list, items remain in the order of categories, but within
8766 each category, sorting takes place according to priority
8767 (@pxref{Priorities}). The priority used for sorting derives from the
8768 priority cookie, with additions depending on how close an item is to its due
8771 For tags matches, items are not sorted at all, but just appear in the
8772 sequence in which they are found in the agenda files.
8775 @vindex org-agenda-sorting-strategy
8776 Sorting can be customized using the variable
8777 @code{org-agenda-sorting-strategy}, and may also include criteria based on
8778 the estimated effort of an entry (@pxref{Effort estimates}).
8780 @node Filtering/limiting agenda items
8781 @subsection Filtering/limiting agenda items
8783 Agenda built-in or customized commands are statically defined. Agenda
8784 filters and limits provide two ways of dynamically narrowing down the list of
8785 agenda entries: @emph{filters} and @emph{limits}. Filters only act on the
8786 display of the items, while limits take effect before the list of agenda
8787 entries is built. Filters are more often used interactively, while limits are
8788 mostly useful when defined as local variables within custom agenda commands.
8790 @subsubheading Filtering in the agenda
8791 @cindex filtering, by tag, category, top headline and effort, in agenda
8792 @cindex tag filtering, in agenda
8793 @cindex category filtering, in agenda
8794 @cindex top headline filtering, in agenda
8795 @cindex effort filtering, in agenda
8796 @cindex query editing, in agenda
8799 @orgcmd{/,org-agenda-filter-by-tag}
8800 @vindex org-agenda-tag-filter-preset
8801 Filter the agenda view with respect to a tag and/or effort estimates. The
8802 difference between this and a custom agenda command is that filtering is very
8803 fast, so that you can switch quickly between different filters without having
8804 to recreate the agenda.@footnote{Custom commands can preset a filter by
8805 binding the variable @code{org-agenda-tag-filter-preset} as an option. This
8806 filter will then be applied to the view and persist as a basic filter through
8807 refreshes and more secondary filtering. The filter is a global property of
8808 the entire agenda view---in a block agenda, you should only set this in the
8809 global options section, not in the section of an individual block.}
8811 You will be prompted for a tag selection letter; @key{SPC} will mean any tag
8812 at all. Pressing @key{TAB} at that prompt will offer use completion to
8813 select a tag (including any tags that do not have a selection character).
8814 The command then hides all entries that do not contain or inherit this tag.
8815 When called with prefix arg, remove the entries that @emph{do} have the tag.
8816 A second @kbd{/} at the prompt will turn off the filter and unhide any hidden
8817 entries. Pressing @kbd{+} or @kbd{-} switches between filtering and
8818 excluding the next tag.
8820 Org also supports automatic, context-aware tag filtering. If the variable
8821 @code{org-agenda-auto-exclude-function} is set to a user-defined function,
8822 that function can decide which tags should be excluded from the agenda
8823 automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
8824 as a sub-option key and runs the auto exclusion logic. For example, let's
8825 say you use a @code{Net} tag to identify tasks which need network access, an
8826 @code{Errand} tag for errands in town, and a @code{Call} tag for making phone
8827 calls. You could auto-exclude these tags based on the availability of the
8828 Internet, and outside of business hours, with something like this:
8832 (defun org-my-auto-exclude-function (tag)
8834 ((string= tag "Net")
8835 (/= 0 (call-process "/sbin/ping" nil nil nil
8836 "-c1" "-q" "-t1" "mail.gnu.org")))
8837 ((or (string= tag "Errand") (string= tag "Call"))
8838 (let ((hour (nth 2 (decode-time))))
8839 (or (< hour 8) (> hour 21)))))
8842 (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
8853 @item @r{in} search view
8854 add new search words (@kbd{[} and @kbd{]}) or new regular expressions
8855 (@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
8856 add a positive search term prefixed by @samp{+}, indicating that this search
8857 term @i{must} occur/match in the entry. The closing bracket/brace will add a
8858 negative search term which @i{must not} occur/match in the entry for it to be
8862 @orgcmd{<,org-agenda-filter-by-category}
8863 @vindex org-agenda-category-filter-preset
8865 Filter the current agenda view with respect to the category of the item at
8866 point. Pressing @code{<} another time will remove this filter. When called
8867 with a prefix argument exclude the category of the item at point from the
8870 You can add a filter preset in custom agenda commands through the option
8871 @code{org-agenda-category-filter-preset}. @xref{Setting options}.
8873 @orgcmd{^,org-agenda-filter-by-top-headline}
8874 Filter the current agenda view and only display the siblings and the parent
8875 headline of the one at point.
8877 @orgcmd{=,org-agenda-filter-by-regexp}
8878 @vindex org-agenda-regexp-filter-preset
8880 Filter the agenda view by a regular expression: only show agenda entries
8881 matching the regular expression the user entered. When called with a prefix
8882 argument, it will filter @emph{out} entries matching the regexp. With two
8883 universal prefix arguments, it will remove all the regexp filters, which can
8886 You can add a filter preset in custom agenda commands through the option
8887 @code{org-agenda-regexp-filter-preset}. @xref{Setting options}.
8889 @orgcmd{_,org-agenda-filter-by-effort}
8890 @vindex org-agenda-effort-filter-preset
8891 @vindex org-sort-agenda-noeffort-is-high
8892 Filter the agenda view with respect to effort estimates.
8893 You first need to set up allowed efforts globally, for example
8895 (setq org-global-properties
8896 '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
8898 You can then filter for an effort by first typing an operator, one of
8899 @kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
8900 estimate in your array of allowed values, where @kbd{0} means the 10th value.
8901 The filter will then restrict to entries with effort smaller-or-equal, equal,
8902 or larger-or-equal than the selected value. For application of the operator,
8903 entries without a defined effort will be treated according to the value of
8904 @code{org-sort-agenda-noeffort-is-high}.
8906 When called with a prefix argument, it will remove entries matching the
8907 condition. With two universal prefix arguments, it will clear effort
8908 filters, which can be accumulated.
8910 You can add a filter preset in custom agenda commands through the option
8911 @code{org-agenda-effort-filter-preset}. @xref{Setting options}.
8913 @orgcmd{|,org-agenda-filter-remove-all}
8914 Remove all filters in the current agenda view.
8917 @subsubheading Setting limits for the agenda
8918 @cindex limits, in agenda
8919 @vindex org-agenda-max-entries
8920 @vindex org-agenda-max-effort
8921 @vindex org-agenda-max-todos
8922 @vindex org-agenda-max-tags
8924 Here is a list of options that you can set, either globally, or locally in
8925 your custom agenda views (@pxref{Custom agenda views}).
8928 @item org-agenda-max-entries
8929 Limit the number of entries.
8930 @item org-agenda-max-effort
8931 Limit the duration of accumulated efforts (as minutes).
8932 @item org-agenda-max-todos
8933 Limit the number of entries with TODO keywords.
8934 @item org-agenda-max-tags
8935 Limit the number of tagged entries.
8938 When set to a positive integer, each option will exclude entries from other
8939 categories: for example, @code{(setq org-agenda-max-effort 100)} will limit
8940 the agenda to 100 minutes of effort and exclude any entry that has no effort
8941 property. If you want to include entries with no effort property, use a
8942 negative value for @code{org-agenda-max-effort}.
8944 One useful setup is to use @code{org-agenda-max-entries} locally in a custom
8945 command. For example, this custom command will display the next five entries
8946 with a @code{NEXT} TODO keyword.
8949 (setq org-agenda-custom-commands
8951 ((org-agenda-max-entries 5)))))
8954 Once you mark one of these five entry as @code{DONE}, rebuilding the agenda
8955 will again the next five entries again, including the first entry that was
8958 You can also dynamically set temporary limits, which will be lost when
8959 rebuilding the agenda:
8962 @orgcmd{~,org-agenda-limit-interactively}
8963 This prompts for the type of limit to apply and its value.
8966 @node Agenda commands
8967 @section Commands in the agenda buffer
8968 @cindex commands, in agenda buffer
8970 Entries in the agenda buffer are linked back to the Org file or diary
8971 file where they originate. You are not allowed to edit the agenda
8972 buffer itself, but commands are provided to show and jump to the
8973 original entry location, and to edit the Org files ``remotely'' from
8974 the agenda buffer. In this way, all information is stored only once,
8975 removing the risk that your agenda and note files may diverge.
8977 Some commands can be executed with mouse clicks on agenda lines. For
8978 the other commands, the cursor needs to be in the desired line.
8981 @tsubheading{Motion}
8982 @cindex motion commands in agenda
8983 @orgcmd{n,org-agenda-next-line}
8984 Next line (same as @key{down} and @kbd{C-n}).
8985 @orgcmd{p,org-agenda-previous-line}
8986 Previous line (same as @key{up} and @kbd{C-p}).
8987 @orgcmd{N,org-agenda-next-item}
8988 Next item: same as next line, but only consider items.
8989 @orgcmd{P,org-agenda-previous-item}
8990 Previous item: same as previous line, but only consider items.
8991 @tsubheading{View/Go to Org file}
8992 @orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
8993 Display the original location of the item in another window. With prefix
8994 arg, make sure that drawers stay folded.
8996 @orgcmd{L,org-agenda-recenter}
8997 Display original location and recenter that window.
8999 @orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
9000 Go to the original location of the item in another window.
9002 @orgcmd{@key{RET},org-agenda-switch-to}
9003 Go to the original location of the item and delete other windows.
9005 @orgcmd{F,org-agenda-follow-mode}
9006 @vindex org-agenda-start-with-follow-mode
9007 Toggle Follow mode. In Follow mode, as you move the cursor through
9008 the agenda buffer, the other window always shows the corresponding
9009 location in the Org file. The initial setting for this mode in new
9010 agenda buffers can be set with the variable
9011 @code{org-agenda-start-with-follow-mode}.
9013 @orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
9014 Display the entire subtree of the current item in an indirect buffer. With a
9015 numeric prefix argument N, go up to level N and then take that tree. If N is
9016 negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the
9017 previously used indirect buffer.
9019 @orgcmd{C-c C-o,org-agenda-open-link}
9020 Follow a link in the entry. This will offer a selection of any links in the
9021 text belonging to the referenced Org node. If there is only one link, it
9022 will be followed without a selection prompt.
9024 @tsubheading{Change display}
9025 @cindex display changing, in agenda
9028 Interactively select another agenda view and append it to the current view.
9032 Delete other windows.
9034 @orgcmdkskc{v d,d,org-agenda-day-view}
9035 @xorgcmdkskc{v w,w,org-agenda-week-view}
9036 @xorgcmd{v t,org-agenda-fortnight-view}
9037 @xorgcmd{v m,org-agenda-month-view}
9038 @xorgcmd{v y,org-agenda-year-view}
9039 @xorgcmd{v SPC,org-agenda-reset-view}
9040 @vindex org-agenda-span
9041 Switch to day/week/month/year view. When switching to day or week view, this
9042 setting becomes the default for subsequent agenda refreshes. Since month and
9043 year views are slow to create, they do not become the default. A numeric
9044 prefix argument may be used to jump directly to a specific day of the year,
9045 ISO week, month, or year, respectively. For example, @kbd{32 d} jumps to
9046 February 1st, @kbd{9 w} to ISO week number 9. When setting day, week, or
9047 month view, a year may be encoded in the prefix argument as well. For
9048 example, @kbd{200712 w} will jump to week 12 in 2007. If such a year
9049 specification has only one or two digits, it will be mapped to the interval
9050 1938--2037. @kbd{v @key{SPC}} will reset to what is set in
9051 @code{org-agenda-span}.
9053 @orgcmd{f,org-agenda-later}
9054 Go forward in time to display the following @code{org-agenda-current-span} days.
9055 For example, if the display covers a week, switch to the following week.
9056 With prefix arg, go forward that many times @code{org-agenda-current-span} days.
9058 @orgcmd{b,org-agenda-earlier}
9059 Go backward in time to display earlier dates.
9061 @orgcmd{.,org-agenda-goto-today}
9064 @orgcmd{j,org-agenda-goto-date}
9065 Prompt for a date and go there.
9067 @orgcmd{J,org-agenda-clock-goto}
9068 Go to the currently clocked-in task @i{in the agenda buffer}.
9070 @orgcmd{D,org-agenda-toggle-diary}
9071 Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}.
9073 @orgcmdkskc{v l,l,org-agenda-log-mode}
9075 @vindex org-log-done
9076 @vindex org-agenda-log-mode-items
9077 Toggle Logbook mode. In Logbook mode, entries that were marked DONE while
9078 logging was on (variable @code{org-log-done}) are shown in the agenda, as are
9079 entries that have been clocked on that day. You can configure the entry
9080 types that should be included in log mode using the variable
9081 @code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show
9082 all possible logbook entries, including state changes. When called with two
9083 prefix arguments @kbd{C-u C-u}, show only logging information, nothing else.
9084 @kbd{v L} is equivalent to @kbd{C-u v l}.
9086 @orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
9087 Include inactive timestamps into the current view. Only for weekly/daily
9090 @orgcmd{v a,org-agenda-archives-mode}
9091 @xorgcmd{v A,org-agenda-archives-mode 'files}
9092 @cindex Archives mode
9093 Toggle Archives mode. In Archives mode, trees that are marked
9094 @code{ARCHIVED} are also scanned when producing the agenda. When you use the
9095 capital @kbd{A}, even all archive files are included. To exit archives mode,
9096 press @kbd{v a} again.
9098 @orgcmdkskc{v R,R,org-agenda-clockreport-mode}
9099 @vindex org-agenda-start-with-clockreport-mode
9100 @vindex org-clock-report-include-clocking-task
9101 Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will
9102 always show a table with the clocked times for the time span and file scope
9103 covered by the current agenda view. The initial setting for this mode in new
9104 agenda buffers can be set with the variable
9105 @code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
9106 when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
9107 contributions from entries that are hidden by agenda filtering@footnote{Only
9108 tags filtering will be respected here, effort filtering is ignored.}. See
9109 also the variable @code{org-clock-report-include-clocking-task}.
9112 @vindex org-agenda-clock-consistency-checks
9113 Show overlapping clock entries, clocking gaps, and other clocking problems in
9114 the current agenda range. You can then visit clocking lines and fix them
9115 manually. See the variable @code{org-agenda-clock-consistency-checks} for
9116 information on how to customize the definition of what constituted a clocking
9117 problem. To return to normal agenda display, press @kbd{l} to exit Logbook
9120 @orgcmdkskc{v E,E,org-agenda-entry-text-mode}
9121 @vindex org-agenda-start-with-entry-text-mode
9122 @vindex org-agenda-entry-text-maxlines
9123 Toggle entry text mode. In entry text mode, a number of lines from the Org
9124 outline node referenced by an agenda line will be displayed below the line.
9125 The maximum number of lines is given by the variable
9126 @code{org-agenda-entry-text-maxlines}. Calling this command with a numeric
9127 prefix argument will temporarily modify that number to the prefix value.
9129 @orgcmd{G,org-agenda-toggle-time-grid}
9130 @vindex org-agenda-use-time-grid
9131 @vindex org-agenda-time-grid
9132 Toggle the time grid on and off. See also the variables
9133 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
9135 @orgcmd{r,org-agenda-redo}
9136 Recreate the agenda buffer, for example to reflect the changes after
9137 modification of the timestamps of items with @kbd{S-@key{left}} and
9138 @kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix
9139 argument is interpreted to create a selective list for a specific TODO
9141 @orgcmd{g,org-agenda-redo}
9144 @orgcmdkskc{C-x C-s,s,org-save-all-org-buffers}
9145 Save all Org buffers in the current Emacs session, and also the locations of
9148 @orgcmd{C-c C-x C-c,org-agenda-columns}
9149 @vindex org-columns-default-format
9150 Invoke column view (@pxref{Column view}) in the agenda buffer. The column
9151 view format is taken from the entry at point, or (if there is no entry at
9152 point), from the first entry in the agenda view. So whatever the format for
9153 that entry would be in the original buffer (taken from a property, from a
9154 @code{#+COLUMNS} line, or from the default variable
9155 @code{org-columns-default-format}), will be used in the agenda.
9157 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
9158 Remove the restriction lock on the agenda, if it is currently restricted to a
9159 file or subtree (@pxref{Agenda files}).
9161 @tsubheading{Secondary filtering and query editing}
9163 For a detailed description of these commands, @pxref{Filtering/limiting
9166 @orgcmd{/,org-agenda-filter-by-tag}
9167 Filter the agenda view with respect to a tag and/or effort estimates.
9169 @orgcmd{<,org-agenda-filter-by-category}
9170 Filter the current agenda view with respect to the category of the item at
9173 @orgcmd{^,org-agenda-filter-by-top-headline}
9174 Filter the current agenda view and only display the siblings and the parent
9175 headline of the one at point.
9177 @orgcmd{=,org-agenda-filter-by-regexp}
9178 Filter the agenda view by a regular expression.
9180 @orgcmd{_,org-agenda-filter-by-effort}
9181 Filter the agenda view with respect to effort estimates.
9183 @orgcmd{|,org-agenda-filter-remove-all}
9184 Remove all filters in the current agenda view.
9186 @tsubheading{Remote editing}
9187 @cindex remote editing, from agenda
9192 @cindex undoing remote-editing events
9193 @cindex remote editing, undo
9194 @orgcmd{C-_,org-agenda-undo}
9195 Undo a change due to a remote editing command. The change is undone
9196 both in the agenda buffer and in the remote buffer.
9198 @orgcmd{t,org-agenda-todo}
9199 Change the TODO state of the item, both in the agenda and in the
9202 @orgcmd{C-S-@key{right},org-agenda-todo-nextset}
9203 @orgcmd{C-S-@key{left},org-agenda-todo-previousset}
9204 Switch to the next/previous set of TODO keywords.
9206 @orgcmd{C-k,org-agenda-kill}
9207 @vindex org-agenda-confirm-kill
9208 Delete the current agenda item along with the entire subtree belonging
9209 to it in the original Org file. If the text to be deleted remotely
9210 is longer than one line, the kill needs to be confirmed by the user. See
9211 variable @code{org-agenda-confirm-kill}.
9213 @orgcmd{C-c C-w,org-agenda-refile}
9214 Refile the entry at point.
9216 @orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation}
9217 @vindex org-archive-default-command
9218 Archive the subtree corresponding to the entry at point using the default
9219 archiving command set in @code{org-archive-default-command}. When using the
9220 @code{a} key, confirmation will be required.
9222 @orgcmd{C-c C-x a,org-agenda-toggle-archive-tag}
9223 Toggle the ARCHIVE tag for the current headline.
9225 @orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling}
9226 Move the subtree corresponding to the current entry to its @emph{archive
9229 @orgcmdkskc{C-c C-x C-s,$,org-agenda-archive}
9230 Archive the subtree corresponding to the current headline. This means the
9231 entry will be moved to the configured archive location, most likely a
9234 @orgcmd{T,org-agenda-show-tags}
9235 @vindex org-agenda-show-inherited-tags
9236 Show all tags associated with the current item. This is useful if you have
9237 turned off @code{org-agenda-show-inherited-tags}, but still want to see all
9238 tags of a headline occasionally.
9240 @orgcmd{:,org-agenda-set-tags}
9241 Set tags for the current headline. If there is an active region in the
9242 agenda, change a tag for all headings in the region.
9246 Set the priority for the current item (@command{org-agenda-priority}).
9247 Org mode prompts for the priority character. If you reply with @key{SPC},
9248 the priority cookie is removed from the entry.
9250 @orgcmd{P,org-agenda-show-priority}
9251 Display weighted priority of current item.
9253 @orgcmdkkc{+,S-@key{up},org-agenda-priority-up}
9254 Increase the priority of the current item. The priority is changed in
9255 the original buffer, but the agenda is not resorted. Use the @kbd{r}
9258 @orgcmdkkc{-,S-@key{down},org-agenda-priority-down}
9259 Decrease the priority of the current item.
9261 @orgcmdkkc{z,C-c C-z,org-agenda-add-note}
9262 @vindex org-log-into-drawer
9263 Add a note to the entry. This note will be recorded, and then filed to the
9264 same location where state change notes are put. Depending on
9265 @code{org-log-into-drawer}, this may be inside a drawer.
9267 @orgcmd{C-c C-a,org-attach}
9268 Dispatcher for all command related to attachments.
9270 @orgcmd{C-c C-s,org-agenda-schedule}
9271 Schedule this item. With prefix arg remove the scheduling timestamp
9273 @orgcmd{C-c C-d,org-agenda-deadline}
9274 Set a deadline for this item. With prefix arg remove the deadline.
9276 @orgcmd{S-@key{right},org-agenda-do-date-later}
9277 Change the timestamp associated with the current line by one day into the
9278 future. If the date is in the past, the first call to this command will move
9280 With a numeric prefix argument, change it by that many days. For example,
9281 @kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix,
9282 change the time by one hour. If you immediately repeat the command, it will
9283 continue to change hours even without the prefix arg. With a double @kbd{C-u
9284 C-u} prefix, do the same for changing minutes.@*
9285 The stamp is changed in the original Org file, but the change is not directly
9286 reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
9288 @orgcmd{S-@key{left},org-agenda-do-date-earlier}
9289 Change the timestamp associated with the current line by one day
9292 @orgcmd{>,org-agenda-date-prompt}
9293 Change the timestamp associated with the current line. The key @kbd{>} has
9294 been chosen, because it is the same as @kbd{S-.} on my keyboard.
9296 @orgcmd{I,org-agenda-clock-in}
9297 Start the clock on the current item. If a clock is running already, it
9300 @orgcmd{O,org-agenda-clock-out}
9301 Stop the previously started clock.
9303 @orgcmd{X,org-agenda-clock-cancel}
9304 Cancel the currently running clock.
9306 @orgcmd{J,org-agenda-clock-goto}
9307 Jump to the running clock in another window.
9309 @orgcmd{k,org-agenda-capture}
9310 Like @code{org-capture}, but use the date at point as the default date for
9311 the capture template. See @code{org-capture-use-agenda-date} to make this
9312 the default behavior of @code{org-capture}.
9313 @cindex capturing, from agenda
9314 @vindex org-capture-use-agenda-date
9316 @tsubheading{Dragging agenda lines forward/backward}
9317 @cindex dragging, agenda lines
9319 @orgcmd{M-<up>,org-agenda-drag-line-backward}
9320 Drag the line at point backward one line@footnote{Moving agenda lines does
9321 not persist after an agenda refresh and does not modify the contributing
9322 @file{.org} files}. With a numeric prefix argument, drag backward by that
9325 @orgcmd{M-<down>,org-agenda-drag-line-forward}
9326 Drag the line at point forward one line. With a numeric prefix argument,
9327 drag forward by that many lines.
9329 @tsubheading{Bulk remote editing selected entries}
9330 @cindex remote editing, bulk, from agenda
9331 @vindex org-agenda-bulk-custom-functions
9333 @orgcmd{m,org-agenda-bulk-mark}
9334 Mark the entry at point for bulk action. If there is an active region in the
9335 agenda, mark the entries in the region. With numeric prefix argument, mark
9336 that many successive entries.
9338 @orgcmd{*,org-agenda-bulk-mark-all}
9339 Mark all visible agenda entries for bulk action.
9341 @orgcmd{u,org-agenda-bulk-unmark}
9342 Unmark entry at point for bulk action.
9344 @orgcmd{U,org-agenda-bulk-remove-all-marks}
9345 Unmark all marked entries for bulk action.
9347 @orgcmd{M-m,org-agenda-bulk-toggle}
9348 Toggle mark of the entry at point for bulk action.
9350 @orgcmd{M-*,org-agenda-bulk-toggle-all}
9351 Toggle marks of all visible entries for bulk action.
9353 @orgcmd{%,org-agenda-bulk-mark-regexp}
9354 Mark entries matching a regular expression for bulk action.
9356 @orgcmd{B,org-agenda-bulk-action}
9357 Bulk action: act on all marked entries in the agenda. This will prompt for
9358 another key to select the action to be applied. The prefix arg to @kbd{B}
9359 will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove
9360 these special timestamps. By default, marks are removed after the bulk. If
9361 you want them to persist, set @code{org-agenda-persistent-marks} to @code{t}
9362 or hit @kbd{p} at the prompt.
9366 Toggle persistent marks.
9368 Archive all selected entries.
9370 Archive entries by moving them to their respective archive siblings.
9372 Change TODO state. This prompts for a single TODO keyword and changes the
9373 state of all selected entries, bypassing blocking and suppressing logging
9374 notes (but not timestamps).
9376 Add a tag to all selected entries.
9378 Remove a tag from all selected entries.
9380 Schedule all items to a new date. To shift existing schedule dates by a
9381 fixed number of days, use something starting with double plus at the prompt,
9382 for example @samp{++8d} or @samp{++2w}.
9384 Set deadline to a specific date.
9386 Prompt for a single refile target and move all entries. The entries will no
9387 longer be in the agenda; refresh (@kbd{g}) to bring them back.
9389 Reschedule randomly into the coming N days. N will be prompted for. With
9390 prefix arg (@kbd{C-u B S}), scatter only across weekdays.
9392 Apply a function@footnote{You can also create persistent custom functions
9393 through @code{org-agenda-bulk-custom-functions}.} to marked entries. For
9394 example, the function below sets the CATEGORY property of the entries to web.
9398 (defun set-category ()
9400 (let* ((marker (or (org-get-at-bol 'org-hd-marker)
9401 (org-agenda-error)))
9402 (buffer (marker-buffer marker)))
9403 (with-current-buffer buffer
9408 (org-back-to-heading t)
9409 (org-set-property "CATEGORY" "web"))))))
9414 @tsubheading{Calendar commands}
9415 @cindex calendar commands, from agenda
9417 @orgcmd{c,org-agenda-goto-calendar}
9418 Open the Emacs calendar and move to the date at the agenda cursor.
9420 @orgcmd{c,org-calendar-goto-agenda}
9421 When in the calendar, compute and show the Org mode agenda for the
9424 @cindex diary entries, creating from agenda
9425 @orgcmd{i,org-agenda-diary-entry}
9426 @vindex org-agenda-diary-file
9427 Insert a new entry into the diary, using the date at the cursor and (for
9428 block entries) the date at the mark. This will add to the Emacs diary
9429 file@footnote{This file is parsed for the agenda when
9430 @code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
9431 command in the calendar. The diary file will pop up in another window, where
9432 you can add the entry.
9434 If you configure @code{org-agenda-diary-file} to point to an Org mode file,
9435 Org will create entries (in Org mode syntax) in that file instead. Most
9436 entries will be stored in a date-based outline tree that will later make it
9437 easy to archive appointments from previous months/years. The tree will be
9438 built under an entry with a @code{DATE_TREE} property, or else with years as
9439 top-level entries. Emacs will prompt you for the entry text---if you specify
9440 it, the entry will be created in @code{org-agenda-diary-file} without further
9441 interaction. If you directly press @key{RET} at the prompt without typing
9442 text, the target file will be shown in another window for you to finish the
9443 entry there. See also the @kbd{k r} command.
9445 @orgcmd{M,org-agenda-phases-of-moon}
9446 Show the phases of the moon for the three months around current date.
9448 @orgcmd{S,org-agenda-sunrise-sunset}
9449 Show sunrise and sunset times. The geographical location must be set
9450 with calendar variables, see the documentation for the Emacs calendar.
9452 @orgcmd{C,org-agenda-convert-date}
9453 Convert the date at cursor into many other cultural and historic
9456 @orgcmd{H,org-agenda-holidays}
9457 Show holidays for three months around the cursor date.
9459 @item M-x org-icalendar-combine-agenda-files RET
9460 Export a single iCalendar file containing entries from all agenda files.
9461 This is a globally available command, and also available in the agenda menu.
9463 @tsubheading{Exporting to a file}
9464 @orgcmd{C-x C-w,org-agenda-write}
9465 @cindex exporting agenda views
9466 @cindex agenda views, exporting
9467 @vindex org-agenda-exporter-settings
9468 Write the agenda view to a file. Depending on the extension of the selected
9469 file name, the view will be exported as HTML (@file{.html} or @file{.htm}),
9470 Postscript (@file{.ps}), PDF (@file{.pdf}), Org (@file{.org}) and plain text
9471 (any other extension). When exporting to Org, only the body of original
9472 headlines are exported, not subtrees or inherited tags. When called with a
9473 @kbd{C-u} prefix argument, immediately open the newly created file. Use the
9474 variable @code{org-agenda-exporter-settings} to set options for
9475 @file{ps-print} and for @file{htmlize} to be used during export.
9477 @tsubheading{Quit and Exit}
9478 @orgcmd{q,org-agenda-quit}
9479 Quit agenda, remove the agenda buffer.
9481 @cindex agenda files, removing buffers
9482 @orgcmd{x,org-agenda-exit}
9483 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
9484 for the compilation of the agenda. Buffers created by the user to
9485 visit Org files will not be removed.
9489 @node Custom agenda views
9490 @section Custom agenda views
9491 @cindex custom agenda views
9492 @cindex agenda views, custom
9494 Custom agenda commands serve two purposes: to store and quickly access
9495 frequently used TODO and tags searches, and to create special composite
9496 agenda buffers. Custom agenda commands will be accessible through the
9497 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
9500 * Storing searches:: Type once, use often
9501 * Block agenda:: All the stuff you need in a single buffer
9502 * Setting options:: Changing the rules
9505 @node Storing searches
9506 @subsection Storing searches
9508 The first application of custom searches is the definition of keyboard
9509 shortcuts for frequently used searches, either creating an agenda
9510 buffer, or a sparse tree (the latter covering of course only the current
9513 @vindex org-agenda-custom-commands
9514 @cindex agenda views, main example
9515 @cindex agenda, as an agenda views
9516 @cindex agenda*, as an agenda views
9517 @cindex tags, as an agenda view
9518 @cindex todo, as an agenda view
9524 Custom commands are configured in the variable
9525 @code{org-agenda-custom-commands}. You can customize this variable, for
9526 example by pressing @kbd{C-c a C}. You can also directly set it with Emacs
9527 Lisp in the Emacs init file. The following example contains all valid agenda
9532 (setq org-agenda-custom-commands
9535 ("w" todo "WAITING")
9536 ("W" todo-tree "WAITING")
9537 ("u" tags "+boss-urgent")
9538 ("v" tags-todo "+boss-urgent")
9539 ("U" tags-tree "+boss-urgent")
9540 ("f" occur-tree "\\<FIXME\\>")
9541 ("h" . "HOME+Name tags searches") ; description for "h" prefix
9542 ("hl" tags "+home+Lisa")
9543 ("hp" tags "+home+Peter")
9544 ("hk" tags "+home+Kim")))
9549 The initial string in each entry defines the keys you have to press
9550 after the dispatcher command @kbd{C-c a} in order to access the command.
9551 Usually this will be just a single character, but if you have many
9552 similar commands, you can also define two-letter combinations where the
9553 first character is the same in several combinations and serves as a
9554 prefix key@footnote{You can provide a description for a prefix key by
9555 inserting a cons cell with the prefix and the description.}. The second
9556 parameter is the search type, followed by the string or regular
9557 expression to be used for the matching. The example above will
9562 as a global search for agenda entries planned@footnote{@emph{Planned} means
9563 here that these entries have some planning information attached to them, like
9564 a time-stamp, a scheduled or a deadline string. See
9565 @code{org-agenda-entry-types} on how to set what planning information will be
9566 taken into account.} this week/day.
9568 as a global search for agenda entries planned this week/day, but only those
9569 with an hour specification like @code{[h]h:mm}---think of them as appointments.
9571 as a global search for TODO entries with @samp{WAITING} as the TODO
9574 as the same search, but only in the current buffer and displaying the
9575 results as a sparse tree
9577 as a global tags search for headlines marked @samp{:boss:} but not
9580 as the same search as @kbd{C-c a u}, but limiting the search to
9581 headlines that are also TODO items
9583 as the same search as @kbd{C-c a u}, but only in the current buffer and
9584 displaying the result as a sparse tree
9586 to create a sparse tree (again: current buffer only) with all entries
9587 containing the word @samp{FIXME}
9589 as a prefix command for a HOME tags search where you have to press an
9590 additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,
9591 Peter, or Kim) as additional tag to match.
9594 Note that the @code{*-tree} agenda views need to be called from an
9595 Org buffer as they operate on the current buffer only.
9598 @subsection Block agenda
9599 @cindex block agenda
9600 @cindex agenda, with block views
9602 Another possibility is the construction of agenda views that comprise
9603 the results of @emph{several} commands, each of which creates a block in
9604 the agenda buffer. The available commands include @code{agenda} for the
9605 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
9606 for the global TODO list (as constructed with @kbd{C-c a t}), and the
9607 matching commands discussed above: @code{todo}, @code{tags}, and
9608 @code{tags-todo}. Here are two examples:
9612 (setq org-agenda-custom-commands
9613 '(("h" "Agenda and Home-related tasks"
9617 ("o" "Agenda and Office-related tasks"
9625 This will define @kbd{C-c a h} to create a multi-block view for stuff
9626 you need to attend to at home. The resulting agenda buffer will contain
9627 your agenda for the current week, all TODO items that carry the tag
9628 @samp{home}, and also all lines tagged with @samp{garden}. Finally the
9629 command @kbd{C-c a o} provides a similar view for office tasks.
9631 @node Setting options
9632 @subsection Setting options for custom commands
9633 @cindex options, for custom agenda views
9635 @vindex org-agenda-custom-commands
9636 Org mode contains a number of variables regulating agenda construction
9637 and display. The global variables define the behavior for all agenda
9638 commands, including the custom commands. However, if you want to change
9639 some settings just for a single custom view, you can do so. Setting
9640 options requires inserting a list of variable names and values at the
9641 right spot in @code{org-agenda-custom-commands}. For example:
9645 (setq org-agenda-custom-commands
9646 '(("w" todo "WAITING"
9647 ((org-agenda-sorting-strategy '(priority-down))
9648 (org-agenda-prefix-format " Mixed: ")))
9649 ("U" tags-tree "+boss-urgent"
9650 ((org-show-context-detail 'minimal)))
9652 ((org-agenda-files '("~org/notes.org"))
9653 (org-agenda-text-search-extra-files nil)))))
9658 Now the @kbd{C-c a w} command will sort the collected entries only by
9659 priority, and the prefix format is modified to just say @samp{ Mixed: }
9660 instead of giving the category of the entry. The sparse tags tree of
9661 @kbd{C-c a U} will now turn out ultra-compact, because neither the
9662 headline hierarchy above the match, nor the headline following the match
9663 will be shown. The command @kbd{C-c a N} will do a text search limited
9664 to only a single file.
9666 @vindex org-agenda-custom-commands
9667 For command sets creating a block agenda,
9668 @code{org-agenda-custom-commands} has two separate spots for setting
9669 options. You can add options that should be valid for just a single
9670 command in the set, and options that should be valid for all commands in
9671 the set. The former are just added to the command entry; the latter
9672 must come after the list of command entries. Going back to the block
9673 agenda example (@pxref{Block agenda}), let's change the sorting strategy
9674 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
9675 the results for GARDEN tags query in the opposite order,
9676 @code{priority-up}. This would look like this:
9680 (setq org-agenda-custom-commands
9681 '(("h" "Agenda and Home-related tasks"
9685 ((org-agenda-sorting-strategy '(priority-up)))))
9686 ((org-agenda-sorting-strategy '(priority-down))))
9687 ("o" "Agenda and Office-related tasks"
9694 As you see, the values and parentheses setting is a little complex.
9695 When in doubt, use the customize interface to set this variable---it
9696 fully supports its structure. Just one caveat: when setting options in
9697 this interface, the @emph{values} are just Lisp expressions. So if the
9698 value is a string, you need to add the double-quotes around the value
9701 @vindex org-agenda-custom-commands-contexts
9702 To control whether an agenda command should be accessible from a specific
9703 context, you can customize @code{org-agenda-custom-commands-contexts}. Let's
9704 say for example that you have an agenda command @code{"o"} displaying a view
9705 that you only need when reading emails. Then you would configure this option
9709 (setq org-agenda-custom-commands-contexts
9710 '(("o" (in-mode . "message-mode"))))
9713 You can also tell that the command key @code{"o"} should refer to another
9714 command key @code{"r"}. In that case, add this command key like this:
9717 (setq org-agenda-custom-commands-contexts
9718 '(("o" "r" (in-mode . "message-mode"))))
9721 See the docstring of the variable for more information.
9723 @node Exporting agenda views
9724 @section Exporting agenda views
9725 @cindex agenda views, exporting
9727 If you are away from your computer, it can be very useful to have a printed
9728 version of some agenda views to carry around. Org mode can export custom
9729 agenda views as plain text, HTML@footnote{You need to install
9730 @file{htmlize.el} from @uref{https://github.com/hniksic/emacs-htmlize,Hrvoje
9731 Niksic's repository.}}, Postscript, PDF@footnote{To create PDF output, the
9732 ghostscript @file{ps2pdf} utility must be installed on the system. Selecting
9733 a PDF file will also create the postscript file.}, and iCalendar files. If
9734 you want to do this only occasionally, use the command
9737 @orgcmd{C-x C-w,org-agenda-write}
9738 @cindex exporting agenda views
9739 @cindex agenda views, exporting
9740 @vindex org-agenda-exporter-settings
9741 Write the agenda view to a file. Depending on the extension of the selected
9742 file name, the view will be exported as HTML (extension @file{.html} or
9743 @file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension
9744 @file{.ics}), or plain text (any other extension). Use the variable
9745 @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
9746 for @file{htmlize} to be used during export, for example
9748 @vindex org-agenda-add-entry-text-maxlines
9749 @vindex htmlize-output-type
9750 @vindex ps-number-of-columns
9751 @vindex ps-landscape-mode
9753 (setq org-agenda-exporter-settings
9754 '((ps-number-of-columns 2)
9755 (ps-landscape-mode t)
9756 (org-agenda-add-entry-text-maxlines 5)
9757 (htmlize-output-type 'css)))
9761 If you need to export certain agenda views frequently, you can associate
9762 any custom agenda command with a list of output file names
9763 @footnote{If you want to store standard views like the weekly agenda
9764 or the global TODO list as well, you need to define custom commands for
9765 them in order to be able to specify file names.}. Here is an example
9766 that first defines custom commands for the agenda and the global
9767 TODO list, together with a number of files to which to export them.
9768 Then we define two block agenda commands and specify file names for them
9769 as well. File names can be relative to the current working directory,
9774 (setq org-agenda-custom-commands
9775 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
9776 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
9777 ("h" "Agenda and Home-related tasks"
9782 ("~/views/home.html"))
9783 ("o" "Agenda and Office-related tasks"
9788 ("~/views/office.ps" "~/calendars/office.ics"))))
9792 The extension of the file name determines the type of export. If it is
9793 @file{.html}, Org mode will try to use the @file{htmlize.el} package to
9794 convert the buffer to HTML and save it to this file name. If the extension
9795 is @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
9796 Postscript output. If the extension is @file{.ics}, iCalendar export is run
9797 export over all files that were used to construct the agenda, and limit the
9798 export to entries listed in the agenda. Any other extension produces a plain
9801 The export files are @emph{not} created when you use one of those
9802 commands interactively because this might use too much overhead.
9803 Instead, there is a special command to produce @emph{all} specified
9807 @orgcmd{C-c a e,org-store-agenda-views}
9808 Export all agenda views that have export file names associated with
9812 You can use the options section of the custom agenda commands to also
9813 set options for the export commands. For example:
9816 (setq org-agenda-custom-commands
9818 ((ps-number-of-columns 2)
9819 (ps-landscape-mode t)
9820 (org-agenda-prefix-format " [ ] ")
9821 (org-agenda-with-colors nil)
9822 (org-agenda-remove-tags t))
9827 This command sets two options for the Postscript exporter, to make it
9828 print in two columns in landscape format---the resulting page can be cut
9829 in two and then used in a paper agenda. The remaining settings modify
9830 the agenda prefix to omit category and scheduling information, and
9831 instead include a checkbox to check off items. We also remove the tags
9832 to make the lines compact, and we don't want to use colors for the
9833 black-and-white printer. Settings specified in
9834 @code{org-agenda-exporter-settings} will also apply, but the settings
9835 in @code{org-agenda-custom-commands} take precedence.
9838 From the command line you may also use
9840 emacs -eval (org-batch-store-agenda-views) -kill
9843 or, if you need to modify some parameters@footnote{Quoting depends on the
9844 system you use, please check the FAQ for examples.}
9846 emacs -eval '(org-batch-store-agenda-views \
9847 org-agenda-span (quote month) \
9848 org-agenda-start-day "2007-11-01" \
9849 org-agenda-include-diary nil \
9850 org-agenda-files (quote ("~/org/project.org")))' \
9854 which will create the agenda views restricted to the file
9855 @file{~/org/project.org}, without diary entries and with a 30-day
9858 You can also extract agenda information in a way that allows further
9859 processing by other programs. See @ref{Extracting agenda information}, for
9863 @node Agenda column view
9864 @section Using column view in the agenda
9865 @cindex column view, in agenda
9866 @cindex agenda, column view
9868 Column view (@pxref{Column view}) is normally used to view and edit
9869 properties embedded in the hierarchical structure of an Org file. It can be
9870 quite useful to use column view also from the agenda, where entries are
9871 collected by certain criteria.
9874 @orgcmd{C-c C-x C-c,org-agenda-columns}
9875 Turn on column view in the agenda.
9878 To understand how to use this properly, it is important to realize that the
9879 entries in the agenda are no longer in their proper outline environment.
9880 This causes the following issues:
9884 @vindex org-columns-default-format
9885 @vindex org-overriding-columns-format
9886 Org needs to make a decision which @code{COLUMNS} format to use. Since the
9887 entries in the agenda are collected from different files, and different files
9888 may have different @code{COLUMNS} formats, this is a non-trivial problem.
9889 Org first checks if the variable @code{org-agenda-overriding-columns-format}
9890 is currently set, and if so, takes the format from there. Otherwise it takes
9891 the format associated with the first item in the agenda, or, if that item
9892 does not have a specific format---defined in a property, or in its file---it
9893 uses @code{org-columns-default-format}.
9896 @cindex property, special, CLOCKSUM
9897 If any of the columns has a summary type defined (@pxref{Column attributes}),
9898 turning on column view in the agenda will visit all relevant agenda files and
9899 make sure that the computations of this property are up to date. This is
9900 also true for the special @code{CLOCKSUM} property. Org will then sum the
9901 values displayed in the agenda. In the daily/weekly agenda, the sums will
9902 cover a single day; in all other views they cover the entire block. It is
9903 vital to realize that the agenda may show the same entry @emph{twice}---for
9904 example as scheduled and as a deadline---and it may show two entries from the
9905 same hierarchy---for example a @emph{parent} and its @emph{child}. In these
9906 cases, the summation in the agenda will lead to incorrect results because
9907 some values will count double.
9910 When the column view in the agenda shows the @code{CLOCKSUM}, that is always
9911 the entire clocked time for this item. So even in the daily/weekly agenda,
9912 the clocksum listed in column view may originate from times outside the
9913 current view. This has the advantage that you can compare these values with
9914 a column listing the planned total effort for a task---one of the major
9915 applications for column view in the agenda. If you want information about
9916 clocked time in the displayed period use clock table mode (press @kbd{R} in
9920 @cindex property, special, CLOCKSUM_T
9921 When the column view in the agenda shows the @code{CLOCKSUM_T}, that is
9922 always today's clocked time for this item. So even in the weekly agenda, the
9923 clocksum listed in column view only originates from today. This lets you
9924 compare the time you spent on a task for today, with the time already
9925 spent ---via @code{CLOCKSUM}---and with the planned total effort for it.
9930 @chapter Markup for rich export
9932 When exporting Org mode documents, the exporter tries to reflect the
9933 structure of the document as accurately as possible in the back-end. Since
9934 export targets like HTML and @LaTeX{} allow much richer formatting, Org mode has
9935 rules on how to prepare text for rich export. This section summarizes the
9936 markup rules used in an Org mode buffer.
9939 * Paragraphs:: The basic unit of text
9940 * Emphasis and monospace:: Bold, italic, etc.
9941 * Horizontal rules:: Make a line
9942 * Images and tables:: Images, tables and caption mechanism
9943 * Literal examples:: Source code examples with special formatting
9944 * Special symbols:: Greek letters and other symbols
9945 * Subscripts and superscripts:: Simple syntax for raising/lowering text
9946 * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
9950 @section Paragraphs, line breaks, and quoting
9951 @cindex paragraphs, markup rules
9953 Paragraphs are separated by at least one empty line. If you need to enforce
9954 a line break within a paragraph, use @samp{\\} at the end of a line.
9956 To preserve the line breaks, indentation and blank lines in a region, but
9957 otherwise use normal formatting, you can use this construct, which can also
9958 be used to format poetry.
9960 @cindex #+BEGIN_VERSE
9961 @cindex verse blocks
9964 Great clouds overhead
9965 Tiny black birds rise and fall
9972 When quoting a passage from another document, it is customary to format this
9973 as a paragraph that is indented on both the left and the right margin. You
9974 can include quotations in Org mode documents like this:
9976 @cindex #+BEGIN_QUOTE
9977 @cindex quote blocks
9980 Everything should be made as simple as possible,
9981 but not any simpler -- Albert Einstein
9985 If you would like to center some text, do it like this:
9986 @cindex #+BEGIN_CENTER
9987 @cindex center blocks
9990 Everything should be made as simple as possible, \\
9995 @node Emphasis and monospace
9996 @section Emphasis and monospace
9998 @cindex underlined text, markup rules
9999 @cindex bold text, markup rules
10000 @cindex italic text, markup rules
10001 @cindex verbatim text, markup rules
10002 @cindex code text, markup rules
10003 @cindex strike-through text, markup rules
10004 @vindex org-fontify-emphasized-text
10005 @vindex org-emphasis-regexp-components
10006 @vindex org-emphasis-alist
10007 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=verbatim=}
10008 and @code{~code~}, and, if you must, @samp{+strike-through+}. Text
10009 in the code and verbatim string is not processed for Org mode specific
10010 syntax, it is exported verbatim.
10012 To turn off fontification for marked up text, you can set
10013 @code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of
10014 available markup syntax, you can customize @code{org-emphasis-alist}. To fine
10015 tune what characters are allowed before and after the markup characters, you
10016 can tweak @code{org-emphasis-regexp-components}. Beware that changing one of
10017 the above variables will no take effect until you reload Org, for which you
10018 may need to restart Emacs.
10020 @node Horizontal rules
10021 @section Horizontal rules
10022 @cindex horizontal rules, markup rules
10023 A line consisting of only dashes, and at least 5 of them, will be exported as
10026 @node Images and tables
10027 @section Images and Tables
10029 @cindex tables, markup rules
10032 Both the native Org mode tables (@pxref{Tables}) and tables formatted with
10033 the @file{table.el} package will be exported properly. For Org mode tables,
10034 the lines before the first horizontal separator line will become table header
10035 lines. You can use the following lines somewhere before the table to assign
10036 a caption and a label for cross references, and in the text you can refer to
10037 the object with @code{[[tab:basic-data]]} (@pxref{Internal links}):
10040 #+CAPTION: This is the caption for the next table (or link)
10041 #+NAME: tab:basic-data
10046 Optionally, the caption can take the form:
10048 #+CAPTION[Caption for list of tables]: Caption for table.
10051 @cindex inlined images, markup rules
10052 Some back-ends allow you to directly include images into the exported
10053 document. Org does this, if a link to an image files does not have
10054 a description part, for example @code{[[./img/a.jpg]]}. If you wish to
10055 define a caption for the image and maybe a label for internal cross
10056 references, make sure that the link is on a line by itself and precede it
10057 with @code{#+CAPTION} and @code{#+NAME} as follows:
10060 #+CAPTION: This is the caption for the next figure link (or table)
10061 #+NAME: fig:SED-HR4049
10066 Such images can be displayed within the buffer. @xref{Handling links,the
10067 discussion of image links}.
10069 Even though images and tables are prominent examples of captioned structures,
10070 the same caption mechanism can apply to many others (e.g., @LaTeX{}
10071 equations, source code blocks). Depending on the export back-end, those may
10072 or may not be handled.
10074 @node Literal examples
10075 @section Literal examples
10076 @cindex literal examples, markup rules
10077 @cindex code line references, markup rules
10079 You can include literal examples that should not be subjected to
10080 markup. Such examples will be typeset in monospace, so this is well suited
10081 for source code and similar examples.
10082 @cindex #+BEGIN_EXAMPLE
10086 Some example from a text file.
10090 Note that such blocks may be @i{indented} in order to align nicely with
10091 indented text and in particular with plain list structure (@pxref{Plain
10092 lists}). For simplicity when using small examples, you can also start the
10093 example lines with a colon followed by a space. There may also be additional
10094 whitespace before the colon:
10098 : Some example from a text file.
10101 @cindex formatting source code, markup rules
10102 @vindex org-latex-listings
10103 If the example is source code from a programming language, or any other text
10104 that can be marked up by font-lock in Emacs, you can ask for the example to
10105 look like the fontified Emacs buffer@footnote{This works automatically for
10106 the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package,
10107 which you need to install). Fontified code chunks in @LaTeX{} can be
10108 achieved using either the
10109 @url{https://www.ctan.org/tex-archive/macros/latex/contrib/listings/?lang=en,
10110 listings,} or the @url{https://github.com/gpoore/minted, minted,} package.
10111 If you use minted or listing, you must load the packages manually, for
10112 example by adding the desired package to @code{org-latex-packages-alist}.
10113 Refer to @code{org-latex-listings} for details.}. This is done with the
10114 @samp{src} block, where you also need to specify the name of the major mode
10115 that should be used to fontify the example@footnote{Code in @samp{src} blocks
10116 may also be evaluated either interactively or on export. @xref{Working with
10117 source code}, for more information on evaluating code blocks.}, see
10118 @ref{Structure templates} for shortcuts to easily insert code blocks.
10119 @cindex #+BEGIN_SRC
10122 #+BEGIN_SRC emacs-lisp
10123 (defun org-xor (a b)
10129 Both in @code{example} and in @code{src} snippets, you can add a @code{-n}
10130 switch to the end of the @code{BEGIN} line, to get the lines of the example
10131 numbered. The @code{-n} takes an optional numeric argument specifying the
10132 starting line number of the block. If you use a @code{+n} switch, the
10133 numbering from the previous numbered snippet will be continued in the current
10134 one. The @code{+n} can also take a numeric argument. The value of the
10135 argument will be added to the last line of the previous block to determine
10136 the starting line number.
10139 #+BEGIN_SRC emacs-lisp -n 20
10140 ;; this will export with line number 20
10141 (message "This is line 21")
10143 #+BEGIN_SRC emacs-lisp +n 10
10144 ;; This will be listed as line 31
10145 (message "This is line 32")
10149 In literal examples, Org will interpret strings like @samp{(ref:name)} as
10150 labels, and use them as targets for special hyperlinks like @code{[[(name)]]}
10151 (i.e., the reference name enclosed in single parenthesis). In HTML, hovering
10152 the mouse over such a link will remote-highlight the corresponding code line,
10153 which is kind of cool.
10155 You can also add a @code{-r} switch which @i{removes} the labels from the
10156 source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
10157 labels in the source code while using line numbers for the links, which might
10158 be useful to explain those in an Org mode example code.}. With the @code{-n}
10159 switch, links to these references will be labeled by the line numbers from
10160 the code listing, otherwise links will use the labels with no parentheses.
10161 Here is an example:
10164 #+BEGIN_SRC emacs-lisp -n -r
10165 (save-excursion (ref:sc)
10166 (goto-char (point-min))) (ref:jump)
10168 In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
10169 jumps to point-min.
10172 @cindex indentation, in source blocks
10173 Finally, you can use @code{-i} to preserve the indentation of a specific code
10174 block (@pxref{Editing source code}).
10176 @vindex org-coderef-label-format
10177 If the syntax for the label format conflicts with the language syntax, use a
10178 @code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
10179 -n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}.
10181 HTML export also allows examples to be published as text areas (@pxref{Text
10182 areas in HTML export}).
10184 Because the @code{#+BEGIN_...} @dots{} @code{#+END_...} patterns need to be
10185 added so often, a shortcut is provided (@pxref{Structure templates}).
10190 Edit the source code example at point in its native mode. This works by
10191 switching to a temporary buffer with the source code. You need to exit by
10192 pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*},
10193 @samp{,*}, @samp{#+} and @samp{,#+} will get a comma prepended, to keep them
10194 from being interpreted by Org as outline nodes or special syntax. These
10195 commas will be stripped for editing with @kbd{C-c '}, and also for export.}.
10196 The edited version will then replace the old version in the Org buffer.
10197 Fixed-width regions (where each line starts with a colon followed by a space)
10198 will be edited using @code{artist-mode}@footnote{You may select
10199 a different-mode with the variable @code{org-edit-fixed-width-region-mode}.}
10200 to allow creating ASCII drawings easily. Using this command in an empty line
10201 will create a new fixed-width region.
10204 Calling @code{org-store-link} while editing a source code example in a
10205 temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure
10206 that it is unique in the current buffer, and insert it with the proper
10207 formatting like @samp{(ref:label)} at the end of the current line. Then the
10208 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
10211 @node Special symbols
10212 @section Special symbols
10213 @cindex Org entities
10214 @cindex math symbols
10215 @cindex special symbols
10216 @cindex HTML entities
10217 @cindex @LaTeX{} entities
10219 You can use @LaTeX{}-like syntax to insert special symbols---named
10220 entities---like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to
10221 indicate an arrow. Completion for these symbols is available, just type
10222 @samp{\} and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible
10223 completions. If you need such a symbol inside a word, terminate it with
10224 a pair of curly brackets. For example
10227 Pro tip: Given a circle \Gamma of diameter d, the length of its circumference
10231 @findex org-entities-help
10232 @vindex org-entities-user
10233 A large number of entities is provided, with names taken from both HTML and
10234 @LaTeX{}; you can comfortably browse the complete list from a dedicated
10235 buffer using the command @code{org-entities-help}. It is also possible to
10236 provide your own special symbols in the variable @code{org-entities-user}.
10238 During export, these symbols are transformed into the native format of the
10239 exporter back-end. Strings like @code{\alpha} are exported as @code{α}
10240 in the HTML output, and as @code{\(\alpha\)} in the @LaTeX{} output.
10241 Similarly, @code{\nbsp} becomes @code{ } in HTML and @code{~} in
10244 @cindex escaping characters
10245 Entities may also be used as a may to escape markup in an Org document, e.g.,
10246 @samp{\under@{@}not underlined\under} exports as @samp{_not underlined_}.
10248 @cindex special symbols, in-buffer display
10249 If you would like to see entities displayed as UTF-8 characters, use the
10250 following command@footnote{You can turn this on by default by setting the
10251 variable @code{org-pretty-entities}, or on a per-file base with the
10252 @code{#+STARTUP} option @code{entitiespretty}.}:
10255 @cindex @code{entitiespretty}, STARTUP keyword
10258 Toggle display of entities as UTF-8 characters. This does not change the
10259 buffer content which remains plain ASCII, but it overlays the UTF-8 character
10260 for display purposes only.
10263 @cindex shy hyphen, special symbol
10264 @cindex dash, special symbol
10265 @cindex ellipsis, special symbol
10266 In addition to regular entities defined above, Org exports in a special
10267 way@footnote{This behaviour can be disabled with @code{-} export setting
10268 (@pxref{Export settings}).} the following commonly used character
10269 combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---}
10270 are converted into dashes, and @samp{...} becomes a compact set of dots.
10272 @node Subscripts and superscripts
10273 @section Subscripts and superscripts
10275 @cindex superscript
10277 @samp{^} and @samp{_} are used to indicate super- and subscripts. To
10278 increase the readability of ASCII text, it is not necessary---but OK---to
10279 surround multi-character sub- and superscripts with curly braces. Those are,
10280 however, mandatory, when more than one word is involved. For example
10283 The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, the
10284 radius of Alpha Centauri is R_@{Alpha Centauri@} = 1.28 x R_@{sun@}.
10287 @vindex org-use-sub-superscripts
10288 If you write a text where the underscore is often used in a different
10289 context, Org's convention to always interpret these as subscripts can get in
10290 your way. Configure the variable @code{org-use-sub-superscripts} to change
10291 this convention. For example, when setting this variable to @code{@{@}},
10292 @samp{a_b} will not be interpreted as a subscript, but @samp{a_@{b@}} will.
10297 In addition to showing entities as UTF-8 characters, this command will also
10298 format sub- and superscripts in a WYSIWYM way.
10301 @node Embedded @LaTeX{}
10302 @section Embedded @LaTeX{}
10303 @cindex @TeX{} interpretation
10304 @cindex @LaTeX{} interpretation
10306 Plain ASCII is normally sufficient for almost all note taking. Exceptions
10307 include scientific notes, which often require mathematical symbols and the
10308 occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on
10309 Donald E. Knuth's @TeX{} system. Many of the features described here as
10310 ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
10311 distinction.} is widely used to typeset scientific documents. Org mode
10312 supports embedding @LaTeX{} code into its files, because many academics are
10313 used to writing and reading @LaTeX{} source code, and because it can be
10314 readily processed to produce pretty output for a number of export back-ends.
10317 * @LaTeX{} fragments:: Complex formulas made easy
10318 * Previewing @LaTeX{} fragments:: What will this snippet look like?
10319 * CDLaTeX mode:: Speed up entering of formulas
10322 @node @LaTeX{} fragments
10323 @subsection @LaTeX{} fragments
10324 @cindex @LaTeX{} fragments
10326 @vindex org-format-latex-header
10327 Org mode can contain @LaTeX{} math fragments, and it supports ways to process
10328 these for several export back-ends. When exporting to @LaTeX{}, the code is
10329 left as it is. When exporting to HTML, Org can use either
10330 @uref{http://www.mathjax.org, MathJax} (@pxref{Math formatting in HTML
10331 export}) or transcode the math into images (see @pxref{Previewing @LaTeX{}
10334 @LaTeX{} fragments don't need any special marking at all. The following
10335 snippets will be identified as @LaTeX{} source code:
10338 Environments of any kind@footnote{When MathJax is used, only the
10339 environments recognized by MathJax will be processed. When
10340 @file{dvipng} program, @file{dvisvgm} program or @file{imagemagick} suite is
10341 used to create images, any @LaTeX{} environment will be handled.}. The only
10342 requirement is that the @code{\begin} statement appears on a new line, at the
10343 beginning of the line or after whitespaces only.
10345 Text within the usual @LaTeX{} math delimiters. To avoid conflicts with
10346 currency specifications, single @samp{$} characters are only recognized as
10347 math delimiters if the enclosed text contains at most two line breaks, is
10348 directly attached to the @samp{$} characters with no whitespace in between,
10349 and if the closing @samp{$} is followed by whitespace or punctuation
10350 (parentheses and quotes are considered to be punctuation in this
10351 context). For the other delimiters, there is no such restriction, so when in
10352 doubt, use @samp{\(...\)} as inline math delimiters.
10355 @noindent For example:
10362 If $a^2=b$ and \( b=2 \), then the solution must be
10363 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
10368 @c @vindex org-format-latex-options
10369 @c If you need any of the delimiter ASCII sequences for other purposes, you
10370 @c can configure the option @code{org-format-latex-options} to deselect the
10371 @c ones you do not wish to have interpreted by the @LaTeX{} converter.
10373 @vindex org-export-with-latex
10374 @LaTeX{} processing can be configured with the variable
10375 @code{org-export-with-latex}. The default setting is @code{t} which means
10376 MathJax for HTML, and no processing for ASCII and @LaTeX{} back-ends.
10377 You can also set this variable on a per-file basis using one of these
10381 #+OPTIONS: tex:t @r{Do the right thing automatically (MathJax)}
10382 #+OPTIONS: tex:nil @r{Do not process @LaTeX{} fragments at all}
10383 #+OPTIONS: tex:verbatim @r{Verbatim export, for jsMath or so}
10386 @node Previewing @LaTeX{} fragments
10387 @subsection Previewing @LaTeX{} fragments
10388 @cindex @LaTeX{} fragments, preview
10390 @vindex org-preview-latex-default-process
10391 If you have a working @LaTeX{} installation and @file{dvipng}, @file{dvisvgm}
10392 or @file{convert} installed@footnote{These are respectively available at
10393 @url{http://sourceforge.net/projects/dvipng/}, @url{http://dvisvgm.bplaced.net/}
10394 and from the @file{imagemagick} suite. Choose the converter by setting the
10395 variable @code{org-preview-latex-default-process} accordingly.}, @LaTeX{}
10396 fragments can be processed to produce images of the typeset expressions to be
10397 used for inclusion while exporting to HTML (see @pxref{@LaTeX{} fragments}),
10398 or for inline previewing within Org mode.
10400 @vindex org-format-latex-options
10401 @vindex org-format-latex-header
10402 You can customize the variables @code{org-format-latex-options} and
10403 @code{org-format-latex-header} to influence some aspects of the preview. In
10404 particular, the @code{:scale} (and for HTML export, @code{:html-scale})
10405 property of the former can be used to adjust the size of the preview images.
10408 @kindex C-c C-x C-l
10410 Produce a preview image of the @LaTeX{} fragment at point and overlay it
10411 over the source code. If there is no fragment at point, process all
10412 fragments in the current entry (between two headlines). When called
10413 with a prefix argument, process the entire subtree. When called with
10414 two prefix arguments, or when the cursor is before the first headline,
10415 process the entire buffer.
10418 Remove the overlay preview images.
10421 @vindex org-startup-with-latex-preview
10422 You can turn on the previewing of all @LaTeX{} fragments in a file with
10425 #+STARTUP: latexpreview
10428 To disable it, simply use
10431 #+STARTUP: nolatexpreview
10435 @subsection Using CD@LaTeX{} to enter math
10438 CD@LaTeX{} mode is a minor mode that is normally used in combination with a
10439 major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
10440 environments and math templates. Inside Org mode, you can make use of
10441 some of the features of CD@LaTeX{} mode. You need to install
10442 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
10443 AUC@TeX{}) from @url{https://staff.fnwi.uva.nl/c.dominik/Tools/cdlatex}.
10444 Don't use CD@LaTeX{} mode itself under Org mode, but use the light
10445 version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it
10446 on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all
10450 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
10453 When this mode is enabled, the following features are present (for more
10454 details see the documentation of CD@LaTeX{} mode):
10458 Environment templates can be inserted with @kbd{C-c @{}.
10461 The @key{TAB} key will do template expansion if the cursor is inside a
10462 @LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is
10463 inside such a fragment, see the documentation of the function
10464 @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
10465 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
10466 correctly inside the first brace. Another @key{TAB} will get you into
10467 the second brace. Even outside fragments, @key{TAB} will expand
10468 environment abbreviations at the beginning of a line. For example, if
10469 you write @samp{equ} at the beginning of a line and press @key{TAB},
10470 this abbreviation will be expanded to an @code{equation} environment.
10471 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help RET}.
10475 @vindex cdlatex-simplify-sub-super-scripts
10476 Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these
10477 characters together with a pair of braces. If you use @key{TAB} to move
10478 out of the braces, and if the braces surround only a single character or
10479 macro, they are removed again (depending on the variable
10480 @code{cdlatex-simplify-sub-super-scripts}).
10483 Pressing the grave accent @kbd{`} followed by a character inserts math
10484 macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds
10485 after the grave accent, a help window will pop up.
10488 Pressing the apostrophe @kbd{'} followed by another character modifies
10489 the symbol before point with an accent or a font. If you wait more than
10490 1.5 seconds after the apostrophe, a help window will pop up. Character
10491 modification will work only inside @LaTeX{} fragments; outside the quote
10499 Sometimes, you may want to pretty print your notes, publish them on the web
10500 or even share them with people not using Org. In these cases, the Org export
10501 facilities can be used to convert your documents to a variety of other
10502 formats, while retaining as much structure (@pxref{Document structure}) and
10503 markup (@pxref{Markup}) as possible.
10505 @cindex export back-end
10506 Libraries responsible for such translation are called back-ends. Org ships
10507 with the following ones
10510 @item ascii (ASCII format)
10511 @item beamer (@LaTeX{} Beamer format)
10512 @item html (HTML format)
10513 @item icalendar (iCalendar format)
10514 @item latex (@LaTeX{} format)
10515 @item md (Markdown format)
10516 @item odt (OpenDocument Text format)
10517 @item org (Org format)
10518 @item texinfo (Texinfo format)
10519 @item man (Man page format)
10522 @noindent Org also uses additional libraries located in @code{contrib/}
10523 directory (@pxref{Installation}). Users can install additional export
10524 libraries for additional formats from the Emacs packaging system. For easy
10525 discovery, these packages have a common naming scheme: @file{ox-NAME}, where
10526 NAME is one of the formats. For example, @file{ox-koma-letter} for
10527 @code{koma-letter} back-end.
10529 @vindex org-export-backends
10530 Org loads back-ends for the following formats by default: @code{ascii},
10531 @code{html}, @code{icalendar}, @code{latex} and @code{odt}.
10533 Org can load additional back-ends either of two ways: through the
10534 @code{org-export-backends} variable configuration; or, by requiring the
10535 library in the Emacs init file like this:
10542 * The export dispatcher:: The main interface
10543 * Export settings:: Common export settings
10544 * Table of contents:: The if and where of the table of contents
10545 * Include files:: Include additional files into a document
10546 * Macro replacement:: Use macros to create templates
10547 * Comment lines:: What will not be exported
10548 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
10549 * Beamer export:: Exporting as a Beamer presentation
10550 * HTML export:: Exporting to HTML
10551 * @LaTeX{} export:: Exporting to @LaTeX{}, and processing to PDF
10552 * Markdown export:: Exporting to Markdown
10553 * OpenDocument Text export:: Exporting to OpenDocument Text
10554 * Org export:: Exporting to Org
10555 * Texinfo export:: Exporting to Texinfo
10556 * iCalendar export:: Exporting to iCalendar
10557 * Other built-in back-ends:: Exporting to a man page
10558 * Advanced configuration:: Fine-tuning the export output
10559 * Export in foreign buffers:: Author tables and lists in Org syntax
10562 @node The export dispatcher
10563 @section The export dispatcher
10564 @vindex org-export-dispatch-use-expert-ui
10565 @cindex Export, dispatcher
10567 The export dispatcher is the main interface for Org's exports. A
10568 hierarchical menu presents the currently configured export formats. Options
10569 are shown as easy toggle switches on the same screen.
10571 Org also has a minimal prompt interface for the export dispatcher. When the
10572 variable @code{org-export-dispatch-use-expert-ui} is set to a non-@code{nil}
10573 value, Org prompts in the minibuffer. To switch back to the hierarchical
10574 menu, press @key{?}.
10577 @orgcmd{C-c C-e,org-export-dispatch}
10579 Invokes the export dispatcher interface. The options show default settings.
10580 The @kbd{C-u} prefix argument preserves options from the previous export,
10581 including any sub-tree selections.
10585 Org exports the entire buffer by default. If the Org buffer has an active
10586 region, then Org exports just that region.
10588 These are the export options, the key combinations that toggle them
10589 (@pxref{Export settings}):
10593 @vindex org-export-async-init-file
10594 Toggles asynchronous export. Asynchronous export uses an external Emacs
10595 process with a specially configured initialization file to complete the
10596 exporting process in the background thereby releasing the current interface.
10597 This is particularly useful when exporting long documents.
10599 Output from an asynchronous export is saved on the ``the export stack''. To
10600 view this stack, call the export dispatcher with a double @kbd{C-u} prefix
10601 argument. If already in the export dispatcher menu, @kbd{&} displays the
10604 @vindex org-export-in-background
10605 To make the background export process the default, customize the variable,
10606 @code{org-export-in-background}.
10609 Toggle body-only export. Useful for excluding headers and footers in the
10610 export. Affects only those back-end formats that have such sections---like
10611 @code{<head>...</head>} in HTML.
10614 @vindex org-export-initial-scope
10615 Toggle sub-tree export. When turned on, Org exports only the sub-tree starting
10616 from the cursor position at the time the export dispatcher was invoked. Org
10617 uses the top heading of this sub-tree as the document's title. If the cursor
10618 is not on a heading, Org uses the nearest enclosing header. If the cursor is
10619 in the document preamble, Org signals an error and aborts export.
10621 To make the sub-tree export the default, customize the variable,
10622 @code{org-export-initial-scope}.
10625 Toggle visible-only export. Useful for exporting only visible parts of an
10626 Org document by adjusting outline visibility settings.
10629 @node Export settings
10630 @section Export settings
10631 @cindex Export, settings
10634 Export options can be set: globally with variables; for an individual file by
10635 making variables buffer-local with in-buffer settings (@pxref{In-buffer
10636 settings}), by setting individual keywords, or by specifying them in a
10637 compact form with the @code{#+OPTIONS} keyword; or for a tree by setting
10638 properties (@pxref{Properties and columns}). Options set at a specific level
10639 override options set at a more general level.
10641 @cindex #+SETUPFILE
10642 In-buffer settings may appear anywhere in the file, either directly or
10643 indirectly through a file included using @samp{#+SETUPFILE: filename or URL}
10644 syntax. Option keyword sets tailored to a particular back-end can be
10645 inserted from the export dispatcher (@pxref{The export dispatcher}) using the
10646 @code{Insert template} command by pressing @key{#}. To insert keywords
10647 individually, a good way to make sure the keyword is correct is to type
10648 @code{#+} and then to use @kbd{M-@key{TAB}}@footnote{Many desktops intercept
10649 @kbd{M-TAB} to switch windows. Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}}
10650 instead.} for completion.
10652 The export keywords available for every back-end, and their equivalent global
10653 variables, include:
10658 @vindex user-full-name
10659 The document author (@code{user-full-name}).
10663 @vindex org-export-creator-string
10664 Entity responsible for output generation (@code{org-export-creator-string}).
10668 @vindex org-export-date-timestamp-format
10669 A date or a time-stamp@footnote{The variable
10670 @code{org-export-date-timestamp-format} defines how this time-stamp will be
10675 @vindex user-mail-address
10676 The email address (@code{user-mail-address}).
10680 @vindex org-export-default-language
10681 Language to use for translating certain strings
10682 (@code{org-export-default-language}). With @samp{#+LANGUAGE: fr}, for
10683 example, Org translates @emph{Table of contents} to the French @emph{Table
10687 @cindex #+SELECT_TAGS
10688 @vindex org-export-select-tags
10689 The default value is @code{:export:}. When a tree is tagged with
10690 @code{:export:} (@code{org-export-select-tags}), Org selects that tree and
10691 its sub-trees for export. Org excludes trees with @code{:noexport:} tags,
10692 see below. When selectively exporting files with @code{:export:} tags set,
10693 Org does not export any text that appears before the first headline.
10696 @cindex #+EXCLUDE_TAGS
10697 @vindex org-export-exclude-tags
10698 The default value is @code{:noexport:}. When a tree is tagged with
10699 @code{:noexport:} (@code{org-export-exclude-tags}), Org excludes that tree
10700 and its sub-trees from export. Entries tagged with @code{:noexport:} will be
10701 unconditionally excluded from the export, even if they have an
10702 @code{:export:} tag. Even if a sub-tree is not exported, Org will execute any
10703 code blocks contained in them.
10707 @cindex document title
10708 Org displays this title. For long titles, use multiple @code{#+TITLE} lines.
10710 @item EXPORT_FILE_NAME
10711 @cindex #+EXPORT_FILE_NAME
10712 The name of the output file to be generated. Otherwise, Org generates the
10713 file name based on the buffer name and the extension based on the back-end
10717 The @code{#+OPTIONS} keyword is a compact form. To configure multiple
10718 options, use several @code{#+OPTIONS} lines. @code{#+OPTIONS} recognizes the
10719 following arguments.
10723 @vindex org-export-with-smart-quotes
10724 Toggle smart quotes (@code{org-export-with-smart-quotes}). Depending on the
10725 language used, when activated, Org treats pairs of double quotes as primary
10726 quotes, pairs of single quotes as secondary quotes, and single quote marks as
10730 Toggle emphasized text (@code{org-export-with-emphasize}).
10733 @vindex org-export-with-special-strings
10734 Toggle conversion of special strings
10735 (@code{org-export-with-special-strings}).
10738 @vindex org-export-with-fixed-width
10739 Toggle fixed-width sections
10740 (@code{org-export-with-fixed-width}).
10743 @vindex org-export-with-timestamps
10744 Toggle inclusion of time/date active/inactive stamps
10745 (@code{org-export-with-timestamps}).
10748 @vindex org-export-preserve-breaks
10749 Toggles whether to preserve line breaks (@code{org-export-preserve-breaks}).
10752 @vindex org-export-with-sub-superscripts
10753 Toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}",
10754 @samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as
10755 it is (@code{org-export-with-sub-superscripts}).
10758 @vindex org-export-with-archived-trees
10759 Configure how archived trees are exported. When set to @code{headline}, the
10760 export process skips the contents and processes only the headlines
10761 (@code{org-export-with-archived-trees}).
10764 @vindex org-export-with-author
10765 Toggle inclusion of author name into exported file
10766 (@code{org-export-with-author}).
10768 @item broken-links:
10769 @vindex org-export-with-broken-links
10770 Toggles if Org should continue exporting upon finding a broken internal link.
10771 When set to @code{mark}, Org clearly marks the problem link in the output
10772 (@code{org-export-with-broken-links}).
10775 @vindex org-export-with-clocks
10776 Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}).
10779 @vindex org-export-with-creator
10780 Toggle inclusion of creator information in the exported file
10781 (@code{org-export-with-creator}).
10784 @vindex org-export-with-drawers
10785 Toggles inclusion of drawers, or list of drawers to include, or list of
10786 drawers to exclude (@code{org-export-with-drawers}).
10789 @vindex org-export-with-date
10790 Toggle inclusion of a date into exported file (@code{org-export-with-date}).
10793 @vindex org-export-with-entities
10794 Toggle inclusion of entities (@code{org-export-with-entities}).
10797 @vindex org-export-with-email
10798 Toggle inclusion of the author's e-mail into exported file
10799 (@code{org-export-with-email}).
10802 @vindex org-export-with-footnotes
10803 Toggle the inclusion of footnotes (@code{org-export-with-footnotes}).
10806 @vindex org-export-headline-levels
10807 Set the number of headline levels for export
10808 (@code{org-export-headline-levels}). Below that level, headlines are treated
10809 differently. In most back-ends, they become list items.
10812 @vindex org-export-with-inlinetasks
10813 Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
10816 @vindex org-export-with-section-numbers
10817 @cindex property, UNNUMBERED
10818 Toggle section-numbers (@code{org-export-with-section-numbers}). When set to
10819 number @samp{n}, Org numbers only those headlines at level @samp{n} or above.
10820 Setting @code{UNNUMBERED} property to non-@code{nil} disables numbering of
10821 the heading. Since subheadings inherit from this property, it affects their
10822 numbering, too. Moreover, when the value is @samp{notoc}, the unnumbered
10823 headline does not appear in the table of contents either (@pxref{Table of
10827 @vindex org-export-with-planning
10828 Toggle export of planning information (@code{org-export-with-planning}).
10829 ``Planning information'' comes from lines located right after the headline
10830 and contain any combination of these cookies: @code{SCHEDULED:},
10831 @code{DEADLINE:}, or @code{CLOSED:}.
10834 @vindex org-export-with-priority
10835 Toggle inclusion of priority cookies (@code{org-export-with-priority}).
10838 @vindex org-export-with-properties
10839 Toggle inclusion of property drawers, or list the properties to include
10840 (@code{org-export-with-properties}).
10843 @vindex org-export-with-statistics-cookies
10844 Toggle inclusion of statistics cookies
10845 (@code{org-export-with-statistics-cookies}).
10848 @vindex org-export-with-tags
10849 Toggle inclusion of tags, may also be @code{not-in-toc}
10850 (@code{org-export-with-tags}).
10853 @vindex org-export-with-tasks
10854 Toggle inclusion of tasks (TODO items); or @code{nil} to remove all tasks; or
10855 @code{todo} to remove DONE tasks; or list the keywords to keep
10856 (@code{org-export-with-tasks}).
10859 @vindex org-export-with-latex
10860 @code{nil} does not export; @code{t} exports; @code{verbatim} keeps
10861 everything in verbatim (@code{org-export-with-latex}).
10864 @vindex org-export-time-stamp-file
10865 Toggle inclusion of the creation time in the exported file
10866 (@code{org-export-time-stamp-file}).
10869 @vindex org-export-with-title
10870 Toggle inclusion of title (@code{org-export-with-title}).
10873 @vindex org-export-with-toc
10874 Toggle inclusion of the table of contents, or set the level limit
10875 (@code{org-export-with-toc}).
10878 @vindex org-export-with-todo-keywords
10879 Toggle inclusion of TODO keywords into exported text
10880 (@code{org-export-with-todo-keywords}).
10883 @vindex org-export-with-tables
10884 Toggle inclusion of tables (@code{org-export-with-tables}).
10888 When exporting sub-trees, special node properties in them can override the
10889 above keywords. They are special because they have an @samp{EXPORT_} prefix.
10890 For example, @samp{DATE} and @samp{EXPORT_FILE_NAME} keywords become,
10891 respectively, @samp{EXPORT_DATE} and @samp{EXPORT_FILE_NAME}. Except for
10892 @samp{SETUPFILE}, all other keywords listed above have an @samp{EXPORT_}
10896 @vindex org-export-allow-bind-keywords
10897 If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables
10898 can become buffer-local during export by using the BIND keyword. Its syntax
10899 is @samp{#+BIND: variable value}. This is particularly useful for in-buffer
10900 settings that cannot be changed using keywords.
10902 @node Table of contents
10903 @section Table of contents
10904 @cindex table of contents
10905 @cindex list of tables
10906 @cindex list of listings
10908 @cindex @samp{toc} in OPTIONS keyword
10909 @vindex org-export-with-toc
10910 The table of contents includes all headlines in the document. Its depth is
10911 therefore the same as the headline levels in the file. If you need to use
10912 a different depth, or turn it off entirely, set the
10913 @code{org-export-with-toc} variable accordingly. You can achieve the same on
10914 a per file basis, using the following @samp{toc} item in @samp{#+OPTIONS}
10918 #+OPTIONS: toc:2 @r{only include two levels in TOC}
10919 #+OPTIONS: toc:nil @r{no default TOC at all}
10922 @cindex excluding entries from table of contents
10923 @cindex table of contents, exclude entries
10924 Org includes both numbered and unnumbered headlines in the table of
10925 contents@footnote{At the moment, some export back-ends do not obey this
10926 specification. For example, @LaTeX{} export excludes every unnumbered
10927 headline from the table of contents.}. If you need to exclude an unnumbered
10928 headline, along with all its children, set the @samp{UNNUMBERED} property to
10929 @samp{notoc} value.
10932 * Subtree not numbered, not in table of contents either
10939 Org normally inserts the table of contents directly before the first headline
10940 of the file. To move the table of contents to a different location, first
10941 turn off the default with @code{org-export-with-toc} variable or with
10942 @code{#+OPTIONS: toc:nil}. Then insert @code{#+TOC: headlines N} at the
10943 desired location(s).
10946 #+OPTIONS: toc:nil @r{no default TOC}
10948 #+TOC: headlines 2 @r{insert TOC here, with two headline levels}
10951 To adjust the TOC depth for a specific section of the Org document, append an
10952 additional @samp{local} parameter. This parameter becomes a relative depth
10953 for the current level.
10955 Note that for this feature to work properly in @LaTeX{} export, the Org file
10956 requires the inclusion of the @code{titletoc} package. Because of
10957 compatibility issues, @code{titletoc} has to be loaded @emph{before}
10958 @code{hyperref}. Customize the @code{org-latex-default-packages-alist}
10963 #+TOC: headlines 1 local @r{insert local TOC, with direct children only}
10966 Use the @code{TOC} keyword to generate list of tables (resp.@: all listings)
10970 #+TOC: listings @r{build a list of listings}
10971 #+TOC: tables @r{build a list of tables}
10974 @cindex property, ALT_TITLE
10975 Normally Org uses the headline for its entry in the table of contents. But
10976 with @code{ALT_TITLE} property, a different entry can be specified for the
10979 @node Include files
10980 @section Include files
10981 @cindex include files, during export
10982 Include other files during export. For example, to include your @file{.emacs}
10983 file, you could use:
10987 #+INCLUDE: "~/.emacs" src emacs-lisp
10991 The first parameter is the file name to include. The optional second
10992 parameter specifies the block type: @samp{example}, @samp{export} or
10993 @samp{src}. The optional third parameter specifies the source code language
10994 to use for formatting the contents. This is relevant to both @samp{export}
10995 and @samp{src} block types.
10997 If an include file is specified as having a markup language, Org neither
10998 checks for valid syntax nor changes the contents in any way. For
10999 @samp{example} and @samp{src} blocks, Org code-escapes the contents before
11002 If an include file is not specified as having any markup language, Org
11003 assumes it be in Org format and proceeds as usual with a few exceptions. Org
11004 makes the footnote labels (@pxref{Footnotes}) in the included file local to
11005 that file. The contents of the included file will belong to the same
11006 structure---headline, item---containing the @code{INCLUDE} keyword. In
11007 particular, headlines within the file will become children of the current
11008 section. That behavior can be changed by providing an additional keyword
11009 parameter, @code{:minlevel}. It shifts the headlines in the included file to
11010 become the lowest level. For example, this syntax makes the included file
11011 a sibling of the current top-level headline:
11014 #+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
11017 Inclusion of only portions of files are specified using ranges parameter with
11018 @code{:lines} keyword. The line at the upper end of the range will not be
11019 included. The start and/or the end of the range may be omitted to use the
11023 #+INCLUDE: "~/.emacs" :lines "5-10" @r{Include lines 5 to 10, 10 excluded}
11024 #+INCLUDE: "~/.emacs" :lines "-10" @r{Include lines 1 to 10, 10 excluded}
11025 #+INCLUDE: "~/.emacs" :lines "10-" @r{Include lines from 10 to EOF}
11028 Inclusions may specify a file-link to extract an object matched by
11029 @code{org-link-search}@footnote{Note that
11030 @code{org-link-search-must-match-exact-headline} is locally bound to
11031 non-@code{nil}. Therefore, @code{org-link-search} only matches headlines and
11032 named elements.} (@pxref{Search options}).
11034 To extract only the contents of the matched object, set @code{:only-contents}
11035 property to non-@code{nil}. This will omit any planning lines or property
11036 drawers. The ranges for @code{:lines} keyword are relative to the requested
11037 element. Some examples:
11040 #+INCLUDE: "./paper.org::#theory" :only-contents t
11041 @r{Include the body of the heading with the custom id @samp{theory}}
11042 #+INCLUDE: "./paper.org::mytable" @r{Include named element.}
11043 #+INCLUDE: "./paper.org::*conclusion" :lines 1-20
11044 @r{Include the first 20 lines of the headline named @samp{conclusion}.}
11050 Visit the include file at point.
11053 @node Macro replacement
11054 @section Macro replacement
11055 @cindex macro replacement, during export
11058 @vindex org-export-global-macros
11059 Macros replace text snippets during export. Macros are defined globally in
11060 @code{org-export-global-macros}, or document-wise with the following syntax:
11063 #+MACRO: name replacement text $1, $2 are arguments
11066 @noindent which can be referenced using
11067 @code{@{@{@{name(arg1, arg2)@}@}@}}@footnote{Since commas separate the
11068 arguments, commas within arguments have to be escaped with the backslash
11069 character. So only those backslash characters before a comma need escaping
11070 with another backslash character.}.
11072 Org recognizes macro references in following Org markup areas: paragraphs,
11073 headlines, verse blocks, tables cells and lists. Org also recognizes macro
11074 references in keywords, such as @code{#+CAPTION}, @code{#+TITLE},
11075 @code{#+AUTHOR}, @code{#+DATE}, and for some back-end specific export
11078 Org comes with following pre-defined macros:
11081 @item @{@{@{keyword(@var{NAME})@}@}@}
11082 @itemx @{@{@{title@}@}@}
11083 @itemx @{@{@{author@}@}@}
11084 @itemx @{@{@{email@}@}@}
11085 @cindex keyword, macro
11086 @cindex title, macro
11087 @cindex author, macro
11088 @cindex email, macro
11089 The @samp{keyword} macro collects all values from @var{NAME} keywords
11090 throughout the buffer, separated with white space. @samp{title},
11091 @samp{author} and @samp{email} macros are shortcuts for, respectively,
11092 @samp{@{@{@{keyword(TITLE)@}@}@}}, @samp{@{@{@{keyword(AUTHOR)@}@}@}} and
11093 @samp{@{@{@{keyword(EMAIL)@}@}@}}.
11095 @item @{@{@{date@}@}@}
11096 @itemx @{@{@{date(@var{FORMAT})@}@}@}
11097 @cindex date, macro
11098 This macro refers to the @code{#+DATE} keyword. @var{FORMAT} is an optional
11099 argument to the @code{@{@{@{date@}@}@}} macro that will be used only if
11100 @code{#+DATE} is a single timestamp. @var{FORMAT} should be a format string
11101 understood by @code{format-time-string}.
11103 @item @{@{@{time(@var{FORMAT})@}@}@}
11104 @itemx @{@{@{modification-time(@var{FORMAT}, @var{VC})@}@}@}
11105 @cindex time, macro
11106 @cindex modification time, macro
11107 These macros refer to the document's date and time of export and date and
11108 time of modification. @var{FORMAT} is a string understood by
11109 @code{format-time-string}. If the second argument to the
11110 @code{modification-time} macro is non-@code{nil}, Org uses @file{vc.el} to
11111 retrieve the document's modification time from the version control
11112 system. Otherwise Org reads the file attributes.
11114 @item @{@{@{input-file@}@}@}
11115 @cindex input file, macro
11116 This macro refers to the filename of the exported file.
11118 @item @{@{@{property(@var{PROPERTY-NAME})@}@}@}
11119 @itemx @{@{@{property(@var{PROPERTY-NAME},@var{SEARCH-OPTION})@}@}@}
11120 @cindex property, macro
11121 This macro returns the value of property @var{PROPERTY-NAME} in the current
11122 entry. If @var{SEARCH-OPTION} (@pxref{Search options}) refers to a remote
11123 entry, that will be used instead.
11125 @item @{@{@{n@}@}@}
11126 @itemx @{@{@{n(@var{NAME})@}@}@}
11127 @itemx @{@{@{n(@var{NAME},@var{ACTION})@}@}@}
11129 @cindex counter, macro
11130 This macro implements custom counters by returning the number of times the
11131 macro has been expanded so far while exporting the buffer. You can create
11132 more than one counter using different @var{NAME} values. If @var{ACTION} is
11133 @code{-}, previous value of the counter is held, i.e. the specified counter
11134 is not incremented. If the value is a number, the specified counter is set
11135 to that value. If it is any other non-empty string, the specified counter is
11136 reset to 1. You may leave @var{NAME} empty to reset the default counter.
11139 The surrounding brackets can be made invisible by setting
11140 @code{org-hide-macro-markers} non-@code{nil}.
11142 Org expands macros at the very beginning of the export process.
11144 @node Comment lines
11145 @section Comment lines
11146 @cindex exporting, not
11148 @cindex comment lines
11149 Lines starting with zero or more whitespace characters followed by one
11150 @samp{#} and a whitespace are treated as comments and, as such, are not
11153 @cindex #+BEGIN_COMMENT
11154 Likewise, regions surrounded by @samp{#+BEGIN_COMMENT}
11155 ... @samp{#+END_COMMENT} are not exported.
11157 @cindex comment trees
11158 Finally, a @samp{COMMENT} keyword at the beginning of an entry, but after any
11159 other keyword or priority cookie, comments out the entire subtree. In this
11160 case, the subtree is not exported and no code block within it is executed
11161 either@footnote{For a less drastic behavior, consider using a select tag
11162 (@pxref{Export settings}) instead.}. The command below helps changing the
11163 comment status of a headline.
11168 Toggle the @samp{COMMENT} keyword at the beginning of an entry.
11171 @node ASCII/Latin-1/UTF-8 export
11172 @section ASCII/Latin-1/UTF-8 export
11173 @cindex ASCII export
11174 @cindex Latin-1 export
11175 @cindex UTF-8 export
11177 ASCII export produces an output file containing only plain ASCII characters.
11178 This is the most simplest and direct text output. It does not contain any
11179 Org markup either. Latin-1 and UTF-8 export use additional characters and
11180 symbols available in these encoding standards. All three of these export
11181 formats offer the most basic of text output for maximum portability.
11183 @vindex org-ascii-text-width
11184 On export, Org fills and justifies text according to the text width set in
11185 @code{org-ascii-text-width}.
11187 @vindex org-ascii-links-to-notes
11188 Org exports links using a footnote-like style where the descriptive part is
11189 in the text and the link is in a note before the next heading. See the
11190 variable @code{org-ascii-links-to-notes} for details.
11192 @subheading ASCII export commands
11195 @orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii}
11196 Export as an ASCII file with a @file{.txt} extension. For @file{myfile.org},
11197 Org exports to @file{myfile.txt}, overwriting without warning. For
11198 @file{myfile.txt}, Org exports to @file{myfile.txt.txt} in order to prevent
11200 @orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii}
11201 Export to a temporary buffer. Does not create a file.
11204 @subheading ASCII specific export settings
11205 The ASCII export back-end has one extra keyword for customizing ASCII output.
11206 Setting this keyword works similar to the general options (@pxref{Export
11211 @cindex #+SUBTITLE (ASCII)
11212 The document subtitle. For long subtitles, use multiple @code{#+SUBTITLE}
11213 lines in the Org file. Org prints them on one continuous line, wrapping into
11214 multiple lines if necessary.
11217 @subheading Header and sectioning structure
11219 Org converts the first three outline levels into headlines for ASCII export.
11220 The remaining levels are turned into lists. To change this cut-off point
11221 where levels become lists, @pxref{Export settings}.
11223 @subheading Quoting ASCII text
11225 To insert text within the Org file by the ASCII back-end, use one the
11226 following constructs, inline, keyword, or export block:
11229 @cindex #+BEGIN_EXPORT ascii
11231 Inline text @@@@ascii:and additional text@@@@ within a paragraph.
11235 #+BEGIN_EXPORT ascii
11236 Org exports text in this block only when using ASCII back-end.
11240 @subheading ASCII specific attributes
11241 @cindex #+ATTR_ASCII
11242 @cindex horizontal rules, in ASCII export
11244 ASCII back-end recognizes only one attribute, @code{:width}, which specifies
11245 the width of an horizontal rule in number of characters. The keyword and
11246 syntax for specifying widths is:
11249 #+ATTR_ASCII: :width 10
11253 @subheading ASCII special blocks
11254 @cindex special blocks, in ASCII export
11255 @cindex #+BEGIN_JUSTIFYLEFT
11256 @cindex #+BEGIN_JUSTIFYRIGHT
11258 Besides @code{#+BEGIN_CENTER} blocks (@pxref{Paragraphs}), ASCII back-end has
11259 these two left and right justification blocks:
11262 #+BEGIN_JUSTIFYLEFT
11263 It's just a jump to the left...
11266 #+BEGIN_JUSTIFYRIGHT
11267 ...and then a step to the right.
11271 @node Beamer export
11272 @section Beamer export
11273 @cindex Beamer export
11275 Org uses @emph{Beamer} export to convert an Org file tree structure into a
11276 high-quality interactive slides for presentations. @emph{Beamer} is a
11277 @LaTeX{} document class for creating presentations in PDF, HTML, and other
11278 popular display formats.
11281 * Beamer export commands:: For creating Beamer documents.
11282 * Beamer specific export settings:: For customizing Beamer export.
11283 * Sectioning Frames and Blocks in Beamer:: For composing Beamer slides.
11284 * Beamer specific syntax:: For using in Org documents.
11285 * Editing support:: For using helper functions.
11286 * A Beamer example:: A complete presentation.
11289 @node Beamer export commands
11290 @subsection Beamer export commands
11293 @orgcmd{C-c C-e l b,org-beamer-export-to-latex}
11294 Export as @LaTeX{} file with a @file{.tex} extension. For @file{myfile.org},
11295 Org exports to @file{myfile.tex}, overwriting without warning.
11296 @orgcmd{C-c C-e l B,org-beamer-export-as-latex}
11297 Export to a temporary buffer. Does not create a file.
11298 @orgcmd{C-c C-e l P,org-beamer-export-to-pdf}
11299 Export as @LaTeX{} file and then convert it to PDF format.
11301 Export as @LaTeX{} file, convert it to PDF format, and then open the PDF
11305 @node Beamer specific export settings
11306 @subsection Beamer specific export settings
11308 Beamer export back-end has several additional keywords for customizing Beamer
11309 output. These keywords work similar to the general options settings
11310 (@pxref{Export settings}).
11314 @cindex #+BEAMER_THEME
11315 @vindex org-beamer-theme
11316 The Beamer layout theme (@code{org-beamer-theme}). Use square brackets for
11317 options. For example:
11319 #+BEAMER_THEME: Rochester [height=20pt]
11322 @item BEAMER_FONT_THEME
11323 @cindex #+BEAMER_FONT_THEME
11324 The Beamer font theme.
11326 @item BEAMER_INNER_THEME
11327 @cindex #+BEAMER_INNER_THEME
11328 The Beamer inner theme.
11330 @item BEAMER_OUTER_THEME
11331 @cindex #+BEAMER_OUTER_THEME
11332 The Beamer outer theme.
11334 @item BEAMER_HEADER
11335 @cindex #+BEAMER_HEADER
11336 Arbitrary lines inserted in the preamble, just before the @samp{hyperref}
11340 @cindex #+DESCRIPTION (Beamer)
11341 The document description. For long descriptions, use multiple
11342 @code{#+DESCRIPTION} keywords. By default, @samp{hyperref} inserts
11343 @code{#+DESCRIPTION} as metadata. Use @code{org-latex-hyperref-template} to
11344 configure document metadata. Use @code{org-latex-title-command} to configure
11345 typesetting of description as part of front matter.
11348 @cindex #+KEYWORDS (Beamer)
11349 The keywords for defining the contents of the document. Use multiple
11350 @code{#+KEYWORDS} lines if necessary. By default, @samp{hyperref} inserts
11351 @code{#+KEYWORDS} as metadata. Use @code{org-latex-hyperref-template} to
11352 configure document metadata. Use @code{org-latex-title-command} to configure
11353 typesetting of keywords as part of front matter.
11356 @cindex #+SUBTITLE (Beamer)
11357 @vindex org-beamer-subtitle-format
11358 Document's subtitle. For typesetting, use @code{org-beamer-subtitle-format}
11359 string. Use @code{org-latex-hyperref-template} to configure document
11360 metadata. Use @code{org-latex-title-command} to configure typesetting of
11361 subtitle as part of front matter.
11364 @node Sectioning Frames and Blocks in Beamer
11365 @subsection Sectioning, Frames and Blocks in Beamer
11367 Org transforms heading levels into Beamer's sectioning elements, frames and
11368 blocks. Any Org tree with a not-too-deep-level nesting should in principle
11369 be exportable as a Beamer presentation.
11373 @vindex org-beamer-frame-level
11374 Org headlines become Beamer frames when the heading level in Org is equal to
11375 @code{org-beamer-frame-level} or @code{H} value in an @code{OPTIONS} line
11376 (@pxref{Export settings}).
11378 @cindex property, BEAMER_ENV
11379 Org overrides headlines to frames conversion for the current tree of an Org
11380 file if it encounters the @code{BEAMER_ENV} property set to @code{frame} or
11381 @code{fullframe}. Org ignores whatever @code{org-beamer-frame-level} happens
11382 to be for that headline level in the Org tree. In Beamer terminology, a
11383 @code{fullframe} is a frame without its title.
11386 @vindex org-beamer-environments-default
11387 @vindex org-beamer-environments-extra
11388 Org exports a Beamer frame's objects as @code{block} environments. Org can
11389 enforce wrapping in special block types when @code{BEAMER_ENV} property is
11390 set@footnote{If @code{BEAMER_ENV} is set, Org export adds
11391 @code{:B_environment:} tag to make it visible. The tag serves as a visual
11392 aid and has no semantic relevance.}. For valid values see
11393 @code{org-beamer-environments-default}. To add more values, see
11394 @code{org-beamer-environments-extra}.
11397 @cindex property, BEAMER_REF
11398 If @code{BEAMER_ENV} is set to @code{appendix}, Org exports the entry as an
11399 appendix. When set to @code{note}, Org exports the entry as a note within
11400 the frame or between frames, depending on the entry's heading level. When
11401 set to @code{noteNH}, Org exports the entry as a note without its title.
11402 When set to @code{againframe}, Org exports the entry with @code{\againframe}
11403 command, which makes setting the @code{BEAMER_REF} property mandatory because
11404 @code{\againframe} needs frame to resume.
11406 When @code{ignoreheading} is set, Org export ignores the entry's headline but
11407 not its content. This is useful for inserting content between frames. It is
11408 also useful for properly closing a @code{column} environment.
11411 @cindex property, BEAMER_ACT
11412 @cindex property, BEAMER_OPT
11413 When @code{BEAMER_ACT} is set for a headline, Org export translates that
11414 headline as an overlay or action specification. When enclosed in square
11415 brackets, Org export makes the overlay specification a default. Use
11416 @code{BEAMER_OPT} to set any options applicable to the current Beamer frame
11417 or block. The Beamer export back-end wraps with appropriate angular or
11418 square brackets. It also adds the @code{fragile} option for any code that may
11419 require a verbatim block.
11421 @cindex property, BEAMER_COL
11422 To create a column on the Beamer slide, use the @code{BEAMER_COL} property
11423 for its headline in the Org file. Set the value of @code{BEAMER_COL} to a
11424 decimal number representing the fraction of the total text width. Beamer
11425 export uses this value to set the column's width and fills the column with
11426 the contents of the Org entry. If the Org entry has no specific environment
11427 defined, Beamer export ignores the heading. If the Org entry has a defined
11428 environment, Beamer export uses the heading as title. Behind the scenes,
11429 Beamer export automatically handles @LaTeX{} column separations for
11430 contiguous headlines. To manually adjust them for any unique configurations
11431 needs, use the @code{BEAMER_ENV} property.
11433 @node Beamer specific syntax
11434 @subsection Beamer specific syntax
11435 Since Org's Beamer export back-end is an extension of the @LaTeX{} back-end,
11436 it recognizes other @LaTeX{} specific syntax---for example, @samp{#+LATEX:}
11437 or @samp{#+ATTR_LATEX:}. @xref{@LaTeX{} export}, for details.
11439 Beamer export wraps the table of contents generated with @code{toc:t}
11440 @code{OPTION} keyword in a @code{frame} environment. Beamer export does not
11441 wrap the table of contents generated with @code{TOC} keyword (@pxref{Table of
11442 contents}). Use square brackets for specifying options.
11445 #+TOC: headlines [currentsection]
11448 Insert Beamer-specific code using the following constructs:
11451 @cindex #+BEGIN_EXPORT beamer
11455 #+BEGIN_EXPORT beamer
11456 Only Beamer export back-end will export this line.
11459 Text @@@@beamer:some code@@@@ within a paragraph.
11462 Inline constructs, such as the last one above, are useful for adding overlay
11463 specifications to objects with @code{bold}, @code{item}, @code{link},
11464 @code{radio-target} and @code{target} types. Enclose the value in angular
11465 brackets and place the specification at the beginning the object as shown in
11469 A *@@@@beamer:<2->@@@@useful* feature
11472 @cindex #+ATTR_BEAMER
11473 Beamer export recognizes the @code{ATTR_BEAMER} keyword with the following
11474 attributes from Beamer configurations: @code{:environment} for changing local
11475 Beamer environment, @code{:overlay} for specifying Beamer overlays in angular
11476 or square brackets, and @code{:options} for inserting optional arguments.
11479 #+ATTR_BEAMER: :environment nonindentlist
11480 - item 1, not indented
11481 - item 2, not indented
11482 - item 3, not indented
11486 #+ATTR_BEAMER: :overlay <+->
11492 #+ATTR_BEAMER: :options [Lagrange]
11493 Let $G$ be a finite group, and let $H$ be
11494 a subgroup of $G$. Then the order of $H$ divides the order of $G$.
11497 @node Editing support
11498 @subsection Editing support
11501 The @code{org-beamer-mode} is a special minor mode for faster editing of
11509 @orgcmd{C-c C-b,org-beamer-select-environment}
11510 The @code{org-beamer-mode} provides this key for quicker selections in Beamer
11511 normal environments, and for selecting the @code{BEAMER_COL} property.
11514 @node A Beamer example
11515 @subsection A Beamer example
11517 Here is an example of an Org document ready for Beamer export.
11520 #+TITLE: Example Presentation
11521 #+AUTHOR: Carsten Dominik
11522 #+OPTIONS: H:2 toc:t num:t
11523 #+LATEX_CLASS: beamer
11524 #+LATEX_CLASS_OPTIONS: [presentation]
11525 #+BEAMER_THEME: Madrid
11526 #+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) %8BEAMER_OPT(Opt)
11528 * This is the first structural section
11531 *** Thanks to Eric Fraga :B_block:
11536 for the first viable Beamer setup in Org
11537 *** Thanks to everyone else :B_block:
11543 for contributing to the discussion
11544 **** This will be formatted as a beamer note :B_note:
11548 ** Frame 2 (where we will not use columns)
11550 Please test this stuff!
11554 @section HTML export
11555 @cindex HTML export
11557 Org mode contains an HTML exporter with extensive HTML formatting compatible
11558 with XHTML 1.0 strict standard.
11561 * HTML Export commands:: Invoking HTML export
11562 * HTML Specific export settings:: Settings for HTML export
11563 * HTML doctypes:: Exporting various (X)HTML flavors
11564 * HTML preamble and postamble:: Inserting preamble and postamble
11565 * Quoting HTML tags:: Using direct HTML in Org files
11566 * Links in HTML export:: Interpreting and formatting links
11567 * Tables in HTML export:: Formatting and modifying tables
11568 * Images in HTML export:: Inserting figures with HTML output
11569 * Math formatting in HTML export:: Handling math equations
11570 * Text areas in HTML export:: Showing an alternate approach, an example
11571 * CSS support:: Styling HTML output
11572 * JavaScript support:: Folding scripting in the web browser
11576 @node HTML Export commands
11577 @subsection HTML export commands
11580 @orgcmd{C-c C-e h h,org-html-export-to-html}
11581 Export as HTML file with a @file{.html} extension. For @file{myfile.org},
11582 Org exports to @file{myfile.html}, overwriting without warning. @kbd{C-c C-e
11583 h o} Exports to HTML and opens it in a web browser.
11585 @orgcmd{C-c C-e h H,org-html-export-as-html}
11586 Exports to a temporary buffer. Does not create a file.
11589 @node HTML Specific export settings
11590 @subsection HTML Specific export settings
11591 HTML export has a number of keywords, similar to the general options settings
11592 described in @ref{Export settings}.
11596 @cindex #+DESCRIPTION (HTML)
11597 This is the document's description, which the HTML exporter inserts it as a
11598 HTML meta tag in the HTML file. For long descriptions, use multiple
11599 @code{#+DESCRIPTION} lines. The exporter takes care of wrapping the lines
11603 @cindex #+HTML_DOCTYPE
11604 @vindex org-html-doctype
11605 Specify the document type, for example: HTML5 (@code{org-html-doctype}).
11607 @item HTML_CONTAINER
11608 @cindex #+HTML_CONTAINER
11609 @vindex org-html-container-element
11610 Specify the HTML container, such as @samp{div}, for wrapping sections and
11611 elements (@code{org-html-container-element}).
11613 @item HTML_LINK_HOME
11614 @cindex #+HTML_LINK_HOME
11615 @vindex org-html-link-home
11616 The URL for home link (@code{org-html-link-home}).
11619 @cindex #+HTML_LINK_UP
11620 @vindex org-html-link-up
11621 The URL for the up link of exported HTML pages (@code{org-html-link-up}).
11624 @cindex #+HTML_MATHJAX
11625 @vindex org-html-mathjax-options
11626 Options for MathJax (@code{org-html-mathjax-options}). MathJax is used to
11627 typeset @LaTeX{} math in HTML documents. @xref{Math formatting in HTML
11628 export}, for an example.
11631 @cindex #+HTML_HEAD
11632 @vindex org-html-head
11633 Arbitrary lines for appending to the HTML document's head
11634 (@code{org-html-head}).
11636 @item HTML_HEAD_EXTRA
11637 @cindex #+HTML_HEAD_EXTRA
11638 @vindex org-html-head-extra
11639 More arbitrary lines for appending to the HTML document's head
11640 (@code{org-html-head-extra}).
11643 @cindex #+KEYWORDS (HTML)
11644 Keywords to describe the document's content. HTML exporter inserts these
11645 keywords as HTML meta tags. For long keywords, use multiple
11646 @code{#+KEYWORDS} lines.
11649 @cindex #+LATEX_HEADER (HTML)
11650 Arbitrary lines for appending to the preamble; HTML exporter appends when
11651 transcoding @LaTeX{} fragments to images (@pxref{Math formatting in HTML
11655 @cindex #+SUBTITLE (HTML)
11656 The document's subtitle. HTML exporter formats subtitle if document type is
11657 @samp{HTML5} and the CSS has a @samp{subtitle} class.
11660 Some of these keywords are explained in more detail in the following sections
11663 @node HTML doctypes
11664 @subsection HTML doctypes
11666 Org can export to various (X)HTML flavors.
11668 @vindex org-html-doctype
11669 @vindex org-html-doctype-alist
11670 Set the @code{org-html-doctype} variable for different (X)HTML variants.
11671 Depending on the variant, the HTML exporter adjusts the syntax of HTML
11672 conversion accordingly. Org includes the following ready-made variants:
11678 ``html4-transitional''
11684 ``xhtml-transitional''
11695 @noindent See the variable @code{org-html-doctype-alist} for details.
11696 The default is ``xhtml-strict''.
11698 @vindex org-html-html5-fancy
11699 @cindex HTML5, export new elements
11700 Org's HTML exporter does not by default enable new block elements introduced
11701 with the HTML5 standard. To enable them, set @code{org-html-html5-fancy} to
11702 non-@code{nil}. Or use an @code{OPTIONS} line in the file to set
11703 @code{html5-fancy}. HTML5 documents can now have arbitrary @code{#+BEGIN}
11704 and @code{#+END} blocks. For example:
11723 #+ATTR_HTML: :controls controls :width 350
11725 #+HTML: <source src="movie.mp4" type="video/mp4">
11726 #+HTML: <source src="movie.ogg" type="video/ogg">
11727 Your browser does not support the video tag.
11734 <video controls="controls" width="350">
11735 <source src="movie.mp4" type="video/mp4">
11736 <source src="movie.ogg" type="video/ogg">
11737 <p>Your browser does not support the video tag.</p>
11741 @vindex org-html-html5-elements
11742 When special blocks do not have a corresponding HTML5 element, the HTML
11743 exporter reverts to standard translation (see
11744 @code{org-html-html5-elements}). For example, @code{#+BEGIN_lederhosen}
11745 exports to @samp{<div class="lederhosen">}.
11747 Special blocks cannot have headlines. For the HTML exporter to wrap the
11748 headline and its contents in @samp{<section>} or @samp{<article>} tags, set
11749 the @code{HTML_CONTAINER} property for the headline.
11751 @node HTML preamble and postamble
11752 @subsection HTML preamble and postamble
11753 @vindex org-html-preamble
11754 @vindex org-html-postamble
11755 @vindex org-html-preamble-format
11756 @vindex org-html-postamble-format
11757 @vindex org-html-validation-link
11758 @vindex org-export-creator-string
11759 @vindex org-export-time-stamp-file
11761 The HTML exporter has delineations for preamble and postamble. The default
11762 value for @code{org-html-preamble} is @code{t}, which makes the HTML exporter
11763 insert the preamble. See the variable @code{org-html-preamble-format} for
11766 Set @code{org-html-preamble} to a string to override the default format
11767 string. If the string is a function, the HTML exporter expects the function
11768 to return a string upon execution. The HTML exporter inserts this string in
11769 the preamble. The HTML exporter will not insert a preamble if
11770 @code{org-html-preamble} is set @code{nil}.
11772 The default value for @code{org-html-postamble} is @code{auto}, which makes
11773 the HTML exporter build a postamble from looking up author's name, email
11774 address, creator's name, and date. Set @code{org-html-postamble} to @code{t}
11775 to insert the postamble in the format specified in the
11776 @code{org-html-postamble-format} variable. The HTML exporter will not insert
11777 a postamble if @code{org-html-postamble} is set to @code{nil}.
11779 @node Quoting HTML tags
11780 @subsection Quoting HTML tags
11782 The HTML export back-end transforms @samp{<} and @samp{>} to @samp{<} and
11783 @samp{>}. To include raw HTML code in the Org file so the HTML export
11784 back-end can insert that HTML code in the output, use this inline syntax:
11785 @samp{@@@@html:}. For example: @samp{@@@@html:<b>@@@@bold
11786 text@@@@html:</b>@@@@}. For larger raw HTML code blocks, use these HTML
11787 export code blocks:
11790 @cindex #+BEGIN_EXPORT html
11792 #+HTML: Literal HTML code for export
11796 @cindex #+BEGIN_EXPORT html
11799 #+BEGIN_EXPORT html
11800 All lines between these markers are exported literally
11805 @node Links in HTML export
11806 @subsection Links in HTML export
11808 @cindex links, in HTML export
11809 @cindex internal links, in HTML export
11810 @cindex external links, in HTML export
11811 @vindex org-html-link-org-files-as-html
11812 The HTML export back-end transforms Org's internal links (@pxref{Internal
11813 links}) to equivalent HTML links in the output. The back-end similarly
11814 handles Org's automatic links created by radio targets (@pxref{Radio
11815 targets}) similarly. For Org links to external files, the back-end
11816 transforms the links to @emph{relative} paths.
11818 For Org links to other @file{.org} files, the back-end automatically changes
11819 the file extension to @file{.html} and makes file paths relative. If the
11820 @file{.org} files have an equivalent @file{.html} version at the same
11821 location, then the converted links should work without any further manual
11822 intervention. However, to disable this automatic path translation, set
11823 @code{org-html-link-org-files-as-html} to @code{nil}. When disabled, the
11824 HTML export back-end substitutes the @samp{id:}-based links in the HTML
11825 output. For more about linking files when publishing to a directory,
11826 @pxref{Publishing links}.
11828 Org files can also have special directives to the HTML export back-end. For
11829 example, by using @code{#+ATTR_HTML} lines to specify new format attributes
11830 to @code{<a>} or @code{<img>} tags. This example shows changing the link's
11831 @code{title} and @code{style}:
11833 @cindex #+ATTR_HTML
11835 #+ATTR_HTML: :title The Org mode homepage :style color:red;
11836 [[http://orgmode.org]]
11839 @node Tables in HTML export
11840 @subsection Tables in HTML export
11841 @cindex tables, in HTML
11842 @vindex org-html-table-default-attributes
11844 The HTML export back-end uses @code{org-html-table-default-attributes} when
11845 exporting Org tables to HTML. By default, the exporter does not draw frames
11846 and cell borders. To change for this for a table, use the following lines
11847 before the table in the Org file:
11850 @cindex #+ATTR_HTML
11852 #+CAPTION: This is a table with lines around and between cells
11853 #+ATTR_HTML: :border 2 :rules all :frame border
11856 The HTML export back-end preserves column groupings in Org tables
11857 (@pxref{Column groups}) when exporting to HTML.
11859 Additional options for customizing tables for HTML export.
11862 @vindex org-html-table-align-individual-fields
11863 @item org-html-table-align-individual-fields
11864 Non-@code{nil} attaches style attributes for alignment to each table field.
11866 @vindex org-html-table-caption-above
11867 @item org-html-table-caption-above
11868 Non-@code{nil} places caption string at the beginning of the table.
11870 @vindex org-html-table-data-tags
11871 @item org-html-table-data-tags
11872 Opening and ending tags for table data fields.
11874 @vindex org-html-table-default-attributes
11875 @item org-html-table-default-attributes
11876 Default attributes and values for table tags.
11878 @vindex org-html-table-header-tags
11879 @item org-html-table-header-tags
11880 Opening and ending tags for table's header fields.
11882 @vindex org-html-table-row-tags
11883 @item org-html-table-row-tags
11884 Opening and ending tags for table rows.
11886 @vindex org-html-table-use-header-tags-for-first-column
11887 @item org-html-table-use-header-tags-for-first-column
11888 Non-@code{nil} formats column one in tables with header tags.
11891 @node Images in HTML export
11892 @subsection Images in HTML export
11894 @cindex images, inline in HTML
11895 @cindex inlining images in HTML
11896 @vindex org-html-inline-images
11898 The HTML export back-end has features to convert Org image links to HTML
11899 inline images and HTML clickable image links.
11901 When the link in the Org file has no description, the HTML export back-end by
11902 default in-lines that image. For example: @samp{[[file:myimg.jpg]]} is
11903 in-lined, while @samp{[[file:myimg.jpg][the image]]} links to the text,
11906 For more details, see the variable @code{org-html-inline-images}.
11908 On the other hand, if the description part of the Org link is itself another
11909 link, such as @code{file:} or @code{http:} URL pointing to an image, the HTML
11910 export back-end in-lines this image and links to the main image. This Org
11911 syntax enables the back-end to link low-resolution thumbnail to the
11912 high-resolution version of the image, as shown in this example:
11915 [[file:highres.jpg][file:thumb.jpg]]
11918 To change attributes of in-lined images, use @code{#+ATTR_HTML} lines in the
11919 Org file. This example shows realignment to right, and adds @code{alt} and
11920 @code{title} attributes in support of text viewers and modern web accessibility
11924 @cindex #+ATTR_HTML
11926 #+CAPTION: A black cat stalking a spider
11927 #+ATTR_HTML: :alt cat/spider image :title Action! :align right
11932 The HTML export back-end copies the @code{http} links from the Org file as
11935 @node Math formatting in HTML export
11936 @subsection Math formatting in HTML export
11940 @cindex imagemagick
11942 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two
11943 different ways on HTML pages. The default is to use
11944 @uref{http://www.mathjax.org, MathJax} which should work out of the box with
11945 Org@footnote{By default Org loads MathJax from @uref{https://cdnjs.com, cdnjs.com} as
11946 recommended by @uref{http://www.mathjax.org, MathJax}.}. Some MathJax display
11947 options can be configured via @code{org-html-mathjax-options}, or in the
11948 buffer. For example, with the following settings,
11950 #+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
11951 #+HTML_MATHJAX: cancel.js noErrors.js
11953 equation labels will be displayed on the left margin and equations will be
11954 five ems from the left margin. In addition, it loads the two MathJax
11955 extensions @samp{cancel.js} and @samp{noErrors.js}@footnote{See
11956 @uref{http://docs.mathjax.org/en/latest/tex.html#tex-extensions, TeX and
11957 LaTeX extensions} in the @uref{http://docs.mathjax.org, MathJax manual} to learn about extensions.}.
11959 @noindent See the docstring of
11960 @code{org-html-mathjax-options} for all supported variables. The MathJax
11961 template can be configure via @code{org-html-mathjax-template}.
11963 If you prefer, you can also request that @LaTeX{} fragments are processed
11964 into small images that will be inserted into the browser page. Before the
11965 availability of MathJax, this was the default method for Org files. This
11966 method requires that the @file{dvipng} program, @file{dvisvgm} or
11967 @file{imagemagick} suite is available on your system. You can still get
11968 this processing with
11971 #+OPTIONS: tex:dvipng
11975 #+OPTIONS: tex:dvisvgm
11981 #+OPTIONS: tex:imagemagick
11984 @node Text areas in HTML export
11985 @subsection Text areas in HTML export
11987 @cindex text areas, in HTML
11988 Before Org mode's Babel, one popular approach to publishing code in HTML was
11989 by using @code{:textarea}. The advantage of this approach was that copying
11990 and pasting was built into browsers with simple JavaScript commands. Even
11991 editing before pasting was made simple.
11993 The HTML export back-end can create such text areas. It requires an
11994 @code{#+ATTR_HTML:} line as shown in the example below with the
11995 @code{:textarea} option. This must be followed by either an
11996 @code{example} or a @code{src} code block. Other Org block types will not
11997 honor the @code{:textarea} option.
11999 By default, the HTML export back-end creates a text area 80 characters wide
12000 and height just enough to fit the content. Override these defaults with
12001 @code{:width} and @code{:height} options on the @code{#+ATTR_HTML:} line.
12004 #+ATTR_HTML: :textarea t :width 40
12006 (defun org-xor (a b)
12014 @subsection CSS support
12015 @cindex CSS, for HTML export
12016 @cindex HTML export, CSS
12018 @vindex org-html-todo-kwd-class-prefix
12019 @vindex org-html-tag-class-prefix
12020 You can modify the CSS style definitions for the exported file. The HTML
12021 exporter assigns the following special CSS classes@footnote{If the classes on
12022 TODO keywords and tags lead to conflicts, use the variables
12023 @code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to
12024 make them unique.} to appropriate parts of the document---your style
12025 specifications may change these, in addition to any of the standard classes
12026 like for headlines, tables, etc.
12028 p.author @r{author information, including email}
12029 p.date @r{publishing date}
12030 p.creator @r{creator info, about org mode version}
12031 .title @r{document title}
12032 .subtitle @r{document subtitle}
12033 .todo @r{TODO keywords, all not-done states}
12034 .done @r{the DONE keywords, all states that count as done}
12035 .WAITING @r{each TODO keyword also uses a class named after itself}
12036 .timestamp @r{timestamp}
12037 .timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED}
12038 .timestamp-wrapper @r{span around keyword plus timestamp}
12039 .tag @r{tag in a headline}
12040 ._HOME @r{each tag uses itself as a class, "@@" replaced by "_"}
12041 .target @r{target for links}
12042 .linenr @r{the line number in a code example}
12043 .code-highlighted @r{for highlighting referenced code lines}
12044 div.outline-N @r{div for outline level N (headline plus text))}
12045 div.outline-text-N @r{extra div for text at outline level N}
12046 .section-number-N @r{section number in headlines, different for each level}
12047 .figure-number @r{label like "Figure 1:"}
12048 .table-number @r{label like "Table 1:"}
12049 .listing-number @r{label like "Listing 1:"}
12050 div.figure @r{how to format an in-lined image}
12051 pre.src @r{formatted source code}
12052 pre.example @r{normal example}
12053 p.verse @r{verse paragraph}
12054 div.footnotes @r{footnote section headline}
12055 p.footnote @r{footnote definition paragraph, containing a footnote}
12056 .footref @r{a footnote reference number (always a <sup>)}
12057 .footnum @r{footnote number in footnote definition (always <sup>)}
12058 .org-svg @r{default class for a linked @file{.svg} image}
12061 @vindex org-html-style-default
12062 @vindex org-html-head-include-default-style
12063 @vindex org-html-head
12064 @vindex org-html-head-extra
12065 @cindex #+HTML_INCLUDE_STYLE
12066 The HTML export back-end includes a compact default style in each exported
12067 HTML file. To override the default style with another style, use these
12068 keywords in the Org file. They will replace the global defaults the HTML
12071 @cindex #+HTML_HEAD
12072 @cindex #+HTML_HEAD_EXTRA
12074 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
12075 #+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
12078 To just turn off the default style, customize
12079 @code{org-html-head-include-default-style} variable, or use this option line in
12083 #+OPTIONS: html-style:nil
12087 For longer style definitions, either use several @code{#+HTML_HEAD} and
12088 @code{#+HTML_HEAD_EXTRA} lines, or use @code{<style>} @code{</style>} blocks
12089 around them. Both of these approaches can avoid referring to an external
12092 In order to add styles to a sub-tree, use the @code{:HTML_CONTAINER_CLASS:}
12093 property to assign a class to the tree. In order to specify CSS styles for a
12094 particular headline, you can use the id specified in a @code{:CUSTOM_ID:}
12097 Never change the @code{org-html-style-default} constant. Instead use other
12098 simpler ways of customizing as described above.
12101 @c FIXME: More about header and footer styles
12102 @c FIXME: Talk about links and targets.
12104 @node JavaScript support
12105 @subsection JavaScript supported display of web pages
12107 @cindex Rose, Sebastian
12108 Sebastian Rose has written a JavaScript program especially designed to
12109 enhance the web viewing experience of HTML files created with Org. This
12110 program enhances large files in two different ways of viewing. One is an
12111 @emph{Info}-like mode where each section is displayed separately and
12112 navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys
12113 as well, press @kbd{?} for an overview of the available keys). The second
12114 one has a @emph{folding} view, much like Org provides inside Emacs. The
12115 script is available at @url{http://orgmode.org/org-info.js} and the
12116 documentation at @url{http://orgmode.org/worg/code/org-info-js/}. The script
12117 is hosted on @url{http://orgmode.org}, but for reliability, prefer installing
12118 it on your own web server.
12120 To use this program, just add this line to the Org file:
12122 @cindex #+INFOJS_OPT
12124 #+INFOJS_OPT: view:info toc:nil
12128 The HTML header now has the code needed to automatically invoke the script.
12129 For setting options, use the syntax from the above line for options described
12133 path: @r{The path to the script. The default grabs the script from}
12134 @r{@url{http://orgmode.org/org-info.js}, but you might want to have}
12135 @r{a local copy and use a path like @samp{../scripts/org-info.js}.}
12136 view: @r{Initial view when the website is first shown. Possible values are:}
12137 info @r{Info-like interface with one section per page.}
12138 overview @r{Folding interface, initially showing only top-level.}
12139 content @r{Folding interface, starting with all headlines visible.}
12140 showall @r{Folding interface, all headlines and text visible.}
12141 sdepth: @r{Maximum headline level that will still become an independent}
12142 @r{section for info and folding modes. The default is taken from}
12143 @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).}
12144 @r{If this is smaller than in @code{org-export-headline-levels}, each}
12145 @r{info/folding section can still contain child headlines.}
12146 toc: @r{Should the table of contents @emph{initially} be visible?}
12147 @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}
12148 tdepth: @r{The depth of the table of contents. The defaults are taken from}
12149 @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}
12150 ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?}
12151 @r{If yes, the toc will never be displayed as a section.}
12152 ltoc: @r{Should there be short contents (children) in each section?}
12153 @r{Make this @code{above} if the section should be above initial text.}
12154 mouse: @r{Headings are highlighted when the mouse is over them. Should be}
12155 @r{@samp{underline} (default) or a background color like @samp{#cccccc}.}
12156 buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the}
12157 @r{default), only one such button will be present.}
12160 @vindex org-html-infojs-options
12161 @vindex org-html-use-infojs
12162 You can choose default values for these options by customizing the variable
12163 @code{org-html-infojs-options}. If you want the script to always apply to
12164 your pages, configure the variable @code{org-html-use-infojs}.
12166 @node @LaTeX{} export
12167 @section @LaTeX{} export
12168 @cindex @LaTeX{} export
12171 The @LaTeX{} export back-end can handle complex documents, incorporate
12172 standard or custom @LaTeX{} document classes, generate documents using
12173 alternate @LaTeX{} engines, and produce fully linked PDF files with indexes,
12174 bibliographies, and tables of contents, destined for interactive online
12175 viewing or high-quality print publication.
12177 While the details are covered in-depth in this section, here are some quick
12178 references to variables for the impatient: for engines, see
12179 @code{org-latex-compiler}; for build sequences, see
12180 @code{org-latex-pdf-process}; for packages, see
12181 @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.
12183 An important note about the @LaTeX{} export back-end: it is sensitive to
12184 blank lines in the Org document. That's because @LaTeX{} itself depends on
12185 blank lines to tell apart syntactical elements, such as paragraphs.
12188 * @LaTeX{} export commands:: For producing @LaTeX{} and PDF documents.
12189 * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end.
12190 * @LaTeX{} header and sectioning:: For file structure.
12191 * Quoting @LaTeX{} code:: Directly in the Org document.
12192 * Tables in @LaTeX{} export:: Attributes specific to tables.
12193 * Images in @LaTeX{} export:: Attributes specific to images.
12194 * Plain lists in @LaTeX{} export:: Attributes specific to lists.
12195 * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks.
12196 * Example blocks in @LaTeX{} export:: Attributes specific to example blocks.
12197 * Special blocks in @LaTeX{} export:: Attributes specific to special blocks.
12198 * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules.
12201 @node @LaTeX{} export commands
12202 @subsection @LaTeX{} export commands
12205 @orgcmd{C-c C-e l l,org-latex-export-to-latex}
12206 Export as @LaTeX{} file with a @file{.tex} extension. For @file{myfile.org},
12207 Org exports to @file{myfile.tex}, overwriting without warning. @kbd{C-c C-e
12208 l l} Exports to @LaTeX{} file.
12210 @orgcmd{C-c C-e l L,org-latex-export-as-latex}
12211 Export to a temporary buffer. Do not create a file.
12212 @orgcmd{C-c C-e l p,org-latex-export-to-pdf}
12213 Export as @LaTeX{} file and convert it to PDF file.
12215 Export as @LaTeX{} file and convert it to PDF, then open the PDF using the default viewer.
12218 @vindex org-latex-compiler
12219 @vindex org-latex-bibtex-compiler
12220 @vindex org-latex-default-packages-alist
12221 The @LaTeX{} export back-end can use any of these @LaTeX{} engines:
12222 @samp{pdflatex}, @samp{xelatex}, and @samp{lualatex}. These engines compile
12223 @LaTeX{} files with different compilers, packages, and output options. The
12224 @LaTeX{} export back-end finds the compiler version to use from
12225 @code{org-latex-compiler} variable or the @code{#+LATEX_COMPILER} keyword in
12226 the Org file. See the docstring for the
12227 @code{org-latex-default-packages-alist} for loading packages with certain
12228 compilers. Also see @code{org-latex-bibtex-compiler} to set the bibliography
12229 compiler@footnote{This does not allow setting different bibliography
12230 compilers for different files. However, ``smart'' @LaTeX{} compilation
12231 systems, such as @samp{latexmk}, can select the correct bibliography
12234 @node @LaTeX{} specific export settings
12235 @subsection @LaTeX{} specific export settings
12237 The @LaTeX{} export back-end has several additional keywords for customizing
12238 @LaTeX{} output. Setting these keywords works similar to the general options
12239 (@pxref{Export settings}).
12243 @cindex #+DESCRIPTION (@LaTeX{})
12244 The document's description. The description along with author name,
12245 keywords, and related file metadata are inserted in the output file by the
12246 @samp{hyperref} package. See @code{org-latex-hyperref-template} for
12247 customizing metadata items. See @code{org-latex-title-command} for
12248 typesetting description into the document's front matter. Use multiple
12249 @code{#+DESCRIPTION} lines for long descriptions.
12252 @cindex #+LATEX_CLASS
12253 @vindex org-latex-default-class
12254 @vindex org-latex-classes
12255 This is @LaTeX{} document class, such as @code{article}, @code{report},
12256 @code{book}, and so on, which contain predefined preamble and headline level
12257 mapping that the @LaTeX{} export back-end needs. The back-end reads the
12258 default class name from the @code{org-latex-default-class} variable. Org has
12259 @code{article} as the default class. A valid default class must be an
12260 element of @code{org-latex-classes}.
12262 @item LATEX_CLASS_OPTIONS
12263 @cindex #+LATEX_CLASS_OPTIONS
12264 Options the @LaTeX{} export back-end uses when calling the @LaTeX{} document
12267 @item LATEX_COMPILER
12268 @cindex #+LATEX_COMPILER
12269 @vindex org-latex-compiler
12270 The compiler, such as @samp{pdflatex}, @samp{xelatex}, @samp{lualatex}, for
12271 producing the PDF (@code{org-latex-compiler}).
12274 @cindex #+LATEX_HEADER
12275 @vindex org-latex-classes
12276 Arbitrary lines to add to the document's preamble, before the @samp{hyperref}
12277 settings. See @code{org-latex-classes} for adjusting the structure and order
12278 of the @LaTeX{} headers.
12280 @item LATEX_HEADER_EXTRA
12281 @cindex #+LATEX_HEADER_EXTRA
12282 @vindex org-latex-classes
12283 Arbitrary lines to add to the document's preamble, before the @samp{hyperref}
12284 settings. See @code{org-latex-classes} for adjusting the structure and order
12285 of the @LaTeX{} headers.
12288 @cindex #+KEYWORDS (@LaTeX{})
12289 The keywords for the document. The description along with author name,
12290 keywords, and related file metadata are inserted in the output file by the
12291 @samp{hyperref} package. See @code{org-latex-hyperref-template} for
12292 customizing metadata items. See @code{org-latex-title-command} for
12293 typesetting description into the document's front matter. Use multiple
12294 @code{#+KEYWORDS} lines if necessary.
12297 @cindex #+SUBTITLE (@LaTeX{})
12298 @vindex org-latex-subtitle-separate
12299 @vindex org-latex-subtitle-format
12300 The document's subtitle. It is typeset as per
12301 @code{org-latex-subtitle-format}. If @code{org-latex-subtitle-separate} is
12302 non-@code{nil}, it is typed as part of the @samp{\title}-macro. See
12303 @code{org-latex-hyperref-template} for customizing metadata items. See
12304 @code{org-latex-title-command} for typesetting description into the
12305 document's front matter.
12308 The following sections have further details.
12310 @node @LaTeX{} header and sectioning
12311 @subsection @LaTeX{} header and sectioning structure
12312 @cindex @LaTeX{} class
12313 @cindex @LaTeX{} sectioning structure
12314 @cindex @LaTeX{} header
12315 @cindex header, for @LaTeX{} files
12316 @cindex sectioning structure, for @LaTeX{} export
12318 The @LaTeX{} export back-end converts the first three of Org's outline levels
12319 into @LaTeX{} headlines. The remaining Org levels are exported as
12320 @code{itemize} or @code{enumerate} lists. To change this globally for the
12321 cut-off point between levels and lists, (@pxref{Export settings}).
12323 By default, the @LaTeX{} export back-end uses the @code{article} class.
12325 @vindex org-latex-default-class
12326 @vindex org-latex-classes
12327 @vindex org-latex-default-packages-alist
12328 @vindex org-latex-packages-alist
12329 To change the default class globally, edit @code{org-latex-default-class}.
12330 To change the default class locally in an Org file, add option lines
12331 @code{#+LATEX_CLASS: myclass}. To change the default class for just a part
12332 of the Org file, set a sub-tree property, @code{EXPORT_LATEX_CLASS}. The
12333 class name entered here must be valid member of @code{org-latex-classes}.
12334 This variable defines a header template for each class into which the
12335 exporter splices the values of @code{org-latex-default-packages-alist} and
12336 @code{org-latex-packages-alist}. Use the same three variables to define
12337 custom sectioning or custom classes.
12339 @cindex #+LATEX_CLASS
12340 @cindex #+LATEX_CLASS_OPTIONS
12341 @cindex property, EXPORT_LATEX_CLASS
12342 @cindex property, EXPORT_LATEX_CLASS_OPTIONS
12343 The @LaTeX{} export back-end sends the @code{LATEX_CLASS_OPTIONS} keyword and
12344 @code{EXPORT_LATEX_CLASS_OPTIONS} property as options to the @LaTeX{}
12345 @code{\documentclass} macro. The options and the syntax for specifying them,
12346 including enclosing them in square brackets, follow @LaTeX{} conventions.
12349 #+LATEX_CLASS_OPTIONS: [a4paper,11pt,twoside,twocolumn]
12352 @cindex #+LATEX_HEADER
12353 @cindex #+LATEX_HEADER_EXTRA
12354 The @LaTeX{} export back-end appends values from @code{LATEX_HEADER} and
12355 @code{LATEX_HEADER_EXTRA} keywords to the @LaTeX{} header. The docstring for
12356 @code{org-latex-classes} explains in more detail. Also note that @LaTeX{}
12357 export back-end does not append @code{LATEX_HEADER_EXTRA} to the header when
12358 previewing @LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).
12360 A sample Org file with the above headers:
12363 #+LATEX_CLASS: article
12364 #+LATEX_CLASS_OPTIONS: [a4paper]
12365 #+LATEX_HEADER: \usepackage@{xyz@}
12373 @node Quoting @LaTeX{} code
12374 @subsection Quoting @LaTeX{} code
12376 The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code,
12377 @pxref{Embedded @LaTeX{}}. There are three ways to embed such code in the
12378 Org file and they all use different quoting syntax.
12380 Inserting in-line quoted with @ symbols:
12381 @cindex inline, in @LaTeX{} export
12383 Code embedded in-line @@@@latex:any arbitrary LaTeX code@@@@ in a paragraph.
12386 Inserting as one or more keyword lines in the Org file:
12389 #+LATEX: any arbitrary LaTeX code
12392 Inserting as an export block in the Org file, where the back-end exports any
12393 code between begin and end markers:
12394 @cindex #+BEGIN_EXPORT latex
12396 #+BEGIN_EXPORT latex
12397 any arbitrary LaTeX code
12401 @node Tables in @LaTeX{} export
12402 @subsection Tables in @LaTeX{} export
12403 @cindex tables, in @LaTeX{} export
12404 @cindex #+ATTR_LATEX, in tables
12406 The @LaTeX{} export back-end can pass several @LaTeX{} attributes for table
12407 contents and layout. Besides specifying label and caption (@pxref{Images and
12408 tables}), the other valid @LaTeX{} attributes include:
12412 @vindex org-latex-default-table-mode
12413 The @LaTeX{} export back-end wraps the table differently depending on the
12414 mode for accurate rendering of math symbols. Mode is either @code{table},
12415 @code{math}, @code{inline-math} or @code{verbatim}. For @code{math} or
12416 @code{inline-math} mode, @LaTeX{} export back-end wraps the table in a math
12417 environment, but every cell in it is exported as-is. The @LaTeX{} export
12418 back-end determines the default mode from
12419 @code{org-latex-default-table-mode}. For , The @LaTeX{} export back-end
12420 merges contiguous tables in the same mode into a single environment.
12422 @vindex org-latex-default-table-environment
12423 Set the default @LaTeX{} table environment for the @LaTeX{} export back-end
12424 to use when exporting Org tables. Common @LaTeX{} table environments are
12425 provided by these packages: @code{tabularx}, @code{longtable}, @code{array},
12426 @code{tabu}, and @code{bmatrix}. For packages, such as @code{tabularx} and
12427 @code{tabu}, or any newer replacements, include them in the
12428 @code{org-latex-packages-alist} variable so the @LaTeX{} export back-end can
12429 insert the appropriate load package headers in the converted @LaTeX{} file.
12430 Look in the docstring for the @code{org-latex-packages-alist} variable for
12431 configuring these packages for @LaTeX{} snippet previews, if any.
12433 Use @code{#+CAPTION} keyword to set a simple caption for a table
12434 (@pxref{Images and tables}). For custom captions, use @code{:caption}
12435 attribute, which accepts raw @LaTeX{} code. @code{:caption} value overrides
12436 @code{#+CAPTION} value.
12439 The table environments by default are not floats in @LaTeX{}. To make them
12440 floating objects use @code{:float} with one of the following options:
12441 @code{sideways}, @code{multicolumn}, @code{t}, and @code{nil}. Note that
12442 @code{sidewaystable} has been deprecated since Org 8.3. @LaTeX{} floats can
12443 also have additional layout @code{:placement} attributes. These are the
12444 usual @code{[h t b p ! H]} permissions specified in square brackets. Note
12445 that for @code{:float sideways} tables, the @LaTeX{} export back-end ignores
12446 @code{:placement} attributes.
12450 The @LaTeX{} export back-end uses these attributes for regular tables to set
12451 their alignments, fonts, and widths.
12453 When @code{:spread} is non-@code{nil}, the @LaTeX{} export back-end spreads
12454 or shrinks the table by the @code{:width} for @code{tabu} and @code{longtabu}
12455 environments. @code{:spread} has no effect if @code{:width} is not set.
12459 @vindex org-latex-tables-booktabs
12460 @vindex org-latex-tables-centered
12461 All three commands are toggles. @code{:booktabs} brings in modern
12462 typesetting enhancements to regular tables. The @code{booktabs} package has
12463 to be loaded through @code{org-latex-packages-alist}. @code{:center} is for
12464 centering the table. @code{:rmlines} removes all but the very first
12465 horizontal line made of ASCII characters from "table.el" tables only.
12467 @itemx :math-suffix
12468 @itemx :math-arguments
12469 The @LaTeX{} export back-end inserts @code{:math-prefix} string value in a
12470 math environment before the table. The @LaTeX{} export back-end inserts
12471 @code{:math-suffix} string value in a math environment after the table. The
12472 @LaTeX{} export back-end inserts @code{:math-arguments} string value between
12473 the macro name and the table's contents. @code{:math-arguments} comes in use
12474 for matrix macros that require more than one argument, such as
12475 @code{qbordermatrix}.
12478 @LaTeX{} table attributes help formatting tables for a wide range of
12479 situations, such as matrix product or spanning multiple pages:
12482 #+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l
12486 #+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
12489 #+ATTR_LATEX: :mode math :environment bmatrix
12494 Set the caption with the @LaTeX{} command
12495 @code{\bicaption@{HeadingA@}@{HeadingB@}}:
12498 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
12504 @node Images in @LaTeX{} export
12505 @subsection Images in @LaTeX{} export
12506 @cindex images, inline in @LaTeX{}
12507 @cindex inlining images in @LaTeX{}
12508 @cindex #+ATTR_LATEX, in images
12510 The @LaTeX{} export back-end processes image links in Org files that do not
12511 have descriptions, such as these links @samp{[[file:img.jpg]]} or
12512 @samp{[[./img.jpg]]}, as direct image insertions in the final PDF output. In
12513 the PDF, they are no longer links but actual images embedded on the page.
12514 The @LaTeX{} export back-end uses @code{\includegraphics} macro to insert the
12515 image. But for TikZ@footnote{@url{http://sourceforge.net/projects/pgf/}}
12516 images, the back-end uses an @code{\input} macro wrapped within
12517 a @code{tikzpicture} environment.
12519 For specifying image @code{:width}, @code{:height}, and other
12520 @code{:options}, use this syntax:
12523 #+ATTR_LATEX: :width 5cm :options angle=90
12524 [[./img/sed-hr4049.pdf]]
12527 For custom commands for captions, use the @code{:caption} attribute. It will
12528 override the default @code{#+CAPTION} value:
12531 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
12532 [[./img/sed-hr4049.pdf]]
12535 When captions follow the method as described in @ref{Images and tables}, the
12536 @LaTeX{} export back-end wraps the picture in a floating @code{figure}
12537 environment. To float an image without specifying a caption, set the
12538 @code{:float} attribute to one of the following:
12541 @code{t}: for a standard @samp{figure} environment; used by default whenever
12542 an image has a caption.
12544 @code{multicolumn}: to span the image across multiple columns of a page; the
12545 back-end wraps the image in a @code{figure*} environment.
12547 @code{wrap}: for text to flow around the image on the right; the figure
12548 occupies the left half of the page.
12550 @code{sideways}: for a new page with the image sideways, rotated ninety
12551 degrees, in a @code{sidewaysfigure} environment; overrides @code{:placement}
12554 @code{nil}: to avoid a @code{:float} even if using a caption.
12557 Use the @code{placement} attribute to modify a floating environment's placement.
12560 #+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement
12561 @{r@}@{0.4\textwidth@} [[./img/hst.png]]
12564 @vindex org-latex-images-centered
12565 @cindex center image (@LaTeX{} export)
12566 @cindex image, centering (@LaTeX{} export)
12568 The @LaTeX{} export back-end centers all images by default. Setting
12569 @code{:center} attribute to @code{nil} disables centering. To disable
12570 centering globally, set @code{org-latex-images-centered} to @code{t}.
12572 Set the @code{:comment-include} attribute to non-@code{nil} value for the
12573 @LaTeX{} export back-end to comment out the @code{\includegraphics} macro.
12575 @node Plain lists in @LaTeX{} export
12576 @subsection Plain lists in @LaTeX{} export
12577 @cindex plain lists, in @LaTeX{} export
12578 @cindex #+ATTR_LATEX, in plain lists
12580 The @LaTeX{} export back-end accepts the @code{:environment} and
12581 @code{:options} attributes for plain lists. Both attributes work together
12582 for customizing lists, as shown in the examples:
12585 #+LATEX_HEADER: \usepackage[inline]@{enumitem@}
12586 Some ways to say "Hello":
12587 #+ATTR_LATEX: :environment itemize*
12588 #+ATTR_LATEX: :options [label=@{@}, itemjoin=@{,@}, itemjoin*=@{, and@}]
12594 Since @LaTeX{} supports only four levels of nesting for lists, use an
12595 external package, such as @samp{enumitem} in @LaTeX{}, for levels deeper than
12599 #+LATEX_HEADER: \usepackage@{enumitem@}
12600 #+LATEX_HEADER: \renewlist@{itemize@}@{itemize@}@{9@}
12601 #+LATEX_HEADER: \setlist[itemize]@{label=$\circ$@}
12609 @node Source blocks in @LaTeX{} export
12610 @subsection Source blocks in @LaTeX{} export
12611 @cindex source blocks, in @LaTeX{} export
12612 @cindex #+ATTR_LATEX, in source blocks
12614 The @LaTeX{} export back-end can make source code blocks into floating
12615 objects through the attributes @code{:float} and @code{:options}. For
12620 @code{t}: makes a source block float; by default floats any source block with
12623 @code{multicolumn}: spans the source block across multiple columns of a page.
12625 @code{nil}: avoids a @code{:float} even if using a caption; useful for
12626 source code blocks that may not fit on a page.
12630 #+ATTR_LATEX: :float nil
12631 #+BEGIN_SRC emacs-lisp
12632 Lisp code that may not fit in a single page.
12636 @vindex org-latex-listings-options
12637 @vindex org-latex-minted-options
12638 The @LaTeX{} export back-end passes string values in @code{:options} to
12639 @LaTeX{} packages for customization of that specific source block. In the
12640 example below, the @code{:options} are set for Minted. Minted is a source
12641 code highlighting @LaTeX{}package with many configurable options.
12644 #+ATTR_LATEX: :options commentstyle=\bfseries
12645 #+BEGIN_SRC emacs-lisp
12647 (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2)))))
12651 To apply similar configuration options for all source blocks in a file, use
12652 the @code{org-latex-listings-options} and @code{org-latex-minted-options}
12655 @node Example blocks in @LaTeX{} export
12656 @subsection Example blocks in @LaTeX{} export
12657 @cindex example blocks, in @LaTeX{} export
12658 @cindex verbatim blocks, in @LaTeX{} export
12659 @cindex #+ATTR_LATEX, in example blocks
12661 The @LaTeX{} export back-end wraps the contents of example blocks in a
12662 @samp{verbatim} environment. To change this behavior to use another
12663 environment globally, specify an appropriate export filter (@pxref{Advanced
12664 configuration}). To change this behavior to use another environment for each
12665 block, use the @code{:environment} parameter to specify a custom environment.
12668 #+ATTR_LATEX: :environment myverbatim
12670 This sentence is false.
12674 @node Special blocks in @LaTeX{} export
12675 @subsection Special blocks in @LaTeX{} export
12676 @cindex special blocks, in @LaTeX{} export
12677 @cindex abstract, in @LaTeX{} export
12678 @cindex proof, in @LaTeX{} export
12679 @cindex #+ATTR_LATEX, in special blocks
12682 For other special blocks in the Org file, the @LaTeX{} export back-end makes
12683 a special environment of the same name. The back-end also takes
12684 @code{:options}, if any, and appends as-is to that environment's opening
12685 string. For example:
12689 We demonstrate how to solve the Syracuse problem.
12692 #+ATTR_LATEX: :options [Proof of important theorem]
12695 Therefore, any even number greater than 2 is the sum of two primes.
12704 We demonstrate how to solve the Syracuse problem.
12707 \begin@{proof@}[Proof of important theorem]
12709 Therefore, any even number greater than 2 is the sum of two primes.
12713 If you need to insert a specific caption command, use @code{:caption}
12714 attribute. It will override standard @code{#+CAPTION} value, if any. For
12718 #+ATTR_LATEX: :caption \MyCaption@{HeadingA@}
12724 @node Horizontal rules in @LaTeX{} export
12725 @subsection Horizontal rules in @LaTeX{} export
12726 @cindex horizontal rules, in @LaTeX{} export
12727 @cindex #+ATTR_LATEX, in horizontal rules
12729 The @LaTeX{} export back-end converts horizontal rules by the specified
12730 @code{:width} and @code{:thickness} attributes. For example:
12733 #+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
12737 @node Markdown export
12738 @section Markdown export
12739 @cindex Markdown export
12741 The Markdown export back-end, @code{md}, converts an Org file to a Markdown
12742 format, as defined at @url{http://daringfireball.net/projects/markdown/}.
12744 Since @code{md} is built on top of the HTML back-end, any Org constructs not
12745 supported by Markdown, such as tables, the underlying @code{html} back-end
12746 (@pxref{HTML export}) converts them.
12748 @subheading Markdown export commands
12751 @orgcmd{C-c C-e m m,org-md-export-to-markdown}
12752 Export to a text file with Markdown syntax. For @file{myfile.org}, Org
12753 exports to @file{myfile.md}, overwritten without warning.
12754 @orgcmd{C-c C-e m M,org-md-export-as-markdown}
12755 Export to a temporary buffer. Does not create a file.
12757 Export as a text file with Markdown syntax, then open it.
12760 @subheading Header and sectioning structure
12762 @vindex org-md-headline-style
12763 Based on @code{org-md-headline-style}, markdown export can generate headlines
12764 of both @code{atx} and @code{setext} types. @code{atx} limits headline
12765 levels to two. @code{setext} limits headline levels to six. Beyond these
12766 limits, the export back-end converts headlines to lists. To set a limit to a
12767 level before the absolute limit (@pxref{Export settings}).
12769 @c begin opendocument
12771 @node OpenDocument Text export
12772 @section OpenDocument Text export
12774 @cindex OpenDocument
12775 @cindex export, OpenDocument
12776 @cindex LibreOffice
12778 The ODT export back-end handles creating of OpenDocument Text (ODT) format
12779 files. The format complies with @cite{OpenDocument-v1.2
12780 specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
12781 Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
12782 is compatible with LibreOffice 3.4.
12785 * Pre-requisites for ODT export:: Required packages.
12786 * ODT export commands:: Invoking export.
12787 * ODT specific export settings:: Configuration options.
12788 * Extending ODT export:: Producing @file{.doc}, @file{.pdf} files.
12789 * Applying custom styles:: Styling the output.
12790 * Links in ODT export:: Handling and formatting links.
12791 * Tables in ODT export:: Org table conversions.
12792 * Images in ODT export:: Inserting images.
12793 * Math formatting in ODT export:: Formatting @LaTeX{} fragments.
12794 * Labels and captions in ODT export:: Rendering objects.
12795 * Literal examples in ODT export:: For source code and example blocks.
12796 * Advanced topics in ODT export:: For power users.
12799 @node Pre-requisites for ODT export
12800 @subsection Pre-requisites for ODT export
12802 The ODT export back-end relies on the @file{zip} program to create the final
12803 compressed ODT output. Check if @file{zip} is locally available and
12804 executable. Without @file{zip}, export cannot finish.
12806 @node ODT export commands
12807 @subsection ODT export commands
12808 @anchor{x-export-to-odt}
12809 @cindex region, active
12810 @cindex active region
12811 @cindex transient-mark-mode
12813 @orgcmd{C-c C-e o o,org-odt-export-to-odt}
12814 @cindex property EXPORT_FILE_NAME
12816 Export as OpenDocument Text file.
12818 @vindex org-odt-preferred-output-format
12819 If @code{org-odt-preferred-output-format} is specified, the ODT export
12820 back-end automatically converts the exported file to that format.
12821 @xref{x-export-to-other-formats, , Automatically exporting to other formats}.
12823 For @file{myfile.org}, Org exports to @file{myfile.odt}, overwriting without
12824 warning. The ODT export back-end exports a region only if a region was
12825 active. Note for exporting active regions, the @code{transient-mark-mode}
12826 has to be turned on.
12828 If the selected region is a single tree, the ODT export back-end makes the
12829 tree head the document title. Incidentally, @kbd{C-c @@} selects the current
12830 sub-tree. If the tree head entry has, or inherits, an
12831 @code{EXPORT_FILE_NAME} property, the ODT export back-end uses that for file
12835 Export to an OpenDocument Text file format and open it.
12837 @vindex org-odt-preferred-output-format
12838 When @code{org-odt-preferred-output-format} is specified, open the converted
12839 file instead. @xref{x-export-to-other-formats, , Automatically exporting to
12843 @node ODT specific export settings
12844 @subsection ODT specific export settings
12845 The ODT export back-end has several additional keywords for customizing ODT
12846 output. Setting these keywords works similar to the general options
12847 (@pxref{Export settings}).
12851 @cindex #+DESCRIPTION (ODT)
12852 This is the document's description, which the ODT export back-end inserts as
12853 document metadata. For long descriptions, use multiple @code{#+DESCRIPTION}
12857 @cindex #+KEYWORDS (ODT)
12858 The keywords for the document. The ODT export back-end inserts the
12859 description along with author name, keywords, and related file metadata as
12860 metadata in the output file. Use multiple @code{#+KEYWORDS} lines if
12863 @item ODT_STYLES_FILE
12864 @cindex ODT_STYLES_FILE
12865 @vindex org-odt-styles-file
12866 The ODT export back-end uses the @code{org-odt-styles-file} by default. See
12867 @ref{Applying custom styles} for details.
12870 @cindex SUBTITLE (ODT)
12871 The document subtitle.
12874 @node Extending ODT export
12875 @subsection Extending ODT export
12877 The ODT export back-end can produce documents in other formats besides ODT
12878 using a specialized ODT converter process. Its common interface works with
12879 popular converters to produce formats such as @samp{doc}, or convert a
12880 document from one format, say @samp{csv}, to another format, say @samp{xls}.
12882 @cindex @file{unoconv}
12883 @cindex LibreOffice
12885 Customize @code{org-odt-convert-process} variable to point to @code{unoconv},
12886 which is the ODT's preferred converter. Working installations of LibreOffice
12887 would already have @code{unoconv} installed. Alternatively, other converters
12888 may be substituted here. @xref{Configuring a document converter}.
12890 @subsubheading Automatically exporting to other formats
12891 @anchor{x-export-to-other-formats}
12893 @vindex org-odt-preferred-output-format
12894 If ODT format is just an intermediate step to get to other formats, such as
12895 @samp{doc}, @samp{docx}, @samp{rtf}, or @samp{pdf}, etc., then extend the ODT
12896 export back-end to directly produce that format. Specify the final format in
12897 the @code{org-odt-preferred-output-format} variable. This is one way to
12898 extend (@pxref{x-export-to-odt,,Exporting to ODT}).
12900 @subsubheading Converting between document formats
12901 @anchor{x-convert-to-other-formats}
12903 The Org export back-end is made to be inter-operable with a wide range of text
12904 document format converters. Newer generation converters, such as LibreOffice
12905 and Pandoc, can handle hundreds of formats at once. Org provides a
12906 consistent interaction with whatever converter is installed. Here are some
12909 @vindex org-odt-convert
12912 @item M-x org-odt-convert RET
12913 Convert an existing document from one format to another. With a prefix
12914 argument, opens the newly produced file.
12917 @node Applying custom styles
12918 @subsection Applying custom styles
12919 @cindex styles, custom
12920 @cindex template, custom
12922 The ODT export back-end comes with many OpenDocument styles (@pxref{Working
12923 with OpenDocument style files}). To expand or further customize these
12924 built-in style sheets, either edit the style sheets directly or generate them
12925 using an application such as LibreOffice. The example here shows creating a
12926 style using LibreOffice.
12928 @subsubheading Applying custom styles: the easy way
12932 Create a sample @file{example.org} file with settings as shown below, and
12933 export it to ODT format.
12936 #+OPTIONS: H:10 num:t
12940 Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist}
12941 to locate the target styles, which typically have the @samp{Org} prefix.
12942 Open one, modify, and save as either OpenDocument Text (@file{.odt}) or
12943 OpenDocument Template (@file{.ott}) file.
12946 @cindex #+ODT_STYLES_FILE
12947 @vindex org-odt-styles-file
12948 Customize the variable @code{org-odt-styles-file} and point it to the
12949 newly created file. For additional configuration options
12950 @pxref{x-overriding-factory-styles,,Overriding factory styles}.
12952 To apply and ODT style to a particular file, use the @code{#+ODT_STYLES_FILE}
12953 option as shown in the example below:
12956 #+ODT_STYLES_FILE: "/path/to/example.ott"
12962 #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
12967 @subsubheading Using third-party styles and templates
12969 The ODT export back-end relies on many templates and style names. Using
12970 third-party styles and templates can lead to mismatches. Templates derived
12971 from built in ODT templates and styles seem to have fewer problems.
12973 @node Links in ODT export
12974 @subsection Links in ODT export
12975 @cindex links, in ODT export
12977 ODT export back-end creates native cross-references for internal links and
12978 Internet-style links for all other link types.
12980 A link with no description and pointing to a regular---un-itemized---outline
12981 heading is replaced with a cross-reference and section number of the heading.
12983 A @samp{\ref@{label@}}-style reference to an image, table etc.@: is replaced
12984 with a cross-reference and sequence number of the labeled entity.
12985 @xref{Labels and captions in ODT export}.
12987 @node Tables in ODT export
12988 @subsection Tables in ODT export
12989 @cindex tables, in ODT export
12991 The ODT export back-end handles native Org mode tables (@pxref{Tables}) and
12992 simple @file{table.el} tables. Complex @file{table.el} tables having column
12993 or row spans are not supported. Such tables are stripped from the exported
12996 By default, the ODT export back-end exports a table with top and bottom
12997 frames and with ruled lines separating row and column groups (@pxref{Column
12998 groups}). All tables are typeset to occupy the same width. The ODT export
12999 back-end honors any table alignments and relative widths for columns
13000 (@pxref{Column width and alignment}).
13002 Note that the ODT export back-end interprets column widths as weighted
13003 ratios, the default weight being 1.
13007 Specifying @code{:rel-width} property on an @code{#+ATTR_ODT} line controls
13008 the width of the table. For example:
13011 #+ATTR_ODT: :rel-width 50
13012 | Area/Month | Jan | Feb | Mar | Sum |
13013 |---------------+-------+-------+-------+-------|
13015 | <l13> | <r5> | <r5> | <r5> | <r6> |
13016 | North America | 1 | 21 | 926 | 948 |
13017 | Middle East | 6 | 75 | 844 | 925 |
13018 | Asia Pacific | 9 | 27 | 790 | 826 |
13019 |---------------+-------+-------+-------+-------|
13020 | Sum | 16 | 123 | 2560 | 2699 |
13023 On export, the above table takes 50% of text width area. The exporter sizes
13024 the columns in the ratio: 13:5:5:5:6. The first column is left-aligned and
13025 rest of the columns, right-aligned. Vertical rules separate the header and
13026 the last column. Horizontal rules separate the header and the last row.
13028 For even more customization, create custom table styles and associate them
13029 with a table using the @code{#+ATTR_ODT} line. @xref{Customizing tables in
13032 @node Images in ODT export
13033 @subsection Images in ODT export
13034 @cindex images, embedding in ODT
13035 @cindex embedding images in ODT
13037 @subsubheading Embedding images
13038 The ODT export back-end processes image links in Org files that do not have
13039 descriptions, such as these links @samp{[[file:img.jpg]]} or
13040 @samp{[[./img.jpg]]}, as direct image insertions in the final output. Either
13041 of these examples works:
13051 @subsubheading Embedding clickable images
13052 For clickable images, provide a link whose description is another link to an
13053 image file. For example, to embed a image @file{org-mode-unicorn.png} which
13054 when clicked jumps to @uref{http://Orgmode.org} website, do the following
13057 [[http://orgmode.org][./org-mode-unicorn.png]]
13060 @subsubheading Sizing and scaling of embedded images
13063 Control the size and scale of the embedded images with the @code{#+ATTR_ODT}
13066 @cindex identify, ImageMagick
13067 @vindex org-odt-pixels-per-inch
13068 The ODT export back-end starts with establishing the size of the image in the
13069 final document. The dimensions of this size is measured in centimeters. The
13070 back-end then queries the image file for its dimensions measured in pixels.
13071 For this measurement, the back-end relies on ImageMagick's @file{identify}
13072 program or Emacs @code{create-image} and @code{image-size} API. ImageMagick
13073 is the preferred choice for large file sizes or frequent batch operations.
13074 The back-end then converts the pixel dimensions using
13075 @code{org-odt-pixels-per-inch} into the familiar 72 dpi or 96 dpi. The
13076 default value for this is in @code{display-pixels-per-inch}, which can be
13077 tweaked for better results based on the capabilities of the output device.
13078 Here are some common image scaling operations:
13081 @item Explicitly size the image
13082 To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
13085 #+ATTR_ODT: :width 10 :height 10
13089 @item Scale the image
13090 To embed @file{img.png} at half its size, do the following:
13093 #+ATTR_ODT: :scale 0.5
13097 @item Scale the image to a specific width
13098 To embed @file{img.png} with a width of 10 cm while retaining the original
13099 height:width ratio, do the following:
13102 #+ATTR_ODT: :width 10
13106 @item Scale the image to a specific height
13107 To embed @file{img.png} with a height of 10 cm while retaining the original
13108 height:width ratio, do the following
13111 #+ATTR_ODT: :height 10
13116 @subsubheading Anchoring of images
13119 The ODT export back-end can anchor images to @samp{"as-char"},
13120 @samp{"paragraph"}, or @samp{"page"}. Set the preferred anchor using the
13121 @code{:anchor} property of the @code{#+ATTR_ODT} line.
13123 To create an image that is anchored to a page:
13125 #+ATTR_ODT: :anchor "page"
13129 @node Math formatting in ODT export
13130 @subsection Math formatting in ODT export
13132 The ODT export back-end has special support built-in for handling math.
13135 * Working with @LaTeX{} math snippets:: Embedding in @LaTeX{} format.
13136 * Working with MathML or OpenDocument formula files:: Embedding in native format.
13139 @node Working with @LaTeX{} math snippets
13140 @subsubheading Working with @LaTeX{} math snippets
13142 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in an ODT
13143 document in one of the following ways:
13149 Add this line to the Org file. This option is activated on a per-file basis.
13155 With this option, @LaTeX{} fragments are first converted into MathML
13156 fragments using an external @LaTeX{}-to-MathML converter program. The
13157 resulting MathML fragments are then embedded as an OpenDocument Formula in
13158 the exported document.
13160 @vindex org-latex-to-mathml-convert-command
13161 @vindex org-latex-to-mathml-jar-file
13163 To specify the @LaTeX{}-to-MathML converter, customize the variables
13164 @code{org-latex-to-mathml-convert-command} and
13165 @code{org-latex-to-mathml-jar-file}.
13167 To use MathToWeb@footnote{See
13168 @uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}.} as the
13169 preferred converter, configure the above variables as
13172 (setq org-latex-to-mathml-convert-command
13173 "java -jar %j -unicode -force -df %o %I"
13174 org-latex-to-mathml-jar-file
13175 "/path/to/mathtoweb.jar")
13177 To use @LaTeX{}ML@footnote{See @uref{http://dlmf.nist.gov/LaTeXML/}.} use
13179 (setq org-latex-to-mathml-convert-command
13180 "latexmlmath \"%i\" --presentationmathml=%o")
13183 To quickly verify the reliability of the @LaTeX{}-to-MathML converter, use
13184 the following commands:
13187 @item M-x org-odt-export-as-odf RET
13188 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file.
13190 @item M-x org-odt-export-as-odf-and-open RET
13191 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file
13192 and open the formula file with the system-registered application.
13197 @cindex imagemagick
13200 Add this line to the Org file. This option is activated on a per-file basis.
13203 #+OPTIONS: tex:dvipng
13207 #+OPTIONS: tex:dvisvgm
13213 #+OPTIONS: tex:imagemagick
13216 Under this option, @LaTeX{} fragments are processed into PNG or SVG images
13217 and the resulting images are embedded in the exported document. This method
13218 requires @file{dvipng} program, @file{dvisvgm} or @file{imagemagick}
13222 @node Working with MathML or OpenDocument formula files
13223 @subsubheading Working with MathML or OpenDocument formula files
13225 When embedding @LaTeX{} math snippets in ODT documents is not reliable, there
13226 is one more option to try. Embed an equation by linking to its MathML
13227 (@file{.mml}) source or its OpenDocument formula (@file{.odf}) file as shown
13240 @node Labels and captions in ODT export
13241 @subsection Labels and captions in ODT export
13243 ODT format handles labeling and captioning of objects based on their
13244 types. Inline images, tables, @LaTeX{} fragments, and Math formulas are
13245 numbered and captioned separately. Each object also gets a unique sequence
13246 number based on its order of first appearance in the Org file. Each category
13247 has its own sequence. A caption is just a label applied to these objects.
13250 #+CAPTION: Bell curve
13251 #+LABEL: fig:SED-HR4049
13255 When rendered, it may show as follows in the exported document:
13258 Figure 2: Bell curve
13261 @vindex org-odt-category-map-alist
13262 To modify the category component of the caption, customize the option
13263 @code{org-odt-category-map-alist}. For example, to tag embedded images with
13264 the string @samp{Illustration} instead of the default string @samp{Figure},
13265 use the following setting:
13268 (setq org-odt-category-map-alist
13269 '(("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
13272 With the above modification, the previous example changes to:
13275 Illustration 2: Bell curve
13278 @node Literal examples in ODT export
13279 @subsection Literal examples in ODT export
13281 The ODT export back-end supports literal examples (@pxref{Literal examples})
13282 with full fontification. Internally, the ODT export back-end relies on
13283 @file{htmlfontify.el} to generate the style definitions needed for fancy
13284 listings. The auto-generated styles get @samp{OrgSrc} prefix and inherit
13285 colors from the faces used by Emacs @code{font-lock} library for that source
13288 @vindex org-odt-fontify-srcblocks
13289 For custom fontification styles, customize the
13290 @code{org-odt-create-custom-styles-for-srcblocks} option.
13292 @vindex org-odt-create-custom-styles-for-srcblocks
13293 To turn off fontification of literal examples, customize the
13294 @code{org-odt-fontify-srcblocks} option.
13296 @node Advanced topics in ODT export
13297 @subsection Advanced topics in ODT export
13299 The ODT export back-end has extensive features useful for power users and
13300 frequent uses of ODT formats.
13303 * Configuring a document converter:: Registering a document converter.
13304 * Working with OpenDocument style files:: Exploring internals.
13305 * Creating one-off styles:: Customizing styles, highlighting.
13306 * Customizing tables in ODT export:: Defining table templates.
13307 * Validating OpenDocument XML:: Debugging corrupted OpenDocument files.
13310 @node Configuring a document converter
13311 @subsubheading Configuring a document converter
13313 @cindex doc, docx, rtf
13316 The ODT export back-end works with popular converters with little or no extra
13317 configuration. @xref{Extending ODT export}. The following is for unsupported
13318 converters or tweaking existing defaults.
13321 @item Register the converter
13323 @vindex org-odt-convert-processes
13324 Add the name of the converter to the @code{org-odt-convert-processes}
13325 variable. Note that it also requires how the converter is invoked on the
13326 command line. See the variable's docstring for details.
13328 @item Configure its capabilities
13330 @vindex org-odt-convert-capabilities
13331 @anchor{x-odt-converter-capabilities} Specify which formats the converter can
13332 handle by customizing the variable @code{org-odt-convert-capabilities}. Use
13333 the entry for the default values in this variable for configuring the new
13334 converter. Also see its docstring for details.
13336 @item Choose the converter
13338 @vindex org-odt-convert-process
13339 Select the newly added converter as the preferred one by customizing the
13340 option @code{org-odt-convert-process}.
13343 @node Working with OpenDocument style files
13344 @subsubheading Working with OpenDocument style files
13345 @cindex styles, custom
13346 @cindex template, custom
13348 This section explores the internals of the ODT exporter; the means by which
13349 it produces styled documents; the use of automatic and custom OpenDocument
13352 @anchor{x-factory-styles}
13353 @subsubheading a) Factory styles
13355 The ODT exporter relies on two files for generating its output.
13356 These files are bundled with the distribution under the directory pointed to
13357 by the variable @code{org-odt-styles-dir}. The two files are:
13360 @anchor{x-orgodtstyles-xml}
13362 @file{OrgOdtStyles.xml}
13364 This file contributes to the @file{styles.xml} file of the final @samp{ODT}
13365 document. This file gets modified for the following purposes:
13369 To control outline numbering based on user settings.
13372 To add styles generated by @file{htmlfontify.el} for fontification of code
13376 @anchor{x-orgodtcontenttemplate-xml}
13378 @file{OrgOdtContentTemplate.xml}
13380 This file contributes to the @file{content.xml} file of the final @samp{ODT}
13381 document. The contents of the Org outline are inserted between the
13382 @samp{<office:text>}@dots{}@samp{</office:text>} elements of this file.
13384 Apart from serving as a template file for the final @file{content.xml}, the
13385 file serves the following purposes:
13389 It contains automatic styles for formatting of tables which are referenced by
13393 It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
13394 elements that control numbering of tables, images, equations, and similar
13399 @anchor{x-overriding-factory-styles}
13400 @subsubheading b) Overriding factory styles
13401 The following two variables control the location from where the ODT exporter
13402 picks up the custom styles and content template files. Customize these
13403 variables to override the factory styles used by the exporter.
13406 @anchor{x-org-odt-styles-file}
13408 @code{org-odt-styles-file}
13410 The ODT export back-end uses the file pointed to by this variable, such as
13411 @file{styles.xml}, for the final output. It can take one of the following
13415 @item A @file{styles.xml} file
13417 Use this file instead of the default @file{styles.xml}
13419 @item A @file{.odt} or @file{.ott} file
13421 Use the @file{styles.xml} contained in the specified OpenDocument Text or
13424 @item A @file{.odt} or @file{.ott} file and a subset of files contained within them
13426 Use the @file{styles.xml} contained in the specified OpenDocument Text or
13427 Template file. Additionally extract the specified member files and embed
13428 those within the final @samp{ODT} document.
13430 Use this option if the @file{styles.xml} file references additional files
13431 like header and footer images.
13435 Use the default @file{styles.xml}
13438 @anchor{x-org-odt-content-template-file}
13440 @code{org-odt-content-template-file}
13442 Use this variable to specify the blank @file{content.xml} that will be used
13443 in the final output.
13446 @node Creating one-off styles
13447 @subsubheading Creating one-off styles
13449 The ODT export back-end can read embedded raw OpenDocument XML from the Org
13450 file. Such direct formatting are useful for one-off instances.
13453 @item Embedding ODT tags as part of regular text
13455 Enclose OpenDocument syntax in @samp{@@@@odt:...@@@@} for inline markup. For
13456 example, to highlight a region of text do the following:
13459 @@@@odt:<text:span text:style-name="Highlight">This is highlighted
13460 text</text:span>@@@@. But this is regular text.
13463 @strong{Hint:} To see the above example in action, edit the @file{styles.xml}
13464 (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a custom
13465 @samp{Highlight} style as shown below:
13468 <style:style style:name="Highlight" style:family="text">
13469 <style:text-properties fo:background-color="#ff0000"/>
13473 @item Embedding a one-line OpenDocument XML
13475 The ODT export back-end can read one-liner options with @code{#+ODT:}
13476 in the Org file. For example, to force a page break:
13479 #+ODT: <text:p text:style-name="PageBreak"/>
13482 @strong{Hint:} To see the above example in action, edit your
13483 @file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
13484 custom @samp{PageBreak} style as shown below.
13487 <style:style style:name="PageBreak" style:family="paragraph"
13488 style:parent-style-name="Text_20_body">
13489 <style:paragraph-properties fo:break-before="page"/>
13493 @item Embedding a block of OpenDocument XML
13495 The ODT export back-end can also read ODT export blocks for OpenDocument XML.
13496 Such blocks use the @code{#+BEGIN_EXPORT odt}@dots{}@code{#+END_EXPORT}
13499 For example, to create a one-off paragraph that uses bold text, do the
13504 <text:p text:style-name="Text_20_body_20_bold">
13505 This paragraph is specially formatted and uses bold text.
13512 @node Customizing tables in ODT export
13513 @subsubheading Customizing tables in ODT export
13514 @cindex tables, in ODT export
13517 Override the default table format by specifying a custom table style with the
13518 @code{#+ATTR_ODT} line. For a discussion on default formatting of tables
13519 @pxref{Tables in ODT export}.
13521 This feature closely mimics the way table templates are defined in the
13523 specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
13524 OpenDocument-v1.2 Specification}}
13526 @vindex org-odt-table-styles
13527 For quick preview of this feature, install the settings below and export the
13528 table that follows:
13531 (setq org-odt-table-styles
13532 (append org-odt-table-styles
13533 '(("TableWithHeaderRowAndColumn" "Custom"
13534 ((use-first-row-styles . t)
13535 (use-first-column-styles . t)))
13536 ("TableWithFirstRowandLastRow" "Custom"
13537 ((use-first-row-styles . t)
13538 (use-last-row-styles . t))))))
13542 #+ATTR_ODT: :style TableWithHeaderRowAndColumn
13543 | Name | Phone | Age |
13544 | Peter | 1234 | 17 |
13545 | Anna | 4321 | 25 |
13548 The example above used @samp{Custom} template and installed two table styles
13549 @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}.
13550 @strong{Important:} The OpenDocument styles needed for producing the above
13551 template were pre-defined. They are available in the section marked
13552 @samp{Custom Table Template} in @file{OrgOdtContentTemplate.xml}
13553 (@pxref{x-orgodtcontenttemplate-xml,,Factory styles}. For adding new
13554 templates, define new styles here.
13556 To use this feature proceed as follows:
13560 Create a table template@footnote{See the @code{<table:table-template>}
13561 element of the OpenDocument-v1.2 specification}
13563 A table template is set of @samp{table-cell} and @samp{paragraph} styles for
13564 each of the following table cell categories:
13578 The names for the above styles must be chosen based on the name of the table
13579 template using a well-defined convention.
13581 The naming convention is better illustrated with an example. For a table
13582 template with the name @samp{Custom}, the needed style names are listed in
13583 the following table.
13585 @multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph}
13586 @headitem Table cell type
13587 @tab @code{table-cell} style
13588 @tab @code{paragraph} style
13593 @tab @samp{CustomTableCell}
13594 @tab @samp{CustomTableParagraph}
13596 @tab @samp{CustomFirstColumnTableCell}
13597 @tab @samp{CustomFirstColumnTableParagraph}
13599 @tab @samp{CustomLastColumnTableCell}
13600 @tab @samp{CustomLastColumnTableParagraph}
13602 @tab @samp{CustomFirstRowTableCell}
13603 @tab @samp{CustomFirstRowTableParagraph}
13605 @tab @samp{CustomLastRowTableCell}
13606 @tab @samp{CustomLastRowTableParagraph}
13608 @tab @samp{CustomEvenRowTableCell}
13609 @tab @samp{CustomEvenRowTableParagraph}
13611 @tab @samp{CustomOddRowTableCell}
13612 @tab @samp{CustomOddRowTableParagraph}
13614 @tab @samp{CustomEvenColumnTableCell}
13615 @tab @samp{CustomEvenColumnTableParagraph}
13617 @tab @samp{CustomOddColumnTableCell}
13618 @tab @samp{CustomOddColumnTableParagraph}
13621 To create a table template with the name @samp{Custom}, define the above
13623 @code{<office:automatic-styles>}...@code{</office:automatic-styles>} element
13624 of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory
13628 Define a table style@footnote{See the attributes @code{table:template-name},
13629 @code{table:use-first-row-styles}, @code{table:use-last-row-styles},
13630 @code{table:use-first-column-styles}, @code{table:use-last-column-styles},
13631 @code{table:use-banding-rows-styles}, and
13632 @code{table:use-banding-column-styles} of the @code{<table:table>} element in
13633 the OpenDocument-v1.2 specification}
13635 @vindex org-odt-table-styles
13636 To define a table style, create an entry for the style in the variable
13637 @code{org-odt-table-styles} and specify the following:
13640 @item the name of the table template created in step (1)
13641 @item the set of cell styles in that template that are to be activated
13644 For example, the entry below defines two different table styles
13645 @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
13646 based on the same template @samp{Custom}. The styles achieve their intended
13647 effect by selectively activating the individual cell styles in that template.
13650 (setq org-odt-table-styles
13651 (append org-odt-table-styles
13652 '(("TableWithHeaderRowAndColumn" "Custom"
13653 ((use-first-row-styles . t)
13654 (use-first-column-styles . t)))
13655 ("TableWithFirstRowandLastRow" "Custom"
13656 ((use-first-row-styles . t)
13657 (use-last-row-styles . t))))))
13661 Associate a table with the table style
13663 To do this, specify the table style created in step (2) as part of
13664 the @code{ATTR_ODT} line as shown below.
13667 #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
13668 | Name | Phone | Age |
13669 | Peter | 1234 | 17 |
13670 | Anna | 4321 | 25 |
13674 @node Validating OpenDocument XML
13675 @subsubheading Validating OpenDocument XML
13677 Sometimes ODT format files may not open due to @file{.odt} file corruption.
13678 To verify if the @file{.odt} file is corrupt, validate it against the
13679 OpenDocument RELAX NG Compact Syntax---RNC---schema. But first the
13680 @file{.odt} files have to be decompressed using @samp{zip}. Note that
13681 @file{.odt} files are @samp{zip} archives: @inforef{File Archives,,emacs}.
13682 The contents of @file{.odt} files are in @file{.xml}. For general help with
13683 validation---and schema-sensitive editing---of XML files:
13684 @inforef{Introduction,,nxml-mode}.
13686 @vindex org-odt-schema-dir
13687 Customize @code{org-odt-schema-dir} to point to a directory with OpenDocument
13688 @file{.rnc} files and the needed schema-locating rules. The ODT export
13689 back-end takes care of updating the @code{rng-schema-locating-files}.
13691 @c end opendocument
13694 @section Org export
13697 @code{org} export back-end creates a normalized version of the Org document
13698 in current buffer. The exporter evaluates Babel code (@pxref{Evaluating code
13699 blocks}) and removes content specific to other back-ends.
13701 @subheading Org export commands
13704 @orgcmd{C-c C-e O o,org-org-export-to-org}
13705 Export as an Org file with a @file{.org} extension. For @file{myfile.org},
13706 Org exports to @file{myfile.org.org}, overwriting without warning.
13708 @orgcmd{C-c C-e O O,org-org-export-as-org}
13709 Export to a temporary buffer. Does not create a file.
13711 Export to an Org file, then open it.
13714 @node Texinfo export
13715 @section Texinfo export
13716 @cindex Texinfo export
13718 The @samp{texinfo} export back-end generates documents with Texinfo code that
13719 can compile to Info format.
13722 * Texinfo export commands:: Invoking commands.
13723 * Texinfo specific export settings:: Setting the environment.
13724 * Texinfo file header:: Generating the header.
13725 * Texinfo title and copyright page:: Creating preamble pages.
13726 * Info directory file:: Installing a manual in Info file hierarchy.
13727 * Headings and sectioning structure:: Building document structure.
13728 * Indices:: Creating indices.
13729 * Quoting Texinfo code:: Incorporating literal Texinfo code.
13730 * Plain lists in Texinfo export:: List attributes.
13731 * Tables in Texinfo export:: Table attributes.
13732 * Images in Texinfo export:: Image attributes.
13733 * Special blocks in Texinfo export:: Special block attributes.
13734 * A Texinfo example:: Processing Org to Texinfo.
13737 @node Texinfo export commands
13738 @subsection Texinfo export commands
13740 @vindex org-texinfo-info-process
13742 @orgcmd{C-c C-e i t,org-texinfo-export-to-texinfo}
13743 Export as a Texinfo file with @file{.texi} extension. For @file{myfile.org},
13744 Org exports to @file{myfile.texi}, overwriting without warning.
13745 @orgcmd{C-c C-e i i,org-texinfo-export-to-info}
13746 Export to Texinfo format first and then process it to make an Info file. To
13747 generate other formats, such as DocBook, customize the
13748 @code{org-texinfo-info-process} variable.
13751 @node Texinfo specific export settings
13752 @subsection Texinfo specific export settings
13753 The Texinfo export back-end has several additional keywords for customizing
13754 Texinfo output. Setting these keywords works similar to the general options
13755 (@pxref{Export settings}).
13760 @cindex #+SUBTITLE (Texinfo)
13761 The document subtitle.
13764 @cindex #+SUBAUTHOR
13765 The document subauthor.
13767 @item TEXINFO_FILENAME
13768 @cindex #+TEXINFO_FILENAME
13769 The Texinfo filename.
13771 @item TEXINFO_CLASS
13772 @cindex #+TEXINFO_CLASS
13773 @vindex org-texinfo-default-class
13774 The default document class (@code{org-texinfo-default-class}), which must be
13775 a member of @code{org-texinfo-classes}.
13777 @item TEXINFO_HEADER
13778 @cindex #+TEXINFO_HEADER
13779 Arbitrary lines inserted at the end of the header.
13781 @item TEXINFO_POST_HEADER
13782 @cindex #+TEXINFO_POST_HEADER
13783 Arbitrary lines inserted after the end of the header.
13785 @item TEXINFO_DIR_CATEGORY
13786 @cindex #+TEXINFO_DIR_CATEGORY
13787 The directory category of the document.
13789 @item TEXINFO_DIR_TITLE
13790 @cindex #+TEXINFO_DIR_TITLE
13791 The directory title of the document.
13793 @item TEXINFO_DIR_DESC
13794 @cindex #+TEXINFO_DIR_DESC
13795 The directory description of the document.
13797 @item TEXINFO_PRINTED_TITLE
13798 @cindex #+TEXINFO_PRINTED_TITLE
13799 The printed title of the document.
13802 @node Texinfo file header
13803 @subsection Texinfo file header
13805 @cindex #+TEXINFO_FILENAME
13806 After creating the header for a Texinfo file, the Texinfo back-end
13807 automatically generates a name and destination path for the Info file. To
13808 override this default with a more sensible path and name, specify the
13809 @code{#+TEXINFO_FILENAME} keyword.
13811 @vindex org-texinfo-coding-system
13812 @vindex org-texinfo-classes
13813 @cindex #+TEXINFO_HEADER
13814 @cindex #+TEXINFO_CLASS
13815 Along with the output's file name, the Texinfo header also contains language
13816 details (@pxref{Export settings}) and encoding system as set in the
13817 @code{org-texinfo-coding-system} variable. Insert @code{#+TEXINFO_HEADER}
13818 keywords for each additional command in the header, for example:
13819 @@code@{@@synindex@}.
13821 Instead of repeatedly installing the same set of commands, define a class in
13822 @code{org-texinfo-classes} once, and then activate it in the document by
13823 setting the @code{#+TEXINFO_CLASS} keyword to that class.
13825 @node Texinfo title and copyright page
13826 @subsection Texinfo title and copyright page
13828 @cindex #+TEXINFO_PRINTED_TITLE
13829 The default template for hard copy output has a title page with
13830 @code{#+TITLE} and @code{#+AUTHOR} (@pxref{Export settings}). To replace the
13831 regular @code{#+TITLE} with something different for the printed version, use
13832 the @code{#+TEXINFO_PRINTED_TITLE} and @code{#+SUBTITLE} keywords. Both
13833 expect raw Texinfo code for setting their values.
13835 @cindex #+SUBAUTHOR
13836 If one @code{#+AUTHOR} is not sufficient, add multiple @code{#+SUBAUTHOR}
13837 keywords. They have to be set in raw Texinfo code.
13840 #+AUTHOR: Jane Smith
13841 #+SUBAUTHOR: John Doe
13842 #+TEXINFO_PRINTED_TITLE: This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@}
13845 @cindex property, COPYING
13846 Copying material is defined in a dedicated headline with a non-@code{nil}
13847 @code{:COPYING:} property. The back-end inserts the contents within a
13848 @code{@@copying} command at the beginning of the document. The heading
13849 itself does not appear in the structure of the document.
13851 Copyright information is printed on the back of the title page.
13859 This is a short example of a complete Texinfo file, version 1.0.
13861 Copyright \copy 2016 Free Software Foundation, Inc.
13864 @node Info directory file
13865 @subsection Info directory file
13866 @cindex @samp{dir} file, in Texinfo export
13867 @cindex Texinfo export, @samp{dir} file
13868 @cindex Info directory file, in Texinfo export
13869 @cindex Texinfo export, Info directory file
13870 @cindex @code{install-info} parameters, in Texinfo export
13871 @cindex Texinfo export, @code{install-info} parameters
13873 @cindex #+TEXINFO_DIR_CATEGORY
13874 @cindex #+TEXINFO_DIR_TITLE
13875 @cindex #+TEXINFO_DIR_DESC
13876 The end result of the Texinfo export process is the creation of an Info file.
13877 This Info file's metadata has variables for category, title, and description:
13878 @code{#+TEXINFO_DIR_CATEGORY}, @code{#+TEXINFO_DIR_TITLE}, and
13879 @code{#+TEXINFO_DIR_DESC} that establish where in the Info hierarchy the file
13882 Here is an example that writes to the Info directory file:
13885 #+TEXINFO_DIR_CATEGORY: Emacs
13886 #+TEXINFO_DIR_TITLE: Org Mode: (org)
13887 #+TEXINFO_DIR_DESC: Outline-based notes management and organizer
13890 @node Headings and sectioning structure
13891 @subsection Headings and sectioning structure
13893 @vindex org-texinfo-classes
13894 @vindex org-texinfo-default-class
13895 @cindex #+TEXINFO_CLASS
13896 The Texinfo export back-end uses a pre-defined scheme to convert Org
13897 headlines to an equivalent Texinfo structuring commands. A scheme like this
13898 maps top-level headlines to numbered chapters tagged as @code{@@chapter} and
13899 lower-level headlines to unnumbered chapters tagged as @code{@@unnumbered}.
13900 To override such mappings to introduce @code{@@part} or other Texinfo
13901 structuring commands, define a new class in @code{org-texinfo-classes}.
13902 Activate the new class with the @code{#+TEXINFO_CLASS} keyword. When no new
13903 class is defined and activated, the Texinfo export back-end defaults to the
13904 @code{org-texinfo-default-class}.
13906 If an Org headline's level has no associated Texinfo structuring command, or
13907 is below a certain threshold (@pxref{Export settings}), then the Texinfo
13908 export back-end makes it into a list item.
13910 @cindex property, APPENDIX
13911 The Texinfo export back-end makes any headline with a non-@code{nil}
13912 @code{:APPENDIX:} property into an appendix. This happens independent of the
13913 Org headline level or the @code{#+TEXINFO_CLASS}.
13915 @cindex property, DESCRIPTION
13916 The Texinfo export back-end creates a menu entry after the Org headline for
13917 each regular sectioning structure. To override this with a shorter menu
13918 entry, use the @code{:ALT_TITLE:} property (@pxref{Table of contents}).
13919 Texinfo menu entries also have an option for a longer @code{:DESCRIPTION:}
13920 property. Here's an example that uses both to override the default menu
13924 * Controlling Screen Display
13926 :ALT_TITLE: Display
13927 :DESCRIPTION: Controlling Screen Display
13931 @cindex The Top node, in Texinfo export
13932 @cindex Texinfo export, Top node
13933 The text before the first headline belongs to the @samp{Top} node, i.e., the
13934 node in which a reader enters an Info manual. As such, it is expected not to
13935 appear in printed output generated from the @file{.texi} file. @inforef{The
13936 Top Node,,texinfo}, for more information.
13939 @subsection Indices
13942 @cindex concept index, in Texinfo export
13943 @cindex Texinfo export, index, concept
13945 @cindex function index, in Texinfo export
13946 @cindex Texinfo export, index, function
13948 @cindex keystroke index, in Texinfo export
13949 @cindex Texinfo export, keystroke index
13951 @cindex program index, in Texinfo export
13952 @cindex Texinfo export, program index
13954 @cindex data type index, in Texinfo export
13955 @cindex Texinfo export, data type index
13957 @cindex variable index, in Texinfo export
13958 @cindex Texinfo export, variable index
13959 The Texinfo export back-end recognizes these indexing keywords if used in the
13960 Org file: @code{#+CINDEX}, @code{#+FINDEX}, @code{#+KINDEX}, @code{#+PINDEX},
13961 @code{#+TINDEX}, and @code{#+VINDEX}. Write their value as verbatim Texinfo
13962 code; in particular, @samp{@{}, @samp{@}} and @samp{@@} characters need to be
13963 escaped with @samp{@@} if they not belong to a Texinfo command.
13966 #+CINDEX: Defining indexing entries
13969 @cindex property, INDEX
13970 For the back-end to generate an index entry for a headline, set the
13971 @code{:INDEX:} property to @samp{cp} or @samp{vr}. These abbreviations come
13972 from Texinfo that stand for concept index and variable index. The Texinfo
13973 manual has abbreviations for all other kinds of indexes. The back-end
13974 exports the headline as an unnumbered chapter or section command, and then
13975 inserts the index after its contents.
13984 @node Quoting Texinfo code
13985 @subsection Quoting Texinfo code
13987 Use any of the following three methods to insert or escape raw Texinfo code:
13990 @cindex #+BEGIN_EXPORT texinfo
13992 Richard @@@@texinfo:@@sc@{@@@@Stallman@@@@texinfo:@}@@@@ commence' GNU.
13994 #+TEXINFO: @@need800
13995 This paragraph is preceded by...
13997 #+BEGIN_EXPORT texinfo
13998 @@auindex Johnson, Mark
13999 @@auindex Lakoff, George
14003 @node Plain lists in Texinfo export
14004 @subsection Plain lists in Texinfo export
14005 @cindex #+ATTR_TEXINFO, in plain lists
14006 @cindex Two-column tables, in Texinfo export
14008 @cindex :table-type attribute, in Texinfo export
14009 The Texinfo export back-end by default converts description lists in the Org
14010 file using the default command @code{@@table}, which results in a table with
14011 two columns. To change this behavior, specify @code{:table-type} with
14012 @code{ftable} or @code{vtable} attributes. For more information,
14013 @inforef{Two-column Tables,,texinfo}.
14015 @vindex org-texinfo-table-default-markup
14016 @cindex :indic attribute, in Texinfo export
14017 The Texinfo export back-end by default also applies a text highlight based on
14018 the defaults stored in @code{org-texinfo-table-default-markup}. To override
14019 the default highlight command, specify another one with the @code{:indic}
14022 @cindex Multiple entries in two-column tables, in Texinfo export
14023 @cindex :sep attribute, in Texinfo export
14024 Org syntax is limited to one entry per list item. Nevertheless, the Texinfo
14025 export back-end can split that entry according to any text provided through
14026 the @code{:sep} attribute. Each part then becomes a new entry in the first
14027 column of the table.
14029 The following example illustrates all the attributes above:
14032 #+ATTR_TEXINFO: :table-type vtable :sep , :indic asis
14033 - foo, bar :: This is the common text for variables foo and bar.
14043 This is the common text for variables foo and bar.
14047 @node Tables in Texinfo export
14048 @subsection Tables in Texinfo export
14049 @cindex #+ATTR_TEXINFO, in tables
14051 When exporting tables, the Texinfo export back-end uses the widest cell width
14052 in each column. To override this and instead specify as fractions of line
14053 length, use the @code{:columns} attribute. See example below.
14056 #+ATTR_TEXINFO: :columns .5 .5
14057 | a cell | another cell |
14060 @node Images in Texinfo export
14061 @subsection Images in Texinfo export
14062 @cindex #+ATTR_TEXINFO, in images
14064 Insert a file link to the image in the Org file, and the Texinfo export
14065 back-end inserts the image. These links must have the usual supported image
14066 extensions and no descriptions. To scale the image, use @code{:width} and
14067 @code{:height} attributes. For alternate text, use @code{:alt} and specify
14068 the text using Texinfo code, as shown in the example:
14071 #+ATTR_TEXINFO: :width 1in :alt Alternate @@i@{text@}
14075 @node Special blocks in Texinfo export
14076 @subsection Special blocks
14077 @cindex #+ATTR_TEXINFO, in special blocks
14079 The Texinfo export back-end converts special blocks to commands with the same
14080 name. It also adds any @code{:options} attributes to the end of the command,
14081 as shown in this example:
14084 #+ATTR_TEXINFO: :options org-org-export-to-org ...
14086 A somewhat obsessive function.
14094 @@defun org-org-export-to-org ...
14095 A somewhat obsessive function.
14099 @node A Texinfo example
14100 @subsection A Texinfo example
14102 Here is a more detailed example Org file. See @ref{GNU Sample
14103 Texts,,,texinfo,GNU Texinfo Manual} for an equivalent example using Texinfo
14107 #+TITLE: GNU Sample @{@{@{version@}@}@}
14108 #+SUBTITLE: for version @{@{@{version@}@}@}, @{@{@{updated@}@}@}
14109 #+AUTHOR: A.U. Thor
14110 #+EMAIL: bug-sample@@gnu.org
14112 #+OPTIONS: ':t toc:t author:t email:t
14115 #+MACRO: version 2.0
14116 #+MACRO: updated last updated 4 March 2014
14118 #+TEXINFO_FILENAME: sample.info
14119 #+TEXINFO_HEADER: @@syncodeindex pg cp
14121 #+TEXINFO_DIR_CATEGORY: Texinfo documentation system
14122 #+TEXINFO_DIR_TITLE: sample: (sample)
14123 #+TEXINFO_DIR_DESC: Invoking sample
14125 #+TEXINFO_PRINTED_TITLE: GNU Sample
14127 This manual is for GNU Sample (version @{@{@{version@}@}@},
14128 @{@{@{updated@}@}@}).
14135 This manual is for GNU Sample (version @{@{@{version@}@}@},
14136 @{@{@{updated@}@}@}), which is an example in the Texinfo documentation.
14138 Copyright \copy 2016 Free Software Foundation, Inc.
14141 Permission is granted to copy, distribute and/or modify this
14142 document under the terms of the GNU Free Documentation License,
14143 Version 1.3 or any later version published by the Free Software
14144 Foundation; with no Invariant Sections, with no Front-Cover Texts,
14145 and with no Back-Cover Texts. A copy of the license is included in
14146 the section entitled "GNU Free Documentation License".
14152 #+CINDEX: invoking @@command@{sample@}
14154 This is a sample manual. There is no sample program to invoke, but
14155 if there were, you could see its basic usage and command line
14158 * GNU Free Documentation License
14163 #+TEXINFO: @@include fdl.texi
14171 @node iCalendar export
14172 @section iCalendar export
14173 @cindex iCalendar export
14175 @vindex org-icalendar-include-todo
14176 @vindex org-icalendar-use-deadline
14177 @vindex org-icalendar-use-scheduled
14178 @vindex org-icalendar-categories
14179 @vindex org-icalendar-alarm-time
14180 A large part of Org mode's inter-operability success is its ability to easily
14181 export to or import from external applications. The iCalendar export
14182 back-end takes calendar data from Org files and exports to the standard
14185 The iCalendar export back-end can also incorporate TODO entries based on the
14186 configuration of the @code{org-icalendar-include-todo} variable. The
14187 back-end exports plain timestamps as VEVENT, TODO items as VTODO, and also
14188 create events from deadlines that are in non-TODO items. The back-end uses
14189 the deadlines and scheduling dates in Org TODO items for setting the start
14190 and due dates for the iCalendar TODO entry. Consult the
14191 @code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}
14192 variables for more details.
14194 For tags on the headline, the iCalendar export back-end makes them into
14195 iCalendar categories. To tweak the inheritance of tags and TODO states,
14196 configure the variable @code{org-icalendar-categories}. To assign clock
14197 alarms based on time, configure the @code{org-icalendar-alarm-time} variable.
14199 @vindex org-icalendar-store-UID
14200 @cindex property, ID
14201 The iCalendar format standard requires globally unique identifier---UID---for
14202 each entry. The iCalendar export back-end creates UIDs during export. To
14203 save a copy of the UID in the Org file set the variable
14204 @code{org-icalendar-store-UID}. The back-end looks for the @code{:ID:}
14205 property of the entry for re-using the same UID for subsequent exports.
14207 Since a single Org entry can result in multiple iCalendar entries---as
14208 timestamp, deadline, scheduled item, or TODO item---Org adds prefixes to the
14209 UID, depending on which part of the Org entry triggered the creation of the
14210 iCalendar entry. Prefixing ensures UIDs remains unique, yet enable
14211 synchronization programs trace the connections.
14214 @orgcmd{C-c C-e c f,org-icalendar-export-to-ics}
14215 Create iCalendar entries from the current Org buffer and store them in the
14216 same directory, using a file extension @file{.ics}.
14217 @orgcmd{C-c C-e c a, org-icalendar-export-agenda-files}
14218 @vindex org-agenda-files
14219 Create iCalendar entries from Org files in @code{org-agenda-files} and store
14220 in a separate iCalendar file for each Org file.
14221 @orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files}
14222 @vindex org-icalendar-combined-agenda-file
14223 Create a combined iCalendar file from Org files in @code{org-agenda-files}
14224 and write it to @code{org-icalendar-combined-agenda-file} file name.
14227 @vindex org-use-property-inheritance
14228 @vindex org-icalendar-include-body
14229 @cindex property, SUMMARY
14230 @cindex property, DESCRIPTION
14231 @cindex property, LOCATION
14232 @cindex property, TIMEZONE
14233 The iCalendar export back-end includes SUMMARY, DESCRIPTION, LOCATION and
14234 TIMEZONE properties from the Org entries when exporting. To force the
14235 back-end to inherit the LOCATION and TIMEZONE properties, configure the
14236 @code{org-use-property-inheritance} variable.
14238 When Org entries do not have SUMMARY, DESCRIPTION and LOCATION properties,
14239 the iCalendar export back-end derives the summary from the headline, and
14240 derives the description from the body of the Org item. The
14241 @code{org-icalendar-include-body} variable limits the maximum number of
14242 characters of the content are turned into its description.
14244 The TIMEZONE property can be used to specify a per-entry time zone, and will
14245 be applied to any entry with timestamp information. Time zones should be
14246 specified as per the IANA time zone database format, e.g.@: ``Asia/Almaty''.
14247 Alternately, the property value can be ``UTC'', to force UTC time for this
14250 Exporting to iCalendar format depends in large part on the capabilities of
14251 the destination application. Some are more lenient than others. Consult the
14252 Org mode FAQ for advice on specific applications.
14254 @node Other built-in back-ends
14255 @section Other built-in back-ends
14256 @cindex export back-ends, built-in
14257 @vindex org-export-backends
14259 Other export back-ends included with Org are:
14262 @item @file{ox-man.el}: export to a man page.
14265 To activate such back-ends, either customize @code{org-export-backends} or
14266 load directly with @code{(require 'ox-man)}. On successful load, the
14267 back-end adds new keys in the export dispatcher (@pxref{The export
14270 Follow the comment section of such files, for example, @file{ox-man.el}, for
14271 usage and configuration details.
14273 @node Advanced configuration
14274 @section Advanced configuration
14278 @vindex org-export-before-processing-hook
14279 @vindex org-export-before-parsing-hook
14280 The export process executes two hooks before the actual exporting begins.
14281 The first hook, @code{org-export-before-processing-hook}, runs before any
14282 expansions of macros, Babel code, and include keywords in the buffer. The
14283 second hook, @code{org-export-before-parsing-hook}, runs before the buffer is
14284 parsed. Both hooks are specified as functions, see example below. Their main
14285 use is for heavy duty structural modifications of the Org content. For
14286 example, removing every headline in the buffer during export:
14290 (defun my-headline-removal (backend)
14291 "Remove all headlines in the current buffer.
14292 BACKEND is the export back-end being used, as a symbol."
14294 (lambda () (delete-region (point) (progn (forward-line) (point))))))
14296 (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
14300 Note that the hook function must have a mandatory argument that is a symbol
14303 @subheading Filters
14305 @cindex Filters, exporting
14306 The Org export process relies on filters to process specific parts of
14307 conversion process. Filters are just lists of functions to be applied to
14308 certain parts for a given back-end. The output from the first function in
14309 the filter is passed on to the next function in the filter. The final output
14310 is the output from the final function in the filter.
14312 The Org export process has many filter sets applicable to different types of
14313 objects, plain text, parse trees, export options, and final output formats.
14314 The filters are named after the element type or object type:
14315 @code{org-export-filter-TYPE-functions}, where @code{TYPE} is the type
14316 targeted by the filter. Valid types are:
14318 @multitable @columnfractions .33 .33 .33
14331 @item export-snippet
14334 @item footnote-definition
14335 @tab footnote-reference
14337 @item horizontal-rule
14338 @tab inline-babel-call
14339 @tab inline-src-block
14344 @tab latex-environment
14345 @tab latex-fragment
14355 @item property-drawer
14361 @item statistics-cookie
14362 @tab strike-through
14375 Here is an example filter that replaces non-breaking spaces @code{~} in the
14376 Org buffer with @code{_} for the @LaTeX{} back-end.
14380 (defun my-latex-filter-nobreaks (text backend info)
14381 "Ensure \"_\" are properly handled in LaTeX export."
14382 (when (org-export-derived-backend-p backend 'latex)
14383 (replace-regexp-in-string "_" "~" text)))
14385 (add-to-list 'org-export-filter-plain-text-functions
14386 'my-latex-filter-nobreaks)
14390 A filter requires three arguments: the code to be transformed, the name of
14391 the back-end, and some optional information about the export process. The
14392 third argument can be safely ignored. Note the use of
14393 @code{org-export-derived-backend-p} predicate that tests for @code{latex}
14394 back-end or any other back-end, such as @code{beamer}, derived from
14397 @subheading Defining filters for individual files
14399 The Org export can filter not just for back-ends, but also for specific files
14400 through the @code{#+BIND} keyword. Here is an example with two filters; one
14401 removes brackets from time stamps, and the other removes strike-through text.
14402 The filter functions are defined in a @samp{src} code block in the same Org
14403 file, which is a handy location for debugging.
14406 #+BIND: org-export-filter-timestamp-functions (tmp-f-timestamp)
14407 #+BIND: org-export-filter-strike-through-functions (tmp-f-strike-through)
14408 #+begin_src emacs-lisp :exports results :results none
14409 (defun tmp-f-timestamp (s backend info)
14410 (replace-regexp-in-string "&[lg]t;\\|[][]" "" s))
14411 (defun tmp-f-strike-through (s backend info) "")
14415 @subheading Extending an existing back-end
14417 Some parts of the conversion process can be extended for certain elements so
14418 as to introduce a new or revised translation. That is how the HTML export
14419 back-end was extended to handle Markdown format. The extensions work
14420 seamlessly so any aspect of filtering not done by the extended back-end is
14421 handled by the original back-end. Of all the export customization in Org,
14422 extending is very powerful as it operates at the parser level.
14424 For this example, make the @code{ascii} back-end display the language used in
14425 a source code block. Also make it display only when some attribute is
14426 non-@code{nil}, like the following:
14429 #+ATTR_ASCII: :language t
14432 Then extend @code{ascii} back-end with a custom @code{my-ascii} back-end.
14436 (defun my-ascii-src-block (src-block contents info)
14437 "Transcode a SRC-BLOCK element from Org to ASCII.
14438 CONTENTS is nil. INFO is a plist used as a communication
14440 (if (not (org-export-read-attribute :attr_ascii src-block :language))
14441 (org-export-with-backend 'ascii src-block contents info)
14443 (format ",--[ %s ]--\n%s`----"
14444 (org-element-property :language src-block)
14445 (replace-regexp-in-string
14447 (org-element-normalize-string
14448 (org-export-format-code-default src-block info)))))))
14450 (org-export-define-derived-backend 'my-ascii 'ascii
14451 :translate-alist '((src-block . my-ascii-src-block)))
14455 The @code{my-ascii-src-block} function looks at the attribute above the
14456 current element. If not true, hands over to @code{ascii} back-end. If true,
14457 which it is in this example, it creates a box around the code and leaves room
14458 for the inserting a string for language. The last form creates the new
14459 back-end that springs to action only when translating @code{src-block} type
14462 To use the newly defined back-end, call the following from an Org buffer:
14465 (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
14468 Further steps to consider would be an interactive function, self-installing
14469 an item in the export dispatcher menu, and other user-friendly improvements.
14471 @node Export in foreign buffers
14472 @section Export in foreign buffers
14474 The export back-ends in Org often include commands to convert selected
14475 regions. A convenient feature of this in-place conversion is that the
14476 exported output replaces the original source. Here are such functions:
14479 @item org-html-convert-region-to-html
14480 Convert the selected region into HTML.
14481 @item org-latex-convert-region-to-latex
14482 Convert the selected region into @LaTeX{}.
14483 @item org-texinfo-convert-region-to-texinfo
14484 Convert the selected region into @code{Texinfo}.
14485 @item org-md-convert-region-to-md
14486 Convert the selected region into @code{MarkDown}.
14489 In-place conversions are particularly handy for quick conversion of tables
14490 and lists in foreign buffers. For example, turn on the minor mode @code{M-x
14491 orgstruct-mode} in an HTML buffer, then use the convenient Org keyboard
14492 commands to create a list, select it, and covert it to HTML with @code{M-x
14493 org-html-convert-region-to-html RET}.
14497 @chapter Publishing
14500 Org includes a publishing management system that allows you to configure
14501 automatic HTML conversion of @emph{projects} composed of interlinked org
14502 files. You can also configure Org to automatically upload your exported HTML
14503 pages and related attachments, such as images and source code files, to a web
14506 You can also use Org to convert files into PDF, or even combine HTML and PDF
14507 conversion so that files are available in both formats on the server.
14509 Publishing has been contributed to Org by David O'Toole.
14512 * Configuration:: Defining projects
14513 * Uploading files:: How to get files up on the server
14514 * Sample configuration:: Example projects
14515 * Triggering publication:: Publication commands
14518 @node Configuration
14519 @section Configuration
14521 Publishing needs significant configuration to specify files, destination
14522 and many other properties of a project.
14525 * Project alist:: The central configuration variable
14526 * Sources and destinations:: From here to there
14527 * Selecting files:: What files are part of the project?
14528 * Publishing action:: Setting the function doing the publishing
14529 * Publishing options:: Tweaking HTML/@LaTeX{} export
14530 * Publishing links:: Which links keep working after publishing?
14531 * Sitemap:: Generating a list of all pages
14532 * Generating an index:: An index that reaches across pages
14535 @node Project alist
14536 @subsection The variable @code{org-publish-project-alist}
14537 @cindex org-publish-project-alist
14538 @cindex projects, for publishing
14540 @vindex org-publish-project-alist
14541 Publishing is configured almost entirely through setting the value of one
14542 variable, called @code{org-publish-project-alist}. Each element of the list
14543 configures one project, and may be in one of the two following forms:
14546 ("project-name" :property value :property value ...)
14547 @r{i.e., a well-formed property list with alternating keys and values}
14549 ("project-name" :components ("project-name" "project-name" ...))
14553 In both cases, projects are configured by specifying property values. A
14554 project defines the set of files that will be published, as well as the
14555 publishing configuration to use when publishing those files. When a project
14556 takes the second form listed above, the individual members of the
14557 @code{:components} property are taken to be sub-projects, which group
14558 together files requiring different publishing options. When you publish such
14559 a ``meta-project'', all the components will also be published, in the
14562 @node Sources and destinations
14563 @subsection Sources and destinations for files
14564 @cindex directories, for publishing
14566 Most properties are optional, but some should always be set. In
14567 particular, Org needs to know where to look for source files,
14568 and where to put published files.
14570 @multitable @columnfractions 0.3 0.7
14571 @item @code{:base-directory}
14572 @tab Directory containing publishing source files
14573 @item @code{:publishing-directory}
14574 @tab Directory where output files will be published. You can directly
14575 publish to a web server using a file name syntax appropriate for
14576 the Emacs @file{tramp} package. Or you can publish to a local directory and
14577 use external tools to upload your website (@pxref{Uploading files}).
14578 @item @code{:preparation-function}
14579 @tab Function or list of functions to be called before starting the
14580 publishing process, for example, to run @code{make} for updating files to be
14581 published. Each preparation function is called with a single argument, the
14582 project property list.
14583 @item @code{:completion-function}
14584 @tab Function or list of functions called after finishing the publishing
14585 process, for example, to change permissions of the resulting files. Each
14586 completion function is called with a single argument, the project property
14591 @node Selecting files
14592 @subsection Selecting files
14593 @cindex files, selecting for publishing
14595 By default, all files with extension @file{.org} in the base directory
14596 are considered part of the project. This can be modified by setting the
14598 @multitable @columnfractions 0.25 0.75
14599 @item @code{:base-extension}
14600 @tab Extension (without the dot!) of source files. This actually is a
14601 regular expression. Set this to the symbol @code{any} if you want to get all
14602 files in @code{:base-directory}, even without extension.
14604 @item @code{:exclude}
14605 @tab Regular expression to match file names that should not be
14606 published, even though they have been selected on the basis of their
14609 @item @code{:include}
14610 @tab List of files to be included regardless of @code{:base-extension}
14611 and @code{:exclude}.
14613 @item @code{:recursive}
14614 @tab non-@code{nil} means, check base-directory recursively for files to publish.
14617 @node Publishing action
14618 @subsection Publishing action
14619 @cindex action, for publishing
14621 Publishing means that a file is copied to the destination directory and
14622 possibly transformed in the process. The default transformation is to export
14623 Org files as HTML files, and this is done by the function
14624 @code{org-html-publish-to-html}, which calls the HTML exporter (@pxref{HTML
14625 export}). But you also can publish your content as PDF files using
14626 @code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc.,
14627 using the corresponding functions.
14629 If you want to publish the Org file as an @code{.org} file but with the
14630 @i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the
14631 function @code{org-org-publish-to-org}. This will produce @file{file.org}
14632 and put it in the publishing directory. If you want a htmlized version of
14633 this file, set the parameter @code{:htmlized-source} to @code{t}, it will
14634 produce @file{file.org.html} in the publishing directory@footnote{If the
14635 publishing directory is the same than the source directory, @file{file.org}
14636 will be exported as @file{file.org.org}, so probably don't want to do this.}.
14638 Other files like images only need to be copied to the publishing destination.
14639 For this you can use @code{org-publish-attachment}. For non-org files, you
14640 always need to specify the publishing function:
14642 @multitable @columnfractions 0.3 0.7
14643 @item @code{:publishing-function}
14644 @tab Function executing the publication of a file. This may also be a
14645 list of functions, which will all be called in turn.
14646 @item @code{:htmlized-source}
14647 @tab non-@code{nil} means, publish htmlized source.
14650 The function must accept three arguments: a property list containing at least
14651 a @code{:publishing-directory} property, the name of the file to be published
14652 and the path to the publishing directory of the output file. It should take
14653 the specified file, make the necessary transformation (if any) and place the
14654 result into the destination folder.
14656 @node Publishing options
14657 @subsection Options for the exporters
14658 @cindex options, for publishing
14660 The property list can be used to set export options during the publishing
14661 process. In most cases, these properties correspond to user variables in
14662 Org. While some properties are available for all export back-ends, most of
14663 them are back-end specific. The following sections list properties along
14664 with the variable they belong to. See the documentation string of these
14665 options for details.
14667 @vindex org-publish-project-alist
14668 When a property is given a value in @code{org-publish-project-alist}, its
14669 setting overrides the value of the corresponding user variable (if any)
14670 during publishing. Options set within a file (@pxref{Export settings}),
14671 however, override everything.
14673 @subsubheading Generic properties
14675 @multitable {@code{:with-sub-superscript}} {@code{org-export-with-sub-superscripts}}
14676 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
14677 @item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
14678 @item @code{:headline-levels} @tab @code{org-export-headline-levels}
14679 @item @code{:language} @tab @code{org-export-default-language}
14680 @item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}
14681 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
14682 @item @code{:select-tags} @tab @code{org-export-select-tags}
14683 @item @code{:with-author} @tab @code{org-export-with-author}
14684 @item @code{:with-broken-links} @tab @code{org-export-with-broken-links}
14685 @item @code{:with-clocks} @tab @code{org-export-with-clocks}
14686 @item @code{:with-creator} @tab @code{org-export-with-creator}
14687 @item @code{:with-date} @tab @code{org-export-with-date}
14688 @item @code{:with-drawers} @tab @code{org-export-with-drawers}
14689 @item @code{:with-email} @tab @code{org-export-with-email}
14690 @item @code{:with-emphasize} @tab @code{org-export-with-emphasize}
14691 @item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width}
14692 @item @code{:with-footnotes} @tab @code{org-export-with-footnotes}
14693 @item @code{:with-latex} @tab @code{org-export-with-latex}
14694 @item @code{:with-planning} @tab @code{org-export-with-planning}
14695 @item @code{:with-priority} @tab @code{org-export-with-priority}
14696 @item @code{:with-properties} @tab @code{org-export-with-properties}
14697 @item @code{:with-special-strings} @tab @code{org-export-with-special-strings}
14698 @item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts}
14699 @item @code{:with-tables} @tab @code{org-export-with-tables}
14700 @item @code{:with-tags} @tab @code{org-export-with-tags}
14701 @item @code{:with-tasks} @tab @code{org-export-with-tasks}
14702 @item @code{:with-timestamps} @tab @code{org-export-with-timestamps}
14703 @item @code{:with-title} @tab @code{org-export-with-title}
14704 @item @code{:with-toc} @tab @code{org-export-with-toc}
14705 @item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords}
14708 @subsubheading ASCII specific properties
14710 @multitable {@code{:ascii-table-keep-all-vertical-lines}} {@code{org-ascii-table-keep-all-vertical-lines}}
14711 @item @code{:ascii-bullets} @tab @code{org-ascii-bullets}
14712 @item @code{:ascii-caption-above} @tab @code{org-ascii-caption-above}
14713 @item @code{:ascii-charset} @tab @code{org-ascii-charset}
14714 @item @code{:ascii-global-margin} @tab @code{org-ascii-global-margin}
14715 @item @code{:ascii-format-drawer-function} @tab @code{org-ascii-format-drawer-function}
14716 @item @code{:ascii-format-inlinetask-function} @tab @code{org-ascii-format-inlinetask-function}
14717 @item @code{:ascii-headline-spacing} @tab @code{org-ascii-headline-spacing}
14718 @item @code{:ascii-indented-line-width} @tab @code{org-ascii-indented-line-width}
14719 @item @code{:ascii-inlinetask-width} @tab @code{org-ascii-inlinetask-width}
14720 @item @code{:ascii-inner-margin} @tab @code{org-ascii-inner-margin}
14721 @item @code{:ascii-links-to-notes} @tab @code{org-ascii-links-to-notes}
14722 @item @code{:ascii-list-margin} @tab @code{org-ascii-list-margin}
14723 @item @code{:ascii-paragraph-spacing} @tab @code{org-ascii-paragraph-spacing}
14724 @item @code{:ascii-quote-margin} @tab @code{org-ascii-quote-margin}
14725 @item @code{:ascii-table-keep-all-vertical-lines} @tab @code{org-ascii-table-keep-all-vertical-lines}
14726 @item @code{:ascii-table-use-ascii-art} @tab @code{org-ascii-table-use-ascii-art}
14727 @item @code{:ascii-table-widen-columns} @tab @code{org-ascii-table-widen-columns}
14728 @item @code{:ascii-text-width} @tab @code{org-ascii-text-width}
14729 @item @code{:ascii-underline} @tab @code{org-ascii-underline}
14730 @item @code{:ascii-verbatim-format} @tab @code{org-ascii-verbatim-format}
14733 @subsubheading Beamer specific properties
14735 @multitable {@code{:beamer-frame-default-options}} {@code{org-beamer-frame-default-options}}
14736 @item @code{:beamer-theme} @tab @code{org-beamer-theme}
14737 @item @code{:beamer-column-view-format} @tab @code{org-beamer-column-view-format}
14738 @item @code{:beamer-environments-extra} @tab @code{org-beamer-environments-extra}
14739 @item @code{:beamer-frame-default-options} @tab @code{org-beamer-frame-default-options}
14740 @item @code{:beamer-outline-frame-options} @tab @code{org-beamer-outline-frame-options}
14741 @item @code{:beamer-outline-frame-title} @tab @code{org-beamer-outline-frame-title}
14742 @item @code{:beamer-subtitle-format} @tab @code{org-beamer-subtitle-format}
14745 @subsubheading HTML specific properties
14747 @multitable {@code{:html-table-use-header-tags-for-first-column}} {@code{org-html-table-use-header-tags-for-first-column}}
14748 @item @code{:html-allow-name-attribute-in-anchors} @tab @code{org-html-allow-name-attribute-in-anchors}
14749 @item @code{:html-checkbox-type} @tab @code{org-html-checkbox-type}
14750 @item @code{:html-container} @tab @code{org-html-container-element}
14751 @item @code{:html-divs} @tab @code{org-html-divs}
14752 @item @code{:html-doctype} @tab @code{org-html-doctype}
14753 @item @code{:html-extension} @tab @code{org-html-extension}
14754 @item @code{:html-footnote-format} @tab @code{org-html-footnote-format}
14755 @item @code{:html-footnote-separator} @tab @code{org-html-footnote-separator}
14756 @item @code{:html-footnotes-section} @tab @code{org-html-footnotes-section}
14757 @item @code{:html-format-drawer-function} @tab @code{org-html-format-drawer-function}
14758 @item @code{:html-format-headline-function} @tab @code{org-html-format-headline-function}
14759 @item @code{:html-format-inlinetask-function} @tab @code{org-html-format-inlinetask-function}
14760 @item @code{:html-head-extra} @tab @code{org-html-head-extra}
14761 @item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style}
14762 @item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts}
14763 @item @code{:html-head} @tab @code{org-html-head}
14764 @item @code{:html-home/up-format} @tab @code{org-html-home/up-format}
14765 @item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy}
14766 @item @code{:html-indent} @tab @code{org-html-indent}
14767 @item @code{:html-infojs-options} @tab @code{org-html-infojs-options}
14768 @item @code{:html-infojs-template} @tab @code{org-html-infojs-template}
14769 @item @code{:html-inline-image-rules} @tab @code{org-html-inline-image-rules}
14770 @item @code{:html-inline-images} @tab @code{org-html-inline-images}
14771 @item @code{:html-link-home} @tab @code{org-html-link-home}
14772 @item @code{:html-link-org-files-as-html} @tab @code{org-html-link-org-files-as-html}
14773 @item @code{:html-link-up} @tab @code{org-html-link-up}
14774 @item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url}
14775 @item @code{:html-mathjax-options} @tab @code{org-html-mathjax-options}
14776 @item @code{:html-mathjax-template} @tab @code{org-html-mathjax-template}
14777 @item @code{:html-metadata-timestamp-format} @tab @code{org-html-metadata-timestamp-format}
14778 @item @code{:html-postamble-format} @tab @code{org-html-postamble-format}
14779 @item @code{:html-postamble} @tab @code{org-html-postamble}
14780 @item @code{:html-preamble-format} @tab @code{org-html-preamble-format}
14781 @item @code{:html-preamble} @tab @code{org-html-preamble}
14782 @item @code{:html-table-align-individual-fields} @tab @code{org-html-table-align-individual-fields}
14783 @item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
14784 @item @code{:html-table-caption-above} @tab @code{org-html-table-caption-above}
14785 @item @code{:html-table-data-tags} @tab @code{org-html-table-data-tags}
14786 @item @code{:html-table-header-tags} @tab @code{org-html-table-header-tags}
14787 @item @code{:html-table-row-tags} @tab @code{org-html-table-row-tags}
14788 @item @code{:html-table-use-header-tags-for-first-column} @tab @code{org-html-table-use-header-tags-for-first-column}
14789 @item @code{:html-tag-class-prefix} @tab @code{org-html-tag-class-prefix}
14790 @item @code{:html-text-markup-alist} @tab @code{org-html-text-markup-alist}
14791 @item @code{:html-todo-kwd-class-prefix} @tab @code{org-html-todo-kwd-class-prefix}
14792 @item @code{:html-toplevel-hlevel} @tab @code{org-html-toplevel-hlevel}
14793 @item @code{:html-use-infojs} @tab @code{org-html-use-infojs}
14794 @item @code{:html-validation-link} @tab @code{org-html-validation-link}
14795 @item @code{:html-viewport} @tab @code{org-html-viewport}
14796 @item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration}
14799 @subsubheading @LaTeX{} specific properties
14801 @multitable {@code{:latex-link-with-unknown-path-format}} {@code{org-latex-link-with-unknown-path-format}}
14802 @item @code{:latex-active-timestamp-format} @tab @code{org-latex-active-timestamp-format}
14803 @item @code{:latex-caption-above} @tab @code{org-latex-caption-above}
14804 @item @code{:latex-classes} @tab @code{org-latex-classes}
14805 @item @code{:latex-class} @tab @code{org-latex-default-class}
14806 @item @code{:latex-compiler} @tab @code{org-latex-compiler}
14807 @item @code{:latex-default-figure-position} @tab @code{org-latex-default-figure-position}
14808 @item @code{:latex-default-table-environment} @tab @code{org-latex-default-table-environment}
14809 @item @code{:latex-default-table-mode} @tab @code{org-latex-default-table-mode}
14810 @item @code{:latex-diary-timestamp-format} @tab @code{org-latex-diary-timestamp-format}
14811 @item @code{:latex-footnote-defined-format} @tab @code{org-latex-footnote-defined-format}
14812 @item @code{:latex-footnote-separator} @tab @code{org-latex-footnote-separator}
14813 @item @code{:latex-format-drawer-function} @tab @code{org-latex-format-drawer-function}
14814 @item @code{:latex-format-headline-function} @tab @code{org-latex-format-headline-function}
14815 @item @code{:latex-format-inlinetask-function} @tab @code{org-latex-format-inlinetask-function}
14816 @item @code{:latex-hyperref-template} @tab @code{org-latex-hyperref-template}
14817 @item @code{:latex-image-default-height} @tab @code{org-latex-image-default-height}
14818 @item @code{:latex-image-default-option} @tab @code{org-latex-image-default-option}
14819 @item @code{:latex-image-default-width} @tab @code{org-latex-image-default-width}
14820 @item @code{:latex-images-centered} @tab @code{org-latex-images-centered}
14821 @item @code{:latex-inactive-timestamp-format} @tab @code{org-latex-inactive-timestamp-format}
14822 @item @code{:latex-inline-image-rules} @tab @code{org-latex-inline-image-rules}
14823 @item @code{:latex-link-with-unknown-path-format} @tab @code{org-latex-link-with-unknown-path-format}
14824 @item @code{:latex-listings-langs} @tab @code{org-latex-listings-langs}
14825 @item @code{:latex-listings-options} @tab @code{org-latex-listings-options}
14826 @item @code{:latex-listings} @tab @code{org-latex-listings}
14827 @item @code{:latex-minted-langs} @tab @code{org-latex-minted-langs}
14828 @item @code{:latex-minted-options} @tab @code{org-latex-minted-options}
14829 @item @code{:latex-prefer-user-labels} @tab @code{org-latex-prefer-user-labels}
14830 @item @code{:latex-subtitle-format} @tab @code{org-latex-subtitle-format}
14831 @item @code{:latex-subtitle-separate} @tab @code{org-latex-subtitle-separate}
14832 @item @code{:latex-table-scientific-notation} @tab @code{org-latex-table-scientific-notation}
14833 @item @code{:latex-tables-booktabs} @tab @code{org-latex-tables-booktabs}
14834 @item @code{:latex-tables-centered} @tab @code{org-latex-tables-centered}
14835 @item @code{:latex-text-markup-alist} @tab @code{org-latex-text-markup-alist}
14836 @item @code{:latex-title-command} @tab @code{org-latex-title-command}
14837 @item @code{:latex-toc-command} @tab @code{org-latex-toc-command}
14840 @subsubheading Markdown specific properties
14842 @multitable {@code{:md-footnotes-section}} {@code{org-md-footnotes-section}}
14843 @item @code{:md-footnote-format} @tab @code{org-md-footnote-format}
14844 @item @code{:md-footnotes-section} @tab @code{org-md-footnotes-section}
14845 @item @code{:md-headline-style} @tab @code{org-md-headline-style}
14848 @subsubheading ODT specific properties
14850 @multitable {@code{:odt-format-inlinetask-function}} {@code{org-odt-format-inlinetask-function}}
14851 @item @code{:odt-content-template-file} @tab @code{org-odt-content-template-file}
14852 @item @code{:odt-display-outline-level} @tab @code{org-odt-display-outline-level}
14853 @item @code{:odt-fontify-srcblocks} @tab @code{org-odt-fontify-srcblocks}
14854 @item @code{:odt-format-drawer-function} @tab @code{org-odt-format-drawer-function}
14855 @item @code{:odt-format-headline-function} @tab @code{org-odt-format-headline-function}
14856 @item @code{:odt-format-inlinetask-function} @tab @code{org-odt-format-inlinetask-function}
14857 @item @code{:odt-inline-formula-rules} @tab @code{org-odt-inline-formula-rules}
14858 @item @code{:odt-inline-image-rules} @tab @code{org-odt-inline-image-rules}
14859 @item @code{:odt-pixels-per-inch} @tab @code{org-odt-pixels-per-inch}
14860 @item @code{:odt-styles-file} @tab @code{org-odt-styles-file}
14861 @item @code{:odt-table-styles} @tab @code{org-odt-table-styles}
14862 @item @code{:odt-use-date-fields} @tab @code{org-odt-use-date-fields}
14865 @subsubheading Texinfo specific properties
14867 @multitable {@code{:texinfo-link-with-unknown-path-format}} {@code{org-texinfo-link-with-unknown-path-format}}
14868 @item @code{:texinfo-active-timestamp-format} @tab @code{org-texinfo-active-timestamp-format}
14869 @item @code{:texinfo-classes} @tab @code{org-texinfo-classes}
14870 @item @code{:texinfo-class} @tab @code{org-texinfo-default-class}
14871 @item @code{:texinfo-table-default-markup} @tab @code{org-texinfo-table-default-markup}
14872 @item @code{:texinfo-diary-timestamp-format} @tab @code{org-texinfo-diary-timestamp-format}
14873 @item @code{:texinfo-filename} @tab @code{org-texinfo-filename}
14874 @item @code{:texinfo-format-drawer-function} @tab @code{org-texinfo-format-drawer-function}
14875 @item @code{:texinfo-format-headline-function} @tab @code{org-texinfo-format-headline-function}
14876 @item @code{:texinfo-format-inlinetask-function} @tab @code{org-texinfo-format-inlinetask-function}
14877 @item @code{:texinfo-inactive-timestamp-format} @tab @code{org-texinfo-inactive-timestamp-format}
14878 @item @code{:texinfo-link-with-unknown-path-format} @tab @code{org-texinfo-link-with-unknown-path-format}
14879 @item @code{:texinfo-node-description-column} @tab @code{org-texinfo-node-description-column}
14880 @item @code{:texinfo-table-scientific-notation} @tab @code{org-texinfo-table-scientific-notation}
14881 @item @code{:texinfo-tables-verbatim} @tab @code{org-texinfo-tables-verbatim}
14882 @item @code{:texinfo-text-markup-alist} @tab @code{org-texinfo-text-markup-alist}
14885 @node Publishing links
14886 @subsection Links between published files
14887 @cindex links, publishing
14889 To create a link from one Org file to another, you would use something like
14890 @samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org}
14891 (@pxref{External links}). When published, this link becomes a link to
14892 @file{foo.html}. You can thus interlink the pages of your ``org web''
14893 project and the links will work as expected when you publish them to HTML.
14894 If you also publish the Org source file and want to link to it, use an
14895 @code{http:} link instead of a @code{file:} link, because @code{file:} links
14896 are converted to link to the corresponding @file{html} file.
14898 You may also link to related files, such as images. Provided you are careful
14899 with relative file names, and provided you have also configured Org to upload
14900 the related files, these links will work too. See @ref{Complex example}, for
14901 an example of this usage.
14903 Eventually, links between published documents can contain some search options
14904 (@pxref{Search options}), which will be resolved to the appropriate location
14905 in the linked file. For example, once published to HTML, the following links
14906 all point to a dedicated anchor in @file{foo.html}.
14909 [[file:foo.org::*heading]]
14910 [[file:foo.org::#custom-id]]
14911 [[file:foo.org::target]]
14915 @subsection Generating a sitemap
14916 @cindex sitemap, of published pages
14918 The following properties may be used to control publishing of
14919 a map of files for a given project.
14921 @multitable @columnfractions 0.35 0.65
14922 @item @code{:auto-sitemap}
14923 @tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project}
14924 or @code{org-publish-all}.
14926 @item @code{:sitemap-filename}
14927 @tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which
14928 becomes @file{sitemap.html}).
14930 @item @code{:sitemap-title}
14931 @tab Title of sitemap page. Defaults to name of file.
14933 @item @code{:sitemap-format-entry}
14934 @tab With this option one can tell how a site-map entry is formatted in the
14935 site-map. It is a function called with three arguments: the file or
14936 directory name relative to base directory of the project, the site-map style
14937 and the current project. It is expected to return a string. Default value
14938 turns file names into links and use document titles as descriptions. For
14939 specific formatting needs, one can use @code{org-publish-find-date},
14940 @code{org-publish-find-title} and @code{org-publish-find-property}, to
14941 retrieve additional information about published documents.
14943 @item @code{:sitemap-function}
14944 @tab Plug-in function to use for generation of the sitemap. It is called
14945 with two arguments: the title of the site-map and a representation of the
14946 files and directories involved in the project as a radio list (@pxref{Radio
14947 lists}). The latter can further be transformed using
14948 @code{org-list-to-generic}, @code{org-list-to-subtree} and alike. Default
14949 value generates a plain list of links to all files in the project.
14951 @item @code{:sitemap-sort-folders}
14952 @tab Where folders should appear in the sitemap. Set this to @code{first}
14953 (default) or @code{last} to display folders first or last, respectively.
14954 When set to @code{ignore}, folders are ignored altogether. Any other value
14955 will mix files and folders. This variable has no effect when site-map style
14958 @item @code{:sitemap-sort-files}
14959 @tab How the files are sorted in the site map. Set this to
14960 @code{alphabetically} (default), @code{chronologically} or
14961 @code{anti-chronologically}. @code{chronologically} sorts the files with
14962 older date first while @code{anti-chronologically} sorts the files with newer
14963 date first. @code{alphabetically} sorts the files alphabetically. The date of
14964 a file is retrieved with @code{org-publish-find-date}.
14966 @item @code{:sitemap-ignore-case}
14967 @tab Should sorting be case-sensitive? Default @code{nil}.
14969 @item @code{:sitemap-date-format}
14970 @tab Format string for the @code{format-time-string} function that tells how
14971 a sitemap entry's date is to be formatted. This property bypasses
14972 @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
14976 @node Generating an index
14977 @subsection Generating an index
14978 @cindex index, in a publishing project
14980 Org mode can generate an index across the files of a publishing project.
14982 @multitable @columnfractions 0.25 0.75
14983 @item @code{:makeindex}
14984 @tab When non-@code{nil}, generate in index in the file @file{theindex.org} and
14985 publish it as @file{theindex.html}.
14988 The file will be created when first publishing a project with the
14989 @code{:makeindex} set. The file only contains a statement @code{#+INCLUDE:
14990 "theindex.inc"}. You can then build around this include statement by adding
14991 a title, style information, etc.
14994 Index entries are specified with @code{#+INDEX} keyword. An entry that
14995 contains an exclamation mark will create a sub item.
15000 #+INDEX: Application!CV
15003 @node Uploading files
15004 @section Uploading files
15008 For those people already utilizing third party sync tools such as
15009 @command{rsync} or @command{unison}, it might be preferable not to use the built in
15010 @i{remote} publishing facilities of Org mode which rely heavily on
15011 Tramp. Tramp, while very useful and powerful, tends not to be
15012 so efficient for multiple file transfer and has been known to cause problems
15015 Specialized synchronization utilities offer several advantages. In addition
15016 to timestamp comparison, they also do content and permissions/attribute
15017 checks. For this reason you might prefer to publish your web to a local
15018 directory (possibly even @i{in place} with your Org files) and then use
15019 @file{unison} or @file{rsync} to do the synchronization with the remote host.
15021 Since Unison (for example) can be configured as to which files to transfer to
15022 a certain remote destination, it can greatly simplify the project publishing
15023 definition. Simply keep all files in the correct location, process your Org
15024 files with @code{org-publish} and let the synchronization tool do the rest.
15025 You do not need, in this scenario, to include attachments such as @file{jpg},
15026 @file{css} or @file{gif} files in the project definition since the 3rd party
15029 Publishing to a local directory is also much faster than to a remote one, so
15030 that you can afford more easily to republish entire projects. If you set
15031 @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
15032 benefit of re-including any changed external files such as source example
15033 files you might include with @code{#+INCLUDE:}. The timestamp mechanism in
15034 Org is not smart enough to detect if included files have been modified.
15036 @node Sample configuration
15037 @section Sample configuration
15039 Below we provide two example configurations. The first one is a simple
15040 project publishing only a set of Org files. The second example is
15041 more complex, with a multi-component project.
15044 * Simple example:: One-component publishing
15045 * Complex example:: A multi-component publishing example
15048 @node Simple example
15049 @subsection Example: simple publishing configuration
15051 This example publishes a set of Org files to the @file{public_html}
15052 directory on the local machine.
15055 (setq org-publish-project-alist
15057 :base-directory "~/org/"
15058 :publishing-directory "~/public_html"
15059 :publishing-function org-html-publish-to-html
15060 :section-numbers nil
15062 :html-head "<link rel=\"stylesheet\"
15063 href=\"../other/mystyle.css\"
15064 type=\"text/css\"/>")))
15067 @node Complex example
15068 @subsection Example: complex publishing configuration
15070 This more complicated example publishes an entire website, including
15071 Org files converted to HTML, image files, Emacs Lisp source code, and
15072 style sheets. The publishing directory is remote and private files are
15075 To ensure that links are preserved, care should be taken to replicate
15076 your directory structure on the web server, and to use relative file
15077 paths. For example, if your Org files are kept in @file{~/org} and your
15078 publishable images in @file{~/images}, you would link to an image with
15081 file:../images/myimage.png
15084 On the web server, the relative path to the image should be the
15085 same. You can accomplish this by setting up an "images" folder in the
15086 right place on the web server, and publishing images to it.
15089 (setq org-publish-project-alist
15091 :base-directory "~/org/"
15092 :base-extension "org"
15093 :publishing-directory "/ssh:user@@host:~/html/notebook/"
15094 :publishing-function org-html-publish-to-html
15095 :exclude "PrivatePage.org" ;; regexp
15097 :section-numbers nil
15099 :html-head "<link rel=\"stylesheet\"
15100 href=\"../other/mystyle.css\" type=\"text/css\"/>"
15104 :base-directory "~/images/"
15105 :base-extension "jpg\\|gif\\|png"
15106 :publishing-directory "/ssh:user@@host:~/html/images/"
15107 :publishing-function org-publish-attachment)
15110 :base-directory "~/other/"
15111 :base-extension "css\\|el"
15112 :publishing-directory "/ssh:user@@host:~/html/other/"
15113 :publishing-function org-publish-attachment)
15114 ("website" :components ("orgfiles" "images" "other"))))
15117 @node Triggering publication
15118 @section Triggering publication
15120 Once properly configured, Org can publish with the following commands:
15123 @orgcmd{C-c C-e P x,org-publish}
15124 Prompt for a specific project and publish all files that belong to it.
15125 @orgcmd{C-c C-e P p,org-publish-current-project}
15126 Publish the project containing the current file.
15127 @orgcmd{C-c C-e P f,org-publish-current-file}
15128 Publish only the current file.
15129 @orgcmd{C-c C-e P a,org-publish-all}
15130 Publish every project.
15133 @vindex org-publish-use-timestamps-flag
15134 Org uses timestamps to track when a file has changed. The above functions
15135 normally only publish changed files. You can override this and force
15136 publishing of all files by giving a prefix argument to any of the commands
15137 above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
15138 This may be necessary in particular if files include other files via
15139 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
15142 @node Working with source code
15143 @chapter Working with source code
15144 @cindex Schulte, Eric
15145 @cindex Davison, Dan
15146 @cindex source code, working with
15148 Source code here refers to any code typed in Org mode documents. Org can
15149 manage source code in any Org file once such code is tagged with begin and
15150 end markers. Working with source code begins with tagging source code
15151 blocks. Tagged @samp{src} code blocks are not restricted to the preamble or
15152 the end of an Org document; they can go anywhere---with a few exceptions,
15153 such as not inside comments and fixed width areas. Here's a sample
15154 @samp{src} code block in emacs-lisp:
15157 #+BEGIN_SRC emacs-lisp
15158 (defun org-xor (a b)
15164 Org can take the code in the block between the @samp{#+BEGIN_SRC} and
15165 @samp{#+END_SRC} tags, and format, compile, execute, and show the results.
15166 Org can simplify many housekeeping tasks essential to modern code
15167 maintenance. That's why these blocks in Org mode literature are sometimes
15168 referred to as @samp{live code} blocks (as compared to the static text and
15169 documentation around it). Users can control how @samp{live} they want each
15170 block by tweaking the headers for compiling, execution, extraction.
15172 Org's @samp{src} code block type is one of many block types, such as quote,
15173 export, verse, latex, example, and verbatim. This section pertains to
15174 @samp{src} code blocks between @samp{#+BEGIN_SRC} and @samp{#+END_SRC}
15176 For editing @samp{src} code blocks, Org provides native Emacs major-modes.
15177 That leverages the latest Emacs features for that source code language mode.
15179 For exporting, Org can then extract @samp{src} code blocks into compilable
15180 source files (in a conversion process known as @dfn{tangling} in literate
15181 programming terminology).
15183 For publishing, Org's back-ends can handle the @samp{src} code blocks and the
15184 text for output to a variety of formats with native syntax highlighting.
15186 For executing the source code in the @samp{src} code blocks, Org provides
15187 facilities that glue the tasks of compiling, collecting the results of the
15188 execution, and inserting them back to the Org file. Besides text output,
15189 results may include links to other data types that Emacs can handle: audio,
15190 video, and graphics.
15192 An important feature of Org's execution of the @samp{src} code blocks is
15193 passing variables, functions, and results between @samp{src} blocks. Such
15194 interoperability uses a common syntax even if these @samp{src} blocks are in
15195 different source code languages. The integration extends to linking the
15196 debugger's error messages to the line in the @samp{src} code block in the Org
15197 file. That should partly explain why this functionality by the original
15198 contributors, Eric Schulte and Dan Davison, was called @samp{Org Babel}.
15200 In literate programming, the main appeal is code and documentation
15201 co-existing in one file. Org mode takes this several steps further. First
15202 by enabling execution, and then by inserting results of that execution back
15203 into the Org file. Along the way, Org provides extensive formatting
15204 features, including handling tables. Org handles multiple source code
15205 languages in one file, and provides a common syntax for passing variables,
15206 functions, and results between @samp{src} code blocks.
15208 Org mode fulfills the promise of easy verification and maintenance of
15209 publishing reproducible research by keeping all these in the same file: text,
15210 data, code, configuration settings of the execution environment, the results
15211 of the execution, and associated narratives, claims, references, and internal
15212 and external links.
15214 Details of Org's facilities for working with source code are shown next.
15217 * Structure of code blocks:: Code block syntax described
15218 * Editing source code:: Language major-mode editing
15219 * Exporting code blocks:: Export contents and/or results
15220 * Extracting source code:: Create pure source code files
15221 * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
15222 * Library of Babel:: Use and contribute to a library of useful code blocks
15223 * Languages:: List of supported code block languages
15224 * Header arguments:: Configure code block functionality
15225 * Results of evaluation:: How evaluation results are handled
15226 * Noweb reference syntax:: Literate programming in Org mode
15227 * Key bindings and useful functions:: Work quickly with code blocks
15228 * Batch execution:: Call functions from the command line
15232 @node Structure of code blocks
15233 @section Structure of code blocks
15234 @cindex code block, structure
15235 @cindex source code, block structure
15237 @cindex #+BEGIN_SRC
15239 Org offers two ways to structure source code in Org documents: in a
15240 @samp{src} block, and directly inline. Both specifications are shown below.
15242 A @samp{src} block conforms to this structure:
15246 #+BEGIN_SRC <language> <switches> <header arguments>
15251 Do not be put-off by having to remember the source block syntax. Org mode
15252 offers a command for wrapping existing text in a block (@pxref{Structure
15253 templates}). Org also works with other completion systems in Emacs, some of
15254 which predate Org and have custom domain-specific languages for defining
15255 templates. Regular use of templates reduces errors, increases accuracy, and
15256 maintains consistency.
15258 @cindex source code, inline
15259 An inline code block conforms to this structure:
15262 src_<language>@{<body>@}
15268 src_<language>[<header arguments>]@{<body>@}
15272 @item #+NAME: <name>
15273 Optional. Names the @samp{src} block so it can be called, like a function,
15274 from other @samp{src} blocks or inline blocks to evaluate or to capture the
15275 results. Code from other blocks, other files, and from table formulas
15276 (@pxref{The spreadsheet}) can use the name to reference a @samp{src} block.
15277 This naming serves the same purpose as naming Org tables. Org mode requires
15278 unique names. For duplicate names, Org mode's behavior is undefined.
15282 Mandatory. They mark the start and end of a block that Org requires. The
15283 @code{#+BEGIN_SRC} line takes additional arguments, as described next.
15284 @cindex begin block, end block
15286 Mandatory for live code blocks. It is the identifier of the source code
15287 language in the block. @xref{Languages}, for identifiers of supported
15289 @cindex source code, language
15291 Optional. Switches provide finer control of the code execution, export, and
15292 format (see the discussion of switches in @ref{Literal examples})
15293 @cindex source code, switches
15294 @item <header arguments>
15295 Optional. Heading arguments control many aspects of evaluation, export and
15296 tangling of code blocks (@pxref{Header arguments}). Using Org's properties
15297 feature, header arguments can be selectively applied to the entire buffer or
15298 specific sub-trees of the Org document.
15299 @item source code, header arguments
15301 Source code in the dialect of the specified language identifier.
15304 @node Editing source code
15305 @section Editing source code
15306 @cindex code block, editing
15307 @cindex source code, editing
15309 @vindex org-edit-src-auto-save-idle-delay
15310 @vindex org-edit-src-turn-on-auto-save
15312 @kbd{C-c '} for editing the current code block. It opens a new major-mode
15313 edit buffer containing the body of the @samp{src} code block, ready for any
15314 edits. @kbd{C-c '} again to close the buffer and return to the Org buffer.
15316 @key{C-x C-s} saves the buffer and updates the contents of the Org buffer.
15318 Set @code{org-edit-src-auto-save-idle-delay} to save the base buffer after
15319 a certain idle delay time.
15321 Set @code{org-edit-src-turn-on-auto-save} to auto-save this buffer into a
15322 separate file using @code{auto-save-mode}.
15324 @kbd{C-c '} to close the major-mode buffer and return back to the Org buffer.
15326 While editing the source code in the major-mode, the @code{org-src-mode}
15327 minor mode remains active. It provides these customization variables as
15328 described below. For even more variables, look in the customization
15329 group @code{org-edit-structure}.
15332 @item org-src-lang-modes
15333 If an Emacs major-mode named @code{<lang>-mode} exists, where @code{<lang>}
15334 is the language identifier from code block's header line, then the edit
15335 buffer uses that major-mode. Use this variable to arbitrarily map language
15336 identifiers to major modes.
15337 @item org-src-window-setup
15338 For specifying Emacs window arrangement when the new edit buffer is created.
15339 @item org-src-preserve-indentation
15340 @cindex indentation, in source blocks
15341 Default is @code{nil}. Source code is indented. This indentation applies
15342 during export or tangling, and depending on the context, may alter leading
15343 spaces and tabs. When non-@code{nil}, source code is aligned with the
15344 leftmost column. No lines are modified during export or tangling, which is
15345 very useful for white-space sensitive languages, such as Python.
15346 @item org-src-ask-before-returning-to-edit-buffer
15347 When @code{nil}, Org returns to the edit buffer without further prompts. The
15348 default prompts for a confirmation.
15351 Set @code{org-src-fontify-natively} to non-@code{nil} to turn on native code
15352 fontification in the @emph{Org} buffer. Fontification of @samp{src} code
15353 blocks can give visual separation of text and code on the display page. To
15354 further customize the appearance of @code{org-block} for specific languages,
15355 customize @code{org-src-block-faces}. The following example shades the
15356 background of regular blocks, and colors source blocks only for Python and
15357 Emacs-Lisp languages.
15360 (set-face-attribute 'org-block nil :background
15362 (face-attribute 'default :background) 3))
15364 (setq org-src-block-faces '(("emacs-lisp" (:background "#EEE2FF"))
15365 ("python" (:background "#E5FFB8"))))
15368 @node Exporting code blocks
15369 @section Exporting code blocks
15370 @cindex code block, exporting
15371 @cindex source code, exporting
15373 Org can flexibly export just the @emph{code} from the code blocks, just the
15374 @emph{results} of evaluation of the code block, @emph{both} the code and the
15375 results of the code block evaluation, or @emph{none}. Org defaults to
15376 exporting @emph{code} for most languages. For some languages, such as
15377 @code{ditaa}, Org defaults to @emph{results}. To export just the body of
15378 code blocks, @pxref{Literal examples}. To selectively export sub-trees of
15379 an Org document, @pxref{Exporting}.
15381 The @code{:exports} header arguments control exporting code blocks only and
15384 @subsubheading Header arguments:
15387 @cindex @code{:exports}, src header argument
15388 @item :exports code
15389 This is the default for most languages where the body of the code block is
15390 exported. See @ref{Literal examples} for more.
15391 @item :exports results
15392 On export, Org includes only the results and not the code block. After each
15393 evaluation, Org inserts the results after the end of code block in the Org
15394 buffer. By default, Org replaces any previous results. Org can also append
15396 @item :exports both
15397 Org exports both the code block and the results.
15398 @item :exports none
15399 Org does not export the code block nor the results.
15402 @vindex org-export-use-babel
15403 To stop Org from evaluating code blocks to speed exports, use the header
15404 argument @code{:eval never-export} (@pxref{eval}). To stop Org from
15405 evaluating code blocks for greater security, set the
15406 @code{org-export-use-babel} variable to @code{nil}, but understand that
15407 header arguments will have no effect.
15409 Turning off evaluation comes in handy when batch processing. For example,
15410 markup languages for wikis, which have a high risk of untrusted code.
15411 Stopping code block evaluation also stops evaluation of all header arguments
15412 of the code block. This may not be desirable in some circumstances. So
15413 during export, to allow evaluation of just the header arguments but not any
15414 code evaluation in the source block, set @code{:eval never-export}
15417 Org never evaluates code blocks in commented sub-trees when exporting
15418 (@pxref{Comment lines}). On the other hand, Org does evaluate code blocks in
15419 sub-trees excluded from export (@pxref{Export settings}).
15421 @node Extracting source code
15422 @section Extracting source code
15424 @cindex source code, extracting
15425 @cindex code block, extracting source code
15427 Extracting source code from code blocks is a basic task in literate
15428 programming. Org has features to make this easy. In literate programming
15429 parlance, documents on creation are @emph{woven} with code and documentation,
15430 and on export, the code is @emph{tangled} for execution by a computer. Org
15431 facilitates weaving and tangling for producing, maintaining, sharing, and
15432 exporting literate programming documents. Org provides extensive
15433 customization options for extracting source code.
15435 When Org tangles @samp{src} code blocks, it expands, merges, and transforms
15436 them. Then Org recomposes them into one or more separate files, as
15437 configured through the options. During this @emph{tangling} process, Org
15438 expands variables in the source code, and resolves any Noweb style references
15439 (@pxref{Noweb reference syntax}).
15441 @subsubheading Header arguments
15444 @cindex @code{:tangle}, src header argument
15446 By default, Org does not tangle the @samp{src} code block on export.
15448 Org extracts the contents of the code block for the tangled output. By
15449 default, the output file name is the same as the Org file but with a file
15450 extension derived from the language identifier of the @samp{src} code block.
15451 @item :tangle filename
15452 Override the default file name with this one for the tangled output.
15456 @subsubheading Functions
15459 @item org-babel-tangle
15460 Tangle the current file. Bound to @kbd{C-c C-v t}.
15462 With prefix argument only tangle the current @samp{src} code block.
15463 @item org-babel-tangle-file
15464 Choose a file to tangle. Bound to @kbd{C-c C-v f}.
15467 @subsubheading Hooks
15470 @item org-babel-post-tangle-hook
15471 This hook runs from within code tangled by @code{org-babel-tangle}, making it
15472 suitable for post-processing, compilation, and evaluation of code in the
15476 @subsubheading Jumping between code and Org
15478 Debuggers normally link errors and messages back to the source code. But for
15479 tangled files, we want to link back to the Org file, not to the tangled
15480 source file. To make this extra jump, Org uses
15481 @code{org-babel-tangle-jump-to-org} function with two additional source code
15482 block header arguments: One, set @code{padline} (@pxref{padline}) to true
15483 (the default setting). Two, set @code{comments} (@pxref{comments}) to
15484 @code{link}, which makes Org insert links to the Org file.
15486 @node Evaluating code blocks
15487 @section Evaluating code blocks
15488 @cindex code block, evaluating
15489 @cindex source code, evaluating
15492 A note about security: With code evaluation comes the risk of harm. Org
15493 safeguards by prompting for user's permission before executing any code in
15494 the source block. To customize this safeguard (or disable it) see @ref{Code
15495 evaluation security}.
15497 Org captures the results of the @samp{src} code block evaluation and inserts
15498 them in the Org file, right after the @samp{src} code block. The insertion
15499 point is after a newline and the @code{#+RESULTS} label. Org creates the
15500 @code{#+RESULTS} label if one is not already there.
15502 By default, Org enables only @code{emacs-lisp} @samp{src} code blocks for
15503 execution. See @ref{Languages} for identifiers to enable other languages.
15506 Org provides many ways to execute @samp{src} code blocks. @kbd{C-c C-c} or
15507 @kbd{C-c C-v e} with the point on a @samp{src} code block@footnote{The option
15508 @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used to remove code
15509 evaluation from the @kbd{C-c C-c} key binding.} calls the
15510 @code{org-babel-execute-src-block} function, which executes the code in the
15511 block, collects the results, and inserts them in the buffer.
15514 By calling a named code block@footnote{Actually, the constructs call_<name>()
15515 and src_<lang>@{@} are not evaluated when they appear in a keyword line
15516 (i.e. lines starting with @code{#+KEYWORD:}, @pxref{In-buffer settings}).}
15517 from an Org mode buffer or a table. Org can call the named @samp{src} code
15518 blocks from the current Org mode buffer or from the ``Library of Babel''
15519 (@pxref{Library of Babel}). Whether inline syntax or the @code{#+CALL:}
15520 syntax is used, the result is wrapped based on the variable
15521 @code{org-babel-inline-result-wrap}, which by default is set to @code{"=%s="}
15522 to produce verbatim text suitable for markup.
15524 The syntax for @code{#+CALL:} is
15527 #+CALL: <name>(<arguments>)
15528 #+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
15531 The syntax for inline named code block is
15534 ... call_<name>(<arguments>) ...
15535 ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
15540 This is the name of the code block to be evaluated (@pxref{Structure of
15543 Org passes arguments to the code block using standard function call syntax.
15544 For example, a @code{#+CALL:} line that passes @samp{4} to a code block named
15545 @code{double}, which declares the header argument @code{:var n=2}, would be
15546 written as @code{#+CALL: double(n=4)}. Note how this function call syntax is
15547 different from the header argument syntax.
15548 @item <inside header arguments>
15549 Org passes inside header arguments to the named @samp{src} code block using
15550 the header argument syntax. Inside header arguments apply to code block
15551 evaluation. For example, @code{[:results output]} collects results printed
15552 to @code{STDOUT} during code execution of that block. Note how this header
15553 argument syntax is different from the function call syntax.
15554 @item <end header arguments>
15555 End header arguments affect the results returned by the code block. For
15556 example, @code{:results html} wraps the results in a @code{BEGIN_EXPORT html}
15557 block before inserting the results in the Org buffer.
15559 For more examples of header arguments for @code{#+CALL:} lines,
15560 @pxref{Arguments in function calls}.
15563 @node Library of Babel
15564 @section Library of Babel
15565 @cindex babel, library of
15566 @cindex source code, library
15567 @cindex code block, library
15569 The ``Library of Babel'' is a collection of code blocks. Like a function
15570 library, these code blocks can be called from other Org files. A collection
15571 of useful code blocks is available on
15572 @uref{http://orgmode.org/worg/library-of-babel.html,Worg}. For remote code
15573 block evaluation syntax, @pxref{Evaluating code blocks}.
15576 For any user to add code to the library, first save the code in regular
15577 @samp{src} code blocks of an Org file, and then load the Org file with
15578 @code{org-babel-lob-ingest}, which is bound to @kbd{C-c C-v i}.
15582 @cindex babel, languages
15583 @cindex source code, languages
15584 @cindex code block, languages
15586 Org supports the following languages for the @samp{src} code blocks:
15588 @multitable @columnfractions 0.25 0.25 0.25 0.25
15589 @headitem @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}
15590 @item Asymptote @tab asymptote @tab Awk @tab awk
15591 @item C @tab C @tab C++ @tab C++
15592 @item Clojure @tab clojure @tab CSS @tab css
15593 @item D @tab d @tab ditaa @tab ditaa
15594 @item Graphviz @tab dot @tab Emacs Calc @tab calc
15595 @item Emacs Lisp @tab emacs-lisp @tab Fortran @tab fortran
15596 @item gnuplot @tab gnuplot @tab Haskell @tab haskell
15597 @item Java @tab java @tab Javascript @tab js
15598 @item LaTeX @tab latex @tab Ledger @tab ledger
15599 @item Lisp @tab lisp @tab Lilypond @tab lilypond
15600 @item Lua @tab lua @tab MATLAB @tab matlab
15601 @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
15602 @item Octave @tab octave @tab Org mode @tab org
15603 @item Oz @tab oz @tab Perl @tab perl
15604 @item Plantuml @tab plantuml @tab Processing.js @tab processing
15605 @item Python @tab python @tab R @tab R
15606 @item Ruby @tab ruby @tab Sass @tab sass
15607 @item Scheme @tab scheme @tab GNU Screen @tab screen
15608 @item Sed @tab sed @tab shell @tab sh
15609 @item SQL @tab sql @tab SQLite @tab sqlite
15610 @item Vala @tab vala
15613 Additional documentation for some languages are at
15614 @uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
15616 @vindex org-babel-load-languages
15617 By default, only @code{emacs-lisp} is enabled for evaluation. To enable or
15618 disable other languages, customize the @code{org-babel-load-languages}
15619 variable either through the Emacs customization interface, or by adding code
15620 to the init file as shown next:
15622 In this example, evaluation is disabled for @code{emacs-lisp}, and enabled
15626 (org-babel-do-load-languages
15627 'org-babel-load-languages
15628 '((emacs-lisp . nil)
15632 Note that this is not the only way to enable a language. Org also enables
15633 languages when loaded with @code{require} statement. For example, the
15634 following enables execution of @code{clojure} code blocks:
15637 (require 'ob-clojure)
15640 @node Header arguments
15641 @section Header arguments
15642 @cindex code block, header arguments
15643 @cindex source code, block header arguments
15645 Details of configuring header arguments are shown here.
15648 * Using header arguments:: Different ways to set header arguments
15649 * Specific header arguments:: List of header arguments
15652 @node Using header arguments
15653 @subsection Using header arguments
15655 Since header arguments can be set in several ways, Org prioritizes them in
15656 case of overlaps or conflicts by giving local settings a higher priority.
15657 Header values in function calls, for example, override header values from
15660 * System-wide header arguments:: Set globally, language-specific
15661 * Language-specific header arguments:: Set in the Org file's headers
15662 * Header arguments in Org mode properties:: Set in the Org file
15663 * Language-specific mode properties::
15664 * Code block specific header arguments:: The most commonly used method
15665 * Arguments in function calls:: The most specific level, takes highest priority
15669 @node System-wide header arguments
15670 @subsubheading System-wide header arguments
15671 @vindex org-babel-default-header-args
15672 System-wide values of header arguments can be specified by adapting the
15673 @code{org-babel-default-header-args} variable:
15675 @cindex @code{:session}, src header argument
15676 @cindex @code{:results}, src header argument
15677 @cindex @code{:exports}, src header argument
15678 @cindex @code{:cache}, src header argument
15679 @cindex @code{:noweb}, src header argument
15682 :results => "replace"
15688 This example sets @code{:noweb} header arguments to @code{yes}, which makes
15689 Org expand @code{:noweb} references by default.
15692 (setq org-babel-default-header-args
15693 (cons '(:noweb . "yes")
15694 (assq-delete-all :noweb org-babel-default-header-args)))
15697 @node Language-specific header arguments
15698 @subsubheading Language-specific header arguments
15699 Each language can have separate default header arguments by customizing the
15700 variable @code{org-babel-default-header-args:<lang>}, where @code{<lang>} is
15701 the name of the language. For details, see the language-specific online
15702 documentation at @uref{http://orgmode.org/worg/org-contrib/babel}.
15704 @node Header arguments in Org mode properties
15705 @subsubheading Header arguments in Org mode properties
15707 For header arguments applicable to the buffer, use @code{#+PROPERTY:} lines
15708 anywhere in the Org mode file (@pxref{Property syntax}).
15710 The following example sets only for @samp{R} code blocks to @code{session},
15711 making all the @samp{R} code blocks execute in the same session. Setting
15712 @code{results} to @code{silent} ignores the results of executions for all
15713 blocks, not just @samp{R} code blocks; no results inserted for any block.
15716 #+PROPERTY: header-args:R :session *R*
15717 #+PROPERTY: header-args :results silent
15720 @vindex org-use-property-inheritance
15721 Header arguments set through Org's property drawers (@pxref{Property syntax})
15722 apply at the sub-tree level on down. Since these property drawers can appear
15723 anywhere in the file hierarchy, Org uses outermost call or source block to
15724 resolve the values. Org ignores @code{org-use-property-inheritance} setting.
15726 In this example, @code{:cache} defaults to @code{yes} for all code blocks in
15727 the sub-tree starting with @samp{sample header}.
15732 :header-args: :cache yes
15737 @vindex org-babel-default-header-args
15738 Properties defined through @code{org-set-property} function, bound to
15739 @kbd{C-c C-x p}, apply to all active languages. They override properties set
15740 in @code{org-babel-default-header-args}.
15742 @node Language-specific mode properties
15743 @subsubheading Language-specific mode properties
15745 Language-specific header arguments are also read from properties
15746 @code{header-args:<lang>} where @code{<lang>} is the language identifier.
15752 :header-args:clojure: :session *clojure-1*
15753 :header-args:R: :session *R*
15757 :header-args:clojure: :session *clojure-2*
15761 would force separate sessions for clojure blocks in Heading and Subheading,
15762 but use the same session for all @samp{R} blocks. Blocks in Subheading
15763 inherit settings from Heading.
15765 @node Code block specific header arguments
15766 @subsubheading Code block specific header arguments
15768 Header arguments are most commonly set at the @samp{src} code block level, on
15769 the @code{#+BEGIN_SRC} line. Arguments set at this level take precedence
15770 over those set in the @code{org-babel-default-header-args} variable, and also
15771 those set as header properties.
15773 In the following example, setting @code{results} to @code{silent} makes it
15774 ignore results of the code execution. Setting @code{:exports} to @code{code}
15775 exports only the body of the @samp{src} code block to HTML or @LaTeX{}.:
15779 #+BEGIN_SRC haskell :results silent :exports code :var n=0
15781 fac n = n * fac (n-1)
15785 The same header arguments in an inline @samp{src} code block:
15788 src_haskell[:exports both]@{fac 5@}
15791 Code block header arguments can span multiple lines using @code{#+HEADER:} on
15792 each line. Note that Org currently accepts the plural spelling of
15793 @code{#+HEADER:} only as a convenience for backward-compatibility. It may be
15794 removed at some point.
15798 Multi-line header arguments on an unnamed @samp{src} code block:
15801 #+HEADER: :var data1=1
15802 #+BEGIN_SRC emacs-lisp :var data2=2
15803 (message "data1:%S, data2:%S" data1 data2)
15810 Multi-line header arguments on a named @samp{src} code block:
15813 #+NAME: named-block
15814 #+HEADER: :var data=2
15815 #+BEGIN_SRC emacs-lisp
15816 (message "data:%S" data)
15819 #+RESULTS: named-block
15823 @node Arguments in function calls
15824 @subsubheading Arguments in function calls
15826 Header arguments in function calls are the most specific and override all
15827 other settings in case of an overlap. They get the highest priority. Two
15828 @code{#+CALL:} examples are shown below. For the complete syntax of
15829 @code{#+CALL:} lines, see @ref{Evaluating code blocks}.
15831 In this example, @code{:exports results} header argument is applied to the
15832 evaluation of the @code{#+CALL:} line.
15835 #+CALL: factorial(n=5) :exports results
15838 In this example, @code{:session special} header argument is applied to the
15839 evaluation of @code{factorial} code block.
15842 #+CALL: factorial[:session special](n=5)
15845 @node Specific header arguments
15846 @subsection Specific header arguments
15847 Org comes with many header arguments common to all languages. New header
15848 arguments are added for specific languages as they become available for use
15849 in @samp{src} code blocks. A header argument is specified with an initial
15850 colon followed by the argument's name in lowercase. Common header arguments
15854 * var:: Pass arguments to @samp{src} code blocks
15855 * results:: Specify results type; how to collect
15856 * file:: Specify a path for output file
15857 * file-desc:: Specify a description for file results
15858 * file-ext:: Specify an extension for file output
15859 * output-dir:: Specify a directory for output file
15860 * dir:: Specify the default directory for code block execution
15861 * exports:: Specify exporting code, results, both, none
15862 * tangle:: Toggle tangling; or specify file name
15863 * mkdirp:: Toggle for parent directory creation for target files during tangling
15864 * comments:: Toggle insertion of comments in tangled code files
15865 * padline:: Control insertion of padding lines in tangled code files
15866 * no-expand:: Turn off variable assignment and noweb expansion during tangling
15867 * session:: Preserve the state of code evaluation
15868 * noweb:: Toggle expansion of noweb references
15869 * noweb-ref:: Specify block's noweb reference resolution target
15870 * noweb-sep:: String to separate noweb references
15871 * cache:: Avoid re-evaluating unchanged code blocks
15872 * sep:: Delimiter for writing tabular results outside Org
15873 * hlines:: Handle horizontal lines in tables
15874 * colnames:: Handle column names in tables
15875 * rownames:: Handle row names in tables
15876 * shebang:: Make tangled files executable
15877 * tangle-mode:: Set permission of tangled files
15878 * eval:: Limit evaluation of specific code blocks
15879 * wrap:: Mark source block evaluation results
15880 * post:: Post processing of results of code block evaluation
15881 * prologue:: Text to prepend to body of code block
15882 * epilogue:: Text to append to body of code block
15885 For language-specific header arguments, see @ref{Languages}.
15888 @subsubsection @code{:var}
15889 @cindex @code{:var}, src header argument
15890 Use @code{:var} for passing arguments to @samp{src} code blocks. The
15891 specifics of variables in @samp{src} code blocks vary by the source language
15892 and are covered in the language-specific documentation. The syntax for
15893 @code{:var}, however, is the same for all languages. This includes declaring
15894 a variable, and assigning a default value.
15896 Arguments can take values as literals, or as references, or even as Emacs
15897 Lisp code (@pxref{var, Emacs Lisp evaluation of variables}). References are
15898 names from the Org file from the lines @code{#+NAME:} or @code{#+RESULTS:}.
15899 References can also refer to tables, lists, @code{#+BEGIN_EXAMPLE} blocks,
15900 other types of @samp{src} code blocks, or the results of execution of
15901 @samp{src} code blocks.
15903 For better performance, Org can cache results of evaluations. But caching
15904 comes with severe limitations (@pxref{cache}).
15906 Argument values are indexed like arrays (@pxref{var, Indexable variable
15909 The following syntax is used to pass arguments to @samp{src} code blocks
15910 using the @code{:var} header argument.
15916 The @code{assign} is a literal value, such as a string @samp{"string"}, a
15917 number @samp{9}, a reference to a table, a list, a literal example, another
15918 code block (with or without arguments), or the results from evaluating a code
15921 Here are examples of passing values by reference:
15926 an Org mode table named with either a @code{#+NAME:} line
15929 #+NAME: example-table
15935 #+NAME: table-length
15936 #+BEGIN_SRC emacs-lisp :var table=example-table
15940 #+RESULTS: table-length
15945 a simple list named with a @code{#+NAME:} line. Note that only the top level
15946 list items are passed along. Nested list items are ignored.
15949 #+NAME: example-list
15955 #+BEGIN_SRC emacs-lisp :var x=example-list
15963 @item code block without arguments
15964 a code block name (from the example above), as assigned by @code{#+NAME:},
15965 optionally followed by parentheses
15968 #+BEGIN_SRC emacs-lisp :var length=table-length()
15976 @item code block with arguments
15977 a @samp{src} code block name, as assigned by @code{#+NAME:}, followed by
15978 parentheses and optional arguments passed within the parentheses following
15979 the @samp{src} code block name using standard function call syntax
15983 #+BEGIN_SRC emacs-lisp :var input=8
15991 #+BEGIN_SRC emacs-lisp :var input=double(input=2)
15999 @item literal example
16000 a literal example block named with a @code{#+NAME:} line
16003 #+NAME: literal-example
16009 #+NAME: read-literal-example
16010 #+BEGIN_SRC emacs-lisp :var x=literal-example
16011 (concatenate 'string x " for you.")
16014 #+RESULTS: read-literal-example
16015 : A literal example
16016 : on two lines for you.
16022 @subsubheading Indexable variable values
16023 Indexing variable values enables referencing portions of a variable. Indexes
16024 are 0 based with negative values counting backwards from the end. If an
16025 index is separated by @code{,}s then each subsequent section will index as
16026 the next dimension. Note that this indexing occurs @emph{before} other
16027 table-related header arguments are applied, such as @code{:hlines},
16028 @code{:colnames} and @code{:rownames}. The following example assigns the
16029 last cell of the first row the table @code{example-table} to the variable
16033 #+NAME: example-table
16039 #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
16047 Ranges of variable values can be referenced using two integers separated by a
16048 @code{:}, in which case the entire inclusive range is referenced. For
16049 example the following assigns the middle three rows of @code{example-table}
16053 #+NAME: example-table
16060 #+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
16070 To pick the entire range, use an empty index, or the single character
16071 @code{*}. @code{0:-1} does the same thing. Example below shows how to
16072 reference the first column only.
16075 #+NAME: example-table
16081 #+BEGIN_SRC emacs-lisp :var data=example-table[,0]
16089 Index referencing can be used for tables and code blocks. Index referencing
16090 can handle any number of dimensions. Commas delimit multiple dimensions, as
16095 #+BEGIN_SRC emacs-lisp
16096 '(((1 2 3) (4 5 6) (7 8 9))
16097 ((10 11 12) (13 14 15) (16 17 18))
16098 ((19 20 21) (22 23 24) (25 26 27)))
16101 #+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
16109 @subsubheading Emacs Lisp evaluation of variables
16111 Emacs lisp code can set the values for variables. To differentiate a value
16112 from lisp code, Org interprets any value starting with @code{(}, @code{[},
16113 @code{'} or @code{`} as Emacs Lisp code. The result of evaluating that code
16114 is then assigned to the value of that variable. The following example shows
16115 how to reliably query and pass file name of the Org mode buffer to a code
16116 block using headers. We need reliability here because the file's name could
16117 change once the code in the block starts executing.
16120 #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
16125 Note that values read from tables and lists will not be mistakenly evaluated
16126 as Emacs Lisp code, as illustrated in the following example.
16132 #+HEADER: :var data=table[0,0]
16142 @subsubsection @code{:results}
16143 @cindex @code{:results}, src header argument
16145 There are four classes of @code{:results} header arguments. Each @samp{src}
16146 code block can take only one option per class.
16150 @b{collection} for how the results should be collected from the @samp{src}
16153 @b{type} for which type of result the code block will return; affects how Org
16154 processes and inserts results in the Org buffer
16156 @b{format} for the result; affects how Org processes and inserts results in
16159 @b{handling} for processing results after evaluation of the @samp{src} code
16163 @subsubheading Collection
16164 Collection options specify the results. Choose one of the options; they are
16165 mutually exclusive.
16169 Default. Functional mode. Result is the value returned by the last
16170 statement in the @samp{src} code block. Languages like Python may require an
16171 explicit @code{return} statement in the @samp{src} code block. Usage
16172 example: @code{:results value}.
16173 @item @code{output}
16174 Scripting mode. Result is collected from STDOUT during execution of the code
16175 in the @samp{src} code block. Usage example: @code{:results output}.
16178 @subsubheading Type
16179 Type tells what result types to expect from the execution of the code
16180 block. Choose one of the options; they are mutually exclusive. The default
16181 behavior is to automatically determine the result type.
16184 @item @code{table}, @code{vector}
16185 Interpret the results as an Org table. If the result is a single value,
16186 create a table with one row and one column. Usage example: @code{:results
16189 Interpret the results as an Org list. If the result is a single value,
16190 create a list of one element.
16191 @item @code{scalar}, @code{verbatim}
16192 Interpret literally and insert as quoted text. Do not create a table. Usage
16193 example: @code{:results value verbatim}.
16195 Interpret as path to a file. Inserts a link to the file. Usage example:
16196 @code{:results value file}.
16199 @subsubheading Format
16200 Format pertains to the type of the result returned by the @samp{src} code
16201 block. Choose one of the options; they are mutually exclusive. The default
16202 follows from the type specified above.
16206 Interpreted as raw Org mode. Inserted directly into the buffer. Aligned if
16207 it is a table. Usage example: @code{:results value raw}.
16209 Results enclosed in a @code{BEGIN_SRC org} block. For comma-escape, either
16210 @kbd{TAB} in the block, or export the file. Usage example: @code{:results
16213 Results enclosed in a @code{BEGIN_EXPORT html} block. Usage example:
16214 @code{:results value html}.
16216 Results enclosed in a @code{BEGIN_EXPORT latex} block. Usage example:
16217 @code{:results value latex}.
16219 Result enclosed in a @samp{src} code block. Useful for parsing. Usage
16220 example: @code{:results value code}.
16222 Result converted to pretty-print source code. Enclosed in a @samp{src} code
16223 block. Languages supported: Emacs Lisp, Python, and Ruby. Usage example:
16224 @code{:results value pp}.
16225 @item @code{drawer}
16226 Result wrapped in a RESULTS drawer. Useful for containing @code{raw} or
16227 @code{org} results for later scripting and automated processing. Usage
16228 example: @code{:results value drawer}.
16231 @subsubheading Handling
16232 Handling options after collecting the results.
16235 @item @code{silent}
16236 Do not insert results in the Org mode buffer, but echo them in the
16237 minibuffer. Usage example: @code{:results output silent}.
16238 @item @code{replace}
16239 Default. Insert results in the Org buffer. Remove previous results. Usage
16240 example: @code{:results output replace}.
16241 @item @code{append}
16242 Append results to the Org buffer. Latest results are at the bottom. Does
16243 not remove previous results. Usage example: @code{:results output append}.
16244 @item @code{prepend}
16245 Prepend results to the Org buffer. Latest results are at the top. Does not
16246 remove previous results. Usage example: @code{:results output prepend}.
16250 @subsubsection @code{:file}
16251 @cindex @code{:file}, src header argument
16253 An external @code{:file} that saves the results of execution of the code
16254 block. The @code{:file} is either a file name or two strings, where the
16255 first is the file name and the second is the description. A link to the file
16256 is inserted. It uses an Org mode style @code{[[file:]]} link (@pxref{Link
16257 format}). Some languages, such as @samp{R}, @samp{dot}, @samp{ditaa}, and
16258 @samp{gnuplot}, automatically wrap the source code in additional boilerplate
16259 code. Such code wrapping helps recreate the output, especially graphics
16260 output, by executing just the @code{:file} contents.
16263 @subsubsection @code{:file-desc}
16265 A description of the results file. Org uses this description for the link
16266 (see @ref{Link format}) it inserts in the Org file. If the @code{:file-desc}
16267 has no value, Org will use file name for both the ``link'' and the
16268 ``description'' portion of the Org mode link.
16271 @subsubsection @code{:file-ext}
16272 @cindex @code{:file-ext}, src header argument
16274 File name extension for the output file. Org generates the file's complete
16275 name, and extension by combining @code{:file-ext}, @code{#+NAME:} of the
16276 source block, and the @ref{output-dir} header argument. To override this
16277 auto generated file name, use the @code{:file} header argument.
16280 @subsubsection @code{:output-dir}
16281 @cindex @code{:output-dir}, src header argument
16283 Specifies the @code{:output-dir} for the results file. Org accepts an
16284 absolute path (beginning with @code{/}) or a relative directory (without
16285 @code{/}). The value can be combined with @code{#+NAME:} of the source block
16286 and @ref{file} or @ref{file-ext} header arguments.
16289 @subsubsection @code{:dir} and remote execution
16290 @cindex @code{:dir}, src header argument
16292 While the @code{:file} header argument can be used to specify the path to the
16293 output file, @code{:dir} specifies the default directory during @samp{src}
16294 code block execution. If it is absent, then the directory associated with
16295 the current buffer is used. In other words, supplying @code{:dir path}
16296 temporarily has the same effect as changing the current directory with
16297 @kbd{M-x cd path RET}, and then not supplying @code{:dir}. Under the
16298 surface, @code{:dir} simply sets the value of the Emacs variable
16299 @code{default-directory}.
16301 When using @code{:dir}, relative paths (for example, @code{:file myfile.jpg}
16302 or @code{:file results/myfile.jpg}) become relative to the default directory.
16304 For example, to save the plot file in the @samp{Work} folder of the home
16305 directory (notice tilde is expanded):
16308 #+BEGIN_SRC R :file myplot.png :dir ~/Work
16309 matplot(matrix(rnorm(100), 10), type="l")
16313 @subsubheading Remote execution
16314 To evaluate the @samp{src} code block on a remote machine, supply a remote s
16315 directory name using @samp{Tramp} syntax. For example:
16318 #+BEGIN_SRC R :file plot.png :dir /scp:dand@@yakuba.princeton.edu:
16319 plot(1:10, main=system("hostname", intern=TRUE))
16323 Org first captures the text results as usual for insertion in the Org file.
16324 Then Org also inserts a link to the remote file, thanks to Emacs
16325 @samp{Tramp}. Org constructs the remote path to the file name from
16326 @code{:dir} and @code{default-directory}, as illustrated here:
16329 [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
16333 @subsubheading Some more warnings
16337 When @code{:dir} is used with @code{:session}, Org sets the starting
16338 directory for a new session. But Org will not alter the directory of an
16339 already existing session.
16341 Do not use @code{:dir} with @code{:exports results} or with @code{:exports
16342 both} to avoid Org inserting incorrect links to remote files. That is because
16343 Org does not expand @code{default directory} to avoid some underlying
16344 portability issues.
16348 @subsubsection @code{:exports}
16349 @cindex @code{:exports}, src header argument
16351 The @code{:exports} header argument is to specify if that part of the Org
16352 file is exported to, say, HTML or @LaTeX{} formats. Note that
16353 @code{:exports} affects only @samp{src} code blocks and not inline code.
16357 The default. The body of code is included into the exported file. Example:
16358 @code{:exports code}.
16359 @item @code{results}
16360 The results of evaluation of the code is included in the exported file.
16361 Example: @code{:exports results}.
16363 Both the code and results of evaluation are included in the exported file.
16364 Example: @code{:exports both}.
16366 Neither the code nor the results of evaluation is included in the exported
16367 file. Whether the code is evaluated at all depends on other
16368 options. Example: @code{:exports none}.
16372 @subsubsection @code{:tangle}
16373 @cindex @code{:tangle}, src header argument
16375 The @code{:tangle} header argument specifies if the @samp{src} code block is
16376 exported to source file(s).
16379 @item @code{tangle}
16380 Export the @samp{src} code block to source file. The file name for the
16381 source file is derived from the name of the Org file, and the file extension
16382 is derived from the source code language identifier. Example: @code{:tangle
16385 The default. Do not extract the code a source code file. Example:
16388 Export the @samp{src} code block to source file whose file name is derived
16389 from any string passed to the @code{:tangle} header argument. Org derives
16390 the file name as being relative to the directory of the Org file's location.
16391 Example: @code{:tangle path}.
16395 @subsubsection @code{:mkdirp}
16396 @cindex @code{:mkdirp}, src header argument
16398 The @code{:mkdirp} header argument creates parent directories for tangled
16399 files if the directory does not exist. @code{yes} enables directory creation
16400 and @code{no} inhibits directory creation.
16403 @subsubsection @code{:comments}
16404 @cindex @code{:comments}, src header argument
16405 Controls inserting comments into tangled files. These are above and beyond
16406 whatever comments may already exist in the @samp{src} code block.
16410 The default. Do not insert any extra comments during tangling.
16412 Wrap the @samp{src} code block in comments. Include links pointing back to
16413 the place in the Org file from where the code was tangled.
16415 Kept for backward compatibility; same as ``link''.
16417 Nearest headline text from Org file is inserted as comment. The exact text
16418 that is inserted is picked from the leading context of the source block.
16420 Includes both ``link'' and ``org'' comment options.
16422 Includes ``link'' comment option, expands noweb references, and wraps them in
16423 link comments inside the body of the @samp{src} code block.
16427 @subsubsection @code{:padline}
16428 @cindex @code{:padline}, src header argument
16429 Control insertion of newlines to pad @samp{src} code blocks in the tangled
16433 Default. Insert a newline before and after each @samp{src} code block in the
16436 Do not insert newlines to pad the tangled @samp{src} code blocks.
16440 @subsubsection @code{:no-expand}
16441 @cindex @code{:no-expand}, src header argument
16443 By default Org expands @samp{src} code blocks during tangling. The
16444 @code{:no-expand} header argument turns off such expansions. Note that one
16445 side-effect of expansion by @code{org-babel-expand-src-block} also assigns
16446 values to @code{:var} (@pxref{var}) variables. Expansions also replace Noweb
16447 references with their targets (@pxref{Noweb reference syntax}). Some of
16448 these expansions may cause premature assignment, hence this option. This
16449 option makes a difference only for tangling. It has no effect when exporting
16450 since @samp{src} code blocks for execution have to be expanded anyway.
16453 @subsubsection @code{:session}
16454 @cindex @code{:session}, src header argument
16456 The @code{:session} header argument is for running multiple source code
16457 blocks under one session. Org runs @samp{src} code blocks with the same
16458 session name in the same interpreter process.
16462 Default. Each @samp{src} code block gets a new interpreter process to
16463 execute. The process terminates once the block is evaluated.
16465 Any string besides @code{none} turns that string into the name of that
16466 session. For example, @code{:session mysession} names it @samp{mysession}.
16467 If @code{:session} has no argument, then the session name is derived from the
16468 source language identifier. Subsequent blocks with the same source code
16469 language use the same session. Depending on the language, state variables,
16470 code from other blocks, and the overall interpreted environment may be
16471 shared. Some interpreted languages support concurrent sessions when
16472 subsequent source code language blocks change session names.
16476 @subsubsection @code{:noweb}
16477 @cindex @code{:noweb}, src header argument
16479 The @code{:noweb} header argument controls expansion of Noweb syntax
16480 references (@pxref{Noweb reference syntax}). Expansions occur when source
16481 code blocks are evaluated, tangled, or exported.
16485 Default. No expansion of Noweb syntax references in the body of the code
16486 when evaluating, tangling, or exporting.
16488 Expansion of Noweb syntax references in the body of the @samp{src} code block
16489 when evaluating, tangling, or exporting.
16490 @item @code{tangle}
16491 Expansion of Noweb syntax references in the body of the @samp{src} code block
16492 when tangling. No expansion when evaluating or exporting.
16493 @item @code{no-export}
16494 Expansion of Noweb syntax references in the body of the @samp{src} code block
16495 when evaluating or tangling. No expansion when exporting.
16496 @item @code{strip-export}
16497 Expansion of Noweb syntax references in the body of the @samp{src} code block
16498 when expanding prior to evaluating or tangling. Removes Noweb syntax
16499 references when exporting.
16501 Expansion of Noweb syntax references in the body of the @samp{src} code block
16502 only before evaluating.
16505 @subsubheading Noweb prefix lines
16506 Noweb insertions now honor prefix characters that appear before the Noweb
16509 This behavior is illustrated in the following example. Because the
16510 @code{<<example>>} noweb reference appears behind the SQL comment syntax,
16511 each line of the expanded noweb reference will be commented.
16519 multi-line body of example
16523 this @samp{src} code block:
16526 #+BEGIN_SRC sql :noweb yes
16535 -- multi-line body of example
16538 Since this change will not affect noweb replacement text without newlines in
16539 them, inline noweb references are acceptable.
16541 This feature can also be used for management of indentation in exported code snippets.
16547 #+BEGIN_SRC python :exports none
16548 print('Do things when True')
16552 #+BEGIN_SRC python :exports none
16553 print('Do things when False')
16557 this @samp{src} code block:
16560 #+BEGIN_SRC python :noweb yes :results output
16572 print('Do things when True')
16574 print('Do things when False')
16580 Do things when True
16584 @subsubsection @code{:noweb-ref}
16585 @cindex @code{:noweb-ref}, src header argument
16587 When expanding Noweb style references, Org concatenates @samp{src} code
16588 blocks by matching the reference name to either the code block name or, if
16589 none is found, to the @code{:noweb-ref} header argument.
16591 For simple concatenation, set this @code{:noweb-ref} header argument at the
16592 sub-tree or file level. In the example Org file shown next, the body of the
16593 source code in each block is extracted for concatenation to a pure code file
16597 #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
16600 * the mount point of the fullest disk
16602 :header-args: :noweb-ref fullest-disk
16605 ** query all mounted disks
16610 ** strip the header row
16615 ** output mount point of fullest disk
16617 |awk '@{if (u < +$5) @{u = +$5; m = $6@}@} END @{print m@}'
16622 @subsubsection @code{:noweb-sep}
16623 @cindex @code{:noweb-sep}, src header argument
16625 By default a newline separates each noweb reference concatenation. To change
16626 this newline separator, edit the @code{:noweb-sep} (@pxref{noweb-sep}) header
16630 @subsubsection @code{:cache}
16631 @cindex @code{:cache}, src header argument
16633 The @code{:cache} header argument is for caching results of evaluating code
16634 blocks. Caching results can avoid re-evaluating @samp{src} code blocks that
16635 have not changed since the previous run. To benefit from the cache and avoid
16636 redundant evaluations, the source block must have a result already present in
16637 the buffer, and neither the header arguments (including the value of
16638 @code{:var} references) nor the text of the block itself has changed since
16639 the result was last computed. This feature greatly helps avoid long-running
16640 calculations. For some edge cases, however, the cached results may not be
16643 The caching feature is best for when @samp{src} blocks are pure functions,
16644 that is functions that return the same value for the same input arguments
16645 (@pxref{var}), and that do not have side effects, and do not rely on external
16646 variables other than the input arguments. Functions that depend on a timer,
16647 file system objects, and random number generators are clearly unsuitable for
16650 A note of warning: when @code{:cache} is used for a @code{:session}, caching
16651 may cause unexpected results.
16653 When the caching mechanism tests for any source code changes, it will not
16654 expand Noweb style references (@pxref{Noweb reference syntax}). For reasons
16655 why, see @uref{http://thread.gmane.org/gmane.emacs.orgmode/79046}.
16657 The @code{:cache} header argument can have one of two values: @code{yes} or
16662 Default. No caching of results; @samp{src} code block evaluated every time.
16664 Whether to run the code or return the cached results is determined by
16665 comparing the SHA1 hash value of the combined @samp{src} code block and
16666 arguments passed to it. This hash value is packed on the @code{#+RESULTS:}
16667 line from previous evaluation. When hash values match, Org does not evaluate
16668 the @samp{src} code block. When hash values mismatch, Org evaluates the
16669 @samp{src} code block, inserts the results, recalculates the hash value, and
16670 updates @code{#+RESULTS:} line.
16673 In this example, both functions are cached. But @code{caller} runs only if
16674 the result from @code{random} has changed since the last run.
16678 #+BEGIN_SRC R :cache yes
16682 #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
16686 #+BEGIN_SRC emacs-lisp :var x=random :cache yes
16690 #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
16695 @subsubsection @code{:sep}
16696 @cindex @code{:sep}, src header argument
16698 The @code{:sep} header argument is the delimiter for saving results as tables
16699 to files (@pxref{file}) external to Org mode. Org defaults to tab delimited
16700 output. The function, @code{org-open-at-point}, which is bound to @kbd{C-c
16701 C-o}, also uses @code{:sep} for opening tabular results.
16704 @subsubsection @code{:hlines}
16705 @cindex @code{:hlines}, src header argument
16707 In-between each table row or below the table headings, sometimes results have
16708 horizontal lines, which are also known as hlines. The @code{:hlines}
16709 argument with the value @code{yes} accepts such lines. The default is
16714 Strips horizontal lines from the input table. For most code, this is
16715 desirable, or else those @code{hline} symbols raise unbound variable errors.
16717 The default is @code{:hlines no}. The example shows hlines removed from the
16729 #+BEGIN_SRC python :var tab=many-cols
16733 #+RESULTS: echo-table
16740 For @code{:hlines yes}, the example shows hlines unchanged.
16751 #+BEGIN_SRC python :var tab=many-cols :hlines yes
16755 #+RESULTS: echo-table
16765 @subsubsection @code{:colnames}
16766 @cindex @code{:colnames}, src header argument
16768 The @code{:colnames} header argument accepts @code{yes}, @code{no}, or
16769 @code{nil} values. The default value is @code{nil}, which is unassigned.
16770 But this header argument behaves differently depending on the source code
16775 If an input table has column names (because the second row is an hline), then
16776 Org removes the column names, processes the table, puts back the column
16777 names, and then writes the table to the results block.
16786 #+NAME: echo-table-again
16787 #+BEGIN_SRC python :var tab=less-cols
16788 return [[val + '*' for val in row] for row in tab]
16791 #+RESULTS: echo-table-again
16798 Note that column names have to accounted for when using variable indexing
16799 (@pxref{var, Indexable variable values}) because column names are not removed
16803 Do not pre-process column names.
16806 For an input table that has no hlines, process it like the @code{nil}
16807 value. That is, Org removes the column names, processes the table, puts back
16808 the column names, and then writes the table to the results block.
16812 @subsubsection @code{:rownames}
16813 @cindex @code{:rownames}, src header argument
16815 The @code{:rownames} header argument can take on values @code{yes} or
16816 @code{no} values. The default is @code{no}. Note that @code{emacs-lisp}
16817 code blocks ignore @code{:rownames} header argument because of the ease of
16818 table-handling in Emacs.
16822 Org will not pre-process row names.
16825 If an input table has row names, then Org removes the row names, processes
16826 the table, puts back the row names, and then writes the table to the results
16830 #+NAME: with-rownames
16831 | one | 1 | 2 | 3 | 4 | 5 |
16832 | two | 6 | 7 | 8 | 9 | 10 |
16834 #+NAME: echo-table-once-again
16835 #+BEGIN_SRC python :var tab=with-rownames :rownames yes
16836 return [[val + 10 for val in row] for row in tab]
16839 #+RESULTS: echo-table-once-again
16840 | one | 11 | 12 | 13 | 14 | 15 |
16841 | two | 16 | 17 | 18 | 19 | 20 |
16844 Note that row names have to accounted for when using variable indexing
16845 (@pxref{var, Indexable variable values}) because row names are not removed
16851 @subsubsection @code{:shebang}
16852 @cindex @code{:shebang}, src header argument
16854 This header argument can turn results into executable script files. By
16855 setting the @code{:shebang} header argument to a string value (for example,
16856 @code{:shebang "#!/bin/bash"}), Org inserts that string as the first line of
16857 the tangled file that the @samp{src} code block is extracted to. Org then
16858 turns on the tangled file's executable permission.
16861 @subsubsection @code{:tangle-mode}
16862 @cindex @code{:tangle-mode}, src header argument
16864 The @code{tangle-mode} header argument specifies what permissions to set for
16865 tangled files by @code{set-file-modes}. For example, to make read-only
16866 tangled file, use @code{:tangle-mode (identity #o444)}. To make it
16867 executable, use @code{:tangle-mode (identity #o755)}.
16869 On @samp{src} code blocks with @code{shebang} (@pxref{shebang}) header
16870 argument, Org will automatically set the tangled file to executable
16871 permissions. But this can be overridden with custom permissions using
16872 @code{tangle-mode} header argument.
16874 When multiple @samp{src} code blocks tangle to a single file with different
16875 and conflicting @code{tangle-mode} header arguments, Org's behavior is
16879 @subsubsection @code{:eval}
16880 @cindex @code{:eval}, src header argument
16881 The @code{:eval} header argument can limit evaluation of specific code
16882 blocks. It is useful for protection against evaluating untrusted @samp{src}
16883 code blocks by prompting for a confirmation. This protection is independent
16884 of the @code{org-confirm-babel-evaluate} setting.
16888 Org will never evaluate this @samp{src} code block.
16890 Org prompts the user for permission to evaluate this @samp{src} code block.
16891 @item never-export or no-export
16892 Org will not evaluate this @samp{src} code block when exporting, yet the user
16893 can evaluate this source block interactively.
16895 Org prompts the user for permission to export this @samp{src} code block.
16898 If @code{:eval} header argument is not set for a source block, then Org
16899 determines whether to evaluate from the @code{org-confirm-babel-evaluate}
16900 variable (@pxref{Code evaluation security}).
16903 @subsubsection @code{:wrap}
16904 @cindex @code{:wrap}, src header argument
16905 The @code{:wrap} header argument marks the results block by appending strings
16906 to @code{#+BEGIN_} and @code{#+END_}. If no string is specified, Org wraps
16907 the results in a @code{#+BEGIN/END_RESULTS} block.
16910 @subsubsection @code{:post}
16911 @cindex @code{:post}, src header argument
16912 The @code{:post} header argument is for post-processing results from
16913 @samp{src} block evaluation. When @code{:post} has any value, Org binds the
16914 results to @code{*this*} variable for easy passing to @ref{var} header
16915 argument specifications. That makes results available to other @samp{src}
16916 code blocks, or for even direct Emacs Lisp code execution.
16918 The following two examples illustrate @code{:post} header argument in action.
16919 The first one shows how to attach @code{#+ATTR_LATEX:} line using
16924 #+begin_src sh :var data="" :var width="\\textwidth" :results output
16925 echo "#+ATTR_LATEX: :width $width"
16929 #+header: :file /tmp/it.png
16930 #+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer
16940 #+ATTR_LATEX :width 5cm
16941 [[file:/tmp/it.png]]
16945 The second example shows use of @code{:colnames} in @code{:post} to pass
16946 data between @samp{src} code blocks.
16950 #+begin_src emacs-lisp :var tbl="" fmt="%.3f"
16951 (mapcar (lambda (row)
16952 (mapcar (lambda (cell)
16960 #+begin_src R :colnames yes :post round-tbl[:colnames yes](*this*)
16962 data.frame(foo=rnorm(1))
16972 @subsubsection @code{:prologue}
16973 @cindex @code{:prologue}, src header argument
16974 The @code{prologue} header argument is for appending to the top of the code
16975 block for execution. For example, a clear or reset code at the start of new
16976 execution of a @samp{src} code block. A @code{reset} for @samp{gnuplot}:
16977 @code{:prologue "reset"}. See also @ref{epilogue}.
16980 (add-to-list 'org-babel-default-header-args:gnuplot
16981 '((:prologue . "reset")))
16985 @subsubsection @code{:epilogue}
16986 @cindex @code{:epilogue}, src header argument
16987 The value of the @code{epilogue} header argument is for appending to the end
16988 of the code block for execution. See also @ref{prologue}.
16990 @node Results of evaluation
16991 @section Results of evaluation
16992 @cindex code block, results of evaluation
16993 @cindex source code, results of evaluation
16995 How Org handles results of a code block execution depends on many header
16996 arguments working together. Here is only a summary of these. For an
16997 enumeration of all the header arguments that affect results, see
17000 The primary determinant is the execution context. Is it in a @code{:session}
17001 or not? Orthogonal to that is if the expected result is a @code{:results
17002 value} or @code{:results output}, which is a concatenation of output from
17003 start to finish of the @samp{src} code block's evaluation.
17005 @multitable @columnfractions 0.26 0.33 0.41
17006 @item @tab @b{Non-session} @tab @b{Session}
17007 @item @code{:results value} @tab value of last expression @tab value of last expression
17008 @item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output
17011 For @code{:session} and non-session, the @code{:results value} turns the
17012 results into an Org mode table format. Single values are wrapped in a one
17013 dimensional vector. Rows and columns of a table are wrapped in a
17014 two-dimensional vector.
17016 @subsection Non-session
17017 @subsubsection @code{:results value}
17018 @cindex @code{:results}, src header argument
17019 Default. Org gets the value by wrapping the code in a function definition in
17020 the language of the @samp{src} block. That is why when using @code{:results
17021 value}, code should execute like a function and return a value. For
17022 languages like Python, an explicit @code{return} statement is mandatory when
17023 using @code{:results value}.
17025 This is one of four evaluation contexts where Org automatically wraps the
17026 code in a function definition.
17028 @subsubsection @code{:results output}
17029 @cindex @code{:results}, src header argument
17030 For @code{:results output}, the code is passed to an external process running
17031 the interpreter. Org returns the contents of the standard output stream as
17034 @subsection Session
17035 @subsubsection @code{:results value}
17036 @cindex @code{:results}, src header argument
17037 For @code{:results value} from a @code{:session}, Org passes the code to an
17038 interpreter running as an interactive Emacs inferior process. So only
17039 languages that provide interactive evaluation can have session support. Not
17040 all languages provide this support, such as @samp{C} and @samp{ditaa}. Even
17041 those that do support, such as @samp{Python} and @samp{Haskell}, they impose
17042 limitations on allowable language constructs that can run interactively. Org
17043 inherits those limitations for those @samp{src} code blocks running in a
17046 Org gets the value from the source code interpreter's last statement
17047 output. Org has to use language-specific methods to obtain the value. For
17048 example, from the variable @code{_} in @samp{Python} and @samp{Ruby}, and the
17049 value of @code{.Last.value} in @samp{R}).
17051 @subsubsection @code{:results output}
17052 @cindex @code{:results}, src header argument
17053 For @code{:results output}, Org passes the code to the interpreter running as
17054 an interactive Emacs inferior process. Org concatenates whatever text output
17055 emitted by the interpreter to return the collection as a result. Note that
17056 this collection is not the same as collected from @code{STDOUT} of a
17057 non-interactive interpreter running as an external process. Compare for
17058 example these two blocks:
17061 #+BEGIN_SRC python :results output
17072 In the above non-session mode, the ``2'' is not printed; so does not appear
17076 #+BEGIN_SRC python :results output :session
17088 In the above @code{:session} mode, the interactive interpreter receives and
17089 prints ``2''. Results show that.
17091 @node Noweb reference syntax
17092 @section Noweb reference syntax
17093 @cindex code block, noweb reference
17094 @cindex syntax, noweb
17095 @cindex source code, noweb reference
17097 Org supports named blocks in Noweb style syntax. For Noweb literate
17098 programming details, see @uref{http://www.cs.tufts.edu/~nr/noweb/}).
17101 <<code-block-name>>
17104 For the header argument @code{:noweb yes}, Org expands Noweb style references
17105 in the @samp{src} code block before evaluation.
17107 For the header argument @code{:noweb no}, Org does not expand Noweb style
17108 references in the @samp{src} code block before evaluation.
17110 The default is @code{:noweb no}. Org defaults to @code{:noweb no} so as not
17111 to cause errors in languages where Noweb syntax is ambiguous. Change Org's
17112 default to @code{:noweb yes} for languages where there is no risk of
17115 Org offers a more flexible way to resolve Noweb style references
17116 (@pxref{noweb-ref}).
17118 Org can include the @emph{results} of a code block rather than its body. To
17119 that effect, append parentheses, possibly including arguments, to the code
17120 block name, as show below.
17123 <<code-block-name(optional arguments)>>
17126 Note that when using the above approach to a code block's results, the code
17127 block name set by @code{#+NAME} keyword is required; the reference set by
17128 @code{:noweb-ref} will not work.
17130 Here is an example that demonstrates how the exported content changes when
17131 Noweb style references are used with parentheses versus without.
17137 #+BEGIN_SRC python :var num=0 :results output :exports none
17145 #+BEGIN_SRC text :noweb yes
17156 Below, a similar Noweb style reference is used, but with parentheses, while
17157 setting a variable @code{num} to 10:
17160 #+BEGIN_SRC text :noweb yes
17161 <<some-code(num=10)>>
17165 Note that now the expansion contains the @emph{results} of the code block
17166 @code{some-code}, not the code block itself:
17173 @node Key bindings and useful functions
17174 @section Key bindings and useful functions
17175 @cindex code block, key bindings
17177 Many common Org mode key sequences are re-bound depending on the context.
17179 Active key bindings in code blocks:
17181 @multitable @columnfractions 0.25 0.75
17183 @item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block}
17185 @item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result}
17187 @item @kbd{M-@key{up}} @tab @code{org-babel-load-in-session}
17189 @item @kbd{M-@key{down}} @tab @code{org-babel-switch-to-session}
17192 Active key bindings in Org mode buffer:
17194 @multitable @columnfractions 0.5 0.5
17196 @kindex C-c C-v C-p
17197 @item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block}
17199 @kindex C-c C-v C-n
17200 @item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block}
17202 @kindex C-c C-v C-e
17203 @item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe}
17205 @kindex C-c C-v C-o
17206 @item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result}
17208 @kindex C-c C-v C-v
17209 @item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block}
17211 @kindex C-c C-v C-u
17212 @item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head}
17214 @kindex C-c C-v C-g
17215 @item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block}
17217 @kindex C-c C-v C-r
17218 @item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result}
17220 @kindex C-c C-v C-b
17221 @item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
17223 @kindex C-c C-v C-s
17224 @item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
17226 @kindex C-c C-v C-d
17227 @item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block}
17229 @kindex C-c C-v C-t
17230 @item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
17232 @kindex C-c C-v C-f
17233 @item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
17235 @kindex C-c C-v C-c
17236 @item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block}
17238 @kindex C-c C-v C-j
17239 @item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg}
17241 @kindex C-c C-v C-l
17242 @item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session}
17244 @kindex C-c C-v C-i
17245 @item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest}
17247 @kindex C-c C-v C-I
17248 @item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info}
17250 @kindex C-c C-v C-z
17251 @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}
17253 @kindex C-c C-v C-a
17254 @item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
17256 @kindex C-c C-v C-h
17257 @item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings}
17259 @kindex C-c C-v C-x
17260 @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}
17263 @c Extended key bindings when control key is kept pressed:
17265 @c @multitable @columnfractions 0.25 0.75
17266 @c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
17267 @c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
17268 @c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
17269 @c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
17270 @c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
17271 @c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
17272 @c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
17273 @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
17276 @node Batch execution
17277 @section Batch execution
17278 @cindex code block, batch execution
17279 @cindex source code, batch execution
17281 Org mode features, including working with source code facilities can be
17282 invoked from the command line. This enables building shell scripts for batch
17283 processing, running automated system tasks, and expanding Org mode's
17286 The sample script shows batch processing of multiple files using
17287 @code{org-babel-tangle}.
17291 # tangle files with org-mode
17293 emacs -Q --batch --eval "
17295 (require 'ob-tangle)
17296 (dolist (file command-line-args-left)
17297 (with-current-buffer (find-file-noselect file)
17298 (org-babel-tangle))))
17302 @node Miscellaneous
17303 @chapter Miscellaneous
17306 * Completion:: M-TAB guesses completions
17307 * Structure templates:: Quick insertion of structural elements
17308 * Speed keys:: Electric commands at the beginning of a headline
17309 * Code evaluation security:: Org mode files evaluate inline code
17310 * Customization:: Adapting Org to changing tastes
17311 * In-buffer settings:: Overview of the #+KEYWORDS
17312 * The very busy C-c C-c key:: When in doubt, press C-c C-c
17313 * Clean view:: Getting rid of leading stars in the outline
17314 * TTY keys:: Using Org on a tty
17315 * Interaction:: With other Emacs packages
17316 * org-crypt:: Encrypting Org files
17321 @section Completion
17322 @cindex completion, of @TeX{} symbols
17323 @cindex completion, of TODO keywords
17324 @cindex completion, of dictionary words
17325 @cindex completion, of option keywords
17326 @cindex completion, of tags
17327 @cindex completion, of property keys
17328 @cindex completion, of link abbreviations
17329 @cindex @TeX{} symbol completion
17330 @cindex TODO keywords completion
17331 @cindex dictionary word completion
17332 @cindex option keyword completion
17333 @cindex tag completion
17334 @cindex link abbreviations, completion of
17336 Org has in-buffer completions. Unlike minibuffer completions, which are
17337 useful for quick command interactions, Org's in-buffer completions are more
17338 suitable for content creation in Org documents. Type one or more letters and
17339 invoke the hot key to complete the text in-place. Depending on the context
17340 and the keys, Org will offer different types of completions. No minibuffer
17341 is involved. Such mode-specific hot keys have become an integral part of
17342 Emacs and Org provides several shortcuts.
17345 @kindex M-@key{TAB}
17347 Complete word at point
17350 At the beginning of a headline, complete TODO keywords.
17352 After @samp{\}, complete @TeX{} symbols supported by the exporter.
17354 After @samp{*}, complete headlines in the current buffer so that they
17355 can be used in search links like @samp{[[*find this headline]]}.
17357 After @samp{:} in a headline, complete tags. The list of tags is taken
17358 from the variable @code{org-tag-alist} (possibly set through the
17359 @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
17360 dynamically from all tags used in the current buffer.
17362 After @samp{:} and not in a headline, complete property keys. The list
17363 of keys is constructed dynamically from all keys used in the current
17366 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
17368 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
17369 file-specific @samp{OPTIONS}. After option keyword is complete, pressing
17370 @kbd{M-@key{TAB}} again will insert example settings for that option.
17372 After @samp{#+STARTUP: }, complete startup keywords.
17374 When the point is anywhere else, complete dictionary words using Ispell.
17377 If your desktop intercepts the combo @kbd{M-@key{TAB}} to switch windows, use
17378 @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} as an alternative or customize your
17382 @node Structure templates
17383 @section Structure templates
17384 @cindex template insertion
17385 @cindex insertion, of templates
17387 With just a few keystrokes, it is possible to insert empty structural blocks,
17388 such as @samp{#+BEGIN_SRC} @dots{} @samp{#+END_SRC}, or to wrap existing text
17392 @orgcmd{C-c C-x w,org-insert-structure-template}
17393 Prompt for a type of block structure, and insert the block at point. If the
17394 region is active, it is wrapped in the block. First prompts the user for
17395 a key, which is used to look up a structure type from the values below. If
17396 the key is @key{TAB}, the user is prompted to enter a type.
17399 @vindex org-structure-template-alist
17400 Available structure types are defined in @code{org-structure-template-alist},
17401 see the docstring for adding or changing values.
17404 @cindex Template expansion
17405 @cindex template insertion
17406 @cindex insertion, of templates
17407 @vindex org-tempo-keywords-alist
17408 @vindex org-structure-template-alist
17409 Org Tempo expands snippets to structures defined in
17410 @code{org-structure-template-alist} and @code{org-tempo-keywords-alist}. For
17411 example, @code{org-tempo} expands @kbd{< s @key{TAB}} to a code block.
17412 Enable it by customizing @code{org-modules} or add @code{(require
17413 'org-tempo)} to your Emacs init file@footnote{For more information, please
17414 refer to the commentary section in @file{org-tempo.el}.}.
17416 @multitable @columnfractions 0.2 0.8
17417 @item @kbd{c} @tab @samp{#+BEGIN_CENTER}
17418 @item @kbd{C} @tab @samp{#+BEGIN_COMMENT}
17419 @item @kbd{e} @tab @samp{#+BEGIN_EXAMPLE}
17420 @item @kbd{E} @tab @samp{#+BEGIN_EXPORT}
17421 @item @kbd{a} @tab @samp{#+BEGIN_EXPORT ascii}
17422 @item @kbd{h} @tab @samp{#+BEGIN_EXPORT html}
17423 @item @kbd{l} @tab @samp{#+BEGIN_EXPORT latex}
17424 @item @kbd{s} @tab @samp{#+BEGIN_SRC}
17425 @item @kbd{q} @tab @samp{#+BEGIN_QUOTE}
17426 @item @kbd{v} @tab @samp{#+BEGIN_VERSE}
17430 @section Speed keys
17433 Single keystrokes can execute custom commands in an Org file when the cursor
17434 is on a headline. Without the extra burden of a meta or modifier key, Speed
17435 Keys can speed navigation or execute custom commands. Besides faster
17436 navigation, Speed Keys may come in handy on small mobile devices that do not
17437 have full keyboards. Speed Keys may also work on TTY devices known for their
17438 problems when entering Emacs keychords.
17440 @vindex org-use-speed-commands
17441 By default, Org has Speed Keys disabled. To activate Speed Keys, set the
17442 variable @code{org-use-speed-commands} to a non-@code{nil} value. To trigger
17443 a Speed Key, the cursor must be at the beginning of an Org headline, before
17446 @vindex org-speed-commands-user
17447 @findex org-speed-command-help
17448 Org comes with a pre-defined list of Speed Keys. To add or modify Speed
17449 Keys, customize the variable, @code{org-speed-commands-user}. For more
17450 details, see the variable's docstring. With Speed Keys activated, @kbd{M-x
17451 org-speed-command-help}, or @kbd{?} when cursor is at the beginning of an Org
17452 headline, shows currently active Speed Keys, including the user-defined ones.
17455 @node Code evaluation security
17456 @section Code evaluation and security issues
17458 Unlike plain text, running code comes with risk. Each @samp{src} code block,
17459 in terms of risk, is equivalent to an executable file. Org therefore puts a
17460 few confirmation prompts by default. This is to alert the casual user from
17461 accidentally running untrusted code.
17463 For users who do not run code blocks or write code regularly, Org's default
17464 settings should suffice. However, some users may want to tweak the prompts
17465 for fewer interruptions. To weigh the risks of automatic execution of code
17466 blocks, here are some details about code evaluation.
17468 Org evaluates code in the following circumstances:
17471 @item Source code blocks
17472 Org evaluates @samp{src} code blocks in an Org file during export. Org also
17473 evaluates a @samp{src} code block with the @kbd{C-c C-c} key chord. Users
17474 exporting or running code blocks must load files only from trusted sources.
17475 Be wary of customizing variables that remove or alter default security
17478 @defopt org-confirm-babel-evaluate
17479 When @code{t}, Org prompts the user for confirmation before executing each
17480 code block. When @code{nil}, Org executes code blocks without prompting the
17481 user for confirmation. When this option is set to a custom function, Org
17482 invokes the function with these two arguments: the source code language and
17483 the body of the code block. The custom function must return either a
17484 @code{t} or @code{nil}, which determines if the user is prompted. Each
17485 source code language can be handled separately through this function
17489 For example, this function enables execution of @samp{ditaa} code +blocks
17493 (defun my-org-confirm-babel-evaluate (lang body)
17494 (not (string= lang "ditaa"))) ; don't ask for ditaa
17495 (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
17498 @item Following @code{shell} and @code{elisp} links
17499 Org has two link types that can also directly evaluate code (@pxref{External
17500 links}). Because such code is not visible, these links have a potential
17501 risk. Org therefore prompts the user when it encounters such links. The
17502 customization variables are:
17504 @defopt org-confirm-shell-link-function
17505 Function that prompts the user before executing a shell link.
17507 @defopt org-confirm-elisp-link-function
17508 Function that prompts the user before executing an Emacs Lisp link.
17511 @item Formulas in tables
17512 Org executes formulas in tables (@pxref{The spreadsheet}) either through the
17513 @emph{calc} or the @emph{Emacs Lisp} interpreters.
17516 @node Customization
17517 @section Customization
17518 @cindex customization
17519 @cindex options, for customization
17520 @cindex variables, for customization
17522 Org has more than 500 variables for customization. They can be accessed
17523 through the usual @kbd{M-x org-customize RET} command. Or through the Org
17524 menu, @code{Org->Customization->Browse Org Group}. Org also has per-file
17525 settings for some variables (@pxref{In-buffer settings}).
17527 @node In-buffer settings
17528 @section Summary of in-buffer settings
17529 @cindex in-buffer settings
17530 @cindex special keywords
17531 In-buffer settings start with @samp{#+}, followed by a keyword, a colon, and
17532 then a word for each setting. Org accepts multiple settings on the same
17533 line. Org also accepts multiple lines for a keyword. This manual describes
17534 these settings throughout. A summary follows here.
17536 @kbd{C-c C-c} activates any changes to the in-buffer settings. Closing and
17537 reopening the Org file in Emacs also activates the changes.
17539 @vindex org-archive-location
17541 @item #+ARCHIVE: %s_done::
17542 Sets the archive location of the agenda file. This location applies to the
17543 lines until the next @samp{#+ARCHIVE} line, if any, in the Org file. The
17544 first archive location in the Org file also applies to any entries before it.
17545 The corresponding variable is @code{org-archive-location}.
17547 Sets the category of the agenda file, which applies to the entire document.
17548 @item #+COLUMNS: %25ITEM ...
17549 @cindex property, COLUMNS
17550 Sets the default format for columns view. Org uses this format for column
17551 views where there is no @code{COLUMNS} property.
17552 @item #+CONSTANTS: name1=value1 ...
17553 @vindex org-table-formula-constants
17554 @vindex org-table-formula
17555 Set file-local values for constants that table formulas can use. This line
17556 sets the local variable @code{org-table-formula-constants-local}. The global
17557 version of this variable is @code{org-table-formula-constants}.
17558 @item #+FILETAGS: :tag1:tag2:tag3:
17559 Set tags that all entries in the file will inherit from here, including the
17561 @item #+LINK: linkword replace
17562 @vindex org-link-abbrev-alist
17563 Each line specifies one abbreviation for one link. Use multiple
17564 @code{#+LINK:} lines for more, @pxref{Link abbreviations}. The corresponding
17565 variable is @code{org-link-abbrev-alist}.
17566 @item #+PRIORITIES: highest lowest default
17567 @vindex org-highest-priority
17568 @vindex org-lowest-priority
17569 @vindex org-default-priority
17570 This line sets the limits and the default for the priorities. All three
17571 must be either letters A--Z or numbers 0--9. The highest priority must
17572 have a lower ASCII number than the lowest priority.
17573 @item #+PROPERTY: Property_Name Value
17574 This line sets a default inheritance value for entries in the current
17575 buffer, most useful for specifying the allowed values of a property.
17576 @cindex #+SETUPFILE
17577 @item #+SETUPFILE: file or URL
17578 The setup file or a URL pointing to such file is for additional in-buffer
17579 settings. Org loads this file and parses it for any settings in it only when
17580 Org opens the main file. If URL is specified, the contents are downloaded
17581 and stored in a temporary file cache. @kbd{C-c C-c} on the settings line
17582 will parse and load the file, and also reset the temporary file cache. Org
17583 also parses and loads the document during normal exporting process. Org
17584 parses the contents of this document as if it was included in the buffer. It
17585 can be another Org file. To visit the file (not a URL), @kbd{C-c '} while
17586 the cursor is on the line with the file name.
17589 Startup options Org uses when first visiting a file.
17591 The first set of options deals with the initial visibility of the outline
17592 tree. The corresponding variable for global default settings is
17593 @code{org-startup-folded} with a default value of @code{t}, which is the same
17594 as @code{overview}.
17596 @vindex org-startup-folded
17597 @cindex @code{overview}, STARTUP keyword
17598 @cindex @code{content}, STARTUP keyword
17599 @cindex @code{showall}, STARTUP keyword
17600 @cindex @code{showeverything}, STARTUP keyword
17602 overview @r{top-level headlines only}
17603 content @r{all headlines}
17604 showall @r{no folding of any entries}
17605 showeverything @r{show even drawer contents}
17608 @vindex org-startup-indented
17609 @cindex @code{indent}, STARTUP keyword
17610 @cindex @code{noindent}, STARTUP keyword
17611 Dynamic virtual indentation is controlled by the variable
17612 @code{org-startup-indented}
17614 indent @r{start with @code{org-indent-mode} turned on}
17615 noindent @r{start with @code{org-indent-mode} turned off}
17618 @vindex org-startup-align-all-tables
17619 Aligns tables consistently upon visiting a file. The corresponding variable
17620 is @code{org-startup-align-all-tables} with @code{nil} as default value.
17622 @cindex @code{align}, STARTUP keyword
17623 @cindex @code{noalign}, STARTUP keyword
17625 align @r{align all tables}
17626 noalign @r{don't align tables on startup}
17629 @vindex org-startup-shrink-all-tables
17630 Shrink table columns with a width cookie. The corresponding variable is
17631 @code{org-startup-shrink-all-tables} with @code{nil} as default value.
17633 @vindex org-startup-with-inline-images
17634 Whether Org should automatically display inline images. The corresponding
17635 variable is @code{org-startup-with-inline-images}, with a default value
17636 @code{nil} to avoid delays when visiting a file.
17637 @cindex @code{inlineimages}, STARTUP keyword
17638 @cindex @code{noinlineimages}, STARTUP keyword
17640 inlineimages @r{show inline images}
17641 noinlineimages @r{don't show inline images on startup}
17644 @vindex org-startup-with-latex-preview
17645 Whether Org should automatically convert @LaTeX{} fragments to images. The
17646 variable @code{org-startup-with-latex-preview}, which controls this setting,
17647 is set to @code{nil} by default to avoid startup delays.
17648 @cindex @code{latexpreview}, STARTUP keyword
17649 @cindex @code{nolatexpreview}, STARTUP keyword
17651 latexpreview @r{preview @LaTeX{} fragments}
17652 nolatexpreview @r{don't preview @LaTeX{} fragments}
17655 @vindex org-log-done
17656 @vindex org-log-note-clock-out
17657 @vindex org-log-repeat
17658 Logging the closing and reopening of TODO items and clock intervals can be
17659 configured using these options (see variables @code{org-log-done},
17660 @code{org-log-note-clock-out} and @code{org-log-repeat})
17661 @cindex @code{logdone}, STARTUP keyword
17662 @cindex @code{lognotedone}, STARTUP keyword
17663 @cindex @code{nologdone}, STARTUP keyword
17664 @cindex @code{lognoteclock-out}, STARTUP keyword
17665 @cindex @code{nolognoteclock-out}, STARTUP keyword
17666 @cindex @code{logrepeat}, STARTUP keyword
17667 @cindex @code{lognoterepeat}, STARTUP keyword
17668 @cindex @code{nologrepeat}, STARTUP keyword
17669 @cindex @code{logreschedule}, STARTUP keyword
17670 @cindex @code{lognotereschedule}, STARTUP keyword
17671 @cindex @code{nologreschedule}, STARTUP keyword
17672 @cindex @code{logredeadline}, STARTUP keyword
17673 @cindex @code{lognoteredeadline}, STARTUP keyword
17674 @cindex @code{nologredeadline}, STARTUP keyword
17675 @cindex @code{logrefile}, STARTUP keyword
17676 @cindex @code{lognoterefile}, STARTUP keyword
17677 @cindex @code{nologrefile}, STARTUP keyword
17678 @cindex @code{logdrawer}, STARTUP keyword
17679 @cindex @code{nologdrawer}, STARTUP keyword
17680 @cindex @code{logstatesreversed}, STARTUP keyword
17681 @cindex @code{nologstatesreversed}, STARTUP keyword
17683 logdone @r{record a timestamp when an item is marked DONE}
17684 lognotedone @r{record timestamp and a note when DONE}
17685 nologdone @r{don't record when items are marked DONE}
17686 logrepeat @r{record a time when reinstating a repeating item}
17687 lognoterepeat @r{record a note when reinstating a repeating item}
17688 nologrepeat @r{do not record when reinstating repeating item}
17689 lognoteclock-out @r{record a note when clocking out}
17690 nolognoteclock-out @r{don't record a note when clocking out}
17691 logreschedule @r{record a timestamp when scheduling time changes}
17692 lognotereschedule @r{record a note when scheduling time changes}
17693 nologreschedule @r{do not record when a scheduling date changes}
17694 logredeadline @r{record a timestamp when deadline changes}
17695 lognoteredeadline @r{record a note when deadline changes}
17696 nologredeadline @r{do not record when a deadline date changes}
17697 logrefile @r{record a timestamp when refiling}
17698 lognoterefile @r{record a note when refiling}
17699 nologrefile @r{do not record when refiling}
17700 logdrawer @r{store log into drawer}
17701 nologdrawer @r{store log outside of drawer}
17702 logstatesreversed @r{reverse the order of states notes}
17703 nologstatesreversed @r{do not reverse the order of states notes}
17706 @vindex org-hide-leading-stars
17707 @vindex org-odd-levels-only
17708 These options hide leading stars in outline headings, and indent outlines.
17709 The corresponding variables are @code{org-hide-leading-stars} and
17710 @code{org-odd-levels-only}, both with a default setting of @code{nil}
17711 (meaning @code{showstars} and @code{oddeven}).
17712 @cindex @code{hidestars}, STARTUP keyword
17713 @cindex @code{showstars}, STARTUP keyword
17714 @cindex @code{odd}, STARTUP keyword
17715 @cindex @code{even}, STARTUP keyword
17717 hidestars @r{hide all stars on the headline except one.}
17718 showstars @r{show all stars on the headline}
17719 indent @r{virtual indents according to the outline level}
17720 noindent @r{no virtual indents}
17721 odd @r{show odd outline levels only (1,3,...)}
17722 oddeven @r{show all outline levels}
17725 @vindex org-put-time-stamp-overlays
17726 @vindex org-time-stamp-overlay-formats
17727 To turn on custom format overlays over timestamps (variables
17728 @code{org-put-time-stamp-overlays} and
17729 @code{org-time-stamp-overlay-formats}), use
17730 @cindex @code{customtime}, STARTUP keyword
17732 customtime @r{overlay custom time format}
17735 @vindex constants-unit-system
17736 The following options influence the table spreadsheet (variable
17737 @code{constants-unit-system}).
17738 @cindex @code{constcgs}, STARTUP keyword
17739 @cindex @code{constSI}, STARTUP keyword
17741 constcgs @r{@file{constants.el} should use the c-g-s unit system}
17742 constSI @r{@file{constants.el} should use the SI unit system}
17745 @vindex org-footnote-define-inline
17746 @vindex org-footnote-auto-label
17747 @vindex org-footnote-auto-adjust
17748 For footnote settings, use the following keywords. The corresponding
17749 variables are @code{org-footnote-define-inline},
17750 @code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.
17751 @cindex @code{fninline}, STARTUP keyword
17752 @cindex @code{nofninline}, STARTUP keyword
17753 @cindex @code{fnlocal}, STARTUP keyword
17754 @cindex @code{fnprompt}, STARTUP keyword
17755 @cindex @code{fnauto}, STARTUP keyword
17756 @cindex @code{fnconfirm}, STARTUP keyword
17757 @cindex @code{fnplain}, STARTUP keyword
17758 @cindex @code{fnadjust}, STARTUP keyword
17759 @cindex @code{nofnadjust}, STARTUP keyword
17761 fninline @r{define footnotes inline}
17762 fnnoinline @r{define footnotes in separate section}
17763 fnlocal @r{define footnotes near first reference, but not inline}
17764 fnprompt @r{prompt for footnote labels}
17765 fnauto @r{create @code{[fn:1]}-like labels automatically (default)}
17766 fnconfirm @r{offer automatic label for editing or confirmation}
17767 fnplain @r{create @code{[1]}-like labels automatically}
17768 fnadjust @r{automatically renumber and sort footnotes}
17769 nofnadjust @r{do not renumber and sort automatically}
17772 @cindex org-hide-block-startup
17773 To hide blocks on startup, use these keywords. The corresponding variable is
17774 @code{org-hide-block-startup}.
17775 @cindex @code{hideblocks}, STARTUP keyword
17776 @cindex @code{nohideblocks}, STARTUP keyword
17778 hideblocks @r{Hide all begin/end blocks on startup}
17779 nohideblocks @r{Do not hide blocks on startup}
17782 @cindex org-pretty-entities
17783 The display of entities as UTF-8 characters is governed by the variable
17784 @code{org-pretty-entities} and the keywords
17785 @cindex @code{entitiespretty}, STARTUP keyword
17786 @cindex @code{entitiesplain}, STARTUP keyword
17788 entitiespretty @r{Show entities as UTF-8 characters where possible}
17789 entitiesplain @r{Leave entities plain}
17792 @item #+TAGS: TAG1(c1) TAG2(c2)
17793 @vindex org-tag-alist
17794 These lines specify valid tags for this file. Org accepts multiple tags
17795 lines. Tags could correspond to the @emph{fast tag selection} keys. The
17796 corresponding variable is @code{org-tag-alist}.
17799 This line is for formulas for the table directly above. A table can have
17800 multiple @samp{#+TBLFM:} lines. On table recalculation, Org applies only the
17801 first @samp{#+TBLFM:} line. For details see @ref{Using multiple #+TBLFM
17802 lines} in @ref{Editing and debugging formulas}.
17803 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:,
17804 @itemx #+OPTIONS:, #+BIND:,
17805 @itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
17806 These lines provide settings for exporting files. For more details see
17807 @ref{Export settings}.
17808 @item #+TODO: #+SEQ_TODO: #+TYP_TODO:
17809 @vindex org-todo-keywords
17810 These lines set the TODO keywords and their significance to the current file.
17811 The corresponding variable is @code{org-todo-keywords}.
17814 @node The very busy C-c C-c key
17815 @section The very busy C-c C-c key
17817 @cindex C-c C-c, overview
17819 The @kbd{C-c C-c} key in Org serves many purposes depending on the context.
17820 It is probably the most over-worked, multi-purpose key combination in Org.
17821 Its uses are well-documented through out this manual, but here is a
17822 consolidated list for easy reference.
17826 If any highlights shown in the buffer from the creation of a sparse tree, or
17827 from clock display, remove such highlights.
17829 If the cursor is in one of the special @code{#+KEYWORD} lines, scan the
17830 buffer for these lines and update the information. Also reset the Org file
17831 cache used to temporary store the contents of URLs used as values for
17832 keywords like @code{#+SETUPFILE}.
17834 If the cursor is inside a table, realign the table. The table realigns even
17835 if automatic table editor is turned off.
17837 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
17840 If the current buffer is a capture buffer, close the note and file it. With
17841 a prefix argument, also jump to the target location after saving the note.
17843 If the cursor is on a @code{<<<target>>>}, update radio targets and
17844 corresponding links in this buffer.
17846 If the cursor is on a property line or at the start or end of a property
17847 drawer, offer property commands.
17849 If the cursor is at a footnote reference, go to the corresponding
17850 definition, and @emph{vice versa}.
17852 If the cursor is on a statistics cookie, update it.
17854 If the cursor is in a plain list item with a checkbox, toggle the status
17857 If the cursor is on a numbered item in a plain list, renumber the
17860 If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
17863 If the cursor is at a timestamp, fix the day name in the timestamp.
17867 @section A cleaner outline view
17868 @cindex hiding leading stars
17869 @cindex dynamic indentation
17870 @cindex odd-levels-only outlines
17871 @cindex clean outline view
17873 Org's default outline with stars and no indents can become too cluttered for
17874 short documents. For @emph{book-like} long documents, the effect is not as
17875 noticeable. Org provides an alternate stars and indentation scheme, as shown
17876 on the right in the following table. It uses only one star and indents text
17877 to line with the heading:
17881 * Top level headline | * Top level headline
17882 ** Second level | * Second level
17883 *** 3rd level | * 3rd level
17884 some text | some text
17885 *** 3rd level | * 3rd level
17886 more text | more text
17887 * Another top level headline | * Another top level headline
17893 To turn this mode on, use the minor mode, @code{org-indent-mode}. Text lines
17894 that are not headlines are prefixed with spaces to vertically align with the
17895 headline text@footnote{The @code{org-indent-mode} also sets the
17896 @code{wrap-prefix} correctly for indenting and wrapping long lines of
17897 headlines or text. This minor mode handles @code{visual-line-mode} and
17898 directly applied settings through @code{word-wrap}.}.
17900 To make more horizontal space, the headlines are shifted by two stars. This
17901 can be configured by the @code{org-indent-indentation-per-level} variable.
17902 Only one star on each headline is visible, the rest are masked with the same
17903 font color as the background. This font face can be configured with the
17904 @code{org-hide} variable.
17906 Note that turning on @code{org-indent-mode} sets
17907 @code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
17908 @code{nil}; @samp{2.} below shows how this works.
17910 To globally turn on @code{org-indent-mode} for all files, customize the
17911 variable @code{org-startup-indented}.
17913 To turn on indenting for individual files, use @code{#+STARTUP} option as
17920 Indent on startup makes Org use hard spaces to align text with headings as
17921 shown in examples below.
17925 @emph{Indentation of text below headlines}@*
17926 Indent text to align with the headline.
17930 more text, now indented
17933 @vindex org-adapt-indentation
17934 Org adapts indentations with paragraph filling, line wrapping, and structure
17935 editing@footnote{Also see the variable @code{org-adapt-indentation}.}.
17938 @vindex org-hide-leading-stars
17939 @emph{Hiding leading stars}@* Org can make leading stars invisible. For
17940 global preference, configure the variable @code{org-hide-leading-stars}. For
17941 per-file preference, use these file @code{#+STARTUP} options:
17944 #+STARTUP: hidestars
17945 #+STARTUP: showstars
17948 With stars hidden, the tree is shown as:
17952 * Top level headline
17960 @vindex org-hide @r{(face)}
17961 Because Org makes the font color same as the background color to hide to
17962 stars, sometimes @code{org-hide} face may need tweaking to get the effect
17963 right. For some black and white combinations, @code{grey90} on a white
17964 background might mask the stars better.
17967 @vindex org-odd-levels-only
17968 Using stars for only odd levels, 1, 3, 5, @dots{}, can also clean up the
17969 clutter. This removes two stars from each level@footnote{Because
17970 @samp{LEVEL=2} has 3 stars, @samp{LEVEL=3} has 4 stars, and so on}. For Org
17971 to properly handle this cleaner structure during edits and exports, configure
17972 the variable @code{org-odd-levels-only}. To set this per-file, use either
17973 one of the following lines:
17980 To switch between single and double stars layouts, use @kbd{M-x
17981 org-convert-to-odd-levels RET} and @kbd{M-x org-convert-to-oddeven-levels}.
17985 @section Using Org on a tty
17986 @cindex tty key bindings
17988 Org provides alternative key bindings for TTY and modern mobile devices that
17989 cannot handle cursor keys and complex modifier key chords. Some of these
17990 workarounds may be more cumbersome than necessary. Users should look into
17991 customizing these further based on their usage needs. For example, the
17992 normal @kbd{S-@key{cursor}} for editing timestamp might be better with
17995 @multitable @columnfractions 0.15 0.2 0.1 0.2
17996 @item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
17997 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab
17998 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
17999 @item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab
18000 @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
18001 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab
18002 @item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
18003 @item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab
18004 @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
18005 @item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab
18006 @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab
18007 @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
18008 @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab
18009 @item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab
18010 @item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab
18011 @item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab
18012 @item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab
18013 @item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab
18014 @item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab
18019 @section Interaction with other packages
18020 @cindex packages, interaction with other
18021 Org's compatibility and the level of interaction with other Emacs packages
18022 are documented here.
18026 * Cooperation:: Packages Org cooperates with
18027 * Conflicts:: Packages that lead to conflicts
18031 @subsection Packages that Org cooperates with
18034 @cindex @file{calc.el}
18035 @cindex Gillespie, Dave
18036 @item @file{calc.el} by Dave Gillespie
18037 Org uses the Calc package for tables to implement spreadsheet functionality
18038 (@pxref{The spreadsheet}). Org also uses Calc for embedded calculations.
18039 @xref{Embedded Mode, , Embedded Mode, calc, GNU Emacs Calc Manual}.
18040 @item @file{constants.el} by Carsten Dominik
18041 @cindex @file{constants.el}
18042 @cindex Dominik, Carsten
18043 @vindex org-table-formula-constants
18044 Org can use names for constants in formulas in tables. Org can also use
18045 calculation suffixes for units, such as @samp{M} for @samp{Mega}. For a
18046 standard collection of such constants, install the @file{constants} package.
18047 Install version 2.0 of this package, available at
18048 @url{https://staff.fnwi.uva.nl/c.dominik/Tools/}. Org checks if the function
18049 @code{constants-get} has been autoloaded. Installation instructions are in
18050 the file, @file{constants.el}.
18051 @item @file{cdlatex.el} by Carsten Dominik
18052 @cindex @file{cdlatex.el}
18053 @cindex Dominik, Carsten
18054 Org mode can use CD@LaTeX{} package to efficiently enter @LaTeX{} fragments
18055 into Org files (@pxref{CDLaTeX mode}).
18056 @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
18057 @cindex @file{imenu.el}
18058 Imenu creates dynamic menus based on an index of items in a file. Org mode
18059 supports Imenu menus. Enable it with a mode hook as follows:
18061 (add-hook 'org-mode-hook
18062 (lambda () (imenu-add-to-menubar "Imenu")))
18064 @vindex org-imenu-depth
18065 By default the Imenu index is two levels deep. Change the index depth using
18066 thes variable, @code{org-imenu-depth}.
18067 @item @file{speedbar.el} by Eric M. Ludlam
18068 @cindex @file{speedbar.el}
18069 @cindex Ludlam, Eric M.
18070 Speedbar package creates a special Emacs frame for displaying files and index
18071 items in files. Org mode supports Speedbar; users can drill into Org files
18072 directly from the Speedbar. The @kbd{<} in the Speedbar frame tweaks the
18073 agenda commands to that file or to a subtree.
18074 @cindex @file{table.el}
18075 @item @file{table.el} by Takaaki Ota
18077 @cindex table editor, @file{table.el}
18078 @cindex @file{table.el}
18079 @cindex Ota, Takaaki
18081 Complex ASCII tables with automatic line wrapping, column- and row-spanning,
18082 and alignment can be created using the Emacs table package by Takaaki Ota.
18083 Org mode recognizes such tables and export them properly. @kbd{C-c '} to
18084 edit these tables in a special buffer, much like Org's @samp{src} code
18085 blocks. Because of interference with other Org mode functionality, Takaaki
18086 Ota tables cannot be edited directly in the Org buffer.
18088 @orgcmd{C-c ',org-edit-special}
18089 Edit a @file{table.el} table. Works when the cursor is in a table.el table.
18091 @orgcmd{C-c ~,org-table-create-with-table.el}
18092 Insert a @file{table.el} table. If there is already a table at point, this
18093 command converts it between the @file{table.el} format and the Org mode
18094 format. See the documentation string of the command @code{org-convert-table}
18100 @subsection Packages that conflict with Org mode
18104 @cindex @code{shift-selection-mode}
18105 @vindex org-support-shift-select
18106 In Emacs, @code{shift-selection-mode} combines cursor motions with shift key
18107 to enlarge regions. Emacs sets this mode by default. This conflicts with
18108 Org's use of @kbd{S-@key{cursor}} commands to change timestamps, TODO
18109 keywords, priorities, and item bullet types, etc. Since @kbd{S-@key{cursor}}
18110 commands outside of specific contexts don't do anything, Org offers the
18111 variable @code{org-support-shift-select} for customization. Org mode
18112 accommodates shift selection by (i) making it available outside of the
18113 special contexts where special commands apply, and (ii) extending an
18114 existing active region even if the cursor moves across a special context.
18116 @item @file{CUA.el} by Kim. F. Storm
18117 @cindex @file{CUA.el}
18118 @cindex Storm, Kim. F.
18119 @vindex org-replace-disputed-keys
18120 Org key bindings conflict with @kbd{S-<cursor>} keys used by CUA mode. For
18121 Org to relinquish these bindings to CUA mode, configure the variable
18122 @code{org-replace-disputed-keys}. When set, Org moves the following key
18123 bindings in Org files, and in the agenda buffer (but not during date
18127 S-UP @result{} M-p S-DOWN @result{} M-n
18128 S-LEFT @result{} M-- S-RIGHT @result{} M-+
18129 C-S-LEFT @result{} M-S-- C-S-RIGHT @result{} M-S-+
18132 @vindex org-disputed-keys
18133 Yes, these are unfortunately more difficult to remember. To define a
18134 different replacement keys, look at the variable @code{org-disputed-keys}.
18136 @item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org}
18137 @cindex @file{ecomplete.el}
18139 Ecomplete provides ``electric'' address completion in address header
18140 lines in message buffers. Sadly Orgtbl mode cuts ecompletes power
18141 supply: No completion happens when Orgtbl mode is enabled in message
18142 buffers while entering text in address header lines. If one wants to
18143 use ecomplete one should @emph{not} follow the advice to automagically
18144 turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but
18145 instead---after filling in the message headers---turn on Orgtbl mode
18146 manually when needed in the messages body.
18148 @item @file{filladapt.el} by Kyle Jones
18149 @cindex @file{filladapt.el}
18151 Org mode tries to do the right thing when filling paragraphs, list items and
18152 other elements. Many users reported problems using both @file{filladapt.el}
18153 and Org mode, so a safe thing to do is to disable filladapt like this:
18156 (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
18159 @item @file{yasnippet.el}
18160 @cindex @file{yasnippet.el}
18161 The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of
18162 @code{"\t"}) overrules YASnippet's access to this key. The following code
18163 fixed this problem:
18166 (add-hook 'org-mode-hook
18168 (setq-local yas/trigger-key [tab])
18169 (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
18172 The latest version of yasnippet doesn't play well with Org mode. If the
18173 above code does not fix the conflict, first define the following function:
18176 (defun yas/org-very-safe-expand ()
18177 (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
18180 Then tell Org mode to use that function:
18183 (add-hook 'org-mode-hook
18185 (make-variable-buffer-local 'yas/trigger-key)
18186 (setq yas/trigger-key [tab])
18187 (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
18188 (define-key yas/keymap [tab] 'yas/next-field)))
18191 @item @file{windmove.el} by Hovav Shacham
18192 @cindex @file{windmove.el}
18193 This package also uses the @kbd{S-<cursor>} keys, so everything written
18194 in the paragraph above about CUA mode also applies here. If you want make
18195 the windmove function active in locations where Org mode does not have
18196 special functionality on @kbd{S-@key{cursor}}, add this to your
18200 ;; Make windmove work in org-mode:
18201 (add-hook 'org-shiftup-final-hook 'windmove-up)
18202 (add-hook 'org-shiftleft-final-hook 'windmove-left)
18203 (add-hook 'org-shiftdown-final-hook 'windmove-down)
18204 (add-hook 'org-shiftright-final-hook 'windmove-right)
18207 @item @file{viper.el} by Michael Kifer
18208 @cindex @file{viper.el}
18210 Viper uses @kbd{C-c /} and therefore makes this key not access the
18211 corresponding Org mode command @code{org-sparse-tree}. You need to find
18212 another key for this command, or override the key in
18213 @code{viper-vi-global-user-map} with
18216 (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
18224 @section org-crypt.el
18225 @cindex @file{org-crypt.el}
18226 @cindex @code{org-decrypt-entry}
18228 Org crypt encrypts the text of an Org entry, but not the headline, or
18229 properties. Org crypt uses the Emacs EasyPG library to encrypt and decrypt.
18231 Any text below a headline that has a @samp{:crypt:} tag will be automatically
18232 be encrypted when the file is saved. To use a different tag, customize the
18233 @code{org-crypt-tag-matcher} variable.
18235 Suggested Org crypt settings in Emacs init file:
18238 (require 'org-crypt)
18239 (org-crypt-use-before-save-magic)
18240 (setq org-tags-exclude-from-inheritance (quote ("crypt")))
18242 (setq org-crypt-key nil)
18243 ;; GPG key to use for encryption
18244 ;; Either the Key ID or set to nil to use symmetric encryption.
18246 (setq auto-save-default nil)
18247 ;; Auto-saving does not cooperate with org-crypt.el: so you need
18248 ;; to turn it off if you plan to use org-crypt.el quite often.
18249 ;; Otherwise, you'll get an (annoying) message each time you
18252 ;; To turn it off only locally, you can insert this:
18254 ;; # -*- buffer-auto-save-file-name: nil; -*-
18257 Excluding the crypt tag from inheritance prevents encrypting previously
18264 This appendix covers some areas where users can extend the functionality of
18268 * Hooks:: How to reach into Org's internals
18269 * Add-on packages:: Available extensions
18270 * Adding hyperlink types:: New custom link types
18271 * Adding export back-ends:: How to write new export back-ends
18272 * Context-sensitive commands:: How to add functionality to such commands
18273 * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
18274 * Dynamic blocks:: Automatically filled blocks
18275 * Special agenda views:: Customized views
18276 * Speeding up your agendas:: Tips on how to speed up your agendas
18277 * Extracting agenda information:: Post-processing of agenda information
18278 * Using the property API:: Writing programs that use entry properties
18279 * Using the mapping API:: Mapping over all or selected entries
18286 Org has a large number of hook variables for adding functionality. This
18287 appendix illustrates using a few. A complete list of hooks with
18288 documentation is maintained by the Worg project at
18289 @uref{http://orgmode.org/worg/doc.html#hooks}.
18291 @node Add-on packages
18292 @section Add-on packages
18293 @cindex add-on packages
18295 Various authors wrote a large number of add-on packages for Org.
18297 These packages are not part of Emacs, but they are distributed as contributed
18298 packages with the separate release available at @uref{http://orgmode.org}.
18299 See the @file{contrib/README} file in the source code directory for a list of
18300 contributed files. Worg page with more information is at:
18301 @uref{http://orgmode.org/worg/org-contrib/}.
18303 @node Adding hyperlink types
18304 @section Adding hyperlink types
18305 @cindex hyperlinks, adding new types
18307 Org has many built-in hyperlink types (@pxref{Hyperlinks}), and an interface
18308 for adding new link types. The example file, @file{org-man.el}, shows the
18309 process of adding Org links to Unix man pages, which look like this:
18310 @samp{[[man:printf][The printf manpage]]}:
18313 ;;; org-man.el - Support for links to manpages in Org
18317 (org-add-link-type "man" 'org-man-open)
18318 (add-hook 'org-store-link-functions 'org-man-store-link)
18320 (defcustom org-man-command 'man
18321 "The Emacs command to be used to display a man page."
18323 :type '(choice (const man) (const woman)))
18325 (defun org-man-open (path)
18326 "Visit the manpage on PATH.
18327 PATH should be a topic that can be thrown at the man command."
18328 (funcall org-man-command path))
18330 (defun org-man-store-link ()
18331 "Store a link to a manpage."
18332 (when (memq major-mode '(Man-mode woman-mode))
18333 ;; This is a man page, we do make this link
18334 (let* ((page (org-man-get-page-name))
18335 (link (concat "man:" page))
18336 (description (format "Manpage for %s" page)))
18337 (org-store-link-props
18340 :description description))))
18342 (defun org-man-get-page-name ()
18343 "Extract the page name from the buffer name."
18344 ;; This works for both `Man-mode' and `woman-mode'.
18345 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
18346 (match-string 1 (buffer-name))
18347 (error "Cannot create link to this man page")))
18351 ;;; org-man.el ends here
18355 To activate links to man pages in Org, enter this in the init file:
18362 A review of @file{org-man.el}:
18365 First, @code{(require 'org)} ensures @file{org.el} is loaded.
18367 The @code{org-add-link-type} defines a new link type with @samp{man} prefix.
18368 The call contains the function to call that follows the link type.
18370 @vindex org-store-link-functions
18371 The next line adds a function to @code{org-store-link-functions} that records
18372 a useful link with the command @kbd{C-c l} in a buffer displaying a man page.
18375 The rest of the file defines necessary variables and functions. First is the
18376 customization variable @code{org-man-command}. It has two options,
18377 @code{man} and @code{woman}. Next is a function whose argument is the link
18378 path, which for man pages is the topic of the man command. To follow the
18379 link, the function calls the @code{org-man-command} to display the man page.
18382 @kbd{C-c l} constructs and stores the link.
18384 @kbd{C-c l} calls the function @code{org-man-store-link}, which first checks
18385 if the @code{major-mode} is appropriate. If check fails, the function
18386 returns @code{nil}. Otherwise the function makes a link string by combining
18387 the @samp{man:} prefix with the man topic. The function then calls
18388 @code{org-store-link-props} with @code{:type} and @code{:link} properties. A
18389 @code{:description} property is an optional string that is displayed when the
18390 function inserts the link in the Org buffer.
18392 @kbd{C-c C-l} inserts the stored link.
18394 To define new link types, define a function that implements completion
18395 support with @kbd{C-c C-l}. This function should not accept any arguments
18396 but return the appropriate prefix and complete link string.
18398 @node Adding export back-ends
18399 @section Adding export back-ends
18400 @cindex Export, writing back-ends
18402 Org's export engine makes it easy for writing new back-ends. The framework
18403 on which the engine was built makes it easy to derive new back-ends from
18406 The two main entry points to the export engine are:
18407 @code{org-export-define-backend} and
18408 @code{org-export-define-derived-backend}. To grok these functions, see
18409 @file{ox-latex.el} for an example of defining a new back-end from scratch,
18410 and @file{ox-beamer.el} for an example of deriving from an existing engine.
18412 For creating a new back-end from scratch, first set its name as a symbol in
18413 an alist consisting of elements and export functions. To make the back-end
18414 visible to the export dispatcher, set @code{:menu-entry} keyword. For export
18415 options specific to this back-end, set the @code{:options-alist}.
18417 For creating a new back-end from an existing one, set @code{:translate-alist}
18418 to an alist of export functions. This alist replaces the parent back-end
18421 For complete documentation, see
18422 @url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
18423 Reference on Worg}.
18425 @node Context-sensitive commands
18426 @section Context-sensitive commands
18427 @cindex context-sensitive commands, hooks
18428 @cindex add-ons, context-sensitive commands
18429 @vindex org-ctrl-c-ctrl-c-hook
18431 Org has facilities for building context sensitive commands. Authors of Org
18432 add-ons can tap into this functionality.
18434 Some Org commands change depending on the context. The most important
18435 example of this behavior is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c
18436 key}). Other examples are @kbd{M-cursor} and @kbd{M-S-cursor}.
18438 These context sensitive commands work by providing a function that detects
18439 special context for that add-on and executes functionality appropriate for
18442 @node Tables in arbitrary syntax
18443 @section Tables and lists in arbitrary syntax
18444 @cindex tables, in other modes
18445 @cindex lists, in other modes
18446 @cindex Orgtbl mode
18448 Because of Org's success in handling tables with Orgtbl, a frequently asked
18449 feature is to Org's usability functions to other table formats native to
18450 other modem's, such as @LaTeX{}. This would be hard to do in a general way
18451 without complicated customization nightmares. Moreover, that would take Org
18452 away from its simplicity roots that Orgtbl has proven. There is, however, an
18453 alternate approach to accomplishing the same.
18455 This approach involves implementing a custom @emph{translate} function that
18456 operates on a native Org @emph{source table} to produce a table in another
18457 format. This strategy would keep the excellently working Orgtbl simple and
18458 isolate complications, if any, confined to the translate function. To add
18459 more alien table formats, we just add more translate functions. Also the
18460 burden of developing custom translate functions for new table formats will be
18461 in the hands of those who know those formats best.
18463 For an example of how this strategy works, see Orgstruct mode. In that mode,
18464 Bastien added the ability to use Org's facilities to edit and re-structure
18465 lists. He did by turning @code{orgstruct-mode} on, and then exporting the
18466 list locally to another format, such as HTML, @LaTeX{} or Texinfo.
18469 * Radio tables:: Sending and receiving radio tables
18470 * A @LaTeX{} example:: Step by step, almost a tutorial
18471 * Translator functions:: Copy and modify
18472 * Radio lists:: Sending and receiving lists
18476 @subsection Radio tables
18477 @cindex radio tables
18479 Radio tables are target locations for translated tables that are not near
18480 their source. Org finds the target location and inserts the translated
18483 The key to finding the target location are the magic words @code{BEGIN/END
18484 RECEIVE ORGTBL}. They have to appear as comments in the current mode. If
18485 the mode is C, then:
18488 /* BEGIN RECEIVE ORGTBL table_name */
18489 /* END RECEIVE ORGTBL table_name */
18493 At the location of source, Org needs a special line to direct Orgtbl to
18494 translate and to find the target for inserting the translated table. For
18498 #+ORGTBL: SEND table_name translation_function arguments...
18502 @code{table_name} is the table's reference name, which is also used in the
18503 receiver lines, and the @code{translation_function} is the Lisp function that
18504 translates. This line, in addition, may also contain alternating key and
18505 value arguments at the end. The translation function gets these values as a
18506 property list. A few standard parameters are already recognized and acted
18507 upon before the translation function is called:
18511 Skip the first N lines of the table. Hlines do count; include them if they
18514 @item :skipcols (n1 n2 ...)
18515 List of columns to be skipped. First Org automatically discards columns with
18516 calculation marks and then sends the table to the translator function, which
18517 then skips columns as specified in @samp{skipcols}.
18521 To keep the source table intact in the buffer without being disturbed when
18522 the source file is compiled or otherwise being worked on, use one of these
18527 Place the table in a block comment. For example, in C mode you could wrap
18528 the table between @samp{/*} and @samp{*/} lines.
18530 Put the table after an @samp{END} statement. For example @samp{\bye} in
18531 @TeX{} and @samp{\end@{document@}} in @LaTeX{}.
18533 Comment and uncomment each line of the table during edits. The @kbd{M-x
18534 orgtbl-toggle-comment RET} command makes toggling easy.
18537 @node A @LaTeX{} example
18538 @subsection A @LaTeX{} example of radio tables
18539 @cindex @LaTeX{}, and Orgtbl mode
18541 To wrap a source table in @LaTeX{}, use the @code{comment} environment
18542 provided by @file{comment.sty}. To activate it, put
18543 @code{\usepackage@{comment@}} in the document header. Orgtbl mode inserts a
18544 radio table skeleton@footnote{By default this works only for @LaTeX{}, HTML,
18545 and Texinfo. Configure the variable @code{orgtbl-radio-table-templates} to
18546 install templates for other export formats.} with the command @kbd{M-x
18547 orgtbl-insert-radio-table RET}, which prompts for a table name. For example,
18548 if @samp{salesfigures} is the name, the template inserts:
18550 @cindex #+ORGTBL, SEND
18552 % BEGIN RECEIVE ORGTBL salesfigures
18553 % END RECEIVE ORGTBL salesfigures
18555 #+ORGTBL: SEND salesfigures orgtbl-to-latex
18561 @vindex @LaTeX{}-verbatim-environments
18562 The line @code{#+ORGTBL: SEND} tells Orgtbl mode to use the function
18563 @code{orgtbl-to-latex} to convert the table to @LaTeX{} format, then insert
18564 the table at the target (receive) location named @code{salesfigures}. Now
18565 the table is ready for data entry. It can even use spreadsheet
18566 features@footnote{If the @samp{#+TBLFM} line contains an odd number of dollar
18567 characters, this may cause problems with font-lock in @LaTeX{} mode. As
18568 shown in the example you can fix this by adding an extra line inside the
18569 @code{comment} environment that is used to balance the dollar expressions.
18570 If you are using AUC@TeX{} with the font-latex library, a much better
18571 solution is to add the @code{comment} environment to the variable
18572 @code{LaTeX-verbatim-environments}.}:
18575 % BEGIN RECEIVE ORGTBL salesfigures
18576 % END RECEIVE ORGTBL salesfigures
18578 #+ORGTBL: SEND salesfigures orgtbl-to-latex
18579 | Month | Days | Nr sold | per day |
18580 |-------+------+---------+---------|
18581 | Jan | 23 | 55 | 2.4 |
18582 | Feb | 21 | 16 | 0.8 |
18583 | March | 22 | 278 | 12.6 |
18584 #+TBLFM: $4=$3/$2;%.1f
18585 % $ (optional extra dollar to keep font-lock happy, see footnote)
18590 After editing, @kbd{C-c C-c} inserts translated table at the target location,
18591 between the two marker lines.
18593 For hand-made custom tables, note that the translator needs to skip the first
18594 two lines of the source table. Also the command has to @emph{splice} out the
18595 target table without the header and footer.
18598 \begin@{tabular@}@{lrrr@}
18599 Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
18600 % BEGIN RECEIVE ORGTBL salesfigures
18601 % END RECEIVE ORGTBL salesfigures
18605 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
18606 | Month | Days | Nr sold | per day |
18607 |-------+------+---------+---------|
18608 | Jan | 23 | 55 | 2.4 |
18609 | Feb | 21 | 16 | 0.8 |
18610 | March | 22 | 278 | 12.6 |
18611 #+TBLFM: $4=$3/$2;%.1f
18615 The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
18616 Orgtbl mode and uses @code{tabular} environment by default to typeset the
18617 table and mark the horizontal lines with @code{\hline}. For additional
18618 parameters to control output, @pxref{Translator functions}:
18621 @item :splice nil/t
18622 When non-@code{nil}, returns only table body lines; not wrapped in tabular
18623 environment. Default is @code{nil}.
18626 Format to warp each field. It should contain @code{%s} for the original
18627 field value. For example, to wrap each field value in dollar symbol, you
18628 could use @code{:fmt "$%s$"}. Format can also wrap a property list with
18629 column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
18630 In place of a string, a function of one argument can be used; the function
18631 must return a formatted string.
18634 Format numbers as exponentials. The spec should have @code{%s} twice for
18635 inserting mantissa and exponent, for example @code{"%s\\times10^@{%s@}"}.
18636 This may also be a property list with column numbers and formats, for example
18637 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
18638 @code{efmt} has been applied to a value, @code{fmt} will also be applied.
18639 Functions with two arguments can be supplied instead of strings. By default,
18640 no special formatting is applied.
18643 @node Translator functions
18644 @subsection Translator functions
18645 @cindex HTML, and Orgtbl mode
18646 @cindex translator function
18648 Orgtbl mode has built-in translator functions: @code{orgtbl-to-csv}
18649 (comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values),
18650 @code{orgtbl-to-latex}, @code{orgtbl-to-html}, @code{orgtbl-to-texinfo},
18651 @code{orgtbl-to-unicode} and @code{orgtbl-to-orgtbl}. They use the generic
18652 translator, @code{orgtbl-to-generic}, which delegates translations to various
18655 Properties passed to the function through the @samp{ORGTBL SEND} line take
18656 precedence over properties defined inside the function. For example, this
18657 overrides the default @LaTeX{} line endings, @samp{\\}, with @samp{\\[2mm]}:
18660 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
18663 For a new language translator, define a converter function. It can be a
18664 generic function, such as shown in this example. It marks a beginning and
18665 ending of a table with @samp{!BTBL!} and @samp{!ETBL!}; a beginning and
18666 ending of lines with @samp{!BL!} and @samp{!EL!}; and uses a TAB for a field
18670 (defun orgtbl-to-language (table params)
18671 "Convert the orgtbl-mode TABLE to language."
18674 (org-combine-plists
18675 '(:tstart "!BTBL!" :tend "!ETBL!" :lstart "!BL!" :lend "!EL!" :sep "\t")
18680 The documentation for the @code{orgtbl-to-generic} function shows a complete
18681 list of parameters, each of which can be passed through to
18682 @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
18683 using that generic function.
18685 For complicated translations the generic translator function could be
18686 replaced by a custom translator function. Such a custom function must take
18687 two arguments and return a single string containing the formatted table. The
18688 first argument is the table whose lines are a list of fields or the symbol
18689 @code{hline}. The second argument is the property list consisting of
18690 parameters specified in the @samp{#+ORGTBL: SEND} line. Please share your
18691 translator functions by posting them to the Org users mailing list,
18692 @email{emacs-orgmode@@gnu.org}.
18695 @subsection Radio lists
18696 @cindex radio lists
18697 @cindex org-list-insert-radio-list
18699 Call the @code{org-list-insert-radio-list} function to insert a radio list
18700 template in HTML, @LaTeX{}, and Texinfo mode documents. Sending and
18701 receiving radio lists works is the same as for radio tables (@pxref{Radio
18702 tables}) except for these differences:
18707 Orgstruct mode must be active.
18709 Use @code{ORGLST} keyword instead of @code{ORGTBL}.
18711 @kbd{C-c C-c} works only on the first list item.
18714 Built-in translators functions are: @code{org-list-to-latex},
18715 @code{org-list-to-html} and @code{org-list-to-texinfo}. They use the
18716 @code{org-list-to-generic} translator function. See its documentation for
18717 parameters for accurate customizations of lists. Here is a @LaTeX{} example:
18720 % BEGIN RECEIVE ORGLST to-buy
18721 % END RECEIVE ORGLST to-buy
18723 #+ORGLST: SEND to-buy org-list-to-latex
18732 @kbd{C-c C-c} on @samp{a new house} inserts the translated @LaTeX{} list
18733 in-between the BEGIN and END marker lines.
18735 @node Dynamic blocks
18736 @section Dynamic blocks
18737 @cindex dynamic blocks
18739 Org supports @emph{dynamic blocks} in Org documents. They are inserted with
18740 begin and end markers like any other @samp{src} code block, but the contents
18741 are updated automatically by a user function. For example, @kbd{C-c C-x C-r}
18742 inserts a dynamic table that updates the work time (@pxref{Clocking work
18745 Dynamic blocks can have names and function parameters. The syntax is similar
18746 to @samp{src} code block specifications:
18748 @cindex #+BEGIN:dynamic block
18750 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
18755 These command update dynamic blocks:
18758 @orgcmd{C-c C-x C-u,org-dblock-update}
18759 Update dynamic block at point.
18760 @orgkey{C-u C-c C-x C-u}
18761 Update all dynamic blocks in the current file.
18764 Before updating a dynamic block, Org removes content between the BEGIN and
18765 END markers. Org then reads the parameters on the BEGIN line for passing to
18766 the writer function. If the function expects to access the removed content,
18767 then Org expects an extra parameter, @code{:content}, on the BEGIN line.
18769 To syntax for calling a writer function with a named block, @code{myblock}
18770 is: @code{org-dblock-write:myblock}. Parameters come from the BEGIN line.
18772 The following is an example of a dynamic block and a block writer function
18773 that updates the time when the function was last run:
18776 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
18782 The dynamic block's writer function:
18785 (defun org-dblock-write:block-update-time (params)
18786 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
18787 (insert "Last block update at: "
18788 (format-time-string fmt))))
18791 To keep dynamic blocks up-to-date in an Org file, use the function,
18792 @code{org-update-all-dblocks} in hook, such as @code{before-save-hook}. The
18793 @code{org-update-all-dblocks} function does not run if the file is not in
18796 Dynamic blocks, like any other block, can be narrowed with
18797 @code{org-narrow-to-block}.
18799 @node Special agenda views
18800 @section Special agenda views
18801 @cindex agenda views, user-defined
18803 @vindex org-agenda-skip-function
18804 @vindex org-agenda-skip-function-global
18805 Org provides a special hook to further limit items in agenda views:
18806 @code{agenda}, @code{agenda*}@footnote{The @code{agenda*} view is the same as
18807 @code{agenda} except that it only considers @emph{appointments}, i.e.,
18808 scheduled and deadline items that have a time specification @samp{[h]h:mm} in
18809 their time-stamps.}, @code{todo}, @code{alltodo}, @code{tags},
18810 @code{tags-todo}, @code{tags-tree}. Specify a custom function that tests
18811 inclusion of every matched item in the view. This function can also
18812 skip as much as is needed.
18814 For a global condition applicable to agenda views, use the
18815 @code{org-agenda-skip-function-global} variable. Org uses a global condition
18816 with @code{org-agenda-skip-function} for custom searching.
18818 This example defines a function for a custom view showing TODO items with
18819 WAITING status. Manually this is a multi step search process, but with a
18820 custom view, this can be automated as follows:
18822 The custom function searches the subtree for the WAITING tag and returns
18823 @code{nil} on match. Otherwise it gives the location from where the search
18827 (defun my-skip-unless-waiting ()
18828 "Skip trees that are not waiting"
18829 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
18830 (if (re-search-forward ":waiting:" subtree-end t)
18831 nil ; tag found, do not skip
18832 subtree-end))) ; tag not found, continue after end of subtree
18835 To use this custom function in a custom agenda command:
18838 (org-add-agenda-custom-command
18839 '("b" todo "PROJECT"
18840 ((org-agenda-skip-function 'my-skip-unless-waiting)
18841 (org-agenda-overriding-header "Projects waiting for something: "))))
18844 @vindex org-agenda-overriding-header
18845 Note that this also binds @code{org-agenda-overriding-header} to a more
18846 meaningful string suitable for the agenda view.
18848 @vindex org-odd-levels-only
18849 @vindex org-agenda-skip-function
18851 Search for entries with a limit set on levels for the custom search. This is
18852 a general approach to creating custom searches in Org. To include all
18853 levels, use @samp{LEVEL>0}@footnote{Note that, for
18854 @code{org-odd-levels-only}, a level number corresponds to order in the
18855 hierarchy, not to the number of stars.}. Then to selectively pick the
18856 matched entries, use @code{org-agenda-skip-function}, which also accepts Lisp
18857 forms, such as @code{org-agenda-skip-entry-if} and
18858 @code{org-agenda-skip-subtree-if}. For example:
18861 @item (org-agenda-skip-entry-if 'scheduled)
18862 Skip current entry if it has been scheduled.
18863 @item (org-agenda-skip-entry-if 'notscheduled)
18864 Skip current entry if it has not been scheduled.
18865 @item (org-agenda-skip-entry-if 'deadline)
18866 Skip current entry if it has a deadline.
18867 @item (org-agenda-skip-entry-if 'scheduled 'deadline)
18868 Skip current entry if it has a deadline, or if it is scheduled.
18869 @item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
18870 Skip current entry if the TODO keyword is TODO or WAITING.
18871 @item (org-agenda-skip-entry-if 'todo 'done)
18872 Skip current entry if the TODO keyword marks a DONE state.
18873 @item (org-agenda-skip-entry-if 'timestamp)
18874 Skip current entry if it has any timestamp, may also be deadline or scheduled.
18875 @anchor{x-agenda-skip-entry-regexp}
18876 @item (org-agenda-skip-entry-if 'regexp "regular expression")
18877 Skip current entry if the regular expression matches in the entry.
18878 @item (org-agenda-skip-entry-if 'notregexp "regular expression")
18879 Skip current entry unless the regular expression matches.
18880 @item (org-agenda-skip-subtree-if 'regexp "regular expression")
18881 Same as above, but check and skip the entire subtree.
18884 The following is an example of a search for @samp{WAITING} without the
18888 (org-add-agenda-custom-command
18889 '("b" todo "PROJECT"
18890 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
18891 'regexp ":waiting:"))
18892 (org-agenda-overriding-header "Projects waiting for something: "))))
18895 @node Speeding up your agendas
18896 @section Speeding up your agendas
18897 @cindex agenda views, optimization
18899 Some agenda commands slow down when the Org files grow in size or number.
18900 Here are tips to speed up:
18904 Reduce the number of Org agenda files to avoid slowdowns due to hard drive
18907 Reduce the number of @samp{DONE} and archived headlines so agenda operations
18908 that skip over these can finish faster.
18910 @vindex org-agenda-dim-blocked-tasks
18911 Do not dim blocked tasks:
18913 (setq org-agenda-dim-blocked-tasks nil)
18916 @vindex org-startup-folded
18917 @vindex org-agenda-inhibit-startup
18918 Stop preparing agenda buffers on startup:
18920 (setq org-agenda-inhibit-startup nil)
18923 @vindex org-agenda-show-inherited-tags
18924 @vindex org-agenda-use-tag-inheritance
18925 Disable tag inheritance for agendas:
18927 (setq org-agenda-use-tag-inheritance nil)
18931 These options can be applied to selected agenda views. For more details
18932 about generation of agenda views, see the docstrings for the relevant
18933 variables, and this @uref{http://orgmode.org/worg/agenda-optimization.html,
18934 dedicated Worg page} for agenda optimization.
18936 @node Extracting agenda information
18937 @section Extracting agenda information
18938 @cindex agenda, pipe
18939 @cindex Scripts, for agenda processing
18941 @vindex org-agenda-custom-commands
18942 Org provides commands to access agendas through Emacs batch mode. Through
18943 this command-line interface, agendas are automated for further processing or
18946 @code{org-batch-agenda} creates an agenda view in ASCII and outputs to
18947 STDOUT. This command takes one string parameter. When string length=1, Org
18948 uses it as a key to @code{org-agenda-custom-commands}. These are the same
18949 ones available through @kbd{C-c a}.
18951 This example command line directly prints the TODO list to the printer:
18954 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
18957 When the string parameter length is two or more characters, Org matches it
18958 with tags/TODO strings. For example, this example command line prints items
18959 tagged with @samp{shop}, but excludes items tagged with @samp{NewYork}:
18962 emacs -batch -l ~/.emacs \
18963 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
18967 An example showing on-the-fly parameter modifications:
18970 emacs -batch -l ~/.emacs \
18971 -eval '(org-batch-agenda "a" \
18972 org-agenda-span (quote month) \
18973 org-agenda-include-diary nil \
18974 org-agenda-files (quote ("~/org/project.org")))' \
18979 which will produce an agenda for the next 30 days from just the
18980 @file{~/org/projects.org} file.
18982 For structured processing of agenda output, use @code{org-batch-agenda-csv}
18983 with the following fields:
18986 category @r{The category of the item}
18987 head @r{The headline, without TODO keyword, TAGS and PRIORITY}
18988 type @r{The type of the agenda entry, can be}
18989 todo @r{selected in TODO match}
18990 tagsmatch @r{selected in tags match}
18991 diary @r{imported from diary}
18992 deadline @r{a deadline}
18993 scheduled @r{scheduled}
18994 timestamp @r{appointment, selected by timestamp}
18995 closed @r{entry was closed on date}
18996 upcoming-deadline @r{warning about nearing deadline}
18997 past-scheduled @r{forwarded scheduled item}
18998 block @r{entry has date block including date}
18999 todo @r{The TODO keyword, if any}
19000 tags @r{All tags including inherited ones, separated by colons}
19001 date @r{The relevant date, like 2007-2-14}
19002 time @r{The time, like 15:00-16:50}
19003 extra @r{String with extra planning info}
19004 priority-l @r{The priority letter if any was given}
19005 priority-n @r{The computed numerical priority}
19009 If the selection of the agenda item was based on a timestamp, including those
19010 items with @samp{DEADLINE} and @samp{SCHEDULED} keywords, then Org includes
19011 date and time in the output.
19013 If the selection of the agenda item was based on a timestamp (or
19014 deadline/scheduled), then Org includes date and time in the output.
19016 Here is an example of a post-processing script in Perl. It takes the CSV
19017 output from Emacs and prints with a checkbox:
19022 # define the Emacs command to run
19023 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
19025 # run it and capture the output
19026 $agenda = qx@{$cmd 2>/dev/null@};
19028 # loop over all lines
19029 foreach $line (split(/\n/,$agenda)) @{
19030 # get the individual values
19031 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
19032 $priority_l,$priority_n) = split(/,/,$line);
19033 # process and print
19034 print "[ ] $head\n";
19038 @node Using the property API
19039 @section Using the property API
19040 @cindex API, for properties
19041 @cindex properties, API
19043 Functions for working with properties.
19045 @defun org-entry-properties &optional pom which
19046 Get all properties of the entry at point-or-marker POM.@*
19047 This includes the TODO keyword, the tags, time strings for deadline,
19048 scheduled, and clocking, and any additional properties defined in the
19049 entry. The return value is an alist. Keys may occur multiple times
19050 if the property key was used several times.@*
19051 POM may also be @code{nil}, in which case the current entry is used.
19052 If WHICH is @code{nil} or @code{all}, get all properties. If WHICH is
19053 @code{special} or @code{standard}, only get that subclass.
19056 @vindex org-use-property-inheritance
19057 @findex org-insert-property-drawer
19058 @defun org-entry-get pom property &optional inherit
19059 Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@. By
19060 default, this only looks at properties defined locally in the entry. If
19061 @code{INHERIT} is non-@code{nil} and the entry does not have the property,
19062 then also check higher levels of the hierarchy. If @code{INHERIT} is the
19063 symbol @code{selective}, use inheritance if and only if the setting of
19064 @code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance.
19067 @defun org-entry-delete pom property
19068 Delete the property @code{PROPERTY} from entry at point-or-marker POM.
19071 @defun org-entry-put pom property value
19072 Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM.
19075 @defun org-buffer-property-keys &optional include-specials
19076 Get all property keys in the current buffer.
19079 @defun org-insert-property-drawer
19080 Insert a property drawer for the current entry.
19083 @defun org-entry-put-multivalued-property pom property &rest values
19084 Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@.
19085 @code{VALUES} should be a list of strings. They will be concatenated, with
19086 spaces as separators.
19089 @defun org-entry-get-multivalued-property pom property
19090 Treat the value of the property @code{PROPERTY} as a whitespace-separated
19091 list of values and return the values as a list of strings.
19094 @defun org-entry-add-to-multivalued-property pom property value
19095 Treat the value of the property @code{PROPERTY} as a whitespace-separated
19096 list of values and make sure that @code{VALUE} is in this list.
19099 @defun org-entry-remove-from-multivalued-property pom property value
19100 Treat the value of the property @code{PROPERTY} as a whitespace-separated
19101 list of values and make sure that @code{VALUE} is @emph{not} in this list.
19104 @defun org-entry-member-in-multivalued-property pom property value
19105 Treat the value of the property @code{PROPERTY} as a whitespace-separated
19106 list of values and check if @code{VALUE} is in this list.
19109 @defopt org-property-allowed-value-functions
19110 Hook for functions supplying allowed values for a specific property.
19111 The functions must take a single argument, the name of the property, and
19112 return a flat list of allowed values. If @samp{:ETC} is one of
19113 the values, use the values as completion help, but allow also other values
19114 to be entered. The functions must return @code{nil} if they are not
19115 responsible for this property.
19118 @node Using the mapping API
19119 @section Using the mapping API
19120 @cindex API, for mapping
19121 @cindex mapping entries, API
19123 Org has sophisticated mapping capabilities for finding entries. Org uses
19124 this functionality internally for generating agenda views. Org also exposes
19125 an API for executing arbitrary functions for each selected entry. The API's
19126 main entry point is:
19128 @defun org-map-entries func &optional match scope &rest skip
19129 Call @samp{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}.
19131 @samp{FUNC} is a function or a Lisp form. With the cursor positioned at the
19132 beginning of the headline, call the function without arguments. Org returns
19133 an alist of return values of calls to the function.
19135 To avoid preserving point, Org wraps the call to @code{FUNC} in
19136 save-excursion form. After evaluation, Org moves the cursor to the end of
19137 the line that was just processed. Search continues from that point forward.
19138 This may not always work as expected under some conditions, such as if the
19139 current sub-tree was removed by a previous archiving operation. In such rare
19140 circumstances, Org skips the next entry entirely when it should not. To stop
19141 Org from such skips, make @samp{FUNC} set the variable
19142 @code{org-map-continue-from} to a specific buffer position.
19144 @samp{MATCH} is a tags/property/TODO match. Org iterates only matched
19145 headlines. Org iterates over all headlines when @code{MATCH} is @code{nil}
19148 @samp{SCOPE} determines the scope of this command. It can be any of:
19151 nil @r{the current buffer, respecting the restriction if any}
19152 tree @r{the subtree started with the entry at point}
19153 region @r{The entries within the active region, if any}
19154 file @r{the current buffer, without restriction}
19156 @r{the current buffer, and any archives associated with it}
19157 agenda @r{all agenda files}
19158 agenda-with-archives
19159 @r{all agenda files with any archive files associated with them}
19161 @r{if this is a list, all files in the list will be scanned}
19164 The remaining args are treated as settings for the scanner's skipping
19165 facilities. Valid args are:
19167 @vindex org-agenda-skip-function
19169 archive @r{skip trees with the archive tag}
19170 comment @r{skip trees with the COMMENT keyword}
19171 function or Lisp form
19172 @r{will be used as value for @code{org-agenda-skip-function},}
19173 @r{so whenever the function returns t, FUNC}
19174 @r{will not be called for that entry and search will}
19175 @r{continue from the point where the function leaves it}
19179 The mapping routine can call any arbitrary function, even functions that
19180 change meta data or query the property API (@pxref{Using the property API}).
19181 Here are some handy functions:
19183 @defun org-todo &optional arg
19184 Change the TODO state of the entry. See the docstring of the functions for
19185 the many possible values for the argument @code{ARG}.
19188 @defun org-priority &optional action
19189 Change the priority of the entry. See the docstring of this function for the
19190 possible values for @code{ACTION}.
19193 @defun org-toggle-tag tag &optional onoff
19194 Toggle the tag @code{TAG} in the current entry. Setting @code{ONOFF} to
19195 either @code{on} or @code{off} will not toggle tag, but ensure that it is
19200 Promote the current entry.
19204 Demote the current entry.
19207 This example turns all entries tagged with @code{TOMORROW} into TODO entries
19208 with keyword @code{UPCOMING}. Org ignores entries in comment trees and
19213 '(org-todo "UPCOMING")
19214 "+TOMORROW" 'file 'archive 'comment)
19217 The following example counts the number of entries with TODO keyword
19218 @code{WAITING}, in all agenda files.
19221 (length (org-map-entries t "/+WAITING" 'agenda))
19225 @appendix MobileOrg
19229 MobileOrg is a companion mobile app that runs on iOS and Android devices.
19230 MobileOrg enables offline-views and capture support for an Org mode system
19231 that is rooted on a ``real'' computer. MobileOrg can record changes to
19234 The @uref{https://github.com/MobileOrg/, iOS implementation} for the
19235 @emph{iPhone/iPod Touch/iPad} series of devices, was started by Richard
19236 Moreland and is now in the hands Sean Escriva. Android users should check
19237 out @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg
19238 Android} by Matt Jones. Though the two implementations are not identical,
19239 they offer similar features.
19241 This appendix describes Org's support for agenda view formats compatible with
19242 MobileOrg. It also describes synchronizing changes, such as to notes,
19243 between MobileOrg and the computer.
19245 To change tags and TODO states in MobileOrg, first customize the variables
19246 @code{org-todo-keywords} and @code{org-tag-alist}. These should cover all
19247 the important tags and TODO keywords, even if Org files use only some of
19248 them. Though MobileOrg has in-buffer settings, it understands TODO states
19249 @emph{sets} (@pxref{Per-file keywords}) and @emph{mutually exclusive} tags
19250 (@pxref{Setting tags}) only for those set in these variables.
19253 * Setting up the staging area:: For the mobile device
19254 * Pushing to MobileOrg:: Uploading Org files and agendas
19255 * Pulling from MobileOrg:: Integrating captured and flagged items
19258 @node Setting up the staging area
19259 @section Setting up the staging area
19261 MobileOrg needs access to a file directory on a server to interact with
19262 Emacs. With a public server, consider encrypting the files. MobileOrg
19263 version 1.5 supports encryption for the iPhone. Org also requires
19264 @file{openssl} installed on the local computer. To turn on encryption, set
19265 the same password in MobileOrg and in Emacs. Set the password in the
19266 variable @code{org-mobile-use-encryption}@footnote{If Emacs is configured for
19267 safe storing of passwords, then configure the variable,
19268 @code{org-mobile-encryption-password}; please read the docstring of that
19269 variable.}. Note that even after MobileOrg encrypts the file contents, the
19270 file names will remain visible on the file systems of the local computer, the
19271 server, and the mobile device.
19273 For a server to host files, consider options like
19274 @uref{http://dropbox.com,Dropbox.com} account@footnote{An alternative is to
19275 use webdav server. MobileOrg documentation has details of webdav server
19276 configuration. Additional help is at
19277 @uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
19278 On first connection, MobileOrg creates a directory @file{MobileOrg/} on
19279 Dropbox. Pass its location to Emacs through an init file variable as
19283 (setq org-mobile-directory "~/Dropbox/MobileOrg")
19286 Org copies files to the above directory for MobileOrg. Org also uses the
19287 same directory for sharing notes between Org and MobileOrg.
19289 @node Pushing to MobileOrg
19290 @section Pushing to MobileOrg
19292 Org pushes files listed in @code{org-mobile-files} to
19293 @code{org-mobile-directory}. Files include agenda files (as listed in
19294 @code{org-agenda-files}). Customize @code{org-mobile-files} to add other
19295 files. File names will be staged with paths relative to
19296 @code{org-directory}, so all files should be inside this
19297 directory@footnote{Symbolic links in @code{org-directory} should have the
19298 same name as their targets.}.
19300 Push creates a special Org file @file{agendas.org} with custom agenda views
19301 defined by the user@footnote{While creating the agendas, Org mode will force
19302 ID properties on all referenced entries, so that these entries can be
19303 uniquely identified if MobileOrg flags them for further action. To avoid
19304 setting properties configure the variable
19305 @code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then
19306 rely on outline paths, assuming they are unique.}.
19308 Org writes the file @file{index.org}, containing links to other files.
19309 MobileOrg reads this file first from the server to determine what other files
19310 to download for agendas. For faster downloads, MobileOrg will read only
19311 those files whose checksums@footnote{Checksums are stored automatically in
19312 the file @file{checksums.dat}.} have changed.
19314 @node Pulling from MobileOrg
19315 @section Pulling from MobileOrg
19317 When MobileOrg synchronizes with the server, it pulls the Org files for
19318 viewing. It then appends to the file @file{mobileorg.org} on the server the
19319 captured entries, pointers to flagged and changed entries. Org integrates
19320 its data in an inbox file format.
19324 Org moves all entries found in
19325 @file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this
19326 operation.} and appends them to the file pointed to by the variable
19327 @code{org-mobile-inbox-for-pull}. Each captured entry and each editing event
19328 is a top-level entry in the inbox file.
19330 After moving the entries, Org attempts changes to MobileOrg. Some changes
19331 are applied directly and without user interaction. Examples include changes
19332 to tags, TODO state, headline and body text. Entries for further action are
19333 tagged as @code{:FLAGGED:}. Org marks entries with problems with an error
19334 message in the inbox. They have to be resolved manually.
19336 Org generates an agenda view for flagged entries for user intervention to
19337 clean up. For notes stored in flagged entries, MobileOrg displays them in
19338 the echo area when the cursor is on the corresponding agenda item.
19343 Pressing @kbd{?} displays the entire flagged note in another window. Org
19344 also pushes it to the kill ring. To store flagged note as a normal note, use
19345 @kbd{? z C-y C-c C-c}. Pressing @kbd{?} twice does these things: first it
19346 removes the @code{:FLAGGED:} tag; second, it removes the flagged note from
19347 the property drawer; third, it signals that manual editing of the flagged
19348 entry is now finished.
19353 @kbd{C-c a ?} returns to the agenda view to finish processing flagged
19354 entries. Note that these entries may not be the most recent since MobileOrg
19355 searches files that were last pulled. To get an updated agenda view with
19356 changes since the last pull, pull again.
19358 @node History and acknowledgments
19359 @appendix History and acknowledgments
19360 @cindex acknowledgments
19364 @section From Carsten
19366 Org was born in 2003, out of frustration over the user interface of the Emacs
19367 Outline mode. I was trying to organize my notes and projects, and using
19368 Emacs seemed to be the natural way to go. However, having to remember eleven
19369 different commands with two or three keys per command, only to hide and show
19370 parts of the outline tree, that seemed entirely unacceptable. Also, when
19371 using outlines to take notes, I constantly wanted to restructure the tree,
19372 organizing it paralleling my thoughts and plans. @emph{Visibility cycling}
19373 and @emph{structure editing} were originally implemented in the package
19374 @file{outline-magic.el}, but quickly moved to the more general @file{org.el}.
19375 As this environment became comfortable for project planning, the next step
19376 was adding @emph{TODO entries}, basic @emph{timestamps}, and @emph{table
19377 support}. These areas highlighted the two main goals that Org still has
19378 today: to be a new, outline-based, plain text mode with innovative and
19379 intuitive editing features, and to incorporate project planning functionality
19380 directly into a notes file.
19382 Since the first release, literally thousands of emails to me or to
19383 @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug
19384 reports, feedback, new ideas, and sometimes patches and add-on code.
19385 Many thanks to everyone who has helped to improve this package. I am
19386 trying to keep here a list of the people who had significant influence
19387 in shaping one or more aspects of Org. The list may not be
19388 complete, if I have forgotten someone, please accept my apologies and
19391 Before I get to this list, a few special mentions are in order:
19394 @item Bastien Guerry
19395 Bastien has written a large number of extensions to Org (most of them
19396 integrated into the core by now), including the @LaTeX{} exporter and the
19397 plain list parser. His support during the early days was central to the
19398 success of this project. Bastien also invented Worg, helped establishing the
19399 Web presence of Org, and sponsored hosting costs for the orgmode.org website.
19400 Bastien stepped in as maintainer of Org between 2011 and 2013, at a time when
19401 I desperately needed a break.
19402 @item Eric Schulte and Dan Davison
19403 Eric and Dan are jointly responsible for the Org-babel system, which turns
19404 Org into a multi-language environment for evaluating code and doing literate
19405 programming and reproducible research. This has become one of Org's killer
19406 features that define what Org is today.
19408 John has contributed a number of great ideas and patches directly to Org,
19409 including the attachment system (@file{org-attach.el}), integration with
19410 Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO
19411 items, habit tracking (@file{org-habits.el}), and encryption
19412 (@file{org-crypt.el}). Also, the capture system is really an extended copy
19413 of his great @file{remember.el}.
19414 @item Sebastian Rose
19415 Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
19416 of an ignorant amateur. Sebastian has pushed this part of Org onto a much
19417 higher level. He also wrote @file{org-info.js}, a Java script for displaying
19418 web pages derived from Org using an Info-like or a folding interface with
19419 single-key navigation.
19422 @noindent See below for the full list of contributions! Again, please
19423 let me know what I am missing here!
19425 @section From Bastien
19427 I (Bastien) have been maintaining Org between 2011 and 2013. This appendix
19428 would not be complete without adding a few more acknowledgments and thanks.
19430 I am first grateful to Carsten for his trust while handing me over the
19431 maintainership of Org. His unremitting support is what really helped me
19432 getting more confident over time, with both the community and the code.
19434 When I took over maintainership, I knew I would have to make Org more
19435 collaborative than ever, as I would have to rely on people that are more
19436 knowledgeable than I am on many parts of the code. Here is a list of the
19437 persons I could rely on, they should really be considered co-maintainers,
19438 either of the code or the community:
19442 Eric is maintaining the Babel parts of Org. His reactivity here kept me away
19443 from worrying about possible bugs here and let me focus on other parts.
19445 @item Nicolas Goaziou
19446 Nicolas is maintaining the consistency of the deepest parts of Org. His work
19447 on @file{org-element.el} and @file{ox.el} has been outstanding, and it opened
19448 the doors for many new ideas and features. He rewrote many of the old
19449 exporters to use the new export engine, and helped with documenting this
19450 major change. More importantly (if that's possible), he has been more than
19451 reliable during all the work done for Org 8.0, and always very reactive on
19455 Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
19456 into a flexible and conceptually clean process. He patiently coped with the
19457 many hiccups that such a change can create for users.
19460 The Org mode mailing list would not be such a nice place without Nick, who
19461 patiently helped users so many times. It is impossible to overestimate such
19462 a great help, and the list would not be so active without him.
19465 I received support from so many users that it is clearly impossible to be
19466 fair when shortlisting a few of them, but Org's history would not be
19467 complete if the ones above were not mentioned in this manual.
19469 @section List of contributions
19474 @i{Russel Adams} came up with the idea for drawers.
19476 @i{Suvayu Ali} has steadily helped on the mailing list, providing useful
19477 feedback on many features and several patches.
19479 @i{Luis Anaya} wrote @file{ox-man.el}.
19481 @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
19483 @i{Michael Brand} helped by reporting many bugs and testing many features.
19484 He also implemented the distinction between empty fields and 0-value fields
19485 in Org's spreadsheets.
19487 @i{Christophe Bataillon} created the great unicorn logo that we use on the
19490 @i{Alex Bochannek} provided a patch for rounding timestamps.
19492 @i{Jan Böcker} wrote @file{org-docview.el}.
19494 @i{Brad Bozarth} showed how to pull RSS feed data into Org mode files.
19496 @i{Tom Breton} wrote @file{org-choose.el}.
19498 @i{Charles Cave}'s suggestion sparked the implementation of templates
19499 for Remember, which are now templates for capture.
19501 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
19504 @i{Gregory Chernov} patched support for Lisp forms into table
19505 calculations and improved XEmacs compatibility, in particular by porting
19506 @file{nouline.el} to XEmacs.
19508 @i{Sacha Chua} suggested copying some linking code from Planner, and helped
19509 make Org popular through her blog.
19511 @i{Toby S. Cubitt} contributed to the code for clock formats.
19513 @i{Baoqiu Cui} contributed the first DocBook exporter. In Org 8.0, we go a
19514 different route: you can now export to Texinfo and export the @file{.texi}
19515 file to DocBook using @code{makeinfo}.
19517 @i{Eddward DeVilla} proposed and tested checkbox statistics. He also
19518 came up with the idea of properties, and that there should be an API for
19521 @i{Nick Dokos} tracked down several nasty bugs.
19523 @i{Kees Dullemond} used to edit projects lists directly in HTML and so
19524 inspired some of the early development, including HTML export. He also
19525 asked for a way to narrow wide table columns.
19527 @i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for
19528 several years now. He also sponsored the hosting costs until Rackspace
19529 started to host us for free.
19531 @i{Thomas S. Dye} contributed documentation on Worg and helped integrating
19532 the Org-Babel documentation into the manual.
19534 @i{Christian Egli} converted the documentation into Texinfo format, inspired
19535 the agenda, patched CSS formatting into the HTML exporter, and wrote
19536 @file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as
19537 @file{ox-taskjuggler.el} for Org 8.0.
19539 @i{David Emery} provided a patch for custom CSS support in exported
19542 @i{Sean Escriva} took over MobileOrg development on the iPhone platform.
19544 @i{Nic Ferrier} contributed mailcap and XOXO support.
19546 @i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
19548 @i{John Foerch} figured out how to make incremental search show context
19549 around a match in a hidden outline tree.
19551 @i{Raimar Finken} wrote @file{org-git-line.el}.
19553 @i{Mikael Fornius} works as a mailing list moderator.
19555 @i{Austin Frank} works as a mailing list moderator.
19557 @i{Eric Fraga} drove the development of BEAMER export with ideas and
19560 @i{Barry Gidden} did proofreading the manual in preparation for the book
19561 publication through Network Theory Ltd.
19563 @i{Niels Giesen} had the idea to automatically archive DONE trees.
19565 @i{Nicolas Goaziou} rewrote much of the plain list code. He also wrote
19566 @file{org-element.el} and @file{org-export.el}, which was a huge step forward
19567 in implementing a clean framework for Org exporters.
19569 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
19571 @i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a
19574 @i{Bernt Hansen} has driven much of the support for auto-repeating tasks,
19575 task state change logging, and the clocktable. His clear explanations have
19576 been critical when we started to adopt the Git version control system.
19578 @i{Manuel Hermenegildo} has contributed various ideas, small fixes and
19581 @i{Phil Jackson} wrote @file{org-irc.el}.
19583 @i{Scott Jaderholm} proposed footnotes, control over whitespace between
19584 folded entries, and column view for properties.
19586 @i{Matt Jones} wrote @i{MobileOrg Android}.
19588 @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
19590 @i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}.
19592 @i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also
19593 provided frequent feedback and some patches.
19595 @i{Matt Lundin} has proposed last-row references for table formulas and named
19596 invisible anchors. He has also worked a lot on the FAQ.
19598 @i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,
19599 and is a prolific contributor on the mailing list with competent replies,
19600 small fixes and patches.
19602 @i{Jason F. McBrayer} suggested agenda export to CSV format.
19604 @i{Max Mikhanosha} came up with the idea of refiling and sticky agendas.
19606 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file
19609 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
19612 @i{Richard Moreland} wrote MobileOrg for the iPhone.
19614 @i{Rick Moynihan} proposed allowing multiple TODO sequences in a file
19615 and being able to quickly restrict the agenda to a subtree.
19617 @i{Todd Neal} provided patches for links to Info files and Elisp forms.
19619 @i{Greg Newman} refreshed the unicorn logo into its current form.
19621 @i{Tim O'Callaghan} suggested in-file links, search options for general
19622 file links, and TAGS.
19624 @i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text
19625 version of the reference card.
19627 @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
19630 @i{Oliver Oppitz} suggested multi-state TODO items.
19632 @i{Scott Otterson} sparked the introduction of descriptive text for
19633 links, among other things.
19635 @i{Pete Phillips} helped during the development of the TAGS feature, and
19636 provided frequent feedback.
19638 @i{Francesco Pizzolante} provided patches that helped speeding up the agenda
19641 @i{Martin Pohlack} provided the code snippet to bundle character insertion
19642 into bundles of 20 for undo.
19644 @i{Rackspace.com} is hosting our website for free. Thank you Rackspace!
19646 @i{T.V. Raman} reported bugs and suggested improvements.
19648 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
19651 @i{Paul Rivier} provided the basic implementation of named footnotes. He
19652 also acted as mailing list moderator for some time.
19654 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
19656 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
19657 conflict with @file{allout.el}.
19659 @i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with
19662 @i{Philip Rooke} created the Org reference card, provided lots
19663 of feedback, developed and applied standards to the Org documentation.
19665 @i{Christian Schlauer} proposed angular brackets around links, among
19668 @i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can
19669 enjoy folding in non-org buffers by using Org headlines in comments.
19671 @i{Paul Sexton} wrote @file{org-ctags.el}.
19673 Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
19674 @file{organizer-mode.el}.
19676 @i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal
19677 examples, and remote highlighting for referenced code lines.
19679 @i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is
19680 now packaged into Org's @file{contrib} directory.
19682 @i{Daniel Sinder} came up with the idea of internal archiving by locking
19685 @i{Dale Smith} proposed link abbreviations.
19687 @i{James TD Smith} has contributed a large number of patches for useful
19688 tweaks and features.
19690 @i{Adam Spiers} asked for global linking commands, inspired the link
19691 extension system, added support for mairix, and proposed the mapping API.
19693 @i{Ulf Stegemann} created the table to translate special symbols to HTML,
19694 @LaTeX{}, UTF-8, Latin-1 and ASCII.
19696 @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
19697 with links transformation to Org syntax.
19699 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
19700 chapter about publishing.
19702 @i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter.
19704 @i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
19705 enabled source code highlighting in Gnus.
19707 @i{Stefan Vollmar} organized a video-recorded talk at the
19708 Max-Planck-Institute for Neurology. He also inspired the creation of a
19709 concept index for HTML export.
19711 @i{Jürgen Vollmer} contributed code generating the table of contents
19714 @i{Samuel Wales} has provided important feedback and bug reports.
19716 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
19719 @i{David Wainberg} suggested archiving, and improvements to the linking
19722 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
19725 @i{Roland Winkler} requested additional key bindings to make Org
19728 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
19729 and contributed various ideas and code snippets.
19731 @i{Marco Wahl} wrote @file{org-eww.el}.
19735 @node GNU Free Documentation License
19736 @appendix GNU Free Documentation License
19737 @include doclicense.texi
19741 @unnumbered Concept index
19746 @unnumbered Key index
19750 @node Command and Function Index
19751 @unnumbered Command and function index
19755 @node Variable Index
19756 @unnumbered Variable index
19758 This is not a complete index of variables and faces, only the ones that are
19759 mentioned in the manual. For a complete list, use @kbd{M-x org-customize
19766 @c Local variables:
19768 @c indent-tabs-mode: nil
19769 @c paragraph-start: "
\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$"
19770 @c paragraph-separate: "
\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$"
19774 @c LocalWords: webdavhost pre