Fix typos: backport revision r117377 from emacs trunk
[org-mode/org-tableheadings.git] / doc / org.texi
blob8ac9f7399a7c30f92606f034a4a2b52ca8516342
1 \input texinfo
2 @c %**start of header
3 @setfilename ../../info/org
4 @settitle The Org Manual
6 @include org-version.inc
8 @c Version and Contact Info
9 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page}
10 @set AUTHOR Carsten Dominik
11 @set MAINTAINER Carsten Dominik
12 @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
13 @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
14 @documentencoding UTF-8
15 @c %**end of header
16 @finalout
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.
27 @set cmdnames
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
44 @c    Inserts:    @item key
45 @macro orgkey{key}
46 @kindex \key\
47 @item @kbd{\key\}
48 @end macro
50 @macro xorgkey{key}
51 @kindex \key\
52 @itemx @kbd{\key\}
53 @end macro
55 @c one key with a command
56 @c   Inserts:    @item KEY               COMMAND
57 @macro orgcmd{key,command}
58 @ifset cmdnames
59 @kindex \key\
60 @findex \command\
61 @iftex
62 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
63 @end iftex
64 @ifnottex
65 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
66 @end ifnottex
67 @end ifset
68 @ifclear cmdnames
69 @kindex \key\
70 @item @kbd{\key\}
71 @end ifclear
72 @end macro
74 @c One key with one command, formatted using @itemx
75 @c   Inserts:    @itemx KEY               COMMAND
76 @macro xorgcmd{key,command}
77 @ifset cmdnames
78 @kindex \key\
79 @findex \command\
80 @iftex
81 @itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
82 @end iftex
83 @ifnottex
84 @itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
85 @end ifnottex
86 @end ifset
87 @ifclear cmdnames
88 @kindex \key\
89 @itemx @kbd{\key\}
90 @end ifclear
91 @end macro
93 @c one key with a command, bit do not index the key
94 @c   Inserts:    @item KEY               COMMAND
95 @macro orgcmdnki{key,command}
96 @ifset cmdnames
97 @findex \command\
98 @iftex
99 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
100 @end iftex
101 @ifnottex
102 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
103 @end ifnottex
104 @end ifset
105 @ifclear cmdnames
106 @item @kbd{\key\}
107 @end ifclear
108 @end macro
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}
113 @ifset cmdnames
114 @kindex \key\
115 @findex \command\
116 @iftex
117 @item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
118 @end iftex
119 @ifnottex
120 @item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
121 @end ifnottex
122 @end ifset
123 @ifclear cmdnames
124 @kindex \key\
125 @item @kbd{\text\}
126 @end ifclear
127 @end macro
129 @c two keys with one command
130 @c   Inserts:    @item KEY1 or KEY2            COMMAND
131 @macro orgcmdkkc{key1,key2,command}
132 @ifset cmdnames
133 @kindex \key1\
134 @kindex \key2\
135 @findex \command\
136 @iftex
137 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
138 @end iftex
139 @ifnottex
140 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
141 @end ifnottex
142 @end ifset
143 @ifclear cmdnames
144 @kindex \key1\
145 @kindex \key2\
146 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
147 @end ifclear
148 @end macro
150 @c Two keys with one command name, but different functions, so format as
151 @c @itemx
152 @c   Inserts:    @item KEY1
153 @c               @itemx KEY2                COMMAND
154 @macro orgcmdkxkc{key1,key2,command}
155 @ifset cmdnames
156 @kindex \key1\
157 @kindex \key2\
158 @findex \command\
159 @iftex
160 @item @kbd{\key1\}
161 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
162 @end iftex
163 @ifnottex
164 @item @kbd{\key1\}
165 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
166 @end ifnottex
167 @end ifset
168 @ifclear cmdnames
169 @kindex \key1\
170 @kindex \key2\
171 @item @kbd{\key1\}
172 @itemx @kbd{\key2\}
173 @end ifclear
174 @end macro
176 @c Same as previous, but use "or short"
177 @c   Inserts:    @item KEY1 or short KEY2            COMMAND
178 @macro orgcmdkskc{key1,key2,command}
179 @ifset cmdnames
180 @kindex \key1\
181 @kindex \key2\
182 @findex \command\
183 @iftex
184 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
185 @end iftex
186 @ifnottex
187 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
188 @end ifnottex
189 @end ifset
190 @ifclear cmdnames
191 @kindex \key1\
192 @kindex \key2\
193 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
194 @end ifclear
195 @end macro
197 @c Same as previous, but use @itemx
198 @c   Inserts:    @itemx KEY1 or short KEY2            COMMAND
199 @macro xorgcmdkskc{key1,key2,command}
200 @ifset cmdnames
201 @kindex \key1\
202 @kindex \key2\
203 @findex \command\
204 @iftex
205 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
206 @end iftex
207 @ifnottex
208 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
209 @end ifnottex
210 @end ifset
211 @ifclear cmdnames
212 @kindex \key1\
213 @kindex \key2\
214 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
215 @end ifclear
216 @end macro
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}
222 @ifset cmdnames
223 @kindex \key1\
224 @kindex \key2\
225 @findex \command1\
226 @findex \command2\
227 @iftex
228 @item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
229 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
230 @end iftex
231 @ifnottex
232 @item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
233 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
234 @end ifnottex
235 @end ifset
236 @ifclear cmdnames
237 @kindex \key1\
238 @kindex \key2\
239 @item @kbd{\key1\}
240 @itemx @kbd{\key2\}
241 @end ifclear
242 @end macro
243 @c -----------------------------------------------------------------------------
245 @iftex
246 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
247 @end iftex
249 @c Subheadings inside a table.
250 @macro tsubheading{text}
251 @ifinfo
252 @subsubheading \text\
253 @end ifinfo
254 @ifnotinfo
255 @item @b{\text\}
256 @end ifnotinfo
257 @end macro
259 @copying
260 This manual is for Org version @value{VERSION}.
262 Copyright @copyright{} 2004--2014 Free Software Foundation, Inc.
264 @quotation
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.''
274 @end quotation
275 @end copying
277 @dircategory Emacs editing modes
278 @direntry
279 * Org Mode: (org).      Outline-based notes management and organizer
280 @end direntry
282 @titlepage
283 @title The Org Manual
285 @subtitle Release @value{VERSION}
286 @author by Carsten Dominik
287 with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan
288 Davison, Eric Schulte, Thomas Dye, Jambunathan K and Nicolas Goaziou.
290 @c The following two commands start the copyright page.
291 @page
292 @vskip 0pt plus 1filll
293 @insertcopying
294 @end titlepage
296 @c Output the table of contents at the beginning.
297 @contents
299 @ifnottex
300 @c FIXME These hand-written next,prev,up node pointers make editing a lot
301 @c harder.  There should be no need for them, makeinfo can do it
302 @c automatically for any document with a normal structure.
303 @node Top, Introduction, (dir), (dir)
304 @top Org Mode Manual
306 @insertcopying
307 @end ifnottex
309 @menu
310 * Introduction::                Getting started
311 * Document Structure::          A tree works like your brain
312 * Tables::                      Pure magic for quick formatting
313 * Hyperlinks::                  Notes in context
314 * TODO Items::                  Every tree branch can be a TODO item
315 * Tags::                        Tagging headlines and matching sets of tags
316 * Properties and Columns::      Storing information about an entry
317 * Dates and Times::             Making items useful for planning
318 * Capture - Refile - Archive::  The ins and outs for projects
319 * Agenda Views::                Collecting information into views
320 * Markup::                      Prepare text for rich export
321 * Exporting::                   Sharing and publishing notes
322 * Publishing::                  Create a web site of linked Org files
323 * Working With Source Code::    Export, evaluate, and tangle code blocks
324 * Miscellaneous::               All the rest which did not fit elsewhere
325 * Hacking::                     How to hack your way around
326 * MobileOrg::                   Viewing and capture on a mobile device
327 * History and Acknowledgments::  How Org came into being
328 * GNU Free Documentation License::  The license for this documentation.
329 * Main Index::                  An index of Org's concepts and features
330 * Key Index::                   Key bindings and where they are described
331 * Command and Function Index::  Command names and some internal functions
332 * Variable Index::              Variables mentioned in the manual
334 @detailmenu
335  --- The Detailed Node Listing ---
337 Introduction
339 * Summary::                     Brief summary of what Org does
340 * Installation::                Installing Org
341 * Activation::                  How to activate Org for certain buffers
342 * Feedback::                    Bug reports, ideas, patches etc.
343 * Conventions::                 Typesetting conventions in the manual
345 Document structure
347 * Outlines::                    Org is based on Outline mode
348 * Headlines::                   How to typeset Org tree headlines
349 * Visibility cycling::          Show and hide, much simplified
350 * Motion::                      Jumping to other headlines
351 * Structure editing::           Changing sequence and level of headlines
352 * Sparse trees::                Matches embedded in context
353 * Plain lists::                 Additional structure within an entry
354 * Drawers::                     Tucking stuff away
355 * Blocks::                      Folding blocks
356 * Footnotes::                   How footnotes are defined in Org's syntax
357 * Orgstruct mode::              Structure editing outside Org
358 * Org syntax::                  Formal description of Org's syntax
360 Visibility cycling
362 * Global and local cycling::    Cycling through various visibility states
363 * Initial visibility::          Setting the initial visibility state
364 * Catching invisible edits::    Preventing mistakes when editing invisible parts
366 Global and local cycling
368 * Initial visibility::          Setting the initial visibility state
369 * Catching invisible edits::    Preventing mistakes when editing invisible parts
371 Tables
373 * Built-in table editor::       Simple tables
374 * Column width and alignment::  Overrule the automatic settings
375 * Column groups::               Grouping to trigger vertical lines
376 * Orgtbl mode::                 The table editor as minor mode
377 * The spreadsheet::             The table editor has spreadsheet capabilities
378 * Org-Plot::                    Plotting from org tables
380 The spreadsheet
382 * References::                  How to refer to another field or range
383 * Formula syntax for Calc::     Using Calc to compute stuff
384 * Formula syntax for Lisp::     Writing formulas in Emacs Lisp
385 * Durations and time values::   How to compute durations and time values
386 * Field and range formulas::    Formula for specific (ranges of) fields
387 * Column formulas::             Formulas valid for an entire column
388 * Lookup functions::            Lookup functions for searching tables
389 * Editing and debugging formulas::  Fixing formulas
390 * Updating the table::          Recomputing all dependent fields
391 * Advanced features::           Field and column names, parameters and automatic recalc
393 Hyperlinks
395 * Link format::                 How links in Org are formatted
396 * Internal links::              Links to other places in the current file
397 * External links::              URL-like links to the world
398 * Handling links::              Creating, inserting and following
399 * Using links outside Org::     Linking from my C source code?
400 * Link abbreviations::          Shortcuts for writing complex links
401 * Search options::              Linking to a specific location
402 * Custom searches::             When the default search is not enough
404 Internal links
406 * Radio targets::               Make targets trigger links in plain text
408 TODO items
410 * TODO basics::                 Marking and displaying TODO entries
411 * TODO extensions::             Workflow and assignments
412 * Progress logging::            Dates and notes for progress
413 * Priorities::                  Some things are more important than others
414 * Breaking down tasks::         Splitting a task into manageable pieces
415 * Checkboxes::                  Tick-off lists
417 Extended use of TODO keywords
419 * Workflow states::             From TODO to DONE in steps
420 * TODO types::                  I do this, Fred does the rest
421 * Multiple sets in one file::   Mixing it all, and still finding your way
422 * Fast access to TODO states::  Single letter selection of a state
423 * Per-file keywords::           Different files, different requirements
424 * Faces for TODO keywords::     Highlighting states
425 * TODO dependencies::           When one task needs to wait for others
427 Progress logging
429 * Closing items::               When was this entry marked DONE?
430 * Tracking TODO state changes::  When did the status change?
431 * Tracking your habits::        How consistent have you been?
433 Tags
435 * Tag inheritance::             Tags use the tree structure of the outline
436 * Setting tags::                How to assign tags to a headline
437 * Tag groups::                  Use one tag to search for several tags
438 * Tag searches::                Searching for combinations of tags
440 Properties and columns
442 * Property syntax::             How properties are spelled out
443 * Special properties::          Access to other Org mode features
444 * Property searches::           Matching property values
445 * Property inheritance::        Passing values down the tree
446 * Column view::                 Tabular viewing and editing
447 * Property API::                Properties for Lisp programmers
449 Column view
451 * Defining columns::            The COLUMNS format property
452 * Using column view::           How to create and use column view
453 * Capturing column view::       A dynamic block for column view
455 Defining columns
457 * Scope of column definitions::  Where defined, where valid?
458 * Column attributes::           Appearance and content of a column
460 Dates and times
462 * Timestamps::                  Assigning a time to a tree entry
463 * Creating timestamps::         Commands which insert timestamps
464 * Deadlines and scheduling::    Planning your work
465 * Clocking work time::          Tracking how long you spend on a task
466 * Effort estimates::            Planning work effort in advance
467 * Relative timer::              Notes with a running timer
468 * Countdown timer::             Starting a countdown timer for a task
470 Creating timestamps
472 * The date/time prompt::        How Org mode helps you entering date and time
473 * Custom time format::          Making dates look different
475 Deadlines and scheduling
477 * Inserting deadline/schedule::  Planning items
478 * Repeated tasks::              Items that show up again and again
480 Clocking work time
482 * Clocking commands::           Starting and stopping a clock
483 * The clock table::             Detailed reports
484 * Resolving idle time::         Resolving time when you've been idle
486 Capture - Refile - Archive
488 * Capture::                     Capturing new stuff
489 * Attachments::                 Add files to tasks
490 * RSS Feeds::                   Getting input from RSS feeds
491 * Protocols::                   External (e.g., Browser) access to Emacs and Org
492 * Refile and copy::             Moving/copying a tree from one place to another
493 * Archiving::                   What to do with finished projects
495 Capture
497 * Setting up capture::          Where notes will be stored
498 * Using capture::               Commands to invoke and terminate capture
499 * Capture templates::           Define the outline of different note types
501 Capture templates
503 * Template elements::           What is needed for a complete template entry
504 * Template expansion::          Filling in information about time and context
505 * Templates in contexts::       Only show a template in a specific context
507 Archiving
509 * Moving subtrees::             Moving a tree to an archive file
510 * Internal archiving::          Switch off a tree but keep it in the file
512 Agenda views
514 * Agenda files::                Files being searched for agenda information
515 * Agenda dispatcher::           Keyboard access to agenda views
516 * Built-in agenda views::       What is available out of the box?
517 * Presentation and sorting::    How agenda items are prepared for display
518 * Agenda commands::             Remote editing of Org trees
519 * Custom agenda views::         Defining special searches and views
520 * Exporting Agenda Views::      Writing a view to a file
521 * Agenda column view::          Using column view for collected entries
523 The built-in agenda views
525 * Weekly/daily agenda::         The calendar page with current tasks
526 * Global TODO list::            All unfinished action items
527 * Matching tags and properties::  Structured information with fine-tuned search
528 * Timeline::                    Time-sorted view for single file
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
539 Custom agenda views
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 * Structural markup elements::  The basic structure as seen by the exporter
548 * Images and tables::           Images, tables and caption mechanism
549 * Literal examples::            Source code examples with special formatting
550 * Include files::               Include additional files into a document
551 * Index entries::               Making an index
552 * Macro replacement::           Use macros to create templates
553 * Embedded @LaTeX{}::           LaTeX can be freely used inside Org documents
554 * Special blocks::              Containers targeted at export back-ends
556 Structural markup elements
558 * Document title::              Where the title is taken from
559 * Headings and sections::       The document structure as seen by the exporter
560 * Table of contents::           The if and where of the table of contents
561 * Lists::                       Lists
562 * Paragraphs::                  Paragraphs
563 * Footnote markup::             Footnotes
564 * Emphasis and monospace::      Bold, italic, etc.
565 * Horizontal rules::            Make a line
566 * Comment lines::               What will *not* be exported
568 Embedded @LaTeX{}
570 * Special symbols::             Greek letters and other symbols
571 * Subscripts and superscripts::  Simple syntax for raising/lowering text
572 * @LaTeX{} fragments::          Complex formulas made easy
573 * Previewing @LaTeX{} fragments::  What will this snippet look like?
574 * CDLaTeX mode::                Speed up entering of formulas
576 Exporting
578 * The Export Dispatcher::       The main exporter interface
579 * Export back-ends::            Built-in export formats
580 * Export settings::             Generic export settings
581 * ASCII/Latin-1/UTF-8 export::  Exporting to flat files with encoding
582 * Beamer export::               Exporting as a Beamer presentation
583 * HTML export::                 Exporting to HTML
584 * @LaTeX{} and PDF export::     Exporting to @LaTeX{}, and processing to PDF
585 * Markdown export::             Exporting to Markdown
586 * OpenDocument Text export::    Exporting to OpenDocument Text
587 * Org export::                  Exporting to Org
588 * iCalendar export::            Exporting to iCalendar
589 * Other built-in back-ends::    Exporting to @code{Texinfo} or a man page
590 * Export in foreign buffers::   Author tables and lists in Org syntax
591 * Advanced configuration::      Fine-tuning the export output
593 HTML export
595 * HTML Export commands::        How to invoke HTML export
596 * HTML doctypes::               Org can export to various (X)HTML flavors
597 * HTML preamble and postamble::  How to insert a preamble and a postamble
598 * Quoting HTML tags::           Using direct HTML in Org mode
599 * Links in HTML export::        How links will be interpreted and formatted
600 * Tables in HTML export::       How to modify the formatting of tables
601 * Images in HTML export::       How to insert figures into HTML output
602 * Math formatting in HTML export::  Beautiful math also on the web
603 * Text areas in HTML export::   An alternative way to show an example
604 * CSS support::                 Changing the appearance of the output
605 * JavaScript support::          Info and Folding in a web browser
607 @LaTeX{} and PDF export
609 * @LaTeX{} export commands::    How to export to LaTeX and PDF
610 * Header and sectioning::       Setting up the export file structure
611 * Quoting @LaTeX{} code::       Incorporating literal @LaTeX{} code
612 * @LaTeX{} specific attributes::  Controlling @LaTeX{} output
614 OpenDocument Text export
616 * Pre-requisites for ODT export::  What packages ODT exporter relies on
617 * ODT export commands::         How to invoke ODT export
618 * Extending ODT export::        How to produce @samp{doc}, @samp{pdf} files
619 * Applying custom styles::      How to apply custom styles to the output
620 * Links in ODT export::         How links will be interpreted and formatted
621 * Tables in ODT export::        How Tables are exported
622 * Images in ODT export::        How to insert images
623 * Math formatting in ODT export::  How @LaTeX{} fragments are formatted
624 * Labels and captions in ODT export::  How captions are rendered
625 * Literal examples in ODT export::  How source and example blocks are formatted
626 * Advanced topics in ODT export::  Read this if you are a power user
628 Math formatting in ODT export
630 * Working with @LaTeX{} math snippets::  How to embed @LaTeX{} math fragments
631 * Working with MathML or OpenDocument formula files::  How to embed equations in native format
633 Advanced topics in ODT export
635 * Configuring a document converter::  How to register a document converter
636 * Working with OpenDocument style files::  Explore the internals
637 * Creating one-off styles::     How to produce custom highlighting etc
638 * Customizing tables in ODT export::  How to define and use Table templates
639 * Validating OpenDocument XML::  How to debug corrupt OpenDocument files
641 Publishing
643 * Configuration::               Defining projects
644 * Uploading files::             How to get files up on the server
645 * Sample configuration::        Example projects
646 * Triggering publication::      Publication commands
648 Configuration
650 * Project alist::               The central configuration variable
651 * Sources and destinations::    From here to there
652 * Selecting files::             What files are part of the project?
653 * Publishing action::           Setting the function doing the publishing
654 * Publishing options::          Tweaking HTML/@LaTeX{} export
655 * Publishing links::            Which links keep working after publishing?
656 * Sitemap::                     Generating a list of all pages
657 * Generating an index::         An index that reaches across pages
659 Sample configuration
661 * Simple example::              One-component publishing
662 * Complex example::             A multi-component publishing example
664 Working with source code
666 * Structure of code blocks::    Code block syntax described
667 * Editing source code::         Language major-mode editing
668 * Exporting code blocks::       Export contents and/or results
669 * Extracting source code::      Create pure source code files
670 * Evaluating code blocks::      Place results of evaluation in the Org mode buffer
671 * Library of Babel::            Use and contribute to a library of useful code blocks
672 * Languages::                   List of supported code block languages
673 * Header arguments::            Configure code block functionality
674 * Results of evaluation::       How evaluation results are handled
675 * Noweb reference syntax::      Literate programming in Org mode
676 * Key bindings and useful functions::  Work quickly with code blocks
677 * Batch execution::             Call functions from the command line
679 Header arguments
681 * Using header arguments::      Different ways to set header arguments
682 * Specific header arguments::   List of header arguments
684 Using header arguments
686 * System-wide header arguments::  Set global default values
687 * Language-specific header arguments::  Set default values by language
688 * Header arguments in Org mode properties::  Set default values for a buffer or heading
689 * Language-specific header arguments in Org mode properties::  Set language-specific default values for a buffer or heading
690 * Code block specific header arguments::  The most common way to set values
691 * Header arguments in function calls::  The most specific level
693 Specific header arguments
695 * var::                         Pass arguments to code blocks
696 * results::                     Specify the type of results and how they will
697                                 be collected and handled
698 * file::                        Specify a path for file output
699 * file-desc::                   Specify a description for file results
700 * dir::                         Specify the default (possibly remote)
701                                 directory for code block execution
702 * exports::                     Export code and/or results
703 * tangle::                      Toggle tangling and specify file name
704 * mkdirp::                      Toggle creation of parent directories of target
705                                 files during tangling
706 * comments::                    Toggle insertion of comments in tangled
707                                 code files
708 * padline::                     Control insertion of padding lines in tangled
709                                 code files
710 * no-expand::                   Turn off variable assignment and noweb
711                                 expansion during tangling
712 * session::                     Preserve the state of code evaluation
713 * noweb::                       Toggle expansion of noweb references
714 * noweb-ref::                   Specify block's noweb reference resolution target
715 * noweb-sep::                   String used to separate noweb references
716 * cache::                       Avoid re-evaluating unchanged code blocks
717 * sep::                         Delimiter for writing tabular results outside Org
718 * hlines::                      Handle horizontal lines in tables
719 * colnames::                    Handle column names in tables
720 * rownames::                    Handle row names in tables
721 * shebang::                     Make tangled files executable
722 * tangle-mode::                 Set permission of tangled files
723 * eval::                        Limit evaluation of specific code blocks
724 * wrap::                        Mark source block evaluation results
725 * post::                        Post processing of code block results
726 * prologue::                    Text to prepend to code block body
727 * epilogue::                    Text to append to code block body
729 Miscellaneous
731 * Completion::                  M-TAB knows what you need
732 * Easy Templates::              Quick insertion of structural elements
733 * Speed keys::                  Electric commands at the beginning of a headline
734 * Code evaluation security::    Org mode files evaluate inline code
735 * Customization::               Adapting Org to your taste
736 * In-buffer settings::          Overview of the #+KEYWORDS
737 * The very busy C-c C-c key::   When in doubt, press C-c C-c
738 * Clean view::                  Getting rid of leading stars in the outline
739 * TTY keys::                    Using Org on a tty
740 * Interaction::                 Other Emacs packages
741 * org-crypt::                   Encrypting Org files
743 Interaction with other packages
745 * Cooperation::                 Packages Org cooperates with
746 * Conflicts::                   Packages that lead to conflicts
748 Hacking
750 * Hooks::                       How to reach into Org's internals
751 * Add-on packages::             Available extensions
752 * Adding hyperlink types::      New custom link types
753 * Adding export back-ends::     How to write new export back-ends
754 * Context-sensitive commands::  How to add functionality to such commands
755 * Tables in arbitrary syntax::  Orgtbl for @LaTeX{} and other programs
756 * Dynamic blocks::              Automatically filled blocks
757 * Special agenda views::        Customized views
758 * Speeding up your agendas::    Tips on how to speed up your agendas
759 * Extracting agenda information::  Post-processing of agenda information
760 * Using the property API::      Writing programs that use entry properties
761 * Using the mapping API::       Mapping over all or selected entries
763 Tables and lists in arbitrary syntax
765 * Radio tables::                Sending and receiving radio tables
766 * A @LaTeX{} example::          Step by step, almost a tutorial
767 * Translator functions::        Copy and modify
768 * Radio lists::                 Sending and receiving lists
770 MobileOrg
772 * Setting up the staging area::  Where to interact with the mobile device
773 * Pushing to MobileOrg::        Uploading Org files and agendas
774 * Pulling from MobileOrg::      Integrating captured and flagged items
776 @end detailmenu
777 @end menu
779 @node Introduction, Document Structure, Top, Top
780 @chapter Introduction
781 @cindex introduction
783 @menu
784 * Summary::                     Brief summary of what Org does
785 * Installation::                Installing Org
786 * Activation::                  How to activate Org for certain buffers
787 * Feedback::                    Bug reports, ideas, patches etc.
788 * Conventions::                 Typesetting conventions in the manual
789 @end menu
791 @node Summary, Installation, Introduction, Introduction
792 @section Summary
793 @cindex summary
795 Org is a mode for keeping notes, maintaining TODO lists, and doing
796 project planning with a fast and effective plain-text system.
798 Org develops organizational tasks around NOTES files that contain
799 lists or information about projects as plain text.  Org is
800 implemented on top of Outline mode, which makes it possible to keep the
801 content of large files well structured.  Visibility cycling and
802 structure editing help to work with the tree.  Tables are easily created
803 with a built-in table editor.  Org supports TODO items, deadlines,
804 timestamps, and scheduling.  It dynamically compiles entries into an
805 agenda that utilizes and smoothly integrates much of the Emacs calendar
806 and diary.  Plain text URL-like links connect to websites, emails,
807 Usenet messages, BBDB entries, and any files related to the projects.
808 For printing and sharing notes, an Org file can be exported as a
809 structured ASCII file, as HTML, or (TODO and agenda items only) as an
810 iCalendar file.  It can also serve as a publishing tool for a set of
811 linked web pages.
813 As a project planning environment, Org works by adding metadata to outline
814 nodes.  Based on this data, specific entries can be extracted in queries and
815 create dynamic @i{agenda views}.
817 Org mode contains the Org Babel environment which allows you to work with
818 embedded source code blocks in a file, to facilitate code evaluation,
819 documentation, and literate programming techniques.
821 Org's automatic, context-sensitive table editor with spreadsheet
822 capabilities can be integrated into any major mode by activating the
823 minor Orgtbl mode.  Using a translation step, it can be used to maintain
824 tables in arbitrary file types, for example in @LaTeX{}.  The structure
825 editing and list creation capabilities can be used outside Org with
826 the minor Orgstruct mode.
828 Org keeps simple things simple.  When first fired up, it should
829 feel like a straightforward, easy to use outliner.  Complexity is not
830 imposed, but a large amount of functionality is available when you need
831 it.  Org is a toolbox and can be used in different ways and for different
832 ends, for example:
834 @example
835 @r{@bullet{} an outline extension with visibility cycling and structure editing}
836 @r{@bullet{} an ASCII system and table editor for taking structured notes}
837 @r{@bullet{} a TODO list editor}
838 @r{@bullet{} a full agenda and planner with deadlines and work scheduling}
839 @pindex GTD, Getting Things Done
840 @r{@bullet{} an environment in which to implement David Allen's GTD system}
841 @r{@bullet{} a simple hypertext system, with HTML and @LaTeX{} export}
842 @r{@bullet{} a publishing tool to create a set of interlinked web pages}
843 @r{@bullet{} an environment for literate programming}
844 @end example
846 @cindex FAQ
847 There is a website for Org which provides links to the newest
848 version of Org, as well as additional information, frequently asked
849 questions (FAQ), links to tutorials, etc.  This page is located at
850 @uref{http://orgmode.org}.
852 @cindex print edition
853 The version 7.3 of this manual is available as a
854 @uref{http://www.network-theory.co.uk/org/manual/, paperback book from Network
855 Theory Ltd.}
857 @page
860 @node Installation, Activation, Summary, Introduction
861 @section Installation
862 @cindex installation
863 @cindex XEmacs
865 Org is part of recent distributions of GNU Emacs, so you normally don't need
866 to install it.  If, for one reason or another, you want to install Org on top
867 of this pre-packaged version, there are three ways to do it:
869 @itemize @bullet
870 @item By using Emacs package system.
871 @item By downloading Org as an archive.
872 @item By using Org's git repository.
873 @end itemize
875 We @b{strongly recommend} to stick to a single installation method.
877 @subsubheading Using Emacs packaging system
879 Recent Emacs distributions include a packaging system which lets you install
880 Elisp libraries.  You can install Org with @kbd{M-x package-install RET org}.
882 @noindent @b{Important}: you need to do this in a session where no @code{.org} file has
883 been visited, i.e. where no Org built-in function have been loaded.
884 Otherwise autoload Org functions will mess up the installation.
886 Then, to make sure your Org configuration is taken into account, initialize
887 the package system with @code{(package-initialize)} in your @file{.emacs}
888 before setting any Org option.  If you want to use Org's package repository,
889 check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
891 @subsubheading Downloading Org as an archive
893 You can download Org latest release from @uref{http://orgmode.org/, Org's
894 website}.  In this case, make sure you set the load-path correctly in your
895 @file{.emacs}:
897 @lisp
898 (add-to-list 'load-path "~/path/to/orgdir/lisp")
899 @end lisp
901 The downloaded archive contains contributed libraries that are not included
902 in Emacs.  If you want to use them, add the @file{contrib} directory to your
903 load-path:
905 @lisp
906 (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
907 @end lisp
909 Optionally, you can compile the files and/or install them in your system.
910 Run @code{make help} to list compilation and installation options.
912 @subsubheading Using Org's git repository
914 You can clone Org's repository and install Org like this:
916 @example
917 $ cd ~/src/
918 $ git clone git://orgmode.org/org-mode.git
919 $ make autoloads
920 @end example
922 Note that in this case, @code{make autoloads} is mandatory: it defines Org's
923 version in @file{org-version.el} and Org's autoloads in
924 @file{org-loaddefs.el}.
926 Remember to add the correct load-path as described in the method above.
928 You can also compile with @code{make}, generate the documentation with
929 @code{make doc}, create a local configuration with @code{make config} and
930 install Org with @code{make install}.  Please run @code{make help} to get
931 the list of compilation/installation options.
933 For more detailed explanations on Org's build system, please check the Org
934 Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
935 Worg}.
937 @node Activation, Feedback, Installation, Introduction
938 @section Activation
939 @cindex activation
940 @cindex autoload
941 @cindex ELPA
942 @cindex global key bindings
943 @cindex key bindings, global
944 @findex org-agenda
945 @findex org-capture
946 @findex org-store-link
947 @findex org-iswitchb
949 Since Emacs 22.2, files with the @file{.org} extension use Org mode by
950 default.  If you are using an earlier version of Emacs, add this line to your
951 @file{.emacs} file:
953 @lisp
954 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
955 @end lisp
957 Org mode buffers need font-lock to be turned on: this is the default in
958 Emacs@footnote{If you don't use font-lock globally, turn it on in Org buffer
959 with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
961 There are compatibility issues between Org mode and some other Elisp
962 packages, please take the time to check the list (@pxref{Conflicts}).
964 The four Org commands @command{org-store-link}, @command{org-capture},
965 @command{org-agenda}, and @command{org-iswitchb} should be accessible through
966 global keys (i.e., anywhere in Emacs, not just in Org buffers).  Here are
967 suggested bindings for these keys, please modify the keys to your own
968 liking.
969 @lisp
970 (global-set-key "\C-cl" 'org-store-link)
971 (global-set-key "\C-cc" 'org-capture)
972 (global-set-key "\C-ca" 'org-agenda)
973 (global-set-key "\C-cb" 'org-iswitchb)
974 @end lisp
976 @cindex Org mode, turning on
977 With this setup, all files with extension @samp{.org} will be put
978 into Org mode.  As an alternative, make the first line of a file look
979 like this:
981 @example
982 MY PROJECTS    -*- mode: org; -*-
983 @end example
985 @vindex org-insert-mode-line-in-empty-file
986 @noindent which will select Org mode for this buffer no matter what
987 the file's name is.  See also the variable
988 @code{org-insert-mode-line-in-empty-file}.
990 Many commands in Org work on the region if the region is @i{active}.  To make
991 use of this, you need to have @code{transient-mark-mode}
992 (@code{zmacs-regions} in XEmacs) turned on.  In Emacs 23 this is the default,
993 in Emacs 22 you need to do this yourself with
994 @lisp
995 (transient-mark-mode 1)
996 @end lisp
997 @noindent If you do not like @code{transient-mark-mode}, you can create an
998 active region by using the mouse to select a region, or pressing
999 @kbd{C-@key{SPC}} twice before moving the cursor.
1001 @node Feedback, Conventions, Activation, Introduction
1002 @section Feedback
1003 @cindex feedback
1004 @cindex bug reports
1005 @cindex maintainer
1006 @cindex author
1008 If you find problems with Org, or if you have questions, remarks, or ideas
1009 about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
1010 If you are not a member of the mailing list, your mail will be passed to the
1011 list after a moderator has approved it@footnote{Please consider subscribing
1012 to the mailing list, in order to minimize the work the mailing list
1013 moderators have to do.}.
1015 For bug reports, please first try to reproduce the bug with the latest
1016 version of Org available---if you are running an outdated version, it is
1017 quite possible that the bug has been fixed already.  If the bug persists,
1018 prepare a report and provide as much information as possible, including the
1019 version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
1020 (@kbd{M-x org-version RET}), as well as the Org related setup in
1021 @file{.emacs}.  The easiest way to do this is to use the command
1022 @example
1023 @kbd{M-x org-submit-bug-report RET}
1024 @end example
1025 @noindent which will put all this information into an Emacs mail buffer so
1026 that you only need to add your description.  If you re not sending the Email
1027 from within Emacs, please copy and paste the content into your Email program.
1029 Sometimes you might face a problem due to an error in your Emacs or Org mode
1030 setup.  Before reporting a bug, it is very helpful to start Emacs with minimal
1031 customizations and reproduce the problem.  Doing so often helps you determine
1032 if the problem is with your customization or with Org mode itself.  You can
1033 start a typical minimal session with a command like the example below.
1035 @example
1036 $ emacs -Q -l /path/to/minimal-org.el
1037 @end example
1039 However if you are using Org mode as distributed with Emacs, a minimal setup
1040 is not necessary.  In that case it is sufficient to start Emacs as
1041 @code{emacs -Q}.  The @code{minimal-org.el} setup file can have contents as
1042 shown below.
1044 @lisp
1045 ;;; Minimal setup to load latest `org-mode'
1047 ;; activate debugging
1048 (setq debug-on-error t
1049       debug-on-signal nil
1050       debug-on-quit nil)
1052 ;; add latest org-mode to load path
1053 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
1054 (add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
1055 @end lisp
1057 If an error occurs, a backtrace can be very useful (see below on how to
1058 create one).  Often a small example file helps, along with clear information
1059 about:
1061 @enumerate
1062 @item What exactly did you do?
1063 @item What did you expect to happen?
1064 @item What happened instead?
1065 @end enumerate
1066 @noindent Thank you for helping to improve this program.
1068 @subsubheading How to create a useful backtrace
1070 @cindex backtrace of an error
1071 If working with Org produces an error with a message you don't
1072 understand, you may have hit a bug.  The best way to report this is by
1073 providing, in addition to what was mentioned above, a @emph{backtrace}.
1074 This is information from the built-in debugger about where and how the
1075 error occurred.  Here is how to produce a useful backtrace:
1077 @enumerate
1078 @item
1079 Reload uncompiled versions of all Org mode Lisp files.  The backtrace
1080 contains much more information if it is produced with uncompiled code.
1081 To do this, use
1082 @example
1083 @kbd{C-u M-x org-reload RET}
1084 @end example
1085 @noindent
1086 or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
1087 menu.
1088 @item
1089 Go to the @code{Options} menu and select @code{Enter Debugger on Error}
1090 (XEmacs has this option in the @code{Troubleshooting} sub-menu).
1091 @item
1092 Do whatever you have to do to hit the error.  Don't forget to
1093 document the steps you take.
1094 @item
1095 When you hit the error, a @file{*Backtrace*} buffer will appear on the
1096 screen.  Save this buffer to a file (for example using @kbd{C-x C-w}) and
1097 attach it to your bug report.
1098 @end enumerate
1100 @node Conventions,  , Feedback, Introduction
1101 @section Typesetting conventions used in this manual
1103 @subsubheading TODO keywords, tags, properties, etc.
1105 Org mainly uses three types of keywords: TODO keywords, tags and property
1106 names.  In this manual we use the following conventions:
1108 @table @code
1109 @item TODO
1110 @itemx WAITING
1111 TODO keywords are written with all capitals, even if they are
1112 user-defined.
1113 @item boss
1114 @itemx ARCHIVE
1115 User-defined tags are written in lowercase; built-in tags with special
1116 meaning are written with all capitals.
1117 @item Release
1118 @itemx PRIORITY
1119 User-defined properties are capitalized; built-in properties with
1120 special meaning are written with all capitals.
1121 @end table
1123 Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
1124 and @i{environment keywords} (like @code{#+BEGIN_HTML} to start a @code{HTML}
1125 environment).  They are written in uppercase in the manual to enhance its
1126 readability, but you can use lowercase in your Org files@footnote{Easy
1127 templates insert lowercase keywords and Babel dynamically inserts
1128 @code{#+results}.}.
1130 @subsubheading Keybindings and commands
1131 @kindex C-c a
1132 @findex org-agenda
1133 @kindex C-c c
1134 @findex org-capture
1136 The manual suggests two global keybindings: @kbd{C-c a} for @code{org-agenda}
1137 and @kbd{C-c c} for @code{org-capture}.  These are only suggestions, but the
1138 rest of the manual assumes that you are using these keybindings.
1140 Also, the manual lists both the keys and the corresponding commands for
1141 accessing a functionality.  Org mode often uses the same key for different
1142 functions, depending on context.  The command that is bound to such keys has
1143 a generic name, like @code{org-metaright}.  In the manual we will, wherever
1144 possible, give the function that is internally called by the generic command.
1145 For example, in the chapter on document structure, @kbd{M-@key{right}} will
1146 be listed to call @code{org-do-demote}, while in the chapter on tables, it
1147 will be listed to call @code{org-table-move-column-right}.  If you prefer,
1148 you can compile the manual without the command names by unsetting the flag
1149 @code{cmdnames} in @file{org.texi}.
1151 @node Document Structure, Tables, Introduction, Top
1152 @chapter Document structure
1153 @cindex document structure
1154 @cindex structure of document
1156 Org is based on Outline mode and provides flexible commands to
1157 edit the structure of the document.
1159 @menu
1160 * Outlines::                    Org is based on Outline mode
1161 * Headlines::                   How to typeset Org tree headlines
1162 * Visibility cycling::          Show and hide, much simplified
1163 * Motion::                      Jumping to other headlines
1164 * Structure editing::           Changing sequence and level of headlines
1165 * Sparse trees::                Matches embedded in context
1166 * Plain lists::                 Additional structure within an entry
1167 * Drawers::                     Tucking stuff away
1168 * Blocks::                      Folding blocks
1169 * Footnotes::                   How footnotes are defined in Org's syntax
1170 * Orgstruct mode::              Structure editing outside Org
1171 * Org syntax::                  Formal description of Org's syntax
1172 @end menu
1174 @node Outlines, Headlines, Document Structure, Document Structure
1175 @section Outlines
1176 @cindex outlines
1177 @cindex Outline mode
1179 Org is implemented on top of Outline mode.  Outlines allow a
1180 document to be organized in a hierarchical structure, which (at least
1181 for me) is the best representation of notes and thoughts.  An overview
1182 of this structure is achieved by folding (hiding) large parts of the
1183 document to show only the general document structure and the parts
1184 currently being worked on.  Org greatly simplifies the use of
1185 outlines by compressing the entire show/hide functionality into a single
1186 command, @command{org-cycle}, which is bound to the @key{TAB} key.
1188 @node Headlines, Visibility cycling, Outlines, Document Structure
1189 @section Headlines
1190 @cindex headlines
1191 @cindex outline tree
1192 @vindex org-special-ctrl-a/e
1193 @vindex org-special-ctrl-k
1194 @vindex org-ctrl-k-protect-subtree
1196 Headlines define the structure of an outline tree.  The headlines in Org
1197 start with one or more stars, on the left margin@footnote{See the variables
1198 @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
1199 @code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
1200 @kbd{C-e}, and @kbd{C-k} in headlines.} @footnote{Clocking only works with
1201 headings indented less then 30 stars.}.  For example:
1203 @example
1204 * Top level headline
1205 ** Second level
1206 *** 3rd level
1207     some text
1208 *** 3rd level
1209     more text
1211 * Another top level headline
1212 @end example
1214 @noindent Some people find the many stars too noisy and would prefer an
1215 outline that has whitespace followed by a single star as headline
1216 starters.  @ref{Clean view}, describes a setup to realize this.
1218 @vindex org-cycle-separator-lines
1219 An empty line after the end of a subtree is considered part of it and
1220 will be hidden when the subtree is folded.  However, if you leave at
1221 least two empty lines, one empty line will remain visible after folding
1222 the subtree, in order to structure the collapsed view.  See the
1223 variable @code{org-cycle-separator-lines} to modify this behavior.
1225 @node Visibility cycling, Motion, Headlines, Document Structure
1226 @section Visibility cycling
1227 @cindex cycling, visibility
1228 @cindex visibility cycling
1229 @cindex trees, visibility
1230 @cindex show hidden text
1231 @cindex hide text
1233 @menu
1234 * Global and local cycling::    Cycling through various visibility states
1235 * Initial visibility::          Setting the initial visibility state
1236 * Catching invisible edits::    Preventing mistakes when editing invisible parts
1237 @end menu
1239 @node Global and local cycling, Initial visibility, Visibility cycling, Visibility cycling
1240 @subsection Global and local cycling
1242 Outlines make it possible to hide parts of the text in the buffer.
1243 Org uses just two commands, bound to @key{TAB} and
1244 @kbd{S-@key{TAB}} to change the visibility in the buffer.
1246 @cindex subtree visibility states
1247 @cindex subtree cycling
1248 @cindex folded, subtree visibility state
1249 @cindex children, subtree visibility state
1250 @cindex subtree, subtree visibility state
1251 @table @asis
1252 @orgcmd{@key{TAB},org-cycle}
1253 @emph{Subtree cycling}: Rotate current subtree among the states
1255 @example
1256 ,-> FOLDED -> CHILDREN -> SUBTREE --.
1257 '-----------------------------------'
1258 @end example
1260 @vindex org-cycle-emulate-tab
1261 @vindex org-cycle-global-at-bob
1262 The cursor must be on a headline for this to work@footnote{see, however,
1263 the option @code{org-cycle-emulate-tab}.}.  When the cursor is at the
1264 beginning of the buffer and the first line is not a headline, then
1265 @key{TAB} actually runs global cycling (see below)@footnote{see the
1266 option @code{org-cycle-global-at-bob}.}.  Also when called with a prefix
1267 argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
1269 @cindex global visibility states
1270 @cindex global cycling
1271 @cindex overview, global visibility state
1272 @cindex contents, global visibility state
1273 @cindex show all, global visibility state
1274 @orgcmd{S-@key{TAB},org-global-cycle}
1275 @itemx C-u @key{TAB}
1276 @emph{Global cycling}: Rotate the entire buffer among the states
1278 @example
1279 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
1280 '--------------------------------------'
1281 @end example
1283 When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the
1284 CONTENTS view up to headlines of level N will be shown.  Note that inside
1285 tables, @kbd{S-@key{TAB}} jumps to the previous field.
1287 @cindex set startup visibility, command
1288 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1289 Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
1290 @cindex show all, command
1291 @orgcmd{C-u C-u C-u @key{TAB},show-all}
1292 Show all, including drawers.
1293 @cindex revealing context
1294 @orgcmd{C-c C-r,org-reveal}
1295 Reveal context around point, showing the current entry, the following heading
1296 and the hierarchy above.  Useful for working near a location that has been
1297 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
1298 (@pxref{Agenda commands}).  With a prefix argument show, on each
1299 level, all sibling headings.  With a double prefix argument, also show the
1300 entire subtree of the parent.
1301 @cindex show branches, command
1302 @orgcmd{C-c C-k,show-branches}
1303 Expose all the headings of the subtree, CONTENT view for just one subtree.
1304 @cindex show children, command
1305 @orgcmd{C-c @key{TAB},show-children}
1306 Expose all direct children of the subtree.  With a numeric prefix argument N,
1307 expose all children down to level N@.
1308 @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
1309 Show the current subtree in an indirect buffer@footnote{The indirect
1310 buffer
1311 @ifinfo
1312 (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual})
1313 @end ifinfo
1314 @ifnotinfo
1315 (see the Emacs manual for more information about indirect buffers)
1316 @end ifnotinfo
1317 will contain the entire buffer, but will be narrowed to the current
1318 tree.  Editing the indirect buffer will also change the original buffer,
1319 but without affecting visibility in that buffer.}.  With a numeric
1320 prefix argument N, go up to level N and then take that tree.  If N is
1321 negative then go up that many levels.  With a @kbd{C-u} prefix, do not remove
1322 the previously used indirect buffer.
1323 @orgcmd{C-c C-x v,org-copy-visible}
1324 Copy the @i{visible} text in the region into the kill ring.
1325 @end table
1327 @menu
1328 * Initial visibility::          Setting the initial visibility state
1329 * Catching invisible edits::    Preventing mistakes when editing invisible parts
1330 @end menu
1332 @node Initial visibility, Catching invisible edits, Global and local cycling, Visibility cycling
1333 @subsection Initial visibility
1335 @cindex visibility, initialize
1336 @vindex org-startup-folded
1337 @vindex org-agenda-inhibit-startup
1338 @cindex @code{overview}, STARTUP keyword
1339 @cindex @code{content}, STARTUP keyword
1340 @cindex @code{showall}, STARTUP keyword
1341 @cindex @code{showeverything}, STARTUP keyword
1343 When Emacs first visits an Org file, the global state is set to OVERVIEW,
1344 i.e., only the top level headlines are visible@footnote{When
1345 @code{org-agenda-inhibit-startup} is non-@code{nil}, Org will not honor the default
1346 visibility state when first opening a file for the agenda (@pxref{Speeding up
1347 your agendas}).}.  This can be configured through the variable
1348 @code{org-startup-folded}, or on a per-file basis by adding one of the
1349 following lines anywhere in the buffer:
1351 @example
1352 #+STARTUP: overview
1353 #+STARTUP: content
1354 #+STARTUP: showall
1355 #+STARTUP: showeverything
1356 @end example
1358 The startup visibility options are ignored when the file is open for the
1359 first time during the agenda generation: if you want the agenda to honor
1360 the startup visibility, set @code{org-agenda-inhibit-startup} to @code{nil}.
1362 @cindex property, VISIBILITY
1363 @noindent
1364 Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
1365 and Columns}) will get their visibility adapted accordingly.  Allowed values
1366 for this property are @code{folded}, @code{children}, @code{content}, and
1367 @code{all}.
1369 @table @asis
1370 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1371 Switch back to the startup visibility of the buffer, i.e., whatever is
1372 requested by startup options and @samp{VISIBILITY} properties in individual
1373 entries.
1374 @end table
1376 @node Catching invisible edits,  , Initial visibility, Visibility cycling
1377 @subsection Catching invisible edits
1379 @vindex org-catch-invisible-edits
1380 @cindex edits, catching invisible
1381 Sometimes you may inadvertently edit an invisible part of the buffer and be
1382 confused on what has been edited and how to undo the mistake.  Setting
1383 @code{org-catch-invisible-edits} to non-@code{nil} will help prevent this.  See the
1384 docstring of this option on how Org should catch invisible edits and process
1385 them.
1387 @node Motion, Structure editing, Visibility cycling, Document Structure
1388 @section Motion
1389 @cindex motion, between headlines
1390 @cindex jumping, to headlines
1391 @cindex headline navigation
1392 The following commands jump to other headlines in the buffer.
1394 @table @asis
1395 @orgcmd{C-c C-n,outline-next-visible-heading}
1396 Next heading.
1397 @orgcmd{C-c C-p,outline-previous-visible-heading}
1398 Previous heading.
1399 @orgcmd{C-c C-f,org-forward-same-level}
1400 Next heading same level.
1401 @orgcmd{C-c C-b,org-backward-same-level}
1402 Previous heading same level.
1403 @orgcmd{C-c C-u,outline-up-heading}
1404 Backward to higher level heading.
1405 @orgcmd{C-c C-j,org-goto}
1406 Jump to a different place without changing the current outline
1407 visibility.  Shows the document structure in a temporary buffer, where
1408 you can use the following keys to find your destination:
1409 @vindex org-goto-auto-isearch
1410 @example
1411 @key{TAB}         @r{Cycle visibility.}
1412 @key{down} / @key{up}   @r{Next/previous visible headline.}
1413 @key{RET}         @r{Select this location.}
1414 @kbd{/}           @r{Do a Sparse-tree search}
1415 @r{The following keys work if you turn off @code{org-goto-auto-isearch}}
1416 n / p        @r{Next/previous visible headline.}
1417 f / b        @r{Next/previous headline same level.}
1418 u            @r{One level up.}
1419 0-9          @r{Digit argument.}
1420 q            @r{Quit}
1421 @end example
1422 @vindex org-goto-interface
1423 @noindent
1424 See also the option @code{org-goto-interface}.
1425 @end table
1427 @node Structure editing, Sparse trees, Motion, Document Structure
1428 @section Structure editing
1429 @cindex structure editing
1430 @cindex headline, promotion and demotion
1431 @cindex promotion, of subtrees
1432 @cindex demotion, of subtrees
1433 @cindex subtree, cut and paste
1434 @cindex pasting, of subtrees
1435 @cindex cutting, of subtrees
1436 @cindex copying, of subtrees
1437 @cindex sorting, of subtrees
1438 @cindex subtrees, cut and paste
1440 @table @asis
1441 @orgcmd{M-@key{RET},org-insert-heading}
1442 @vindex org-M-RET-may-split-line
1443 Insert a new heading/item with the same level than the one at point.
1444 If the cursor is in a plain list item, a new item is created
1445 (@pxref{Plain lists}).  To prevent this behavior in lists, call the
1446 command with a prefix argument.  When this command is used in the
1447 middle of a line, the line is split and the rest of the line becomes
1448 the new item or headline@footnote{If you do not want the line to be
1449 split, customize the variable @code{org-M-RET-may-split-line}.}.  If
1450 the command is used at the @emph{beginning} of a headline, the new
1451 headline is created before the current line.  If the command is used
1452 at the @emph{end} of a folded subtree (i.e., behind the ellipses at
1453 the end of a headline), then a headline will be
1454 inserted after the end of the subtree.  Calling this command with
1455 @kbd{C-u C-u} will unconditionally respect the headline's content and
1456 create a new item at the end of the parent subtree.
1457 @orgcmd{C-@key{RET},org-insert-heading-respect-content}
1458 Just like @kbd{M-@key{RET}}, except when adding a new heading below the
1459 current heading, the new heading is placed after the body instead of before
1460 it.  This command works from anywhere in the entry.
1461 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
1462 @vindex org-treat-insert-todo-heading-as-state-change
1463 Insert new TODO entry with same level as current heading.  See also the
1464 variable @code{org-treat-insert-todo-heading-as-state-change}.
1465 @orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
1466 Insert new TODO entry with same level as current heading.  Like
1467 @kbd{C-@key{RET}}, the new headline will be inserted after the current
1468 subtree.
1469 @orgcmd{@key{TAB},org-cycle}
1470 In a new entry with no text yet, the first @key{TAB} demotes the entry to
1471 become a child of the previous one.  The next @key{TAB} makes it a parent,
1472 and so on, all the way to top level.  Yet another @key{TAB}, and you are back
1473 to the initial level.
1474 @orgcmd{M-@key{left},org-do-promote}
1475 Promote current heading by one level.
1476 @orgcmd{M-@key{right},org-do-demote}
1477 Demote current heading by one level.
1478 @orgcmd{M-S-@key{left},org-promote-subtree}
1479 Promote the current subtree by one level.
1480 @orgcmd{M-S-@key{right},org-demote-subtree}
1481 Demote the current subtree by one level.
1482 @orgcmd{M-S-@key{up},org-move-subtree-up}
1483 Move subtree up (swap with previous subtree of same
1484 level).
1485 @orgcmd{M-S-@key{down},org-move-subtree-down}
1486 Move subtree down (swap with next subtree of same level).
1487 @orgcmd{M-h,org-mark-element}
1488 Mark the element at point.  Hitting repeatedly will mark subsequent elements
1489 of the one just marked.  E.g., hitting @key{M-h} on a paragraph will mark it,
1490 hitting @key{M-h} immediately again will mark the next one.
1491 @orgcmd{C-c @@,org-mark-subtree}
1492 Mark the subtree at point.  Hitting repeatedly will mark subsequent subtrees
1493 of the same level than the marked subtree.
1494 @orgcmd{C-c C-x C-w,org-cut-subtree}
1495 Kill subtree, i.e., remove it from buffer but save in kill ring.
1496 With a numeric prefix argument N, kill N sequential subtrees.
1497 @orgcmd{C-c C-x M-w,org-copy-subtree}
1498 Copy subtree to kill ring.  With a numeric prefix argument N, copy the N
1499 sequential subtrees.
1500 @orgcmd{C-c C-x C-y,org-paste-subtree}
1501 Yank subtree from kill ring.  This does modify the level of the subtree to
1502 make sure the tree fits in nicely at the yank position.  The yank level can
1503 also be specified with a numeric prefix argument, or by yanking after a
1504 headline marker like @samp{****}.
1505 @orgcmd{C-y,org-yank}
1506 @vindex org-yank-adjusted-subtrees
1507 @vindex org-yank-folded-subtrees
1508 Depending on the options @code{org-yank-adjusted-subtrees} and
1509 @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
1510 paste subtrees folded and in a clever way, using the same command as @kbd{C-c
1511 C-x C-y}.  With the default settings, no level adjustment will take place,
1512 but the yanked tree will be folded unless doing so would swallow text
1513 previously visible.  Any prefix argument to this command will force a normal
1514 @code{yank} to be executed, with the prefix passed along.  A good way to
1515 force a normal yank is @kbd{C-u C-y}.  If you use @code{yank-pop} after a
1516 yank, it will yank previous kill items plainly, without adjustment and
1517 folding.
1518 @orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
1519 Clone a subtree by making a number of sibling copies of it.  You will be
1520 prompted for the number of copies to make, and you can also specify if any
1521 timestamps in the entry should be shifted.  This can be useful, for example,
1522 to create a number of tasks related to a series of lectures to prepare.  For
1523 more details, see the docstring of the command
1524 @code{org-clone-subtree-with-time-shift}.
1525 @orgcmd{C-c C-w,org-refile}
1526 Refile entry or region to a different location.  @xref{Refile and copy}.
1527 @orgcmd{C-c ^,org-sort}
1528 Sort same-level entries.  When there is an active region, all entries in the
1529 region will be sorted.  Otherwise the children of the current headline are
1530 sorted.  The command prompts for the sorting method, which can be
1531 alphabetically, numerically, by time (first timestamp with active preferred,
1532 creation time, scheduled time, deadline time), by priority, by TODO keyword
1533 (in the sequence the keywords have been defined in the setup) or by the value
1534 of a property.  Reverse sorting is possible as well.  You can also supply
1535 your own function to extract the sorting key.  With a @kbd{C-u} prefix,
1536 sorting will be case-sensitive.
1537 @orgcmd{C-x n s,org-narrow-to-subtree}
1538 Narrow buffer to current subtree.
1539 @orgcmd{C-x n b,org-narrow-to-block}
1540 Narrow buffer to current block.
1541 @orgcmd{C-x n w,widen}
1542 Widen buffer to remove narrowing.
1543 @orgcmd{C-c *,org-toggle-heading}
1544 Turn a normal line or plain list item into a headline (so that it becomes a
1545 subheading at its location).  Also turn a headline into a normal line by
1546 removing the stars.  If there is an active region, turn all lines in the
1547 region into headlines.  If the first line in the region was an item, turn
1548 only the item lines into headlines.  Finally, if the first line is a
1549 headline, remove the stars from all headlines in the region.
1550 @end table
1552 @cindex region, active
1553 @cindex active region
1554 @cindex transient mark mode
1555 When there is an active region (Transient Mark mode), promotion and
1556 demotion work on all headlines in the region.  To select a region of
1557 headlines, it is best to place both point and mark at the beginning of a
1558 line, mark at the beginning of the first headline, and point at the line
1559 just after the last headline to change.  Note that when the cursor is
1560 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
1561 functionality.
1564 @node Sparse trees, Plain lists, Structure editing, Document Structure
1565 @section Sparse trees
1566 @cindex sparse trees
1567 @cindex trees, sparse
1568 @cindex folding, sparse trees
1569 @cindex occur, command
1571 @vindex org-show-hierarchy-above
1572 @vindex org-show-following-heading
1573 @vindex org-show-siblings
1574 @vindex org-show-entry-below
1575 An important feature of Org mode is the ability to construct @emph{sparse
1576 trees} for selected information in an outline tree, so that the entire
1577 document is folded as much as possible, but the selected information is made
1578 visible along with the headline structure above it@footnote{See also the
1579 variables @code{org-show-hierarchy-above}, @code{org-show-following-heading},
1580 @code{org-show-siblings}, and @code{org-show-entry-below} for detailed
1581 control on how much context is shown around each match.}.  Just try it out
1582 and you will see immediately how it works.
1584 Org mode contains several commands creating such trees, all these
1585 commands can be accessed through a dispatcher:
1587 @table @asis
1588 @orgcmd{C-c /,org-sparse-tree}
1589 This prompts for an extra key to select a sparse-tree creating command.
1590 @orgcmd{C-c / r,org-occur}
1591 @vindex org-remove-highlights-with-change
1592 Prompts for a regexp and shows a sparse tree with all matches.  If
1593 the match is in a headline, the headline is made visible.  If the match is in
1594 the body of an entry, headline and body are made visible.  In order to
1595 provide minimal context, also the full hierarchy of headlines above the match
1596 is shown, as well as the headline following the match.  Each match is also
1597 highlighted; the highlights disappear when the buffer is changed by an
1598 editing command@footnote{This depends on the option
1599 @code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
1600 When called with a @kbd{C-u} prefix argument, previous highlights are kept,
1601 so several calls to this command can be stacked.
1602 @orgcmdkkc{M-g n,M-g M-n,next-error}
1603 Jump to the next sparse tree match in this buffer.
1604 @orgcmdkkc{M-g p,M-g M-p,previous-error}
1605 Jump to the previous sparse tree match in this buffer.
1606 @end table
1608 @noindent
1609 @vindex org-agenda-custom-commands
1610 For frequently used sparse trees of specific search strings, you can
1611 use the option @code{org-agenda-custom-commands} to define fast
1612 keyboard access to specific sparse trees.  These commands will then be
1613 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
1614 For example:
1616 @lisp
1617 (setq org-agenda-custom-commands
1618       '(("f" occur-tree "FIXME")))
1619 @end lisp
1621 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
1622 a sparse tree matching the string @samp{FIXME}.
1624 The other sparse tree commands select headings based on TODO keywords,
1625 tags, or properties and will be discussed later in this manual.
1627 @kindex C-c C-e C-v
1628 @cindex printing sparse trees
1629 @cindex visible text, printing
1630 To print a sparse tree, you can use the Emacs command
1631 @code{ps-print-buffer-with-faces} which does not print invisible parts
1632 of the document @footnote{This does not work under XEmacs, because
1633 XEmacs uses selective display for outlining, not text properties.}.
1634 Or you can use @kbd{C-c C-e C-v} to export only the visible part of
1635 the document and print the resulting file.
1637 @node Plain lists, Drawers, Sparse trees, Document Structure
1638 @section Plain lists
1639 @cindex plain lists
1640 @cindex lists, plain
1641 @cindex lists, ordered
1642 @cindex ordered lists
1644 Within an entry of the outline tree, hand-formatted lists can provide
1645 additional structure.  They also provide a way to create lists of checkboxes
1646 (@pxref{Checkboxes}).  Org supports editing such lists, and every exporter
1647 (@pxref{Exporting}) can parse and format them.
1649 Org knows ordered lists, unordered lists, and description lists.
1650 @itemize @bullet
1651 @item
1652 @emph{Unordered} list items start with @samp{-}, @samp{+}, or
1653 @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
1654 they will be seen as top-level headlines.  Also, when you are hiding leading
1655 stars to get a clean outline view, plain list items starting with a star may
1656 be hard to distinguish from true headlines.  In short: even though @samp{*}
1657 is supported, it may be better to not use it for plain list items.}  as
1658 bullets.
1659 @item
1660 @vindex org-plain-list-ordered-item-terminator
1661 @vindex org-list-allow-alphabetical
1662 @emph{Ordered} list items start with a numeral followed by either a period or
1663 a right parenthesis@footnote{You can filter out any of them by configuring
1664 @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
1665 @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
1666 @samp{A)} by configuring @code{org-list-allow-alphabetical}.  To minimize
1667 confusion with normal text, those are limited to one character only.  Beyond
1668 that limit, bullets will automatically fallback to numbers.}.  If you want a
1669 list to start with a different value (e.g., 20), start the text of the item
1670 with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
1671 must be put @emph{before} the checkbox.  If you have activated alphabetical
1672 lists, you can also use counters like @code{[@@b]}.}.  Those constructs can
1673 be used in any item of the list in order to enforce a particular numbering.
1674 @item
1675 @emph{Description} list items are unordered list items, and contain the
1676 separator @samp{ :: } to distinguish the description @emph{term} from the
1677 description.
1678 @end itemize
1680 Items belonging to the same list must have the same indentation on the first
1681 line.  In particular, if an ordered list reaches number @samp{10.}, then the
1682 2--digit numbers must be written left-aligned with the other numbers in the
1683 list.  An item ends before the next line that is less or equally indented
1684 than its bullet/number.
1686 @vindex org-list-empty-line-terminates-plain-lists
1687 A list ends whenever every item has ended, which means before any line less
1688 or equally indented than items at top level.  It also ends before two blank
1689 lines@footnote{See also @code{org-list-empty-line-terminates-plain-lists}.}.
1690 In that case, all items are closed.  Here is an example:
1692 @example
1693 @group
1694 ** Lord of the Rings
1695    My favorite scenes are (in this order)
1696    1. The attack of the Rohirrim
1697    2. Eowyn's fight with the witch king
1698       + this was already my favorite scene in the book
1699       + I really like Miranda Otto.
1700    3. Peter Jackson being shot by Legolas
1701       - on DVD only
1702       He makes a really funny face when it happens.
1703    But in the end, no individual scenes matter but the film as a whole.
1704    Important actors in this film are:
1705    - @b{Elijah Wood} :: He plays Frodo
1706    - @b{Sean Austin} :: He plays Sam, Frodo's friend.  I still remember
1707      him very well from his role as Mikey Walsh in @i{The Goonies}.
1708 @end group
1709 @end example
1711 Org supports these lists by tuning filling and wrapping commands to deal with
1712 them correctly@footnote{Org only changes the filling settings for Emacs.  For
1713 XEmacs, you should use Kyle E. Jones' @file{filladapt.el}.  To turn this on,
1714 put into @file{.emacs}: @code{(require 'filladapt)}}, and by exporting them
1715 properly (@pxref{Exporting}).  Since indentation is what governs the
1716 structure of these lists, many structural constructs like @code{#+BEGIN_...}
1717 blocks can be indented to signal that they belong to a particular item.
1719 @vindex org-list-demote-modify-bullet
1720 @vindex org-list-indent-offset
1721 If you find that using a different bullet for a sub-list (than that used for
1722 the current list-level) improves readability, customize the variable
1723 @code{org-list-demote-modify-bullet}.  To get a greater difference of
1724 indentation between items and theirs sub-items, customize
1725 @code{org-list-indent-offset}.
1727 @vindex org-list-automatic-rules
1728 The following commands act on items when the cursor is in the first line of
1729 an item (the line with the bullet or number).  Some of them imply the
1730 application of automatic rules to keep list structure intact.  If some of
1731 these actions get in your way, configure @code{org-list-automatic-rules}
1732 to disable them individually.
1734 @table @asis
1735 @orgcmd{@key{TAB},org-cycle}
1736 @cindex cycling, in plain lists
1737 @vindex org-cycle-include-plain-lists
1738 Items can be folded just like headline levels.  Normally this works only if
1739 the cursor is on a plain list item.  For more details, see the variable
1740 @code{org-cycle-include-plain-lists}.  If this variable is set to
1741 @code{integrate}, plain list items will be treated like low-level
1742 headlines.  The level of an item is then given by the indentation of the
1743 bullet/number.  Items are always subordinate to real headlines, however; the
1744 hierarchies remain completely separated.  In a new item with no text yet, the
1745 first @key{TAB} demotes the item to become a child of the previous
1746 one.  Subsequent @key{TAB}s move the item to meaningful levels in the list
1747 and eventually get it back to its initial position.
1748 @orgcmd{M-@key{RET},org-insert-heading}
1749 @vindex org-M-RET-may-split-line
1750 @vindex org-list-automatic-rules
1751 Insert new item at current level.  With a prefix argument, force a new
1752 heading (@pxref{Structure editing}).  If this command is used in the middle
1753 of an item, that item is @emph{split} in two, and the second part becomes the
1754 new item@footnote{If you do not want the item to be split, customize the
1755 variable @code{org-M-RET-may-split-line}.}.  If this command is executed
1756 @emph{before item's body}, the new item is created @emph{before} the current
1757 one.
1758 @end table
1760 @table @kbd
1761 @kindex M-S-@key{RET}
1762 @item M-S-@key{RET}
1763 Insert a new item with a checkbox (@pxref{Checkboxes}).
1764 @kindex S-@key{down}
1765 @item S-up
1766 @itemx S-down
1767 @cindex shift-selection-mode
1768 @vindex org-support-shift-select
1769 @vindex org-list-use-circular-motion
1770 Jump to the previous/next item in the current list@footnote{If you want to
1771 cycle around items that way, you may customize
1772 @code{org-list-use-circular-motion}.}, but only if
1773 @code{org-support-shift-select} is off.  If not, you can still use paragraph
1774 jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
1775 similar effect.
1776 @kindex M-@key{up}
1777 @kindex M-@key{down}
1778 @item M-up
1779 @itemx M-down
1780 Move the item including subitems up/down@footnote{See
1781 @code{org-list-use-circular-motion} for a cyclic behavior.} (swap with
1782 previous/next item of same indentation).  If the list is ordered, renumbering
1783 is automatic.
1784 @kindex M-@key{left}
1785 @kindex M-@key{right}
1786 @item M-left
1787 @itemx M-right
1788 Decrease/increase the indentation of an item, leaving children alone.
1789 @kindex M-S-@key{left}
1790 @kindex M-S-@key{right}
1791 @item M-S-@key{left}
1792 @itemx M-S-@key{right}
1793 Decrease/increase the indentation of the item, including subitems.
1794 Initially, the item tree is selected based on current indentation.  When
1795 these commands are executed several times in direct succession, the initially
1796 selected region is used, even if the new indentation would imply a different
1797 hierarchy.  To use the new hierarchy, break the command chain with a cursor
1798 motion or so.
1800 As a special case, using this command on the very first item of a list will
1801 move the whole list.  This behavior can be disabled by configuring
1802 @code{org-list-automatic-rules}.  The global indentation of a list has no
1803 influence on the text @emph{after} the list.
1804 @kindex C-c C-c
1805 @item C-c C-c
1806 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1807 state of the checkbox.  In any case, verify bullets and indentation
1808 consistency in the whole list.
1809 @kindex C-c -
1810 @vindex org-plain-list-ordered-item-terminator
1811 @item C-c -
1812 Cycle the entire list level through the different itemize/enumerate bullets
1813 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
1814 depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
1815 and its indentation.  With a numeric prefix argument N, select the Nth bullet
1816 from this list.  If there is an active region when calling this, selected
1817 text will be changed into an item.  With a prefix argument, all lines will be
1818 converted to list items.  If the first line already was a list item, any item
1819 marker will be removed from the list.  Finally, even without an active
1820 region, a normal line will be converted into a list item.
1821 @kindex C-c *
1822 @item C-c *
1823 Turn a plain list item into a headline (so that it becomes a subheading at
1824 its location).  @xref{Structure editing}, for a detailed explanation.
1825 @kindex C-c C-*
1826 @item C-c C-*
1827 Turn the whole plain list into a subtree of the current heading.  Checkboxes
1828 (@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
1829 (resp. checked).
1830 @kindex S-@key{left}
1831 @kindex S-@key{right}
1832 @item S-left/right
1833 @vindex org-support-shift-select
1834 This command also cycles bullet styles when the cursor in on the bullet or
1835 anywhere in an item line, details depending on
1836 @code{org-support-shift-select}.
1837 @kindex C-c ^
1838 @cindex sorting, of plain list
1839 @item C-c ^
1840 Sort the plain list.  You will be prompted for the sorting method:
1841 numerically, alphabetically, by time, by checked status for check lists,
1842 or by a custom function.
1843 @end table
1845 @node Drawers, Blocks, Plain lists, Document Structure
1846 @section Drawers
1847 @cindex drawers
1848 @cindex #+DRAWERS
1849 @cindex visibility cycling, drawers
1851 @vindex org-drawers
1852 @cindex org-insert-drawer
1853 @kindex C-c C-x d
1854 Sometimes you want to keep information associated with an entry, but you
1855 normally don't want to see it.  For this, Org mode has @emph{drawers}.
1856 Drawers need to be configured with the option @code{org-drawers}@footnote{You
1857 can define additional drawers on a per-file basis with a line like
1858 @code{#+DRAWERS: HIDDEN STATE}}.  Drawers look like this:
1860 @example
1861 ** This is a headline
1862    Still outside the drawer
1863    :DRAWERNAME:
1864    This is inside the drawer.
1865    :END:
1866    After the drawer.
1867 @end example
1869 You can interactively insert drawers at point by calling
1870 @code{org-insert-drawer}, which is bound to @key{C-c C-x d}.  With an active
1871 region, this command will put the region inside the drawer.  With a prefix
1872 argument, this command calls @code{org-insert-property-drawer} and add a
1873 property drawer right below the current headline.  Completion over drawer
1874 keywords is also possible using @key{M-TAB}.
1876 Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
1877 show the entry, but keep the drawer collapsed to a single line.  In order to
1878 look inside the drawer, you need to move the cursor to the drawer line and
1879 press @key{TAB} there.  Org mode uses the @code{PROPERTIES} drawer for
1880 storing properties (@pxref{Properties and Columns}), and you can also arrange
1881 for state change notes (@pxref{Tracking TODO state changes}) and clock times
1882 (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}.  If you
1883 want to store a quick note in the LOGBOOK drawer, in a similar way to state changes, use
1885 @table @kbd
1886 @kindex C-c C-z
1887 @item C-c C-z
1888 Add a time-stamped note to the LOGBOOK drawer.
1889 @end table
1891 @vindex org-export-with-drawers
1892 You can select the name of the drawers which should be exported with
1893 @code{org-export-with-drawers}.  In that case, drawer contents will appear in
1894 export output.  Property drawers are not affected by this variable and are
1895 never exported.
1897 @node Blocks, Footnotes, Drawers, Document Structure
1898 @section Blocks
1900 @vindex org-hide-block-startup
1901 @cindex blocks, folding
1902 Org mode uses begin...end blocks for various purposes from including source
1903 code examples (@pxref{Literal examples}) to capturing time logging
1904 information (@pxref{Clocking work time}).  These blocks can be folded and
1905 unfolded by pressing TAB in the begin line.  You can also get all blocks
1906 folded at startup by configuring the option @code{org-hide-block-startup}
1907 or on a per-file basis by using
1909 @cindex @code{hideblocks}, STARTUP keyword
1910 @cindex @code{nohideblocks}, STARTUP keyword
1911 @example
1912 #+STARTUP: hideblocks
1913 #+STARTUP: nohideblocks
1914 @end example
1916 @node Footnotes, Orgstruct mode, Blocks, Document Structure
1917 @section Footnotes
1918 @cindex footnotes
1920 Org mode supports the creation of footnotes.  In contrast to the
1921 @file{footnote.el} package, Org mode's footnotes are designed for work on
1922 a larger document, not only for one-off documents like emails.
1924 A footnote is started by a footnote marker in square brackets in column 0, no
1925 indentation allowed.  It ends at the next footnote definition, headline, or
1926 after two consecutive empty lines.  The footnote reference is simply the
1927 marker in square brackets, inside text.  For example:
1929 @example
1930 The Org homepage[fn:1] now looks a lot better than it used to.
1932 [fn:1] The link is: http://orgmode.org
1933 @end example
1935 Org mode extends the number-based syntax to @emph{named} footnotes and
1936 optional inline definition.  Using plain numbers as markers (as
1937 @file{footnote.el} does) is supported for backward compatibility, but not
1938 encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded
1939 @LaTeX{}}).  Here are the valid references:
1941 @table @code
1942 @item [1]
1943 A plain numeric footnote marker.  Compatible with @file{footnote.el}, but not
1944 recommended because something like @samp{[1]} could easily be part of a code
1945 snippet.
1946 @item [fn:name]
1947 A named footnote reference, where @code{name} is a unique label word, or, for
1948 simplicity of automatic creation, a number.
1949 @item [fn:: This is the inline definition of this footnote]
1950 A @LaTeX{}-like anonymous footnote where the definition is given directly at the
1951 reference point.
1952 @item [fn:name: a definition]
1953 An inline definition of a footnote, which also specifies a name for the note.
1954 Since Org allows multiple references to the same note, you can then use
1955 @code{[fn:name]} to create additional references.
1956 @end table
1958 @vindex org-footnote-auto-label
1959 Footnote labels can be created automatically, or you can create names yourself.
1960 This is handled by the variable @code{org-footnote-auto-label} and its
1961 corresponding @code{#+STARTUP} keywords.  See the docstring of that variable
1962 for details.
1964 @noindent The following command handles footnotes:
1966 @table @kbd
1967 @kindex C-c C-x f
1968 @item C-c C-x f
1969 The footnote action command.
1971 When the cursor is on a footnote reference, jump to the definition.  When it
1972 is at a definition, jump to the (first) reference.
1974 @vindex org-footnote-define-inline
1975 @vindex org-footnote-section
1976 @vindex org-footnote-auto-adjust
1977 Otherwise, create a new footnote.  Depending on the option
1978 @code{org-footnote-define-inline}@footnote{The corresponding in-buffer
1979 setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
1980 definition will be placed right into the text as part of the reference, or
1981 separately into the location determined by the option
1982 @code{org-footnote-section}.
1984 When this command is called with a prefix argument, a menu of additional
1985 options is offered:
1986 @example
1987 s   @r{Sort the footnote definitions by reference sequence.  During editing,}
1988     @r{Org makes no effort to sort footnote definitions into a particular}
1989     @r{sequence.  If you want them sorted, use this command, which will}
1990     @r{also move entries according to @code{org-footnote-section}.  Automatic}
1991     @r{sorting after each insertion/deletion can be configured using the}
1992     @r{option @code{org-footnote-auto-adjust}.}
1993 r   @r{Renumber the simple @code{fn:N} footnotes.  Automatic renumbering}
1994     @r{after each insertion/deletion can be configured using the option}
1995     @r{@code{org-footnote-auto-adjust}.}
1996 S   @r{Short for first @code{r}, then @code{s} action.}
1997 n   @r{Normalize the footnotes by collecting all definitions (including}
1998     @r{inline definitions) into a special section, and then numbering them}
1999     @r{in sequence.  The references will then also be numbers.  This is}
2000     @r{meant to be the final step before finishing a document (e.g., sending}
2001     @r{off an email).}
2002 d   @r{Delete the footnote at point, and all definitions of and references}
2003     @r{to it.}
2004 @end example
2005 Depending on the variable @code{org-footnote-auto-adjust}@footnote{the
2006 corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},
2007 renumbering and sorting footnotes can be automatic after each insertion or
2008 deletion.
2010 @kindex C-c C-c
2011 @item C-c C-c
2012 If the cursor is on a footnote reference, jump to the definition.  If it is a
2013 the definition, jump back to the reference.  When called at a footnote
2014 location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
2015 @kindex C-c C-o
2016 @kindex mouse-1
2017 @kindex mouse-2
2018 @item C-c C-o  @r{or} mouse-1/2
2019 Footnote labels are also links to the corresponding definition/reference, and
2020 you can use the usual commands to follow these links.
2021 @end table
2023 @node Orgstruct mode, Org syntax, Footnotes, Document Structure
2024 @section The Orgstruct minor mode
2025 @cindex Orgstruct mode
2026 @cindex minor mode for structure editing
2028 If you like the intuitive way the Org mode structure editing and list
2029 formatting works, you might want to use these commands in other modes like
2030 Text mode or Mail mode as well.  The minor mode @code{orgstruct-mode} makes
2031 this possible.   Toggle the mode with @kbd{M-x orgstruct-mode RET}, or
2032 turn it on by default, for example in Message mode, with one of:
2034 @lisp
2035 (add-hook 'message-mode-hook 'turn-on-orgstruct)
2036 (add-hook 'message-mode-hook 'turn-on-orgstruct++)
2037 @end lisp
2039 When this mode is active and the cursor is on a line that looks to Org like a
2040 headline or the first line of a list item, most structure editing commands
2041 will work, even if the same keys normally have different functionality in the
2042 major mode you are using.  If the cursor is not in one of those special
2043 lines, Orgstruct mode lurks silently in the shadows.
2045 When you use @code{orgstruct++-mode}, Org will also export indentation and
2046 autofill settings into that mode, and detect item context after the first
2047 line of an item.
2049 @vindex orgstruct-heading-prefix-regexp
2050 You can also use Org structure editing to fold and unfold headlines in
2051 @emph{any} file, provided you defined @code{orgstruct-heading-prefix-regexp}:
2052 the regular expression must match the local prefix to use before Org's
2053 headlines.  For example, if you set this variable to @code{";; "} in Emacs
2054 Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
2055 commented lines.  Some commands like @code{org-demote} are disabled when the
2056 prefix is set, but folding/unfolding will work correctly.
2058 @node Org syntax,  , Orgstruct mode, Document Structure
2059 @section Org syntax
2060 @cindex Org syntax
2062 A reference document providing a formal description of Org's syntax is
2063 available as @uref{http://orgmode.org/worg/dev/org-syntax.html, a draft on
2064 Worg}, written and maintained by Nicolas Goaziou.  It defines Org's core
2065 internal concepts such as @code{headlines}, @code{sections}, @code{affiliated
2066 keywords}, @code{(greater) elements} and @code{objects}.  Each part of an Org
2067 file falls into one of the categories above.
2069 To explore the abstract structure of an Org buffer, run this in a buffer:
2071 @lisp
2072 M-: (org-element-parse-buffer) RET
2073 @end lisp
2075 It will output a list containing the buffer's content represented as an
2076 abstract structure.  The export engine relies on the information stored in
2077 this list.  Most interactive commands (e.g., for structure editing) also
2078 rely on the syntactic meaning of the surrounding context.
2080 @node Tables, Hyperlinks, Document Structure, Top
2081 @chapter Tables
2082 @cindex tables
2083 @cindex editing tables
2085 Org comes with a fast and intuitive table editor.  Spreadsheet-like
2086 calculations are supported using the Emacs @file{calc} package
2087 (@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}).
2089 @menu
2090 * Built-in table editor::       Simple tables
2091 * Column width and alignment::  Overrule the automatic settings
2092 * Column groups::               Grouping to trigger vertical lines
2093 * Orgtbl mode::                 The table editor as minor mode
2094 * The spreadsheet::             The table editor has spreadsheet capabilities
2095 * Org-Plot::                    Plotting from org tables
2096 @end menu
2098 @node Built-in table editor, Column width and alignment, Tables, Tables
2099 @section The built-in table editor
2100 @cindex table editor, built-in
2102 Org makes it easy to format tables in plain ASCII@.  Any line with @samp{|} as
2103 the first non-whitespace character is considered part of a table.  @samp{|}
2104 is also the column separator@footnote{To insert a vertical bar into a table
2105 field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}.  A table
2106 might look like this:
2108 @example
2109 | Name  | Phone | Age |
2110 |-------+-------+-----|
2111 | Peter |  1234 |  17 |
2112 | Anna  |  4321 |  25 |
2113 @end example
2115 A table is re-aligned automatically each time you press @key{TAB} or
2116 @key{RET} or @kbd{C-c C-c} inside the table.  @key{TAB} also moves to
2117 the next field (@key{RET} to the next row) and creates new table rows
2118 at the end of the table or before horizontal lines.  The indentation
2119 of the table is set by the first line.  Any line starting with
2120 @samp{|-} is considered as a horizontal separator line and will be
2121 expanded on the next re-align to span the whole table width.  So, to
2122 create the above table, you would only type
2124 @example
2125 |Name|Phone|Age|
2127 @end example
2129 @noindent and then press @key{TAB} to align the table and start filling in
2130 fields.  Even faster would be to type @code{|Name|Phone|Age} followed by
2131 @kbd{C-c @key{RET}}.
2133 @vindex org-enable-table-editor
2134 @vindex org-table-auto-blank-field
2135 When typing text into a field, Org treats @key{DEL},
2136 @key{Backspace}, and all character keys in a special way, so that
2137 inserting and deleting avoids shifting other fields.  Also, when
2138 typing @emph{immediately after the cursor was moved into a new field
2139 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
2140 field is automatically made blank.  If this behavior is too
2141 unpredictable for you, configure the options
2142 @code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
2144 @table @kbd
2145 @tsubheading{Creation and conversion}
2146 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2147 Convert the active region to table.  If every line contains at least one
2148 TAB character, the function assumes that the material is tab separated.
2149 If every line contains a comma, comma-separated values (CSV) are assumed.
2150 If not, lines are split at whitespace into fields.  You can use a prefix
2151 argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
2152 C-u} forces TAB, and a numeric argument N indicates that at least N
2153 consecutive spaces, or alternatively a TAB will be the separator.
2155 If there is no active region, this command creates an empty Org
2156 table.  But it is easier just to start typing, like
2157 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
2159 @tsubheading{Re-aligning and field motion}
2160 @orgcmd{C-c C-c,org-table-align}
2161 Re-align the table and don't move to another field.
2163 @orgcmd{<TAB>,org-table-next-field}
2164 Re-align the table, move to the next field.  Creates a new row if
2165 necessary.
2167 @orgcmd{S-@key{TAB},org-table-previous-field}
2168 Re-align, move to previous field.
2170 @orgcmd{@key{RET},org-table-next-row}
2171 Re-align the table and move down to next row.  Creates a new row if
2172 necessary.  At the beginning or end of a line, @key{RET} still does
2173 NEWLINE, so it can be used to split a table.
2175 @orgcmd{M-a,org-table-beginning-of-field}
2176 Move to beginning of the current table field, or on to the previous field.
2177 @orgcmd{M-e,org-table-end-of-field}
2178 Move to end of the current table field, or on to the next field.
2180 @tsubheading{Column and row editing}
2181 @orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
2182 Move the current column left/right.
2184 @orgcmd{M-S-@key{left},org-table-delete-column}
2185 Kill the current column.
2187 @orgcmd{M-S-@key{right},org-table-insert-column}
2188 Insert a new column to the left of the cursor position.
2190 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
2191 Move the current row up/down.
2193 @orgcmd{M-S-@key{up},org-table-kill-row}
2194 Kill the current row or horizontal line.
2196 @orgcmd{M-S-@key{down},org-table-insert-row}
2197 Insert a new row above the current row.  With a prefix argument, the line is
2198 created below the current one.
2200 @orgcmd{C-c -,org-table-insert-hline}
2201 Insert a horizontal line below current row.  With a prefix argument, the line
2202 is created above the current line.
2204 @orgcmd{C-c @key{RET},org-table-hline-and-move}
2205 Insert a horizontal line below current row, and move the cursor into the row
2206 below that line.
2208 @orgcmd{C-c ^,org-table-sort-lines}
2209 Sort the table lines in the region.  The position of point indicates the
2210 column to be used for sorting, and the range of lines is the range
2211 between the nearest horizontal separator lines, or the entire table.  If
2212 point is before the first column, you will be prompted for the sorting
2213 column.  If there is an active region, the mark specifies the first line
2214 and the sorting column, while point should be in the last line to be
2215 included into the sorting.  The command prompts for the sorting type
2216 (alphabetically, numerically, or by time).  When called with a prefix
2217 argument, alphabetic sorting will be case-sensitive.
2219 @tsubheading{Regions}
2220 @orgcmd{C-c C-x M-w,org-table-copy-region}
2221 Copy a rectangular region from a table to a special clipboard.  Point and
2222 mark determine edge fields of the rectangle.  If there is no active region,
2223 copy just the current field.  The process ignores horizontal separator lines.
2225 @orgcmd{C-c C-x C-w,org-table-cut-region}
2226 Copy a rectangular region from a table to a special clipboard, and
2227 blank all fields in the rectangle.  So this is the ``cut'' operation.
2229 @orgcmd{C-c C-x C-y,org-table-paste-rectangle}
2230 Paste a rectangular region into a table.
2231 The upper left corner ends up in the current field.  All involved fields
2232 will be overwritten.  If the rectangle does not fit into the present table,
2233 the table is enlarged as needed.  The process ignores horizontal separator
2234 lines.
2236 @orgcmd{M-@key{RET},org-table-wrap-region}
2237 Split the current field at the cursor position and move the rest to the line
2238 below.  If there is an active region, and both point and mark are in the same
2239 column, the text in the column is wrapped to minimum width for the given
2240 number of lines.  A numeric prefix argument may be used to change the number
2241 of desired lines.  If there is no region, but you specify a prefix argument,
2242 the current field is made blank, and the content is appended to the field
2243 above.
2245 @tsubheading{Calculations}
2246 @cindex formula, in tables
2247 @cindex calculations, in tables
2248 @cindex region, active
2249 @cindex active region
2250 @cindex transient mark mode
2251 @orgcmd{C-c +,org-table-sum}
2252 Sum the numbers in the current column, or in the rectangle defined by
2253 the active region.  The result is shown in the echo area and can
2254 be inserted with @kbd{C-y}.
2256 @orgcmd{S-@key{RET},org-table-copy-down}
2257 @vindex org-table-copy-increment
2258 When current field is empty, copy from first non-empty field above.  When not
2259 empty, copy current field down to next row and move cursor along with it.
2260 Depending on the option @code{org-table-copy-increment}, integer field
2261 values will be incremented during copy.  Integers that are too large will not
2262 be incremented.  Also, a @code{0} prefix argument temporarily disables the
2263 increment.  This key is also used by shift-selection and related modes
2264 (@pxref{Conflicts}).
2266 @tsubheading{Miscellaneous}
2267 @orgcmd{C-c `,org-table-edit-field}
2268 Edit the current field in a separate window.  This is useful for fields that
2269 are not fully visible (@pxref{Column width and alignment}).  When called with
2270 a @kbd{C-u} prefix, just make the full field visible, so that it can be
2271 edited in place.  When called with two @kbd{C-u} prefixes, make the editor
2272 window follow the cursor through the table and always show the current
2273 field.  The follow mode exits automatically when the cursor leaves the table,
2274 or when you repeat this command with @kbd{C-u C-u C-c `}.
2276 @item M-x org-table-import RET
2277 Import a file as a table.  The table should be TAB or whitespace
2278 separated.  Use, for example, to import a spreadsheet table or data
2279 from a database, because these programs generally can write
2280 TAB-separated text files.  This command works by inserting the file into
2281 the buffer and then converting the region to a table.  Any prefix
2282 argument is passed on to the converter, which uses it to determine the
2283 separator.
2284 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2285 Tables can also be imported by pasting tabular text into the Org
2286 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
2287 @kbd{C-c |} command (see above under @i{Creation and conversion}).
2289 @item M-x org-table-export RET
2290 @findex org-table-export
2291 @vindex org-table-export-default-format
2292 Export the table, by default as a TAB-separated file.  Use for data
2293 exchange with, for example, spreadsheet or database programs.  The format
2294 used to export the file can be configured in the option
2295 @code{org-table-export-default-format}.  You may also use properties
2296 @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
2297 name and the format for table export in a subtree.  Org supports quite
2298 general formats for exported tables.  The exporter format is the same as the
2299 format used by Orgtbl radio tables, see @ref{Translator functions}, for a
2300 detailed description.
2301 @end table
2303 If you don't like the automatic table editor because it gets in your
2304 way on lines which you would like to start with @samp{|}, you can turn
2305 it off with
2307 @lisp
2308 (setq org-enable-table-editor nil)
2309 @end lisp
2311 @noindent Then the only table command that still works is
2312 @kbd{C-c C-c} to do a manual re-align.
2314 @node Column width and alignment, Column groups, Built-in table editor, Tables
2315 @section Column width and alignment
2316 @cindex narrow columns in tables
2317 @cindex alignment in tables
2319 The width of columns is automatically determined by the table editor.  And
2320 also the alignment of a column is determined automatically from the fraction
2321 of number-like versus non-number fields in the column.
2323 Sometimes a single field or a few fields need to carry more text, leading to
2324 inconveniently wide columns.  Or maybe you want to make a table with several
2325 columns having a fixed width, regardless of content.  To set@footnote{This
2326 feature does not work on XEmacs.} the width of a column, one field anywhere
2327 in the column may contain just the string @samp{<N>} where @samp{N} is an
2328 integer specifying the width of the column in characters.  The next re-align
2329 will then set the width of this column to this value.
2331 @example
2332 @group
2333 |---+------------------------------|               |---+--------|
2334 |   |                              |               |   | <6>    |
2335 | 1 | one                          |               | 1 | one    |
2336 | 2 | two                          |     ----\     | 2 | two    |
2337 | 3 | This is a long chunk of text |     ----/     | 3 | This=> |
2338 | 4 | four                         |               | 4 | four   |
2339 |---+------------------------------|               |---+--------|
2340 @end group
2341 @end example
2343 @noindent
2344 Fields that are wider become clipped and end in the string @samp{=>}.
2345 Note that the full text is still in the buffer but is hidden.
2346 To see the full text, hold the mouse over the field---a tool-tip window
2347 will show the full content.  To edit such a field, use the command
2348 @kbd{C-c `} (that is @kbd{C-c} followed by the backquote).  This will
2349 open a new window with the full field.  Edit it and finish with @kbd{C-c
2350 C-c}.
2352 @vindex org-startup-align-all-tables
2353 When visiting a file containing a table with narrowed columns, the
2354 necessary character hiding has not yet happened, and the table needs to
2355 be aligned before it looks nice.  Setting the option
2356 @code{org-startup-align-all-tables} will realign all tables in a file
2357 upon visiting, but also slow down startup.  You can also set this option
2358 on a per-file basis with:
2360 @example
2361 #+STARTUP: align
2362 #+STARTUP: noalign
2363 @end example
2365 If you would like to overrule the automatic alignment of number-rich columns
2366 to the right and of string-rich column to the left, you can use @samp{<r>},
2367 @samp{<c>}@footnote{Centering does not work inside Emacs, but it does have an
2368 effect when exporting to HTML.} or @samp{<l>} in a similar fashion.  You may
2369 also combine alignment and field width like this: @samp{<r10>}.
2371 Lines which only contain these formatting cookies will be removed
2372 automatically when exporting the document.
2374 @node Column groups, Orgtbl mode, Column width and alignment, Tables
2375 @section Column groups
2376 @cindex grouping columns in tables
2378 When Org exports tables, it does so by default without vertical
2379 lines because that is visually more satisfying in general.  Occasionally
2380 however, vertical lines can be useful to structure a table into groups
2381 of columns, much like horizontal lines can do for groups of rows.  In
2382 order to specify column groups, you can use a special row where the
2383 first field contains only @samp{/}.  The further fields can either
2384 contain @samp{<} to indicate that this column should start a group,
2385 @samp{>} to indicate the end of a column, or @samp{<>} (no space between @samp{<}
2386 and @samp{>}) to make a column
2387 a group of its own.  Boundaries between column groups will upon export be
2388 marked with vertical lines.  Here is an example:
2390 @example
2391 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2392 |---+-----+-----+-----+---------+------------|
2393 | / |   < |     |   > |       < |          > |
2394 | 1 |   1 |   1 |   1 |       1 |          1 |
2395 | 2 |   4 |   8 |  16 |  1.4142 |     1.1892 |
2396 | 3 |   9 |  27 |  81 |  1.7321 |     1.3161 |
2397 |---+-----+-----+-----+---------+------------|
2398 #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
2399 @end example
2401 It is also sufficient to just insert the column group starters after
2402 every vertical line you would like to have:
2404 @example
2405 |  N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2406 |----+-----+-----+-----+---------+------------|
2407 | /  | <   |     |     | <       |            |
2408 @end example
2410 @node Orgtbl mode, The spreadsheet, Column groups, Tables
2411 @section The Orgtbl minor mode
2412 @cindex Orgtbl mode
2413 @cindex minor mode for tables
2415 If you like the intuitive way the Org table editor works, you
2416 might also want to use it in other modes like Text mode or Mail mode.
2417 The minor mode Orgtbl mode makes this possible.  You can always toggle
2418 the mode with @kbd{M-x orgtbl-mode RET}.  To turn it on by default, for
2419 example in Message mode, use
2421 @lisp
2422 (add-hook 'message-mode-hook 'turn-on-orgtbl)
2423 @end lisp
2425 Furthermore, with some special setup, it is possible to maintain tables
2426 in arbitrary syntax with Orgtbl mode.  For example, it is possible to
2427 construct @LaTeX{} tables with the underlying ease and power of
2428 Orgtbl mode, including spreadsheet capabilities.  For details, see
2429 @ref{Tables in arbitrary syntax}.
2431 @node The spreadsheet, Org-Plot, Orgtbl mode, Tables
2432 @section The spreadsheet
2433 @cindex calculations, in tables
2434 @cindex spreadsheet capabilities
2435 @cindex @file{calc} package
2437 The table editor makes use of the Emacs @file{calc} package to implement
2438 spreadsheet-like capabilities.  It can also evaluate Emacs Lisp forms to
2439 derive fields from other fields.  While fully featured, Org's implementation
2440 is not identical to other spreadsheets.  For example, Org knows the concept
2441 of a @emph{column formula} that will be applied to all non-header fields in a
2442 column without having to copy the formula to each relevant field.  There is
2443 also a formula debugger, and a formula editor with features for highlighting
2444 fields in the table corresponding to the references at the point in the
2445 formula, moving these references by arrow keys
2447 @menu
2448 * References::                  How to refer to another field or range
2449 * Formula syntax for Calc::     Using Calc to compute stuff
2450 * Formula syntax for Lisp::     Writing formulas in Emacs Lisp
2451 * Durations and time values::   How to compute durations and time values
2452 * Field and range formulas::    Formula for specific (ranges of) fields
2453 * Column formulas::             Formulas valid for an entire column
2454 * Lookup functions::            Lookup functions for searching tables
2455 * Editing and debugging formulas::  Fixing formulas
2456 * Updating the table::          Recomputing all dependent fields
2457 * Advanced features::           Field and column names, parameters and automatic recalc
2458 @end menu
2460 @node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
2461 @subsection References
2462 @cindex references
2464 To compute fields in the table from other fields, formulas must
2465 reference other fields or ranges.  In Org, fields can be referenced
2466 by name, by absolute coordinates, and by relative coordinates.  To find
2467 out what the coordinates of a field are, press @kbd{C-c ?} in that
2468 field, or press @kbd{C-c @}} to toggle the display of a grid.
2470 @subsubheading Field references
2471 @cindex field references
2472 @cindex references, to fields
2474 Formulas can reference the value of another field in two ways.  Like in
2475 any other spreadsheet, you may reference fields with a letter/number
2476 combination like @code{B3}, meaning the 2nd field in the 3rd row.
2477 @vindex org-table-use-standard-references
2478 However, Org prefers@footnote{Org will understand references typed by the
2479 user as @samp{B4}, but it will not use this syntax when offering a formula
2480 for editing.  You can customize this behavior using the option
2481 @code{org-table-use-standard-references}.} to use another, more general
2482 representation that looks like this:
2483 @example
2484 @@@var{row}$@var{column}
2485 @end example
2487 Column specifications can be absolute like @code{$1},
2488 @code{$2},...@code{$@var{N}}, or relative to the current column (i.e., the
2489 column of the field which is being computed) like @code{$+1} or @code{$-2}.
2490 @code{$<} and @code{$>} are immutable references to the first and last
2491 column, respectively, and you can use @code{$>>>} to indicate the third
2492 column from the right.
2494 The row specification only counts data lines and ignores horizontal separator
2495 lines (hlines).  Like with columns, you can use absolute row numbers
2496 @code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
2497 current row like @code{@@+3} or @code{@@-1}.  @code{@@<} and @code{@@>} are
2498 immutable references the first and last@footnote{For backward compatibility
2499 you can also use special names like @code{$LR5} and @code{$LR12} to refer in
2500 a stable way to the 5th and 12th field in the last row of the table.
2501 However, this syntax is deprecated, it should not be used for new documents.
2502 Use @code{@@>$} instead.} row in the table, respectively.  You may also
2503 specify the row relative to one of the hlines: @code{@@I} refers to the first
2504 hline, @code{@@II} to the second, etc.  @code{@@-I} refers to the first such
2505 line above the current line, @code{@@+I} to the first such line below the
2506 current line.  You can also write @code{@@III+2} which is the second data line
2507 after the third hline in the table.
2509 @code{@@0} and @code{$0} refer to the current row and column, respectively,
2510 i.e., to the row/column for the field being computed.  Also, if you omit
2511 either the column or the row part of the reference, the current row/column is
2512 implied.
2514 Org's references with @emph{unsigned} numbers are fixed references
2515 in the sense that if you use the same reference in the formula for two
2516 different fields, the same field will be referenced each time.
2517 Org's references with @emph{signed} numbers are floating
2518 references because the same reference operator can reference different
2519 fields depending on the field being calculated by the formula.
2521 Here are a few examples:
2523 @example
2524 @@2$3      @r{2nd row, 3rd column (same as @code{C2})}
2525 $5        @r{column 5 in the current row (same as @code{E&})}
2526 @@2        @r{current column, row 2}
2527 @@-1$-3    @r{the field one row up, three columns to the left}
2528 @@-I$2     @r{field just under hline above current row, column 2}
2529 @@>$5      @r{field in the last row, in column 5}
2530 @end example
2532 @subsubheading Range references
2533 @cindex range references
2534 @cindex references, to ranges
2536 You may reference a rectangular range of fields by specifying two field
2537 references connected by two dots @samp{..}.  If both fields are in the
2538 current row, you may simply use @samp{$2..$7}, but if at least one field
2539 is in a different row, you need to use the general @code{@@row$column}
2540 format at least for the first field (i.e the reference must start with
2541 @samp{@@} in order to be interpreted correctly).  Examples:
2543 @example
2544 $1..$3        @r{first three fields in the current row}
2545 $P..$Q        @r{range, using column names (see under Advanced)}
2546 $<<<..$>>     @r{start in third column, continue to the one but last}
2547 @@2$1..@@4$3    @r{6 fields between these two fields (same as @code{A2..C4})}
2548 @@-1$-2..@@-1   @r{3 fields in the row above, starting from 2 columns on the left}
2549 @@I..II        @r{between first and second hline, short for @code{@@I..@@II}}
2550 @end example
2552 @noindent Range references return a vector of values that can be fed
2553 into Calc vector functions.  Empty fields in ranges are normally suppressed,
2554 so that the vector contains only the non-empty fields.  For other options
2555 with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax
2556 for Calc}.
2558 @subsubheading Field coordinates in formulas
2559 @cindex field coordinates
2560 @cindex coordinates, of field
2561 @cindex row, of field coordinates
2562 @cindex column, of field coordinates
2564 For Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used to
2565 get the row or column number of the field where the formula result goes.
2566 The traditional Lisp formula equivalents are @code{org-table-current-dline}
2567 and @code{org-table-current-column}.  Examples:
2569 @example
2570 if(@@# % 2, $#, string(""))   @r{column number on odd lines only}
2571 $3 = remote(FOO, @@@@#$2)      @r{copy column 2 from table FOO into}
2572                              @r{column 3 of the current table}
2573 @end example
2575 @noindent For the second example, table FOO must have at least as many rows
2576 as the current table.  Note that this is inefficient@footnote{The computation time scales as
2577 O(N^2) because table FOO is parsed for each field to be copied.} for large
2578 number of rows.
2580 @subsubheading Named references
2581 @cindex named references
2582 @cindex references, named
2583 @cindex name, of column or field
2584 @cindex constants, in calculations
2585 @cindex #+CONSTANTS
2587 @vindex org-table-formula-constants
2588 @samp{$name} is interpreted as the name of a column, parameter or
2589 constant.  Constants are defined globally through the option
2590 @code{org-table-formula-constants}, and locally (for the file) through a
2591 line like
2593 @example
2594 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
2595 @end example
2597 @noindent
2598 @vindex constants-unit-system
2599 @pindex constants.el
2600 Also properties (@pxref{Properties and Columns}) can be used as
2601 constants in table formulas: for a property @samp{:Xyz:} use the name
2602 @samp{$PROP_Xyz}, and the property will be searched in the current
2603 outline entry and in the hierarchy above it.  If you have the
2604 @file{constants.el} package, it will also be used to resolve constants,
2605 including natural constants like @samp{$h} for Planck's constant, and
2606 units like @samp{$km} for kilometers@footnote{@file{constants.el} can
2607 supply the values of constants in two different unit systems, @code{SI}
2608 and @code{cgs}.  Which one is used depends on the value of the variable
2609 @code{constants-unit-system}.  You can use the @code{#+STARTUP} options
2610 @code{constSI} and @code{constcgs} to set this value for the current
2611 buffer.}.  Column names and parameters can be specified in special table
2612 lines.  These are described below, see @ref{Advanced features}.  All
2613 names must start with a letter, and further consist of letters and
2614 numbers.
2616 @subsubheading Remote references
2617 @cindex remote references
2618 @cindex references, remote
2619 @cindex references, to a different table
2620 @cindex name, of column or field
2621 @cindex constants, in calculations
2622 @cindex #+NAME, for table
2624 You may also reference constants, fields and ranges from a different table,
2625 either in the current file or even in a different file.  The syntax is
2627 @example
2628 remote(NAME-OR-ID,REF)
2629 @end example
2631 @noindent
2632 where NAME can be the name of a table in the current file as set by a
2633 @code{#+NAME: Name} line before the table.  It can also be the ID of an
2634 entry, even in a different file, and the reference then refers to the first
2635 table in that entry.  REF is an absolute field or range reference as
2636 described above for example @code{@@3$3} or @code{$somename}, valid in the
2637 referenced table.
2639 @node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet
2640 @subsection Formula syntax for Calc
2641 @cindex formula syntax, Calc
2642 @cindex syntax, of formulas
2644 A formula can be any algebraic expression understood by the Emacs @file{Calc}
2645 package.  Note that @file{calc} has the non-standard convention that @samp{/}
2646 has lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as
2647 @samp{a/(b*c)}.  Before evaluation by @code{calc-eval} (@pxref{Calling Calc
2648 from Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc,
2649 GNU Emacs Calc Manual}), variable substitution takes place according to the
2650 rules described above.
2651 @cindex vectors, in table calculations
2652 The range vectors can be directly fed into the Calc vector functions
2653 like @samp{vmean} and @samp{vsum}.
2655 @cindex format specifier
2656 @cindex mode, for @file{calc}
2657 @vindex org-calc-default-modes
2658 A formula can contain an optional mode string after a semicolon.  This
2659 string consists of flags to influence Calc and other modes during
2660 execution.  By default, Org uses the standard Calc modes (precision
2661 12, angular units degrees, fraction and symbolic modes off).  The display
2662 format, however, has been changed to @code{(float 8)} to keep tables
2663 compact.  The default settings can be configured using the option
2664 @code{org-calc-default-modes}.
2666 @noindent List of modes:
2668 @table @asis
2669 @item @code{p20}
2670 Set the internal Calc calculation precision to 20 digits.
2671 @item @code{n3}, @code{s3}, @code{e2}, @code{f4}
2672 Normal, scientific, engineering or fixed format of the result of Calc passed
2673 back to Org.  Calc formatting is unlimited in precision as long as the Calc
2674 calculation precision is greater.
2675 @item @code{D}, @code{R}
2676 Degree and radian angle modes of Calc.
2677 @item @code{F}, @code{S}
2678 Fraction and symbolic modes of Calc.
2679 @item @code{T}, @code{t}
2680 Duration computations in Calc or Lisp, @pxref{Durations and time values}.
2681 @item @code{E}
2682 If and how to consider empty fields.  Without @samp{E} empty fields in range
2683 references are suppressed so that the Calc vector or Lisp list contains only
2684 the non-empty fields.  With @samp{E} the empty fields are kept.  For empty
2685 fields in ranges or empty field references the value @samp{nan} (not a
2686 number) is used in Calc formulas and the empty string is used for Lisp
2687 formulas.  Add @samp{N} to use 0 instead for both formula types.  For the
2688 value of a field the mode @samp{N} has higher precedence than @samp{E}.
2689 @item @code{N}
2690 Interpret all fields as numbers, use 0 for non-numbers.  See the next section
2691 to see how this is essential for computations with Lisp formulas.  In Calc
2692 formulas it is used only occasionally because there number strings are
2693 already interpreted as numbers without @samp{N}.
2694 @item @code{L}
2695 Literal, for Lisp formulas only.  See the next section.
2696 @end table
2698 @noindent
2699 Unless you use large integer numbers or high-precision-calculation and
2700 -display for floating point numbers you may alternatively provide a
2701 @samp{printf} format specifier to reformat the Calc result after it has been
2702 passed back to Org instead of letting Calc already do the
2703 formatting@footnote{The @samp{printf} reformatting is limited in precision
2704 because the value passed to it is converted into an @samp{integer} or
2705 @samp{double}.  The @samp{integer} is limited in size by truncating the
2706 signed value to 32 bits.  The @samp{double} is limited in precision to 64
2707 bits overall which leaves approximately 16 significant decimal digits.}.  A
2708 few examples:
2710 @example
2711 $1+$2                @r{Sum of first and second field}
2712 $1+$2;%.2f           @r{Same, format result to two decimals}
2713 exp($2)+exp($1)      @r{Math functions can be used}
2714 $0;%.1f              @r{Reformat current cell to 1 decimal}
2715 ($3-32)*5/9          @r{Degrees F -> C conversion}
2716 $c/$1/$cm            @r{Hz -> cm conversion, using @file{constants.el}}
2717 tan($1);Dp3s1        @r{Compute in degrees, precision 3, display SCI 1}
2718 sin($1);Dp3%.1e      @r{Same, but use printf specifier for display}
2719 taylor($3,x=7,2)     @r{Taylor series of $3, at x=7, second degree}
2720 @end example
2722 Calc also contains a complete set of logical operations, (@pxref{Logical
2723 Operations, , Logical Operations, calc, GNU Emacs Calc Manual}).  For example
2725 @table @code
2726 @item if($1 < 20, teen, string(""))
2727 "teen" if age $1 is less than 20, else the Org table result field is set to
2728 empty with the empty string.
2729 @item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1
2730 Sum of the first two columns.  When at least one of the input fields is empty
2731 the Org table result field is set to empty.  @samp{E} is required to not
2732 convert empty fields to 0.  @samp{f-1} is an optional Calc format string
2733 similar to @samp{%.1f} but leaves empty results empty.
2734 @item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E
2735 Mean value of a range unless there is any empty field.  Every field in the
2736 range that is empty is replaced by @samp{nan} which lets @samp{vmean} result
2737 in @samp{nan}.  Then @samp{typeof == 12} detects the @samp{nan} from
2738 @samp{vmean} and the Org table result field is set to empty.  Use this when
2739 the sample set is expected to never have missing values.
2740 @item if("$1..$7" == "[]", string(""), vmean($1..$7))
2741 Mean value of a range with empty fields skipped.  Every field in the range
2742 that is empty is skipped.  When all fields in the range are empty the mean
2743 value is not defined and the Org table result field is set to empty.  Use
2744 this when the sample set can have a variable size.
2745 @item vmean($1..$7); EN
2746 To complete the example before: Mean value of a range with empty fields
2747 counting as samples with value 0.  Use this only when incomplete sample sets
2748 should be padded with 0 to the full size.
2749 @end table
2751 You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
2752 and use them in formula syntax for Calc.
2754 @node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet
2755 @subsection Emacs Lisp forms as formulas
2756 @cindex Lisp forms, as table formulas
2758 It is also possible to write a formula in Emacs Lisp.  This can be useful
2759 for string manipulation and control structures, if Calc's functionality is
2760 not enough.
2762 If a formula starts with a single-quote followed by an opening parenthesis,
2763 then it is evaluated as a Lisp form.  The evaluation should return either a
2764 string or a number.  Just as with @file{calc} formulas, you can specify modes
2765 and a printf format after a semicolon.
2767 With Emacs Lisp forms, you need to be conscious about the way field
2768 references are interpolated into the form.  By default, a reference will be
2769 interpolated as a Lisp string (in double-quotes) containing the field.  If
2770 you provide the @samp{N} mode switch, all referenced elements will be numbers
2771 (non-number fields will be zero) and interpolated as Lisp numbers, without
2772 quotes.  If you provide the @samp{L} flag, all fields will be interpolated
2773 literally, without quotes.  I.e., if you want a reference to be interpreted
2774 as a string by the Lisp form, enclose the reference operator itself in
2775 double-quotes, like @code{"$3"}.  Ranges are inserted as space-separated
2776 fields, so you can embed them in list or vector syntax.
2778 Here are a few examples---note how the @samp{N} mode is used when we do
2779 computations in Lisp:
2781 @table @code
2782 @item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
2783 Swap the first two characters of the content of column 1.
2784 @item '(+ $1 $2);N
2785 Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
2786 @item '(apply '+ '($1..$4));N
2787 Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
2788 @end table
2790 @node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet
2791 @subsection Durations and time values
2792 @cindex Duration, computing
2793 @cindex Time, computing
2794 @vindex org-table-duration-custom-format
2796 If you want to compute time values use the @code{T} flag, either in Calc
2797 formulas or Elisp formulas:
2799 @example
2800 @group
2801   |  Task 1 |   Task 2 |    Total |
2802   |---------+----------+----------|
2803   |    2:12 |     1:47 | 03:59:00 |
2804   | 3:02:20 | -2:07:00 |     0.92 |
2805   #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;t
2806 @end group
2807 @end example
2809 Input duration values must be of the form @code{[HH:MM[:SS]}, where seconds
2810 are optional.  With the @code{T} flag, computed durations will be displayed
2811 as @code{HH:MM:SS} (see the first formula above).  With the @code{t} flag,
2812 computed durations will be displayed according to the value of the option
2813 @code{org-table-duration-custom-format}, which defaults to @code{'hours} and
2814 will display the result as a fraction of hours (see the second formula in the
2815 example above).
2817 Negative duration values can be manipulated as well, and integers will be
2818 considered as seconds in addition and subtraction.
2820 @node Field and range formulas, Column formulas, Durations and time values, The spreadsheet
2821 @subsection Field and range formulas
2822 @cindex field formula
2823 @cindex range formula
2824 @cindex formula, for individual table field
2825 @cindex formula, for range of fields
2827 To assign a formula to a particular field, type it directly into the field,
2828 preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}.  When you press
2829 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2830 the formula will be stored as the formula for this field, evaluated, and the
2831 current field will be replaced with the result.
2833 @cindex #+TBLFM
2834 Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
2835 below the table.  If you type the equation in the 4th field of the 3rd data
2836 line in the table, the formula will look like @samp{@@3$4=$1+$2}.  When
2837 inserting/deleting/swapping column and rows with the appropriate commands,
2838 @i{absolute references} (but not relative ones) in stored formulas are
2839 modified in order to still reference the same field.  To avoid this from
2840 happening, in particular in range references, anchor ranges at the table
2841 borders (using @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines
2842 using the @code{@@I} notation.  Automatic adaptation of field references does
2843 of course not happen if you edit the table structure with normal editing
2844 commands---then you must fix the equations yourself.
2846 Instead of typing an equation into the field, you may also use the following
2847 command
2849 @table @kbd
2850 @orgcmd{C-u C-c =,org-table-eval-formula}
2851 Install a new formula for the current field.  The command prompts for a
2852 formula with default taken from the @samp{#+TBLFM:} line, applies
2853 it to the current field, and stores it.
2854 @end table
2856 The left-hand side of a formula can also be a special expression in order to
2857 assign the formula to a number of different fields.  There is no keyboard
2858 shortcut to enter such range formulas.  To add them, use the formula editor
2859 (@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
2860 directly.
2862 @table @code
2863 @item $2=
2864 Column formula, valid for the entire column.  This is so common that Org
2865 treats these formulas in a special way, see @ref{Column formulas}.
2866 @item @@3=
2867 Row formula, applies to all fields in the specified row.  @code{@@>=} means
2868 the last row.
2869 @item @@1$2..@@4$3=
2870 Range formula, applies to all fields in the given rectangular range.  This
2871 can also be used to assign a formula to some but not all fields in a row.
2872 @item $name=
2873 Named field, see @ref{Advanced features}.
2874 @end table
2876 @node Column formulas, Lookup functions, Field and range formulas, The spreadsheet
2877 @subsection Column formulas
2878 @cindex column formula
2879 @cindex formula, for table column
2881 When you assign a formula to a simple column reference like @code{$3=}, the
2882 same formula will be used in all fields of that column, with the following
2883 very convenient exceptions: (i) If the table contains horizontal separator
2884 hlines with rows above and below, everything before the first such hline is
2885 considered part of the table @emph{header} and will not be modified by column
2886 formulas.  Therefore a header is mandatory when you use column formulas and
2887 want to add hlines to group rows, like for example to separate a total row at
2888 the bottom from the summand rows above.  (ii) Fields that already get a value
2889 from a field/range formula will be left alone by column formulas.  These
2890 conditions make column formulas very easy to use.
2892 To assign a formula to a column, type it directly into any field in the
2893 column, preceded by an equal sign, like @samp{=$1+$2}.  When you press
2894 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2895 the formula will be stored as the formula for the current column, evaluated
2896 and the current field replaced with the result.  If the field contains only
2897 @samp{=}, the previously stored formula for this column is used.  For each
2898 column, Org will only remember the most recently used formula.  In the
2899 @samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}.  The
2900 left-hand side of a column formula can not be the name of column, it must be
2901 the numeric column reference or @code{$>}.
2903 Instead of typing an equation into the field, you may also use the
2904 following command:
2906 @table @kbd
2907 @orgcmd{C-c =,org-table-eval-formula}
2908 Install a new formula for the current column and replace current field with
2909 the result of the formula.  The command prompts for a formula, with default
2910 taken from the @samp{#+TBLFM} line, applies it to the current field and
2911 stores it.  With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
2912 will apply it to that many consecutive fields in the current column.
2913 @end table
2915 @node Lookup functions, Editing and debugging formulas, Column formulas, The spreadsheet
2916 @subsection Lookup functions
2917 @cindex lookup functions in tables
2918 @cindex table lookup functions
2920 Org has three predefined Emacs Lisp functions for lookups in tables.
2921 @table @code
2922 @item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)
2923 @findex org-lookup-first
2924 Searches for the first element @code{S} in list @code{S-LIST} for which
2925 @lisp
2926 (PREDICATE VAL S)
2927 @end lisp
2928 is @code{t}; returns the value from the corresponding position in list
2929 @code{R-LIST}.  The default @code{PREDICATE} is @code{equal}.  Note that the
2930 parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same
2931 order as the corresponding parameters are in the call to
2932 @code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}.  If
2933 @code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST}
2934 is returned.
2935 @item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)
2936 @findex org-lookup-last
2937 Similar to @code{org-lookup-first} above, but searches for the @i{last}
2938 element for which @code{PREDICATE} is @code{t}.
2939 @item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)
2940 @findex org-lookup-all
2941 Similar to @code{org-lookup-first}, but searches for @i{all} elements for
2942 which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding
2943 values.  This function can not be used by itself in a formula, because it
2944 returns a list of values.  However, powerful lookups can be built when this
2945 function is combined with other Emacs Lisp functions.
2946 @end table
2948 If the ranges used in these functions contain empty fields, the @code{E} mode
2949 for the formula should usually be specified: otherwise empty fields will not be
2950 included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result
2951 in an incorrect mapping from an element of @code{S-LIST} to the corresponding
2952 element of @code{R-LIST}.
2954 These three functions can be used to implement associative arrays, count
2955 matching cells, rank results, group data etc.  For practical examples
2956 see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
2957 tutorial on Worg}.
2959 @node Editing and debugging formulas, Updating the table, Lookup functions, The spreadsheet
2960 @subsection Editing and debugging formulas
2961 @cindex formula editing
2962 @cindex editing, of table formulas
2964 @vindex org-table-use-standard-references
2965 You can edit individual formulas in the minibuffer or directly in the field.
2966 Org can also prepare a special buffer with all active formulas of a table.
2967 When offering a formula for editing, Org converts references to the standard
2968 format (like @code{B3} or @code{D&}) if possible.  If you prefer to only work
2969 with the internal format (like @code{@@3$2} or @code{$4}), configure the
2970 option @code{org-table-use-standard-references}.
2972 @table @kbd
2973 @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
2974 Edit the formula associated with the current column/field in the
2975 minibuffer.  See @ref{Column formulas}, and @ref{Field and range formulas}.
2976 @orgcmd{C-u C-u C-c =,org-table-eval-formula}
2977 Re-insert the active formula (either a
2978 field formula, or a column formula) into the current field, so that you
2979 can edit it directly in the field.  The advantage over editing in the
2980 minibuffer is that you can use the command @kbd{C-c ?}.
2981 @orgcmd{C-c ?,org-table-field-info}
2982 While editing a formula in a table field, highlight the field(s)
2983 referenced by the reference at the cursor position in the formula.
2984 @kindex C-c @}
2985 @findex org-table-toggle-coordinate-overlays
2986 @item C-c @}
2987 Toggle the display of row and column numbers for a table, using overlays
2988 (@command{org-table-toggle-coordinate-overlays}).  These are updated each
2989 time the table is aligned; you can force it with @kbd{C-c C-c}.
2990 @kindex C-c @{
2991 @findex org-table-toggle-formula-debugger
2992 @item C-c @{
2993 Toggle the formula debugger on and off
2994 (@command{org-table-toggle-formula-debugger}).  See below.
2995 @orgcmd{C-c ',org-table-edit-formulas}
2996 Edit all formulas for the current table in a special buffer, where the
2997 formulas will be displayed one per line.  If the current field has an
2998 active formula, the cursor in the formula editor will mark it.
2999 While inside the special buffer, Org will automatically highlight
3000 any field or range reference at the cursor position.  You may edit,
3001 remove and add formulas, and use the following commands:
3003 @table @kbd
3004 @orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
3005 Exit the formula editor and store the modified formulas.  With @kbd{C-u}
3006 prefix, also apply the new formulas to the entire table.
3007 @orgcmd{C-c C-q,org-table-fedit-abort}
3008 Exit the formula editor without installing changes.
3009 @orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
3010 Toggle all references in the formula editor between standard (like
3011 @code{B3}) and internal (like @code{@@3$2}).
3012 @orgcmd{@key{TAB},org-table-fedit-lisp-indent}
3013 Pretty-print or indent Lisp formula at point.  When in a line containing
3014 a Lisp formula, format the formula according to Emacs Lisp rules.
3015 Another @key{TAB} collapses the formula back again.  In the open
3016 formula, @key{TAB} re-indents just like in Emacs Lisp mode.
3017 @orgcmd{M-@key{TAB},lisp-complete-symbol}
3018 Complete Lisp symbols, just like in Emacs Lisp mode.
3019 @kindex S-@key{up}
3020 @kindex S-@key{down}
3021 @kindex S-@key{left}
3022 @kindex S-@key{right}
3023 @findex org-table-fedit-ref-up
3024 @findex org-table-fedit-ref-down
3025 @findex org-table-fedit-ref-left
3026 @findex org-table-fedit-ref-right
3027 @item S-@key{up}/@key{down}/@key{left}/@key{right}
3028 Shift the reference at point.  For example, if the reference is
3029 @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
3030 This also works for relative references and for hline references.
3031 @orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
3032 Move the test line for column formulas in the Org buffer up and
3033 down.
3034 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
3035 Scroll the window displaying the table.
3036 @kindex C-c @}
3037 @findex org-table-toggle-coordinate-overlays
3038 @item C-c @}
3039 Turn the coordinate grid in the table on and off.
3040 @end table
3041 @end table
3043 Making a table field blank does not remove the formula associated with
3044 the field, because that is stored in a different line (the @samp{#+TBLFM}
3045 line)---during the next recalculation the field will be filled again.
3046 To remove a formula from a field, you have to give an empty reply when
3047 prompted for the formula, or to edit the @samp{#+TBLFM} line.
3049 @kindex C-c C-c
3050 You may edit the @samp{#+TBLFM} directly and re-apply the changed
3051 equations with @kbd{C-c C-c} in that line or with the normal
3052 recalculation commands in the table.
3054 @anchor{Using multiple #+TBLFM lines}
3055 @subsubheading Using multiple #+TBLFM lines
3056 @cindex #+TBLFM line, multiple
3057 @cindex #+TBLFM
3058 @cindex #+TBLFM, switching
3059 @kindex C-c C-c
3061 You may apply the formula temporarily.  This is useful when you
3062 switch the formula.  Place multiple @samp{#+TBLFM} lines right
3063 after the table, and then press @kbd{C-c C-c} on the formula to
3064 apply.  Here is an example:
3066 @example
3067 | x | y |
3068 |---+---|
3069 | 1 |   |
3070 | 2 |   |
3071 #+TBLFM: $2=$1*1
3072 #+TBLFM: $2=$1*2
3073 @end example
3075 @noindent
3076 Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
3078 @example
3079 | x | y |
3080 |---+---|
3081 | 1 | 2 |
3082 | 2 | 4 |
3083 #+TBLFM: $2=$1*1
3084 #+TBLFM: $2=$1*2
3085 @end example
3087 @noindent
3088 Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
3089 will get the following result of applying only the first @samp{#+TBLFM} line.
3091 @example
3092 | x | y |
3093 |---+---|
3094 | 1 | 1 |
3095 | 2 | 2 |
3096 #+TBLFM: $2=$1*1
3097 #+TBLFM: $2=$1*2
3098 @end example
3100 @subsubheading Debugging formulas
3101 @cindex formula debugging
3102 @cindex debugging, of table formulas
3103 When the evaluation of a formula leads to an error, the field content
3104 becomes the string @samp{#ERROR}.  If you would like see what is going
3105 on during variable substitution and calculation in order to find a bug,
3106 turn on formula debugging in the @code{Tbl} menu and repeat the
3107 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
3108 field.  Detailed information will be displayed.
3110 @node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet
3111 @subsection Updating the table
3112 @cindex recomputing table fields
3113 @cindex updating, table
3115 Recalculation of a table is normally not automatic, but needs to be
3116 triggered by a command.  See @ref{Advanced features}, for a way to make
3117 recalculation at least semi-automatic.
3119 In order to recalculate a line of a table or the entire table, use the
3120 following commands:
3122 @table @kbd
3123 @orgcmd{C-c *,org-table-recalculate}
3124 Recalculate the current row by first applying the stored column formulas
3125 from left to right, and all field/range formulas in the current row.
3127 @kindex C-u C-c *
3128 @item C-u C-c *
3129 @kindex C-u C-c C-c
3130 @itemx C-u C-c C-c
3131 Recompute the entire table, line by line.  Any lines before the first
3132 hline are left alone, assuming that these are part of the table header.
3134 @orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
3135 Iterate the table by recomputing it until no further changes occur.
3136 This may be necessary if some computed fields use the value of other
3137 fields that are computed @i{later} in the calculation sequence.
3138 @item M-x org-table-recalculate-buffer-tables RET
3139 @findex org-table-recalculate-buffer-tables
3140 Recompute all tables in the current buffer.
3141 @item M-x org-table-iterate-buffer-tables RET
3142 @findex org-table-iterate-buffer-tables
3143 Iterate all tables in the current buffer, in order to converge table-to-table
3144 dependencies.
3145 @end table
3147 @node Advanced features,  , Updating the table, The spreadsheet
3148 @subsection Advanced features
3150 If you want the recalculation of fields to happen automatically, or if you
3151 want to be able to assign @i{names}@footnote{Such names must start by an
3152 alphabetic character and use only alphanumeric/underscore characters.} to
3153 fields and columns, you need to reserve the first column of the table for
3154 special marking characters.
3156 @table @kbd
3157 @orgcmd{C-#,org-table-rotate-recalc-marks}
3158 Rotate the calculation mark in first column through the states @samp{ },
3159 @samp{#}, @samp{*}, @samp{!}, @samp{$}.  When there is an active region,
3160 change all marks in the region.
3161 @end table
3163 Here is an example of a table that collects exam results of students and
3164 makes use of these features:
3166 @example
3167 @group
3168 |---+---------+--------+--------+--------+-------+------|
3169 |   | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
3170 |---+---------+--------+--------+--------+-------+------|
3171 | ! |         |     P1 |     P2 |     P3 |   Tot |      |
3172 | # | Maximum |     10 |     15 |     25 |    50 | 10.0 |
3173 | ^ |         |     m1 |     m2 |     m3 |    mt |      |
3174 |---+---------+--------+--------+--------+-------+------|
3175 | # | Peter   |     10 |      8 |     23 |    41 |  8.2 |
3176 | # | Sam     |      2 |      4 |      3 |     9 |  1.8 |
3177 |---+---------+--------+--------+--------+-------+------|
3178 |   | Average |        |        |        |  25.0 |      |
3179 | ^ |         |        |        |        |    at |      |
3180 | $ | max=50  |        |        |        |       |      |
3181 |---+---------+--------+--------+--------+-------+------|
3182 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
3183 @end group
3184 @end example
3186 @noindent @b{Important}: please note that for these special tables,
3187 recalculating the table with @kbd{C-u C-c *} will only affect rows that
3188 are marked @samp{#} or @samp{*}, and fields that have a formula assigned
3189 to the field itself.  The column formulas are not applied in rows with
3190 empty first field.
3192 @cindex marking characters, tables
3193 The marking characters have the following meaning:
3195 @table @samp
3196 @item !
3197 The fields in this line define names for the columns, so that you may
3198 refer to a column as @samp{$Tot} instead of @samp{$6}.
3199 @item ^
3200 This row defines names for the fields @emph{above} the row.  With such
3201 a definition, any formula in the table may use @samp{$m1} to refer to
3202 the value @samp{10}.  Also, if you assign a formula to a names field, it
3203 will be stored as @samp{$name=...}.
3204 @item _
3205 Similar to @samp{^}, but defines names for the fields in the row
3206 @emph{below}.
3207 @item $
3208 Fields in this row can define @emph{parameters} for formulas.  For
3209 example, if a field in a @samp{$} row contains @samp{max=50}, then
3210 formulas in this table can refer to the value 50 using @samp{$max}.
3211 Parameters work exactly like constants, only that they can be defined on
3212 a per-table basis.
3213 @item #
3214 Fields in this row are automatically recalculated when pressing
3215 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row.  Also, this row
3216 is selected for a global recalculation with @kbd{C-u C-c *}.  Unmarked
3217 lines will be left alone by this command.
3218 @item *
3219 Selects this line for global recalculation with @kbd{C-u C-c *}, but
3220 not for automatic recalculation.  Use this when automatic
3221 recalculation slows down editing too much.
3222 @item @w{ }
3223 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
3224 All lines that should be recalculated should be marked with @samp{#}
3225 or @samp{*}.
3226 @item /
3227 Do not export this line.  Useful for lines that contain the narrowing
3228 @samp{<N>} markers or column group markers.
3229 @end table
3231 Finally, just to whet your appetite for what can be done with the
3232 fantastic @file{calc.el} package, here is a table that computes the Taylor
3233 series of degree @code{n} at location @code{x} for a couple of
3234 functions.
3236 @example
3237 @group
3238 |---+-------------+---+-----+--------------------------------------|
3239 |   | Func        | n | x   | Result                               |
3240 |---+-------------+---+-----+--------------------------------------|
3241 | # | exp(x)      | 1 | x   | 1 + x                                |
3242 | # | exp(x)      | 2 | x   | 1 + x + x^2 / 2                      |
3243 | # | exp(x)      | 3 | x   | 1 + x + x^2 / 2 + x^3 / 6            |
3244 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
3245 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2    |
3246 | * | tan(x)      | 3 | x   | 0.0175 x + 1.77e-6 x^3               |
3247 |---+-------------+---+-----+--------------------------------------|
3248 #+TBLFM: $5=taylor($2,$4,$3);n3
3249 @end group
3250 @end example
3252 @node Org-Plot,  , The spreadsheet, Tables
3253 @section Org-Plot
3254 @cindex graph, in tables
3255 @cindex plot tables using Gnuplot
3256 @cindex #+PLOT
3258 Org-Plot can produce 2D and 3D graphs of information stored in org tables
3259 using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
3260 @uref{http://xafs.org/BruceRavel/GnuplotMode}.  To see this in action, ensure
3261 that you have both Gnuplot and Gnuplot mode installed on your system, then
3262 call @code{org-plot/gnuplot} on the following table.
3264 @example
3265 @group
3266 #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
3267 | Sede      | Max cites | H-index |
3268 |-----------+-----------+---------|
3269 | Chile     |    257.72 |   21.39 |
3270 | Leeds     |    165.77 |   19.68 |
3271 | Sao Paolo |     71.00 |   11.50 |
3272 | Stockholm |    134.19 |   14.33 |
3273 | Morelia   |    257.56 |   17.67 |
3274 @end group
3275 @end example
3277 Notice that Org Plot is smart enough to apply the table's headers as labels.
3278 Further control over the labels, type, content, and appearance of plots can
3279 be exercised through the @code{#+PLOT:} lines preceding a table.  See below
3280 for a complete list of Org-plot options.  For more information and examples
3281 see the Org-plot tutorial at
3282 @uref{http://orgmode.org/worg/org-tutorials/org-plot.html}.
3284 @subsubheading Plot Options
3286 @table @code
3287 @item set
3288 Specify any @command{gnuplot} option to be set when graphing.
3290 @item title
3291 Specify the title of the plot.
3293 @item ind
3294 Specify which column of the table to use as the @code{x} axis.
3296 @item deps
3297 Specify the columns to graph as a Lisp style list, surrounded by parentheses
3298 and separated by spaces for example @code{dep:(3 4)} to graph the third and
3299 fourth columns (defaults to graphing all other columns aside from the @code{ind}
3300 column).
3302 @item type
3303 Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
3305 @item with
3306 Specify a @code{with} option to be inserted for every col being plotted
3307 (e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
3308 Defaults to @code{lines}.
3310 @item file
3311 If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
3313 @item labels
3314 List of labels to be used for the @code{deps} (defaults to the column headers
3315 if they exist).
3317 @item line
3318 Specify an entire line to be inserted in the Gnuplot script.
3320 @item map
3321 When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
3322 flat mapping rather than a @code{3d} slope.
3324 @item timefmt
3325 Specify format of Org mode timestamps as they will be parsed by Gnuplot.
3326 Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
3328 @item script
3329 If you want total control, you can specify a script file (place the file name
3330 between double-quotes) which will be used to plot.  Before plotting, every
3331 instance of @code{$datafile} in the specified script will be replaced with
3332 the path to the generated data file.  Note: even if you set this option, you
3333 may still want to specify the plot type, as that can impact the content of
3334 the data file.
3335 @end table
3337 @node Hyperlinks, TODO Items, Tables, Top
3338 @chapter Hyperlinks
3339 @cindex hyperlinks
3341 Like HTML, Org provides links inside a file, external links to
3342 other files, Usenet articles, emails, and much more.
3344 @menu
3345 * Link format::                 How links in Org are formatted
3346 * Internal links::              Links to other places in the current file
3347 * External links::              URL-like links to the world
3348 * Handling links::              Creating, inserting and following
3349 * Using links outside Org::     Linking from my C source code?
3350 * Link abbreviations::          Shortcuts for writing complex links
3351 * Search options::              Linking to a specific location
3352 * Custom searches::             When the default search is not enough
3353 @end menu
3355 @node Link format, Internal links, Hyperlinks, Hyperlinks
3356 @section Link format
3357 @cindex link format
3358 @cindex format, of links
3360 Org will recognize plain URL-like links and activate them as
3361 clickable links.  The general link format, however, looks like this:
3363 @example
3364 [[link][description]]       @r{or alternatively}           [[link]]
3365 @end example
3367 @noindent
3368 Once a link in the buffer is complete (all brackets present), Org
3369 will change the display so that @samp{description} is displayed instead
3370 of @samp{[[link][description]]} and @samp{link} is displayed instead of
3371 @samp{[[link]]}.  Links will be highlighted in the face @code{org-link},
3372 which by default is an underlined face.  You can directly edit the
3373 visible part of a link.  Note that this can be either the @samp{link}
3374 part (if there is no description) or the @samp{description} part.  To
3375 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
3376 cursor on the link.
3378 If you place the cursor at the beginning or just behind the end of the
3379 displayed text and press @key{BACKSPACE}, you will remove the
3380 (invisible) bracket at that location.  This makes the link incomplete
3381 and the internals are again displayed as plain text.  Inserting the
3382 missing bracket hides the link internals again.  To show the
3383 internal structure of all links, use the menu entry
3384 @code{Org->Hyperlinks->Literal links}.
3386 @node Internal links, External links, Link format, Hyperlinks
3387 @section Internal links
3388 @cindex internal links
3389 @cindex links, internal
3390 @cindex targets, for links
3392 @cindex property, CUSTOM_ID
3393 If the link does not look like a URL, it is considered to be internal in the
3394 current file.  The most important case is a link like
3395 @samp{[[#my-custom-id]]} which will link to the entry with the
3396 @code{CUSTOM_ID} property @samp{my-custom-id}.  You are responsible yourself
3397 to make sure these custom IDs are unique in a file.
3399 Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
3400 lead to a text search in the current file.
3402 The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
3403 or with a mouse click (@pxref{Handling links}).  Links to custom IDs will
3404 point to the corresponding headline.  The preferred match for a text link is
3405 a @i{dedicated target}: the same string in double angular brackets, like
3406 @samp{<<My Target>>}.
3408 @cindex #+NAME
3409 If no dedicated target exists, the link will then try to match the exact name
3410 of an element within the buffer.  Naming is done with the @code{#+NAME}
3411 keyword, which has to be put the line before the element it refers to, as in
3412 the following example
3414 @example
3415 #+NAME: My Target
3416 | a  | table      |
3417 |----+------------|
3418 | of | four cells |
3419 @end example
3421 If none of the above succeeds, Org will search for a headline that is exactly
3422 the link text but may also include a TODO keyword and tags@footnote{To insert
3423 a link targeting a headline, in-buffer completion can be used.  Just type
3424 a star followed by a few optional letters into the buffer and press
3425 @kbd{M-@key{TAB}}.  All headlines in the current buffer will be offered as
3426 completions.}.
3428 During export, internal links will be used to mark objects and assign them
3429 a number.  Marked objects will then be referenced by links pointing to them.
3430 In particular, links without a description will appear as the number assigned
3431 to the marked object@footnote{When targeting a @code{#+NAME} keyword,
3432 @code{#+CAPTION} keyword is mandatory in order to get proper numbering
3433 (@pxref{Images and tables}).}.  In the following excerpt from an Org buffer
3435 @example
3436 - one item
3437 - <<target>>another item
3438 Here we refer to item [[target]].
3439 @end example
3441 @noindent
3442 The last sentence will appear as @samp{Here we refer to item 2} when
3443 exported.
3445 In non-Org files, the search will look for the words in the link text.  In
3446 the above example the search would be for @samp{my target}.
3448 Following a link pushes a mark onto Org's own mark ring.  You can
3449 return to the previous position with @kbd{C-c &}.  Using this command
3450 several times in direct succession goes back to positions recorded
3451 earlier.
3453 @menu
3454 * Radio targets::               Make targets trigger links in plain text
3455 @end menu
3457 @node Radio targets,  , Internal links, Internal links
3458 @subsection Radio targets
3459 @cindex radio targets
3460 @cindex targets, radio
3461 @cindex links, radio targets
3463 Org can automatically turn any occurrences of certain target names
3464 in normal text into a link.  So without explicitly creating a link, the
3465 text connects to the target radioing its position.  Radio targets are
3466 enclosed by triple angular brackets.  For example, a target @samp{<<<My
3467 Target>>>} causes each occurrence of @samp{my target} in normal text to
3468 become activated as a link.  The Org file is scanned automatically
3469 for radio targets only when the file is first loaded into Emacs.  To
3470 update the target list during editing, press @kbd{C-c C-c} with the
3471 cursor on or at a target.
3473 @node External links, Handling links, Internal links, Hyperlinks
3474 @section External links
3475 @cindex links, external
3476 @cindex external links
3477 @cindex Gnus links
3478 @cindex BBDB links
3479 @cindex IRC links
3480 @cindex URL links
3481 @cindex file links
3482 @cindex RMAIL links
3483 @cindex MH-E links
3484 @cindex USENET links
3485 @cindex SHELL links
3486 @cindex Info links
3487 @cindex Elisp links
3489 Org supports links to files, websites, Usenet and email messages, BBDB
3490 database entries and links to both IRC conversations and their logs.
3491 External links are URL-like locators.  They start with a short identifying
3492 string followed by a colon.  There can be no space after the colon.  The
3493 following list shows examples for each link type.
3495 @example
3496 http://www.astro.uva.nl/~dominik          @r{on the web}
3497 doi:10.1000/182                           @r{DOI for an electronic resource}
3498 file:/home/dominik/images/jupiter.jpg     @r{file, absolute path}
3499 /home/dominik/images/jupiter.jpg          @r{same as above}
3500 file:papers/last.pdf                      @r{file, relative path}
3501 ./papers/last.pdf                         @r{same as above}
3502 file:/myself@@some.where:papers/last.pdf   @r{file, path on remote machine}
3503 /myself@@some.where:papers/last.pdf        @r{same as above}
3504 file:sometextfile::NNN                    @r{file, jump to line number}
3505 file:projects.org                         @r{another Org file}
3506 file:projects.org::some words             @r{text search in Org file}@footnote{
3507 The actual behavior of the search will depend on the value of
3508 the option @code{org-link-search-must-match-exact-headline}.  If its value
3509 is @code{nil}, then a fuzzy text search will be done.  If it is t, then only the
3510 exact headline will be matched.  If the value is @code{'query-to-create},
3511 then an exact headline will be searched; if it is not found, then the user
3512 will be queried to create it.}
3513 file:projects.org::*task title            @r{heading search in Org file}
3514 file+sys:/path/to/file                    @r{open via OS, like double-click}
3515 file+emacs:/path/to/file                  @r{force opening by Emacs}
3516 docview:papers/last.pdf::NNN              @r{open in doc-view mode at page}
3517 id:B7423F4D-2E8A-471B-8810-C40F074717E9   @r{Link to heading by ID}
3518 news:comp.emacs                           @r{Usenet link}
3519 mailto:adent@@galaxy.net                   @r{Mail link}
3520 mhe:folder                                @r{MH-E folder link}
3521 mhe:folder#id                             @r{MH-E message link}
3522 rmail:folder                              @r{RMAIL folder link}
3523 rmail:folder#id                           @r{RMAIL message link}
3524 gnus:group                                @r{Gnus group link}
3525 gnus:group#id                             @r{Gnus article link}
3526 bbdb:R.*Stallman                          @r{BBDB link (with regexp)}
3527 irc:/irc.com/#emacs/bob                   @r{IRC link}
3528 info:org#External links                   @r{Info node link}
3529 shell:ls *.org                            @r{A shell command}
3530 elisp:org-agenda                          @r{Interactive Elisp command}
3531 elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
3532 @end example
3534 @cindex VM links
3535 @cindex WANDERLUST links
3536 On top of these built-in link types, some are available through the
3537 @code{contrib/} directory (@pxref{Installation}).  For example, these links
3538 to VM or Wanderlust messages are available when you load the corresponding
3539 libraries from the @code{contrib/} directory:
3541 @example
3542 vm:folder                                 @r{VM folder link}
3543 vm:folder#id                              @r{VM message link}
3544 vm://myself@@some.where.org/folder#id      @r{VM on remote machine}
3545 vm-imap:account:folder                    @r{VM IMAP folder link}
3546 vm-imap:account:folder#id                 @r{VM IMAP message link}
3547 wl:folder                                 @r{WANDERLUST folder link}
3548 wl:folder#id                              @r{WANDERLUST message link}
3549 @end example
3551 For customizing Org to add new link types @ref{Adding hyperlink types}.
3553 A link should be enclosed in double brackets and may contain a descriptive
3554 text to be displayed instead of the URL (@pxref{Link format}), for example:
3556 @example
3557 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
3558 @end example
3560 @noindent
3561 If the description is a file name or URL that points to an image, HTML
3562 export (@pxref{HTML export}) will inline the image as a clickable
3563 button.  If there is no description at all and the link points to an
3564 image,
3565 that image will be inlined into the exported HTML file.
3567 @cindex square brackets, around links
3568 @cindex plain text external links
3569 Org also finds external links in the normal text and activates them
3570 as links.  If spaces must be part of the link (for example in
3571 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
3572 about the end of the link, enclose them in square brackets.
3574 @node Handling links, Using links outside Org, External links, Hyperlinks
3575 @section Handling links
3576 @cindex links, handling
3578 Org provides methods to create a link in the correct syntax, to
3579 insert it into an Org file, and to follow the link.
3581 @table @kbd
3582 @orgcmd{C-c l,org-store-link}
3583 @cindex storing links
3584 Store a link to the current location.  This is a @emph{global} command (you
3585 must create the key binding yourself) which can be used in any buffer to
3586 create a link.  The link will be stored for later insertion into an Org
3587 buffer (see below).  What kind of link will be created depends on the current
3588 buffer:
3590 @b{Org mode buffers}@*
3591 For Org files, if there is a @samp{<<target>>} at the cursor, the link points
3592 to the target.  Otherwise it points to the current headline, which will also
3593 be the description@footnote{If the headline contains a timestamp, it will be
3594 removed from the link and result in a wrong link---you should avoid putting
3595 timestamp in the headline.}.
3597 @vindex org-id-link-to-org-use-id
3598 @cindex property, CUSTOM_ID
3599 @cindex property, ID
3600 If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
3601 will be stored.  In addition or alternatively (depending on the value of
3602 @code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
3603 be created and/or used to construct a link@footnote{The library
3604 @file{org-id.el} must first be loaded, either through @code{org-customize} by
3605 enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
3606 'org-id)} in your @file{.emacs}.}. So using this command in Org buffers will
3607 potentially create two links: a human-readable from the custom ID, and one
3608 that is globally unique and works even if the entry is moved from file to
3609 file.  Later, when inserting the link, you need to decide which one to use.
3611 @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
3612 Pretty much all Emacs mail clients are supported.  The link will point to the
3613 current article, or, in some GNUS buffers, to the group.  The description is
3614 constructed from the author and the subject.
3616 @b{Web browsers: W3 and W3M}@*
3617 Here the link will be the current URL, with the page title as description.
3619 @b{Contacts: BBDB}@*
3620 Links created in a BBDB buffer will point to the current entry.
3622 @b{Chat: IRC}@*
3623 @vindex org-irc-link-to-logs
3624 For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t},
3625 a @samp{file:/} style link to the relevant point in the logs for the current
3626 conversation is created.  Otherwise an @samp{irc:/} style link to the
3627 user/channel/server under the point will be stored.
3629 @b{Other files}@*
3630 For any other files, the link will point to the file, with a search string
3631 (@pxref{Search options}) pointing to the contents of the current line.  If
3632 there is an active region, the selected words will form the basis of the
3633 search string.  If the automatically created link is not working correctly or
3634 accurately enough, you can write custom functions to select the search string
3635 and to do the search for particular file types---see @ref{Custom searches}.
3636 The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
3638 @b{Agenda view}@*
3639 When the cursor is in an agenda view, the created link points to the
3640 entry referenced by the current line.
3643 @orgcmd{C-c C-l,org-insert-link}
3644 @cindex link completion
3645 @cindex completion, of links
3646 @cindex inserting links
3647 @vindex org-keep-stored-link-after-insertion
3648 Insert a link@footnote{ Note that you don't have to use this command to
3649 insert a link.  Links in Org are plain text, and you can type or paste them
3650 straight into the buffer.  By using this command, the links are automatically
3651 enclosed in double brackets, and you will be asked for the optional
3652 descriptive text.}.  This prompts for a link to be inserted into the buffer.
3653 You can just type a link, using text for an internal link, or one of the link
3654 type prefixes mentioned in the examples above.  The link will be inserted
3655 into the buffer@footnote{After insertion of a stored link, the link will be
3656 removed from the list of stored links.  To keep it in the list later use, use
3657 a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
3658 @code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
3659 If some text was selected when this command is called, the selected text
3660 becomes the default description.
3662 @b{Inserting stored links}@*
3663 All links stored during the
3664 current session are part of the history for this prompt, so you can access
3665 them with @key{up} and @key{down} (or @kbd{M-p/n}).
3667 @b{Completion support}@* Completion with @key{TAB} will help you to insert
3668 valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes
3669 defined through link abbreviations (@pxref{Link abbreviations}).  If you
3670 press @key{RET} after inserting only the @var{prefix}, Org will offer
3671 specific completion support for some link types@footnote{This works by
3672 calling a special function @code{org-PREFIX-complete-link}.}  For
3673 example, if you type @kbd{file @key{RET}}, file name completion (alternative
3674 access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb
3675 @key{RET}} you can complete contact names.
3676 @orgkey C-u C-c C-l
3677 @cindex file name completion
3678 @cindex completion, of file names
3679 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
3680 a file will be inserted and you may use file name completion to select
3681 the name of the file.  The path to the file is inserted relative to the
3682 directory of the current Org file, if the linked file is in the current
3683 directory or in a sub-directory of it, or if the path is written relative
3684 to the current directory using @samp{../}.  Otherwise an absolute path
3685 is used, if possible with @samp{~/} for your home directory.  You can
3686 force an absolute path with two @kbd{C-u} prefixes.
3688 @item C-c C-l @ @r{(with cursor on existing link)}
3689 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
3690 link and description parts of the link.
3692 @cindex following links
3693 @orgcmd{C-c C-o,org-open-at-point}
3694 @vindex org-file-apps
3695 @vindex org-link-frame-setup
3696 Open link at point.  This will launch a web browser for URLs (using
3697 @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
3698 the corresponding links, and execute the command in a shell link.  When the
3699 cursor is on an internal link, this command runs the corresponding search.
3700 When the cursor is on a TAG list in a headline, it creates the corresponding
3701 TAGS view.  If the cursor is on a timestamp, it compiles the agenda for that
3702 date.  Furthermore, it will visit text and remote files in @samp{file:} links
3703 with Emacs and select a suitable application for local non-text files.
3704 Classification of files is based on file extension only.  See option
3705 @code{org-file-apps}.  If you want to override the default application and
3706 visit the file with Emacs, use a @kbd{C-u} prefix.  If you want to avoid
3707 opening in Emacs, use a @kbd{C-u C-u} prefix.@*
3708 If the cursor is on a headline, but not on a link, offer all links in the
3709 headline and entry text.  If you want to setup the frame configuration for
3710 following links, customize @code{org-link-frame-setup}.
3712 @orgkey @key{RET}
3713 @vindex org-return-follows-link
3714 When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
3715 the link at point.
3717 @kindex mouse-2
3718 @kindex mouse-1
3719 @item mouse-2
3720 @itemx mouse-1
3721 On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
3722 would.  Under Emacs 22 and later, @kbd{mouse-1} will also follow a link.
3724 @kindex mouse-3
3725 @item mouse-3
3726 @vindex org-display-internal-link-with-indirect-buffer
3727 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
3728 internal links to be displayed in another window@footnote{See the
3729 option @code{org-display-internal-link-with-indirect-buffer}}.
3731 @orgcmd{C-c C-x C-v,org-toggle-inline-images}
3732 @cindex inlining images
3733 @cindex images, inlining
3734 @vindex org-startup-with-inline-images
3735 @cindex @code{inlineimages}, STARTUP keyword
3736 @cindex @code{noinlineimages}, STARTUP keyword
3737 Toggle the inline display of linked images.  Normally this will only inline
3738 images that have no description part in the link, i.e., images that will also
3739 be inlined during export.  When called with a prefix argument, also display
3740 images that do have a link description.  You can ask for inline images to be
3741 displayed at startup by configuring the variable
3742 @code{org-startup-with-inline-images}@footnote{with corresponding
3743 @code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
3744 @orgcmd{C-c %,org-mark-ring-push}
3745 @cindex mark ring
3746 Push the current position onto the mark ring, to be able to return
3747 easily.  Commands following an internal link do this automatically.
3749 @orgcmd{C-c &,org-mark-ring-goto}
3750 @cindex links, returning to
3751 Jump back to a recorded position.  A position is recorded by the
3752 commands following internal links, and by @kbd{C-c %}.  Using this
3753 command several times in direct succession moves through a ring of
3754 previously recorded positions.
3756 @orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
3757 @cindex links, finding next/previous
3758 Move forward/backward to the next link in the buffer.  At the limit of
3759 the buffer, the search fails once, and then wraps around.  The key
3760 bindings for this are really too long; you might want to bind this also
3761 to @kbd{C-n} and @kbd{C-p}
3762 @lisp
3763 (add-hook 'org-load-hook
3764   (lambda ()
3765     (define-key org-mode-map "\C-n" 'org-next-link)
3766     (define-key org-mode-map "\C-p" 'org-previous-link)))
3767 @end lisp
3768 @end table
3770 @node Using links outside Org, Link abbreviations, Handling links, Hyperlinks
3771 @section Using links outside Org
3773 You can insert and follow links that have Org syntax not only in
3774 Org, but in any Emacs buffer.  For this, you should create two
3775 global commands, like this (please select suitable global keys
3776 yourself):
3778 @lisp
3779 (global-set-key "\C-c L" 'org-insert-link-global)
3780 (global-set-key "\C-c o" 'org-open-at-point-global)
3781 @end lisp
3783 @node Link abbreviations, Search options, Using links outside Org, Hyperlinks
3784 @section Link abbreviations
3785 @cindex link abbreviations
3786 @cindex abbreviation, links
3788 Long URLs can be cumbersome to type, and often many similar links are
3789 needed in a document.  For this you can use link abbreviations.  An
3790 abbreviated link looks like this
3792 @example
3793 [[linkword:tag][description]]
3794 @end example
3796 @noindent
3797 @vindex org-link-abbrev-alist
3798 where the tag is optional.
3799 The @i{linkword} must be a word, starting with a letter, followed by
3800 letters, numbers, @samp{-}, and @samp{_}.  Abbreviations are resolved
3801 according to the information in the variable @code{org-link-abbrev-alist}
3802 that relates the linkwords to replacement text.  Here is an example:
3804 @smalllisp
3805 @group
3806 (setq org-link-abbrev-alist
3807   '(("bugzilla"  . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
3808     ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
3809     ("google"    . "http://www.google.com/search?q=")
3810     ("gmap"      . "http://maps.google.com/maps?q=%s")
3811     ("omap"      . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
3812     ("ads"       . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
3813 @end group
3814 @end smalllisp
3816 If the replacement text contains the string @samp{%s}, it will be
3817 replaced with the tag.  Using @samp{%h} instead of @samp{%s} will
3818 url-encode the tag (see the example above, where we need to encode
3819 the URL parameter.)  Using @samp{%(my-function)} will pass the tag
3820 to a custom function, and replace it by the resulting string.
3822 If the replacement text don't contain any specifier, it will simply
3823 be appended to the string in order to create the link.
3825 Instead of a string, you may also specify a function that will be
3826 called with the tag as the only argument to create the link.
3828 With the above setting, you could link to a specific bug with
3829 @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
3830 @code{[[google:OrgMode]]}, show the map location of the Free Software
3831 Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
3832 @code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
3833 what the Org author is doing besides Emacs hacking with
3834 @code{[[ads:Dominik,C]]}.
3836 If you need special abbreviations just for a single Org buffer, you
3837 can define them in the file with
3839 @cindex #+LINK
3840 @example
3841 #+LINK: bugzilla  http://10.1.2.9/bugzilla/show_bug.cgi?id=
3842 #+LINK: google    http://www.google.com/search?q=%s
3843 @end example
3845 @noindent
3846 In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
3847 complete link abbreviations.  You may also define a function
3848 @code{org-PREFIX-complete-link} that implements special (e.g., completion)
3849 support for inserting such a link with @kbd{C-c C-l}.  Such a function should
3850 not accept any arguments, and return the full link with prefix.
3852 @node Search options, Custom searches, Link abbreviations, Hyperlinks
3853 @section Search options in file links
3854 @cindex search option in file links
3855 @cindex file links, searching
3857 File links can contain additional information to make Emacs jump to a
3858 particular location in the file when following a link.  This can be a
3859 line number or a search option after a double@footnote{For backward
3860 compatibility, line numbers can also follow a single colon.} colon.  For
3861 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
3862 links}) to a file, it encodes the words in the current line as a search
3863 string that can be used to find this line back later when following the
3864 link with @kbd{C-c C-o}.
3866 Here is the syntax of the different ways to attach a search to a file
3867 link, together with an explanation:
3869 @example
3870 [[file:~/code/main.c::255]]
3871 [[file:~/xx.org::My Target]]
3872 [[file:~/xx.org::*My Target]]
3873 [[file:~/xx.org::#my-custom-id]]
3874 [[file:~/xx.org::/regexp/]]
3875 @end example
3877 @table @code
3878 @item 255
3879 Jump to line 255.
3880 @item My Target
3881 Search for a link target @samp{<<My Target>>}, or do a text search for
3882 @samp{my target}, similar to the search in internal links, see
3883 @ref{Internal links}.  In HTML export (@pxref{HTML export}), such a file
3884 link will become an HTML reference to the corresponding named anchor in
3885 the linked file.
3886 @item *My Target
3887 In an Org file, restrict search to headlines.
3888 @item #my-custom-id
3889 Link to a heading with a @code{CUSTOM_ID} property
3890 @item /regexp/
3891 Do a regular expression search for @code{regexp}.  This uses the Emacs
3892 command @code{occur} to list all matches in a separate window.  If the
3893 target file is in Org mode, @code{org-occur} is used to create a
3894 sparse tree with the matches.
3895 @c If the target file is a directory,
3896 @c @code{grep} will be used to search all files in the directory.
3897 @end table
3899 As a degenerate case, a file link with an empty file name can be used
3900 to search the current file.  For example, @code{[[file:::find me]]} does
3901 a search for @samp{find me} in the current file, just as
3902 @samp{[[find me]]} would.
3904 @node Custom searches,  , Search options, Hyperlinks
3905 @section Custom Searches
3906 @cindex custom search strings
3907 @cindex search strings, custom
3909 The default mechanism for creating search strings and for doing the
3910 actual search related to a file link may not work correctly in all
3911 cases.  For example, Bib@TeX{} database files have many entries like
3912 @samp{year="1993"} which would not result in good search strings,
3913 because the only unique identification for a Bib@TeX{} entry is the
3914 citation key.
3916 @vindex org-create-file-search-functions
3917 @vindex org-execute-file-search-functions
3918 If you come across such a problem, you can write custom functions to set
3919 the right search string for a particular file type, and to do the search
3920 for the string in the file.  Using @code{add-hook}, these functions need
3921 to be added to the hook variables
3922 @code{org-create-file-search-functions} and
3923 @code{org-execute-file-search-functions}.  See the docstring for these
3924 variables for more information.  Org actually uses this mechanism
3925 for Bib@TeX{} database files, and you can use the corresponding code as
3926 an implementation example.  See the file @file{org-bibtex.el}.
3928 @node TODO Items, Tags, Hyperlinks, Top
3929 @chapter TODO items
3930 @cindex TODO items
3932 Org mode does not maintain TODO lists as separate documents@footnote{Of
3933 course, you can make a document that contains only long lists of TODO items,
3934 but this is not required.}.  Instead, TODO items are an integral part of the
3935 notes file, because TODO items usually come up while taking notes!  With Org
3936 mode, simply mark any entry in a tree as being a TODO item.  In this way,
3937 information is not duplicated, and the entire context from which the TODO
3938 item emerged is always present.
3940 Of course, this technique for managing TODO items scatters them
3941 throughout your notes file.  Org mode compensates for this by providing
3942 methods to give you an overview of all the things that you have to do.
3944 @menu
3945 * TODO basics::                 Marking and displaying TODO entries
3946 * TODO extensions::             Workflow and assignments
3947 * Progress logging::            Dates and notes for progress
3948 * Priorities::                  Some things are more important than others
3949 * Breaking down tasks::         Splitting a task into manageable pieces
3950 * Checkboxes::                  Tick-off lists
3951 @end menu
3953 @node TODO basics, TODO extensions, TODO Items, TODO Items
3954 @section Basic TODO functionality
3956 Any headline becomes a TODO item when it starts with the word
3957 @samp{TODO}, for example:
3959 @example
3960 *** TODO Write letter to Sam Fortune
3961 @end example
3963 @noindent
3964 The most important commands to work with TODO entries are:
3966 @table @kbd
3967 @orgcmd{C-c C-t,org-todo}
3968 @cindex cycling, of TODO states
3969 @vindex org-use-fast-todo-selection
3971 Rotate the TODO state of the current item among
3973 @example
3974 ,-> (unmarked) -> TODO -> DONE --.
3975 '--------------------------------'
3976 @end example
3978 If TODO keywords have fast access keys (see @ref{Fast access to TODO
3979 states}), you will be prompted for a TODO keyword through the fast selection
3980 interface; this is the default behavior when
3981 @code{org-use-fast-todo-selection} is non-@code{nil}.
3983 The same rotation can also be done ``remotely'' from the timeline and agenda
3984 buffers with the @kbd{t} command key (@pxref{Agenda commands}).
3986 @orgkey{C-u C-c C-t}
3987 When TODO keywords have no selection keys, select a specific keyword using
3988 completion; otherwise force cycling through TODO states with no prompt.  When
3989 @code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
3990 selection interface.
3992 @kindex S-@key{right}
3993 @kindex S-@key{left}
3994 @item S-@key{right} @ @r{/} @ S-@key{left}
3995 @vindex org-treat-S-cursor-todo-selection-as-state-change
3996 Select the following/preceding TODO state, similar to cycling.  Useful
3997 mostly if more than two TODO states are possible (@pxref{TODO
3998 extensions}).  See also @ref{Conflicts}, for a discussion of the interaction
3999 with @code{shift-selection-mode}.  See also the variable
4000 @code{org-treat-S-cursor-todo-selection-as-state-change}.
4001 @orgcmd{C-c / t,org-show-todo-tree}
4002 @cindex sparse tree, for TODO
4003 @vindex org-todo-keywords
4004 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}).  Folds the
4005 entire buffer, but shows all TODO items (with not-DONE state) and the
4006 headings hierarchy above them.  With a prefix argument (or by using @kbd{C-c
4007 / T}), search for a specific TODO@.  You will be prompted for the keyword,
4008 and you can also give a list of keywords like @code{KWD1|KWD2|...} to list
4009 entries that match any one of these keywords.  With a numeric prefix argument
4010 N, show the tree for the Nth keyword in the option @code{org-todo-keywords}.
4011 With two prefix arguments, find all TODO states, both un-done and done.
4012 @orgcmd{C-c a t,org-todo-list}
4013 Show the global TODO list.  Collects the TODO items (with not-DONE states)
4014 from all agenda files (@pxref{Agenda Views}) into a single buffer.  The new
4015 buffer will be in @code{agenda-mode}, which provides commands to examine and
4016 manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
4017 @xref{Global TODO list}, for more information.
4018 @orgcmd{S-M-@key{RET},org-insert-todo-heading}
4019 Insert a new TODO entry below the current one.
4020 @end table
4022 @noindent
4023 @vindex org-todo-state-tags-triggers
4024 Changing a TODO state can also trigger tag changes.  See the docstring of the
4025 option @code{org-todo-state-tags-triggers} for details.
4027 @node TODO extensions, Progress logging, TODO basics, TODO Items
4028 @section Extended use of TODO keywords
4029 @cindex extended TODO keywords
4031 @vindex org-todo-keywords
4032 By default, marked TODO entries have one of only two states: TODO and
4033 DONE@.  Org mode allows you to classify TODO items in more complex ways
4034 with @emph{TODO keywords} (stored in @code{org-todo-keywords}).  With
4035 special setup, the TODO keyword system can work differently in different
4036 files.
4038 Note that @i{tags} are another way to classify headlines in general and
4039 TODO items in particular (@pxref{Tags}).
4041 @menu
4042 * Workflow states::             From TODO to DONE in steps
4043 * TODO types::                  I do this, Fred does the rest
4044 * Multiple sets in one file::   Mixing it all, and still finding your way
4045 * Fast access to TODO states::  Single letter selection of a state
4046 * Per-file keywords::           Different files, different requirements
4047 * Faces for TODO keywords::     Highlighting states
4048 * TODO dependencies::           When one task needs to wait for others
4049 @end menu
4051 @node Workflow states, TODO types, TODO extensions, TODO extensions
4052 @subsection TODO keywords as workflow states
4053 @cindex TODO workflow
4054 @cindex workflow states as TODO keywords
4056 You can use TODO keywords to indicate different @emph{sequential} states
4057 in the process of working on an item, for example@footnote{Changing
4058 this variable only becomes effective after restarting Org mode in a
4059 buffer.}:
4061 @lisp
4062 (setq org-todo-keywords
4063   '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
4064 @end lisp
4066 The vertical bar separates the TODO keywords (states that @emph{need
4067 action}) from the DONE states (which need @emph{no further action}).  If
4068 you don't provide the separator bar, the last state is used as the DONE
4069 state.
4070 @cindex completion, of TODO keywords
4071 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
4072 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@.  You may
4073 also use a numeric prefix argument to quickly select a specific state.  For
4074 example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
4075 Or you can use @kbd{S-@key{left}} to go backward through the sequence.  If you
4076 define many keywords, you can use in-buffer completion
4077 (@pxref{Completion}) or even a special one-key selection scheme
4078 (@pxref{Fast access to TODO states}) to insert these words into the
4079 buffer.  Changing a TODO state can be logged with a timestamp, see
4080 @ref{Tracking TODO state changes}, for more information.
4082 @node TODO types, Multiple sets in one file, Workflow states, TODO extensions
4083 @subsection TODO keywords as types
4084 @cindex TODO types
4085 @cindex names as TODO keywords
4086 @cindex types as TODO keywords
4088 The second possibility is to use TODO keywords to indicate different
4089 @emph{types} of action items.  For example, you might want to indicate
4090 that items are for ``work'' or ``home''.  Or, when you work with several
4091 people on a single project, you might want to assign action items
4092 directly to persons, by using their names as TODO keywords.  This would
4093 be set up like this:
4095 @lisp
4096 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
4097 @end lisp
4099 In this case, different keywords do not indicate a sequence, but rather
4100 different types.  So the normal work flow would be to assign a task to a
4101 person, and later to mark it DONE@.  Org mode supports this style by adapting
4102 the workings of the command @kbd{C-c C-t}@footnote{This is also true for the
4103 @kbd{t} command in the timeline and agenda buffers.}.  When used several
4104 times in succession, it will still cycle through all names, in order to first
4105 select the right type for a task.  But when you return to the item after some
4106 time and execute @kbd{C-c C-t} again, it will switch from any name directly
4107 to DONE@.  Use prefix arguments or completion to quickly select a specific
4108 name.  You can also review the items of a specific TODO type in a sparse tree
4109 by using a numeric prefix to @kbd{C-c / t}.  For example, to see all things
4110 Lucy has to do, you would use @kbd{C-3 C-c / t}.  To collect Lucy's items
4111 from all agenda files into a single buffer, you would use the numeric prefix
4112 argument as well when creating the global TODO list: @kbd{C-3 C-c a t}.
4114 @node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions
4115 @subsection Multiple keyword sets in one file
4116 @cindex TODO keyword sets
4118 Sometimes you may want to use different sets of TODO keywords in
4119 parallel.  For example, you may want to have the basic
4120 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
4121 separate state indicating that an item has been canceled (so it is not
4122 DONE, but also does not require action).  Your setup would then look
4123 like this:
4125 @lisp
4126 (setq org-todo-keywords
4127       '((sequence "TODO" "|" "DONE")
4128         (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
4129         (sequence "|" "CANCELED")))
4130 @end lisp
4132 The keywords should all be different, this helps Org mode to keep track
4133 of which subsequence should be used for a given entry.  In this setup,
4134 @kbd{C-c C-t} only operates within a subsequence, so it switches from
4135 @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
4136 (nothing) to @code{REPORT}.  Therefore you need a mechanism to initially
4137 select the correct sequence.  Besides the obvious ways like typing a
4138 keyword or using completion, you may also apply the following commands:
4140 @table @kbd
4141 @kindex C-S-@key{right}
4142 @kindex C-S-@key{left}
4143 @kindex C-u C-u C-c C-t
4144 @item C-u C-u C-c C-t
4145 @itemx C-S-@key{right}
4146 @itemx C-S-@key{left}
4147 These keys jump from one TODO subset to the next.  In the above example,
4148 @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or
4149 @code{DONE} to @code{REPORT}, and any of the words in the second row to
4150 @code{CANCELED}.  Note that the @kbd{C-S-} key binding conflict with
4151 @code{shift-selection-mode} (@pxref{Conflicts}).
4152 @kindex S-@key{right}
4153 @kindex S-@key{left}
4154 @item S-@key{right}
4155 @itemx S-@key{left}
4156 @kbd{S-@key{<left>}} and @kbd{S-@key{<right>}} and walk through @emph{all}
4157 keywords from all sets, so for example @kbd{S-@key{<right>}} would switch
4158 from @code{DONE} to @code{REPORT} in the example above.  See also
4159 @ref{Conflicts}, for a discussion of the interaction with
4160 @code{shift-selection-mode}.
4161 @end table
4163 @node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions
4164 @subsection Fast access to TODO states
4166 If you would like to quickly change an entry to an arbitrary TODO state
4167 instead of cycling through the states, you can set up keys for single-letter
4168 access to the states.  This is done by adding the selection character after
4169 each keyword, in parentheses@footnote{All characters are allowed except
4170 @code{@@^!}, which have a special meaning here.}.  For example:
4172 @lisp
4173 (setq org-todo-keywords
4174       '((sequence "TODO(t)" "|" "DONE(d)")
4175         (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
4176         (sequence "|" "CANCELED(c)")))
4177 @end lisp
4179 @vindex org-fast-tag-selection-include-todo
4180 If you then press @kbd{C-c C-t} followed by the selection key, the entry
4181 will be switched to this state.  @kbd{SPC} can be used to remove any TODO
4182 keyword from an entry.@footnote{Check also the option
4183 @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
4184 state through the tags interface (@pxref{Setting tags}), in case you like to
4185 mingle the two concepts.  Note that this means you need to come up with
4186 unique keys across both sets of keywords.}
4188 @node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions
4189 @subsection Setting up keywords for individual files
4190 @cindex keyword options
4191 @cindex per-file keywords
4192 @cindex #+TODO
4193 @cindex #+TYP_TODO
4194 @cindex #+SEQ_TODO
4196 It can be very useful to use different aspects of the TODO mechanism in
4197 different files.  For file-local settings, you need to add special lines
4198 to the file which set the keywords and interpretation for that file
4199 only.  For example, to set one of the two examples discussed above, you
4200 need one of the following lines, starting in column zero anywhere in the
4201 file:
4203 @example
4204 #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
4205 @end example
4206 @noindent (you may also write @code{#+SEQ_TODO} to be explicit about the
4207 interpretation, but it means the same as @code{#+TODO}), or
4208 @example
4209 #+TYP_TODO: Fred Sara Lucy Mike | DONE
4210 @end example
4212 A setup for using several sets in parallel would be:
4214 @example
4215 #+TODO: TODO | DONE
4216 #+TODO: REPORT BUG KNOWNCAUSE | FIXED
4217 #+TODO: | CANCELED
4218 @end example
4220 @cindex completion, of option keywords
4221 @kindex M-@key{TAB}
4222 @noindent To make sure you are using the correct keyword, type
4223 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
4225 @cindex DONE, final TODO keyword
4226 Remember that the keywords after the vertical bar (or the last keyword
4227 if no bar is there) must always mean that the item is DONE (although you
4228 may use a different word).  After changing one of these lines, use
4229 @kbd{C-c C-c} with the cursor still in the line to make the changes
4230 known to Org mode@footnote{Org mode parses these lines only when
4231 Org mode is activated after visiting a file.  @kbd{C-c C-c} with the
4232 cursor in a line starting with @samp{#+} is simply restarting Org mode
4233 for the current buffer.}.
4235 @node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions
4236 @subsection Faces for TODO keywords
4237 @cindex faces, for TODO keywords
4239 @vindex org-todo @r{(face)}
4240 @vindex org-done @r{(face)}
4241 @vindex org-todo-keyword-faces
4242 Org mode highlights TODO keywords with special faces: @code{org-todo}
4243 for keywords indicating that an item still has to be acted upon, and
4244 @code{org-done} for keywords indicating that an item is finished.  If
4245 you are using more than 2 different states, you might want to use
4246 special faces for some of them.  This can be done using the option
4247 @code{org-todo-keyword-faces}.  For example:
4249 @lisp
4250 @group
4251 (setq org-todo-keyword-faces
4252       '(("TODO" . org-warning) ("STARTED" . "yellow")
4253         ("CANCELED" . (:foreground "blue" :weight bold))))
4254 @end group
4255 @end lisp
4257 While using a list with face properties as shown for CANCELED @emph{should}
4258 work, this does not always seem to be the case.  If necessary, define a
4259 special face and use that.  A string is interpreted as a color.  The option
4260 @code{org-faces-easy-properties} determines if that color is interpreted as a
4261 foreground or a background color.
4263 @node TODO dependencies,  , Faces for TODO keywords, TODO extensions
4264 @subsection TODO dependencies
4265 @cindex TODO dependencies
4266 @cindex dependencies, of TODO states
4268 @vindex org-enforce-todo-dependencies
4269 @cindex property, ORDERED
4270 The structure of Org files (hierarchy and lists) makes it easy to define TODO
4271 dependencies.  Usually, a parent TODO task should not be marked DONE until
4272 all subtasks (defined as children tasks) are marked as DONE@.  And sometimes
4273 there is a logical sequence to a number of (sub)tasks, so that one task
4274 cannot be acted upon before all siblings above it are done.  If you customize
4275 the option @code{org-enforce-todo-dependencies}, Org will block entries
4276 from changing state to DONE while they have children that are not DONE@.
4277 Furthermore, if an entry has a property @code{ORDERED}, each of its children
4278 will be blocked until all earlier siblings are marked DONE@.  Here is an
4279 example:
4281 @example
4282 * TODO Blocked until (two) is done
4283 ** DONE one
4284 ** TODO two
4286 * Parent
4287   :PROPERTIES:
4288   :ORDERED: t
4289   :END:
4290 ** TODO a
4291 ** TODO b, needs to wait for (a)
4292 ** TODO c, needs to wait for (a) and (b)
4293 @end example
4295 @table @kbd
4296 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4297 @vindex org-track-ordered-property-with-tag
4298 @cindex property, ORDERED
4299 Toggle the @code{ORDERED} property of the current entry.  A property is used
4300 for this behavior because this should be local to the current entry, not
4301 inherited like a tag.  However, if you would like to @i{track} the value of
4302 this property with a tag for better visibility, customize the option
4303 @code{org-track-ordered-property-with-tag}.
4304 @orgkey{C-u C-u C-u C-c C-t}
4305 Change TODO state, circumventing any state blocking.
4306 @end table
4308 @vindex org-agenda-dim-blocked-tasks
4309 If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries
4310 that cannot be closed because of such dependencies will be shown in a dimmed
4311 font or even made invisible in agenda views (@pxref{Agenda Views}).
4313 @cindex checkboxes and TODO dependencies
4314 @vindex org-enforce-todo-dependencies
4315 You can also block changes of TODO states by looking at checkboxes
4316 (@pxref{Checkboxes}).  If you set the option
4317 @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
4318 checkboxes will be blocked from switching to DONE.
4320 If you need more complex dependency structures, for example dependencies
4321 between entries in different trees or files, check out the contributed
4322 module @file{org-depend.el}.
4324 @page
4325 @node Progress logging, Priorities, TODO extensions, TODO Items
4326 @section Progress logging
4327 @cindex progress logging
4328 @cindex logging, of progress
4330 Org mode can automatically record a timestamp and possibly a note when
4331 you mark a TODO item as DONE, or even each time you change the state of
4332 a TODO item.  This system is highly configurable; settings can be on a
4333 per-keyword basis and can be localized to a file or even a subtree.  For
4334 information on how to clock working time for a task, see @ref{Clocking
4335 work time}.
4337 @menu
4338 * Closing items::               When was this entry marked DONE?
4339 * Tracking TODO state changes::  When did the status change?
4340 * Tracking your habits::        How consistent have you been?
4341 @end menu
4343 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging
4344 @subsection Closing items
4346 The most basic logging is to keep track of @emph{when} a certain TODO
4347 item was finished.  This is achieved with@footnote{The corresponding
4348 in-buffer setting is: @code{#+STARTUP: logdone}}
4350 @lisp
4351 (setq org-log-done 'time)
4352 @end lisp
4354 @vindex org-closed-keep-when-no-todo
4355 @noindent
4356 Then each time you turn an entry from a TODO (not-done) state into any of the
4357 DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
4358 the headline.  If you turn the entry back into a TODO item through further
4359 state cycling, that line will be removed again.  If you turn the entry back
4360 to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line
4361 will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
4362 non-@code{nil}.  If you want to record a note along with the timestamp,
4363 use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
4364 lognotedone}.}
4366 @lisp
4367 (setq org-log-done 'note)
4368 @end lisp
4370 @noindent
4371 You will then be prompted for a note, and that note will be stored below
4372 the entry with a @samp{Closing Note} heading.
4374 In the timeline (@pxref{Timeline}) and in the agenda
4375 (@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key to
4376 display the TODO items with a @samp{CLOSED} timestamp on each day,
4377 giving you an overview of what has been done.
4379 @node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging
4380 @subsection Tracking TODO state changes
4381 @cindex drawer, for state change recording
4383 @vindex org-log-states-order-reversed
4384 @vindex org-log-into-drawer
4385 @cindex property, LOG_INTO_DRAWER
4386 When TODO keywords are used as workflow states (@pxref{Workflow states}), you
4387 might want to keep track of when a state change occurred and maybe take a
4388 note about this change.  You can either record just a timestamp, or a
4389 time-stamped note for a change.  These records will be inserted after the
4390 headline as an itemized list, newest first@footnote{See the option
4391 @code{org-log-states-order-reversed}}.  When taking a lot of notes, you might
4392 want to get the notes out of the way into a drawer (@pxref{Drawers}).
4393 Customize @code{org-log-into-drawer} to get this behavior---the recommended
4394 drawer for this is called @code{LOGBOOK}@footnote{Note that the
4395 @code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to
4396 show an entry---use @key{C-u SPC} to keep it folded here}.  You can also
4397 overrule the setting of this variable for a subtree by setting a
4398 @code{LOG_INTO_DRAWER} property.
4400 Since it is normally too much to record a note for every state, Org mode
4401 expects configuration on a per-keyword basis for this.  This is achieved by
4402 adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note
4403 with timestamp) in parentheses after each keyword.  For example, with the
4404 setting
4406 @lisp
4407 (setq org-todo-keywords
4408   '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
4409 @end lisp
4411 To record a timestamp without a note for TODO keywords configured with
4412 @samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
4414 @noindent
4415 @vindex org-log-done
4416 you not only define global TODO keywords and fast access keys, but also
4417 request that a time is recorded when the entry is set to
4418 DONE@footnote{It is possible that Org mode will record two timestamps
4419 when you are using both @code{org-log-done} and state change logging.
4420 However, it will never prompt for two notes---if you have configured
4421 both, the state change recording note will take precedence and cancel
4422 the @samp{Closing Note}.}, and that a note is recorded when switching to
4423 WAIT or CANCELED@.  The setting for WAIT is even more special: the
4424 @samp{!} after the slash means that in addition to the note taken when
4425 entering the state, a timestamp should be recorded when @i{leaving} the
4426 WAIT state, if and only if the @i{target} state does not configure
4427 logging for entering it.  So it has no effect when switching from WAIT
4428 to DONE, because DONE is configured to record a timestamp only.  But
4429 when switching from WAIT back to TODO, the @samp{/!} in the WAIT
4430 setting now triggers a timestamp even though TODO has no logging
4431 configured.
4433 You can use the exact same syntax for setting logging preferences local
4434 to a buffer:
4435 @example
4436 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
4437 @end example
4439 @cindex property, LOGGING
4440 In order to define logging settings that are local to a subtree or a
4441 single item, define a LOGGING property in this entry.  Any non-empty
4442 LOGGING property resets all logging settings to @code{nil}.  You may then turn
4443 on logging for this specific tree using STARTUP keywords like
4444 @code{lognotedone} or @code{logrepeat}, as well as adding state specific
4445 settings like @code{TODO(!)}.  For example
4447 @example
4448 * TODO Log each state with only a time
4449   :PROPERTIES:
4450   :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
4451   :END:
4452 * TODO Only log when switching to WAIT, and when repeating
4453   :PROPERTIES:
4454   :LOGGING: WAIT(@@) logrepeat
4455   :END:
4456 * TODO No logging at all
4457   :PROPERTIES:
4458   :LOGGING: nil
4459   :END:
4460 @end example
4462 @node Tracking your habits,  , Tracking TODO state changes, Progress logging
4463 @subsection Tracking your habits
4464 @cindex habits
4466 Org has the ability to track the consistency of a special category of TODOs,
4467 called ``habits''.  A habit has the following properties:
4469 @enumerate
4470 @item
4471 You have enabled the @code{habits} module by customizing @code{org-modules}.
4472 @item
4473 The habit is a TODO item, with a TODO keyword representing an open state.
4474 @item
4475 The property @code{STYLE} is set to the value @code{habit}.
4476 @item
4477 The TODO has a scheduled date, usually with a @code{.+} style repeat
4478 interval.  A @code{++} style may be appropriate for habits with time
4479 constraints, e.g., must be done on weekends, or a @code{+} style for an
4480 unusual habit that can have a backlog, e.g., weekly reports.
4481 @item
4482 The TODO may also have minimum and maximum ranges specified by using the
4483 syntax @samp{.+2d/3d}, which says that you want to do the task at least every
4484 three days, but at most every two days.
4485 @item
4486 You must also have state logging for the @code{DONE} state enabled
4487 (@pxref{Tracking TODO state changes}), in order for historical data to be
4488 represented in the consistency graph.  If it is not enabled it is not an
4489 error, but the consistency graphs will be largely meaningless.
4490 @end enumerate
4492 To give you an idea of what the above rules look like in action, here's an
4493 actual habit with some history:
4495 @example
4496 ** TODO Shave
4497    SCHEDULED: <2009-10-17 Sat .+2d/4d>
4498    - State "DONE"       from "TODO"       [2009-10-15 Thu]
4499    - State "DONE"       from "TODO"       [2009-10-12 Mon]
4500    - State "DONE"       from "TODO"       [2009-10-10 Sat]
4501    - State "DONE"       from "TODO"       [2009-10-04 Sun]
4502    - State "DONE"       from "TODO"       [2009-10-02 Fri]
4503    - State "DONE"       from "TODO"       [2009-09-29 Tue]
4504    - State "DONE"       from "TODO"       [2009-09-25 Fri]
4505    - State "DONE"       from "TODO"       [2009-09-19 Sat]
4506    - State "DONE"       from "TODO"       [2009-09-16 Wed]
4507    - State "DONE"       from "TODO"       [2009-09-12 Sat]
4508    :PROPERTIES:
4509    :STYLE:    habit
4510    :LAST_REPEAT: [2009-10-19 Mon 00:36]
4511    :END:
4512 @end example
4514 What this habit says is: I want to shave at most every 2 days (given by the
4515 @code{SCHEDULED} date and repeat interval) and at least every 4 days.  If
4516 today is the 15th, then the habit first appears in the agenda on Oct 17,
4517 after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
4518 after four days have elapsed.
4520 What's really useful about habits is that they are displayed along with a
4521 consistency graph, to show how consistent you've been at getting that task
4522 done in the past.  This graph shows every day that the task was done over the
4523 past three weeks, with colors for each day.  The colors used are:
4525 @table @code
4526 @item Blue
4527 If the task wasn't to be done yet on that day.
4528 @item Green
4529 If the task could have been done on that day.
4530 @item Yellow
4531 If the task was going to be overdue the next day.
4532 @item Red
4533 If the task was overdue on that day.
4534 @end table
4536 In addition to coloring each day, the day is also marked with an asterisk if
4537 the task was actually done that day, and an exclamation mark to show where
4538 the current day falls in the graph.
4540 There are several configuration variables that can be used to change the way
4541 habits are displayed in the agenda.
4543 @table @code
4544 @item org-habit-graph-column
4545 The buffer column at which the consistency graph should be drawn.  This will
4546 overwrite any text in that column, so it is a good idea to keep your habits'
4547 titles brief and to the point.
4548 @item org-habit-preceding-days
4549 The amount of history, in days before today, to appear in consistency graphs.
4550 @item org-habit-following-days
4551 The number of days after today that will appear in consistency graphs.
4552 @item org-habit-show-habits-only-for-today
4553 If non-@code{nil}, only show habits in today's agenda view.  This is set to true by
4554 default.
4555 @end table
4557 Lastly, pressing @kbd{K} in the agenda buffer will cause habits to
4558 temporarily be disabled and they won't appear at all.  Press @kbd{K} again to
4559 bring them back.  They are also subject to tag filtering, if you have habits
4560 which should only be done in certain contexts, for example.
4562 @node Priorities, Breaking down tasks, Progress logging, TODO Items
4563 @section Priorities
4564 @cindex priorities
4566 If you use Org mode extensively, you may end up with enough TODO items that
4567 it starts to make sense to prioritize them.  Prioritizing can be done by
4568 placing a @emph{priority cookie} into the headline of a TODO item, like this
4570 @example
4571 *** TODO [#A] Write letter to Sam Fortune
4572 @end example
4574 @noindent
4575 @vindex org-priority-faces
4576 By default, Org mode supports three priorities: @samp{A}, @samp{B}, and
4577 @samp{C}.  @samp{A} is the highest priority.  An entry without a cookie is
4578 treated just like priority @samp{B}.  Priorities make a difference only for
4579 sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
4580 have no inherent meaning to Org mode.  The cookies can be highlighted with
4581 special faces by customizing @code{org-priority-faces}.
4583 Priorities can be attached to any outline node; they do not need to be TODO
4584 items.
4586 @table @kbd
4587 @item @kbd{C-c ,}
4588 @kindex @kbd{C-c ,}
4589 @findex org-priority
4590 Set the priority of the current headline (@command{org-priority}).  The
4591 command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
4592 When you press @key{SPC} instead, the priority cookie is removed from the
4593 headline.  The priorities can also be changed ``remotely'' from the timeline
4594 and agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
4596 @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
4597 @vindex org-priority-start-cycle-with-default
4598 Increase/decrease priority of current headline@footnote{See also the option
4599 @code{org-priority-start-cycle-with-default}.}.  Note that these keys are
4600 also used to modify timestamps (@pxref{Creating timestamps}).  See also
4601 @ref{Conflicts}, for a discussion of the interaction with
4602 @code{shift-selection-mode}.
4603 @end table
4605 @vindex org-highest-priority
4606 @vindex org-lowest-priority
4607 @vindex org-default-priority
4608 You can change the range of allowed priorities by setting the options
4609 @code{org-highest-priority}, @code{org-lowest-priority}, and
4610 @code{org-default-priority}.  For an individual buffer, you may set
4611 these values (highest, lowest, default) like this (please make sure that
4612 the highest priority is earlier in the alphabet than the lowest
4613 priority):
4615 @cindex #+PRIORITIES
4616 @example
4617 #+PRIORITIES: A C B
4618 @end example
4620 @node Breaking down tasks, Checkboxes, Priorities, TODO Items
4621 @section Breaking tasks down into subtasks
4622 @cindex tasks, breaking down
4623 @cindex statistics, for TODO items
4625 @vindex org-agenda-todo-list-sublevels
4626 It is often advisable to break down large tasks into smaller, manageable
4627 subtasks.  You can do this by creating an outline tree below a TODO item,
4628 with detailed subtasks on the tree@footnote{To keep subtasks out of the
4629 global TODO list, see the @code{org-agenda-todo-list-sublevels}.}.  To keep
4630 the overview over the fraction of subtasks that are already completed, insert
4631 either @samp{[/]} or @samp{[%]} anywhere in the headline.  These cookies will
4632 be updated each time the TODO status of a child changes, or when pressing
4633 @kbd{C-c C-c} on the cookie.  For example:
4635 @example
4636 * Organize Party [33%]
4637 ** TODO Call people [1/2]
4638 *** TODO Peter
4639 *** DONE Sarah
4640 ** TODO Buy food
4641 ** DONE Talk to neighbor
4642 @end example
4644 @cindex property, COOKIE_DATA
4645 If a heading has both checkboxes and TODO children below it, the meaning of
4646 the statistics cookie become ambiguous.  Set the property
4647 @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
4648 this issue.
4650 @vindex org-hierarchical-todo-statistics
4651 If you would like to have the statistics cookie count any TODO entries in the
4652 subtree (not just direct children), configure
4653 @code{org-hierarchical-todo-statistics}.  To do this for a single subtree,
4654 include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
4655 property.
4657 @example
4658 * Parent capturing statistics [2/20]
4659   :PROPERTIES:
4660   :COOKIE_DATA: todo recursive
4661   :END:
4662 @end example
4664 If you would like a TODO entry to automatically change to DONE
4665 when all children are done, you can use the following setup:
4667 @example
4668 (defun org-summary-todo (n-done n-not-done)
4669   "Switch entry to DONE when all subentries are done, to TODO otherwise."
4670   (let (org-log-done org-log-states)   ; turn off logging
4671     (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
4673 (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
4674 @end example
4677 Another possibility is the use of checkboxes to identify (a hierarchy of) a
4678 large number of subtasks (@pxref{Checkboxes}).
4681 @node Checkboxes,  , Breaking down tasks, TODO Items
4682 @section Checkboxes
4683 @cindex checkboxes
4685 @vindex org-list-automatic-rules
4686 Every item in a plain list@footnote{With the exception of description
4687 lists.  But you can allow it by modifying @code{org-list-automatic-rules}
4688 accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
4689 it with the string @samp{[ ]}.  This feature is similar to TODO items
4690 (@pxref{TODO Items}), but is more lightweight.  Checkboxes are not included
4691 in the global TODO list, so they are often great to split a task into a
4692 number of simple steps.  Or you can use them in a shopping list.  To toggle a
4693 checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
4694 @file{org-mouse.el}).
4696 Here is an example of a checkbox list.
4698 @example
4699 * TODO Organize party [2/4]
4700   - [-] call people [1/3]
4701     - [ ] Peter
4702     - [X] Sarah
4703     - [ ] Sam
4704   - [X] order food
4705   - [ ] think about what music to play
4706   - [X] talk to the neighbors
4707 @end example
4709 Checkboxes work hierarchically, so if a checkbox item has children that
4710 are checkboxes, toggling one of the children checkboxes will make the
4711 parent checkbox reflect if none, some, or all of the children are
4712 checked.
4714 @cindex statistics, for checkboxes
4715 @cindex checkbox statistics
4716 @cindex property, COOKIE_DATA
4717 @vindex org-checkbox-hierarchical-statistics
4718 The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
4719 indicating how many checkboxes present in this entry have been checked off,
4720 and the total number of checkboxes present.  This can give you an idea on how
4721 many checkboxes remain, even without opening a folded entry.  The cookies can
4722 be placed into a headline or into (the first line of) a plain list item.
4723 Each cookie covers checkboxes of direct children structurally below the
4724 headline/item on which the cookie appears@footnote{Set the option
4725 @code{org-checkbox-hierarchical-statistics} if you want such cookies to
4726 count all checkboxes below the cookie, not just those belonging to direct
4727 children.}.  You have to insert the cookie yourself by typing either
4728 @samp{[/]} or @samp{[%]}.  With @samp{[/]} you get an @samp{n out of m}
4729 result, as in the examples above.  With @samp{[%]} you get information about
4730 the percentage of checkboxes checked (in the above example, this would be
4731 @samp{[50%]} and @samp{[33%]}, respectively).  In a headline, a cookie can
4732 count either checkboxes below the heading or TODO states of children, and it
4733 will display whatever was changed last.  Set the property @code{COOKIE_DATA}
4734 to either @samp{checkbox} or @samp{todo} to resolve this issue.
4736 @cindex blocking, of checkboxes
4737 @cindex checkbox blocking
4738 @cindex property, ORDERED
4739 If the current outline node has an @code{ORDERED} property, checkboxes must
4740 be checked off in sequence, and an error will be thrown if you try to check
4741 off a box while there are unchecked boxes above it.
4743 @noindent The following commands work with checkboxes:
4745 @table @kbd
4746 @orgcmd{C-c C-c,org-toggle-checkbox}
4747 Toggle checkbox status or (with prefix arg) checkbox presence at point.
4748 With a single prefix argument, add an empty checkbox or remove the current
4749 one@footnote{@kbd{C-u C-c C-c} on the @emph{first} item of a list with no checkbox
4750 will add checkboxes to the rest of the list.}.  With a double prefix argument, set it to @samp{[-]}, which is
4751 considered to be an intermediate state.
4752 @orgcmd{C-c C-x C-b,org-toggle-checkbox}
4753 Toggle checkbox status or (with prefix arg) checkbox presence at point.  With
4754 double prefix argument, set it to @samp{[-]}, which is considered to be an
4755 intermediate state.
4756 @itemize @minus
4757 @item
4758 If there is an active region, toggle the first checkbox in the region
4759 and set all remaining boxes to the same status as the first.  With a prefix
4760 arg, add or remove the checkbox for all items in the region.
4761 @item
4762 If the cursor is in a headline, toggle checkboxes in the region between
4763 this headline and the next (so @emph{not} the entire subtree).
4764 @item
4765 If there is no active region, just toggle the checkbox at point.
4766 @end itemize
4767 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
4768 Insert a new item with a checkbox.  This works only if the cursor is already
4769 in a plain list item (@pxref{Plain lists}).
4770 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4771 @vindex org-track-ordered-property-with-tag
4772 @cindex property, ORDERED
4773 Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
4774 be checked off in sequence.  A property is used for this behavior because
4775 this should be local to the current entry, not inherited like a tag.
4776 However, if you would like to @i{track} the value of this property with a tag
4777 for better visibility, customize @code{org-track-ordered-property-with-tag}.
4778 @orgcmd{C-c #,org-update-statistics-cookies}
4779 Update the statistics cookie in the current outline entry.  When called with
4780 a @kbd{C-u} prefix, update the entire file.  Checkbox statistic cookies are
4781 updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
4782 new ones with @kbd{M-S-@key{RET}}.  TODO statistics cookies update when
4783 changing TODO states.  If you delete boxes/entries or add/change them by
4784 hand, use this command to get things back into sync.
4785 @end table
4787 @node Tags, Properties and Columns, TODO Items, Top
4788 @chapter Tags
4789 @cindex tags
4790 @cindex headline tagging
4791 @cindex matching, tags
4792 @cindex sparse tree, tag based
4794 An excellent way to implement labels and contexts for cross-correlating
4795 information is to assign @i{tags} to headlines.  Org mode has extensive
4796 support for tags.
4798 @vindex org-tag-faces
4799 Every headline can contain a list of tags; they occur at the end of the
4800 headline.  Tags are normal words containing letters, numbers, @samp{_}, and
4801 @samp{@@}.  Tags must be preceded and followed by a single colon, e.g.,
4802 @samp{:work:}.  Several tags can be specified, as in @samp{:work:urgent:}.
4803 Tags will by default be in bold face with the same color as the headline.
4804 You may specify special faces for specific tags using the option
4805 @code{org-tag-faces}, in much the same way as you can for TODO keywords
4806 (@pxref{Faces for TODO keywords}).
4808 @menu
4809 * Tag inheritance::             Tags use the tree structure of the outline
4810 * Setting tags::                How to assign tags to a headline
4811 * Tag groups::                  Use one tag to search for several tags
4812 * Tag searches::                Searching for combinations of tags
4813 @end menu
4815 @node Tag inheritance, Setting tags, Tags, Tags
4816 @section Tag inheritance
4817 @cindex tag inheritance
4818 @cindex inheritance, of tags
4819 @cindex sublevels, inclusion into tags match
4821 @i{Tags} make use of the hierarchical structure of outline trees.  If a
4822 heading has a certain tag, all subheadings will inherit the tag as
4823 well.  For example, in the list
4825 @example
4826 * Meeting with the French group      :work:
4827 ** Summary by Frank                  :boss:notes:
4828 *** TODO Prepare slides for him      :action:
4829 @end example
4831 @noindent
4832 the final heading will have the tags @samp{:work:}, @samp{:boss:},
4833 @samp{:notes:}, and @samp{:action:} even though the final heading is not
4834 explicitly marked with those tags.  You can also set tags that all entries in
4835 a file should inherit just as if these tags were defined in a hypothetical
4836 level zero that surrounds the entire file.  Use a line like this@footnote{As
4837 with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
4838 changes in the line.}:
4840 @cindex #+FILETAGS
4841 @example
4842 #+FILETAGS: :Peter:Boss:Secret:
4843 @end example
4845 @noindent
4846 @vindex org-use-tag-inheritance
4847 @vindex org-tags-exclude-from-inheritance
4848 To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
4849 To turn it off entirely, use @code{org-use-tag-inheritance}.
4851 @vindex org-tags-match-list-sublevels
4852 When a headline matches during a tags search while tag inheritance is turned
4853 on, all the sublevels in the same tree will (for a simple match form) match
4854 as well@footnote{This is only true if the search does not involve more
4855 complex tests including properties (@pxref{Property searches}).}.  The list
4856 of matches may then become very long.  If you only want to see the first tags
4857 match in a subtree, configure @code{org-tags-match-list-sublevels} (not
4858 recommended).
4860 @vindex org-agenda-use-tag-inheritance
4861 Tag inheritance is relevant when the agenda search tries to match a tag,
4862 either in the @code{tags} or @code{tags-todo} agenda types.  In other agenda
4863 types, @code{org-use-tag-inheritance} has no effect.  Still, you may want to
4864 have your tags correctly set in the agenda, so that tag filtering works fine,
4865 with inherited tags.  Set @code{org-agenda-use-tag-inheritance} to control
4866 this: the default value includes all agenda types, but setting this to @code{nil}
4867 can really speed up agenda generation.
4869 @node Setting tags, Tag groups, Tag inheritance, Tags
4870 @section Setting tags
4871 @cindex setting tags
4872 @cindex tags, setting
4874 @kindex M-@key{TAB}
4875 Tags can simply be typed into the buffer at the end of a headline.
4876 After a colon, @kbd{M-@key{TAB}} offers completion on tags.  There is
4877 also a special command for inserting tags:
4879 @table @kbd
4880 @orgcmd{C-c C-q,org-set-tags-command}
4881 @cindex completion, of tags
4882 @vindex org-tags-column
4883 Enter new tags for the current headline.  Org mode will either offer
4884 completion or a special single-key interface for setting tags, see
4885 below.  After pressing @key{RET}, the tags will be inserted and aligned
4886 to @code{org-tags-column}.  When called with a @kbd{C-u} prefix, all
4887 tags in the current buffer will be aligned to that column, just to make
4888 things look nice.  TAGS are automatically realigned after promotion,
4889 demotion, and TODO state changes (@pxref{TODO basics}).
4891 @orgcmd{C-c C-c,org-set-tags-command}
4892 When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
4893 @end table
4895 @vindex org-tag-alist
4896 Org supports tag insertion based on a @emph{list of tags}.  By
4897 default this list is constructed dynamically, containing all tags
4898 currently used in the buffer.  You may also globally specify a hard list
4899 of tags with the variable @code{org-tag-alist}.  Finally you can set
4900 the default tags for a given file with lines like
4902 @cindex #+TAGS
4903 @example
4904 #+TAGS: @@work @@home @@tennisclub
4905 #+TAGS: laptop car pc sailboat
4906 @end example
4908 If you have globally defined your preferred set of tags using the
4909 variable @code{org-tag-alist}, but would like to use a dynamic tag list
4910 in a specific file, add an empty TAGS option line to that file:
4912 @example
4913 #+TAGS:
4914 @end example
4916 @vindex org-tag-persistent-alist
4917 If you have a preferred set of tags that you would like to use in every file,
4918 in addition to those defined on a per-file basis by TAGS option lines, then
4919 you may specify a list of tags with the variable
4920 @code{org-tag-persistent-alist}.  You may turn this off on a per-file basis
4921 by adding a STARTUP option line to that file:
4923 @example
4924 #+STARTUP: noptag
4925 @end example
4927 By default Org mode uses the standard minibuffer completion facilities for
4928 entering tags.  However, it also implements another, quicker, tag selection
4929 method called @emph{fast tag selection}.  This allows you to select and
4930 deselect tags with just a single key press.  For this to work well you should
4931 assign unique letters to most of your commonly used tags.  You can do this
4932 globally by configuring the variable @code{org-tag-alist} in your
4933 @file{.emacs} file.  For example, you may find the need to tag many items in
4934 different files with @samp{:@@home:}.  In this case you can set something
4935 like:
4937 @lisp
4938 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
4939 @end lisp
4941 @noindent If the tag is only relevant to the file you are working on, then you
4942 can instead set the TAGS option line as:
4944 @example
4945 #+TAGS: @@work(w)  @@home(h)  @@tennisclub(t)  laptop(l)  pc(p)
4946 @end example
4948 @noindent The tags interface will show the available tags in a splash
4949 window.  If you want to start a new line after a specific tag, insert
4950 @samp{\n} into the tag list
4952 @example
4953 #+TAGS: @@work(w)  @@home(h)  @@tennisclub(t) \n laptop(l)  pc(p)
4954 @end example
4956 @noindent or write them in two lines:
4958 @example
4959 #+TAGS: @@work(w)  @@home(h)  @@tennisclub(t)
4960 #+TAGS: laptop(l)  pc(p)
4961 @end example
4963 @noindent
4964 You can also group together tags that are mutually exclusive by using
4965 braces, as in:
4967 @example
4968 #+TAGS: @{ @@work(w)  @@home(h)  @@tennisclub(t) @}  laptop(l)  pc(p)
4969 @end example
4971 @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
4972 and @samp{@@tennisclub} should be selected.  Multiple such groups are allowed.
4974 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
4975 these lines to activate any changes.
4977 @noindent
4978 To set these mutually exclusive groups in the variable @code{org-tag-alist},
4979 you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
4980 of the braces.  Similarly, you can use @code{:newline} to indicate a line
4981 break.  The previous example would be set globally by the following
4982 configuration:
4984 @lisp
4985 (setq org-tag-alist '((:startgroup . nil)
4986                       ("@@work" . ?w) ("@@home" . ?h)
4987                       ("@@tennisclub" . ?t)
4988                       (:endgroup . nil)
4989                       ("laptop" . ?l) ("pc" . ?p)))
4990 @end lisp
4992 If at least one tag has a selection key then pressing @kbd{C-c C-c} will
4993 automatically present you with a special interface, listing inherited tags,
4994 the tags of the current headline, and a list of all valid tags with
4995 corresponding keys@footnote{Keys will automatically be assigned to tags which
4996 have no configured keys.}.  In this interface, you can use the following
4997 keys:
4999 @table @kbd
5000 @item a-z...
5001 Pressing keys assigned to tags will add or remove them from the list of
5002 tags in the current line.  Selecting a tag in a group of mutually
5003 exclusive tags will turn off any other tags from that group.
5004 @kindex @key{TAB}
5005 @item @key{TAB}
5006 Enter a tag in the minibuffer, even if the tag is not in the predefined
5007 list.  You will be able to complete on all tags present in the buffer.
5008 You can also add several tags: just separate them with a comma.
5010 @kindex @key{SPC}
5011 @item @key{SPC}
5012 Clear all tags for this line.
5013 @kindex @key{RET}
5014 @item @key{RET}
5015 Accept the modified set.
5016 @item C-g
5017 Abort without installing changes.
5018 @item q
5019 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
5020 @item !
5021 Turn off groups of mutually exclusive tags.  Use this to (as an
5022 exception) assign several tags from such a group.
5023 @item C-c
5024 Toggle auto-exit after the next change (see below).
5025 If you are using expert mode, the first @kbd{C-c} will display the
5026 selection window.
5027 @end table
5029 @noindent
5030 This method lets you assign tags to a headline with very few keys.  With
5031 the above setup, you could clear the current tags and set @samp{@@home},
5032 @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
5033 C-c @key{SPC} h l p @key{RET}}.  Switching from @samp{@@home} to
5034 @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
5035 alternatively with @kbd{C-c C-c C-c w}.  Adding the non-predefined tag
5036 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
5037 @key{RET} @key{RET}}.
5039 @vindex org-fast-tag-selection-single-key
5040 If you find that most of the time you need only a single key press to
5041 modify your list of tags, set @code{org-fast-tag-selection-single-key}.
5042 Then you no longer have to press @key{RET} to exit fast tag selection---it
5043 will immediately exit after the first change.  If you then occasionally
5044 need more keys, press @kbd{C-c} to turn off auto-exit for the current tag
5045 selection process (in effect: start selection with @kbd{C-c C-c C-c}
5046 instead of @kbd{C-c C-c}).  If you set the variable to the value
5047 @code{expert}, the special window is not even shown for single-key tag
5048 selection, it comes up only when you press an extra @kbd{C-c}.
5050 @node Tag groups, Tag searches, Setting tags, Tags
5051 @section Tag groups
5053 @cindex group tags
5054 @cindex tags, groups
5055 In a set of mutually exclusive tags, the first tag can be defined as a
5056 @emph{group tag}.  When you search for a group tag, it will return matches
5057 for all members in the group.  In an agenda view, filtering by a group tag
5058 will display headlines tagged with at least one of the members of the
5059 group.  This makes tag searches and filters even more flexible.
5061 You can set group tags by inserting a colon between the group tag and other
5062 tags---beware that all whitespaces are mandatory so that Org can parse this
5063 line correctly:
5065 @example
5066 #+TAGS: @{ @@read : @@read_book @@read_ebook @}
5067 @end example
5069 In this example, @samp{@@read} is a @emph{group tag} for a set of three
5070 tags: @samp{@@read}, @samp{@@read_book} and @samp{@@read_ebook}.
5072 You can also use the @code{:grouptags} keyword directly when setting
5073 @code{org-tag-alist}:
5075 @lisp
5076 (setq org-tag-alist '((:startgroup . nil)
5077                       ("@@read" . nil)
5078                       (:grouptags . nil)
5079                       ("@@read_book" . nil)
5080                       ("@@read_ebook" . nil)
5081                       (:endgroup . nil)))
5082 @end lisp
5084 You cannot nest group tags or use a group tag as a tag in another group.
5086 @kindex C-c C-x q
5087 @vindex org-group-tags
5088 If you want to ignore group tags temporarily, toggle group tags support
5089 with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}.  If you
5090 want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
5092 @node Tag searches,  , Tag groups, Tags
5093 @section Tag searches
5094 @cindex tag searches
5095 @cindex searching for tags
5097 Once a system of tags has been set up, it can be used to collect related
5098 information into special lists.
5100 @table @kbd
5101 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5102 Create a sparse tree with all headlines matching a tags/property/TODO search.
5103 With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5104 @xref{Matching tags and properties}.
5105 @orgcmd{C-c a m,org-tags-view}
5106 Create a global list of tag matches from all agenda files.  @xref{Matching
5107 tags and properties}.
5108 @orgcmd{C-c a M,org-tags-view}
5109 @vindex org-tags-match-list-sublevels
5110 Create a global list of tag matches from all agenda files, but check
5111 only TODO items and force checking subitems (see the option
5112 @code{org-tags-match-list-sublevels}).
5113 @end table
5115 These commands all prompt for a match string which allows basic Boolean logic
5116 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
5117 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
5118 which are tagged, like @samp{Kathy} or @samp{Sally}.  The full syntax of the search
5119 string is rich and allows also matching against TODO keywords, entry levels
5120 and properties.  For a complete description with many examples, see
5121 @ref{Matching tags and properties}.
5124 @node Properties and Columns, Dates and Times, Tags, Top
5125 @chapter Properties and columns
5126 @cindex properties
5128 A property is a key-value pair associated with an entry.  Properties can be
5129 set so they are associated with a single entry, with every entry in a tree,
5130 or with every entry in an Org mode file.
5132 There are two main applications for properties in Org mode.  First,
5133 properties are like tags, but with a value.  Imagine maintaining a file where
5134 you document bugs and plan releases for a piece of software.  Instead of
5135 using tags like @code{:release_1:}, @code{:release_2:}, you can use a
5136 property, say @code{:Release:}, that in different subtrees has different
5137 values, such as @code{1.0} or @code{2.0}.  Second, you can use properties to
5138 implement (very basic) database capabilities in an Org buffer.  Imagine
5139 keeping track of your music CDs, where properties could be things such as the
5140 album, artist, date of release, number of tracks, and so on.
5142 Properties can be conveniently edited and viewed in column view
5143 (@pxref{Column view}).
5145 @menu
5146 * Property syntax::             How properties are spelled out
5147 * Special properties::          Access to other Org mode features
5148 * Property searches::           Matching property values
5149 * Property inheritance::        Passing values down the tree
5150 * Column view::                 Tabular viewing and editing
5151 * Property API::                Properties for Lisp programmers
5152 @end menu
5154 @node Property syntax, Special properties, Properties and Columns, Properties and Columns
5155 @section Property syntax
5156 @cindex property syntax
5157 @cindex drawer, for properties
5159 Properties are key-value pairs.  When they are associated with a single entry
5160 or with a tree they need to be inserted into a special
5161 drawer (@pxref{Drawers}) with the name @code{PROPERTIES}.  Each property
5162 is specified on a single line, with the key (surrounded by colons)
5163 first, and the value after it.  Here is an example:
5165 @example
5166 * CD collection
5167 ** Classic
5168 *** Goldberg Variations
5169     :PROPERTIES:
5170     :Title:     Goldberg Variations
5171     :Composer:  J.S. Bach
5172     :Artist:    Glen Gould
5173     :Publisher: Deutsche Grammophon
5174     :NDisks:    1
5175     :END:
5176 @end example
5178 Depending on the value of @code{org-use-property-inheritance}, a property set
5179 this way will either be associated with a single entry, or the sub-tree
5180 defined by the entry, see @ref{Property inheritance}.
5182 You may define the allowed values for a particular property @samp{:Xyz:}
5183 by setting a property @samp{:Xyz_ALL:}.  This special property is
5184 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
5185 the entire tree.  When allowed values are defined, setting the
5186 corresponding property becomes easier and is less prone to typing
5187 errors.  For the example with the CD collection, we can predefine
5188 publishers and the number of disks in a box like this:
5190 @example
5191 * CD collection
5192   :PROPERTIES:
5193   :NDisks_ALL:  1 2 3 4
5194   :Publisher_ALL: "Deutsche Grammophon" Philips EMI
5195   :END:
5196 @end example
5198 If you want to set properties that can be inherited by any entry in a
5199 file, use a line like
5200 @cindex property, _ALL
5201 @cindex #+PROPERTY
5202 @example
5203 #+PROPERTY: NDisks_ALL 1 2 3 4
5204 @end example
5206 Contrary to properties set from a special drawer, you have to refresh the
5207 buffer with @kbd{C-c C-c} to activate this changes.
5209 If you want to add to the value of an existing property, append a @code{+} to
5210 the property name.  The following results in the property @code{var} having
5211 the value ``foo=1 bar=2''.
5212 @cindex property, +
5213 @example
5214 #+PROPERTY: var  foo=1
5215 #+PROPERTY: var+ bar=2
5216 @end example
5218 It is also possible to add to the values of inherited properties.  The
5219 following results in the @code{genres} property having the value ``Classic
5220 Baroque'' under the @code{Goldberg Variations} subtree.
5221 @cindex property, +
5222 @example
5223 * CD collection
5224 ** Classic
5225     :PROPERTIES:
5226     :GENRES: Classic
5227     :END:
5228 *** Goldberg Variations
5229     :PROPERTIES:
5230     :Title:     Goldberg Variations
5231     :Composer:  J.S. Bach
5232     :Artist:    Glen Gould
5233     :Publisher: Deutsche Grammophon
5234     :NDisks:    1
5235     :GENRES+:   Baroque
5236     :END:
5237 @end example
5238 Note that a property can only have one entry per Drawer.
5240 @vindex org-global-properties
5241 Property values set with the global variable
5242 @code{org-global-properties} can be inherited by all entries in all
5243 Org files.
5245 @noindent
5246 The following commands help to work with properties:
5248 @table @kbd
5249 @orgcmd{M-@key{TAB},pcomplete}
5250 After an initial colon in a line, complete property keys.  All keys used
5251 in the current file will be offered as possible completions.
5252 @orgcmd{C-c C-x p,org-set-property}
5253 Set a property.  This prompts for a property name and a value.  If
5254 necessary, the property drawer is created as well.
5255 @item C-u M-x org-insert-drawer RET
5256 @cindex org-insert-drawer
5257 Insert a property drawer into the current entry.  The drawer will be
5258 inserted early in the entry, but after the lines with planning
5259 information like deadlines.
5260 @orgcmd{C-c C-c,org-property-action}
5261 With the cursor in a property drawer, this executes property commands.
5262 @orgcmd{C-c C-c s,org-set-property}
5263 Set a property in the current entry.  Both the property and the value
5264 can be inserted using completion.
5265 @orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
5266 Switch property at point to the next/previous allowed value.
5267 @orgcmd{C-c C-c d,org-delete-property}
5268 Remove a property from the current entry.
5269 @orgcmd{C-c C-c D,org-delete-property-globally}
5270 Globally remove a property, from all entries in the current file.
5271 @orgcmd{C-c C-c c,org-compute-property-at-point}
5272 Compute the property at point, using the operator and scope from the
5273 nearest column format definition.
5274 @end table
5276 @node Special properties, Property searches, Property syntax, Properties and Columns
5277 @section Special properties
5278 @cindex properties, special
5280 Special properties provide an alternative access method to Org mode features,
5281 like the TODO state or the priority of an entry, discussed in the previous
5282 chapters.  This interface exists so that you can include these states in a
5283 column view (@pxref{Column view}), or to use them in queries.  The following
5284 property names are special and (except for @code{:CATEGORY:}) should not be
5285 used as keys in the properties drawer:
5287 @cindex property, special, ID
5288 @cindex property, special, TODO
5289 @cindex property, special, TAGS
5290 @cindex property, special, ALLTAGS
5291 @cindex property, special, CATEGORY
5292 @cindex property, special, PRIORITY
5293 @cindex property, special, DEADLINE
5294 @cindex property, special, SCHEDULED
5295 @cindex property, special, CLOSED
5296 @cindex property, special, TIMESTAMP
5297 @cindex property, special, TIMESTAMP_IA
5298 @cindex property, special, CLOCKSUM
5299 @cindex property, special, CLOCKSUM_T
5300 @cindex property, special, BLOCKED
5301 @c guessing that ITEM is needed in this area; also, should this list be sorted?
5302 @cindex property, special, ITEM
5303 @cindex property, special, FILE
5304 @example
5305 ID           @r{A globally unique ID used for synchronization during}
5306              @r{iCalendar or MobileOrg export.}
5307 TODO         @r{The TODO keyword of the entry.}
5308 TAGS         @r{The tags defined directly in the headline.}
5309 ALLTAGS      @r{All tags, including inherited ones.}
5310 CATEGORY     @r{The category of an entry.}
5311 PRIORITY     @r{The priority of the entry, a string with a single letter.}
5312 DEADLINE     @r{The deadline time string, without the angular brackets.}
5313 SCHEDULED    @r{The scheduling timestamp, without the angular brackets.}
5314 CLOSED       @r{When was this entry closed?}
5315 TIMESTAMP    @r{The first keyword-less timestamp in the entry.}
5316 TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
5317 CLOCKSUM     @r{The sum of CLOCK intervals in the subtree.  @code{org-clock-sum}}
5318              @r{must be run first to compute the values in the current buffer.}
5319 CLOCKSUM_T   @r{The sum of CLOCK intervals in the subtree for today.}
5320              @r{@code{org-clock-sum-today} must be run first to compute the}
5321              @r{values in the current buffer.}
5322 BLOCKED      @r{"t" if task is currently blocked by children or siblings}
5323 ITEM         @r{The headline of the entry.}
5324 FILE         @r{The filename the entry is located in.}
5325 @end example
5327 @node Property searches, Property inheritance, Special properties, Properties and Columns
5328 @section Property searches
5329 @cindex properties, searching
5330 @cindex searching, of properties
5332 To create sparse trees and special lists with selection based on properties,
5333 the same commands are used as for tag searches (@pxref{Tag searches}).
5335 @table @kbd
5336 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
5337 Create a sparse tree with all matching entries.  With a
5338 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
5339 @orgcmd{C-c a m,org-tags-view}
5340 Create a global list of tag/property  matches from all agenda files.
5341 @xref{Matching tags and properties}.
5342 @orgcmd{C-c a M,org-tags-view}
5343 @vindex org-tags-match-list-sublevels
5344 Create a global list of tag matches from all agenda files, but check
5345 only TODO items and force checking of subitems (see the option
5346 @code{org-tags-match-list-sublevels}).
5347 @end table
5349 The syntax for the search string is described in @ref{Matching tags and
5350 properties}.
5352 There is also a special command for creating sparse trees based on a
5353 single property:
5355 @table @kbd
5356 @orgkey{C-c / p}
5357 Create a sparse tree based on the value of a property.  This first
5358 prompts for the name of a property, and then for a value.  A sparse tree
5359 is created with all entries that define this property with the given
5360 value.  If you enclose the value in curly braces, it is interpreted as
5361 a regular expression and matched against the property values.
5362 @end table
5364 @node Property inheritance, Column view, Property searches, Properties and Columns
5365 @section Property Inheritance
5366 @cindex properties, inheritance
5367 @cindex inheritance, of properties
5369 @vindex org-use-property-inheritance
5370 The outline structure of Org mode documents lends itself to an
5371 inheritance model of properties: if the parent in a tree has a certain
5372 property, the children can inherit this property.  Org mode does not
5373 turn this on by default, because it can slow down property searches
5374 significantly and is often not needed.  However, if you find inheritance
5375 useful, you can turn it on by setting the variable
5376 @code{org-use-property-inheritance}.  It may be set to @code{t} to make
5377 all properties inherited from the parent, to a list of properties
5378 that should be inherited, or to a regular expression that matches
5379 inherited properties.  If a property has the value @code{nil}, this is
5380 interpreted as an explicit undefine of the property, so that inheritance
5381 search will stop at this value and return @code{nil}.
5383 Org mode has a few properties for which inheritance is hard-coded, at
5384 least for the special applications for which they are used:
5386 @cindex property, COLUMNS
5387 @table @code
5388 @item COLUMNS
5389 The @code{:COLUMNS:} property defines the format of column view
5390 (@pxref{Column view}).  It is inherited in the sense that the level
5391 where a @code{:COLUMNS:} property is defined is used as the starting
5392 point for a column view table, independently of the location in the
5393 subtree from where columns view is turned on.
5394 @item CATEGORY
5395 @cindex property, CATEGORY
5396 For agenda view, a category set through a @code{:CATEGORY:} property
5397 applies to the entire subtree.
5398 @item ARCHIVE
5399 @cindex property, ARCHIVE
5400 For archiving, the @code{:ARCHIVE:} property may define the archive
5401 location for the entire subtree (@pxref{Moving subtrees}).
5402 @item LOGGING
5403 @cindex property, LOGGING
5404 The LOGGING property may define logging settings for an entry or a
5405 subtree (@pxref{Tracking TODO state changes}).
5406 @end table
5408 @node Column view, Property API, Property inheritance, Properties and Columns
5409 @section Column view
5411 A great way to view and edit properties in an outline tree is
5412 @emph{column view}.  In column view, each outline node is turned into a
5413 table row.  Columns in this table provide access to properties of the
5414 entries.  Org mode implements columns by overlaying a tabular structure
5415 over the headline of each item.  While the headlines have been turned
5416 into a table row, you can still change the visibility of the outline
5417 tree.  For example, you get a compact table by switching to CONTENTS
5418 view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
5419 is active), but you can still open, read, and edit the entry below each
5420 headline.  Or, you can switch to column view after executing a sparse
5421 tree command and in this way get a table only for the selected items.
5422 Column view also works in agenda buffers (@pxref{Agenda Views}) where
5423 queries have collected selected items, possibly from a number of files.
5425 @menu
5426 * Defining columns::            The COLUMNS format property
5427 * Using column view::           How to create and use column view
5428 * Capturing column view::       A dynamic block for column view
5429 @end menu
5431 @node Defining columns, Using column view, Column view, Column view
5432 @subsection Defining columns
5433 @cindex column view, for properties
5434 @cindex properties, column view
5436 Setting up a column view first requires defining the columns.  This is
5437 done by defining a column format line.
5439 @menu
5440 * Scope of column definitions::  Where defined, where valid?
5441 * Column attributes::           Appearance and content of a column
5442 @end menu
5444 @node Scope of column definitions, Column attributes, Defining columns, Defining columns
5445 @subsubsection Scope of column definitions
5447 To define a column format for an entire file, use a line like
5449 @cindex #+COLUMNS
5450 @example
5451 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5452 @end example
5454 To specify a format that only applies to a specific tree, add a
5455 @code{:COLUMNS:} property to the top node of that tree, for example:
5457 @example
5458 ** Top node for columns view
5459    :PROPERTIES:
5460    :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
5461    :END:
5462 @end example
5464 If a @code{:COLUMNS:} property is present in an entry, it defines columns
5465 for the entry itself, and for the entire subtree below it.  Since the
5466 column definition is part of the hierarchical structure of the document,
5467 you can define columns on level 1 that are general enough for all
5468 sublevels, and more specific columns further down, when you edit a
5469 deeper part of the tree.
5471 @node Column attributes,  , Scope of column definitions, Defining columns
5472 @subsubsection Column attributes
5473 A column definition sets the attributes of a column.  The general
5474 definition looks like this:
5476 @example
5477  %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]
5478 @end example
5480 @noindent
5481 Except for the percent sign and the property name, all items are
5482 optional.  The individual parts have the following meaning:
5484 @example
5485 @var{width}           @r{An integer specifying the width of the column in characters.}
5486                 @r{If omitted, the width will be determined automatically.}
5487 @var{property}        @r{The property that should be edited in this column.}
5488                 @r{Special properties representing meta data are allowed here}
5489                 @r{as well (@pxref{Special properties})}
5490 @var{title}           @r{The header text for the column.  If omitted, the property}
5491                 @r{name is used.}
5492 @{@var{summary-type}@}  @r{The summary type.  If specified, the column values for}
5493                 @r{parent nodes are computed from the children.}
5494                 @r{Supported summary types are:}
5495                 @{+@}       @r{Sum numbers in this column.}
5496                 @{+;%.1f@}  @r{Like @samp{+}, but format result with @samp{%.1f}.}
5497                 @{$@}       @r{Currency, short for @samp{+;%.2f}.}
5498                 @{:@}       @r{Sum times, HH:MM, plain numbers are hours.}
5499                 @{X@}       @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
5500                 @{X/@}      @r{Checkbox status, @samp{[n/m]}.}
5501                 @{X%@}      @r{Checkbox status, @samp{[n%]}.}
5502                 @{min@}     @r{Smallest number in column.}
5503                 @{max@}     @r{Largest number.}
5504                 @{mean@}    @r{Arithmetic mean of numbers.}
5505                 @{:min@}    @r{Smallest time value in column.}
5506                 @{:max@}    @r{Largest time value.}
5507                 @{:mean@}   @r{Arithmetic mean of time values.}
5508                 @{@@min@}    @r{Minimum age (in days/hours/mins/seconds).}
5509                 @{@@max@}    @r{Maximum age (in days/hours/mins/seconds).}
5510                 @{@@mean@}   @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
5511                 @{est+@}    @r{Add low-high estimates.}
5512 @end example
5514 @noindent
5515 Be aware that you can only have one summary type for any property you
5516 include.  Subsequent columns referencing the same property will all display the
5517 same summary information.
5519 The @code{est+} summary type requires further explanation.  It is used for
5520 combining estimates, expressed as low-high ranges.  For example, instead
5521 of estimating a particular task will take 5 days, you might estimate it as
5522 5--6 days if you're fairly confident you know how much work is required, or
5523 1--10 days if you don't really know what needs to be done.  Both ranges
5524 average at 5.5 days, but the first represents a more predictable delivery.
5526 When combining a set of such estimates, simply adding the lows and highs
5527 produces an unrealistically wide result.  Instead, @code{est+} adds the
5528 statistical mean and variance of the sub-tasks, generating a final estimate
5529 from the sum.  For example, suppose you had ten tasks, each of which was
5530 estimated at 0.5 to 2 days of work.  Straight addition produces an estimate
5531 of 5 to 20 days, representing what to expect if everything goes either
5532 extremely well or extremely poorly.  In contrast, @code{est+} estimates the
5533 full job more realistically, at 10--15 days.
5535 Numbers are right-aligned when a format specifier with an explicit width like
5536 @code{%5d} or @code{%5.1f} is used.
5538 Here is an example for a complete columns definition, along with allowed
5539 values.
5541 @example
5542 :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.}
5543                    %10Time_Estimate@{:@} %CLOCKSUM %CLOCKSUM_T
5544 :Owner_ALL:    Tammy Mark Karl Lisa Don
5545 :Status_ALL:   "In progress" "Not started yet" "Finished" ""
5546 :Approved_ALL: "[ ]" "[X]"
5547 @end example
5549 @noindent
5550 The first column, @samp{%25ITEM}, means the first 25 characters of the
5551 item itself, i.e., of the headline.  You probably always should start the
5552 column definition with the @samp{ITEM} specifier.  The other specifiers
5553 create columns @samp{Owner} with a list of names as allowed values, for
5554 @samp{Status} with four different possible values, and for a checkbox
5555 field @samp{Approved}.  When no width is given after the @samp{%}
5556 character, the column will be exactly as wide as it needs to be in order
5557 to fully display all values.  The @samp{Approved} column does have a
5558 modified title (@samp{Approved?}, with a question mark).  Summaries will
5559 be created for the @samp{Time_Estimate} column by adding time duration
5560 expressions like HH:MM, and for the @samp{Approved} column, by providing
5561 an @samp{[X]} status if all children have been checked.  The
5562 @samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns are special, they lists the
5563 sums of CLOCK intervals in the subtree, either for all clocks or just for
5564 today.
5566 @node Using column view, Capturing column view, Defining columns, Column view
5567 @subsection Using column view
5569 @table @kbd
5570 @tsubheading{Turning column view on and off}
5571 @orgcmd{C-c C-x C-c,org-columns}
5572 @vindex org-columns-default-format
5573 Turn on column view.  If the cursor is before the first headline in the file,
5574 column view is turned on for the entire file, using the @code{#+COLUMNS}
5575 definition.  If the cursor is somewhere inside the outline, this command
5576 searches the hierarchy, up from point, for a @code{:COLUMNS:} property that
5577 defines a format.  When one is found, the column view table is established
5578 for the tree starting at the entry that contains the @code{:COLUMNS:}
5579 property.  If no such property is found, the format is taken from the
5580 @code{#+COLUMNS} line or from the variable @code{org-columns-default-format},
5581 and column view is established for the current entry and its subtree.
5582 @orgcmd{r,org-columns-redo}
5583 Recreate the column view, to include recent changes made in the buffer.
5584 @orgcmd{g,org-columns-redo}
5585 Same as @kbd{r}.
5586 @orgcmd{q,org-columns-quit}
5587 Exit column view.
5588 @tsubheading{Editing values}
5589 @item @key{left} @key{right} @key{up} @key{down}
5590 Move through the column view from field to field.
5591 @kindex S-@key{left}
5592 @kindex S-@key{right}
5593 @item  S-@key{left}/@key{right}
5594 Switch to the next/previous allowed value of the field.  For this, you
5595 have to have specified allowed values for a property.
5596 @item 1..9,0
5597 Directly select the Nth allowed value, @kbd{0} selects the 10th value.
5598 @orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value}
5599 Same as @kbd{S-@key{left}/@key{right}}
5600 @orgcmd{e,org-columns-edit-value}
5601 Edit the property at point.  For the special properties, this will
5602 invoke the same interface that you normally use to change that
5603 property.  For example, when editing a TAGS property, the tag completion
5604 or fast selection interface will pop up.
5605 @orgcmd{C-c C-c,org-columns-set-tags-or-toggle}
5606 When there is a checkbox at point, toggle it.
5607 @orgcmd{v,org-columns-show-value}
5608 View the full value of this property.  This is useful if the width of
5609 the column is smaller than that of the value.
5610 @orgcmd{a,org-columns-edit-allowed}
5611 Edit the list of allowed values for this property.  If the list is found
5612 in the hierarchy, the modified values is stored there.  If no list is
5613 found, the new value is stored in the first entry that is part of the
5614 current column view.
5615 @tsubheading{Modifying the table structure}
5616 @orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen}
5617 Make the column narrower/wider by one character.
5618 @orgcmd{S-M-@key{right},org-columns-new}
5619 Insert a new column, to the left of the current column.
5620 @orgcmd{S-M-@key{left},org-columns-delete}
5621 Delete the current column.
5622 @end table
5624 @node Capturing column view,  , Using column view, Column view
5625 @subsection Capturing column view
5627 Since column view is just an overlay over a buffer, it cannot be
5628 exported or printed directly.  If you want to capture a column view, use
5629 a @code{columnview} dynamic block (@pxref{Dynamic blocks}).  The frame
5630 of this block looks like this:
5632 @cindex #+BEGIN, columnview
5633 @example
5634 * The column view
5635 #+BEGIN: columnview :hlines 1 :id "label"
5637 #+END:
5638 @end example
5640 @noindent This dynamic block has the following parameters:
5642 @table @code
5643 @item :id
5644 This is the most important parameter.  Column view is a feature that is
5645 often localized to a certain (sub)tree, and the capture block might be
5646 at a different location in the file.  To identify the tree whose view to
5647 capture, you can use 4 values:
5648 @cindex property, ID
5649 @example
5650 local     @r{use the tree in which the capture block is located}
5651 global    @r{make a global view, including all headings in the file}
5652 "file:@var{path-to-file}"
5653           @r{run column view at the top of this file}
5654 "@var{ID}"      @r{call column view in the tree that has an @code{:ID:}}
5655           @r{property with the value @i{label}.  You can use}
5656           @r{@kbd{M-x org-id-copy RET} to create a globally unique ID for}
5657           @r{the current entry and copy it to the kill-ring.}
5658 @end example
5659 @item :hlines
5660 When @code{t}, insert an hline after every line.  When a number @var{N}, insert
5661 an hline before each headline with level @code{<= @var{N}}.
5662 @item :vlines
5663 When set to @code{t}, force column groups to get vertical lines.
5664 @item :maxlevel
5665 When set to a number, don't capture entries below this level.
5666 @item :skip-empty-rows
5667 When set to @code{t}, skip rows where the only non-empty specifier of the
5668 column view is @code{ITEM}.
5670 @end table
5672 @noindent
5673 The following commands insert or update the dynamic block:
5675 @table @kbd
5676 @orgcmd{C-c C-x i,org-insert-columns-dblock}
5677 Insert a dynamic block capturing a column view.  You will be prompted
5678 for the scope or ID of the view.
5679 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
5680 Update dynamic block at point.  The cursor needs to be in the
5681 @code{#+BEGIN} line of the dynamic block.
5682 @orgcmd{C-u C-c C-x C-u,org-update-all-dblocks}
5683 Update all dynamic blocks (@pxref{Dynamic blocks}).  This is useful if
5684 you have several clock table blocks, column-capturing blocks or other dynamic
5685 blocks in a buffer.
5686 @end table
5688 You can add formulas to the column view table and you may add plotting
5689 instructions in front of the table---these will survive an update of the
5690 block.  If there is a @code{#+TBLFM:} after the table, the table will
5691 actually be recalculated automatically after an update.
5693 An alternative way to capture and process property values into a table is
5694 provided by Eric Schulte's @file{org-collector.el} which is a contributed
5695 package@footnote{Contributed packages are not part of Emacs, but are
5696 distributed with the main distribution of Org (visit
5697 @uref{http://orgmode.org}).}.  It provides a general API to collect
5698 properties from entries in a certain scope, and arbitrary Lisp expressions to
5699 process these values before inserting them into a table or a dynamic block.
5701 @node Property API,  , Column view, Properties and Columns
5702 @section The Property API
5703 @cindex properties, API
5704 @cindex API, for properties
5706 There is a full API for accessing and changing properties.  This API can
5707 be used by Emacs Lisp programs to work with properties and to implement
5708 features based on them.  For more information see @ref{Using the
5709 property API}.
5711 @node Dates and Times, Capture - Refile - Archive, Properties and Columns, Top
5712 @chapter Dates and times
5713 @cindex dates
5714 @cindex times
5715 @cindex timestamp
5716 @cindex date stamp
5718 To assist project planning, TODO items can be labeled with a date and/or
5719 a time.  The specially formatted string carrying the date and time
5720 information is called a @emph{timestamp} in Org mode.  This may be a
5721 little confusing because timestamp is often used as indicating when
5722 something was created or last changed.  However, in Org mode this term
5723 is used in a much wider sense.
5725 @menu
5726 * Timestamps::                  Assigning a time to a tree entry
5727 * Creating timestamps::         Commands which insert timestamps
5728 * Deadlines and scheduling::    Planning your work
5729 * Clocking work time::          Tracking how long you spend on a task
5730 * Effort estimates::            Planning work effort in advance
5731 * Relative timer::              Notes with a running timer
5732 * Countdown timer::             Starting a countdown timer for a task
5733 @end menu
5736 @node Timestamps, Creating timestamps, Dates and Times, Dates and Times
5737 @section Timestamps, deadlines, and scheduling
5738 @cindex timestamps
5739 @cindex ranges, time
5740 @cindex date stamps
5741 @cindex deadlines
5742 @cindex scheduling
5744 A timestamp is a specification of a date (possibly with a time or a range of
5745 times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this
5746 simplest form, the day name is optional when you type the date yourself.
5747 However, any dates inserted or modified by Org will add that day name, for
5748 reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16
5749 Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601
5750 date/time format.  To use an alternative format, see @ref{Custom time
5751 format}.}.  A timestamp can appear anywhere in the headline or body of an Org
5752 tree entry.  Its presence causes entries to be shown on specific dates in the
5753 agenda (@pxref{Weekly/daily agenda}).  We distinguish:
5755 @table @var
5756 @item Plain timestamp; Event; Appointment
5757 @cindex timestamp
5758 @cindex appointment
5759 A simple timestamp just assigns a date/time to an item.  This is just
5760 like writing down an appointment or event in a paper agenda.  In the
5761 timeline and agenda displays, the headline of an entry associated with a
5762 plain timestamp will be shown exactly on that date.
5764 @example
5765 * Meet Peter at the movies
5766   <2006-11-01 Wed 19:15>
5767 * Discussion on climate change
5768   <2006-11-02 Thu 20:00-22:00>
5769 @end example
5771 @item Timestamp with repeater interval
5772 @cindex timestamp, with repeater interval
5773 A timestamp may contain a @emph{repeater interval}, indicating that it
5774 applies not only on the given date, but again and again after a certain
5775 interval of N days (d), weeks (w), months (m), or years (y).  The
5776 following will show up in the agenda every Wednesday:
5778 @example
5779 * Pick up Sam at school
5780   <2007-05-16 Wed 12:30 +1w>
5781 @end example
5783 @item Diary-style sexp entries
5784 For more complex date specifications, Org mode supports using the special
5785 sexp diary entries implemented in the Emacs calendar/diary
5786 package@footnote{When working with the standard diary sexp functions, you
5787 need to be very careful with the order of the arguments.  That order depend
5788 evilly on the variable @code{calendar-date-style} (or, for older Emacs
5789 versions, @code{european-calendar-style}).  For example, to specify a date
5790 December 12, 2005, the call might look like @code{(diary-date 12 1 2005)} or
5791 @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
5792 the settings.  This has been the source of much confusion.  Org mode users
5793 can resort to special versions of these functions like @code{org-date} or
5794 @code{org-anniversary}.  These work just like the corresponding @code{diary-}
5795 functions, but with stable ISO order of arguments (year, month, day) wherever
5796 applicable, independent of the value of @code{calendar-date-style}.}.  For
5797 example with optional time
5799 @example
5800 * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
5801   <%%(diary-float t 4 2)>
5802 @end example
5804 @item Time/Date range
5805 @cindex timerange
5806 @cindex date range
5807 Two timestamps connected by @samp{--} denote a range.  The headline
5808 will be shown on the first and last day of the range, and on any dates
5809 that are displayed and fall in the range.  Here is an example:
5811 @example
5812 ** Meeting in Amsterdam
5813    <2004-08-23 Mon>--<2004-08-26 Thu>
5814 @end example
5816 @item Inactive timestamp
5817 @cindex timestamp, inactive
5818 @cindex inactive timestamp
5819 Just like a plain timestamp, but with square brackets instead of
5820 angular ones.  These timestamps are inactive in the sense that they do
5821 @emph{not} trigger an entry to show up in the agenda.
5823 @example
5824 * Gillian comes late for the fifth time
5825   [2006-11-01 Wed]
5826 @end example
5828 @end table
5830 @node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times
5831 @section Creating timestamps
5832 @cindex creating timestamps
5833 @cindex timestamps, creating
5835 For Org mode to recognize timestamps, they need to be in the specific
5836 format.  All commands listed below produce timestamps in the correct
5837 format.
5839 @table @kbd
5840 @orgcmd{C-c .,org-time-stamp}
5841 Prompt for a date and insert a corresponding timestamp.  When the cursor is
5842 at an existing timestamp in the buffer, the command is used to modify this
5843 timestamp instead of inserting a new one.  When this command is used twice in
5844 succession, a time range is inserted.
5846 @orgcmd{C-c !,org-time-stamp-inactive}
5847 Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
5848 an agenda entry.
5850 @kindex C-u C-c .
5851 @kindex C-u C-c !
5852 @item C-u C-c .
5853 @itemx C-u C-c !
5854 @vindex org-time-stamp-rounding-minutes
5855 Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which
5856 contains date and time.  The default time can be rounded to multiples of 5
5857 minutes, see the option @code{org-time-stamp-rounding-minutes}.
5859 @orgkey{C-c C-c}
5860 Normalize timestamp, insert/fix day name if missing or wrong.
5862 @orgcmd{C-c <,org-date-from-calendar}
5863 Insert a timestamp corresponding to the cursor date in the Calendar.
5865 @orgcmd{C-c >,org-goto-calendar}
5866 Access the Emacs calendar for the current date.  If there is a
5867 timestamp in the current line, go to the corresponding date
5868 instead.
5870 @orgcmd{C-c C-o,org-open-at-point}
5871 Access the agenda for the date given by the timestamp or -range at
5872 point (@pxref{Weekly/daily agenda}).
5874 @orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day}
5875 Change date at cursor by one day.  These key bindings conflict with
5876 shift-selection and related modes (@pxref{Conflicts}).
5878 @orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down}
5879 Change the item under the cursor in a timestamp.  The cursor can be on a
5880 year, month, day, hour or minute.  When the timestamp contains a time range
5881 like @samp{15:30-16:30}, modifying the first time will also shift the second,
5882 shifting the time block with constant length.  To change the length, modify
5883 the second time.  Note that if the cursor is in a headline and not at a
5884 timestamp, these same keys modify the priority of an item.
5885 (@pxref{Priorities}).  The key bindings also conflict with shift-selection and
5886 related modes (@pxref{Conflicts}).
5888 @orgcmd{C-c C-y,org-evaluate-time-range}
5889 @cindex evaluate time range
5890 Evaluate a time range by computing the difference between start and end.
5891 With a prefix argument, insert result after the time range (in a table: into
5892 the following column).
5893 @end table
5896 @menu
5897 * The date/time prompt::        How Org mode helps you entering date and time
5898 * Custom time format::          Making dates look different
5899 @end menu
5901 @node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps
5902 @subsection The date/time prompt
5903 @cindex date, reading in minibuffer
5904 @cindex time, reading in minibuffer
5906 @vindex org-read-date-prefer-future
5907 When Org mode prompts for a date/time, the default is shown in default
5908 date/time format, and the prompt therefore seems to ask for a specific
5909 format.  But it will in fact accept date/time information in a variety of
5910 formats.  Generally, the information should start at the beginning of the
5911 string.  Org mode will find whatever information is in
5912 there and derive anything you have not specified from the @emph{default date
5913 and time}.  The default is usually the current date and time, but when
5914 modifying an existing timestamp, or when entering the second stamp of a
5915 range, it is taken from the stamp in the buffer.  When filling in
5916 information, Org mode assumes that most of the time you will want to enter a
5917 date in the future: if you omit the month/year and the given day/month is
5918 @i{before} today, it will assume that you mean a future date@footnote{See the
5919 variable @code{org-read-date-prefer-future}.  You may set that variable to
5920 the symbol @code{time} to even make a time before now shift the date to
5921 tomorrow.}.  If the date has been automatically shifted into the future, the
5922 time prompt will show this with @samp{(=>F).}
5924 For example, let's assume that today is @b{June 13, 2006}.  Here is how
5925 various inputs will be interpreted, the items filled in by Org mode are
5926 in @b{bold}.
5928 @example
5929 3-2-5         @result{} 2003-02-05
5930 2/5/3         @result{} 2003-02-05
5931 14            @result{} @b{2006}-@b{06}-14
5932 12            @result{} @b{2006}-@b{07}-12
5933 2/5           @result{} @b{2007}-02-05
5934 Fri           @result{} nearest Friday after the default date
5935 sep 15        @result{} @b{2006}-09-15
5936 feb 15        @result{} @b{2007}-02-15
5937 sep 12 9      @result{} 2009-09-12
5938 12:45         @result{} @b{2006}-@b{06}-@b{13} 12:45
5939 22 sept 0:34  @result{} @b{2006}-09-22 0:34
5940 w4            @result{} ISO week for of the current year @b{2006}
5941 2012 w4 fri   @result{} Friday of ISO week 4 in 2012
5942 2012-w04-5    @result{} Same as above
5943 @end example
5945 Furthermore you can specify a relative date by giving, as the @emph{first}
5946 thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to
5947 indicate change in hours, days, weeks, months, or years.  With a single plus
5948 or minus, the date is always relative to today.  With a double plus or minus,
5949 it is relative to the default date.  If instead of a single letter, you use
5950 the abbreviation of day name, the date will be the Nth such day, e.g.:
5952 @example
5953 +0            @result{} today
5954 .             @result{} today
5955 +4d           @result{} four days from today
5956 +4            @result{} same as above
5957 +2w           @result{} two weeks from today
5958 ++5           @result{} five days from default date
5959 +2tue         @result{} second Tuesday from now
5960 -wed          @result{} last Wednesday
5961 @end example
5963 @vindex parse-time-months
5964 @vindex parse-time-weekdays
5965 The function understands English month and weekday abbreviations.  If
5966 you want to use unabbreviated names and/or other languages, configure
5967 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
5969 @vindex org-read-date-force-compatible-dates
5970 Not all dates can be represented in a given Emacs implementation.  By default
5971 Org mode forces dates into the compatibility range 1970--2037 which works on
5972 all Emacs implementations.  If you want to use dates outside of this range,
5973 read the docstring of the variable
5974 @code{org-read-date-force-compatible-dates}.
5976 You can specify a time range by giving start and end times or by giving a
5977 start time and a duration (in HH:MM format).  Use one or two dash(es) as the
5978 separator in the former case and use '+' as the separator in the latter
5979 case, e.g.:
5981 @example
5982 11am-1:15pm    @result{} 11:00-13:15
5983 11am--1:15pm   @result{} same as above
5984 11am+2:15      @result{} same as above
5985 @end example
5987 @cindex calendar, for selecting date
5988 @vindex org-popup-calendar-for-date-prompt
5989 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
5990 you don't need/want the calendar, configure the variable
5991 @code{org-popup-calendar-for-date-prompt}.}.  When you exit the date
5992 prompt, either by clicking on a date in the calendar, or by pressing
5993 @key{RET}, the date selected in the calendar will be combined with the
5994 information entered at the prompt.  You can control the calendar fully
5995 from the minibuffer:
5997 @kindex <
5998 @kindex >
5999 @kindex M-v
6000 @kindex C-v
6001 @kindex mouse-1
6002 @kindex S-@key{right}
6003 @kindex S-@key{left}
6004 @kindex S-@key{down}
6005 @kindex S-@key{up}
6006 @kindex M-S-@key{right}
6007 @kindex M-S-@key{left}
6008 @kindex @key{RET}
6009 @example
6010 @key{RET}           @r{Choose date at cursor in calendar.}
6011 mouse-1        @r{Select date by clicking on it.}
6012 S-@key{right}/@key{left}     @r{One day forward/backward.}
6013 S-@key{down}/@key{up}     @r{One week forward/backward.}
6014 M-S-@key{right}/@key{left}   @r{One month forward/backward.}
6015 > / <          @r{Scroll calendar forward/backward by one month.}
6016 M-v / C-v      @r{Scroll calendar forward/backward by 3 months.}
6017 @end example
6019 @vindex org-read-date-display-live
6020 The actions of the date/time prompt may seem complex, but I assure you they
6021 will grow on you, and you will start getting annoyed by pretty much any other
6022 way of entering a date/time out there.  To help you understand what is going
6023 on, the current interpretation of your input will be displayed live in the
6024 minibuffer@footnote{If you find this distracting, turn the display off with
6025 @code{org-read-date-display-live}.}.
6027 @node Custom time format,  , The date/time prompt, Creating timestamps
6028 @subsection Custom time format
6029 @cindex custom date/time format
6030 @cindex time format, custom
6031 @cindex date format, custom
6033 @vindex org-display-custom-times
6034 @vindex org-time-stamp-custom-formats
6035 Org mode uses the standard ISO notation for dates and times as it is
6036 defined in ISO 8601.  If you cannot get used to this and require another
6037 representation of date and time to keep you happy, you can get it by
6038 customizing the options @code{org-display-custom-times} and
6039 @code{org-time-stamp-custom-formats}.
6041 @table @kbd
6042 @orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays}
6043 Toggle the display of custom formats for dates and times.
6044 @end table
6046 @noindent
6047 Org mode needs the default format for scanning, so the custom date/time
6048 format does not @emph{replace} the default format---instead it is put
6049 @emph{over} the default format using text properties.  This has the
6050 following consequences:
6051 @itemize @bullet
6052 @item
6053 You cannot place the cursor onto a timestamp anymore, only before or
6054 after.
6055 @item
6056 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
6057 each component of a timestamp.  If the cursor is at the beginning of
6058 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
6059 just like @kbd{S-@key{left}/@key{right}}.  At the end of the stamp, the
6060 time will be changed by one minute.
6061 @item
6062 If the timestamp contains a range of clock times or a repeater, these
6063 will not be overlaid, but remain in the buffer as they were.
6064 @item
6065 When you delete a timestamp character-by-character, it will only
6066 disappear from the buffer after @emph{all} (invisible) characters
6067 belonging to the ISO timestamp have been removed.
6068 @item
6069 If the custom timestamp format is longer than the default and you are
6070 using dates in tables, table alignment will be messed up.  If the custom
6071 format is shorter, things do work as expected.
6072 @end itemize
6075 @node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times
6076 @section Deadlines and scheduling
6078 A timestamp may be preceded by special keywords to facilitate planning:
6080 @table @var
6081 @item DEADLINE
6082 @cindex DEADLINE keyword
6084 Meaning: the task (most likely a TODO item, though not necessarily) is supposed
6085 to be finished on that date.
6087 @vindex org-deadline-warning-days
6088 @vindex org-agenda-skip-deadline-prewarning-if-scheduled
6089 On the deadline date, the task will be listed in the agenda.  In
6090 addition, the agenda for @emph{today} will carry a warning about the
6091 approaching or missed deadline, starting
6092 @code{org-deadline-warning-days} before the due date, and continuing
6093 until the entry is marked DONE@.  An example:
6095 @example
6096 *** TODO write article about the Earth for the Guide
6097     DEADLINE: <2004-02-29 Sun>
6098     The editor in charge is [[bbdb:Ford Prefect]]
6099 @end example
6101 You can specify a different lead time for warnings for a specific
6102 deadlines using the following syntax.  Here is an example with a warning
6103 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}.  This warning is
6104 deactivated if the task get scheduled and you set
6105 @code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}.
6107 @item SCHEDULED
6108 @cindex SCHEDULED keyword
6110 Meaning: you are planning to start working on that task on the given
6111 date.
6113 @vindex org-agenda-skip-scheduled-if-done
6114 The headline will be listed under the given date@footnote{It will still
6115 be listed on that date after it has been marked DONE@.  If you don't like
6116 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}.  In
6117 addition, a reminder that the scheduled date has passed will be present
6118 in the compilation for @emph{today}, until the entry is marked DONE, i.e.,
6119 the task will automatically be forwarded until completed.
6121 @example
6122 *** TODO Call Trillian for a date on New Years Eve.
6123     SCHEDULED: <2004-12-25 Sat>
6124 @end example
6126 @vindex org-scheduled-delay-days
6127 @vindex org-agenda-skip-scheduled-delay-if-deadline
6128 If you want to @emph{delay} the display of this task in the agenda, use
6129 @code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the
6130 25th but will appear two days later.  In case the task contains a repeater,
6131 the delay is considered to affect all occurrences; if you want the delay to
6132 only affect the first scheduled occurrence of the task, use @code{--2d}
6133 instead.  See @code{org-scheduled-delay-days} and
6134 @code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to
6135 control this globally or per agenda.
6137 @noindent
6138 @b{Important:} Scheduling an item in Org mode should @i{not} be
6139 understood in the same way that we understand @i{scheduling a meeting}.
6140 Setting a date for a meeting is just a simple appointment, you should
6141 mark this entry with a simple plain timestamp, to get this item shown
6142 on the date where it applies.  This is a frequent misunderstanding by
6143 Org users.  In Org mode, @i{scheduling} means setting a date when you
6144 want to start working on an action item.
6145 @end table
6147 You may use timestamps with repeaters in scheduling and deadline
6148 entries.  Org mode will issue early and late warnings based on the
6149 assumption that the timestamp represents the @i{nearest instance} of
6150 the repeater.  However, the use of diary sexp entries like
6152 @code{<%%(diary-float t 42)>}
6154 in scheduling and deadline timestamps is limited.  Org mode does not
6155 know enough about the internals of each sexp function to issue early and
6156 late warnings.  However, it will show the item on each day where the
6157 sexp entry matches.
6159 @menu
6160 * Inserting deadline/schedule::  Planning items
6161 * Repeated tasks::              Items that show up again and again
6162 @end menu
6164 @node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling
6165 @subsection Inserting deadlines or schedules
6167 The following commands allow you to quickly insert@footnote{The @samp{SCHEDULED} and
6168 @samp{DEADLINE} dates are inserted on the line right below the headline.  Don't put
6169 any text between this line and the headline.} a deadline or to schedule
6170 an item:
6172 @table @kbd
6174 @orgcmd{C-c C-d,org-deadline}
6175 Insert @samp{DEADLINE} keyword along with a stamp.  The insertion will happen
6176 in the line directly following the headline.  Any CLOSED timestamp will be
6177 removed.  When called with a prefix arg, an existing deadline will be removed
6178 from the entry.  Depending on the variable @code{org-log-redeadline}@footnote{with corresponding
6179 @code{#+STARTUP} keywords @code{logredeadline}, @code{lognoteredeadline},
6180 and @code{nologredeadline}}, a note will be taken when changing an existing
6181 deadline.
6183 @orgcmd{C-c C-s,org-schedule}
6184 Insert @samp{SCHEDULED} keyword along with a stamp.  The insertion will
6185 happen in the line directly following the headline.  Any CLOSED timestamp
6186 will be removed.  When called with a prefix argument, remove the scheduling
6187 date from the entry.  Depending on the variable
6188 @code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}
6189 keywords @code{logreschedule}, @code{lognotereschedule}, and
6190 @code{nologreschedule}}, a note will be taken when changing an existing
6191 scheduling time.
6193 @orgcmd{C-c C-x C-k,org-mark-entry-for-agenda-action}
6194 @kindex k a
6195 @kindex k s
6196 Mark the current entry for agenda action.  After you have marked the entry
6197 like this, you can open the agenda or the calendar to find an appropriate
6198 date.  With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to
6199 schedule the marked item.
6201 @orgcmd{C-c / d,org-check-deadlines}
6202 @cindex sparse tree, for deadlines
6203 @vindex org-deadline-warning-days
6204 Create a sparse tree with all deadlines that are either past-due, or
6205 which will become due within @code{org-deadline-warning-days}.
6206 With @kbd{C-u} prefix, show all deadlines in the file.  With a numeric
6207 prefix, check that many days.  For example, @kbd{C-1 C-c / d} shows
6208 all deadlines due tomorrow.
6210 @orgcmd{C-c / b,org-check-before-date}
6211 Sparse tree for deadlines and scheduled items before a given date.
6213 @orgcmd{C-c / a,org-check-after-date}
6214 Sparse tree for deadlines and scheduled items after a given date.
6215 @end table
6217 Note that @code{org-schedule} and @code{org-deadline} supports
6218 setting the date by indicating a relative time: e.g., +1d will set
6219 the date to the next day after today, and --1w will set the date
6220 to the previous week before any current timestamp.
6222 @node Repeated tasks,  , Inserting deadline/schedule, Deadlines and scheduling
6223 @subsection Repeated tasks
6224 @cindex tasks, repeated
6225 @cindex repeated tasks
6227 Some tasks need to be repeated again and again.  Org mode helps to
6228 organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
6229 or plain timestamp.  In the following example
6230 @example
6231 ** TODO Pay the rent
6232    DEADLINE: <2005-10-01 Sat +1m>
6233 @end example
6234 @noindent
6235 the @code{+1m} is a repeater; the intended interpretation is that the task
6236 has a deadline on <2005-10-01> and repeats itself every (one) month starting
6237 from that time.  You can use yearly, monthly, weekly, daily and hourly repeat
6238 cookies by using the @code{y/w/m/d/h} letters.  If you need both a repeater
6239 and a special warning period in a deadline entry, the repeater should come
6240 first and the warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
6242 @vindex org-todo-repeat-to-state
6243 Deadlines and scheduled items produce entries in the agenda when they are
6244 over-due, so it is important to be able to mark such an entry as completed
6245 once you have done so.  When you mark a DEADLINE or a SCHEDULE with the TODO
6246 keyword DONE, it will no longer produce entries in the agenda.  The problem
6247 with this is, however, that then also the @emph{next} instance of the
6248 repeated entry will not be active.  Org mode deals with this in the following
6249 way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
6250 shift the base date of the repeating timestamp by the repeater interval, and
6251 immediately set the entry state back to TODO@footnote{In fact, the target
6252 state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or
6253 the variable @code{org-todo-repeat-to-state}.  If neither of these is
6254 specified, the target state defaults to the first state of the TODO state
6255 sequence.}.  In the example above, setting the state to DONE would actually
6256 switch the date like this:
6258 @example
6259 ** TODO Pay the rent
6260    DEADLINE: <2005-11-01 Tue +1m>
6261 @end example
6263 @vindex org-log-repeat
6264 A timestamp@footnote{You can change this using the option
6265 @code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},
6266 @code{lognoterepeat}, and @code{nologrepeat}.  With @code{lognoterepeat}, you
6267 will also be prompted for a note.} will be added under the deadline, to keep
6268 a record that you actually acted on the previous instance of this deadline.
6270 As a consequence of shifting the base date, this entry will no longer be
6271 visible in the agenda when checking past dates, but all future instances
6272 will be visible.
6274 With the @samp{+1m} cookie, the date shift will always be exactly one
6275 month.  So if you have not paid the rent for three months, marking this
6276 entry DONE will still keep it as an overdue deadline.  Depending on the
6277 task, this may not be the best way to handle it.  For example, if you
6278 forgot to call your father for 3 weeks, it does not make sense to call
6279 him 3 times in a single day to make up for it.  Finally, there are tasks
6280 like changing batteries which should always repeat a certain time
6281 @i{after} the last time you did it.  For these tasks, Org mode has
6282 special repeaters  @samp{++} and @samp{.+}.  For example:
6284 @example
6285 ** TODO Call Father
6286    DEADLINE: <2008-02-10 Sun ++1w>
6287    Marking this DONE will shift the date by at least one week,
6288    but also by as many weeks as it takes to get this date into
6289    the future.  However, it stays on a Sunday, even if you called
6290    and marked it done on Saturday.
6291 ** TODO Check the batteries in the smoke detectors
6292    DEADLINE: <2005-11-01 Tue .+1m>
6293    Marking this DONE will shift the date to one month after
6294    today.
6295 @end example
6297 @vindex org-agenda-skip-scheduled-if-deadline-is-shown
6298 You may have both scheduling and deadline information for a specific task.
6299 If the repeater is set for the scheduling information only, you probably want
6300 the repeater to be ignored after the deadline.  If so, set the variable
6301 @code{org-agenda-skip-scheduled-if-deadline-is-shown} to
6302 @code{repeated-after-deadline}.  If you want both scheduling and deadline
6303 information to repeat after the same interval, set the same repeater for both
6304 timestamps.
6306 An alternative to using a repeater is to create a number of copies of a task
6307 subtree, with dates shifted in each copy.  The command @kbd{C-c C-x c} was
6308 created for this purpose, it is described in @ref{Structure editing}.
6311 @node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and Times
6312 @section Clocking work time
6313 @cindex clocking time
6314 @cindex time clocking
6316 Org mode allows you to clock the time you spend on specific tasks in a
6317 project.  When you start working on an item, you can start the clock.  When
6318 you stop working on that task, or when you mark the task done, the clock is
6319 stopped and the corresponding time interval is recorded.  It also computes
6320 the total time spent on each subtree@footnote{Clocking only works if all
6321 headings are indented with less than 30 stars.  This is a hardcoded
6322 limitation of `lmax' in `org-clock-sum'.} of a project.  And it remembers a
6323 history or tasks recently clocked, to that you can jump quickly between a
6324 number of tasks absorbing your time.
6326 To save the clock history across Emacs sessions, use
6327 @lisp
6328 (setq org-clock-persist 'history)
6329 (org-clock-persistence-insinuate)
6330 @end lisp
6331 When you clock into a new task after resuming Emacs, the incomplete
6332 clock@footnote{To resume the clock under the assumption that you have worked
6333 on this task while outside Emacs, use @code{(setq org-clock-persist t)}.}
6334 will be found (@pxref{Resolving idle time}) and you will be prompted about
6335 what to do with it.
6337 @menu
6338 * Clocking commands::           Starting and stopping a clock
6339 * The clock table::             Detailed reports
6340 * Resolving idle time::         Resolving time when you've been idle
6341 @end menu
6343 @node Clocking commands, The clock table, Clocking work time, Clocking work time
6344 @subsection Clocking commands
6346 @table @kbd
6347 @orgcmd{C-c C-x C-i,org-clock-in}
6348 @vindex org-clock-into-drawer
6349 @vindex org-clock-continuously
6350 @cindex property, LOG_INTO_DRAWER
6351 Start the clock on the current item (clock-in).  This inserts the CLOCK
6352 keyword together with a timestamp.  If this is not the first clocking of
6353 this item, the multiple CLOCK lines will be wrapped into a
6354 @code{:LOGBOOK:} drawer (see also the variable
6355 @code{org-clock-into-drawer}).  You can also overrule
6356 the setting of this variable for a subtree by setting a
6357 @code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
6358 When called with a @kbd{C-u} prefix argument,
6359 select the task from a list of recently clocked tasks.  With two @kbd{C-u
6360 C-u} prefixes, clock into the task at point and mark it as the default task;
6361 the default task will then always be available with letter @kbd{d} when
6362 selecting a clocking task.  With three @kbd{C-u C-u C-u} prefixes, force
6363 continuous clocking by starting the clock when the last clock stopped.@*
6364 @cindex property: CLOCK_MODELINE_TOTAL
6365 @cindex property: LAST_REPEAT
6366 @vindex org-clock-modeline-total
6367 While the clock is running, the current clocking time is shown in the mode
6368 line, along with the title of the task.  The clock time shown will be all
6369 time ever clocked for this task and its children.  If the task has an effort
6370 estimate (@pxref{Effort estimates}), the mode line displays the current
6371 clocking time against it@footnote{To add an effort estimate ``on the fly'',
6372 hook a function doing this to @code{org-clock-in-prepare-hook}.}  If the task
6373 is a repeating one (@pxref{Repeated tasks}), only the time since the last
6374 reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}
6375 will be shown.  More control over what time is shown can be exercised with
6376 the @code{CLOCK_MODELINE_TOTAL} property.  It may have the values
6377 @code{current} to show only the current clocking instance, @code{today} to
6378 show all time clocked on this tasks today (see also the variable
6379 @code{org-extend-today-until}), @code{all} to include all time, or
6380 @code{auto} which is the default@footnote{See also the variable
6381 @code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
6382 mode line entry will pop up a menu with clocking options.
6384 @orgcmd{C-c C-x C-o,org-clock-out}
6385 @vindex org-log-note-clock-out
6386 Stop the clock (clock-out).  This inserts another timestamp at the same
6387 location where the clock was last started.  It also directly computes
6388 the resulting time in inserts it after the time range as @samp{=>
6389 HH:MM}.  See the variable @code{org-log-note-clock-out} for the
6390 possibility to record an additional note together with the clock-out
6391 timestamp@footnote{The corresponding in-buffer setting is:
6392 @code{#+STARTUP: lognoteclock-out}}.
6393 @orgcmd{C-c C-x C-x,org-clock-in-last}
6394 @vindex org-clock-continuously
6395 Reclock the last clocked task.  With one @kbd{C-u} prefix argument,
6396 select the task from the clock history.  With two @kbd{C-u} prefixes,
6397 force continuous clocking by starting the clock when the last clock
6398 stopped.
6399 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6400 Update the effort estimate for the current clock task.
6401 @kindex C-c C-y
6402 @kindex C-c C-c
6403 @orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range}
6404 Recompute the time interval after changing one of the timestamps.  This
6405 is only necessary if you edit the timestamps directly.  If you change
6406 them with @kbd{S-@key{cursor}} keys, the update is automatic.
6407 @orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
6408 On @code{CLOCK} log lines, increase/decrease both timestamps so that the
6409 clock duration keeps the same.
6410 @orgcmd{S-M-@key{up/down},org-timestamp-up/down}
6411 On @code{CLOCK} log lines, increase/decrease the timestamp at point and
6412 the one of the previous (or the next clock) timestamp by the same duration.
6413 For example, if you hit @kbd{S-M-@key{up}} to increase a clocked-out timestamp
6414 by five minutes, then the clocked-in timestamp of the next clock will be
6415 increased by five minutes.
6416 @orgcmd{C-c C-t,org-todo}
6417 Changing the TODO state of an item to DONE automatically stops the clock
6418 if it is running in this same item.
6419 @orgcmd{C-c C-x C-q,org-clock-cancel}
6420 Cancel the current clock.  This is useful if a clock was started by
6421 mistake, or if you ended up working on something else.
6422 @orgcmd{C-c C-x C-j,org-clock-goto}
6423 Jump to the headline of the currently clocked in task.  With a @kbd{C-u}
6424 prefix arg, select the target task from a list of recently clocked tasks.
6425 @orgcmd{C-c C-x C-d,org-clock-display}
6426 @vindex org-remove-highlights-with-change
6427 Display time summaries for each subtree in the current buffer.  This puts
6428 overlays at the end of each headline, showing the total time recorded under
6429 that heading, including the time of any subheadings.  You can use visibility
6430 cycling to study the tree, but the overlays disappear when you change the
6431 buffer (see variable @code{org-remove-highlights-with-change}) or press
6432 @kbd{C-c C-c}.
6433 @end table
6435 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
6436 the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
6437 worked on or closed during a day.
6439 @strong{Important:} note that both @code{org-clock-out} and
6440 @code{org-clock-in-last} can have a global keybinding and will not
6441 modify the window disposition.
6443 @node The clock table, Resolving idle time, Clocking commands, Clocking work time
6444 @subsection The clock table
6445 @cindex clocktable, dynamic block
6446 @cindex report, of clocked time
6448 Org mode can produce quite complex reports based on the time clocking
6449 information.  Such a report is called a @emph{clock table}, because it is
6450 formatted as one or several Org tables.
6452 @table @kbd
6453 @orgcmd{C-c C-x C-r,org-clock-report}
6454 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
6455 report as an Org mode table into the current file.  When the cursor is
6456 at an existing clock table, just update it.  When called with a prefix
6457 argument, jump to the first clock report in the current document and
6458 update it.  The clock table always includes also trees with
6459 @code{:ARCHIVE:} tag.
6460 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
6461 Update dynamic block at point.  The cursor needs to be in the
6462 @code{#+BEGIN} line of the dynamic block.
6463 @orgkey{C-u C-c C-x C-u}
6464 Update all dynamic blocks (@pxref{Dynamic blocks}).  This is useful if
6465 you have several clock table blocks in a buffer.
6466 @orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift}
6467 Shift the current @code{:block} interval and update the table.  The cursor
6468 needs to be in the @code{#+BEGIN: clocktable} line for this command.  If
6469 @code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
6470 @end table
6473 Here is an example of the frame for a clock table as it is inserted into the
6474 buffer with the @kbd{C-c C-x C-r} command:
6476 @cindex #+BEGIN, clocktable
6477 @example
6478 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
6479 #+END: clocktable
6480 @end example
6481 @noindent
6482 @vindex org-clocktable-defaults
6483 The @samp{BEGIN} line and specify a number of options to define the scope,
6484 structure, and formatting of the report.  Defaults for all these options can
6485 be configured in the variable @code{org-clocktable-defaults}.
6487 @noindent First there are options that determine which clock entries are to
6488 be selected:
6489 @example
6490 :maxlevel    @r{Maximum level depth to which times are listed in the table.}
6491              @r{Clocks at deeper levels will be summed into the upper level.}
6492 :scope       @r{The scope to consider.  This can be any of the following:}
6493              nil        @r{the current buffer or narrowed region}
6494              file       @r{the full current buffer}
6495              subtree    @r{the subtree where the clocktable is located}
6496              tree@var{N}      @r{the surrounding level @var{N} tree, for example @code{tree3}}
6497              tree       @r{the surrounding level 1 tree}
6498              agenda     @r{all agenda files}
6499              ("file"..) @r{scan these files}
6500              file-with-archives    @r{current file and its archives}
6501              agenda-with-archives  @r{all agenda files, including archives}
6502 :block       @r{The time block to consider.  This block is specified either}
6503              @r{absolute, or relative to the current time and may be any of}
6504              @r{these formats:}
6505              2007-12-31    @r{New year eve 2007}
6506              2007-12       @r{December 2007}
6507              2007-W50      @r{ISO-week 50 in 2007}
6508              2007-Q2       @r{2nd quarter in 2007}
6509              2007          @r{the year 2007}
6510              today, yesterday, today-@var{N}          @r{a relative day}
6511              thisweek, lastweek, thisweek-@var{N}     @r{a relative week}
6512              thismonth, lastmonth, thismonth-@var{N}  @r{a relative month}
6513              thisyear, lastyear, thisyear-@var{N}     @r{a relative year}
6514              @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}
6515 :tstart      @r{A time string specifying when to start considering times.}
6516              @r{Relative times like @code{"<-2w>"} can also be used.  See}
6517              @r{@ref{Matching tags and properties} for relative time syntax.}
6518 :tend        @r{A time string specifying when to stop considering times.}
6519              @r{Relative times like @code{"<now>"} can also be used.  See}
6520              @r{@ref{Matching tags and properties} for relative time syntax.}
6521 :wstart      @r{The starting day of the week.  The default is 1 for monday.}
6522 :mstart      @r{The starting day of the month.  The default 1 is for the first}
6523              @r{day of the month.}
6524 :step        @r{@code{week} or @code{day}, to split the table into chunks.}
6525              @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}
6526 :stepskip0   @r{Do not show steps that have zero time.}
6527 :fileskip0   @r{Do not show table sections from files which did not contribute.}
6528 :tags        @r{A tags match to select entries that should contribute.  See}
6529              @r{@ref{Matching tags and properties} for the match syntax.}
6530 @end example
6532 Then there are options which determine the formatting of the table.  There
6533 options are interpreted by the function @code{org-clocktable-write-default},
6534 but you can specify your own function using the @code{:formatter} parameter.
6535 @example
6536 :emphasize   @r{When @code{t}, emphasize level one and level two items.}
6537 :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".}
6538 :link        @r{Link the item headlines in the table to their origins.}
6539 :narrow      @r{An integer to limit the width of the headline column in}
6540              @r{the org table.  If you write it like @samp{50!}, then the}
6541              @r{headline will also be shortened in export.}
6542 :indent      @r{Indent each headline field according to its level.}
6543 :tcolumns    @r{Number of columns to be used for times.  If this is smaller}
6544              @r{than @code{:maxlevel}, lower levels will be lumped into one column.}
6545 :level       @r{Should a level number column be included?}
6546 :compact     @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}}
6547              @r{All are overwritten except if there is an explicit @code{:narrow}}
6548 :timestamp   @r{A timestamp for the entry, when available.  Look for SCHEDULED,}
6549              @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}
6550 :properties  @r{List of properties that should be shown in the table.  Each}
6551              @r{property will get its own column.}
6552 :inherit-props @r{When this flag is @code{t}, the values for @code{:properties} will be inherited.}
6553 :formula     @r{Content of a @code{#+TBLFM} line to be added and evaluated.}
6554              @r{As a special case, @samp{:formula %} adds a column with % time.}
6555              @r{If you do not specify a formula here, any existing formula}
6556              @r{below the clock table will survive updates and be evaluated.}
6557 :formatter   @r{A function to format clock data and insert it into the buffer.}
6558 @end example
6559 To get a clock summary of the current level 1 tree, for the current
6560 day, you could write
6561 @example
6562 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
6563 #+END: clocktable
6564 @end example
6565 @noindent
6566 and to use a specific time range you could write@footnote{Note that all
6567 parameters must be specified in a single line---the line is broken here
6568 only to fit it into the manual.}
6569 @example
6570 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
6571                     :tend "<2006-08-10 Thu 12:00>"
6572 #+END: clocktable
6573 @end example
6574 A range starting a week ago and ending right now could be written as
6575 @example
6576 #+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
6577 #+END: clocktable
6578 @end example
6579 A summary of the current subtree with % times would be
6580 @example
6581 #+BEGIN: clocktable :scope subtree :link t :formula %
6582 #+END: clocktable
6583 @end example
6584 A horizontally compact representation of everything clocked during last week
6585 would be
6586 @example
6587 #+BEGIN: clocktable :scope agenda :block lastweek :compact t
6588 #+END: clocktable
6589 @end example
6591 @node Resolving idle time,  , The clock table, Clocking work time
6592 @subsection Resolving idle time and continuous clocking
6594 @subsubheading Resolving idle time
6595 @cindex resolve idle time
6596 @vindex org-clock-x11idle-program-name
6598 @cindex idle, resolve, dangling
6599 If you clock in on a work item, and then walk away from your
6600 computer---perhaps to take a phone call---you often need to ``resolve'' the
6601 time you were away by either subtracting it from the current clock, or
6602 applying it to another one.
6604 @vindex org-clock-idle-time
6605 By customizing the variable @code{org-clock-idle-time} to some integer, such
6606 as 10 or 15, Emacs can alert you when you get back to your computer after
6607 being idle for that many minutes@footnote{On computers using Mac OS X,
6608 idleness is based on actual user idleness, not just Emacs' idle time.  For
6609 X11, you can install a utility program @file{x11idle.c}, available in the
6610 @code{contrib/scripts} directory of the Org git distribution, or install the
6611 @file{xprintidle} package and set it to the variable
6612 @code{org-clock-x11idle-program-name} if you are running Debian, to get the
6613 same general treatment of idleness.  On other systems, idle time refers to
6614 Emacs idle time only.}, and ask what you want to do with the idle time.
6615 There will be a question waiting for you when you get back, indicating how
6616 much idle time has passed (constantly updated with the current amount), as
6617 well as a set of choices to correct the discrepancy:
6619 @table @kbd
6620 @item k
6621 To keep some or all of the minutes and stay clocked in, press @kbd{k}.  Org
6622 will ask how many of the minutes to keep.  Press @key{RET} to keep them all,
6623 effectively changing nothing, or enter a number to keep that many minutes.
6624 @item K
6625 If you use the shift key and press @kbd{K}, it will keep however many minutes
6626 you request and then immediately clock out of that task.  If you keep all of
6627 the minutes, this is the same as just clocking out of the current task.
6628 @item s
6629 To keep none of the minutes, use @kbd{s} to subtract all the away time from
6630 the clock, and then check back in from the moment you returned.
6631 @item S
6632 To keep none of the minutes and just clock out at the start of the away time,
6633 use the shift key and press @kbd{S}.  Remember that using shift will always
6634 leave you clocked out, no matter which option you choose.
6635 @item C
6636 To cancel the clock altogether, use @kbd{C}.  Note that if instead of
6637 canceling you subtract the away time, and the resulting clock amount is less
6638 than a minute, the clock will still be canceled rather than clutter up the
6639 log with an empty entry.
6640 @end table
6642 What if you subtracted those away minutes from the current clock, and now
6643 want to apply them to a new clock?  Simply clock in to any task immediately
6644 after the subtraction.  Org will notice that you have subtracted time ``on
6645 the books'', so to speak, and will ask if you want to apply those minutes to
6646 the next task you clock in on.
6648 There is one other instance when this clock resolution magic occurs.  Say you
6649 were clocked in and hacking away, and suddenly your cat chased a mouse who
6650 scared a hamster that crashed into your UPS's power button!  You suddenly
6651 lose all your buffers, but thanks to auto-save you still have your recent Org
6652 mode changes, including your last clock in.
6654 If you restart Emacs and clock into any task, Org will notice that you have a
6655 dangling clock which was never clocked out from your last session.  Using
6656 that clock's starting time as the beginning of the unaccounted-for period,
6657 Org will ask how you want to resolve that time.  The logic and behavior is
6658 identical to dealing with away time due to idleness; it is just happening due
6659 to a recovery event rather than a set amount of idle time.
6661 You can also check all the files visited by your Org agenda for dangling
6662 clocks at any time using @kbd{M-x org-resolve-clocks RET} (or @kbd{C-c C-x C-z}).
6664 @subsubheading Continuous clocking
6665 @cindex continuous clocking
6666 @vindex org-clock-continuously
6668 You may want to start clocking from the time when you clocked out the
6669 previous task.  To enable this systematically, set @code{org-clock-continuously}
6670 to @code{t}.  Each time you clock in, Org retrieves the clock-out time of the
6671 last clocked entry for this session, and start the new clock from there.
6673 If you only want this from time to time, use three universal prefix arguments
6674 with @code{org-clock-in} and two @kbd{C-u C-u} with @code{org-clock-in-last}.
6676 @node Effort estimates, Relative timer, Clocking work time, Dates and Times
6677 @section Effort estimates
6678 @cindex effort estimates
6680 @cindex property, Effort
6681 @vindex org-effort-property
6682 If you want to plan your work in a very detailed way, or if you need to
6683 produce offers with quotations of the estimated work effort, you may want to
6684 assign effort estimates to entries.  If you are also clocking your work, you
6685 may later want to compare the planned effort with the actual working time, a
6686 great way to improve planning estimates.  Effort estimates are stored in a
6687 special property @samp{Effort}@footnote{You may change the property being
6688 used with the variable @code{org-effort-property}.}.  You can set the effort
6689 for an entry with the following commands:
6691 @table @kbd
6692 @orgcmd{C-c C-x e,org-set-effort}
6693 Set the effort estimate for the current entry.  With a numeric prefix
6694 argument, set it to the Nth allowed value (see below).  This command is also
6695 accessible from the agenda with the @kbd{e} key.
6696 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6697 Modify the effort estimate of the item currently being clocked.
6698 @end table
6700 Clearly the best way to work with effort estimates is through column view
6701 (@pxref{Column view}).  You should start by setting up discrete values for
6702 effort estimates, and a @code{COLUMNS} format that displays these values
6703 together with clock sums (if you want to clock your time).  For a specific
6704 buffer you can use
6706 @example
6707 #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
6708 #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM
6709 @end example
6711 @noindent
6712 @vindex org-global-properties
6713 @vindex org-columns-default-format
6714 or, even better, you can set up these values globally by customizing the
6715 variables @code{org-global-properties} and @code{org-columns-default-format}.
6716 In particular if you want to use this setup also in the agenda, a global
6717 setup may be advised.
6719 The way to assign estimates to individual items is then to switch to column
6720 mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the
6721 value.  The values you enter will immediately be summed up in the hierarchy.
6722 In the column next to it, any clocked time will be displayed.
6724 @vindex org-agenda-columns-add-appointments-to-effort-sum
6725 If you switch to column view in the daily/weekly agenda, the effort column
6726 will summarize the estimated work effort for each day@footnote{Please note
6727 the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda
6728 column view}).}, and you can use this to find space in your schedule.  To get
6729 an overview of the entire part of the day that is committed, you can set the
6730 option @code{org-agenda-columns-add-appointments-to-effort-sum}.  The
6731 appointments on a day that take place over a specified time interval will
6732 then also be added to the load estimate of the day.
6734 Effort estimates can be used in secondary agenda filtering that is triggered
6735 with the @kbd{/} key in the agenda (@pxref{Agenda commands}).  If you have
6736 these estimates defined consistently, two or three key presses will narrow
6737 down the list to stuff that fits into an available time slot.
6739 @node Relative timer, Countdown timer, Effort estimates, Dates and Times
6740 @section Taking notes with a relative timer
6741 @cindex relative timer
6743 When taking notes during, for example, a meeting or a video viewing, it can
6744 be useful to have access to times relative to a starting time.  Org provides
6745 such a relative timer and make it easy to create timed notes.
6747 @table @kbd
6748 @orgcmd{C-c C-x .,org-timer}
6749 Insert a relative time into the buffer.  The first time you use this, the
6750 timer will be started.  When called with a prefix argument, the timer is
6751 restarted.
6752 @orgcmd{C-c C-x -,org-timer-item}
6753 Insert a description list item with the current relative time.  With a prefix
6754 argument, first reset the timer to 0.
6755 @orgcmd{M-@key{RET},org-insert-heading}
6756 Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert
6757 new timer items.
6758 @c for key sequences with a comma, command name macros fail :(
6759 @kindex C-c C-x ,
6760 @item C-c C-x ,
6761 Pause the timer, or continue it if it is already paused
6762 (@command{org-timer-pause-or-continue}).
6763 @c removed the sentence because it is redundant to the following item
6764 @kindex C-u C-c C-x ,
6765 @item C-u C-c C-x ,
6766 Stop the timer.  After this, you can only start a new timer, not continue the
6767 old one.  This command also removes the timer from the mode line.
6768 @orgcmd{C-c C-x 0,org-timer-start}
6769 Reset the timer without inserting anything into the buffer.  By default, the
6770 timer is reset to 0.  When called with a @kbd{C-u} prefix, reset the timer to
6771 specific starting offset.  The user is prompted for the offset, with a
6772 default taken from a timer string at point, if any, So this can be used to
6773 restart taking notes after a break in the process.  When called with a double
6774 prefix argument @kbd{C-u C-u}, change all timer strings in the active region
6775 by a certain amount.  This can be used to fix timer strings if the timer was
6776 not started at exactly the right moment.
6777 @end table
6779 @node Countdown timer,  , Relative timer, Dates and Times
6780 @section Countdown timer
6781 @cindex Countdown timer
6782 @kindex C-c C-x ;
6783 @kindex ;
6785 Calling @code{org-timer-set-timer} from an Org mode buffer runs a countdown
6786 timer.  Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everywhere else.
6788 @code{org-timer-set-timer} prompts the user for a duration and displays a
6789 countdown timer in the modeline.  @code{org-timer-default-timer} sets the
6790 default countdown value.  Giving a prefix numeric argument overrides this
6791 default value.
6793 @node Capture - Refile - Archive, Agenda Views, Dates and Times, Top
6794 @chapter Capture - Refile - Archive
6795 @cindex capture
6797 An important part of any organization system is the ability to quickly
6798 capture new ideas and tasks, and to associate reference material with them.
6799 Org does this using a process called @i{capture}.  It also can store files
6800 related to a task (@i{attachments}) in a special directory.  Once in the
6801 system, tasks and projects need to be moved around.  Moving completed project
6802 trees to an archive file keeps the system compact and fast.
6804 @menu
6805 * Capture::                     Capturing new stuff
6806 * Attachments::                 Add files to tasks
6807 * RSS Feeds::                   Getting input from RSS feeds
6808 * Protocols::                   External (e.g., Browser) access to Emacs and Org
6809 * Refile and copy::             Moving/copying a tree from one place to another
6810 * Archiving::                   What to do with finished projects
6811 @end menu
6813 @node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
6814 @section Capture
6815 @cindex capture
6817 Capture lets you quickly store notes with little interruption of your work
6818 flow.  Org's method for capturing new items is heavily inspired by John
6819 Wiegley excellent @file{remember.el} package.  Up to version 6.36, Org
6820 used a special setup for @file{remember.el}, then replaced it with
6821 @file{org-remember.el}.  As of version 8.0, @file{org-remember.el} has
6822 been completely replaced by @file{org-capture.el}.
6824 If your configuration depends on @file{org-remember.el}, you need to update
6825 it and use the setup described below.  To convert your
6826 @code{org-remember-templates}, run the command
6827 @example
6828 @kbd{M-x org-capture-import-remember-templates RET}
6829 @end example
6830 @noindent and then customize the new variable with @kbd{M-x
6831 customize-variable org-capture-templates}, check the result, and save the
6832 customization.
6834 @menu
6835 * Setting up capture::          Where notes will be stored
6836 * Using capture::               Commands to invoke and terminate capture
6837 * Capture templates::           Define the outline of different note types
6838 @end menu
6840 @node Setting up capture, Using capture, Capture, Capture
6841 @subsection Setting up capture
6843 The following customization sets a default target file for notes, and defines
6844 a global key@footnote{Please select your own key, @kbd{C-c c} is only a
6845 suggestion.}  for capturing new material.
6847 @vindex org-default-notes-file
6848 @smalllisp
6849 @group
6850 (setq org-default-notes-file (concat org-directory "/notes.org"))
6851 (define-key global-map "\C-cc" 'org-capture)
6852 @end group
6853 @end smalllisp
6855 @node Using capture, Capture templates, Setting up capture, Capture
6856 @subsection Using capture
6858 @table @kbd
6859 @orgcmd{C-c c,org-capture}
6860 Call the command @code{org-capture}.  Note that this keybinding is global and
6861 not active by default: you need to install it.  If you have templates
6862 @cindex date tree
6863 defined @pxref{Capture templates}, it will offer these templates for
6864 selection or use a new Org outline node as the default template.  It will
6865 insert the template into the target file and switch to an indirect buffer
6866 narrowed to this new node.  You may then insert the information you want.
6868 @orgcmd{C-c C-c,org-capture-finalize}
6869 Once you have finished entering information into the capture buffer, @kbd{C-c
6870 C-c} will return you to the window configuration before the capture process,
6871 so that you can resume your work without further distraction.  When called
6872 with a prefix arg, finalize and then jump to the captured item.
6874 @orgcmd{C-c C-w,org-capture-refile}
6875 Finalize the capture process by refiling (@pxref{Refile and copy}) the note to
6876 a different place.  Please realize that this is a normal refiling command
6877 that will be executed---so the cursor position at the moment you run this
6878 command is important.  If you have inserted a tree with a parent and
6879 children, first move the cursor back to the parent.  Any prefix argument
6880 given to this command will be passed on to the @code{org-refile} command.
6882 @orgcmd{C-c C-k,org-capture-kill}
6883 Abort the capture process and return to the previous state.
6885 @end table
6887 You can also call @code{org-capture} in a special way from the agenda, using
6888 the @kbd{k c} key combination.  With this access, any timestamps inserted by
6889 the selected capture template will default to the cursor date in the agenda,
6890 rather than to the current date.
6892 To find the locations of the last stored capture, use @code{org-capture} with
6893 prefix commands:
6895 @table @kbd
6896 @orgkey{C-u C-c c}
6897 Visit the target location of a capture template.  You get to select the
6898 template in the usual way.
6899 @orgkey{C-u C-u C-c c}
6900 Visit the last stored capture item in its buffer.
6901 @end table
6903 @vindex org-capture-bookmark
6904 @cindex org-capture-last-stored
6905 You can also jump to the bookmark @code{org-capture-last-stored}, which will
6906 automatically be created unless you set @code{org-capture-bookmark} to
6907 @code{nil}.
6909 To insert the capture at point in an Org buffer, call @code{org-capture} with
6910 a @code{C-0} prefix argument.
6912 @node Capture templates,  , Using capture, Capture
6913 @subsection Capture templates
6914 @cindex templates, for Capture
6916 You can use templates for different types of capture items, and
6917 for different target locations.  The easiest way to create such templates is
6918 through the customize interface.
6920 @table @kbd
6921 @orgkey{C-c c C}
6922 Customize the variable @code{org-capture-templates}.
6923 @end table
6925 Before we give the formal description of template definitions, let's look at
6926 an example.  Say you would like to use one template to create general TODO
6927 entries, and you want to put these entries under the heading @samp{Tasks} in
6928 your file @file{~/org/gtd.org}.  Also, a date tree in the file
6929 @file{journal.org} should capture journal entries.  A possible configuration
6930 would look like:
6932 @smalllisp
6933 @group
6934 (setq org-capture-templates
6935  '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
6936         "* TODO %?\n  %i\n  %a")
6937    ("j" "Journal" entry (file+datetree "~/org/journal.org")
6938         "* %?\nEntered on %U\n  %i\n  %a")))
6939 @end group
6940 @end smalllisp
6942 @noindent If you then press @kbd{C-c c t}, Org will prepare the template
6943 for you like this:
6944 @example
6945 * TODO
6946   [[file:@var{link to where you initiated capture}]]
6947 @end example
6949 @noindent
6950 During expansion of the template, @code{%a} has been replaced by a link to
6951 the location from where you called the capture command.  This can be
6952 extremely useful for deriving tasks from emails, for example.  You fill in
6953 the task definition, press @kbd{C-c C-c} and Org returns you to the same
6954 place where you started the capture process.
6956 To define special keys to capture to a particular template without going
6957 through the interactive template selection, you can create your key binding
6958 like this:
6960 @lisp
6961 (define-key global-map "\C-cx"
6962    (lambda () (interactive) (org-capture nil "x")))
6963 @end lisp
6965 @menu
6966 * Template elements::           What is needed for a complete template entry
6967 * Template expansion::          Filling in information about time and context
6968 * Templates in contexts::       Only show a template in a specific context
6969 @end menu
6971 @node Template elements, Template expansion, Capture templates, Capture templates
6972 @subsubsection Template elements
6974 Now lets look at the elements of a template definition.  Each entry in
6975 @code{org-capture-templates} is a list with the following items:
6977 @table @var
6978 @item keys
6979 The keys that will select the template, as a string, characters
6980 only, for example @code{"a"} for a template to be selected with a
6981 single key, or @code{"bt"} for selection with two keys.  When using
6982 several keys, keys using the same prefix key must be sequential
6983 in the list and preceded by a 2-element entry explaining the
6984 prefix key, for example
6985 @smalllisp
6986          ("b" "Templates for marking stuff to buy")
6987 @end smalllisp
6988 @noindent If you do not define a template for the @kbd{C} key, this key will
6989 be used to open the customize buffer for this complex variable.
6991 @item description
6992 A short string describing the template, which will be shown during
6993 selection.
6995 @item type
6996 The type of entry, a symbol.  Valid values are:
6998 @table @code
6999 @item entry
7000 An Org mode node, with a headline.  Will be filed as the child of the target
7001 entry or as a top-level entry.  The target file should be an Org mode file.
7002 @item item
7003 A plain list item, placed in the first plain  list at the target
7004 location.  Again the target file should be an Org file.
7005 @item checkitem
7006 A checkbox item.  This only differs from the plain list item by the
7007 default template.
7008 @item table-line
7009 a new line in the first table at the target location.  Where exactly the
7010 line will be inserted depends on the properties @code{:prepend} and
7011 @code{:table-line-pos} (see below).
7012 @item plain
7013 Text to be inserted as it is.
7014 @end table
7016 @item target
7017 @vindex org-default-notes-file
7018 Specification of where the captured item should be placed.  In Org mode
7019 files, targets usually define a node.  Entries will become children of this
7020 node.  Other types will be added to the table or list in the body of this
7021 node.  Most target specifications contain a file name.  If that file name is
7022 the empty string, it defaults to @code{org-default-notes-file}.  A file can
7023 also be given as a variable, function, or Emacs Lisp form.
7025 Valid values are:
7027 @table @code
7028 @item (file "path/to/file")
7029 Text will be placed at the beginning or end of that file.
7031 @item (id "id of existing org entry")
7032 Filing as child of this entry, or in the body of the entry.
7034 @item (file+headline "path/to/file" "node headline")
7035 Fast configuration if the target heading is unique in the file.
7037 @item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
7038 For non-unique headings, the full path is safer.
7040 @item (file+regexp  "path/to/file" "regexp to find location")
7041 Use a regular expression to position the cursor.
7043 @item (file+datetree "path/to/file")
7044 Will create a heading in a date tree for today's date@footnote{Datetree
7045 headlines for years accept tags, so if you use both @code{* 2013 :noexport:}
7046 and @code{* 2013} in your file, the capture will refile the note to the first
7047 one matched.}.
7049 @item (file+datetree+prompt "path/to/file")
7050 Will create a heading in a date tree, but will prompt for the date.
7052 @item (file+function "path/to/file" function-finding-location)
7053 A function to find the right location in the file.
7055 @item (clock)
7056 File to the entry that is currently being clocked.
7058 @item (function function-finding-location)
7059 Most general way, write your own function to find both
7060 file and location.
7061 @end table
7063 @item template
7064 The template for creating the capture item.  If you leave this empty, an
7065 appropriate default template will be used.  Otherwise this is a string with
7066 escape codes, which will be replaced depending on time and context of the
7067 capture call.  The string with escapes may be loaded from a template file,
7068 using the special syntax @code{(file "path/to/template")}.  See below for
7069 more details.
7071 @item properties
7072 The rest of the entry is a property list of additional options.
7073 Recognized properties are:
7075 @table @code
7076 @item :prepend
7077 Normally new captured information will be appended at
7078 the target location (last child, last table line, last list item...).
7079 Setting this property will change that.
7081 @item :immediate-finish
7082 When set, do not offer to edit the information, just
7083 file it away immediately.  This makes sense if the template only needs
7084 information that can be added automatically.
7086 @item :empty-lines
7087 Set this to the number of lines to insert
7088 before and after the new item.  Default 0, only common other value is 1.
7090 @item :clock-in
7091 Start the clock in this item.
7093 @item :clock-keep
7094 Keep the clock running when filing the captured entry.
7096 @item :clock-resume
7097 If starting the capture interrupted a clock, restart that clock when finished
7098 with the capture.  Note that @code{:clock-keep} has precedence over
7099 @code{:clock-resume}.  When setting both to @code{t}, the current clock will
7100 run and the previous one will not be resumed.
7102 @item :unnarrowed
7103 Do not narrow the target buffer, simply show the full buffer.  Default is to
7104 narrow it so that you only see the new material.
7106 @item :table-line-pos
7107 Specification of the location in the table where the new line should be
7108 inserted.  It should be a string like @code{"II-3"} meaning that the new
7109 line should become the third line before the second horizontal separator
7110 line.
7112 @item :kill-buffer
7113 If the target file was not yet visited when capture was invoked, kill the
7114 buffer again after capture is completed.
7115 @end table
7116 @end table
7118 @node Template expansion, Templates in contexts, Template elements, Capture templates
7119 @subsubsection Template expansion
7121 In the template itself, special @kbd{%}-escapes@footnote{If you need one of
7122 these sequences literally, escape the @kbd{%} with a backslash.} allow
7123 dynamic insertion of content.  The templates are expanded in the order given here:
7125 @smallexample
7126 %[@var{file}]     @r{Insert the contents of the file given by @var{file}.}
7127 %(@var{sexp})     @r{Evaluate Elisp @var{sexp} and replace with the result.}
7128                   @r{For convenience, %:keyword (see below) placeholders}
7129                   @r{within the expression will be expanded prior to this.}
7130                   @r{The sexp must return a string.}
7131 %<...>      @r{The result of format-time-string on the ... format specification.}
7132 %t          @r{Timestamp, date only.}
7133 %T          @r{Timestamp, with date and time.}
7134 %u, %U      @r{Like the above, but inactive timestamps.}
7135 %i          @r{Initial content, the region when capture is called while the}
7136             @r{region is active.}
7137             @r{The entire text will be indented like @code{%i} itself.}
7138 %a          @r{Annotation, normally the link created with @code{org-store-link}.}
7139 %A          @r{Like @code{%a}, but prompt for the description part.}
7140 %l          @r{Like %a, but only insert the literal link.}
7141 %c          @r{Current kill ring head.}
7142 %x          @r{Content of the X clipboard.}
7143 %k          @r{Title of the currently clocked task.}
7144 %K          @r{Link to the currently clocked task.}
7145 %n          @r{User name (taken from @code{user-full-name}).}
7146 %f          @r{File visited by current buffer when org-capture was called.}
7147 %F          @r{Full path of the file or directory visited by current buffer.}
7148 %:keyword   @r{Specific information for certain link types, see below.}
7149 %^g         @r{Prompt for tags, with completion on tags in target file.}
7150 %^G         @r{Prompt for tags, with completion all tags in all agenda files.}
7151 %^t         @r{Like @code{%t}, but prompt for date.  Similarly @code{%^T}, @code{%^u}, @code{%^U}.}
7152             @r{You may define a prompt like @code{%^@{Birthday@}t}.}
7153 %^C         @r{Interactive selection of which kill or clip to use.}
7154 %^L         @r{Like @code{%^C}, but insert as link.}
7155 %^@{@var{prop}@}p   @r{Prompt the user for a value for property @var{prop}.}
7156 %^@{@var{prompt}@}  @r{prompt the user for a string and replace this sequence with it.}
7157             @r{You may specify a default value and a completion table with}
7158             @r{%^@{prompt|default|completion2|completion3...@}.}
7159             @r{The arrow keys access a prompt-specific history.}
7160 %\n         @r{Insert the text entered at the nth %^@{@var{prompt}@}, where @code{n} is}
7161             @r{a number, starting from 1.}
7162 %?          @r{After completing the template, position cursor here.}
7163 @end smallexample
7165 @noindent
7166 For specific link types, the following keywords will be
7167 defined@footnote{If you define your own link types (@pxref{Adding
7168 hyperlink types}), any property you store with
7169 @code{org-store-link-props} can be accessed in capture templates in a
7170 similar way.}:
7172 @vindex org-from-is-user-regexp
7173 @smallexample
7174 Link type                        |  Available keywords
7175 ---------------------------------+----------------------------------------------
7176 bbdb                             |  %:name %:company
7177 irc                              |  %:server %:port %:nick
7178 vm, vm-imap, wl, mh, mew, rmail  |  %:type %:subject %:message-id
7179                                  |  %:from %:fromname %:fromaddress
7180                                  |  %:to   %:toname   %:toaddress
7181                                  |  %:date @r{(message date header field)}
7182                                  |  %:date-timestamp @r{(date as active timestamp)}
7183                                  |  %:date-timestamp-inactive @r{(date as inactive timestamp)}
7184                                  |  %: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}.}}
7185 gnus                             |  %:group, @r{for messages also all email fields}
7186 w3, w3m                          |  %:url
7187 info                             |  %:file %:node
7188 calendar                         |  %:date
7189 @end smallexample
7191 @noindent
7192 To place the cursor after template expansion use:
7194 @smallexample
7195 %?          @r{After completing the template, position cursor here.}
7196 @end smallexample
7198 @node Templates in contexts,  , Template expansion, Capture templates
7199 @subsubsection Templates in contexts
7201 @vindex org-capture-templates-contexts
7202 To control whether a capture template should be accessible from a specific
7203 context, you can customize @code{org-capture-templates-contexts}.  Let's say
7204 for example that you have a capture template @code{"p"} for storing Gnus
7205 emails containing patches.  Then you would configure this option like this:
7207 @smalllisp
7208 (setq org-capture-templates-contexts
7209       '(("p" (in-mode . "message-mode"))))
7210 @end smalllisp
7212 You can also tell that the command key @code{"p"} should refer to another
7213 template.  In that case, add this command key like this:
7215 @smalllisp
7216 (setq org-capture-templates-contexts
7217       '(("p" "q" (in-mode . "message-mode"))))
7218 @end smalllisp
7220 See the docstring of the variable for more information.
7222 @node Attachments, RSS Feeds, Capture, Capture - Refile - Archive
7223 @section Attachments
7224 @cindex attachments
7226 @vindex org-attach-directory
7227 It is often useful to associate reference material with an outline node/task.
7228 Small chunks of plain text can simply be stored in the subtree of a project.
7229 Hyperlinks (@pxref{Hyperlinks}) can establish associations with
7230 files that live elsewhere on your computer or in the cloud, like emails or
7231 source code files belonging to a project.  Another method is @i{attachments},
7232 which are files located in a directory belonging to an outline node.  Org
7233 uses directories named by the unique ID of each entry.  These directories are
7234 located in the @file{data} directory which lives in the same directory where
7235 your Org file lives@footnote{If you move entries or Org files from one
7236 directory to another, you may want to configure @code{org-attach-directory}
7237 to contain an absolute path.}.  If you initialize this directory with
7238 @code{git init}, Org will automatically commit changes when it sees them.
7239 The attachment system has been contributed to Org by John Wiegley.
7241 In cases where it seems better to do so, you can also attach a directory of your
7242 choice to an entry.  You can also make children inherit the attachment
7243 directory from a parent, so that an entire subtree uses the same attached
7244 directory.
7246 @noindent The following commands deal with attachments:
7248 @table @kbd
7249 @orgcmd{C-c C-a,org-attach}
7250 The dispatcher for commands related to the attachment system.  After these
7251 keys, a list of commands is displayed and you must press an additional key
7252 to select a command:
7254 @table @kbd
7255 @orgcmdtkc{a,C-c C-a a,org-attach-attach}
7256 @vindex org-attach-method
7257 Select a file and move it into the task's attachment directory.  The file
7258 will be copied, moved, or linked, depending on @code{org-attach-method}.
7259 Note that hard links are not supported on all systems.
7261 @kindex C-c C-a c
7262 @kindex C-c C-a m
7263 @kindex C-c C-a l
7264 @item c/m/l
7265 Attach a file using the copy/move/link method.
7266 Note that hard links are not supported on all systems.
7268 @orgcmdtkc{n,C-c C-a n,org-attach-new}
7269 Create a new attachment as an Emacs buffer.
7271 @orgcmdtkc{z,C-c C-a z,org-attach-sync}
7272 Synchronize the current task with its attachment directory, in case you added
7273 attachments yourself.
7275 @orgcmdtkc{o,C-c C-a o,org-attach-open}
7276 @vindex org-file-apps
7277 Open current task's attachment.  If there is more than one, prompt for a
7278 file name first.  Opening will follow the rules set by @code{org-file-apps}.
7279 For more details, see the information on following hyperlinks
7280 (@pxref{Handling links}).
7282 @orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs}
7283 Also open the attachment, but force opening the file in Emacs.
7285 @orgcmdtkc{f,C-c C-a f,org-attach-reveal}
7286 Open the current task's attachment directory.
7288 @orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs}
7289 Also open the directory, but force using @command{dired} in Emacs.
7291 @orgcmdtkc{d,C-c C-a d,org-attach-delete-one}
7292 Select and delete a single attachment.
7294 @orgcmdtkc{D,C-c C-a D,org-attach-delete-all}
7295 Delete all of a task's attachments.  A safer way is to open the directory in
7296 @command{dired} and delete from there.
7298 @orgcmdtkc{s,C-c C-a s,org-attach-set-directory}
7299 @cindex property, ATTACH_DIR
7300 Set a specific directory as the entry's attachment directory.  This works by
7301 putting the directory path into the @code{ATTACH_DIR} property.
7303 @orgcmdtkc{i,C-c C-a i,org-attach-set-inherit}
7304 @cindex property, ATTACH_DIR_INHERIT
7305 Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the
7306 same directory for attachments as the parent does.
7307 @end table
7308 @end table
7310 @node RSS Feeds, Protocols, Attachments, Capture - Refile - Archive
7311 @section RSS feeds
7312 @cindex RSS feeds
7313 @cindex Atom feeds
7315 Org can add and change entries based on information found in RSS feeds and
7316 Atom feeds.  You could use this to make a task out of each new podcast in a
7317 podcast feed.  Or you could use a phone-based note-creating service on the
7318 web to import tasks into Org.  To access feeds, configure the variable
7319 @code{org-feed-alist}.  The docstring of this variable has detailed
7320 information.  Here is just an example:
7322 @smalllisp
7323 @group
7324 (setq org-feed-alist
7325      '(("Slashdot"
7326          "http://rss.slashdot.org/Slashdot/slashdot"
7327          "~/txt/org/feeds.org" "Slashdot Entries")))
7328 @end group
7329 @end smalllisp
7331 @noindent
7332 will configure that new items from the feed provided by
7333 @code{rss.slashdot.org} will result in new entries in the file
7334 @file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
7335 the following command is used:
7337 @table @kbd
7338 @orgcmd{C-c C-x g,org-feed-update-all}
7339 @item C-c C-x g
7340 Collect items from the feeds configured in @code{org-feed-alist} and act upon
7341 them.
7342 @orgcmd{C-c C-x G,org-feed-goto-inbox}
7343 Prompt for a feed name and go to the inbox configured for this feed.
7344 @end table
7346 Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which
7347 it will store information about the status of items in the feed, to avoid
7348 adding the same item several times.  You should add @samp{FEEDSTATUS} to the
7349 list of drawers in that file:
7351 @example
7352 #+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS
7353 @end example
7355 For more information, including how to read atom feeds, see
7356 @file{org-feed.el} and the docstring of @code{org-feed-alist}.
7358 @node Protocols, Refile and copy, RSS Feeds, Capture - Refile - Archive
7359 @section Protocols for external access
7360 @cindex protocols, for external access
7361 @cindex emacsserver
7363 You can set up Org for handling protocol calls from outside applications that
7364 are passed to Emacs through the @file{emacsserver}.  For example, you can
7365 configure bookmarks in your web browser to send a link to the current page to
7366 Org and create a note from it using capture (@pxref{Capture}).  Or you
7367 could create a bookmark that will tell Emacs to open the local source file of
7368 a remote website you are looking at with the browser.  See
7369 @uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed
7370 documentation and setup instructions.
7372 @node Refile and copy, Archiving, Protocols, Capture - Refile - Archive
7373 @section Refile and copy
7374 @cindex refiling notes
7375 @cindex copying notes
7377 When reviewing the captured data, you may want to refile or to copy some of
7378 the entries into a different list, for example into a project.  Cutting,
7379 finding the right location, and then pasting the note is cumbersome.  To
7380 simplify this process, you can use the following special command:
7382 @table @kbd
7383 @orgcmd{C-c M-w,org-copy}
7384 @findex org-copy
7385 Copying works like refiling, except that the original note is not deleted.
7386 @orgcmd{C-c C-w,org-refile}
7387 @findex org-refile
7388 @vindex org-reverse-note-order
7389 @vindex org-refile-targets
7390 @vindex org-refile-use-outline-path
7391 @vindex org-outline-path-complete-in-steps
7392 @vindex org-refile-allow-creating-parent-nodes
7393 @vindex org-log-refile
7394 @vindex org-refile-use-cache
7395 @vindex org-refile-keep
7396 Refile the entry or region at point.  This command offers possible locations
7397 for refiling the entry and lets you select one with completion.  The item (or
7398 all items in the region) is filed below the target heading as a subitem.
7399 Depending on @code{org-reverse-note-order}, it will be either the first or
7400 last subitem.@*
7401 By default, all level 1 headlines in the current buffer are considered to be
7402 targets, but you can have more complex definitions across a number of files.
7403 See the variable @code{org-refile-targets} for details.  If you would like to
7404 select a location via a file-path-like completion along the outline path, see
7405 the variables @code{org-refile-use-outline-path} and
7406 @code{org-outline-path-complete-in-steps}.  If you would like to be able to
7407 create new nodes as new parents for refiling on the fly, check the
7408 variable @code{org-refile-allow-creating-parent-nodes}.
7409 When the variable @code{org-log-refile}@footnote{with corresponding
7410 @code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},
7411 and @code{nologrefile}} is set, a timestamp or a note will be
7412 recorded when an entry has been refiled.
7413 @orgkey{C-u C-c C-w}
7414 Use the refile interface to jump to a heading.
7415 @orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored}
7416 Jump to the location where @code{org-refile} last moved a tree to.
7417 @item C-2 C-c C-w
7418 Refile as the child of the item currently being clocked.
7419 @item C-3 C-c C-w
7420 Refile and keep the entry in place.  Also see @code{org-refile-keep} to make
7421 this the default behavior, and beware that this may result in duplicated
7422 @code{ID} properties.
7423 @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}
7424 Clear the target cache.  Caching of refile targets can be turned on by
7425 setting @code{org-refile-use-cache}.  To make the command see new possible
7426 targets, you have to clear the cache with this command.
7427 @end table
7429 @node Archiving,  , Refile and copy, Capture - Refile - Archive
7430 @section Archiving
7431 @cindex archiving
7433 When a project represented by a (sub)tree is finished, you may want
7434 to move the tree out of the way and to stop it from contributing to the
7435 agenda.  Archiving is important to keep your working files compact and global
7436 searches like the construction of agenda views fast.
7438 @table @kbd
7439 @orgcmd{C-c C-x C-a,org-archive-subtree-default}
7440 @vindex org-archive-default-command
7441 Archive the current entry using the command specified in the variable
7442 @code{org-archive-default-command}.
7443 @end table
7445 @menu
7446 * Moving subtrees::             Moving a tree to an archive file
7447 * Internal archiving::          Switch off a tree but keep it in the file
7448 @end menu
7450 @node Moving subtrees, Internal archiving, Archiving, Archiving
7451 @subsection Moving a tree to the archive file
7452 @cindex external archiving
7454 The most common archiving action is to move a project tree to another file,
7455 the archive file.
7457 @table @kbd
7458 @orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
7459 @vindex org-archive-location
7460 Archive the subtree starting at the cursor position to the location
7461 given by @code{org-archive-location}.
7462 @orgkey{C-u C-c C-x C-s}
7463 Check if any direct children of the current headline could be moved to
7464 the archive.  To do this, each subtree is checked for open TODO entries.
7465 If none are found, the command offers to move it to the archive
7466 location.  If the cursor is @emph{not} on a headline when this command
7467 is invoked, the level 1 trees will be checked.
7468 @end table
7470 @cindex archive locations
7471 The default archive location is a file in the same directory as the
7472 current file, with the name derived by appending @file{_archive} to the
7473 current file name.  You can also choose what heading to file archived
7474 items under, with the possibility to add them to a datetree in a file.
7475 For information and examples on how to specify the file and the heading,
7476 see the documentation string of the variable
7477 @code{org-archive-location}.
7479 There is also an in-buffer option for setting this variable, for
7480 example@footnote{For backward compatibility, the following also works:
7481 If there are several such lines in a file, each specifies the archive
7482 location for the text below it.  The first such line also applies to any
7483 text before its definition.  However, using this method is
7484 @emph{strongly} deprecated as it is incompatible with the outline
7485 structure of the document.  The correct method for setting multiple
7486 archive locations in a buffer is using properties.}:
7488 @cindex #+ARCHIVE
7489 @example
7490 #+ARCHIVE: %s_done::
7491 @end example
7493 @cindex property, ARCHIVE
7494 @noindent
7495 If you would like to have a special ARCHIVE location for a single entry
7496 or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
7497 location as the value (@pxref{Properties and Columns}).
7499 @vindex org-archive-save-context-info
7500 When a subtree is moved, it receives a number of special properties that
7501 record context information like the file from where the entry came, its
7502 outline path the archiving time etc.  Configure the variable
7503 @code{org-archive-save-context-info} to adjust the amount of information
7504 added.
7507 @node Internal archiving,  , Moving subtrees, Archiving
7508 @subsection Internal archiving
7510 If you want to just switch off (for agenda views) certain subtrees without
7511 moving them to a different file, you can use the @code{ARCHIVE tag}.
7513 A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
7514 its location in the outline tree, but behaves in the following way:
7515 @itemize @minus
7516 @item
7517 @vindex org-cycle-open-archived-trees
7518 It does not open when you attempt to do so with a visibility cycling
7519 command (@pxref{Visibility cycling}).  You can force cycling archived
7520 subtrees with @kbd{C-@key{TAB}}, or by setting the option
7521 @code{org-cycle-open-archived-trees}.  Also normal outline commands like
7522 @code{show-all} will open archived subtrees.
7523 @item
7524 @vindex org-sparse-tree-open-archived-trees
7525 During sparse tree construction (@pxref{Sparse trees}), matches in
7526 archived subtrees are not exposed, unless you configure the option
7527 @code{org-sparse-tree-open-archived-trees}.
7528 @item
7529 @vindex org-agenda-skip-archived-trees
7530 During agenda view construction (@pxref{Agenda Views}), the content of
7531 archived trees is ignored unless you configure the option
7532 @code{org-agenda-skip-archived-trees}, in which case these trees will always
7533 be included.  In the agenda you can press @kbd{v a} to get archives
7534 temporarily included.
7535 @item
7536 @vindex org-export-with-archived-trees
7537 Archived trees are not exported (@pxref{Exporting}), only the headline
7538 is.  Configure the details using the variable
7539 @code{org-export-with-archived-trees}.
7540 @item
7541 @vindex org-columns-skip-archived-trees
7542 Archived trees are excluded from column view unless the variable
7543 @code{org-columns-skip-archived-trees} is configured to @code{nil}.
7544 @end itemize
7546 The following commands help manage the ARCHIVE tag:
7548 @table @kbd
7549 @orgcmd{C-c C-x a,org-toggle-archive-tag}
7550 Toggle the ARCHIVE tag for the current headline.  When the tag is set,
7551 the headline changes to a shadowed face, and the subtree below it is
7552 hidden.
7553 @orgkey{C-u C-c C-x a}
7554 Check if any direct children of the current headline should be archived.
7555 To do this, each subtree is checked for open TODO entries.  If none are
7556 found, the command offers to set the ARCHIVE tag for the child.  If the
7557 cursor is @emph{not} on a headline when this command is invoked, the
7558 level 1 trees will be checked.
7559 @orgcmd{C-@kbd{TAB},org-force-cycle-archived}
7560 Cycle a tree even if it is tagged with ARCHIVE.
7561 @orgcmd{C-c C-x A,org-archive-to-archive-sibling}
7562 Move the current entry to the @emph{Archive Sibling}.  This is a sibling of
7563 the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}.  The
7564 entry becomes a child of that sibling and in this way retains a lot of its
7565 original context, including inherited tags and approximate position in the
7566 outline.
7567 @end table
7570 @node Agenda Views, Markup, Capture - Refile - Archive, Top
7571 @chapter Agenda views
7572 @cindex agenda views
7574 Due to the way Org works, TODO items, time-stamped items, and
7575 tagged headlines can be scattered throughout a file or even a number of
7576 files.  To get an overview of open action items, or of events that are
7577 important for a particular date, this information must be collected,
7578 sorted and displayed in an organized way.
7580 Org can select items based on various criteria and display them
7581 in a separate buffer.  Seven different view types are provided:
7583 @itemize @bullet
7584 @item
7585 an @emph{agenda} that is like a calendar and shows information
7586 for specific dates,
7587 @item
7588 a @emph{TODO list} that covers all unfinished
7589 action items,
7590 @item
7591 a @emph{match view}, showings headlines based on the tags, properties, and
7592 TODO state associated with them,
7593 @item
7594 a @emph{timeline view} that shows all events in a single Org file,
7595 in time-sorted view,
7596 @item
7597 a @emph{text search view} that shows all entries from multiple files
7598 that contain specified keywords,
7599 @item
7600 a @emph{stuck projects view} showing projects that currently don't move
7601 along, and
7602 @item
7603 @emph{custom views} that are special searches and combinations of different
7604 views.
7605 @end itemize
7607 @noindent
7608 The extracted information is displayed in a special @emph{agenda
7609 buffer}.  This buffer is read-only, but provides commands to visit the
7610 corresponding locations in the original Org files, and even to
7611 edit these files remotely.
7613 @vindex org-agenda-window-setup
7614 @vindex org-agenda-restore-windows-after-quit
7615 Two variables control how the agenda buffer is displayed and whether the
7616 window configuration is restored when the agenda exits:
7617 @code{org-agenda-window-setup} and
7618 @code{org-agenda-restore-windows-after-quit}.
7620 @menu
7621 * Agenda files::                Files being searched for agenda information
7622 * Agenda dispatcher::           Keyboard access to agenda views
7623 * Built-in agenda views::       What is available out of the box?
7624 * Presentation and sorting::    How agenda items are prepared for display
7625 * Agenda commands::             Remote editing of Org trees
7626 * Custom agenda views::         Defining special searches and views
7627 * Exporting Agenda Views::      Writing a view to a file
7628 * Agenda column view::          Using column view for collected entries
7629 @end menu
7631 @node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views
7632 @section Agenda files
7633 @cindex agenda files
7634 @cindex files for agenda
7636 @vindex org-agenda-files
7637 The information to be shown is normally collected from all @emph{agenda
7638 files}, the files listed in the variable
7639 @code{org-agenda-files}@footnote{If the value of that variable is not a
7640 list, but a single file name, then the list of agenda files will be
7641 maintained in that external file.}.  If a directory is part of this list,
7642 all files with the extension @file{.org} in this directory will be part
7643 of the list.
7645 Thus, even if you only work with a single Org file, that file should
7646 be put into the list@footnote{When using the dispatcher, pressing
7647 @kbd{<} before selecting a command will actually limit the command to
7648 the current file, and ignore @code{org-agenda-files} until the next
7649 dispatcher command.}.  You can customize @code{org-agenda-files}, but
7650 the easiest way to maintain it is through the following commands
7652 @cindex files, adding to agenda list
7653 @table @kbd
7654 @orgcmd{C-c [,org-agenda-file-to-front}
7655 Add current file to the list of agenda files.  The file is added to
7656 the front of the list.  If it was already in the list, it is moved to
7657 the front.  With a prefix argument, file is added/moved to the end.
7658 @orgcmd{C-c ],org-remove-file}
7659 Remove current file from the list of agenda files.
7660 @kindex C-,
7661 @cindex cycling, of agenda files
7662 @orgcmd{C-',org-cycle-agenda-files}
7663 @itemx C-,
7664 Cycle through agenda file list, visiting one file after the other.
7665 @kindex M-x org-iswitchb
7666 @item M-x org-iswitchb RET
7667 Command to use an @code{iswitchb}-like interface to switch to and between Org
7668 buffers.
7669 @end table
7671 @noindent
7672 The Org menu contains the current list of files and can be used
7673 to visit any of them.
7675 If you would like to focus the agenda temporarily on a file not in
7676 this list, or on just one file in the list, or even on only a subtree in a
7677 file, then this can be done in different ways.  For a single agenda command,
7678 you may press @kbd{<} once or several times in the dispatcher
7679 (@pxref{Agenda dispatcher}).  To restrict the agenda scope for an
7680 extended period, use the following commands:
7682 @table @kbd
7683 @orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
7684 Permanently restrict the agenda to the current subtree.  When with a
7685 prefix argument, or with the cursor before the first headline in a file,
7686 the agenda scope is set to the entire file.  This restriction remains in
7687 effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
7688 or @kbd{>} in the agenda dispatcher.  If there is a window displaying an
7689 agenda view, the new restriction takes effect immediately.
7690 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
7691 Remove the permanent restriction created by @kbd{C-c C-x <}.
7692 @end table
7694 @noindent
7695 When working with @file{speedbar.el}, you can use the following commands in
7696 the Speedbar frame:
7698 @table @kbd
7699 @orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
7700 Permanently restrict the agenda to the item---either an Org file or a subtree
7701 in such a file---at the cursor in the Speedbar frame.
7702 If there is a window displaying an agenda view, the new restriction takes
7703 effect immediately.
7704 @orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
7705 Lift the restriction.
7706 @end table
7708 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views
7709 @section The agenda dispatcher
7710 @cindex agenda dispatcher
7711 @cindex dispatching agenda commands
7712 The views are created through a dispatcher, which should be bound to a
7713 global key---for example @kbd{C-c a} (@pxref{Activation}).  In the
7714 following we will assume that @kbd{C-c a} is indeed how the dispatcher
7715 is accessed and list keyboard access to commands accordingly.  After
7716 pressing @kbd{C-c a}, an additional letter is required to execute a
7717 command.  The dispatcher offers the following default commands:
7719 @table @kbd
7720 @item a
7721 Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
7722 @item t @r{/} T
7723 Create a list of all TODO items (@pxref{Global TODO list}).
7724 @item m @r{/} M
7725 Create a list of headlines matching a TAGS expression (@pxref{Matching
7726 tags and properties}).
7727 @item L
7728 Create the timeline view for the current buffer (@pxref{Timeline}).
7729 @item s
7730 Create a list of entries selected by a boolean expression of keywords
7731 and/or regular expressions that must or must not occur in the entry.
7732 @item /
7733 @vindex org-agenda-text-search-extra-files
7734 Search for a regular expression in all agenda files and additionally in
7735 the files listed in @code{org-agenda-text-search-extra-files}.  This
7736 uses the Emacs command @code{multi-occur}.  A prefix argument can be
7737 used to specify the number of context lines for each match, default is
7739 @item # @r{/} !
7740 Create a list of stuck projects (@pxref{Stuck projects}).
7741 @item <
7742 Restrict an agenda command to the current buffer@footnote{For backward
7743 compatibility, you can also press @kbd{1} to restrict to the current
7744 buffer.}.  After pressing @kbd{<}, you still need to press the character
7745 selecting the command.
7746 @item < <
7747 If there is an active region, restrict the following agenda command to
7748 the region.  Otherwise, restrict it to the current subtree@footnote{For
7749 backward compatibility, you can also press @kbd{0} to restrict to the
7750 current region/subtree.}.  After pressing @kbd{< <}, you still need to press the
7751 character selecting the command.
7753 @item *
7754 @vindex org-agenda-sticky
7755 Toggle sticky agenda views.  By default, Org maintains only a single agenda
7756 buffer and rebuilds it each time you change the view, to make sure everything
7757 is always up to date.  If you switch between views often and the build time
7758 bothers you, you can turn on sticky agenda buffers (make this the default by
7759 customizing the variable @code{org-agenda-sticky}).  With sticky agendas, the
7760 dispatcher only switches to the selected view, you need to update it by hand
7761 with @kbd{r} or @kbd{g}.  You can toggle sticky agenda view any time with
7762 @code{org-toggle-sticky-agenda}.
7763 @end table
7765 You can also define custom commands that will be accessible through the
7766 dispatcher, just like the default commands.  This includes the
7767 possibility to create extended agenda buffers that contain several
7768 blocks together, for example the weekly agenda, the global TODO list and
7769 a number of special tags matches.  @xref{Custom agenda views}.
7771 @node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda Views
7772 @section The built-in agenda views
7774 In this section we describe the built-in views.
7776 @menu
7777 * Weekly/daily agenda::         The calendar page with current tasks
7778 * Global TODO list::            All unfinished action items
7779 * Matching tags and properties::  Structured information with fine-tuned search
7780 * Timeline::                    Time-sorted view for single file
7781 * Search view::                 Find entries by searching for text
7782 * Stuck projects::              Find projects you need to review
7783 @end menu
7785 @node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
7786 @subsection The weekly/daily agenda
7787 @cindex agenda
7788 @cindex weekly agenda
7789 @cindex daily agenda
7791 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
7792 paper agenda, showing all the tasks for the current week or day.
7794 @table @kbd
7795 @cindex org-agenda, command
7796 @orgcmd{C-c a a,org-agenda-list}
7797 Compile an agenda for the current week from a list of Org files.  The agenda
7798 shows the entries for each day.  With a numeric prefix@footnote{For backward
7799 compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be
7800 listed before the agenda.  This feature is deprecated, use the dedicated TODO
7801 list, or a block agenda instead (@pxref{Block agenda}).}  (like @kbd{C-u 2 1
7802 C-c a a}) you may set the number of days to be displayed.
7803 @end table
7805 @vindex org-agenda-span
7806 @vindex org-agenda-ndays
7807 @vindex org-agenda-start-day
7808 @vindex org-agenda-start-on-weekday
7809 The default number of days displayed in the agenda is set by the variable
7810 @code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}).  This
7811 variable can be set to any number of days you want to see by default in the
7812 agenda, or to a span name, such as @code{day}, @code{week}, @code{month} or
7813 @code{year}.  For weekly agendas, the default is to start on the previous
7814 monday (see @code{org-agenda-start-on-weekday}).  You can also set the start
7815 date using a date shift: @code{(setq org-agenda-start-day "+10d")} will
7816 start the agenda ten days from today in the future.
7818 Remote editing from the agenda buffer means, for example, that you can
7819 change the dates of deadlines and appointments from the agenda buffer.
7820 The commands available in the Agenda buffer are listed in @ref{Agenda
7821 commands}.
7823 @subsubheading Calendar/Diary integration
7824 @cindex calendar integration
7825 @cindex diary integration
7827 Emacs contains the calendar and diary by Edward M. Reingold.  The
7828 calendar displays a three-month calendar with holidays from different
7829 countries and cultures.  The diary allows you to keep track of
7830 anniversaries, lunar phases, sunrise/set, recurrent appointments
7831 (weekly, monthly) and more.  In this way, it is quite complementary to
7832 Org.  It can be very useful to combine output from Org with
7833 the diary.
7835 In order to include entries from the Emacs diary into Org mode's
7836 agenda, you only need to customize the variable
7838 @lisp
7839 (setq org-agenda-include-diary t)
7840 @end lisp
7842 @noindent After that, everything will happen automatically.  All diary
7843 entries including holidays, anniversaries, etc., will be included in the
7844 agenda buffer created by Org mode.  @key{SPC}, @key{TAB}, and
7845 @key{RET} can be used from the agenda buffer to jump to the diary
7846 file in order to edit existing diary entries.  The @kbd{i} command to
7847 insert new entries for the current date works in the agenda buffer, as
7848 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
7849 Sunrise/Sunset times, show lunar phases and to convert to other
7850 calendars, respectively.  @kbd{c} can be used to switch back and forth
7851 between calendar and agenda.
7853 If you are using the diary only for sexp entries and holidays, it is
7854 faster to not use the above setting, but instead to copy or even move
7855 the entries into an Org file.  Org mode evaluates diary-style sexp
7856 entries, and does it faster because there is no overhead for first
7857 creating the diary display.  Note that the sexp entries must start at
7858 the left margin, no whitespace is allowed before them.  For example,
7859 the following segment of an Org file will be processed and entries
7860 will be made in the agenda:
7862 @example
7863 * Birthdays and similar stuff
7864 #+CATEGORY: Holiday
7865 %%(org-calendar-holiday)   ; special function for holiday names
7866 #+CATEGORY: Ann
7867 %%(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
7868 %%(org-anniversary 1869 10  2) Mahatma Gandhi would be %d years old
7869 @end example
7871 @subsubheading Anniversaries from BBDB
7872 @cindex BBDB, anniversaries
7873 @cindex anniversaries, from BBDB
7875 If you are using the Big Brothers Database to store your contacts, you will
7876 very likely prefer to store anniversaries in BBDB rather than in a
7877 separate Org or diary file.  Org supports this and will show BBDB
7878 anniversaries as part of the agenda.  All you need to do is to add the
7879 following to one of your agenda files:
7881 @example
7882 * Anniversaries
7883   :PROPERTIES:
7884   :CATEGORY: Anniv
7885   :END:
7886 %%(org-bbdb-anniversaries)
7887 @end example
7889 You can then go ahead and define anniversaries for a BBDB record.  Basically,
7890 you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
7891 record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
7892 followed by a space and the class of the anniversary (@samp{birthday} or
7893 @samp{wedding}, or a format string).  If you omit the class, it will default to
7894 @samp{birthday}.  Here are a few examples, the header for the file
7895 @file{org-bbdb.el} contains more detailed information.
7897 @example
7898 1973-06-22
7899 06-22
7900 1955-08-02 wedding
7901 2008-04-14 %s released version 6.01 of org mode, %d years ago
7902 @end example
7904 After a change to BBDB, or for the first agenda display during an Emacs
7905 session, the agenda display will suffer a short delay as Org updates its
7906 hash with anniversaries.  However, from then on things will be very fast---much
7907 faster in fact than a long list of @samp{%%(diary-anniversary)} entries
7908 in an Org or Diary file.
7910 @subsubheading Appointment reminders
7911 @cindex @file{appt.el}
7912 @cindex appointment reminders
7913 @cindex appointment
7914 @cindex reminders
7916 Org can interact with Emacs appointments notification facility.  To add the
7917 appointments of your agenda files, use the command @code{org-agenda-to-appt}.
7918 This command lets you filter through the list of your appointments and add
7919 only those belonging to a specific category or matching a regular expression.
7920 It also reads a @code{APPT_WARNTIME} property which will then override the
7921 value of @code{appt-message-warning-time} for this appointment.  See the
7922 docstring for details.
7924 @node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views
7925 @subsection The global TODO list
7926 @cindex global TODO list
7927 @cindex TODO list, global
7929 The global TODO list contains all unfinished TODO items formatted and
7930 collected into a single place.
7932 @table @kbd
7933 @orgcmd{C-c a t,org-todo-list}
7934 Show the global TODO list.  This collects the TODO items from all agenda
7935 files (@pxref{Agenda Views}) into a single buffer.  By default, this lists
7936 items with a state the is not a DONE state.  The buffer is in
7937 @code{agenda-mode}, so there are commands to examine and manipulate the TODO
7938 entries directly from that buffer (@pxref{Agenda commands}).
7939 @orgcmd{C-c a T,org-todo-list}
7940 @cindex TODO keyword matching
7941 @vindex org-todo-keywords
7942 Like the above, but allows selection of a specific TODO keyword.  You can
7943 also do this by specifying a prefix argument to @kbd{C-c a t}.  You are
7944 prompted for a keyword, and you may also specify several keywords by
7945 separating them with @samp{|} as the boolean OR operator.  With a numeric
7946 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
7947 @kindex r
7948 The @kbd{r} key in the agenda buffer regenerates it, and you can give
7949 a prefix argument to this command to change the selected TODO keyword,
7950 for example @kbd{3 r}.  If you often need a search for a specific
7951 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
7952 Matching specific TODO keywords can also be done as part of a tags
7953 search (@pxref{Tag searches}).
7954 @end table
7956 Remote editing of TODO items means that you can change the state of a
7957 TODO entry with a single key press.  The commands available in the
7958 TODO list are described in @ref{Agenda commands}.
7960 @cindex sublevels, inclusion into TODO list
7961 Normally the global TODO list simply shows all headlines with TODO
7962 keywords.  This list can become very long.  There are two ways to keep
7963 it more compact:
7964 @itemize @minus
7965 @item
7966 @vindex org-agenda-todo-ignore-scheduled
7967 @vindex org-agenda-todo-ignore-deadlines
7968 @vindex org-agenda-todo-ignore-timestamp
7969 @vindex org-agenda-todo-ignore-with-date
7970 Some people view a TODO item that has been @emph{scheduled} for execution or
7971 have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.
7972 Configure the variables @code{org-agenda-todo-ignore-scheduled},
7973 @code{org-agenda-todo-ignore-deadlines},
7974 @code{org-agenda-todo-ignore-timestamp} and/or
7975 @code{org-agenda-todo-ignore-with-date} to exclude such items from the global
7976 TODO list.
7977 @item
7978 @vindex org-agenda-todo-list-sublevels
7979 TODO items may have sublevels to break up the task into subtasks.  In
7980 such cases it may be enough to list only the highest level TODO headline
7981 and omit the sublevels from the global list.  Configure the variable
7982 @code{org-agenda-todo-list-sublevels} to get this behavior.
7983 @end itemize
7985 @node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views
7986 @subsection Matching tags and properties
7987 @cindex matching, of tags
7988 @cindex matching, of properties
7989 @cindex tags view
7990 @cindex match view
7992 If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
7993 or have properties (@pxref{Properties and Columns}), you can select headlines
7994 based on this metadata and collect them into an agenda buffer.  The match
7995 syntax described here also applies when creating sparse trees with @kbd{C-c /
7998 @table @kbd
7999 @orgcmd{C-c a m,org-tags-view}
8000 Produce a list of all headlines that match a given set of tags.  The
8001 command prompts for a selection criterion, which is a boolean logic
8002 expression with tags, like @samp{+work+urgent-withboss} or
8003 @samp{work|home} (@pxref{Tags}).  If you often need a specific search,
8004 define a custom command for it (@pxref{Agenda dispatcher}).
8005 @orgcmd{C-c a M,org-tags-view}
8006 @vindex org-tags-match-list-sublevels
8007 @vindex org-agenda-tags-todo-honor-ignore-options
8008 Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
8009 not-DONE state and force checking subitems (see variable
8010 @code{org-tags-match-list-sublevels}).  To exclude scheduled/deadline items,
8011 see the variable @code{org-agenda-tags-todo-honor-ignore-options}.  Matching
8012 specific TODO keywords together with a tags match is also possible, see
8013 @ref{Tag searches}.
8014 @end table
8016 The commands available in the tags list are described in @ref{Agenda
8017 commands}.
8019 @subsubheading Match syntax
8021 @cindex Boolean logic, for tag/property searches
8022 A search string can use Boolean operators @samp{&} for @code{AND} and
8023 @samp{|} for @code{OR}@.  @samp{&} binds more strongly than @samp{|}.
8024 Parentheses are not implemented.  Each element in the search is either a
8025 tag, a regular expression matching tags, or an expression like
8026 @code{PROPERTY OPERATOR VALUE} with a comparison operator, accessing a
8027 property value.  Each element may be preceded by @samp{-}, to select
8028 against it, and @samp{+} is syntactic sugar for positive selection.  The
8029 @code{AND} operator @samp{&} is optional when @samp{+} or @samp{-} is
8030 present.  Here are some examples, using only tags.
8032 @table @samp
8033 @item work
8034 Select headlines tagged @samp{:work:}.
8035 @item work&boss
8036 Select headlines tagged @samp{:work:} and @samp{:boss:}.
8037 @item +work-boss
8038 Select headlines tagged @samp{:work:}, but discard those also tagged
8039 @samp{:boss:}.
8040 @item work|laptop
8041 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
8042 @item work|laptop+night
8043 Like before, but require the @samp{:laptop:} lines to be tagged also
8044 @samp{:night:}.
8045 @end table
8047 @cindex regular expressions, with tags search
8048 Instead of a tag, you may also specify a regular expression enclosed in curly
8049 braces.  For example,
8050 @samp{work+@{^boss.*@}} matches headlines that contain the tag
8051 @samp{:work:} and any tag @i{starting} with @samp{boss}.
8053 @cindex group tags, as regular expressions
8054 Group tags (@pxref{Tag groups}) are expanded as regular expressions.  E.g.,
8055 if @samp{:work:} is a group tag for the group @samp{:work:lab:conf:}, then
8056 searching for @samp{work} will search for @samp{@{\(?:work\|lab\|conf\)@}}
8057 and searching for @samp{-work} will search for all headlines but those with
8058 one of the tag in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}).
8060 @cindex TODO keyword matching, with tags search
8061 @cindex level, require for tags/property match
8062 @cindex category, require for tags/property match
8063 @vindex org-odd-levels-only
8064 You may also test for properties (@pxref{Properties and Columns}) at the same
8065 time as matching tags.  The properties may be real properties, or special
8066 properties that represent other metadata (@pxref{Special properties}).  For
8067 example, the ``property'' @code{TODO} represents the TODO keyword of the
8068 entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of
8069 the entry.  The ITEM special property cannot currently be used in tags/property
8070 searches@footnote{But @pxref{x-agenda-skip-entry-regexp,
8071 ,skipping entries based on regexp}.}.
8073 Except the @pxref{Special properties}, one other ``property'' can also be
8074 used. @code{LEVEL} represents the level of an entry.  So a search
8075 @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines that have
8076 the tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE@.
8077 In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not count
8078 the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
8080 Here are more examples:
8082 @table @samp
8083 @item work+TODO="WAITING"
8084 Select @samp{:work:}-tagged TODO lines with the specific TODO
8085 keyword @samp{WAITING}.
8086 @item work+TODO="WAITING"|home+TODO="WAITING"
8087 Waiting tasks both at work and at home.
8088 @end table
8090 When matching properties, a number of different operators can be used to test
8091 the value of a property.  Here is a complex example:
8093 @example
8094 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2         \
8095          +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
8096 @end example
8098 @noindent
8099 The type of comparison will depend on how the comparison value is written:
8100 @itemize @minus
8101 @item
8102 If the comparison value is a plain number, a numerical comparison is done,
8103 and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
8104 @samp{>=}, and @samp{<>}.
8105 @item
8106 If the comparison value is enclosed in double-quotes,
8107 a string comparison is done, and the same operators are allowed.
8108 @item
8109 If the comparison value is enclosed in double-quotes @emph{and} angular
8110 brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
8111 assumed to be date/time specifications in the standard Org way, and the
8112 comparison will be done accordingly.  Special values that will be recognized
8113 are @code{"<now>"} for now (including time), and @code{"<today>"}, and
8114 @code{"<tomorrow>"} for these days at 0:00 hours, i.e., without a time
8115 specification.  Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
8116 @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
8117 respectively, can be used.
8118 @item
8119 If the comparison value is enclosed
8120 in curly braces, a regexp match is performed, with @samp{=} meaning that the
8121 regexp matches the property value, and @samp{<>} meaning that it does not
8122 match.
8123 @end itemize
8125 So the search string in the example finds entries tagged @samp{:work:} but
8126 not @samp{:boss:}, which also have a priority value @samp{A}, a
8127 @samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
8128 property that is numerically smaller than 2, a @samp{:With:} property that is
8129 matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
8130 on or after October 11, 2008.
8132 Accessing TODO, LEVEL, and CATEGORY during a search is fast.  Accessing any
8133 other properties will slow down the search.  However, once you have paid the
8134 price by accessing one property, testing additional properties is cheap
8135 again.
8137 You can configure Org mode to use property inheritance during a search, but
8138 beware that this can slow down searches considerably.  See @ref{Property
8139 inheritance}, for details.
8141 For backward compatibility, and also for typing speed, there is also a
8142 different way to test TODO states in a search.  For this, terminate the
8143 tags/property part of the search string (which may include several terms
8144 connected with @samp{|}) with a @samp{/} and then specify a Boolean
8145 expression just for TODO keywords.  The syntax is then similar to that for
8146 tags, but should be applied with care: for example, a positive selection on
8147 several TODO keywords cannot meaningfully be combined with boolean AND@.
8148 However, @emph{negative selection} combined with AND can be meaningful.  To
8149 make sure that only lines are checked that actually have any TODO keyword
8150 (resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
8151 part after the slash with @samp{!}.  Using @kbd{C-c a M} or @samp{/!} will
8152 not match TODO keywords in a DONE state.  Examples:
8154 @table @samp
8155 @item work/WAITING
8156 Same as @samp{work+TODO="WAITING"}
8157 @item work/!-WAITING-NEXT
8158 Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
8159 nor @samp{NEXT}
8160 @item work/!+WAITING|+NEXT
8161 Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
8162 @samp{NEXT}.
8163 @end table
8165 @node Timeline, Search view, Matching tags and properties, Built-in agenda views
8166 @subsection Timeline for a single file
8167 @cindex timeline, single file
8168 @cindex time-sorted view
8170 The timeline summarizes all time-stamped items from a single Org mode
8171 file in a @emph{time-sorted view}.  The main purpose of this command is
8172 to give an overview over events in a project.
8174 @table @kbd
8175 @orgcmd{C-c a L,org-timeline}
8176 Show a time-sorted view of the Org file, with all time-stamped items.
8177 When called with a @kbd{C-u} prefix, all unfinished TODO entries
8178 (scheduled or not) are also listed under the current date.
8179 @end table
8181 @noindent
8182 The commands available in the timeline buffer are listed in
8183 @ref{Agenda commands}.
8185 @node Search view, Stuck projects, Timeline, Built-in agenda views
8186 @subsection Search view
8187 @cindex search view
8188 @cindex text search
8189 @cindex searching, for text
8191 This agenda view is a general text search facility for Org mode entries.
8192 It is particularly useful to find notes.
8194 @table @kbd
8195 @orgcmd{C-c a s,org-search-view}
8196 This is a special search that lets you select entries by matching a substring
8197 or specific words using a boolean logic.
8198 @end table
8199 For example, the search string @samp{computer equipment} will find entries
8200 that contain @samp{computer equipment} as a substring.  If the two words are
8201 separated by more space or a line break, the search will still match.
8202 Search view can also search for specific keywords in the entry, using Boolean
8203 logic.  The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
8204 will search for note entries that contain the keywords @code{computer}
8205 and @code{wifi}, but not the keyword @code{ethernet}, and which are also
8206 not matched by the regular expression @code{8\.11[bg]}, meaning to
8207 exclude both 8.11b and 8.11g.  The first @samp{+} is necessary to turn on
8208 word search, other @samp{+} characters are optional.  For more details, see
8209 the docstring of the command @code{org-search-view}.
8211 @vindex org-agenda-text-search-extra-files
8212 Note that in addition to the agenda files, this command will also search
8213 the files listed in @code{org-agenda-text-search-extra-files}.
8215 @node Stuck projects,  , Search view, Built-in agenda views
8216 @subsection Stuck projects
8217 @pindex GTD, Getting Things Done
8219 If you are following a system like David Allen's GTD to organize your
8220 work, one of the ``duties'' you have is a regular review to make sure
8221 that all projects move along.  A @emph{stuck} project is a project that
8222 has no defined next actions, so it will never show up in the TODO lists
8223 Org mode produces.  During the review, you need to identify such
8224 projects and define next actions for them.
8226 @table @kbd
8227 @orgcmd{C-c a #,org-agenda-list-stuck-projects}
8228 List projects that are stuck.
8229 @kindex C-c a !
8230 @item C-c a !
8231 @vindex org-stuck-projects
8232 Customize the variable @code{org-stuck-projects} to define what a stuck
8233 project is and how to find it.
8234 @end table
8236 You almost certainly will have to configure this view before it will
8237 work for you.  The built-in default assumes that all your projects are
8238 level-2 headlines, and that a project is not stuck if it has at least
8239 one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
8241 Let's assume that you, in your own way of using Org mode, identify
8242 projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
8243 indicate a project that should not be considered yet.  Let's further
8244 assume that the TODO keyword DONE marks finished projects, and that NEXT
8245 and TODO indicate next actions.  The tag @@SHOP indicates shopping and
8246 is a next action even without the NEXT tag.  Finally, if the project
8247 contains the special word IGNORE anywhere, it should not be listed
8248 either.  In this case you would start by identifying eligible projects
8249 with a tags/todo match@footnote{@xref{Tag searches}.}
8250 @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, and
8251 IGNORE in the subtree to identify projects that are not stuck.  The
8252 correct customization for this is
8254 @lisp
8255 (setq org-stuck-projects
8256       '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
8257                                "\\<IGNORE\\>"))
8258 @end lisp
8260 Note that if a project is identified as non-stuck, the subtree of this entry
8261 will still be searched for stuck projects.
8263 @node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda Views
8264 @section Presentation and sorting
8265 @cindex presentation, of agenda items
8267 @vindex org-agenda-prefix-format
8268 @vindex org-agenda-tags-column
8269 Before displaying items in an agenda view, Org mode visually prepares the
8270 items and sorts them.  Each item occupies a single line.  The line starts
8271 with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
8272 of the item and other important information.  You can customize in which
8273 column tags will be displayed through @code{org-agenda-tags-column}.  You can
8274 also customize the prefix using the option @code{org-agenda-prefix-format}.
8275 This prefix is followed by a cleaned-up version of the outline headline
8276 associated with the item.
8278 @menu
8279 * Categories::                  Not all tasks are equal
8280 * Time-of-day specifications::  How the agenda knows the time
8281 * Sorting agenda items::        The order of things
8282 * Filtering/limiting agenda items::  Dynamically narrow the agenda
8283 @end menu
8285 @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
8286 @subsection Categories
8288 @cindex category
8289 @cindex #+CATEGORY
8290 The category is a broad label assigned to each agenda item.  By default,
8291 the category is simply derived from the file name, but you can also
8292 specify it with a special line in the buffer, like this@footnote{For
8293 backward compatibility, the following also works: if there are several
8294 such lines in a file, each specifies the category for the text below it.
8295 The first category also applies to any text before the first CATEGORY
8296 line.  However, using this method is @emph{strongly} deprecated as it is
8297 incompatible with the outline structure of the document.  The correct
8298 method for setting multiple categories in a buffer is using a
8299 property.}:
8301 @example
8302 #+CATEGORY: Thesis
8303 @end example
8305 @noindent
8306 @cindex property, CATEGORY
8307 If you would like to have a special CATEGORY for a single entry or a
8308 (sub)tree, give the entry a @code{:CATEGORY:} property with the
8309 special category you want to apply as the value.
8311 @noindent
8312 The display in the agenda buffer looks best if the category is not
8313 longer than 10 characters.
8315 @noindent
8316 You can set up icons for category by customizing the
8317 @code{org-agenda-category-icon-alist} variable.
8319 @node Time-of-day specifications, Sorting agenda items, Categories, Presentation and sorting
8320 @subsection Time-of-day specifications
8321 @cindex time-of-day specification
8323 Org mode checks each agenda item for a time-of-day specification.  The
8324 time can be part of the timestamp that triggered inclusion into the
8325 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}.  Time
8326 ranges can be specified with two timestamps, like
8328 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
8330 In the headline of the entry itself, a time(range) may also appear as
8331 plain text (like @samp{12:45} or a @samp{8:30-1pm}).  If the agenda
8332 integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
8333 specifications in diary entries are recognized as well.
8335 For agenda display, Org mode extracts the time and displays it in a
8336 standard 24 hour format as part of the prefix.  The example times in
8337 the previous paragraphs would end up in the agenda like this:
8339 @example
8340     8:30-13:00 Arthur Dent lies in front of the bulldozer
8341    12:45...... Ford Prefect arrives and takes Arthur to the pub
8342    19:00...... The Vogon reads his poem
8343    20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8344 @end example
8346 @cindex time grid
8347 If the agenda is in single-day mode, or for the display of today, the
8348 timed entries are embedded in a time grid, like
8350 @example
8351     8:00...... ------------------
8352     8:30-13:00 Arthur Dent lies in front of the bulldozer
8353    10:00...... ------------------
8354    12:00...... ------------------
8355    12:45...... Ford Prefect arrives and takes Arthur to the pub
8356    14:00...... ------------------
8357    16:00...... ------------------
8358    18:00...... ------------------
8359    19:00...... The Vogon reads his poem
8360    20:00...... ------------------
8361    20:30-22:15 Marvin escorts the Hitchhikers to the bridge
8362 @end example
8364 @vindex org-agenda-use-time-grid
8365 @vindex org-agenda-time-grid
8366 The time grid can be turned on and off with the variable
8367 @code{org-agenda-use-time-grid}, and can be configured with
8368 @code{org-agenda-time-grid}.
8370 @node Sorting agenda items, Filtering/limiting agenda items, Time-of-day specifications, Presentation and sorting
8371 @subsection Sorting agenda items
8372 @cindex sorting, of agenda items
8373 @cindex priorities, of agenda items
8374 Before being inserted into a view, the items are sorted.  How this is
8375 done depends on the type of view.
8376 @itemize @bullet
8377 @item
8378 @vindex org-agenda-files
8379 For the daily/weekly agenda, the items for each day are sorted.  The
8380 default order is to first collect all items containing an explicit
8381 time-of-day specification.  These entries will be shown at the beginning
8382 of the list, as a @emph{schedule} for the day.  After that, items remain
8383 grouped in categories, in the sequence given by @code{org-agenda-files}.
8384 Within each category, items are sorted by priority (@pxref{Priorities}),
8385 which is composed of the base priority (2000 for priority @samp{A}, 1000
8386 for @samp{B}, and 0 for @samp{C}), plus additional increments for
8387 overdue scheduled or deadline items.
8388 @item
8389 For the TODO list, items remain in the order of categories, but within
8390 each category, sorting takes place according to priority
8391 (@pxref{Priorities}).  The priority used for sorting derives from the
8392 priority cookie, with additions depending on how close an item is to its due
8393 or scheduled date.
8394 @item
8395 For tags matches, items are not sorted at all, but just appear in the
8396 sequence in which they are found in the agenda files.
8397 @end itemize
8399 @vindex org-agenda-sorting-strategy
8400 Sorting can be customized using the variable
8401 @code{org-agenda-sorting-strategy}, and may also include criteria based on
8402 the estimated effort of an entry (@pxref{Effort estimates}).
8404 @node Filtering/limiting agenda items,  , Sorting agenda items, Presentation and sorting
8405 @subsection Filtering/limiting agenda items
8407 Agenda built-in or customized commands are statically defined.  Agenda
8408 filters and limits provide two ways of dynamically narrowing down the list of
8409 agenda entries: @emph{fitlers} and @emph{limits}.  Filters only act on the
8410 display of the items, while limits take effect before the list of agenda
8411 entries is built.  Filter are more often used interactively, while limits are
8412 mostly useful when defined as local variables within custom agenda commands.
8414 @subsubheading Filtering in the agenda
8415 @cindex filtering, by tag, category, top headline and effort, in agenda
8416 @cindex tag filtering, in agenda
8417 @cindex category filtering, in agenda
8418 @cindex top headline filtering, in agenda
8419 @cindex effort filtering, in agenda
8420 @cindex query editing, in agenda
8422 @table @kbd
8423 @orgcmd{/,org-agenda-filter-by-tag}
8424 @vindex org-agenda-tag-filter-preset
8425 Filter the agenda view with respect to a tag and/or effort estimates.  The
8426 difference between this and a custom agenda command is that filtering is very
8427 fast, so that you can switch quickly between different filters without having
8428 to recreate the agenda.@footnote{Custom commands can preset a filter by
8429 binding the variable @code{org-agenda-tag-filter-preset} as an option.  This
8430 filter will then be applied to the view and persist as a basic filter through
8431 refreshes and more secondary filtering.  The filter is a global property of
8432 the entire agenda view---in a block agenda, you should only set this in the
8433 global options section, not in the section of an individual block.}
8435 You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
8436 all.  Pressing @key{TAB} at that prompt will offer use completion to select a
8437 tag (including any tags that do not have a selection character).  The command
8438 then hides all entries that do not contain or inherit this tag.  When called
8439 with prefix arg, remove the entries that @emph{do} have the tag.  A second
8440 @kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
8441 If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
8442 will be narrowed by requiring or forbidding the selected additional tag.
8443 Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
8444 immediately use the @kbd{\} command.
8446 @vindex org-sort-agenda-noeffort-is-high
8447 In order to filter for effort estimates, you should set up allowed
8448 efforts globally, for example
8449 @lisp
8450 (setq org-global-properties
8451     '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
8452 @end lisp
8453 You can then filter for an effort by first typing an operator, one of
8454 @kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
8455 estimate in your array of allowed values, where @kbd{0} means the 10th value.
8456 The filter will then restrict to entries with effort smaller-or-equal, equal,
8457 or larger-or-equal than the selected value.  If the digits 0--9 are not used
8458 as fast access keys to tags, you can also simply press the index digit
8459 directly without an operator.  In this case, @kbd{<} will be assumed.  For
8460 application of the operator, entries without a defined effort will be treated
8461 according to the value of @code{org-sort-agenda-noeffort-is-high}.  To filter
8462 for tasks without effort definition, press @kbd{?} as the operator.
8464 Org also supports automatic, context-aware tag filtering.  If the variable
8465 @code{org-agenda-auto-exclude-function} is set to a user-defined function,
8466 that function can decide which tags should be excluded from the agenda
8467 automatically.  Once this is set, the @kbd{/} command then accepts @kbd{RET}
8468 as a sub-option key and runs the auto exclusion logic.  For example, let's
8469 say you use a @code{Net} tag to identify tasks which need network access, an
8470 @code{Errand} tag for errands in town, and a @code{Call} tag for making phone
8471 calls.  You could auto-exclude these tags based on the availability of the
8472 Internet, and outside of business hours, with something like this:
8474 @smalllisp
8475 @group
8476 (defun org-my-auto-exclude-function (tag)
8477   (and (cond
8478         ((string= tag "Net")
8479          (/= 0 (call-process "/sbin/ping" nil nil nil
8480                              "-c1" "-q" "-t1" "mail.gnu.org")))
8481         ((or (string= tag "Errand") (string= tag "Call"))
8482          (let ((hour (nth 2 (decode-time))))
8483            (or (< hour 8) (> hour 21)))))
8484        (concat "-" tag)))
8486 (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
8487 @end group
8488 @end smalllisp
8490 @orgcmd{\\,org-agenda-filter-by-tag-refine}
8491 Narrow the current agenda filter by an additional condition.  When called with
8492 prefix arg, remove the entries that @emph{do} have the tag, or that do match
8493 the effort criterion.  You can achieve the same effect by pressing @kbd{+} or
8494 @kbd{-} as the first key after the @kbd{/} command.
8497 @kindex [
8498 @kindex ]
8499 @kindex @{
8500 @kindex @}
8501 @item [ ] @{ @}
8502 @table @i
8503 @item @r{in} search view
8504 add new search words (@kbd{[} and @kbd{]}) or new regular expressions
8505 (@kbd{@{} and @kbd{@}}) to the query string.  The opening bracket/brace will
8506 add a positive search term prefixed by @samp{+}, indicating that this search
8507 term @i{must} occur/match in the entry.  The closing bracket/brace will add a
8508 negative search term which @i{must not} occur/match in the entry for it to be
8509 selected.
8510 @end table
8512 @orgcmd{<,org-agenda-filter-by-category}
8513 @vindex org-agenda-category-filter-preset
8515 Filter the current agenda view with respect to the category of the item at
8516 point.  Pressing @code{<} another time will remove this filter.  You can add
8517 a filter preset through the option @code{org-agenda-category-filter-preset}
8518 (see below.)
8520 @orgcmd{^,org-agenda-filter-by-top-headline}
8521 Filter the current agenda view and only display the siblings and the parent
8522 headline of the one at point.
8524 @orgcmd{=,org-agenda-filter-by-regexp}
8525 @vindex org-agenda-regexp-filter-preset
8527 Filter the agenda view by a regular expression: only show agenda entries
8528 matching the regular expression the user entered.  When called with a prefix
8529 argument, it will filter @emph{out} entries matching the regexp.  With two
8530 universal prefix arguments, it will remove all the regexp filters, which can
8531 be accumulated.  You can add a filter preset through the option
8532 @code{org-agenda-category-filter-preset} (see below.)
8534 @orgcmd{|,org-agenda-filter-remove-all}
8535 Remove all filters in the current agenda view.
8536 @end table
8538 @subsubheading Setting limits for the agenda
8539 @cindex limits, in agenda
8540 @vindex org-agenda-max-entries
8541 @vindex org-agenda-max-effort
8542 @vindex org-agenda-max-todos
8543 @vindex org-agenda-max-tags
8545 Here is a list of options that you can set, either globally, or locally in
8546 your custom agenda views@pxref{Custom agenda views}.
8548 @table @var
8549 @item org-agenda-max-entries
8550 Limit the number of entries.
8551 @item org-agenda-max-effort
8552 Limit the duration of accumulated efforts (as minutes).
8553 @item org-agenda-max-todos
8554 Limit the number of entries with TODO keywords.
8555 @item org-agenda-max-tags
8556 Limit the number of tagged entries.
8557 @end table
8559 When set to a positive integer, each option will exclude entries from other
8560 categories: for example, @code{(setq org-agenda-max-effort 100)} will limit
8561 the agenda to 100 minutes of effort and exclude any entry that as no effort
8562 property.  If you want to include entries with no effort property, use a
8563 negative value for @code{org-agenda-max-effort}.
8565 One useful setup is to use @code{org-agenda-max-entries} locally in a custom
8566 command.  For example, this custom command will display the next five entries
8567 with a @code{NEXT} TODO keyword.
8569 @smalllisp
8570 (setq org-agenda-custom-commands
8571       '(("n" todo "NEXT"
8572          ((org-agenda-max-entries 5)))))
8573 @end smalllisp
8575 Once you mark one of these five entry as @code{DONE}, rebuilding the agenda
8576 will again the next five entries again, including the first entry that was
8577 excluded so far.
8579 You can also dynamically set temporary limits@footnote{Those temporary limits
8580 are lost when rebuilding the agenda.}:
8582 @table @kbd
8583 @orgcmd{~,org-agenda-limit-interactively}
8584 This prompts for the type of limit to apply and its value.
8585 @end table
8587 @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views
8588 @section Commands in the agenda buffer
8589 @cindex commands, in agenda buffer
8591 Entries in the agenda buffer are linked back to the Org file or diary
8592 file where they originate.  You are not allowed to edit the agenda
8593 buffer itself, but commands are provided to show and jump to the
8594 original entry location, and to edit the Org files ``remotely'' from
8595 the agenda buffer.  In this way, all information is stored only once,
8596 removing the risk that your agenda and note files may diverge.
8598 Some commands can be executed with mouse clicks on agenda lines.  For
8599 the other commands, the cursor needs to be in the desired line.
8601 @table @kbd
8602 @tsubheading{Motion}
8603 @cindex motion commands in agenda
8604 @orgcmd{n,org-agenda-next-line}
8605 Next line (same as @key{down} and @kbd{C-n}).
8606 @orgcmd{p,org-agenda-previous-line}
8607 Previous line (same as @key{up} and @kbd{C-p}).
8608 @tsubheading{View/Go to Org file}
8609 @orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
8610 Display the original location of the item in another window.
8611 With prefix arg, make sure that the entire entry is made visible in the
8612 outline, not only the heading.
8614 @orgcmd{L,org-agenda-recenter}
8615 Display original location and recenter that window.
8617 @orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
8618 Go to the original location of the item in another window.
8620 @orgcmd{@key{RET},org-agenda-switch-to}
8621 Go to the original location of the item and delete other windows.
8623 @orgcmd{F,org-agenda-follow-mode}
8624 @vindex org-agenda-start-with-follow-mode
8625 Toggle Follow mode.  In Follow mode, as you move the cursor through
8626 the agenda buffer, the other window always shows the corresponding
8627 location in the Org file.  The initial setting for this mode in new
8628 agenda buffers can be set with the variable
8629 @code{org-agenda-start-with-follow-mode}.
8631 @orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
8632 Display the entire subtree of the current item in an indirect buffer.  With a
8633 numeric prefix argument N, go up to level N and then take that tree.  If N is
8634 negative, go up that many levels.  With a @kbd{C-u} prefix, do not remove the
8635 previously used indirect buffer.
8637 @orgcmd{C-c C-o,org-agenda-open-link}
8638 Follow a link in the entry.  This will offer a selection of any links in the
8639 text belonging to the referenced Org node.  If there is only one link, it
8640 will be followed without a selection prompt.
8642 @tsubheading{Change display}
8643 @cindex display changing, in agenda
8644 @kindex A
8645 @item A
8646 Interactively select another agenda view and append it to the current view.
8648 @kindex o
8649 @item o
8650 Delete other windows.
8652 @orgcmdkskc{v d,d,org-agenda-day-view}
8653 @xorgcmdkskc{v w,w,org-agenda-week-view}
8654 @xorgcmd{v t,org-agenda-fortnight-view}
8655 @xorgcmd{v m,org-agenda-month-view}
8656 @xorgcmd{v y,org-agenda-year-view}
8657 @xorgcmd{v SPC,org-agenda-reset-view}
8658 @vindex org-agenda-span
8659 Switch to day/week/month/year view.  When switching to day or week view, this
8660 setting becomes the default for subsequent agenda refreshes.  Since month and
8661 year views are slow to create, they do not become the default.  A numeric
8662 prefix argument may be used to jump directly to a specific day of the year,
8663 ISO week, month, or year, respectively.  For example, @kbd{32 d} jumps to
8664 February 1st, @kbd{9 w} to ISO week number 9.  When setting day, week, or
8665 month view, a year may be encoded in the prefix argument as well.  For
8666 example, @kbd{200712 w} will jump to week 12 in 2007.  If such a year
8667 specification has only one or two digits, it will be mapped to the interval
8668 1938--2037.  @kbd{v @key{SPC}} will reset to what is set in
8669 @code{org-agenda-span}.
8671 @orgcmd{f,org-agenda-later}
8672 Go forward in time to display the following @code{org-agenda-current-span} days.
8673 For example, if the display covers a week, switch to the following week.
8674 With prefix arg, go forward that many times @code{org-agenda-current-span} days.
8676 @orgcmd{b,org-agenda-earlier}
8677 Go backward in time to display earlier dates.
8679 @orgcmd{.,org-agenda-goto-today}
8680 Go to today.
8682 @orgcmd{j,org-agenda-goto-date}
8683 Prompt for a date and go there.
8685 @orgcmd{J,org-agenda-clock-goto}
8686 Go to the currently clocked-in task @i{in the agenda buffer}.
8688 @orgcmd{D,org-agenda-toggle-diary}
8689 Toggle the inclusion of diary entries.  See @ref{Weekly/daily agenda}.
8691 @orgcmdkskc{v l,l,org-agenda-log-mode}
8692 @kindex v L
8693 @vindex org-log-done
8694 @vindex org-agenda-log-mode-items
8695 Toggle Logbook mode.  In Logbook mode, entries that were marked DONE while
8696 logging was on (variable @code{org-log-done}) are shown in the agenda, as are
8697 entries that have been clocked on that day.  You can configure the entry
8698 types that should be included in log mode using the variable
8699 @code{org-agenda-log-mode-items}.  When called with a @kbd{C-u} prefix, show
8700 all possible logbook entries, including state changes.  When called with two
8701 prefix arguments @kbd{C-u C-u}, show only logging information, nothing else.
8702 @kbd{v L} is equivalent to @kbd{C-u v l}.
8704 @orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
8705 Include inactive timestamps into the current view.  Only for weekly/daily
8706 agenda and timeline views.
8708 @orgcmd{v a,org-agenda-archives-mode}
8709 @xorgcmd{v A,org-agenda-archives-mode 'files}
8710 Toggle Archives mode.  In Archives mode, trees that are marked
8711 @code{ARCHIVED} are also scanned when producing the agenda.  When you use the
8712 capital @kbd{A}, even all archive files are included.  To exit archives mode,
8713 press @kbd{v a} again.
8715 @orgcmdkskc{v R,R,org-agenda-clockreport-mode}
8716 @vindex org-agenda-start-with-clockreport-mode
8717 @vindex org-clock-report-include-clocking-task
8718 Toggle Clockreport mode.  In Clockreport mode, the daily/weekly agenda will
8719 always show a table with the clocked times for the time span and file scope
8720 covered by the current agenda view.  The initial setting for this mode in new
8721 agenda buffers can be set with the variable
8722 @code{org-agenda-start-with-clockreport-mode}.  By using a prefix argument
8723 when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
8724 contributions from entries that are hidden by agenda filtering@footnote{Only
8725 tags filtering will be respected here, effort filtering is ignored.}.  See
8726 also the variable @code{org-clock-report-include-clocking-task}.
8728 @orgkey{v c}
8729 @vindex org-agenda-clock-consistency-checks
8730 Show overlapping clock entries, clocking gaps, and other clocking problems in
8731 the current agenda range.  You can then visit clocking lines and fix them
8732 manually.  See the variable @code{org-agenda-clock-consistency-checks} for
8733 information on how to customize the definition of what constituted a clocking
8734 problem.  To return to normal agenda display, press @kbd{l} to exit Logbook
8735 mode.
8737 @orgcmdkskc{v E,E,org-agenda-entry-text-mode}
8738 @vindex org-agenda-start-with-entry-text-mode
8739 @vindex org-agenda-entry-text-maxlines
8740 Toggle entry text mode.  In entry text mode, a number of lines from the Org
8741 outline node referenced by an agenda line will be displayed below the line.
8742 The maximum number of lines is given by the variable
8743 @code{org-agenda-entry-text-maxlines}.  Calling this command with a numeric
8744 prefix argument will temporarily modify that number to the prefix value.
8746 @orgcmd{G,org-agenda-toggle-time-grid}
8747 @vindex org-agenda-use-time-grid
8748 @vindex org-agenda-time-grid
8749 Toggle the time grid on and off.  See also the variables
8750 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
8752 @orgcmd{r,org-agenda-redo}
8753 Recreate the agenda buffer, for example to reflect the changes after
8754 modification of the timestamps of items with @kbd{S-@key{left}} and
8755 @kbd{S-@key{right}}.  When the buffer is the global TODO list, a prefix
8756 argument is interpreted to create a selective list for a specific TODO
8757 keyword.
8758 @orgcmd{g,org-agenda-redo}
8759 Same as @kbd{r}.
8761 @orgcmdkskc{C-x C-s,s,org-save-all-org-buffers}
8762 Save all Org buffers in the current Emacs session, and also the locations of
8763 IDs.
8765 @orgcmd{C-c C-x C-c,org-agenda-columns}
8766 @vindex org-columns-default-format
8767 Invoke column view (@pxref{Column view}) in the agenda buffer.  The column
8768 view format is taken from the entry at point, or (if there is no entry at
8769 point), from the first entry in the agenda view.  So whatever the format for
8770 that entry would be in the original buffer (taken from a property, from a
8771 @code{#+COLUMNS} line, or from the default variable
8772 @code{org-columns-default-format}), will be used in the agenda.
8774 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
8775 Remove the restriction lock on the agenda, if it is currently restricted to a
8776 file or subtree (@pxref{Agenda files}).
8778 @tsubheading{Secondary filtering and query editing}
8780 For a detailed description of these commands, see @pxref{Filtering/limiting
8781 agenda items}.
8783 @orgcmd{/,org-agenda-filter-by-tag}
8784 @vindex org-agenda-tag-filter-preset
8785 Filter the agenda view with respect to a tag and/or effort estimates.
8787 @orgcmd{\\,org-agenda-filter-by-tag-refine}
8788 Narrow the current agenda filter by an additional condition.
8790 @orgcmd{<,org-agenda-filter-by-category}
8791 @vindex org-agenda-category-filter-preset
8793 Filter the current agenda view with respect to the category of the item at
8794 point.  Pressing @code{<} another time will remove this filter.
8796 @orgcmd{^,org-agenda-filter-by-top-headline}
8797 Filter the current agenda view and only display the siblings and the parent
8798 headline of the one at point.
8800 @orgcmd{=,org-agenda-filter-by-regexp}
8801 @vindex org-agenda-regexp-filter-preset
8803 Filter the agenda view by a regular expression: only show agenda entries
8804 matching the regular expression the user entered.  When called with a prefix
8805 argument, it will filter @emph{out} entries matching the regexp.  With two
8806 universal prefix arguments, it will remove all the regexp filters, which can
8807 be accumulated.  You can add a filter preset through the option
8808 @code{org-agenda-category-filter-preset} (see below.)
8810 @orgcmd{|,org-agenda-filter-remove-all}
8811 Remove all filters in the current agenda view.
8813 @tsubheading{Remote editing}
8814 @cindex remote editing, from agenda
8816 @item 0--9
8817 Digit argument.
8819 @cindex undoing remote-editing events
8820 @cindex remote editing, undo
8821 @orgcmd{C-_,org-agenda-undo}
8822 Undo a change due to a remote editing command.  The change is undone
8823 both in the agenda buffer and in the remote buffer.
8825 @orgcmd{t,org-agenda-todo}
8826 Change the TODO state of the item, both in the agenda and in the
8827 original org file.
8829 @orgcmd{C-S-@key{right},org-agenda-todo-nextset}
8830 @orgcmd{C-S-@key{left},org-agenda-todo-previousset}
8831 Switch to the next/previous set of TODO keywords.
8833 @orgcmd{C-k,org-agenda-kill}
8834 @vindex org-agenda-confirm-kill
8835 Delete the current agenda item along with the entire subtree belonging
8836 to it in the original Org file.  If the text to be deleted remotely
8837 is longer than one line, the kill needs to be confirmed by the user.  See
8838 variable @code{org-agenda-confirm-kill}.
8840 @orgcmd{C-c C-w,org-agenda-refile}
8841 Refile the entry at point.
8843 @orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation}
8844 @vindex org-archive-default-command
8845 Archive the subtree corresponding to the entry at point using the default
8846 archiving command set in @code{org-archive-default-command}.  When using the
8847 @code{a} key, confirmation will be required.
8849 @orgcmd{C-c C-x a,org-agenda-toggle-archive-tag}
8850 Toggle the ARCHIVE tag for the current headline.
8852 @orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling}
8853 Move the subtree corresponding to the current entry to its @emph{archive
8854 sibling}.
8856 @orgcmdkskc{C-c C-x C-s,$,org-agenda-archive}
8857 Archive the subtree corresponding to the current headline.  This means the
8858 entry will be moved to the configured archive location, most likely a
8859 different file.
8861 @orgcmd{T,org-agenda-show-tags}
8862 @vindex org-agenda-show-inherited-tags
8863 Show all tags associated with the current item.  This is useful if you have
8864 turned off @code{org-agenda-show-inherited-tags}, but still want to see all
8865 tags of a headline occasionally.
8867 @orgcmd{:,org-agenda-set-tags}
8868 Set tags for the current headline.  If there is an active region in the
8869 agenda, change a tag for all headings in the region.
8871 @kindex ,
8872 @item ,
8873 Set the priority for the current item (@command{org-agenda-priority}).
8874 Org mode prompts for the priority character.  If you reply with @key{SPC},
8875 the priority cookie is removed from the entry.
8877 @orgcmd{P,org-agenda-show-priority}
8878 Display weighted priority of current item.
8880 @orgcmdkkc{+,S-@key{up},org-agenda-priority-up}
8881 Increase the priority of the current item.  The priority is changed in
8882 the original buffer, but the agenda is not resorted.  Use the @kbd{r}
8883 key for this.
8885 @orgcmdkkc{-,S-@key{down},org-agenda-priority-down}
8886 Decrease the priority of the current item.
8888 @orgcmdkkc{z,C-c C-z,org-agenda-add-note}
8889 @vindex org-log-into-drawer
8890 Add a note to the entry.  This note will be recorded, and then filed to the
8891 same location where state change notes are put.  Depending on
8892 @code{org-log-into-drawer}, this may be inside a drawer.
8894 @orgcmd{C-c C-a,org-attach}
8895 Dispatcher for all command related to attachments.
8897 @orgcmd{C-c C-s,org-agenda-schedule}
8898 Schedule this item.  With prefix arg remove the scheduling timestamp
8900 @orgcmd{C-c C-d,org-agenda-deadline}
8901 Set a deadline for this item.  With prefix arg remove the deadline.
8903 @orgcmd{S-@key{right},org-agenda-do-date-later}
8904 Change the timestamp associated with the current line by one day into the
8905 future.  If the date is in the past, the first call to this command will move
8906 it to today.@*
8907 With a numeric prefix argument, change it by that many days.  For example,
8908 @kbd{3 6 5 S-@key{right}} will change it by a year.  With a @kbd{C-u} prefix,
8909 change the time by one hour.  If you immediately repeat the command, it will
8910 continue to change hours even without the prefix arg.  With a double @kbd{C-u
8911 C-u} prefix, do the same for changing minutes.@*
8912 The stamp is changed in the original Org file, but the change is not directly
8913 reflected in the agenda buffer.  Use @kbd{r} or @kbd{g} to update the buffer.
8915 @orgcmd{S-@key{left},org-agenda-do-date-earlier}
8916 Change the timestamp associated with the current line by one day
8917 into the past.
8919 @orgcmd{>,org-agenda-date-prompt}
8920 Change the timestamp associated with the current line.  The key @kbd{>} has
8921 been chosen, because it is the same as @kbd{S-.}  on my keyboard.
8923 @orgcmd{I,org-agenda-clock-in}
8924 Start the clock on the current item.  If a clock is running already, it
8925 is stopped first.
8927 @orgcmd{O,org-agenda-clock-out}
8928 Stop the previously started clock.
8930 @orgcmd{X,org-agenda-clock-cancel}
8931 Cancel the currently running clock.
8933 @orgcmd{J,org-agenda-clock-goto}
8934 Jump to the running clock in another window.
8936 @orgcmd{k,org-agenda-capture}
8937 Like @code{org-capture}, but use the date at point as the default date for
8938 the capture template.  See @code{org-capture-use-agenda-date} to make this
8939 the default behavior of @code{org-capture}.
8940 @cindex capturing, from agenda
8941 @vindex org-capture-use-agenda-date
8943 @tsubheading{Dragging agenda lines forward/backward}
8944 @cindex dragging, agenda lines
8946 @orgcmd{M-<up>,org-agenda-drag-line-backward}
8947 Drag the line at point backward one line@footnote{Moving agenda lines does
8948 not persist after an agenda refresh and does not modify the contributing
8949 @file{.org} files}.  With a numeric prefix argument, drag backward by that
8950 many lines.
8952 @orgcmd{M-<down>,org-agenda-drag-line-forward}
8953 Drag the line at point forward one line.  With a numeric prefix argument,
8954 drag forward by that many lines.
8956 @tsubheading{Bulk remote editing selected entries}
8957 @cindex remote editing, bulk, from agenda
8958 @vindex org-agenda-bulk-custom-functions
8960 @orgcmd{m,org-agenda-bulk-mark}
8961 Mark the entry at point for bulk action.  With numeric prefix argument, mark
8962 that many successive entries.
8964 @orgcmd{*,org-agenda-bulk-mark-all}
8965 Mark all visible agenda entries for bulk action.
8967 @orgcmd{u,org-agenda-bulk-unmark}
8968 Unmark entry at point for bulk action.
8970 @orgcmd{U,org-agenda-bulk-remove-all-marks}
8971 Unmark all marked entries for bulk action.
8973 @orgcmd{M-m,org-agenda-bulk-toggle}
8974 Toggle mark of the entry at point for bulk action.
8976 @orgcmd{M-*,org-agenda-bulk-toggle-all}
8977 Toggle marks of all visible entries for bulk action.
8979 @orgcmd{%,org-agenda-bulk-mark-regexp}
8980 Mark entries matching a regular expression for bulk action.
8982 @orgcmd{B,org-agenda-bulk-action}
8983 Bulk action: act on all marked entries in the agenda.  This will prompt for
8984 another key to select the action to be applied.  The prefix arg to @kbd{B}
8985 will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove
8986 these special timestamps.  By default, marks are removed after the bulk.  If
8987 you want them to persist, set @code{org-agenda-bulk-persistent-marks} to
8988 @code{t} or hit @kbd{p} at the prompt.
8990 @table @kbd
8991 @item *
8992 Toggle persistent marks.
8993 @item $
8994 Archive all selected entries.
8995 @item A
8996 Archive entries by moving them to their respective archive siblings.
8997 @item t
8998 Change TODO state.  This prompts for a single TODO keyword and changes the
8999 state of all selected entries, bypassing blocking and suppressing logging
9000 notes (but not timestamps).
9001 @item +
9002 Add a tag to all selected entries.
9003 @item -
9004 Remove a tag from all selected entries.
9005 @item s
9006 Schedule all items to a new date.  To shift existing schedule dates by a
9007 fixed number of days, use something starting with double plus at the prompt,
9008 for example @samp{++8d} or @samp{++2w}.
9009 @item d
9010 Set deadline to a specific date.
9011 @item r
9012 Prompt for a single refile target and move all entries.  The entries will no
9013 longer be in the agenda; refresh (@kbd{g}) to bring them back.
9014 @item S
9015 Reschedule randomly into the coming N days.  N will be prompted for.  With
9016 prefix arg (@kbd{C-u B S}), scatter only across weekdays.
9017 @item f
9018 Apply a function@footnote{You can also create persistent custom functions
9019 through @code{org-agenda-bulk-custom-functions}.} to marked entries.  For
9020 example, the function below sets the CATEGORY property of the entries to web.
9022 @lisp
9023 @group
9024 (defun set-category ()
9025   (interactive "P")
9026   (let* ((marker (or (org-get-at-bol 'org-hd-marker)
9027                      (org-agenda-error)))
9028          (buffer (marker-buffer marker)))
9029     (with-current-buffer buffer
9030       (save-excursion
9031         (save-restriction
9032           (widen)
9033           (goto-char marker)
9034           (org-back-to-heading t)
9035           (org-set-property "CATEGORY" "web"))))))
9036 @end group
9037 @end lisp
9038 @end table
9040 @tsubheading{Calendar commands}
9041 @cindex calendar commands, from agenda
9043 @orgcmd{c,org-agenda-goto-calendar}
9044 Open the Emacs calendar and move to the date at the agenda cursor.
9046 @orgcmd{c,org-calendar-goto-agenda}
9047 When in the calendar, compute and show the Org mode agenda for the
9048 date at the cursor.
9050 @cindex diary entries, creating from agenda
9051 @orgcmd{i,org-agenda-diary-entry}
9052 @vindex org-agenda-diary-file
9053 Insert a new entry into the diary, using the date at the cursor and (for
9054 block entries) the date at the mark.  This will add to the Emacs diary
9055 file@footnote{This file is parsed for the agenda when
9056 @code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
9057 command in the calendar.  The diary file will pop up in another window, where
9058 you can add the entry.
9060 If you configure @code{org-agenda-diary-file} to point to an Org mode file,
9061 Org will create entries (in Org mode syntax) in that file instead.  Most
9062 entries will be stored in a date-based outline tree that will later make it
9063 easy to archive appointments from previous months/years.  The tree will be
9064 built under an entry with a @code{DATE_TREE} property, or else with years as
9065 top-level entries.  Emacs will prompt you for the entry text---if you specify
9066 it, the entry will be created in @code{org-agenda-diary-file} without further
9067 interaction.  If you directly press @key{RET} at the prompt without typing
9068 text, the target file will be shown in another window for you to finish the
9069 entry there.  See also the @kbd{k r} command.
9071 @orgcmd{M,org-agenda-phases-of-moon}
9072 Show the phases of the moon for the three months around current date.
9074 @orgcmd{S,org-agenda-sunrise-sunset}
9075 Show sunrise and sunset times.  The geographical location must be set
9076 with calendar variables, see the documentation for the Emacs calendar.
9078 @orgcmd{C,org-agenda-convert-date}
9079 Convert the date at cursor into many other cultural and historic
9080 calendars.
9082 @orgcmd{H,org-agenda-holidays}
9083 Show holidays for three months around the cursor date.
9085 @item M-x org-icalendar-combine-agenda-files RET
9086 Export a single iCalendar file containing entries from all agenda files.
9087 This is a globally available command, and also available in the agenda menu.
9089 @tsubheading{Exporting to a file}
9090 @orgcmd{C-x C-w,org-agenda-write}
9091 @cindex exporting agenda views
9092 @cindex agenda views, exporting
9093 @vindex org-agenda-exporter-settings
9094 Write the agenda view to a file.  Depending on the extension of the selected
9095 file name, the view will be exported as HTML (@file{.html} or @file{.htm}),
9096 Postscript (@file{.ps}), PDF (@file{.pdf}), Org (@file{.org}) and plain text
9097 (any other extension).  When exporting to Org, only the body of original
9098 headlines are exported, not subtrees or inherited tags.  When called with a
9099 @kbd{C-u} prefix argument, immediately open the newly created file.  Use the
9100 variable @code{org-agenda-exporter-settings} to set options for
9101 @file{ps-print} and for @file{htmlize} to be used during export.
9103 @tsubheading{Quit and Exit}
9104 @orgcmd{q,org-agenda-quit}
9105 Quit agenda, remove the agenda buffer.
9107 @cindex agenda files, removing buffers
9108 @orgcmd{x,org-agenda-exit}
9109 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
9110 for the compilation of the agenda.  Buffers created by the user to
9111 visit Org files will not be removed.
9112 @end table
9115 @node Custom agenda views, Exporting Agenda Views, Agenda commands, Agenda Views
9116 @section Custom agenda views
9117 @cindex custom agenda views
9118 @cindex agenda views, custom
9120 Custom agenda commands serve two purposes: to store and quickly access
9121 frequently used TODO and tags searches, and to create special composite
9122 agenda buffers.  Custom agenda commands will be accessible through the
9123 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
9125 @menu
9126 * Storing searches::            Type once, use often
9127 * Block agenda::                All the stuff you need in a single buffer
9128 * Setting Options::             Changing the rules
9129 @end menu
9131 @node Storing searches, Block agenda, Custom agenda views, Custom agenda views
9132 @subsection Storing searches
9134 The first application of custom searches is the definition of keyboard
9135 shortcuts for frequently used searches, either creating an agenda
9136 buffer, or a sparse tree (the latter covering of course only the current
9137 buffer).
9138 @kindex C-c a C
9139 @vindex org-agenda-custom-commands
9140 @cindex agenda views, main example
9141 @cindex agenda, as an agenda views
9142 @cindex agenda*, as an agenda views
9143 @cindex tags, as an agenda view
9144 @cindex todo, as an agenda view
9145 @cindex tags-todo
9146 @cindex todo-tree
9147 @cindex occur-tree
9148 @cindex tags-tree
9150 Custom commands are configured in the variable
9151 @code{org-agenda-custom-commands}.  You can customize this variable, for
9152 example by pressing @kbd{C-c a C}.  You can also directly set it with Emacs
9153 Lisp in @file{.emacs}.  The following example contains all valid agenda
9154 views:
9156 @lisp
9157 @group
9158 (setq org-agenda-custom-commands
9159       '(("x" agenda)
9160         ("y" agenda*)
9161         ("w" todo "WAITING")
9162         ("W" todo-tree "WAITING")
9163         ("u" tags "+boss-urgent")
9164         ("v" tags-todo "+boss-urgent")
9165         ("U" tags-tree "+boss-urgent")
9166         ("f" occur-tree "\\<FIXME\\>")
9167         ("h" . "HOME+Name tags searches") ; description for "h" prefix
9168         ("hl" tags "+home+Lisa")
9169         ("hp" tags "+home+Peter")
9170         ("hk" tags "+home+Kim")))
9171 @end group
9172 @end lisp
9174 @noindent
9175 The initial string in each entry defines the keys you have to press
9176 after the dispatcher command @kbd{C-c a} in order to access the command.
9177 Usually this will be just a single character, but if you have many
9178 similar commands, you can also define two-letter combinations where the
9179 first character is the same in several combinations and serves as a
9180 prefix key@footnote{You can provide a description for a prefix key by
9181 inserting a cons cell with the prefix and the description.}.  The second
9182 parameter is the search type, followed by the string or regular
9183 expression to be used for the matching.  The example above will
9184 therefore define:
9186 @table @kbd
9187 @item C-c a x
9188 as a global search for agenda entries planned@footnote{@emph{Planned} means
9189 here that these entries have some planning information attached to them, like
9190 a time-stamp, a scheduled or a deadline string.  See
9191 @code{org-agenda-entry-types} on how to set what planning information will be
9192 taken into account.} this week/day.
9193 @item C-c a y
9194 as a global search for agenda entries planned this week/day, but only those
9195 with an hour specification like @code{[h]h:mm}---think of them as appointments.
9196 @item C-c a w
9197 as a global search for TODO entries with @samp{WAITING} as the TODO
9198 keyword
9199 @item C-c a W
9200 as the same search, but only in the current buffer and displaying the
9201 results as a sparse tree
9202 @item C-c a u
9203 as a global tags search for headlines marked @samp{:boss:} but not
9204 @samp{:urgent:}
9205 @item C-c a v
9206 as the same search as @kbd{C-c a u}, but limiting the search to
9207 headlines that are also TODO items
9208 @item C-c a U
9209 as the same search as @kbd{C-c a u}, but only in the current buffer and
9210 displaying the result as a sparse tree
9211 @item C-c a f
9212 to create a sparse tree (again: current buffer only) with all entries
9213 containing the word @samp{FIXME}
9214 @item C-c a h
9215 as a prefix command for a HOME tags search where you have to press an
9216 additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,
9217 Peter, or Kim) as additional tag to match.
9218 @end table
9220 Note that the @code{*-tree} agenda views need to be called from an
9221 Org buffer as they operate on the current buffer only.
9223 @node Block agenda, Setting Options, Storing searches, Custom agenda views
9224 @subsection Block agenda
9225 @cindex block agenda
9226 @cindex agenda, with block views
9228 Another possibility is the construction of agenda views that comprise
9229 the results of @emph{several} commands, each of which creates a block in
9230 the agenda buffer.  The available commands include @code{agenda} for the
9231 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
9232 for the global TODO list (as constructed with @kbd{C-c a t}), and the
9233 matching commands discussed above: @code{todo}, @code{tags}, and
9234 @code{tags-todo}.  Here are two examples:
9236 @lisp
9237 @group
9238 (setq org-agenda-custom-commands
9239       '(("h" "Agenda and Home-related tasks"
9240          ((agenda "")
9241           (tags-todo "home")
9242           (tags "garden")))
9243         ("o" "Agenda and Office-related tasks"
9244          ((agenda "")
9245           (tags-todo "work")
9246           (tags "office")))))
9247 @end group
9248 @end lisp
9250 @noindent
9251 This will define @kbd{C-c a h} to create a multi-block view for stuff
9252 you need to attend to at home.  The resulting agenda buffer will contain
9253 your agenda for the current week, all TODO items that carry the tag
9254 @samp{home}, and also all lines tagged with @samp{garden}.  Finally the
9255 command @kbd{C-c a o} provides a similar view for office tasks.
9257 @node Setting Options,  , Block agenda, Custom agenda views
9258 @subsection Setting options for custom commands
9259 @cindex options, for custom agenda views
9261 @vindex org-agenda-custom-commands
9262 Org mode contains a number of variables regulating agenda construction
9263 and display.  The global variables define the behavior for all agenda
9264 commands, including the custom commands.  However, if you want to change
9265 some settings just for a single custom view, you can do so.  Setting
9266 options requires inserting a list of variable names and values at the
9267 right spot in @code{org-agenda-custom-commands}.  For example:
9269 @lisp
9270 @group
9271 (setq org-agenda-custom-commands
9272       '(("w" todo "WAITING"
9273          ((org-agenda-sorting-strategy '(priority-down))
9274           (org-agenda-prefix-format "  Mixed: ")))
9275         ("U" tags-tree "+boss-urgent"
9276          ((org-show-following-heading nil)
9277           (org-show-hierarchy-above nil)))
9278         ("N" search ""
9279          ((org-agenda-files '("~org/notes.org"))
9280           (org-agenda-text-search-extra-files nil)))))
9281 @end group
9282 @end lisp
9284 @noindent
9285 Now the @kbd{C-c a w} command will sort the collected entries only by
9286 priority, and the prefix format is modified to just say @samp{  Mixed: }
9287 instead of giving the category of the entry.  The sparse tags tree of
9288 @kbd{C-c a U} will now turn out ultra-compact, because neither the
9289 headline hierarchy above the match, nor the headline following the match
9290 will be shown.  The command @kbd{C-c a N} will do a text search limited
9291 to only a single file.
9293 @vindex org-agenda-custom-commands
9294 For command sets creating a block agenda,
9295 @code{org-agenda-custom-commands} has two separate spots for setting
9296 options.  You can add options that should be valid for just a single
9297 command in the set, and options that should be valid for all commands in
9298 the set.  The former are just added to the command entry; the latter
9299 must come after the list of command entries.  Going back to the block
9300 agenda example (@pxref{Block agenda}), let's change the sorting strategy
9301 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
9302 the results for GARDEN tags query in the opposite order,
9303 @code{priority-up}.  This would look like this:
9305 @lisp
9306 @group
9307 (setq org-agenda-custom-commands
9308       '(("h" "Agenda and Home-related tasks"
9309          ((agenda)
9310           (tags-todo "home")
9311           (tags "garden"
9312                 ((org-agenda-sorting-strategy '(priority-up)))))
9313          ((org-agenda-sorting-strategy '(priority-down))))
9314         ("o" "Agenda and Office-related tasks"
9315          ((agenda)
9316           (tags-todo "work")
9317           (tags "office")))))
9318 @end group
9319 @end lisp
9321 As you see, the values and parentheses setting is a little complex.
9322 When in doubt, use the customize interface to set this variable---it
9323 fully supports its structure.  Just one caveat: when setting options in
9324 this interface, the @emph{values} are just Lisp expressions.  So if the
9325 value is a string, you need to add the double-quotes around the value
9326 yourself.
9328 @vindex org-agenda-custom-commands-contexts
9329 To control whether an agenda command should be accessible from a specific
9330 context, you can customize @code{org-agenda-custom-commands-contexts}.  Let's
9331 say for example that you have an agenda commands @code{"o"} displaying a view
9332 that you only need when reading emails.  Then you would configure this option
9333 like this:
9335 @lisp
9336 (setq org-agenda-custom-commands-contexts
9337       '(("o" (in-mode . "message-mode"))))
9338 @end lisp
9340 You can also tell that the command key @code{"o"} should refer to another
9341 command key @code{"r"}.  In that case, add this command key like this:
9343 @lisp
9344 (setq org-agenda-custom-commands-contexts
9345       '(("o" "r" (in-mode . "message-mode"))))
9346 @end lisp
9348 See the docstring of the variable for more information.
9350 @node Exporting Agenda Views, Agenda column view, Custom agenda views, Agenda Views
9351 @section Exporting Agenda Views
9352 @cindex agenda views, exporting
9354 If you are away from your computer, it can be very useful to have a printed
9355 version of some agenda views to carry around.  Org mode can export custom
9356 agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's
9357 @file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the
9358 ghostscript @file{ps2pdf} utility must be installed on the system.  Selecting
9359 a PDF file will also create the postscript file.}, and iCalendar files.  If
9360 you want to do this only occasionally, use the command
9362 @table @kbd
9363 @orgcmd{C-x C-w,org-agenda-write}
9364 @cindex exporting agenda views
9365 @cindex agenda views, exporting
9366 @vindex org-agenda-exporter-settings
9367 Write the agenda view to a file.  Depending on the extension of the selected
9368 file name, the view will be exported as HTML (extension @file{.html} or
9369 @file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension
9370 @file{.ics}), or plain text (any other extension).  Use the variable
9371 @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
9372 for @file{htmlize} to be used during export, for example
9374 @vindex org-agenda-add-entry-text-maxlines
9375 @vindex htmlize-output-type
9376 @vindex ps-number-of-columns
9377 @vindex ps-landscape-mode
9378 @lisp
9379 (setq org-agenda-exporter-settings
9380       '((ps-number-of-columns 2)
9381         (ps-landscape-mode t)
9382         (org-agenda-add-entry-text-maxlines 5)
9383         (htmlize-output-type 'css)))
9384 @end lisp
9385 @end table
9387 If you need to export certain agenda views frequently, you can associate
9388 any custom agenda command with a list of output file names
9389 @footnote{If you want to store standard views like the weekly agenda
9390 or the global TODO list as well, you need to define custom commands for
9391 them in order to be able to specify file names.}.  Here is an example
9392 that first defines custom commands for the agenda and the global
9393 TODO list, together with a number of files to which to export them.
9394 Then we define two block agenda commands and specify file names for them
9395 as well.  File names can be relative to the current working directory,
9396 or absolute.
9398 @lisp
9399 @group
9400 (setq org-agenda-custom-commands
9401       '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
9402         ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
9403         ("h" "Agenda and Home-related tasks"
9404          ((agenda "")
9405           (tags-todo "home")
9406           (tags "garden"))
9407          nil
9408          ("~/views/home.html"))
9409         ("o" "Agenda and Office-related tasks"
9410          ((agenda)
9411           (tags-todo "work")
9412           (tags "office"))
9413          nil
9414          ("~/views/office.ps" "~/calendars/office.ics"))))
9415 @end group
9416 @end lisp
9418 The extension of the file name determines the type of export.  If it is
9419 @file{.html}, Org mode will use the @file{htmlize.el} package to convert
9420 the buffer to HTML and save it to this file name.  If the extension is
9421 @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
9422 Postscript output.  If the extension is @file{.ics}, iCalendar export is
9423 run export over all files that were used to construct the agenda, and
9424 limit the export to entries listed in the agenda.  Any other
9425 extension produces a plain ASCII file.
9427 The export files are @emph{not} created when you use one of those
9428 commands interactively because this might use too much overhead.
9429 Instead, there is a special command to produce @emph{all} specified
9430 files in one step:
9432 @table @kbd
9433 @orgcmd{C-c a e,org-store-agenda-views}
9434 Export all agenda views that have export file names associated with
9435 them.
9436 @end table
9438 You can use the options section of the custom agenda commands to also
9439 set options for the export commands.  For example:
9441 @lisp
9442 (setq org-agenda-custom-commands
9443       '(("X" agenda ""
9444          ((ps-number-of-columns 2)
9445           (ps-landscape-mode t)
9446           (org-agenda-prefix-format " [ ] ")
9447           (org-agenda-with-colors nil)
9448           (org-agenda-remove-tags t))
9449          ("theagenda.ps"))))
9450 @end lisp
9452 @noindent
9453 This command sets two options for the Postscript exporter, to make it
9454 print in two columns in landscape format---the resulting page can be cut
9455 in two and then used in a paper agenda.  The remaining settings modify
9456 the agenda prefix to omit category and scheduling information, and
9457 instead include a checkbox to check off items.  We also remove the tags
9458 to make the lines compact, and we don't want to use colors for the
9459 black-and-white printer.  Settings specified in
9460 @code{org-agenda-exporter-settings} will also apply, but the settings
9461 in @code{org-agenda-custom-commands} take precedence.
9463 @noindent
9464 From the command line you may also use
9465 @example
9466 emacs -eval (org-batch-store-agenda-views) -kill
9467 @end example
9468 @noindent
9469 or, if you need to modify some parameters@footnote{Quoting depends on the
9470 system you use, please check the FAQ for examples.}
9471 @example
9472 emacs -eval '(org-batch-store-agenda-views                      \
9473               org-agenda-span (quote month)                     \
9474               org-agenda-start-day "2007-11-01"                 \
9475               org-agenda-include-diary nil                      \
9476               org-agenda-files (quote ("~/org/project.org")))'  \
9477       -kill
9478 @end example
9479 @noindent
9480 which will create the agenda views restricted to the file
9481 @file{~/org/project.org}, without diary entries and with a 30-day
9482 extent.
9484 You can also extract agenda information in a way that allows further
9485 processing by other programs.  See @ref{Extracting agenda information}, for
9486 more information.
9489 @node Agenda column view,  , Exporting Agenda Views, Agenda Views
9490 @section Using column view in the agenda
9491 @cindex column view, in agenda
9492 @cindex agenda, column view
9494 Column view (@pxref{Column view}) is normally used to view and edit
9495 properties embedded in the hierarchical structure of an Org file.  It can be
9496 quite useful to use column view also from the agenda, where entries are
9497 collected by certain criteria.
9499 @table @kbd
9500 @orgcmd{C-c C-x C-c,org-agenda-columns}
9501 Turn on column view in the agenda.
9502 @end table
9504 To understand how to use this properly, it is important to realize that the
9505 entries in the agenda are no longer in their proper outline environment.
9506 This causes the following issues:
9508 @enumerate
9509 @item
9510 @vindex org-columns-default-format
9511 @vindex org-overriding-columns-format
9512 Org needs to make a decision which @code{COLUMNS} format to use.  Since the
9513 entries in the agenda are collected from different files, and different files
9514 may have different @code{COLUMNS} formats, this is a non-trivial problem.
9515 Org first checks if the variable @code{org-agenda-overriding-columns-format} is
9516 currently set, and if so, takes the format from there.  Otherwise it takes
9517 the format associated with the first item in the agenda, or, if that item
9518 does not have a specific format (defined in a property, or in its file), it
9519 uses @code{org-columns-default-format}.
9520 @item
9521 @cindex property, special, CLOCKSUM
9522 If any of the columns has a summary type defined (@pxref{Column attributes}),
9523 turning on column view in the agenda will visit all relevant agenda files and
9524 make sure that the computations of this property are up to date.  This is
9525 also true for the special @code{CLOCKSUM} property.  Org will then sum the
9526 values displayed in the agenda.  In the daily/weekly agenda, the sums will
9527 cover a single day; in all other views they cover the entire block.  It is
9528 vital to realize that the agenda may show the same entry @emph{twice} (for
9529 example as scheduled and as a deadline), and it may show two entries from the
9530 same hierarchy (for example a @emph{parent} and its @emph{child}).  In these
9531 cases, the summation in the agenda will lead to incorrect results because
9532 some values will count double.
9533 @item
9534 When the column view in the agenda shows the @code{CLOCKSUM}, that is always
9535 the entire clocked time for this item.  So even in the daily/weekly agenda,
9536 the clocksum listed in column view may originate from times outside the
9537 current view.  This has the advantage that you can compare these values with
9538 a column listing the planned total effort for a task---one of the major
9539 applications for column view in the agenda.  If you want information about
9540 clocked time in the displayed period use clock table mode (press @kbd{R} in
9541 the agenda).
9543 @item
9544 @cindex property, special, CLOCKSUM_T
9545 When the column view in the agenda shows the @code{CLOCKSUM_T}, that is
9546 always today's clocked time for this item.  So even in the weekly agenda,
9547 the clocksum listed in column view only originates from today.  This lets
9548 you compare the time you spent on a task for today, with the time already
9549 spent (via @code{CLOCKSUM}) and with the planned total effort for it.
9550 @end enumerate
9553 @node Markup, Exporting, Agenda Views, Top
9554 @chapter Markup for rich export
9556 When exporting Org mode documents, the exporter tries to reflect the
9557 structure of the document as accurately as possible in the back-end.  Since
9558 export targets like HTML, @LaTeX{} allow much richer formatting, Org mode has
9559 rules on how to prepare text for rich export.  This section summarizes the
9560 markup rules used in an Org mode buffer.
9562 @menu
9563 * Structural markup elements::  The basic structure as seen by the exporter
9564 * Images and tables::           Images, tables and caption mechanism
9565 * Literal examples::            Source code examples with special formatting
9566 * Include files::               Include additional files into a document
9567 * Index entries::               Making an index
9568 * Macro replacement::           Use macros to create templates
9569 * Embedded @LaTeX{}::           LaTeX can be freely used inside Org documents
9570 * Special blocks::              Containers targeted at export back-ends
9571 @end menu
9573 @node Structural markup elements, Images and tables, Markup, Markup
9574 @section Structural markup elements
9576 @menu
9577 * Document title::              Where the title is taken from
9578 * Headings and sections::       The document structure as seen by the exporter
9579 * Table of contents::           The if and where of the table of contents
9580 * Lists::                       Lists
9581 * Paragraphs::                  Paragraphs
9582 * Footnote markup::             Footnotes
9583 * Emphasis and monospace::      Bold, italic, etc.
9584 * Horizontal rules::            Make a line
9585 * Comment lines::               What will *not* be exported
9586 @end menu
9588 @node Document title, Headings and sections, Structural markup elements, Structural markup elements
9589 @subheading Document title
9590 @cindex document title, markup rules
9592 @noindent
9593 The title of the exported document is taken from the special line
9595 @cindex #+TITLE
9596 @example
9597 #+TITLE: This is the title of the document
9598 @end example
9600 @noindent
9601 If this line does not exist, the title will be the name of the file
9602 associated to buffer, without extension, or the buffer name.
9604 @cindex property, EXPORT_TITLE
9605 If you are exporting only a subtree, its heading will become the title of the
9606 document.  If the subtree has a property @code{EXPORT_TITLE}, that will take
9607 precedence.
9609 @node Headings and sections, Table of contents, Document title, Structural markup elements
9610 @subheading Headings and sections
9611 @cindex headings and sections, markup rules
9613 @vindex org-export-headline-levels
9614 The outline structure of the document as described in @ref{Document
9615 Structure}, forms the basis for defining sections of the exported document.
9616 However, since the outline structure is also used for (for example) lists of
9617 tasks, only the first three outline levels will be used as headings.  Deeper
9618 levels will become itemized lists.  You can change the location of this
9619 switch globally by setting the variable @code{org-export-headline-levels}, or on a
9620 per-file basis with a line
9622 @cindex #+OPTIONS
9623 @example
9624 #+OPTIONS: H:4
9625 @end example
9627 @node Table of contents, Lists, Headings and sections, Structural markup elements
9628 @subheading Table of contents
9629 @cindex table of contents, markup rules
9631 @cindex #+TOC
9632 @vindex org-export-with-toc
9633 The table of contents is normally inserted directly before the first headline
9634 of the file.  The depth of the table is by default the same as the number of
9635 headline levels, but you can choose a smaller number, or turn off the table
9636 of contents entirely, by configuring the variable @code{org-export-with-toc},
9637 or on a per-file basis with a line like
9639 @example
9640 #+OPTIONS: toc:2          (only to two levels in TOC)
9641 #+OPTIONS: toc:nil        (no default TOC at all)
9642 @end example
9644 If you would like to move the table of contents to a different location, you
9645 should turn off the default table using @code{org-export-with-toc} or
9646 @code{#+OPTIONS} and insert @code{#+TOC: headlines N} at the desired
9647 location(s).
9649 @example
9650 #+OPTIONS: toc:nil        (no default TOC)
9652 #+TOC: headlines 2        (insert TOC here, with two headline levels)
9653 @end example
9655 Multiple @code{#+TOC: headline} lines are allowed.  The same @code{TOC}
9656 keyword can also generate a list of all tables (resp.@: all listings) with a
9657 caption in the buffer.
9659 @example
9660 #+TOC: listings           (build a list of listings)
9661 #+TOC: tables             (build a list of tables)
9662 @end example
9664 @cindex property, ALT_TITLE
9665 The headline's title usually determines its corresponding entry in a table of
9666 contents.  However, it is possible to specify an alternative title by
9667 setting @code{ALT_TITLE} property accordingly.  It will then be used when
9668 building the table.
9670 @node Lists, Paragraphs, Table of contents, Structural markup elements
9671 @subheading Lists
9672 @cindex lists, markup rules
9674 Plain lists as described in @ref{Plain lists}, are translated to the back-end's
9675 syntax for such lists.  Most back-ends support unordered, ordered, and
9676 description lists.
9678 @node Paragraphs, Footnote markup, Lists, Structural markup elements
9679 @subheading Paragraphs, line breaks, and quoting
9680 @cindex paragraphs, markup rules
9682 Paragraphs are separated by at least one empty line.  If you need to enforce
9683 a line break within a paragraph, use @samp{\\} at the end of a line.
9685 To keep the line breaks in a region, but otherwise use normal formatting, you
9686 can use this construct, which can also be used to format poetry.
9688 @cindex #+BEGIN_VERSE
9689 @example
9690 #+BEGIN_VERSE
9691  Great clouds overhead
9692  Tiny black birds rise and fall
9693  Snow covers Emacs
9695      -- AlexSchroeder
9696 #+END_VERSE
9697 @end example
9699 When quoting a passage from another document, it is customary to format this
9700 as a paragraph that is indented on both the left and the right margin.  You
9701 can include quotations in Org mode documents like this:
9703 @cindex #+BEGIN_QUOTE
9704 @example
9705 #+BEGIN_QUOTE
9706 Everything should be made as simple as possible,
9707 but not any simpler -- Albert Einstein
9708 #+END_QUOTE
9709 @end example
9711 If you would like to center some text, do it like this:
9712 @cindex #+BEGIN_CENTER
9713 @example
9714 #+BEGIN_CENTER
9715 Everything should be made as simple as possible, \\
9716 but not any simpler
9717 #+END_CENTER
9718 @end example
9721 @node Footnote markup, Emphasis and monospace, Paragraphs, Structural markup elements
9722 @subheading Footnote markup
9723 @cindex footnotes, markup rules
9724 @cindex @file{footnote.el}
9726 Footnotes defined in the way described in @ref{Footnotes}, will be exported
9727 by all back-ends.  Org allows multiple references to the same note, and
9728 multiple footnotes side by side.
9730 @node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements
9731 @subheading Emphasis and monospace
9733 @cindex underlined text, markup rules
9734 @cindex bold text, markup rules
9735 @cindex italic text, markup rules
9736 @cindex verbatim text, markup rules
9737 @cindex code text, markup rules
9738 @cindex strike-through text, markup rules
9739 @vindex org-fontify-emphasized-text
9740 @vindex org-emphasis-regexp-components
9741 @vindex org-emphasis-alist
9742 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=verbatim=}
9743 and @code{~code~}, and, if you must, @samp{+strike-through+}.  Text
9744 in the code and verbatim string is not processed for Org mode specific
9745 syntax, it is exported verbatim.
9747 To turn off fontification for marked up text, you can set
9748 @code{org-fontify-emphasized-text} to @code{nil}.  To narrow down the list of
9749 available markup syntax, you can customize @code{org-emphasis-alist}.  To fine
9750 tune what characters are allowed before and after the markup characters, you
9751 can tweak @code{org-emphasis-regexp-components}.  Beware that changing one of
9752 the above variables will no take effect until you reload Org, for which you
9753 may need to restart Emacs.
9755 @node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements
9756 @subheading  Horizontal rules
9757 @cindex horizontal rules, markup rules
9758 A line consisting of only dashes, and at least 5 of them, will be exported as
9759 a horizontal line.
9761 @node Comment lines,  , Horizontal rules, Structural markup elements
9762 @subheading Comment lines
9763 @cindex comment lines
9764 @cindex exporting, not
9765 @cindex #+BEGIN_COMMENT
9767 Lines starting with zero or more whitespace characters followed by one
9768 @samp{#} and a whitespace are treated as comments and will never be exported.
9769 Also entire subtrees starting with the word @samp{COMMENT} will never be
9770 exported.  Finally, regions surrounded by @samp{#+BEGIN_COMMENT}
9771 ... @samp{#+END_COMMENT} will not be exported.
9773 @table @kbd
9774 @kindex C-c ;
9775 @item C-c ;
9776 Toggle the COMMENT keyword at the beginning of an entry.
9777 @end table
9780 @node Images and tables, Literal examples, Structural markup elements, Markup
9781 @section Images and Tables
9783 @cindex tables, markup rules
9784 @cindex #+CAPTION
9785 @cindex #+NAME
9786 Both the native Org mode tables (@pxref{Tables}) and tables formatted with
9787 the @file{table.el} package will be exported properly.  For Org mode tables,
9788 the lines before the first horizontal separator line will become table header
9789 lines.  You can use the following lines somewhere before the table to assign
9790 a caption and a label for cross references, and in the text you can refer to
9791 the object with @code{[[tab:basic-data]]} (@pxref{Internal links}):
9793 @example
9794 #+CAPTION: This is the caption for the next table (or link)
9795 #+NAME:   tab:basic-data
9796    | ... | ...|
9797    |-----|----|
9798 @end example
9800 Optionally, the caption can take the form:
9801 @example
9802 #+CAPTION[Caption for list of tables]: Caption for table.
9803 @end example
9805 @cindex inlined images, markup rules
9806 Some back-ends allow you to directly include images into the exported
9807 document.  Org does this, if a link to an image files does not have
9808 a description part, for example @code{[[./img/a.jpg]]}.  If you wish to
9809 define a caption for the image and maybe a label for internal cross
9810 references, make sure that the link is on a line by itself and precede it
9811 with @code{#+CAPTION} and @code{#+NAME} as follows:
9813 @example
9814 #+CAPTION: This is the caption for the next figure link (or table)
9815 #+NAME:   fig:SED-HR4049
9816 [[./img/a.jpg]]
9817 @end example
9819 @noindent
9820 Such images can be displayed within the buffer.  @xref{Handling links,the
9821 discussion of image links}.
9823 Even though images and tables are prominent examples of captioned structures,
9824 the same caption mechanism can apply to many others (e.g., @LaTeX{}
9825 equations, source code blocks).  Depending on the export back-end, those may
9826 or may not be handled.
9828 @node Literal examples, Include files, Images and tables, Markup
9829 @section Literal examples
9830 @cindex literal examples, markup rules
9831 @cindex code line references, markup rules
9833 You can include literal examples that should not be subjected to
9834 markup.  Such examples will be typeset in monospace, so this is well suited
9835 for source code and similar examples.
9836 @cindex #+BEGIN_EXAMPLE
9838 @example
9839 #+BEGIN_EXAMPLE
9840 Some example from a text file.
9841 #+END_EXAMPLE
9842 @end example
9844 Note that such blocks may be @i{indented} in order to align nicely with
9845 indented text and in particular with plain list structure (@pxref{Plain
9846 lists}).  For simplicity when using small examples, you can also start the
9847 example lines with a colon followed by a space.  There may also be additional
9848 whitespace before the colon:
9850 @example
9851 Here is an example
9852    : Some example from a text file.
9853 @end example
9855 @cindex formatting source code, markup rules
9856 If the example is source code from a programming language, or any other text
9857 that can be marked up by font-lock in Emacs, you can ask for the example to
9858 look like the fontified Emacs buffer@footnote{This works automatically for
9859 the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package,
9860 which is distributed with Org).  Fontified code chunks in @LaTeX{} can be
9861 achieved using either the listings or the
9862 @url{http://code.google.com/p/minted, minted,} package.  Refer to
9863 @code{org-latex-listings} documentation for details.}.  This is done
9864 with the @samp{src} block, where you also need to specify the name of the
9865 major mode that should be used to fontify the example@footnote{Code in
9866 @samp{src} blocks may also be evaluated either interactively or on export.
9867 See @pxref{Working With Source Code} for more information on evaluating code
9868 blocks.}, see @ref{Easy Templates} for shortcuts to easily insert code
9869 blocks.
9870 @cindex #+BEGIN_SRC
9872 @example
9873 #+BEGIN_SRC emacs-lisp
9874   (defun org-xor (a b)
9875      "Exclusive or."
9876      (if a (not b) b))
9877 #+END_SRC
9878 @end example
9880 Both in @code{example} and in @code{src} snippets, you can add a @code{-n}
9881 switch to the end of the @code{BEGIN} line, to get the lines of the example
9882 numbered.  If you use a @code{+n} switch, the numbering from the previous
9883 numbered snippet will be continued in the current one.  In literal examples,
9884 Org will interpret strings like @samp{(ref:name)} as labels, and use them as
9885 targets for special hyperlinks like @code{[[(name)]]} (i.e., the reference name
9886 enclosed in single parenthesis).  In HTML, hovering the mouse over such a
9887 link will remote-highlight the corresponding code line, which is kind of
9888 cool.
9890 You can also add a @code{-r} switch which @i{removes} the labels from the
9891 source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
9892 labels in the source code while using line numbers for the links, which might
9893 be useful to explain those in an Org mode example code.}.  With the @code{-n}
9894 switch, links to these references will be labeled by the line numbers from
9895 the code listing, otherwise links will use the labels with no parentheses.
9896 Here is an example:
9898 @example
9899 #+BEGIN_SRC emacs-lisp -n -r
9900 (save-excursion                  (ref:sc)
9901    (goto-char (point-min)))      (ref:jump)
9902 #+END_SRC
9903 In line [[(sc)]] we remember the current position.  [[(jump)][Line (jump)]]
9904 jumps to point-min.
9905 @end example
9907 @vindex org-coderef-label-format
9908 If the syntax for the label format conflicts with the language syntax, use a
9909 @code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
9910 -n -r -l "((%s))"}.  See also the variable @code{org-coderef-label-format}.
9912 HTML export also allows examples to be published as text areas (@pxref{Text
9913 areas in HTML export}).
9915 Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
9916 so often, shortcuts are provided using the Easy Templates facility
9917 (@pxref{Easy Templates}).
9919 @table @kbd
9920 @kindex C-c '
9921 @item C-c '
9922 Edit the source code example at point in its native mode.  This works by
9923 switching to a temporary buffer with the source code.  You need to exit by
9924 pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*},
9925 @samp{,*}, @samp{#+} and @samp{,#+} will get a comma prepended, to keep them
9926 from being interpreted by Org as outline nodes or special syntax.  These
9927 commas will be stripped for editing with @kbd{C-c '}, and also for export.}.
9928 The edited version will then replace the old version in the Org buffer.
9929 Fixed-width regions (where each line starts with a colon followed by a space)
9930 will be edited using @code{artist-mode}@footnote{You may select
9931 a different-mode with the variable @code{org-edit-fixed-width-region-mode}.}
9932 to allow creating ASCII drawings easily.  Using this command in an empty line
9933 will create a new fixed-width region.
9934 @kindex C-c l
9935 @item C-c l
9936 Calling @code{org-store-link} while editing a source code example in a
9937 temporary buffer created with @kbd{C-c '} will prompt for a label.  Make sure
9938 that it is unique in the current buffer, and insert it with the proper
9939 formatting like @samp{(ref:label)} at the end of the current line.  Then the
9940 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
9941 @end table
9944 @node Include files, Index entries, Literal examples, Markup
9945 @section Include files
9946 @cindex include files, markup rules
9948 During export, you can include the content of another file.  For example, to
9949 include your @file{.emacs} file, you could use:
9950 @cindex #+INCLUDE
9952 @example
9953 #+INCLUDE: "~/.emacs" src emacs-lisp
9954 @end example
9956 @noindent
9957 The optional second and third parameter are the markup (i.e., @samp{example}
9958 or @samp{src}), and, if the markup is @samp{src}, the language for formatting
9959 the contents.  The markup is optional; if it is not given, the text will be
9960 assumed to be in Org mode format and will be processed normally.
9962 Contents of the included file will belong to the same structure (headline,
9963 item) containing the @code{INCLUDE} keyword.  In particular, headlines within
9964 the file will become children of the current section.  That behavior can be
9965 changed by providing an additional keyword parameter, @code{:minlevel}.  In
9966 that case, all headlines in the included file will be shifted so the one with
9967 the lowest level reaches that specified level.  For example, to make a file
9968 become a sibling of the current top-level headline, use
9970 @example
9971 #+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
9972 @end example
9974 You can also include a portion of a file by specifying a lines range using
9975 the @code{:lines} parameter.  The line at the upper end of the range will not
9976 be included.  The start and/or the end of the range may be omitted to use the
9977 obvious defaults.
9979 @example
9980 #+INCLUDE: "~/.emacs" :lines "5-10"   @r{Include lines 5 to 10, 10 excluded}
9981 #+INCLUDE: "~/.emacs" :lines "-10"    @r{Include lines 1 to 10, 10 excluded}
9982 #+INCLUDE: "~/.emacs" :lines "10-"    @r{Include lines from 10 to EOF}
9983 @end example
9985 @table @kbd
9986 @kindex C-c '
9987 @item C-c '
9988 Visit the include file at point.
9989 @end table
9991 @node Index entries, Macro replacement, Include files, Markup
9992 @section Index entries
9993 @cindex index entries, for publishing
9995 You can specify entries that will be used for generating an index during
9996 publishing.  This is done by lines starting with @code{#+INDEX}.  An entry
9997 the contains an exclamation mark will create a sub item.  See @ref{Generating
9998 an index} for more information.
10000 @example
10001 * Curriculum Vitae
10002 #+INDEX: CV
10003 #+INDEX: Application!CV
10004 @end example
10009 @node Macro replacement, Embedded @LaTeX{}, Index entries, Markup
10010 @section Macro replacement
10011 @cindex macro replacement, during export
10012 @cindex #+MACRO
10014 You can define text snippets with
10016 @example
10017 #+MACRO: name   replacement text $1, $2 are arguments
10018 @end example
10020 @noindent which can be referenced in
10021 paragraphs, verse blocks, table cells and some keywords with
10022 @code{@{@{@{name(arg1,arg2)@}@}@}}@footnote{Since commas separate arguments,
10023 commas within arguments have to be escaped with a backslash character.
10024 Conversely, backslash characters before a comma, and only them, need to be
10025 escaped with another backslash character.}.  In addition to defined macros,
10026 @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc., will reference
10027 information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and similar lines.
10028 Also, @code{@{@{@{time(@var{FORMAT})@}@}@}} and
10029 @code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date time
10030 and to the modification time of the file being exported, respectively.
10031 @var{FORMAT} should be a format string understood by
10032 @code{format-time-string}.
10034 Macro expansion takes place during export.
10037 @node Embedded @LaTeX{}, Special blocks, Macro replacement, Markup
10038 @section Embedded @LaTeX{}
10039 @cindex @TeX{} interpretation
10040 @cindex @LaTeX{} interpretation
10042 Plain ASCII is normally sufficient for almost all note taking.  Exceptions
10043 include scientific notes, which often require mathematical symbols and the
10044 occasional formula.  @LaTeX{}@footnote{@LaTeX{} is a macro system based on
10045 Donald E. Knuth's @TeX{} system.  Many of the features described here as
10046 ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
10047 distinction.}  is widely used to typeset scientific documents.  Org mode
10048 supports embedding @LaTeX{} code into its files, because many academics are
10049 used to writing and reading @LaTeX{} source code, and because it can be
10050 readily processed to produce pretty output for a number of export back-ends.
10052 @menu
10053 * Special symbols::             Greek letters and other symbols
10054 * Subscripts and superscripts::  Simple syntax for raising/lowering text
10055 * @LaTeX{} fragments::          Complex formulas made easy
10056 * Previewing @LaTeX{} fragments::  What will this snippet look like?
10057 * CDLaTeX mode::                Speed up entering of formulas
10058 @end menu
10060 @node Special symbols, Subscripts and superscripts, Embedded @LaTeX{}, Embedded @LaTeX{}
10061 @subsection Special symbols
10062 @cindex math symbols
10063 @cindex special symbols
10064 @cindex @TeX{} macros
10065 @cindex @LaTeX{} fragments, markup rules
10066 @cindex HTML entities
10067 @cindex @LaTeX{} entities
10069 You can use @LaTeX{}-like syntax to insert special symbols like @samp{\alpha}
10070 to indicate the Greek letter, or @samp{\to} to indicate an arrow.  Completion
10071 for these symbols is available, just type @samp{\} and maybe a few letters,
10072 and press @kbd{M-@key{TAB}} to see possible completions.  Unlike @LaTeX{}
10073 code, Org mode allows these symbols to be present without surrounding math
10074 delimiters, for example:
10076 @example
10077 Angles are written as Greek letters \alpha, \beta and \gamma.
10078 @end example
10080 @vindex org-entities
10081 During export, these symbols will be transformed into the native format of
10082 the exporter back-end.  Strings like @code{\alpha} will be exported as
10083 @code{&alpha;} in the HTML output, and as @code{$\alpha$} in the @LaTeX{}
10084 output.  Similarly, @code{\nbsp} will become @code{&nbsp;} in HTML and
10085 @code{~} in @LaTeX{}.  If you need such a symbol inside a word, terminate it
10086 like this: @samp{\Aacute@{@}stor}.
10088 A large number of entities is provided, with names taken from both HTML and
10089 @LaTeX{}; see the variable @code{org-entities} for the complete list.
10090 @samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and
10091 @samp{...} are all converted into special commands creating hyphens of
10092 different lengths or a compact set of dots.
10094 If you would like to see entities displayed as UTF-8 characters, use the
10095 following command@footnote{You can turn this on by default by setting the
10096 variable @code{org-pretty-entities}, or on a per-file base with the
10097 @code{#+STARTUP} option @code{entitiespretty}.}:
10099 @table @kbd
10100 @cindex @code{entitiespretty}, STARTUP keyword
10101 @kindex C-c C-x \
10102 @item C-c C-x \
10103 Toggle display of entities as UTF-8 characters.  This does not change the
10104 buffer content which remains plain ASCII, but it overlays the UTF-8 character
10105 for display purposes only.
10106 @end table
10108 @node Subscripts and superscripts, @LaTeX{} fragments, Special symbols, Embedded @LaTeX{}
10109 @subsection Subscripts and superscripts
10110 @cindex subscript
10111 @cindex superscript
10113 Just like in @LaTeX{}, @samp{^} and @samp{_} are used to indicate super- and
10114 subscripts.  Again, these can be used without embedding them in math-mode
10115 delimiters.  To increase the readability of ASCII text, it is not necessary
10116 (but OK) to surround multi-character sub- and superscripts with curly braces.
10117 For example
10119 @example
10120 The mass of the sun is M_sun = 1.989 x 10^30 kg.  The radius of
10121 the sun is R_@{sun@} = 6.96 x 10^8 m.
10122 @end example
10124 @vindex org-use-sub-superscripts
10125 If you write a text where the underscore is often used in a different
10126 context, Org's convention to always interpret these as subscripts can get in
10127 your way.  Configure the variable @code{org-use-sub-superscripts} to change
10128 this convention.  For example, when setting this variable to @code{@{@}},
10129 @samp{a_b} will not be interpreted as a subscript, but @samp{a_@{b@}} will.
10131 @table @kbd
10132 @kindex C-c C-x \
10133 @item C-c C-x \
10134 In addition to showing entities as UTF-8 characters, this command will also
10135 format sub- and superscripts in a WYSIWYM way.
10136 @end table
10138 @node @LaTeX{} fragments, Previewing @LaTeX{} fragments, Subscripts and superscripts, Embedded @LaTeX{}
10139 @subsection @LaTeX{} fragments
10140 @cindex @LaTeX{} fragments
10142 @vindex org-format-latex-header
10143 Going beyond symbols and sub- and superscripts, a full formula language is
10144 needed.  Org mode can contain @LaTeX{} math fragments, and it supports ways
10145 to process these for several export back-ends.  When exporting to @LaTeX{},
10146 the code is obviously left as it is.  When exporting to HTML, Org invokes the
10147 @uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in
10148 HTML export}) to process and display the math@footnote{If you plan to use
10149 this regularly or on pages with significant page views, you should install
10150 @file{MathJax} on your own server in order to limit the load of our server.}.
10151 Finally, it can also process the mathematical expressions into
10152 images@footnote{For this to work you need to be on a system with a working
10153 @LaTeX{} installation.  You also need the @file{dvipng} program or the
10154 @file{convert}, respectively available at
10155 @url{http://sourceforge.net/projects/dvipng/} and from the @file{imagemagick}
10156 suite.  The @LaTeX{} header that will be used when processing a fragment can
10157 be configured with the variable @code{org-format-latex-header}.} that can be
10158 displayed in a browser.
10160 @LaTeX{} fragments don't need any special marking at all.  The following
10161 snippets will be identified as @LaTeX{} source code:
10162 @itemize @bullet
10163 @item
10164 Environments of any kind@footnote{When @file{MathJax} is used, only the
10165 environments recognized by @file{MathJax} will be processed.  When
10166 @file{dvipng} program or @file{imagemagick} suite is used to create images,
10167 any @LaTeX{} environment will be handled.}.  The only requirement is that the
10168 @code{\begin} and @code{\end} statements appear on a new line, at the
10169 beginning of the line or after whitespaces only.
10170 @item
10171 Text within the usual @LaTeX{} math delimiters.  To avoid conflicts with
10172 currency specifications, single @samp{$} characters are only recognized as
10173 math delimiters if the enclosed text contains at most two line breaks, is
10174 directly attached to the @samp{$} characters with no whitespace in between,
10175 and if the closing @samp{$} is followed by whitespace, punctuation or a dash.
10176 For the other delimiters, there is no such restriction, so when in doubt, use
10177 @samp{\(...\)} as inline math delimiters.
10178 @end itemize
10180 @noindent For example:
10182 @example
10183 \begin@{equation@}
10184 x=\sqrt@{b@}
10185 \end@{equation@}
10187 If $a^2=b$ and \( b=2 \), then the solution must be
10188 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
10189 @end example
10191 @c FIXME
10192 @c @noindent
10193 @c @vindex org-format-latex-options
10194 @c If you need any of the delimiter ASCII sequences for other purposes, you
10195 @c can configure the option @code{org-format-latex-options} to deselect the
10196 @c ones you do not wish to have interpreted by the @LaTeX{} converter.
10198 @vindex org-export-with-latex
10199 @LaTeX{} processing can be configured with the variable
10200 @code{org-export-with-latex}.  The default setting is @code{t} which means
10201 @file{MathJax} for HTML, and no processing for ASCII and @LaTeX{} back-ends.
10202 You can also set this variable on a per-file basis using one of these
10203 lines:
10205 @example
10206 #+OPTIONS: tex:t          @r{Do the right thing automatically (MathJax)}
10207 #+OPTIONS: tex:nil        @r{Do not process @LaTeX{} fragments at all}
10208 #+OPTIONS: tex:verbatim   @r{Verbatim export, for jsMath or so}
10209 @end example
10211 @node Previewing @LaTeX{} fragments, CDLaTeX mode, @LaTeX{} fragments, Embedded @LaTeX{}
10212 @subsection Previewing @LaTeX{} fragments
10213 @cindex @LaTeX{} fragments, preview
10215 @vindex org-latex-create-formula-image-program
10216 If you have @file{dvipng} or @file{imagemagick} installed@footnote{Choose the
10217 converter by setting the variable
10218 @code{org-latex-create-formula-image-program} accordingly.}, @LaTeX{}
10219 fragments can be processed to produce preview images of the typeset
10220 expressions:
10222 @table @kbd
10223 @kindex C-c C-x C-l
10224 @item C-c C-x C-l
10225 Produce a preview image of the @LaTeX{} fragment at point and overlay it
10226 over the source code.  If there is no fragment at point, process all
10227 fragments in the current entry (between two headlines).  When called
10228 with a prefix argument, process the entire subtree.  When called with
10229 two prefix arguments, or when the cursor is before the first headline,
10230 process the entire buffer.
10231 @kindex C-c C-c
10232 @item C-c C-c
10233 Remove the overlay preview images.
10234 @end table
10236 @vindex org-format-latex-options
10237 You can customize the variable @code{org-format-latex-options} to influence
10238 some aspects of the preview.  In particular, the @code{:scale} (and for HTML
10239 export, @code{:html-scale}) property can be used to adjust the size of the
10240 preview images.
10242 @vindex org-startup-with-latex-preview
10243 You can turn on the previewing of all @LaTeX{} fragments in a file with
10245 @example
10246 #+STARTUP: latexpreview
10247 @end example
10249 To disable it, simply use
10251 @example
10252 #+STARTUP: nolatexpreview
10253 @end example
10255 @node CDLaTeX mode,  , Previewing @LaTeX{} fragments, Embedded @LaTeX{}
10256 @subsection Using CD@LaTeX{} to enter math
10257 @cindex CD@LaTeX{}
10259 CD@LaTeX{} mode is a minor mode that is normally used in combination with a
10260 major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
10261 environments and math templates.  Inside Org mode, you can make use of
10262 some of the features of CD@LaTeX{} mode.  You need to install
10263 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
10264 AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
10265 Don't use CD@LaTeX{} mode itself under Org mode, but use the light
10266 version @code{org-cdlatex-mode} that comes as part of Org mode.  Turn it
10267 on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all
10268 Org files with
10270 @lisp
10271 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
10272 @end lisp
10274 When this mode is enabled, the following features are present (for more
10275 details see the documentation of CD@LaTeX{} mode):
10276 @itemize @bullet
10277 @kindex C-c @{
10278 @item
10279 Environment templates can be inserted with @kbd{C-c @{}.
10280 @item
10281 @kindex @key{TAB}
10282 The @key{TAB} key will do template expansion if the cursor is inside a
10283 @LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is
10284 inside such a fragment, see the documentation of the function
10285 @code{org-inside-LaTeX-fragment-p}.}.  For example, @key{TAB} will
10286 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
10287 correctly inside the first brace.  Another @key{TAB} will get you into
10288 the second brace.  Even outside fragments, @key{TAB} will expand
10289 environment abbreviations at the beginning of a line.  For example, if
10290 you write @samp{equ} at the beginning of a line and press @key{TAB},
10291 this abbreviation will be expanded to an @code{equation} environment.
10292 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help RET}.
10293 @item
10294 @kindex _
10295 @kindex ^
10296 @vindex cdlatex-simplify-sub-super-scripts
10297 Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these
10298 characters together with a pair of braces.  If you use @key{TAB} to move
10299 out of the braces, and if the braces surround only a single character or
10300 macro, they are removed again (depending on the variable
10301 @code{cdlatex-simplify-sub-super-scripts}).
10302 @item
10303 @kindex `
10304 Pressing the backquote @kbd{`} followed by a character inserts math
10305 macros, also outside @LaTeX{} fragments.  If you wait more than 1.5 seconds
10306 after the backquote, a help window will pop up.
10307 @item
10308 @kindex '
10309 Pressing the single-quote @kbd{'} followed by another character modifies
10310 the symbol before point with an accent or a font.  If you wait more than
10311 1.5 seconds after the single-quote, a help window will pop up.  Character
10312 modification will work only inside @LaTeX{} fragments; outside the quote
10313 is normal.
10314 @end itemize
10316 @node Special blocks,  , Embedded @LaTeX{}, Markup
10317 @section Special blocks
10318 @cindex Special blocks
10320 Org syntax includes pre-defined blocks (@pxref{Paragraphs} and @ref{Literal
10321 examples}).  It is also possible to create blocks containing raw code
10322 targeted at a specific back-ends (e.g., @samp{#+BEGIN_LATEX}).
10324 Any other block is a @emph{special block}.
10326 For example, @samp{#+BEGIN_ABSTRACT} and @samp{#+BEGIN_VIDEO} are special
10327 blocks.  The first one is useful when exporting to @LaTeX{}, the second one
10328 when exporting to HTML5.
10330 Each export back-end decides if they should be exported, and how.  When the
10331 block is ignored, its contents are still exported, as if the opening and
10332 closing block lines were not there.  For example, when exporting a
10333 @samp{#+BEGIN_TEST} block, HTML back-end wraps its contents within a
10334 @samp{<div name="test">} tag.
10336 Refer to back-end specific documentation for more information.
10338 @node Exporting, Publishing, Markup, Top
10339 @chapter Exporting
10340 @cindex exporting
10342 The Org mode export facilities can be used to export Org documents or parts
10343 of Org documents to a variety of other formats.  In addition, these
10344 facilities can be used with @code{orgtbl-mode} and/or @code{orgstruct-mode}
10345 in foreign buffers so you can author tables and lists in Org syntax and
10346 convert them in place to the target language.
10348 ASCII export produces a readable and simple version of an Org file for
10349 printing and sharing notes.  HTML export allows you to easily publish notes
10350 on the web, or to build full-fledged websites.  @LaTeX{} export lets you use
10351 Org mode and its structured editing functions to create arbitrarily complex
10352 @LaTeX{} files for any kind of document.  OpenDocument Text (ODT) export
10353 allows seamless collaboration across organizational boundaries.  Markdown
10354 export lets you seamlessly collaborate with other developers.  Finally, iCal
10355 export can extract entries with deadlines or appointments to produce a file
10356 in the iCalendar format.
10358 @menu
10359 * The Export Dispatcher::       The main exporter interface
10360 * Export back-ends::            Built-in export formats
10361 * Export settings::             Generic export settings
10362 * ASCII/Latin-1/UTF-8 export::  Exporting to flat files with encoding
10363 * Beamer export::               Exporting as a Beamer presentation
10364 * HTML export::                 Exporting to HTML
10365 * @LaTeX{} and PDF export::     Exporting to @LaTeX{}, and processing to PDF
10366 * Markdown export::             Exporting to Markdown
10367 * OpenDocument Text export::    Exporting to OpenDocument Text
10368 * Org export::                  Exporting to Org
10369 * iCalendar export::            Exporting to iCalendar
10370 * Other built-in back-ends::    Exporting to @code{Texinfo} or a man page
10371 * Export in foreign buffers::   Author tables and lists in Org syntax
10372 * Advanced configuration::      Fine-tuning the export output
10373 @end menu
10375 @node The Export Dispatcher, Export back-ends, Exporting, Exporting
10376 @section The Export Dispatcher
10377 @vindex org-export-dispatch-use-expert-ui
10378 @cindex Export, dispatcher
10380 The main entry point for export related tasks is the dispatcher, a
10381 hierarchical menu from which it is possible to select an export format and
10382 toggle export options@footnote{It is also possible to use a less intrusive
10383 interface by setting @code{org-export-dispatch-use-expert-ui} to a
10384 non-@code{nil} value.  In that case, only a prompt is visible from the
10385 minibuffer.  From there one can still switch back to regular menu by pressing
10386 @key{?}.} from which it is possible to select an export format and to toggle
10387 export options.
10389 @c @quotation
10390 @table @asis
10391 @orgcmd{C-c C-e,org-export-dispatch}
10393 Dispatch for export and publishing commands.  When called with a @kbd{C-u}
10394 prefix argument, repeat the last export command on the current buffer while
10395 preserving toggled options.  If the current buffer hasn't changed and subtree
10396 export was activated, the command will affect that same subtree.
10397 @end table
10398 @c @end quotation
10400 Normally the entire buffer is exported, but if there is an active region
10401 only that part of the buffer will be exported.
10403 Several export options (@pxref{Export settings}) can be toggled from the
10404 export dispatcher with the following key combinations:
10406 @table @kbd
10407 @item C-a
10408 @vindex org-export-async-init-file
10409 Toggle asynchronous export.  Asynchronous export uses an external Emacs
10410 process that is configured with a specified initialization file.
10412 While exporting asynchronously, the output is not displayed, but stored in
10413 a place called ``the export stack''.  This stack can be displayed by calling
10414 the dispatcher with a double @kbd{C-u} prefix argument, or with @kbd{&} key
10415 from the dispatcher menu.
10417 @vindex org-export-in-background
10418 To make this behavior the default, customize the variable
10419 @code{org-export-in-background}.
10421 @item C-b
10422 Toggle body-only export.  Its effect depends on the back-end used.
10423 Typically, if the back-end has a header section (like @code{<head>...</head>}
10424 in the HTML back-end), a body-only export will not include this header.
10426 @item C-s
10427 @vindex org-export-initial-scope
10428 Toggle subtree export.  The top heading becomes the document title.
10430 You can change the default state of this option by setting
10431 @code{org-export-initial-scope}.
10433 @item C-v
10434 Toggle visible-only export.  Only export the text that is currently
10435 visible, i.e. not hidden by outline visibility in the buffer.
10437 @end table
10439 @vindex org-export-copy-to-kill-ring
10440 With the exception of asynchronous export, a successful export process writes
10441 its output to the kill-ring. You can configure this behavior by altering the
10442 option @code{org-export-copy-to-kill-ring}.
10444 @node Export back-ends, Export settings, The Export Dispatcher, Exporting
10445 @section Export back-ends
10446 @cindex Export, back-ends
10448 An export back-end is a library that translates Org syntax into a foreign
10449 format.  An export format is not available until the proper back-end has been
10450 loaded.
10452 @vindex org-export-backends
10453 By default, the following four back-ends are loaded: @code{ascii},
10454 @code{html}, @code{icalendar} and @code{latex}.  It is possible to add more
10455 (or remove some) by customizing @code{org-export-backends}.
10457 Built-in back-ends include:
10459 @itemize
10460 @item ascii (ASCII format)
10461 @item beamer (@LaTeX{} Beamer format)
10462 @item html (HTML format)
10463 @item icalendar (iCalendar format)
10464 @item latex (@LaTeX{} format)
10465 @item man (Man page format)
10466 @item md (Markdown format)
10467 @item odt (OpenDocument Text format)
10468 @item org (Org format)
10469 @item texinfo (Texinfo format)
10470 @end itemize
10472 Other back-ends might be found in the @code{contrib/} directory
10473 (@pxref{Installation}).
10475 @node Export settings, ASCII/Latin-1/UTF-8 export, Export back-ends, Exporting
10476 @section Export settings
10477 @cindex Export, settings
10479 Export options can be set: globally with variables; for an individual file by
10480 making variables buffer-local with in-buffer settings (@pxref{In-buffer
10481 settings}), by setting individual keywords, or by specifying them in a
10482 compact form with the @code{#+OPTIONS} keyword; or for a tree by setting
10483 properties (@pxref{Properties and Columns}).  Options set at a specific level
10484 override options set at a more general level.
10486 @cindex #+SETUPFILE
10487 In-buffer settings may appear anywhere in the file, either directly or
10488 indirectly through a file included using @samp{#+SETUPFILE: filename} syntax.
10489 Option keyword sets tailored to a particular back-end can be inserted from
10490 the export dispatcher (@pxref{The Export Dispatcher}) using the @code{Insert
10491 template} command by pressing @key{#}.  To insert keywords individually,
10492 a good way to make sure the keyword is correct is to type @code{#+} and then
10493 to use @kbd{M-<TAB>} for completion.
10495 The export keywords available for every back-end, and their equivalent global
10496 variables, include:
10498 @table @samp
10499 @item AUTHOR
10500 @vindex user-full-name
10501 The document author (@code{user-full-name}).
10503 @item CREATOR
10504 @vindex org-export-creator-string
10505 Entity responsible for output generation (@code{org-export-creator-string}).
10507 @item DATE
10508 @vindex org-export-date-timestamp-format
10509 A date or a time-stamp@footnote{The variable
10510 @code{org-export-date-timestamp-format} defines how this time-stamp will be
10511 exported.}.
10513 @item DESCRIPTION
10514 The document description.  Back-ends handle it as they see fit (e.g., for the
10515 XHTML meta tag), if at all.  You can use several such keywords for long
10516 descriptions.
10518 @item EMAIL
10519 @vindex user-mail-address
10520 The email address (@code{user-mail-address}).
10522 @item KEYWORDS
10523 The keywords defining the contents of the document.  Back-ends handle it as
10524 they see fit (e.g., for the XHTML meta tag), if at all.  You can use several
10525 such keywords if the list is long.
10527 @item LANGUAGE
10528 @vindex org-export-default-language
10529 The language used for translating some strings
10530 (@code{org-export-default-language}).  E.g., @samp{#+LANGUAGE: fr} will tell
10531 Org to translate @emph{File} (english) into @emph{Fichier} (french) in the
10532 clocktable.
10534 @item SELECT_TAGS
10535 @vindex org-export-select-tags
10536 The tags that select a tree for export (@code{org-export-select-tags}).  The
10537 default value is @code{:export:}.  Within a subtree tagged with
10538 @code{:export:}, you can still exclude entries with @code{:noexport:} (see
10539 below).  When headlines are selectively exported with @code{:export:}
10540 anywhere in a file, text before the first headline is ignored.
10542 @item EXCLUDE_TAGS
10543 The tags that exclude a tree from export (@code{org-export-exclude-tags}).
10544 The default value is @code{:noexport:}.  Entries with the @code{:noexport:}
10545 tag will be unconditionally excluded from the export, even if they have an
10546 @code{:export:} tag.
10548 @item TITLE
10549 The title to be shown (otherwise derived from buffer's name).  You can use
10550 several such keywords for long titles.
10551 @end table
10553 The @code{#+OPTIONS} keyword is a compact@footnote{If you want to configure
10554 many options this way, you can use several @code{#+OPTIONS} lines.} form that
10555 recognizes the following arguments:
10557 @table @code
10558 @item ':
10559 @vindex org-export-with-smart-quotes
10560 Toggle smart quotes (@code{org-export-with-smart-quotes}).
10562 @item *:
10563 Toggle emphasized text (@code{org-export-with-emphasize}).
10565 @item -:
10566 @vindex org-export-with-special-strings
10567 Toggle conversion of special strings
10568 (@code{org-export-with-special-strings}).
10570 @item ::
10571 @vindex org-export-with-fixed-width
10572 Toggle fixed-width sections
10573 (@code{org-export-with-fixed-width}).
10575 @item <:
10576 @vindex org-export-with-timestamps
10577 Toggle inclusion of any time/date active/inactive stamps
10578 (@code{org-export-with-timestamps}).
10580 @item :
10581 @vindex org-export-preserve-breaks
10582 Toggle line-break-preservation (@code{org-export-preserve-breaks}).
10584 @item ^:
10585 @vindex org-export-with-sub-superscripts
10586 Toggle @TeX{}-like syntax for sub- and superscripts.  If you write "^:@{@}",
10587 @samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as
10588 it is (@code{org-export-with-sub-superscripts}).
10590 @item arch:
10591 @vindex org-export-with-archived-trees
10592 Configure export of archived trees.  Can be set to @code{headline} to only
10593 process the headline, skipping its contents
10594 (@code{org-export-with-archived-trees}).
10596 @item author:
10597 @vindex org-export-with-author
10598 Toggle inclusion of author name into exported file
10599 (@code{org-export-with-author}).
10601 @item c:
10602 @vindex org-export-with-clocks
10603 Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}).
10605 @item creator:
10606 @vindex org-export-with-creator
10607 Configure inclusion of creator info into exported file.  It may be set to
10608 @code{comment} (@code{org-export-with-creator}).
10610 @item d:
10611 @vindex org-export-with-drawers
10612 Toggle inclusion of drawers, or list drawers to include
10613 (@code{org-export-with-drawers}).
10615 @item e:
10616 @vindex org-export-with-entities
10617 Toggle inclusion of entities (@code{org-export-with-entities}).
10619 @item email:
10620 @vindex org-export-with-email
10621 Toggle inclusion of the author's e-mail into exported file
10622 (@code{org-export-with-email}).
10624 @item f:
10625 @vindex org-export-with-footnotes
10626 Toggle the inclusion of footnotes (@code{org-export-with-footnotes}).
10628 @item H:
10629 @vindex org-export-headline-levels
10630 Set the number of headline levels for export
10631 (@code{org-export-headline-levels}).  Below that level, headlines are treated
10632 differently.  In most back-ends, they become list items.
10634 @item inline:
10635 @vindex org-export-with-inlinetasks
10636 Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
10638 @item num:
10639 @vindex org-export-with-section-numbers
10640 Toggle section-numbers (@code{org-export-with-section-numbers}).  It can also
10641 be set to a number @samp{n}, so only headlines at that level or above will be
10642 numbered.
10644 @item p:
10645 @vindex org-export-with-planning
10646 Toggle export of planning information (@code{org-export-with-planning}).
10647 ``Planning information'' is the line containing the @code{SCHEDULED:}, the
10648 @code{DEADLINE:} or the @code{CLOSED:} cookies or a combination of them.
10650 @item pri:
10651 @vindex org-export-with-priority
10652 Toggle inclusion of priority cookies (@code{org-export-with-priority}).
10654 @item stat:
10655 @vindex org-export-with-statistics-cookies
10656 Toggle inclusion of statistics cookies
10657 (@code{org-export-with-statistics-cookies}).
10659 @item tags:
10660 @vindex org-export-with-tags
10661 Toggle inclusion of tags, may also be @code{not-in-toc}
10662 (@code{org-export-with-tags}).
10664 @item tasks:
10665 @vindex org-export-with-tasks
10666 Toggle inclusion of tasks (TODO items), can be @code{nil} to remove all
10667 tasks, @code{todo} to remove DONE tasks, or a list of keywords to keep
10668 (@code{org-export-with-tasks}).
10670 @item tex:
10671 @vindex org-export-with-latex
10672 Configure export of @LaTeX{} fragments and environments.  It may be set to
10673 @code{verbatim} (@code{org-export-with-latex}).
10675 @item timestamp:
10676 @vindex org-export-time-stamp-file
10677 Toggle inclusion of the creation time into exported file
10678 (@code{org-export-time-stamp-file}).
10680 @item toc:
10681 @vindex org-export-with-toc
10682 Toggle inclusion of the table of contents, or set the level limit
10683 (@code{org-export-with-toc}).
10685 @item todo:
10686 @vindex org-export-with-todo-keywords
10687 Toggle inclusion of TODO keywords into exported text
10688 (@code{org-export-with-todo-keywords}).
10690 @item |:
10691 @vindex org-export-with-tables
10692 Toggle inclusion of tables (@code{org-export-with-tables}).
10693 @end table
10695 @cindex property, EXPORT_FILE_NAME
10696 When exporting only a subtree, each of the previous keywords@footnote{With
10697 the exception of @samp{SETUPFILE}.} can be overridden locally by special node
10698 properties.  These begin with @samp{EXPORT_}, followed by the name of the
10699 keyword they supplant.  For example, @samp{DATE} and @samp{OPTIONS} keywords
10700 become, respectively, @samp{EXPORT_DATE} and @samp{EXPORT_OPTIONS}
10701 properties.  Subtree export also supports the self-explicit
10702 @samp{EXPORT_FILE_NAME} property@footnote{There is no buffer-wide equivalent
10703 for this property.  The file name in this case is derived from the file
10704 associated to the buffer, if possible, or asked to the user otherwise.}.
10706 @cindex #+BIND
10707 @vindex org-export-allow-bind-keywords
10708 If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables
10709 can become buffer-local during export by using the BIND keyword.  Its syntax
10710 is @samp{#+BIND: variable value}.  This is particularly useful for in-buffer
10711 settings that cannot be changed using specific keywords.
10713 @node ASCII/Latin-1/UTF-8 export, Beamer export, Export settings, Exporting
10714 @section ASCII/Latin-1/UTF-8 export
10715 @cindex ASCII export
10716 @cindex Latin-1 export
10717 @cindex UTF-8 export
10719 ASCII export produces a simple and very readable version of an Org mode
10720 file, containing only plain ASCII@.  Latin-1 and UTF-8 export augment the file
10721 with special characters and symbols available in these encodings.
10723 @vindex org-ascii-links-to-notes
10724 Links are exported in a footnote-like style, with the descriptive part in the
10725 text and the link in a note before the next heading.  See the variable
10726 @code{org-ascii-links-to-notes} for details and other options.
10728 @subheading ASCII export commands
10730 @table @kbd
10731 @orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii}
10732 Export as an ASCII file.  For an Org file, @file{myfile.org}, the ASCII file
10733 will be @file{myfile.txt}.  The file will be overwritten without warning.
10734 When the original file is @file{myfile.txt}, the resulting file becomes
10735 @file{myfile.txt.txt} in order to prevent data loss.
10736 @orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii}
10737 Export to a temporary buffer.  Do not create a file.
10738 @end table
10740 @subheading Header and sectioning structure
10742 In the exported version, the first three outline levels become headlines,
10743 defining a general document structure.  Additional levels are exported as
10744 lists.  The transition can also occur at a different level (@pxref{Export
10745 settings}).
10747 @subheading Quoting ASCII text
10749 You can insert text that will only appear when using @code{ASCII} back-end
10750 with the following constructs:
10752 @cindex #+ASCII
10753 @cindex #+BEGIN_ASCII
10754 @example
10755 Text @@@@ascii:and additional text@@@@ within a paragraph.
10757 #+ASCII: Some text
10759 #+BEGIN_ASCII
10760 All lines in this block will appear only when using this back-end.
10761 #+END_ASCII
10762 @end example
10764 @subheading ASCII specific attributes
10765 @cindex #+ATTR_ASCII
10766 @cindex horizontal rules, in ASCII export
10768 @code{ASCII} back-end only understands one attribute, @code{:width}, which
10769 specifies the length, in characters, of a given horizontal rule.  It must be
10770 specified using an @code{ATTR_ASCII} line, directly preceding the rule.
10772 @example
10773 #+ATTR_ASCII: :width 10
10774 -----
10775 @end example
10777 @node Beamer export, HTML export, ASCII/Latin-1/UTF-8 export, Exporting
10778 @section Beamer export
10779 @cindex Beamer export
10781 The @LaTeX{} class @emph{Beamer} allows production of high quality
10782 presentations using @LaTeX{} and pdf processing.  Org mode has special
10783 support for turning an Org mode file or tree into a Beamer presentation.
10785 @subheading Beamer export commands
10787 @table @kbd
10788 @orgcmd{C-c C-e l b,org-beamer-export-to-latex}
10789 Export as a @LaTeX{} file.  For an Org file @file{myfile.org}, the @LaTeX{}
10790 file will be @file{myfile.tex}.  The file will be overwritten without
10791 warning.
10792 @orgcmd{C-c C-e l B,org-beamer-export-as-latex}
10793 Export to a temporary buffer.  Do not create a file.
10794 @orgcmd{C-c C-e l P,org-beamer-export-to-pdf}
10795 Export as @LaTeX{} and then process to PDF.
10796 @item C-c C-e l O
10797 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
10798 @end table
10800 @subheading Sectioning, Frames and Blocks
10802 Any tree with not-too-deep level nesting should in principle be exportable as
10803 a Beamer presentation.  Headlines fall into three categories: sectioning
10804 elements, frames and blocks.
10806 @itemize @minus
10807 @item
10808 @vindex org-beamer-frame-level
10809 Headlines become frames when their level is equal to
10810 @code{org-beamer-frame-level} or @code{H} value in an @code{OPTIONS} line
10811 (@pxref{Export settings}).
10813 @cindex property, BEAMER_ENV
10814 Though, if a headline in the current tree has a @code{BEAMER_ENV} property
10815 set to either to @code{frame} or @code{fullframe}, its level overrides the
10816 variable.  A @code{fullframe} is a frame with an empty (ignored) title.
10818 @item
10819 @vindex org-beamer-environments-default
10820 @vindex org-beamer-environments-extra
10821 All frame's children become @code{block} environments.  Special block types
10822 can be enforced by setting headline's @code{BEAMER_ENV} property@footnote{If
10823 this property is set, the entry will also get a @code{:B_environment:} tag to
10824 make this visible.  This tag has no semantic meaning, it is only a visual
10825 aid.} to an appropriate value (see @code{org-beamer-environments-default} for
10826 supported values and @code{org-beamer-environments-extra} for adding more).
10828 @item
10829 @cindex property, BEAMER_REF
10830 As a special case, if the @code{BEAMER_ENV} property is set to either
10831 @code{appendix}, @code{note}, @code{noteNH} or @code{againframe}, the
10832 headline will become, respectively, an appendix, a note (within frame or
10833 between frame, depending on its level), a note with its title ignored or an
10834 @code{\againframe} command.  In the latter case, a @code{BEAMER_REF} property
10835 is mandatory in order to refer to the frame being resumed, and contents are
10836 ignored.
10838 Also, a headline with an @code{ignoreheading} environment will have its
10839 contents only inserted in the output.  This special value is useful to have
10840 data between frames, or to properly close a @code{column} environment.
10841 @end itemize
10843 @cindex property, BEAMER_ACT
10844 @cindex property, BEAMER_OPT
10845 Headlines also support @code{BEAMER_ACT} and @code{BEAMER_OPT} properties.
10846 The former is translated as an overlay/action specification, or a default
10847 overlay specification when enclosed within square brackets.  The latter
10848 specifies options@footnote{The @code{fragile} option is added automatically
10849 if it contains code that requires a verbatim environment, though.} for the
10850 current frame or block.  The export back-end will automatically wrap
10851 properties within angular or square brackets when appropriate.
10853 @cindex property, BEAMER_COL
10854 Moreover, headlines handle the @code{BEAMER_COL} property.  Its value should
10855 be a decimal number representing the width of the column as a fraction of the
10856 total text width.  If the headline has no specific environment, its title
10857 will be ignored and its contents will fill the column created.  Otherwise,
10858 the block will fill the whole column and the title will be preserved.  Two
10859 contiguous headlines with a non-@code{nil} @code{BEAMER_COL} value share the same
10860 @code{columns} @LaTeX{} environment.  It will end before the next headline
10861 without such a property.  This environment is generated automatically.
10862 Although, it can also be explicitly created, with a special @code{columns}
10863 value for @code{BEAMER_ENV} property (if it needs to be set up with some
10864 specific options, for example).
10866 @subheading Beamer specific syntax
10868 Beamer back-end is an extension of @LaTeX{} back-end.  As such, all @LaTeX{}
10869 specific syntax (e.g., @samp{#+LATEX:} or @samp{#+ATTR_LATEX:}) is
10870 recognized.  See @ref{@LaTeX{} and PDF export} for more information.
10872 @cindex #+BEAMER_THEME
10873 @cindex #+BEAMER_COLOR_THEME
10874 @cindex #+BEAMER_FONT_THEME
10875 @cindex #+BEAMER_INNER_THEME
10876 @cindex #+BEAMER_OUTER_THEME
10877 Beamer export introduces a number of keywords to insert code in the
10878 document's header.  Four control appearance of the presentation:
10879 @code{#+BEAMER_THEME}, @code{#+BEAMER_COLOR_THEME},
10880 @code{#+BEAMER_FONT_THEME}, @code{#+BEAMER_INNER_THEME} and
10881 @code{#+BEAMER_OUTER_THEME}.  All of them accept optional arguments
10882 within square brackets.  The last one, @code{#+BEAMER_HEADER}, is more
10883 generic and allows you to append any line of code in the header.
10885 @example
10886 #+BEAMER_THEME: Rochester [height=20pt]
10887 #+BEAMER_COLOR_THEME: spruce
10888 @end example
10890 Table of contents generated from @code{toc:t} @code{OPTION} keyword are
10891 wrapped within a @code{frame} environment.  Those generated from a @code{TOC}
10892 keyword (@pxref{Table of contents}) are not.  In that case, it is also
10893 possible to specify options, enclosed within square brackets.
10895 @example
10896 #+TOC: headlines [currentsection]
10897 @end example
10899 Beamer specific code can be inserted with the following constructs:
10901 @cindex #+BEAMER
10902 @cindex #+BEGIN_BEAMER
10903 @example
10904 #+BEAMER: \pause
10906 #+BEGIN_BEAMER
10907 All lines in this block will appear only when using this back-end.
10908 #+END_BEAMER
10910 Text @@@@beamer:some code@@@@ within a paragraph.
10911 @end example
10913 In particular, this last example can be used to add overlay specifications to
10914 objects whose type is among @code{bold}, @code{item}, @code{link},
10915 @code{radio-target} and @code{target}, when the value is enclosed within
10916 angular brackets and put at the beginning the object.
10918 @example
10919 A *@@@@beamer:<2->@@@@useful* feature
10920 @end example
10922 @cindex #+ATTR_BEAMER
10923 Eventually, every plain list has support for @code{:environment},
10924 @code{:overlay} and @code{:options} attributes through
10925 @code{ATTR_BEAMER} affiliated keyword.  The first one allows the use
10926 of a different environment, the second sets overlay specifications and
10927 the last one inserts optional arguments in current list environment.
10929 @example
10930 #+ATTR_BEAMER: :overlay +-
10931 - item 1
10932 - item 2
10933 @end example
10935 @subheading Editing support
10937 You can turn on a special minor mode @code{org-beamer-mode} for faster
10938 editing with:
10940 @example
10941 #+STARTUP: beamer
10942 @end example
10944 @table @kbd
10945 @orgcmd{C-c C-b,org-beamer-select-environment}
10946 In @code{org-beamer-mode}, this key offers fast selection of a Beamer
10947 environment or the @code{BEAMER_COL} property.
10948 @end table
10950 Also, a template for useful in-buffer settings or properties can be inserted
10951 into the buffer with @kbd{M-x org-beamer-insert-options-template}.  Among
10952 other things, this will install a column view format which is very handy for
10953 editing special properties used by Beamer.
10955 @subheading An example
10957 Here is a simple example Org document that is intended for Beamer export.
10959 @smallexample
10960 #+TITLE: Example Presentation
10961 #+AUTHOR: Carsten Dominik
10962 #+OPTIONS: H:2
10963 #+LATEX_CLASS: beamer
10964 #+LATEX_CLASS_OPTIONS: [presentation]
10965 #+BEAMER_THEME: Madrid
10966 #+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) %8BEAMER_OPT(Opt)
10968 * This is the first structural section
10970 ** Frame 1
10971 *** Thanks to Eric Fraga                                           :B_block:BMCOL:
10972     :PROPERTIES:
10973     :BEAMER_COL: 0.48
10974     :BEAMER_ENV: block
10975     :END:
10976     for the first viable Beamer setup in Org
10977 *** Thanks to everyone else                                        :B_block:BMCOL:
10978     :PROPERTIES:
10979     :BEAMER_COL: 0.48
10980     :BEAMER_ACT: <2->
10981     :BEAMER_ENV: block
10982     :END:
10983     for contributing to the discussion
10984 **** This will be formatted as a beamer note                              :B_note:
10985      :PROPERTIES:
10986      :BEAMER_env: note
10987      :END:
10988 ** Frame 2 (where we will not use columns)
10989 *** Request
10990     Please test this stuff!
10991 @end smallexample
10993 @node HTML export, @LaTeX{} and PDF export, Beamer export, Exporting
10994 @section HTML export
10995 @cindex HTML export
10997 Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive
10998 HTML formatting, in ways similar to John Gruber's @emph{markdown}
10999 language, but with additional support for tables.
11001 @menu
11002 * HTML Export commands::        How to invoke HTML export
11003 * HTML doctypes::               Org can export to various (X)HTML flavors
11004 * HTML preamble and postamble::  How to insert a preamble and a postamble
11005 * Quoting HTML tags::           Using direct HTML in Org mode
11006 * Links in HTML export::        How links will be interpreted and formatted
11007 * Tables in HTML export::       How to modify the formatting of tables
11008 * Images in HTML export::       How to insert figures into HTML output
11009 * Math formatting in HTML export::  Beautiful math also on the web
11010 * Text areas in HTML export::   An alternative way to show an example
11011 * CSS support::                 Changing the appearance of the output
11012 * JavaScript support::          Info and Folding in a web browser
11013 @end menu
11015 @node HTML Export commands, HTML doctypes, HTML export, HTML export
11016 @subsection HTML export commands
11018 @table @kbd
11019 @orgcmd{C-c C-e h h,org-html-export-to-html}
11020 Export as an HTML file.  For an Org file @file{myfile.org},
11021 the HTML file will be @file{myfile.html}.  The file will be overwritten
11022 without warning.
11023 @kbd{C-c C-e h o}
11024 Export as an HTML file and immediately open it with a browser.
11025 @orgcmd{C-c C-e h H,org-html-export-as-html}
11026 Export to a temporary buffer.  Do not create a file.
11027 @end table
11029 @c FIXME Exporting sublevels
11030 @c @cindex headline levels, for exporting
11031 @c In the exported version, the first 3 outline levels will become headlines,
11032 @c defining a general document structure.  Additional levels will be exported as
11033 @c itemized lists.  If you want that transition to occur at a different level,
11034 @c specify it with a numeric prefix argument.  For example,
11036 @c @example
11037 @c @kbd{C-2 C-c C-e b}
11038 @c @end example
11040 @c @noindent
11041 @c creates two levels of headings and does the rest as items.
11043 @node HTML doctypes, HTML preamble and postamble, HTML Export commands, HTML export
11044 @subsection HTML doctypes
11045 @vindex org-html-doctype
11046 @vindex org-html-doctype-alist
11048 Org can export to various (X)HTML flavors.
11050 Setting the variable @code{org-html-doctype} allows you to export to different
11051 (X)HTML variants.  The exported HTML will be adjusted according to the syntax
11052 requirements of that variant.  You can either set this variable to a doctype
11053 string directly, in which case the exporter will try to adjust the syntax
11054 automatically, or you can use a ready-made doctype.  The ready-made options
11055 are:
11057 @itemize
11058 @item
11059 ``html4-strict''
11060 @item
11061 ``html4-transitional''
11062 @item
11063 ``html4-frameset''
11064 @item
11065 ``xhtml-strict''
11066 @item
11067 ``xhtml-transitional''
11068 @item
11069 ``xhtml-frameset''
11070 @item
11071 ``xhtml-11''
11072 @item
11073 ``html5''
11074 @item
11075 ``xhtml5''
11076 @end itemize
11078 See the variable @code{org-html-doctype-alist} for details.  The default is
11079 ``xhtml-strict''.
11081 @subsubheading Fancy HTML5 export
11082 @vindex org-html-html5-fancy
11083 @vindex org-html-html5-elements
11085 HTML5 introduces several new element types.  By default, Org will not make
11086 use of these element types, but you can set @code{org-html-html5-fancy} to
11087 @code{t} (or set @code{html5-fancy} item in an @code{OPTIONS} line), to
11088 enable a few new block-level elements.  These are created using arbitrary
11089 #+BEGIN and #+END blocks. For instance:
11091 @example
11092 #+BEGIN_ASIDE
11093 Lorem ipsum
11094 #+END_ASIDE
11095 @end example
11097 Will export to:
11099 @example
11100 <aside>
11101   <p>Lorem ipsum</p>
11102 </aside>
11103 @end example
11105 While this:
11107 @example
11108 #+ATTR_HTML: :controls controls :width 350
11109 #+BEGIN_VIDEO
11110 #+HTML: <source src="movie.mp4" type="video/mp4">
11111 #+HTML: <source src="movie.ogg" type="video/ogg">
11112 Your browser does not support the video tag.
11113 #+END_VIDEO
11114 @end example
11116 Becomes:
11118 @example
11119 <video controls="controls" width="350">
11120   <source src="movie.mp4" type="video/mp4">
11121   <source src="movie.ogg" type="video/ogg">
11122   <p>Your browser does not support the video tag.</p>
11123 </video>
11124 @end example
11126 Special blocks that do not correspond to HTML5 elements (see
11127 @code{org-html-html5-elements}) will revert to the usual behavior, i.e.,
11128 @code{#+BEGIN_LEDERHOSEN} will still export to @samp{<div class="lederhosen">}.
11130 Headlines cannot appear within special blocks.  To wrap a headline and its
11131 contents in e.g., @samp{<section>} or @samp{<article>} tags, set the
11132 @code{HTML_CONTAINER} property on the headline itself.
11134 @node HTML preamble and postamble, Quoting HTML tags, HTML doctypes, HTML export
11135 @subsection HTML preamble and postamble
11136 @vindex org-html-preamble
11137 @vindex org-html-postamble
11138 @vindex org-html-preamble-format
11139 @vindex org-html-postamble-format
11140 @vindex org-html-validation-link
11141 @vindex org-export-creator-string
11142 @vindex org-export-time-stamp-file
11144 The HTML exporter lets you define a preamble and a postamble.
11146 The default value for @code{org-html-preamble} is @code{t}, which means
11147 that the preamble is inserted depending on the relevant format string in
11148 @code{org-html-preamble-format}.
11150 Setting @code{org-html-preamble} to a string will override the default format
11151 string.  If you set it to a function, it will insert the output of the
11152 function, which must be a string.  Setting to @code{nil} will not insert any
11153 preamble.
11155 The default value for @code{org-html-postamble} is @code{'auto}, which means
11156 that the HTML exporter will look for information about the author, the email,
11157 the creator and the date, and build the postamble from these values.  Setting
11158 @code{org-html-postamble} to @code{t} will insert the postamble from the
11159 relevant format string found in @code{org-html-postamble-format}.  Setting it
11160 to @code{nil} will not insert any postamble.
11162 @node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export
11163 @subsection Quoting HTML tags
11165 Plain @samp{<} and @samp{>} are always transformed to @samp{&lt;} and
11166 @samp{&gt;} in HTML export.  If you want to include raw HTML code, which
11167 should only appear in HTML export, mark it with @samp{@@@@html:} as in
11168 @samp{@@@@html:<b>@@@@bold text@@@@html:</b>@@@@}.  For more extensive HTML
11169 that should be copied verbatim to the exported file use either
11171 @cindex #+HTML
11172 @cindex #+BEGIN_HTML
11173 @example
11174 #+HTML: Literal HTML code for export
11175 @end example
11177 @noindent or
11178 @cindex #+BEGIN_HTML
11180 @example
11181 #+BEGIN_HTML
11182 All lines between these markers are exported literally
11183 #+END_HTML
11184 @end example
11187 @node Links in HTML export, Tables in HTML export, Quoting HTML tags, HTML export
11188 @subsection Links in HTML export
11190 @cindex links, in HTML export
11191 @cindex internal links, in HTML export
11192 @cindex external links, in HTML export
11193 Internal links (@pxref{Internal links}) will continue to work in HTML@.  This
11194 includes automatic links created by radio targets (@pxref{Radio
11195 targets}).  Links to external files will still work if the target file is on
11196 the same @i{relative} path as the published Org file.  Links to other
11197 @file{.org} files will be translated into HTML links under the assumption
11198 that an HTML version also exists of the linked file, at the same relative
11199 path.  @samp{id:} links can then be used to jump to specific entries across
11200 files.  For information related to linking files while publishing them to a
11201 publishing directory see @ref{Publishing links}.
11203 If you want to specify attributes for links, you can do so using a special
11204 @code{#+ATTR_HTML} line to define attributes that will be added to the
11205 @code{<a>} or @code{<img>} tags.  Here is an example that sets @code{title}
11206 and @code{style} attributes for a link:
11208 @cindex #+ATTR_HTML
11209 @example
11210 #+ATTR_HTML: :title The Org mode homepage :style color:red;
11211 [[http://orgmode.org]]
11212 @end example
11214 @node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export
11215 @subsection Tables
11216 @cindex tables, in HTML
11217 @vindex org-html-table-default-attributes
11219 Org mode tables are exported to HTML using the table attributes defined in
11220 @code{org-html-table-default-attributes}.  The default setting makes tables
11221 without cell borders and frame.  If you would like to change this for
11222 individual tables, place something like the following before the table:
11224 @cindex #+CAPTION
11225 @cindex #+ATTR_HTML
11226 @example
11227 #+CAPTION: This is a table with lines around and between cells
11228 #+ATTR_HTML: :border 2 :rules all :frame border
11229 @end example
11231 @vindex org-html-table-row-tags
11232 You can also modify the default tags used for each row by setting
11233 @code{org-html-table-row-tags}.  See the docstring for an example on
11234 how to use this option.
11236 @node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export
11237 @subsection Images in HTML export
11239 @cindex images, inline in HTML
11240 @cindex inlining images in HTML
11241 @vindex org-html-inline-images
11242 HTML export can inline images given as links in the Org file, and
11243 it can make an image the clickable part of a link.  By
11244 default@footnote{But see the variable
11245 @code{org-html-inline-images}.}, images are inlined if a link does
11246 not have a description.  So @samp{[[file:myimg.jpg]]} will be inlined,
11247 while @samp{[[file:myimg.jpg][the image]]} will just produce a link
11248 @samp{the image} that points to the image.  If the description part
11249 itself is a @code{file:} link or a @code{http:} URL pointing to an
11250 image, this image will be inlined and activated so that clicking on the
11251 image will activate the link.  For example, to include a thumbnail that
11252 will link to a high resolution version of the image, you could use:
11254 @example
11255 [[file:highres.jpg][file:thumb.jpg]]
11256 @end example
11258 If you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}.
11259 In the example below we specify the @code{alt} and @code{title} attributes to
11260 support text viewers and accessibility, and align it to the right.
11262 @cindex #+CAPTION
11263 @cindex #+ATTR_HTML
11264 @example
11265 #+CAPTION: A black cat stalking a spider
11266 #+ATTR_HTML: :alt cat/spider image :title Action! :align right
11267 [[./img/a.jpg]]
11268 @end example
11270 @noindent
11271 You could use @code{http} addresses just as well.
11273 @node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export
11274 @subsection Math formatting in HTML export
11275 @cindex MathJax
11276 @cindex dvipng
11277 @cindex imagemagick
11279 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two
11280 different ways on HTML pages.  The default is to use the
11281 @uref{http://www.mathjax.org, MathJax system} which should work out of the
11282 box with Org mode installation because @uref{http://orgmode.org} serves
11283 @file{MathJax} for Org mode users for small applications and for testing
11284 purposes.  @b{If you plan to use this regularly or on pages with significant
11285 page views, you should install@footnote{Installation instructions can be
11286 found on the MathJax website, see
11287 @uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on
11288 your own server in order to limit the load of our server.}  To configure
11289 @file{MathJax}, use the variable @code{org-html-mathjax-options} or
11290 insert something like the following into the buffer:
11292 @example
11293 #+HTML_MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
11294 @end example
11296 @noindent See the docstring of the variable
11297 @code{org-html-mathjax-options} for the meaning of the parameters in
11298 this line.
11300 If you prefer, you can also request that @LaTeX{} fragments are processed
11301 into small images that will be inserted into the browser page.  Before the
11302 availability of MathJax, this was the default method for Org files.  This
11303 method requires that the @file{dvipng} program or @file{imagemagick} suite is
11304 available on your system.  You can still get this processing with
11306 @example
11307 #+OPTIONS: tex:dvipng
11308 @end example
11312 @example
11313 #+OPTIONS: tex:imagemagick
11314 @end example
11316 @node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export
11317 @subsection Text areas in HTML export
11319 @cindex text areas, in HTML
11320 An alternative way to publish literal code examples in HTML is to use text
11321 areas, where the example can even be edited before pasting it into an
11322 application.  It is triggered by @code{:textarea} attribute at an
11323 @code{example} or @code{src} block.
11325 You may also use @code{:height} and @code{:width} attributes to specify the
11326 height and width of the text area, which default to the number of lines in
11327 the example, and 80, respectively.  For example
11329 @example
11330 #+ATTR_HTML: :textarea t :width 40
11331 #+BEGIN_EXAMPLE
11332   (defun org-xor (a b)
11333      "Exclusive or."
11334      (if a (not b) b))
11335 #+END_EXAMPLE
11336 @end example
11339 @node CSS support, JavaScript support, Text areas in HTML export, HTML export
11340 @subsection CSS support
11341 @cindex CSS, for HTML export
11342 @cindex HTML export, CSS
11344 @vindex org-html-todo-kwd-class-prefix
11345 @vindex org-html-tag-class-prefix
11346 You can modify the CSS style definitions for the exported file.  The HTML
11347 exporter assigns the following special CSS classes@footnote{If the classes on
11348 TODO keywords and tags lead to conflicts, use the variables
11349 @code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to
11350 make them unique.} to appropriate parts of the document---your style
11351 specifications may change these, in addition to any of the standard classes
11352 like for headlines, tables, etc.
11353 @example
11354 p.author            @r{author information, including email}
11355 p.date              @r{publishing date}
11356 p.creator           @r{creator info, about org mode version}
11357 .title              @r{document title}
11358 .todo               @r{TODO keywords, all not-done states}
11359 .done               @r{the DONE keywords, all states that count as done}
11360 .WAITING            @r{each TODO keyword also uses a class named after itself}
11361 .timestamp          @r{timestamp}
11362 .timestamp-kwd      @r{keyword associated with a timestamp, like SCHEDULED}
11363 .timestamp-wrapper  @r{span around keyword plus timestamp}
11364 .tag                @r{tag in a headline}
11365 ._HOME              @r{each tag uses itself as a class, "@@" replaced by "_"}
11366 .target             @r{target for links}
11367 .linenr             @r{the line number in a code example}
11368 .code-highlighted   @r{for highlighting referenced code lines}
11369 div.outline-N       @r{div for outline level N (headline plus text))}
11370 div.outline-text-N  @r{extra div for text at outline level N}
11371 .section-number-N   @r{section number in headlines, different for each level}
11372 .figure-number      @r{label like "Figure 1:"}
11373 .table-number       @r{label like "Table 1:"}
11374 .listing-number     @r{label like "Listing 1:"}
11375 div.figure          @r{how to format an inlined image}
11376 pre.src             @r{formatted source code}
11377 pre.example         @r{normal example}
11378 p.verse             @r{verse paragraph}
11379 div.footnotes       @r{footnote section headline}
11380 p.footnote          @r{footnote definition paragraph, containing a footnote}
11381 .footref            @r{a footnote reference number (always a <sup>)}
11382 .footnum            @r{footnote number in footnote definition (always <sup>)}
11383 @end example
11385 @vindex org-html-style-default
11386 @vindex org-html-head-include-default-style
11387 @vindex org-html-head
11388 @vindex org-html-head-extra
11389 @cindex #+HTML_INCLUDE_STYLE
11390 Each exported file contains a compact default style that defines these
11391 classes in a basic way@footnote{This style is defined in the constant
11392 @code{org-html-style-default}, which you should not modify.  To turn
11393 inclusion of these defaults off, customize
11394 @code{org-html-head-include-default-style} or set @code{html-style} to
11395 @code{nil} in an @code{OPTIONS} line.}.  You may overwrite these settings, or
11396 add to them by using the variables @code{org-html-head} and
11397 @code{org-html-head-extra}.  You can override the global values of these
11398 variables for each file by using these keywords:
11400 @cindex #+HTML_HEAD
11401 @cindex #+HTML_HEAD_EXTRA
11402 @example
11403 #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
11404 #+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
11405 @end example
11407 @noindent
11408 For longer style definitions, you can use several such lines.  You could also
11409 directly write a @code{<style>} @code{</style>} section in this way, without
11410 referring to an external file.
11412 In order to add styles to a subtree, use the @code{:HTML_CONTAINER_CLASS:}
11413 property to assign a class to the tree.  In order to specify CSS styles for a
11414 particular headline, you can use the id specified in a @code{:CUSTOM_ID:}
11415 property.
11417 @c FIXME: More about header and footer styles
11418 @c FIXME: Talk about links and targets.
11420 @node JavaScript support,  , CSS support, HTML export
11421 @subsection JavaScript supported display of web pages
11423 @cindex Rose, Sebastian
11424 Sebastian Rose has written a JavaScript program especially designed to
11425 enhance the web viewing experience of HTML files created with Org.  This
11426 program allows you to view large files in two different ways.  The first one
11427 is an @emph{Info}-like mode where each section is displayed separately and
11428 navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys
11429 as well, press @kbd{?} for an overview of the available keys).  The second
11430 view type is a @emph{folding} view much like Org provides inside Emacs.  The
11431 script is available at @url{http://orgmode.org/org-info.js} and you can find
11432 the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}.
11433 We host the script at our site, but if you use it a lot, you might not want
11434 to be dependent on @url{http://orgmode.org} and prefer to install a local
11435 copy on your own web server.
11437 All it then takes to use this program is adding a single line to the Org
11438 file:
11440 @cindex #+INFOJS_OPT
11441 @example
11442 #+INFOJS_OPT: view:info toc:nil
11443 @end example
11445 @noindent
11446 If this line is found, the HTML header will automatically contain the code
11447 needed to invoke the script.  Using the line above, you can set the following
11448 viewing options:
11450 @example
11451 path:    @r{The path to the script.  The default is to grab the script from}
11452          @r{@url{http://orgmode.org/org-info.js}, but you might want to have}
11453          @r{a local copy and use a path like @samp{../scripts/org-info.js}.}
11454 view:    @r{Initial view when the website is first shown.  Possible values are:}
11455          info      @r{Info-like interface with one section per page.}
11456          overview  @r{Folding interface, initially showing only top-level.}
11457          content   @r{Folding interface, starting with all headlines visible.}
11458          showall   @r{Folding interface, all headlines and text visible.}
11459 sdepth:  @r{Maximum headline level that will still become an independent}
11460          @r{section for info and folding modes.  The default is taken from}
11461          @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).}
11462          @r{If this is smaller than in @code{org-export-headline-levels}, each}
11463          @r{info/folding section can still contain child headlines.}
11464 toc:     @r{Should the table of contents @emph{initially} be visible?}
11465          @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}
11466 tdepth:  @r{The depth of the table of contents.  The defaults are taken from}
11467          @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}
11468 ftoc:    @r{Does the CSS of the page specify a fixed position for the "toc"?}
11469          @r{If yes, the toc will never be displayed as a section.}
11470 ltoc:    @r{Should there be short contents (children) in each section?}
11471          @r{Make this @code{above} if the section should be above initial text.}
11472 mouse:   @r{Headings are highlighted when the mouse is over them.  Should be}
11473          @r{@samp{underline} (default) or a background color like @samp{#cccccc}.}
11474 buttons: @r{Should view-toggle buttons be everywhere?  When @code{nil} (the}
11475          @r{default), only one such button will be present.}
11476 @end example
11477 @noindent
11478 @vindex org-html-infojs-options
11479 @vindex org-html-use-infojs
11480 You can choose default values for these options by customizing the variable
11481 @code{org-html-infojs-options}.  If you always want to apply the script to your
11482 pages, configure the variable @code{org-html-use-infojs}.
11484 @node @LaTeX{} and PDF export, Markdown export, HTML export, Exporting
11485 @section @LaTeX{} and PDF export
11486 @cindex @LaTeX{} export
11487 @cindex PDF export
11489 @LaTeX{} export can produce an arbitrarily complex LaTeX document of any
11490 standard or custom document class.  With further processing@footnote{The
11491 default @LaTeX{} output is designed for processing with @code{pdftex} or
11492 @LaTeX{}.  It includes packages that are not compatible with @code{xetex} and
11493 possibly @code{luatex}.  The @LaTeX{} exporter can be configured to support
11494 alternative TeX engines, see the options
11495 @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.},
11496 which the @LaTeX{} exporter is able to control, this back-end is able to
11497 produce PDF output.  Because the @LaTeX{} exporter can be configured to use
11498 the @code{hyperref} package, the default setup produces fully-linked PDF
11499 output.
11501 As in @LaTeX{}, blank lines are meaningful for this back-end: a paragraph
11502 will not be started if two contiguous syntactical elements are not separated
11503 by an empty line.
11505 This back-end also offers enhanced support for footnotes.  Thus, it handles
11506 nested footnotes, footnotes in tables and footnotes in a list item's
11507 description.
11509 @menu
11510 * @LaTeX{} export commands::    How to export to LaTeX and PDF
11511 * Header and sectioning::       Setting up the export file structure
11512 * Quoting @LaTeX{} code::       Incorporating literal @LaTeX{} code
11513 * @LaTeX{} specific attributes::  Controlling @LaTeX{} output
11514 @end menu
11516 @node @LaTeX{} export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export
11517 @subsection @LaTeX{} export commands
11519 @table @kbd
11520 @orgcmd{C-c C-e l l,org-latex-export-to-latex}
11521 Export as a @LaTeX{} file.  For an Org file @file{myfile.org}, the @LaTeX{}
11522 file will be @file{myfile.tex}.  The file will be overwritten without
11523 warning.
11524 @orgcmd{C-c C-e l L,org-latex-export-as-latex}
11525 Export to a temporary buffer.  Do not create a file.
11526 @orgcmd{C-c C-e l p,org-latex-export-to-pdf}
11527 Export as @LaTeX{} and then process to PDF.
11528 @item C-c C-e l o
11529 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
11530 @end table
11532 @node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{} export commands, @LaTeX{} and PDF export
11533 @subsection Header and sectioning structure
11534 @cindex @LaTeX{} class
11535 @cindex @LaTeX{} sectioning structure
11536 @cindex @LaTeX{} header
11537 @cindex header, for @LaTeX{} files
11538 @cindex sectioning structure, for @LaTeX{} export
11540 By default, the first three outline levels become headlines, defining a
11541 general document structure.  Additional levels are exported as @code{itemize}
11542 or @code{enumerate} lists.  The transition can also occur at a different
11543 level (@pxref{Export settings}).
11545 By default, the @LaTeX{} output uses the class @code{article}.
11547 @vindex org-latex-default-class
11548 @vindex org-latex-classes
11549 @vindex org-latex-default-packages-alist
11550 @vindex org-latex-packages-alist
11551 You can change this globally by setting a different value for
11552 @code{org-latex-default-class} or locally by adding an option like
11553 @code{#+LATEX_CLASS: myclass} in your file, or with
11554 a @code{EXPORT_LATEX_CLASS} property that applies when exporting a region
11555 containing only this (sub)tree.  The class must be listed in
11556 @code{org-latex-classes}.  This variable defines a header template for each
11557 class@footnote{Into which the values of
11558 @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}
11559 are spliced.}, and allows you to define the sectioning structure for each
11560 class.  You can also define your own classes there.
11562 @cindex #+LATEX_CLASS
11563 @cindex #+LATEX_CLASS_OPTIONS
11564 @cindex property, EXPORT_LATEX_CLASS
11565 @cindex property, EXPORT_LATEX_CLASS_OPTIONS
11566 The @code{LATEX_CLASS_OPTIONS} keyword or @code{EXPORT_LATEX_CLASS_OPTIONS}
11567 property can specify the options for the @code{\documentclass} macro.  These
11568 options have to be provided, as expected by @LaTeX{}, within square brackets.
11570 @cindex #+LATEX_HEADER
11571 @cindex #+LATEX_HEADER_EXTRA
11572 You can also use the @code{LATEX_HEADER} and
11573 @code{LATEX_HEADER_EXTRA}@footnote{Unlike @code{LATEX_HEADER}, contents
11574 from @code{LATEX_HEADER_EXTRA} keywords will not be loaded when previewing
11575 @LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).} keywords in order
11576 to add lines to the header.  See the docstring of @code{org-latex-classes} for
11577 more information.
11579 An example is shown below.
11581 @example
11582 #+LATEX_CLASS: article
11583 #+LATEX_CLASS_OPTIONS: [a4paper]
11584 #+LATEX_HEADER: \usepackage@{xyz@}
11586 * Headline 1
11587   some text
11588 @end example
11590 @node Quoting @LaTeX{} code, @LaTeX{} specific attributes, Header and sectioning, @LaTeX{} and PDF export
11591 @subsection Quoting @LaTeX{} code
11593 Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly
11594 inserted into the @LaTeX{} file.  Furthermore, you can add special code that
11595 should only be present in @LaTeX{} export with the following constructs:
11597 @cindex #+LATEX
11598 @cindex #+BEGIN_LATEX
11599 @example
11600 Code within @@@@latex:some code@@@@ a paragraph.
11602 #+LATEX: Literal @LaTeX{} code for export
11604 #+BEGIN_LATEX
11605 All lines between these markers are exported literally
11606 #+END_LATEX
11607 @end example
11609 @node @LaTeX{} specific attributes,  , Quoting @LaTeX{} code, @LaTeX{} and PDF export
11610 @subsection @LaTeX{} specific attributes
11611 @cindex #+ATTR_LATEX
11613 @LaTeX{} understands attributes specified in an @code{ATTR_LATEX} line.  They
11614 affect tables, images, plain lists, special blocks and source blocks.
11616 @subsubheading Tables in @LaTeX{} export
11617 @cindex tables, in @LaTeX{} export
11619 For @LaTeX{} export of a table, you can specify a label and a caption
11620 (@pxref{Images and tables}).  You can also use attributes to control table
11621 layout and contents.  Valid @LaTeX{} attributes include:
11623 @table @code
11624 @item :mode
11625 @vindex org-latex-default-table-mode
11626 Nature of table's contents.  It can be set to @code{table}, @code{math},
11627 @code{inline-math} or @code{verbatim}.  In particular, when in @code{math} or
11628 @code{inline-math} mode, every cell is exported as-is, horizontal rules are
11629 ignored and the table will be wrapped in a math environment.  Also,
11630 contiguous tables sharing the same math mode will be wrapped within the same
11631 environment.  Default mode is determined in
11632 @code{org-latex-default-table-mode}.
11633 @item :environment
11634 @vindex org-latex-default-table-environment
11635 Environment used for the table.  It can be set to any @LaTeX{} table
11636 environment, like @code{tabularx}@footnote{Requires adding the
11637 @code{tabularx} package to @code{org-latex-packages-alist}.},
11638 @code{longtable}, @code{array}, @code{tabu}@footnote{Requires adding the
11639 @code{tabu} package to @code{org-latex-packages-alist}.},
11640 @code{bmatrix}@enddots{} It defaults to
11641 @code{org-latex-default-table-environment} value.
11642 @item :caption
11643 @code{#+CAPTION} keyword is the simplest way to set a caption for a table
11644 (@pxref{Images and tables}).  If you need more advanced commands for that
11645 task, you can use @code{:caption} attribute instead.  Its value should be raw
11646 @LaTeX{} code.  It has precedence over @code{#+CAPTION}.
11647 @item :float
11648 @itemx :placement
11649 Float environment for the table.  Possible values are @code{sidewaystable},
11650 @code{multicolumn}, @code{t} and @code{nil}.  When unspecified, a table with
11651 a caption will have a @code{table} environment.  Moreover, @code{:placement}
11652 attribute can specify the positioning of the float.
11653 @item :align
11654 @itemx :font
11655 @itemx :width
11656 Set, respectively, the alignment string of the table, its font size and its
11657 width.  They only apply on regular tables.
11658 @item :spread
11659 Boolean specific to the @code{tabu} and @code{longtabu} environments, and
11660 only takes effect when used in conjunction with the @code{:width} attribute.
11661 When @code{:spread} is non-@code{nil}, the table will be spread or shrunk by the
11662 value of @code{:width}.
11663 @item :booktabs
11664 @itemx :center
11665 @itemx :rmlines
11666 @vindex org-latex-tables-booktabs
11667 @vindex org-latex-tables-centered
11668 They toggle, respectively, @code{booktabs} usage (assuming the package is
11669 properly loaded), table centering and removal of every horizontal rule but
11670 the first one (in a "table.el" table only).  In particular,
11671 @code{org-latex-tables-booktabs} (respectively @code{org-latex-tables-centered})
11672 activates the first (respectively second) attribute globally.
11673 @item :math-prefix
11674 @itemx :math-suffix
11675 @itemx :math-arguments
11676 A string that will be inserted, respectively, before the table within the
11677 math environment, after the table within the math environment, and between
11678 the macro name and the contents of the table.  The @code{:math-arguments}
11679 attribute is used for matrix macros that require more than one argument
11680 (e.g., @code{qbordermatrix}).
11681 @end table
11683 Thus, attributes can be used in a wide array of situations, like writing
11684 a table that will span over multiple pages, or a matrix product:
11686 @example
11687 #+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l
11688 | ..... | ..... |
11689 | ..... | ..... |
11691 #+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
11692 | a | b |
11693 | c | d |
11694 #+ATTR_LATEX: :mode math :environment bmatrix
11695 | 1 | 2 |
11696 | 3 | 4 |
11697 @end example
11699 In the example below, @LaTeX{} command
11700 @code{\bicaption@{HeadingA@}@{HeadingB@}} will set the caption.
11702 @example
11703 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
11704 | ..... | ..... |
11705 | ..... | ..... |
11706 @end example
11709 @subsubheading Images in @LaTeX{} export
11710 @cindex images, inline in @LaTeX{}
11711 @cindex inlining images in @LaTeX{}
11713 Images that are linked to without a description part in the link, like
11714 @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF
11715 output file resulting from @LaTeX{} processing.  Org will use an
11716 @code{\includegraphics} macro to insert the image@footnote{In the case of
11717 TikZ (@url{http://sourceforge.net/projects/pgf/}) images, it will become an
11718 @code{\input} macro wrapped within a @code{tikzpicture} environment.}.
11720 You can specify specify image width or height with, respectively,
11721 @code{:width} and @code{:height} attributes.  It is also possible to add any
11722 other option with the @code{:options} attribute, as shown in the following
11723 example:
11725 @example
11726 #+ATTR_LATEX: :width 5cm :options angle=90
11727 [[./img/sed-hr4049.pdf]]
11728 @end example
11730 If you need a specific command for the caption, use @code{:caption}
11731 attribute.  It will override standard @code{#+CAPTION} value, if any.
11733 @example
11734 #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
11735 [[./img/sed-hr4049.pdf]]
11736 @end example
11738 If you have specified a caption as described in @ref{Images and tables}, the
11739 picture will be wrapped into a @code{figure} environment and thus become
11740 a floating element.  You can also ask Org to export an image as a float
11741 without specifying caption by setting the @code{:float} attribute.  You may
11742 also set it to:
11743 @itemize @minus
11744 @item
11745 @code{t}: if you want to use the standard @samp{figure} environment.  It is
11746 used by default if you provide a caption to the image.
11747 @item
11748 @code{multicolumn}: if you wish to include an image which spans multiple
11749 columns in a page.  This will export the image wrapped in a @code{figure*}
11750 environment.
11751 @item
11752 @code{wrap}: if you would like to let text flow around the image.  It will
11753 make the figure occupy the left half of the page.
11754 @item
11755 @code{nil}: if you need to avoid any floating environment, even when
11756 a caption is provided.
11757 @end itemize
11758 @noindent
11759 To modify the placement option of any floating environment, set the
11760 @code{placement} attribute.
11762 @example
11763 #+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement @{r@}@{0.4\textwidth@}
11764 [[./img/hst.png]]
11765 @end example
11767 If the @code{:comment-include} attribute is set to a non-@code{nil} value,
11768 the @LaTeX{} @code{\includegraphics} macro will be commented out.
11770 @subsubheading Plain lists in @LaTeX{} export
11771 @cindex plain lists, in @LaTeX{} export
11773 Plain lists accept two optional attributes: @code{:environment} and
11774 @code{:options}.  The first one allows the use of a non-standard environment
11775 (e.g., @samp{inparaenum}).  The second one specifies additional arguments for
11776 that environment.
11778 @example
11779 #+ATTR_LATEX: :environment compactitem :options [$\circ$]
11780 - you need ``paralist'' package to reproduce this example.
11781 @end example
11783 @subsubheading Source blocks in @LaTeX{} export
11784 @cindex source blocks, in @LaTeX{} export
11786 In addition to syntax defined in @ref{Literal examples}, names and captions
11787 (@pxref{Images and tables}), source blocks also accept a @code{:float}
11788 attribute.  You may set it to:
11789 @itemize @minus
11790 @item
11791 @code{t}: if you want to make the source block a float.  It is the default
11792 value when a caption is provided.
11793 @item
11794 @code{multicolumn}: if you wish to include a source block which spans multiple
11795 columns in a page.
11796 @item
11797 @code{nil}: if you need to avoid any floating environment, even when a caption
11798 is provided.  It is useful for source code that may not fit in a single page.
11799 @end itemize
11801 @example
11802 #+ATTR_LATEX: :float nil
11803 #+BEGIN_SRC emacs-lisp
11804 Code that may not fit in a single page.
11805 #+END_SRC
11806 @end example
11808 @subsubheading Special blocks in @LaTeX{} export
11809 @cindex special blocks, in @LaTeX{} export
11810 @cindex abstract, in @LaTeX{} export
11811 @cindex proof, in @LaTeX{} export
11813 In @LaTeX{} back-end, special blocks become environments of the same name.
11814 Value of @code{:options} attribute will be appended as-is to that
11815 environment's opening string.  For example:
11817 @example
11818 #+BEGIN_ABSTRACT
11819 We demonstrate how to solve the Syracuse problem.
11820 #+END_ABSTRACT
11822 #+ATTR_LATEX: :options [Proof of important theorem]
11823 #+BEGIN_PROOF
11825 Therefore, any even number greater than 2 is the sum of two primes.
11826 #+END_PROOF
11827 @end example
11829 @noindent
11830 becomes
11832 @example
11833 \begin@{abstract@}
11834 We demonstrate how to solve the Syracuse problem.
11835 \end@{abstract@}
11837 \begin@{proof@}[Proof of important theorem]
11839 Therefore, any even number greater than 2 is the sum of two primes.
11840 \end@{proof@}
11841 @end example
11843 If you need to insert a specific caption command, use @code{:caption}
11844 attribute.  It will override standard @code{#+CAPTION} value, if any.  For
11845 example:
11847 @example
11848 #+ATTR_LATEX: :caption \MyCaption@{HeadingA@}
11849 #+BEGIN_PROOF
11851 #+END_PROOF
11852 @end example
11854 @subsubheading Horizontal rules
11855 @cindex horizontal rules, in @LaTeX{} export
11857 Width and thickness of a given horizontal rule can be controlled with,
11858 respectively, @code{:width} and @code{:thickness} attributes:
11860 @example
11861 #+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
11862 -----
11863 @end example
11865 @node Markdown export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting
11866 @section Markdown export
11867 @cindex Markdown export
11869 @code{md} export back-end generates Markdown syntax@footnote{Vanilla flavor,
11870 as defined at @url{http://daringfireball.net/projects/markdown/}.} for an Org
11871 mode buffer.
11873 It is built over HTML back-end: any construct not supported by Markdown
11874 syntax (e.g., tables) will be controlled and translated by @code{html}
11875 back-end (@pxref{HTML export}).
11877 @subheading Markdown export commands
11879 @table @kbd
11880 @orgcmd{C-c C-e m m,org-md-export-to-markdown}
11881 Export as a text file written in Markdown syntax.  For an Org file,
11882 @file{myfile.org}, the resulting file will be @file{myfile.md}.  The file
11883 will be overwritten without warning.
11884 @orgcmd{C-c C-e m M,org-md-export-as-markdown}
11885 Export to a temporary buffer.  Do not create a file.
11886 @item C-c C-e m o
11887 Export as a text file with Markdown syntax, then open it.
11888 @end table
11890 @subheading Header and sectioning structure
11892 @vindex org-md-headline-style
11893 Markdown export can generate both @code{atx} and @code{setext} types for
11894 headlines, according to @code{org-md-headline-style}.  The former introduces
11895 a hard limit of two levels, whereas the latter pushes it to six.  Headlines
11896 below that limit are exported as lists.  You can also set a soft limit before
11897 that one (@pxref{Export settings}).
11899 @c begin opendocument
11901 @node OpenDocument Text export, Org export, Markdown export, Exporting
11902 @section OpenDocument Text export
11903 @cindex ODT
11904 @cindex OpenDocument
11905 @cindex export, OpenDocument
11906 @cindex LibreOffice
11908 Org mode@footnote{Versions 7.8 or later} supports export to OpenDocument Text
11909 (ODT) format.  Documents created by this exporter use the
11910 @cite{OpenDocument-v1.2
11911 specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
11912 Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
11913 are compatible with LibreOffice 3.4.
11915 @menu
11916 * Pre-requisites for ODT export::  What packages ODT exporter relies on
11917 * ODT export commands::         How to invoke ODT export
11918 * Extending ODT export::        How to produce @samp{doc}, @samp{pdf} files
11919 * Applying custom styles::      How to apply custom styles to the output
11920 * Links in ODT export::         How links will be interpreted and formatted
11921 * Tables in ODT export::        How Tables are exported
11922 * Images in ODT export::        How to insert images
11923 * Math formatting in ODT export::  How @LaTeX{} fragments are formatted
11924 * Labels and captions in ODT export::  How captions are rendered
11925 * Literal examples in ODT export::  How source and example blocks are formatted
11926 * Advanced topics in ODT export::  Read this if you are a power user
11927 @end menu
11929 @node Pre-requisites for ODT export, ODT export commands, OpenDocument Text export, OpenDocument Text export
11930 @subsection Pre-requisites for ODT export
11931 @cindex zip
11932 The ODT exporter relies on the @file{zip} program to create the final
11933 output.  Check the availability of this program before proceeding further.
11935 @node ODT export commands, Extending ODT export, Pre-requisites for ODT export, OpenDocument Text export
11936 @subsection ODT export commands
11938 @subsubheading Exporting to ODT
11939 @anchor{x-export-to-odt}
11941 @cindex region, active
11942 @cindex active region
11943 @cindex transient-mark-mode
11944 @table @kbd
11945 @orgcmd{C-c C-e o o,org-odt-export-to-odt}
11946 @cindex property EXPORT_FILE_NAME
11948 Export as OpenDocument Text file.
11950 @vindex org-odt-preferred-output-format
11951 If @code{org-odt-preferred-output-format} is specified, automatically convert
11952 the exported file to that format.  @xref{x-export-to-other-formats, ,
11953 Automatically exporting to other formats}.
11955 For an Org file @file{myfile.org}, the ODT file will be
11956 @file{myfile.odt}.  The file will be overwritten without warning.  If there
11957 is an active region,@footnote{This requires @code{transient-mark-mode} to be
11958 turned on} only the region will be exported.  If the selected region is a
11959 single tree,@footnote{To select the current subtree, use @kbd{C-c @@}} the
11960 tree head will become the document title.  If the tree head entry has, or
11961 inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the
11962 export.
11964 @kbd{C-c C-e o O}
11965 Export as an OpenDocument Text file and open the resulting file.
11967 @vindex org-odt-preferred-output-format
11968 If @code{org-odt-preferred-output-format} is specified, open the converted
11969 file instead.  @xref{x-export-to-other-formats, , Automatically exporting to
11970 other formats}.
11971 @end table
11973 @node Extending ODT export, Applying custom styles, ODT export commands, OpenDocument Text export
11974 @subsection Extending ODT export
11976 The ODT exporter can interface with a variety of document
11977 converters and supports popular converters out of the box.  As a result, you
11978 can use it to export to formats like @samp{doc} or convert a document from
11979 one format (say @samp{csv}) to another format (say @samp{ods} or @samp{xls}).
11981 @cindex @file{unoconv}
11982 @cindex LibreOffice
11983 If you have a working installation of LibreOffice, a document converter is
11984 pre-configured for you and you can use it right away.  If you would like to
11985 use @file{unoconv} as your preferred converter, customize the variable
11986 @code{org-odt-convert-process} to point to @code{unoconv}.  You can
11987 also use your own favorite converter or tweak the default settings of the
11988 @file{LibreOffice} and @samp{unoconv} converters.  @xref{Configuring a
11989 document converter}.
11991 @subsubsection Automatically exporting to other formats
11992 @anchor{x-export-to-other-formats}
11994 @vindex org-odt-preferred-output-format
11995 Very often, you will find yourself exporting to ODT format, only to
11996 immediately save the exported document to other formats like @samp{doc},
11997 @samp{docx}, @samp{rtf}, @samp{pdf} etc.  In such cases, you can specify your
11998 preferred output format by customizing the variable
11999 @code{org-odt-preferred-output-format}.  This way, the export commands
12000 (@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to export to a
12001 format that is of immediate interest to you.
12003 @subsubsection Converting between document formats
12004 @anchor{x-convert-to-other-formats}
12006 There are many document converters in the wild which support conversion to
12007 and from various file formats, including, but not limited to the
12008 ODT format.  LibreOffice converter, mentioned above, is one such
12009 converter.  Once a converter is configured, you can interact with it using
12010 the following command.
12012 @vindex org-odt-convert
12013 @table @kbd
12015 @item M-x org-odt-convert RET
12016 Convert an existing document from one format to another.  With a prefix
12017 argument, also open the newly produced file.
12018 @end table
12020 @node Applying custom styles, Links in ODT export, Extending ODT export, OpenDocument Text export
12021 @subsection Applying custom styles
12022 @cindex styles, custom
12023 @cindex template, custom
12025 The ODT exporter ships with a set of OpenDocument styles
12026 (@pxref{Working with OpenDocument style files}) that ensure a well-formatted
12027 output.  These factory styles, however, may not cater to your specific
12028 tastes.  To customize the output, you can either modify the above styles
12029 files directly, or generate the required styles using an application like
12030 LibreOffice.  The latter method is suitable for expert and non-expert
12031 users alike, and is described here.
12033 @subsubsection Applying custom styles: the easy way
12035 @enumerate
12036 @item
12037 Create a sample @file{example.org} file with the below settings and export it
12038 to ODT format.
12040 @example
12041 #+OPTIONS: H:10 num:t
12042 @end example
12044 @item
12045 Open the above @file{example.odt} using LibreOffice.  Use the @file{Stylist}
12046 to locate the target styles---these typically have the @samp{Org} prefix---and
12047 modify those to your taste.  Save the modified file either as an
12048 OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file.
12050 @item
12051 @cindex #+ODT_STYLES_FILE
12052 @vindex org-odt-styles-file
12053 Customize the variable @code{org-odt-styles-file} and point it to the
12054 newly created file.  For additional configuration options
12055 @pxref{x-overriding-factory-styles,,Overriding factory styles}.
12057 If you would like to choose a style on a per-file basis, you can use the
12058 @code{#+ODT_STYLES_FILE} option.  A typical setting will look like
12060 @example
12061 #+ODT_STYLES_FILE: "/path/to/example.ott"
12062 @end example
12066 @example
12067 #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
12068 @end example
12070 @end enumerate
12072 @subsubsection Using third-party styles and templates
12074 You can use third-party styles and templates for customizing your output.
12075 This will produce the desired output only if the template provides all
12076 style names that the @samp{ODT} exporter relies on.  Unless this condition is
12077 met, the output is going to be less than satisfactory.  So it is highly
12078 recommended that you only work with templates that are directly derived from
12079 the factory settings.
12081 @node Links in ODT export, Tables in ODT export, Applying custom styles, OpenDocument Text export
12082 @subsection Links in ODT export
12083 @cindex links, in ODT export
12085 ODT exporter creates native cross-references for internal links.  It creates
12086 Internet-style links for all other links.
12088 A link with no description and destined to a regular (un-itemized) outline
12089 heading is replaced with a cross-reference and section number of the heading.
12091 A @samp{\ref@{label@}}-style reference to an image, table etc. is replaced
12092 with a cross-reference and sequence number of the labeled entity.
12093 @xref{Labels and captions in ODT export}.
12095 @node Tables in ODT export, Images in ODT export, Links in ODT export, OpenDocument Text export
12096 @subsection Tables in ODT export
12097 @cindex tables, in ODT export
12099 Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el}
12100 tables is supported.  However, export of complex @file{table.el} tables---tables
12101 that have column or row spans---is not supported.  Such tables are
12102 stripped from the exported document.
12104 By default, a table is exported with top and bottom frames and with rules
12105 separating row and column groups (@pxref{Column groups}).  Furthermore, all
12106 tables are typeset to occupy the same width.  If the table specifies
12107 alignment and relative width for its columns (@pxref{Column width and
12108 alignment}) then these are honored on export.@footnote{The column widths are
12109 interpreted as weighted ratios with the default weight being 1}
12111 @cindex #+ATTR_ODT
12112 You can control the width of the table by specifying @code{:rel-width}
12113 property using an @code{#+ATTR_ODT} line.
12115 For example, consider the following table which makes use of all the rules
12116 mentioned above.
12118 @example
12119 #+ATTR_ODT: :rel-width 50
12120 | Area/Month    |   Jan |   Feb |   Mar |   Sum |
12121 |---------------+-------+-------+-------+-------|
12122 | /             |     < |       |       |     < |
12123 | <l13>         |  <r5> |  <r5> |  <r5> |  <r6> |
12124 | North America |     1 |    21 |   926 |   948 |
12125 | Middle East   |     6 |    75 |   844 |   925 |
12126 | Asia Pacific  |     9 |    27 |   790 |   826 |
12127 |---------------+-------+-------+-------+-------|
12128 | Sum           |    16 |   123 |  2560 |  2699 |
12129 @end example
12131 On export, the table will occupy 50% of text area.  The columns will be sized
12132 (roughly) in the ratio of 13:5:5:5:6.  The first column will be left-aligned
12133 and rest of the columns will be right-aligned.  There will be vertical rules
12134 after separating the header and last columns from other columns.  There will
12135 be horizontal rules separating the header and last rows from other rows.
12137 If you are not satisfied with the above formatting options, you can create
12138 custom table styles and associate them with a table using the
12139 @code{#+ATTR_ODT} line.  @xref{Customizing tables in ODT export}.
12141 @node Images in ODT export, Math formatting in ODT export, Tables in ODT export, OpenDocument Text export
12142 @subsection Images in ODT export
12143 @cindex images, embedding in ODT
12144 @cindex embedding images in ODT
12146 @subsubheading Embedding images
12147 You can embed images within the exported document by providing a link to the
12148 desired image file with no link description.  For example, to embed
12149 @samp{img.png} do either of the following:
12151 @example
12152 [[file:img.png]]
12153 @end example
12155 @example
12156 [[./img.png]]
12157 @end example
12159 @subsubheading Embedding clickable images
12160 You can create clickable images by providing a link whose description is a
12161 link to an image file.  For example, to embed a image
12162 @file{org-mode-unicorn.png} which when clicked jumps to
12163 @uref{http://Orgmode.org} website, do the following
12165 @example
12166 [[http://orgmode.org][./org-mode-unicorn.png]]
12167 @end example
12169 @subsubheading Sizing and scaling of embedded images
12171 @cindex #+ATTR_ODT
12172 You can control the size and scale of the embedded images using the
12173 @code{#+ATTR_ODT} attribute.
12175 @cindex identify, ImageMagick
12176 @vindex org-odt-pixels-per-inch
12177 The exporter specifies the desired size of the image in the final document in
12178 units of centimeters.  In order to scale the embedded images, the exporter
12179 queries for pixel dimensions of the images using one of a) ImageMagick's
12180 @file{identify} program or b) Emacs `create-image' and `image-size'
12181 APIs@footnote{Use of @file{ImageMagick} is only desirable.  However, if you
12182 routinely produce documents that have large images or you export your Org
12183 files that has images using a Emacs batch script, then the use of
12184 @file{ImageMagick} is mandatory.}. The pixel dimensions are subsequently
12185 converted in to units of centimeters using
12186 @code{org-odt-pixels-per-inch}.  The default value of this variable is
12187 set to @code{display-pixels-per-inch}.  You can tweak this variable to
12188 achieve the best results.
12190 The examples below illustrate the various possibilities.
12192 @table @asis
12193 @item Explicitly size the image
12194 To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
12196 @example
12197 #+ATTR_ODT: :width 10 :height 10
12198 [[./img.png]]
12199 @end example
12201 @item Scale the image
12202 To embed @file{img.png} at half its size, do the following:
12204 @example
12205 #+ATTR_ODT: :scale 0.5
12206 [[./img.png]]
12207 @end example
12209 @item Scale the image to a specific width
12210 To embed @file{img.png} with a width of 10 cm while retaining the original
12211 height:width ratio, do the following:
12213 @example
12214 #+ATTR_ODT: :width 10
12215 [[./img.png]]
12216 @end example
12218 @item Scale the image to a specific height
12219 To embed @file{img.png} with a height of 10 cm while retaining the original
12220 height:width ratio, do the following
12222 @example
12223 #+ATTR_ODT: :height 10
12224 [[./img.png]]
12225 @end example
12226 @end table
12228 @subsubheading Anchoring of images
12230 @cindex #+ATTR_ODT
12231 You can control the manner in which an image is anchored by setting the
12232 @code{:anchor} property of it's @code{#+ATTR_ODT} line.  You can specify one
12233 of the following three values for the @code{:anchor} property:
12234 @samp{"as-char"}, @samp{"paragraph"} and @samp{"page"}.
12236 To create an image that is anchored to a page, do the following:
12237 @example
12238 #+ATTR_ODT: :anchor "page"
12239 [[./img.png]]
12240 @end example
12242 @node Math formatting in ODT export, Labels and captions in ODT export, Images in ODT export, OpenDocument Text export
12243 @subsection Math formatting in ODT export
12245 The ODT exporter has special support for handling math.
12247 @menu
12248 * Working with @LaTeX{} math snippets::  How to embed @LaTeX{} math fragments
12249 * Working with MathML or OpenDocument formula files::  How to embed equations in native format
12250 @end menu
12252 @node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in ODT export, Math formatting in ODT export
12253 @subsubsection Working with @LaTeX{} math snippets
12255 @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT
12256 document in one of the following ways:
12258 @cindex MathML
12259 @enumerate
12260 @item MathML
12262 This option is activated on a per-file basis with
12264 @example
12265 #+OPTIONS: LaTeX:t
12266 @end example
12268 With this option, @LaTeX{} fragments are first converted into MathML
12269 fragments using an external @LaTeX{}-to-MathML converter program.  The
12270 resulting MathML fragments are then embedded as an OpenDocument Formula in
12271 the exported document.
12273 @vindex org-latex-to-mathml-convert-command
12274 @vindex org-latex-to-mathml-jar-file
12276 You can specify the @LaTeX{}-to-MathML converter by customizing the variables
12277 @code{org-latex-to-mathml-convert-command} and
12278 @code{org-latex-to-mathml-jar-file}.
12280 If you prefer to use @file{MathToWeb}@footnote{See
12281 @uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}} as your
12282 converter, you can configure the above variables as shown below.
12284 @lisp
12285 (setq org-latex-to-mathml-convert-command
12286       "java -jar %j -unicode -force -df %o %I"
12287       org-latex-to-mathml-jar-file
12288       "/path/to/mathtoweb.jar")
12289 @end lisp
12291 You can use the following commands to quickly verify the reliability of
12292 the @LaTeX{}-to-MathML converter.
12294 @table @kbd
12295 @item M-x org-odt-export-as-odf RET
12296 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file.
12298 @item M-x org-odt-export-as-odf-and-open RET
12299 Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file
12300 and open the formula file with the system-registered application.
12301 @end table
12303 @cindex dvipng
12304 @cindex imagemagick
12305 @item PNG images
12307 This option is activated on a per-file basis with
12309 @example
12310 #+OPTIONS: tex:dvipng
12311 @end example
12315 @example
12316 #+OPTIONS: tex:imagemagick
12317 @end example
12319 With this option, @LaTeX{} fragments are processed into PNG images and the
12320 resulting images are embedded in the exported document.  This method requires
12321 that the @file{dvipng} program or @file{imagemagick} suite be available on
12322 your system.
12323 @end enumerate
12325 @node Working with MathML or OpenDocument formula files,  , Working with @LaTeX{} math snippets, Math formatting in ODT export
12326 @subsubsection Working with MathML or OpenDocument formula files
12328 For various reasons, you may find embedding @LaTeX{} math snippets in an
12329 ODT document less than reliable.  In that case, you can embed a
12330 math equation by linking to its MathML (@file{.mml}) source or its
12331 OpenDocument formula (@file{.odf}) file as shown below:
12333 @example
12334 [[./equation.mml]]
12335 @end example
12339 @example
12340 [[./equation.odf]]
12341 @end example
12343 @node Labels and captions in ODT export, Literal examples in ODT export, Math formatting in ODT export, OpenDocument Text export
12344 @subsection Labels and captions in ODT export
12346 You can label and caption various category of objects---an inline image, a
12347 table, a @LaTeX{} fragment or a Math formula---using @code{#+LABEL} and
12348 @code{#+CAPTION} lines.  @xref{Images and tables}.  ODT exporter enumerates
12349 each labeled or captioned object of a given category separately.  As a
12350 result, each such object is assigned a sequence number based on order of it's
12351 appearance in the Org file.
12353 In the exported document, a user-provided caption is augmented with the
12354 category and sequence number.  Consider the following inline image in an Org
12355 file.
12357 @example
12358 #+CAPTION: Bell curve
12359 #+LABEL:   fig:SED-HR4049
12360 [[./img/a.png]]
12361 @end example
12363 It could be rendered as shown below in the exported document.
12365 @example
12366 Figure 2: Bell curve
12367 @end example
12369 @vindex org-odt-category-map-alist
12370 You can modify the category component of the caption by customizing the
12371 option @code{org-odt-category-map-alist}.  For example, to tag all embedded
12372 images with the string @samp{Illustration} (instead of the default
12373 @samp{Figure}) use the following setting:
12375 @lisp
12376 (setq org-odt-category-map-alist
12377       (("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
12378 @end lisp
12380 With this, previous image will be captioned as below in the exported
12381 document.
12383 @example
12384 Illustration 2: Bell curve
12385 @end example
12387 @node Literal examples in ODT export, Advanced topics in ODT export, Labels and captions in ODT export, OpenDocument Text export
12388 @subsection Literal examples in ODT export
12390 Export of literal examples (@pxref{Literal examples}) with full fontification
12391 is supported.  Internally, the exporter relies on @file{htmlfontify.el} to
12392 generate all style definitions needed for a fancy listing.@footnote{Your
12393 @file{htmlfontify.el} library must at least be at Emacs 24.1 levels for
12394 fontification to be turned on.}  The auto-generated styles have @samp{OrgSrc}
12395 as prefix and inherit their color from the faces used by Emacs
12396 @code{font-lock} library for the source language.
12398 @vindex org-odt-fontify-srcblocks
12399 If you prefer to use your own custom styles for fontification, you can do
12400 so by customizing the option
12401 @code{org-odt-create-custom-styles-for-srcblocks}.
12403 @vindex org-odt-create-custom-styles-for-srcblocks
12404 You can turn off fontification of literal examples by customizing the
12405 option @code{org-odt-fontify-srcblocks}.
12407 @node Advanced topics in ODT export,  , Literal examples in ODT export, OpenDocument Text export
12408 @subsection Advanced topics in ODT export
12410 If you rely heavily on ODT export, you may want to exploit the full
12411 set of features that the exporter offers.  This section describes features
12412 that would be of interest to power users.
12414 @menu
12415 * Configuring a document converter::  How to register a document converter
12416 * Working with OpenDocument style files::  Explore the internals
12417 * Creating one-off styles::     How to produce custom highlighting etc
12418 * Customizing tables in ODT export::  How to define and use Table templates
12419 * Validating OpenDocument XML::  How to debug corrupt OpenDocument files
12420 @end menu
12422 @node Configuring a document converter, Working with OpenDocument style files, Advanced topics in ODT export, Advanced topics in ODT export
12423 @subsubsection Configuring a document converter
12424 @cindex convert
12425 @cindex doc, docx, rtf
12426 @cindex converter
12428 The ODT exporter can work with popular converters with little or no
12429 extra configuration from your side. @xref{Extending ODT export}.
12430 If you are using a converter that is not supported by default or if you would
12431 like to tweak the default converter settings, proceed as below.
12433 @enumerate
12434 @item Register the converter
12436 @vindex org-odt-convert-processes
12437 Name your converter and add it to the list of known converters by
12438 customizing the option @code{org-odt-convert-processes}.  Also specify how
12439 the converter can be invoked via command-line to effect the conversion.
12441 @item Configure its capabilities
12443 @vindex org-odt-convert-capabilities
12444 @anchor{x-odt-converter-capabilities} Specify the set of formats the
12445 converter can handle by customizing the variable
12446 @code{org-odt-convert-capabilities}.  Use the default value for this
12447 variable as a guide for configuring your converter.  As suggested by the
12448 default setting, you can specify the full set of formats supported by the
12449 converter and not limit yourself to specifying formats that are related to
12450 just the OpenDocument Text format.
12452 @item Choose the converter
12454 @vindex org-odt-convert-process
12455 Select the newly added converter as the preferred one by customizing the
12456 option @code{org-odt-convert-process}.
12457 @end enumerate
12459 @node Working with OpenDocument style files, Creating one-off styles, Configuring a document converter, Advanced topics in ODT export
12460 @subsubsection Working with OpenDocument style files
12461 @cindex styles, custom
12462 @cindex template, custom
12464 This section explores the internals of the ODT exporter and the
12465 means by which it produces styled documents.  Read this section if you are
12466 interested in exploring the automatic and custom OpenDocument styles used by
12467 the exporter.
12469 @anchor{x-factory-styles}
12470 @subsubheading Factory styles
12472 The ODT exporter relies on two files for generating its output.
12473 These files are bundled with the distribution under the directory pointed to
12474 by the variable @code{org-odt-styles-dir}.  The two files are:
12476 @itemize
12477 @anchor{x-orgodtstyles-xml}
12478 @item
12479 @file{OrgOdtStyles.xml}
12481 This file contributes to the @file{styles.xml} file of the final @samp{ODT}
12482 document.  This file gets modified for the following purposes:
12483 @enumerate
12485 @item
12486 To control outline numbering based on user settings.
12488 @item
12489 To add styles generated by @file{htmlfontify.el} for fontification of code
12490 blocks.
12491 @end enumerate
12493 @anchor{x-orgodtcontenttemplate-xml}
12494 @item
12495 @file{OrgOdtContentTemplate.xml}
12497 This file contributes to the @file{content.xml} file of the final @samp{ODT}
12498 document.  The contents of the Org outline are inserted between the
12499 @samp{<office:text>}@dots{}@samp{</office:text>} elements of this file.
12501 Apart from serving as a template file for the final @file{content.xml}, the
12502 file serves the following purposes:
12503 @enumerate
12505 @item
12506 It contains automatic styles for formatting of tables which are referenced by
12507 the exporter.
12509 @item
12510 It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
12511 elements that control how various entities---tables, images, equations,
12512 etc.---are numbered.
12513 @end enumerate
12514 @end itemize
12516 @anchor{x-overriding-factory-styles}
12517 @subsubheading Overriding factory styles
12518 The following two variables control the location from which the ODT
12519 exporter picks up the custom styles and content template files.  You can
12520 customize these variables to override the factory styles used by the
12521 exporter.
12523 @itemize
12524 @anchor{x-org-odt-styles-file}
12525 @item
12526 @code{org-odt-styles-file}
12528 Use this variable to specify the @file{styles.xml} that will be used in the
12529 final output.  You can specify one of the following values:
12531 @enumerate
12532 @item A @file{styles.xml} file
12534 Use this file instead of the default @file{styles.xml}
12536 @item A @file{.odt} or @file{.ott} file
12538 Use the @file{styles.xml} contained in the specified OpenDocument Text or
12539 Template file
12541 @item A @file{.odt} or @file{.ott} file and a subset of files contained within them
12543 Use the @file{styles.xml} contained in the specified OpenDocument Text or
12544 Template file.  Additionally extract the specified member files and embed
12545 those within the final @samp{ODT} document.
12547 Use this option if the @file{styles.xml} file references additional files
12548 like header and footer images.
12550 @item @code{nil}
12552 Use the default @file{styles.xml}
12553 @end enumerate
12555 @anchor{x-org-odt-content-template-file}
12556 @item
12557 @code{org-odt-content-template-file}
12559 Use this variable to specify the blank @file{content.xml} that will be used
12560 in the final output.
12561 @end itemize
12563 @node Creating one-off styles, Customizing tables in ODT export, Working with OpenDocument style files, Advanced topics in ODT export
12564 @subsubsection Creating one-off styles
12566 There are times when you would want one-off formatting in the exported
12567 document.  You can achieve this by embedding raw OpenDocument XML in the Org
12568 file.  The use of this feature is better illustrated with couple of examples.
12570 @enumerate
12571 @item Embedding ODT tags as part of regular text
12573 You can inline OpenDocument syntax by enclosing it within
12574 @samp{@@@@odt:...@@@@} markup.  For example, to highlight a region of text do
12575 the following:
12577 @example
12578 @@@@odt:<text:span text:style-name="Highlight">This is a highlighted
12579 text</text:span>@@@@.  But this is a regular text.
12580 @end example
12582 @strong{Hint:} To see the above example in action, edit your
12583 @file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
12584 custom @samp{Highlight} style as shown below.
12586 @example
12587 <style:style style:name="Highlight" style:family="text">
12588   <style:text-properties fo:background-color="#ff0000"/>
12589 </style:style>
12590 @end example
12592 @item Embedding a one-line OpenDocument XML
12594 You can add a simple OpenDocument one-liner using the @code{#+ODT:}
12595 directive.  For example, to force a page break do the following:
12597 @example
12598 #+ODT: <text:p text:style-name="PageBreak"/>
12599 @end example
12601 @strong{Hint:} To see the above example in action, edit your
12602 @file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
12603 custom @samp{PageBreak} style as shown below.
12605 @example
12606 <style:style style:name="PageBreak" style:family="paragraph"
12607              style:parent-style-name="Text_20_body">
12608   <style:paragraph-properties fo:break-before="page"/>
12609 </style:style>
12610 @end example
12612 @item Embedding a block of OpenDocument XML
12614 You can add a large block of OpenDocument XML using the
12615 @code{#+BEGIN_ODT}@dots{}@code{#+END_ODT} construct.
12617 For example, to create a one-off paragraph that uses bold text, do the
12618 following:
12620 @example
12621 #+BEGIN_ODT
12622 <text:p text:style-name="Text_20_body_20_bold">
12623 This paragraph is specially formatted and uses bold text.
12624 </text:p>
12625 #+END_ODT
12626 @end example
12628 @end enumerate
12630 @node Customizing tables in ODT export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in ODT export
12631 @subsubsection Customizing tables in ODT export
12632 @cindex tables, in ODT export
12634 @cindex #+ATTR_ODT
12635 You can override the default formatting of the table by specifying a custom
12636 table style with the @code{#+ATTR_ODT} line.  For a discussion on default
12637 formatting of tables @pxref{Tables in ODT export}.
12639 This feature closely mimics the way table templates are defined in the
12640 OpenDocument-v1.2
12641 specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
12642 OpenDocument-v1.2 Specification}}
12644 @subsubheading Custom table styles: an illustration
12646 @vindex org-odt-table-styles
12647 To have a quick preview of this feature, install the below setting and
12648 export the table that follows:
12650 @lisp
12651 (setq org-odt-table-styles
12652       (append org-odt-table-styles
12653             '(("TableWithHeaderRowAndColumn" "Custom"
12654                 ((use-first-row-styles . t)
12655                  (use-first-column-styles . t)))
12656                 ("TableWithFirstRowandLastRow" "Custom"
12657                  ((use-first-row-styles . t)
12658                  (use-last-row-styles . t))))))
12659 @end lisp
12661 @example
12662 #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
12663 | Name  | Phone | Age |
12664 | Peter |  1234 |  17 |
12665 | Anna  |  4321 |  25 |
12666 @end example
12668 In the above example, you used a template named @samp{Custom} and installed
12669 two table styles with the names @samp{TableWithHeaderRowAndColumn} and
12670 @samp{TableWithFirstRowandLastRow}.  (@strong{Important:} The OpenDocument
12671 styles needed for producing the above template have been pre-defined for
12672 you.  These styles are available under the section marked @samp{Custom
12673 Table Template} in @file{OrgOdtContentTemplate.xml}
12674 (@pxref{x-orgodtcontenttemplate-xml,,Factory styles}).  If you need
12675 additional templates you have to define these styles yourselves.
12677 @subsubheading Custom table styles: the nitty-gritty
12678 To use this feature proceed as follows:
12680 @enumerate
12681 @item
12682 Create a table template@footnote{See the @code{<table:table-template>}
12683 element of the OpenDocument-v1.2 specification}
12685 A table template is nothing but a set of @samp{table-cell} and
12686 @samp{paragraph} styles for each of the following table cell categories:
12688 @itemize @minus
12689 @item Body
12690 @item First column
12691 @item Last column
12692 @item First row
12693 @item Last row
12694 @item Even row
12695 @item Odd row
12696 @item Even column
12697 @item Odd Column
12698 @end itemize
12700 The names for the above styles must be chosen based on the name of the table
12701 template using a well-defined convention.
12703 The naming convention is better illustrated with an example.  For a table
12704 template with the name @samp{Custom}, the needed style names are listed in
12705 the following table.
12707 @multitable  {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph}
12708 @headitem Table cell type
12709 @tab @code{table-cell} style
12710 @tab @code{paragraph} style
12711 @item
12712 @tab
12713 @tab
12714 @item Body
12715 @tab @samp{CustomTableCell}
12716 @tab @samp{CustomTableParagraph}
12717 @item First column
12718 @tab @samp{CustomFirstColumnTableCell}
12719 @tab @samp{CustomFirstColumnTableParagraph}
12720 @item Last column
12721 @tab @samp{CustomLastColumnTableCell}
12722 @tab @samp{CustomLastColumnTableParagraph}
12723 @item First row
12724 @tab @samp{CustomFirstRowTableCell}
12725 @tab @samp{CustomFirstRowTableParagraph}
12726 @item Last row
12727 @tab @samp{CustomLastRowTableCell}
12728 @tab @samp{CustomLastRowTableParagraph}
12729 @item Even row
12730 @tab @samp{CustomEvenRowTableCell}
12731 @tab @samp{CustomEvenRowTableParagraph}
12732 @item Odd row
12733 @tab @samp{CustomOddRowTableCell}
12734 @tab @samp{CustomOddRowTableParagraph}
12735 @item Even column
12736 @tab @samp{CustomEvenColumnTableCell}
12737 @tab @samp{CustomEvenColumnTableParagraph}
12738 @item Odd column
12739 @tab @samp{CustomOddColumnTableCell}
12740 @tab @samp{CustomOddColumnTableParagraph}
12741 @end multitable
12743 To create a table template with the name @samp{Custom}, define the above
12744 styles in the
12745 @code{<office:automatic-styles>}...@code{</office:automatic-styles>} element
12746 of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory
12747 styles}).
12749 @item
12750 Define a table style@footnote{See the attributes @code{table:template-name},
12751 @code{table:use-first-row-styles}, @code{table:use-last-row-styles},
12752 @code{table:use-first-column-styles}, @code{table:use-last-column-styles},
12753 @code{table:use-banding-rows-styles}, and
12754 @code{table:use-banding-column-styles} of the @code{<table:table>} element in
12755 the OpenDocument-v1.2 specification}
12757 @vindex org-odt-table-styles
12758 To define a table style, create an entry for the style in the variable
12759 @code{org-odt-table-styles} and specify the following:
12761 @itemize @minus
12762 @item the name of the table template created in step (1)
12763 @item the set of cell styles in that template that are to be activated
12764 @end itemize
12766 For example, the entry below defines two different table styles
12767 @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
12768 based on the same template @samp{Custom}.  The styles achieve their intended
12769 effect by selectively activating the individual cell styles in that template.
12771 @lisp
12772 (setq org-odt-table-styles
12773       (append org-odt-table-styles
12774               '(("TableWithHeaderRowAndColumn" "Custom"
12775                  ((use-first-row-styles . t)
12776                   (use-first-column-styles . t)))
12777                 ("TableWithFirstRowandLastRow" "Custom"
12778                  ((use-first-row-styles . t)
12779                   (use-last-row-styles . t))))))
12780 @end lisp
12782 @item
12783 Associate a table with the table style
12785 To do this, specify the table style created in step (2) as part of
12786 the @code{ATTR_ODT} line as shown below.
12788 @example
12789 #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
12790 | Name  | Phone | Age |
12791 | Peter |  1234 |  17 |
12792 | Anna  |  4321 |  25 |
12793 @end example
12794 @end enumerate
12796 @node Validating OpenDocument XML,  , Customizing tables in ODT export, Advanced topics in ODT export
12797 @subsubsection Validating OpenDocument XML
12799 Occasionally, you will discover that the document created by the
12800 ODT exporter cannot be opened by your favorite application.  One of
12801 the common reasons for this is that the @file{.odt} file is corrupt.  In such
12802 cases, you may want to validate the document against the OpenDocument RELAX
12803 NG Compact Syntax (RNC) schema.
12805 For de-compressing the @file{.odt} file@footnote{@file{.odt} files are
12806 nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}.  For
12807 general help with validation (and schema-sensitive editing) of XML files:
12808 @inforef{Introduction,,nxml-mode}.
12810 @vindex org-odt-schema-dir
12811 If you have ready access to OpenDocument @file{.rnc} files and the needed
12812 schema-locating rules in a single folder, you can customize the variable
12813 @code{org-odt-schema-dir} to point to that directory.  The ODT exporter
12814 will take care of updating the @code{rng-schema-locating-files} for you.
12816 @c end opendocument
12818 @node Org export
12819 @section Org export
12820 @cindex Org export
12822 @code{org} export back-end creates a normalized version of the Org document
12823 in current buffer.  In particular, it evaluates Babel code (@pxref{Evaluating
12824 code blocks}) and removes other back-ends specific contents.
12826 @subheading Org export commands
12828 @table @kbd
12829 @orgcmd{C-c C-e O o,org-org-export-to-org}
12830 Export as an Org document.  For an Org file, @file{myfile.org}, the resulting
12831 file will be @file{myfile.org.org}.  The file will be overwritten without
12832 warning.
12833 @orgcmd{C-c C-e O O,org-org-export-as-org}
12834 Export to a temporary buffer.  Do not create a file.
12835 @item C-c C-e O v
12836 Export to an Org file, then open it.
12837 @end table
12839 @node iCalendar export, Other built-in back-ends, Org export, Exporting
12840 @section iCalendar export
12841 @cindex iCalendar export
12843 @vindex org-icalendar-include-todo
12844 @vindex org-icalendar-use-deadline
12845 @vindex org-icalendar-use-scheduled
12846 @vindex org-icalendar-categories
12847 @vindex org-icalendar-alarm-time
12848 Some people use Org mode for keeping track of projects, but still prefer a
12849 standard calendar application for anniversaries and appointments.  In this
12850 case it can be useful to show deadlines and other time-stamped items in Org
12851 files in the calendar application.  Org mode can export calendar information
12852 in the standard iCalendar format.  If you also want to have TODO entries
12853 included in the export, configure the variable
12854 @code{org-icalendar-include-todo}.  Plain timestamps are exported as VEVENT,
12855 and TODO items as VTODO@.  It will also create events from deadlines that are
12856 in non-TODO items.  Deadlines and scheduling dates in TODO items will be used
12857 to set the start and due dates for the TODO entry@footnote{See the variables
12858 @code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}.
12859 As categories, it will use the tags locally defined in the heading, and the
12860 file/tree category@footnote{To add inherited tags or the TODO state,
12861 configure the variable @code{org-icalendar-categories}.}.  See the variable
12862 @code{org-icalendar-alarm-time} for a way to assign alarms to entries with a
12863 time.
12865 @vindex org-icalendar-store-UID
12866 @cindex property, ID
12867 The iCalendar standard requires each entry to have a globally unique
12868 identifier (UID).  Org creates these identifiers during export.  If you set
12869 the variable @code{org-icalendar-store-UID}, the UID will be stored in the
12870 @code{:ID:} property of the entry and re-used next time you report this
12871 entry.  Since a single entry can give rise to multiple iCalendar entries (as
12872 a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds
12873 prefixes to the UID, depending on what triggered the inclusion of the entry.
12874 In this way the UID remains unique, but a synchronization program can still
12875 figure out from which entry all the different instances originate.
12877 @table @kbd
12878 @orgcmd{C-c C-e c f,org-icalendar-export-to-ics}
12879 Create iCalendar entries for the current buffer and store them in the same
12880 directory, using a file extension @file{.ics}.
12881 @orgcmd{C-c C-e c a, org-icalendar-export-agenda-files}
12882 @vindex org-agenda-files
12883 Like @kbd{C-c C-e c f}, but do this for all files in
12884 @code{org-agenda-files}.  For each of these files, a separate iCalendar
12885 file will be written.
12886 @orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files}
12887 @vindex org-icalendar-combined-agenda-file
12888 Create a single large iCalendar file from all files in
12889 @code{org-agenda-files} and write it to the file given by
12890 @code{org-icalendar-combined-agenda-file}.
12891 @end table
12893 @vindex org-use-property-inheritance
12894 @vindex org-icalendar-include-body
12895 @cindex property, SUMMARY
12896 @cindex property, DESCRIPTION
12897 @cindex property, LOCATION
12898 The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION
12899 property can be inherited from higher in the hierarchy if you configure
12900 @code{org-use-property-inheritance} accordingly.} properties if the selected
12901 entries have them.  If not, the summary will be derived from the headline,
12902 and the description from the body (limited to
12903 @code{org-icalendar-include-body} characters).
12905 How this calendar is best read and updated, depends on the application
12906 you are using.  The FAQ covers this issue.
12908 @node Other built-in back-ends, Export in foreign buffers, iCalendar export, Exporting
12909 @section Other built-in back-ends
12910 @cindex export back-ends, built-in
12911 @vindex org-export-backends
12913 On top of the aforementioned back-ends, Org comes with other built-in ones:
12915 @itemize
12916 @item @file{ox-man.el}: export to a man page.
12917 @item @file{ox-texinfo.el}: export to @code{Texinfo} format.
12918 @end itemize
12920 To activate these export back-end, customize @code{org-export-backends} or
12921 load them directly with e.g., @code{(require 'ox-texinfo)}.  This will add
12922 new keys in the export dispatcher (@pxref{The Export Dispatcher}).
12924 See the comment section of these files for more information on how to use
12925 them.
12927 @node Export in foreign buffers, Advanced configuration, Other built-in back-ends, Exporting
12928 @section Export in foreign buffers
12930 Most built-in back-ends come with a command to convert the selected region
12931 into a selected format and replace this region by the exported output.  Here
12932 is a list of such conversion commands:
12934 @table @code
12935 @item org-html-convert-region-to-html
12936 Convert the selected region into HTML.
12937 @item org-latex-convert-region-to-latex
12938 Convert the selected region into @LaTeX{}.
12939 @item org-texinfo-convert-region-to-texinfo
12940 Convert the selected region into @code{Texinfo}.
12941 @item org-md-convert-region-to-md
12942 Convert the selected region into @code{MarkDown}.
12943 @end table
12945 This is particularly useful for converting tables and lists in foreign
12946 buffers.  E.g., in an HTML buffer, you can turn on @code{orgstruct-mode}, then
12947 use Org commands for editing a list, and finally select and convert the list
12948 with @code{M-x org-html-convert-region-to-html RET}.
12950 @node Advanced configuration,  , Export in foreign buffers, Exporting
12951 @section Advanced configuration
12953 @subheading Hooks
12955 @vindex org-export-before-processing-hook
12956 @vindex org-export-before-parsing-hook
12957 Two hooks are run during the first steps of the export process.  The first
12958 one, @code{org-export-before-processing-hook} is called before expanding
12959 macros, Babel code and include keywords in the buffer.  The second one,
12960 @code{org-export-before-parsing-hook}, as its name suggests, happens just
12961 before parsing the buffer.  Their main use is for heavy duties, that is
12962 duties involving structural modifications of the document.  For example, one
12963 may want to remove every headline in the buffer during export.  The following
12964 code can achieve this:
12966 @lisp
12967 @group
12968 (defun my-headline-removal (backend)
12969   "Remove all headlines in the current buffer.
12970 BACKEND is the export back-end being used, as a symbol."
12971   (org-map-entries
12972    (lambda () (delete-region (point) (progn (forward-line) (point))))))
12974 (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
12975 @end group
12976 @end lisp
12978 Note that functions used in these hooks require a mandatory argument,
12979 a symbol representing the back-end used.
12981 @subheading Filters
12983 @cindex Filters, exporting
12984 Filters are lists of functions applied on a specific part of the output from
12985 a given back-end.  More explicitly, each time a back-end transforms an Org
12986 object or element into another language, all functions within a given filter
12987 type are called in turn on the string produced.  The string returned by the
12988 last function will be the one used in the final output.
12990 There are filters sets for each type of element or object, for plain text,
12991 for the parse tree, for the export options and for the final output.  They
12992 are all named after the same scheme: @code{org-export-filter-TYPE-functions},
12993 where @code{TYPE} is the type targeted by the filter.  Valid types are:
12995 @multitable @columnfractions .33 .33 .33
12996 @item bold
12997 @tab babel-call
12998 @tab center-block
12999 @item clock
13000 @tab code
13001 @tab comment
13002 @item comment-block
13003 @tab diary-sexp
13004 @tab drawer
13005 @item dynamic-block
13006 @tab entity
13007 @tab example-block
13008 @item export-block
13009 @tab export-snippet
13010 @tab final-output
13011 @item fixed-width
13012 @tab footnote-definition
13013 @tab footnote-reference
13014 @item headline
13015 @tab horizontal-rule
13016 @tab inline-babel-call
13017 @item inline-src-block
13018 @tab inlinetask
13019 @tab italic
13020 @item item
13021 @tab keyword
13022 @tab latex-environment
13023 @item latex-fragment
13024 @tab line-break
13025 @tab link
13026 @item node-property
13027 @tab options
13028 @tab paragraph
13029 @item parse-tree
13030 @tab plain-list
13031 @tab plain-text
13032 @item planning
13033 @tab property-drawer
13034 @tab quote-block
13035 @item quote-section
13036 @tab radio-target
13037 @tab section
13038 @item special-block
13039 @tab src-block
13040 @tab statistics-cookie
13041 @item strike-through
13042 @tab subscript
13043 @tab superscript
13044 @item table
13045 @tab table-cell
13046 @tab table-row
13047 @item target
13048 @tab timestamp
13049 @tab underline
13050 @item verbatim
13051 @tab verse-block
13052 @tab
13053 @end multitable
13055 For example, the following snippet allows me to use non-breaking spaces in
13056 the Org buffer and get them translated into @LaTeX{} without using the
13057 @code{\nbsp} macro (where @code{_} stands for the non-breaking space):
13059 @lisp
13060 @group
13061 (defun my-latex-filter-nobreaks (text backend info)
13062   "Ensure \" \" are properly handled in LaTeX export."
13063   (when (org-export-derived-backend-p backend 'latex)
13064         (replace-regexp-in-string " " "~" text)))
13066 (add-to-list 'org-export-filter-plain-text-functions
13067              'my-latex-filter-nobreaks)
13068 @end group
13069 @end lisp
13071 Three arguments must be provided to a filter: the code being changed, the
13072 back-end used, and some information about the export process.  You can safely
13073 ignore the third argument for most purposes.  Note the use of
13074 @code{org-export-derived-backend-p}, which ensures that the filter will only
13075 be applied when using @code{latex} back-end or any other back-end derived
13076 from it (e.g., @code{beamer}).
13078 @subheading Extending an existing back-end
13080 This is obviously the most powerful customization, since the changes happen
13081 at the parser level.  Indeed, some export back-ends are built as extensions
13082 of other ones (e.g. Markdown back-end an extension of HTML back-end).
13084 Extending a back-end means that if an element type is not transcoded by the
13085 new back-end, it will be handled by the original one.  Hence you can extend
13086 specific parts of a back-end without too much work.
13088 As an example, imagine we want the @code{ascii} back-end to display the
13089 language used in a source block, when it is available, but only when some
13090 attribute is non-@code{nil}, like the following:
13092 @example
13093 #+ATTR_ASCII: :language t
13094 @end example
13096 Because that back-end is lacking in that area, we are going to create a new
13097 back-end, @code{my-ascii} that will do the job.
13099 @lisp
13100 @group
13101 (defun my-ascii-src-block (src-block contents info)
13102   "Transcode a SRC-BLOCK element from Org to ASCII.
13103 CONTENTS is nil.  INFO is a plist used as a communication
13104 channel."
13105   (if (not (org-export-read-attribute :attr_ascii src-block :language))
13106     (org-export-with-backend 'ascii src-block contents info)
13107   (concat
13108    (format ",--[ %s ]--\n%s`----"
13109            (org-element-property :language src-block)
13110            (replace-regexp-in-string
13111             "^" "| "
13112             (org-element-normalize-string
13113              (org-export-format-code-default src-block info)))))))
13115 (org-export-define-derived-backend 'my-ascii 'ascii
13116   :translate-alist '((src-block . my-ascii-src-block)))
13117 @end group
13118 @end lisp
13120 The @code{my-ascii-src-block} function looks at the attribute above the
13121 element.  If it isn't true, it gives hand to the @code{ascii} back-end.
13122 Otherwise, it creates a box around the code, leaving room for the language.
13123 A new back-end is then created.  It only changes its behavior when
13124 translating @code{src-block} type element.  Now, all it takes to use the new
13125 back-end is calling the following from an Org buffer:
13127 @smalllisp
13128 (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
13129 @end smalllisp
13131 It is obviously possible to write an interactive function for this, install
13132 it in the export dispatcher menu, and so on.
13134 @node Publishing, Working With Source Code, Exporting, Top
13135 @chapter Publishing
13136 @cindex publishing
13138 Org includes a publishing management system that allows you to configure
13139 automatic HTML conversion of @emph{projects} composed of interlinked org
13140 files.  You can also configure Org to automatically upload your exported HTML
13141 pages and related attachments, such as images and source code files, to a web
13142 server.
13144 You can also use Org to convert files into PDF, or even combine HTML and PDF
13145 conversion so that files are available in both formats on the server.
13147 Publishing has been contributed to Org by David O'Toole.
13149 @menu
13150 * Configuration::               Defining projects
13151 * Uploading files::             How to get files up on the server
13152 * Sample configuration::        Example projects
13153 * Triggering publication::      Publication commands
13154 @end menu
13156 @node Configuration, Uploading files, Publishing, Publishing
13157 @section Configuration
13159 Publishing needs significant configuration to specify files, destination
13160 and many other properties of a project.
13162 @menu
13163 * Project alist::               The central configuration variable
13164 * Sources and destinations::    From here to there
13165 * Selecting files::             What files are part of the project?
13166 * Publishing action::           Setting the function doing the publishing
13167 * Publishing options::          Tweaking HTML/@LaTeX{} export
13168 * Publishing links::            Which links keep working after publishing?
13169 * Sitemap::                     Generating a list of all pages
13170 * Generating an index::         An index that reaches across pages
13171 @end menu
13173 @node Project alist, Sources and destinations, Configuration, Configuration
13174 @subsection The variable @code{org-publish-project-alist}
13175 @cindex org-publish-project-alist
13176 @cindex projects, for publishing
13178 @vindex org-publish-project-alist
13179 Publishing is configured almost entirely through setting the value of one
13180 variable, called @code{org-publish-project-alist}.  Each element of the list
13181 configures one project, and may be in one of the two following forms:
13183 @lisp
13184    ("project-name" :property value :property value ...)
13185      @r{i.e., a well-formed property list with alternating keys and values}
13186 @r{or}
13187    ("project-name" :components ("project-name" "project-name" ...))
13189 @end lisp
13191 In both cases, projects are configured by specifying property values.  A
13192 project defines the set of files that will be published, as well as the
13193 publishing configuration to use when publishing those files.  When a project
13194 takes the second form listed above, the individual members of the
13195 @code{:components} property are taken to be sub-projects, which group
13196 together files requiring different publishing options.  When you publish such
13197 a ``meta-project'', all the components will also be published, in the
13198 sequence given.
13200 @node Sources and destinations, Selecting files, Project alist, Configuration
13201 @subsection Sources and destinations for files
13202 @cindex directories, for publishing
13204 Most properties are optional, but some should always be set.  In
13205 particular, Org needs to know where to look for source files,
13206 and where to put published files.
13208 @multitable @columnfractions 0.3 0.7
13209 @item @code{:base-directory}
13210 @tab Directory containing publishing source files
13211 @item @code{:publishing-directory}
13212 @tab Directory where output files will be published.  You can directly
13213 publish to a web server using a file name syntax appropriate for
13214 the Emacs @file{tramp} package.  Or you can publish to a local directory and
13215 use external tools to upload your website (@pxref{Uploading files}).
13216 @item @code{:preparation-function}
13217 @tab Function or list of functions to be called before starting the
13218 publishing process, for example, to run @code{make} for updating files to be
13219 published.  The project property list is scoped into this call as the
13220 variable @code{project-plist}.
13221 @item @code{:completion-function}
13222 @tab Function or list of functions called after finishing the publishing
13223 process, for example, to change permissions of the resulting files.  The
13224 project property list is scoped into this call as the variable
13225 @code{project-plist}.
13226 @end multitable
13227 @noindent
13229 @node Selecting files, Publishing action, Sources and destinations, Configuration
13230 @subsection Selecting files
13231 @cindex files, selecting for publishing
13233 By default, all files with extension @file{.org} in the base directory
13234 are considered part of the project.  This can be modified by setting the
13235 properties
13236 @multitable @columnfractions 0.25 0.75
13237 @item @code{:base-extension}
13238 @tab Extension (without the dot!) of source files.  This actually is a
13239 regular expression.  Set this to the symbol @code{any} if you want to get all
13240 files in @code{:base-directory}, even without extension.
13242 @item @code{:exclude}
13243 @tab Regular expression to match file names that should not be
13244 published, even though they have been selected on the basis of their
13245 extension.
13247 @item @code{:include}
13248 @tab List of files to be included regardless of @code{:base-extension}
13249 and @code{:exclude}.
13251 @item @code{:recursive}
13252 @tab non-@code{nil} means, check base-directory recursively for files to publish.
13253 @end multitable
13255 @node Publishing action, Publishing options, Selecting files, Configuration
13256 @subsection Publishing action
13257 @cindex action, for publishing
13259 Publishing means that a file is copied to the destination directory and
13260 possibly transformed in the process.  The default transformation is to export
13261 Org files as HTML files, and this is done by the function
13262 @code{org-html-publish-to-html}, which calls the HTML exporter (@pxref{HTML
13263 export}).  But you also can publish your content as PDF files using
13264 @code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc.,
13265 using the corresponding functions.
13267 If you want to publish the Org file as an @code{.org} file but with the
13268 @i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the
13269 function @code{org-org-publish-to-org}.  This will produce @file{file.org}
13270 and put it in the publishing directory.  If you want a htmlized version of
13271 this file, set the parameter @code{:htmlized-source} to @code{t}, it will
13272 produce @file{file.org.html} in the publishing directory@footnote{If the
13273 publishing directory is the same than the source directory, @file{file.org}
13274 will be exported as @file{file.org.org}, so probably don't want to do this.}.
13276 Other files like images only need to be copied to the publishing destination.
13277 For this you can use @code{org-publish-attachment}.  For non-org files, you
13278 always need to specify the publishing function:
13280 @multitable @columnfractions 0.3 0.7
13281 @item @code{:publishing-function}
13282 @tab Function executing the publication of a file.  This may also be a
13283 list of functions, which will all be called in turn.
13284 @item @code{:htmlized-source}
13285 @tab non-@code{nil} means, publish htmlized source.
13286 @end multitable
13288 The function must accept three arguments: a property list containing at least
13289 a @code{:publishing-directory} property, the name of the file to be published
13290 and the path to the publishing directory of the output file.  It should take
13291 the specified file, make the necessary transformation (if any) and place the
13292 result into the destination folder.
13294 @node Publishing options, Publishing links, Publishing action, Configuration
13295 @subsection Options for the exporters
13296 @cindex options, for publishing
13298 The property list can be used to set many export options for the exporters.
13299 In most cases, these properties correspond to user variables in Org.  The
13300 first table below lists these properties along with the variable they belong
13301 to.  The second table list HTML specific properties.  See the documentation
13302 string of these options for details.
13304 @vindex org-display-custom-times
13305 @vindex org-export-default-language
13306 @vindex org-export-exclude-tags
13307 @vindex org-export-headline-levels
13308 @vindex org-export-preserve-breaks
13309 @vindex org-export-publishing-directory
13310 @vindex org-export-select-tags
13311 @vindex org-export-with-archived-trees
13312 @vindex org-export-with-author
13313 @vindex org-export-with-creator
13314 @vindex org-export-with-drawers
13315 @vindex org-export-with-email
13316 @vindex org-export-with-emphasize
13317 @vindex org-export-with-fixed-width
13318 @vindex org-export-with-footnotes
13319 @vindex org-export-with-latex
13320 @vindex org-export-with-planning
13321 @vindex org-export-with-priority
13322 @vindex org-export-with-section-numbers
13323 @vindex org-export-with-special-strings
13324 @vindex org-export-with-sub-superscripts
13325 @vindex org-export-with-tables
13326 @vindex org-export-with-tags
13327 @vindex org-export-with-tasks
13328 @vindex org-export-with-timestamps
13329 @vindex org-export-with-toc
13330 @vindex org-export-with-todo-keywords
13331 @vindex user-mail-address
13333 @multitable @columnfractions 0.32 0.68
13334 @item @code{:archived-trees}        @tab @code{org-export-with-archived-trees}
13335 @item @code{:exclude-tags}          @tab @code{org-export-exclude-tags}
13336 @item @code{:headline-levels}       @tab @code{org-export-headline-levels}
13337 @item @code{:language}              @tab @code{org-export-default-language}
13338 @item @code{:preserve-breaks}       @tab @code{org-export-preserve-breaks}
13339 @item @code{:section-numbers}       @tab @code{org-export-with-section-numbers}
13340 @item @code{:select-tags}           @tab @code{org-export-select-tags}
13341 @item @code{:with-author}           @tab @code{org-export-with-author}
13342 @item @code{:with-creator}          @tab @code{org-export-with-creator}
13343 @item @code{:with-drawers}          @tab @code{org-export-with-drawers}
13344 @item @code{:with-email}            @tab @code{org-export-with-email}
13345 @item @code{:with-emphasize}        @tab @code{org-export-with-emphasize}
13346 @item @code{:with-fixed-width}      @tab @code{org-export-with-fixed-width}
13347 @item @code{:with-footnotes}        @tab @code{org-export-with-footnotes}
13348 @item @code{:with-latex}            @tab @code{org-export-with-latex}
13349 @item @code{:with-planning}         @tab @code{org-export-with-planning}
13350 @item @code{:with-priority}         @tab @code{org-export-with-priority}
13351 @item @code{:with-special-strings}  @tab @code{org-export-with-special-strings}
13352 @item @code{:with-sub-superscript}  @tab @code{org-export-with-sub-superscripts}
13353 @item @code{:with-tables}           @tab @code{org-export-with-tables}
13354 @item @code{:with-tags}             @tab @code{org-export-with-tags}
13355 @item @code{:with-tasks}            @tab @code{org-export-with-tasks}
13356 @item @code{:with-timestamps}       @tab @code{org-export-with-timestamps}
13357 @item @code{:with-toc}              @tab @code{org-export-with-toc}
13358 @item @code{:with-todo-keywords}    @tab @code{org-export-with-todo-keywords}
13359 @end multitable
13361 @vindex org-html-doctype
13362 @vindex org-html-container-element
13363 @vindex org-html-html5-fancy
13364 @vindex org-html-xml-declaration
13365 @vindex org-html-link-up
13366 @vindex org-html-link-home
13367 @vindex org-html-link-org-files-as-html
13368 @vindex org-html-link-use-abs-url
13369 @vindex org-html-head
13370 @vindex org-html-head-extra
13371 @vindex org-html-inline-images
13372 @vindex org-html-extension
13373 @vindex org-html-preamble
13374 @vindex org-html-postamble
13375 @vindex org-html-table-default-attributes
13376 @vindex org-html-table-row-tags
13377 @vindex org-html-head-include-default-style
13378 @vindex org-html-head-include-scripts
13379 @multitable @columnfractions 0.32 0.68
13380 @item @code{:html-doctype}          @tab @code{org-html-doctype}
13381 @item @code{:html-container}        @tab @code{org-html-container-element}
13382 @item @code{:html-html5-fancy}      @tab @code{org-html-html5-fancy}
13383 @item @code{:html-xml-declaration}  @tab @code{org-html-xml-declaration}
13384 @item @code{:html-link-up}          @tab @code{org-html-link-up}
13385 @item @code{:html-link-home}        @tab @code{org-html-link-home}
13386 @item @code{:html-link-org-as-html} @tab @code{org-html-link-org-files-as-html}
13387 @item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url}
13388 @item @code{:html-head}             @tab @code{org-html-head}
13389 @item @code{:html-head-extra}       @tab @code{org-html-head-extra}
13390 @item @code{:html-inline-images}    @tab @code{org-html-inline-images}
13391 @item @code{:html-extension}        @tab @code{org-html-extension}
13392 @item @code{:html-preamble}         @tab @code{org-html-preamble}
13393 @item @code{:html-postamble}        @tab @code{org-html-postamble}
13394 @item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
13395 @item @code{:html-table-row-tags}   @tab @code{org-html-table-row-tags}
13396 @item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style}
13397 @item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts}
13398 @end multitable
13400 Most of the @code{org-export-with-*} variables have the same effect in each
13401 exporter.
13403 @vindex org-publish-project-alist
13404 When a property is given a value in @code{org-publish-project-alist}, its
13405 setting overrides the value of the corresponding user variable (if any)
13406 during publishing.  Options set within a file (@pxref{Export settings}),
13407 however, override everything.
13409 @node Publishing links, Sitemap, Publishing options, Configuration
13410 @subsection Links between published files
13411 @cindex links, publishing
13413 To create a link from one Org file to another, you would use something like
13414 @samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org.}
13415 (@pxref{Hyperlinks}).  When published, this link becomes a link to
13416 @file{foo.html}.  You can thus interlink the pages of your "org web" project
13417 and the links will work as expected when you publish them to HTML@.  If you
13418 also publish the Org source file and want to link to it, use an @code{http:}
13419 link instead of a @code{file:} link, because @code{file:} links are converted
13420 to link to the corresponding @file{html} file.
13422 You may also link to related files, such as images.  Provided you are careful
13423 with relative file names, and provided you have also configured Org to upload
13424 the related files, these links will work too.  See @ref{Complex example}, for
13425 an example of this usage.
13427 @node Sitemap, Generating an index, Publishing links, Configuration
13428 @subsection Generating a sitemap
13429 @cindex sitemap, of published pages
13431 The following properties may be used to control publishing of
13432 a map of files for a given project.
13434 @multitable @columnfractions 0.35 0.65
13435 @item @code{:auto-sitemap}
13436 @tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project}
13437 or @code{org-publish-all}.
13439 @item @code{:sitemap-filename}
13440 @tab Filename for output of sitemap.  Defaults to @file{sitemap.org} (which
13441 becomes @file{sitemap.html}).
13443 @item @code{:sitemap-title}
13444 @tab Title of sitemap page.  Defaults to name of file.
13446 @item @code{:sitemap-function}
13447 @tab Plug-in function to use for generation of the sitemap.
13448 Defaults to @code{org-publish-org-sitemap}, which generates a plain list
13449 of links to all files in the project.
13451 @item @code{:sitemap-sort-folders}
13452 @tab Where folders should appear in the sitemap.  Set this to @code{first}
13453 (default) or @code{last} to display folders first or last,
13454 respectively.  Any other value will mix files and folders.
13456 @item @code{:sitemap-sort-files}
13457 @tab How the files are sorted in the site map.  Set this to
13458 @code{alphabetically} (default), @code{chronologically} or
13459 @code{anti-chronologically}.  @code{chronologically} sorts the files with
13460 older date first while @code{anti-chronologically} sorts the files with newer
13461 date first.  @code{alphabetically} sorts the files alphabetically.  The date of
13462 a file is retrieved with @code{org-publish-find-date}.
13464 @item @code{:sitemap-ignore-case}
13465 @tab Should sorting be case-sensitive?  Default @code{nil}.
13467 @item @code{:sitemap-file-entry-format}
13468 @tab With this option one can tell how a sitemap's entry is formatted in the
13469 sitemap.  This is a format string with some escape sequences: @code{%t} stands
13470 for the title of the file, @code{%a} stands for the author of the file and
13471 @code{%d} stands for the date of the file.  The date is retrieved with the
13472 @code{org-publish-find-date} function and formatted with
13473 @code{org-publish-sitemap-date-format}.  Default @code{%t}.
13475 @item @code{:sitemap-date-format}
13476 @tab Format string for the @code{format-time-string} function that tells how
13477 a sitemap entry's date is to be formatted.  This property bypasses
13478 @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
13480 @item @code{:sitemap-sans-extension}
13481 @tab When non-@code{nil}, remove filenames' extensions from the generated sitemap.
13482 Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}).
13483 Defaults to @code{nil}.
13485 @end multitable
13487 @node Generating an index,  , Sitemap, Configuration
13488 @subsection Generating an index
13489 @cindex index, in a publishing project
13491 Org mode can generate an index across the files of a publishing project.
13493 @multitable @columnfractions 0.25 0.75
13494 @item @code{:makeindex}
13495 @tab When non-@code{nil}, generate in index in the file @file{theindex.org} and
13496 publish it as @file{theindex.html}.
13497 @end multitable
13499 The file will be created when first publishing a project with the
13500 @code{:makeindex} set.  The file only contains a statement @code{#+INCLUDE:
13501 "theindex.inc"}.  You can then build around this include statement by adding
13502 a title, style information, etc.
13504 @node Uploading files, Sample configuration, Configuration, Publishing
13505 @section Uploading files
13506 @cindex rsync
13507 @cindex unison
13509 For those people already utilizing third party sync tools such as
13510 @command{rsync} or @command{unison}, it might be preferable not to use the built in
13511 @i{remote} publishing facilities of Org mode which rely heavily on
13512 Tramp.  Tramp, while very useful and powerful, tends not to be
13513 so efficient for multiple file transfer and has been known to cause problems
13514 under heavy usage.
13516 Specialized synchronization utilities offer several advantages.  In addition
13517 to timestamp comparison, they also do content and permissions/attribute
13518 checks.  For this reason you might prefer to publish your web to a local
13519 directory (possibly even @i{in place} with your Org files) and then use
13520 @file{unison} or @file{rsync} to do the synchronization with the remote host.
13522 Since Unison (for example) can be configured as to which files to transfer to
13523 a certain remote destination, it can greatly simplify the project publishing
13524 definition.  Simply keep all files in the correct location, process your Org
13525 files with @code{org-publish} and let the synchronization tool do the rest.
13526 You do not need, in this scenario, to include attachments such as @file{jpg},
13527 @file{css} or @file{gif} files in the project definition since the 3rd party
13528 tool syncs them.
13530 Publishing to a local directory is also much faster than to a remote one, so
13531 that you can afford more easily to republish entire projects.  If you set
13532 @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
13533 benefit of re-including any changed external files such as source example
13534 files you might include with @code{#+INCLUDE:}.  The timestamp mechanism in
13535 Org is not smart enough to detect if included files have been modified.
13537 @node Sample configuration, Triggering publication, Uploading files, Publishing
13538 @section Sample configuration
13540 Below we provide two example configurations.  The first one is a simple
13541 project publishing only a set of Org files.  The second example is
13542 more complex, with a multi-component project.
13544 @menu
13545 * Simple example::              One-component publishing
13546 * Complex example::             A multi-component publishing example
13547 @end menu
13549 @node Simple example, Complex example, Sample configuration, Sample configuration
13550 @subsection Example: simple publishing configuration
13552 This example publishes a set of Org files to the @file{public_html}
13553 directory on the local machine.
13555 @lisp
13556 (setq org-publish-project-alist
13557       '(("org"
13558          :base-directory "~/org/"
13559          :publishing-directory "~/public_html"
13560          :section-numbers nil
13561          :with-toc nil
13562          :html-head "<link rel=\"stylesheet\"
13563                     href=\"../other/mystyle.css\"
13564                     type=\"text/css\"/>")))
13565 @end lisp
13567 @node Complex example,  , Simple example, Sample configuration
13568 @subsection Example: complex publishing configuration
13570 This more complicated example publishes an entire website, including
13571 Org files converted to HTML, image files, Emacs Lisp source code, and
13572 style sheets.  The publishing directory is remote and private files are
13573 excluded.
13575 To ensure that links are preserved, care should be taken to replicate
13576 your directory structure on the web server, and to use relative file
13577 paths.  For example, if your Org files are kept in @file{~/org} and your
13578 publishable images in @file{~/images}, you would link to an image with
13580 @example
13581 file:../images/myimage.png
13582 @end example
13584 On the web server, the relative path to the image should be the
13585 same.  You can accomplish this by setting up an "images" folder in the
13586 right place on the web server, and publishing images to it.
13588 @lisp
13589 (setq org-publish-project-alist
13590       '(("orgfiles"
13591           :base-directory "~/org/"
13592           :base-extension "org"
13593           :publishing-directory "/ssh:user@@host:~/html/notebook/"
13594           :publishing-function org-html-publish-to-html
13595           :exclude "PrivatePage.org"   ;; regexp
13596           :headline-levels 3
13597           :section-numbers nil
13598           :with-toc nil
13599           :html-head "<link rel=\"stylesheet\"
13600                   href=\"../other/mystyle.css\" type=\"text/css\"/>"
13601           :html-preamble t)
13603          ("images"
13604           :base-directory "~/images/"
13605           :base-extension "jpg\\|gif\\|png"
13606           :publishing-directory "/ssh:user@@host:~/html/images/"
13607           :publishing-function org-publish-attachment)
13609          ("other"
13610           :base-directory "~/other/"
13611           :base-extension "css\\|el"
13612           :publishing-directory "/ssh:user@@host:~/html/other/"
13613           :publishing-function org-publish-attachment)
13614          ("website" :components ("orgfiles" "images" "other"))))
13615 @end lisp
13617 @node Triggering publication,  , Sample configuration, Publishing
13618 @section Triggering publication
13620 Once properly configured, Org can publish with the following commands:
13622 @table @kbd
13623 @orgcmd{C-c C-e P x,org-publish}
13624 Prompt for a specific project and publish all files that belong to it.
13625 @orgcmd{C-c C-e P p,org-publish-current-project}
13626 Publish the project containing the current file.
13627 @orgcmd{C-c C-e P f,org-publish-current-file}
13628 Publish only the current file.
13629 @orgcmd{C-c C-e P a,org-publish-all}
13630 Publish every project.
13631 @end table
13633 @vindex org-publish-use-timestamps-flag
13634 Org uses timestamps to track when a file has changed.  The above functions
13635 normally only publish changed files.  You can override this and force
13636 publishing of all files by giving a prefix argument to any of the commands
13637 above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
13638 This may be necessary in particular if files include other files via
13639 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
13641 @comment  node-name,  next,  previous,  up
13642 @comment Working With Source Code, Miscellaneous, Publishing, Top
13644 @node Working With Source Code, Miscellaneous, Publishing, Top
13645 @chapter Working with source code
13646 @cindex Schulte, Eric
13647 @cindex Davison, Dan
13648 @cindex source code, working with
13650 Source code can be included in Org mode documents using a @samp{src} block,
13651 e.g.:
13653 @example
13654 #+BEGIN_SRC emacs-lisp
13655   (defun org-xor (a b)
13656      "Exclusive or."
13657      (if a (not b) b))
13658 #+END_SRC
13659 @end example
13661 Org mode provides a number of features for working with live source code,
13662 including editing of code blocks in their native major-mode, evaluation of
13663 code blocks, converting code blocks into source files (known as @dfn{tangling}
13664 in literate programming), and exporting code blocks and their
13665 results in several formats.  This functionality was contributed by Eric
13666 Schulte and Dan Davison, and was originally named Org-babel.
13668 The following sections describe Org mode's code block handling facilities.
13670 @menu
13671 * Structure of code blocks::    Code block syntax described
13672 * Editing source code::         Language major-mode editing
13673 * Exporting code blocks::       Export contents and/or results
13674 * Extracting source code::      Create pure source code files
13675 * Evaluating code blocks::      Place results of evaluation in the Org mode buffer
13676 * Library of Babel::            Use and contribute to a library of useful code blocks
13677 * Languages::                   List of supported code block languages
13678 * Header arguments::            Configure code block functionality
13679 * Results of evaluation::       How evaluation results are handled
13680 * Noweb reference syntax::      Literate programming in Org mode
13681 * Key bindings and useful functions::  Work quickly with code blocks
13682 * Batch execution::             Call functions from the command line
13683 @end menu
13685 @comment  node-name,  next,  previous,  up
13686 @comment  Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code
13688 @node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code
13689 @section Structure of code blocks
13690 @cindex code block, structure
13691 @cindex source code, block structure
13692 @cindex #+NAME
13693 @cindex #+BEGIN_SRC
13695 Live code blocks can be specified with a @samp{src} block or
13696 inline.@footnote{Note that @samp{src} blocks may be inserted using Org mode's
13697 @ref{Easy Templates} system}  The structure of a @samp{src} block is
13699 @example
13700 #+NAME: <name>
13701 #+BEGIN_SRC <language> <switches> <header arguments>
13702   <body>
13703 #+END_SRC
13704 @end example
13706 The @code{#+NAME:} line is optional, and can be used to name the code
13707 block.  Live code blocks require that a language be specified on the
13708 @code{#+BEGIN_SRC} line.  Switches and header arguments are optional.
13709 @cindex source code, inline
13711 Live code blocks can also be specified inline using
13713 @example
13714 src_<language>@{<body>@}
13715 @end example
13719 @example
13720 src_<language>[<header arguments>]@{<body>@}
13721 @end example
13723 @table @code
13724 @item <#+NAME: name>
13725 This line associates a name with the code block.  This is similar to the
13726 @code{#+NAME: Name} lines that can be used to name tables in Org mode
13727 files.  Referencing the name of a code block makes it possible to evaluate
13728 the block from other places in the file, from other files, or from Org mode
13729 table formulas (see @ref{The spreadsheet}).  Names are assumed to be unique
13730 and the behavior of Org mode when two or more blocks share the same name is
13731 undefined.
13732 @cindex #+NAME
13733 @item <language>
13734 The language of the code in the block (see @ref{Languages}).
13735 @cindex source code, language
13736 @item <switches>
13737 Optional switches control code block export (see the discussion of switches in
13738 @ref{Literal examples})
13739 @cindex source code, switches
13740 @item <header arguments>
13741 Optional header arguments control many aspects of evaluation, export and
13742 tangling of code blocks (see @ref{Header arguments}).
13743 Header arguments can also be set on a per-buffer or per-subtree
13744 basis using properties.
13745 @item source code, header arguments
13746 @item <body>
13747 Source code in the specified language.
13748 @end table
13750 @comment  node-name,  next,  previous,  up
13751 @comment  Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code
13753 @node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code
13754 @section Editing source code
13755 @cindex code block, editing
13756 @cindex source code, editing
13758 @vindex org-edit-src-auto-save-idle-delay
13759 @vindex org-edit-src-turn-on-auto-save
13760 @kindex C-c '
13761 Use @kbd{C-c '} to edit the current code block.  This brings up a language
13762 major-mode edit buffer containing the body of the code block.  Manually
13763 saving this buffer with @key{C-x C-s} will write the contents back to the Org
13764 buffer.  You can also set @code{org-edit-src-auto-save-idle-delay} to save the
13765 base buffer after some idle delay, or @code{org-edit-src-turn-on-auto-save}
13766 to auto-save this buffer into a separate file using @code{auto-save-mode}.
13767 Use @kbd{C-c '} again to exit.
13769 The @code{org-src-mode} minor mode will be active in the edit buffer.  The
13770 following variables can be used to configure the behavior of the edit
13771 buffer.  See also the customization group @code{org-edit-structure} for
13772 further configuration options.
13774 @table @code
13775 @item org-src-lang-modes
13776 If an Emacs major-mode named @code{<lang>-mode} exists, where
13777 @code{<lang>} is the language named in the header line of the code block,
13778 then the edit buffer will be placed in that major-mode.  This variable
13779 can be used to map arbitrary language names to existing major modes.
13780 @item org-src-window-setup
13781 Controls the way Emacs windows are rearranged when the edit buffer is created.
13782 @item org-src-preserve-indentation
13783 By default, the value is @code{nil}, which means that when code blocks are
13784 evaluated during export or tangled, they are re-inserted into the code block,
13785 which may replace sequences of spaces with tab characters.  When non-nil,
13786 whitespace in code blocks will be preserved during export or tangling,
13787 exactly as it appears.  This variable is especially useful for tangling
13788 languages such as Python, in which whitespace indentation in the output is
13789 critical.
13790 @item org-src-ask-before-returning-to-edit-buffer
13791 By default, Org will ask before returning to an open edit buffer.  Set this
13792 variable to @code{nil} to switch without asking.
13793 @end table
13795 To turn on native code fontification in the @emph{Org} buffer, configure the
13796 variable @code{org-src-fontify-natively}.
13798 @comment  node-name,  next,  previous,  up
13799 @comment  Exporting code blocks, Extracting source code, Editing source code, Working With Source Code
13801 @node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code
13802 @section Exporting code blocks
13803 @cindex code block, exporting
13804 @cindex source code, exporting
13806 It is possible to export the @emph{code} of code blocks, the @emph{results}
13807 of code block evaluation, @emph{both} the code and the results of code block
13808 evaluation, or @emph{none}.  For most languages, the default exports code.
13809 However, for some languages (e.g., @code{ditaa}) the default exports the
13810 results of code block evaluation.  For information on exporting code block
13811 bodies, see @ref{Literal examples}.
13813 The @code{:exports} header argument can be used to specify export
13814 behavior:
13816 @subsubheading Header arguments:
13818 @table @code
13819 @item :exports code
13820 The default in most languages.  The body of the code block is exported, as
13821 described in @ref{Literal examples}.
13822 @item :exports results
13823 The code block will be evaluated and the results will be placed in the
13824 Org mode buffer for export, either updating previous results of the code
13825 block located anywhere in the buffer or, if no previous results exist,
13826 placing the results immediately after the code block.  The body of the code
13827 block will not be exported.
13828 @item :exports both
13829 Both the code block and its results will be exported.
13830 @item :exports none
13831 Neither the code block nor its results will be exported.
13832 @end table
13834 It is possible to inhibit the evaluation of code blocks during export.
13835 Setting the @code{org-export-babel-evaluate} variable to @code{nil} will
13836 ensure that no code blocks are evaluated as part of the export process.  This
13837 can be useful in situations where potentially untrusted Org mode files are
13838 exported in an automated fashion, for example when Org mode is used as the
13839 markup language for a wiki.  It is also possible to set this variable to
13840 @code{'inline-only}.  In that case, only inline code blocks will be
13841 evaluated, in order to insert their results.  Non-inline code blocks are
13842 assumed to have their results already inserted in the buffer by manual
13843 evaluation.  This setting is useful to avoid expensive recalculations during
13844 export, not to provide security.
13846 @comment  node-name,  next,  previous,  up
13847 @comment  Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
13848 @node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
13849 @section Extracting source code
13850 @cindex tangling
13851 @cindex source code, extracting
13852 @cindex code block, extracting source code
13854 Creating pure source code files by extracting code from source blocks is
13855 referred to as ``tangling''---a term adopted from the literate programming
13856 community.  During ``tangling'' of code blocks their bodies are expanded
13857 using @code{org-babel-expand-src-block} which can expand both variable and
13858 ``noweb'' style references  (see @ref{Noweb reference syntax}).
13860 @subsubheading Header arguments
13862 @table @code
13863 @item :tangle no
13864 The default.  The code block is not included in the tangled output.
13865 @item :tangle yes
13866 Include the code block in the tangled output.  The output file name is the
13867 name of the org file with the extension @samp{.org} replaced by the extension
13868 for the block language.
13869 @item :tangle filename
13870 Include the code block in the tangled output to file @samp{filename}.
13871 @end table
13873 @kindex  C-c C-v t
13874 @subsubheading Functions
13876 @table @code
13877 @item org-babel-tangle
13878 Tangle the current file.  Bound to @kbd{C-c C-v t}.
13880 With prefix argument only tangle the current code block.
13881 @item org-babel-tangle-file
13882 Choose a file to tangle.  Bound to @kbd{C-c C-v f}.
13883 @end table
13885 @subsubheading Hooks
13887 @table @code
13888 @item org-babel-post-tangle-hook
13889 This hook is run from within code files tangled by @code{org-babel-tangle}.
13890 Example applications could include post-processing, compilation or evaluation
13891 of tangled code files.
13892 @end table
13894 @subsubheading Jumping between code and Org
13896 When tangling code from an Org-mode buffer to a source code file, you'll
13897 frequently find yourself viewing the file of tangled source code (e.g., many
13898 debuggers point to lines of the source code file).  It is useful to be able
13899 to navigate from the tangled source to the Org-mode buffer from which the
13900 code originated.
13902 The @code{org-babel-tangle-jump-to-org} function provides this jumping from
13903 code to Org-mode functionality.  Two header arguments are required for
13904 jumping to work, first the @code{padline} (@ref{padline}) option must be set
13905 to true (the default setting), second the @code{comments} (@ref{comments})
13906 header argument must be set to @code{links}, which will insert comments into
13907 the source code buffer which point back to the original Org-mode file.
13909 @node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code
13910 @section Evaluating code blocks
13911 @cindex code block, evaluating
13912 @cindex source code, evaluating
13913 @cindex #+RESULTS
13915 Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
13916 potential for that code to do harm.  Org mode provides safeguards to ensure
13917 that code is only evaluated after explicit confirmation from the user.  For
13918 information on these safeguards (and on how to disable them) see @ref{Code
13919 evaluation security}.} and the results of evaluation optionally placed in the
13920 Org mode buffer.  The results of evaluation are placed following a line that
13921 begins by default with @code{#+RESULTS} and optionally a cache identifier
13922 and/or the name of the evaluated code block.  The default value of
13923 @code{#+RESULTS} can be changed with the customizable variable
13924 @code{org-babel-results-keyword}.
13926 By default, the evaluation facility is only enabled for Lisp code blocks
13927 specified as @code{emacs-lisp}.  However, source code blocks in many languages
13928 can be evaluated within Org mode (see @ref{Languages} for a list of supported
13929 languages and @ref{Structure of code blocks} for information on the syntax
13930 used to define a code block).
13932 @kindex C-c C-c
13933 There are a number of ways to evaluate code blocks.  The simplest is to press
13934 @kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The
13935 option @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used to remove code
13936 evaluation from the @kbd{C-c C-c} key binding.}.  This will call the
13937 @code{org-babel-execute-src-block} function to evaluate the block and insert
13938 its results into the Org mode buffer.
13939 @cindex #+CALL
13941 It is also possible to evaluate named code blocks from anywhere in an Org
13942 mode buffer or an Org mode table.  Live code blocks located in the current
13943 Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel})
13944 can be executed.  Named code blocks can be executed with a separate
13945 @code{#+CALL:} line or inline within a block of text.
13947 The syntax of the @code{#+CALL:} line is
13949 @example
13950 #+CALL: <name>(<arguments>)
13951 #+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
13952 @end example
13954 The syntax for inline evaluation of named code blocks is
13956 @example
13957 ... call_<name>(<arguments>) ...
13958 ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
13959 @end example
13961 @table @code
13962 @item <name>
13963 The name of the code block to be evaluated (see @ref{Structure of code blocks}).
13964 @item <arguments>
13965 Arguments specified in this section will be passed to the code block.  These
13966 arguments use standard function call syntax, rather than
13967 header argument syntax.  For example, a @code{#+CALL:} line that passes the
13968 number four to a code block named @code{double}, which declares the header
13969 argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}.
13970 @item <inside header arguments>
13971 Inside header arguments are passed through and applied to the named code
13972 block.  These arguments use header argument syntax rather than standard
13973 function call syntax.  Inside header arguments affect how the code block is
13974 evaluated.  For example, @code{[:results output]} will collect the results of
13975 everything printed to @code{STDOUT} during execution of the code block.
13976 @item <end header arguments>
13977 End header arguments are applied to the calling instance and do not affect
13978 evaluation of the named code block.  They affect how the results are
13979 incorporated into the Org mode buffer and how the call line is exported.  For
13980 example, @code{:results html} will insert the results of the call line
13981 evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block.
13983 For more examples of passing header arguments to @code{#+CALL:} lines see
13984 @ref{Header arguments in function calls}.
13985 @end table
13987 @node Library of Babel, Languages, Evaluating code blocks, Working With Source Code
13988 @section Library of Babel
13989 @cindex babel, library of
13990 @cindex source code, library
13991 @cindex code block, library
13993 The ``Library of Babel'' consists of code blocks that can be called from any
13994 Org mode file.  Code blocks defined in the ``Library of Babel'' can be called
13995 remotely as if they were in the current Org mode buffer (see @ref{Evaluating
13996 code blocks} for information on the syntax of remote code block evaluation).
13999 The central repository of code blocks in the ``Library of Babel'' is housed
14000 in an Org mode file located in the @samp{contrib} directory of Org mode.
14002 Users can add code blocks they believe to be generally useful to their
14003 ``Library of Babel.''  The code blocks can be stored in any Org mode file and
14004 then loaded into the library with @code{org-babel-lob-ingest}.
14007 @kindex C-c C-v i
14008 Code blocks located in any Org mode file can be loaded into the ``Library of
14009 Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v
14012 @node Languages, Header arguments, Library of Babel, Working With Source Code
14013 @section Languages
14014 @cindex babel, languages
14015 @cindex source code, languages
14016 @cindex code block, languages
14018 Code blocks in the following languages are supported.
14020 @multitable @columnfractions 0.28 0.3 0.22 0.2
14021 @item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}
14022 @item Asymptote @tab asymptote @tab Awk @tab awk
14023 @item Emacs Calc @tab calc @tab C @tab C
14024 @item C++ @tab C++ @tab Clojure @tab clojure
14025 @item CSS @tab css @tab ditaa @tab ditaa
14026 @item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp
14027 @item gnuplot @tab gnuplot @tab Haskell @tab haskell
14028 @item Java @tab java @tab @tab
14029 @item Javascript @tab js @tab LaTeX @tab latex
14030 @item Ledger @tab ledger @tab Lisp @tab lisp
14031 @item Lilypond @tab lilypond @tab MATLAB @tab matlab
14032 @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
14033 @item Octave @tab octave @tab Org mode @tab org
14034 @item Oz @tab oz @tab Perl @tab perl
14035 @item Plantuml @tab plantuml @tab Python @tab python
14036 @item R @tab R @tab Ruby @tab ruby
14037 @item Sass @tab sass @tab Scheme @tab scheme
14038 @item GNU Screen @tab screen @tab shell @tab sh
14039 @item SQL @tab sql @tab SQLite @tab sqlite
14040 @end multitable
14042 Language-specific documentation is available for some languages.  If
14043 available, it can be found at
14044 @uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
14046 The option @code{org-babel-load-languages} controls which languages are
14047 enabled for evaluation (by default only @code{emacs-lisp} is enabled).  This
14048 variable can be set using the customization interface or by adding code like
14049 the following to your emacs configuration.
14051 @quotation
14052 The following disables @code{emacs-lisp} evaluation and enables evaluation of
14053 @code{R} code blocks.
14054 @end quotation
14056 @lisp
14057 (org-babel-do-load-languages
14058  'org-babel-load-languages
14059  '((emacs-lisp . nil)
14060    (R . t)))
14061 @end lisp
14063 It is also possible to enable support for a language by loading the related
14064 elisp file with @code{require}.
14066 @quotation
14067 The following adds support for evaluating @code{clojure} code blocks.
14068 @end quotation
14070 @lisp
14071 (require 'ob-clojure)
14072 @end lisp
14074 @node Header arguments, Results of evaluation, Languages, Working With Source Code
14075 @section Header arguments
14076 @cindex code block, header arguments
14077 @cindex source code, block header arguments
14079 Code block functionality can be configured with header arguments.  This
14080 section provides an overview of the use of header arguments, and then
14081 describes each header argument in detail.
14083 @menu
14084 * Using header arguments::      Different ways to set header arguments
14085 * Specific header arguments::   List of header arguments
14086 @end menu
14088 @node Using header arguments, Specific header arguments, Header arguments, Header arguments
14089 @subsection Using header arguments
14091 The values of header arguments can be set in several way.  When the header
14092 arguments in each layer have been determined, they are combined in order from
14093 the first, least specific (having the lowest priority) up to the last, most
14094 specific (having the highest priority).  A header argument with a higher
14095 priority replaces the same header argument specified at lower priority.
14096 @menu
14097 * System-wide header arguments::  Set global default values
14098 * Language-specific header arguments::  Set default values by language
14099 * Header arguments in Org mode properties::  Set default values for a buffer or heading
14100 * Language-specific header arguments in Org mode properties::  Set language-specific default values for a buffer or heading
14101 * Code block specific header arguments::  The most common way to set values
14102 * Header arguments in function calls::  The most specific level
14103 @end menu
14106 @node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments
14107 @subsubheading System-wide header arguments
14108 @vindex org-babel-default-header-args
14109 System-wide values of header arguments can be specified by adapting the
14110 @code{org-babel-default-header-args} variable:
14112 @example
14113 :session    => "none"
14114 :results    => "replace"
14115 :exports    => "code"
14116 :cache      => "no"
14117 :noweb      => "no"
14118 @end example
14120 For example, the following example could be used to set the default value of
14121 @code{:noweb} header arguments to @code{yes}.  This would have the effect of
14122 expanding @code{:noweb} references by default when evaluating source code
14123 blocks.
14125 @lisp
14126 (setq org-babel-default-header-args
14127       (cons '(:noweb . "yes")
14128             (assq-delete-all :noweb org-babel-default-header-args)))
14129 @end lisp
14131 @node Language-specific header arguments, Header arguments in Org mode properties, System-wide header arguments, Using header arguments
14132 @subsubheading Language-specific header arguments
14133 Each language can define its own set of default header arguments in variable
14134 @code{org-babel-default-header-args:<lang>}, where @code{<lang>} is the name
14135 of the language.  See the language-specific documentation available online at
14136 @uref{http://orgmode.org/worg/org-contrib/babel}.
14138 @node Header arguments in Org mode properties, Language-specific header arguments in Org mode properties, Language-specific header arguments, Using header arguments
14139 @subsubheading Header arguments in Org mode properties
14141 Buffer-wide header arguments may be specified as properties through the use
14142 of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see
14143 @ref{Property syntax}).
14145 For example the following would set @code{session} to @code{*R*} (only for R
14146 code blocks), and @code{results} to @code{silent} for every code block in the
14147 buffer, ensuring that all execution took place in the same session, and no
14148 results would be inserted into the buffer.
14150 @example
14151 #+PROPERTY: header-args:R  :session *R*
14152 #+PROPERTY: header-args    :results silent
14153 @end example
14155 Header arguments read from Org mode properties can also be set on a
14156 per-subtree basis using property drawers (see @ref{Property syntax}).
14157 @vindex org-use-property-inheritance
14158 When properties are used to set default header arguments, they are always
14159 looked up with inheritance, regardless of the value of
14160 @code{org-use-property-inheritance}.  Properties are evaluated as seen by the
14161 outermost call or source block.@footnote{The deprecated syntax for default
14162 header argument properties, using the name of the header argument as a
14163 property name directly, evaluates the property as seen by the corresponding
14164 source block definition.  This behavior has been kept for backwards
14165 compatibility.}
14167 In the following example the value of
14168 the @code{:cache} header argument will default to @code{yes} in all code
14169 blocks in the subtree rooted at the following heading:
14171 @example
14172 * outline header
14173   :PROPERTIES:
14174   :header-args:    :cache yes
14175   :END:
14176 @end example
14178 @kindex C-c C-x p
14179 @vindex org-babel-default-header-args
14180 Properties defined in this way override the properties set in
14181 @code{org-babel-default-header-args} and are applied for all activated
14182 languages.  It is convenient to use the @code{org-set-property} function
14183 bound to @kbd{C-c C-x p} to set properties in Org mode documents.
14185 @node Language-specific header arguments in Org mode properties, Code block specific header arguments, Header arguments in Org mode properties, Using header arguments
14186 @subsubheading Language-specific header arguments in Org mode properties
14188 Language-specific header arguments are also read from properties
14189 @code{header-args:<lang>} where @code{<lang>} is the name of the language
14190 targeted.  As an example
14192 @example
14193 * Heading
14194   :PROPERTIES:
14195   :header-args:clojure:    :session *clojure-1*
14196   :header-args:R:          :session *R*
14197   :END:
14198 ** Subheading
14199   :PROPERTIES:
14200   :header-args:clojure:    :session *clojure-2*
14201   :END:
14202 @end example
14204 would independently set a default session header argument for R and clojure
14205 for calls and source blocks under subtree ``Heading'' and change to a
14206 different clojure setting for evaluations under subtree ``Subheading'', while
14207 the R session is inherited from ``Heading'' and therefore unchanged.
14209 @node Code block specific header arguments, Header arguments in function calls, Language-specific header arguments in Org mode properties, Using header arguments
14210 @subsubheading Code block specific header arguments
14212 The most common way to assign values to header arguments is at the
14213 code block level.  This can be done by listing a sequence of header
14214 arguments and their values as part of the @code{#+BEGIN_SRC} line.
14215 Properties set in this way override both the values of
14216 @code{org-babel-default-header-args} and header arguments specified as
14217 properties.  In the following example, the @code{:results} header argument
14218 is set to @code{silent}, meaning the results of execution will not be
14219 inserted in the buffer, and the @code{:exports} header argument is set to
14220 @code{code}, meaning only the body of the code block will be
14221 preserved on export to HTML or @LaTeX{}.
14223 @example
14224 #+NAME: factorial
14225 #+BEGIN_SRC haskell :results silent :exports code :var n=0
14226 fac 0 = 1
14227 fac n = n * fac (n-1)
14228 #+END_SRC
14229 @end example
14230 Similarly, it is possible to set header arguments for inline code blocks
14232 @example
14233 src_haskell[:exports both]@{fac 5@}
14234 @end example
14236 Code block header arguments can span multiple lines using @code{#+HEADER:} or
14237 @code{#+HEADERS:} lines preceding a code block or nested between the
14238 @code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block.
14239 @cindex #+HEADER:
14240 @cindex #+HEADERS:
14242 Multi-line header arguments on an un-named code block:
14244 @example
14245  #+HEADERS: :var data1=1
14246  #+BEGIN_SRC emacs-lisp :var data2=2
14247    (message "data1:%S, data2:%S" data1 data2)
14248  #+END_SRC
14250  #+RESULTS:
14251  : data1:1, data2:2
14252 @end example
14254 Multi-line header arguments on a named code block:
14256 @example
14257    #+NAME: named-block
14258    #+HEADER: :var data=2
14259    #+BEGIN_SRC emacs-lisp
14260      (message "data:%S" data)
14261    #+END_SRC
14263    #+RESULTS: named-block
14264    : data:2
14265 @end example
14267 @node Header arguments in function calls,  , Code block specific header arguments, Using header arguments
14268 @comment  node-name,  next,  previous,  up
14269 @subsubheading Header arguments in function calls
14271 At the most specific level, header arguments for ``Library of Babel'' or
14272 @code{#+CALL:} lines can be set as shown in the two examples below.  For more
14273 information on the structure of @code{#+CALL:} lines see @ref{Evaluating code
14274 blocks}.
14276 The following will apply the @code{:exports results} header argument to the
14277 evaluation of the @code{#+CALL:} line.
14279 @example
14280 #+CALL: factorial(n=5) :exports results
14281 @end example
14283 The following will apply the @code{:session special} header argument to the
14284 evaluation of the @code{factorial} code block.
14286 @example
14287 #+CALL: factorial[:session special](n=5)
14288 @end example
14290 @node Specific header arguments,  , Using header arguments, Header arguments
14291 @subsection Specific header arguments
14292 Header arguments consist of an initial colon followed by the name of the
14293 argument in lowercase letters.  The following header arguments are defined:
14295 @menu
14296 * var::                         Pass arguments to code blocks
14297 * results::                     Specify the type of results and how they will
14298                                 be collected and handled
14299 * file::                        Specify a path for file output
14300 * file-desc::                   Specify a description for file results
14301 * dir::                         Specify the default (possibly remote)
14302                                 directory for code block execution
14303 * exports::                     Export code and/or results
14304 * tangle::                      Toggle tangling and specify file name
14305 * mkdirp::                      Toggle creation of parent directories of target
14306                                 files during tangling
14307 * comments::                    Toggle insertion of comments in tangled
14308                                 code files
14309 * padline::                     Control insertion of padding lines in tangled
14310                                 code files
14311 * no-expand::                   Turn off variable assignment and noweb
14312                                 expansion during tangling
14313 * session::                     Preserve the state of code evaluation
14314 * noweb::                       Toggle expansion of noweb references
14315 * noweb-ref::                   Specify block's noweb reference resolution target
14316 * noweb-sep::                   String used to separate noweb references
14317 * cache::                       Avoid re-evaluating unchanged code blocks
14318 * sep::                         Delimiter for writing tabular results outside Org
14319 * hlines::                      Handle horizontal lines in tables
14320 * colnames::                    Handle column names in tables
14321 * rownames::                    Handle row names in tables
14322 * shebang::                     Make tangled files executable
14323 * tangle-mode::                 Set permission of tangled files
14324 * eval::                        Limit evaluation of specific code blocks
14325 * wrap::                        Mark source block evaluation results
14326 * post::                        Post processing of code block results
14327 * prologue::                    Text to prepend to code block body
14328 * epilogue::                    Text to append to code block body
14329 @end menu
14331 Additional header arguments are defined on a language-specific basis, see
14332 @ref{Languages}.
14334 @node var, results, Specific header arguments, Specific header arguments
14335 @subsubsection @code{:var}
14336 The @code{:var} header argument is used to pass arguments to code blocks.
14337 The specifics of how arguments are included in a code block vary by language;
14338 these are addressed in the language-specific documentation.  However, the
14339 syntax used to specify arguments is the same across all languages.  In every
14340 case, variables require a default value when they are declared.
14342 The values passed to arguments can either be literal values, references, or
14343 Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}).
14344 References include anything in the Org mode file that takes a @code{#+NAME:}
14345 or @code{#+RESULTS:} line: tables, lists, @code{#+BEGIN_EXAMPLE} blocks,
14346 other code blocks and the results of other code blocks.
14348 Note: When a reference is made to another code block, the referenced block
14349 will be evaluated unless it has current cached results (see @ref{cache}).
14351 Argument values can be indexed in a manner similar to arrays (see @ref{var,
14352 Indexable variable values}).
14354 The following syntax is used to pass arguments to code blocks using the
14355 @code{:var} header argument.
14357 @example
14358 :var name=assign
14359 @end example
14361 The argument, @code{assign}, can either be a literal value, such as a string
14362 @samp{"string"} or a number @samp{9}, or a reference to a table, a list, a
14363 literal example, another code block (with or without arguments), or the
14364 results of evaluating another code block.
14366 Here are examples of passing values by reference:
14368 @table @dfn
14370 @item table
14371 an Org mode table named with either a @code{#+NAME:} line
14373 @example
14374 #+NAME: example-table
14375 | 1 |
14376 | 2 |
14377 | 3 |
14378 | 4 |
14380 #+NAME: table-length
14381 #+BEGIN_SRC emacs-lisp :var table=example-table
14382 (length table)
14383 #+END_SRC
14385 #+RESULTS: table-length
14386 : 4
14387 @end example
14389 @item list
14390 a simple list named with a @code{#+NAME:} line (note that nesting is not
14391 carried through to the source code block)
14393 @example
14394 #+NAME: example-list
14395   - simple
14396     - not
14397     - nested
14398   - list
14400 #+BEGIN_SRC emacs-lisp :var x=example-list
14401   (print x)
14402 #+END_SRC
14404 #+RESULTS:
14405 | simple | list |
14406 @end example
14408 @item code block without arguments
14409 a code block name (from the example above), as assigned by @code{#+NAME:},
14410 optionally followed by parentheses
14412 @example
14413 #+BEGIN_SRC emacs-lisp :var length=table-length()
14414 (* 2 length)
14415 #+END_SRC
14417 #+RESULTS:
14418 : 8
14419 @end example
14421 @item code block with arguments
14422 a code block name, as assigned by @code{#+NAME:}, followed by parentheses and
14423 optional arguments passed within the parentheses following the
14424 code block name using standard function call syntax
14426 @example
14427 #+NAME: double
14428 #+BEGIN_SRC emacs-lisp :var input=8
14429 (* 2 input)
14430 #+END_SRC
14432 #+RESULTS: double
14433 : 16
14435 #+NAME: squared
14436 #+BEGIN_SRC emacs-lisp :var input=double(input=1)
14437 (* input input)
14438 #+END_SRC
14440 #+RESULTS: squared
14441 : 4
14442 @end example
14444 @item literal example
14445 a literal example block named with a @code{#+NAME:} line
14447 @example
14448 #+NAME: literal-example
14449 #+BEGIN_EXAMPLE
14450 A literal example
14451 on two lines
14452 #+END_EXAMPLE
14454 #+NAME: read-literal-example
14455 #+BEGIN_SRC emacs-lisp :var x=literal-example
14456   (concatenate 'string x " for you.")
14457 #+END_SRC
14459 #+RESULTS: read-literal-example
14460 : A literal example
14461 : on two lines for you.
14463 @end example
14465 @end table
14467 @subsubheading Indexable variable values
14468 It is possible to reference portions of variable values by ``indexing'' into
14469 the variables.  Indexes are 0 based with negative values counting back from
14470 the end.  If an index is separated by @code{,}s then each subsequent section
14471 will index into the next deepest nesting or dimension of the value.  Note
14472 that this indexing occurs @emph{before} other table related header arguments
14473 like @code{:hlines}, @code{:colnames} and @code{:rownames} are applied.  The
14474 following example assigns the last cell of the first row the table
14475 @code{example-table} to the variable @code{data}:
14477 @example
14478 #+NAME: example-table
14479 | 1 | a |
14480 | 2 | b |
14481 | 3 | c |
14482 | 4 | d |
14484 #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
14485   data
14486 #+END_SRC
14488 #+RESULTS:
14489 : a
14490 @end example
14492 Ranges of variable values can be referenced using two integers separated by a
14493 @code{:}, in which case the entire inclusive range is referenced.  For
14494 example the following assigns the middle three rows of @code{example-table}
14495 to @code{data}.
14497 @example
14498 #+NAME: example-table
14499 | 1 | a |
14500 | 2 | b |
14501 | 3 | c |
14502 | 4 | d |
14503 | 5 | 3 |
14505 #+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
14506   data
14507 #+END_SRC
14509 #+RESULTS:
14510 | 2 | b |
14511 | 3 | c |
14512 | 4 | d |
14513 @end example
14515 Additionally, an empty index, or the single character @code{*}, are both
14516 interpreted to mean the entire range and as such are equivalent to
14517 @code{0:-1}, as shown in the following example in which the entire first
14518 column is referenced.
14520 @example
14521 #+NAME: example-table
14522 | 1 | a |
14523 | 2 | b |
14524 | 3 | c |
14525 | 4 | d |
14527 #+BEGIN_SRC emacs-lisp :var data=example-table[,0]
14528   data
14529 #+END_SRC
14531 #+RESULTS:
14532 | 1 | 2 | 3 | 4 |
14533 @end example
14535 It is possible to index into the results of code blocks as well as tables.
14536 Any number of dimensions can be indexed.  Dimensions are separated from one
14537 another by commas, as shown in the following example.
14539 @example
14540 #+NAME: 3D
14541 #+BEGIN_SRC emacs-lisp
14542   '(((1  2  3)  (4  5  6)  (7  8  9))
14543     ((10 11 12) (13 14 15) (16 17 18))
14544     ((19 20 21) (22 23 24) (25 26 27)))
14545 #+END_SRC
14547 #+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
14548   data
14549 #+END_SRC
14551 #+RESULTS:
14552 | 11 | 14 | 17 |
14553 @end example
14555 @subsubheading Emacs Lisp evaluation of variables
14557 Emacs lisp code can be used to initialize variable values.  When a variable
14558 value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be
14559 evaluated as Emacs Lisp and the result of the evaluation will be assigned as
14560 the variable value.  The following example demonstrates use of this
14561 evaluation to reliably pass the file-name of the Org mode buffer to a code
14562 block---note that evaluation of header arguments is guaranteed to take place
14563 in the original Org mode file, while there is no such guarantee for
14564 evaluation of the code block body.
14566 @example
14567 #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
14568   wc -w $filename
14569 #+END_SRC
14570 @end example
14572 Note that values read from tables and lists will not be evaluated as
14573 Emacs Lisp, as shown in the following example.
14575 @example
14576 #+NAME: table
14577 | (a b c) |
14579 #+HEADERS: :var data=table[0,0]
14580 #+BEGIN_SRC perl
14581   $data
14582 #+END_SRC
14584 #+RESULTS:
14585 : (a b c)
14586 @end example
14588 @node results, file, var, Specific header arguments
14589 @subsubsection @code{:results}
14591 There are four classes of @code{:results} header argument.  Only one option
14592 per class may be supplied per code block.
14594 @itemize @bullet
14595 @item
14596 @b{collection} header arguments specify how the results should be collected
14597 from the code block
14598 @item
14599 @b{type} header arguments specify what type of result the code block will
14600 return---which has implications for how they will be processed before
14601 insertion into the Org mode buffer
14602 @item
14603 @b{format} header arguments specify what type of result the code block will
14604 return---which has implications for how they will be inserted into the
14605 Org mode buffer
14606 @item
14607 @b{handling} header arguments specify how the results of evaluating the code
14608 block should be handled.
14609 @end itemize
14611 @subsubheading Collection
14612 The following options are mutually exclusive, and specify how the results
14613 should be collected from the code block.
14615 @itemize @bullet
14616 @item @code{value}
14617 This is the default.  The result is the value of the last statement in the
14618 code block.  This header argument places the evaluation in functional
14619 mode.  Note that in some languages, e.g., Python, use of this result type
14620 requires that a @code{return} statement be included in the body of the source
14621 code block.  E.g., @code{:results value}.
14622 @item @code{output}
14623 The result is the collection of everything printed to STDOUT during the
14624 execution of the code block.  This header argument places the
14625 evaluation in scripting mode.  E.g., @code{:results output}.
14626 @end itemize
14628 @subsubheading Type
14630 The following options are mutually exclusive and specify what type of results
14631 the code block will return.  By default, results are inserted as either a
14632 table or scalar depending on their value.
14634 @itemize @bullet
14635 @item @code{table}, @code{vector}
14636 The results should be interpreted as an Org mode table.  If a single value is
14637 returned, it will be converted into a table with one row and one column.
14638 E.g., @code{:results value table}.
14639 @item @code{list}
14640 The results should be interpreted as an Org mode list.  If a single scalar
14641 value is returned it will be converted into a list with only one element.
14642 @item @code{scalar}, @code{verbatim}
14643 The results should be interpreted literally---they will not be
14644 converted into a table.  The results will be inserted into the Org mode
14645 buffer as quoted text.  E.g., @code{:results value verbatim}.
14646 @item @code{file}
14647 The results will be interpreted as the path to a file, and will be inserted
14648 into the Org mode buffer as a file link.  E.g., @code{:results value file}.
14649 @end itemize
14651 @subsubheading Format
14653 The following options are mutually exclusive and specify what type of results
14654 the code block will return.  By default, results are inserted according to the
14655 type as specified above.
14657 @itemize @bullet
14658 @item @code{raw}
14659 The results are interpreted as raw Org mode code and are inserted directly
14660 into the buffer.  If the results look like a table they will be aligned as
14661 such by Org mode.  E.g., @code{:results value raw}.
14662 @item @code{org}
14663 The results are will be enclosed in a @code{BEGIN_SRC org} block.
14664 They are not comma-escaped by default but they will be if you hit @kbd{TAB}
14665 in the block and/or if you export the file.  E.g., @code{:results value org}.
14666 @item @code{html}
14667 Results are assumed to be HTML and will be enclosed in a @code{BEGIN_HTML}
14668 block.  E.g., @code{:results value html}.
14669 @item @code{latex}
14670 Results assumed to be @LaTeX{} and are enclosed in a @code{BEGIN_LaTeX} block.
14671 E.g., @code{:results value latex}.
14672 @item @code{code}
14673 Result are assumed to be parsable code and are enclosed in a code block.
14674 E.g., @code{:results value code}.
14675 @item @code{pp}
14676 The result is converted to pretty-printed code and is enclosed in a code
14677 block.  This option currently supports Emacs Lisp, Python, and Ruby.  E.g.,
14678 @code{:results value pp}.
14679 @item @code{drawer}
14680 The result is wrapped in a RESULTS drawer.  This can be useful for
14681 inserting @code{raw} or @code{org} syntax results in such a way that their
14682 extent is known and they can be automatically removed or replaced.
14683 @end itemize
14685 @subsubheading Handling
14686 The following results options indicate what happens with the
14687 results once they are collected.
14689 @itemize @bullet
14690 @item @code{silent}
14691 The results will be echoed in the minibuffer but will not be inserted into
14692 the Org mode buffer.  E.g., @code{:results output silent}.
14693 @item @code{replace}
14694 The default value.  Any existing results will be removed, and the new results
14695 will be inserted into the Org mode buffer in their place.  E.g.,
14696 @code{:results output replace}.
14697 @item @code{append}
14698 If there are pre-existing results of the code block then the new results will
14699 be appended to the existing results.  Otherwise the new results will be
14700 inserted as with @code{replace}.
14701 @item @code{prepend}
14702 If there are pre-existing results of the code block then the new results will
14703 be prepended to the existing results.  Otherwise the new results will be
14704 inserted as with @code{replace}.
14705 @end itemize
14707 @node file, file-desc, results, Specific header arguments
14708 @subsubsection @code{:file}
14710 The header argument @code{:file} is used to specify an external file in which
14711 to save code block results.  After code block evaluation an Org mode style
14712 @code{[[file:]]} link (see @ref{Link format}) to the file will be inserted
14713 into the Org mode buffer.  Some languages including R, gnuplot, dot, and
14714 ditaa provide special handling of the @code{:file} header argument
14715 automatically wrapping the code block body in the boilerplate code required
14716 to save output to the specified file.  This is often useful for saving
14717 graphical output of a code block to the specified file.
14719 The argument to @code{:file} should be either a string specifying the path to
14720 a file, or a list of two strings in which case the first element of the list
14721 should be the path to a file and the second a description for the link.
14723 @node file-desc, dir, file, Specific header arguments
14724 @subsubsection @code{:file-desc}
14726 The value of the @code{:file-desc} header argument is used to provide a
14727 description for file code block results which are inserted as Org mode links
14728 (see @ref{Link format}).  If the @code{:file-desc} header argument is given
14729 with no value the link path will be placed in both the ``link'' and the
14730 ``description'' portion of the Org mode link.
14732 @node dir, exports, file-desc, Specific header arguments
14733 @subsubsection @code{:dir} and remote execution
14735 While the @code{:file} header argument can be used to specify the path to the
14736 output file, @code{:dir} specifies the default directory during code block
14737 execution.  If it is absent, then the directory associated with the current
14738 buffer is used.  In other words, supplying @code{:dir path} temporarily has
14739 the same effect as changing the current directory with @kbd{M-x cd path RET}, and
14740 then not supplying @code{:dir}.  Under the surface, @code{:dir} simply sets
14741 the value of the Emacs variable @code{default-directory}.
14743 When using @code{:dir}, you should supply a relative path for file output
14744 (e.g., @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
14745 case that path will be interpreted relative to the default directory.
14747 In other words, if you want your plot to go into a folder called @file{Work}
14748 in your home directory, you could use
14750 @example
14751 #+BEGIN_SRC R :file myplot.png :dir ~/Work
14752 matplot(matrix(rnorm(100), 10), type="l")
14753 #+END_SRC
14754 @end example
14756 @subsubheading Remote execution
14757 A directory on a remote machine can be specified using tramp file syntax, in
14758 which case the code will be evaluated on the remote machine.  An example is
14760 @example
14761 #+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu:
14762 plot(1:10, main=system("hostname", intern=TRUE))
14763 #+END_SRC
14764 @end example
14766 Text results will be returned to the local Org mode buffer as usual, and file
14767 output will be created on the remote machine with relative paths interpreted
14768 relative to the remote directory.  An Org mode link to the remote file will be
14769 created.
14771 So, in the above example a plot will be created on the remote machine,
14772 and a link of the following form will be inserted in the org buffer:
14774 @example
14775 [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
14776 @end example
14778 Most of this functionality follows immediately from the fact that @code{:dir}
14779 sets the value of the Emacs variable @code{default-directory}, thanks to
14780 tramp.  Those using XEmacs, or GNU Emacs prior to version 23 may need to
14781 install tramp separately in order for these features to work correctly.
14783 @subsubheading Further points
14785 @itemize @bullet
14786 @item
14787 If @code{:dir} is used in conjunction with @code{:session}, although it will
14788 determine the starting directory for a new session as expected, no attempt is
14789 currently made to alter the directory associated with an existing session.
14790 @item
14791 @code{:dir} should typically not be used to create files during export with
14792 @code{:exports results} or @code{:exports both}.  The reason is that, in order
14793 to retain portability of exported material between machines, during export
14794 links inserted into the buffer will @emph{not} be expanded against @code{default
14795 directory}.  Therefore, if @code{default-directory} is altered using
14796 @code{:dir}, it is probable that the file will be created in a location to
14797 which the link does not point.
14798 @end itemize
14800 @node exports, tangle, dir, Specific header arguments
14801 @subsubsection @code{:exports}
14803 The @code{:exports} header argument specifies what should be included in HTML
14804 or @LaTeX{} exports of the Org mode file.
14806 @itemize @bullet
14807 @item @code{code}
14808 The default.  The body of code is included into the exported file.  E.g.,
14809 @code{:exports code}.
14810 @item @code{results}
14811 The result of evaluating the code is included in the exported file.  E.g.,
14812 @code{:exports results}.
14813 @item @code{both}
14814 Both the code and results are included in the exported file.  E.g.,
14815 @code{:exports both}.
14816 @item @code{none}
14817 Nothing is included in the exported file.  E.g., @code{:exports none}.
14818 @end itemize
14820 @node tangle, mkdirp, exports, Specific header arguments
14821 @subsubsection @code{:tangle}
14823 The @code{:tangle} header argument specifies whether or not the code
14824 block should be included in tangled extraction of source code files.
14826 @itemize @bullet
14827 @item @code{tangle}
14828 The code block is exported to a source code file named after the full path
14829 (including the directory) and file name (w/o extension) of the Org mode file.
14830 E.g., @code{:tangle yes}.
14831 @item @code{no}
14832 The default.  The code block is not exported to a source code file.
14833 E.g., @code{:tangle no}.
14834 @item other
14835 Any other string passed to the @code{:tangle} header argument is interpreted
14836 as a path (directory and file name relative to the directory of the Org mode
14837 file) to which the block will be exported.  E.g., @code{:tangle path}.
14838 @end itemize
14840 @node mkdirp, comments, tangle, Specific header arguments
14841 @subsubsection @code{:mkdirp}
14843 The @code{:mkdirp} header argument can be used to create parent directories
14844 of tangled files when missing.  This can be set to @code{yes} to enable
14845 directory creation or to @code{no} to inhibit directory creation.
14847 @node comments, padline, mkdirp, Specific header arguments
14848 @subsubsection @code{:comments}
14849 By default code blocks are tangled to source-code files without any insertion
14850 of comments beyond those which may already exist in the body of the code
14851 block.  The @code{:comments} header argument can be set as follows to control
14852 the insertion of extra comments into the tangled code file.
14854 @itemize @bullet
14855 @item @code{no}
14856 The default.  No extra comments are inserted during tangling.
14857 @item @code{link}
14858 The code block is wrapped in comments which contain pointers back to the
14859 original Org file from which the code was tangled.
14860 @item @code{yes}
14861 A synonym for ``link'' to maintain backwards compatibility.
14862 @item @code{org}
14863 Include text from the Org mode file as a comment.
14864 The text is picked from the leading context of the tangled code and is
14865 limited by the nearest headline or source block as the case may be.
14866 @item @code{both}
14867 Turns on both the ``link'' and ``org'' comment options.
14868 @item @code{noweb}
14869 Turns on the ``link'' comment option, and additionally wraps expanded noweb
14870 references in the code block body in link comments.
14871 @end itemize
14873 @node padline, no-expand, comments, Specific header arguments
14874 @subsubsection @code{:padline}
14875 Control in insertion of padding lines around code block bodies in tangled
14876 code files.  The default value is @code{yes} which results in insertion of
14877 newlines before and after each tangled code block.  The following arguments
14878 are accepted.
14880 @itemize @bullet
14881 @item @code{yes}
14882 Insert newlines before and after each code block body in tangled code files.
14883 @item @code{no}
14884 Do not insert any newline padding in tangled output.
14885 @end itemize
14887 @node no-expand, session, padline, Specific header arguments
14888 @subsubsection @code{:no-expand}
14890 By default, code blocks are expanded with @code{org-babel-expand-src-block}
14891 during tangling.  This has the effect of assigning values to variables
14892 specified with @code{:var} (see @ref{var}), and of replacing ``noweb''
14893 references (see @ref{Noweb reference syntax}) with their targets.  The
14894 @code{:no-expand} header argument can be used to turn off this behavior.
14896 @node session, noweb, no-expand, Specific header arguments
14897 @subsubsection @code{:session}
14899 The @code{:session} header argument starts a session for an interpreted
14900 language where state is preserved.
14902 By default, a session is not started.
14904 A string passed to the @code{:session} header argument will give the session
14905 a name.  This makes it possible to run concurrent sessions for each
14906 interpreted language.
14908 @node noweb, noweb-ref, session, Specific header arguments
14909 @subsubsection @code{:noweb}
14911 The @code{:noweb} header argument controls expansion of ``noweb'' syntax
14912 references (see @ref{Noweb reference syntax}) when the code block is
14913 evaluated, tangled, or exported.  The @code{:noweb} header argument can have
14914 one of the five values: @code{no}, @code{yes}, @code{tangle}, or
14915 @code{no-export} @code{strip-export}.
14917 @itemize @bullet
14918 @item @code{no}
14919 The default.  ``Noweb'' syntax references in the body of the code block will
14920 not be expanded before the code block is evaluated, tangled or exported.
14921 @item @code{yes}
14922 ``Noweb'' syntax references in the body of the code block will be
14923 expanded before the code block is evaluated, tangled or exported.
14924 @item @code{tangle}
14925 ``Noweb'' syntax references in the body of the code block will be expanded
14926 before the code block is tangled.  However, ``noweb'' syntax references will
14927 not be expanded when the code block is evaluated or exported.
14928 @item @code{no-export}
14929 ``Noweb'' syntax references in the body of the code block will be expanded
14930 before the block is evaluated or tangled.  However, ``noweb'' syntax
14931 references will not be expanded when the code block is exported.
14932 @item @code{strip-export}
14933 ``Noweb'' syntax references in the body of the code block will be expanded
14934 before the block is evaluated or tangled.  However, ``noweb'' syntax
14935 references will be removed when the code block is exported.
14936 @item @code{eval}
14937 ``Noweb'' syntax references in the body of the code block will only be
14938 expanded before the block is evaluated.
14939 @end itemize
14941 @subsubheading Noweb prefix lines
14942 Noweb insertions are now placed behind the line prefix of the
14943 @code{<<reference>>}.
14944 This behavior is illustrated in the following example.  Because the
14945 @code{<<example>>} noweb reference appears behind the SQL comment syntax,
14946 each line of the expanded noweb reference will be commented.
14948 This code block:
14950 @example
14951 -- <<example>>
14952 @end example
14954 expands to:
14956 @example
14957 -- this is the
14958 -- multi-line body of example
14959 @end example
14961 Note that noweb replacement text that does not contain any newlines will not
14962 be affected by this change, so it is still possible to use inline noweb
14963 references.
14965 @node noweb-ref, noweb-sep, noweb, Specific header arguments
14966 @subsubsection @code{:noweb-ref}
14967 When expanding ``noweb'' style references the bodies of all code block with
14968 @emph{either} a block name matching the reference name @emph{or} a
14969 @code{:noweb-ref} header argument matching the reference name will be
14970 concatenated together to form the replacement text.
14972 By setting this header argument at the sub-tree or file level, simple code
14973 block concatenation may be achieved.  For example, when tangling the
14974 following Org mode file, the bodies of code blocks will be concatenated into
14975 the resulting pure code file@footnote{(The example needs property inheritance
14976 to be turned on for the @code{noweb-ref} property, see @ref{Property
14977 inheritance}).}.
14979 @example
14980  #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
14981    <<fullest-disk>>
14982  #+END_SRC
14983  * the mount point of the fullest disk
14984    :PROPERTIES:
14985    :noweb-ref: fullest-disk
14986    :END:
14988  ** query all mounted disks
14989  #+BEGIN_SRC sh
14990    df \
14991  #+END_SRC
14993  ** strip the header row
14994  #+BEGIN_SRC sh
14995    |sed '1d' \
14996  #+END_SRC
14998  ** sort by the percent full
14999  #+BEGIN_SRC sh
15000    |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
15001  #+END_SRC
15003  ** extract the mount point
15004  #+BEGIN_SRC sh
15005    |awk '@{print $2@}'
15006  #+END_SRC
15007 @end example
15009 The @code{:noweb-sep} (see @ref{noweb-sep}) header argument holds the string
15010 used to separate accumulate noweb references like those above.  By default a
15011 newline is used.
15013 @node noweb-sep, cache, noweb-ref, Specific header arguments
15014 @subsubsection @code{:noweb-sep}
15016 The @code{:noweb-sep} header argument holds the string used to separate
15017 accumulate noweb references (see @ref{noweb-ref}).  By default a newline is
15018 used.
15020 @node cache, sep, noweb-sep, Specific header arguments
15021 @subsubsection @code{:cache}
15023 The @code{:cache} header argument controls the use of in-buffer caching of
15024 the results of evaluating code blocks.  It can be used to avoid re-evaluating
15025 unchanged code blocks.  Note that the @code{:cache} header argument will not
15026 attempt to cache results when the @code{:session} header argument is used,
15027 because the results of the code block execution may be stored in the session
15028 outside of the Org mode buffer.  The @code{:cache} header argument can have
15029 one of two values: @code{yes} or @code{no}.
15031 @itemize @bullet
15032 @item @code{no}
15033 The default.  No caching takes place, and the code block will be evaluated
15034 every time it is called.
15035 @item @code{yes}
15036 Every time the code block is run a SHA1 hash of the code and arguments
15037 passed to the block will be generated.  This hash is packed into the
15038 @code{#+RESULTS:} line and will be checked on subsequent
15039 executions of the code block.  If the code block has not
15040 changed since the last time it was evaluated, it will not be re-evaluated.
15041 @end itemize
15043 Code block caches notice if the value of a variable argument
15044 to the code block has changed.  If this is the case, the cache is
15045 invalidated and the code block is re-run.  In the following example,
15046 @code{caller} will not be re-run unless the results of @code{random} have
15047 changed since it was last run.
15049 @example
15050  #+NAME: random
15051  #+BEGIN_SRC R :cache yes
15052  runif(1)
15053  #+END_SRC
15055  #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
15056  0.4659510825295
15058  #+NAME: caller
15059  #+BEGIN_SRC emacs-lisp :var x=random :cache yes
15061  #+END_SRC
15063  #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
15064  0.254227238707244
15065 @end example
15067 @node sep, hlines, cache, Specific header arguments
15068 @subsubsection @code{:sep}
15070 The @code{:sep} header argument can be used to control the delimiter used
15071 when writing tabular results out to files external to Org mode.  This is used
15072 either when opening tabular results of a code block by calling the
15073 @code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block,
15074 or when writing code block results to an external file (see @ref{file})
15075 header argument.
15077 By default, when @code{:sep} is not specified output tables are tab
15078 delimited.
15080 @node hlines, colnames, sep, Specific header arguments
15081 @subsubsection @code{:hlines}
15083 Tables are frequently represented with one or more horizontal lines, or
15084 hlines.  The @code{:hlines} argument to a code block accepts the
15085 values @code{yes} or @code{no}, with a default value of @code{no}.
15087 @itemize @bullet
15088 @item @code{no}
15089 Strips horizontal lines from the input table.  In most languages this is the
15090 desired effect because an @code{hline} symbol is interpreted as an unbound
15091 variable and raises an error.  Setting @code{:hlines no} or relying on the
15092 default value yields the following results.
15094 @example
15095 #+NAME: many-cols
15096 | a | b | c |
15097 |---+---+---|
15098 | d | e | f |
15099 |---+---+---|
15100 | g | h | i |
15102 #+NAME: echo-table
15103 #+BEGIN_SRC python :var tab=many-cols
15104   return tab
15105 #+END_SRC
15107 #+RESULTS: echo-table
15108 | a | b | c |
15109 | d | e | f |
15110 | g | h | i |
15111 @end example
15113 @item @code{yes}
15114 Leaves hlines in the table.  Setting @code{:hlines yes} has this effect.
15116 @example
15117 #+NAME: many-cols
15118 | a | b | c |
15119 |---+---+---|
15120 | d | e | f |
15121 |---+---+---|
15122 | g | h | i |
15124 #+NAME: echo-table
15125 #+BEGIN_SRC python :var tab=many-cols :hlines yes
15126   return tab
15127 #+END_SRC
15129 #+RESULTS: echo-table
15130 | a | b | c |
15131 |---+---+---|
15132 | d | e | f |
15133 |---+---+---|
15134 | g | h | i |
15135 @end example
15136 @end itemize
15138 @node colnames, rownames, hlines, Specific header arguments
15139 @subsubsection @code{:colnames}
15141 The @code{:colnames} header argument accepts the values @code{yes},
15142 @code{no}, or @code{nil} for unassigned.  The default value is @code{nil}.
15143 Note that the behavior of the @code{:colnames} header argument may differ
15144 across languages.
15146 @itemize @bullet
15147 @item @code{nil}
15148 If an input table looks like it has column names
15149 (because its second row is an hline), then the column
15150 names will be removed from the table before
15151 processing, then reapplied to the results.
15153 @example
15154 #+NAME: less-cols
15155 | a |
15156 |---|
15157 | b |
15158 | c |
15160 #+NAME: echo-table-again
15161 #+BEGIN_SRC python :var tab=less-cols
15162   return [[val + '*' for val in row] for row in tab]
15163 #+END_SRC
15165 #+RESULTS: echo-table-again
15166 | a  |
15167 |----|
15168 | b* |
15169 | c* |
15170 @end example
15172 Please note that column names are not removed before the table is indexed
15173 using variable indexing @xref{var, Indexable variable values}.
15175 @item @code{no}
15176 No column name pre-processing takes place
15178 @item @code{yes}
15179 Column names are removed and reapplied as with @code{nil} even if the table
15180 does not ``look like'' it has column names (i.e., the second row is not an
15181 hline)
15182 @end itemize
15184 @node rownames, shebang, colnames, Specific header arguments
15185 @subsubsection @code{:rownames}
15187 The @code{:rownames} header argument can take on the values @code{yes} or
15188 @code{no}, with a default value of @code{no}.  Note that Emacs Lisp code
15189 blocks ignore the @code{:rownames} header argument entirely given the ease
15190 with which tables with row names may be handled directly in Emacs Lisp.
15192 @itemize @bullet
15193 @item @code{no}
15194 No row name pre-processing will take place.
15196 @item @code{yes}
15197 The first column of the table is removed from the table before processing,
15198 and is then reapplied to the results.
15200 @example
15201 #+NAME: with-rownames
15202 | one | 1 | 2 | 3 | 4 |  5 |
15203 | two | 6 | 7 | 8 | 9 | 10 |
15205 #+NAME: echo-table-once-again
15206 #+BEGIN_SRC python :var tab=with-rownames :rownames yes
15207   return [[val + 10 for val in row] for row in tab]
15208 #+END_SRC
15210 #+RESULTS: echo-table-once-again
15211 | one | 11 | 12 | 13 | 14 | 15 |
15212 | two | 16 | 17 | 18 | 19 | 20 |
15213 @end example
15215 Please note that row names are not removed before the table is indexed using
15216 variable indexing @xref{var, Indexable variable values}.
15218 @end itemize
15220 @node shebang, tangle-mode, rownames, Specific header arguments
15221 @subsubsection @code{:shebang}
15223 Setting the @code{:shebang} header argument to a string value
15224 (e.g., @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the
15225 first line of any tangled file holding the code block, and the file
15226 permissions of the tangled file are set to make it executable.
15229 @node tangle-mode, eval, shebang, Specific header arguments
15230 @subsubsection @code{:tangle-mode}
15232 The @code{tangle-mode} header argument controls the permission set on tangled
15233 files.  The value of this header argument will be passed to
15234 @code{set-file-modes}.  For example, to set a tangled file as read only use
15235 @code{:tangle-mode (identity #o444)}, or to set a tangled file as executable
15236 use @code{:tangle-mode (identity #o755)}.  Blocks with @code{shebang}
15237 (@ref{shebang}) header arguments will automatically be made executable unless
15238 the @code{tangle-mode} header argument is also used.  The behavior is
15239 undefined if multiple code blocks with different values for the
15240 @code{tangle-mode} header argument are tangled to the same file.
15242 @node eval, wrap, tangle-mode, Specific header arguments
15243 @subsubsection @code{:eval}
15244 The @code{:eval} header argument can be used to limit the evaluation of
15245 specific code blocks.  The @code{:eval} header argument can be useful for
15246 protecting against the evaluation of dangerous code blocks or to ensure that
15247 evaluation will require a query regardless of the value of the
15248 @code{org-confirm-babel-evaluate} variable.  The possible values of
15249 @code{:eval} and their effects are shown below.
15251 @table @code
15252 @item never or no
15253 The code block will not be evaluated under any circumstances.
15254 @item query
15255 Evaluation of the code block will require a query.
15256 @item never-export or no-export
15257 The code block will not be evaluated during export but may still be called
15258 interactively.
15259 @item query-export
15260 Evaluation of the code block during export will require a query.
15261 @end table
15263 If this header argument is not set then evaluation is determined by the value
15264 of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation
15265 security}.
15267 @node wrap, post, eval, Specific header arguments
15268 @subsubsection @code{:wrap}
15269 The @code{:wrap} header argument is used to mark the results of source block
15270 evaluation.  The header argument can be passed a string that will be appended
15271 to @code{#+BEGIN_} and @code{#+END_}, which will then be used to wrap the
15272 results.  If not string is specified then the results will be wrapped in a
15273 @code{#+BEGIN/END_RESULTS} block.
15275 @node post, prologue, wrap, Specific header arguments
15276 @subsubsection @code{:post}
15277 The @code{:post} header argument is used to post-process the results of a
15278 code block execution.  When a post argument is given, the results of the code
15279 block will temporarily be bound to the @code{*this*} variable.  This variable
15280 may then be included in header argument forms such as those used in @ref{var}
15281 header argument specifications allowing passing of results to other code
15282 blocks, or direct execution via Emacs Lisp.
15284 The following example illustrates the usage of the @code{:post} header
15285 argument.
15287 @example
15288 #+name: attr_wrap
15289 #+begin_src sh :var data="" :var width="\\textwidth" :results output
15290   echo "#+ATTR_LATEX :width $width"
15291   echo "$data"
15292 #+end_src
15294 #+header: :file /tmp/it.png
15295 #+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer
15296   digraph@{
15297           a -> b;
15298           b -> c;
15299           c -> a;
15300   @}
15301 #+end_src
15303 #+RESULTS:
15304 :RESULTS:
15305 #+ATTR_LATEX :width 5cm
15306 [[file:/tmp/it.png]]
15307 :END:
15308 @end example
15310 @node prologue, epilogue, post, Specific header arguments
15311 @subsubsection @code{:prologue}
15312 The value of the @code{prologue} header argument will be prepended to the
15313 code block body before execution.  For example, @code{:prologue "reset"} may
15314 be used to reset a gnuplot session before execution of a particular code
15315 block, or the following configuration may be used to do this for all gnuplot
15316 code blocks.  Also see @ref{epilogue}.
15318 @lisp
15319 (add-to-list 'org-babel-default-header-args:gnuplot
15320              '((:prologue . "reset")))
15321 @end lisp
15323 @node epilogue, , prologue, Specific header arguments
15324 @subsubsection @code{:epilogue}
15325 The value of the @code{epilogue} header argument will be appended to the code
15326 block body before execution.  Also see @ref{prologue}.
15328 @node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code
15329 @section Results of evaluation
15330 @cindex code block, results of evaluation
15331 @cindex source code, results of evaluation
15333 The way in which results are handled depends on whether a session is invoked,
15334 as well as on whether @code{:results value} or @code{:results output} is
15335 used.  The following table shows the table possibilities.  For a full listing
15336 of the possible results header arguments see @ref{results}.
15338 @multitable @columnfractions 0.26 0.33 0.41
15339 @item @tab @b{Non-session} @tab @b{Session}
15340 @item @code{:results value} @tab value of last expression @tab value of last expression
15341 @item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output
15342 @end multitable
15344 Note: With @code{:results value}, the result in both @code{:session} and
15345 non-session is returned to Org mode as a table (a one- or two-dimensional
15346 vector of strings or numbers) when appropriate.
15348 @subsection Non-session
15349 @subsubsection @code{:results value}
15350 This is the default.  Internally, the value is obtained by wrapping the code
15351 in a function definition in the external language, and evaluating that
15352 function.  Therefore, code should be written as if it were the body of such a
15353 function.  In particular, note that Python does not automatically return a
15354 value from a function unless a @code{return} statement is present, and so a
15355 @samp{return} statement will usually be required in Python.
15357 This is the only one of the four evaluation contexts in which the code is
15358 automatically wrapped in a function definition.
15360 @subsubsection @code{:results output}
15361 The code is passed to the interpreter as an external process, and the
15362 contents of the standard output stream are returned as text.  (In certain
15363 languages this also contains the error output stream; this is an area for
15364 future work.)
15366 @subsection Session
15367 @subsubsection @code{:results value}
15368 The code is passed to an interpreter running as an interactive Emacs inferior
15369 process.  Only languages which provide tools for interactive evaluation of
15370 code have session support, so some language (e.g., C and ditaa) do not
15371 support the @code{:session} header argument, and in other languages (e.g.,
15372 Python and Haskell) which have limitations on the code which may be entered
15373 into interactive sessions, those limitations apply to the code in code blocks
15374 using the @code{:session} header argument as well.
15376 Unless the @code{:results output} option is supplied (see below) the result
15377 returned is the result of the last evaluation performed by the
15378 interpreter.  (This is obtained in a language-specific manner: the value of
15379 the variable @code{_} in Python and Ruby, and the value of @code{.Last.value}
15380 in R).
15382 @subsubsection @code{:results output}
15383 The code is passed to the interpreter running as an interactive Emacs
15384 inferior process.  The result returned is the concatenation of the sequence of
15385 (text) output from the interactive interpreter.  Notice that this is not
15386 necessarily the same as what would be sent to @code{STDOUT} if the same code
15387 were passed to a non-interactive interpreter running as an external
15388 process.  For example, compare the following two blocks:
15390 @example
15391 #+BEGIN_SRC python :results output
15392  print "hello"
15394  print "bye"
15395 #+END_SRC
15397 #+RESULTS:
15398 : hello
15399 : bye
15400 @end example
15402 In non-session mode, the `2' is not printed and does not appear.
15404 @example
15405 #+BEGIN_SRC python :results output :session
15406  print "hello"
15408  print "bye"
15409 #+END_SRC
15411 #+RESULTS:
15412 : hello
15413 : 2
15414 : bye
15415 @end example
15417 But in @code{:session} mode, the interactive interpreter receives input `2'
15418 and prints out its value, `2'.  (Indeed, the other print statements are
15419 unnecessary here).
15421 @node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code
15422 @section Noweb reference syntax
15423 @cindex code block, noweb reference
15424 @cindex syntax, noweb
15425 @cindex source code, noweb reference
15427 The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate
15428 Programming system allows named blocks of code to be referenced by using the
15429 familiar Noweb syntax:
15431 @example
15432 <<code-block-name>>
15433 @end example
15435 When a code block is tangled or evaluated, whether or not ``noweb''
15436 references are expanded depends upon the value of the @code{:noweb} header
15437 argument.  If @code{:noweb yes}, then a Noweb reference is expanded before
15438 evaluation.  If @code{:noweb no}, the default, then the reference is not
15439 expanded before evaluation.  See the @ref{noweb-ref} header argument for
15440 a more flexible way to resolve noweb references.
15442 It is possible to include the @emph{results} of a code block rather than the
15443 body.  This is done by appending parenthesis to the code block name which may
15444 optionally contain arguments to the code block as shown below.
15446 @example
15447 <<code-block-name(optional arguments)>>
15448 @end example
15450 Note: the default value, @code{:noweb no}, was chosen to ensure that
15451 correct code is not broken in a language, such as Ruby, where
15452 @code{<<arg>>} is a syntactically valid construct.  If @code{<<arg>>} is not
15453 syntactically valid in languages that you use, then please consider setting
15454 the default value.
15456 Note: if noweb tangling is slow in large Org mode files consider setting the
15457 @code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}.
15458 This will result in faster noweb reference resolution at the expense of not
15459 correctly resolving inherited values of the @code{:noweb-ref} header
15460 argument.
15462 @node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code
15463 @section Key bindings and useful functions
15464 @cindex code block, key bindings
15466 Many common Org mode key sequences are re-bound depending on
15467 the context.
15469 Within a code block, the following key bindings
15470 are active:
15472 @multitable @columnfractions 0.25 0.75
15473 @kindex C-c C-c
15474 @item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block}
15475 @kindex C-c C-o
15476 @item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result}
15477 @kindex C-up
15478 @item @kbd{C-@key{up}}    @tab @code{org-babel-load-in-session}
15479 @kindex M-down
15480 @item @kbd{M-@key{down}}  @tab @code{org-babel-pop-to-session}
15481 @end multitable
15483 In an Org mode buffer, the following key bindings are active:
15485 @multitable @columnfractions 0.45 0.55
15486 @kindex C-c C-v p
15487 @kindex C-c C-v C-p
15488 @item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block}
15489 @kindex C-c C-v n
15490 @kindex C-c C-v C-n
15491 @item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block}
15492 @kindex C-c C-v e
15493 @kindex C-c C-v C-e
15494 @item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe}
15495 @kindex C-c C-v o
15496 @kindex C-c C-v C-o
15497 @item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result}
15498 @kindex C-c C-v v
15499 @kindex C-c C-v C-v
15500 @item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block}
15501 @kindex C-c C-v u
15502 @kindex C-c C-v C-u
15503 @item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head}
15504 @kindex C-c C-v g
15505 @kindex C-c C-v C-g
15506 @item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block}
15507 @kindex C-c C-v r
15508 @kindex C-c C-v C-r
15509 @item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result}
15510 @kindex C-c C-v b
15511 @kindex C-c C-v C-b
15512 @item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
15513 @kindex C-c C-v s
15514 @kindex C-c C-v C-s
15515 @item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
15516 @kindex C-c C-v d
15517 @kindex C-c C-v C-d
15518 @item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block}
15519 @kindex C-c C-v t
15520 @kindex C-c C-v C-t
15521 @item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
15522 @kindex C-c C-v f
15523 @kindex C-c C-v C-f
15524 @item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
15525 @kindex C-c C-v c
15526 @kindex C-c C-v C-c
15527 @item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block}
15528 @kindex C-c C-v j
15529 @kindex C-c C-v C-j
15530 @item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg}
15531 @kindex C-c C-v l
15532 @kindex C-c C-v C-l
15533 @item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session}
15534 @kindex C-c C-v i
15535 @kindex C-c C-v C-i
15536 @item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest}
15537 @kindex C-c C-v I
15538 @kindex C-c C-v C-I
15539 @item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info}
15540 @kindex C-c C-v z
15541 @kindex C-c C-v C-z
15542 @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}
15543 @kindex C-c C-v a
15544 @kindex C-c C-v C-a
15545 @item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
15546 @kindex C-c C-v h
15547 @kindex C-c C-v C-h
15548 @item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings}
15549 @kindex C-c C-v x
15550 @kindex C-c C-v C-x
15551 @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}
15552 @end multitable
15554 @c When possible these keybindings were extended to work when the control key is
15555 @c kept pressed, resulting in the following additional keybindings.
15557 @c @multitable @columnfractions 0.25 0.75
15558 @c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
15559 @c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
15560 @c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
15561 @c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
15562 @c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
15563 @c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
15564 @c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
15565 @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
15566 @c @end multitable
15568 @node Batch execution,  , Key bindings and useful functions, Working With Source Code
15569 @section Batch execution
15570 @cindex code block, batch execution
15571 @cindex source code, batch execution
15573 It is possible to call functions from the command line.  This shell
15574 script calls @code{org-babel-tangle} on every one of its arguments.
15576 Be sure to adjust the paths to fit your system.
15578 @example
15579 #!/bin/sh
15580 # -*- mode: shell-script -*-
15582 # tangle files with org-mode
15584 DIR=`pwd`
15585 FILES=""
15587 # wrap each argument in the code required to call tangle on it
15588 for i in $@@; do
15589     FILES="$FILES \"$i\""
15590 done
15592 emacs -Q --batch \
15593 --eval "(progn
15594 (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
15595 (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\" t))
15596 (require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
15597 (mapc (lambda (file)
15598        (find-file (expand-file-name file \"$DIR\"))
15599        (org-babel-tangle)
15600        (kill-buffer)) '($FILES)))" 2>&1 |grep tangled
15601 @end example
15603 @node Miscellaneous, Hacking, Working With Source Code, Top
15604 @chapter Miscellaneous
15606 @menu
15607 * Completion::                  M-TAB knows what you need
15608 * Easy Templates::              Quick insertion of structural elements
15609 * Speed keys::                  Electric commands at the beginning of a headline
15610 * Code evaluation security::    Org mode files evaluate inline code
15611 * Customization::               Adapting Org to your taste
15612 * In-buffer settings::          Overview of the #+KEYWORDS
15613 * The very busy C-c C-c key::   When in doubt, press C-c C-c
15614 * Clean view::                  Getting rid of leading stars in the outline
15615 * TTY keys::                    Using Org on a tty
15616 * Interaction::                 Other Emacs packages
15617 * org-crypt::                   Encrypting Org files
15618 @end menu
15621 @node Completion, Easy Templates, Miscellaneous, Miscellaneous
15622 @section Completion
15623 @cindex completion, of @TeX{} symbols
15624 @cindex completion, of TODO keywords
15625 @cindex completion, of dictionary words
15626 @cindex completion, of option keywords
15627 @cindex completion, of tags
15628 @cindex completion, of property keys
15629 @cindex completion, of link abbreviations
15630 @cindex @TeX{} symbol completion
15631 @cindex TODO keywords completion
15632 @cindex dictionary word completion
15633 @cindex option keyword completion
15634 @cindex tag completion
15635 @cindex link abbreviations, completion of
15637 Emacs would not be Emacs without completion, and Org mode uses it whenever it
15638 makes sense.  If you prefer an @i{iswitchb}- or @i{ido}-like interface for
15639 some of the completion prompts, you can specify your preference by setting at
15640 most one of the variables @code{org-completion-use-iswitchb}
15641 @code{org-completion-use-ido}.
15643 Org supports in-buffer completion.  This type of completion does
15644 not make use of the minibuffer.  You simply type a few letters into
15645 the buffer and use the key to complete text right there.
15647 @table @kbd
15648 @kindex M-@key{TAB}
15649 @item M-@key{TAB}
15650 Complete word at point
15651 @itemize @bullet
15652 @item
15653 At the beginning of a headline, complete TODO keywords.
15654 @item
15655 After @samp{\}, complete @TeX{} symbols supported by the exporter.
15656 @item
15657 After @samp{*}, complete headlines in the current buffer so that they
15658 can be used in search links like @samp{[[*find this headline]]}.
15659 @item
15660 After @samp{:} in a headline, complete tags.  The list of tags is taken
15661 from the variable @code{org-tag-alist} (possibly set through the
15662 @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
15663 dynamically from all tags used in the current buffer.
15664 @item
15665 After @samp{:} and not in a headline, complete property keys.  The list
15666 of keys is constructed dynamically from all keys used in the current
15667 buffer.
15668 @item
15669 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
15670 @item
15671 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
15672 @samp{OPTIONS} which set file-specific options for Org mode.  When the
15673 option keyword is already complete, pressing @kbd{M-@key{TAB}} again
15674 will insert example settings for this keyword.
15675 @item
15676 In the line after @samp{#+STARTUP: }, complete startup keywords,
15677 i.e., valid keys for this line.
15678 @item
15679 Elsewhere, complete dictionary words using Ispell.
15680 @end itemize
15681 @end table
15683 @node Easy Templates, Speed keys, Completion, Miscellaneous
15684 @section Easy Templates
15685 @cindex template insertion
15686 @cindex insertion, of templates
15688 Org mode supports insertion of empty structural elements (like
15689 @code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key
15690 strokes.  This is achieved through a native template expansion mechanism.
15691 Note that Emacs has several other template mechanisms which could be used in
15692 a similar way, for example @file{yasnippet}.
15694 To insert a structural element, type a @samp{<}, followed by a template
15695 selector and @kbd{@key{TAB}}.  Completion takes effect only when the above
15696 keystrokes are typed on a line by itself.
15698 The following template selectors are currently supported.
15700 @multitable @columnfractions 0.1 0.9
15701 @item @kbd{s} @tab @code{#+BEGIN_SRC     ... #+END_SRC}
15702 @item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
15703 @item @kbd{q} @tab @code{#+BEGIN_QUOTE   ... #+END_QUOTE}
15704 @item @kbd{v} @tab @code{#+BEGIN_VERSE   ... #+END_VERSE}
15705 @item @kbd{c} @tab @code{#+BEGIN_CENTER  ... #+END_CENTER}
15706 @item @kbd{l} @tab @code{#+BEGIN_LaTeX   ... #+END_LaTeX}
15707 @item @kbd{L} @tab @code{#+LaTeX:}
15708 @item @kbd{h} @tab @code{#+BEGIN_HTML    ... #+END_HTML}
15709 @item @kbd{H} @tab @code{#+HTML:}
15710 @item @kbd{a} @tab @code{#+BEGIN_ASCII   ... #+END_ASCII}
15711 @item @kbd{A} @tab @code{#+ASCII:}
15712 @item @kbd{i} @tab @code{#+INDEX:} line
15713 @item @kbd{I} @tab @code{#+INCLUDE:} line
15714 @end multitable
15716 For example, on an empty line, typing "<e" and then pressing TAB, will expand
15717 into a complete EXAMPLE template.
15719 You can install additional templates by customizing the variable
15720 @code{org-structure-template-alist}.  See the docstring of the variable for
15721 additional details.
15723 @node Speed keys, Code evaluation security, Easy Templates, Miscellaneous
15724 @section Speed keys
15725 @cindex speed keys
15726 @vindex org-use-speed-commands
15727 @vindex org-speed-commands-user
15729 Single keys can be made to execute commands when the cursor is at the
15730 beginning of a headline, i.e., before the first star.  Configure the variable
15731 @code{org-use-speed-commands} to activate this feature.  There is a
15732 pre-defined list of commands, and you can add more such commands using the
15733 variable @code{org-speed-commands-user}.  Speed keys do not only speed up
15734 navigation and other commands, but they also provide an alternative way to
15735 execute commands bound to keys that are not or not easily available on a TTY,
15736 or on a small mobile device with a limited keyboard.
15738 To see which commands are available, activate the feature and press @kbd{?}
15739 with the cursor at the beginning of a headline.
15741 @node Code evaluation security, Customization, Speed keys, Miscellaneous
15742 @section Code evaluation and security issues
15744 Org provides tools to work with the code snippets, including evaluating them.
15746 Running code on your machine always comes with a security risk.  Badly
15747 written or malicious code can be executed on purpose or by accident.  Org has
15748 default settings which will only evaluate such code if you give explicit
15749 permission to do so, and as a casual user of these features you should leave
15750 these precautions intact.
15752 For people who regularly work with such code, the confirmation prompts can
15753 become annoying, and you might want to turn them off.  This can be done, but
15754 you must be aware of the risks that are involved.
15756 Code evaluation can happen under the following circumstances:
15758 @table @i
15759 @item Source code blocks
15760 Source code blocks can be evaluated during export, or when pressing @kbd{C-c
15761 C-c} in the block.  The most important thing to realize here is that Org mode
15762 files which contain code snippets are, in a certain sense, like executable
15763 files.  So you should accept them and load them into Emacs only from trusted
15764 sources---just like you would do with a program you install on your computer.
15766 Make sure you know what you are doing before customizing the variables
15767 which take off the default security brakes.
15769 @defopt org-confirm-babel-evaluate
15770 When t (the default), the user is asked before every code block evaluation.
15771 When @code{nil}, the user is not asked.  When set to a function, it is called with
15772 two arguments (language and body of the code block) and should return t to
15773 ask and @code{nil} not to ask.
15774 @end defopt
15776 For example, here is how to execute "ditaa" code (which is considered safe)
15777 without asking:
15779 @lisp
15780 (defun my-org-confirm-babel-evaluate (lang body)
15781   (not (string= lang "ditaa")))  ; don't ask for ditaa
15782 (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
15783 @end lisp
15785 @item Following @code{shell} and @code{elisp} links
15786 Org has two link types that can directly evaluate code (@pxref{External
15787 links}).  These links can be problematic because the code to be evaluated is
15788 not visible.
15790 @defopt org-confirm-shell-link-function
15791 Function to queries user about shell link execution.
15792 @end defopt
15793 @defopt org-confirm-elisp-link-function
15794 Functions to query user for Emacs Lisp link execution.
15795 @end defopt
15797 @item Formulas in tables
15798 Formulas in tables (@pxref{The spreadsheet}) are code that is evaluated
15799 either by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter.
15800 @end table
15802 @node Customization, In-buffer settings, Code evaluation security, Miscellaneous
15803 @section Customization
15804 @cindex customization
15805 @cindex options, for customization
15806 @cindex variables, for customization
15808 There are more than 500 variables that can be used to customize
15809 Org.  For the sake of compactness of the manual, I am not
15810 describing the variables here.  A structured overview of customization
15811 variables is available with @kbd{M-x org-customize RET}.  Or select
15812 @code{Browse Org Group} from the @code{Org->Customization} menu.  Many
15813 settings can also be activated on a per-file basis, by putting special
15814 lines into the buffer (@pxref{In-buffer settings}).
15816 @node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
15817 @section Summary of in-buffer settings
15818 @cindex in-buffer settings
15819 @cindex special keywords
15821 Org mode uses special lines in the buffer to define settings on a
15822 per-file basis.  These lines start with a @samp{#+} followed by a
15823 keyword, a colon, and then individual words defining a setting.  Several
15824 setting words can be in the same line, but you can also have multiple
15825 lines for the keyword.  While these settings are described throughout
15826 the manual, here is a summary.  After changing any of those lines in the
15827 buffer, press @kbd{C-c C-c} with the cursor still in the line to
15828 activate the changes immediately.  Otherwise they become effective only
15829 when the file is visited again in a new Emacs session.
15831 @vindex org-archive-location
15832 @table @kbd
15833 @item #+ARCHIVE: %s_done::
15834 This line sets the archive location for the agenda file.  It applies for
15835 all subsequent lines until the next @samp{#+ARCHIVE} line, or the end
15836 of the file.  The first such line also applies to any entries before it.
15837 The corresponding variable is @code{org-archive-location}.
15838 @item #+CATEGORY:
15839 This line sets the category for the agenda file.  The category applies
15840 for all subsequent lines until the next @samp{#+CATEGORY} line, or the
15841 end of the file.  The first such line also applies to any entries before it.
15842 @item #+COLUMNS: %25ITEM ...
15843 @cindex property, COLUMNS
15844 Set the default format for columns view.  This format applies when
15845 columns view is invoked in locations where no @code{COLUMNS} property
15846 applies.
15847 @item #+CONSTANTS: name1=value1 ...
15848 @vindex org-table-formula-constants
15849 @vindex org-table-formula
15850 Set file-local values for constants to be used in table formulas.  This
15851 line sets the local variable @code{org-table-formula-constants-local}.
15852 The global version of this variable is
15853 @code{org-table-formula-constants}.
15854 @item #+FILETAGS: :tag1:tag2:tag3:
15855 Set tags that can be inherited by any entry in the file, including the
15856 top-level entries.
15857 @item #+DRAWERS: NAME1 ...
15858 @vindex org-drawers
15859 Set the file-local set of additional drawers.  The corresponding global
15860 variable is @code{org-drawers}.
15861 @item #+LINK: linkword replace
15862 @vindex org-link-abbrev-alist
15863 These lines (several are allowed) specify link abbreviations.
15864 @xref{Link abbreviations}.  The corresponding variable is
15865 @code{org-link-abbrev-alist}.
15866 @item #+PRIORITIES: highest lowest default
15867 @vindex org-highest-priority
15868 @vindex org-lowest-priority
15869 @vindex org-default-priority
15870 This line sets the limits and the default for the priorities.  All three
15871 must be either letters A--Z or numbers 0--9.  The highest priority must
15872 have a lower ASCII number than the lowest priority.
15873 @item #+PROPERTY: Property_Name Value
15874 This line sets a default inheritance value for entries in the current
15875 buffer, most useful for specifying the allowed values of a property.
15876 @cindex #+SETUPFILE
15877 @item #+SETUPFILE: file
15878 This line defines a file that holds more in-buffer setup.  Normally this is
15879 entirely ignored.  Only when the buffer is parsed for option-setting lines
15880 (i.e., when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
15881 settings line, or when exporting), then the contents of this file are parsed
15882 as if they had been included in the buffer.  In particular, the file can be
15883 any other Org mode file with internal setup.  You can visit the file the
15884 cursor is in the line with @kbd{C-c '}.
15885 @item #+STARTUP:
15886 @cindex #+STARTUP
15887 This line sets options to be used at startup of Org mode, when an
15888 Org file is being visited.
15890 The first set of options deals with the initial visibility of the outline
15891 tree.  The corresponding variable for global default settings is
15892 @code{org-startup-folded}, with a default value @code{t}, which means
15893 @code{overview}.
15894 @vindex org-startup-folded
15895 @cindex @code{overview}, STARTUP keyword
15896 @cindex @code{content}, STARTUP keyword
15897 @cindex @code{showall}, STARTUP keyword
15898 @cindex @code{showeverything}, STARTUP keyword
15899 @example
15900 overview         @r{top-level headlines only}
15901 content          @r{all headlines}
15902 showall          @r{no folding of any entries}
15903 showeverything   @r{show even drawer contents}
15904 @end example
15906 @vindex org-startup-indented
15907 @cindex @code{indent}, STARTUP keyword
15908 @cindex @code{noindent}, STARTUP keyword
15909 Dynamic virtual indentation is controlled by the variable
15910 @code{org-startup-indented}@footnote{Emacs 23 and Org mode 6.29 are required}
15911 @example
15912 indent     @r{start with @code{org-indent-mode} turned on}
15913 noindent   @r{start with @code{org-indent-mode} turned off}
15914 @end example
15916 @vindex org-startup-align-all-tables
15917 Then there are options for aligning tables upon visiting a file.  This
15918 is useful in files containing narrowed table columns.  The corresponding
15919 variable is @code{org-startup-align-all-tables}, with a default value
15920 @code{nil}.
15921 @cindex @code{align}, STARTUP keyword
15922 @cindex @code{noalign}, STARTUP keyword
15923 @example
15924 align      @r{align all tables}
15925 noalign    @r{don't align tables on startup}
15926 @end example
15928 @vindex org-startup-with-inline-images
15929 When visiting a file, inline images can be automatically displayed.  The
15930 corresponding variable is @code{org-startup-with-inline-images}, with a
15931 default value @code{nil} to avoid delays when visiting a file.
15932 @cindex @code{inlineimages}, STARTUP keyword
15933 @cindex @code{noinlineimages}, STARTUP keyword
15934 @example
15935 inlineimages   @r{show inline images}
15936 noinlineimages @r{don't show inline images on startup}
15937 @end example
15939 @vindex org-startup-with-latex-preview
15940 When visiting a file, @LaTeX{} fragments can be converted to images
15941 automatically.  The variable @code{org-startup-with-latex-preview} which
15942 controls this behavior, is set to @code{nil} by default to avoid delays on
15943 startup.
15944 @cindex @code{latexpreview}, STARTUP keyword
15945 @cindex @code{nolatexpreview}, STARTUP keyword
15946 @example
15947 latexpreview   @r{preview @LaTeX{} fragments}
15948 nolatexpreview @r{don't preview @LaTeX{} fragments}
15949 @end example
15951 @vindex org-log-done
15952 @vindex org-log-note-clock-out
15953 @vindex org-log-repeat
15954 Logging the closing and reopening of TODO items and clock intervals can be
15955 configured using these options (see variables @code{org-log-done},
15956 @code{org-log-note-clock-out} and @code{org-log-repeat})
15957 @cindex @code{logdone}, STARTUP keyword
15958 @cindex @code{lognotedone}, STARTUP keyword
15959 @cindex @code{nologdone}, STARTUP keyword
15960 @cindex @code{lognoteclock-out}, STARTUP keyword
15961 @cindex @code{nolognoteclock-out}, STARTUP keyword
15962 @cindex @code{logrepeat}, STARTUP keyword
15963 @cindex @code{lognoterepeat}, STARTUP keyword
15964 @cindex @code{nologrepeat}, STARTUP keyword
15965 @cindex @code{logreschedule}, STARTUP keyword
15966 @cindex @code{lognotereschedule}, STARTUP keyword
15967 @cindex @code{nologreschedule}, STARTUP keyword
15968 @cindex @code{logredeadline}, STARTUP keyword
15969 @cindex @code{lognoteredeadline}, STARTUP keyword
15970 @cindex @code{nologredeadline}, STARTUP keyword
15971 @cindex @code{logrefile}, STARTUP keyword
15972 @cindex @code{lognoterefile}, STARTUP keyword
15973 @cindex @code{nologrefile}, STARTUP keyword
15974 @cindex @code{logdrawer}, STARTUP keyword
15975 @cindex @code{nologdrawer}, STARTUP keyword
15976 @cindex @code{logstatesreversed}, STARTUP keyword
15977 @cindex @code{nologstatesreversed}, STARTUP keyword
15978 @example
15979 logdone             @r{record a timestamp when an item is marked DONE}
15980 lognotedone         @r{record timestamp and a note when DONE}
15981 nologdone           @r{don't record when items are marked DONE}
15982 logrepeat           @r{record a time when reinstating a repeating item}
15983 lognoterepeat       @r{record a note when reinstating a repeating item}
15984 nologrepeat         @r{do not record when reinstating repeating item}
15985 lognoteclock-out    @r{record a note when clocking out}
15986 nolognoteclock-out  @r{don't record a note when clocking out}
15987 logreschedule       @r{record a timestamp when scheduling time changes}
15988 lognotereschedule   @r{record a note when scheduling time changes}
15989 nologreschedule     @r{do not record when a scheduling date changes}
15990 logredeadline       @r{record a timestamp when deadline changes}
15991 lognoteredeadline   @r{record a note when deadline changes}
15992 nologredeadline     @r{do not record when a deadline date changes}
15993 logrefile           @r{record a timestamp when refiling}
15994 lognoterefile       @r{record a note when refiling}
15995 nologrefile         @r{do not record when refiling}
15996 logdrawer           @r{store log into drawer}
15997 nologdrawer         @r{store log outside of drawer}
15998 logstatesreversed   @r{reverse the order of states notes}
15999 nologstatesreversed @r{do not reverse the order of states notes}
16000 @end example
16002 @vindex org-hide-leading-stars
16003 @vindex org-odd-levels-only
16004 Here are the options for hiding leading stars in outline headings, and for
16005 indenting outlines.  The corresponding variables are
16006 @code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a
16007 default setting @code{nil} (meaning @code{showstars} and @code{oddeven}).
16008 @cindex @code{hidestars}, STARTUP keyword
16009 @cindex @code{showstars}, STARTUP keyword
16010 @cindex @code{odd}, STARTUP keyword
16011 @cindex @code{even}, STARTUP keyword
16012 @example
16013 hidestars  @r{make all but one of the stars starting a headline invisible.}
16014 showstars  @r{show all stars starting a headline}
16015 indent     @r{virtual indentation according to outline level}
16016 noindent   @r{no virtual indentation according to outline level}
16017 odd        @r{allow only odd outline levels (1,3,...)}
16018 oddeven    @r{allow all outline levels}
16019 @end example
16021 @vindex org-put-time-stamp-overlays
16022 @vindex org-time-stamp-overlay-formats
16023 To turn on custom format overlays over timestamps (variables
16024 @code{org-put-time-stamp-overlays} and
16025 @code{org-time-stamp-overlay-formats}), use
16026 @cindex @code{customtime}, STARTUP keyword
16027 @example
16028 customtime @r{overlay custom time format}
16029 @end example
16031 @vindex constants-unit-system
16032 The following options influence the table spreadsheet (variable
16033 @code{constants-unit-system}).
16034 @cindex @code{constcgs}, STARTUP keyword
16035 @cindex @code{constSI}, STARTUP keyword
16036 @example
16037 constcgs   @r{@file{constants.el} should use the c-g-s unit system}
16038 constSI    @r{@file{constants.el} should use the SI unit system}
16039 @end example
16041 @vindex org-footnote-define-inline
16042 @vindex org-footnote-auto-label
16043 @vindex org-footnote-auto-adjust
16044 To influence footnote settings, use the following keywords.  The
16045 corresponding variables are @code{org-footnote-define-inline},
16046 @code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.
16047 @cindex @code{fninline}, STARTUP keyword
16048 @cindex @code{nofninline}, STARTUP keyword
16049 @cindex @code{fnlocal}, STARTUP keyword
16050 @cindex @code{fnprompt}, STARTUP keyword
16051 @cindex @code{fnauto}, STARTUP keyword
16052 @cindex @code{fnconfirm}, STARTUP keyword
16053 @cindex @code{fnplain}, STARTUP keyword
16054 @cindex @code{fnadjust}, STARTUP keyword
16055 @cindex @code{nofnadjust}, STARTUP keyword
16056 @example
16057 fninline    @r{define footnotes inline}
16058 fnnoinline  @r{define footnotes in separate section}
16059 fnlocal     @r{define footnotes near first reference, but not inline}
16060 fnprompt    @r{prompt for footnote labels}
16061 fnauto      @r{create @code{[fn:1]}-like labels automatically (default)}
16062 fnconfirm   @r{offer automatic label for editing or confirmation}
16063 fnplain     @r{create @code{[1]}-like labels automatically}
16064 fnadjust    @r{automatically renumber and sort footnotes}
16065 nofnadjust  @r{do not renumber and sort automatically}
16066 @end example
16068 @cindex org-hide-block-startup
16069 To hide blocks on startup, use these keywords.  The corresponding variable is
16070 @code{org-hide-block-startup}.
16071 @cindex @code{hideblocks}, STARTUP keyword
16072 @cindex @code{nohideblocks}, STARTUP keyword
16073 @example
16074 hideblocks   @r{Hide all begin/end blocks on startup}
16075 nohideblocks @r{Do not hide blocks on startup}
16076 @end example
16078 @cindex org-pretty-entities
16079 The display of entities as UTF-8 characters is governed by the variable
16080 @code{org-pretty-entities} and the keywords
16081 @cindex @code{entitiespretty}, STARTUP keyword
16082 @cindex @code{entitiesplain}, STARTUP keyword
16083 @example
16084 entitiespretty  @r{Show entities as UTF-8 characters where possible}
16085 entitiesplain   @r{Leave entities plain}
16086 @end example
16088 @item #+TAGS:  TAG1(c1) TAG2(c2)
16089 @vindex org-tag-alist
16090 These lines (several such lines are allowed) specify the valid tags in
16091 this file, and (potentially) the corresponding @emph{fast tag selection}
16092 keys.  The corresponding variable is @code{org-tag-alist}.
16093 @cindex #+TBLFM
16094 @item #+TBLFM:
16095 This line contains the formulas for the table directly above the line.
16097 Table can have multiple lines containing @samp{#+TBLFM:}.  Note
16098 that only the first line of @samp{#+TBLFM:} will be applied when
16099 you recalculate the table.  For more details see @ref{Using
16100 multiple #+TBLFM lines} in @ref{Editing and debugging formulas}.
16102 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:,
16103 @itemx #+OPTIONS:, #+BIND:,
16104 @itemx #+DESCRIPTION:, #+KEYWORDS:,
16105 @itemx #+LaTeX_HEADER:, #+LaTeX_HEADER_EXTRA:,
16106 @itemx #+HTML_HEAD:, #+HTML_HEAD_EXTRA:, #+HTML_LINK_UP:, #+HTML_LINK_HOME:,
16107 @itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
16108 These lines provide settings for exporting files.  For more details see
16109 @ref{Export settings}.
16110 @item #+TODO:    #+SEQ_TODO:   #+TYP_TODO:
16111 @vindex org-todo-keywords
16112 These lines set the TODO keywords and their interpretation in the
16113 current file.  The corresponding variable is @code{org-todo-keywords}.
16114 @end table
16116 @node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
16117 @section The very busy C-c C-c key
16118 @kindex C-c C-c
16119 @cindex C-c C-c, overview
16121 The key @kbd{C-c C-c} has many purposes in Org, which are all
16122 mentioned scattered throughout this manual.  One specific function of
16123 this key is to add @emph{tags} to a headline (@pxref{Tags}).  In many
16124 other circumstances it means something like @emph{``Hey Org, look
16125 here and update according to what you see here''}.  Here is a summary of
16126 what this means in different contexts.
16128 @itemize @minus
16129 @item
16130 If there are highlights in the buffer from the creation of a sparse
16131 tree, or from clock display, remove these highlights.
16132 @item
16133 If the cursor is in one of the special @code{#+KEYWORD} lines, this
16134 triggers scanning the buffer for these lines and updating the
16135 information.
16136 @item
16137 If the cursor is inside a table, realign the table.  This command
16138 works even if the automatic table editor has been turned off.
16139 @item
16140 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
16141 the entire table.
16142 @item
16143 If the current buffer is a capture buffer, close the note and file it.
16144 With a prefix argument, file it, without further interaction, to the
16145 default location.
16146 @item
16147 If the cursor is on a @code{<<<target>>>}, update radio targets and
16148 corresponding links in this buffer.
16149 @item
16150 If the cursor is in a property line or at the start or end of a property
16151 drawer, offer property commands.
16152 @item
16153 If the cursor is at a footnote reference, go to the corresponding
16154 definition, and @emph{vice versa}.
16155 @item
16156 If the cursor is on a statistics cookie, update it.
16157 @item
16158 If the cursor is in a plain list item with a checkbox, toggle the status
16159 of the checkbox.
16160 @item
16161 If the cursor is on a numbered item in a plain list, renumber the
16162 ordered list.
16163 @item
16164 If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
16165 block is updated.
16166 @item
16167 If the cursor is at a timestamp, fix the day name in the timestamp.
16168 @end itemize
16170 @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
16171 @section A cleaner outline view
16172 @cindex hiding leading stars
16173 @cindex dynamic indentation
16174 @cindex odd-levels-only outlines
16175 @cindex clean outline view
16177 Some people find it noisy and distracting that the Org headlines start with a
16178 potentially large number of stars, and that text below the headlines is not
16179 indented.  While this is no problem when writing a @emph{book-like} document
16180 where the outline headings are really section headings, in a more
16181 @emph{list-oriented} outline, indented structure is a lot cleaner:
16183 @example
16184 @group
16185 * Top level headline             |    * Top level headline
16186 ** Second level                  |      * Second level
16187 *** 3rd level                    |        * 3rd level
16188 some text                        |          some text
16189 *** 3rd level                    |        * 3rd level
16190 more text                        |          more text
16191 * Another top level headline     |    * Another top level headline
16192 @end group
16193 @end example
16195 @noindent
16197 If you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crash
16198 with @code{org-indent-mode}} and version 6.29 of Org, this kind of view can
16199 be achieved dynamically at display time using @code{org-indent-mode}.  In
16200 this minor mode, all lines are prefixed for display with the necessary amount
16201 of space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix}
16202 property, such that @code{visual-line-mode} (or purely setting
16203 @code{word-wrap}) wraps long lines (including headlines) correctly indented.
16204 }.  Also headlines are prefixed with additional stars, so that the amount of
16205 indentation shifts by two@footnote{See the variable
16206 @code{org-indent-indentation-per-level}.}  spaces per level.  All headline
16207 stars but the last one are made invisible using the @code{org-hide}
16208 face@footnote{Turning on @code{org-indent-mode} sets
16209 @code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
16210 @code{nil}.}; see below under @samp{2.} for more information on how this
16211 works.  You can turn on @code{org-indent-mode} for all files by customizing
16212 the variable @code{org-startup-indented}, or you can turn it on for
16213 individual files using
16215 @example
16216 #+STARTUP: indent
16217 @end example
16219 If you want a similar effect in an earlier version of Emacs and/or Org, or if
16220 you want the indentation to be hard space characters so that the plain text
16221 file looks as similar as possible to the Emacs display, Org supports you in
16222 the following way:
16224 @enumerate
16225 @item
16226 @emph{Indentation of text below headlines}@*
16227 You may indent text below each headline to make the left boundary line up
16228 with the headline, like
16230 @example
16231 *** 3rd level
16232     more text, now indented
16233 @end example
16235 @vindex org-adapt-indentation
16236 Org supports this with paragraph filling, line wrapping, and structure
16237 editing@footnote{See also the variable @code{org-adapt-indentation}.},
16238 preserving or adapting the indentation as appropriate.
16240 @item
16241 @vindex org-hide-leading-stars
16242 @emph{Hiding leading stars}@* You can modify the display in such a way that
16243 all leading stars become invisible.  To do this in a global way, configure
16244 the variable @code{org-hide-leading-stars} or change this on a per-file basis
16245 with
16247 @example
16248 #+STARTUP: hidestars
16249 #+STARTUP: showstars
16250 @end example
16252 With hidden stars, the tree becomes:
16254 @example
16255 @group
16256 * Top level headline
16257  * Second level
16258   * 3rd level
16259   ...
16260 @end group
16261 @end example
16263 @noindent
16264 @vindex org-hide @r{(face)}
16265 The leading stars are not truly replaced by whitespace, they are only
16266 fontified with the face @code{org-hide} that uses the background color as
16267 font color.  If you are not using either white or black background, you may
16268 have to customize this face to get the wanted effect.  Another possibility is
16269 to set this font such that the extra stars are @i{almost} invisible, for
16270 example using the color @code{grey90} on a white background.
16272 @item
16273 @vindex org-odd-levels-only
16274 Things become cleaner still if you skip all the even levels and use only odd
16275 levels 1, 3, 5..., effectively adding two stars to go from one outline level
16276 to the next@footnote{When you need to specify a level for a property search
16277 or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc.}.  In this
16278 way we get the outline view shown at the beginning of this section.  In order
16279 to make the structure editing and export commands handle this convention
16280 correctly, configure the variable @code{org-odd-levels-only}, or set this on
16281 a per-file basis with one of the following lines:
16283 @example
16284 #+STARTUP: odd
16285 #+STARTUP: oddeven
16286 @end example
16288 You can convert an Org file from single-star-per-level to the
16289 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
16290 RET} in that file.  The reverse operation is @kbd{M-x
16291 org-convert-to-oddeven-levels}.
16292 @end enumerate
16294 @node TTY keys, Interaction, Clean view, Miscellaneous
16295 @section Using Org on a tty
16296 @cindex tty key bindings
16298 Because Org contains a large number of commands, by default many of
16299 Org's core commands are bound to keys that are generally not
16300 accessible on a tty, such as the cursor keys (@key{left}, @key{right},
16301 @key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used
16302 together with modifiers like @key{Meta} and/or @key{Shift}.  To access
16303 these commands on a tty when special keys are unavailable, the following
16304 alternative bindings can be used.  The tty bindings below will likely be
16305 more cumbersome; you may find for some of the bindings below that a
16306 customized workaround suits you better.  For example, changing a timestamp
16307 is really only fun with @kbd{S-@key{cursor}} keys, whereas on a
16308 tty you would rather use @kbd{C-c .} to re-insert the timestamp.
16310 @multitable @columnfractions 0.15 0.2 0.1 0.2
16311 @item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
16312 @item @kbd{S-@key{TAB}}     @tab @kbd{C-u @key{TAB}}       @tab @kbd{C} @tab
16313 @item @kbd{M-@key{left}}    @tab @kbd{C-c C-x l}           @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
16314 @item @kbd{M-S-@key{left}}  @tab @kbd{C-c C-x L}           @tab @kbd{L} @tab
16315 @item @kbd{M-@key{right}}   @tab @kbd{C-c C-x r}           @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
16316 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R}           @tab @kbd{R} @tab
16317 @item @kbd{M-@key{up}}      @tab @kbd{C-c C-x u}           @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
16318 @item @kbd{M-S-@key{up}}    @tab @kbd{C-c C-x U}           @tab @kbd{U} @tab
16319 @item @kbd{M-@key{down}}    @tab @kbd{C-c C-x d}           @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
16320 @item @kbd{M-S-@key{down}}  @tab @kbd{C-c C-x D}           @tab @kbd{D} @tab
16321 @item @kbd{S-@key{RET}}     @tab @kbd{C-c C-x c}           @tab @kbd{ } @tab
16322 @item @kbd{M-@key{RET}}     @tab @kbd{C-c C-x m}           @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
16323 @item @kbd{M-S-@key{RET}}   @tab @kbd{C-c C-x M}           @tab @kbd{ } @tab
16324 @item @kbd{S-@key{left}}    @tab @kbd{C-c @key{left}}      @tab @kbd{ } @tab
16325 @item @kbd{S-@key{right}}   @tab @kbd{C-c @key{right}}     @tab @kbd{ } @tab
16326 @item @kbd{S-@key{up}}      @tab @kbd{C-c @key{up}}        @tab @kbd{ } @tab
16327 @item @kbd{S-@key{down}}    @tab @kbd{C-c @key{down}}      @tab @kbd{ } @tab
16328 @item @kbd{C-S-@key{left}}  @tab @kbd{C-c C-x @key{left}}  @tab @kbd{ } @tab
16329 @item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab
16330 @end multitable
16333 @node Interaction, org-crypt, TTY keys, Miscellaneous
16334 @section Interaction with other packages
16335 @cindex packages, interaction with other
16336 Org lives in the world of GNU Emacs and interacts in various ways
16337 with other code out there.
16339 @menu
16340 * Cooperation::                 Packages Org cooperates with
16341 * Conflicts::                   Packages that lead to conflicts
16342 @end menu
16344 @node Cooperation, Conflicts, Interaction, Interaction
16345 @subsection Packages that Org cooperates with
16347 @table @asis
16348 @cindex @file{calc.el}
16349 @cindex Gillespie, Dave
16350 @item @file{calc.el} by Dave Gillespie
16351 Org uses the Calc package for implementing spreadsheet
16352 functionality in its tables (@pxref{The spreadsheet}).  Org
16353 checks for the availability of Calc by looking for the function
16354 @code{calc-eval} which will have been autoloaded during setup if Calc has
16355 been installed properly.  As of Emacs 22, Calc is part of the Emacs
16356 distribution.  Another possibility for interaction between the two
16357 packages is using Calc for embedded calculations.  @xref{Embedded Mode,
16358 , Embedded Mode, calc, GNU Emacs Calc Manual}.
16359 @item @file{constants.el} by Carsten Dominik
16360 @cindex @file{constants.el}
16361 @cindex Dominik, Carsten
16362 @vindex org-table-formula-constants
16363 In a table formula (@pxref{The spreadsheet}), it is possible to use
16364 names for natural constants or units.  Instead of defining your own
16365 constants in the variable @code{org-table-formula-constants}, install
16366 the @file{constants} package which defines a large number of constants
16367 and units, and lets you use unit prefixes like @samp{M} for
16368 @samp{Mega}, etc.  You will need version 2.0 of this package, available
16369 at @url{http://www.astro.uva.nl/~dominik/Tools}.  Org checks for
16370 the function @code{constants-get}, which has to be autoloaded in your
16371 setup.  See the installation instructions in the file
16372 @file{constants.el}.
16373 @item @file{cdlatex.el} by Carsten Dominik
16374 @cindex @file{cdlatex.el}
16375 @cindex Dominik, Carsten
16376 Org mode can make use of the CD@LaTeX{} package to efficiently enter
16377 @LaTeX{} fragments into Org files.  See @ref{CDLaTeX mode}.
16378 @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
16379 @cindex @file{imenu.el}
16380 Imenu allows menu access to an index of items in a file.  Org mode
16381 supports Imenu---all you need to do to get the index is the following:
16382 @lisp
16383 (add-hook 'org-mode-hook
16384           (lambda () (imenu-add-to-menubar "Imenu")))
16385 @end lisp
16386 @vindex org-imenu-depth
16387 By default the index is two levels deep---you can modify the depth using
16388 the option @code{org-imenu-depth}.
16389 @item @file{remember.el} by John Wiegley
16390 @cindex @file{remember.el}
16391 @cindex Wiegley, John
16392 Org used to use this package for capture, but no longer does.
16393 @item @file{speedbar.el} by Eric M. Ludlam
16394 @cindex @file{speedbar.el}
16395 @cindex Ludlam, Eric M.
16396 Speedbar is a package that creates a special frame displaying files and
16397 index items in files.  Org mode supports Speedbar and allows you to
16398 drill into Org files directly from the Speedbar.  It also allows you to
16399 restrict the scope of agenda commands to a file or a subtree by using
16400 the command @kbd{<} in the Speedbar frame.
16401 @cindex @file{table.el}
16402 @item @file{table.el} by Takaaki Ota
16403 @kindex C-c C-c
16404 @cindex table editor, @file{table.el}
16405 @cindex @file{table.el}
16406 @cindex Ota, Takaaki
16408 Complex ASCII tables with automatic line wrapping, column- and row-spanning,
16409 and alignment can be created using the Emacs table package by Takaaki Ota
16410 (@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22).
16411 Org mode will recognize these tables and export them properly.  Because of
16412 interference with other Org mode functionality, you unfortunately cannot edit
16413 these tables directly in the buffer.  Instead, you need to use the command
16414 @kbd{C-c '} to edit them, similar to source code snippets.
16416 @table @kbd
16417 @orgcmd{C-c ',org-edit-special}
16418 Edit a @file{table.el} table.  Works when the cursor is in a table.el table.
16420 @orgcmd{C-c ~,org-table-create-with-table.el}
16421 Insert a @file{table.el} table.  If there is already a table at point, this
16422 command converts it between the @file{table.el} format and the Org mode
16423 format.  See the documentation string of the command
16424 @code{org-convert-table} for the restrictions under which this is
16425 possible.
16426 @end table
16427 @file{table.el} is part of Emacs since Emacs 22.
16428 @item @file{footnote.el} by Steven L. Baur
16429 @cindex @file{footnote.el}
16430 @cindex Baur, Steven L.
16431 Org mode recognizes numerical footnotes as provided by this package.
16432 However, Org mode also has its own footnote support (@pxref{Footnotes}),
16433 which makes using @file{footnote.el} unnecessary.
16434 @end table
16436 @node Conflicts,  , Cooperation, Interaction
16437 @subsection Packages that lead to conflicts with Org mode
16439 @table @asis
16441 @cindex @code{shift-selection-mode}
16442 @vindex org-support-shift-select
16443 In Emacs 23, @code{shift-selection-mode} is on by default, meaning that
16444 cursor motions combined with the shift key should start or enlarge regions.
16445 This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change
16446 timestamps, TODO keywords, priorities, and item bullet types if the cursor is
16447 at such a location.  By default, @kbd{S-@key{cursor}} commands outside
16448 special contexts don't do anything, but you can customize the variable
16449 @code{org-support-shift-select}.  Org mode then tries to accommodate shift
16450 selection by (i) using it outside of the special contexts where special
16451 commands apply, and by (ii) extending an existing active region even if the
16452 cursor moves across a special context.
16454 @item @file{CUA.el} by Kim. F. Storm
16455 @cindex @file{CUA.el}
16456 @cindex Storm, Kim. F.
16457 @vindex org-replace-disputed-keys
16458 Key bindings in Org conflict with the @kbd{S-<cursor>} keys used by CUA mode
16459 (as well as @code{pc-select-mode} and @code{s-region-mode}) to select and extend the
16460 region.  In fact, Emacs 23 has this built-in in the form of
16461 @code{shift-selection-mode}, see previous paragraph.  If you are using Emacs
16462 23, you probably don't want to use another package for this purpose.  However,
16463 if you prefer to leave these keys to a different package while working in
16464 Org mode, configure the variable @code{org-replace-disputed-keys}.  When set,
16465 Org will move the following key bindings in Org files, and in the agenda
16466 buffer (but not during date selection).
16468 @example
16469 S-UP      @result{}  M-p             S-DOWN     @result{}  M-n
16470 S-LEFT    @result{}  M--             S-RIGHT    @result{}  M-+
16471 C-S-LEFT  @result{}  M-S--           C-S-RIGHT  @result{}  M-S-+
16472 @end example
16474 @vindex org-disputed-keys
16475 Yes, these are unfortunately more difficult to remember.  If you want
16476 to have other replacement keys, look at the variable
16477 @code{org-disputed-keys}.
16479 @item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org}
16480 @cindex @file{ecomplete.el}
16482 Ecomplete provides ``electric'' address completion in address header
16483 lines in message buffers.  Sadly Orgtbl mode cuts ecompletes power
16484 supply: No completion happens when Orgtbl mode is enabled in message
16485 buffers while entering text in address header lines.  If one wants to
16486 use ecomplete one should @emph{not} follow the advice to automagically
16487 turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but
16488 instead---after filling in the message headers---turn on Orgtbl mode
16489 manually when needed in the messages body.
16491 @item @file{filladapt.el} by Kyle Jones
16492 @cindex @file{filladapt.el}
16494 Org mode tries to do the right thing when filling paragraphs, list items and
16495 other elements.  Many users reported they had problems using both
16496 @file{filladapt.el} and Org mode, so a safe thing to do is to disable it like
16497 this:
16499 @lisp
16500 (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
16501 @end lisp
16503 @item @file{yasnippet.el}
16504 @cindex @file{yasnippet.el}
16505 The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of
16506 @code{"\t"}) overrules YASnippet's access to this key.  The following code
16507 fixed this problem:
16509 @lisp
16510 (add-hook 'org-mode-hook
16511           (lambda ()
16512             (org-set-local 'yas/trigger-key [tab])
16513             (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
16514 @end lisp
16516 The latest version of yasnippet doesn't play well with Org mode.  If the
16517 above code does not fix the conflict, start by defining the following
16518 function:
16520 @lisp
16521 (defun yas/org-very-safe-expand ()
16522   (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
16523 @end lisp
16525 Then, tell Org mode what to do with the new function:
16527 @lisp
16528 (add-hook 'org-mode-hook
16529           (lambda ()
16530             (make-variable-buffer-local 'yas/trigger-key)
16531             (setq yas/trigger-key [tab])
16532             (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
16533             (define-key yas/keymap [tab] 'yas/next-field)))
16534 @end lisp
16536 @item @file{windmove.el} by Hovav Shacham
16537 @cindex @file{windmove.el}
16538 This package also uses the @kbd{S-<cursor>} keys, so everything written
16539 in the paragraph above about CUA mode also applies here.  If you want make
16540 the windmove function active in locations where Org mode does not have
16541 special functionality on @kbd{S-@key{cursor}}, add this to your
16542 configuration:
16544 @lisp
16545 ;; Make windmove work in org-mode:
16546 (add-hook 'org-shiftup-final-hook 'windmove-up)
16547 (add-hook 'org-shiftleft-final-hook 'windmove-left)
16548 (add-hook 'org-shiftdown-final-hook 'windmove-down)
16549 (add-hook 'org-shiftright-final-hook 'windmove-right)
16550 @end lisp
16552 @item @file{viper.el} by Michael Kifer
16553 @cindex @file{viper.el}
16554 @kindex C-c /
16555 Viper uses @kbd{C-c /} and therefore makes this key not access the
16556 corresponding Org mode command @code{org-sparse-tree}.  You need to find
16557 another key for this command, or override the key in
16558 @code{viper-vi-global-user-map} with
16560 @lisp
16561 (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
16562 @end lisp
16566 @end table
16568 @node org-crypt,  , Interaction, Miscellaneous
16569 @section org-crypt.el
16570 @cindex @file{org-crypt.el}
16571 @cindex @code{org-decrypt-entry}
16573 Org-crypt will encrypt the text of an entry, but not the headline, or
16574 properties.  Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
16575 files.
16577 Any text below a headline that has a @samp{:crypt:} tag will be automatically
16578 be encrypted when the file is saved.  If you want to use a different tag just
16579 customize the @code{org-crypt-tag-matcher} setting.
16581 To use org-crypt it is suggested that you have the following in your
16582 @file{.emacs}:
16584 @lisp
16585 (require 'org-crypt)
16586 (org-crypt-use-before-save-magic)
16587 (setq org-tags-exclude-from-inheritance (quote ("crypt")))
16589 (setq org-crypt-key nil)
16590   ;; GPG key to use for encryption
16591   ;; Either the Key ID or set to nil to use symmetric encryption.
16593 (setq auto-save-default nil)
16594   ;; Auto-saving does not cooperate with org-crypt.el: so you need
16595   ;; to turn it off if you plan to use org-crypt.el quite often.
16596   ;; Otherwise, you'll get an (annoying) message each time you
16597   ;; start Org.
16599   ;; To turn it off only locally, you can insert this:
16600   ;;
16601   ;; # -*- buffer-auto-save-file-name: nil; -*-
16602 @end lisp
16604 Excluding the crypt tag from inheritance prevents already encrypted text
16605 being encrypted again.
16607 @node Hacking, MobileOrg, Miscellaneous, Top
16608 @appendix Hacking
16609 @cindex hacking
16611 This appendix covers some aspects where users can extend the functionality of
16612 Org.
16614 @menu
16615 * Hooks::                       How to reach into Org's internals
16616 * Add-on packages::             Available extensions
16617 * Adding hyperlink types::      New custom link types
16618 * Adding export back-ends::     How to write new export back-ends
16619 * Context-sensitive commands::  How to add functionality to such commands
16620 * Tables in arbitrary syntax::  Orgtbl for @LaTeX{} and other programs
16621 * Dynamic blocks::              Automatically filled blocks
16622 * Special agenda views::        Customized views
16623 * Speeding up your agendas::    Tips on how to speed up your agendas
16624 * Extracting agenda information::  Post-processing of agenda information
16625 * Using the property API::      Writing programs that use entry properties
16626 * Using the mapping API::       Mapping over all or selected entries
16627 @end menu
16629 @node Hooks, Add-on packages, Hacking, Hacking
16630 @section Hooks
16631 @cindex hooks
16633 Org has a large number of hook variables that can be used to add
16634 functionality.  This appendix about hacking is going to illustrate the
16635 use of some of them.  A complete list of all hooks with documentation is
16636 maintained by the Worg project and can be found at
16637 @uref{http://orgmode.org/worg/org-configs/org-hooks.php}.
16639 @node Add-on packages, Adding hyperlink types, Hooks, Hacking
16640 @section Add-on packages
16641 @cindex add-on packages
16643 A large number of add-on packages have been written by various authors.
16645 These packages are not part of Emacs, but they are distributed as contributed
16646 packages with the separate release available at @uref{http://orgmode.org}.
16647 See the @file{contrib/README} file in the source code directory for a list of
16648 contributed files.  You may also find some more information on the Worg page:
16649 @uref{http://orgmode.org/worg/org-contrib/}.
16651 @node Adding hyperlink types, Adding export back-ends, Add-on packages, Hacking
16652 @section Adding hyperlink types
16653 @cindex hyperlinks, adding new types
16655 Org has a large number of hyperlink types built-in
16656 (@pxref{Hyperlinks}).  If you would like to add new link types, Org
16657 provides an interface for doing so.  Let's look at an example file,
16658 @file{org-man.el}, that will add support for creating links like
16659 @samp{[[man:printf][The printf manpage]]} to show Unix manual pages inside
16660 Emacs:
16662 @lisp
16663 ;;; org-man.el - Support for links to manpages in Org
16665 (require 'org)
16667 (org-add-link-type "man" 'org-man-open)
16668 (add-hook 'org-store-link-functions 'org-man-store-link)
16670 (defcustom org-man-command 'man
16671   "The Emacs command to be used to display a man page."
16672   :group 'org-link
16673   :type '(choice (const man) (const woman)))
16675 (defun org-man-open (path)
16676   "Visit the manpage on PATH.
16677 PATH should be a topic that can be thrown at the man command."
16678   (funcall org-man-command path))
16680 (defun org-man-store-link ()
16681   "Store a link to a manpage."
16682   (when (memq major-mode '(Man-mode woman-mode))
16683     ;; This is a man page, we do make this link
16684     (let* ((page (org-man-get-page-name))
16685            (link (concat "man:" page))
16686            (description (format "Manpage for %s" page)))
16687       (org-store-link-props
16688        :type "man"
16689        :link link
16690        :description description))))
16692 (defun org-man-get-page-name ()
16693   "Extract the page name from the buffer name."
16694   ;; This works for both `Man-mode' and `woman-mode'.
16695   (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
16696       (match-string 1 (buffer-name))
16697     (error "Cannot create link to this man page")))
16699 (provide 'org-man)
16701 ;;; org-man.el ends here
16702 @end lisp
16704 @noindent
16705 You would activate this new link type in @file{.emacs} with
16707 @lisp
16708 (require 'org-man)
16709 @end lisp
16711 @noindent
16712 Let's go through the file and see what it does.
16713 @enumerate
16714 @item
16715 It does @code{(require 'org)} to make sure that @file{org.el} has been
16716 loaded.
16717 @item
16718 The next line calls @code{org-add-link-type} to define a new link type
16719 with prefix @samp{man}.  The call also contains the name of a function
16720 that will be called to follow such a link.
16721 @item
16722 @vindex org-store-link-functions
16723 The next line adds a function to @code{org-store-link-functions}, in
16724 order to allow the command @kbd{C-c l} to record a useful link in a
16725 buffer displaying a man page.
16726 @end enumerate
16728 The rest of the file defines the necessary variables and functions.
16729 First there is a customization variable that determines which Emacs
16730 command should be used to display man pages.  There are two options,
16731 @code{man} and @code{woman}.  Then the function to follow a link is
16732 defined.  It gets the link path as an argument---in this case the link
16733 path is just a topic for the manual command.  The function calls the
16734 value of @code{org-man-command} to display the man page.
16736 Finally the function @code{org-man-store-link} is defined.  When you try
16737 to store a link with @kbd{C-c l}, this function will be called to
16738 try to make a link.  The function must first decide if it is supposed to
16739 create the link for this buffer type; we do this by checking the value
16740 of the variable @code{major-mode}.  If not, the function must exit and
16741 return the value @code{nil}.  If yes, the link is created by getting the
16742 manual topic from the buffer name and prefixing it with the string
16743 @samp{man:}.  Then it must call the command @code{org-store-link-props}
16744 and set the @code{:type} and @code{:link} properties.  Optionally you
16745 can also set the @code{:description} property to provide a default for
16746 the link description when the link is later inserted into an Org
16747 buffer with @kbd{C-c C-l}.
16749 When it makes sense for your new link type, you may also define a function
16750 @code{org-PREFIX-complete-link} that implements special (e.g., completion)
16751 support for inserting such a link with @kbd{C-c C-l}.  Such a function should
16752 not accept any arguments, and return the full link with prefix.
16754 @node Adding export back-ends, Context-sensitive commands, Adding hyperlink types, Hacking
16755 @section Adding export back-ends
16756 @cindex Export, writing back-ends
16758 Org 8.0 comes with a completely rewritten export engine which makes it easy
16759 to write new export back-ends, either from scratch, or from deriving them
16760 from existing ones.
16762 Your two entry points are respectively @code{org-export-define-backend} and
16763 @code{org-export-define-derived-backend}.  To grok these functions, you
16764 should first have a look at @file{ox-latex.el} (for how to define a new
16765 back-end from scratch) and @file{ox-beamer.el} (for how to derive a new
16766 back-end from an existing one.
16768 When creating a new back-end from scratch, the basic idea is to set the name
16769 of the back-end (as a symbol) and an an alist of elements and export
16770 functions.  On top of this, you will need to set additional keywords like
16771 @code{:menu-entry} (to display the back-end in the export dispatcher),
16772 @code{:export-block} (to specify what blocks should not be exported by this
16773 back-end), and @code{:options-alist} (to let the user set export options that
16774 are specific to this back-end.)
16776 Deriving a new back-end is similar, except that you need to set
16777 @code{:translate-alist} to an alist of export functions that should be used
16778 instead of the parent back-end functions.
16780 For a complete reference documentation, see
16781 @url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
16782 Reference on Worg}.
16784 @node Context-sensitive commands, Tables in arbitrary syntax, Adding export back-ends, Hacking
16785 @section Context-sensitive commands
16786 @cindex context-sensitive commands, hooks
16787 @cindex add-ons, context-sensitive commands
16788 @vindex org-ctrl-c-ctrl-c-hook
16790 Org has several commands that act differently depending on context.  The most
16791 important example is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).
16792 Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property.
16794 Add-ons can tap into this functionality by providing a function that detects
16795 special context for that add-on and executes functionality appropriate for
16796 the context.  Here is an example from Dan Davison's @file{org-R.el} which
16797 allows you to evaluate commands based on the @file{R} programming language
16798 @footnote{@file{org-R.el} has been replaced by the Org mode functionality
16799 described in @ref{Working With Source Code} and is now obsolete.}.  For this
16800 package, special contexts are lines that start with @code{#+R:} or
16801 @code{#+RR:}.
16803 @lisp
16804 (defun org-R-apply-maybe ()
16805   "Detect if this is context for org-R and execute R commands."
16806   (if (save-excursion
16807         (beginning-of-line 1)
16808         (looking-at "#\\+RR?:"))
16809       (progn (call-interactively 'org-R-apply)
16810              t) ;; to signal that we took action
16811     nil)) ;; to signal that we did not
16813 (add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe)
16814 @end lisp
16816 The function first checks if the cursor is in such a line.  If that is the
16817 case, @code{org-R-apply} is called and the function returns @code{t} to
16818 signal that action was taken, and @kbd{C-c C-c} will stop looking for other
16819 contexts.  If the function finds it should do nothing locally, it returns
16820 @code{nil} so that other, similar functions can have a try.
16823 @node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking
16824 @section Tables and lists in arbitrary syntax
16825 @cindex tables, in other modes
16826 @cindex lists, in other modes
16827 @cindex Orgtbl mode
16829 Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a
16830 frequent feature request has been to make it work with native tables in
16831 specific languages, for example @LaTeX{}.  However, this is extremely
16832 hard to do in a general way, would lead to a customization nightmare,
16833 and would take away much of the simplicity of the Orgtbl mode table
16834 editor.
16836 This appendix describes a different approach.  We keep the Orgtbl mode
16837 table in its native format (the @i{source table}), and use a custom
16838 function to @i{translate} the table to the correct syntax, and to
16839 @i{install} it in the right location (the @i{target table}).  This puts
16840 the burden of writing conversion functions on the user, but it allows
16841 for a very flexible system.
16843 Bastien added the ability to do the same with lists, in Orgstruct mode.  You
16844 can use Org's facilities to edit and structure lists by turning
16845 @code{orgstruct-mode} on, then locally exporting such lists in another format
16846 (HTML, @LaTeX{} or Texinfo.)
16849 @menu
16850 * Radio tables::                Sending and receiving radio tables
16851 * A @LaTeX{} example::          Step by step, almost a tutorial
16852 * Translator functions::        Copy and modify
16853 * Radio lists::                 Sending and receiving lists
16854 @end menu
16856 @node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax
16857 @subsection Radio tables
16858 @cindex radio tables
16860 To define the location of the target table, you first need to create two
16861 lines that are comments in the current mode, but contain magic words
16862 @code{BEGIN/END RECEIVE ORGTBL} for Orgtbl mode to find.  Orgtbl mode will
16863 insert the translated table between these lines, replacing whatever was there
16864 before.  For example in C mode where comments are between @code{/* ... */}:
16866 @example
16867 /* BEGIN RECEIVE ORGTBL table_name */
16868 /* END RECEIVE ORGTBL table_name */
16869 @end example
16871 @noindent
16872 Just above the source table, we put a special line that tells
16873 Orgtbl mode how to translate this table and where to install it.  For
16874 example:
16875 @cindex #+ORGTBL
16876 @example
16877 #+ORGTBL: SEND table_name translation_function arguments...
16878 @end example
16880 @noindent
16881 @code{table_name} is the reference name for the table that is also used
16882 in the receiver lines.  @code{translation_function} is the Lisp function
16883 that does the translation.  Furthermore, the line can contain a list of
16884 arguments (alternating key and value) at the end.  The arguments will be
16885 passed as a property list to the translation function for
16886 interpretation.  A few standard parameters are already recognized and
16887 acted upon before the translation function is called:
16889 @table @code
16890 @item :skip N
16891 Skip the first N lines of the table.  Hlines do count as separate lines for
16892 this parameter!
16894 @item :skipcols (n1 n2 ...)
16895 List of columns that should be skipped.  If the table has a column with
16896 calculation marks, that column is automatically discarded as well.
16897 Please note that the translator function sees the table @emph{after} the
16898 removal of these columns, the function never knows that there have been
16899 additional columns.
16901 @item :no-escape t
16902 When non-@code{nil}, do not escape special characters @code{&%#_^} when exporting
16903 the table.  The default value is @code{nil}.
16904 @end table
16906 @noindent
16907 The one problem remaining is how to keep the source table in the buffer
16908 without disturbing the normal workings of the file, for example during
16909 compilation of a C file or processing of a @LaTeX{} file.  There are a
16910 number of different solutions:
16912 @itemize @bullet
16913 @item
16914 The table could be placed in a block comment if that is supported by the
16915 language.  For example, in C mode you could wrap the table between
16916 @samp{/*} and @samp{*/} lines.
16917 @item
16918 Sometimes it is possible to put the table after some kind of @i{END}
16919 statement, for example @samp{\bye} in @TeX{} and @samp{\end@{document@}}
16920 in @LaTeX{}.
16921 @item
16922 You can just comment the table line-by-line whenever you want to process
16923 the file, and uncomment it whenever you need to edit the table.  This
16924 only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment RET}
16925 makes this comment-toggling very easy, in particular if you bind it to a
16926 key.
16927 @end itemize
16929 @node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax
16930 @subsection A @LaTeX{} example of radio tables
16931 @cindex @LaTeX{}, and Orgtbl mode
16933 The best way to wrap the source table in @LaTeX{} is to use the
16934 @code{comment} environment provided by @file{comment.sty}.  It has to be
16935 activated by placing @code{\usepackage@{comment@}} into the document
16936 header.  Orgtbl mode can insert a radio table skeleton@footnote{By
16937 default this works only for @LaTeX{}, HTML, and Texinfo.  Configure the
16938 variable @code{orgtbl-radio-table-templates} to install templates for other
16939 modes.}  with the command @kbd{M-x orgtbl-insert-radio-table RET}.  You will
16940 be prompted for a table name, let's say we use @samp{salesfigures}.  You
16941 will then get the following template:
16943 @cindex #+ORGTBL, SEND
16944 @example
16945 % BEGIN RECEIVE ORGTBL salesfigures
16946 % END RECEIVE ORGTBL salesfigures
16947 \begin@{comment@}
16948 #+ORGTBL: SEND salesfigures orgtbl-to-latex
16949 | | |
16950 \end@{comment@}
16951 @end example
16953 @noindent
16954 @vindex @LaTeX{}-verbatim-environments
16955 The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function
16956 @code{orgtbl-to-latex} to convert the table into @LaTeX{} and to put it
16957 into the receiver location with name @code{salesfigures}.  You may now
16958 fill in the table---feel free to use the spreadsheet features@footnote{If
16959 the @samp{#+TBLFM} line contains an odd number of dollar characters,
16960 this may cause problems with font-lock in @LaTeX{} mode.  As shown in the
16961 example you can fix this by adding an extra line inside the
16962 @code{comment} environment that is used to balance the dollar
16963 expressions.  If you are using AUC@TeX{} with the font-latex library, a
16964 much better solution is to add the @code{comment} environment to the
16965 variable @code{LaTeX-verbatim-environments}.}:
16967 @example
16968 % BEGIN RECEIVE ORGTBL salesfigures
16969 % END RECEIVE ORGTBL salesfigures
16970 \begin@{comment@}
16971 #+ORGTBL: SEND salesfigures orgtbl-to-latex
16972 | Month | Days | Nr sold | per day |
16973 |-------+------+---------+---------|
16974 | Jan   |   23 |      55 |     2.4 |
16975 | Feb   |   21 |      16 |     0.8 |
16976 | March |   22 |     278 |    12.6 |
16977 #+TBLFM: $4=$3/$2;%.1f
16978 % $ (optional extra dollar to keep font-lock happy, see footnote)
16979 \end@{comment@}
16980 @end example
16982 @noindent
16983 When you are done, press @kbd{C-c C-c} in the table to get the converted
16984 table inserted between the two marker lines.
16986 Now let's assume you want to make the table header by hand, because you
16987 want to control how columns are aligned, etc.  In this case we make sure
16988 that the table translator skips the first 2 lines of the source
16989 table, and tell the command to work as a @i{splice}, i.e., to not produce
16990 header and footer commands of the target table:
16992 @example
16993 \begin@{tabular@}@{lrrr@}
16994 Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
16995 % BEGIN RECEIVE ORGTBL salesfigures
16996 % END RECEIVE ORGTBL salesfigures
16997 \end@{tabular@}
16999 \begin@{comment@}
17000 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
17001 | Month | Days | Nr sold | per day |
17002 |-------+------+---------+---------|
17003 | Jan   |   23 |      55 |     2.4 |
17004 | Feb   |   21 |      16 |     0.8 |
17005 | March |   22 |     278 |    12.6 |
17006 #+TBLFM: $4=$3/$2;%.1f
17007 \end@{comment@}
17008 @end example
17010 The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
17011 Orgtbl mode.  It uses a @code{tabular} environment to typeset the table
17012 and marks horizontal lines with @code{\hline}.  Furthermore, it
17013 interprets the following parameters (see also @pxref{Translator functions}):
17015 @table @code
17016 @item :splice nil/t
17017 When set to t, return only table body lines, don't wrap them into a
17018 tabular environment.  Default is @code{nil}.
17020 @item :fmt fmt
17021 A format to be used to wrap each field, it should contain @code{%s} for the
17022 original field value.  For example, to wrap each field value in dollars,
17023 you could use @code{:fmt "$%s$"}.  This may also be a property list with
17024 column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
17025 A function of one argument can be used in place of the strings; the
17026 function must return a formatted string.
17028 @item :efmt efmt
17029 Use this format to print numbers with exponentials.  The format should
17030 have @code{%s} twice for inserting mantissa and exponent, for example
17031 @code{"%s\\times10^@{%s@}"}.  The default is @code{"%s\\,(%s)"}.  This
17032 may also be a property list with column numbers and formats, for example
17033 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}.  After
17034 @code{efmt} has been applied to a value, @code{fmt} will also be
17035 applied.  Similar to @code{fmt}, functions of two arguments can be
17036 supplied instead of strings.
17037 @end table
17039 @node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax
17040 @subsection Translator functions
17041 @cindex HTML, and Orgtbl mode
17042 @cindex translator function
17044 Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv}
17045 (comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values)
17046 @code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}.
17047 Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the same
17048 code that produces tables during HTML export.}, these all use a generic
17049 translator, @code{orgtbl-to-generic}.  For example, @code{orgtbl-to-latex}
17050 itself is a very short function that computes the column definitions for the
17051 @code{tabular} environment, defines a few field and line separators and then
17052 hands processing over to the generic translator.  Here is the entire code:
17054 @lisp
17055 @group
17056 (defun orgtbl-to-latex (table params)
17057   "Convert the Orgtbl mode TABLE to LaTeX."
17058   (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
17059                                org-table-last-alignment ""))
17060          (params2
17061           (list
17062            :tstart (concat "\\begin@{tabular@}@{" alignment "@}")
17063            :tend "\\end@{tabular@}"
17064            :lstart "" :lend " \\\\" :sep " & "
17065            :efmt "%s\\,(%s)" :hline "\\hline")))
17066     (orgtbl-to-generic table (org-combine-plists params2 params))))
17067 @end group
17068 @end lisp
17070 As you can see, the properties passed into the function (variable
17071 @var{PARAMS}) are combined with the ones newly defined in the function
17072 (variable @var{PARAMS2}).  The ones passed into the function (i.e., the
17073 ones set by the @samp{ORGTBL SEND} line) take precedence.  So if you
17074 would like to use the @LaTeX{} translator, but wanted the line endings to
17075 be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
17076 overrule the default with
17078 @example
17079 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
17080 @end example
17082 For a new language, you can either write your own converter function in
17083 analogy with the @LaTeX{} translator, or you can use the generic function
17084 directly.  For example, if you have a language where a table is started
17085 with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are
17086 started with @samp{!BL!}, ended with @samp{!EL!}, and where the field
17087 separator is a TAB, you could call the generic translator like this (on
17088 a single line!):
17090 @example
17091 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
17092                               :lstart "!BL! " :lend " !EL!" :sep "\t"
17093 @end example
17095 @noindent
17096 Please check the documentation string of the function
17097 @code{orgtbl-to-generic} for a full list of parameters understood by
17098 that function, and remember that you can pass each of them into
17099 @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
17100 using the generic function.
17102 Of course you can also write a completely new function doing complicated
17103 things the generic translator cannot do.  A translator function takes
17104 two arguments.  The first argument is the table, a list of lines, each
17105 line either the symbol @code{hline} or a list of fields.  The second
17106 argument is the property list containing all parameters specified in the
17107 @samp{#+ORGTBL: SEND} line.  The function must return a single string
17108 containing the formatted table.  If you write a generally useful
17109 translator, please post it on @email{emacs-orgmode@@gnu.org} so that
17110 others can benefit from your work.
17112 @node Radio lists,  , Translator functions, Tables in arbitrary syntax
17113 @subsection Radio lists
17114 @cindex radio lists
17115 @cindex org-list-insert-radio-list
17117 Sending and receiving radio lists works exactly the same way as sending and
17118 receiving radio tables (@pxref{Radio tables}).  As for radio tables, you can
17119 insert radio list templates in HTML, @LaTeX{} and Texinfo modes by calling
17120 @code{org-list-insert-radio-list}.
17122 Here are the differences with radio tables:
17124 @itemize @minus
17125 @item
17126 Orgstruct mode must be active.
17127 @item
17128 Use the @code{ORGLST} keyword instead of @code{ORGTBL}.
17129 @item
17130 The available translation functions for radio lists don't take
17131 parameters.
17132 @item
17133 @kbd{C-c C-c} will work when pressed on the first item of the list.
17134 @end itemize
17136 Here is a @LaTeX{} example.  Let's say that you have this in your
17137 @LaTeX{} file:
17139 @cindex #+ORGLST
17140 @example
17141 % BEGIN RECEIVE ORGLST to-buy
17142 % END RECEIVE ORGLST to-buy
17143 \begin@{comment@}
17144 #+ORGLST: SEND to-buy org-list-to-latex
17145 - a new house
17146 - a new computer
17147   + a new keyboard
17148   + a new mouse
17149 - a new life
17150 \end@{comment@}
17151 @end example
17153 Pressing @kbd{C-c C-c} on @code{a new house} and will insert the converted
17154 @LaTeX{} list between the two marker lines.
17156 @node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking
17157 @section Dynamic blocks
17158 @cindex dynamic blocks
17160 Org documents can contain @emph{dynamic blocks}.  These are
17161 specially marked regions that are updated by some user-written function.
17162 A good example for such a block is the clock table inserted by the
17163 command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
17165 Dynamic blocks are enclosed by a BEGIN-END structure that assigns a name
17166 to the block and can also specify parameters for the function producing
17167 the content of the block.
17169 @cindex #+BEGIN:dynamic block
17170 @example
17171 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
17173 #+END:
17174 @end example
17176 Dynamic blocks are updated with the following commands
17178 @table @kbd
17179 @orgcmd{C-c C-x C-u,org-dblock-update}
17180 Update dynamic block at point.
17181 @orgkey{C-u C-c C-x C-u}
17182 Update all dynamic blocks in the current file.
17183 @end table
17185 Updating a dynamic block means to remove all the text between BEGIN and
17186 END, parse the BEGIN line for parameters and then call the specific
17187 writer function for this block to insert the new content.  If you want
17188 to use the original content in the writer function, you can use the
17189 extra parameter @code{:content}.
17191 For a block with name @code{myblock}, the writer function is
17192 @code{org-dblock-write:myblock} with as only parameter a property list
17193 with the parameters given in the begin line.  Here is a trivial example
17194 of a block that keeps track of when the block update function was last
17195 run:
17197 @example
17198 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
17200 #+END:
17201 @end example
17203 @noindent
17204 The corresponding block writer function could look like this:
17206 @lisp
17207 (defun org-dblock-write:block-update-time (params)
17208   (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
17209     (insert "Last block update at: "
17210             (format-time-string fmt (current-time)))))
17211 @end lisp
17213 If you want to make sure that all dynamic blocks are always up-to-date,
17214 you could add the function @code{org-update-all-dblocks} to a hook, for
17215 example @code{before-save-hook}.  @code{org-update-all-dblocks} is
17216 written in a way such that it does nothing in buffers that are not in
17217 @code{org-mode}.
17219 You can narrow the current buffer to the current dynamic block (like any
17220 other block) with @code{org-narrow-to-block}.
17222 @node Special agenda views, Speeding up your agendas, Dynamic blocks, Hacking
17223 @section Special agenda views
17224 @cindex agenda views, user-defined
17226 @vindex org-agenda-skip-function
17227 @vindex org-agenda-skip-function-global
17228 Org provides a special hook that can be used to narrow down the selection
17229 made by these agenda views: @code{agenda}, @code{agenda*}@footnote{The
17230 @code{agenda*} view is the same than @code{agenda} except that it only
17231 considers @emph{appointments}, i.e., scheduled and deadline items that have a
17232 time specification @code{[h]h:mm} in their time-stamps.}, @code{todo},
17233 @code{alltodo}, @code{tags}, @code{tags-todo}, @code{tags-tree}.  You may
17234 specify a function that is used at each match to verify if the match should
17235 indeed be part of the agenda view, and if not, how much should be skipped.
17236 You can specify a global condition that will be applied to all agenda views,
17237 this condition would be stored in the variable
17238 @code{org-agenda-skip-function-global}.  More commonly, such a definition is
17239 applied only to specific custom searches, using
17240 @code{org-agenda-skip-function}.
17242 Let's say you want to produce a list of projects that contain a WAITING
17243 tag anywhere in the project tree.  Let's further assume that you have
17244 marked all tree headings that define a project with the TODO keyword
17245 PROJECT@.  In this case you would run a TODO search for the keyword
17246 PROJECT, but skip the match unless there is a WAITING tag anywhere in
17247 the subtree belonging to the project line.
17249 To achieve this, you must write a function that searches the subtree for
17250 the tag.  If the tag is found, the function must return @code{nil} to
17251 indicate that this match should not be skipped.  If there is no such
17252 tag, return the location of the end of the subtree, to indicate that
17253 search should continue from there.
17255 @lisp
17256 (defun my-skip-unless-waiting ()
17257   "Skip trees that are not waiting"
17258   (let ((subtree-end (save-excursion (org-end-of-subtree t))))
17259     (if (re-search-forward ":waiting:" subtree-end t)
17260         nil          ; tag found, do not skip
17261       subtree-end))) ; tag not found, continue after end of subtree
17262 @end lisp
17264 Now you may use this function in an agenda custom command, for example
17265 like this:
17267 @lisp
17268 (org-add-agenda-custom-command
17269  '("b" todo "PROJECT"
17270    ((org-agenda-skip-function 'my-skip-unless-waiting)
17271     (org-agenda-overriding-header "Projects waiting for something: "))))
17272 @end lisp
17274 @vindex org-agenda-overriding-header
17275 Note that this also binds @code{org-agenda-overriding-header} to get a
17276 meaningful header in the agenda view.
17278 @vindex org-odd-levels-only
17279 @vindex org-agenda-skip-function
17280 A general way to create custom searches is to base them on a search for
17281 entries with a certain level limit.  If you want to study all entries with
17282 your custom search function, simply do a search for
17283 @samp{LEVEL>0}@footnote{Note that, when using @code{org-odd-levels-only}, a
17284 level number corresponds to order in the hierarchy, not to the number of
17285 stars.}, and then use @code{org-agenda-skip-function} to select the entries
17286 you really want to have.
17288 You may also put a Lisp form into @code{org-agenda-skip-function}.  In
17289 particular, you may use the functions @code{org-agenda-skip-entry-if}
17290 and @code{org-agenda-skip-subtree-if} in this form, for example:
17292 @table @code
17293 @item (org-agenda-skip-entry-if 'scheduled)
17294 Skip current entry if it has been scheduled.
17295 @item (org-agenda-skip-entry-if 'notscheduled)
17296 Skip current entry if it has not been scheduled.
17297 @item (org-agenda-skip-entry-if 'deadline)
17298 Skip current entry if it has a deadline.
17299 @item (org-agenda-skip-entry-if 'scheduled 'deadline)
17300 Skip current entry if it has a deadline, or if it is scheduled.
17301 @item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
17302 Skip current entry if the TODO keyword is TODO or WAITING.
17303 @item (org-agenda-skip-entry-if 'todo 'done)
17304 Skip current entry if the TODO keyword marks a DONE state.
17305 @item (org-agenda-skip-entry-if 'timestamp)
17306 Skip current entry if it has any timestamp, may also be deadline or scheduled.
17307 @anchor{x-agenda-skip-entry-regexp}
17308 @item (org-agenda-skip-entry-if 'regexp "regular expression")
17309 Skip current entry if the regular expression matches in the entry.
17310 @item (org-agenda-skip-entry-if 'notregexp "regular expression")
17311 Skip current entry unless the regular expression matches.
17312 @item (org-agenda-skip-subtree-if 'regexp "regular expression")
17313 Same as above, but check and skip the entire subtree.
17314 @end table
17316 Therefore we could also have written the search for WAITING projects
17317 like this, even without defining a special function:
17319 @lisp
17320 (org-add-agenda-custom-command
17321  '("b" todo "PROJECT"
17322    ((org-agenda-skip-function '(org-agenda-skip-subtree-if
17323                                 'regexp ":waiting:"))
17324     (org-agenda-overriding-header "Projects waiting for something: "))))
17325 @end lisp
17327 @node Speeding up your agendas, Extracting agenda information, Special agenda views, Hacking
17328 @section Speeding up your agendas
17329 @cindex agenda views, optimization
17331 When your Org files grow in both number and size, agenda commands may start
17332 to become slow.  Below are some tips on how to speed up the agenda commands.
17334 @enumerate
17335 @item
17336 Reduce the number of Org agenda files: this will reduce the slowness caused
17337 by accessing a hard drive.
17338 @item
17339 Reduce the number of DONE and archived headlines: this way the agenda does
17340 not need to skip them.
17341 @item
17342 @vindex org-agenda-dim-blocked-tasks
17343 Inhibit the dimming of blocked tasks:
17344 @lisp
17345 (setq org-agenda-dim-blocked-tasks nil)
17346 @end lisp
17347 @item
17348 @vindex org-startup-folded
17349 @vindex org-agenda-inhibit-startup
17350 Inhibit agenda files startup options:
17351 @lisp
17352 (setq org-agenda-inhibit-startup nil)
17353 @end lisp
17354 @item
17355 @vindex org-agenda-show-inherited-tags
17356 @vindex org-agenda-use-tag-inheritance
17357 Disable tag inheritance in agenda:
17358 @lisp
17359 (setq org-agenda-use-tag-inheritance nil)
17360 @end lisp
17361 @end enumerate
17363 You can set these options for specific agenda views only.  See the docstrings
17364 of these variables for details on why they affect the agenda generation, and
17365 this @uref{http://orgmode.org/worg/agenda-optimization.html, dedicated Worg
17366 page} for further explanations.
17368 @node Extracting agenda information, Using the property API, Speeding up your agendas, Hacking
17369 @section Extracting agenda information
17370 @cindex agenda, pipe
17371 @cindex Scripts, for agenda processing
17373 @vindex org-agenda-custom-commands
17374 Org provides commands to access agenda information for the command
17375 line in Emacs batch mode.  This extracted information can be sent
17376 directly to a printer, or it can be read by a program that does further
17377 processing of the data.  The first of these commands is the function
17378 @code{org-batch-agenda}, that produces an agenda view and sends it as
17379 ASCII text to STDOUT@.  The command takes a single string as parameter.
17380 If the string has length 1, it is used as a key to one of the commands
17381 you have configured in @code{org-agenda-custom-commands}, basically any
17382 key you can use after @kbd{C-c a}.  For example, to directly print the
17383 current TODO list, you could use
17385 @example
17386 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
17387 @end example
17389 If the parameter is a string with 2 or more characters, it is used as a
17390 tags/TODO match string.  For example, to print your local shopping list
17391 (all items with the tag @samp{shop}, but excluding the tag
17392 @samp{NewYork}), you could use
17394 @example
17395 emacs -batch -l ~/.emacs                                      \
17396       -eval '(org-batch-agenda "+shop-NewYork")' | lpr
17397 @end example
17399 @noindent
17400 You may also modify parameters on the fly like this:
17402 @example
17403 emacs -batch -l ~/.emacs                                      \
17404    -eval '(org-batch-agenda "a"                               \
17405             org-agenda-span (quote month)                     \
17406             org-agenda-include-diary nil                      \
17407             org-agenda-files (quote ("~/org/project.org")))'  \
17408    | lpr
17409 @end example
17411 @noindent
17412 which will produce a 30-day agenda, fully restricted to the Org file
17413 @file{~/org/projects.org}, not even including the diary.
17415 If you want to process the agenda data in more sophisticated ways, you
17416 can use the command @code{org-batch-agenda-csv} to get a comma-separated
17417 list of values for each agenda item.  Each line in the output will
17418 contain a number of fields separated by commas.  The fields in a line
17419 are:
17421 @example
17422 category     @r{The category of the item}
17423 head         @r{The headline, without TODO keyword, TAGS and PRIORITY}
17424 type         @r{The type of the agenda entry, can be}
17425                 todo               @r{selected in TODO match}
17426                 tagsmatch          @r{selected in tags match}
17427                 diary              @r{imported from diary}
17428                 deadline           @r{a deadline}
17429                 scheduled          @r{scheduled}
17430                 timestamp          @r{appointment, selected by timestamp}
17431                 closed             @r{entry was closed on date}
17432                 upcoming-deadline  @r{warning about nearing deadline}
17433                 past-scheduled     @r{forwarded scheduled item}
17434                 block              @r{entry has date block including date}
17435 todo         @r{The TODO keyword, if any}
17436 tags         @r{All tags including inherited ones, separated by colons}
17437 date         @r{The relevant date, like 2007-2-14}
17438 time         @r{The time, like 15:00-16:50}
17439 extra        @r{String with extra planning info}
17440 priority-l   @r{The priority letter if any was given}
17441 priority-n   @r{The computed numerical priority}
17442 @end example
17444 @noindent
17445 Time and date will only be given if a timestamp (or deadline/scheduled)
17446 led to the selection of the item.
17448 A CSV list like this is very easy to use in a post-processing script.
17449 For example, here is a Perl program that gets the TODO list from
17450 Emacs/Org and prints all the items, preceded by a checkbox:
17452 @example
17453 #!/usr/bin/perl
17455 # define the Emacs command to run
17456 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
17458 # run it and capture the output
17459 $agenda = qx@{$cmd 2>/dev/null@};
17461 # loop over all lines
17462 foreach $line (split(/\n/,$agenda)) @{
17463   # get the individual values
17464   ($category,$head,$type,$todo,$tags,$date,$time,$extra,
17465    $priority_l,$priority_n) = split(/,/,$line);
17466   # process and print
17467   print "[ ] $head\n";
17469 @end example
17471 @node Using the property API, Using the mapping API, Extracting agenda information, Hacking
17472 @section Using the property API
17473 @cindex API, for properties
17474 @cindex properties, API
17476 Here is a description of the functions that can be used to work with
17477 properties.
17479 @defun org-entry-properties &optional pom which
17480 Get all properties of the entry at point-or-marker POM.@*
17481 This includes the TODO keyword, the tags, time strings for deadline,
17482 scheduled, and clocking, and any additional properties defined in the
17483 entry.  The return value is an alist.  Keys may occur multiple times
17484 if the property key was used several times.@*
17485 POM may also be @code{nil}, in which case the current entry is used.
17486 If WHICH is @code{nil} or `all', get all properties.  If WHICH is
17487 `special' or `standard', only get that subclass.
17488 @end defun
17489 @vindex org-use-property-inheritance
17490 @findex org-insert-property-drawer
17491 @defun org-entry-get pom property &optional inherit
17492 Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@.  By default,
17493 this only looks at properties defined locally in the entry.  If @code{INHERIT}
17494 is non-@code{nil} and the entry does not have the property, then also check
17495 higher levels of the hierarchy.  If @code{INHERIT} is the symbol
17496 @code{selective}, use inheritance if and only if the setting of
17497 @code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance.
17498 @end defun
17500 @defun org-entry-delete pom property
17501 Delete the property @code{PROPERTY} from entry at point-or-marker POM.
17502 @end defun
17504 @defun org-entry-put pom property value
17505 Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM.
17506 @end defun
17508 @defun org-buffer-property-keys &optional include-specials
17509 Get all property keys in the current buffer.
17510 @end defun
17512 @defun org-insert-property-drawer
17513 Insert a property drawer for the current entry.  Also
17514 @end defun
17516 @defun org-entry-put-multivalued-property pom property &rest values
17517 Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@.
17518 @code{VALUES} should be a list of strings.  They will be concatenated, with
17519 spaces as separators.
17520 @end defun
17522 @defun org-entry-get-multivalued-property pom property
17523 Treat the value of the property @code{PROPERTY} as a whitespace-separated
17524 list of values and return the values as a list of strings.
17525 @end defun
17527 @defun org-entry-add-to-multivalued-property pom property value
17528 Treat the value of the property @code{PROPERTY} as a whitespace-separated
17529 list of values and make sure that @code{VALUE} is in this list.
17530 @end defun
17532 @defun org-entry-remove-from-multivalued-property pom property value
17533 Treat the value of the property @code{PROPERTY} as a whitespace-separated
17534 list of values and make sure that @code{VALUE} is @emph{not} in this list.
17535 @end defun
17537 @defun org-entry-member-in-multivalued-property pom property value
17538 Treat the value of the property @code{PROPERTY} as a whitespace-separated
17539 list of values and check if @code{VALUE} is in this list.
17540 @end defun
17542 @defopt org-property-allowed-value-functions
17543 Hook for functions supplying allowed values for a specific property.
17544 The functions must take a single argument, the name of the property, and
17545 return a flat list of allowed values.  If @samp{:ETC} is one of
17546 the values, use the values as completion help, but allow also other values
17547 to be entered.  The functions must return @code{nil} if they are not
17548 responsible for this property.
17549 @end defopt
17551 @node Using the mapping API,  , Using the property API, Hacking
17552 @section Using the mapping API
17553 @cindex API, for mapping
17554 @cindex mapping entries, API
17556 Org has sophisticated mapping capabilities to find all entries satisfying
17557 certain criteria.  Internally, this functionality is used to produce agenda
17558 views, but there is also an API that can be used to execute arbitrary
17559 functions for each or selected entries.  The main entry point for this API
17562 @defun org-map-entries func &optional match scope &rest skip
17563 Call @code{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}.
17565 @code{FUNC} is a function or a Lisp form.  The function will be called
17566 without arguments, with the cursor positioned at the beginning of the
17567 headline.  The return values of all calls to the function will be collected
17568 and returned as a list.
17570 The call to @code{FUNC} will be wrapped into a save-excursion form, so
17571 @code{FUNC} does not need to preserve point.  After evaluation, the cursor
17572 will be moved to the end of the line (presumably of the headline of the
17573 processed entry) and search continues from there.  Under some circumstances,
17574 this may not produce the wanted results.  For example, if you have removed
17575 (e.g., archived) the current (sub)tree it could mean that the next entry will
17576 be skipped entirely.  In such cases, you can specify the position from where
17577 search should continue by making @code{FUNC} set the variable
17578 @code{org-map-continue-from} to the desired buffer position.
17580 @code{MATCH} is a tags/property/todo match as it is used in the agenda match
17581 view.  Only headlines that are matched by this query will be considered
17582 during the iteration.  When @code{MATCH} is @code{nil} or @code{t}, all
17583 headlines will be visited by the iteration.
17585 @code{SCOPE} determines the scope of this command.  It can be any of:
17587 @example
17588 nil     @r{the current buffer, respecting the restriction if any}
17589 tree    @r{the subtree started with the entry at point}
17590 region  @r{The entries within the active region, if any}
17591 file    @r{the current buffer, without restriction}
17592 file-with-archives
17593         @r{the current buffer, and any archives associated with it}
17594 agenda  @r{all agenda files}
17595 agenda-with-archives
17596         @r{all agenda files with any archive files associated with them}
17597 (file1 file2 ...)
17598         @r{if this is a list, all files in the list will be scanned}
17599 @end example
17600 @noindent
17601 The remaining args are treated as settings for the skipping facilities of
17602 the scanner.  The following items can be given here:
17604 @vindex org-agenda-skip-function
17605 @example
17606 archive   @r{skip trees with the archive tag}
17607 comment   @r{skip trees with the COMMENT keyword}
17608 function or Lisp form
17609           @r{will be used as value for @code{org-agenda-skip-function},}
17610           @r{so whenever the function returns t, FUNC}
17611           @r{will not be called for that entry and search will}
17612           @r{continue from the point where the function leaves it}
17613 @end example
17614 @end defun
17616 The function given to that mapping routine can really do anything you like.
17617 It can use the property API (@pxref{Using the property API}) to gather more
17618 information about the entry, or in order to change metadata in the entry.
17619 Here are a couple of functions that might be handy:
17621 @defun org-todo &optional arg
17622 Change the TODO state of the entry.  See the docstring of the functions for
17623 the many possible values for the argument @code{ARG}.
17624 @end defun
17626 @defun org-priority &optional action
17627 Change the priority of the entry.  See the docstring of this function for the
17628 possible values for @code{ACTION}.
17629 @end defun
17631 @defun org-toggle-tag tag &optional onoff
17632 Toggle the tag @code{TAG} in the current entry.  Setting @code{ONOFF} to
17633 either @code{on} or @code{off} will not toggle tag, but ensure that it is
17634 either on or off.
17635 @end defun
17637 @defun org-promote
17638 Promote the current entry.
17639 @end defun
17641 @defun org-demote
17642 Demote the current entry.
17643 @end defun
17645 Here is a simple example that will turn all entries in the current file with
17646 a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}.
17647 Entries in comment trees and in archive trees will be ignored.
17649 @lisp
17650 (org-map-entries
17651  '(org-todo "UPCOMING")
17652  "+TOMORROW" 'file 'archive 'comment)
17653 @end lisp
17655 The following example counts the number of entries with TODO keyword
17656 @code{WAITING}, in all agenda files.
17658 @lisp
17659 (length (org-map-entries t "/+WAITING" 'agenda))
17660 @end lisp
17662 @node MobileOrg, History and Acknowledgments, Hacking, Top
17663 @appendix MobileOrg
17664 @cindex iPhone
17665 @cindex MobileOrg
17667 @i{MobileOrg} is the name of the mobile companion app for Org mode, currently
17668 available for iOS and for Android.  @i{MobileOrg} offers offline viewing and
17669 capture support for an Org mode system rooted on a ``real'' computer.  It
17670 does also allow you to record changes to existing entries.  The
17671 @uref{https://github.com/MobileOrg/, iOS implementation} for the
17672 @i{iPhone/iPod Touch/iPad} series of devices, was started by Richard Moreland
17673 and is now in the hands Sean Escriva.  Android users should check out
17674 @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}
17675 by Matt Jones.  The two implementations are not identical but offer similar
17676 features.
17678 This appendix describes the support Org has for creating agenda views in a
17679 format that can be displayed by @i{MobileOrg}, and for integrating notes
17680 captured and changes made by @i{MobileOrg} into the main system.
17682 For changing tags and TODO states in MobileOrg, you should have set up the
17683 customization variables @code{org-todo-keywords} and @code{org-tag-alist} to
17684 cover all important tags and TODO keywords, even if individual files use only
17685 part of these.  MobileOrg will also offer you states and tags set up with
17686 in-buffer settings, but it will understand the logistics of TODO state
17687 @i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags
17688 (@pxref{Setting tags}) only for those set in these variables.
17690 @menu
17691 * Setting up the staging area::  Where to interact with the mobile device
17692 * Pushing to MobileOrg::        Uploading Org files and agendas
17693 * Pulling from MobileOrg::      Integrating captured and flagged items
17694 @end menu
17696 @node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg
17697 @section Setting up the staging area
17699 MobileOrg needs to interact with Emacs through a directory on a server.  If you
17700 are using a public server, you should consider to encrypt the files that are
17701 uploaded to the server.  This can be done with Org mode 7.02 and with
17702 @i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl}
17703 installation on your system.  To turn on encryption, set a password in
17704 @i{MobileOrg} and, on the Emacs side, configure the variable
17705 @code{org-mobile-use-encryption}@footnote{If you can safely store the
17706 password in your Emacs setup, you might also want to configure
17707 @code{org-mobile-encryption-password}.  Please read the docstring of that
17708 variable.  Note that encryption will apply only to the contents of the
17709 @file{.org} files.  The file names themselves will remain visible.}.
17711 The easiest way to create that directory is to use a free
17712 @uref{http://dropbox.com,Dropbox.com} account@footnote{If you cannot use
17713 Dropbox, or if your version of MobileOrg does not support it, you can use a
17714 webdav server.  For more information, check out the documentation of MobileOrg and also this
17715 @uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
17716 When MobileOrg first connects to your Dropbox, it will create a directory
17717 @i{MobileOrg} inside the Dropbox.  After the directory has been created, tell
17718 Emacs about it:
17720 @lisp
17721 (setq org-mobile-directory "~/Dropbox/MobileOrg")
17722 @end lisp
17724 Org mode has commands to put files for @i{MobileOrg} into that directory,
17725 and to read captured notes from there.
17727 @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
17728 @section Pushing to MobileOrg
17730 This operation copies all files currently listed in @code{org-mobile-files}
17731 to the directory @code{org-mobile-directory}.  By default this list contains
17732 all agenda files (as listed in @code{org-agenda-files}), but additional files
17733 can be included by customizing @code{org-mobile-files}.  File names will be
17734 staged with paths relative to @code{org-directory}, so all files should be
17735 inside this directory@footnote{Symbolic links in @code{org-directory} need to
17736 have the same name than their targets.}.
17738 The push operation also creates a special Org file @file{agendas.org} with
17739 all custom agenda view defined by the user@footnote{While creating the
17740 agendas, Org mode will force ID properties on all referenced entries, so that
17741 these entries can be uniquely identified if @i{MobileOrg} flags them for
17742 further action.  If you do not want to get these properties in so many
17743 entries, you can set the variable @code{org-mobile-force-id-on-agenda-items}
17744 to @code{nil}.  Org mode will then rely on outline paths, in the hope that
17745 these will be unique enough.}.
17747 Finally, Org writes the file @file{index.org}, containing links to all other
17748 files.  @i{MobileOrg} first reads this file from the server, and then
17749 downloads all agendas and Org files listed in it.  To speed up the download,
17750 MobileOrg will only read files whose checksums@footnote{Checksums are stored
17751 automatically in the file @file{checksums.dat}} have changed.
17753 @node Pulling from MobileOrg,  , Pushing to MobileOrg, MobileOrg
17754 @section Pulling from MobileOrg
17756 When @i{MobileOrg} synchronizes with the server, it not only pulls the Org
17757 files for viewing.  It also appends captured entries and pointers to flagged
17758 and changed entries to the file @file{mobileorg.org} on the server.  Org has
17759 a @emph{pull} operation that integrates this information into an inbox file
17760 and operates on the pointers to flagged entries.  Here is how it works:
17762 @enumerate
17763 @item
17764 Org moves all entries found in
17765 @file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this
17766 operation.} and appends them to the file pointed to by the variable
17767 @code{org-mobile-inbox-for-pull}.  Each captured entry and each editing event
17768 will be a top-level entry in the inbox file.
17769 @item
17770 After moving the entries, Org will attempt to implement the changes made in
17771 @i{MobileOrg}.  Some changes are applied directly and without user
17772 interaction.  Examples are all changes to tags, TODO state, headline and body
17773 text that can be cleanly applied.  Entries that have been flagged for further
17774 action will receive a tag @code{:FLAGGED:}, so that they can be easily found
17775 again.  When there is a problem finding an entry or applying the change, the
17776 pointer entry will remain in the inbox and will be marked with an error
17777 message.  You need to later resolve these issues by hand.
17778 @item
17779 Org will then generate an agenda view with all flagged entries.  The user
17780 should then go through these entries and do whatever actions are necessary.
17781 If a note has been stored while flagging an entry in @i{MobileOrg}, that note
17782 will be displayed in the echo area when the cursor is on the corresponding
17783 agenda line.
17785 @table @kbd
17786 @kindex ?
17787 @item ?
17788 Pressing @kbd{?} in that special agenda will display the full flagging note in
17789 another window and also push it onto the kill ring.  So you could use @kbd{?
17790 z C-y C-c C-c} to store that flagging note as a normal note in the entry.
17791 Pressing @kbd{?} twice in succession will offer to remove the
17792 @code{:FLAGGED:} tag along with the recorded flagging note (which is stored
17793 in a property).  In this way you indicate that the intended processing for
17794 this flagged entry is finished.
17795 @end table
17796 @end enumerate
17798 @kindex C-c a ?
17799 If you are not able to process all flagged entries directly, you can always
17800 return to this agenda view@footnote{Note, however, that there is a subtle
17801 difference.  The view created automatically by @kbd{M-x org-mobile-pull RET}
17802 is guaranteed to search all files that have been addressed by the last pull.
17803 This might include a file that is not currently in your list of agenda files.
17804 If you later use @kbd{C-c a ?} to regenerate the view, only the current
17805 agenda files will be searched.} using @kbd{C-c a ?}.
17807 @node History and Acknowledgments, GNU Free Documentation License, MobileOrg, Top
17808 @appendix History and acknowledgments
17809 @cindex acknowledgments
17810 @cindex history
17811 @cindex thanks
17813 @section From Carsten
17815 Org was born in 2003, out of frustration over the user interface of the Emacs
17816 Outline mode.  I was trying to organize my notes and projects, and using
17817 Emacs seemed to be the natural way to go.  However, having to remember eleven
17818 different commands with two or three keys per command, only to hide and show
17819 parts of the outline tree, that seemed entirely unacceptable to me.  Also,
17820 when using outlines to take notes, I constantly wanted to restructure the
17821 tree, organizing it parallel to my thoughts and plans.  @emph{Visibility
17822 cycling} and @emph{structure editing} were originally implemented in the
17823 package @file{outline-magic.el}, but quickly moved to the more general
17824 @file{org.el}.  As this environment became comfortable for project planning,
17825 the next step was adding @emph{TODO entries}, basic @emph{timestamps}, and
17826 @emph{table support}.  These areas highlighted the two main goals that Org
17827 still has today: to be a new, outline-based, plain text mode with innovative
17828 and intuitive editing features, and to incorporate project planning
17829 functionality directly into a notes file.
17831 Since the first release, literally thousands of emails to me or to
17832 @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug
17833 reports, feedback, new ideas, and sometimes patches and add-on code.
17834 Many thanks to everyone who has helped to improve this package.  I am
17835 trying to keep here a list of the people who had significant influence
17836 in shaping one or more aspects of Org.  The list may not be
17837 complete, if I have forgotten someone, please accept my apologies and
17838 let me know.
17840 Before I get to this list, a few special mentions are in order:
17842 @table @i
17843 @item Bastien Guerry
17844 Bastien has written a large number of extensions to Org (most of them
17845 integrated into the core by now), including the @LaTeX{} exporter and the plain
17846 list parser.  His support during the early days, when he basically acted as
17847 co-maintainer, was central to the success of this project.  Bastien also
17848 invented Worg, helped establishing the Web presence of Org, and sponsored
17849 hosting costs for the orgmode.org website.
17850 @item Eric Schulte and Dan Davison
17851 Eric and Dan are jointly responsible for the Org-babel system, which turns
17852 Org into a multi-language environment for evaluating code and doing literate
17853 programming and reproducible research.
17854 @item John Wiegley
17855 John has contributed a number of great ideas and patches directly to Org,
17856 including the attachment system (@file{org-attach.el}), integration with
17857 Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO
17858 items, habit tracking (@file{org-habits.el}), and encryption
17859 (@file{org-crypt.el}).  Also, the capture system is really an extended copy
17860 of his great @file{remember.el}.
17861 @item Sebastian Rose
17862 Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
17863 of an ignorant amateur.  Sebastian has pushed this part of Org onto a much
17864 higher level.  He also wrote @file{org-info.js}, a Java script for displaying
17865 web pages derived from Org using an Info-like or a folding interface with
17866 single-key navigation.
17867 @end table
17869 @noindent See below for the full list of contributions!  Again, please
17870 let me know what I am missing here!
17872 @section From Bastien
17874 I (Bastien) have been maintaining Org since January 2011.  This appendix
17875 would not be complete without adding a few more acknowledgements and thanks
17876 to Carsten's ones above.
17878 I am first grateful to Carsten for his trust while handing me over the
17879 maintainership of Org.  His unremitting support is what really helped me
17880 getting more confident over time, with both the community and the code.
17882 When I took over maintainership, I knew I would have to make Org more
17883 collaborative than ever, as I would have to rely on people that are more
17884 knowledgeable than I am on many parts of the code.  Here is a list of the
17885 persons I could rely on, they should really be considered co-maintainers,
17886 either of the code or the community:
17888 @table @i
17889 @item Eric Schulte
17890 Eric is maintaining the Babel parts of Org.  His reactivity here kept me away
17891 from worrying about possible bugs here and let me focus on other parts.
17893 @item Nicolas Goaziou
17894 Nicolas is maintaining the consistency of the deepest parts of Org.  His
17895 work on @file{org-element.el} and @file{ox.el} has been outstanding, and
17896 opened the doors for many new ideas and features.  He rewrote many of the
17897 old exporters to use the new export engine, and helped with documenting
17898 this major change.  More importantly (if that's possible), he has been more
17899 than reliable during all the work done for Org 8.0, and always very
17900 reactive on the mailing list.
17902 @item Achim Gratz
17903 Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
17904 into a flexible and conceptually clean process.  He patiently coped with the
17905 many hiccups that such a change can create for users.
17907 @item Nick Dokos
17908 The Org mode mailing list would not be such a nice place without Nick, who
17909 patiently helped users so many times.  It is impossible to overestimate such
17910 a great help, and the list would not be so active without him.
17911 @end table
17913 I received support from so many users that it is clearly impossible to be
17914 fair when shortlisting a few of them, but Org's history would not be
17915 complete if the ones above were not mentioned in this manual.
17917 @section List of contributions
17919 @itemize @bullet
17921 @item
17922 @i{Russel Adams} came up with the idea for drawers.
17923 @item
17924 @i{Suvayu Ali} has steadily helped on the mailing list, providing useful
17925 feedback on many features and several patches.
17926 @item
17927 @i{Luis Anaya} wrote @file{ox-man.el}.
17928 @item
17929 @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
17930 @item
17931 @i{Michael Brand} helped by reporting many bugs and testing many features.
17932 He also implemented the distinction between empty fields and 0-value fields
17933 in Org's spreadsheets.
17934 @item
17935 @i{Christophe Bataillon} created the great unicorn logo that we use on the
17936 Org mode website.
17937 @item
17938 @i{Alex Bochannek} provided a patch for rounding timestamps.
17939 @item
17940 @i{Jan Böcker} wrote @file{org-docview.el}.
17941 @item
17942 @i{Brad Bozarth} showed how to pull RSS feed data into Org mode files.
17943 @item
17944 @i{Tom Breton} wrote @file{org-choose.el}.
17945 @item
17946 @i{Charles Cave}'s suggestion sparked the implementation of templates
17947 for Remember, which are now templates for capture.
17948 @item
17949 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
17950 specified time.
17951 @item
17952 @i{Gregory Chernov} patched support for Lisp forms into table
17953 calculations and improved XEmacs compatibility, in particular by porting
17954 @file{nouline.el} to XEmacs.
17955 @item
17956 @i{Sacha Chua} suggested copying some linking code from Planner.
17957 @item
17958 @i{Toby S. Cubitt} contributed to the code for clock formats.
17959 @item
17960 @i{Baoqiu Cui} contributed the DocBook exporter.  It has been deleted from
17961 Org 8.0: you can now export to Texinfo and export the @file{.texi} file to
17962 DocBook using @code{makeinfo}.
17963 @item
17964 @i{Eddward DeVilla} proposed and tested checkbox statistics.  He also
17965 came up with the idea of properties, and that there should be an API for
17966 them.
17967 @item
17968 @i{Nick Dokos} tracked down several nasty bugs.
17969 @item
17970 @i{Kees Dullemond} used to edit projects lists directly in HTML and so
17971 inspired some of the early development, including HTML export.  He also
17972 asked for a way to narrow wide table columns.
17973 @item
17974 @i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for
17975 several years now.  He also sponsored the hosting costs until Rackspace
17976 started to host us for free.
17977 @item
17978 @i{Thomas S. Dye} contributed documentation on Worg and helped integrating
17979 the Org-Babel documentation into the manual.
17980 @item
17981 @i{Christian Egli} converted the documentation into Texinfo format, inspired
17982 the agenda, patched CSS formatting into the HTML exporter, and wrote
17983 @file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as
17984 @file{ox-taskjuggler.el} for Org 8.0.
17985 @item
17986 @i{David Emery} provided a patch for custom CSS support in exported
17987 HTML agendas.
17988 @item
17989 @i{Sean Escriva} took over MobileOrg development on the iPhone platform.
17990 @item
17991 @i{Nic Ferrier} contributed mailcap and XOXO support.
17992 @item
17993 @i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
17994 @item
17995 @i{John Foerch} figured out how to make incremental search show context
17996 around a match in a hidden outline tree.
17997 @item
17998 @i{Raimar Finken} wrote @file{org-git-line.el}.
17999 @item
18000 @i{Mikael Fornius} works as a mailing list moderator.
18001 @item
18002 @i{Austin Frank} works as a mailing list moderator.
18003 @item
18004 @i{Eric Fraga} drove the development of BEAMER export with ideas and
18005 testing.
18006 @item
18007 @i{Barry Gidden} did proofreading the manual in preparation for the book
18008 publication through Network Theory Ltd.
18009 @item
18010 @i{Niels Giesen} had the idea to automatically archive DONE trees.
18011 @item
18012 @i{Nicolas Goaziou} rewrote much of the plain list code.  He also wrote
18013 @file{org-element.el} and @file{org-export.el}, which was a huge step forward
18014 in implementing a clean framework for Org exporters.
18015 @item
18016 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
18017 @item
18018 @i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a
18019 book.
18020 @item
18021 @i{Bernt Hansen} has driven much of the support for auto-repeating tasks,
18022 task state change logging, and the clocktable.  His clear explanations have
18023 been critical when we started to adopt the Git version control system.
18024 @item
18025 @i{Manuel Hermenegildo} has contributed various ideas, small fixes and
18026 patches.
18027 @item
18028 @i{Phil Jackson} wrote @file{org-irc.el}.
18029 @item
18030 @i{Scott Jaderholm} proposed footnotes, control over whitespace between
18031 folded entries, and column view for properties.
18032 @item
18033 @i{Matt Jones} wrote @i{MobileOrg Android}.
18034 @item
18035 @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
18036 @item
18037 @i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}.
18038 @item
18039 @i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it.  He also
18040 provided frequent feedback and some patches.
18041 @item
18042 @i{Matt Lundin} has proposed last-row references for table formulas and named
18043 invisible anchors.  He has also worked a lot on the FAQ.
18044 @item
18045 @i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,
18046 and is a prolific contributor on the mailing list with competent replies,
18047 small fixes and patches.
18048 @item
18049 @i{Jason F. McBrayer} suggested agenda export to CSV format.
18050 @item
18051 @i{Max Mikhanosha} came up with the idea of refiling and sticky agendas.
18052 @item
18053 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file
18054 basis.
18055 @item
18056 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
18057 happy.
18058 @item
18059 @i{Richard Moreland} wrote @i{MobileOrg} for the iPhone.
18060 @item
18061 @i{Rick Moynihan} proposed allowing multiple TODO sequences in a file
18062 and being able to quickly restrict the agenda to a subtree.
18063 @item
18064 @i{Todd Neal} provided patches for links to Info files and Elisp forms.
18065 @item
18066 @i{Greg Newman} refreshed the unicorn logo into its current form.
18067 @item
18068 @i{Tim O'Callaghan} suggested in-file links, search options for general
18069 file links, and TAGS.
18070 @item
18071 @i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text
18072 version of the reference card.
18073 @item
18074 @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
18075 into Japanese.
18076 @item
18077 @i{Oliver Oppitz} suggested multi-state TODO items.
18078 @item
18079 @i{Scott Otterson} sparked the introduction of descriptive text for
18080 links, among other things.
18081 @item
18082 @i{Pete Phillips} helped during the development of the TAGS feature, and
18083 provided frequent feedback.
18084 @item
18085 @i{Francesco Pizzolante} provided patches that helped speeding up the agenda
18086 generation.
18087 @item
18088 @i{Martin Pohlack} provided the code snippet to bundle character insertion
18089 into bundles of 20 for undo.
18090 @item
18091 @i{Rackspace.com} is hosting our website for free.  Thank you Rackspace!
18092 @item
18093 @i{T.V. Raman} reported bugs and suggested improvements.
18094 @item
18095 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
18096 control.
18097 @item
18098 @i{Paul Rivier} provided the basic implementation of named footnotes.  He
18099 also acted as mailing list moderator for some time.
18100 @item
18101 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
18102 @item
18103 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
18104 conflict with @file{allout.el}.
18105 @item
18106 @i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with
18107 extensive patches.
18108 @item
18109 @i{Philip Rooke} created the Org reference card, provided lots
18110 of feedback, developed and applied standards to the Org documentation.
18111 @item
18112 @i{Christian Schlauer} proposed angular brackets around links, among
18113 other things.
18114 @item
18115 @i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can
18116 enjoy folding in non-org buffers by using Org headlines in comments.
18117 @item
18118 @i{Paul Sexton} wrote @file{org-ctags.el}.
18119 @item
18120 Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
18121 @file{organizer-mode.el}.
18122 @item
18123 @i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal
18124 examples, and remote highlighting for referenced code lines.
18125 @item
18126 @i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is
18127 now packaged into Org's @file{contrib} directory.
18128 @item
18129 @i{Daniel Sinder} came up with the idea of internal archiving by locking
18130 subtrees.
18131 @item
18132 @i{Dale Smith} proposed link abbreviations.
18133 @item
18134 @i{James TD Smith} has contributed a large number of patches for useful
18135 tweaks and features.
18136 @item
18137 @i{Adam Spiers} asked for global linking commands, inspired the link
18138 extension system, added support for mairix, and proposed the mapping API.
18139 @item
18140 @i{Ulf Stegemann} created the table to translate special symbols to HTML,
18141 @LaTeX{}, UTF-8, Latin-1 and ASCII.
18142 @item
18143 @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
18144 with links transformation to Org syntax.
18145 @item
18146 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
18147 chapter about publishing.
18148 @item
18149 @i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter.
18150 @item
18151 @i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
18152 enabled source code highlighting in Gnus.
18153 @item
18154 @i{Stefan Vollmar} organized a video-recorded talk at the
18155 Max-Planck-Institute for Neurology.  He also inspired the creation of a
18156 concept index for HTML export.
18157 @item
18158 @i{J@"urgen Vollmer} contributed code generating the table of contents
18159 in HTML output.
18160 @item
18161 @i{Samuel Wales} has provided important feedback and bug reports.
18162 @item
18163 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
18164 keyword.
18165 @item
18166 @i{David Wainberg} suggested archiving, and improvements to the linking
18167 system.
18168 @item
18169 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
18170 linking to Gnus.
18171 @item
18172 @i{Roland Winkler} requested additional key bindings to make Org
18173 work on a tty.
18174 @item
18175 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
18176 and contributed various ideas and code snippets.
18177 @end itemize
18180 @node GNU Free Documentation License, Main Index, History and Acknowledgments, Top
18181 @appendix GNU Free Documentation License
18182 @include doclicense.texi
18185 @node Main Index, Key Index, GNU Free Documentation License, Top
18186 @unnumbered Concept index
18188 @printindex cp
18190 @node Key Index, Command and Function Index, Main Index, Top
18191 @unnumbered Key index
18193 @printindex ky
18195 @node Command and Function Index, Variable Index, Key Index, Top
18196 @unnumbered Command and function index
18198 @printindex fn
18200 @node Variable Index,  , Command and Function Index, Top
18201 @unnumbered Variable index
18203 This is not a complete index of variables and faces, only the ones that are
18204 mentioned in the manual.  For a more complete list, use @kbd{M-x
18205 org-customize @key{RET}} and then click yourself through the tree.
18207 @printindex vr
18209 @bye
18211 @c Local variables:
18212 @c fill-column: 77
18213 @c indent-tabs-mode: nil
18214 @c paragraph-start:    "\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[  ]*$"
18215 @c paragraph-separate: "\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[       \f]*$"
18216 @c End:
18219 @c  LocalWords:  webdavhost pre