org-html.el: New defcustom: `org-export-html-before-content-div'
[org-mode.git] / doc / org.texi
blob10a2428d32d279cb078eacef99dc39bfe781cc4b
2 \input texinfo
3 @c %**start of header
4 @setfilename ../../info/org
5 @settitle The Org Manual
7 @set VERSION 7.6
8 @set DATE July 2011
10 @c Use proper quote and backtick for code sections in PDF output
11 @c Cf. Texinfo manual 14.2
12 @set txicodequoteundirected
13 @set txicodequotebacktick
15 @c Version and Contact Info
16 @set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}
17 @set AUTHOR Carsten Dominik
18 @set MAINTAINER Carsten Dominik
19 @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
20 @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
21 @c %**end of header
22 @finalout
25 @c -----------------------------------------------------------------------------
27 @c Macro definitions for commands and keys
28 @c =======================================
30 @c The behavior of the key/command macros will depend on the flag cmdnames
31 @c When set, commands names are shown.  When clear, they are not shown.
33 @set cmdnames
35 @c Below we define the following macros for Org key tables:
37 @c orgkey{key}                        A key item                     
38 @c orgcmd{key,cmd}                    Key with command name
39 @c xorgcmd{key,cmmand}                Key with command name as @itemx
40 @c orgcmdnki{key,cmd}                 Like orgcmd, but do not index the key
41 @c orgcmdtkc{text,key,cmd}            Like orgcmd,special text instead of key
42 @c orgcmdkkc{key1,key2,cmd}           Two keys with one command name, use "or"
43 @c orgcmdkxkc{key1,key2,cmd}          Two keys with one command name, but
44 @c                                    different functions, so format as @itemx
45 @c orgcmdkskc{key1,key2,cmd}          Same as orgcmdkkc, but use "or short"
46 @c xorgcmdkskc{key1,key2,cmd}         Same as previous, but use @itemx
47 @c orgcmdkkcc{key1,key2,cmd1,cmd2}    Two keys and two commands
49 @c a key but no command
50 @c    Inserts:    @item key
51 @macro orgkey{key}
52 @kindex \key\
53 @item @kbd{\key\}
54 @end macro
56 @macro xorgkey{key}
57 @kindex \key\
58 @itemx @kbd{\key\}
59 @end macro
61 @c one key with a command
62 @c   Inserts:    @item KEY               COMMAND
63 @macro orgcmd{key,command}
64 @ifset cmdnames
65 @kindex \key\
66 @findex \command\
67 @iftex
68 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
69 @end iftex
70 @ifnottex
71 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
72 @end ifnottex
73 @end ifset
74 @ifclear cmdnames
75 @kindex \key\
76 @item @kbd{\key\}
77 @end ifclear
78 @end macro
80 @c One key with one command, formatted using @itemx
81 @c   Inserts:    @itemx KEY               COMMAND
82 @macro xorgcmd{key,command}
83 @ifset cmdnames
84 @kindex \key\
85 @findex \command\
86 @iftex
87 @itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
88 @end iftex
89 @ifnottex
90 @itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
91 @end ifnottex
92 @end ifset
93 @ifclear cmdnames
94 @kindex \key\
95 @itemx @kbd{\key\}
96 @end ifclear
97 @end macro
99 @c one key with a command, bit do not index the key
100 @c   Inserts:    @item KEY               COMMAND
101 @macro orgcmdnki{key,command}
102 @ifset cmdnames
103 @findex \command\
104 @iftex
105 @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
106 @end iftex
107 @ifnottex
108 @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
109 @end ifnottex
110 @end ifset
111 @ifclear cmdnames
112 @item @kbd{\key\}
113 @end ifclear
114 @end macro
116 @c one key with a command, and special text to replace key in item
117 @c   Inserts:    @item TEXT                    COMMAND
118 @macro orgcmdtkc{text,key,command}
119 @ifset cmdnames
120 @kindex \key\
121 @findex \command\
122 @iftex
123 @item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
124 @end iftex
125 @ifnottex
126 @item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
127 @end ifnottex
128 @end ifset
129 @ifclear cmdnames
130 @kindex \key\
131 @item @kbd{\text\}
132 @end ifclear
133 @end macro
135 @c two keys with one command
136 @c   Inserts:    @item KEY1 or KEY2            COMMAND
137 @macro orgcmdkkc{key1,key2,command}
138 @ifset cmdnames
139 @kindex \key1\
140 @kindex \key2\
141 @findex \command\
142 @iftex
143 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
144 @end iftex
145 @ifnottex
146 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
147 @end ifnottex
148 @end ifset
149 @ifclear cmdnames
150 @kindex \key1\
151 @kindex \key2\
152 @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
153 @end ifclear
154 @end macro
156 @c Two keys with one command name, but different functions, so format as
157 @c @itemx
158 @c   Inserts:    @item KEY1
159 @c               @itemx KEY2                COMMAND
160 @macro orgcmdkxkc{key1,key2,command}
161 @ifset cmdnames
162 @kindex \key1\
163 @kindex \key2\
164 @findex \command\
165 @iftex
166 @item @kbd{\key1\}
167 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
168 @end iftex
169 @ifnottex
170 @item @kbd{\key1\}
171 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
172 @end ifnottex
173 @end ifset
174 @ifclear cmdnames
175 @kindex \key1\
176 @kindex \key2\
177 @item @kbd{\key1\}
178 @itemx @kbd{\key2\}
179 @end ifclear
180 @end macro
182 @c Same as previous, but use "or short"
183 @c   Inserts:    @item KEY1 or short KEY2            COMMAND
184 @macro orgcmdkskc{key1,key2,command}
185 @ifset cmdnames
186 @kindex \key1\
187 @kindex \key2\
188 @findex \command\
189 @iftex
190 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
191 @end iftex
192 @ifnottex
193 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
194 @end ifnottex
195 @end ifset
196 @ifclear cmdnames
197 @kindex \key1\
198 @kindex \key2\
199 @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
200 @end ifclear
201 @end macro
203 @c Same as previous, but use @itemx
204 @c   Inserts:    @itemx KEY1 or short KEY2            COMMAND
205 @macro xorgcmdkskc{key1,key2,command}
206 @ifset cmdnames
207 @kindex \key1\
208 @kindex \key2\
209 @findex \command\
210 @iftex
211 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
212 @end iftex
213 @ifnottex
214 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
215 @end ifnottex
216 @end ifset
217 @ifclear cmdnames
218 @kindex \key1\
219 @kindex \key2\
220 @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
221 @end ifclear
222 @end macro
224 @c two keys with two commands
225 @c   Inserts:    @item KEY1                        COMMAND1
226 @c               @itemx KEY2                       COMMAND2
227 @macro orgcmdkkcc{key1,key2,command1,command2}
228 @ifset cmdnames
229 @kindex \key1\
230 @kindex \key2\
231 @findex \command1\
232 @findex \command2\
233 @iftex
234 @item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
235 @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
236 @end iftex
237 @ifnottex
238 @item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
239 @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
240 @end ifnottex
241 @end ifset
242 @ifclear cmdnames
243 @kindex \key1\
244 @kindex \key2\
245 @item @kbd{\key1\}
246 @itemx @kbd{\key2\}
247 @end ifclear
248 @end macro
249 @c -----------------------------------------------------------------------------
251 @iftex
252 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
253 @end iftex
255 @c Subheadings inside a table.
256 @macro tsubheading{text}
257 @ifinfo
258 @subsubheading \text\
259 @end ifinfo
260 @ifnotinfo
261 @item @b{\text\}
262 @end ifnotinfo
263 @end macro
265 @copying
266 This manual is for Org version @value{VERSION}.
268 Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
269 Free Software Foundation, Inc.
271 @quotation
272 Permission is granted to copy, distribute and/or modify this document
273 under the terms of the GNU Free Documentation License, Version 1.3 or
274 any later version published by the Free Software Foundation; with no
275 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
276 and with the Back-Cover Texts as in (a) below.  A copy of the license
277 is included in the section entitled ``GNU Free Documentation License.''
279 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
280 modify this GNU manual.  Buying copies from the FSF supports it in
281 developing GNU and promoting software freedom.''
283 This document is part of a collection distributed under the GNU Free
284 Documentation License.  If you want to distribute this document
285 separately from the collection, you can do so by adding a copy of the
286 license to the document, as described in section 6 of the license.
287 @end quotation
288 @end copying
290 @dircategory Emacs
291 @direntry
292 * Org Mode: (org).      Outline-based notes management and organizer
293 @end direntry
295 @titlepage
296 @title The Org Manual
298 @subtitle Release @value{VERSION}
299 @author by Carsten Dominik
300 with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, and Thomas Dye
302 @c The following two commands start the copyright page.
303 @page
304 @vskip 0pt plus 1filll
305 @insertcopying
306 @end titlepage
308 @c Output the table of contents at the beginning.
309 @contents
311 @ifnottex
312 @node Top, Introduction, (dir), (dir)
313 @top Org Mode Manual
315 @insertcopying
316 @end ifnottex
318 @menu
319 * Introduction::                Getting started
320 * Document Structure::          A tree works like your brain
321 * Tables::                      Pure magic for quick formatting
322 * Hyperlinks::                  Notes in context
323 * TODO Items::                  Every tree branch can be a TODO item
324 * Tags::                        Tagging headlines and matching sets of tags
325 * Properties and Columns::      Storing information about an entry
326 * Dates and Times::             Making items useful for planning
327 * Capture - Refile - Archive::  The ins and outs for projects
328 * Agenda Views::                Collecting information into views
329 * Markup::                      Prepare text for rich export
330 * Exporting::                   Sharing and publishing of notes
331 * Publishing::                  Create a web site of linked Org files
332 * Working With Source Code::    Export, evaluate, and tangle code blocks
333 * Miscellaneous::               All the rest which did not fit elsewhere
334 * Hacking::                     How to hack your way around
335 * MobileOrg::                   Viewing and capture on a mobile device
336 * History and Acknowledgments::  How Org came into being
337 * Main Index::                  An index of Org's concepts and features
338 * Key Index::                   Key bindings and where they are described
339 * Command and Function Index::  Command names and some internal functions
340 * Variable Index::              Variables mentioned in the manual
342 @detailmenu
343  --- The Detailed Node Listing ---
345 Introduction
347 * Summary::                     Brief summary of what Org does
348 * Installation::                How to install a downloaded version of Org
349 * Activation::                  How to activate Org for certain buffers
350 * Feedback::                    Bug reports, ideas, patches etc.
351 * Conventions::                 Type-setting conventions in the manual
353 Document structure
355 * Outlines::                    Org is based on Outline mode
356 * Headlines::                   How to typeset Org tree headlines
357 * Visibility cycling::          Show and hide, much simplified
358 * Motion::                      Jumping to other headlines
359 * Structure editing::           Changing sequence and level of headlines
360 * Sparse trees::                Matches embedded in context
361 * Plain lists::                 Additional structure within an entry
362 * Drawers::                     Tucking stuff away
363 * Blocks::                      Folding blocks
364 * Footnotes::                   How footnotes are defined in Org's syntax
365 * Orgstruct mode::              Structure editing outside Org
367 Tables
369 * Built-in table editor::       Simple tables
370 * Column width and alignment::  Overrule the automatic settings
371 * Column groups::               Grouping to trigger vertical lines
372 * Orgtbl mode::                 The table editor as minor mode
373 * The spreadsheet::             The table editor has spreadsheet capabilities
374 * Org-Plot::                    Plotting from org tables
376 The spreadsheet
378 * References::                  How to refer to another field or range
379 * Formula syntax for Calc::     Using Calc to compute stuff
380 * Formula syntax for Lisp::     Writing formulas in Emacs Lisp
381 * Durations and time values::   How to compute durations and time values
382 * Field and range formulas::    Formula for specific (ranges of) fields
383 * Column formulas::             Formulas valid for an entire column
384 * Editing and debugging formulas::  Fixing formulas
385 * Updating the table::          Recomputing all dependent fields
386 * Advanced features::           Field names, parameters and automatic recalc
388 Hyperlinks
390 * Link format::                 How links in Org are formatted
391 * Internal links::              Links to other places in the current file
392 * External links::              URL-like links to the world
393 * Handling links::              Creating, inserting and following
394 * Using links outside Org::     Linking from my C source code?
395 * Link abbreviations::          Shortcuts for writing complex links
396 * Search options::              Linking to a specific location
397 * Custom searches::             When the default search is not enough
399 Internal links
401 * Radio targets::               Make targets trigger links in plain text
403 TODO items
405 * TODO basics::                 Marking and displaying TODO entries
406 * TODO extensions::             Workflow and assignments
407 * Progress logging::            Dates and notes for progress
408 * Priorities::                  Some things are more important than others
409 * Breaking down tasks::         Splitting a task into manageable pieces
410 * Checkboxes::                  Tick-off lists
412 Extended use of TODO keywords
414 * Workflow states::             From TODO to DONE in steps
415 * TODO types::                  I do this, Fred does the rest
416 * Multiple sets in one file::   Mixing it all, and still finding your way
417 * Fast access to TODO states::  Single letter selection of a state
418 * Per-file keywords::           Different files, different requirements
419 * Faces for TODO keywords::     Highlighting states
420 * TODO dependencies::           When one task needs to wait for others
422 Progress logging
424 * Closing items::               When was this entry marked DONE?
425 * Tracking TODO state changes::  When did the status change?
426 * Tracking your habits::        How consistent have you been?
428 Tags
430 * Tag inheritance::             Tags use the tree structure of the outline
431 * Setting tags::                How to assign tags to a headline
432 * Tag searches::                Searching for combinations of tags
434 Properties and columns
436 * Property syntax::             How properties are spelled out
437 * Special properties::          Access to other Org-mode features
438 * Property searches::           Matching property values
439 * Property inheritance::        Passing values down the tree
440 * Column view::                 Tabular viewing and editing
441 * Property API::                Properties for Lisp programmers
443 Column view
445 * Defining columns::            The COLUMNS format property
446 * Using column view::           How to create and use column view
447 * Capturing column view::       A dynamic block for column view
449 Defining columns
451 * Scope of column definitions::  Where defined, where valid?
452 * Column attributes::           Appearance and content of a column
454 Dates and times
456 * Timestamps::                  Assigning a time to a tree entry
457 * Creating timestamps::         Commands which insert timestamps
458 * Deadlines and scheduling::    Planning your work
459 * Clocking work time::          Tracking how long you spend on a task
460 * Effort estimates::            Planning work effort in advance
461 * Relative timer::              Notes with a running timer
462 * Countdown timer::             Starting a countdown timer for a task
464 Creating timestamps
466 * The date/time prompt::        How Org-mode helps you entering date and time
467 * Custom time format::          Making dates look different
469 Deadlines and scheduling
471 * Inserting deadline/schedule::  Planning items
472 * Repeated tasks::              Items that show up again and again
474 Clocking work time
476 * Clocking commands::           Starting and stopping a clock
477 * The clock table::             Detailed reports
478 * Resolving idle time::         Resolving time when you've been idle
480 Capture - Refile - Archive
482 * Capture::                     Capturing new stuff
483 * Attachments::                 Add files to tasks
484 * RSS Feeds::                   Getting input from RSS feeds
485 * Protocols::                   External (e.g.@: Browser) access to Emacs and Org
486 * Refiling notes::              Moving a tree from one place to another
487 * Archiving::                   What to do with finished projects
489 Capture
491 * Setting up capture::          Where notes will be stored
492 * Using capture::               Commands to invoke and terminate capture
493 * Capture templates::           Define the outline of different note types
495 Capture templates
497 * Template elements::           What is needed for a complete template entry
498 * Template expansion::          Filling in information about time and context
500 Archiving
502 * Moving subtrees::             Moving a tree to an archive file
503 * Internal archiving::          Switch off a tree but keep it in the file
505 Agenda views
507 * Agenda files::                Files being searched for agenda information
508 * Agenda dispatcher::           Keyboard access to agenda views
509 * Built-in agenda views::       What is available out of the box?
510 * Presentation and sorting::    How agenda items are prepared for display
511 * Agenda commands::             Remote editing of Org trees
512 * Custom agenda views::         Defining special searches and views
513 * Exporting Agenda Views::      Writing a view to a file
514 * Agenda column view::          Using column view for collected entries
516 The built-in agenda views
518 * Weekly/daily agenda::         The calendar page with current tasks
519 * Global TODO list::            All unfinished action items
520 * Matching tags and properties::  Structured information with fine-tuned search
521 * Timeline::                    Time-sorted view for single file
522 * Search view::                 Find entries by searching for text
523 * Stuck projects::              Find projects you need to review
525 Presentation and sorting
527 * Categories::                  Not all tasks are equal
528 * Time-of-day specifications::  How the agenda knows the time
529 * Sorting of agenda items::     The order of things
531 Custom agenda views
533 * Storing searches::            Type once, use often
534 * Block agenda::                All the stuff you need in a single buffer
535 * Setting Options::             Changing the rules
537 Markup for rich export
539 * Structural markup elements::  The basic structure as seen by the exporter
540 * Images and tables::           Tables and Images will be included
541 * Literal examples::            Source code examples with special formatting
542 * Include files::               Include additional files into a document
543 * Index entries::               Making an index
544 * Macro replacement::           Use macros to create complex output
545 * Embedded LaTeX::              LaTeX can be freely used inside Org documents
547 Structural markup elements
549 * Document title::              Where the title is taken from
550 * Headings and sections::       The document structure as seen by the exporter
551 * Table of contents::           The if and where of the table of contents
552 * Initial text::                Text before the first heading?
553 * Lists::                       Lists
554 * Paragraphs::                  Paragraphs
555 * Footnote markup::             Footnotes
556 * Emphasis and monospace::      Bold, italic, etc.
557 * Horizontal rules::            Make a line
558 * Comment lines::               What will *not* be exported
560 Embedded @LaTeX{}
562 * Special symbols::             Greek letters and other symbols
563 * Subscripts and superscripts::  Simple syntax for raising/lowering text
564 * LaTeX fragments::             Complex formulas made easy
565 * Previewing LaTeX fragments::  What will this snippet look like?
566 * CDLaTeX mode::                Speed up entering of formulas
568 Exporting
570 * Selective export::            Using tags to select and exclude trees
571 * Export options::              Per-file export settings
572 * The export dispatcher::       How to access exporter commands
573 * ASCII/Latin-1/UTF-8 export::  Exporting to flat files with encoding
574 * HTML export::                 Exporting to HTML
575 * LaTeX and PDF export::        Exporting to @LaTeX{}, and processing to PDF
576 * DocBook export::              Exporting to DocBook
577 * OpenDocumentText export::     Exporting to OpenDocumentText
578 * TaskJuggler export::          Exporting to TaskJuggler
579 * Freemind export::             Exporting to Freemind mind maps
580 * XOXO export::                 Exporting to XOXO
581 * iCalendar export::            Exporting in iCalendar format
583 HTML export
585 * HTML Export commands::        How to invoke HTML export
586 * HTML preamble and postamble::  How to insert a preamble and a postamble
587 * Quoting HTML tags::           Using direct HTML in Org-mode
588 * Links in HTML export::        How links will be interpreted and formatted
589 * Tables in HTML export::       How to modify the formatting of tables
590 * Images in HTML export::       How to insert figures into HTML output
591 * Math formatting in HTML export::  Beautiful math also on the web
592 * Text areas in HTML export::   An alternative way to show an example
593 * CSS support::                 Changing the appearance of the output
594 * JavaScript support::          Info and Folding in a web browser
596 @LaTeX{} and PDF export
598 * LaTeX/PDF export commands::   Which key invokes which commands
599 * Header and sectioning::       Setting up the export file structure
600 * Quoting LaTeX code::          Incorporating literal @LaTeX{} code
601 * Tables in LaTeX export::      Options for exporting tables to @LaTeX{}
602 * Images in LaTeX export::      How to insert figures into @LaTeX{} output
603 * Beamer class export::         Turning the file into a presentation
605 DocBook export
607 * DocBook export commands::     How to invoke DocBook export
608 * Quoting DocBook code::        Incorporating DocBook code in Org files
609 * Recursive sections::          Recursive sections in DocBook
610 * Tables in DocBook export::    Tables are exported as HTML tables
611 * Images in DocBook export::    How to insert figures into DocBook output
612 * Special characters::          How to handle special characters
614 OpenDocument export
616 * OpenDocumentText export commands::    How to invoke OpenDocumentText export
617 * Applying Custom Styles::      How to apply custom styles to the output
618 * Converting to Other formats:: How to convert to formats like doc, docx etc
619 * Links in OpenDocumentText export::  How links will be interpreted and formatted
620 * Tables in OpenDocumentText export::    How Tables are handled
621 * Images in OpenDocumentText export::    How to insert figures
622 * Additional Documentation::          How to handle special characters
624 Publishing
626 * Configuration::               Defining projects
627 * Uploading files::             How to get files up on the server
628 * Sample configuration::        Example projects
629 * Triggering publication::      Publication commands
631 Configuration
633 * Project alist::               The central configuration variable
634 * Sources and destinations::    From here to there
635 * Selecting files::             What files are part of the project?
636 * Publishing action::           Setting the function doing the publishing
637 * Publishing options::          Tweaking HTML/@LaTeX{} export
638 * Publishing links::            Which links keep working after publishing?
639 * Sitemap::                     Generating a list of all pages
640 * Generating an index::         An index that reaches across pages
642 Sample configuration
644 * Simple example::              One-component publishing
645 * Complex example::             A multi-component publishing example
647 Working with source code
649 * Structure of code blocks::    Code block syntax described
650 * Editing source code::         Language major-mode editing
651 * Exporting code blocks::       Export contents and/or results
652 * Extracting source code::      Create pure source code files
653 * Evaluating code blocks::      Place results of evaluation in the Org-mode buffer
654 * Library of Babel::            Use and contribute to a library of useful code blocks
655 * Languages::                   List of supported code block languages
656 * Header arguments::            Configure code block functionality
657 * Results of evaluation::       How evaluation results are handled
658 * Noweb reference syntax::      Literate programming in Org-mode
659 * Key bindings and useful functions::  Work quickly with code blocks
660 * Batch execution::             Call functions from the command line
662 Header arguments
664 * Using header arguments::      Different ways to set header arguments
665 * Specific header arguments::   List of header arguments
667 Using header arguments
669 * System-wide header arguments::  Set global default values
670 * Language-specific header arguments::  Set default values by language
671 * Buffer-wide header arguments::  Set default values for a specific buffer
672 * Header arguments in Org-mode properties::  Set default values for a buffer or heading
673 * Code block specific header arguments::  The most common way to set values
674 * Header arguments in function calls::  The most specific level
676 Specific header arguments
678 * var::                         Pass arguments to code blocks
679 * results::                     Specify the type of results and how they will
680                                 be collected and handled
681 * file::                        Specify a path for file output
682 * dir::                         Specify the default (possibly remote)
683                                 directory for code block execution
684 * exports::                     Export code and/or results
685 * tangle::                      Toggle tangling and specify file name
686 * mkdirp::                      Toggle creation of parent directories of target
687                                 files during tangling
688 * comments::                    Toggle insertion of comments in tangled
689                                 code files
690 * padline::                     Control insertion of padding lines in tangled
691                                 code files
692 * no-expand::                   Turn off variable assignment and noweb
693                                 expansion during tangling
694 * session::                     Preserve the state of code evaluation
695 * noweb::                       Toggle expansion of noweb references
696 * noweb-ref::                   Specify block's noweb reference resolution target
697 * cache::                       Avoid re-evaluating unchanged code blocks
698 * sep::                         Delimiter for writing tabular results outside Org
699 * hlines::                      Handle horizontal lines in tables
700 * colnames::                    Handle column names in tables
701 * rownames::                    Handle row names in tables
702 * shebang::                     Make tangled files executable
703 * eval::                        Limit evaluation of specific code blocks
705 Miscellaneous
707 * Completion::                  M-TAB knows what you need
708 * Easy Templates::              Quick insertion of structural elements
709 * Speed keys::                  Electric commands at the beginning of a headline
710 * Code evaluation security::    Org mode files evaluate inline code
711 * Customization::               Adapting Org to your taste
712 * In-buffer settings::          Overview of the #+KEYWORDS
713 * The very busy C-c C-c key::   When in doubt, press C-c C-c
714 * Clean view::                  Getting rid of leading stars in the outline
715 * TTY keys::                    Using Org on a tty
716 * Interaction::                 Other Emacs packages
717 * org-crypt.el::                Encrypting Org files
719 Interaction with other packages
721 * Cooperation::                 Packages Org cooperates with
722 * Conflicts::                   Packages that lead to conflicts
724 Hacking
726 * Hooks::                       Who to reach into Org's internals
727 * Add-on packages::             Available extensions
728 * Adding hyperlink types::      New custom link types
729 * Context-sensitive commands::  How to add functionality to such commands
730 * Tables in arbitrary syntax::  Orgtbl for @LaTeX{} and other programs
731 * Dynamic blocks::              Automatically filled blocks
732 * Special agenda views::        Customized views
733 * Extracting agenda information::  Postprocessing of agenda information
734 * Using the property API::      Writing programs that use entry properties
735 * Using the mapping API::       Mapping over all or selected entries
737 Tables and lists in arbitrary syntax
739 * Radio tables::                Sending and receiving radio tables
740 * A LaTeX example::             Step by step, almost a tutorial
741 * Translator functions::        Copy and modify
742 * Radio lists::                 Doing the same for lists
744 MobileOrg
746 * Setting up the staging area::  Where to interact with the mobile device
747 * Pushing to MobileOrg::        Uploading Org files and agendas
748 * Pulling from MobileOrg::      Integrating captured and flagged items
750 @end detailmenu
751 @end menu
753 @node Introduction, Document Structure, Top, Top
754 @chapter Introduction
755 @cindex introduction
757 @menu
758 * Summary::                     Brief summary of what Org does
759 * Installation::                How to install a downloaded version of Org
760 * Activation::                  How to activate Org for certain buffers
761 * Feedback::                    Bug reports, ideas, patches etc.
762 * Conventions::                 Type-setting conventions in the manual
763 @end menu
765 @node Summary, Installation, Introduction, Introduction
766 @section Summary
767 @cindex summary
769 Org is a mode for keeping notes, maintaining TODO lists, and doing
770 project planning with a fast and effective plain-text system.
772 Org develops organizational tasks around NOTES files that contain
773 lists or information about projects as plain text.  Org is
774 implemented on top of Outline mode, which makes it possible to keep the
775 content of large files well structured.  Visibility cycling and
776 structure editing help to work with the tree.  Tables are easily created
777 with a built-in table editor.  Org supports TODO items, deadlines,
778 timestamps, and scheduling.  It dynamically compiles entries into an
779 agenda that utilizes and smoothly integrates much of the Emacs calendar
780 and diary.  Plain text URL-like links connect to websites, emails,
781 Usenet messages, BBDB entries, and any files related to the projects.
782 For printing and sharing of notes, an Org file can be exported as a
783 structured ASCII file, as HTML, or (TODO and agenda items only) as an
784 iCalendar file.  It can also serve as a publishing tool for a set of
785 linked web pages.
787 As a project planning environment, Org works by adding metadata to outline
788 nodes.  Based on this data, specific entries can be extracted in queries and
789 create dynamic @i{agenda views}.
791 Org mode contains the Org Babel environment which allows you to work with
792 embedded source code blocks in a file, to facilitate code evaluation,
793 documentation, and literate programming techniques.
795 Org's automatic, context-sensitive table editor with spreadsheet
796 capabilities can be integrated into any major mode by activating the
797 minor Orgtbl mode.  Using a translation step, it can be used to maintain
798 tables in arbitrary file types, for example in @LaTeX{}.  The structure
799 editing and list creation capabilities can be used outside Org with
800 the minor Orgstruct mode.
802 Org keeps simple things simple.  When first fired up, it should
803 feel like a straightforward, easy to use outliner.  Complexity is not
804 imposed, but a large amount of functionality is available when you need
805 it.  Org is a toolbox and can be used in different ways and for different
806 ends, for example:
808 @example
809 @r{@bullet{} an outline extension with visibility cycling and structure editing}
810 @r{@bullet{} an ASCII system and table editor for taking structured notes}
811 @r{@bullet{} a TODO list editor}
812 @r{@bullet{} a full agenda and planner with deadlines and work scheduling}
813 @pindex GTD, Getting Things Done
814 @r{@bullet{} an environment in which to implement David Allen's GTD system}
815 @r{@bullet{} a simple hypertext system, with HTML and @LaTeX{} export}
816 @r{@bullet{} a publishing tool to create a set of interlinked webpages}
817 @r{@bullet{} an environment for literate programming}
818 @end example
821 @cindex FAQ
822 There is a website for Org which provides links to the newest
823 version of Org, as well as additional information, frequently asked
824 questions (FAQ), links to tutorials, etc@.  This page is located at
825 @uref{http://orgmode.org}.
827 @cindex print edition
828 The version 7.3 of this manual is available as a
829 @uref{http://www.network-theory.co.uk/org/manual/, paperback book from Network
830 Theory Ltd.}
832 @page
835 @node Installation, Activation, Summary, Introduction
836 @section Installation
837 @cindex installation
838 @cindex XEmacs
840 @b{Important:} @i{If you are using a version of Org that is part of the Emacs
841 distribution or an XEmacs package, please skip this section and go directly
842 to @ref{Activation}.  To see what version of Org (if any) is part of your
843 Emacs distribution, type @kbd{M-x load-library RET org} and then @kbd{M-x
844 org-version}.}
846 If you have downloaded Org from the Web, either as a distribution @file{.zip}
847 or @file{.tar} file, or as a Git archive, you must take the following steps
848 to install it: go into the unpacked Org distribution directory and edit the
849 top section of the file @file{Makefile}.  You must set the name of the Emacs
850 binary (likely either @file{emacs} or @file{xemacs}), and the paths to the
851 directories where local Lisp and Info files are kept.  If you don't have
852 access to the system-wide directories, you can simply run Org directly from
853 the distribution directory by adding the @file{lisp} subdirectory to the
854 Emacs load path.  To do this, add the following line to @file{.emacs}:
856 @example
857 (setq load-path (cons "~/path/to/orgdir/lisp" load-path))
858 @end example
860 @noindent
861 If you plan to use code from the @file{contrib} subdirectory, do a similar
862 step for this directory:
864 @example
865 (setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))
866 @end example
868 @noindent Now byte-compile the Lisp files with the shell command:
870 @example
871 make
872 @end example
874 @noindent If you are running Org from the distribution directory, this is
875 all.  If you want to install Org into the system directories, use (as
876 administrator)
878 @example
879 make install
880 @end example
882 Installing Info files is system dependent, because of differences in the
883 @file{install-info} program.  In Debian it copies the info files into the
884 correct directory and modifies the info directory file.  In many other
885 systems, the files need to be copied to the correct directory separately, and
886 @file{install-info} then only modifies the directory file.  Check your system
887 documentation to find out which of the following commands you need:
889 @example
890 make install-info
891 make install-info-debian
892 @end example
894 Then add the following line to @file{.emacs}.  It is needed so that
895 Emacs can autoload functions that are located in files not immediately loaded
896 when Org-mode starts.
897 @lisp
898 (require 'org-install)
899 @end lisp
901 Do not forget to activate Org as described in the following section.
902 @page
904 @node Activation, Feedback, Installation, Introduction
905 @section Activation
906 @cindex activation
907 @cindex autoload
908 @cindex global key bindings
909 @cindex key bindings, global
911 To make sure files with extension @file{.org} use Org mode, add the following
912 line to your @file{.emacs} file.
913 @lisp
914 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
915 @end lisp
916 @noindent Org mode buffers need font-lock to be turned on - this is the
917 default in Emacs@footnote{If you don't use font-lock globally, turn it on in
918 Org buffer with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
920 The four Org commands @command{org-store-link}, @command{org-capture},
921 @command{org-agenda}, and @command{org-iswitchb} should be accessible through
922 global keys (i.e.@: anywhere in Emacs, not just in Org buffers).  Here are
923 suggested bindings for these keys, please modify the keys to your own
924 liking.
925 @lisp
926 (global-set-key "\C-cl" 'org-store-link)
927 (global-set-key "\C-cc" 'org-capture)
928 (global-set-key "\C-ca" 'org-agenda)
929 (global-set-key "\C-cb" 'org-iswitchb)
930 @end lisp
932 @cindex Org-mode, turning on
933 With this setup, all files with extension @samp{.org} will be put
934 into Org-mode.  As an alternative, make the first line of a file look
935 like this:
937 @example
938 MY PROJECTS    -*- mode: org; -*-
939 @end example
941 @vindex org-insert-mode-line-in-empty-file
942 @noindent which will select Org-mode for this buffer no matter what
943 the file's name is.  See also the variable
944 @code{org-insert-mode-line-in-empty-file}.
946 Many commands in Org work on the region if the region is @i{active}.  To make
947 use of this, you need to have @code{transient-mark-mode}
948 (@code{zmacs-regions} in XEmacs) turned on.  In Emacs 23 this is the default,
949 in Emacs 22 you need to do this yourself with
950 @lisp
951 (transient-mark-mode 1)
952 @end lisp
953 @noindent If you do not like @code{transient-mark-mode}, you can create an
954 active region by using the mouse to select a region, or pressing
955 @kbd{C-@key{SPC}} twice before moving the cursor.
957 @node Feedback, Conventions, Activation, Introduction
958 @section Feedback
959 @cindex feedback
960 @cindex bug reports
961 @cindex maintainer
962 @cindex author
964 If you find problems with Org, or if you have questions, remarks, or ideas
965 about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
966 If you are not a member of the mailing list, your mail will be passed to the
967 list after a moderator has approved it@footnote{Please consider subscribing
968 to the mailing list, in order to minimize the work the mailing list
969 moderators have to do.}.
971 For bug reports, please first try to reproduce the bug with the latest
972 version of Org available---if you are running an outdated version, it is
973 quite possible that the bug has been fixed already.  If the bug persists,
974 prepare a report and provide as much information as possible, including the
975 version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
976 (@kbd{M-x org-version @key{RET}}), as well as the Org related setup in
977 @file{.emacs}.  The easiest way to do this is to use the command
978 @example
979 @kbd{M-x org-submit-bug-report}
980 @end example
981 @noindent which will put all this information into an Emacs mail buffer so
982 that you only need to add your description.  If you re not sending the Email
983 from within Emacs, please copy and paste the content into your Email program.
985 If an error occurs, a backtrace can be very useful (see below on how to
986 create one).  Often a small example file helps, along with clear information
987 about:
989 @enumerate
990 @item What exactly did you do?
991 @item What did you expect to happen?
992 @item What happened instead?
993 @end enumerate
994 @noindent Thank you for helping to improve this program.
996 @subsubheading How to create a useful backtrace
998 @cindex backtrace of an error
999 If working with Org produces an error with a message you don't
1000 understand, you may have hit a bug.  The best way to report this is by
1001 providing, in addition to what was mentioned above, a @emph{backtrace}.
1002 This is information from the built-in debugger about where and how the
1003 error occurred.  Here is how to produce a useful backtrace:
1005 @enumerate
1006 @item
1007 Reload uncompiled versions of all Org-mode Lisp files.  The backtrace
1008 contains much more information if it is produced with uncompiled code.
1009 To do this, use
1010 @example
1011 C-u M-x org-reload RET
1012 @end example
1013 @noindent
1014 or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
1015 menu.
1016 @item
1017 Go to the @code{Options} menu and select @code{Enter Debugger on Error}
1018 (XEmacs has this option in the @code{Troubleshooting} sub-menu).
1019 @item
1020 Do whatever you have to do to hit the error.  Don't forget to
1021 document the steps you take.
1022 @item
1023 When you hit the error, a @file{*Backtrace*} buffer will appear on the
1024 screen.  Save this buffer to a file (for example using @kbd{C-x C-w}) and
1025 attach it to your bug report.
1026 @end enumerate
1028 @node Conventions,  , Feedback, Introduction
1029 @section Typesetting conventions used in this manual
1031 Org uses three types of keywords: TODO keywords, tags, and property
1032 names.  In this manual we use the following conventions:
1034 @table @code
1035 @item TODO
1036 @itemx WAITING
1037 TODO keywords are written with all capitals, even if they are
1038 user-defined.
1039 @item boss
1040 @itemx ARCHIVE
1041 User-defined tags are written in lowercase; built-in tags with special
1042 meaning are written with all capitals.
1043 @item Release
1044 @itemx PRIORITY
1045 User-defined properties are capitalized; built-in properties with
1046 special meaning are written with all capitals.
1047 @end table
1049 The manual lists both the keys and the corresponding commands for accessing
1050 functionality.  Org mode often uses the same key for different functions,
1051 depending on context.  The command that is bound to such keys has a generic
1052 name, like @code{org-metaright}.  In the manual we will, wherever possible,
1053 give the function that is internally called by the generic command.  For
1054 example, in the chapter on document structure, @kbd{M-@key{right}} will be
1055 listed to call @code{org-do-demote}, while in the chapter on tables, it will
1056 be listed to call org-table-move-column-right.
1058 If you prefer, you can compile the manual without the command names by
1059 unsetting the flag @code{cmdnames} in @file{org.texi}.
1061 @node Document Structure, Tables, Introduction, Top
1062 @chapter Document structure
1063 @cindex document structure
1064 @cindex structure of document
1066 Org is based on Outline mode and provides flexible commands to
1067 edit the structure of the document.
1069 @menu
1070 * Outlines::                    Org is based on Outline mode
1071 * Headlines::                   How to typeset Org tree headlines
1072 * Visibility cycling::          Show and hide, much simplified
1073 * Motion::                      Jumping to other headlines
1074 * Structure editing::           Changing sequence and level of headlines
1075 * Sparse trees::                Matches embedded in context
1076 * Plain lists::                 Additional structure within an entry
1077 * Drawers::                     Tucking stuff away
1078 * Blocks::                      Folding blocks
1079 * Footnotes::                   How footnotes are defined in Org's syntax
1080 * Orgstruct mode::              Structure editing outside Org
1081 @end menu
1083 @node Outlines, Headlines, Document Structure, Document Structure
1084 @section Outlines
1085 @cindex outlines
1086 @cindex Outline mode
1088 Org is implemented on top of Outline mode.  Outlines allow a
1089 document to be organized in a hierarchical structure, which (at least
1090 for me) is the best representation of notes and thoughts.  An overview
1091 of this structure is achieved by folding (hiding) large parts of the
1092 document to show only the general document structure and the parts
1093 currently being worked on.  Org greatly simplifies the use of
1094 outlines by compressing the entire show/hide functionality into a single
1095 command, @command{org-cycle}, which is bound to the @key{TAB} key.
1097 @node Headlines, Visibility cycling, Outlines, Document Structure
1098 @section Headlines
1099 @cindex headlines
1100 @cindex outline tree
1101 @vindex org-special-ctrl-a/e
1102 @vindex org-special-ctrl-k
1103 @vindex org-ctrl-k-protect-subtree
1105 Headlines define the structure of an outline tree.  The headlines in Org
1106 start with one or more stars, on the left margin@footnote{See the variables
1107 @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
1108 @code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
1109 @kbd{C-e}, and @kbd{C-k} in headlines.}.  For example:
1111 @example
1112 * Top level headline
1113 ** Second level
1114 *** 3rd level
1115     some text
1116 *** 3rd level
1117     more text
1119 * Another top level headline
1120 @end example
1122 @noindent Some people find the many stars too noisy and would prefer an
1123 outline that has whitespace followed by a single star as headline
1124 starters.  @ref{Clean view}, describes a setup to realize this.
1126 @vindex org-cycle-separator-lines
1127 An empty line after the end of a subtree is considered part of it and
1128 will be hidden when the subtree is folded.  However, if you leave at
1129 least two empty lines, one empty line will remain visible after folding
1130 the subtree, in order to structure the collapsed view.  See the
1131 variable @code{org-cycle-separator-lines} to modify this behavior.
1133 @node Visibility cycling, Motion, Headlines, Document Structure
1134 @section Visibility cycling
1135 @cindex cycling, visibility
1136 @cindex visibility cycling
1137 @cindex trees, visibility
1138 @cindex show hidden text
1139 @cindex hide text
1141 Outlines make it possible to hide parts of the text in the buffer.
1142 Org uses just two commands, bound to @key{TAB} and
1143 @kbd{S-@key{TAB}} to change the visibility in the buffer.
1145 @cindex subtree visibility states
1146 @cindex subtree cycling
1147 @cindex folded, subtree visibility state
1148 @cindex children, subtree visibility state
1149 @cindex subtree, subtree visibility state
1150 @table @asis
1151 @orgcmd{@key{TAB},org-cycle}
1152 @emph{Subtree cycling}: Rotate current subtree among the states
1154 @example
1155 ,-> FOLDED -> CHILDREN -> SUBTREE --.
1156 '-----------------------------------'
1157 @end example
1159 @vindex org-cycle-emulate-tab
1160 @vindex org-cycle-global-at-bob
1161 The cursor must be on a headline for this to work@footnote{see, however,
1162 the option @code{org-cycle-emulate-tab}.}.  When the cursor is at the
1163 beginning of the buffer and the first line is not a headline, then
1164 @key{TAB} actually runs global cycling (see below)@footnote{see the
1165 option @code{org-cycle-global-at-bob}.}.  Also when called with a prefix
1166 argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
1168 @cindex global visibility states
1169 @cindex global cycling
1170 @cindex overview, global visibility state
1171 @cindex contents, global visibility state
1172 @cindex show all, global visibility state
1173 @orgcmd{S-@key{TAB},org-global-cycle}
1174 @itemx C-u @key{TAB}
1175 @emph{Global cycling}: Rotate the entire buffer among the states
1177 @example
1178 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
1179 '--------------------------------------'
1180 @end example
1182 When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the
1183 CONTENTS view up to headlines of level N will be shown.  Note that inside
1184 tables, @kbd{S-@key{TAB}} jumps to the previous field.
1186 @cindex show all, command
1187 @orgcmd{C-u C-u C-u @key{TAB},show-all}
1188 Show all, including drawers.
1189 @orgcmd{C-c C-r,org-reveal}
1190 Reveal context around point, showing the current entry, the following heading
1191 and the hierarchy above.  Useful for working near a location that has been
1192 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
1193 (@pxref{Agenda commands}).  With a prefix argument show, on each
1194 level, all sibling headings.  With double prefix arg, also show the entire
1195 subtree of the parent.
1196 @orgcmd{C-c C-k,show-branches}
1197 Expose all the headings of the subtree, CONTENT view for just one subtree.
1198 @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
1199 Show the current subtree in an indirect buffer@footnote{The indirect
1200 buffer
1201 @ifinfo
1202 (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual})
1203 @end ifinfo
1204 @ifnotinfo
1205 (see the Emacs manual for more information about indirect buffers)
1206 @end ifnotinfo
1207 will contain the entire buffer, but will be narrowed to the current
1208 tree.  Editing the indirect buffer will also change the original buffer,
1209 but without affecting visibility in that buffer.}.  With a numeric
1210 prefix argument N, go up to level N and then take that tree.  If N is
1211 negative then go up that many levels.  With a @kbd{C-u} prefix, do not remove
1212 the previously used indirect buffer.
1213 @end table
1215 @vindex org-startup-folded
1216 @cindex @code{overview}, STARTUP keyword
1217 @cindex @code{content}, STARTUP keyword
1218 @cindex @code{showall}, STARTUP keyword
1219 @cindex @code{showeverything}, STARTUP keyword
1221 When Emacs first visits an Org file, the global state is set to
1222 OVERVIEW, i.e.@: only the top level headlines are visible.  This can be
1223 configured through the variable @code{org-startup-folded}, or on a
1224 per-file basis by adding one of the following lines anywhere in the
1225 buffer:
1227 @example
1228 #+STARTUP: overview
1229 #+STARTUP: content
1230 #+STARTUP: showall
1231 #+STARTUP: showeverything
1232 @end example
1234 @cindex property, VISIBILITY
1235 @noindent
1236 Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
1237 and Columns}) will get their visibility adapted accordingly.  Allowed values
1238 for this property are @code{folded}, @code{children}, @code{content}, and
1239 @code{all}.
1240 @table @asis
1241 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1242 Switch back to the startup visibility of the buffer, i.e.@: whatever is
1243 requested by startup options and @samp{VISIBILITY} properties in individual
1244 entries.
1245 @end table
1247 @node Motion, Structure editing, Visibility cycling, Document Structure
1248 @section Motion
1249 @cindex motion, between headlines
1250 @cindex jumping, to headlines
1251 @cindex headline navigation
1252 The following commands jump to other headlines in the buffer.
1254 @table @asis
1255 @orgcmd{C-c C-n,outline-next-visible-heading}
1256 Next heading.
1257 @orgcmd{C-c C-p,outline-previous-visible-heading}
1258 Previous heading.
1259 @orgcmd{C-c C-f,org-forward-same-level}
1260 Next heading same level.
1261 @orgcmd{C-c C-b,org-backward-same-level}
1262 Previous heading same level.
1263 @orgcmd{C-c C-u,outline-up-heading}
1264 Backward to higher level heading.
1265 @orgcmd{C-c C-j,org-goto}
1266 Jump to a different place without changing the current outline
1267 visibility.  Shows the document structure in a temporary buffer, where
1268 you can use the following keys to find your destination:
1269 @vindex org-goto-auto-isearch
1270 @example
1271 @key{TAB}         @r{Cycle visibility.}
1272 @key{down} / @key{up}   @r{Next/previous visible headline.}
1273 @key{RET}         @r{Select this location.}
1274 @kbd{/}           @r{Do a Sparse-tree search}
1275 @r{The following keys work if you turn off @code{org-goto-auto-isearch}}
1276 n / p        @r{Next/previous visible headline.}
1277 f / b        @r{Next/previous headline same level.}
1278 u            @r{One level up.}
1279 0-9          @r{Digit argument.}
1280 q            @r{Quit}
1281 @end example
1282 @vindex org-goto-interface
1283 @noindent
1284 See also the variable @code{org-goto-interface}.
1285 @end table
1287 @node Structure editing, Sparse trees, Motion, Document Structure
1288 @section Structure editing
1289 @cindex structure editing
1290 @cindex headline, promotion and demotion
1291 @cindex promotion, of subtrees
1292 @cindex demotion, of subtrees
1293 @cindex subtree, cut and paste
1294 @cindex pasting, of subtrees
1295 @cindex cutting, of subtrees
1296 @cindex copying, of subtrees
1297 @cindex sorting, of subtrees
1298 @cindex subtrees, cut and paste
1300 @table @asis
1301 @orgcmd{M-@key{RET},org-insert-heading}
1302 @vindex org-M-RET-may-split-line
1303 Insert new heading with same level as current.  If the cursor is in a plain
1304 list item, a new item is created (@pxref{Plain lists}).  To force creation of
1305 a new headline, use a prefix argument.  When this command is used in the
1306 middle of a line, the line is split and the rest of the line becomes the new
1307 headline@footnote{If you do not want the line to be split, customize the
1308 variable @code{org-M-RET-may-split-line}.}.  If the command is used at the
1309 beginning of a headline, the new headline is created before the current line.
1310 If at the beginning of any other line, the content of that line is made the
1311 new heading.  If the command is used at the end of a folded subtree (i.e.@:
1312 behind the ellipses at the end of a headline), then a headline like the
1313 current one will be inserted after the end of the subtree.
1314 @orgcmd{C-@key{RET},org-insert-heading-respect-content}
1315 Just like @kbd{M-@key{RET}}, except when adding a new heading below the
1316 current heading, the new heading is placed after the body instead of before
1317 it.  This command works from anywhere in the entry.
1318 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
1319 @vindex org-treat-insert-todo-heading-as-state-change
1320 Insert new TODO entry with same level as current heading.  See also the
1321 variable @code{org-treat-insert-todo-heading-as-state-change}.
1322 @orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
1323 Insert new TODO entry with same level as current heading.  Like
1324 @kbd{C-@key{RET}}, the new headline will be inserted after the current
1325 subtree.
1326 @orgcmd{@key{TAB},org-cycle}
1327 In a new entry with no text yet, the first @key{TAB} demotes the entry to
1328 become a child of the previous one.  The next @key{TAB} makes it a parent,
1329 and so on, all the way to top level.  Yet another @key{TAB}, and you are back
1330 to the initial level.
1331 @orgcmd{M-@key{left},org-do-promote}
1332 Promote current heading by one level.
1333 @orgcmd{M-@key{right},org-do-demote}
1334 Demote current heading by one level.
1335 @orgcmd{M-S-@key{left},org-promote-subtree}
1336 Promote the current subtree by one level.
1337 @orgcmd{M-S-@key{right},org-demote-subtree}
1338 Demote the current subtree by one level.
1339 @orgcmd{M-S-@key{up},org-move-subtree-up}
1340 Move subtree up (swap with previous subtree of same
1341 level).
1342 @orgcmd{M-S-@key{down},org-move-subtree-down}
1343 Move subtree down (swap with next subtree of same level).
1344 @orgcmd{C-c C-x C-w,org-cut-subtree}
1345 Kill subtree, i.e.@: remove it from buffer but save in kill ring.
1346 With a numeric prefix argument N, kill N sequential subtrees.
1347 @orgcmd{C-c C-x M-w,org-copy-subtree}
1348 Copy subtree to kill ring.  With a numeric prefix argument N, copy the N
1349 sequential subtrees.
1350 @orgcmd{C-c C-x C-y,org-paste-subtree}
1351 Yank subtree from kill ring.  This does modify the level of the subtree to
1352 make sure the tree fits in nicely at the yank position.  The yank level can
1353 also be specified with a numeric prefix argument, or by yanking after a
1354 headline marker like @samp{****}.
1355 @orgcmd{C-y,org-yank}
1356 @vindex org-yank-adjusted-subtrees
1357 @vindex org-yank-folded-subtrees
1358 Depending on the variables @code{org-yank-adjusted-subtrees} and
1359 @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
1360 paste subtrees folded and in a clever way, using the same command as @kbd{C-c
1361 C-x C-y}.  With the default settings, no level adjustment will take place,
1362 but the yanked tree will be folded unless doing so would swallow text
1363 previously visible.  Any prefix argument to this command will force a normal
1364 @code{yank} to be executed, with the prefix passed along.  A good way to
1365 force a normal yank is @kbd{C-u C-y}.  If you use @code{yank-pop} after a
1366 yank, it will yank previous kill items plainly, without adjustment and
1367 folding.
1368 @orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
1369 Clone a subtree by making a number of sibling copies of it.  You will be
1370 prompted for the number of copies to make, and you can also specify if any
1371 timestamps in the entry should be shifted.  This can be useful, for example,
1372 to create a number of tasks related to a series of lectures to prepare.  For
1373 more details, see the docstring of the command
1374 @code{org-clone-subtree-with-time-shift}.
1375 @orgcmd{C-c C-w,org-refile}
1376 Refile entry or region to a different location.  @xref{Refiling notes}.
1377 @orgcmd{C-c ^,org-sort-entries-or-items}
1378 Sort same-level entries.  When there is an active region, all entries in the
1379 region will be sorted.  Otherwise the children of the current headline are
1380 sorted.  The command prompts for the sorting method, which can be
1381 alphabetically, numerically, by time (first timestamp with active preferred,
1382 creation time, scheduled time, deadline time), by priority, by TODO keyword
1383 (in the sequence the keywords have been defined in the setup) or by the value
1384 of a property.  Reverse sorting is possible as well.  You can also supply
1385 your own function to extract the sorting key.  With a @kbd{C-u} prefix,
1386 sorting will be case-sensitive.  With two @kbd{C-u C-u} prefixes, duplicate
1387 entries will also be removed.
1388 @orgcmd{C-x n s,org-narrow-to-subtree}
1389 Narrow buffer to current subtree.
1390 @orgcmd{C-x n b,org-narrow-to-block}
1391 Narrow buffer to current block.
1392 @orgcmd{C-x n w,widen}
1393 Widen buffer to remove narrowing.
1394 @orgcmd{C-c *,org-toggle-heading}
1395 Turn a normal line or plain list item into a headline (so that it becomes a
1396 subheading at its location).  Also turn a headline into a normal line by
1397 removing the stars.  If there is an active region, turn all lines in the
1398 region into headlines.  If the first line in the region was an item, turn
1399 only the item lines into headlines.  Finally, if the first line is a
1400 headline, remove the stars from all headlines in the region.
1401 @end table
1403 @cindex region, active
1404 @cindex active region
1405 @cindex transient mark mode
1406 When there is an active region (Transient Mark mode), promotion and
1407 demotion work on all headlines in the region.  To select a region of
1408 headlines, it is best to place both point and mark at the beginning of a
1409 line, mark at the beginning of the first headline, and point at the line
1410 just after the last headline to change.  Note that when the cursor is
1411 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
1412 functionality.
1415 @node Sparse trees, Plain lists, Structure editing, Document Structure
1416 @section Sparse trees
1417 @cindex sparse trees
1418 @cindex trees, sparse
1419 @cindex folding, sparse trees
1420 @cindex occur, command
1422 @vindex org-show-hierarchy-above
1423 @vindex org-show-following-heading
1424 @vindex org-show-siblings
1425 @vindex org-show-entry-below
1426 An important feature of Org-mode is the ability to construct @emph{sparse
1427 trees} for selected information in an outline tree, so that the entire
1428 document is folded as much as possible, but the selected information is made
1429 visible along with the headline structure above it@footnote{See also the
1430 variables @code{org-show-hierarchy-above}, @code{org-show-following-heading},
1431 @code{org-show-siblings}, and @code{org-show-entry-below} for detailed
1432 control on how much context is shown around each match.}.  Just try it out
1433 and you will see immediately how it works.
1435 Org-mode contains several commands creating such trees, all these
1436 commands can be accessed through a dispatcher:
1438 @table @asis
1439 @orgcmd{C-c /,org-sparse-tree}
1440 This prompts for an extra key to select a sparse-tree creating command.
1441 @orgcmd{C-c / r,org-occur}
1442 @vindex org-remove-highlights-with-change
1443 Prompts for a regexp and shows a sparse tree with all matches.  If
1444 the match is in a headline, the headline is made visible.  If the match is in
1445 the body of an entry, headline and body are made visible.  In order to
1446 provide minimal context, also the full hierarchy of headlines above the match
1447 is shown, as well as the headline following the match.  Each match is also
1448 highlighted; the highlights disappear when the buffer is changed by an
1449 editing command@footnote{This depends on the option
1450 @code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
1451 When called with a @kbd{C-u} prefix argument, previous highlights are kept,
1452 so several calls to this command can be stacked.
1453 @orgcmdkkc{M-g n,M-g M-n,next-error}
1454 Jump to the next sparse tree match in this buffer.
1455 @orgcmdkkc{M-g p,M-g M-p,previous-error}
1456 Jump to the previous sparse tree match in this buffer.
1457 @end table
1460 @noindent
1461 @vindex org-agenda-custom-commands
1462 For frequently used sparse trees of specific search strings, you can
1463 use the variable @code{org-agenda-custom-commands} to define fast
1464 keyboard access to specific sparse trees.  These commands will then be
1465 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
1466 For example:
1468 @lisp
1469 (setq org-agenda-custom-commands
1470       '(("f" occur-tree "FIXME")))
1471 @end lisp
1473 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
1474 a sparse tree matching the string @samp{FIXME}.
1476 The other sparse tree commands select headings based on TODO keywords,
1477 tags, or properties and will be discussed later in this manual.
1479 @kindex C-c C-e v
1480 @cindex printing sparse trees
1481 @cindex visible text, printing
1482 To print a sparse tree, you can use the Emacs command
1483 @code{ps-print-buffer-with-faces} which does not print invisible parts
1484 of the document @footnote{This does not work under XEmacs, because
1485 XEmacs uses selective display for outlining, not text properties.}.
1486 Or you can use the command @kbd{C-c C-e v} to export only the visible
1487 part of the document and print the resulting file.
1489 @node Plain lists, Drawers, Sparse trees, Document Structure
1490 @section Plain lists
1491 @cindex plain lists
1492 @cindex lists, plain
1493 @cindex lists, ordered
1494 @cindex ordered lists
1496 Within an entry of the outline tree, hand-formatted lists can provide
1497 additional structure.  They also provide a way to create lists of checkboxes
1498 (@pxref{Checkboxes}).  Org supports editing such lists, and every exporter
1499 (@pxref{Exporting}) can parse and format them.
1501 Org knows ordered lists, unordered lists, and description lists.
1502 @itemize @bullet
1503 @item
1504 @emph{Unordered} list items start with @samp{-}, @samp{+}, or
1505 @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
1506 they will be seen as top-level headlines.  Also, when you are hiding leading
1507 stars to get a clean outline view, plain list items starting with a star may
1508 be hard to distinguish from true headlines.  In short: even though @samp{*}
1509 is supported, it may be better to not use it for plain list items.}  as
1510 bullets.
1511 @item
1512 @vindex org-plain-list-ordered-item-terminator
1513 @vindex org-alphabetical-lists
1514 @emph{Ordered} list items start with a numeral followed by either a period or
1515 a right parenthesis@footnote{You can filter out any of them by configuring
1516 @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
1517 @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
1518 @samp{A)} by configuring @code{org-alphabetical-lists}.  To minimize
1519 confusion with normal text, those are limited to one character only.  Beyond
1520 that limit, bullets will automatically fallback to numbers.}.  If you want a
1521 list to start with a different value (e.g.@: 20), start the text of the item
1522 with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
1523 must be put @emph{before} the checkbox.  If you have activated alphabetical
1524 lists, you can also use counters like @code{[@@b]}.}.  Those constructs can
1525 be used in any item of the list in order to enforce a particular numbering.
1526 @item
1527 @emph{Description} list items are unordered list items, and contain the
1528 separator @samp{ :: } to distinguish the description @emph{term} from the
1529 description.
1530 @end itemize
1532 Items belonging to the same list must have the same indentation on the first
1533 line.  In particular, if an ordered list reaches number @samp{10.}, then the
1534 2--digit numbers must be written left-aligned with the other numbers in the
1535 list.  An item ends before the next line that is less or equally indented
1536 than its bullet/number.
1538 @vindex org-list-ending-method
1539 @vindex org-list-end-regexp
1540 @vindex org-empty-line-terminates-plain-lists
1541 Two methods@footnote{To disable either of them, configure
1542 @code{org-list-ending-method}.} are provided to terminate lists.  A list ends
1543 whenever every item has ended, which means before any line less or equally
1544 indented than items at top level.  It also ends before two blank
1545 lines@footnote{See also @code{org-empty-line-terminates-plain-lists}.}.  In
1546 that case, all items are closed.  For finer control, you can end lists with
1547 any pattern set in @code{org-list-end-regexp}.  Here is an example:
1549 @example
1550 @group
1551 ** Lord of the Rings
1552    My favorite scenes are (in this order)
1553    1. The attack of the Rohirrim
1554    2. Eowyn's fight with the witch king
1555       + this was already my favorite scene in the book
1556       + I really like Miranda Otto.
1557    3. Peter Jackson being shot by Legolas
1558       - on DVD only
1559       He makes a really funny face when it happens.
1560    But in the end, no individual scenes matter but the film as a whole.
1561    Important actors in this film are:
1562    - @b{Elijah Wood} :: He plays Frodo
1563    - @b{Sean Austin} :: He plays Sam, Frodo's friend.  I still remember
1564      him very well from his role as Mikey Walsh in @i{The Goonies}.
1565 @end group
1566 @end example
1568 Org supports these lists by tuning filling and wrapping commands to deal with
1569 them correctly@footnote{Org only changes the filling settings for Emacs.  For
1570 XEmacs, you should use Kyle E. Jones' @file{filladapt.el}.  To turn this on,
1571 put into @file{.emacs}: @code{(require 'filladapt)}}, and by exporting them
1572 properly (@pxref{Exporting}).  Since indentation is what governs the
1573 structure of these lists, many structural constructs like @code{#+BEGIN_...}
1574 blocks can be indented to signal that they belong to a particular item.
1576 @vindex org-list-demote-modify-bullet
1577 If you find that using a different bullet for a sub-list (than that used for
1578 the current list-level) improves readability, customize the variable
1579 @code{org-list-demote-modify-bullet}.
1581 @vindex org-list-automatic-rules
1582 The following commands act on items when the cursor is in the first line of
1583 an item (the line with the bullet or number).  Some of them imply the
1584 application of automatic rules to keep list structure intact.  If some of
1585 these actions get in your way, configure @code{org-list-automatic-rules}
1586 to disable them individually.
1588 @table @asis
1589 @orgcmd{@key{TAB},org-cycle}
1590 @vindex org-cycle-include-plain-lists
1591 Items can be folded just like headline levels.  Normally this works only if
1592 the cursor is on a plain list item.  For more details, see the variable
1593 @code{org-cycle-include-plain-lists}.  If this variable is set to
1594 @code{integrate}, plain list items will be treated like low-level
1595 headlines.  The level of an item is then given by the
1596 indentation of the bullet/number.  Items are always subordinate to real
1597 headlines, however; the hierarchies remain completely separated.
1598 @orgcmd{M-@key{RET},org-insert-heading}
1599 @vindex org-M-RET-may-split-line
1600 @vindex org-list-automatic-rules
1601 Insert new item at current level.  With a prefix argument, force a new
1602 heading (@pxref{Structure editing}).  If this command is used in the middle
1603 of an item, that item is @emph{split} in two, and the second part becomes the
1604 new item@footnote{If you do not want the item to be split, customize the
1605 variable @code{org-M-RET-may-split-line}.}.  If this command is executed
1606 @emph{before item's body}, the new item is created @emph{before} the current
1607 one.
1608 @kindex M-S-@key{RET}
1609 @item M-S-@key{RET}
1610 Insert a new item with a checkbox (@pxref{Checkboxes}).
1611 @orgcmd{@key{TAB},org-cycle}
1612 In a new item with no text yet, the first @key{TAB} demotes the item to
1613 become a child of the previous one.  Subsequent @key{TAB}s move the item to
1614 meaningful levels in the list and eventually get it back to its initial
1615 position.
1616 @kindex S-@key{down}
1617 @item S-@key{up}
1618 @itemx S-@key{down}
1619 @cindex shift-selection-mode
1620 @vindex org-support-shift-select
1621 Jump to the previous/next item in the current list, but only if
1622 @code{org-support-shift-select} is off.  If not, you can still use paragraph
1623 jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
1624 similar effect.
1625 @kindex M-S-@key{up}
1626 @kindex M-S-@key{down}
1627 @item M-S-@key{up}
1628 @itemx M-S-@key{down}
1629 Move the item including subitems up/down (swap with previous/next item
1630 of same indentation).  If the list is ordered, renumbering is
1631 automatic.
1632 @kindex M-@key{left}
1633 @kindex M-@key{right}
1634 @item M-@key{left}
1635 @itemx M-@key{right}
1636 Decrease/increase the indentation of an item, leaving children alone.
1637 @kindex M-S-@key{left}
1638 @kindex M-S-@key{right}
1639 @item M-S-@key{left}
1640 @itemx M-S-@key{right}
1641 Decrease/increase the indentation of the item, including subitems.
1642 Initially, the item tree is selected based on current indentation.  When
1643 these commands are executed several times in direct succession, the initially
1644 selected region is used, even if the new indentation would imply a different
1645 hierarchy.  To use the new hierarchy, break the command chain with a cursor
1646 motion or so.
1648 As a special case, using this command on the very first item of a list will
1649 move the whole list.  This behavior can be disabled by configuring
1650 @code{org-list-automatic-rules}.  The global indentation of a list has no
1651 influence on the text @emph{after} the list.
1652 @kindex C-c C-c
1653 @item C-c C-c
1654 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1655 state of the checkbox.  In any case, verify bullets and indentation
1656 consistency in the whole list.
1657 @kindex C-c -
1658 @vindex org-plain-list-ordered-item-terminator
1659 @vindex org-list-automatic-rules
1660 @item C-c -
1661 Cycle the entire list level through the different itemize/enumerate bullets
1662 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
1663 depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
1664 and its position@footnote{See @code{bullet} rule in
1665 @code{org-list-automatic-rules} for more information.}.  With a numeric
1666 prefix argument N, select the Nth bullet from this list.  If there is an
1667 active region when calling this, selected text will be changed into an item.
1668 With a prefix argument, all lines will be converted to list items.  If the
1669 first line already was a list item, any item marker will be removed from the
1670 list.  Finally, even without an active region, a normal line will be
1671 converted into a list item.
1672 @kindex C-c *
1673 @item C-c *
1674 Turn a plain list item into a headline (so that it becomes a subheading at
1675 its location).  @xref{Structure editing}, for a detailed explanation.
1676 @kindex C-c C-*
1677 @item C-c C-*
1678 Turn the whole plain list into a subtree of the current heading.  Checkboxes
1679 (@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
1680 (resp. checked).
1681 @kindex S-@key{left}
1682 @kindex S-@key{right}
1683 @item S-@key{left}/@key{right}
1684 @vindex org-support-shift-select
1685 This command also cycles bullet styles when the cursor in on the bullet or
1686 anywhere in an item line, details depending on
1687 @code{org-support-shift-select}.
1688 @kindex C-c ^
1689 @item C-c ^
1690 Sort the plain list.  You will be prompted for the sorting method:
1691 numerically, alphabetically, by time, or by custom function.
1692 @end table
1694 @node Drawers, Blocks, Plain lists, Document Structure
1695 @section Drawers
1696 @cindex drawers
1697 @cindex #+DRAWERS
1698 @cindex visibility cycling, drawers
1700 @vindex org-drawers
1701 Sometimes you want to keep information associated with an entry, but you
1702 normally don't want to see it.  For this, Org-mode has @emph{drawers}.
1703 Drawers need to be configured with the variable
1704 @code{org-drawers}@footnote{You can define drawers on a per-file basis
1705 with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}.  Drawers
1706 look like this:
1708 @example
1709 ** This is a headline
1710    Still outside the drawer
1711    :DRAWERNAME:
1712    This is inside the drawer.
1713    :END:
1714    After the drawer.
1715 @end example
1717 Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
1718 show the entry, but keep the drawer collapsed to a single line.  In order to
1719 look inside the drawer, you need to move the cursor to the drawer line and
1720 press @key{TAB} there.  Org-mode uses the @code{PROPERTIES} drawer for
1721 storing properties (@pxref{Properties and Columns}), and you can also arrange
1722 for state change notes (@pxref{Tracking TODO state changes}) and clock times
1723 (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}.  If you
1724 want to store a quick note in the LOGBOOK drawer, in a similar way to state changes, use
1726 @table @kbd
1727 @kindex C-c C-z
1728 @item C-c C-z
1729 Add a time-stamped note to the LOGBOOK drawer.
1730 @end table
1732 @node Blocks, Footnotes, Drawers, Document Structure
1733 @section Blocks
1735 @vindex org-hide-block-startup
1736 @cindex blocks, folding
1737 Org-mode uses begin...end blocks for various purposes from including source
1738 code examples (@pxref{Literal examples}) to capturing time logging
1739 information (@pxref{Clocking work time}).  These blocks can be folded and
1740 unfolded by pressing TAB in the begin line.  You can also get all blocks
1741 folded at startup by configuring the variable @code{org-hide-block-startup}
1742 or on a per-file basis by using
1744 @cindex @code{hideblocks}, STARTUP keyword
1745 @cindex @code{nohideblocks}, STARTUP keyword
1746 @example
1747 #+STARTUP: hideblocks
1748 #+STARTUP: nohideblocks
1749 @end example
1751 @node Footnotes, Orgstruct mode, Blocks, Document Structure
1752 @section Footnotes
1753 @cindex footnotes
1755 Org-mode supports the creation of footnotes.  In contrast to the
1756 @file{footnote.el} package, Org-mode's footnotes are designed for work on a
1757 larger document, not only for one-off documents like emails.  The basic
1758 syntax is similar to the one used by @file{footnote.el}, i.e.@: a footnote is
1759 defined in a paragraph that is started by a footnote marker in square
1760 brackets in column 0, no indentation allowed.  If you need a paragraph break
1761 inside a footnote, use the @LaTeX{} idiom @samp{\par}.  The footnote reference
1762 is simply the marker in square brackets, inside text.  For example:
1764 @example
1765 The Org homepage[fn:1] now looks a lot better than it used to.
1767 [fn:1] The link is: http://orgmode.org
1768 @end example
1770 Org-mode extends the number-based syntax to @emph{named} footnotes and
1771 optional inline definition.  Using plain numbers as markers (as
1772 @file{footnote.el} does) is supported for backward compatibility, but not
1773 encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded
1774 LaTeX}).  Here are the valid references:
1776 @table @code
1777 @item [1]
1778 A plain numeric footnote marker.  Compatible with @file{footnote.el}, but not
1779 recommended because something like @samp{[1]} could easily be part of a code
1780 snippet.
1781 @item [fn:name]
1782 A named footnote reference, where @code{name} is a unique label word, or, for
1783 simplicity of automatic creation, a number.
1784 @item [fn:: This is the inline definition of this footnote]
1785 A @LaTeX{}-like anonymous footnote where the definition is given directly at the
1786 reference point.
1787 @item [fn:name: a definition]
1788 An inline definition of a footnote, which also specifies a name for the note.
1789 Since Org allows multiple references to the same note, you can then use
1790 @code{[fn:name]} to create additional references.
1791 @end table
1793 @vindex org-footnote-auto-label
1794 Footnote labels can be created automatically, or you can create names yourself.
1795 This is handled by the variable @code{org-footnote-auto-label} and its
1796 corresponding @code{#+STARTUP} keywords.  See the docstring of that variable
1797 for details.
1799 @noindent The following command handles footnotes:
1801 @table @kbd
1802 @kindex C-c C-x f
1803 @item C-c C-x f
1804 The footnote action command.
1806 When the cursor is on a footnote reference, jump to the definition.  When it
1807 is at a definition, jump to the (first) reference.
1809 @vindex org-footnote-define-inline
1810 @vindex org-footnote-section
1811 @vindex org-footnote-auto-adjust
1812 Otherwise, create a new footnote.  Depending on the variable
1813 @code{org-footnote-define-inline}@footnote{The corresponding in-buffer
1814 setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
1815 definition will be placed right into the text as part of the reference, or
1816 separately into the location determined by the variable
1817 @code{org-footnote-section}.
1819 When this command is called with a prefix argument, a menu of additional
1820 options is offered:
1821 @example
1822 s   @r{Sort the footnote definitions by reference sequence.  During editing,}
1823     @r{Org makes no effort to sort footnote definitions into a particular}
1824     @r{sequence.  If you want them sorted, use this command, which will}
1825     @r{also move entries according to @code{org-footnote-section}.  Automatic}
1826     @r{sorting after each insertion/deletion can be configured using the}
1827     @r{variable @code{org-footnote-auto-adjust}.}
1828 r   @r{Renumber the simple @code{fn:N} footnotes.  Automatic renumbering}
1829     @r{after each insertion/deletion can be configured using the variable}
1830     @r{@code{org-footnote-auto-adjust}.}
1831 S   @r{Short for first @code{r}, then @code{s} action.}
1832 n   @r{Normalize the footnotes by collecting all definitions (including}
1833     @r{inline definitions) into a special section, and then numbering them}
1834     @r{in sequence.  The references will then also be numbers.  This is}
1835     @r{meant to be the final step before finishing a document (e.g.@: sending}
1836     @r{off an email).  The exporters do this automatically, and so could}
1837     @r{something like @code{message-send-hook}.}
1838 d   @r{Delete the footnote at point, and all definitions of and references}
1839     @r{to it.}
1840 @end example
1841 Depending on the variable @code{org-footnote-auto-adjust}@footnote{the
1842 corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},
1843 renumbering and sorting footnotes can be automatic after each insertion or
1844 deletion.
1846 @kindex C-c C-c
1847 @item C-c C-c
1848 If the cursor is on a footnote reference, jump to the definition.  If it is a
1849 the definition, jump back to the reference.  When called at a footnote
1850 location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
1851 @kindex C-c C-o
1852 @kindex mouse-1
1853 @kindex mouse-2
1854 @item C-c C-o  @r{or} mouse-1/2
1855 Footnote labels are also links to the corresponding definition/reference, and
1856 you can use the usual commands to follow these links.
1857 @end table
1859 @node Orgstruct mode,  , Footnotes, Document Structure
1860 @section The Orgstruct minor mode
1861 @cindex Orgstruct mode
1862 @cindex minor mode for structure editing
1864 If you like the intuitive way the Org-mode structure editing and list
1865 formatting works, you might want to use these commands in other modes like
1866 Text mode or Mail mode as well.  The minor mode @code{orgstruct-mode} makes
1867 this possible.   Toggle the mode with @kbd{M-x orgstruct-mode}, or
1868 turn it on by default, for example in Message mode, with one of:
1870 @lisp
1871 (add-hook 'message-mode-hook 'turn-on-orgstruct)
1872 (add-hook 'message-mode-hook 'turn-on-orgstruct++)
1873 @end lisp
1875 When this mode is active and the cursor is on a line that looks to Org like a
1876 headline or the first line of a list item, most structure editing commands
1877 will work, even if the same keys normally have different functionality in the
1878 major mode you are using.  If the cursor is not in one of those special
1879 lines, Orgstruct mode lurks silently in the shadows.  When you use
1880 @code{orgstruct++-mode}, Org will also export indentation and autofill
1881 settings into that mode, and detect item context after the first line of an
1882 item.
1884 @node Tables, Hyperlinks, Document Structure, Top
1885 @chapter Tables
1886 @cindex tables
1887 @cindex editing tables
1889 Org comes with a fast and intuitive table editor.  Spreadsheet-like
1890 calculations are supported using the Emacs @file{calc} package
1891 @ifinfo
1892 (@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}).
1893 @end ifinfo
1894 @ifnotinfo
1895 (see the Emacs Calculator manual for more information about the Emacs
1896 calculator).
1897 @end ifnotinfo
1899 @menu
1900 * Built-in table editor::       Simple tables
1901 * Column width and alignment::  Overrule the automatic settings
1902 * Column groups::               Grouping to trigger vertical lines
1903 * Orgtbl mode::                 The table editor as minor mode
1904 * The spreadsheet::             The table editor has spreadsheet capabilities
1905 * Org-Plot::                    Plotting from org tables
1906 @end menu
1908 @node Built-in table editor, Column width and alignment, Tables, Tables
1909 @section The built-in table editor
1910 @cindex table editor, built-in
1912 Org makes it easy to format tables in plain ASCII.  Any line with @samp{|} as
1913 the first non-whitespace character is considered part of a table.  @samp{|}
1914 is also the column separator@footnote{To insert a vertical bar into a table
1915 field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}.  A table
1916 might look like this:
1918 @example
1919 | Name  | Phone | Age |
1920 |-------+-------+-----|
1921 | Peter |  1234 |  17 |
1922 | Anna  |  4321 |  25 |
1923 @end example
1925 A table is re-aligned automatically each time you press @key{TAB} or
1926 @key{RET} or @kbd{C-c C-c} inside the table.  @key{TAB} also moves to
1927 the next field (@key{RET} to the next row) and creates new table rows
1928 at the end of the table or before horizontal lines.  The indentation
1929 of the table is set by the first line.  Any line starting with
1930 @samp{|-} is considered as a horizontal separator line and will be
1931 expanded on the next re-align to span the whole table width.  So, to
1932 create the above table, you would only type
1934 @example
1935 |Name|Phone|Age|
1937 @end example
1939 @noindent and then press @key{TAB} to align the table and start filling in
1940 fields.  Even faster would be to type @code{|Name|Phone|Age} followed by
1941 @kbd{C-c @key{RET}}.
1943 @vindex org-enable-table-editor
1944 @vindex org-table-auto-blank-field
1945 When typing text into a field, Org treats @key{DEL},
1946 @key{Backspace}, and all character keys in a special way, so that
1947 inserting and deleting avoids shifting other fields.  Also, when
1948 typing @emph{immediately after the cursor was moved into a new field
1949 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
1950 field is automatically made blank.  If this behavior is too
1951 unpredictable for you, configure the variables
1952 @code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
1954 @table @kbd
1955 @tsubheading{Creation and conversion}
1956 @orgcmd{C-c |,org-table-create-or-convert-from-region}
1957 Convert the active region to table.  If every line contains at least one
1958 TAB character, the function assumes that the material is tab separated.
1959 If every line contains a comma, comma-separated values (CSV) are assumed.
1960 If not, lines are split at whitespace into fields.  You can use a prefix
1961 argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
1962 C-u} forces TAB, and a numeric argument N indicates that at least N
1963 consecutive spaces, or alternatively a TAB will be the separator.
1965 If there is no active region, this command creates an empty Org
1966 table.  But it is easier just to start typing, like
1967 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
1969 @tsubheading{Re-aligning and field motion}
1970 @orgcmd{C-c C-c,org-table-align}
1971 Re-align the table without moving the cursor.
1973 @orgcmd{<TAB>,org-table-next-field}
1974 Re-align the table, move to the next field.  Creates a new row if
1975 necessary.
1977 @orgcmd{S-@key{TAB},org-table-previous-field}
1978 Re-align, move to previous field.
1980 @orgcmd{@key{RET},org-table-next-row}
1981 Re-align the table and move down to next row.  Creates a new row if
1982 necessary.  At the beginning or end of a line, @key{RET} still does
1983 NEWLINE, so it can be used to split a table.
1985 @orgcmd{M-a,org-table-beginning-of-field}
1986 Move to beginning of the current table field, or on to the previous field.
1987 @orgcmd{M-e,org-table-end-of-field}
1988 Move to end of the current table field, or on to the next field.
1990 @tsubheading{Column and row editing}
1991 @orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
1992 Move the current column left/right.
1994 @orgcmd{M-S-@key{left},org-table-delete-column}
1995 Kill the current column.
1997 @orgcmd{M-S-@key{right},org-table-insert-column}
1998 Insert a new column to the left of the cursor position.
2000 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
2001 Move the current row up/down.
2003 @orgcmd{M-S-@key{up},org-table-kill-row}
2004 Kill the current row or horizontal line.
2006 @orgcmd{M-S-@key{down},org-table-insert-row}
2007 Insert a new row above the current row.  With a prefix argument, the line is
2008 created below the current one.
2010 @orgcmd{C-c -,org-table-insert-hline}
2011 Insert a horizontal line below current row.  With a prefix argument, the line
2012 is created above the current line.
2014 @orgcmd{C-c @key{RET},org-table-hline-and-move}
2015 Insert a horizontal line below current row, and move the cursor into the row
2016 below that line.
2018 @orgcmd{C-c ^,org-table-sort-lines}
2019 Sort the table lines in the region.  The position of point indicates the
2020 column to be used for sorting, and the range of lines is the range
2021 between the nearest horizontal separator lines, or the entire table.  If
2022 point is before the first column, you will be prompted for the sorting
2023 column.  If there is an active region, the mark specifies the first line
2024 and the sorting column, while point should be in the last line to be
2025 included into the sorting.  The command prompts for the sorting type
2026 (alphabetically, numerically, or by time).  When called with a prefix
2027 argument, alphabetic sorting will be case-sensitive.
2029 @tsubheading{Regions}
2030 @orgcmd{C-c C-x M-w,org-table-copy-region}
2031 Copy a rectangular region from a table to a special clipboard.  Point and
2032 mark determine edge fields of the rectangle.  If there is no active region,
2033 copy just the current field.  The process ignores horizontal separator lines.
2035 @orgcmd{C-c C-x C-w,org-table-cut-region}
2036 Copy a rectangular region from a table to a special clipboard, and
2037 blank all fields in the rectangle.  So this is the ``cut'' operation.
2039 @orgcmd{C-c C-x C-y,org-table-paste-rectangle}
2040 Paste a rectangular region into a table.
2041 The upper left corner ends up in the current field.  All involved fields
2042 will be overwritten.  If the rectangle does not fit into the present table,
2043 the table is enlarged as needed.  The process ignores horizontal separator
2044 lines.
2046 @orgcmd{M-@key{RET},org-table-wrap-region}
2047 Split the current field at the cursor position and move the rest to the line
2048 below.  If there is an active region, and both point and mark are in the same
2049 column, the text in the column is wrapped to minimum width for the given
2050 number of lines.  A numeric prefix argument may be used to change the number
2051 of desired lines.  If there is no region, but you specify a prefix argument,
2052 the current field is made blank, and the content is appended to the field
2053 above.
2055 @tsubheading{Calculations}
2056 @cindex formula, in tables
2057 @cindex calculations, in tables
2058 @cindex region, active
2059 @cindex active region
2060 @cindex transient mark mode
2061 @orgcmd{C-c +,org-table-sum}
2062 Sum the numbers in the current column, or in the rectangle defined by
2063 the active region.  The result is shown in the echo area and can
2064 be inserted with @kbd{C-y}.
2066 @orgcmd{S-@key{RET},org-table-copy-down}
2067 @vindex org-table-copy-increment
2068 When current field is empty, copy from first non-empty field above.  When not
2069 empty, copy current field down to next row and move cursor along with it.
2070 Depending on the variable @code{org-table-copy-increment}, integer field
2071 values will be incremented during copy.  Integers that are too large will not
2072 be incremented.  Also, a @code{0} prefix argument temporarily disables the
2073 increment.  This key is also used by shift-selection and related modes
2074 (@pxref{Conflicts}).
2076 @tsubheading{Miscellaneous}
2077 @orgcmd{C-c `,org-table-edit-field}
2078 Edit the current field in a separate window.  This is useful for fields that
2079 are not fully visible (@pxref{Column width and alignment}).  When called with
2080 a @kbd{C-u} prefix, just make the full field visible, so that it can be
2081 edited in place.  When called with two @kbd{C-u} prefixes, make the editor
2082 window follow the cursor through the table and always show the current
2083 field.  The follow mode exits automatically when the cursor leaves the table,
2084 or when you repeat this command with @kbd{C-u C-u C-c `}.
2086 @item M-x org-table-import
2087 Import a file as a table.  The table should be TAB or whitespace
2088 separated.  Use, for example, to import a spreadsheet table or data
2089 from a database, because these programs generally can write
2090 TAB-separated text files.  This command works by inserting the file into
2091 the buffer and then converting the region to a table.  Any prefix
2092 argument is passed on to the converter, which uses it to determine the
2093 separator.
2094 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2095 Tables can also be imported by pasting tabular text into the Org
2096 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
2097 @kbd{C-c |} command (see above under @i{Creation and conversion}).
2099 @item M-x org-table-export
2100 @findex org-table-export
2101 @vindex org-table-export-default-format
2102 Export the table, by default as a TAB-separated file.  Use for data
2103 exchange with, for example, spreadsheet or database programs.  The format
2104 used to export the file can be configured in the variable
2105 @code{org-table-export-default-format}.  You may also use properties
2106 @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
2107 name and the format for table export in a subtree.  Org supports quite
2108 general formats for exported tables.  The exporter format is the same as the
2109 format used by Orgtbl radio tables, see @ref{Translator functions}, for a
2110 detailed description.
2111 @end table
2113 If you don't like the automatic table editor because it gets in your
2114 way on lines which you would like to start with @samp{|}, you can turn
2115 it off with
2117 @lisp
2118 (setq org-enable-table-editor nil)
2119 @end lisp
2121 @noindent Then the only table command that still works is
2122 @kbd{C-c C-c} to do a manual re-align.
2124 @node Column width and alignment, Column groups, Built-in table editor, Tables
2125 @section Column width and alignment
2126 @cindex narrow columns in tables
2127 @cindex alignment in tables
2129 The width of columns is automatically determined by the table editor.  And
2130 also the alignment of a column is determined automatically from the fraction
2131 of number-like versus non-number fields in the column.
2133 Sometimes a single field or a few fields need to carry more text, leading to
2134 inconveniently wide columns.  Or maybe you want to make a table with several
2135 columns having a fixed width, regardless of content.  To set@footnote{This
2136 feature does not work on XEmacs.} the width of a column, one field anywhere
2137 in the column may contain just the string @samp{<N>} where @samp{N} is an
2138 integer specifying the width of the column in characters.  The next re-align
2139 will then set the width of this column to this value.
2141 @example
2142 @group
2143 |---+------------------------------|               |---+--------|
2144 |   |                              |               |   | <6>    |
2145 | 1 | one                          |               | 1 | one    |
2146 | 2 | two                          |     ----\     | 2 | two    |
2147 | 3 | This is a long chunk of text |     ----/     | 3 | This=> |
2148 | 4 | four                         |               | 4 | four   |
2149 |---+------------------------------|               |---+--------|
2150 @end group
2151 @end example
2153 @noindent
2154 Fields that are wider become clipped and end in the string @samp{=>}.
2155 Note that the full text is still in the buffer but is hidden.
2156 To see the full text, hold the mouse over the field---a tool-tip window
2157 will show the full content.  To edit such a field, use the command
2158 @kbd{C-c `} (that is @kbd{C-c} followed by the backquote).  This will
2159 open a new window with the full field.  Edit it and finish with @kbd{C-c
2160 C-c}.
2162 @vindex org-startup-align-all-tables
2163 When visiting a file containing a table with narrowed columns, the
2164 necessary character hiding has not yet happened, and the table needs to
2165 be aligned before it looks nice.  Setting the option
2166 @code{org-startup-align-all-tables} will realign all tables in a file
2167 upon visiting, but also slow down startup.  You can also set this option
2168 on a per-file basis with:
2170 @example
2171 #+STARTUP: align
2172 #+STARTUP: noalign
2173 @end example
2175 If you would like to overrule the automatic alignment of number-rich columns
2176 to the right and of string-rich column to the left, you can use @samp{<r>},
2177 @samp{c}@footnote{Centering does not work inside Emacs, but it does have an
2178 effect when exporting to HTML.} or @samp{<l>} in a similar fashion.  You may
2179 also combine alignment and field width like this: @samp{<l10>}.
2181 Lines which only contain these formatting cookies will be removed
2182 automatically when exporting the document.
2184 @node Column groups, Orgtbl mode, Column width and alignment, Tables
2185 @section Column groups
2186 @cindex grouping columns in tables
2188 When Org exports tables, it does so by default without vertical
2189 lines because that is visually more satisfying in general.  Occasionally
2190 however, vertical lines can be useful to structure a table into groups
2191 of columns, much like horizontal lines can do for groups of rows.  In
2192 order to specify column groups, you can use a special row where the
2193 first field contains only @samp{/}.  The further fields can either
2194 contain @samp{<} to indicate that this column should start a group,
2195 @samp{>} to indicate the end of a column, or @samp{<>} to make a column
2196 a group of its own.  Boundaries between column groups will upon export be
2197 marked with vertical lines.  Here is an example:
2199 @example
2200 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2201 |---+-----+-----+-----+---------+------------|
2202 | / |   < |     |   > |       < |          > |
2203 | 1 |   1 |   1 |   1 |       1 |          1 |
2204 | 2 |   4 |   8 |  16 |  1.4142 |     1.1892 |
2205 | 3 |   9 |  27 |  81 |  1.7321 |     1.3161 |
2206 |---+-----+-----+-----+---------+------------|
2207 #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
2208 @end example
2210 It is also sufficient to just insert the column group starters after
2211 every vertical line you would like to have:
2213 @example
2214 |  N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2215 |----+-----+-----+-----+---------+------------|
2216 | /  | <   |     |     | <       |            |
2217 @end example
2219 @node Orgtbl mode, The spreadsheet, Column groups, Tables
2220 @section The Orgtbl minor mode
2221 @cindex Orgtbl mode
2222 @cindex minor mode for tables
2224 If you like the intuitive way the Org table editor works, you
2225 might also want to use it in other modes like Text mode or Mail mode.
2226 The minor mode Orgtbl mode makes this possible.  You can always toggle
2227 the mode with @kbd{M-x orgtbl-mode}.  To turn it on by default, for
2228 example in Message mode, use
2230 @lisp
2231 (add-hook 'message-mode-hook 'turn-on-orgtbl)
2232 @end lisp
2234 Furthermore, with some special setup, it is possible to maintain tables
2235 in arbitrary syntax with Orgtbl mode.  For example, it is possible to
2236 construct @LaTeX{} tables with the underlying ease and power of
2237 Orgtbl mode, including spreadsheet capabilities.  For details, see
2238 @ref{Tables in arbitrary syntax}.
2240 @node The spreadsheet, Org-Plot, Orgtbl mode, Tables
2241 @section The spreadsheet
2242 @cindex calculations, in tables
2243 @cindex spreadsheet capabilities
2244 @cindex @file{calc} package
2246 The table editor makes use of the Emacs @file{calc} package to implement
2247 spreadsheet-like capabilities.  It can also evaluate Emacs Lisp forms to
2248 derive fields from other fields.  While fully featured, Org's implementation
2249 is not identical to other spreadsheets.  For example, Org knows the concept
2250 of a @emph{column formula} that will be applied to all non-header fields in a
2251 column without having to copy the formula to each relevant field.  There is
2252 also a formula debugger, and a formula editor with features for highlighting
2253 fields in the table corresponding to the references at the point in the
2254 formula, moving these references by arrow keys
2256 @menu
2257 * References::                  How to refer to another field or range
2258 * Formula syntax for Calc::     Using Calc to compute stuff
2259 * Formula syntax for Lisp::     Writing formulas in Emacs Lisp
2260 * Durations and time values::   How to compute durations and time values
2261 * Field and range formulas::    Formula for specific (ranges of) fields
2262 * Column formulas::             Formulas valid for an entire column
2263 * Editing and debugging formulas::  Fixing formulas
2264 * Updating the table::          Recomputing all dependent fields
2265 * Advanced features::           Field names, parameters and automatic recalc
2266 @end menu
2268 @node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
2269 @subsection References
2270 @cindex references
2272 To compute fields in the table from other fields, formulas must
2273 reference other fields or ranges.  In Org, fields can be referenced
2274 by name, by absolute coordinates, and by relative coordinates.  To find
2275 out what the coordinates of a field are, press @kbd{C-c ?} in that
2276 field, or press @kbd{C-c @}} to toggle the display of a grid.
2278 @subsubheading Field references
2279 @cindex field references
2280 @cindex references, to fields
2282 Formulas can reference the value of another field in two ways.  Like in
2283 any other spreadsheet, you may reference fields with a letter/number
2284 combination like @code{B3}, meaning the 2nd field in the 3rd row.
2285 @vindex org-table-use-standard-references
2286 However, Org prefers@footnote{Org will understand references typed by the
2287 user as @samp{B4}, but it will not use this syntax when offering a formula
2288 for editing.  You can customize this behavior using the variable
2289 @code{org-table-use-standard-references}.}  to use another, more general
2290 representation that looks like this:
2291 @example
2292 @@@var{row}$@var{column}
2293 @end example
2295 Column specifications can be absolute like @code{$1},
2296 @code{$2},...@code{$@var{N}}, or relative to the current column (i.e.@: the
2297 column of the field which is being computed) like @code{$+1} or @code{$-2}.
2298 @code{$<} and @code{$>} are immutable references to the first and last
2299 column, respectively, and you can use @code{$>>>} to indicate the third
2300 column from the right.
2302 The row specification only counts data lines and ignores horizontal separator
2303 lines (hlines).  Like with columns, you can use absolute row numbers
2304 @code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
2305 current row like @code{@@+3} or @code{@@-1}.  @code{@@<} and @code{@@>} are
2306 immutable references the first and last@footnote{For backward compatibility
2307 you can also use special names like @code{$LR5} and @code{$LR12} to refer in
2308 a stable way to the 5th and 12th field in the last row of the table.
2309 However, this syntax is deprecated, it should not be used for new documents.
2310 Use @code{@@>$} instead.} row in the table, respectively.  You may also
2311 specify the row relative to one of the hlines: @code{@@I} refers to the first
2312 hline, @code{@@II} to the second, etc@.  @code{@@-I} refers to the first such
2313 line above the current line, @code{@@+I} to the first such line below the
2314 current line.  You can also write @code{@@III+2} which is the second data line
2315 after the third hline in the table.
2317 @code{@@0} and @code{$0} refer to the current row and column, respectively,
2318 i.e. to the row/column for the field being computed.  Also, if you omit
2319 either the column or the row part of the reference, the current row/column is
2320 implied.
2322 Org's references with @emph{unsigned} numbers are fixed references
2323 in the sense that if you use the same reference in the formula for two
2324 different fields, the same field will be referenced each time.
2325 Org's references with @emph{signed} numbers are floating
2326 references because the same reference operator can reference different
2327 fields depending on the field being calculated by the formula.
2329 Here are a few examples:
2331 @example
2332 @@2$3      @r{2nd row, 3rd column (same as @code{C2})}
2333 $5        @r{column 5 in the current row (same as @code{E&})}
2334 @@2        @r{current column, row 2}
2335 @@-1$-3    @r{the field one row up, three columns to the left}
2336 @@-I$2     @r{field just under hline above current row, column 2}
2337 @@>$5      @r{field in the last row, in column 5}
2338 @end example
2340 @subsubheading Range references
2341 @cindex range references
2342 @cindex references, to ranges
2344 You may reference a rectangular range of fields by specifying two field
2345 references connected by two dots @samp{..}.  If both fields are in the
2346 current row, you may simply use @samp{$2..$7}, but if at least one field
2347 is in a different row, you need to use the general @code{@@row$column}
2348 format at least for the first field (i.e the reference must start with
2349 @samp{@@} in order to be interpreted correctly).  Examples:
2351 @example
2352 $1..$3        @r{first three fields in the current row}
2353 $P..$Q        @r{range, using column names (see under Advanced)}
2354 $<<<..$>>     @r{start in third column, continue to the one but last}
2355 @@2$1..@@4$3    @r{6 fields between these two fields (same as @code{A2..C4})}
2356 @@-1$-2..@@-1   @r{3 numbers from the column to the left, 2 up to current row}
2357 @@I..II        @r{between first and second hline, short for @code{@@I..@@II}}
2358 @end example
2360 @noindent Range references return a vector of values that can be fed
2361 into Calc vector functions.  Empty fields in ranges are normally
2362 suppressed, so that the vector contains only the non-empty fields (but
2363 see the @samp{E} mode switch below).  If there are no non-empty fields,
2364 @samp{[0]} is returned to avoid syntax errors in formulas.
2366 @subsubheading Field coordinates in formulas
2367 @cindex field coordinates
2368 @cindex coordinates, of field
2369 @cindex row, of field coordinates
2370 @cindex column, of field coordinates
2372 For Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used to
2373 get the row or column number of the field where the formula result goes.
2374 The traditional Lisp formula equivalents are @code{org-table-current-dline}
2375 and @code{org-table-current-column}.  Examples:
2377 @example
2378 if(@@# % 2, $#, string(""))   @r{column number on odd lines only}
2379 $3 = remote(FOO, @@@@#$2)      @r{copy column 2 from table FOO into}
2380                              @r{column 3 of the current table}
2381 @end example
2383 @noindent For the second example, table FOO must have at least as many rows
2384 as the current table.  Note that this is inefficient@footnote{The computation time scales as
2385 O(N^2) because table FOO is parsed for each field to be copied.} for large
2386 number of rows.
2388 @subsubheading Named references
2389 @cindex named references
2390 @cindex references, named
2391 @cindex name, of column or field
2392 @cindex constants, in calculations
2393 @cindex #+CONSTANTS
2395 @vindex org-table-formula-constants
2396 @samp{$name} is interpreted as the name of a column, parameter or
2397 constant.  Constants are defined globally through the variable
2398 @code{org-table-formula-constants}, and locally (for the file) through a
2399 line like
2401 @example
2402 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
2403 @end example
2405 @noindent
2406 @vindex constants-unit-system
2407 @pindex constants.el
2408 Also properties (@pxref{Properties and Columns}) can be used as
2409 constants in table formulas: for a property @samp{:Xyz:} use the name
2410 @samp{$PROP_Xyz}, and the property will be searched in the current
2411 outline entry and in the hierarchy above it.  If you have the
2412 @file{constants.el} package, it will also be used to resolve constants,
2413 including natural constants like @samp{$h} for Planck's constant, and
2414 units like @samp{$km} for kilometers@footnote{@file{constants.el} can
2415 supply the values of constants in two different unit systems, @code{SI}
2416 and @code{cgs}.  Which one is used depends on the value of the variable
2417 @code{constants-unit-system}.  You can use the @code{#+STARTUP} options
2418 @code{constSI} and @code{constcgs} to set this value for the current
2419 buffer.}.  Column names and parameters can be specified in special table
2420 lines.  These are described below, see @ref{Advanced features}.  All
2421 names must start with a letter, and further consist of letters and
2422 numbers.
2424 @subsubheading Remote references
2425 @cindex remote references
2426 @cindex references, remote
2427 @cindex references, to a different table
2428 @cindex name, of column or field
2429 @cindex constants, in calculations
2430 @cindex #+TBLNAME
2432 You may also reference constants, fields and ranges from a different table,
2433 either in the current file or even in a different file.  The syntax is
2435 @example
2436 remote(NAME-OR-ID,REF)
2437 @end example
2439 @noindent
2440 where NAME can be the name of a table in the current file as set by a
2441 @code{#+TBLNAME: NAME} line before the table.  It can also be the ID of an
2442 entry, even in a different file, and the reference then refers to the first
2443 table in that entry.  REF is an absolute field or range reference as
2444 described above for example @code{@@3$3} or @code{$somename}, valid in the
2445 referenced table.
2447 @node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet
2448 @subsection Formula syntax for Calc
2449 @cindex formula syntax, Calc
2450 @cindex syntax, of formulas
2452 A formula can be any algebraic expression understood by the Emacs
2453 @file{Calc} package.  @b{Note that @file{calc} has the
2454 non-standard convention that @samp{/} has lower precedence than
2455 @samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.}  Before
2456 evaluation by @code{calc-eval} (@pxref{Calling Calc from
2457 Your Programs,calc-eval,Calling Calc from Your Lisp Programs,Calc,GNU
2458 Emacs Calc Manual}),
2459 @c FIXME:  The link to the Calc manual in HTML does not work.
2460 variable substitution takes place according to the rules described above.
2461 @cindex vectors, in table calculations
2462 The range vectors can be directly fed into the Calc vector functions
2463 like @samp{vmean} and @samp{vsum}.
2465 @cindex format specifier
2466 @cindex mode, for @file{calc}
2467 @vindex org-calc-default-modes
2468 A formula can contain an optional mode string after a semicolon.  This
2469 string consists of flags to influence Calc and other modes during
2470 execution.  By default, Org uses the standard Calc modes (precision
2471 12, angular units degrees, fraction and symbolic modes off).  The display
2472 format, however, has been changed to @code{(float 8)} to keep tables
2473 compact.  The default settings can be configured using the variable
2474 @code{org-calc-default-modes}.
2476 @example
2477 p20           @r{set the internal Calc calculation precision to 20 digits}
2478 n3 s3 e2 f4   @r{Normal, scientific, engineering, or fixed}
2479               @r{format of the result of Calc passed back to Org.}
2480               @r{Calc formatting is unlimited in precision as}
2481               @r{long as the Calc calculation precision is greater.}
2482 D R           @r{angle modes: degrees, radians}
2483 F S           @r{fraction and symbolic modes}
2484 N             @r{interpret all fields as numbers, use 0 for non-numbers}
2485 T             @r{force text interpretation}
2486 E             @r{keep empty fields in ranges}
2487 L             @r{literal}
2488 @end example
2490 @noindent
2491 Unless you use large integer numbers or high-precision-calculation
2492 and -display for floating point numbers you may alternatively provide a
2493 @code{printf} format specifier to reformat the Calc result after it has been
2494 passed back to Org instead of letting Calc already do the
2495 formatting@footnote{The @code{printf} reformatting is limited in precision
2496 because the value passed to it is converted into an @code{integer} or
2497 @code{double}.  The @code{integer} is limited in size by truncating the
2498 signed value to 32 bits.  The @code{double} is limited in precision to 64
2499 bits overall which leaves approximately 16 significant decimal digits.}.
2500 A few examples:
2502 @example
2503 $1+$2                @r{Sum of first and second field}
2504 $1+$2;%.2f           @r{Same, format result to two decimals}
2505 exp($2)+exp($1)      @r{Math functions can be used}
2506 $0;%.1f              @r{Reformat current cell to 1 decimal}
2507 ($3-32)*5/9          @r{Degrees F -> C conversion}
2508 $c/$1/$cm            @r{Hz -> cm conversion, using @file{constants.el}}
2509 tan($1);Dp3s1        @r{Compute in degrees, precision 3, display SCI 1}
2510 sin($1);Dp3%.1e      @r{Same, but use printf specifier for display}
2511 vmean($2..$7)        @r{Compute column range mean, using vector function}
2512 vmean($2..$7);EN     @r{Same, but treat empty fields as 0}
2513 taylor($3,x=7,2)     @r{Taylor series of $3, at x=7, second degree}
2514 @end example
2516 Calc also contains a complete set of logical operations.  For example
2518 @example
2519 if($1<20,teen,string(""))  @r{"teen" if age $1 less than 20, else empty}
2520 @end example
2522 @node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet
2523 @subsection Emacs Lisp forms as formulas
2524 @cindex Lisp forms, as table formulas
2526 It is also possible to write a formula in Emacs Lisp; this can be useful for
2527 string manipulation and control structures, if Calc's functionality is not
2528 enough.  If a formula starts with a single-quote followed by an opening
2529 parenthesis, then it is evaluated as a Lisp form.  The evaluation should
2530 return either a string or a number.  Just as with @file{calc} formulas, you
2531 can specify modes and a printf format after a semicolon.  With Emacs Lisp
2532 forms, you need to be conscious about the way field references are
2533 interpolated into the form.  By default, a reference will be interpolated as
2534 a Lisp string (in double-quotes) containing the field.  If you provide the
2535 @samp{N} mode switch, all referenced elements will be numbers (non-number
2536 fields will be zero) and interpolated as Lisp numbers, without quotes.  If
2537 you provide the @samp{L} flag, all fields will be interpolated literally,
2538 without quotes.  I.e., if you want a reference to be interpreted as a string
2539 by the Lisp form, enclose the reference operator itself in double-quotes,
2540 like @code{"$3"}.  Ranges are inserted as space-separated fields, so you can
2541 embed them in list or vector syntax.  Here are a few examples---note how the
2542 @samp{N} mode is used when we do computations in Lisp:
2544 @example
2545 @r{Swap the first two characters of the content of column 1}
2546   '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
2547 @r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}}
2548   '(+ $1 $2);N
2549 @r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}}
2550   '(apply '+ '($1..$4));N
2551 @end example
2553 @node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet
2554 @subsection Durations and time values
2555 @cindex Duration, computing
2556 @cindex Time, computing
2558 If you want to compute time values use the @code{T} flag, either in Calc
2559 formulas or Elisp formulas:
2561 @example
2562 @group
2563 | Task 1 | Task 2 |   Total |
2564 |--------+--------+---------|
2565 |  35:00 |  35:00 | 1:10:00 |
2566 #+TBLFM: @@2$3=$1+$2;T
2567 @end group
2568 @end example
2570 Values must be of the form @code{[HH:]MM:SS}, where hours are optional.
2572 @node Field and range formulas, Column formulas, Durations and time values, The spreadsheet
2573 @subsection Field and range formulas
2574 @cindex field formula
2575 @cindex range formula
2576 @cindex formula, for individual table field
2577 @cindex formula, for range of fields
2579 To assign a formula to a particular field, type it directly into the field,
2580 preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}.  When you press
2581 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2582 the formula will be stored as the formula for this field, evaluated, and the
2583 current field will be replaced with the result.
2585 @cindex #+TBLFM
2586 Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
2587 below the table.  If you type the equation in the 4th field of the 3rd data
2588 line in the table, the formula will look like @samp{@@3$4=$1+$2}.  When
2589 inserting/deleting/swapping column and rows with the appropriate commands,
2590 @i{absolute references} (but not relative ones) in stored formulas are
2591 modified in order to still reference the same field.  To avoid this from
2592 happening, in particular in range references, anchor ranges at the table
2593 borders (using @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines
2594 using the @code{@@I} notation.  Automatic adaptation of field references does
2595 of cause not happen if you edit the table structure with normal editing
2596 commands---then you must fix the equations yourself.
2598 Instead of typing an equation into the field, you may also use the following
2599 command
2601 @table @kbd
2602 @orgcmd{C-u C-c =,org-table-eval-formula}
2603 Install a new formula for the current field.  The command prompts for a
2604 formula with default taken from the @samp{#+TBLFM:} line, applies
2605 it to the current field, and stores it.
2606 @end table
2608 The left-hand side of a formula can also be a special expression in order to
2609 assign the formula to a number of different fields.  There is no keyboard
2610 shortcut to enter such range formulas.  To add them, use the formula editor
2611 (@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
2612 directly.
2614 @table @code
2615 @item $2=
2616 Column formula, valid for the entire column.  This is so common that Org
2617 treats these formulas in a special way, see @ref{Column formulas}.
2618 @item @@3=
2619 Row formula, applies to all fields in the specified row.  @code{@@>=} means
2620 the last row.
2621 @item @@1$2..@@4$3=
2622 Range formula, applies to all fields in the given rectangular range.  This
2623 can also be used to assign a formula to some but not all fields in a row.
2624 @item $name=
2625 Named field, see @ref{Advanced features}.
2626 @end table
2628 @node Column formulas, Editing and debugging formulas, Field and range formulas, The spreadsheet
2629 @subsection Column formulas
2630 @cindex column formula
2631 @cindex formula, for table column
2633 When you assign a formula to a simple column reference like @code{$3=}, the
2634 same formula will be used in all fields of that column, with the following
2635 very convenient exceptions: (i) If the table contains horizontal separator
2636 hlines, everything before the first such line is considered part of the table
2637 @emph{header} and will not be modified by column formulas.  (ii) Fields that
2638 already get a value from a field/range formula will be left alone by column
2639 formulas.  These conditions make column formulas very easy to use.
2641 To assign a formula to a column, type it directly into any field in the
2642 column, preceded by an equal sign, like @samp{=$1+$2}.  When you press
2643 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2644 the formula will be stored as the formula for the current column, evaluated
2645 and the current field replaced with the result.  If the field contains only
2646 @samp{=}, the previously stored formula for this column is used.  For each
2647 column, Org will only remember the most recently used formula.  In the
2648 @samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}.  The
2649 left-hand side of a column formula can not be the name of column, it must be
2650 the numeric column reference or @code{$>}.
2652 Instead of typing an equation into the field, you may also use the
2653 following command:
2655 @table @kbd
2656 @orgcmd{C-c =,org-table-eval-formula}
2657 Install a new formula for the current column and replace current field with
2658 the result of the formula.  The command prompts for a formula, with default
2659 taken from the @samp{#+TBLFM} line, applies it to the current field and
2660 stores it.  With a numeric prefix argument(e.g.@: @kbd{C-5 C-c =}) the command
2661 will apply it to that many consecutive fields in the current column.
2662 @end table
2664 @node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet
2665 @subsection Editing and debugging formulas
2666 @cindex formula editing
2667 @cindex editing, of table formulas
2669 @vindex org-table-use-standard-references
2670 You can edit individual formulas in the minibuffer or directly in the
2671 field.  Org can also prepare a special buffer with all active
2672 formulas of a table.  When offering a formula for editing, Org
2673 converts references to the standard format (like @code{B3} or @code{D&})
2674 if possible.  If you prefer to only work with the internal format (like
2675 @code{@@3$2} or @code{$4}), configure the variable
2676 @code{org-table-use-standard-references}.
2678 @table @kbd
2679 @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
2680 Edit the formula associated with the current column/field in the
2681 minibuffer.  See @ref{Column formulas}, and @ref{Field and range formulas}.
2682 @orgcmd{C-u C-u C-c =,org-table-eval-formula}
2683 Re-insert the active formula (either a
2684 field formula, or a column formula) into the current field, so that you
2685 can edit it directly in the field.  The advantage over editing in the
2686 minibuffer is that you can use the command @kbd{C-c ?}.
2687 @orgcmd{C-c ?,org-table-field-info}
2688 While editing a formula in a table field, highlight the field(s)
2689 referenced by the reference at the cursor position in the formula.
2690 @kindex C-c @}
2691 @findex org-table-toggle-coordinate-overlays
2692 @item C-c @}
2693 Toggle the display of row and column numbers for a table, using overlays
2694 (@command{org-table-toggle-coordinate-overlays}).  These are updated each
2695 time the table is aligned; you can force it with @kbd{C-c C-c}.
2696 @kindex C-c @{
2697 @findex org-table-toggle-formula-debugger
2698 @item C-c @{
2699 Toggle the formula debugger on and off
2700 (@command{org-table-toggle-formula-debugger}).  See below.
2701 @orgcmd{C-c ',org-table-edit-formulas}
2702 Edit all formulas for the current table in a special buffer, where the
2703 formulas will be displayed one per line.  If the current field has an
2704 active formula, the cursor in the formula editor will mark it.
2705 While inside the special buffer, Org will automatically highlight
2706 any field or range reference at the cursor position.  You may edit,
2707 remove and add formulas, and use the following commands:
2708 @table @kbd
2709 @orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
2710 Exit the formula editor and store the modified formulas.  With @kbd{C-u}
2711 prefix, also apply the new formulas to the entire table.
2712 @orgcmd{C-c C-q,org-table-fedit-abort}
2713 Exit the formula editor without installing changes.
2714 @orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
2715 Toggle all references in the formula editor between standard (like
2716 @code{B3}) and internal (like @code{@@3$2}).
2717 @orgcmd{@key{TAB},org-table-fedit-lisp-indent}
2718 Pretty-print or indent Lisp formula at point.  When in a line containing
2719 a Lisp formula, format the formula according to Emacs Lisp rules.
2720 Another @key{TAB} collapses the formula back again.  In the open
2721 formula, @key{TAB} re-indents just like in Emacs Lisp mode.
2722 @orgcmd{M-@key{TAB},lisp-complete-symbol}
2723 Complete Lisp symbols, just like in Emacs Lisp mode.
2724 @kindex S-@key{up}
2725 @kindex S-@key{down}
2726 @kindex S-@key{left}
2727 @kindex S-@key{right}
2728 @findex org-table-fedit-ref-up
2729 @findex org-table-fedit-ref-down
2730 @findex org-table-fedit-ref-left
2731 @findex org-table-fedit-ref-right
2732 @item S-@key{up}/@key{down}/@key{left}/@key{right}
2733 Shift the reference at point.  For example, if the reference is
2734 @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
2735 This also works for relative references and for hline references.
2736 @orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
2737 Move the test line for column formulas in the Org buffer up and
2738 down.
2739 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
2740 Scroll the window displaying the table.
2741 @kindex C-c @}
2742 @findex org-table-toggle-coordinate-overlays
2743 @item C-c @}
2744 Turn the coordinate grid in the table on and off.
2745 @end table
2746 @end table
2748 Making a table field blank does not remove the formula associated with
2749 the field, because that is stored in a different line (the @samp{#+TBLFM}
2750 line)---during the next recalculation the field will be filled again.
2751 To remove a formula from a field, you have to give an empty reply when
2752 prompted for the formula, or to edit the @samp{#+TBLFM} line.
2754 @kindex C-c C-c
2755 You may edit the @samp{#+TBLFM} directly and re-apply the changed
2756 equations with @kbd{C-c C-c} in that line or with the normal
2757 recalculation commands in the table.
2759 @subsubheading Debugging formulas
2760 @cindex formula debugging
2761 @cindex debugging, of table formulas
2762 When the evaluation of a formula leads to an error, the field content
2763 becomes the string @samp{#ERROR}.  If you would like see what is going
2764 on during variable substitution and calculation in order to find a bug,
2765 turn on formula debugging in the @code{Tbl} menu and repeat the
2766 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
2767 field.  Detailed information will be displayed.
2769 @node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet
2770 @subsection Updating the table
2771 @cindex recomputing table fields
2772 @cindex updating, table
2774 Recalculation of a table is normally not automatic, but needs to be
2775 triggered by a command.  See @ref{Advanced features}, for a way to make
2776 recalculation at least semi-automatic.
2778 In order to recalculate a line of a table or the entire table, use the
2779 following commands:
2781 @table @kbd
2782 @orgcmd{C-c *,org-table-recalculate}
2783 Recalculate the current row by first applying the stored column formulas
2784 from left to right, and all field/range formulas in the current row.
2786 @kindex C-u C-c *
2787 @item C-u C-c *
2788 @kindex C-u C-c C-c
2789 @itemx C-u C-c C-c
2790 Recompute the entire table, line by line.  Any lines before the first
2791 hline are left alone, assuming that these are part of the table header.
2793 @orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
2794 Iterate the table by recomputing it until no further changes occur.
2795 This may be necessary if some computed fields use the value of other
2796 fields that are computed @i{later} in the calculation sequence.
2797 @item M-x org-table-recalculate-buffer-tables
2798 @findex org-table-recalculate-buffer-tables
2799 Recompute all tables in the current buffer.
2800 @item M-x org-table-iterate-buffer-tables
2801 @findex org-table-iterate-buffer-tables
2802 Iterate all tables in the current buffer, in order to converge table-to-table
2803 dependencies.
2804 @end table
2806 @node Advanced features,  , Updating the table, The spreadsheet
2807 @subsection Advanced features
2809 If you want the recalculation of fields to happen automatically, or if
2810 you want to be able to assign @i{names} to fields and columns, you need
2811 to reserve the first column of the table for special marking characters.
2813 @table @kbd
2814 @orgcmd{C-#,org-table-rotate-recalc-marks}
2815 Rotate the calculation mark in first column through the states @samp{ },
2816 @samp{#}, @samp{*}, @samp{!}, @samp{$}.  When there is an active region,
2817 change all marks in the region.
2818 @end table
2820 Here is an example of a table that collects exam results of students and
2821 makes use of these features:
2823 @example
2824 @group
2825 |---+---------+--------+--------+--------+-------+------|
2826 |   | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
2827 |---+---------+--------+--------+--------+-------+------|
2828 | ! |         |     P1 |     P2 |     P3 |   Tot |      |
2829 | # | Maximum |     10 |     15 |     25 |    50 | 10.0 |
2830 | ^ |         |     m1 |     m2 |     m3 |    mt |      |
2831 |---+---------+--------+--------+--------+-------+------|
2832 | # | Peter   |     10 |      8 |     23 |    41 |  8.2 |
2833 | # | Sam     |      2 |      4 |      3 |     9 |  1.8 |
2834 |---+---------+--------+--------+--------+-------+------|
2835 |   | Average |        |        |        |  29.7 |      |
2836 | ^ |         |        |        |        |    at |      |
2837 | $ | max=50  |        |        |        |       |      |
2838 |---+---------+--------+--------+--------+-------+------|
2839 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
2840 @end group
2841 @end example
2843 @noindent @b{Important}: please note that for these special tables,
2844 recalculating the table with @kbd{C-u C-c *} will only affect rows that
2845 are marked @samp{#} or @samp{*}, and fields that have a formula assigned
2846 to the field itself.  The column formulas are not applied in rows with
2847 empty first field.
2849 @cindex marking characters, tables
2850 The marking characters have the following meaning:
2851 @table @samp
2852 @item !
2853 The fields in this line define names for the columns, so that you may
2854 refer to a column as @samp{$Tot} instead of @samp{$6}.
2855 @item ^
2856 This row defines names for the fields @emph{above} the row.  With such
2857 a definition, any formula in the table may use @samp{$m1} to refer to
2858 the value @samp{10}.  Also, if you assign a formula to a names field, it
2859 will be stored as @samp{$name=...}.
2860 @item _
2861 Similar to @samp{^}, but defines names for the fields in the row
2862 @emph{below}.
2863 @item $
2864 Fields in this row can define @emph{parameters} for formulas.  For
2865 example, if a field in a @samp{$} row contains @samp{max=50}, then
2866 formulas in this table can refer to the value 50 using @samp{$max}.
2867 Parameters work exactly like constants, only that they can be defined on
2868 a per-table basis.
2869 @item #
2870 Fields in this row are automatically recalculated when pressing
2871 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row.  Also, this row
2872 is selected for a global recalculation with @kbd{C-u C-c *}.  Unmarked
2873 lines will be left alone by this command.
2874 @item *
2875 Selects this line for global recalculation with @kbd{C-u C-c *}, but
2876 not for automatic recalculation.  Use this when automatic
2877 recalculation slows down editing too much.
2878 @item
2879 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
2880 All lines that should be recalculated should be marked with @samp{#}
2881 or @samp{*}.
2882 @item /
2883 Do not export this line.  Useful for lines that contain the narrowing
2884 @samp{<N>} markers or column group markers.
2885 @end table
2887 Finally, just to whet your appetite for what can be done with the
2888 fantastic @file{calc.el} package, here is a table that computes the Taylor
2889 series of degree @code{n} at location @code{x} for a couple of
2890 functions.
2892 @example
2893 @group
2894 |---+-------------+---+-----+--------------------------------------|
2895 |   | Func        | n | x   | Result                               |
2896 |---+-------------+---+-----+--------------------------------------|
2897 | # | exp(x)      | 1 | x   | 1 + x                                |
2898 | # | exp(x)      | 2 | x   | 1 + x + x^2 / 2                      |
2899 | # | exp(x)      | 3 | x   | 1 + x + x^2 / 2 + x^3 / 6            |
2900 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
2901 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2    |
2902 | * | tan(x)      | 3 | x   | 0.0175 x + 1.77e-6 x^3               |
2903 |---+-------------+---+-----+--------------------------------------|
2904 #+TBLFM: $5=taylor($2,$4,$3);n3
2905 @end group
2906 @end example
2908 @node Org-Plot,  , The spreadsheet, Tables
2909 @section Org-Plot
2910 @cindex graph, in tables
2911 @cindex plot tables using Gnuplot
2912 @cindex #+PLOT
2914 Org-Plot can produce 2D and 3D graphs of information stored in org tables
2915 using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
2916 @uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}.  To see
2917 this in action, ensure that you have both Gnuplot and Gnuplot mode installed
2918 on your system, then call @code{org-plot/gnuplot} on the following table.
2920 @example
2921 @group
2922 #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
2923 | Sede      | Max cites | H-index |
2924 |-----------+-----------+---------|
2925 | Chile     |    257.72 |   21.39 |
2926 | Leeds     |    165.77 |   19.68 |
2927 | Sao Paolo |     71.00 |   11.50 |
2928 | Stockholm |    134.19 |   14.33 |
2929 | Morelia   |    257.56 |   17.67 |
2930 @end group
2931 @end example
2933 Notice that Org Plot is smart enough to apply the table's headers as labels.
2934 Further control over the labels, type, content, and appearance of plots can
2935 be exercised through the @code{#+PLOT:} lines preceding a table.  See below
2936 for a complete list of Org-plot options.  For more information and examples
2937 see the Org-plot tutorial at
2938 @uref{http://orgmode.org/worg/org-tutorials/org-plot.html}.
2940 @subsubheading Plot Options
2942 @table @code
2943 @item set
2944 Specify any @command{gnuplot} option to be set when graphing.
2946 @item title
2947 Specify the title of the plot.
2949 @item ind
2950 Specify which column of the table to use as the @code{x} axis.
2952 @item deps
2953 Specify the columns to graph as a Lisp style list, surrounded by parentheses
2954 and separated by spaces for example @code{dep:(3 4)} to graph the third and
2955 fourth columns (defaults to graphing all other columns aside from the @code{ind}
2956 column).
2958 @item type
2959 Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
2961 @item with
2962 Specify a @code{with} option to be inserted for every col being plotted
2963 (e.g.@: @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
2964 Defaults to @code{lines}.
2966 @item file
2967 If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
2969 @item labels
2970 List of labels to be used for the @code{deps} (defaults to the column headers
2971 if they exist).
2973 @item line
2974 Specify an entire line to be inserted in the Gnuplot script.
2976 @item map
2977 When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
2978 flat mapping rather than a @code{3d} slope.
2980 @item timefmt
2981 Specify format of Org-mode timestamps as they will be parsed by Gnuplot.
2982 Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
2984 @item script
2985 If you want total control, you can specify a script file (place the file name
2986 between double-quotes) which will be used to plot.  Before plotting, every
2987 instance of @code{$datafile} in the specified script will be replaced with
2988 the path to the generated data file.  Note: even if you set this option, you
2989 may still want to specify the plot type, as that can impact the content of
2990 the data file.
2991 @end table
2993 @node Hyperlinks, TODO Items, Tables, Top
2994 @chapter Hyperlinks
2995 @cindex hyperlinks
2997 Like HTML, Org provides links inside a file, external links to
2998 other files, Usenet articles, emails, and much more.
3000 @menu
3001 * Link format::                 How links in Org are formatted
3002 * Internal links::              Links to other places in the current file
3003 * External links::              URL-like links to the world
3004 * Handling links::              Creating, inserting and following
3005 * Using links outside Org::     Linking from my C source code?
3006 * Link abbreviations::          Shortcuts for writing complex links
3007 * Search options::              Linking to a specific location
3008 * Custom searches::             When the default search is not enough
3009 @end menu
3011 @node Link format, Internal links, Hyperlinks, Hyperlinks
3012 @section Link format
3013 @cindex link format
3014 @cindex format, of links
3016 Org will recognize plain URL-like links and activate them as
3017 clickable links.  The general link format, however, looks like this:
3019 @example
3020 [[link][description]]       @r{or alternatively}           [[link]]
3021 @end example
3023 @noindent
3024 Once a link in the buffer is complete (all brackets present), Org
3025 will change the display so that @samp{description} is displayed instead
3026 of @samp{[[link][description]]} and @samp{link} is displayed instead of
3027 @samp{[[link]]}.  Links will be highlighted in the face @code{org-link},
3028 which by default is an underlined face.  You can directly edit the
3029 visible part of a link.  Note that this can be either the @samp{link}
3030 part (if there is no description) or the @samp{description} part.  To
3031 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
3032 cursor on the link.
3034 If you place the cursor at the beginning or just behind the end of the
3035 displayed text and press @key{BACKSPACE}, you will remove the
3036 (invisible) bracket at that location.  This makes the link incomplete
3037 and the internals are again displayed as plain text.  Inserting the
3038 missing bracket hides the link internals again.  To show the
3039 internal structure of all links, use the menu entry
3040 @code{Org->Hyperlinks->Literal links}.
3042 @node Internal links, External links, Link format, Hyperlinks
3043 @section Internal links
3044 @cindex internal links
3045 @cindex links, internal
3046 @cindex targets, for links
3048 @cindex property, CUSTOM_ID
3049 If the link does not look like a URL, it is considered to be internal in the
3050 current file.  The most important case is a link like
3051 @samp{[[#my-custom-id]]} which will link to the entry with the
3052 @code{CUSTOM_ID} property @samp{my-custom-id}.  Such custom IDs are very good
3053 for HTML export (@pxref{HTML export}) where they produce pretty section
3054 links.  You are responsible yourself to make sure these custom IDs are unique
3055 in a file.
3057 Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
3058 lead to a text search in the current file.
3060 The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
3061 or with a mouse click (@pxref{Handling links}).  Links to custom IDs will
3062 point to the corresponding headline.  The preferred match for a text link is
3063 a @i{dedicated target}: the same string in double angular brackets.  Targets
3064 may be located anywhere; sometimes it is convenient to put them into a
3065 comment line.  For example
3067 @example
3068 # <<My Target>>
3069 @end example
3071 @noindent In HTML export (@pxref{HTML export}), such targets will become
3072 named anchors for direct access through @samp{http} links@footnote{Note that
3073 text before the first headline is usually not exported, so the first such
3074 target should be after the first headline, or in the line directly before the
3075 first headline.}.
3077 If no dedicated target exists, Org will search for a headline that is exactly
3078 the link text but may also include a TODO keyword and tags@footnote{To insert
3079 a link targeting a headline, in-buffer completion can be used.  Just type a
3080 star followed by a few optional letters into the buffer and press
3081 @kbd{M-@key{TAB}}.  All headlines in the current buffer will be offered as
3082 completions.}.  In non-Org files, the search will look for the words in the
3083 link text.  In the above example the search would be for @samp{my target}.
3085 Following a link pushes a mark onto Org's own mark ring.  You can
3086 return to the previous position with @kbd{C-c &}.  Using this command
3087 several times in direct succession goes back to positions recorded
3088 earlier.
3090 @menu
3091 * Radio targets::               Make targets trigger links in plain text
3092 @end menu
3094 @node Radio targets,  , Internal links, Internal links
3095 @subsection Radio targets
3096 @cindex radio targets
3097 @cindex targets, radio
3098 @cindex links, radio targets
3100 Org can automatically turn any occurrences of certain target names
3101 in normal text into a link.  So without explicitly creating a link, the
3102 text connects to the target radioing its position.  Radio targets are
3103 enclosed by triple angular brackets.  For example, a target @samp{<<<My
3104 Target>>>} causes each occurrence of @samp{my target} in normal text to
3105 become activated as a link.  The Org file is scanned automatically
3106 for radio targets only when the file is first loaded into Emacs.  To
3107 update the target list during editing, press @kbd{C-c C-c} with the
3108 cursor on or at a target.
3110 @node External links, Handling links, Internal links, Hyperlinks
3111 @section External links
3112 @cindex links, external
3113 @cindex external links
3114 @cindex links, external
3115 @cindex Gnus links
3116 @cindex BBDB links
3117 @cindex IRC links
3118 @cindex URL links
3119 @cindex file links
3120 @cindex VM links
3121 @cindex RMAIL links
3122 @cindex WANDERLUST links
3123 @cindex MH-E links
3124 @cindex USENET links
3125 @cindex SHELL links
3126 @cindex Info links
3127 @cindex Elisp links
3129 Org supports links to files, websites, Usenet and email messages,
3130 BBDB database entries and links to both IRC conversations and their
3131 logs.  External links are URL-like locators.  They start with a short
3132 identifying string followed by a colon.  There can be no space after
3133 the colon.  The following list shows examples for each link type.
3135 @example
3136 http://www.astro.uva.nl/~dominik          @r{on the web}
3137 doi:10.1000/182                           @r{DOI for an electronic resource}
3138 file:/home/dominik/images/jupiter.jpg     @r{file, absolute path}
3139 /home/dominik/images/jupiter.jpg          @r{same as above}
3140 file:papers/last.pdf                      @r{file, relative path}
3141 ./papers/last.pdf                         @r{same as above}
3142 file:/myself@@some.where:papers/last.pdf   @r{file, path on remote machine}
3143 /myself@@some.where:papers/last.pdf        @r{same as above}
3144 file:sometextfile::NNN                    @r{file with line number to jump to}
3145 file:projects.org                         @r{another Org file}
3146 file:projects.org::some words             @r{text search in Org file}
3147 file:projects.org::*task title            @r{heading search in Org file}
3148 docview:papers/last.pdf::NNN              @r{open file in doc-view mode at page NNN}
3149 id:B7423F4D-2E8A-471B-8810-C40F074717E9   @r{Link to heading by ID}
3150 news:comp.emacs                           @r{Usenet link}
3151 mailto:adent@@galaxy.net                   @r{Mail link}
3152 vm:folder                                 @r{VM folder link}
3153 vm:folder#id                              @r{VM message link}
3154 vm://myself@@some.where.org/folder#id      @r{VM on remote machine}
3155 wl:folder                                 @r{WANDERLUST folder link}
3156 wl:folder#id                              @r{WANDERLUST message link}
3157 mhe:folder                                @r{MH-E folder link}
3158 mhe:folder#id                             @r{MH-E message link}
3159 rmail:folder                              @r{RMAIL folder link}
3160 rmail:folder#id                           @r{RMAIL message link}
3161 gnus:group                                @r{Gnus group link}
3162 gnus:group#id                             @r{Gnus article link}
3163 bbdb:R.*Stallman                          @r{BBDB link (with regexp)}
3164 irc:/irc.com/#emacs/bob                   @r{IRC link}
3165 info:org#External%20links                 @r{Info node link (with encoded space)}
3166 shell:ls *.org                            @r{A shell command}
3167 elisp:org-agenda                          @r{Interactive Elisp command}
3168 elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
3169 @end example
3171 For customizing Org to add new link types @ref{Adding hyperlink types}.
3173 A link should be enclosed in double brackets and may contain a
3174 descriptive text to be displayed instead of the URL (@pxref{Link
3175 format}), for example:
3177 @example
3178 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
3179 @end example
3181 @noindent
3182 If the description is a file name or URL that points to an image, HTML
3183 export (@pxref{HTML export}) will inline the image as a clickable
3184 button.  If there is no description at all and the link points to an
3185 image,
3186 that image will be inlined into the exported HTML file.
3188 @cindex square brackets, around links
3189 @cindex plain text external links
3190 Org also finds external links in the normal text and activates them
3191 as links.  If spaces must be part of the link (for example in
3192 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
3193 about the end of the link, enclose them in square brackets.
3195 @node Handling links, Using links outside Org, External links, Hyperlinks
3196 @section Handling links
3197 @cindex links, handling
3199 Org provides methods to create a link in the correct syntax, to
3200 insert it into an Org file, and to follow the link.
3202 @table @kbd
3203 @orgcmd{C-c l,org-store-link}
3204 @cindex storing links
3205 Store a link to the current location.  This is a @emph{global} command (you
3206 must create the key binding yourself) which can be used in any buffer to
3207 create a link.  The link will be stored for later insertion into an Org
3208 buffer (see below).  What kind of link will be created depends on the current
3209 buffer:
3211 @b{Org-mode buffers}@*
3212 For Org files, if there is a @samp{<<target>>} at the cursor, the link points
3213 to the target.  Otherwise it points to the current headline, which will also
3214 be the description@footnote{If the headline contains a timestamp, it will be
3215 removed from the link and result in a wrong link -- you should avoid putting
3216 timestamp in the headline.}.
3218 @vindex org-link-to-org-use-id
3219 @cindex property, CUSTOM_ID
3220 @cindex property, ID
3221 If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
3222 will be stored.  In addition or alternatively (depending on the value of
3223 @code{org-link-to-org-use-id}), a globally unique @code{ID} property will be
3224 created and/or used to construct a link.  So using this command in Org
3225 buffers will potentially create two links: a human-readable from the custom
3226 ID, and one that is globally unique and works even if the entry is moved from
3227 file to file.  Later, when inserting the link, you need to decide which one
3228 to use.
3230 @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
3231 Pretty much all Emacs mail clients are supported.  The link will point to the
3232 current article, or, in some GNUS buffers, to the group.  The description is
3233 constructed from the author and the subject.
3235 @b{Web browsers: W3 and W3M}@*
3236 Here the link will be the current URL, with the page title as description.
3238 @b{Contacts: BBDB}@*
3239 Links created in a BBDB buffer will point to the current entry.
3241 @b{Chat: IRC}@*
3242 @vindex org-irc-link-to-logs
3243 For IRC links, if you set the variable @code{org-irc-link-to-logs} to
3244 @code{t}, a @samp{file:/} style link to the relevant point in the logs for
3245 the current conversation is created.  Otherwise an @samp{irc:/} style link to
3246 the user/channel/server under the point will be stored.
3248 @b{Other files}@*
3249 For any other files, the link will point to the file, with a search string
3250 (@pxref{Search options}) pointing to the contents of the current line.  If
3251 there is an active region, the selected words will form the basis of the
3252 search string.  If the automatically created link is not working correctly or
3253 accurately enough, you can write custom functions to select the search string
3254 and to do the search for particular file types---see @ref{Custom searches}.
3255 The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
3257 @b{Agenda view}@*
3258 When the cursor is in an agenda view, the created link points to the
3259 entry referenced by the current line.
3262 @orgcmd{C-c C-l,org-insert-link}
3263 @cindex link completion
3264 @cindex completion, of links
3265 @cindex inserting links
3266 @vindex org-keep-stored-link-after-insertion
3267 Insert a link@footnote{ Note that you don't have to use this command to
3268 insert a link.  Links in Org are plain text, and you can type or paste them
3269 straight into the buffer.  By using this command, the links are automatically
3270 enclosed in double brackets, and you will be asked for the optional
3271 descriptive text.}.  This prompts for a link to be inserted into the buffer.
3272 You can just type a link, using text for an internal link, or one of the link
3273 type prefixes mentioned in the examples above.  The link will be inserted
3274 into the buffer@footnote{After insertion of a stored link, the link will be
3275 removed from the list of stored links.  To keep it in the list later use, use
3276 a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
3277 @code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
3278 If some text was selected when this command is called, the selected text
3279 becomes the default description.
3281 @b{Inserting stored links}@*
3282 All links stored during the
3283 current session are part of the history for this prompt, so you can access
3284 them with @key{up} and @key{down} (or @kbd{M-p/n}).
3286 @b{Completion support}@* Completion with @key{TAB} will help you to insert
3287 valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes
3288 defined through link abbreviations (@pxref{Link abbreviations}).  If you
3289 press @key{RET} after inserting only the @var{prefix}, Org will offer
3290 specific completion support for some link types@footnote{This works by
3291 calling a special function @code{org-PREFIX-complete-link}.}  For
3292 example, if you type @kbd{file @key{RET}}, file name completion (alternative
3293 access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb
3294 @key{RET}} you can complete contact names.
3295 @orgkey C-u C-c C-l
3296 @cindex file name completion
3297 @cindex completion, of file names
3298 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
3299 a file will be inserted and you may use file name completion to select
3300 the name of the file.  The path to the file is inserted relative to the
3301 directory of the current Org file, if the linked file is in the current
3302 directory or in a sub-directory of it, or if the path is written relative
3303 to the current directory using @samp{../}.  Otherwise an absolute path
3304 is used, if possible with @samp{~/} for your home directory.  You can
3305 force an absolute path with two @kbd{C-u} prefixes.
3307 @item C-c C-l @ @r{(with cursor on existing link)}
3308 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
3309 link and description parts of the link.
3311 @cindex following links
3312 @orgcmd{C-c C-o,org-open-at-point}
3313 @vindex org-file-apps
3314 Open link at point.  This will launch a web browser for URLs (using
3315 @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
3316 the corresponding links, and execute the command in a shell link.  When the
3317 cursor is on an internal link, this command runs the corresponding search.
3318 When the cursor is on a TAG list in a headline, it creates the corresponding
3319 TAGS view.  If the cursor is on a timestamp, it compiles the agenda for that
3320 date.  Furthermore, it will visit text and remote files in @samp{file:} links
3321 with Emacs and select a suitable application for local non-text files.
3322 Classification of files is based on file extension only.  See option
3323 @code{org-file-apps}.  If you want to override the default application and
3324 visit the file with Emacs, use a @kbd{C-u} prefix.  If you want to avoid
3325 opening in Emacs, use a @kbd{C-u C-u} prefix.@*
3326 If the cursor is on a headline, but not on a link, offer all links in the
3327 headline and entry text.
3328 @orgkey @key{RET}
3329 @vindex org-return-follows-link
3330 When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
3331 the link at point.
3333 @kindex mouse-2
3334 @kindex mouse-1
3335 @item mouse-2
3336 @itemx mouse-1
3337 On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
3338 would.  Under Emacs 22 and later, @kbd{mouse-1} will also follow a link.
3340 @kindex mouse-3
3341 @item mouse-3
3342 @vindex org-display-internal-link-with-indirect-buffer
3343 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
3344 internal links to be displayed in another window@footnote{See the
3345 variable @code{org-display-internal-link-with-indirect-buffer}}.
3347 @orgcmd{C-c C-x C-v,org-toggle-inline-images}
3348 @cindex inlining images
3349 @cindex images, inlining
3350 @vindex org-startup-with-inline-images
3351 @cindex @code{inlineimages}, STARTUP keyword
3352 @cindex @code{noinlineimages}, STARTUP keyword
3353 Toggle the inline display of linked images.  Normally this will only inline
3354 images that have no description part in the link, i.e.@: images that will also
3355 be inlined during export.  When called with a prefix argument, also display
3356 images that do have a link description.  You can ask for inline images to be
3357 displayed at startup by configuring the variable
3358 @code{org-startup-with-inline-images}@footnote{with corresponding
3359 @code{#+STARTUP} keywords @code{inlineimages} and @code{inlineimages}}.
3360 @orgcmd{C-c %,org-mark-ring-push}
3361 @cindex mark ring
3362 Push the current position onto the mark ring, to be able to return
3363 easily.  Commands following an internal link do this automatically.
3365 @orgcmd{C-c &,org-mark-ring-goto}
3366 @cindex links, returning to
3367 Jump back to a recorded position.  A position is recorded by the
3368 commands following internal links, and by @kbd{C-c %}.  Using this
3369 command several times in direct succession moves through a ring of
3370 previously recorded positions.
3372 @orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
3373 @cindex links, finding next/previous
3374 Move forward/backward to the next link in the buffer.  At the limit of
3375 the buffer, the search fails once, and then wraps around.  The key
3376 bindings for this are really too long; you might want to bind this also
3377 to @kbd{C-n} and @kbd{C-p}
3378 @lisp
3379 (add-hook 'org-load-hook
3380   (lambda ()
3381     (define-key org-mode-map "\C-n" 'org-next-link)
3382     (define-key org-mode-map "\C-p" 'org-previous-link)))
3383 @end lisp
3384 @end table
3386 @node Using links outside Org, Link abbreviations, Handling links, Hyperlinks
3387 @section Using links outside Org
3389 You can insert and follow links that have Org syntax not only in
3390 Org, but in any Emacs buffer.  For this, you should create two
3391 global commands, like this (please select suitable global keys
3392 yourself):
3394 @lisp
3395 (global-set-key "\C-c L" 'org-insert-link-global)
3396 (global-set-key "\C-c o" 'org-open-at-point-global)
3397 @end lisp
3399 @node Link abbreviations, Search options, Using links outside Org, Hyperlinks
3400 @section Link abbreviations
3401 @cindex link abbreviations
3402 @cindex abbreviation, links
3404 Long URLs can be cumbersome to type, and often many similar links are
3405 needed in a document.  For this you can use link abbreviations.  An
3406 abbreviated link looks like this
3408 @example
3409 [[linkword:tag][description]]
3410 @end example
3412 @noindent
3413 @vindex org-link-abbrev-alist
3414 where the tag is optional.
3415 The @i{linkword} must be a word, starting with a letter, followed by
3416 letters, numbers, @samp{-}, and @samp{_}.  Abbreviations are resolved
3417 according to the information in the variable @code{org-link-abbrev-alist}
3418 that relates the linkwords to replacement text.  Here is an example:
3420 @smalllisp
3421 @group
3422 (setq org-link-abbrev-alist
3423   '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
3424     ("google"   . "http://www.google.com/search?q=")
3425     ("gmap"     . "http://maps.google.com/maps?q=%s")
3426     ("omap"     . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
3427     ("ads"      . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
3428 @end group
3429 @end smalllisp
3431 If the replacement text contains the string @samp{%s}, it will be
3432 replaced with the tag.  Otherwise the tag will be appended to the string
3433 in order to create the link.  You may also specify a function that will
3434 be called with the tag as the only argument to create the link.
3436 With the above setting, you could link to a specific bug with
3437 @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
3438 @code{[[google:OrgMode]]}, show the map location of the Free Software
3439 Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
3440 @code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
3441 what the Org author is doing besides Emacs hacking with
3442 @code{[[ads:Dominik,C]]}.
3444 If you need special abbreviations just for a single Org buffer, you
3445 can define them in the file with
3447 @cindex #+LINK
3448 @example
3449 #+LINK: bugzilla  http://10.1.2.9/bugzilla/show_bug.cgi?id=
3450 #+LINK: google    http://www.google.com/search?q=%s
3451 @end example
3453 @noindent
3454 In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
3455 complete link abbreviations.  You may also define a function
3456 @code{org-PREFIX-complete-link} that implements special (e.g.@: completion)
3457 support for inserting such a link with @kbd{C-c C-l}.  Such a function should
3458 not accept any arguments, and return the full link with prefix.
3460 @node Search options, Custom searches, Link abbreviations, Hyperlinks
3461 @section Search options in file links
3462 @cindex search option in file links
3463 @cindex file links, searching
3465 File links can contain additional information to make Emacs jump to a
3466 particular location in the file when following a link.  This can be a
3467 line number or a search option after a double@footnote{For backward
3468 compatibility, line numbers can also follow a single colon.} colon.  For
3469 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
3470 links}) to a file, it encodes the words in the current line as a search
3471 string that can be used to find this line back later when following the
3472 link with @kbd{C-c C-o}.
3474 Here is the syntax of the different ways to attach a search to a file
3475 link, together with an explanation:
3477 @example
3478 [[file:~/code/main.c::255]]
3479 [[file:~/xx.org::My Target]]
3480 [[file:~/xx.org::*My Target]]
3481 [[file:~/xx.org::#my-custom-id]]
3482 [[file:~/xx.org::/regexp/]]
3483 @end example
3485 @table @code
3486 @item 255
3487 Jump to line 255.
3488 @item My Target
3489 Search for a link target @samp{<<My Target>>}, or do a text search for
3490 @samp{my target}, similar to the search in internal links, see
3491 @ref{Internal links}.  In HTML export (@pxref{HTML export}), such a file
3492 link will become an HTML reference to the corresponding named anchor in
3493 the linked file.
3494 @item *My Target
3495 In an Org file, restrict search to headlines.
3496 @item #my-custom-id
3497 Link to a heading with a @code{CUSTOM_ID} property
3498 @item /regexp/
3499 Do a regular expression search for @code{regexp}.  This uses the Emacs
3500 command @code{occur} to list all matches in a separate window.  If the
3501 target file is in Org-mode, @code{org-occur} is used to create a
3502 sparse tree with the matches.
3503 @c If the target file is a directory,
3504 @c @code{grep} will be used to search all files in the directory.
3505 @end table
3507 As a degenerate case, a file link with an empty file name can be used
3508 to search the current file.  For example, @code{[[file:::find me]]} does
3509 a search for @samp{find me} in the current file, just as
3510 @samp{[[find me]]} would.
3512 @node Custom searches,  , Search options, Hyperlinks
3513 @section Custom Searches
3514 @cindex custom search strings
3515 @cindex search strings, custom
3517 The default mechanism for creating search strings and for doing the
3518 actual search related to a file link may not work correctly in all
3519 cases.  For example, Bib@TeX{} database files have many entries like
3520 @samp{year="1993"} which would not result in good search strings,
3521 because the only unique identification for a Bib@TeX{} entry is the
3522 citation key.
3524 @vindex org-create-file-search-functions
3525 @vindex org-execute-file-search-functions
3526 If you come across such a problem, you can write custom functions to set
3527 the right search string for a particular file type, and to do the search
3528 for the string in the file.  Using @code{add-hook}, these functions need
3529 to be added to the hook variables
3530 @code{org-create-file-search-functions} and
3531 @code{org-execute-file-search-functions}.  See the docstring for these
3532 variables for more information.  Org actually uses this mechanism
3533 for Bib@TeX{} database files, and you can use the corresponding code as
3534 an implementation example.  See the file @file{org-bibtex.el}.
3536 @node TODO Items, Tags, Hyperlinks, Top
3537 @chapter TODO items
3538 @cindex TODO items
3540 Org-mode does not maintain TODO lists as separate documents@footnote{Of
3541 course, you can make a document that contains only long lists of TODO items,
3542 but this is not required.}.  Instead, TODO items are an integral part of the
3543 notes file, because TODO items usually come up while taking notes!  With Org
3544 mode, simply mark any entry in a tree as being a TODO item.  In this way,
3545 information is not duplicated, and the entire context from which the TODO
3546 item emerged is always present.
3548 Of course, this technique for managing TODO items scatters them
3549 throughout your notes file.  Org-mode compensates for this by providing
3550 methods to give you an overview of all the things that you have to do.
3552 @menu
3553 * TODO basics::                 Marking and displaying TODO entries
3554 * TODO extensions::             Workflow and assignments
3555 * Progress logging::            Dates and notes for progress
3556 * Priorities::                  Some things are more important than others
3557 * Breaking down tasks::         Splitting a task into manageable pieces
3558 * Checkboxes::                  Tick-off lists
3559 @end menu
3561 @node TODO basics, TODO extensions, TODO Items, TODO Items
3562 @section Basic TODO functionality
3564 Any headline becomes a TODO item when it starts with the word
3565 @samp{TODO}, for example:
3567 @example
3568 *** TODO Write letter to Sam Fortune
3569 @end example
3571 @noindent
3572 The most important commands to work with TODO entries are:
3574 @table @kbd
3575 @orgcmd{C-c C-t,org-todo}
3576 @cindex cycling, of TODO states
3577 Rotate the TODO state of the current item among
3579 @example
3580 ,-> (unmarked) -> TODO -> DONE --.
3581 '--------------------------------'
3582 @end example
3584 The same rotation can also be done ``remotely'' from the timeline and
3585 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
3587 @orgkey{C-u C-c C-t}
3588 Select a specific keyword using completion or (if it has been set up)
3589 the fast selection interface.  For the latter, you need to assign keys
3590 to TODO states, see @ref{Per-file keywords}, and @ref{Setting tags}, for
3591 more information.
3593 @kindex S-@key{right}
3594 @kindex S-@key{left}
3595 @item S-@key{right} @ @r{/} @ S-@key{left}
3596 @vindex org-treat-S-cursor-todo-selection-as-state-change
3597 Select the following/preceding TODO state, similar to cycling.  Useful
3598 mostly if more than two TODO states are possible (@pxref{TODO
3599 extensions}).  See also @ref{Conflicts}, for a discussion of the interaction
3600 with @code{shift-selection-mode}.  See also the variable
3601 @code{org-treat-S-cursor-todo-selection-as-state-change}.
3602 @orgcmd{C-c / t,org-show-todo-key}
3603 @cindex sparse tree, for TODO
3604 @vindex org-todo-keywords
3605 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}).  Folds the
3606 entire buffer, but shows all TODO items (with not-DONE state) and the
3607 headings hierarchy above them.  With a prefix argument (or by using @kbd{C-c
3608 / T}), search for a specific TODO.  You will be prompted for the keyword, and
3609 you can also give a list of keywords like @code{KWD1|KWD2|...} to list
3610 entries that match any one of these keywords.  With a numeric prefix argument
3611 N, show the tree for the Nth keyword in the variable
3612 @code{org-todo-keywords}.  With two prefix arguments, find all TODO states,
3613 both un-done and done.
3614 @orgcmd{C-c a t,org-todo-list}
3615 Show the global TODO list.  Collects the TODO items (with not-DONE states)
3616 from all agenda files (@pxref{Agenda Views}) into a single buffer.  The new
3617 buffer will be in @code{agenda-mode}, which provides commands to examine and
3618 manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
3619 @xref{Global TODO list}, for more information.
3620 @orgcmd{S-M-@key{RET},org-insert-todo-heading}
3621 Insert a new TODO entry below the current one.
3622 @end table
3624 @noindent
3625 @vindex org-todo-state-tags-triggers
3626 Changing a TODO state can also trigger tag changes.  See the docstring of the
3627 option @code{org-todo-state-tags-triggers} for details.
3629 @node TODO extensions, Progress logging, TODO basics, TODO Items
3630 @section Extended use of TODO keywords
3631 @cindex extended TODO keywords
3633 @vindex org-todo-keywords
3634 By default, marked TODO entries have one of only two states: TODO and
3635 DONE.  Org-mode allows you to classify TODO items in more complex ways
3636 with @emph{TODO keywords} (stored in @code{org-todo-keywords}).  With
3637 special setup, the TODO keyword system can work differently in different
3638 files.
3640 Note that @i{tags} are another way to classify headlines in general and
3641 TODO items in particular (@pxref{Tags}).
3643 @menu
3644 * Workflow states::             From TODO to DONE in steps
3645 * TODO types::                  I do this, Fred does the rest
3646 * Multiple sets in one file::   Mixing it all, and still finding your way
3647 * Fast access to TODO states::  Single letter selection of a state
3648 * Per-file keywords::           Different files, different requirements
3649 * Faces for TODO keywords::     Highlighting states
3650 * TODO dependencies::           When one task needs to wait for others
3651 @end menu
3653 @node Workflow states, TODO types, TODO extensions, TODO extensions
3654 @subsection TODO keywords as workflow states
3655 @cindex TODO workflow
3656 @cindex workflow states as TODO keywords
3658 You can use TODO keywords to indicate different @emph{sequential} states
3659 in the process of working on an item, for example@footnote{Changing
3660 this variable only becomes effective after restarting Org-mode in a
3661 buffer.}:
3663 @lisp
3664 (setq org-todo-keywords
3665   '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
3666 @end lisp
3668 The vertical bar separates the TODO keywords (states that @emph{need
3669 action}) from the DONE states (which need @emph{no further action}).  If
3670 you don't provide the separator bar, the last state is used as the DONE
3671 state.
3672 @cindex completion, of TODO keywords
3673 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
3674 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.  You may
3675 also use a numeric prefix argument to quickly select a specific state.  For
3676 example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
3677 Or you can use @kbd{S-@key{left}} to go backward through the sequence.  If you
3678 define many keywords, you can use in-buffer completion
3679 (@pxref{Completion}) or even a special one-key selection scheme
3680 (@pxref{Fast access to TODO states}) to insert these words into the
3681 buffer.  Changing a TODO state can be logged with a timestamp, see
3682 @ref{Tracking TODO state changes}, for more information.
3684 @node TODO types, Multiple sets in one file, Workflow states, TODO extensions
3685 @subsection TODO keywords as types
3686 @cindex TODO types
3687 @cindex names as TODO keywords
3688 @cindex types as TODO keywords
3690 The second possibility is to use TODO keywords to indicate different
3691 @emph{types} of action items.  For example, you might want to indicate
3692 that items are for ``work'' or ``home''.  Or, when you work with several
3693 people on a single project, you might want to assign action items
3694 directly to persons, by using their names as TODO keywords.  This would
3695 be set up like this:
3697 @lisp
3698 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
3699 @end lisp
3701 In this case, different keywords do not indicate a sequence, but rather
3702 different types.  So the normal work flow would be to assign a task to a
3703 person, and later to mark it DONE.  Org-mode supports this style by adapting
3704 the workings of the command @kbd{C-c C-t}@footnote{This is also true for the
3705 @kbd{t} command in the timeline and agenda buffers.}.  When used several
3706 times in succession, it will still cycle through all names, in order to first
3707 select the right type for a task.  But when you return to the item after some
3708 time and execute @kbd{C-c C-t} again, it will switch from any name directly
3709 to DONE.  Use prefix arguments or completion to quickly select a specific
3710 name.  You can also review the items of a specific TODO type in a sparse tree
3711 by using a numeric prefix to @kbd{C-c / t}.  For example, to see all things
3712 Lucy has to do, you would use @kbd{C-3 C-c / t}.  To collect Lucy's items
3713 from all agenda files into a single buffer, you would use the numeric prefix
3714 argument as well when creating the global TODO list: @kbd{C-3 C-c a t}.
3716 @node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions
3717 @subsection Multiple keyword sets in one file
3718 @cindex TODO keyword sets
3720 Sometimes you may want to use different sets of TODO keywords in
3721 parallel.  For example, you may want to have the basic
3722 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
3723 separate state indicating that an item has been canceled (so it is not
3724 DONE, but also does not require action).  Your setup would then look
3725 like this:
3727 @lisp
3728 (setq org-todo-keywords
3729       '((sequence "TODO" "|" "DONE")
3730         (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
3731         (sequence "|" "CANCELED")))
3732 @end lisp
3734 The keywords should all be different, this helps Org-mode to keep track
3735 of which subsequence should be used for a given entry.  In this setup,
3736 @kbd{C-c C-t} only operates within a subsequence, so it switches from
3737 @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
3738 (nothing) to @code{REPORT}.  Therefore you need a mechanism to initially
3739 select the correct sequence.  Besides the obvious ways like typing a
3740 keyword or using completion, you may also apply the following commands:
3742 @table @kbd
3743 @kindex C-S-@key{right}
3744 @kindex C-S-@key{left}
3745 @kindex C-u C-u C-c C-t
3746 @item C-u C-u C-c C-t
3747 @itemx C-S-@key{right}
3748 @itemx C-S-@key{left}
3749 These keys jump from one TODO subset to the next.  In the above example,
3750 @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or
3751 @code{DONE} to @code{REPORT}, and any of the words in the second row to
3752 @code{CANCELED}.  Note that the @kbd{C-S-} key binding conflict with
3753 @code{shift-selection-mode} (@pxref{Conflicts}).
3754 @kindex S-@key{right}
3755 @kindex S-@key{left}
3756 @item S-@key{right}
3757 @itemx S-@key{left}
3758 @kbd{S-@key{<left>}} and @kbd{S-@key{<right>}} and walk through @emph{all}
3759 keywords from all sets, so for example @kbd{S-@key{<right>}} would switch
3760 from @code{DONE} to @code{REPORT} in the example above.  See also
3761 @ref{Conflicts}, for a discussion of the interaction with
3762 @code{shift-selection-mode}.
3763 @end table
3765 @node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions
3766 @subsection Fast access to TODO states
3768 If you would like to quickly change an entry to an arbitrary TODO state
3769 instead of cycling through the states, you can set up keys for
3770 single-letter access to the states.  This is done by adding the section
3771 key after each keyword, in parentheses.  For example:
3773 @lisp
3774 (setq org-todo-keywords
3775       '((sequence "TODO(t)" "|" "DONE(d)")
3776         (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
3777         (sequence "|" "CANCELED(c)")))
3778 @end lisp
3780 @vindex org-fast-tag-selection-include-todo
3781 If you then press @kbd{C-c C-t} followed by the selection key, the entry
3782 will be switched to this state.  @kbd{SPC} can be used to remove any TODO
3783 keyword from an entry.@footnote{Check also the variable
3784 @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
3785 state through the tags interface (@pxref{Setting tags}), in case you like to
3786 mingle the two concepts.  Note that this means you need to come up with
3787 unique keys across both sets of keywords.}
3789 @node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions
3790 @subsection Setting up keywords for individual files
3791 @cindex keyword options
3792 @cindex per-file keywords
3793 @cindex #+TODO
3794 @cindex #+TYP_TODO
3795 @cindex #+SEQ_TODO
3797 It can be very useful to use different aspects of the TODO mechanism in
3798 different files.  For file-local settings, you need to add special lines
3799 to the file which set the keywords and interpretation for that file
3800 only.  For example, to set one of the two examples discussed above, you
3801 need one of the following lines, starting in column zero anywhere in the
3802 file:
3804 @example
3805 #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
3806 @end example
3807 @noindent (you may also write @code{#+SEQ_TODO} to be explicit about the
3808 interpretation, but it means the same as @code{#+TODO}), or
3809 @example
3810 #+TYP_TODO: Fred Sara Lucy Mike | DONE
3811 @end example
3813 A setup for using several sets in parallel would be:
3815 @example
3816 #+TODO: TODO | DONE
3817 #+TODO: REPORT BUG KNOWNCAUSE | FIXED
3818 #+TODO: | CANCELED
3819 @end example
3821 @cindex completion, of option keywords
3822 @kindex M-@key{TAB}
3823 @noindent To make sure you are using the correct keyword, type
3824 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
3826 @cindex DONE, final TODO keyword
3827 Remember that the keywords after the vertical bar (or the last keyword
3828 if no bar is there) must always mean that the item is DONE (although you
3829 may use a different word).  After changing one of these lines, use
3830 @kbd{C-c C-c} with the cursor still in the line to make the changes
3831 known to Org-mode@footnote{Org-mode parses these lines only when
3832 Org-mode is activated after visiting a file.  @kbd{C-c C-c} with the
3833 cursor in a line starting with @samp{#+} is simply restarting Org-mode
3834 for the current buffer.}.
3836 @node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions
3837 @subsection Faces for TODO keywords
3838 @cindex faces, for TODO keywords
3840 @vindex org-todo @r{(face)}
3841 @vindex org-done @r{(face)}
3842 @vindex org-todo-keyword-faces
3843 Org-mode highlights TODO keywords with special faces: @code{org-todo}
3844 for keywords indicating that an item still has to be acted upon, and
3845 @code{org-done} for keywords indicating that an item is finished.  If
3846 you are using more than 2 different states, you might want to use
3847 special faces for some of them.  This can be done using the variable
3848 @code{org-todo-keyword-faces}.  For example:
3850 @lisp
3851 @group
3852 (setq org-todo-keyword-faces
3853       '(("TODO" . org-warning) ("STARTED" . "yellow")
3854         ("CANCELED" . (:foreground "blue" :weight bold))))
3855 @end group
3856 @end lisp
3858 While using a list with face properties as shown for CANCELED @emph{should}
3859 work, this does not aways seem to be the case.  If necessary, define a
3860 special face and use that.  A string is interpreted as a color.  The variable
3861 @code{org-faces-easy-properties} determines if that color is interpreted as a
3862 foreground or a background color.
3864 @node TODO dependencies,  , Faces for TODO keywords, TODO extensions
3865 @subsection TODO dependencies
3866 @cindex TODO dependencies
3867 @cindex dependencies, of TODO states
3869 @vindex org-enforce-todo-dependencies
3870 @cindex property, ORDERED
3871 The structure of Org files (hierarchy and lists) makes it easy to define TODO
3872 dependencies.  Usually, a parent TODO task should not be marked DONE until
3873 all subtasks (defined as children tasks) are marked as DONE.  And sometimes
3874 there is a logical sequence to a number of (sub)tasks, so that one task
3875 cannot be acted upon before all siblings above it are done.  If you customize
3876 the variable @code{org-enforce-todo-dependencies}, Org will block entries
3877 from changing state to DONE while they have children that are not DONE.
3878 Furthermore, if an entry has a property @code{ORDERED}, each of its children
3879 will be blocked until all earlier siblings are marked DONE.  Here is an
3880 example:
3882 @example
3883 * TODO Blocked until (two) is done
3884 ** DONE one
3885 ** TODO two
3887 * Parent
3888   :PROPERTIES:
3889     :ORDERED: t
3890   :END:
3891 ** TODO a
3892 ** TODO b, needs to wait for (a)
3893 ** TODO c, needs to wait for (a) and (b)
3894 @end example
3896 @table @kbd
3897 @orgcmd{C-c C-x o,org-toggle-ordered-property}
3898 @vindex org-track-ordered-property-with-tag
3899 @cindex property, ORDERED
3900 Toggle the @code{ORDERED} property of the current entry.  A property is used
3901 for this behavior because this should be local to the current entry, not
3902 inherited like a tag.  However, if you would like to @i{track} the value of
3903 this property with a tag for better visibility, customize the variable
3904 @code{org-track-ordered-property-with-tag}.
3905 @orgkey{C-u C-u C-u C-c C-t}
3906 Change TODO state, circumventing any state blocking.
3907 @end table
3909 @vindex org-agenda-dim-blocked-tasks
3910 If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries
3911 that cannot be closed because of such dependencies will be shown in a dimmed
3912 font or even made invisible in agenda views (@pxref{Agenda Views}).
3914 @cindex checkboxes and TODO dependencies
3915 @vindex org-enforce-todo-dependencies
3916 You can also block changes of TODO states by looking at checkboxes
3917 (@pxref{Checkboxes}).  If you set the variable
3918 @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
3919 checkboxes will be blocked from switching to DONE.
3921 If you need more complex dependency structures, for example dependencies
3922 between entries in different trees or files, check out the contributed
3923 module @file{org-depend.el}.
3925 @page
3926 @node Progress logging, Priorities, TODO extensions, TODO Items
3927 @section Progress logging
3928 @cindex progress logging
3929 @cindex logging, of progress
3931 Org-mode can automatically record a timestamp and possibly a note when
3932 you mark a TODO item as DONE, or even each time you change the state of
3933 a TODO item.  This system is highly configurable, settings can be on a
3934 per-keyword basis and can be localized to a file or even a subtree.  For
3935 information on how to clock working time for a task, see @ref{Clocking
3936 work time}.
3938 @menu
3939 * Closing items::               When was this entry marked DONE?
3940 * Tracking TODO state changes::  When did the status change?
3941 * Tracking your habits::        How consistent have you been?
3942 @end menu
3944 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging
3945 @subsection Closing items
3947 The most basic logging is to keep track of @emph{when} a certain TODO
3948 item was finished.  This is achieved with@footnote{The corresponding
3949 in-buffer setting is: @code{#+STARTUP: logdone}}
3951 @lisp
3952 (setq org-log-done 'time)
3953 @end lisp
3955 @noindent
3956 Then each time you turn an entry from a TODO (not-done) state into any
3957 of the DONE states, a line @samp{CLOSED: [timestamp]} will be inserted
3958 just after the headline.  If you turn the entry back into a TODO item
3959 through further state cycling, that line will be removed again.  If you
3960 want to record a note along with the timestamp, use@footnote{The
3961 corresponding in-buffer setting is: @code{#+STARTUP: lognotedone}}
3963 @lisp
3964 (setq org-log-done 'note)
3965 @end lisp
3967 @noindent
3968 You will then be prompted for a note, and that note will be stored below
3969 the entry with a @samp{Closing Note} heading.
3971 In the timeline (@pxref{Timeline}) and in the agenda
3972 (@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key to
3973 display the TODO items with a @samp{CLOSED} timestamp on each day,
3974 giving you an overview of what has been done.
3976 @node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging
3977 @subsection Tracking TODO state changes
3978 @cindex drawer, for state change recording
3980 @vindex org-log-states-order-reversed
3981 @vindex org-log-into-drawer
3982 @cindex property, LOG_INTO_DRAWER
3983 When TODO keywords are used as workflow states (@pxref{Workflow states}), you
3984 might want to keep track of when a state change occurred and maybe take a
3985 note about this change.  You can either record just a timestamp, or a
3986 time-stamped note for a change.  These records will be inserted after the
3987 headline as an itemized list, newest first@footnote{See the variable
3988 @code{org-log-states-order-reversed}}.  When taking a lot of notes, you might
3989 want to get the notes out of the way into a drawer (@pxref{Drawers}).
3990 Customize the variable @code{org-log-into-drawer} to get this
3991 behavior---the recommended drawer for this is called @code{LOGBOOK}.  You can
3992 also overrule the setting of this variable for a subtree by setting a
3993 @code{LOG_INTO_DRAWER} property.
3995 Since it is normally too much to record a note for every state, Org-mode
3996 expects configuration on a per-keyword basis for this.  This is achieved by
3997 adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note)
3998 in parentheses after each keyword.  For example, with the setting
4000 @lisp
4001 (setq org-todo-keywords
4002   '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
4003 @end lisp
4005 @noindent
4006 @vindex org-log-done
4007 you not only define global TODO keywords and fast access keys, but also
4008 request that a time is recorded when the entry is set to
4009 DONE@footnote{It is possible that Org-mode will record two timestamps
4010 when you are using both @code{org-log-done} and state change logging.
4011 However, it will never prompt for two notes---if you have configured
4012 both, the state change recording note will take precedence and cancel
4013 the @samp{Closing Note}.}, and that a note is recorded when switching to
4014 WAIT or CANCELED.  The setting for WAIT is even more special: the
4015 @samp{!} after the slash means that in addition to the note taken when
4016 entering the state, a timestamp should be recorded when @i{leaving} the
4017 WAIT state, if and only if the @i{target} state does not configure
4018 logging for entering it.  So it has no effect when switching from WAIT
4019 to DONE, because DONE is configured to record a timestamp only.  But
4020 when switching from WAIT back to TODO, the @samp{/!} in the WAIT
4021 setting now triggers a timestamp even though TODO has no logging
4022 configured.
4024 You can use the exact same syntax for setting logging preferences local
4025 to a buffer:
4026 @example
4027 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
4028 @end example
4030 @cindex property, LOGGING
4031 In order to define logging settings that are local to a subtree or a
4032 single item, define a LOGGING property in this entry.  Any non-empty
4033 LOGGING property resets all logging settings to nil.  You may then turn
4034 on logging for this specific tree using STARTUP keywords like
4035 @code{lognotedone} or @code{logrepeat}, as well as adding state specific
4036 settings like @code{TODO(!)}.  For example
4038 @example
4039 * TODO Log each state with only a time
4040   :PROPERTIES:
4041   :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
4042   :END:
4043 * TODO Only log when switching to WAIT, and when repeating
4044   :PROPERTIES:
4045   :LOGGING: WAIT(@@) logrepeat
4046   :END:
4047 * TODO No logging at all
4048   :PROPERTIES:
4049   :LOGGING: nil
4050   :END:
4051 @end example
4053 @node Tracking your habits,  , Tracking TODO state changes, Progress logging
4054 @subsection Tracking your habits
4055 @cindex habits
4057 Org has the ability to track the consistency of a special category of TODOs,
4058 called ``habits''.  A habit has the following properties:
4060 @enumerate
4061 @item
4062 You have enabled the @code{habits} module by customizing the variable
4063 @code{org-modules}.
4064 @item
4065 The habit is a TODO item, with a TODO keyword representing an open state.
4066 @item
4067 The property @code{STYLE} is set to the value @code{habit}.
4068 @item
4069 The TODO has a scheduled date, usually with a @code{.+} style repeat
4070 interval.  A @code{++} style may be appropriate for habits with time
4071 constraints, e.g., must be done on weekends, or a @code{+} style for an
4072 unusual habit that can have a backlog, e.g., weekly reports.
4073 @item
4074 The TODO may also have minimum and maximum ranges specified by using the
4075 syntax @samp{.+2d/3d}, which says that you want to do the task at least every
4076 three days, but at most every two days.
4077 @item
4078 You must also have state logging for the @code{DONE} state enabled, in order
4079 for historical data to be represented in the consistency graph.  If it is not
4080 enabled it is not an error, but the consistency graphs will be largely
4081 meaningless.
4082 @end enumerate
4084 To give you an idea of what the above rules look like in action, here's an
4085 actual habit with some history:
4087 @example
4088 ** TODO Shave
4089    SCHEDULED: <2009-10-17 Sat .+2d/4d>
4090    - State "DONE"       from "TODO"       [2009-10-15 Thu]
4091    - State "DONE"       from "TODO"       [2009-10-12 Mon]
4092    - State "DONE"       from "TODO"       [2009-10-10 Sat]
4093    - State "DONE"       from "TODO"       [2009-10-04 Sun]
4094    - State "DONE"       from "TODO"       [2009-10-02 Fri]
4095    - State "DONE"       from "TODO"       [2009-09-29 Tue]
4096    - State "DONE"       from "TODO"       [2009-09-25 Fri]
4097    - State "DONE"       from "TODO"       [2009-09-19 Sat]
4098    - State "DONE"       from "TODO"       [2009-09-16 Wed]
4099    - State "DONE"       from "TODO"       [2009-09-12 Sat]
4100    :PROPERTIES:
4101    :STYLE:    habit
4102    :LAST_REPEAT: [2009-10-19 Mon 00:36]
4103    :END:
4104 @end example
4106 What this habit says is: I want to shave at most every 2 days (given by the
4107 @code{SCHEDULED} date and repeat interval) and at least every 4 days.  If
4108 today is the 15th, then the habit first appears in the agenda on Oct 17,
4109 after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
4110 after four days have elapsed.
4112 What's really useful about habits is that they are displayed along with a
4113 consistency graph, to show how consistent you've been at getting that task
4114 done in the past.  This graph shows every day that the task was done over the
4115 past three weeks, with colors for each day.  The colors used are:
4117 @table @code
4118 @item Blue
4119 If the task wasn't to be done yet on that day.
4120 @item Green
4121 If the task could have been done on that day.
4122 @item Yellow
4123 If the task was going to be overdue the next day.
4124 @item Red
4125 If the task was overdue on that day.
4126 @end table
4128 In addition to coloring each day, the day is also marked with an asterisk if
4129 the task was actually done that day, and an exclamation mark to show where
4130 the current day falls in the graph.
4132 There are several configuration variables that can be used to change the way
4133 habits are displayed in the agenda.
4135 @table @code
4136 @item org-habit-graph-column
4137 The buffer column at which the consistency graph should be drawn.  This will
4138 overwrite any text in that column, so it is a good idea to keep your habits'
4139 titles brief and to the point.
4140 @item org-habit-preceding-days
4141 The amount of history, in days before today, to appear in consistency graphs.
4142 @item org-habit-following-days
4143 The number of days after today that will appear in consistency graphs.
4144 @item org-habit-show-habits-only-for-today
4145 If non-nil, only show habits in today's agenda view.  This is set to true by
4146 default.
4147 @end table
4149 Lastly, pressing @kbd{K} in the agenda buffer will cause habits to
4150 temporarily be disabled and they won't appear at all.  Press @kbd{K} again to
4151 bring them back.  They are also subject to tag filtering, if you have habits
4152 which should only be done in certain contexts, for example.
4154 @node Priorities, Breaking down tasks, Progress logging, TODO Items
4155 @section Priorities
4156 @cindex priorities
4158 If you use Org-mode extensively, you may end up with enough TODO items that
4159 it starts to make sense to prioritize them.  Prioritizing can be done by
4160 placing a @emph{priority cookie} into the headline of a TODO item, like this
4162 @example
4163 *** TODO [#A] Write letter to Sam Fortune
4164 @end example
4166 @noindent
4167 @vindex org-priority-faces
4168 By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and
4169 @samp{C}.  @samp{A} is the highest priority.  An entry without a cookie is
4170 treated just like priority @samp{B}.  Priorities make a difference only for
4171 sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
4172 have no inherent meaning to Org-mode.  The cookies can be highlighted with
4173 special faces by customizing the variable @code{org-priority-faces}.
4175 Priorities can be attached to any outline node; they do not need to be TODO
4176 items.
4178 @table @kbd
4179 @item @kbd{C-c ,}
4180 @kindex @kbd{C-c ,}
4181 @findex org-priority
4182 Set the priority of the current headline (@command{org-priority}).  The
4183 command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
4184 When you press @key{SPC} instead, the priority cookie is removed from the
4185 headline.  The priorities can also be changed ``remotely'' from the timeline
4186 and agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
4188 @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
4189 @vindex org-priority-start-cycle-with-default
4190 Increase/decrease priority of current headline@footnote{See also the option
4191 @code{org-priority-start-cycle-with-default}.}.  Note that these keys are
4192 also used to modify timestamps (@pxref{Creating timestamps}).  See also
4193 @ref{Conflicts}, for a discussion of the interaction with
4194 @code{shift-selection-mode}.
4195 @end table
4197 @vindex org-highest-priority
4198 @vindex org-lowest-priority
4199 @vindex org-default-priority
4200 You can change the range of allowed priorities by setting the variables
4201 @code{org-highest-priority}, @code{org-lowest-priority}, and
4202 @code{org-default-priority}.  For an individual buffer, you may set
4203 these values (highest, lowest, default) like this (please make sure that
4204 the highest priority is earlier in the alphabet than the lowest
4205 priority):
4207 @cindex #+PRIORITIES
4208 @example
4209 #+PRIORITIES: A C B
4210 @end example
4212 @node Breaking down tasks, Checkboxes, Priorities, TODO Items
4213 @section Breaking tasks down into subtasks
4214 @cindex tasks, breaking down
4215 @cindex statistics, for TODO items
4217 @vindex org-agenda-todo-list-sublevels
4218 It is often advisable to break down large tasks into smaller, manageable
4219 subtasks.  You can do this by creating an outline tree below a TODO item,
4220 with detailed subtasks on the tree@footnote{To keep subtasks out of the
4221 global TODO list, see the @code{org-agenda-todo-list-sublevels}.}.  To keep
4222 the overview over the fraction of subtasks that are already completed, insert
4223 either @samp{[/]} or @samp{[%]} anywhere in the headline.  These cookies will
4224 be updated each time the TODO status of a child changes, or when pressing
4225 @kbd{C-c C-c} on the cookie.  For example:
4227 @example
4228 * Organize Party [33%]
4229 ** TODO Call people [1/2]
4230 *** TODO Peter
4231 *** DONE Sarah
4232 ** TODO Buy food
4233 ** DONE Talk to neighbor
4234 @end example
4236 @cindex property, COOKIE_DATA
4237 If a heading has both checkboxes and TODO children below it, the meaning of
4238 the statistics cookie become ambiguous.  Set the property
4239 @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
4240 this issue.
4242 @vindex org-hierarchical-todo-statistics
4243 If you would like to have the statistics cookie count any TODO entries in the
4244 subtree (not just direct children), configure the variable
4245 @code{org-hierarchical-todo-statistics}.  To do this for a single subtree,
4246 include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
4247 property.
4249 @example
4250 * Parent capturing statistics [2/20]
4251   :PROPERTIES:
4252   :COOKIE_DATA: todo recursive
4253   :END:
4254 @end example
4256 If you would like a TODO entry to automatically change to DONE
4257 when all children are done, you can use the following setup:
4259 @example
4260 (defun org-summary-todo (n-done n-not-done)
4261   "Switch entry to DONE when all subentries are done, to TODO otherwise."
4262   (let (org-log-done org-log-states)   ; turn off logging
4263     (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
4265 (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
4266 @end example
4269 Another possibility is the use of checkboxes to identify (a hierarchy of) a
4270 large number of subtasks (@pxref{Checkboxes}).
4273 @node Checkboxes,  , Breaking down tasks, TODO Items
4274 @section Checkboxes
4275 @cindex checkboxes
4277 @vindex org-list-automatic-rules
4278 Every item in a plain list@footnote{With the exception of description
4279 lists.  But you can allow it by modifying @code{org-list-automatic-rules}
4280 accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
4281 it with the string @samp{[ ]}.  This feature is similar to TODO items
4282 (@pxref{TODO Items}), but is more lightweight.  Checkboxes are not included
4283 into the global TODO list, so they are often great to split a task into a
4284 number of simple steps.  Or you can use them in a shopping list.  To toggle a
4285 checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
4286 @file{org-mouse.el}).
4288 Here is an example of a checkbox list.
4290 @example
4291 * TODO Organize party [2/4]
4292   - [-] call people [1/3]
4293     - [ ] Peter
4294     - [X] Sarah
4295     - [ ] Sam
4296   - [X] order food
4297   - [ ] think about what music to play
4298   - [X] talk to the neighbors
4299 @end example
4301 Checkboxes work hierarchically, so if a checkbox item has children that
4302 are checkboxes, toggling one of the children checkboxes will make the
4303 parent checkbox reflect if none, some, or all of the children are
4304 checked.
4306 @cindex statistics, for checkboxes
4307 @cindex checkbox statistics
4308 @cindex property, COOKIE_DATA
4309 @vindex org-hierarchical-checkbox-statistics
4310 The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
4311 indicating how many checkboxes present in this entry have been checked off,
4312 and the total number of checkboxes present.  This can give you an idea on how
4313 many checkboxes remain, even without opening a folded entry.  The cookies can
4314 be placed into a headline or into (the first line of) a plain list item.
4315 Each cookie covers checkboxes of direct children structurally below the
4316 headline/item on which the cookie appears@footnote{Set the variable
4317 @code{org-hierarchical-checkbox-statistics} if you want such cookies to
4318 count all checkboxes below the cookie, not just those belonging to direct
4319 children.}.  You have to insert the cookie yourself by typing either
4320 @samp{[/]} or @samp{[%]}.  With @samp{[/]} you get an @samp{n out of m}
4321 result, as in the examples above.  With @samp{[%]} you get information about
4322 the percentage of checkboxes checked (in the above example, this would be
4323 @samp{[50%]} and @samp{[33%]}, respectively).  In a headline, a cookie can
4324 count either checkboxes below the heading or TODO states of children, and it
4325 will display whatever was changed last.  Set the property @code{COOKIE_DATA}
4326 to either @samp{checkbox} or @samp{todo} to resolve this issue.
4328 @cindex blocking, of checkboxes
4329 @cindex checkbox blocking
4330 @cindex property, ORDERED
4331 If the current outline node has an @code{ORDERED} property, checkboxes must
4332 be checked off in sequence, and an error will be thrown if you try to check
4333 off a box while there are unchecked boxes above it.
4335 @noindent The following commands work with checkboxes:
4337 @table @kbd
4338 @orgcmd{C-c C-c,org-toggle-checkbox}
4339 Toggle checkbox status or (with prefix arg) checkbox presence at point.  With
4340 double prefix argument, set it to @samp{[-]}, which is considered to be an
4341 intermediate state.
4342 @orgcmd{C-c C-x C-b,org-toggle-checkbox}
4343 Toggle checkbox status or (with prefix arg) checkbox presence at point.  With
4344 double prefix argument, set it to @samp{[-]}, which is considered to be an
4345 intermediate state.
4346 @itemize @minus
4347 @item
4348 If there is an active region, toggle the first checkbox in the region
4349 and set all remaining boxes to the same status as the first.  With a prefix
4350 arg, add or remove the checkbox for all items in the region.
4351 @item
4352 If the cursor is in a headline, toggle checkboxes in the region between
4353 this headline and the next (so @emph{not} the entire subtree).
4354 @item
4355 If there is no active region, just toggle the checkbox at point.
4356 @end itemize
4357 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
4358 Insert a new item with a checkbox.  This works only if the cursor is already
4359 in a plain list item (@pxref{Plain lists}).
4360 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4361 @vindex org-track-ordered-property-with-tag
4362 @cindex property, ORDERED
4363 Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
4364 be checked off in sequence.  A property is used for this behavior because
4365 this should be local to the current entry, not inherited like a tag.
4366 However, if you would like to @i{track} the value of this property with a tag
4367 for better visibility, customize the variable
4368 @code{org-track-ordered-property-with-tag}.
4369 @orgcmd{C-c #,org-update-statistics-cookies}
4370 Update the statistics cookie in the current outline entry.  When called with
4371 a @kbd{C-u} prefix, update the entire file.  Checkbox statistic cookies are
4372 updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
4373 new ones with @kbd{M-S-@key{RET}}.  TODO statistics cookies update when
4374 changing TODO states.  If you delete boxes/entries or add/change them by
4375 hand, use this command to get things back into sync.
4376 @end table
4378 @node Tags, Properties and Columns, TODO Items, Top
4379 @chapter Tags
4380 @cindex tags
4381 @cindex headline tagging
4382 @cindex matching, tags
4383 @cindex sparse tree, tag based
4385 An excellent way to implement labels and contexts for cross-correlating
4386 information is to assign @i{tags} to headlines.  Org-mode has extensive
4387 support for tags.
4389 @vindex org-tag-faces
4390 Every headline can contain a list of tags; they occur at the end of the
4391 headline.  Tags are normal words containing letters, numbers, @samp{_}, and
4392 @samp{@@}.  Tags must be preceded and followed by a single colon, e.g.,
4393 @samp{:work:}.  Several tags can be specified, as in @samp{:work:urgent:}.
4394 Tags will by default be in bold face with the same color as the headline.
4395 You may specify special faces for specific tags using the variable
4396 @code{org-tag-faces}, in much the same way as you can for TODO keywords
4397 (@pxref{Faces for TODO keywords}).
4399 @menu
4400 * Tag inheritance::             Tags use the tree structure of the outline
4401 * Setting tags::                How to assign tags to a headline
4402 * Tag searches::                Searching for combinations of tags
4403 @end menu
4405 @node Tag inheritance, Setting tags, Tags, Tags
4406 @section Tag inheritance
4407 @cindex tag inheritance
4408 @cindex inheritance, of tags
4409 @cindex sublevels, inclusion into tags match
4411 @i{Tags} make use of the hierarchical structure of outline trees.  If a
4412 heading has a certain tag, all subheadings will inherit the tag as
4413 well.  For example, in the list
4415 @example
4416 * Meeting with the French group      :work:
4417 ** Summary by Frank                  :boss:notes:
4418 *** TODO Prepare slides for him      :action:
4419 @end example
4421 @noindent
4422 the final heading will have the tags @samp{:work:}, @samp{:boss:},
4423 @samp{:notes:}, and @samp{:action:} even though the final heading is not
4424 explicitly marked with those tags.  You can also set tags that all entries in
4425 a file should inherit just as if these tags were defined in a hypothetical
4426 level zero that surrounds the entire file.  Use a line like this@footnote{As
4427 with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
4428 changes in the line.}:
4430 @cindex #+FILETAGS
4431 @example
4432 #+FILETAGS: :Peter:Boss:Secret:
4433 @end example
4435 @noindent
4436 @vindex org-use-tag-inheritance
4437 @vindex org-tags-exclude-from-inheritance
4438 To limit tag inheritance to specific tags, or to turn it off entirely, use
4439 the variables @code{org-use-tag-inheritance} and
4440 @code{org-tags-exclude-from-inheritance}.
4442 @vindex org-tags-match-list-sublevels
4443 When a headline matches during a tags search while tag inheritance is turned
4444 on, all the sublevels in the same tree will (for a simple match form) match
4445 as well@footnote{This is only true if the search does not involve more
4446 complex tests including properties (@pxref{Property searches}).}.  The list
4447 of matches may then become very long.  If you only want to see the first tags
4448 match in a subtree, configure the variable
4449 @code{org-tags-match-list-sublevels} (not recommended).
4451 @node Setting tags, Tag searches, Tag inheritance, Tags
4452 @section Setting tags
4453 @cindex setting tags
4454 @cindex tags, setting
4456 @kindex M-@key{TAB}
4457 Tags can simply be typed into the buffer at the end of a headline.
4458 After a colon, @kbd{M-@key{TAB}} offers completion on tags.  There is
4459 also a special command for inserting tags:
4461 @table @kbd
4462 @orgcmd{C-c C-q,org-set-tags-command}
4463 @cindex completion, of tags
4464 @vindex org-tags-column
4465 Enter new tags for the current headline.  Org-mode will either offer
4466 completion or a special single-key interface for setting tags, see
4467 below.  After pressing @key{RET}, the tags will be inserted and aligned
4468 to @code{org-tags-column}.  When called with a @kbd{C-u} prefix, all
4469 tags in the current buffer will be aligned to that column, just to make
4470 things look nice.  TAGS are automatically realigned after promotion,
4471 demotion, and TODO state changes (@pxref{TODO basics}).
4472 @orgcmd{C-c C-c,org-set-tags-command}
4473 When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
4474 @end table
4476 @vindex org-tag-alist
4477 Org supports tag insertion based on a @emph{list of tags}.  By
4478 default this list is constructed dynamically, containing all tags
4479 currently used in the buffer.  You may also globally specify a hard list
4480 of tags with the variable @code{org-tag-alist}.  Finally you can set
4481 the default tags for a given file with lines like
4483 @cindex #+TAGS
4484 @example
4485 #+TAGS: @@work @@home @@tennisclub
4486 #+TAGS: laptop car pc sailboat
4487 @end example
4489 If you have globally defined your preferred set of tags using the
4490 variable @code{org-tag-alist}, but would like to use a dynamic tag list
4491 in a specific file, add an empty TAGS option line to that file:
4493 @example
4494 #+TAGS:
4495 @end example
4497 @vindex org-tag-persistent-alist
4498 If you have a preferred set of tags that you would like to use in every file,
4499 in addition to those defined on a per-file basis by TAGS option lines, then
4500 you may specify a list of tags with the variable
4501 @code{org-tag-persistent-alist}.  You may turn this off on a per-file basis
4502 by adding a STARTUP option line to that file:
4504 @example
4505 #+STARTUP: noptag
4506 @end example
4508 By default Org-mode uses the standard minibuffer completion facilities for
4509 entering tags.  However, it also implements another, quicker, tag selection
4510 method called @emph{fast tag selection}.  This allows you to select and
4511 deselect tags with just a single key press.  For this to work well you should
4512 assign unique letters to most of your commonly used tags.  You can do this
4513 globally by configuring the variable @code{org-tag-alist} in your
4514 @file{.emacs} file.  For example, you may find the need to tag many items in
4515 different files with @samp{:@@home:}.  In this case you can set something
4516 like:
4518 @lisp
4519 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
4520 @end lisp
4522 @noindent If the tag is only relevant to the file you are working on, then you
4523 can instead set the TAGS option line as:
4525 @example
4526 #+TAGS: @@work(w)  @@home(h)  @@tennisclub(t)  laptop(l)  pc(p)
4527 @end example
4529 @noindent The tags interface will show the available tags in a splash
4530 window.  If you want to start a new line after a specific tag, insert
4531 @samp{\n} into the tag list
4533 @example
4534 #+TAGS: @@work(w)  @@home(h)  @@tennisclub(t) \n laptop(l)  pc(p)
4535 @end example
4537 @noindent or write them in two lines:
4539 @example
4540 #+TAGS: @@work(w)  @@home(h)  @@tennisclub(t)
4541 #+TAGS: laptop(l)  pc(p)
4542 @end example
4544 @noindent
4545 You can also group together tags that are mutually exclusive by using
4546 braces, as in:
4548 @example
4549 #+TAGS: @{ @@work(w)  @@home(h)  @@tennisclub(t) @}  laptop(l)  pc(p)
4550 @end example
4552 @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
4553 and @samp{@@tennisclub} should be selected.  Multiple such groups are allowed.
4555 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
4556 these lines to activate any changes.
4558 @noindent
4559 To set these mutually exclusive groups in the variable @code{org-tags-alist},
4560 you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
4561 of the braces.  Similarly, you can use @code{:newline} to indicate a line
4562 break.  The previous example would be set globally by the following
4563 configuration:
4565 @lisp
4566 (setq org-tag-alist '((:startgroup . nil)
4567                       ("@@work" . ?w) ("@@home" . ?h)
4568                       ("@@tennisclub" . ?t)
4569                       (:endgroup . nil)
4570                       ("laptop" . ?l) ("pc" . ?p)))
4571 @end lisp
4573 If at least one tag has a selection key then pressing @kbd{C-c C-c} will
4574 automatically present you with a special interface, listing inherited tags,
4575 the tags of the current headline, and a list of all valid tags with
4576 corresponding keys@footnote{Keys will automatically be assigned to tags which
4577 have no configured keys.}.  In this interface, you can use the following
4578 keys:
4580 @table @kbd
4581 @item a-z...
4582 Pressing keys assigned to tags will add or remove them from the list of
4583 tags in the current line.  Selecting a tag in a group of mutually
4584 exclusive tags will turn off any other tags from that group.
4585 @kindex @key{TAB}
4586 @item @key{TAB}
4587 Enter a tag in the minibuffer, even if the tag is not in the predefined
4588 list.  You will be able to complete on all tags present in the buffer.
4589 You can also add several tags: just separate them with a comma.
4591 @kindex @key{SPC}
4592 @item @key{SPC}
4593 Clear all tags for this line.
4594 @kindex @key{RET}
4595 @item @key{RET}
4596 Accept the modified set.
4597 @item C-g
4598 Abort without installing changes.
4599 @item q
4600 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
4601 @item !
4602 Turn off groups of mutually exclusive tags.  Use this to (as an
4603 exception) assign several tags from such a group.
4604 @item C-c
4605 Toggle auto-exit after the next change (see below).
4606 If you are using expert mode, the first @kbd{C-c} will display the
4607 selection window.
4608 @end table
4610 @noindent
4611 This method lets you assign tags to a headline with very few keys.  With
4612 the above setup, you could clear the current tags and set @samp{@@home},
4613 @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
4614 C-c @key{SPC} h l p @key{RET}}.  Switching from @samp{@@home} to
4615 @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
4616 alternatively with @kbd{C-c C-c C-c w}.  Adding the non-predefined tag
4617 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
4618 @key{RET} @key{RET}}.
4620 @vindex org-fast-tag-selection-single-key
4621 If you find that most of the time you need only a single key press to
4622 modify your list of tags, set the variable
4623 @code{org-fast-tag-selection-single-key}.  Then you no longer have to
4624 press @key{RET} to exit fast tag selection---it will immediately exit
4625 after the first change.  If you then occasionally need more keys, press
4626 @kbd{C-c} to turn off auto-exit for the current tag selection process
4627 (in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c
4628 C-c}).  If you set the variable to the value @code{expert}, the special
4629 window is not even shown for single-key tag selection, it comes up only
4630 when you press an extra @kbd{C-c}.
4632 @node Tag searches,  , Setting tags, Tags
4633 @section Tag searches
4634 @cindex tag searches
4635 @cindex searching for tags
4637 Once a system of tags has been set up, it can be used to collect related
4638 information into special lists.
4640 @table @kbd
4641 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
4642 Create a sparse tree with all headlines matching a tags search.  With a
4643 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
4644 @orgcmd{C-c a m,org-tags-view}
4645 Create a global list of tag matches from all agenda files.
4646 @xref{Matching tags and properties}.
4647 @orgcmd{C-c a M,org-tags-view}
4648 @vindex org-tags-match-list-sublevels
4649 Create a global list of tag matches from all agenda files, but check
4650 only TODO items and force checking subitems (see variable
4651 @code{org-tags-match-list-sublevels}).
4652 @end table
4654 These commands all prompt for a match string which allows basic Boolean logic
4655 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
4656 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
4657 which are tagged, like @samp{Kathy} or @samp{Sally}.  The full syntax of the search
4658 string is rich and allows also matching against TODO keywords, entry levels
4659 and properties.  For a complete description with many examples, see
4660 @ref{Matching tags and properties}.
4663 @node Properties and Columns, Dates and Times, Tags, Top
4664 @chapter Properties and columns
4665 @cindex properties
4667 Properties are a set of key-value pairs associated with an entry.  There
4668 are two main applications for properties in Org-mode.  First, properties
4669 are like tags, but with a value.  Second, you can use properties to
4670 implement (very basic) database capabilities in an Org buffer.  For
4671 an example of the first application, imagine maintaining a file where
4672 you document bugs and plan releases for a piece of software.  Instead of
4673 using tags like @code{:release_1:}, @code{:release_2:}, one can use a
4674 property, say @code{:Release:}, that in different subtrees has different
4675 values, such as @code{1.0} or @code{2.0}.  For an example of the second
4676 application of properties, imagine keeping track of your music CDs,
4677 where properties could be things such as the album, artist, date of
4678 release, number of tracks, and so on.
4680 Properties can be conveniently edited and viewed in column view
4681 (@pxref{Column view}).
4683 @menu
4684 * Property syntax::             How properties are spelled out
4685 * Special properties::          Access to other Org-mode features
4686 * Property searches::           Matching property values
4687 * Property inheritance::        Passing values down the tree
4688 * Column view::                 Tabular viewing and editing
4689 * Property API::                Properties for Lisp programmers
4690 @end menu
4692 @node Property syntax, Special properties, Properties and Columns, Properties and Columns
4693 @section Property syntax
4694 @cindex property syntax
4695 @cindex drawer, for properties
4697 Properties are key-value pairs.  They need to be inserted into a special
4698 drawer (@pxref{Drawers}) with the name @code{PROPERTIES}.  Each property
4699 is specified on a single line, with the key (surrounded by colons)
4700 first, and the value after it.  Here is an example:
4702 @example
4703 * CD collection
4704 ** Classic
4705 *** Goldberg Variations
4706     :PROPERTIES:
4707     :Title:     Goldberg Variations
4708     :Composer:  J.S. Bach
4709     :Artist:    Glen Gould
4710     :Publisher: Deutsche Grammophon
4711     :NDisks:    1
4712     :END:
4713 @end example
4715 You may define the allowed values for a particular property @samp{:Xyz:}
4716 by setting a property @samp{:Xyz_ALL:}.  This special property is
4717 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
4718 the entire tree.  When allowed values are defined, setting the
4719 corresponding property becomes easier and is less prone to typing
4720 errors.  For the example with the CD collection, we can predefine
4721 publishers and the number of disks in a box like this:
4723 @example
4724 * CD collection
4725   :PROPERTIES:
4726   :NDisks_ALL:  1 2 3 4
4727   :Publisher_ALL: "Deutsche Grammophon" Philips EMI
4728   :END:
4729 @end example
4731 If you want to set properties that can be inherited by any entry in a
4732 file, use a line like
4733 @cindex property, _ALL
4734 @cindex #+PROPERTY
4735 @example
4736 #+PROPERTY: NDisks_ALL 1 2 3 4
4737 @end example
4739 @vindex org-global-properties
4740 Property values set with the global variable
4741 @code{org-global-properties} can be inherited by all entries in all
4742 Org files.
4744 @noindent
4745 The following commands help to work with properties:
4747 @table @kbd
4748 @orgcmd{M-@key{TAB},pcomplete}
4749 After an initial colon in a line, complete property keys.  All keys used
4750 in the current file will be offered as possible completions.
4751 @orgcmd{C-c C-x p,org-set-property}
4752 Set a property.  This prompts for a property name and a value.  If
4753 necessary, the property drawer is created as well.
4754 @item M-x org-insert-property-drawer
4755 @findex org-insert-property-drawer
4756 Insert a property drawer into the current entry.  The drawer will be
4757 inserted early in the entry, but after the lines with planning
4758 information like deadlines.
4759 @orgcmd{C-c C-c,org-property-action}
4760 With the cursor in a property drawer, this executes property commands.
4761 @orgcmd{C-c C-c s,org-set-property}
4762 Set a property in the current entry.  Both the property and the value
4763 can be inserted using completion.
4764 @orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
4765 Switch property at point to the next/previous allowed value.
4766 @orgcmd{C-c C-c d,org-delete-property}
4767 Remove a property from the current entry.
4768 @orgcmd{C-c C-c D,org-delete-property-globally}
4769 Globally remove a property, from all entries in the current file.
4770 @orgcmd{C-c C-c c,org-compute-property-at-point}
4771 Compute the property at point, using the operator and scope from the
4772 nearest column format definition.
4773 @end table
4775 @node Special properties, Property searches, Property syntax, Properties and Columns
4776 @section Special properties
4777 @cindex properties, special
4779 Special properties provide an alternative access method to Org-mode features,
4780 like the TODO state or the priority of an entry, discussed in the previous
4781 chapters.  This interface exists so that you can include these states in a
4782 column view (@pxref{Column view}), or to use them in queries.  The following
4783 property names are special and (except for @code{:CATEGORY:}) should not be
4784 used as keys in the properties drawer:
4786 @cindex property, special, TODO
4787 @cindex property, special, TAGS
4788 @cindex property, special, ALLTAGS
4789 @cindex property, special, CATEGORY
4790 @cindex property, special, PRIORITY
4791 @cindex property, special, DEADLINE
4792 @cindex property, special, SCHEDULED
4793 @cindex property, special, CLOSED
4794 @cindex property, special, TIMESTAMP
4795 @cindex property, special, TIMESTAMP_IA
4796 @cindex property, special, CLOCKSUM
4797 @cindex property, special, BLOCKED
4798 @c guessing that ITEM is needed in this area; also, should this list be sorted?
4799 @cindex property, special, ITEM
4800 @cindex property, special, FILE
4801 @example
4802 TODO         @r{The TODO keyword of the entry.}
4803 TAGS         @r{The tags defined directly in the headline.}
4804 ALLTAGS      @r{All tags, including inherited ones.}
4805 CATEGORY     @r{The category of an entry.}
4806 PRIORITY     @r{The priority of the entry, a string with a single letter.}
4807 DEADLINE     @r{The deadline time string, without the angular brackets.}
4808 SCHEDULED    @r{The scheduling timestamp, without the angular brackets.}
4809 CLOSED       @r{When was this entry closed?}
4810 TIMESTAMP    @r{The first keyword-less timestamp in the entry.}
4811 TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
4812 CLOCKSUM     @r{The sum of CLOCK intervals in the subtree.  @code{org-clock-sum}}
4813              @r{must be run first to compute the values in the current buffer.}
4814 BLOCKED      @r{"t" if task is currently blocked by children or siblings}
4815 ITEM         @r{The content of the entry.}
4816 FILE         @r{The filename the entry is located in.}
4817 @end example
4819 @node Property searches, Property inheritance, Special properties, Properties and Columns
4820 @section Property searches
4821 @cindex properties, searching
4822 @cindex searching, of properties
4824 To create sparse trees and special lists with selection based on properties,
4825 the same commands are used as for tag searches (@pxref{Tag searches}).
4826 @table @kbd
4827 @orgcmdkkc{C-c / m,C-c \,org-match-sparse-tree}
4828 Create a sparse tree with all matching entries.  With a
4829 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
4830 @orgcmd{C-c a m,org-tags-view}
4831 Create a global list of tag/property  matches from all agenda files.
4832 @xref{Matching tags and properties}.
4833 @orgcmd{C-c a M,org-tags-view}
4834 @vindex org-tags-match-list-sublevels
4835 Create a global list of tag matches from all agenda files, but check
4836 only TODO items and force checking of subitems (see variable
4837 @code{org-tags-match-list-sublevels}).
4838 @end table
4840 The syntax for the search string is described in @ref{Matching tags and
4841 properties}.
4843 There is also a special command for creating sparse trees based on a
4844 single property:
4846 @table @kbd
4847 @orgkey{C-c / p}
4848 Create a sparse tree based on the value of a property.  This first
4849 prompts for the name of a property, and then for a value.  A sparse tree
4850 is created with all entries that define this property with the given
4851 value.  If you enclose the value in curly braces, it is interpreted as
4852 a regular expression and matched against the property values.
4853 @end table
4855 @node Property inheritance, Column view, Property searches, Properties and Columns
4856 @section Property Inheritance
4857 @cindex properties, inheritance
4858 @cindex inheritance, of properties
4860 @vindex org-use-property-inheritance
4861 The outline structure of Org-mode documents lends itself to an
4862 inheritance model of properties: if the parent in a tree has a certain
4863 property, the children can inherit this property.  Org-mode does not
4864 turn this on by default, because it can slow down property searches
4865 significantly and is often not needed.  However, if you find inheritance
4866 useful, you can turn it on by setting the variable
4867 @code{org-use-property-inheritance}.  It may be set to @code{t} to make
4868 all properties inherited from the parent, to a list of properties
4869 that should be inherited, or to a regular expression that matches
4870 inherited properties.  If a property has the value @samp{nil}, this is
4871 interpreted as an explicit undefine of the property, so that inheritance
4872 search will stop at this value and return @code{nil}.
4874 Org-mode has a few properties for which inheritance is hard-coded, at
4875 least for the special applications for which they are used:
4877 @cindex property, COLUMNS
4878 @table @code
4879 @item COLUMNS
4880 The @code{:COLUMNS:} property defines the format of column view
4881 (@pxref{Column view}).  It is inherited in the sense that the level
4882 where a @code{:COLUMNS:} property is defined is used as the starting
4883 point for a column view table, independently of the location in the
4884 subtree from where columns view is turned on.
4885 @item CATEGORY
4886 @cindex property, CATEGORY
4887 For agenda view, a category set through a @code{:CATEGORY:} property
4888 applies to the entire subtree.
4889 @item ARCHIVE
4890 @cindex property, ARCHIVE
4891 For archiving, the @code{:ARCHIVE:} property may define the archive
4892 location for the entire subtree (@pxref{Moving subtrees}).
4893 @item LOGGING
4894 @cindex property, LOGGING
4895 The LOGGING property may define logging settings for an entry or a
4896 subtree (@pxref{Tracking TODO state changes}).
4897 @end table
4899 @node Column view, Property API, Property inheritance, Properties and Columns
4900 @section Column view
4902 A great way to view and edit properties in an outline tree is
4903 @emph{column view}.  In column view, each outline node is turned into a
4904 table row.  Columns in this table provide access to properties of the
4905 entries.  Org-mode implements columns by overlaying a tabular structure
4906 over the headline of each item.  While the headlines have been turned
4907 into a table row, you can still change the visibility of the outline
4908 tree.  For example, you get a compact table by switching to CONTENTS
4909 view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
4910 is active), but you can still open, read, and edit the entry below each
4911 headline.  Or, you can switch to column view after executing a sparse
4912 tree command and in this way get a table only for the selected items.
4913 Column view also works in agenda buffers (@pxref{Agenda Views}) where
4914 queries have collected selected items, possibly from a number of files.
4916 @menu
4917 * Defining columns::            The COLUMNS format property
4918 * Using column view::           How to create and use column view
4919 * Capturing column view::       A dynamic block for column view
4920 @end menu
4922 @node Defining columns, Using column view, Column view, Column view
4923 @subsection Defining columns
4924 @cindex column view, for properties
4925 @cindex properties, column view
4927 Setting up a column view first requires defining the columns.  This is
4928 done by defining a column format line.
4930 @menu
4931 * Scope of column definitions::  Where defined, where valid?
4932 * Column attributes::           Appearance and content of a column
4933 @end menu
4935 @node Scope of column definitions, Column attributes, Defining columns, Defining columns
4936 @subsubsection Scope of column definitions
4938 To define a column format for an entire file, use a line like
4940 @cindex #+COLUMNS
4941 @example
4942 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
4943 @end example
4945 To specify a format that only applies to a specific tree, add a
4946 @code{:COLUMNS:} property to the top node of that tree, for example:
4948 @example
4949 ** Top node for columns view
4950    :PROPERTIES:
4951    :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
4952    :END:
4953 @end example
4955 If a @code{:COLUMNS:} property is present in an entry, it defines columns
4956 for the entry itself, and for the entire subtree below it.  Since the
4957 column definition is part of the hierarchical structure of the document,
4958 you can define columns on level 1 that are general enough for all
4959 sublevels, and more specific columns further down, when you edit a
4960 deeper part of the tree.
4962 @node Column attributes,  , Scope of column definitions, Defining columns
4963 @subsubsection Column attributes
4964 A column definition sets the attributes of a column.  The general
4965 definition looks like this:
4967 @example
4968  %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]
4969 @end example
4971 @noindent
4972 Except for the percent sign and the property name, all items are
4973 optional.  The individual parts have the following meaning:
4975 @example
4976 @var{width}           @r{An integer specifying the width of the column in characters.}
4977                 @r{If omitted, the width will be determined automatically.}
4978 @var{property}        @r{The property that should be edited in this column.}
4979                 @r{Special properties representing meta data are allowed here}
4980                 @r{as well (@pxref{Special properties})}
4981 @var{title}           @r{The header text for the column.  If omitted, the property}
4982                 @r{name is used.}
4983 @{@var{summary-type}@}  @r{The summary type.  If specified, the column values for}
4984                 @r{parent nodes are computed from the children.}
4985                 @r{Supported summary types are:}
4986                 @{+@}       @r{Sum numbers in this column.}
4987                 @{+;%.1f@}  @r{Like @samp{+}, but format result with @samp{%.1f}.}
4988                 @{$@}       @r{Currency, short for @samp{+;%.2f}.}
4989                 @{:@}       @r{Sum times, HH:MM, plain numbers are hours.}
4990                 @{X@}       @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
4991                 @{X/@}      @r{Checkbox status, @samp{[n/m]}.}
4992                 @{X%@}      @r{Checkbox status, @samp{[n%]}.}
4993                 @{min@}     @r{Smallest number in column.}
4994                 @{max@}     @r{Largest number.}
4995                 @{mean@}    @r{Arithmetic mean of numbers.}
4996                 @{:min@}    @r{Smallest time value in column.}
4997                 @{:max@}    @r{Largest time value.}
4998                 @{:mean@}   @r{Arithmetic mean of time values.}
4999                 @{@@min@}    @r{Minimum age (in days/hours/mins/seconds).}
5000                 @{@@max@}    @r{Maximum age (in days/hours/mins/seconds).}
5001                 @{@@mean@}   @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
5002                 @{est+@}    @r{Add low-high estimates.}
5003 @end example
5005 @noindent
5006 Be aware that you can only have one summary type for any property you
5007 include.  Subsequent columns referencing the same property will all display the
5008 same summary information.
5010 The @code{est+} summary type requires further explanation.  It is used for
5011 combining estimates, expressed as low-high ranges.  For example, instead
5012 of estimating a particular task will take 5 days, you might estimate it as
5013 5-6 days if you're fairly confident you know how much work is required, or
5014 1-10 days if you don't really know what needs to be done.  Both ranges
5015 average at 5.5 days, but the first represents a more predictable delivery.
5017 When combining a set of such estimates, simply adding the lows and highs
5018 produces an unrealistically wide result.  Instead, @code{est+} adds the
5019 statistical mean and variance of the sub-tasks, generating a final estimate
5020 from the sum.  For example, suppose you had ten tasks, each of which was
5021 estimated at 0.5 to 2 days of work.  Straight addition produces an estimate
5022 of 5 to 20 days, representing what to expect if everything goes either
5023 extremely well or extremely poorly.  In contrast, @code{est+} estimates the
5024 full job more realistically, at 10-15 days.
5026 Here is an example for a complete columns definition, along with allowed
5027 values.
5029 @example
5030 :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.}
5031                    %10Time_Estimate@{:@} %CLOCKSUM
5032 :Owner_ALL:    Tammy Mark Karl Lisa Don
5033 :Status_ALL:   "In progress" "Not started yet" "Finished" ""
5034 :Approved_ALL: "[ ]" "[X]"
5035 @end example
5037 @noindent
5038 The first column, @samp{%25ITEM}, means the first 25 characters of the
5039 item itself, i.e.@: of the headline.  You probably always should start the
5040 column definition with the @samp{ITEM} specifier.  The other specifiers
5041 create columns @samp{Owner} with a list of names as allowed values, for
5042 @samp{Status} with four different possible values, and for a checkbox
5043 field @samp{Approved}.  When no width is given after the @samp{%}
5044 character, the column will be exactly as wide as it needs to be in order
5045 to fully display all values.  The @samp{Approved} column does have a
5046 modified title (@samp{Approved?}, with a question mark).  Summaries will
5047 be created for the @samp{Time_Estimate} column by adding time duration
5048 expressions like HH:MM, and for the @samp{Approved} column, by providing
5049 an @samp{[X]} status if all children have been checked.  The
5050 @samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervals
5051 in the subtree.
5053 @node Using column view, Capturing column view, Defining columns, Column view
5054 @subsection Using column view
5056 @table @kbd
5057 @tsubheading{Turning column view on and off}
5058 @orgcmd{C-c C-x C-c,org-columns}
5059 @vindex org-columns-default-format
5060 Turn on column view.  If the cursor is before the first headline in the file,
5061 column view is turned on for the entire file, using the @code{#+COLUMNS}
5062 definition.  If the cursor is somewhere inside the outline, this command
5063 searches the hierarchy, up from point, for a @code{:COLUMNS:} property that
5064 defines a format.  When one is found, the column view table is established
5065 for the tree starting at the entry that contains the @code{:COLUMNS:}
5066 property.  If no such property is found, the format is taken from the
5067 @code{#+COLUMNS} line or from the variable @code{org-columns-default-format},
5068 and column view is established for the current entry and its subtree.
5069 @orgcmd{r,org-columns-redo}
5070 Recreate the column view, to include recent changes made in the buffer.
5071 @orgcmd{g,org-columns-redo}
5072 Same as @kbd{r}.
5073 @orgcmd{q,org-columns-quit}
5074 Exit column view.
5075 @tsubheading{Editing values}
5076 @item @key{left} @key{right} @key{up} @key{down}
5077 Move through the column view from field to field.
5078 @kindex S-@key{left}
5079 @kindex S-@key{right}
5080 @item  S-@key{left}/@key{right}
5081 Switch to the next/previous allowed value of the field.  For this, you
5082 have to have specified allowed values for a property.
5083 @item 1..9,0
5084 Directly select the Nth allowed value, @kbd{0} selects the 10th value.
5085 @orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value}
5086 Same as @kbd{S-@key{left}/@key{right}}
5087 @orgcmd{e,org-columns-edit-value}
5088 Edit the property at point.  For the special properties, this will
5089 invoke the same interface that you normally use to change that
5090 property.  For example, when editing a TAGS property, the tag completion
5091 or fast selection interface will pop up.
5092 @orgcmd{C-c C-c,org-columns-set-tags-or-toggle}
5093 When there is a checkbox at point, toggle it.
5094 @orgcmd{v,org-columns-show-value}
5095 View the full value of this property.  This is useful if the width of
5096 the column is smaller than that of the value.
5097 @orgcmd{a,org-columns-edit-allowed}
5098 Edit the list of allowed values for this property.  If the list is found
5099 in the hierarchy, the modified values is stored there.  If no list is
5100 found, the new value is stored in the first entry that is part of the
5101 current column view.
5102 @tsubheading{Modifying the table structure}
5103 @orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen}
5104 Make the column narrower/wider by one character.
5105 @orgcmd{S-M-@key{right},org-columns-new}
5106 Insert a new column, to the left of the current column.
5107 @orgcmd{S-M-@key{left},org-columns-delete}
5108 Delete the current column.
5109 @end table
5111 @node Capturing column view,  , Using column view, Column view
5112 @subsection Capturing column view
5114 Since column view is just an overlay over a buffer, it cannot be
5115 exported or printed directly.  If you want to capture a column view, use
5116 a @code{columnview} dynamic block (@pxref{Dynamic blocks}).  The frame
5117 of this block looks like this:
5119 @cindex #+BEGIN, columnview
5120 @example
5121 * The column view
5122 #+BEGIN: columnview :hlines 1 :id "label"
5124 #+END:
5125 @end example
5127 @noindent This dynamic block has the following parameters:
5129 @table @code
5130 @item :id
5131 This is the most important parameter.  Column view is a feature that is
5132 often localized to a certain (sub)tree, and the capture block might be
5133 at a different location in the file.  To identify the tree whose view to
5134 capture, you can use 4 values:
5135 @cindex property, ID
5136 @example
5137 local     @r{use the tree in which the capture block is located}
5138 global    @r{make a global view, including all headings in the file}
5139 "file:@var{path-to-file}"
5140           @r{run column view at the top of this file}
5141 "@var{ID}"      @r{call column view in the tree that has an @code{:ID:}}
5142           @r{property with the value @i{label}.  You can use}
5143           @r{@kbd{M-x org-id-copy} to create a globally unique ID for}
5144           @r{the current entry and copy it to the kill-ring.}
5145 @end example
5146 @item :hlines
5147 When @code{t}, insert an hline after every line.  When a number @var{N}, insert
5148 an hline before each headline with level @code{<= @var{N}}.
5149 @item :vlines
5150 When set to @code{t}, force column groups to get vertical lines.
5151 @item :maxlevel
5152 When set to a number, don't capture entries below this level.
5153 @item :skip-empty-rows
5154 When set to @code{t}, skip rows where the only non-empty specifier of the
5155 column view is @code{ITEM}.
5157 @end table
5159 @noindent
5160 The following commands insert or update the dynamic block:
5162 @table @kbd
5163 @orgcmd{C-c C-x i,org-insert-columns-dblock}
5164 Insert a dynamic block capturing a column view.  You will be prompted
5165 for the scope or ID of the view.
5166 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
5167 Update dynamic block at point.  The cursor needs to be in the
5168 @code{#+BEGIN} line of the dynamic block.
5169 @orgcmd{C-u C-c C-x C-u,org-update-all-dblocks}
5170 Update all dynamic blocks (@pxref{Dynamic blocks}).  This is useful if
5171 you have several clock table blocks, column-capturing blocks or other dynamic
5172 blocks in a buffer.
5173 @end table
5175 You can add formulas to the column view table and you may add plotting
5176 instructions in front of the table---these will survive an update of the
5177 block.  If there is a @code{#+TBLFM:} after the table, the table will
5178 actually be recalculated automatically after an update.
5180 An alternative way to capture and process property values into a table is
5181 provided by Eric Schulte's @file{org-collector.el} which is a contributed
5182 package@footnote{Contributed packages are not part of Emacs, but are
5183 distributed with the main distribution of Org (visit
5184 @uref{http://orgmode.org}).}.  It provides a general API to collect
5185 properties from entries in a certain scope, and arbitrary Lisp expressions to
5186 process these values before inserting them into a table or a dynamic block.
5188 @node Property API,  , Column view, Properties and Columns
5189 @section The Property API
5190 @cindex properties, API
5191 @cindex API, for properties
5193 There is a full API for accessing and changing properties.  This API can
5194 be used by Emacs Lisp programs to work with properties and to implement
5195 features based on them.  For more information see @ref{Using the
5196 property API}.
5198 @node Dates and Times, Capture - Refile - Archive, Properties and Columns, Top
5199 @chapter Dates and times
5200 @cindex dates
5201 @cindex times
5202 @cindex timestamp
5203 @cindex date stamp
5205 To assist project planning, TODO items can be labeled with a date and/or
5206 a time.  The specially formatted string carrying the date and time
5207 information is called a @emph{timestamp} in Org-mode.  This may be a
5208 little confusing because timestamp is often used as indicating when
5209 something was created or last changed.  However, in Org-mode this term
5210 is used in a much wider sense.
5212 @menu
5213 * Timestamps::                  Assigning a time to a tree entry
5214 * Creating timestamps::         Commands which insert timestamps
5215 * Deadlines and scheduling::    Planning your work
5216 * Clocking work time::          Tracking how long you spend on a task
5217 * Effort estimates::            Planning work effort in advance
5218 * Relative timer::              Notes with a running timer
5219 * Countdown timer::             Starting a countdown timer for a task
5220 @end menu
5223 @node Timestamps, Creating timestamps, Dates and Times, Dates and Times
5224 @section Timestamps, deadlines, and scheduling
5225 @cindex timestamps
5226 @cindex ranges, time
5227 @cindex date stamps
5228 @cindex deadlines
5229 @cindex scheduling
5231 A timestamp is a specification of a date (possibly with a time or a range of
5232 times) in a special format, either @samp{<2003-09-16 Tue>} or
5233 @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue
5234 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 date/time
5235 format.  To use an alternative format, see @ref{Custom time format}.}.  A
5236 timestamp can appear anywhere in the headline or body of an Org tree entry.
5237 Its presence causes entries to be shown on specific dates in the agenda
5238 (@pxref{Weekly/daily agenda}).  We distinguish:
5240 @table @var
5241 @item Plain timestamp; Event; Appointment
5242 @cindex timestamp
5243 A simple timestamp just assigns a date/time to an item.  This is just
5244 like writing down an appointment or event in a paper agenda.  In the
5245 timeline and agenda displays, the headline of an entry associated with a
5246 plain timestamp will be shown exactly on that date.
5248 @example
5249 * Meet Peter at the movies <2006-11-01 Wed 19:15>
5250 * Discussion on climate change <2006-11-02 Thu 20:00-22:00>
5251 @end example
5253 @item Timestamp with repeater interval
5254 @cindex timestamp, with repeater interval
5255 A timestamp may contain a @emph{repeater interval}, indicating that it
5256 applies not only on the given date, but again and again after a certain
5257 interval of N days (d), weeks (w), months (m), or years (y).  The
5258 following will show up in the agenda every Wednesday:
5260 @example
5261 * Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
5262 @end example
5264 @item Diary-style sexp entries
5265 For more complex date specifications, Org-mode supports using the special
5266 sexp diary entries implemented in the Emacs calendar/diary
5267 package@footnote{When working with the standard diary sexp functions, you
5268 need to be very careful with the order of the arguments.  That order depend
5269 evilly on the variable @code{calendar-date-style} (or, for older Emacs
5270 versions, @code{european-calendar-style}).  For example, to specify a date
5271 December 12, 2005, the call might look like @code{(diary-date 12 1 2005)} or
5272 @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
5273 the settings.  This has been the source of much confusion.  Org-mode users
5274 can resort to special versions of these functions like @code{org-date} or
5275 @code{org-anniversary}.  These work just like the corresponding @code{diary-}
5276 functions, but with stable ISO order of arguments (year, month, day) wherever
5277 applicable, independent of the value of @code{calendar-date-style}.}.  For example
5279 @example
5280 * The nerd meeting on every 2nd Thursday of the month
5281   <%%(org-float t 4 2)>
5282 @end example
5284 @item Time/Date range
5285 @cindex timerange
5286 @cindex date range
5287 Two timestamps connected by @samp{--} denote a range.  The headline
5288 will be shown on the first and last day of the range, and on any dates
5289 that are displayed and fall in the range.  Here is an example:
5291 @example
5292 ** Meeting in Amsterdam
5293    <2004-08-23 Mon>--<2004-08-26 Thu>
5294 @end example
5296 @item Inactive timestamp
5297 @cindex timestamp, inactive
5298 @cindex inactive timestamp
5299 Just like a plain timestamp, but with square brackets instead of
5300 angular ones.  These timestamps are inactive in the sense that they do
5301 @emph{not} trigger an entry to show up in the agenda.
5303 @example
5304 * Gillian comes late for the fifth time [2006-11-01 Wed]
5305 @end example
5307 @end table
5309 @node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times
5310 @section Creating timestamps
5311 @cindex creating timestamps
5312 @cindex timestamps, creating
5314 For Org-mode to recognize timestamps, they need to be in the specific
5315 format.  All commands listed below produce timestamps in the correct
5316 format.
5318 @table @kbd
5319 @orgcmd{C-c .,org-time-stamp}
5320 Prompt for a date and insert a corresponding timestamp.  When the cursor is
5321 at an existing timestamp in the buffer, the command is used to modify this
5322 timestamp instead of inserting a new one.  When this command is used twice in
5323 succession, a time range is inserted.
5325 @orgcmd{C-c !,org-time-stamp-inactive}
5326 Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
5327 an agenda entry.
5329 @kindex C-u C-c .
5330 @kindex C-u C-c !
5331 @item C-u C-c .
5332 @itemx C-u C-c !
5333 @vindex org-time-stamp-rounding-minutes
5334 Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which
5335 contains date and time.  The default time can be rounded to multiples of 5
5336 minutes, see the option @code{org-time-stamp-rounding-minutes}.
5338 @orgcmd{C-c <,org-date-from-calendar}
5339 Insert a timestamp corresponding to the cursor date in the Calendar.
5341 @orgcmd{C-c >,org-goto-calendar}
5342 Access the Emacs calendar for the current date.  If there is a
5343 timestamp in the current line, go to the corresponding date
5344 instead.
5346 @orgcmd{C-c C-o,org-open-at-point}
5347 Access the agenda for the date given by the timestamp or -range at
5348 point (@pxref{Weekly/daily agenda}).
5350 @orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day}
5351 Change date at cursor by one day.  These key bindings conflict with
5352 shift-selection and related modes (@pxref{Conflicts}).
5354 @orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down}
5355 Change the item under the cursor in a timestamp.  The cursor can be on a
5356 year, month, day, hour or minute.  When the timestamp contains a time range
5357 like @samp{15:30-16:30}, modifying the first time will also shift the second,
5358 shifting the time block with constant length.  To change the length, modify
5359 the second time.  Note that if the cursor is in a headline and not at a
5360 timestamp, these same keys modify the priority of an item.
5361 (@pxref{Priorities}).  The key bindings also conflict with shift-selection and
5362 related modes (@pxref{Conflicts}).
5364 @orgcmd{C-c C-y,org-evaluate-time-range}
5365 @cindex evaluate time range
5366 Evaluate a time range by computing the difference between start and end.
5367 With a prefix argument, insert result after the time range (in a table: into
5368 the following column).
5369 @end table
5372 @menu
5373 * The date/time prompt::        How Org-mode helps you entering date and time
5374 * Custom time format::          Making dates look different
5375 @end menu
5377 @node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps
5378 @subsection The date/time prompt
5379 @cindex date, reading in minibuffer
5380 @cindex time, reading in minibuffer
5382 @vindex org-read-date-prefer-future
5383 When Org-mode prompts for a date/time, the default is shown in default
5384 date/time format, and the prompt therefore seems to ask for a specific
5385 format.  But it will in fact accept any string containing some date and/or
5386 time information, and it is really smart about interpreting your input.  You
5387 can, for example, use @kbd{C-y} to paste a (possibly multi-line) string
5388 copied from an email message.  Org-mode will find whatever information is in
5389 there and derive anything you have not specified from the @emph{default date
5390 and time}.  The default is usually the current date and time, but when
5391 modifying an existing timestamp, or when entering the second stamp of a
5392 range, it is taken from the stamp in the buffer.  When filling in
5393 information, Org-mode assumes that most of the time you will want to enter a
5394 date in the future: if you omit the month/year and the given day/month is
5395 @i{before} today, it will assume that you mean a future date@footnote{See the
5396 variable @code{org-read-date-prefer-future}.  You may set that variable to
5397 the symbol @code{time} to even make a time before now shift the date to
5398 tomorrow.}.  If the date has been automatically shifted into the future, the
5399 time prompt will show this with @samp{(=>F).}
5401 For example, let's assume that today is @b{June 13, 2006}.  Here is how
5402 various inputs will be interpreted, the items filled in by Org-mode are
5403 in @b{bold}.
5405 @example
5406 3-2-5         @result{} 2003-02-05
5407 2/5/3         @result{} 2003-02-05
5408 14            @result{} @b{2006}-@b{06}-14
5409 12            @result{} @b{2006}-@b{07}-12
5410 2/5           @result{} @b{2007}-02-05
5411 Fri           @result{} nearest Friday (default date or later)
5412 sep 15        @result{} @b{2006}-09-15
5413 feb 15        @result{} @b{2007}-02-15
5414 sep 12 9      @result{} 2009-09-12
5415 12:45         @result{} @b{2006}-@b{06}-@b{13} 12:45
5416 22 sept 0:34  @result{} @b{2006}-09-22 0:34
5417 w4            @result{} ISO week for of the current year @b{2006}
5418 2012 w4 fri   @result{} Friday of ISO week 4 in 2012
5419 2012-w04-5    @result{} Same as above
5420 @end example
5422 Furthermore you can specify a relative date by giving, as the
5423 @emph{first} thing in the input: a plus/minus sign, a number and a
5424 letter ([dwmy]) to indicate change in days, weeks, months, or years.  With a
5425 single plus or minus, the date is always relative to today.  With a
5426 double plus or minus, it is relative to the default date.  If instead of
5427 a single letter, you use the abbreviation of day name, the date will be
5428 the Nth such day, e.g.@:
5430 @example
5431 +0            @result{} today
5432 .             @result{} today
5433 +4d           @result{} four days from today
5434 +4            @result{} same as above
5435 +2w           @result{} two weeks from today
5436 ++5           @result{} five days from default date
5437 +2tue         @result{} second Tuesday from now.
5438 @end example
5440 @vindex parse-time-months
5441 @vindex parse-time-weekdays
5442 The function understands English month and weekday abbreviations.  If
5443 you want to use unabbreviated names and/or other languages, configure
5444 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
5446 @vindex org-read-date-force-compatible-dates
5447 Not all dates can be represented in a given Emacs implementation.  By default
5448 Org mode forces dates into the compatibility range 1970--2037 which works on
5449 all Emacs implementations.  If you want to use dates outside of this range,
5450 read the docstring of the variable
5451 @code{org-read-date-force-compatible-dates}.
5453 You can specify a time range by giving start and end times or by giving a
5454 start time and a duration (in HH:MM format).  Use one or two dash(es) as the
5455 separator in the former case and use '+' as the separator in the latter
5456 case, e.g.@:
5458 @example
5459 11am-1:15pm    @result{} 11:00-13:15
5460 11am--1:15pm   @result{} same as above
5461 11am+2:15      @result{} same as above
5462 @end example
5464 @cindex calendar, for selecting date
5465 @vindex org-popup-calendar-for-date-prompt
5466 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
5467 you don't need/want the calendar, configure the variable
5468 @code{org-popup-calendar-for-date-prompt}.}.  When you exit the date
5469 prompt, either by clicking on a date in the calendar, or by pressing
5470 @key{RET}, the date selected in the calendar will be combined with the
5471 information entered at the prompt.  You can control the calendar fully
5472 from the minibuffer:
5474 @kindex <
5475 @kindex >
5476 @kindex M-v
5477 @kindex C-v
5478 @kindex mouse-1
5479 @kindex S-@key{right}
5480 @kindex S-@key{left}
5481 @kindex S-@key{down}
5482 @kindex S-@key{up}
5483 @kindex M-S-@key{right}
5484 @kindex M-S-@key{left}
5485 @kindex @key{RET}
5486 @example
5487 @key{RET}           @r{Choose date at cursor in calendar.}
5488 mouse-1        @r{Select date by clicking on it.}
5489 S-@key{right}/@key{left}     @r{One day forward/backward.}
5490 S-@key{down}/@key{up}     @r{One week forward/backward.}
5491 M-S-@key{right}/@key{left}   @r{One month forward/backward.}
5492 > / <          @r{Scroll calendar forward/backward by one month.}
5493 M-v / C-v      @r{Scroll calendar forward/backward by 3 months.}
5494 @end example
5496 @vindex org-read-date-display-live
5497 The actions of the date/time prompt may seem complex, but I assure you they
5498 will grow on you, and you will start getting annoyed by pretty much any other
5499 way of entering a date/time out there.  To help you understand what is going
5500 on, the current interpretation of your input will be displayed live in the
5501 minibuffer@footnote{If you find this distracting, turn the display of with
5502 @code{org-read-date-display-live}.}.
5504 @node Custom time format,  , The date/time prompt, Creating timestamps
5505 @subsection Custom time format
5506 @cindex custom date/time format
5507 @cindex time format, custom
5508 @cindex date format, custom
5510 @vindex org-display-custom-times
5511 @vindex org-time-stamp-custom-formats
5512 Org-mode uses the standard ISO notation for dates and times as it is
5513 defined in ISO 8601.  If you cannot get used to this and require another
5514 representation of date and time to keep you happy, you can get it by
5515 customizing the variables @code{org-display-custom-times} and
5516 @code{org-time-stamp-custom-formats}.
5518 @table @kbd
5519 @orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays}
5520 Toggle the display of custom formats for dates and times.
5521 @end table
5523 @noindent
5524 Org-mode needs the default format for scanning, so the custom date/time
5525 format does not @emph{replace} the default format---instead it is put
5526 @emph{over} the default format using text properties.  This has the
5527 following consequences:
5528 @itemize @bullet
5529 @item
5530 You cannot place the cursor onto a timestamp anymore, only before or
5531 after.
5532 @item
5533 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
5534 each component of a timestamp.  If the cursor is at the beginning of
5535 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
5536 just like @kbd{S-@key{left}/@key{right}}.  At the end of the stamp, the
5537 time will be changed by one minute.
5538 @item
5539 If the timestamp contains a range of clock times or a repeater, these
5540 will not be overlaid, but remain in the buffer as they were.
5541 @item
5542 When you delete a timestamp character-by-character, it will only
5543 disappear from the buffer after @emph{all} (invisible) characters
5544 belonging to the ISO timestamp have been removed.
5545 @item
5546 If the custom timestamp format is longer than the default and you are
5547 using dates in tables, table alignment will be messed up.  If the custom
5548 format is shorter, things do work as expected.
5549 @end itemize
5552 @node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times
5553 @section Deadlines and scheduling
5555 A timestamp may be preceded by special keywords to facilitate planning:
5557 @table @var
5558 @item DEADLINE
5559 @cindex DEADLINE keyword
5561 Meaning: the task (most likely a TODO item, though not necessarily) is supposed
5562 to be finished on that date.
5564 @vindex org-deadline-warning-days
5565 On the deadline date, the task will be listed in the agenda.  In
5566 addition, the agenda for @emph{today} will carry a warning about the
5567 approaching or missed deadline, starting
5568 @code{org-deadline-warning-days} before the due date, and continuing
5569 until the entry is marked DONE.  An example:
5571 @example
5572 *** TODO write article about the Earth for the Guide
5573     The editor in charge is [[bbdb:Ford Prefect]]
5574     DEADLINE: <2004-02-29 Sun>
5575 @end example
5577 You can specify a different lead time for warnings for a specific
5578 deadlines using the following syntax.  Here is an example with a warning
5579 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}.
5581 @item SCHEDULED
5582 @cindex SCHEDULED keyword
5584 Meaning: you are planning to start working on that task on the given
5585 date.
5587 @vindex org-agenda-skip-scheduled-if-done
5588 The headline will be listed under the given date@footnote{It will still
5589 be listed on that date after it has been marked DONE.  If you don't like
5590 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}.  In
5591 addition, a reminder that the scheduled date has passed will be present
5592 in the compilation for @emph{today}, until the entry is marked DONE, i.e.@:
5593 the task will automatically be forwarded until completed.
5595 @example
5596 *** TODO Call Trillian for a date on New Years Eve.
5597     SCHEDULED: <2004-12-25 Sat>
5598 @end example
5600 @noindent
5601 @b{Important:} Scheduling an item in Org-mode should @i{not} be
5602 understood in the same way that we understand @i{scheduling a meeting}.
5603 Setting a date for a meeting is just a simple appointment, you should
5604 mark this entry with a simple plain timestamp, to get this item shown
5605 on the date where it applies.  This is a frequent misunderstanding by
5606 Org users.  In Org-mode, @i{scheduling} means setting a date when you
5607 want to start working on an action item.
5608 @end table
5610 You may use timestamps with repeaters in scheduling and deadline
5611 entries.  Org-mode will issue early and late warnings based on the
5612 assumption that the timestamp represents the @i{nearest instance} of
5613 the repeater.  However, the use of diary sexp entries like
5615 @code{<%%(org-float t 42)>}
5617 in scheduling and deadline timestamps is limited.  Org-mode does not
5618 know enough about the internals of each sexp function to issue early and
5619 late warnings.  However, it will show the item on each day where the
5620 sexp entry matches.
5622 @menu
5623 * Inserting deadline/schedule::  Planning items
5624 * Repeated tasks::              Items that show up again and again
5625 @end menu
5627 @node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling
5628 @subsection Inserting deadlines or schedules
5630 The following commands allow you to quickly insert@footnote{The @samp{SCHEDULED} and
5631 @samp{DEADLINE} dates are inserted on the line right below the headline.  Don't put
5632 any text between this line and the headline.} a deadline or to schedule
5633 an item:
5635 @table @kbd
5637 @orgcmd{C-c C-d,org-deadline}
5638 Insert @samp{DEADLINE} keyword along with a stamp.  The insertion will happen
5639 in the line directly following the headline.  When called with a prefix arg,
5640 an existing deadline will be removed from the entry.  Depending on the
5641 variable @code{org-log-redeadline}@footnote{with corresponding
5642 @code{#+STARTUP} keywords @code{logredeadline}, @code{lognoteredeadline},
5643 and @code{nologredeadline}}, a note will be taken when changing an existing
5644 deadline.
5645 @c FIXME Any CLOSED timestamp will be removed.????????
5647 @orgcmd{C-c C-s,org-schedule}
5648 Insert @samp{SCHEDULED} keyword along with a stamp.  The insertion will
5649 happen in the line directly following the headline.  Any CLOSED timestamp
5650 will be removed.  When called with a prefix argument, remove the scheduling
5651 date from the entry.  Depending on the variable
5652 @code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}
5653 keywords @code{logreschedule}, @code{lognotereschedule}, and
5654 @code{nologreschedule}}, a note will be taken when changing an existing
5655 scheduling time.
5657 @orgcmd{C-c C-x C-k,org-mark-entry-for-agenda-action}
5658 @kindex k a
5659 @kindex k s
5660 Mark the current entry for agenda action.  After you have marked the entry
5661 like this, you can open the agenda or the calendar to find an appropriate
5662 date.  With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to
5663 schedule the marked item.
5665 @orgcmd{C-c / d,org-check-deadlines}
5666 @cindex sparse tree, for deadlines
5667 @vindex org-deadline-warning-days
5668 Create a sparse tree with all deadlines that are either past-due, or
5669 which will become due within @code{org-deadline-warning-days}.
5670 With @kbd{C-u} prefix, show all deadlines in the file.  With a numeric
5671 prefix, check that many days.  For example, @kbd{C-1 C-c / d} shows
5672 all deadlines due tomorrow.
5674 @orgcmd{C-c / b,org-check-before-date}
5675 Sparse tree for deadlines and scheduled items before a given date.
5677 @orgcmd{C-c / a,org-check-after-date}
5678 Sparse tree for deadlines and scheduled items after a given date.
5679 @end table
5681 @node Repeated tasks,  , Inserting deadline/schedule, Deadlines and scheduling
5682 @subsection Repeated tasks
5683 @cindex tasks, repeated
5684 @cindex repeated tasks
5686 Some tasks need to be repeated again and again.  Org-mode helps to
5687 organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
5688 or plain timestamp.  In the following example
5689 @example
5690 ** TODO Pay the rent
5691    DEADLINE: <2005-10-01 Sat +1m>
5692 @end example
5693 @noindent
5694 the @code{+1m} is a repeater; the intended interpretation is that the task
5695 has a deadline on <2005-10-01> and repeats itself every (one) month starting
5696 from that time.  If you need both a repeater and a special warning period in
5697 a deadline entry, the repeater should come first and the warning period last:
5698 @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
5700 @vindex org-todo-repeat-to-state
5701 Deadlines and scheduled items produce entries in the agenda when they are
5702 over-due, so it is important to be able to mark such an entry as completed
5703 once you have done so.  When you mark a DEADLINE or a SCHEDULE with the TODO
5704 keyword DONE, it will no longer produce entries in the agenda.  The problem
5705 with this is, however, that then also the @emph{next} instance of the
5706 repeated entry will not be active.  Org-mode deals with this in the following
5707 way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
5708 shift the base date of the repeating timestamp by the repeater interval, and
5709 immediately set the entry state back to TODO@footnote{In fact, the target
5710 state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or
5711 the variable @code{org-todo-repeat-to-state}.  If neither of these is
5712 specified, the target state defaults to the first state of the TODO state
5713 sequence.}.  In the example above, setting the state to DONE would actually
5714 switch the date like this:
5716 @example
5717 ** TODO Pay the rent
5718    DEADLINE: <2005-11-01 Tue +1m>
5719 @end example
5721 @vindex org-log-repeat
5722 A timestamp@footnote{You can change this using the option
5723 @code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},
5724 @code{lognoterepeat}, and @code{nologrepeat}.  With @code{lognoterepeat}, you
5725 will also be prompted for a note.} will be added under the deadline, to keep
5726 a record that you actually acted on the previous instance of this deadline.
5728 As a consequence of shifting the base date, this entry will no longer be
5729 visible in the agenda when checking past dates, but all future instances
5730 will be visible.
5732 With the @samp{+1m} cookie, the date shift will always be exactly one
5733 month.  So if you have not paid the rent for three months, marking this
5734 entry DONE will still keep it as an overdue deadline.  Depending on the
5735 task, this may not be the best way to handle it.  For example, if you
5736 forgot to call your father for 3 weeks, it does not make sense to call
5737 him 3 times in a single day to make up for it.  Finally, there are tasks
5738 like changing batteries which should always repeat a certain time
5739 @i{after} the last time you did it.  For these tasks, Org-mode has
5740 special repeaters  @samp{++} and @samp{.+}.  For example:
5742 @example
5743 ** TODO Call Father
5744    DEADLINE: <2008-02-10 Sun ++1w>
5745    Marking this DONE will shift the date by at least one week,
5746    but also by as many weeks as it takes to get this date into
5747    the future.  However, it stays on a Sunday, even if you called
5748    and marked it done on Saturday.
5749 ** TODO Check the batteries in the smoke detectors
5750    DEADLINE: <2005-11-01 Tue .+1m>
5751    Marking this DONE will shift the date to one month after
5752    today.
5753 @end example
5755 You may have both scheduling and deadline information for a specific
5756 task---just make sure that the repeater intervals on both are the same.
5758 An alternative to using a repeater is to create a number of copies of a task
5759 subtree, with dates shifted in each copy.  The command @kbd{C-c C-x c} was
5760 created for this purpose, it is described in @ref{Structure editing}.
5763 @node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and Times
5764 @section Clocking work time
5765 @cindex clocking time
5766 @cindex time clocking
5768 Org-mode allows you to clock the time you spend on specific tasks in a
5769 project.  When you start working on an item, you can start the clock.
5770 When you stop working on that task, or when you mark the task done, the
5771 clock is stopped and the corresponding time interval is recorded.  It
5772 also computes the total time spent on each subtree of a project.  And it
5773 remembers a history or tasks recently clocked, to that you can jump quickly
5774 between a number of tasks absorbing your time.
5776 To save the clock history across Emacs sessions, use
5777 @lisp
5778 (setq org-clock-persist 'history)
5779 (org-clock-persistence-insinuate)
5780 @end lisp
5781 When you clock into a new task after resuming Emacs, the incomplete
5782 clock@footnote{To resume the clock under the assumption that you have worked
5783 on this task while outside Emacs, use @code{(setq org-clock-persist t)}.}
5784 will be found (@pxref{Resolving idle time}) and you will be prompted about
5785 what to do with it.
5787 @menu
5788 * Clocking commands::           Starting and stopping a clock
5789 * The clock table::             Detailed reports
5790 * Resolving idle time::         Resolving time when you've been idle
5791 @end menu
5793 @node Clocking commands, The clock table, Clocking work time, Clocking work time
5794 @subsection Clocking commands
5796 @table @kbd
5797 @orgcmd{C-c C-x C-i,org-clock-in}
5798 @vindex org-clock-into-drawer
5799 @cindex property, LOG_INTO_DRAWER
5800 Start the clock on the current item (clock-in).  This inserts the CLOCK
5801 keyword together with a timestamp.  If this is not the first clocking of
5802 this item, the multiple CLOCK lines will be wrapped into a
5803 @code{:LOGBOOK:} drawer (see also the variable
5804 @code{org-clock-into-drawer}).  You can also overrule
5805 the setting of this variable for a subtree by setting a
5806 @code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
5807 When called with a @kbd{C-u} prefix argument,
5808 select the task from a list of recently clocked tasks.  With two @kbd{C-u
5809 C-u} prefixes, clock into the task at point and mark it as the default task.
5810 The default task will always be available when selecting a clocking task,
5811 with letter @kbd{d}.@*
5812 @cindex property: CLOCK_MODELINE_TOTAL
5813 @cindex property: LAST_REPEAT
5814 @vindex org-clock-modeline-total
5815 While the clock is running, the current clocking time is shown in the mode
5816 line, along with the title of the task.  The clock time shown will be all
5817 time ever clocked for this task and its children.  If the task has an effort
5818 estimate (@pxref{Effort estimates}), the mode line displays the current
5819 clocking time against it@footnote{To add an effort estimate ``on the fly'',
5820 hook a function doing this to @code{org-clock-in-prepare-hook}.}  If the task
5821 is a repeating one (@pxref{Repeated tasks}), only the time since the last
5822 reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}
5823 will be shown.  More control over what time is shown can be exercised with
5824 the @code{CLOCK_MODELINE_TOTAL} property.  It may have the values
5825 @code{current} to show only the current clocking instance, @code{today} to
5826 show all time clocked on this tasks today (see also the variable
5827 @code{org-extend-today-until}), @code{all} to include all time, or
5828 @code{auto} which is the default@footnote{See also the variable
5829 @code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
5830 mode line entry will pop up a menu with clocking options.
5832 @orgcmd{C-c C-x C-o,org-clock-out}
5833 @vindex org-log-note-clock-out
5834 Stop the clock (clock-out).  This inserts another timestamp at the same
5835 location where the clock was last started.  It also directly computes
5836 the resulting time in inserts it after the time range as @samp{=>
5837 HH:MM}.  See the variable @code{org-log-note-clock-out} for the
5838 possibility to record an additional note together with the clock-out
5839 timestamp@footnote{The corresponding in-buffer setting is:
5840 @code{#+STARTUP: lognoteclock-out}}.
5841 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
5842 Update the effort estimate for the current clock task.
5843 @kindex C-c C-y
5844 @kindex C-c C-c
5845 @orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range}
5846 Recompute the time interval after changing one of the timestamps.  This
5847 is only necessary if you edit the timestamps directly.  If you change
5848 them with @kbd{S-@key{cursor}} keys, the update is automatic.
5849 @orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
5850 On @code{CLOCK} log lines, increase/decrease both timestamps at the same
5851 time so that duration keeps the same.
5852 @orgcmd{C-c C-t,org-todo}
5853 Changing the TODO state of an item to DONE automatically stops the clock
5854 if it is running in this same item.
5855 @orgcmd{C-c C-x C-x,org-clock-cancel}
5856 Cancel the current clock.  This is useful if a clock was started by
5857 mistake, or if you ended up working on something else.
5858 @orgcmd{C-c C-x C-j,org-clock-goto}
5859 Jump to the headline of the currently clocked in task.  With a @kbd{C-u}
5860 prefix arg, select the target task from a list of recently clocked tasks.
5861 @orgcmd{C-c C-x C-d,org-clock-display}
5862 @vindex org-remove-highlights-with-change
5863 Display time summaries for each subtree in the current buffer.  This puts
5864 overlays at the end of each headline, showing the total time recorded under
5865 that heading, including the time of any subheadings.  You can use visibility
5866 cycling to study the tree, but the overlays disappear when you change the
5867 buffer (see variable @code{org-remove-highlights-with-change}) or press
5868 @kbd{C-c C-c}.
5869 @end table
5871 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
5872 the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
5873 worked on or closed during a day.
5875 @node The clock table, Resolving idle time, Clocking commands, Clocking work time
5876 @subsection The clock table
5877 @cindex clocktable, dynamic block
5878 @cindex report, of clocked time
5880 Org mode can produce quite complex reports based on the time clocking
5881 information.  Such a report is called a @emph{clock table}, because it is
5882 formatted as one or several Org tables.
5884 @table @kbd
5885 @orgcmd{C-c C-x C-r,org-clock-report}
5886 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
5887 report as an Org-mode table into the current file.  When the cursor is
5888 at an existing clock table, just update it.  When called with a prefix
5889 argument, jump to the first clock report in the current document and
5890 update it.
5891 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
5892 Update dynamic block at point.  The cursor needs to be in the
5893 @code{#+BEGIN} line of the dynamic block.
5894 @orgkey{C-u C-c C-x C-u}
5895 Update all dynamic blocks (@pxref{Dynamic blocks}).  This is useful if
5896 you have several clock table blocks in a buffer.
5897 @orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift}
5898 Shift the current @code{:block} interval and update the table.  The cursor
5899 needs to be in the @code{#+BEGIN: clocktable} line for this command.  If
5900 @code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
5901 @end table
5904 Here is an example of the frame for a clock table as it is inserted into the
5905 buffer with the @kbd{C-c C-x C-r} command:
5907 @cindex #+BEGIN, clocktable
5908 @example
5909 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
5910 #+END: clocktable
5911 @end example
5912 @noindent
5913 @vindex org-clocktable-defaults
5914 The @samp{BEGIN} line and specify a number of options to define the scope,
5915 structure, and formatting of the report.  Defaults for all these options can
5916 be configured in the variable @code{org-clocktable-defaults}.
5918 @noindent First there are options that determine which clock entries are to
5919 be selected:
5920 @example
5921 :maxlevel    @r{Maximum level depth to which times are listed in the table.}
5922              @r{Clocks at deeper levels will be summed into the upper level.}
5923 :scope       @r{The scope to consider.  This can be any of the following:}
5924              nil        @r{the current buffer or narrowed region}
5925              file       @r{the full current buffer}
5926              subtree    @r{the subtree where the clocktable is located}
5927              tree@var{N}      @r{the surrounding level @var{N} tree, for example @code{tree3}}
5928              tree       @r{the surrounding level 1 tree}
5929              agenda     @r{all agenda files}
5930              ("file"..) @r{scan these files}
5931              file-with-archives    @r{current file and its archives}
5932              agenda-with-archives  @r{all agenda files, including archives}
5933 :block       @r{The time block to consider.  This block is specified either}
5934              @r{absolute, or relative to the current time and may be any of}
5935              @r{these formats:}
5936              2007-12-31    @r{New year eve 2007}
5937              2007-12       @r{December 2007}
5938              2007-W50      @r{ISO-week 50 in 2007}
5939              2007-Q2       @r{2nd quarter in 2007}
5940              2007          @r{the year 2007}
5941              today, yesterday, today-@var{N}          @r{a relative day}
5942              thisweek, lastweek, thisweek-@var{N}     @r{a relative week}
5943              thismonth, lastmonth, thismonth-@var{N}  @r{a relative month}
5944              thisyear, lastyear, thisyear-@var{N}     @r{a relative year}
5945              @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}
5946 :tstart      @r{A time string specifying when to start considering times.}
5947 :tend        @r{A time string specifying when to stop considering times.}
5948 :step        @r{@code{week} or @code{day}, to split the table into chunks.}
5949              @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}
5950 :stepskip0   @r{Do not show steps that have zero time.}
5951 :fileskip0   @r{Do not show table sections from files which did not contribute.}
5952 :tags        @r{A tags match to select entries that should contribute.  See}
5953              @r{@ref{Matching tags and properties} for the match syntax.}
5954 @end example
5956 Then there are options which determine the formatting of the table.  There
5957 options are interpreted by the function @code{org-clocktable-write-default},
5958 but you can specify your own function using the @code{:formatter} parameter.
5959 @example
5960 :emphasize   @r{When @code{t}, emphasize level one and level two items.}
5961 :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".}
5962 :link        @r{Link the item headlines in the table to their origins.}
5963 :narrow      @r{An integer to limit the width of the headline column in}
5964              @r{the org table.  If you write it like @samp{50!}, then the}
5965              @r{headline will also be shortened in export.}
5966 :indent      @r{Indent each headline field according to its level.}
5967 :tcolumns    @r{Number of columns to be used for times.  If this is smaller}
5968              @r{than @code{:maxlevel}, lower levels will be lumped into one column.}
5969 :level       @r{Should a level number column be included?}
5970 :compact     @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}}
5971              @r{All are overwritten except if there is an explicit @code{:narrow}}
5972 :timestamp   @r{A timestamp for the entry, when available.  Look for SCHEDULED,}
5973              @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}
5974 :properties  @r{List of properties that should be shown in the table.  Each}
5975              @r{property will get its own column.}
5976 :inherit-props @r{When this flag is @code{t}, the values for @code{:properties} will be inherited.}
5977 :formula     @r{Content of a @code{#+TBLFM} line to be added and evaluated.}
5978              @r{As a special case, @samp{:formula %} adds a column with % time.}
5979              @r{If you do not specify a formula here, any existing formula}
5980              @r{below the clock table will survive updates and be evaluated.}
5981 :formatter   @r{A function to format clock data and insert it into the buffer.}
5982 @end example
5983 To get a clock summary of the current level 1 tree, for the current
5984 day, you could write
5985 @example
5986 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
5987 #+END: clocktable
5988 @end example
5989 @noindent
5990 and to use a specific time range you could write@footnote{Note that all
5991 parameters must be specified in a single line---the line is broken here
5992 only to fit it into the manual.}
5993 @example
5994 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
5995                     :tend "<2006-08-10 Thu 12:00>"
5996 #+END: clocktable
5997 @end example
5998 A summary of the current subtree with % times would be
5999 @example
6000 #+BEGIN: clocktable :scope subtree :link t :formula %
6001 #+END: clocktable
6002 @end example
6003 A horizontally compact representation of everything clocked during last week
6004 would be
6005 @example
6006 #+BEGIN: clocktable :scope agenda :block lastweek :compact t
6007 #+END: clocktable
6008 @end example
6010 @node Resolving idle time,  , The clock table, Clocking work time
6011 @subsection Resolving idle time
6012 @cindex resolve idle time
6014 @cindex idle, resolve, dangling
6015 If you clock in on a work item, and then walk away from your
6016 computer---perhaps to take a phone call---you often need to ``resolve'' the
6017 time you were away by either subtracting it from the current clock, or
6018 applying it to another one.
6020 @vindex org-clock-idle-time
6021 By customizing the variable @code{org-clock-idle-time} to some integer, such
6022 as 10 or 15, Emacs can alert you when you get back to your computer after
6023 being idle for that many minutes@footnote{On computers using Mac OS X,
6024 idleness is based on actual user idleness, not just Emacs' idle time.  For
6025 X11, you can install a utility program @file{x11idle.c}, available in the
6026 UTILITIES directory of the Org git distribution, to get the same general
6027 treatment of idleness.  On other systems, idle time refers to Emacs idle time
6028 only.}, and ask what you want to do with the idle time.  There will be a
6029 question waiting for you when you get back, indicating how much idle time has
6030 passed (constantly updated with the current amount), as well as a set of
6031 choices to correct the discrepancy:
6033 @table @kbd
6034 @item k
6035 To keep some or all of the minutes and stay clocked in, press @kbd{k}.  Org
6036 will ask how many of the minutes to keep.  Press @key{RET} to keep them all,
6037 effectively changing nothing, or enter a number to keep that many minutes.
6038 @item K
6039 If you use the shift key and press @kbd{K}, it will keep however many minutes
6040 you request and then immediately clock out of that task.  If you keep all of
6041 the minutes, this is the same as just clocking out of the current task.
6042 @item s
6043 To keep none of the minutes, use @kbd{s} to subtract all the away time from
6044 the clock, and then check back in from the moment you returned.
6045 @item S
6046 To keep none of the minutes and just clock out at the start of the away time,
6047 use the shift key and press @kbd{S}.  Remember that using shift will always
6048 leave you clocked out, no matter which option you choose.
6049 @item C
6050 To cancel the clock altogether, use @kbd{C}.  Note that if instead of
6051 canceling you subtract the away time, and the resulting clock amount is less
6052 than a minute, the clock will still be canceled rather than clutter up the
6053 log with an empty entry.
6054 @end table
6056 What if you subtracted those away minutes from the current clock, and now
6057 want to apply them to a new clock?  Simply clock in to any task immediately
6058 after the subtraction.  Org will notice that you have subtracted time ``on
6059 the books'', so to speak, and will ask if you want to apply those minutes to
6060 the next task you clock in on.
6062 There is one other instance when this clock resolution magic occurs.  Say you
6063 were clocked in and hacking away, and suddenly your cat chased a mouse who
6064 scared a hamster that crashed into your UPS's power button!  You suddenly
6065 lose all your buffers, but thanks to auto-save you still have your recent Org
6066 mode changes, including your last clock in.
6068 If you restart Emacs and clock into any task, Org will notice that you have a
6069 dangling clock which was never clocked out from your last session.  Using
6070 that clock's starting time as the beginning of the unaccounted-for period,
6071 Org will ask how you want to resolve that time.  The logic and behavior is
6072 identical to dealing with away time due to idleness; it is just happening due
6073 to a recovery event rather than a set amount of idle time.
6075 You can also check all the files visited by your Org agenda for dangling
6076 clocks at any time using @kbd{M-x org-resolve-clocks}.
6078 @node Effort estimates, Relative timer, Clocking work time, Dates and Times
6079 @section Effort estimates
6080 @cindex effort estimates
6082 @cindex property, Effort
6083 @vindex org-effort-property
6084 If you want to plan your work in a very detailed way, or if you need to
6085 produce offers with quotations of the estimated work effort, you may want to
6086 assign effort estimates to entries.  If you are also clocking your work, you
6087 may later want to compare the planned effort with the actual working time, a
6088 great way to improve planning estimates.  Effort estimates are stored in a
6089 special property @samp{Effort}@footnote{You may change the property being
6090 used with the variable @code{org-effort-property}.}.  You can set the effort
6091 for an entry with the following commands:
6093 @table @kbd
6094 @orgcmd{C-c C-x e,org-set-effort}
6095 Set the effort estimate for the current entry.  With a numeric prefix
6096 argument, set it to the Nth allowed value (see below).  This command is also
6097 accessible from the agenda with the @kbd{e} key.
6098 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6099 Modify the effort estimate of the item currently being clocked.
6100 @end table
6102 Clearly the best way to work with effort estimates is through column view
6103 (@pxref{Column view}).  You should start by setting up discrete values for
6104 effort estimates, and a @code{COLUMNS} format that displays these values
6105 together with clock sums (if you want to clock your time).  For a specific
6106 buffer you can use
6108 @example
6109 #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
6110 #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM
6111 @end example
6113 @noindent
6114 @vindex org-global-properties
6115 @vindex org-columns-default-format
6116 or, even better, you can set up these values globally by customizing the
6117 variables @code{org-global-properties} and @code{org-columns-default-format}.
6118 In particular if you want to use this setup also in the agenda, a global
6119 setup may be advised.
6121 The way to assign estimates to individual items is then to switch to column
6122 mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the
6123 value.  The values you enter will immediately be summed up in the hierarchy.
6124 In the column next to it, any clocked time will be displayed.
6126 @vindex org-agenda-columns-add-appointments-to-effort-sum
6127 If you switch to column view in the daily/weekly agenda, the effort column
6128 will summarize the estimated work effort for each day@footnote{Please note
6129 the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda
6130 column view}).}, and you can use this to find space in your schedule.  To get
6131 an overview of the entire part of the day that is committed, you can set the
6132 option @code{org-agenda-columns-add-appointments-to-effort-sum}.  The
6133 appointments on a day that take place over a specified time interval will
6134 then also be added to the load estimate of the day.
6136 Effort estimates can be used in secondary agenda filtering that is triggered
6137 with the @kbd{/} key in the agenda (@pxref{Agenda commands}).  If you have
6138 these estimates defined consistently, two or three key presses will narrow
6139 down the list to stuff that fits into an available time slot.
6141 @node Relative timer, Countdown timer, Effort estimates, Dates and Times
6142 @section Taking notes with a relative timer
6143 @cindex relative timer
6145 When taking notes during, for example, a meeting or a video viewing, it can
6146 be useful to have access to times relative to a starting time.  Org provides
6147 such a relative timer and make it easy to create timed notes.
6149 @table @kbd
6150 @orgcmd{C-c C-x .,org-timer}
6151 Insert a relative time into the buffer.  The first time you use this, the
6152 timer will be started.  When called with a prefix argument, the timer is
6153 restarted.
6154 @orgcmd{C-c C-x -,org-timer-item}
6155 Insert a description list item with the current relative time.  With a prefix
6156 argument, first reset the timer to 0.
6157 @orgcmd{M-@key{RET},org-insert-heading}
6158 Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert
6159 new timer items.
6160 @c for key sequences with a comma, command name macros fail :(
6161 @kindex C-c C-x ,
6162 @item C-c C-x ,
6163 Pause the timer, or continue it if it is already paused
6164 (@command{org-timer-pause-or-continue}).
6165 @c removed the sentence because it is redundant to the following item
6166 @kindex C-u C-c C-x ,
6167 @item C-u C-c C-x ,
6168 Stop the timer.  After this, you can only start a new timer, not continue the
6169 old one.  This command also removes the timer from the mode line.
6170 @orgcmd{C-c C-x 0,org-timer-start}
6171 Reset the timer without inserting anything into the buffer.  By default, the
6172 timer is reset to 0.  When called with a @kbd{C-u} prefix, reset the timer to
6173 specific starting offset.  The user is prompted for the offset, with a
6174 default taken from a timer string at point, if any, So this can be used to
6175 restart taking notes after a break in the process.  When called with a double
6176 prefix argument @kbd{C-u C-u}, change all timer strings in the active region
6177 by a certain amount.  This can be used to fix timer strings if the timer was
6178 not started at exactly the right moment.
6179 @end table
6181 @node Countdown timer,  , Relative timer, Dates and Times
6182 @section Countdown timer
6183 @cindex Countdown timer
6184 @kindex C-c C-x ;
6185 @kindex ;
6187 Calling @code{org-timer-set-timer} from an Org-mode buffer runs a countdown
6188 timer.  Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everwhere else.
6190 @code{org-timer-set-timer} prompts the user for a duration and displays a
6191 countdown timer in the modeline.  @code{org-timer-default-timer} sets the
6192 default countdown value.  Giving a prefix numeric argument overrides this
6193 default value.
6195 @node Capture - Refile - Archive, Agenda Views, Dates and Times, Top
6196 @chapter Capture - Refile - Archive
6197 @cindex capture
6199 An important part of any organization system is the ability to quickly
6200 capture new ideas and tasks, and to associate reference material with them.
6201 Org does this using a process called @i{capture}.  It also can store files
6202 related to a task (@i{attachments}) in a special directory.  Once in the
6203 system, tasks and projects need to be moved around.  Moving completed project
6204 trees to an archive file keeps the system compact and fast.
6206 @menu
6207 * Capture::                     Capturing new stuff
6208 * Attachments::                 Add files to tasks
6209 * RSS Feeds::                   Getting input from RSS feeds
6210 * Protocols::                   External (e.g.@: Browser) access to Emacs and Org
6211 * Refiling notes::              Moving a tree from one place to another
6212 * Archiving::                   What to do with finished projects
6213 @end menu
6215 @node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
6216 @section Capture
6217 @cindex capture
6219 Org's method for capturing new items is heavily inspired by John Wiegley
6220 excellent remember package.  Up to version 6.36 Org used a special setup
6221 for @file{remember.el}.  @file{org-remember.el} is still part of Org-mode for
6222 backward compatibility with existing setups.  You can find the documentation
6223 for org-remember at @url{http://orgmode.org/org-remember.pdf}.
6225 The new capturing setup described here is preferred and should be used by new
6226 users.  To convert your @code{org-remember-templates}, run the command
6227 @example
6228 @kbd{M-x org-capture-import-remember-templates @key{RET}}
6229 @end example
6230 @noindent and then customize the new variable with @kbd{M-x
6231 customize-variable org-capture-templates}, check the result, and save the
6232 customization.  You can then use both remember and capture until
6233 you are familiar with the new mechanism.
6235 Capture lets you quickly store notes with little interruption of your work
6236 flow.  The basic process of capturing is very similar to remember, but Org
6237 does enhance it with templates and more.
6239 @menu
6240 * Setting up capture::          Where notes will be stored
6241 * Using capture::               Commands to invoke and terminate capture
6242 * Capture templates::           Define the outline of different note types
6243 @end menu
6245 @node Setting up capture, Using capture, Capture, Capture
6246 @subsection Setting up capture
6248 The following customization sets a default target file for notes, and defines
6249 a global key@footnote{Please select your own key, @kbd{C-c c} is only a
6250 suggestion.}  for capturing new material.
6252 @vindex org-default-notes-file
6253 @example
6254 (setq org-default-notes-file (concat org-directory "/notes.org"))
6255 (define-key global-map "\C-cc" 'org-capture)
6256 @end example
6258 @node Using capture, Capture templates, Setting up capture, Capture
6259 @subsection Using capture
6261 @table @kbd
6262 @orgcmd{C-c c,org-capture}
6263 Call the command @code{org-capture}.  Note that this keybinding is global and
6264 not active by default - you need to install it.  If you have templates
6265 @cindex date tree
6266 defined @pxref{Capture templates}, it will offer these templates for
6267 selection or use a new Org outline node as the default template.  It will
6268 insert the template into the target file and switch to an indirect buffer
6269 narrowed to this new node.  You may then insert the information you want.
6271 @orgcmd{C-c C-c,org-capture-finalize}
6272 Once you have finished entering information into the capture buffer, @kbd{C-c
6273 C-c} will return you to the window configuration before the capture process,
6274 so that you can resume your work without further distraction.  When called
6275 with a prefix arg, finalize and then jump to the captured item.
6277 @orgcmd{C-c C-w,org-capture-refile}
6278 Finalize the capture process by refiling (@pxref{Refiling notes}) the note to
6279 a different place.  Please realize that this is a normal refiling command
6280 that will be executed---so the cursor position at the moment you run this
6281 command is important.  If you have inserted a tree with a parent and
6282 children, first move the cursor back to the parent.  Any prefix argument
6283 given to this command will be passed on to the @code{org-refile} command.
6285 @orgcmd{C-c C-k,org-capture-kill}
6286 Abort the capture process and return to the previous state.
6288 @end table
6290 You can also call @code{org-capture} in a special way from the agenda, using
6291 the @kbd{k c} key combination.  With this access, any timestamps inserted by
6292 the selected capture template will default to the cursor date in the agenda,
6293 rather than to the current date.
6295 To find the locations of the last stored capture, use @code{org-capture} with
6296 prefix commands:
6298 @table @kbd
6299 @orgkey{C-u C-c c}
6300 Visit the target location of a capture template.  You get to select the
6301 template in the usual way.
6302 @orgkey{C-u C-u C-c c}
6303 Visit the last stored capture item in its buffer.
6304 @end table
6306 @node Capture templates,  , Using capture, Capture
6307 @subsection Capture templates
6308 @cindex templates, for Capture
6310 You can use templates for different types of capture items, and
6311 for different target locations.  The easiest way to create such templates is
6312 through the customize interface.
6314 @table @kbd
6315 @orgkey{C-c c C}
6316 Customize the variable @code{org-capture-templates}.
6317 @end table
6319 Before we give the formal description of template definitions, let's look at
6320 an example.  Say you would like to use one template to create general TODO
6321 entries, and you want to put these entries under the heading @samp{Tasks} in
6322 your file @file{~/org/gtd.org}.  Also, a date tree in the file
6323 @file{journal.org} should capture journal entries.  A possible configuration
6324 would look like:
6326 @example
6327 (setq org-capture-templates
6328  '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
6329         "* TODO %?\n  %i\n  %a")
6330    ("j" "Journal" entry (file+datetree "~/org/journal.org")
6331         "* %?\nEntered on %U\n  %i\n  %a")))
6332 @end example
6334 @noindent If you then press @kbd{C-c c t}, Org will prepare the template
6335 for you like this:
6336 @example
6337 * TODO
6338   [[file:@var{link to where you initiated capture}]]
6339 @end example
6341 @noindent
6342 During expansion of the template, @code{%a} has been replaced by a link to
6343 the location from where you called the capture command.  This can be
6344 extremely useful for deriving tasks from emails, for example.  You fill in
6345 the task definition, press @code{C-c C-c} and Org returns you to the same
6346 place where you started the capture process.
6348 To define special keys to capture to a particular template without going
6349 through the interactive template selection, you can create your key binding
6350 like this:
6352 @lisp
6353 (define-key global-map "\C-cx"
6354    (lambda () (interactive) (org-capture nil "x")))
6355 @end lisp
6357 @menu
6358 * Template elements::           What is needed for a complete template entry
6359 * Template expansion::          Filling in information about time and context
6360 @end menu
6362 @node Template elements, Template expansion, Capture templates, Capture templates
6363 @subsubsection Template elements
6365 Now lets look at the elements of a template definition.  Each entry in
6366 @code{org-capture-templates} is a list with the following items: 
6368 @table @var
6369 @item keys
6370 The keys that will select the template, as a string, characters
6371 only, for example @code{"a"} for a template to be selected with a
6372 single key, or @code{"bt"} for selection with two keys.  When using
6373 several keys, keys using the same prefix key must be sequential 
6374 in the list and preceded by a 2-element entry explaining the
6375 prefix key, for example
6376 @example
6377          ("b" "Templates for marking stuff to buy")
6378 @end example
6379 @noindent If you do not define a template for the @kbd{C} key, this key will
6380 be used to open the customize buffer for this complex variable.
6382 @item description
6383 A short string describing the template, which will be shown during
6384 selection.
6386 @item type
6387 The type of entry, a symbol.  Valid values are:
6388 @table @code
6389 @item entry
6390 An Org-mode node, with a headline.  Will be filed as the child of the target
6391 entry or as a top-level entry.  The target file should be an Org-mode file.
6392 @item item
6393 A plain list item, placed in the first plain  list at the target
6394 location.  Again the target file should be an Org file.
6395 @item checkitem
6396 A checkbox item.  This only differs from the plain list item by the
6397 default template.
6398 @item table-line
6399 a new line in the first table at the target location.  Where exactly the
6400 line will be inserted depends on the properties @code{:prepend} and
6401 @code{:table-line-pos} (see below).
6402 @item plain
6403 Text to be inserted as it is.
6404 @end table
6406 @item target
6407 @vindex org-default-notes-file
6408 Specification of where the captured item should be placed.  In Org-mode
6409 files, targets usually define a node.  Entries will become children of this
6410 node.  Other types will be added to the table or list in the body of this
6411 node.  Most target specifications contain a file name.  If that file name is
6412 the empty string, it defaults to @code{org-default-notes-file}.  A file can
6413 also be given as a variable, function, or Emacs Lisp form.
6415 Valid values are:
6416 @table @code
6417 @item (file "path/to/file")
6418 Text will be placed at the beginning or end of that file.
6420 @item (id "id of existing org entry")
6421 Filing as child of this entry, or in the body of the entry.
6423 @item (file+headline "path/to/file" "node headline")
6424 Fast configuration if the target heading is unique in the file.
6426 @item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
6427 For non-unique headings, the full path is safer.
6429 @item (file+regexp  "path/to/file" "regexp to find location")
6430 Use a regular expression to position the cursor.
6432 @item (file+datetree "path/to/file")
6433 Will create a heading in a date tree for today's date.
6435 @item (file+datetree+prompt "path/to/file")
6436 Will create a heading in a date tree, but will prompt for the date.
6438 @item (file+function "path/to/file" function-finding-location)
6439 A function to find the right location in the file.
6441 @item (clock)
6442 File to the entry that is currently being clocked.
6444 @item (function function-finding-location)
6445 Most general way, write your own function to find both
6446 file and location.
6447 @end table
6449 @item template
6450 The template for creating the capture item.  If you leave this empty, an
6451 appropriate default template will be used.  Otherwise this is a string with
6452 escape codes, which will be replaced depending on time and context of the
6453 capture call.  The string with escapes may be loaded from a template file,
6454 using the special syntax @code{(file "path/to/template")}.  See below for
6455 more details.
6457 @item properties
6458 The rest of the entry is a property list of additional options.
6459 Recognized properties are:
6460 @table @code
6461 @item :prepend
6462 Normally new captured information will be appended at
6463 the target location (last child, last table line, last list item...).
6464 Setting this property will change that.
6466 @item :immediate-finish
6467 When set, do not offer to edit the information, just
6468 file it away immediately.  This makes sense if the template only needs
6469 information that can be added automatically.
6471 @item :empty-lines
6472 Set this to the number of lines to insert
6473 before and after the new item.  Default 0, only common other value is 1.
6475 @item :clock-in
6476 Start the clock in this item.
6478 @item :clock-keep
6479 Keep the clock running when filing the captured entry.
6481 @item :clock-resume
6482 If starting the capture interrupted a clock, restart that clock when finished
6483 with the capture.  Note that @code{:clock-keep} has precedence over
6484 @code{:clock-resume}.  When setting both to @code{t}, the current clock will
6485 run and the previous one will not be resumed.
6487 @item :unnarrowed
6488 Do not narrow the target buffer, simply show the full buffer.  Default is to
6489 narrow it so that you only see the new material.
6491 @item :table-line-pos
6492 Specification of the location in the table where the new line should be
6493 inserted.  It should be a string like @code{"II-3"} meaning that the new
6494 line should become the third line before the second horizontal separator
6495 line.
6497 @item :kill-buffer
6498 If the target file was not yet visited when capture was invoked, kill the
6499 buffer again after capture is completed.
6500 @end table
6501 @end table
6503 @node Template expansion,  , Template elements, Capture templates
6504 @subsubsection Template expansion
6506 In the template itself, special @kbd{%}-escapes@footnote{If you need one of
6507 these sequences literally, escape the @kbd{%} with a backslash.}  allow
6508 dynamic insertion of content:
6510 @comment SJE: should these sentences terminate in period?
6511 @smallexample
6512 %^@{@var{prompt}@}  @r{prompt the user for a string and replace this sequence with it.}
6513             @r{You may specify a default value and a completion table with}
6514             @r{%^@{prompt|default|completion2|completion3...@}}
6515             @r{The arrow keys access a prompt-specific history.}
6516 %a          @r{annotation, normally the link created with @code{org-store-link}}
6517 %A          @r{like @code{%a}, but prompt for the description part}
6518 %i          @r{initial content, the region when capture is called while the}
6519             @r{region is active.}
6520             @r{The entire text will be indented like @code{%i} itself.}
6521 %t          @r{timestamp, date only}
6522 %T          @r{timestamp with date and time}
6523 %u, %U      @r{like the above, but inactive timestamps}
6524 %^t         @r{like @code{%t}, but prompt for date.  Similarly @code{%^T}, @code{%^u}, @code{%^U}}
6525             @r{You may define a prompt like @code{%^@{Birthday@}t}}
6526 %<...>      @r{the result of format-time-string on the ... format specification}
6527 %n          @r{user name (taken from @code{user-full-name})}
6528 %c          @r{Current kill ring head.}
6529 %x          @r{Content of the X clipboard.}
6530 %^C         @r{Interactive selection of which kill or clip to use.}
6531 %^L         @r{Like @code{%^C}, but insert as link.}
6532 %k          @r{title of the currently clocked task}
6533 %K          @r{link to the currently clocked task}
6534 %f          @r{file visited by current buffer when org-capture was called}
6535 %F          @r{like @code{%f}, but include full path}
6536 %^g         @r{prompt for tags, with completion on tags in target file.}
6537 %^G         @r{prompt for tags, with completion all tags in all agenda files.}
6538 %^@{@var{prop}@}p   @r{Prompt the user for a value for property @var{prop}}
6539 %:keyword   @r{specific information for certain link types, see below}
6540 %[@var{file}]     @r{insert the contents of the file given by @var{file}}
6541 %(@var{sexp})     @r{evaluate Elisp @var{sexp} and replace with the result}
6542 @end smallexample
6544 @noindent
6545 For specific link types, the following keywords will be
6546 defined@footnote{If you define your own link types (@pxref{Adding
6547 hyperlink types}), any property you store with
6548 @code{org-store-link-props} can be accessed in capture templates in a
6549 similar way.}:
6551 @vindex org-from-is-user-regexp
6552 @smallexample
6553 Link type               |  Available keywords
6554 ------------------------+----------------------------------------------
6555 bbdb                    |  %:name %:company
6556 irc                     |  %:server %:port %:nick
6557 vm, wl, mh, mew, rmail  |  %:type %:subject %:message-id
6558                         |  %:from %:fromname %:fromaddress
6559                         |  %:to   %:toname   %:toaddress
6560                         |  %:date @r{(message date header field)}
6561                         |  %:date-timestamp @r{(date as active timestamp)}
6562                         |  %:date-timestamp-inactive @r{(date as inactive timestamp)}
6563                         |  %: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}.}}
6564 gnus                    |  %:group, @r{for messages also all email fields}
6565 w3, w3m                 |  %:url
6566 info                    |  %:file %:node
6567 calendar                |  %:date
6568 @end smallexample
6570 @noindent
6571 To place the cursor after template expansion use:
6573 @smallexample
6574 %?          @r{After completing the template, position cursor here.}
6575 @end smallexample
6578 @node Attachments, RSS Feeds, Capture, Capture - Refile - Archive
6579 @section Attachments
6580 @cindex attachments
6582 @vindex org-attach-directory
6583 It is often useful to associate reference material with an outline node/task.
6584 Small chunks of plain text can simply be stored in the subtree of a project.
6585 Hyperlinks (@pxref{Hyperlinks}) can establish associations with
6586 files that live elsewhere on your computer or in the cloud, like emails or
6587 source code files belonging to a project.  Another method is @i{attachments},
6588 which are files located in a directory belonging to an outline node.  Org
6589 uses directories named by the unique ID of each entry.  These directories are
6590 located in the @file{data} directory which lives in the same directory where
6591 your Org file lives@footnote{If you move entries or Org files from one
6592 directory to another, you may want to configure @code{org-attach-directory}
6593 to contain an absolute path.}.  If you initialize this directory with
6594 @code{git init}, Org will automatically commit changes when it sees them.
6595 The attachment system has been contributed to Org by John Wiegley.
6597 In cases where it seems better to do so, you can also attach a directory of your
6598 choice to an entry.  You can also make children inherit the attachment
6599 directory from a parent, so that an entire subtree uses the same attached
6600 directory.
6602 @noindent The following commands deal with attachments:
6604 @table @kbd
6606 @orgcmd{C-c C-a,org-attach}
6607 The dispatcher for commands related to the attachment system.  After these
6608 keys, a list of commands is displayed and you must press an additional key
6609 to select a command:
6611 @table @kbd
6612 @orgcmdtkc{a,C-c C-a a,org-attach-attach}
6613 @vindex org-attach-method
6614 Select a file and move it into the task's attachment directory.  The file
6615 will be copied, moved, or linked, depending on @code{org-attach-method}.
6616 Note that hard links are not supported on all systems.
6618 @kindex C-c C-a c
6619 @kindex C-c C-a m
6620 @kindex C-c C-a l
6621 @item c/m/l
6622 Attach a file using the copy/move/link method.
6623 Note that hard links are not supported on all systems.
6625 @orgcmdtkc{n,C-c C-a n,org-attach-new}
6626 Create a new attachment as an Emacs buffer.
6628 @orgcmdtkc{z,C-c C-a z,org-attach-sync}
6629 Synchronize the current task with its attachment directory, in case you added
6630 attachments yourself.
6632 @orgcmdtkc{o,C-c C-a o,org-attach-open}
6633 @vindex org-file-apps
6634 Open current task's attachment.  If there is more than one, prompt for a
6635 file name first.  Opening will follow the rules set by @code{org-file-apps}.
6636 For more details, see the information on following hyperlinks
6637 (@pxref{Handling links}).
6639 @orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs}
6640 Also open the attachment, but force opening the file in Emacs.
6642 @orgcmdtkc{f,C-c C-a f,org-attach-reveal}
6643 Open the current task's attachment directory.
6645 @orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs}
6646 Also open the directory, but force using @command{dired} in Emacs.
6648 @orgcmdtkc{d,C-c C-a d,org-attach-delete-one}
6649 Select and delete a single attachment.
6651 @orgcmdtkc{D,C-c C-a D,org-attach-delete-all}
6652 Delete all of a task's attachments.  A safer way is to open the directory in
6653 @command{dired} and delete from there.
6655 @orgcmdtkc{s,C-c C-a s,org-attach-set-directory}
6656 @cindex property, ATTACH_DIR
6657 Set a specific directory as the entry's attachment directory.  This works by
6658 putting the directory path into the @code{ATTACH_DIR} property.
6660 @orgcmdtkc{i,C-c C-a i,org-attach-set-inherit}
6661 @cindex property, ATTACH_DIR_INHERIT
6662 Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the
6663 same directory for attachments as the parent does.
6664 @end table
6665 @end table
6667 @node RSS Feeds, Protocols, Attachments, Capture - Refile - Archive
6668 @section RSS feeds
6669 @cindex RSS feeds
6670 @cindex Atom feeds
6672 Org can add and change entries based on information found in RSS feeds and
6673 Atom feeds.  You could use this to make a task out of each new podcast in a
6674 podcast feed.  Or you could use a phone-based note-creating service on the
6675 web to import tasks into Org.  To access feeds, configure the variable
6676 @code{org-feed-alist}.  The docstring of this variable has detailed
6677 information.  Here is just an example:
6679 @example
6680 (setq org-feed-alist
6681      '(("Slashdot"
6682          "http://rss.slashdot.org/Slashdot/slashdot"
6683          "~/txt/org/feeds.org" "Slashdot Entries")))
6684 @end example
6686 @noindent
6687 will configure that new items from the feed provided by
6688 @code{rss.slashdot.org} will result in new entries in the file
6689 @file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
6690 the following command is used:
6692 @table @kbd
6693 @orgcmd{C-c C-x g,org-feed-update-all}
6694 @item C-c C-x g
6695 Collect items from the feeds configured in @code{org-feed-alist} and act upon
6696 them.
6697 @orgcmd{C-c C-x G,org-feed-goto-inbox}
6698 Prompt for a feed name and go to the inbox configured for this feed.
6699 @end table
6701 Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which
6702 it will store information about the status of items in the feed, to avoid
6703 adding the same item several times.  You should add @samp{FEEDSTATUS} to the
6704 list of drawers in that file:
6706 @example
6707 #+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS
6708 @end example
6710 For more information, including how to read atom feeds, see
6711 @file{org-feed.el} and the docstring of @code{org-feed-alist}.
6713 @node Protocols, Refiling notes, RSS Feeds, Capture - Refile - Archive
6714 @section Protocols for external access
6715 @cindex protocols, for external access
6716 @cindex emacsserver
6718 You can set up Org for handling protocol calls from outside applications that
6719 are passed to Emacs through the @file{emacsserver}.  For example, you can
6720 configure bookmarks in your web browser to send a link to the current page to
6721 Org and create a note from it using capture (@pxref{Capture}).  Or you
6722 could create a bookmark that will tell Emacs to open the local source file of
6723 a remote website you are looking at with the browser.  See
6724 @uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed
6725 documentation and setup instructions.
6727 @node Refiling notes, Archiving, Protocols, Capture - Refile - Archive
6728 @section Refiling notes
6729 @cindex refiling notes
6731 When reviewing the captured data, you may want to refile some of the entries
6732 into a different list, for example into a project.  Cutting, finding the
6733 right location, and then pasting the note is cumbersome.  To simplify this
6734 process, you can use the following special command:
6736 @table @kbd
6737 @orgcmd{C-c C-w,org-refile}
6738 @vindex org-reverse-note-order
6739 @vindex org-refile-targets
6740 @vindex org-refile-use-outline-path
6741 @vindex org-outline-path-complete-in-steps
6742 @vindex org-refile-allow-creating-parent-nodes
6743 @vindex org-log-refile
6744 @vindex org-refile-use-cache
6745 Refile the entry or region at point.  This command offers possible locations
6746 for refiling the entry and lets you select one with completion.  The item (or
6747 all items in the region) is filed below the target heading as a subitem.
6748 Depending on @code{org-reverse-note-order}, it will be either the first or
6749 last subitem.@*
6750 By default, all level 1 headlines in the current buffer are considered to be
6751 targets, but you can have more complex definitions across a number of files.
6752 See the variable @code{org-refile-targets} for details.  If you would like to
6753 select a location via a file-path-like completion along the outline path, see
6754 the variables @code{org-refile-use-outline-path} and
6755 @code{org-outline-path-complete-in-steps}.  If you would like to be able to
6756 create new nodes as new parents for refiling on the fly, check the
6757 variable @code{org-refile-allow-creating-parent-nodes}.
6758 When the variable @code{org-log-refile}@footnote{with corresponding
6759 @code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},
6760 and @code{nologrefile}} is set, a timestamp or a note will be
6761 recorded when an entry has been refiled.
6762 @orgkey{C-u C-c C-w}
6763 Use the refile interface to jump to a heading.
6764 @orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored}
6765 Jump to the location where @code{org-refile} last moved a tree to.
6766 @item C-2 C-c C-w
6767 Refile as the child of the item currently being clocked.
6768 @item C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w
6770 @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}
6772 Clear the target cache.  Caching of refile targets can be turned on by
6773 setting @code{org-refile-use-cache}.  To make the command see new possible
6774 targets, you have to clear the cache with this command.
6775 @end table
6777 @node Archiving,  , Refiling notes, Capture - Refile - Archive
6778 @section Archiving
6779 @cindex archiving
6781 When a project represented by a (sub)tree is finished, you may want
6782 to move the tree out of the way and to stop it from contributing to the
6783 agenda.  Archiving is important to keep your working files compact and global
6784 searches like the construction of agenda views fast.
6786 @table @kbd
6787 @orgcmd{C-c C-x C-a,org-archive-subtree-default}
6788 @vindex org-archive-default-command
6789 Archive the current entry using the command specified in the variable
6790 @code{org-archive-default-command}.
6791 @end table
6793 @menu
6794 * Moving subtrees::             Moving a tree to an archive file
6795 * Internal archiving::          Switch off a tree but keep it in the file
6796 @end menu
6798 @node Moving subtrees, Internal archiving, Archiving, Archiving
6799 @subsection Moving a tree to the archive file
6800 @cindex external archiving
6802 The most common archiving action is to move a project tree to another file,
6803 the archive file.
6805 @table @kbd
6806 @orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
6807 @vindex org-archive-location
6808 Archive the subtree starting at the cursor position to the location
6809 given by @code{org-archive-location}.
6810 @orgkey{C-u C-c C-x C-s}
6811 Check if any direct children of the current headline could be moved to
6812 the archive.  To do this, each subtree is checked for open TODO entries.
6813 If none are found, the command offers to move it to the archive
6814 location.  If the cursor is @emph{not} on a headline when this command
6815 is invoked, the level 1 trees will be checked.
6816 @end table
6818 @cindex archive locations
6819 The default archive location is a file in the same directory as the
6820 current file, with the name derived by appending @file{_archive} to the
6821 current file name.  For information and examples on how to change this,
6822 see the documentation string of the variable
6823 @code{org-archive-location}.  There is also an in-buffer option for
6824 setting this variable, for example@footnote{For backward compatibility,
6825 the following also works: If there are several such lines in a file,
6826 each specifies the archive location for the text below it.  The first
6827 such line also applies to any text before its definition.  However,
6828 using this method is @emph{strongly} deprecated as it is incompatible
6829 with the outline structure of the document.  The correct method for
6830 setting multiple archive locations in a buffer is using properties.}:
6832 @cindex #+ARCHIVE
6833 @example
6834 #+ARCHIVE: %s_done::
6835 @end example
6837 @cindex property, ARCHIVE
6838 @noindent
6839 If you would like to have a special ARCHIVE location for a single entry
6840 or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
6841 location as the value (@pxref{Properties and Columns}).
6843 @vindex org-archive-save-context-info
6844 When a subtree is moved, it receives a number of special properties that
6845 record context information like the file from where the entry came, its
6846 outline path the archiving time etc.  Configure the variable
6847 @code{org-archive-save-context-info} to adjust the amount of information
6848 added.
6851 @node Internal archiving,  , Moving subtrees, Archiving
6852 @subsection Internal archiving
6854 If you want to just switch off (for agenda views) certain subtrees without
6855 moving them to a different file, you can use the @code{ARCHIVE tag}.
6857 A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
6858 its location in the outline tree, but behaves in the following way:
6859 @itemize @minus
6860 @item
6861 @vindex org-cycle-open-archived-trees
6862 It does not open when you attempt to do so with a visibility cycling
6863 command (@pxref{Visibility cycling}).  You can force cycling archived
6864 subtrees with @kbd{C-@key{TAB}}, or by setting the option
6865 @code{org-cycle-open-archived-trees}.  Also normal outline commands like
6866 @code{show-all} will open archived subtrees.
6867 @item
6868 @vindex org-sparse-tree-open-archived-trees
6869 During sparse tree construction (@pxref{Sparse trees}), matches in
6870 archived subtrees are not exposed, unless you configure the option
6871 @code{org-sparse-tree-open-archived-trees}.
6872 @item
6873 @vindex org-agenda-skip-archived-trees
6874 During agenda view construction (@pxref{Agenda Views}), the content of
6875 archived trees is ignored unless you configure the option
6876 @code{org-agenda-skip-archived-trees}, in which case these trees will always
6877 be included.  In the agenda you can press @kbd{v a} to get archives
6878 temporarily included.
6879 @item
6880 @vindex org-export-with-archived-trees
6881 Archived trees are not exported (@pxref{Exporting}), only the headline
6882 is.  Configure the details using the variable
6883 @code{org-export-with-archived-trees}.
6884 @item
6885 @vindex org-columns-skip-archived-trees
6886 Archived trees are excluded from column view unless the variable
6887 @code{org-columns-skip-archived-trees} is configured to @code{nil}.
6888 @end itemize
6890 The following commands help manage the ARCHIVE tag:
6892 @table @kbd
6893 @orgcmd{C-c C-x a,org-toggle-archive-tag}
6894 Toggle the ARCHIVE tag for the current headline.  When the tag is set,
6895 the headline changes to a shadowed face, and the subtree below it is
6896 hidden.
6897 @orgkey{C-u C-c C-x a}
6898 Check if any direct children of the current headline should be archived.
6899 To do this, each subtree is checked for open TODO entries.  If none are
6900 found, the command offers to set the ARCHIVE tag for the child.  If the
6901 cursor is @emph{not} on a headline when this command is invoked, the
6902 level 1 trees will be checked.
6903 @orgcmd{C-@kbd{TAB},org-force-cycle-archived}
6904 Cycle a tree even if it is tagged with ARCHIVE.
6905 @orgcmd{C-c C-x A,org-archive-to-archive-sibling}
6906 Move the current entry to the @emph{Archive Sibling}.  This is a sibling of
6907 the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}.  The
6908 entry becomes a child of that sibling and in this way retains a lot of its
6909 original context, including inherited tags and approximate position in the
6910 outline.
6911 @end table
6914 @node Agenda Views, Markup, Capture - Refile - Archive, Top
6915 @chapter Agenda views
6916 @cindex agenda views
6918 Due to the way Org works, TODO items, time-stamped items, and
6919 tagged headlines can be scattered throughout a file or even a number of
6920 files.  To get an overview of open action items, or of events that are
6921 important for a particular date, this information must be collected,
6922 sorted and displayed in an organized way.
6924 Org can select items based on various criteria and display them
6925 in a separate buffer.  Seven different view types are provided:
6927 @itemize @bullet
6928 @item
6929 an @emph{agenda} that is like a calendar and shows information
6930 for specific dates,
6931 @item
6932 a @emph{TODO list} that covers all unfinished
6933 action items,
6934 @item
6935 a @emph{match view}, showings headlines based on the tags, properties, and
6936 TODO state associated with them,
6937 @item
6938 a @emph{timeline view} that shows all events in a single Org file,
6939 in time-sorted view,
6940 @item
6941 a @emph{text search view} that shows all entries from multiple files
6942 that contain specified keywords,
6943 @item
6944 a @emph{stuck projects view} showing projects that currently don't move
6945 along, and
6946 @item
6947 @emph{custom views} that are special searches and combinations of different
6948 views.
6949 @end itemize
6951 @noindent
6952 The extracted information is displayed in a special @emph{agenda
6953 buffer}.  This buffer is read-only, but provides commands to visit the
6954 corresponding locations in the original Org files, and even to
6955 edit these files remotely.
6957 @vindex org-agenda-window-setup
6958 @vindex org-agenda-restore-windows-after-quit
6959 Two variables control how the agenda buffer is displayed and whether the
6960 window configuration is restored when the agenda exits:
6961 @code{org-agenda-window-setup} and
6962 @code{org-agenda-restore-windows-after-quit}.
6964 @menu
6965 * Agenda files::                Files being searched for agenda information
6966 * Agenda dispatcher::           Keyboard access to agenda views
6967 * Built-in agenda views::       What is available out of the box?
6968 * Presentation and sorting::    How agenda items are prepared for display
6969 * Agenda commands::             Remote editing of Org trees
6970 * Custom agenda views::         Defining special searches and views
6971 * Exporting Agenda Views::      Writing a view to a file
6972 * Agenda column view::          Using column view for collected entries
6973 @end menu
6975 @node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views
6976 @section Agenda files
6977 @cindex agenda files
6978 @cindex files for agenda
6980 @vindex org-agenda-files
6981 The information to be shown is normally collected from all @emph{agenda
6982 files}, the files listed in the variable
6983 @code{org-agenda-files}@footnote{If the value of that variable is not a
6984 list, but a single file name, then the list of agenda files will be
6985 maintained in that external file.}.  If a directory is part of this list,
6986 all files with the extension @file{.org} in this directory will be part
6987 of the list.
6989 Thus, even if you only work with a single Org file, that file should
6990 be put into the list@footnote{When using the dispatcher, pressing
6991 @kbd{<} before selecting a command will actually limit the command to
6992 the current file, and ignore @code{org-agenda-files} until the next
6993 dispatcher command.}.  You can customize @code{org-agenda-files}, but
6994 the easiest way to maintain it is through the following commands
6996 @cindex files, adding to agenda list
6997 @table @kbd
6998 @orgcmd{C-c [,org-agenda-file-to-front}
6999 Add current file to the list of agenda files.  The file is added to
7000 the front of the list.  If it was already in the list, it is moved to
7001 the front.  With a prefix argument, file is added/moved to the end.
7002 @orgcmd{C-c ],org-remove-file}
7003 Remove current file from the list of agenda files.
7004 @kindex C-,
7005 @orgcmd{C-',org-cycle-agenda-files}
7006 @itemx C-,
7007 Cycle through agenda file list, visiting one file after the other.
7008 @kindex M-x org-iswitchb
7009 @item M-x org-iswitchb
7010 Command to use an @code{iswitchb}-like interface to switch to and between Org
7011 buffers.
7012 @end table
7014 @noindent
7015 The Org menu contains the current list of files and can be used
7016 to visit any of them.
7018 If you would like to focus the agenda temporarily on a file not in
7019 this list, or on just one file in the list, or even on only a subtree in a
7020 file, then this can be done in different ways.  For a single agenda command,
7021 you may press @kbd{<} once or several times in the dispatcher
7022 (@pxref{Agenda dispatcher}).  To restrict the agenda scope for an
7023 extended period, use the following commands:
7025 @table @kbd
7026 @orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
7027 Permanently restrict the agenda to the current subtree.  When with a
7028 prefix argument, or with the cursor before the first headline in a file,
7029 the agenda scope is set to the entire file.  This restriction remains in
7030 effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
7031 or @kbd{>} in the agenda dispatcher.  If there is a window displaying an
7032 agenda view, the new restriction takes effect immediately.
7033 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
7034 Remove the permanent restriction created by @kbd{C-c C-x <}.
7035 @end table
7037 @noindent
7038 When working with @file{speedbar.el}, you can use the following commands in
7039 the Speedbar frame:
7040 @table @kbd
7041 @orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
7042 Permanently restrict the agenda to the item---either an Org file or a subtree
7043 in such a file---at the cursor in the Speedbar frame.
7044 If there is a window displaying an agenda view, the new restriction takes
7045 effect immediately.
7046 @orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
7047 Lift the restriction.
7048 @end table
7050 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views
7051 @section The agenda dispatcher
7052 @cindex agenda dispatcher
7053 @cindex dispatching agenda commands
7054 The views are created through a dispatcher, which should be bound to a
7055 global key---for example @kbd{C-c a} (@pxref{Activation}).  In the
7056 following we will assume that @kbd{C-c a} is indeed how the dispatcher
7057 is accessed and list keyboard access to commands accordingly.  After
7058 pressing @kbd{C-c a}, an additional letter is required to execute a
7059 command.  The dispatcher offers the following default commands:
7060 @table @kbd
7061 @item a
7062 Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
7063 @item t @r{/} T
7064 Create a list of all TODO items (@pxref{Global TODO list}).
7065 @item m @r{/} M
7066 Create a list of headlines matching a TAGS expression (@pxref{Matching
7067 tags and properties}).
7068 @item L
7069 Create the timeline view for the current buffer (@pxref{Timeline}).
7070 @item s
7071 Create a list of entries selected by a boolean expression of keywords
7072 and/or regular expressions that must or must not occur in the entry.
7073 @item /
7074 @vindex org-agenda-text-search-extra-files
7075 Search for a regular expression in all agenda files and additionally in
7076 the files listed in @code{org-agenda-text-search-extra-files}.  This
7077 uses the Emacs command @code{multi-occur}.  A prefix argument can be
7078 used to specify the number of context lines for each match, default is
7080 @item # @r{/} !
7081 Create a list of stuck projects (@pxref{Stuck projects}).
7082 @item <
7083 Restrict an agenda command to the current buffer@footnote{For backward
7084 compatibility, you can also press @kbd{1} to restrict to the current
7085 buffer.}.  After pressing @kbd{<}, you still need to press the character
7086 selecting the command.
7087 @item < <
7088 If there is an active region, restrict the following agenda command to
7089 the region.  Otherwise, restrict it to the current subtree@footnote{For
7090 backward compatibility, you can also press @kbd{0} to restrict to the
7091 current region/subtree.}.  After pressing @kbd{< <}, you still need to press the
7092 character selecting the command.
7093 @end table
7095 You can also define custom commands that will be accessible through the
7096 dispatcher, just like the default commands.  This includes the
7097 possibility to create extended agenda buffers that contain several
7098 blocks together, for example the weekly agenda, the global TODO list and
7099 a number of special tags matches.  @xref{Custom agenda views}.
7101 @node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda Views
7102 @section The built-in agenda views
7104 In this section we describe the built-in views.
7106 @menu
7107 * Weekly/daily agenda::         The calendar page with current tasks
7108 * Global TODO list::            All unfinished action items
7109 * Matching tags and properties::  Structured information with fine-tuned search
7110 * Timeline::                    Time-sorted view for single file
7111 * Search view::                 Find entries by searching for text
7112 * Stuck projects::              Find projects you need to review
7113 @end menu
7115 @node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
7116 @subsection The weekly/daily agenda
7117 @cindex agenda
7118 @cindex weekly agenda
7119 @cindex daily agenda
7121 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
7122 paper agenda, showing all the tasks for the current week or day.
7124 @table @kbd
7125 @cindex org-agenda, command
7126 @orgcmd{C-c a a,org-agenda-list}
7127 Compile an agenda for the current week from a list of Org files.  The agenda
7128 shows the entries for each day.  With a numeric prefix@footnote{For backward
7129 compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be
7130 listed before the agenda.  This feature is deprecated, use the dedicated TODO
7131 list, or a block agenda instead (@pxref{Block agenda}).}  (like @kbd{C-u 2 1
7132 C-c a a}) you may set the number of days to be displayed.
7133 @end table
7135 @vindex org-agenda-span
7136 @vindex org-agenda-ndays
7137 The default number of days displayed in the agenda is set by the variable
7138 @code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}).  This
7139 variable can be set to any number of days you want to see by default in the
7140 agenda, or to a span name, such a @code{day}, @code{week}, @code{month} or
7141 @code{year}.
7143 Remote editing from the agenda buffer means, for example, that you can
7144 change the dates of deadlines and appointments from the agenda buffer.
7145 The commands available in the Agenda buffer are listed in @ref{Agenda
7146 commands}.
7148 @subsubheading Calendar/Diary integration
7149 @cindex calendar integration
7150 @cindex diary integration
7152 Emacs contains the calendar and diary by Edward M. Reingold.  The
7153 calendar displays a three-month calendar with holidays from different
7154 countries and cultures.  The diary allows you to keep track of
7155 anniversaries, lunar phases, sunrise/set, recurrent appointments
7156 (weekly, monthly) and more.  In this way, it is quite complementary to
7157 Org.  It can be very useful to combine output from Org with
7158 the diary.
7160 In order to include entries from the Emacs diary into Org-mode's
7161 agenda, you only need to customize the variable
7163 @lisp
7164 (setq org-agenda-include-diary t)
7165 @end lisp
7167 @noindent After that, everything will happen automatically.  All diary
7168 entries including holidays, anniversaries, etc., will be included in the
7169 agenda buffer created by Org-mode.  @key{SPC}, @key{TAB}, and
7170 @key{RET} can be used from the agenda buffer to jump to the diary
7171 file in order to edit existing diary entries.  The @kbd{i} command to
7172 insert new entries for the current date works in the agenda buffer, as
7173 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
7174 Sunrise/Sunset times, show lunar phases and to convert to other
7175 calendars, respectively.  @kbd{c} can be used to switch back and forth
7176 between calendar and agenda.
7178 If you are using the diary only for sexp entries and holidays, it is
7179 faster to not use the above setting, but instead to copy or even move
7180 the entries into an Org file.  Org-mode evaluates diary-style sexp
7181 entries, and does it faster because there is no overhead for first
7182 creating the diary display.  Note that the sexp entries must start at
7183 the left margin, no whitespace is allowed before them.  For example,
7184 the following segment of an Org file will be processed and entries
7185 will be made in the agenda:
7187 @example
7188 * Birthdays and similar stuff
7189 #+CATEGORY: Holiday
7190 %%(org-calendar-holiday)   ; special function for holiday names
7191 #+CATEGORY: Ann
7192 %%(org-anniversary 1956  5 14)@footnote{@code{org-anniversary} is just like @code{diary-anniversary}, but the argument order is allways according to ISO and therefore independent of the value of @code{calendar-date-style}.} Arthur Dent is %d years old
7193 %%(org-anniversary 1869 10  2) Mahatma Gandhi would be %d years old
7194 @end example
7196 @subsubheading Anniversaries from BBDB
7197 @cindex BBDB, anniversaries
7198 @cindex anniversaries, from BBDB
7200 If you are using the Big Brothers Database to store your contacts, you will
7201 very likely prefer to store anniversaries in BBDB rather than in a
7202 separate Org or diary file.  Org supports this and will show BBDB
7203 anniversaries as part of the agenda.  All you need to do is to add the
7204 following to one your your agenda files:
7206 @example
7207 * Anniversaries
7208   :PROPERTIES:
7209   :CATEGORY: Anniv
7210   :END:
7211 %%(org-bbdb-anniversaries)
7212 @end example
7214 You can then go ahead and define anniversaries for a BBDB record.  Basically,
7215 you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
7216 record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
7217 followed by a space and the class of the anniversary (@samp{birthday} or
7218 @samp{wedding}, or a format string).  If you omit the class, it will default to
7219 @samp{birthday}.  Here are a few examples, the header for the file
7220 @file{org-bbdb.el} contains more detailed information.
7222 @example
7223 1973-06-22
7224 06-22
7225 1955-08-02 wedding
7226 2008-04-14 %s released version 6.01 of org-mode, %d years ago
7227 @end example
7229 After a change to BBDB, or for the first agenda display during an Emacs
7230 session, the agenda display will suffer a short delay as Org updates its
7231 hash with anniversaries.  However, from then on things will be very fast---much
7232 faster in fact than a long list of @samp{%%(diary-anniversary)} entries
7233 in an Org or Diary file.
7235 @subsubheading Appointment reminders
7236 @cindex @file{appt.el}
7237 @cindex appointment reminders
7239 Org can interact with Emacs appointments notification facility.  To add all
7240 the appointments of your agenda files, use the command
7241 @code{org-agenda-to-appt}.  This command also lets you filter through the
7242 list of your appointments and add only those belonging to a specific category
7243 or matching a regular expression.  See the docstring for details.
7245 @node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views
7246 @subsection The global TODO list
7247 @cindex global TODO list
7248 @cindex TODO list, global
7250 The global TODO list contains all unfinished TODO items formatted and
7251 collected into a single place.
7253 @table @kbd
7254 @orgcmd{C-c a t,org-todo-list}
7255 Show the global TODO list.  This collects the TODO items from all agenda
7256 files (@pxref{Agenda Views}) into a single buffer.  By default, this lists
7257 items with a state the is not a DONE state.  The buffer is in
7258 @code{agenda-mode}, so there are commands to examine and manipulate the TODO
7259 entries directly from that buffer (@pxref{Agenda commands}).
7260 @orgcmd{C-c a T,org-todo-list}
7261 @cindex TODO keyword matching
7262 @vindex org-todo-keywords
7263 Like the above, but allows selection of a specific TODO keyword.  You can
7264 also do this by specifying a prefix argument to @kbd{C-c a t}.  You are
7265 prompted for a keyword, and you may also specify several keywords by
7266 separating them with @samp{|} as the boolean OR operator.  With a numeric
7267 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
7268 @kindex r
7269 The @kbd{r} key in the agenda buffer regenerates it, and you can give
7270 a prefix argument to this command to change the selected TODO keyword,
7271 for example @kbd{3 r}.  If you often need a search for a specific
7272 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
7273 Matching specific TODO keywords can also be done as part of a tags
7274 search (@pxref{Tag searches}).
7275 @end table
7277 Remote editing of TODO items means that you can change the state of a
7278 TODO entry with a single key press.  The commands available in the
7279 TODO list are described in @ref{Agenda commands}.
7281 @cindex sublevels, inclusion into TODO list
7282 Normally the global TODO list simply shows all headlines with TODO
7283 keywords.  This list can become very long.  There are two ways to keep
7284 it more compact:
7285 @itemize @minus
7286 @item
7287 @vindex org-agenda-todo-ignore-scheduled
7288 @vindex org-agenda-todo-ignore-deadlines
7289 @vindex org-agenda-todo-ignore-timestamp
7290 @vindex org-agenda-todo-ignore-with-date
7291 Some people view a TODO item that has been @emph{scheduled} for execution or
7292 have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.
7293 Configure the variables @code{org-agenda-todo-ignore-scheduled},
7294 @code{org-agenda-todo-ignore-deadlines},
7295 @code{org-agenda-todo-ignore-timestamp} and/or
7296 @code{org-agenda-todo-ignore-with-date} to exclude such items from the global
7297 TODO list.
7298 @item
7299 @vindex org-agenda-todo-list-sublevels
7300 TODO items may have sublevels to break up the task into subtasks.  In
7301 such cases it may be enough to list only the highest level TODO headline
7302 and omit the sublevels from the global list.  Configure the variable
7303 @code{org-agenda-todo-list-sublevels} to get this behavior.
7304 @end itemize
7306 @node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views
7307 @subsection Matching tags and properties
7308 @cindex matching, of tags
7309 @cindex matching, of properties
7310 @cindex tags view
7311 @cindex match view
7313 If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
7314 or have properties (@pxref{Properties and Columns}), you can select headlines
7315 based on this metadata and collect them into an agenda buffer.  The match
7316 syntax described here also applies when creating sparse trees with @kbd{C-c /
7319 @table @kbd
7320 @orgcmd{C-c a m,org-tags-view}
7321 Produce a list of all headlines that match a given set of tags.  The
7322 command prompts for a selection criterion, which is a boolean logic
7323 expression with tags, like @samp{+work+urgent-withboss} or
7324 @samp{work|home} (@pxref{Tags}).  If you often need a specific search,
7325 define a custom command for it (@pxref{Agenda dispatcher}).
7326 @orgcmd{C-c a M,org-tags-view}
7327 @vindex org-tags-match-list-sublevels
7328 @vindex org-agenda-tags-todo-honor-ignore-options
7329 Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
7330 not-DONE state and force checking subitems (see variable
7331 @code{org-tags-match-list-sublevels}).  To exclude scheduled/deadline items,
7332 see the variable @code{org-agenda-tags-todo-honor-ignore-options}.  Matching
7333 specific TODO keywords together with a tags match is also possible, see
7334 @ref{Tag searches}.
7335 @end table
7337 The commands available in the tags list are described in @ref{Agenda
7338 commands}.
7340 @subsubheading Match syntax
7342 @cindex Boolean logic, for tag/property searches
7343 A search string can use Boolean operators @samp{&} for AND and @samp{|} for
7344 OR.  @samp{&} binds more strongly than @samp{|}.  Parentheses are currently
7345 not implemented.  Each element in the search is either a tag, a regular
7346 expression matching tags, or an expression like @code{PROPERTY OPERATOR
7347 VALUE} with a comparison operator, accessing a property value.  Each element
7348 may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic
7349 sugar for positive selection.  The AND operator @samp{&} is optional when
7350 @samp{+} or @samp{-} is present.  Here are some examples, using only tags.
7352 @table @samp
7353 @item +work-boss
7354 Select headlines tagged @samp{:work:}, but discard those also tagged
7355 @samp{:boss:}.
7356 @item work|laptop
7357 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
7358 @item work|laptop+night
7359 Like before, but require the @samp{:laptop:} lines to be tagged also
7360 @samp{:night:}.
7361 @end table
7363 @cindex regular expressions, with tags search
7364 Instead of a tag, you may also specify a regular expression enclosed in curly
7365 braces.  For example,
7366 @samp{work+@{^boss.*@}} matches headlines that contain the tag
7367 @samp{:work:} and any tag @i{starting} with @samp{boss}.
7369 @cindex TODO keyword matching, with tags search
7370 @cindex level, require for tags/property match
7371 @cindex category, require for tags/property match
7372 @vindex org-odd-levels-only
7373 You may also test for properties (@pxref{Properties and Columns}) at the same
7374 time as matching tags.  The properties may be real properties, or special
7375 properties that represent other metadata (@pxref{Special properties}).  For
7376 example, the ``property'' @code{TODO} represents the TODO keyword of the
7377 entry.  Or, the ``property'' @code{LEVEL} represents the level of an entry.
7378 So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines
7379 that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword
7380 DONE.  In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not
7381 count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
7383 Here are more examples:
7384 @table @samp
7385 @item work+TODO="WAITING"
7386 Select @samp{:work:}-tagged TODO lines with the specific TODO
7387 keyword @samp{WAITING}.
7388 @item work+TODO="WAITING"|home+TODO="WAITING"
7389 Waiting tasks both at work and at home.
7390 @end table
7392 When matching properties, a number of different operators can be used to test
7393 the value of a property.  Here is a complex example:
7395 @example
7396 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2         \
7397          +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
7398 @end example
7400 @noindent
7401 The type of comparison will depend on how the comparison value is written:
7402 @itemize @minus
7403 @item
7404 If the comparison value is a plain number, a numerical comparison is done,
7405 and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
7406 @samp{>=}, and @samp{<>}.
7407 @item
7408 If the comparison value is enclosed in double-quotes,
7409 a string comparison is done, and the same operators are allowed.
7410 @item
7411 If the comparison value is enclosed in double-quotes @emph{and} angular
7412 brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
7413 assumed to be date/time specifications in the standard Org way, and the
7414 comparison will be done accordingly.  Special values that will be recognized
7415 are @code{"<now>"} for now (including time), and @code{"<today>"}, and
7416 @code{"<tomorrow>"} for these days at 0:00 hours, i.e.@: without a time
7417 specification.  Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
7418 @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
7419 respectively, can be used.
7420 @item
7421 If the comparison value is enclosed
7422 in curly braces, a regexp match is performed, with @samp{=} meaning that the
7423 regexp matches the property value, and @samp{<>} meaning that it does not
7424 match.
7425 @end itemize
7427 So the search string in the example finds entries tagged @samp{:work:} but
7428 not @samp{:boss:}, which also have a priority value @samp{A}, a
7429 @samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
7430 property that is numerically smaller than 2, a @samp{:With:} property that is
7431 matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
7432 on or after October 11, 2008.
7434 Accessing TODO, LEVEL, and CATEGORY during a search is fast.  Accessing any
7435 other properties will slow down the search.  However, once you have paid the
7436 price by accessing one property, testing additional properties is cheap
7437 again.
7439 You can configure Org-mode to use property inheritance during a search, but
7440 beware that this can slow down searches considerably.  See @ref{Property
7441 inheritance}, for details.
7443 For backward compatibility, and also for typing speed, there is also a
7444 different way to test TODO states in a search.  For this, terminate the
7445 tags/property part of the search string (which may include several terms
7446 connected with @samp{|}) with a @samp{/} and then specify a Boolean
7447 expression just for TODO keywords.  The syntax is then similar to that for
7448 tags, but should be applied with care: for example, a positive selection on
7449 several TODO keywords cannot meaningfully be combined with boolean AND.
7450 However, @emph{negative selection} combined with AND can be meaningful.  To
7451 make sure that only lines are checked that actually have any TODO keyword
7452 (resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
7453 part after the slash with @samp{!}.  Using @kbd{C-c a M} or @samp{/!} will
7454 not match TODO keywords in a DONE state.  Examples:
7456 @table @samp
7457 @item work/WAITING
7458 Same as @samp{work+TODO="WAITING"}
7459 @item work/!-WAITING-NEXT
7460 Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
7461 nor @samp{NEXT}
7462 @item work/!+WAITING|+NEXT
7463 Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
7464 @samp{NEXT}.
7465 @end table
7467 @node Timeline, Search view, Matching tags and properties, Built-in agenda views
7468 @subsection Timeline for a single file
7469 @cindex timeline, single file
7470 @cindex time-sorted view
7472 The timeline summarizes all time-stamped items from a single Org-mode
7473 file in a @emph{time-sorted view}.  The main purpose of this command is
7474 to give an overview over events in a project.
7476 @table @kbd
7477 @orgcmd{C-c a L,org-timeline}
7478 Show a time-sorted view of the Org file, with all time-stamped items.
7479 When called with a @kbd{C-u} prefix, all unfinished TODO entries
7480 (scheduled or not) are also listed under the current date.
7481 @end table
7483 @noindent
7484 The commands available in the timeline buffer are listed in
7485 @ref{Agenda commands}.
7487 @node Search view, Stuck projects, Timeline, Built-in agenda views
7488 @subsection Search view
7489 @cindex search view
7490 @cindex text search
7491 @cindex searching, for text
7493 This agenda view is a general text search facility for Org-mode entries.
7494 It is particularly useful to find notes.
7496 @table @kbd
7497 @orgcmd{C-c a s,org-search-view}
7498 This is a special search that lets you select entries by matching a substring
7499 or specific words using a boolean logic.
7500 @end table
7501 For example, the search string @samp{computer equipment} will find entries
7502 that contain @samp{computer equipment} as a substring.  If the two words are
7503 separated by more space or a line break, the search will still match.
7504 Search view can also search for specific keywords in the entry, using Boolean
7505 logic.  The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
7506 will search for note entries that contain the keywords @code{computer}
7507 and @code{wifi}, but not the keyword @code{ethernet}, and which are also
7508 not matched by the regular expression @code{8\.11[bg]}, meaning to
7509 exclude both 8.11b and 8.11g.  The first @samp{+} is necessary to turn on
7510 word search, other @samp{+} characters are optional.  For more details, see
7511 the docstring of the command @code{org-search-view}.
7513 @vindex org-agenda-text-search-extra-files
7514 Note that in addition to the agenda files, this command will also search
7515 the files listed in @code{org-agenda-text-search-extra-files}.
7517 @node Stuck projects,  , Search view, Built-in agenda views
7518 @subsection Stuck projects
7519 @pindex GTD, Getting Things Done
7521 If you are following a system like David Allen's GTD to organize your
7522 work, one of the ``duties'' you have is a regular review to make sure
7523 that all projects move along.  A @emph{stuck} project is a project that
7524 has no defined next actions, so it will never show up in the TODO lists
7525 Org-mode produces.  During the review, you need to identify such
7526 projects and define next actions for them.
7528 @table @kbd
7529 @orgcmd{C-c a #,org-agenda-list-stuck-projects}
7530 List projects that are stuck.
7531 @kindex C-c a !
7532 @item C-c a !
7533 @vindex org-stuck-projects
7534 Customize the variable @code{org-stuck-projects} to define what a stuck
7535 project is and how to find it.
7536 @end table
7538 You almost certainly will have to configure this view before it will
7539 work for you.  The built-in default assumes that all your projects are
7540 level-2 headlines, and that a project is not stuck if it has at least
7541 one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
7543 Let's assume that you, in your own way of using Org-mode, identify
7544 projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
7545 indicate a project that should not be considered yet.  Let's further
7546 assume that the TODO keyword DONE marks finished projects, and that NEXT
7547 and TODO indicate next actions.  The tag @@SHOP indicates shopping and
7548 is a next action even without the NEXT tag.  Finally, if the project
7549 contains the special word IGNORE anywhere, it should not be listed
7550 either.  In this case you would start by identifying eligible projects
7551 with a tags/todo match@footnote{@xref{Tag searches}.}
7552 @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, and
7553 IGNORE in the subtree to identify projects that are not stuck.  The
7554 correct customization for this is
7556 @lisp
7557 (setq org-stuck-projects
7558       '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
7559                                "\\<IGNORE\\>"))
7560 @end lisp
7562 Note that if a project is identified as non-stuck, the subtree of this entry
7563 will still be searched for stuck projects.
7565 @node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda Views
7566 @section Presentation and sorting
7567 @cindex presentation, of agenda items
7569 @vindex org-agenda-prefix-format
7570 @vindex org-agenda-tags-column
7571 Before displaying items in an agenda view, Org-mode visually prepares the
7572 items and sorts them.  Each item occupies a single line.  The line starts
7573 with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
7574 of the item and other important information.  You can customize in which
7575 column tags will be displayed through @code{org-agenda-tags-column}.  You can
7576 also customize the prefix using the option @code{org-agenda-prefix-format}.
7577 This prefix is followed by a cleaned-up version of the outline headline
7578 associated with the item.
7580 @menu
7581 * Categories::                  Not all tasks are equal
7582 * Time-of-day specifications::  How the agenda knows the time
7583 * Sorting of agenda items::     The order of things
7584 @end menu
7586 @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
7587 @subsection Categories
7589 @cindex category
7590 @cindex #+CATEGORY
7591 The category is a broad label assigned to each agenda item.  By default,
7592 the category is simply derived from the file name, but you can also
7593 specify it with a special line in the buffer, like this@footnote{For
7594 backward compatibility, the following also works: if there are several
7595 such lines in a file, each specifies the category for the text below it.
7596 The first category also applies to any text before the first CATEGORY
7597 line.  However, using this method is @emph{strongly} deprecated as it is
7598 incompatible with the outline structure of the document.  The correct
7599 method for setting multiple categories in a buffer is using a
7600 property.}:
7602 @example
7603 #+CATEGORY: Thesis
7604 @end example
7606 @noindent
7607 @cindex property, CATEGORY
7608 If you would like to have a special CATEGORY for a single entry or a
7609 (sub)tree, give the entry a @code{:CATEGORY:} property with the
7610 special category you want to apply as the value.
7612 @noindent
7613 The display in the agenda buffer looks best if the category is not
7614 longer than 10 characters.
7616 @noindent
7617 You can set up icons for category by customizing the
7618 @code{org-agenda-category-icon-alist} variable.
7620 @node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
7621 @subsection Time-of-day specifications
7622 @cindex time-of-day specification
7624 Org-mode checks each agenda item for a time-of-day specification.  The
7625 time can be part of the timestamp that triggered inclusion into the
7626 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}.  Time
7627 ranges can be specified with two timestamps, like
7629 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
7631 In the headline of the entry itself, a time(range) may also appear as
7632 plain text (like @samp{12:45} or a @samp{8:30-1pm}).  If the agenda
7633 integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
7634 specifications in diary entries are recognized as well.
7636 For agenda display, Org-mode extracts the time and displays it in a
7637 standard 24 hour format as part of the prefix.  The example times in
7638 the previous paragraphs would end up in the agenda like this:
7640 @example
7641     8:30-13:00 Arthur Dent lies in front of the bulldozer
7642    12:45...... Ford Prefect arrives and takes Arthur to the pub
7643    19:00...... The Vogon reads his poem
7644    20:30-22:15 Marvin escorts the Hitchhikers to the bridge
7645 @end example
7647 @cindex time grid
7648 If the agenda is in single-day mode, or for the display of today, the
7649 timed entries are embedded in a time grid, like
7651 @example
7652     8:00...... ------------------
7653     8:30-13:00 Arthur Dent lies in front of the bulldozer
7654    10:00...... ------------------
7655    12:00...... ------------------
7656    12:45...... Ford Prefect arrives and takes Arthur to the pub
7657    14:00...... ------------------
7658    16:00...... ------------------
7659    18:00...... ------------------
7660    19:00...... The Vogon reads his poem
7661    20:00...... ------------------
7662    20:30-22:15 Marvin escorts the Hitchhikers to the bridge
7663 @end example
7665 @vindex org-agenda-use-time-grid
7666 @vindex org-agenda-time-grid
7667 The time grid can be turned on and off with the variable
7668 @code{org-agenda-use-time-grid}, and can be configured with
7669 @code{org-agenda-time-grid}.
7671 @node Sorting of agenda items,  , Time-of-day specifications, Presentation and sorting
7672 @subsection Sorting of agenda items
7673 @cindex sorting, of agenda items
7674 @cindex priorities, of agenda items
7675 Before being inserted into a view, the items are sorted.  How this is
7676 done depends on the type of view.
7677 @itemize @bullet
7678 @item
7679 @vindex org-agenda-files
7680 For the daily/weekly agenda, the items for each day are sorted.  The
7681 default order is to first collect all items containing an explicit
7682 time-of-day specification.  These entries will be shown at the beginning
7683 of the list, as a @emph{schedule} for the day.  After that, items remain
7684 grouped in categories, in the sequence given by @code{org-agenda-files}.
7685 Within each category, items are sorted by priority (@pxref{Priorities}),
7686 which is composed of the base priority (2000 for priority @samp{A}, 1000
7687 for @samp{B}, and 0 for @samp{C}), plus additional increments for
7688 overdue scheduled or deadline items.
7689 @item
7690 For the TODO list, items remain in the order of categories, but within
7691 each category, sorting takes place according to priority
7692 (@pxref{Priorities}).  The priority used for sorting derives from the
7693 priority cookie, with additions depending on how close an item is to its due
7694 or scheduled date.
7695 @item
7696 For tags matches, items are not sorted at all, but just appear in the
7697 sequence in which they are found in the agenda files.
7698 @end itemize
7700 @vindex org-agenda-sorting-strategy
7701 Sorting can be customized using the variable
7702 @code{org-agenda-sorting-strategy}, and may also include criteria based on
7703 the estimated effort of an entry (@pxref{Effort estimates}).
7705 @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views
7706 @section Commands in the agenda buffer
7707 @cindex commands, in agenda buffer
7709 Entries in the agenda buffer are linked back to the Org file or diary
7710 file where they originate.  You are not allowed to edit the agenda
7711 buffer itself, but commands are provided to show and jump to the
7712 original entry location, and to edit the Org files ``remotely'' from
7713 the agenda buffer.  In this way, all information is stored only once,
7714 removing the risk that your agenda and note files may diverge.
7716 Some commands can be executed with mouse clicks on agenda lines.  For
7717 the other commands, the cursor needs to be in the desired line.
7719 @table @kbd
7720 @tsubheading{Motion}
7721 @cindex motion commands in agenda
7722 @orgcmd{n,org-agenda-next-line}
7723 Next line (same as @key{up} and @kbd{C-p}).
7724 @orgcmd{p,org-agenda-previous-line}
7725 Previous line (same as @key{down} and @kbd{C-n}).
7726 @tsubheading{View/Go to Org file}
7727 @orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
7728 Display the original location of the item in another window.
7729 With prefix arg, make sure that the entire entry is made visible in the
7730 outline, not only the heading.
7732 @orgcmd{L,org-agenda-recenter}
7733 Display original location and recenter that window.
7735 @orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
7736 Go to the original location of the item in another window.
7738 @orgcmd{@key{RET},org-agenda-switch-to}
7739 Go to the original location of the item and delete other windows.
7741 @orgcmd{F,org-agenda-follow-mode}
7742 @vindex org-agenda-start-with-follow-mode
7743 Toggle Follow mode.  In Follow mode, as you move the cursor through
7744 the agenda buffer, the other window always shows the corresponding
7745 location in the Org file.  The initial setting for this mode in new
7746 agenda buffers can be set with the variable
7747 @code{org-agenda-start-with-follow-mode}.
7749 @orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
7750 Display the entire subtree of the current item in an indirect buffer.  With a
7751 numeric prefix argument N, go up to level N and then take that tree.  If N is
7752 negative, go up that many levels.  With a @kbd{C-u} prefix, do not remove the
7753 previously used indirect buffer.
7755 @orgcmd{C-c C-o,org-agenda-open-link}
7756 Follow a link in the entry.  This will offer a selection of any links in the
7757 text belonging to the referenced Org node.  If there is only one link, it
7758 will be followed without a selection prompt.
7760 @tsubheading{Change display}
7761 @cindex display changing, in agenda
7762 @kindex A
7763 @item A
7764 Interactively select another agenda view and append it to the current view.
7766 @kindex o
7767 @item o
7768 Delete other windows.
7770 @orgcmdkskc{v d,d,org-aganda-day-view}
7771 @xorgcmdkskc{v w,w,org-aganda-day-view}
7772 @xorgcmd{v m,org-agenda-month-view}
7773 @xorgcmd{v y,org-agenda-month-year}
7774 @xorgcmd{v SPC,org-agenda-reset-view}
7775 @vindex org-agenda-span
7776 Switch to day/week/month/year view.  When switching to day or week view, this
7777 setting becomes the default for subsequent agenda refreshes.  Since month and
7778 year views are slow to create, they do not become the default.  A numeric
7779 prefix argument may be used to jump directly to a specific day of the year,
7780 ISO week, month, or year, respectively.  For example, @kbd{32 d} jumps to
7781 February 1st, @kbd{9 w} to ISO week number 9.  When setting day, week, or
7782 month view, a year may be encoded in the prefix argument as well.  For
7783 example, @kbd{200712 w} will jump to week 12 in 2007.  If such a year
7784 specification has only one or two digits, it will be mapped to the interval
7785 1938-2037.  @kbd{v @key{SPC}} will reset to what is set in
7786 @code{org-agenda-span}.
7788 @orgcmd{f,org-agenda-later}
7789 Go forward in time to display the following @code{org-agenda-current-span} days.
7790 For example, if the display covers a week, switch to the following week.
7791 With prefix arg, go forward that many times @code{org-agenda-current-span} days.
7793 @orgcmd{b,org-agenda-earlier}
7794 Go backward in time to display earlier dates.
7796 @orgcmd{.,org-agenda-goto-today}
7797 Go to today.
7799 @orgcmd{j,org-agenda-goto-date}
7800 Prompt for a date and go there.
7802 @orgcmd{J,org-agenda-clock-goto}
7803 Go to the currently clocked-in task @i{in the agenda buffer}.
7805 @orgcmd{D,org-agenda-toggle-diary}
7806 Toggle the inclusion of diary entries.  See @ref{Weekly/daily agenda}.
7808 @orgcmdkskc{v l,l,org-agenda-log-mode}
7809 @kindex v L
7810 @vindex org-log-done
7811 @vindex org-agenda-log-mode-items
7812 Toggle Logbook mode.  In Logbook mode, entries that were marked DONE while
7813 logging was on (variable @code{org-log-done}) are shown in the agenda, as are
7814 entries that have been clocked on that day.  You can configure the entry
7815 types that should be included in log mode using the variable
7816 @code{org-agenda-log-mode-items}.  When called with a @kbd{C-u} prefix, show
7817 all possible logbook entries, including state changes.  When called with two
7818 prefix args @kbd{C-u C-u}, show only logging information, nothing else.
7819 @kbd{v L} is equivalent to @kbd{C-u v l}.
7821 @orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
7822 Include inactive timestamps into the current view.  Only for weekly/daily
7823 agenda and timeline views.
7825 @orgcmd{v a,org-agenda-archives-mode}
7826 @xorgcmd{v A,org-agenda-archives-mode 'files}
7827 Toggle Archives mode.  In Archives mode, trees that are marked
7828 @code{ARCHIVED} are also scanned when producing the agenda.  When you use the
7829 capital @kbd{A}, even all archive files are included.  To exit archives mode,
7830 press @kbd{v a} again.
7832 @orgcmdkskc{v R,R,org-agenda-clockreport-mode}
7833 @vindex org-agenda-start-with-clockreport-mode
7834 Toggle Clockreport mode.  In Clockreport mode, the daily/weekly agenda will
7835 always show a table with the clocked times for the timespan and file scope
7836 covered by the current agenda view.  The initial setting for this mode in new
7837 agenda buffers can be set with the variable
7838 @code{org-agenda-start-with-clockreport-mode}.  By using a prefix argument
7839 when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show
7840 contributions from entries that are hidden by agenda filtering@footnote{Only
7841 tags filtering will be respected here, effort filtering is ignored.}.
7843 @orgkey{v c}
7844 @vindex org-agenda-clock-consistency-checks
7845 Show overlapping clock entries, clocking gaps, and other clocking problems in
7846 the current agenda range.  You can then visit clocking lines and fix them
7847 manually.  See the variable @code{org-agenda-clock-consistency-checks} for
7848 information on how to customize the definition of what constituted a clocking
7849 problem.  To return to normal agenda display, press @kbd{l} to exit Logbook
7850 mode.
7852 @orgcmdkskc{v E,E,org-agenda-entry-text-mode}
7853 @vindex org-agenda-start-with-entry-text-mode
7854 @vindex org-agenda-entry-text-maxlines
7855 Toggle entry text mode.  In entry text mode, a number of lines from the Org
7856 outline node referenced by an agenda line will be displayed below the line.
7857 The maximum number of lines is given by the variable
7858 @code{org-agenda-entry-text-maxlines}.  Calling this command with a numeric
7859 prefix argument will temporarily modify that number to the prefix value.
7861 @orgcmd{G,org-agenda-toggle-time-grid}
7862 @vindex org-agenda-use-time-grid
7863 @vindex org-agenda-time-grid
7864 Toggle the time grid on and off.  See also the variables
7865 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
7867 @orgcmd{r,org-agenda-redo}
7868 Recreate the agenda buffer, for example to reflect the changes after
7869 modification of the timestamps of items with @kbd{S-@key{left}} and
7870 @kbd{S-@key{right}}.  When the buffer is the global TODO list, a prefix
7871 argument is interpreted to create a selective list for a specific TODO
7872 keyword.
7873 @orgcmd{g,org-agenda-redo}
7874 Same as @kbd{r}.
7876 @orgcmdkskc{C-x C-s,s,org-save-all-org-buffers}
7877 Save all Org buffers in the current Emacs session, and also the locations of
7878 IDs.
7880 @orgcmd{C-c C-x C-c,org-agenda-columns}
7881 @vindex org-columns-default-format
7882 Invoke column view (@pxref{Column view}) in the agenda buffer.  The column
7883 view format is taken from the entry at point, or (if there is no entry at
7884 point), from the first entry in the agenda view.  So whatever the format for
7885 that entry would be in the original buffer (taken from a property, from a
7886 @code{#+COLUMNS} line, or from the default variable
7887 @code{org-columns-default-format}), will be used in the agenda.
7889 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
7890 Remove the restriction lock on the agenda, if it is currently restricted to a
7891 file or subtree (@pxref{Agenda files}).
7893 @tsubheading{Secondary filtering and query editing}
7894 @cindex filtering, by tag and effort, in agenda
7895 @cindex tag filtering, in agenda
7896 @cindex effort filtering, in agenda
7897 @cindex query editing, in agenda
7899 @orgcmd{/,org-agenda-filter-by-tag}
7900 @vindex org-agenda-filter-preset
7901 Filter the current agenda view with respect to a tag and/or effort estimates.
7902 The difference between this and a custom agenda command is that filtering is
7903 very fast, so that you can switch quickly between different filters without
7904 having to recreate the agenda.@footnote{Custom commands can preset a filter by
7905 binding the variable @code{org-agenda-filter-preset} as an option.  This
7906 filter will then be applied to the view and persist as a basic filter through
7907 refreshes and more secondary filtering.  The filter is a global property of
7908 the entire agenda view---in a block agenda, you should only set this in the
7909 global options section, not in the section of an individual block.}
7911 You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
7912 all.  Pressing @key{TAB} at that prompt will offer use completion to select a
7913 tag (including any tags that do not have a selection character).  The command
7914 then hides all entries that do not contain or inherit this tag.  When called
7915 with prefix arg, remove the entries that @emph{do} have the tag.  A second
7916 @kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
7917 If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
7918 will be narrowed by requiring or forbidding the selected additional tag.
7919 Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
7920 immediately use the @kbd{\} command.
7922 @vindex org-sort-agenda-noeffort-is-high
7923 In order to filter for effort estimates, you should set up allowed
7924 efforts globally, for example
7925 @lisp
7926 (setq org-global-properties
7927     '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
7928 @end lisp
7929 You can then filter for an effort by first typing an operator, one of
7930 @kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
7931 estimate in your array of allowed values, where @kbd{0} means the 10th value.
7932 The filter will then restrict to entries with effort smaller-or-equal, equal,
7933 or larger-or-equal than the selected value.  If the digits 0-9 are not used
7934 as fast access keys to tags, you can also simply press the index digit
7935 directly without an operator.  In this case, @kbd{<} will be assumed.  For
7936 application of the operator, entries without a defined effort will be treated
7937 according to the value of @code{org-sort-agenda-noeffort-is-high}.  To filter
7938 for tasks without effort definition, press @kbd{?} as the operator.
7940 Org also supports automatic, context-aware tag filtering.  If the variable
7941 @code{org-agenda-auto-exclude-function} is set to a user-defined function,
7942 that function can decide which tags should be excluded from the agenda
7943 automatically.  Once this is set, the @kbd{/} command then accepts @kbd{RET}
7944 as a sub-option key and runs the auto exclusion logic.  For example, let's
7945 say you use a @code{Net} tag to identify tasks which need network access, an
7946 @code{Errand} tag for errands in town, and a @code{Call} tag for making phone
7947 calls.  You could auto-exclude these tags based on the availability of the
7948 Internet, and outside of business hours, with something like this:
7950 @lisp
7951 @group
7952 (defun org-my-auto-exclude-function (tag)
7953   (and (cond
7954         ((string= tag "Net")
7955          (/= 0 (call-process "/sbin/ping" nil nil nil
7956                              "-c1" "-q" "-t1" "mail.gnu.org")))
7957         ((or (string= tag "Errand") (string= tag "Call"))
7958          (let ((hour (nth 2 (decode-time))))
7959            (or (< hour 8) (> hour 21)))))
7960        (concat "-" tag)))
7962 (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
7963 @end group
7964 @end lisp
7966 @orgcmd{\\,org-agenda-filter-by-tag-refine}
7967 Narrow the current agenda filter by an additional condition.  When called with
7968 prefix arg, remove the entries that @emph{do} have the tag, or that do match
7969 the effort criterion.  You can achieve the same effect by pressing @kbd{+} or
7970 @kbd{-} as the first key after the @kbd{/} command.
7973 @kindex [
7974 @kindex ]
7975 @kindex @{
7976 @kindex @}
7977 @item [ ] @{ @}
7978 @table @i
7979 @item @r{in} search view
7980 add new search words (@kbd{[} and @kbd{]}) or new regular expressions
7981 (@kbd{@{} and @kbd{@}}) to the query string.  The opening bracket/brace will
7982 add a positive search term prefixed by @samp{+}, indicating that this search
7983 term @i{must} occur/match in the entry.  The closing bracket/brace will add a
7984 negative search term which @i{must not} occur/match in the entry for it to be
7985 selected.
7986 @end table
7988 @tsubheading{Remote editing}
7989 @cindex remote editing, from agenda
7991 @item 0-9
7992 Digit argument.
7994 @cindex undoing remote-editing events
7995 @cindex remote editing, undo
7996 @orgcmd{C-_,org-agenda-undo}
7997 Undo a change due to a remote editing command.  The change is undone
7998 both in the agenda buffer and in the remote buffer.
8000 @orgcmd{t,org-agenda-todo}
8001 Change the TODO state of the item, both in the agenda and in the
8002 original org file.
8004 @orgcmd{C-S-@key{right},org-agenda-todo-nextset}
8005 @orgcmd{C-S-@key{left},org-agenda-todo-previousset}
8006 Switch to the next/previous set of TODO keywords.
8008 @orgcmd{C-k,org-agenda-kill}
8009 @vindex org-agenda-confirm-kill
8010 Delete the current agenda item along with the entire subtree belonging
8011 to it in the original Org file.  If the text to be deleted remotely
8012 is longer than one line, the kill needs to be confirmed by the user.  See
8013 variable @code{org-agenda-confirm-kill}.
8015 @orgcmd{C-c C-w,org-agenda-refile}
8016 Refile the entry at point.
8018 @orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation}
8019 @vindex org-archive-default-command
8020 Archive the subtree corresponding to the entry at point using the default
8021 archiving command set in @code{org-archive-default-command}.  When using the
8022 @code{a} key, confirmation will be required.
8024 @orgcmd{C-c C-x a,org-agenda-toggle-archive-tag}
8025 Toggle the ARCHIVE tag for the current headline.
8027 @orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling}
8028 Move the subtree corresponding to the current entry to its @emph{archive
8029 sibling}.
8031 @orgcmdkskc{C-c C-x C-s,$,org-agenda-archive}
8032 Archive the subtree corresponding to the current headline.  This means the
8033 entry will be moved to the configured archive location, most likely a
8034 different file.
8036 @orgcmd{T,org-agenda-show-tags}
8037 @vindex org-agenda-show-inherited-tags
8038 Show all tags associated with the current item.  This is useful if you have
8039 turned off @code{org-agenda-show-inherited-tags}, but still want to see all
8040 tags of a headline occasionally.
8042 @orgcmd{:,org-agenda-set-tags}
8043 Set tags for the current headline.  If there is an active region in the
8044 agenda, change a tag for all headings in the region.
8046 @kindex ,
8047 @item ,
8048 Set the priority for the current item (@command{org-agenda-priority}).
8049 Org-mode prompts for the priority character.  If you reply with @key{SPC},
8050 the priority cookie is removed from the entry.
8052 @orgcmd{P,org-agenda-show-priority}
8053 Display weighted priority of current item.
8055 @orgcmdkkc{+,S-@key{up},org-agenda-priority-up}
8056 Increase the priority of the current item.  The priority is changed in
8057 the original buffer, but the agenda is not resorted.  Use the @kbd{r}
8058 key for this.
8060 @orgcmdkkc{-,S-@key{down},org-agenda-priority-down}
8061 Decrease the priority of the current item.
8063 @orgcmdkkc{z,C-c C-z,org-agenda-add-note}
8064 @vindex org-log-into-drawer
8065 Add a note to the entry.  This note will be recorded, and then filed to the
8066 same location where state change notes are put.  Depending on
8067 @code{org-log-into-drawer}, this may be inside a drawer.
8069 @orgcmd{C-c C-a,org-attach}
8070 Dispatcher for all command related to attachments.
8072 @orgcmd{C-c C-s,org-agenda-schedule}
8073 Schedule this item.  With prefix arg remove the scheduling timestamp
8075 @orgcmd{C-c C-d,org-agenda-deadline}
8076 Set a deadline for this item.  With prefix arg remove the deadline.
8078 @orgcmd{k,org-agenda-action}
8079 Agenda actions, to set dates for selected items to the cursor date.
8080 This command also works in the calendar!  The command prompts for an
8081 additional key:
8082 @example
8083 m   @r{Mark the entry at point for action.  You can also make entries}
8084     @r{in Org files with @kbd{C-c C-x C-k}.}
8085 d   @r{Set the deadline of the marked entry to the date at point.}
8086 s   @r{Schedule the marked entry at the date at point.}
8087 r   @r{Call @code{org-capture} with the cursor date as default date.}
8088 @end example
8089 @noindent
8090 Press @kbd{r} afterward to refresh the agenda and see the effect of the
8091 command.
8093 @orgcmd{S-@key{right},org-agenda-do-date-later}
8094 Change the timestamp associated with the current line by one day into the
8095 future.  With a numeric prefix argument, change it by that many days.  For
8096 example, @kbd{3 6 5 S-@key{right}} will change it by a year.  With a
8097 @kbd{C-u} prefix, change the time by one hour.  If you immediately repeat the
8098 command, it will continue to change hours even without the prefix arg.  With
8099 a double @kbd{C-u C-u} prefix, do the same for changing minutes.  The stamp
8100 is changed in the original Org file, but the change is not directly reflected
8101 in the agenda buffer.  Use @kbd{r} or @kbd{g} to update the buffer.
8103 @orgcmd{S-@key{left},org-agenda-do-date-earlier}
8104 Change the timestamp associated with the current line by one day
8105 into the past.
8107 @orgcmd{>,org-agenda-date-prompt}
8108 Change the timestamp associated with the current line.  The key @kbd{>} has
8109 been chosen, because it is the same as @kbd{S-.}  on my keyboard.
8111 @orgcmd{I,org-agenda-clock-in}
8112 Start the clock on the current item.  If a clock is running already, it
8113 is stopped first.
8115 @orgcmd{O,org-agenda-clock-out}
8116 Stop the previously started clock.
8118 @orgcmd{X,org-agenda-clock-cancel}
8119 Cancel the currently running clock.
8121 @orgcmd{J,org-agenda-clock-goto}
8122 Jump to the running clock in another window.
8124 @tsubheading{Bulk remote editing selected entries}
8125 @cindex remote editing, bulk, from agenda
8127 @orgcmd{m,org-agenda-bulk-mark}
8128 Mark the entry at point for bulk action.  With prefix arg, mark that many
8129 successive entries.
8131 @orgcmd{%,org-agenda-bulk-mark-regexp}
8132 Mark entries matching a regular expression for bulk action.
8134 @orgcmd{u,org-agenda-bulk-unmark}
8135 Unmark entry for bulk action.
8137 @orgcmd{U,org-agenda-bulk-remove-all-marks}
8138 Unmark all marked entries for bulk action.
8140 @orgcmd{B,org-agenda-bulk-action}
8141 Bulk action: act on all marked entries in the agenda.  This will prompt for
8142 another key to select the action to be applied.  The prefix arg to @kbd{B}
8143 will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove
8144 these special timestamps.
8145 @example
8146 r  @r{Prompt for a single refile target and move all entries.  The entries}
8147    @r{will no longer be in the agenda; refresh (@kbd{g}) to bring them back.}
8148 $  @r{Archive all selected entries.}
8149 A  @r{Archive entries by moving them to their respective archive siblings.}
8150 t  @r{Change TODO state.  This prompts for a single TODO keyword and}
8151    @r{changes the state of all selected entries, bypassing blocking and}
8152    @r{suppressing logging notes (but not timestamps).}
8153 +  @r{Add a tag to all selected entries.}
8154 -  @r{Remove a tag from all selected entries.}
8155 s  @r{Schedule all items to a new date.  To shift existing schedule dates}
8156    @r{by a fixed number of days, use something starting with double plus}
8157    @r{at the prompt, for example @samp{++8d} or @samp{++2w}.}
8158 S  @r{Reschedule randomly into the coming N days.  N will be prompted for.}
8159    @r{With prefix arg (@kbd{C-u B S}), scatter only across weekdays.}
8160 d  @r{Set deadline to a specific date.}
8161 f  @r{Apply a function to marked entries.}
8162    @r{For example, the function below sets the CATEGORY property of the}
8163    @r{entries to web.}
8164    @r{(defun set-category ()}
8165    @r{  (interactive "P")}
8166    @r{  (let* ((marker (or (org-get-at-bol 'org-hd-marker)}
8167    @r{                     (org-agenda-error)))}
8168    @r{            (buffer (marker-buffer marker)))}
8169    @r{       (with-current-buffer buffer}
8170    @r{         (save-excursion}
8171    @r{           (save-restriction}
8172    @r{             (widen)}
8173    @r{             (goto-char marker)}
8174    @r{             (org-back-to-heading t)}
8175    @r{             (org-set-property "CATEGORY" "web"))))))}
8176 @end example
8179 @tsubheading{Calendar commands}
8180 @cindex calendar commands, from agenda
8182 @orgcmd{c,org-agenda-goto-calendar}
8183 Open the Emacs calendar and move to the date at the agenda cursor.
8185 @orgcmd{c,org-calendar-goto-agenda}
8186 When in the calendar, compute and show the Org-mode agenda for the
8187 date at the cursor.
8189 @cindex diary entries, creating from agenda
8190 @orgcmd{i,org-agenda-diary-entry}
8191 @vindex org-agenda-diary-file
8192 Insert a new entry into the diary, using the date at the cursor and (for
8193 block entries) the date at the mark.  This will add to the Emacs diary
8194 file@footnote{This file is parsed for the agenda when
8195 @code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
8196 command in the calendar.  The diary file will pop up in another window, where
8197 you can add the entry.
8199 If you configure @code{org-agenda-diary-file} to point to an Org-mode file,
8200 Org will create entries (in org-mode syntax) in that file instead.  Most
8201 entries will be stored in a date-based outline tree that will later make it
8202 easy to archive appointments from previous months/years.  The tree will be
8203 built under an entry with a @code{DATE_TREE} property, or else with years as
8204 top-level entries.  Emacs will prompt you for the entry text---if you specify
8205 it, the entry will be created in @code{org-agenda-diary-file} without further
8206 interaction.  If you directly press @key{RET} at the prompt without typing
8207 text, the target file will be shown in another window for you to finish the
8208 entry there.  See also the @kbd{k r} command.
8210 @orgcmd{M,org-agenda-phases-of-moon}
8211 Show the phases of the moon for the three months around current date.
8213 @orgcmd{S,org-agenda-sunrise-sunset}
8214 Show sunrise and sunset times.  The geographical location must be set
8215 with calendar variables, see the documentation for the Emacs calendar.
8217 @orgcmd{C,org-agenda-convert-date}
8218 Convert the date at cursor into many other cultural and historic
8219 calendars.
8221 @orgcmd{H,org-agenda-holidays}
8222 Show holidays for three months around the cursor date.
8224 @item M-x org-export-icalendar-combine-agenda-files
8225 Export a single iCalendar file containing entries from all agenda files.
8226 This is a globally available command, and also available in the agenda menu.
8228 @tsubheading{Exporting to a file}
8229 @orgcmd{C-x C-w,org-write-agenda}
8230 @cindex exporting agenda views
8231 @cindex agenda views, exporting
8232 @vindex org-agenda-exporter-settings
8233 Write the agenda view to a file.  Depending on the extension of the selected
8234 file name, the view will be exported as HTML (extension @file{.html} or
8235 @file{.htm}), Postscript (extension @file{.ps}), PDF (extension @file{.pdf}),
8236 and plain text (any other extension).  When called with a @kbd{C-u} prefix
8237 argument, immediately open the newly created file.  Use the variable
8238 @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
8239 for @file{htmlize} to be used during export.
8241 @tsubheading{Quit and Exit}
8242 @orgcmd{q,org-agenda-quit}
8243 Quit agenda, remove the agenda buffer.
8245 @cindex agenda files, removing buffers
8246 @orgcmd{x,org-agenda-exit}
8247 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
8248 for the compilation of the agenda.  Buffers created by the user to
8249 visit Org files will not be removed.
8250 @end table
8253 @node Custom agenda views, Exporting Agenda Views, Agenda commands, Agenda Views
8254 @section Custom agenda views
8255 @cindex custom agenda views
8256 @cindex agenda views, custom
8258 Custom agenda commands serve two purposes: to store and quickly access
8259 frequently used TODO and tags searches, and to create special composite
8260 agenda buffers.  Custom agenda commands will be accessible through the
8261 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
8263 @menu
8264 * Storing searches::            Type once, use often
8265 * Block agenda::                All the stuff you need in a single buffer
8266 * Setting Options::             Changing the rules
8267 @end menu
8269 @node Storing searches, Block agenda, Custom agenda views, Custom agenda views
8270 @subsection Storing searches
8272 The first application of custom searches is the definition of keyboard
8273 shortcuts for frequently used searches, either creating an agenda
8274 buffer, or a sparse tree (the latter covering of course only the current
8275 buffer).
8276 @kindex C-c a C
8277 @vindex org-agenda-custom-commands
8278 Custom commands are configured in the variable
8279 @code{org-agenda-custom-commands}.  You can customize this variable, for
8280 example by pressing @kbd{C-c a C}.  You can also directly set it with
8281 Emacs Lisp in @file{.emacs}.  The following example contains all valid
8282 search types:
8284 @lisp
8285 @group
8286 (setq org-agenda-custom-commands
8287       '(("w" todo "WAITING")
8288         ("W" todo-tree "WAITING")
8289         ("u" tags "+boss-urgent")
8290         ("v" tags-todo "+boss-urgent")
8291         ("U" tags-tree "+boss-urgent")
8292         ("f" occur-tree "\\<FIXME\\>")
8293         ("h" . "HOME+Name tags searches") ; description for "h" prefix
8294         ("hl" tags "+home+Lisa")
8295         ("hp" tags "+home+Peter")
8296         ("hk" tags "+home+Kim")))
8297 @end group
8298 @end lisp
8300 @noindent
8301 The initial string in each entry defines the keys you have to press
8302 after the dispatcher command @kbd{C-c a} in order to access the command.
8303 Usually this will be just a single character, but if you have many
8304 similar commands, you can also define two-letter combinations where the
8305 first character is the same in several combinations and serves as a
8306 prefix key@footnote{You can provide a description for a prefix key by
8307 inserting a cons cell with the prefix and the description.}.  The second
8308 parameter is the search type, followed by the string or regular
8309 expression to be used for the matching.  The example above will
8310 therefore define:
8312 @table @kbd
8313 @item C-c a w
8314 as a global search for TODO entries with @samp{WAITING} as the TODO
8315 keyword
8316 @item C-c a W
8317 as the same search, but only in the current buffer and displaying the
8318 results as a sparse tree
8319 @item C-c a u
8320 as a global tags search for headlines marked @samp{:boss:} but not
8321 @samp{:urgent:}
8322 @item C-c a v
8323 as the same search as @kbd{C-c a u}, but limiting the search to
8324 headlines that are also TODO items
8325 @item C-c a U
8326 as the same search as @kbd{C-c a u}, but only in the current buffer and
8327 displaying the result as a sparse tree
8328 @item C-c a f
8329 to create a sparse tree (again: current buffer only) with all entries
8330 containing the word @samp{FIXME}
8331 @item C-c a h
8332 as a prefix command for a HOME tags search where you have to press an
8333 additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,
8334 Peter, or Kim) as additional tag to match.
8335 @end table
8337 @node Block agenda, Setting Options, Storing searches, Custom agenda views
8338 @subsection Block agenda
8339 @cindex block agenda
8340 @cindex agenda, with block views
8342 Another possibility is the construction of agenda views that comprise
8343 the results of @emph{several} commands, each of which creates a block in
8344 the agenda buffer.  The available commands include @code{agenda} for the
8345 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
8346 for the global TODO list (as constructed with @kbd{C-c a t}), and the
8347 matching commands discussed above: @code{todo}, @code{tags}, and
8348 @code{tags-todo}.  Here are two examples:
8350 @lisp
8351 @group
8352 (setq org-agenda-custom-commands
8353       '(("h" "Agenda and Home-related tasks"
8354          ((agenda "")
8355           (tags-todo "home")
8356           (tags "garden")))
8357         ("o" "Agenda and Office-related tasks"
8358          ((agenda "")
8359           (tags-todo "work")
8360           (tags "office")))))
8361 @end group
8362 @end lisp
8364 @noindent
8365 This will define @kbd{C-c a h} to create a multi-block view for stuff
8366 you need to attend to at home.  The resulting agenda buffer will contain
8367 your agenda for the current week, all TODO items that carry the tag
8368 @samp{home}, and also all lines tagged with @samp{garden}.  Finally the
8369 command @kbd{C-c a o} provides a similar view for office tasks.
8371 @node Setting Options,  , Block agenda, Custom agenda views
8372 @subsection Setting options for custom commands
8373 @cindex options, for custom agenda views
8375 @vindex org-agenda-custom-commands
8376 Org-mode contains a number of variables regulating agenda construction
8377 and display.  The global variables define the behavior for all agenda
8378 commands, including the custom commands.  However, if you want to change
8379 some settings just for a single custom view, you can do so.  Setting
8380 options requires inserting a list of variable names and values at the
8381 right spot in @code{org-agenda-custom-commands}.  For example:
8383 @lisp
8384 @group
8385 (setq org-agenda-custom-commands
8386       '(("w" todo "WAITING"
8387          ((org-agenda-sorting-strategy '(priority-down))
8388           (org-agenda-prefix-format "  Mixed: ")))
8389         ("U" tags-tree "+boss-urgent"
8390          ((org-show-following-heading nil)
8391           (org-show-hierarchy-above nil)))
8392         ("N" search ""
8393          ((org-agenda-files '("~org/notes.org"))
8394           (org-agenda-text-search-extra-files nil)))))
8395 @end group
8396 @end lisp
8398 @noindent
8399 Now the @kbd{C-c a w} command will sort the collected entries only by
8400 priority, and the prefix format is modified to just say @samp{  Mixed: }
8401 instead of giving the category of the entry.  The sparse tags tree of
8402 @kbd{C-c a U} will now turn out ultra-compact, because neither the
8403 headline hierarchy above the match, nor the headline following the match
8404 will be shown.  The command @kbd{C-c a N} will do a text search limited
8405 to only a single file.
8407 @vindex org-agenda-custom-commands
8408 For command sets creating a block agenda,
8409 @code{org-agenda-custom-commands} has two separate spots for setting
8410 options.  You can add options that should be valid for just a single
8411 command in the set, and options that should be valid for all commands in
8412 the set.  The former are just added to the command entry; the latter
8413 must come after the list of command entries.  Going back to the block
8414 agenda example (@pxref{Block agenda}), let's change the sorting strategy
8415 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
8416 the results for GARDEN tags query in the opposite order,
8417 @code{priority-up}.  This would look like this:
8419 @lisp
8420 @group
8421 (setq org-agenda-custom-commands
8422       '(("h" "Agenda and Home-related tasks"
8423          ((agenda)
8424           (tags-todo "home")
8425           (tags "garden"
8426                 ((org-agenda-sorting-strategy '(priority-up)))))
8427          ((org-agenda-sorting-strategy '(priority-down))))
8428         ("o" "Agenda and Office-related tasks"
8429          ((agenda)
8430           (tags-todo "work")
8431           (tags "office")))))
8432 @end group
8433 @end lisp
8435 As you see, the values and parentheses setting is a little complex.
8436 When in doubt, use the customize interface to set this variable---it
8437 fully supports its structure.  Just one caveat: when setting options in
8438 this interface, the @emph{values} are just Lisp expressions.  So if the
8439 value is a string, you need to add the double-quotes around the value
8440 yourself.
8443 @node Exporting Agenda Views, Agenda column view, Custom agenda views, Agenda Views
8444 @section Exporting Agenda Views
8445 @cindex agenda views, exporting
8447 If you are away from your computer, it can be very useful to have a printed
8448 version of some agenda views to carry around.  Org-mode can export custom
8449 agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's
8450 @file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the
8451 ghostscript @file{ps2pdf} utility must be installed on the system.  Selecting
8452 a PDF file will also create the postscript file.}, and iCalendar files.  If
8453 you want to do this only occasionally, use the command
8455 @table @kbd
8456 @orgcmd{C-x C-w,org-write-agenda}
8457 @cindex exporting agenda views
8458 @cindex agenda views, exporting
8459 @vindex org-agenda-exporter-settings
8460 Write the agenda view to a file.  Depending on the extension of the selected
8461 file name, the view will be exported as HTML (extension @file{.html} or
8462 @file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension
8463 @file{.ics}), or plain text (any other extension).  Use the variable
8464 @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
8465 for @file{htmlize} to be used during export, for example
8467 @vindex org-agenda-add-entry-text-maxlines
8468 @vindex htmlize-output-type
8469 @vindex ps-number-of-columns
8470 @vindex ps-landscape-mode
8471 @lisp
8472 (setq org-agenda-exporter-settings
8473       '((ps-number-of-columns 2)
8474         (ps-landscape-mode t)
8475         (org-agenda-add-entry-text-maxlines 5)
8476         (htmlize-output-type 'css)))
8477 @end lisp
8478 @end table
8480 If you need to export certain agenda views frequently, you can associate
8481 any custom agenda command with a list of output file names
8482 @footnote{If you want to store standard views like the weekly agenda
8483 or the global TODO list as well, you need to define custom commands for
8484 them in order to be able to specify file names.}.  Here is an example
8485 that first defines custom commands for the agenda and the global
8486 TODO list, together with a number of files to which to export them.
8487 Then we define two block agenda commands and specify file names for them
8488 as well.  File names can be relative to the current working directory,
8489 or absolute.
8491 @lisp
8492 @group
8493 (setq org-agenda-custom-commands
8494       '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
8495         ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
8496         ("h" "Agenda and Home-related tasks"
8497          ((agenda "")
8498           (tags-todo "home")
8499           (tags "garden"))
8500          nil
8501          ("~/views/home.html"))
8502         ("o" "Agenda and Office-related tasks"
8503          ((agenda)
8504           (tags-todo "work")
8505           (tags "office"))
8506          nil
8507          ("~/views/office.ps" "~/calendars/office.ics"))))
8508 @end group
8509 @end lisp
8511 The extension of the file name determines the type of export.  If it is
8512 @file{.html}, Org-mode will use the @file{htmlize.el} package to convert
8513 the buffer to HTML and save it to this file name.  If the extension is
8514 @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
8515 Postscript output.  If the extension is @file{.ics}, iCalendar export is
8516 run export over all files that were used to construct the agenda, and
8517 limit the export to entries listed in the agenda.  Any other
8518 extension produces a plain ASCII file.
8520 The export files are @emph{not} created when you use one of those
8521 commands interactively because this might use too much overhead.
8522 Instead, there is a special command to produce @emph{all} specified
8523 files in one step:
8525 @table @kbd
8526 @orgcmd{C-c a e,org-store-agenda-views}
8527 Export all agenda views that have export file names associated with
8528 them.
8529 @end table
8531 You can use the options section of the custom agenda commands to also
8532 set options for the export commands.  For example:
8534 @lisp
8535 (setq org-agenda-custom-commands
8536       '(("X" agenda ""
8537          ((ps-number-of-columns 2)
8538           (ps-landscape-mode t)
8539           (org-agenda-prefix-format " [ ] ")
8540           (org-agenda-with-colors nil)
8541           (org-agenda-remove-tags t))
8542          ("theagenda.ps"))))
8543 @end lisp
8545 @noindent
8546 This command sets two options for the Postscript exporter, to make it
8547 print in two columns in landscape format---the resulting page can be cut
8548 in two and then used in a paper agenda.  The remaining settings modify
8549 the agenda prefix to omit category and scheduling information, and
8550 instead include a checkbox to check off items.  We also remove the tags
8551 to make the lines compact, and we don't want to use colors for the
8552 black-and-white printer.  Settings specified in
8553 @code{org-agenda-exporter-settings} will also apply, but the settings
8554 in @code{org-agenda-custom-commands} take precedence.
8556 @noindent
8557 From the command line you may also use
8558 @example
8559 emacs -f org-batch-store-agenda-views -kill
8560 @end example
8561 @noindent
8562 or, if you need to modify some parameters@footnote{Quoting depends on the
8563 system you use, please check the FAQ for examples.}
8564 @example
8565 emacs -eval '(org-batch-store-agenda-views                      \
8566               org-agenda-span month                             \
8567               org-agenda-start-day "2007-11-01"                 \
8568               org-agenda-include-diary nil                      \
8569               org-agenda-files (quote ("~/org/project.org")))'  \
8570       -kill
8571 @end example
8572 @noindent
8573 which will create the agenda views restricted to the file
8574 @file{~/org/project.org}, without diary entries and with a 30-day
8575 extent.
8577 You can also extract agenda information in a way that allows further
8578 processing by other programs.  See @ref{Extracting agenda information}, for
8579 more information.
8582 @node Agenda column view,  , Exporting Agenda Views, Agenda Views
8583 @section Using column view in the agenda
8584 @cindex column view, in agenda
8585 @cindex agenda, column view
8587 Column view (@pxref{Column view}) is normally used to view and edit
8588 properties embedded in the hierarchical structure of an Org file.  It can be
8589 quite useful to use column view also from the agenda, where entries are
8590 collected by certain criteria.
8592 @table @kbd
8593 @orgcmd{C-c C-x C-c,org-agenda-columns}
8594 Turn on column view in the agenda.
8595 @end table
8597 To understand how to use this properly, it is important to realize that the
8598 entries in the agenda are no longer in their proper outline environment.
8599 This causes the following issues:
8601 @enumerate
8602 @item
8603 @vindex org-columns-default-format
8604 @vindex org-overriding-columns-format
8605 Org needs to make a decision which @code{COLUMNS} format to use.  Since the
8606 entries in the agenda are collected from different files, and different files
8607 may have different @code{COLUMNS} formats, this is a non-trivial problem.
8608 Org first checks if the variable @code{org-agenda-overriding-columns-format} is
8609 currently set, and if so, takes the format from there.  Otherwise it takes
8610 the format associated with the first item in the agenda, or, if that item
8611 does not have a specific format (defined in a property, or in its file), it
8612 uses @code{org-columns-default-format}.
8613 @item
8614 @cindex property, special, CLOCKSUM
8615 If any of the columns has a summary type defined (@pxref{Column attributes}),
8616 turning on column view in the agenda will visit all relevant agenda files and
8617 make sure that the computations of this property are up to date.  This is
8618 also true for the special @code{CLOCKSUM} property.  Org will then sum the
8619 values displayed in the agenda.  In the daily/weekly agenda, the sums will
8620 cover a single day; in all other views they cover the entire block.  It is
8621 vital to realize that the agenda may show the same entry @emph{twice} (for
8622 example as scheduled and as a deadline), and it may show two entries from the
8623 same hierarchy (for example a @emph{parent} and its @emph{child}).  In these
8624 cases, the summation in the agenda will lead to incorrect results because
8625 some values will count double.
8626 @item
8627 When the column view in the agenda shows the @code{CLOCKSUM}, that is always
8628 the entire clocked time for this item.  So even in the daily/weekly agenda,
8629 the clocksum listed in column view may originate from times outside the
8630 current view.  This has the advantage that you can compare these values with
8631 a column listing the planned total effort for a task---one of the major
8632 applications for column view in the agenda.  If you want information about
8633 clocked time in the displayed period use clock table mode (press @kbd{R} in
8634 the agenda).
8635 @end enumerate
8638 @node Markup, Exporting, Agenda Views, Top
8639 @chapter Markup for rich export
8641 When exporting Org-mode documents, the exporter tries to reflect the
8642 structure of the document as accurately as possible in the backend.  Since
8643 export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting,
8644 Org-mode has rules on how to prepare text for rich export.  This section
8645 summarizes the markup rules used in an Org-mode buffer.
8647 @menu
8648 * Structural markup elements::  The basic structure as seen by the exporter
8649 * Images and tables::           Tables and Images will be included
8650 * Literal examples::            Source code examples with special formatting
8651 * Include files::               Include additional files into a document
8652 * Index entries::               Making an index
8653 * Macro replacement::           Use macros to create complex output
8654 * Embedded LaTeX::              LaTeX can be freely used inside Org documents
8655 @end menu
8657 @node Structural markup elements, Images and tables, Markup, Markup
8658 @section Structural markup elements
8660 @menu
8661 * Document title::              Where the title is taken from
8662 * Headings and sections::       The document structure as seen by the exporter
8663 * Table of contents::           The if and where of the table of contents
8664 * Initial text::                Text before the first heading?
8665 * Lists::                       Lists
8666 * Paragraphs::                  Paragraphs
8667 * Footnote markup::             Footnotes
8668 * Emphasis and monospace::      Bold, italic, etc.
8669 * Horizontal rules::            Make a line
8670 * Comment lines::               What will *not* be exported
8671 @end menu
8673 @node Document title, Headings and sections, Structural markup elements, Structural markup elements
8674 @subheading Document title
8675 @cindex document title, markup rules
8677 @noindent
8678 The title of the exported document is taken from the special line
8680 @cindex #+TITLE
8681 @example
8682 #+TITLE: This is the title of the document
8683 @end example
8685 @noindent
8686 If this line does not exist, the title is derived from the first non-empty,
8687 non-comment line in the buffer.  If no such line exists, or if you have
8688 turned off exporting of the text before the first headline (see below), the
8689 title will be the file name without extension.
8691 @cindex property, EXPORT_TITLE
8692 If you are exporting only a subtree by marking is as the region, the heading
8693 of the subtree will become the title of the document.  If the subtree has a
8694 property @code{EXPORT_TITLE}, that will take precedence.
8696 @node Headings and sections, Table of contents, Document title, Structural markup elements
8697 @subheading Headings and sections
8698 @cindex headings and sections, markup rules
8700 @vindex org-export-headline-levels
8701 The outline structure of the document as described in @ref{Document
8702 Structure}, forms the basis for defining sections of the exported document.
8703 However, since the outline structure is also used for (for example) lists of
8704 tasks, only the first three outline levels will be used as headings.  Deeper
8705 levels will become itemized lists.  You can change the location of this
8706 switch globally by setting the variable @code{org-export-headline-levels}, or on a
8707 per-file basis with a line
8709 @cindex #+OPTIONS
8710 @example
8711 #+OPTIONS: H:4
8712 @end example
8714 @node Table of contents, Initial text, Headings and sections, Structural markup elements
8715 @subheading Table of contents
8716 @cindex table of contents, markup rules
8718 @vindex org-export-with-toc
8719 The table of contents is normally inserted directly before the first headline
8720 of the file.  If you would like to get it to a different location, insert the
8721 string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired
8722 location.  The depth of the table of contents is by default the same as the
8723 number of headline levels, but you can choose a smaller number, or turn off
8724 the table of contents entirely, by configuring the variable
8725 @code{org-export-with-toc}, or on a per-file basis with a line like
8727 @example
8728 #+OPTIONS: toc:2          (only to two levels in TOC)
8729 #+OPTIONS: toc:nil        (no TOC at all)
8730 @end example
8732 @node Initial text, Lists, Table of contents, Structural markup elements
8733 @subheading Text before the first headline
8734 @cindex text before first headline, markup rules
8735 @cindex #+TEXT
8737 Org-mode normally exports the text before the first headline, and even uses
8738 the first line as the document title.  The text will be fully marked up.  If
8739 you need to include literal HTML, @LaTeX{}, or DocBook code, use the special
8740 constructs described below in the sections for the individual exporters.
8742 @vindex org-export-skip-text-before-1st-heading
8743 Some people like to use the space before the first headline for setup and
8744 internal links and therefore would like to control the exported text before
8745 the first headline in a different way.  You can do so by setting the variable
8746 @code{org-export-skip-text-before-1st-heading} to @code{t}.  On a per-file
8747 basis, you can get the same effect with @samp{#+OPTIONS: skip:t}.
8749 @noindent
8750 If you still want to have some text before the first headline, use the
8751 @code{#+TEXT} construct:
8753 @example
8754 #+OPTIONS: skip:t
8755 #+TEXT: This text will go before the *first* headline.
8756 #+TEXT: [TABLE-OF-CONTENTS]
8757 #+TEXT: This goes between the table of contents and the *first* headline
8758 @end example
8760 @node Lists, Paragraphs, Initial text, Structural markup elements
8761 @subheading Lists
8762 @cindex lists, markup rules
8764 Plain lists as described in @ref{Plain lists}, are translated to the backend's
8765 syntax for such lists.  Most backends support unordered, ordered, and
8766 description lists.
8768 @node Paragraphs, Footnote markup, Lists, Structural markup elements
8769 @subheading Paragraphs, line breaks, and quoting
8770 @cindex paragraphs, markup rules
8772 Paragraphs are separated by at least one empty line.  If you need to enforce
8773 a line break within a paragraph, use @samp{\\} at the end of a line.
8775 To keep the line breaks in a region, but otherwise use normal formatting, you
8776 can use this construct, which can also be used to format poetry.
8778 @cindex #+BEGIN_VERSE
8779 @example
8780 #+BEGIN_VERSE
8781  Great clouds overhead
8782  Tiny black birds rise and fall
8783  Snow covers Emacs
8785      -- AlexSchroeder
8786 #+END_VERSE
8787 @end example
8789 When quoting a passage from another document, it is customary to format this
8790 as a paragraph that is indented on both the left and the right margin.  You
8791 can include quotations in Org-mode documents like this:
8793 @cindex #+BEGIN_QUOTE
8794 @example
8795 #+BEGIN_QUOTE
8796 Everything should be made as simple as possible,
8797 but not any simpler -- Albert Einstein
8798 #+END_QUOTE
8799 @end example
8801 If you would like to center some text, do it like this:
8802 @cindex #+BEGIN_CENTER
8803 @example
8804 #+BEGIN_CENTER
8805 Everything should be made as simple as possible, \\
8806 but not any simpler
8807 #+END_CENTER
8808 @end example
8811 @node Footnote markup, Emphasis and monospace, Paragraphs, Structural markup elements
8812 @subheading Footnote markup
8813 @cindex footnotes, markup rules
8814 @cindex @file{footnote.el}
8816 Footnotes defined in the way described in @ref{Footnotes}, will be exported
8817 by all backends.  Org allows multiple references to the same note, and
8818 multiple footnotes side by side.
8820 @node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements
8821 @subheading Emphasis and monospace
8823 @cindex underlined text, markup rules
8824 @cindex bold text, markup rules
8825 @cindex italic text, markup rules
8826 @cindex verbatim text, markup rules
8827 @cindex code text, markup rules
8828 @cindex strike-through text, markup rules
8829 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
8830 and @code{~verbatim~}, and, if you must, @samp{+strike-through+}.  Text
8831 in the code and verbatim string is not processed for Org-mode specific
8832 syntax; it is exported verbatim.
8834 @node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements
8835 @subheading  Horizontal rules
8836 @cindex horizontal rules, markup rules
8837 A line consisting of only dashes, and at least 5 of them, will be exported as
8838 a horizontal line (@samp{<hr/>} in HTML and @code{\hrule} in @LaTeX{}).
8840 @node Comment lines,  , Horizontal rules, Structural markup elements
8841 @subheading Comment lines
8842 @cindex comment lines
8843 @cindex exporting, not
8844 @cindex #+BEGIN_COMMENT
8846 Lines starting with @samp{#} in column zero are treated as comments and will
8847 never be exported.  If you want an indented line to be treated as a comment,
8848 start it with @samp{#+ }.  Also entire subtrees starting with the word
8849 @samp{COMMENT} will never be exported.  Finally, regions surrounded by
8850 @samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported.
8852 @table @kbd
8853 @kindex C-c ;
8854 @item C-c ;
8855 Toggle the COMMENT keyword at the beginning of an entry.
8856 @end table
8859 @node Images and tables, Literal examples, Structural markup elements, Markup
8860 @section Images and Tables
8862 @cindex tables, markup rules
8863 @cindex #+CAPTION
8864 @cindex #+LABEL
8865 Both the native Org-mode tables (@pxref{Tables}) and tables formatted with
8866 the @file{table.el} package will be exported properly.  For Org-mode tables,
8867 the lines before the first horizontal separator line will become table header
8868 lines.  You can use the following lines somewhere before the table to assign
8869 a caption and a label for cross references, and in the text you can refer to
8870 the object with @code{\ref@{tab:basic-data@}}:
8872 @example
8873 #+CAPTION: This is the caption for the next table (or link)
8874 #+LABEL:   tbl:basic-data
8875    | ... | ...|
8876    |-----|----|
8877 @end example
8879 Optionally, the caption can take the form:
8880 @example
8881 #+CAPTION: [Caption for list of figures]@{Caption for table (or link).@}
8882 @end example
8884 @cindex inlined images, markup rules
8885 Some backends (HTML, @LaTeX{}, and DocBook) allow you to directly include
8886 images into the exported document.  Org does this, if a link to an image
8887 files does not have a description part, for example @code{[[./img/a.jpg]]}.
8888 If you wish to define a caption for the image and maybe a label for internal
8889 cross references, make sure that the link is on a line by itself and precede
8890 it with @code{#+CAPTION} and @code{#+LABEL} as follows:
8892 @example
8893 #+CAPTION: This is the caption for the next figure link (or table)
8894 #+LABEL:   fig:SED-HR4049
8895 [[./img/a.jpg]]
8896 @end example
8898 You may also define additional attributes for the figure.  As this is
8899 backend-specific, see the sections about the individual backends for more
8900 information.
8902 @xref{Handling links,the discussion of image links}.
8904 @node Literal examples, Include files, Images and tables, Markup
8905 @section Literal examples
8906 @cindex literal examples, markup rules
8907 @cindex code line references, markup rules
8909 You can include literal examples that should not be subjected to
8910 markup.  Such examples will be typeset in monospace, so this is well suited
8911 for source code and similar examples.
8912 @cindex #+BEGIN_EXAMPLE
8914 @example
8915 #+BEGIN_EXAMPLE
8916 Some example from a text file.
8917 #+END_EXAMPLE
8918 @end example
8920 Note that such blocks may be @i{indented} in order to align nicely with
8921 indented text and in particular with plain list structure (@pxref{Plain
8922 lists}).  For simplicity when using small examples, you can also start the
8923 example lines with a colon followed by a space.  There may also be additional
8924 whitespace before the colon:
8926 @example
8927 Here is an example
8928    : Some example from a text file.
8929 @end example
8931 @cindex formatting source code, markup rules
8932 If the example is source code from a programming language, or any other text
8933 that can be marked up by font-lock in Emacs, you can ask for the example to
8934 look like the fontified Emacs buffer@footnote{This works automatically for
8935 the HTML backend (it requires version 1.34 of the @file{htmlize.el} package,
8936 which is distributed with Org).  Fontified code chunks in LaTeX can be
8937 achieved using either the listings or the
8938 @url{http://code.google.com/p/minted, minted,} package.  To use listings, turn
8939 on the variable @code{org-export-latex-listings} and ensure that the listings
8940 package is included by the LaTeX header (e.g.@: by configuring
8941 @code{org-export-latex-packages-alist}).  See the listings documentation for
8942 configuration options, including obtaining colored output.  For minted it is
8943 necessary to install the program @url{http://pygments.org, pygments}, in
8944 addition to setting @code{org-export-latex-minted}, ensuring that the minted
8945 package is included by the LaTeX header, and ensuring that the
8946 @code{-shell-escape} option is passed to @file{pdflatex} (see
8947 @code{org-latex-to-pdf-process}).  See the documentation of the variables
8948 @code{org-export-latex-listings} and @code{org-export-latex-minted} for
8949 further details.}.  This is done with the @samp{src} block, where you also
8950 need to specify the name of the major mode that should be used to fontify the
8951 example@footnote{Code in @samp{src} blocks may also be evaluated either
8952 interactively or on export.  See @pxref{Working With Source Code} for more
8953 information on evaluating code blocks.}: 
8954 @cindex #+BEGIN_SRC
8956 @example
8957 #+BEGIN_SRC emacs-lisp
8958   (defun org-xor (a b)
8959      "Exclusive or."
8960      (if a (not b) b))
8961 #+END_SRC
8962 @end example
8964 Both in @code{example} and in @code{src} snippets, you can add a @code{-n}
8965 switch to the end of the @code{BEGIN} line, to get the lines of the example
8966 numbered.  If you use a @code{+n} switch, the numbering from the previous
8967 numbered snippet will be continued in the current one.  In literal examples,
8968 Org will interpret strings like @samp{(ref:name)} as labels, and use them as
8969 targets for special hyperlinks like @code{[[(name)]]} (i.e.@: the reference name
8970 enclosed in single parenthesis).  In HTML, hovering the mouse over such a
8971 link will remote-highlight the corresponding code line, which is kind of
8972 cool.
8974 You can also add a @code{-r} switch which @i{removes} the labels from the
8975 source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
8976 labels in the source code while using line numbers for the links, which might
8977 be useful to explain those in an org-mode example code.}.  With the @code{-n}
8978 switch, links to these references will be labeled by the line numbers from
8979 the code listing, otherwise links will use the labels with no parentheses.
8980 Here is an example:
8982 @example
8983 #+BEGIN_SRC emacs-lisp -n -r
8984 (save-excursion                  (ref:sc)
8985    (goto-char (point-min))       (ref:jump)
8986 #+END_SRC
8987 In line [[(sc)]] we remember the current position.  [[(jump)][Line (jump)]]
8988 jumps to point-min.
8989 @end example
8991 @vindex org-coderef-label-format
8992 If the syntax for the label format conflicts with the language syntax, use a
8993 @code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
8994 -n -r -l "((%s))"}.  See also the variable @code{org-coderef-label-format}.
8996 HTML export also allows examples to be published as text areas (@pxref{Text
8997 areas in HTML export}).
8999 Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
9000 so often, shortcuts are provided using the Easy Templates facility
9001 (@pxref{Easy Templates}).
9003 @table @kbd
9004 @kindex C-c '
9005 @item C-c '
9006 Edit the source code example at point in its native mode.  This works by
9007 switching to a temporary buffer with the source code.  You need to exit by
9008 pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*}
9009 or @samp{#} will get a comma prepended, to keep them from being interpreted
9010 by Org as outline nodes or special comments.  These commas will be stripped
9011 for editing with @kbd{C-c '}, and also for export.}.  The edited version will
9012 then replace the old version in the Org buffer.  Fixed-width regions
9013 (where each line starts with a colon followed by a space) will be edited
9014 using @code{artist-mode}@footnote{You may select a different-mode with the
9015 variable @code{org-edit-fixed-width-region-mode}.} to allow creating ASCII
9016 drawings easily.  Using this command in an empty line will create a new
9017 fixed-width region.
9018 @kindex C-c l
9019 @item C-c l
9020 Calling @code{org-store-link} while editing a source code example in a
9021 temporary buffer created with @kbd{C-c '} will prompt for a label.  Make sure
9022 that it is unique in the current buffer, and insert it with the proper
9023 formatting like @samp{(ref:label)} at the end of the current line.  Then the
9024 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
9025 @end table
9028 @node Include files, Index entries, Literal examples, Markup
9029 @section Include files
9030 @cindex include files, markup rules
9032 During export, you can include the content of another file.  For example, to
9033 include your @file{.emacs} file, you could use:
9034 @cindex #+INCLUDE
9036 @example
9037 #+INCLUDE: "~/.emacs" src emacs-lisp
9038 @end example
9039 @noindent
9040 The optional second and third parameter are the markup (e.g.@: @samp{quote},
9041 @samp{example}, or @samp{src}), and, if the markup is @samp{src}, the
9042 language for formatting the contents.  The markup is optional; if it is not
9043 given, the text will be assumed to be in Org-mode format and will be
9044 processed normally.  The include line will also allow additional keyword
9045 parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the
9046 first line and for each following line, @code{:minlevel} in order to get
9047 org-mode content demoted to a specified level, as well as any options
9048 accepted by the selected markup.  For example, to include a file as an item,
9051 @example
9052 #+INCLUDE: "~/snippets/xx" :prefix1 "   + " :prefix "     "
9053 @end example
9055 You can also include a portion of a file by specifying a lines range using
9056 the @code{:lines} parameter.  The line at the upper end of the range will not
9057 be included.  The start and/or the end of the range may be omitted to use the
9058 obvious defaults.
9060 @example
9061 #+INCLUDE: "~/.emacs" :lines "5-10"   @r{Include lines 5 to 10, 10 excluded}
9062 #+INCLUDE: "~/.emacs" :lines "-10"    @r{Include lines 1 to 10, 10 excluded}
9063 #+INCLUDE: "~/.emacs" :lines "10-"    @r{Include lines from 10 to EOF}
9064 @end example
9066 @table @kbd
9067 @kindex C-c '
9068 @item C-c '
9069 Visit the include file at point.
9070 @end table
9072 @node Index entries, Macro replacement, Include files, Markup
9073 @section Index entries
9074 @cindex index entries, for publishing
9076 You can specify entries that will be used for generating an index during
9077 publishing.  This is done by lines starting with @code{#+INDEX}.  An entry
9078 the contains an exclamation mark will create a sub item.  See @ref{Generating
9079 an index} for more information.
9081 @example
9082 * Curriculum Vitae
9083 #+INDEX: CV
9084 #+INDEX: Application!CV
9085 @end example
9090 @node Macro replacement, Embedded LaTeX, Index entries, Markup
9091 @section Macro replacement
9092 @cindex macro replacement, during export
9093 @cindex #+MACRO
9095 You can define text snippets with
9097 @example
9098 #+MACRO: name   replacement text $1, $2 are arguments
9099 @end example
9101 @noindent which can be referenced anywhere in the document (even in
9102 code examples) with @code{@{@{@{name(arg1,arg2)@}@}@}}.  In addition to
9103 defined macros, @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc.,
9104 will reference information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and
9105 similar lines.  Also, @code{@{@{@{date(@var{FORMAT})@}@}@}} and
9106 @code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date time
9107 and to the modification time of the file being exported, respectively.
9108 @var{FORMAT} should be a format string understood by
9109 @code{format-time-string}.
9111 Macro expansion takes place during export, and some people use it to
9112 construct complex HTML code.
9115 @node Embedded LaTeX,  , Macro replacement, Markup
9116 @section Embedded @LaTeX{}
9117 @cindex @TeX{} interpretation
9118 @cindex @LaTeX{} interpretation
9120 Plain ASCII is normally sufficient for almost all note taking.  Exceptions
9121 include scientific notes, which often require mathematical symbols and the
9122 occasional formula.  @LaTeX{}@footnote{@LaTeX{} is a macro system based on
9123 Donald E. Knuth's @TeX{} system.  Many of the features described here as
9124 ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
9125 distinction.}  is widely used to typeset scientific documents.  Org-mode
9126 supports embedding @LaTeX{} code into its files, because many academics are
9127 used to writing and reading @LaTeX{} source code, and because it can be
9128 readily processed to produce pretty output for a number of export backends.
9130 @menu
9131 * Special symbols::             Greek letters and other symbols
9132 * Subscripts and superscripts::  Simple syntax for raising/lowering text
9133 * LaTeX fragments::             Complex formulas made easy
9134 * Previewing LaTeX fragments::  What will this snippet look like?
9135 * CDLaTeX mode::                Speed up entering of formulas
9136 @end menu
9138 @node Special symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX
9139 @subsection Special symbols
9140 @cindex math symbols
9141 @cindex special symbols
9142 @cindex @TeX{} macros
9143 @cindex @LaTeX{} fragments, markup rules
9144 @cindex HTML entities
9145 @cindex @LaTeX{} entities
9147 You can use @LaTeX{} macros to insert special symbols like @samp{\alpha} to
9148 indicate the Greek letter, or @samp{\to} to indicate an arrow.  Completion
9149 for these macros is available, just type @samp{\} and maybe a few letters,
9150 and press @kbd{M-@key{TAB}} to see possible completions.  Unlike @LaTeX{}
9151 code, Org-mode allows these macros to be present without surrounding math
9152 delimiters, for example:
9154 @example
9155 Angles are written as Greek letters \alpha, \beta and \gamma.
9156 @end example
9158 @vindex org-entities
9159 During export, these symbols will be transformed into the native format of
9160 the exporter backend.  Strings like @code{\alpha} will be exported as
9161 @code{&alpha;} in the HTML output, and as @code{$\alpha$} in the @LaTeX{}
9162 output.  Similarly, @code{\nbsp} will become @code{&nbsp;} in HTML and
9163 @code{~} in @LaTeX{}.  If you need such a symbol inside a word, terminate it
9164 like this: @samp{\Aacute@{@}stor}.
9166 A large number of entities is provided, with names taken from both HTML and
9167 @LaTeX{}; see the variable @code{org-entities} for the complete list.
9168 @samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and
9169 @samp{...} are all converted into special commands creating hyphens of
9170 different lengths or a compact set of dots.
9172 If you would like to see entities displayed as UTF8 characters, use the
9173 following command@footnote{You can turn this on by default by setting the
9174 variable @code{org-pretty-entities}, or on a per-file base with the
9175 @code{#+STARTUP} option @code{entitiespretty}.}:
9177 @table @kbd
9178 @kindex C-c C-x \
9179 @item C-c C-x \
9180 Toggle display of entities as UTF-8 characters.  This does not change the
9181 buffer content which remains plain ASCII, but it overlays the UTF-8 character
9182 for display purposes only.
9183 @end table
9185 @node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX
9186 @subsection Subscripts and superscripts
9187 @cindex subscript
9188 @cindex superscript
9190 Just like in @LaTeX{}, @samp{^} and @samp{_} are used to indicate super-
9191 and subscripts.  Again, these can be used without embedding them in
9192 math-mode delimiters.  To increase the readability of ASCII text, it is
9193 not necessary (but OK) to surround multi-character sub- and superscripts
9194 with curly braces.  For example
9196 @example
9197 The mass of the sun is M_sun = 1.989 x 10^30 kg.  The radius of
9198 the sun is R_@{sun@} = 6.96 x 10^8 m.
9199 @end example
9201 @vindex org-export-with-sub-superscripts
9202 To avoid interpretation as raised or lowered text, you can quote @samp{^} and
9203 @samp{_} with a backslash: @samp{\^} and @samp{\_}.  If you write a text
9204 where the underscore is often used in a different context, Org's convention
9205 to always interpret these as subscripts can get in your way.  Configure the
9206 variable @code{org-export-with-sub-superscripts} to globally change this
9207 convention, or use, on a per-file basis:
9209 @example
9210 #+OPTIONS: ^:@{@}
9211 @end example
9213 @noindent With this setting, @samp{a_b} will not be interpreted as a
9214 subscript, but @samp{a_@{b@}} will.
9216 @table @kbd
9217 @kindex C-c C-x \
9218 @item C-c C-x \
9219 In addition to showing entities as UTF-8 characters, this command will also
9220 format sub- and superscripts in a WYSIWYM way.
9221 @end table
9223 @node LaTeX fragments, Previewing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX
9224 @subsection @LaTeX{} fragments
9225 @cindex @LaTeX{} fragments
9227 @vindex org-format-latex-header
9228 Going beyond symbols and sub- and superscripts, a full formula language is
9229 needed.  Org-mode can contain @LaTeX{} math fragments, and it supports ways
9230 to process these for several export backends.  When exporting to @LaTeX{},
9231 the code is obviously left as it is.  When exporting to HTML, Org invokes the
9232 @uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in
9233 HTML export}) to process and display the math@footnote{If you plan to use
9234 this regularly or on pages with significant page views, you should install
9235 @file{MathJax} on your own
9236 server in order to limit the load of our server.}.  Finally, it can also
9237 process the mathematical expressions into images@footnote{For this to work
9238 you need to be on a system with a working @LaTeX{} installation.  You also
9239 need the @file{dvipng} program, available at
9240 @url{http://sourceforge.net/projects/dvipng/}.  The @LaTeX{} header that will
9241 be used when processing a fragment can be configured with the variable
9242 @code{org-format-latex-header}.}  that can be displayed in a browser or in
9243 DocBook documents.
9245 @LaTeX{} fragments don't need any special marking at all.  The following
9246 snippets will be identified as @LaTeX{} source code:
9247 @itemize @bullet
9248 @item
9249 Environments of any kind@footnote{When @file{MathJax} is used, only the
9250 environment recognized by @file{MathJax} will be processed.  When
9251 @file{dvipng} is used to create images, any @LaTeX{} environments will be
9252 handled.}.  The only requirement is that the @code{\begin} statement appears
9253 on a new line, preceded by only whitespace.
9254 @item
9255 Text within the usual @LaTeX{} math delimiters.  To avoid conflicts with
9256 currency specifications, single @samp{$} characters are only recognized as
9257 math delimiters if the enclosed text contains at most two line breaks, is
9258 directly attached to the @samp{$} characters with no whitespace in between,
9259 and if the closing @samp{$} is followed by whitespace, punctuation or a dash.
9260 For the other delimiters, there is no such restriction, so when in doubt, use
9261 @samp{\(...\)} as inline math delimiters.
9262 @end itemize
9264 @noindent For example:
9266 @example
9267 \begin@{equation@}                          % arbitrary environments,
9268 x=\sqrt@{b@}                                % even tables, figures
9269 \end@{equation@}                            % etc
9271 If $a^2=b$ and \( b=2 \), then the solution must be
9272 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
9273 @end example
9275 @noindent
9276 @vindex org-format-latex-options
9277 If you need any of the delimiter ASCII sequences for other purposes, you
9278 can configure the option @code{org-format-latex-options} to deselect the
9279 ones you do not wish to have interpreted by the @LaTeX{} converter.
9281 @vindex org-export-with-LaTeX-fragments
9282 LaTeX processing can be configured with the variable
9283 @code{org-export-with-LaTeX-fragments}.  The default setting is @code{t}
9284 which means @file{MathJax} for HTML, and no processing for DocBook, ASCII and
9285 LaTeX backends.  You can also set this variable on a per-file basis using one
9286 of these lines:
9288 @example
9289 #+OPTIONS: LaTeX:t          @r{Do the right thing automatically (MathJax)}
9290 #+OPTIONS: LaTeX:dvipng     @r{Force using dvipng images}
9291 #+OPTIONS: LaTeX:nil        @r{Do not process @LaTeX{} fragments at all}
9292 #+OPTIONS: LaTeX:verbatim   @r{Verbatim export, for jsMath or so}
9293 @end example
9295 @node Previewing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
9296 @subsection Previewing LaTeX fragments
9297 @cindex LaTeX fragments, preview
9299 If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to
9300 produce preview images of the typeset expressions:
9302 @table @kbd
9303 @kindex C-c C-x C-l
9304 @item C-c C-x C-l
9305 Produce a preview image of the @LaTeX{} fragment at point and overlay it
9306 over the source code.  If there is no fragment at point, process all
9307 fragments in the current entry (between two headlines).  When called
9308 with a prefix argument, process the entire subtree.  When called with
9309 two prefix arguments, or when the cursor is before the first headline,
9310 process the entire buffer.
9311 @kindex C-c C-c
9312 @item C-c C-c
9313 Remove the overlay preview images.
9314 @end table
9316 @vindex org-format-latex-options
9317 You can customize the variable @code{org-format-latex-options} to influence
9318 some aspects of the preview.  In particular, the @code{:scale} (and for HTML
9319 export, @code{:html-scale}) property can be used to adjust the size of the
9320 preview images.
9322 @node CDLaTeX mode,  , Previewing LaTeX fragments, Embedded LaTeX
9323 @subsection Using CDLa@TeX{} to enter math
9324 @cindex CDLa@TeX{}
9326 CDLa@TeX{} mode is a minor mode that is normally used in combination with a
9327 major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
9328 environments and math templates.  Inside Org-mode, you can make use of
9329 some of the features of CDLa@TeX{} mode.  You need to install
9330 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
9331 AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
9332 Don't use CDLa@TeX{} mode itself under Org-mode, but use the light
9333 version @code{org-cdlatex-mode} that comes as part of Org-mode.  Turn it
9334 on for the current buffer with @code{M-x org-cdlatex-mode}, or for all
9335 Org files with
9337 @lisp
9338 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
9339 @end lisp
9341 When this mode is enabled, the following features are present (for more
9342 details see the documentation of CDLa@TeX{} mode):
9343 @itemize @bullet
9344 @kindex C-c @{
9345 @item
9346 Environment templates can be inserted with @kbd{C-c @{}.
9347 @item
9348 @kindex @key{TAB}
9349 The @key{TAB} key will do template expansion if the cursor is inside a
9350 @LaTeX{} fragment@footnote{Org-mode has a method to test if the cursor is
9351 inside such a fragment, see the documentation of the function
9352 @code{org-inside-LaTeX-fragment-p}.}.  For example, @key{TAB} will
9353 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
9354 correctly inside the first brace.  Another @key{TAB} will get you into
9355 the second brace.  Even outside fragments, @key{TAB} will expand
9356 environment abbreviations at the beginning of a line.  For example, if
9357 you write @samp{equ} at the beginning of a line and press @key{TAB},
9358 this abbreviation will be expanded to an @code{equation} environment.
9359 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
9360 @item
9361 @kindex _
9362 @kindex ^
9363 @vindex cdlatex-simplify-sub-super-scripts
9364 Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these
9365 characters together with a pair of braces.  If you use @key{TAB} to move
9366 out of the braces, and if the braces surround only a single character or
9367 macro, they are removed again (depending on the variable
9368 @code{cdlatex-simplify-sub-super-scripts}).
9369 @item
9370 @kindex `
9371 Pressing the backquote @kbd{`} followed by a character inserts math
9372 macros, also outside @LaTeX{} fragments.  If you wait more than 1.5 seconds
9373 after the backquote, a help window will pop up.
9374 @item
9375 @kindex '
9376 Pressing the single-quote @kbd{'} followed by another character modifies
9377 the symbol before point with an accent or a font.  If you wait more than
9378 1.5 seconds after the single-quote, a help window will pop up.  Character
9379 modification will work only inside @LaTeX{} fragments; outside the quote
9380 is normal.
9381 @end itemize
9383 @node Exporting, Publishing, Markup, Top
9384 @chapter Exporting
9385 @cindex exporting
9387 Org-mode documents can be exported into a variety of other formats.  For
9388 printing and sharing of notes, ASCII export produces a readable and simple
9389 version of an Org file.  HTML export allows you to publish a notes file on
9390 the web, while the XOXO format provides a solid base for exchange with a
9391 broad range of other applications.  @LaTeX{} export lets you use Org-mode and
9392 its structured editing functions to easily create @LaTeX{} files.  DocBook
9393 export makes it possible to convert Org files to many other formats using
9394 DocBook tools.  OpenDocumentText export allows seamless colloboration across
9395 organizational boundaries.  For project management you can create gantt and
9396 resource charts by using TaskJuggler export.  To incorporate entries with
9397 associated times like deadlines or appointments into a desktop calendar
9398 program like iCal, Org-mode can also produce extracts in the iCalendar
9399 format.  Currently Org-mode only supports export, not import of these
9400 different formats.
9402 Org supports export of selected regions when @code{transient-mark-mode} is
9403 enabled (default in Emacs 23).
9405 @menu
9406 * Selective export::            Using tags to select and exclude trees
9407 * Export options::              Per-file export settings
9408 * The export dispatcher::       How to access exporter commands
9409 * ASCII/Latin-1/UTF-8 export::  Exporting to flat files with encoding
9410 * HTML export::                 Exporting to HTML
9411 * LaTeX and PDF export::        Exporting to @LaTeX{}, and processing to PDF
9412 * DocBook export::              Exporting to DocBook
9413 * OpenDocumentText export::     Exporting to OpenDocumentText
9414 * TaskJuggler export::          Exporting to TaskJuggler
9415 * Freemind export::             Exporting to Freemind mind maps
9416 * XOXO export::                 Exporting to XOXO
9417 * iCalendar export::            Exporting in iCalendar format
9418 @end menu
9420 @node Selective export, Export options, Exporting, Exporting
9421 @section Selective export
9422 @cindex export, selective by tags or TODO keyword
9424 @vindex org-export-select-tags
9425 @vindex org-export-exclude-tags
9426 @cindex org-export-with-tasks
9427 You may use tags to select the parts of a document that should be exported,
9428 or to exclude parts from export.  This behavior is governed by two variables:
9429 @code{org-export-select-tags} and @code{org-export-exclude-tags}.
9431 @enumerate
9432 @item 
9433 Org first checks if any of the @emph{select} tags is present in the
9434 buffer.  If yes, all trees that do not carry one of these tags will be
9435 excluded.  If a selected tree is a subtree, the heading hierarchy above it
9436 will also be selected for export, but not the text below those headings.
9438 @item
9439 If none of the select tags is found, the whole buffer will be selected for
9440 export.
9442 @item
9443 Finally, all subtrees that are marked by any of the @emph{exclude} tags will
9444 be removed from the export buffer.
9445 @end enumerate
9447 The variable @code{org-export-with-tasks} can be configured to select which
9448 kind of tasks should be included for export.  See the docstring of the
9449 variable for more information.
9451 @node Export options, The export dispatcher, Selective export, Exporting
9452 @section Export options
9453 @cindex options, for export
9455 @cindex completion, of option keywords
9456 The exporter recognizes special lines in the buffer which provide
9457 additional information.  These lines may be put anywhere in the file.
9458 The whole set of lines can be inserted into the buffer with @kbd{C-c
9459 C-e t}.  For individual lines, a good way to make sure the keyword is
9460 correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
9461 (@pxref{Completion}).   For a summary of other in-buffer settings not
9462 specifically related to export, see @ref{In-buffer settings}.
9463 In particular, note that you can place commonly-used (export) options in
9464 a separate file which can be included using @code{#+SETUPFILE}.
9466 @table @kbd
9467 @orgcmd{C-c C-e t,org-insert-export-options-template}
9468 Insert template with export options, see example below.
9469 @end table
9471 @cindex #+TITLE
9472 @cindex #+AUTHOR
9473 @cindex #+DATE
9474 @cindex #+EMAIL
9475 @cindex #+DESCRIPTION
9476 @cindex #+KEYWORDS
9477 @cindex #+LANGUAGE
9478 @cindex #+TEXT
9479 @cindex #+OPTIONS
9480 @cindex #+BIND
9481 @cindex #+LINK_UP
9482 @cindex #+LINK_HOME
9483 @cindex #+EXPORT_SELECT_TAGS
9484 @cindex #+EXPORT_EXCLUDE_TAGS
9485 @cindex #+XSLT
9486 @cindex #+LATEX_HEADER
9487 @vindex user-full-name
9488 @vindex user-mail-address
9489 @vindex org-export-default-language
9490 @example
9491 #+TITLE:       the title to be shown (default is the buffer name)
9492 #+AUTHOR:      the author (default taken from @code{user-full-name})
9493 #+DATE:        a date, fixed, or a format string for @code{format-time-string}
9494 #+EMAIL:       his/her email address (default from @code{user-mail-address})
9495 #+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag
9496 #+KEYWORDS:    the page keywords, e.g.@: for the XHTML meta tag
9497 #+LANGUAGE:    language for HTML, e.g.@: @samp{en} (@code{org-export-default-language})
9498 #+TEXT:        Some descriptive text to be inserted at the beginning.
9499 #+TEXT:        Several lines may be given.
9500 #+OPTIONS:     H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
9501 #+BIND:        lisp-var lisp-val, e.g.@:: org-export-latex-low-levels itemize
9502                @r{You need to confirm using these, or configure @code{org-export-allow-BIND}}
9503 #+LINK_UP:     the ``up'' link of an exported page
9504 #+LINK_HOME:   the ``home'' link of an exported page
9505 #+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@}
9506 #+EXPORT_SELECT_TAGS:   Tags that select a tree for export
9507 #+EXPORT_EXCLUDE_TAGS:  Tags that exclude a tree from export
9508 #+XSLT:        the XSLT stylesheet used by DocBook exporter to generate FO file
9509 @end example
9511 @noindent
9512 The OPTIONS line is a compact@footnote{If you want to configure many options
9513 this way, you can use several OPTIONS lines.} form to specify export
9514 settings.  Here you can:
9515 @cindex headline levels
9516 @cindex section-numbers
9517 @cindex table of contents
9518 @cindex line-break preservation
9519 @cindex quoted HTML tags
9520 @cindex fixed-width sections
9521 @cindex tables
9522 @cindex @TeX{}-like syntax for sub- and superscripts
9523 @cindex footnotes
9524 @cindex special strings
9525 @cindex emphasized text
9526 @cindex @TeX{} macros
9527 @cindex @LaTeX{} fragments
9528 @cindex author info, in export
9529 @cindex time info, in export
9530 @vindex org-export-plist-vars
9531 @vindex org-export-author-info
9532 @vindex org-export-creator-info
9533 @vindex org-export-email-info
9534 @vindex org-export-time-stamp-file
9535 @example
9536 H:         @r{set the number of headline levels for export}
9537 num:       @r{turn on/off section-numbers}
9538 toc:       @r{turn on/off table of contents, or set level limit (integer)}
9539 \n:        @r{turn on/off line-break-preservation (DOES NOT WORK)}
9540 @@:         @r{turn on/off quoted HTML tags}
9541 ::         @r{turn on/off fixed-width sections}
9542 |:         @r{turn on/off tables}
9543 ^:         @r{turn on/off @TeX{}-like syntax for sub- and superscripts.  If}
9544            @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but}
9545            @r{the simple @code{a_b} will be left as it is.}
9546 -:         @r{turn on/off conversion of special strings.}
9547 f:         @r{turn on/off footnotes like this[1].}
9548 todo:      @r{turn on/off inclusion of TODO keywords into exported text}
9549 tasks:     @r{turn on/off inclusion of tasks (TODO items), can be nil to remove}
9550            @r{all tasks, @code{todo} to remove DONE tasks, or list of kwds to keep}
9551 pri:       @r{turn on/off priority cookies}
9552 tags:      @r{turn on/off inclusion of tags, may also be @code{not-in-toc}}
9553 <:         @r{turn on/off inclusion of any time/date stamps like DEADLINES}
9554 *:         @r{turn on/off emphasized text (bold, italic, underlined)}
9555 TeX:       @r{turn on/off simple @TeX{} macros in plain text}
9556 LaTeX:     @r{configure export of @LaTeX{} fragments.  Default @code{auto}}
9557 skip:      @r{turn on/off skipping the text before the first heading}
9558 author:    @r{turn on/off inclusion of author name/email into exported file}
9559 email:     @r{turn on/off inclusion of author email into exported file}
9560 creator:   @r{turn on/off inclusion of creator info into exported file}
9561 timestamp: @r{turn on/off inclusion creation time into exported file}
9562 d:         @r{turn on/off inclusion of drawers}
9563 @end example
9564 @noindent
9565 These options take effect in both the HTML and @LaTeX{} export, except for
9566 @code{TeX} and @code{LaTeX} options, which are respectively @code{t} and
9567 @code{nil} for the @LaTeX{} export.
9569 The default values for these and many other options are given by a set of
9570 variables.  For a list of such variables, the corresponding OPTIONS keys and
9571 also the publishing keys (@pxref{Project alist}), see the constant
9572 @code{org-export-plist-vars}.
9574 When exporting only a single subtree by selecting it with @kbd{C-c @@} before
9575 calling an export command, the subtree can overrule some of the file's export
9576 settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE},
9577 @code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and
9578 @code{EXPORT_OPTIONS}.
9580 @node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting
9581 @section The export dispatcher
9582 @cindex dispatcher, for export commands
9584 All export commands can be reached using the export dispatcher, which is a
9585 prefix key that prompts for an additional key specifying the command.
9586 Normally the entire file is exported, but if there is an active region that
9587 contains one outline tree, the first heading is used as document title and
9588 the subtrees are exported.
9590 @table @kbd
9591 @orgcmd{C-c C-e,org-export}
9592 @vindex org-export-run-in-background
9593 Dispatcher for export and publishing commands.  Displays a help-window
9594 listing the additional key(s) needed to launch an export or publishing
9595 command.  The prefix arg is passed through to the exporter.  A double prefix
9596 @kbd{C-u C-u} causes most commands to be executed in the background, in a
9597 separate Emacs process@footnote{To make this behavior the default, customize
9598 the variable @code{org-export-run-in-background}.}.
9599 @orgcmd{C-c C-e v,org-export-visible}
9600 Like @kbd{C-c C-e}, but only export the text that is currently visible
9601 (i.e.@: not hidden by outline visibility).
9602 @orgcmd{C-u C-u C-c C-e,org-export}
9603 @vindex org-export-run-in-background
9604 Call the exporter, but reverse the setting of
9605 @code{org-export-run-in-background}, i.e.@: request background processing if
9606 not set, or force processing in the current Emacs process if set.
9607 @end table
9609 @node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting
9610 @section ASCII/Latin-1/UTF-8 export
9611 @cindex ASCII export
9612 @cindex Latin-1 export
9613 @cindex UTF-8 export
9615 ASCII export produces a simple and very readable version of an Org-mode
9616 file, containing only plain ASCII.  Latin-1 and UTF-8 export augment the file
9617 with special characters and symbols available in these encodings.
9619 @cindex region, active
9620 @cindex active region
9621 @cindex transient-mark-mode
9622 @table @kbd
9623 @orgcmd{C-c C-e a,org-export-as-ascii}
9624 @cindex property, EXPORT_FILE_NAME
9625 Export as ASCII file.  For an Org file, @file{myfile.org}, the ASCII file
9626 will be @file{myfile.txt}.  The file will be overwritten without
9627 warning.  If there is an active region@footnote{This requires
9628 @code{transient-mark-mode} be turned on.}, only the region will be
9629 exported.  If the selected region is a single tree@footnote{To select the
9630 current subtree, use @kbd{C-c @@}.}, the tree head will
9631 become the document title.  If the tree head entry has or inherits an
9632 @code{EXPORT_FILE_NAME} property, that name will be used for the
9633 export.
9634 @orgcmd{C-c C-e A,org-export-as-ascii-to-buffer}
9635 Export to a temporary buffer.  Do not create a file.
9636 @orgcmd{C-c C-e n,org-export-as-latin1}
9637 @xorgcmd{C-c C-e N,org-export-as-latin1-to-buffer}
9638 Like the above commands, but use Latin-1 encoding.
9639 @orgcmd{C-c C-e u,org-export-as-utf8}
9640 @xorgcmd{C-c C-e U,org-export-as-utf8-to-buffer}
9641 Like the above commands, but use UTF-8 encoding.
9642 @item C-c C-e v a/n/u
9643 Export only the visible part of the document.
9644 @end table
9646 @cindex headline levels, for exporting
9647 In the exported version, the first 3 outline levels will become
9648 headlines, defining a general document structure.  Additional levels
9649 will be exported as itemized lists.  If you want that transition to occur
9650 at a different level, specify it with a prefix argument.  For example,
9652 @example
9653 @kbd{C-1 C-c C-e a}
9654 @end example
9656 @noindent
9657 creates only top level headlines and does the rest as items.  When
9658 headlines are converted to items, the indentation of the text following
9659 the headline is changed to fit nicely under the item.  This is done with
9660 the assumption that the first body line indicates the base indentation of
9661 the body text.  Any indentation larger than this is adjusted to preserve
9662 the layout relative to the first line.  Should there be lines with less
9663 indentation than the first, these are left alone.
9665 @vindex org-export-ascii-links-to-notes
9666 Links will be exported in a footnote-like style, with the descriptive part in
9667 the text and the link in a note before the next heading.  See the variable
9668 @code{org-export-ascii-links-to-notes} for details and other options.
9670 @node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting
9671 @section HTML export
9672 @cindex HTML export
9674 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
9675 HTML formatting, in ways similar to John Gruber's @emph{markdown}
9676 language, but with additional support for tables.
9678 @menu
9679 * HTML Export commands::        How to invoke HTML export
9680 * HTML preamble and postamble::  How to insert a preamble and a postamble
9681 * Quoting HTML tags::           Using direct HTML in Org-mode
9682 * Links in HTML export::        How links will be interpreted and formatted
9683 * Tables in HTML export::       How to modify the formatting of tables
9684 * Images in HTML export::       How to insert figures into HTML output
9685 * Math formatting in HTML export::  Beautiful math also on the web
9686 * Text areas in HTML export::   An alternative way to show an example
9687 * CSS support::                 Changing the appearance of the output
9688 * JavaScript support::          Info and Folding in a web browser
9689 @end menu
9691 @node HTML Export commands, HTML preamble and postamble, HTML export, HTML export
9692 @subsection HTML export commands
9694 @cindex region, active
9695 @cindex active region
9696 @cindex transient-mark-mode
9697 @table @kbd
9698 @orgcmd{C-c C-e h,org-export-as-html}
9699 @cindex property, EXPORT_FILE_NAME
9700 Export as HTML file.  For an Org file @file{myfile.org},
9701 the HTML file will be @file{myfile.html}.  The file will be overwritten
9702 without warning.  If there is an active region@footnote{This requires
9703 @code{transient-mark-mode} be turned on.}, only the region will be
9704 exported.  If the selected region is a single tree@footnote{To select the
9705 current subtree, use @kbd{C-c @@}.}, the tree head will become the document
9706 title.  If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}
9707 property, that name will be used for the export.
9708 @orgcmd{C-c C-e b,org-export-as-html-and-open}
9709 Export as HTML file and immediately open it with a browser.
9710 @orgcmd{C-c C-e H,org-export-as-html-to-buffer}
9711 Export to a temporary buffer.  Do not create a file.
9712 @orgcmd{C-c C-e R,org-export-region-as-html}
9713 Export the active region to a temporary buffer.  With a prefix argument, do
9714 not produce the file header and footer, but just the plain HTML section for
9715 the region.  This is good for cut-and-paste operations.
9716 @item C-c C-e v h/b/H/R
9717 Export only the visible part of the document.
9718 @item M-x org-export-region-as-html
9719 Convert the region to HTML under the assumption that it was Org-mode
9720 syntax before.  This is a global command that can be invoked in any
9721 buffer.
9722 @item M-x org-replace-region-by-HTML
9723 Replace the active region (assumed to be in Org-mode syntax) by HTML
9724 code.
9725 @end table
9727 @cindex headline levels, for exporting
9728 In the exported version, the first 3 outline levels will become headlines,
9729 defining a general document structure.  Additional levels will be exported as
9730 itemized lists.  If you want that transition to occur at a different level,
9731 specify it with a numeric prefix argument.  For example,
9733 @example
9734 @kbd{C-2 C-c C-e b}
9735 @end example
9737 @noindent
9738 creates two levels of headings and does the rest as items.
9741 @node HTML preamble and postamble, Quoting HTML tags, HTML Export commands, HTML export
9742 @subsection HTML preamble and postamble
9743 @vindex org-export-html-preamble
9744 @vindex org-export-html-postamble
9745 @vindex org-export-html-preamble-format
9746 @vindex org-export-html-postamble-format
9747 @vindex org-export-html-validation-link
9748 @vindex org-export-author-info
9749 @vindex org-export-email-info
9750 @vindex org-export-creator-info
9751 @vindex org-export-time-stamp-file
9753 The HTML exporter lets you define a preamble and a postamble.
9755 The default value for @code{org-export-html-preamble} is @code{t}, which
9756 means that the preamble is inserted depending on the relevant formatting
9757 string in @code{org-export-html-preamble-format}.  Setting
9758 @code{org-export-html-preamble} to a string will override the default
9759 formatting string.  Setting it to a function, will insert the output of the
9760 function.  Setting to @code{nil} will not insert any preamble.
9762 The default value for @code{org-export-html-postamble} is @code{'auto}, which
9763 means that the HTML exporter will look for the value of
9764 @code{org-export-author-info}, @code{org-export-email-info},
9765 @code{org-export-creator-info} and @code{org-export-time-stamp-file},
9766 @code{org-export-html-validation-link} and build the postamble from these
9767 values.  Setting @code{org-export-html-postamble} to @code{t} will insert the
9768 postamble from the relevant formatting string found in
9769 @code{org-export-html-postamble-format}.  Setting it to @code{nil} will not
9770 insert any postamble.
9772 @node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export
9773 @subsection Quoting HTML tags
9775 Plain @samp{<} and @samp{>} are always transformed to @samp{&lt;} and
9776 @samp{&gt;} in HTML export.  If you want to include simple HTML tags
9777 which should be interpreted as such, mark them with @samp{@@} as in
9778 @samp{@@<b>bold text@@</b>}.  Note that this really works only for
9779 simple tags.  For more extensive HTML that should be copied verbatim to
9780 the exported file use either
9782 @cindex #+HTML
9783 @cindex #+BEGIN_HTML
9784 @example
9785 #+HTML: Literal HTML code for export
9786 @end example
9788 @noindent or
9789 @cindex #+BEGIN_HTML
9791 @example
9792 #+BEGIN_HTML
9793 All lines between these markers are exported literally
9794 #+END_HTML
9795 @end example
9798 @node Links in HTML export, Tables in HTML export, Quoting HTML tags, HTML export
9799 @subsection Links in HTML export
9801 @cindex links, in HTML export
9802 @cindex internal links, in HTML export
9803 @cindex external links, in HTML export
9804 Internal links (@pxref{Internal links}) will continue to work in HTML.  This
9805 includes automatic links created by radio targets (@pxref{Radio
9806 targets}).  Links to external files will still work if the target file is on
9807 the same @i{relative} path as the published Org file.  Links to other
9808 @file{.org} files will be translated into HTML links under the assumption
9809 that an HTML version also exists of the linked file, at the same relative
9810 path.  @samp{id:} links can then be used to jump to specific entries across
9811 files.  For information related to linking files while publishing them to a
9812 publishing directory see @ref{Publishing links}.
9814 If you want to specify attributes for links, you can do so using a special
9815 @code{#+ATTR_HTML} line to define attributes that will be added to the
9816 @code{<a>} or @code{<img>} tags.  Here is an example that sets @code{title}
9817 and @code{style} attributes for a link:
9819 @cindex #+ATTR_HTML
9820 @example
9821 #+ATTR_HTML: title="The Org-mode homepage" style="color:red;"
9822 [[http://orgmode.org]]
9823 @end example
9825 @node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export
9826 @subsection Tables
9827 @cindex tables, in HTML
9828 @vindex org-export-html-table-tag
9830 Org-mode tables are exported to HTML using the table tag defined in
9831 @code{org-export-html-table-tag}.  The default setting makes tables without
9832 cell borders and frame.  If you would like to change this for individual
9833 tables, place something like the following before the table:
9835 @cindex #+CAPTION
9836 @cindex #+ATTR_HTML
9837 @example
9838 #+CAPTION: This is a table with lines around and between cells
9839 #+ATTR_HTML: border="2" rules="all" frame="all"
9840 @end example
9842 @node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export
9843 @subsection Images in HTML export
9845 @cindex images, inline in HTML
9846 @cindex inlining images in HTML
9847 @vindex org-export-html-inline-images
9848 HTML export can inline images given as links in the Org file, and
9849 it can make an image the clickable part of a link.  By
9850 default@footnote{But see the variable
9851 @code{org-export-html-inline-images}.}, images are inlined if a link does
9852 not have a description.  So @samp{[[file:myimg.jpg]]} will be inlined,
9853 while @samp{[[file:myimg.jpg][the image]]} will just produce a link
9854 @samp{the image} that points to the image.  If the description part
9855 itself is a @code{file:} link or a @code{http:} URL pointing to an
9856 image, this image will be inlined and activated so that clicking on the
9857 image will activate the link.  For example, to include a thumbnail that
9858 will link to a high resolution version of the image, you could use:
9860 @example
9861 [[file:highres.jpg][file:thumb.jpg]]
9862 @end example
9864 If you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}.
9865 In the example below we specify the @code{alt} and @code{title} attributes to
9866 support text viewers and accessibility, and align it to the right.
9868 @cindex #+CAPTION
9869 @cindex #+ATTR_HTML
9870 @example
9871 #+CAPTION: A black cat stalking a spider
9872 #+ATTR_HTML: alt="cat/spider image" title="Action!" align="right"
9873 [[./img/a.jpg]]
9874 @end example
9876 @noindent
9877 You could use @code{http} addresses just as well.
9879 @node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export
9880 @subsection Math formatting in HTML export
9881 @cindex MathJax
9882 @cindex dvipng
9884 @LaTeX{} math snippets (@pxref{LaTeX fragments}) can be displayed in two
9885 different ways on HTML pages.  The default is to use the
9886 @uref{http://www.mathjax.org, MathJax system} which should work out of the
9887 box with Org mode installation because @code{http://orgmode.org} serves
9888 @file{MathJax} for Org-mode users for small applications and for testing
9889 purposes.  @b{If you plan to use this regularly or on pages with significant
9890 page views, you should install@footnote{Installation instructions can be
9891 found on the MathJax website, see
9892 @uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on
9893 your own server in order to limit the load of our server.}  To configure
9894 @file{MathJax}, use the variable @code{org-export-html-mathjax-options} or
9895 insert something like the following into the buffer:
9897 @example
9898 #+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
9899 @end example
9901 @noindent See the docstring of the variable
9902 @code{org-export-html-mathjax-options} for the meaning of the parameters in
9903 this line.
9905 If you prefer, you can also request that @LaTeX{} fragments are processed
9906 into small images that will be inserted into the browser page.  Before the
9907 availability of MathJax, this was the default method for Org files.  This
9908 method requires that the @file{dvipng} program is available on your system.
9909 You can still get this processing with
9911 @example
9912 #+OPTIONS: LaTeX:dvipng
9913 @end example
9915 @node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export
9916 @subsection Text areas in HTML export
9918 @cindex text areas, in HTML
9919 An alternative way to publish literal code examples in HTML is to use text
9920 areas, where the example can even be edited before pasting it into an
9921 application.  It is triggered by a @code{-t} switch at an @code{example} or
9922 @code{src} block.  Using this switch disables any options for syntax and
9923 label highlighting, and line numbering, which may be present.  You may also
9924 use @code{-h} and @code{-w} switches to specify the height and width of the
9925 text area, which default to the number of lines in the example, and 80,
9926 respectively.  For example
9928 @example
9929 #+BEGIN_EXAMPLE -t -w 40
9930   (defun org-xor (a b)
9931      "Exclusive or."
9932      (if a (not b) b))
9933 #+END_EXAMPLE
9934 @end example
9937 @node CSS support, JavaScript support, Text areas in HTML export, HTML export
9938 @subsection CSS support
9939 @cindex CSS, for HTML export
9940 @cindex HTML export, CSS
9942 @vindex org-export-html-todo-kwd-class-prefix
9943 @vindex org-export-html-tag-class-prefix
9944 You can also give style information for the exported file.  The HTML exporter
9945 assigns the following special CSS classes@footnote{If the classes on TODO
9946 keywords and tags lead to conflicts, use the variables
9947 @code{org-export-html-todo-kwd-class-prefix} and
9948 @code{org-export-html-tag-class-prefix} to make them unique.} to appropriate
9949 parts of the document---your style specifications may change these, in
9950 addition to any of the standard classes like for headlines, tables, etc.
9951 @example
9952 p.author            @r{author information, including email}
9953 p.date              @r{publishing date}
9954 p.creator           @r{creator info, about org-mode version}
9955 .title              @r{document title}
9956 .todo               @r{TODO keywords, all not-done states}
9957 .done               @r{the DONE keywords, all states that count as done}
9958 .WAITING            @r{each TODO keyword also uses a class named after itself}
9959 .timestamp          @r{timestamp}
9960 .timestamp-kwd      @r{keyword associated with a timestamp, like SCHEDULED}
9961 .timestamp-wrapper  @r{span around keyword plus timestamp}
9962 .tag                @r{tag in a headline}
9963 ._HOME              @r{each tag uses itself as a class, "@@" replaced by "_"}
9964 .target             @r{target for links}
9965 .linenr             @r{the line number in a code example}
9966 .code-highlighted   @r{for highlighting referenced code lines}
9967 div.outline-N       @r{div for outline level N (headline plus text))}
9968 div.outline-text-N  @r{extra div for text at outline level N}
9969 .section-number-N   @r{section number in headlines, different for each level}
9970 div.figure          @r{how to format an inlined image}
9971 pre.src             @r{formatted source code}
9972 pre.example         @r{normal example}
9973 p.verse             @r{verse paragraph}
9974 div.footnotes       @r{footnote section headline}
9975 p.footnote          @r{footnote definition paragraph, containing a footnote}
9976 .footref            @r{a footnote reference number (always a <sup>)}
9977 .footnum            @r{footnote number in footnote definition (always <sup>)}
9978 @end example
9980 @vindex org-export-html-style-default
9981 @vindex org-export-html-style-include-default
9982 @vindex org-export-html-style
9983 @vindex org-export-html-extra
9984 @vindex org-export-html-style-default
9985 Each exported file contains a compact default style that defines these
9986 classes in a basic way@footnote{This style is defined in the constant
9987 @code{org-export-html-style-default}, which you should not modify.  To turn
9988 inclusion of these defaults off, customize
9989 @code{org-export-html-style-include-default}}.  You may overwrite these
9990 settings, or add to them by using the variables @code{org-export-html-style}
9991 (for Org-wide settings) and @code{org-export-html-style-extra} (for more
9992 fine-grained settings, like file-local settings).  To set the latter variable
9993 individually for each file, you can use
9995 @cindex #+STYLE
9996 @example
9997 #+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />
9998 @end example
10000 @noindent
10001 For longer style definitions, you can use several such lines.  You could also
10002 directly write a @code{<style>} @code{</style>} section in this way, without
10003 referring to an external file.
10005 In order to add styles to a subtree, use the @code{:HTML_CONTAINER_CLASS:}
10006 property to assign a class to the tree.  In order to specify CSS styles for a
10007 particular headline, you can use the id specified in a @code{:CUSTOM_ID:}
10008 property.
10010 @c FIXME: More about header and footer styles
10011 @c FIXME: Talk about links and targets.
10013 @node JavaScript support,  , CSS support, HTML export
10014 @subsection JavaScript supported display of web pages
10016 @cindex Rose, Sebastian
10017 Sebastian Rose has written a JavaScript program especially designed to
10018 enhance the web viewing experience of HTML files created with Org.  This
10019 program allows you to view large files in two different ways.  The first one
10020 is an @emph{Info}-like mode where each section is displayed separately and
10021 navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys
10022 as well, press @kbd{?} for an overview of the available keys).  The second
10023 view type is a @emph{folding} view much like Org provides inside Emacs.  The
10024 script is available at @url{http://orgmode.org/org-info.js} and you can find
10025 the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}.
10026 We host the script at our site, but if you use it a lot, you might
10027 not want to be dependent on @url{orgmode.org} and prefer to install a local
10028 copy on your own web server.
10030 To use the script, you need to make sure that the @file{org-jsinfo.el} module
10031 gets loaded.  It should be loaded by default, but you can try @kbd{M-x
10032 customize-variable @key{RET} org-modules @key{RET}} to convince yourself that
10033 this is indeed the case.  All it then takes to make use of the program is
10034 adding a single line to the Org file:
10036 @cindex #+INFOJS_OPT
10037 @example
10038 #+INFOJS_OPT: view:info toc:nil
10039 @end example
10041 @noindent
10042 If this line is found, the HTML header will automatically contain the code
10043 needed to invoke the script.  Using the line above, you can set the following
10044 viewing options:
10046 @example
10047 path:    @r{The path to the script.  The default is to grab the script from}
10048          @r{@url{http://orgmode.org/org-info.js}, but you might want to have}
10049          @r{a local copy and use a path like @samp{../scripts/org-info.js}.}
10050 view:    @r{Initial view when website is first shown.  Possible values are:}
10051          info      @r{Info-like interface with one section per page.}
10052          overview  @r{Folding interface, initially showing only top-level.}
10053          content   @r{Folding interface, starting with all headlines visible.}
10054          showall   @r{Folding interface, all headlines and text visible.}
10055 sdepth:  @r{Maximum headline level that will still become an independent}
10056          @r{section for info and folding modes.  The default is taken from}
10057          @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).}
10058          @r{If this is smaller than in @code{org-export-headline-levels}, each}
10059          @r{info/folding section can still contain child headlines.}
10060 toc:     @r{Should the table of contents @emph{initially} be visible?}
10061          @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}
10062 tdepth:  @r{The depth of the table of contents.  The defaults are taken from}
10063          @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}
10064 ftoc:    @r{Does the CSS of the page specify a fixed position for the "toc"?}
10065          @r{If yes, the toc will never be displayed as a section.}
10066 ltoc:    @r{Should there be short contents (children) in each section?}
10067          @r{Make this @code{above} if the section should be above initial text.}
10068 mouse:   @r{Headings are highlighted when the mouse is over them.  Should be}
10069          @r{@samp{underline} (default) or a background color like @samp{#cccccc}.}
10070 buttons: @r{Should view-toggle buttons be everywhere?  When @code{nil} (the}
10071          @r{default), only one such button will be present.}
10072 @end example
10073 @noindent
10074 @vindex org-infojs-options
10075 @vindex org-export-html-use-infojs
10076 You can choose default values for these options by customizing the variable
10077 @code{org-infojs-options}.  If you always want to apply the script to your
10078 pages, configure the variable @code{org-export-html-use-infojs}.
10080 @node LaTeX and PDF export, DocBook export, HTML export, Exporting
10081 @section @LaTeX{} and PDF export
10082 @cindex @LaTeX{} export
10083 @cindex PDF export
10084 @cindex Guerry, Bastien
10086 Org-mode contains a @LaTeX{} exporter written by Bastien Guerry.  With
10087 further processing@footnote{The default LaTeX output is designed for
10088 processing with pdftex or latex.  It includes packages that are not
10089 compatible with xetex and possibly luatex.  See the variables
10090 @code{org-export-latex-default-packages-alist} and
10091 @code{org-export-latex-packages-alist}.}, this backend is also used to
10092 produce PDF output.  Since the @LaTeX{} output uses @file{hyperref} to
10093 implement links and cross references, the PDF output file will be fully
10094 linked.  Beware of the fact that your @code{org} file has to be properly
10095 structured in order to be correctly exported: respect the hierarchy of
10096 sections.
10098 @menu
10099 * LaTeX/PDF export commands::   Which key invokes which commands
10100 * Header and sectioning::       Setting up the export file structure
10101 * Quoting LaTeX code::          Incorporating literal @LaTeX{} code
10102 * Tables in LaTeX export::      Options for exporting tables to @LaTeX{}
10103 * Images in LaTeX export::      How to insert figures into @LaTeX{} output
10104 * Beamer class export::         Turning the file into a presentation
10105 @end menu
10107 @node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export
10108 @subsection @LaTeX{} export commands
10110 @cindex region, active
10111 @cindex active region
10112 @cindex transient-mark-mode
10113 @table @kbd
10114 @orgcmd{C-c C-e l,org-export-as-latex}
10115 @cindex property EXPORT_FILE_NAME
10116 Export as @LaTeX{} file.  For an Org file
10117 @file{myfile.org}, the @LaTeX{} file will be @file{myfile.tex}.  The file will
10118 be overwritten without warning.  If there is an active region@footnote{This
10119 requires @code{transient-mark-mode} be turned on.}, only the region will be
10120 exported.  If the selected region is a single tree@footnote{To select the
10121 current subtree, use @kbd{C-c @@}.}, the tree head will become the document
10122 title.  If the tree head entry has or inherits an @code{EXPORT_FILE_NAME}
10123 property, that name will be used for the export.
10124 @orgcmd{C-c C-e L,org-export-as-latex-to-buffer}
10125 Export to a temporary buffer.  Do not create a file.
10126 @item C-c C-e v l/L 
10127 Export only the visible part of the document.
10128 @item M-x org-export-region-as-latex
10129 Convert the region to @LaTeX{} under the assumption that it was Org-mode
10130 syntax before.  This is a global command that can be invoked in any
10131 buffer.
10132 @item M-x org-replace-region-by-latex
10133 Replace the active region (assumed to be in Org-mode syntax) by @LaTeX{}
10134 code.
10135 @orgcmd{C-c C-e p,org-export-as-pdf}
10136 Export as @LaTeX{} and then process to PDF.
10137 @orgcmd{C-c C-e d,org-export-as-pdf-and-open}
10138 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
10139 @end table
10141 @cindex headline levels, for exporting
10142 @vindex org-latex-low-levels
10143 In the exported version, the first 3 outline levels will become
10144 headlines, defining a general document structure.  Additional levels
10145 will be exported as description lists.  The exporter can ignore them or
10146 convert them to a custom string depending on
10147 @code{org-latex-low-levels}.
10149 If you want that transition to occur at a different level, specify it
10150 with a numeric prefix argument.  For example,
10152 @example
10153 @kbd{C-2 C-c C-e l}
10154 @end example
10156 @noindent
10157 creates two levels of headings and does the rest as items.
10159 @node Header and sectioning, Quoting LaTeX code, LaTeX/PDF export commands, LaTeX and PDF export
10160 @subsection Header and sectioning structure
10161 @cindex @LaTeX{} class
10162 @cindex @LaTeX{} sectioning structure
10163 @cindex @LaTeX{} header
10164 @cindex header, for LaTeX files
10165 @cindex sectioning structure, for LaTeX export
10167 By default, the @LaTeX{} output uses the class @code{article}.
10169 @vindex org-export-latex-default-class
10170 @vindex org-export-latex-classes
10171 @vindex org-export-latex-default-packages-alist
10172 @vindex org-export-latex-packages-alist
10173 @cindex #+LATEX_HEADER
10174 @cindex #+LATEX_CLASS
10175 @cindex #+LATEX_CLASS_OPTIONS
10176 @cindex property, LATEX_CLASS
10177 @cindex property, LATEX_CLASS_OPTIONS
10178 You can change this globally by setting a different value for
10179 @code{org-export-latex-default-class} or locally by adding an option like
10180 @code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:}
10181 property that applies when exporting a region containing only this (sub)tree.
10182 The class must be listed in @code{org-export-latex-classes}.  This variable
10183 defines a header template for each class@footnote{Into which the values of
10184 @code{org-export-latex-default-packages-alist} and
10185 @code{org-export-latex-packages-alist} are spliced.}, and allows you to
10186 define the sectioning structure for each class.  You can also define your own
10187 classes there.  @code{#+LaTeX_CLASS_OPTIONS} or a @code{LaTeX_CLASS_OPTIONS}
10188 property can specify the options for the @code{\documentclass} macro.  You
10189 can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to the
10190 header.  See the docstring of @code{org-export-latex-classes} for more
10191 information.
10193 @node Quoting LaTeX code, Tables in LaTeX export, Header and sectioning, LaTeX and PDF export
10194 @subsection Quoting @LaTeX{} code
10196 Embedded @LaTeX{} as described in @ref{Embedded LaTeX}, will be correctly
10197 inserted into the @LaTeX{} file.  This includes simple macros like
10198 @samp{\ref@{LABEL@}} to create a cross reference to a figure.  Furthermore,
10199 you can add special code that should only be present in @LaTeX{} export with
10200 the following constructs:
10202 @cindex #+LaTeX
10203 @cindex #+BEGIN_LaTeX
10204 @example
10205 #+LaTeX: Literal LaTeX code for export
10206 @end example
10208 @noindent or
10209 @cindex #+BEGIN_LaTeX
10211 @example
10212 #+BEGIN_LaTeX
10213 All lines between these markers are exported literally
10214 #+END_LaTeX
10215 @end example
10218 @node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export
10219 @subsection Tables in @LaTeX{} export
10220 @cindex tables, in @LaTeX{} export
10222 For @LaTeX{} export of a table, you can specify a label, a caption and
10223 placement options (@pxref{Images and tables}).  You can also use the
10224 @code{ATTR_LaTeX} line to request a @code{longtable} environment for the
10225 table, so that it may span several pages, or to change the default table
10226 environment from @code{table} to @code{table*} or to change the default inner
10227 tabular environment to @code{tabularx} or @code{tabulary}.  Finally, you can
10228 set the alignment string, and (with @code{tabularx} or @code{tabulary}) the
10229 width:
10231 @cindex #+CAPTION
10232 @cindex #+LABEL
10233 @cindex #+ATTR_LaTeX
10234 @example
10235 #+CAPTION: A long table
10236 #+LABEL: tbl:long
10237 #+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l
10238 | ..... | ..... |
10239 | ..... | ..... |
10240 @end example
10242 or to specify a multicolumn table with @code{tabulary}
10244 @cindex #+CAPTION
10245 @cindex #+LABEL
10246 @cindex #+ATTR_LaTeX
10247 @example
10248 #+CAPTION: A wide table with tabulary
10249 #+LABEL: tbl:wide
10250 #+ATTR_LaTeX: table* tabulary width=\textwidth
10251 | ..... | ..... |
10252 | ..... | ..... |
10253 @end example
10255 @node Images in LaTeX export, Beamer class export, Tables in LaTeX export, LaTeX and PDF export
10256 @subsection Images in @LaTeX{} export
10257 @cindex images, inline in @LaTeX{}
10258 @cindex inlining images in @LaTeX{}
10260 Images that are linked to without a description part in the link, like
10261 @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF
10262 output file resulting from @LaTeX{} processing.  Org will use an
10263 @code{\includegraphics} macro to insert the image.  If you have specified a
10264 caption and/or a label as described in @ref{Images and tables}, the figure
10265 will be wrapped into a @code{figure} environment and thus become a floating
10266 element.  You can use an @code{#+ATTR_LaTeX:} line to specify various other
10267 options.  You can ask org to export an image as a float without specifying
10268 a label or a caption by using the keyword @code{float} in this line.  Various
10269 optional arguments to the @code{\includegraphics} macro can also be specified
10270 in this fashion.  To modify the placement option of the floating environment,
10271 add something like @samp{placement=[h!]} to the attributes.  It is to be noted
10272 this option can be used with tables as well@footnote{One can also take
10273 advantage of this option to pass other, unrelated options into the figure or
10274 table environment.  For an example see the section ``Exporting org files'' in
10275 @url{http://orgmode.org/worg/org-hacks.html}}.  For example the
10276 @code{#+ATTR_LaTeX:} line below is exported as the @code{figure} environment
10277 below it.
10279 If you would like to let text flow around the image, add the word @samp{wrap}
10280 to the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the left
10281 half of the page.  To fine-tune, the @code{placement} field will be the set
10282 of additional arguments needed by the @code{wrapfigure} environment.  Note
10283 that if you change the size of the image, you need to use compatible settings
10284 for @code{\includegraphics} and @code{wrapfigure}.
10286 @cindex #+CAPTION
10287 @cindex #+LABEL
10288 @cindex #+ATTR_LaTeX
10289 @example
10290 #+CAPTION:    The black-body emission of the disk around HR 4049
10291 #+LABEL:      fig:SED-HR4049
10292 #+ATTR_LaTeX: width=5cm,angle=90
10293 [[./img/sed-hr4049.pdf]]
10295 #+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@}
10296 [[./img/hst.png]]
10297 @end example
10299 If you wish to include an image which spans multiple columns in a page, you
10300 can use the keyword @code{multicolumn} in the @code{#+ATTR_LaTeX} line.  This
10301 will export the image wrapped in a @code{figure*} environment.
10303 If you need references to a label created in this way, write
10304 @samp{\ref@{fig:SED-HR4049@}} just like in @LaTeX{}.
10306 @node Beamer class export,  , Images in LaTeX export, LaTeX and PDF export
10307 @subsection Beamer class export
10309 The LaTeX class @file{beamer} allows production of high quality presentations
10310 using LaTeX and pdf processing.  Org-mode has special support for turning an
10311 Org-mode file or tree into a @file{beamer} presentation.
10313 When the LaTeX class for the current buffer (as set with @code{#+LaTeX_CLASS:
10314 beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is
10315 @code{beamer}, a special export mode will turn the file or tree into a beamer
10316 presentation.  Any tree with not-too-deep level nesting should in principle be
10317 exportable as a beamer presentation.  By default, the top-level entries (or
10318 the first level below the selected subtree heading) will be turned into
10319 frames, and the outline structure below this level will become itemize lists.
10320 You can also configure the variable @code{org-beamer-frame-level} to a
10321 different level---then the hierarchy above frames will produce the sectioning
10322 structure of the presentation.
10324 A template for useful in-buffer settings or properties can be inserted into
10325 the buffer with @kbd{M-x org-insert-beamer-options-template}.  Among other
10326 things, this will install a column view format which is very handy for
10327 editing special properties used by beamer.
10329 You can influence the structure of the presentation using the following
10330 properties:
10332 @table @code
10333 @item BEAMER_env
10334 The environment that should be used to format this entry.  Valid environments
10335 are defined in the constant @code{org-beamer-environments-default}, and you
10336 can define more in @code{org-beamer-environments-extra}.  If this property is
10337 set, the entry will also get a @code{:B_environment:} tag to make this
10338 visible.  This tag has no semantic meaning, it is only a visual aid.
10339 @item BEAMER_envargs
10340 The beamer-special arguments that should be used for the environment, like
10341 @code{[t]} or @code{[<+->]} of @code{<2-3>}.  If the @code{BEAMER_col}
10342 property is also set, something like @code{C[t]} can be added here as well to
10343 set an options argument for the implied @code{columns} environment.
10344 @code{c[t]} or @code{c<2->} will set an options for the implied @code{column}
10345 environment.
10346 @item BEAMER_col
10347 The width of a column that should start with this entry.  If this property is
10348 set, the entry will also get a @code{:BMCOL:} property to make this visible.
10349 Also this tag is only a visual aid.  When this is a plain number, it will be
10350 interpreted as a fraction of @code{\textwidth}.  Otherwise it will be assumed
10351 that you have specified the units, like @samp{3cm}.  The first such property
10352 in a frame will start a @code{columns} environment to surround the columns.
10353 This environment is closed when an entry has a @code{BEAMER_col} property
10354 with value 0 or 1, or automatically at the end of the frame.
10355 @item BEAMER_extra
10356 Additional commands that should be inserted after the environment has been
10357 opened.  For example, when creating a frame, this can be used to specify
10358 transitions.
10359 @end table
10361 Frames will automatically receive a @code{fragile} option if they contain
10362 source code that uses the verbatim environment.  Special @file{beamer}
10363 specific code can be inserted using @code{#+BEAMER:} and
10364 @code{#+BEGIN_beamer...#+end_beamer} constructs, similar to other export
10365 backends, but with the difference that @code{#+LaTeX:} stuff will be included
10366 in the presentation as well.
10368 Outline nodes with @code{BEAMER_env} property value @samp{note} or
10369 @samp{noteNH} will be formatted as beamer notes, i,e, they will be wrapped
10370 into @code{\note@{...@}}.  The former will include the heading as part of the
10371 note text, the latter will ignore the heading of that node.  To simplify note
10372 generation, it is actually enough to mark the note with a @emph{tag} (either
10373 @code{:B_note:} or @code{:B_noteNH:}) instead of creating the
10374 @code{BEAMER_env} property.
10376 You can turn on a special minor mode @code{org-beamer-mode} for editing
10377 support with
10379 @example
10380 #+STARTUP: beamer
10381 @end example
10383 @table @kbd
10384 @orgcmd{C-c C-b,org-beamer-select-environment}
10385 In @code{org-beamer-mode}, this key offers fast selection of a beamer
10386 environment or the @code{BEAMER_col} property.
10387 @end table
10389 Column view provides a great way to set the environment of a node and other
10390 important parameters.  Make sure you are using a COLUMN format that is geared
10391 toward this special purpose.  The command @kbd{M-x
10392 org-insert-beamer-options-template} defines such a format.
10394 Here is a simple example Org document that is intended for beamer export.
10396 @smallexample
10397 #+LaTeX_CLASS: beamer
10398 #+TITLE: Example Presentation
10399 #+AUTHOR: Carsten Dominik
10400 #+LaTeX_CLASS_OPTIONS: [presentation]
10401 #+BEAMER_FRAME_LEVEL: 2
10402 #+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@}
10403 #+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex)
10405 * This is the first structural section
10407 ** Frame 1 \\ with a subtitle
10408 *** Thanks to Eric Fraga                                      :BMCOL:B_block:
10409     :PROPERTIES:
10410     :BEAMER_env: block
10411     :BEAMER_envargs: C[t]
10412     :BEAMER_col: 0.5
10413     :END:
10414     for the first viable beamer setup in Org
10415 *** Thanks to everyone else                                   :BMCOL:B_block:
10416     :PROPERTIES:
10417     :BEAMER_col: 0.5
10418     :BEAMER_env: block
10419     :BEAMER_envargs: <2->
10420     :END:
10421     for contributing to the discussion
10422 **** This will be formatted as a beamer note                  :B_note:
10423 ** Frame 2 \\ where we will not use columns
10424 *** Request                                                   :B_block:
10425     Please test this stuff!
10426     :PROPERTIES:
10427     :BEAMER_env: block
10428     :END:
10429 @end smallexample
10431 For more information, see the documentation on Worg.
10433 @node DocBook export, OpenDocumentText export, LaTeX and PDF export, Exporting
10434 @section DocBook export
10435 @cindex DocBook export
10436 @cindex PDF export
10437 @cindex Cui, Baoqiu
10439 Org contains a DocBook exporter written by Baoqiu Cui.  Once an Org file is
10440 exported to DocBook format, it can be further processed to produce other
10441 formats, including PDF, HTML, man pages, etc., using many available DocBook
10442 tools and stylesheets.
10444 Currently DocBook exporter only supports DocBook V5.0.
10446 @menu
10447 * DocBook export commands::     How to invoke DocBook export
10448 * Quoting DocBook code::        Incorporating DocBook code in Org files
10449 * Recursive sections::          Recursive sections in DocBook
10450 * Tables in DocBook export::    Tables are exported as HTML tables
10451 * Images in DocBook export::    How to insert figures into DocBook output
10452 * Special characters::          How to handle special characters
10453 @end menu
10455 @node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export
10456 @subsection DocBook export commands
10458 @cindex region, active
10459 @cindex active region
10460 @cindex transient-mark-mode
10461 @table @kbd
10462 @orgcmd{C-c C-e D,org-export-as-docbook}
10463 @cindex property EXPORT_FILE_NAME
10464 Export as DocBook file.  For an Org file, @file{myfile.org}, the DocBook XML
10465 file will be @file{myfile.xml}.  The file will be overwritten without
10466 warning.  If there is an active region@footnote{This requires
10467 @code{transient-mark-mode} to be turned on}, only the region will be
10468 exported.  If the selected region is a single tree@footnote{To select the
10469 current subtree, use @kbd{C-c @@}.}, the tree head will become the document
10470 title.  If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}
10471 property, that name will be used for the export.
10472 @orgcmd{C-c C-e V,org-export-as-docbook-pdf-and-open}
10473 Export as DocBook file, process to PDF, then open the resulting PDF file.
10475 @vindex org-export-docbook-xslt-proc-command
10476 @vindex org-export-docbook-xsl-fo-proc-command
10477 Note that, in order to produce PDF output based on exported DocBook file, you
10478 need to have XSLT processor and XSL-FO processor software installed on your
10479 system.  Check variables @code{org-export-docbook-xslt-proc-command} and
10480 @code{org-export-docbook-xsl-fo-proc-command}.
10482 @vindex org-export-docbook-xslt-stylesheet
10483 The stylesheet argument @code{%s} in variable
10484 @code{org-export-docbook-xslt-proc-command} is replaced by the value of
10485 variable @code{org-export-docbook-xslt-stylesheet}, which needs to be set by
10486 the user.  You can also overrule this global setting on a per-file basis by
10487 adding an in-buffer setting @code{#+XSLT:} to the Org file.
10489 @orgkey{C-c C-e v D}
10490 Export only the visible part of the document.
10491 @end table
10493 @node Quoting DocBook code, Recursive sections, DocBook export commands, DocBook export
10494 @subsection Quoting DocBook code
10496 You can quote DocBook code in Org files and copy it verbatim into exported
10497 DocBook file with the following constructs:
10499 @cindex #+DOCBOOK
10500 @cindex #+BEGIN_DOCBOOK
10501 @example
10502 #+DOCBOOK: Literal DocBook code for export
10503 @end example
10505 @noindent or
10506 @cindex #+BEGIN_DOCBOOK
10508 @example
10509 #+BEGIN_DOCBOOK
10510 All lines between these markers are exported by DocBook exporter
10511 literally.
10512 #+END_DOCBOOK
10513 @end example
10515 For example, you can use the following lines to include a DocBook warning
10516 admonition.  As to what this warning says, you should pay attention to the
10517 document context when quoting DocBook code in Org files.  You may make
10518 exported DocBook XML files invalid by not quoting DocBook code correctly.
10520 @example
10521 #+BEGIN_DOCBOOK
10522 <warning>
10523   <para>You should know what you are doing when quoting DocBook XML code
10524   in your Org file.  Invalid DocBook XML may be generated by
10525   DocBook exporter if you are not careful!</para>
10526 </warning>
10527 #+END_DOCBOOK
10528 @end example
10530 @node Recursive sections, Tables in DocBook export, Quoting DocBook code, DocBook export
10531 @subsection Recursive sections
10532 @cindex DocBook recursive sections
10534 DocBook exporter exports Org files as articles using the @code{article}
10535 element in DocBook.  Recursive sections, i.e.@: @code{section} elements, are
10536 used in exported articles.  Top level headlines in Org files are exported as
10537 top level sections, and lower level headlines are exported as nested
10538 sections.  The entire structure of Org files will be exported completely, no
10539 matter how many nested levels of headlines there are.
10541 Using recursive sections makes it easy to port and reuse exported DocBook
10542 code in other DocBook document types like @code{book} or @code{set}.
10544 @node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export
10545 @subsection Tables in DocBook export
10546 @cindex tables, in DocBook export
10548 Tables in Org files are exported as HTML tables, which have been supported since
10549 DocBook V4.3.
10551 If a table does not have a caption, an informal table is generated using the
10552 @code{informaltable} element; otherwise, a formal table will be generated
10553 using the @code{table} element.
10555 @node Images in DocBook export, Special characters, Tables in DocBook export, DocBook export
10556 @subsection Images in DocBook export
10557 @cindex images, inline in DocBook
10558 @cindex inlining images in DocBook
10560 Images that are linked to without a description part in the link, like
10561 @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, will be exported to DocBook
10562 using @code{mediaobject} elements.  Each @code{mediaobject} element contains
10563 an @code{imageobject} that wraps an @code{imagedata} element.  If you have
10564 specified a caption for an image as described in @ref{Images and tables}, a
10565 @code{caption} element will be added in @code{mediaobject}.  If a label is
10566 also specified, it will be exported as an @code{xml:id} attribute of the
10567 @code{mediaobject} element.
10569 @vindex org-export-docbook-default-image-attributes
10570 Image attributes supported by the @code{imagedata} element, like @code{align}
10571 or @code{width}, can be specified in two ways: you can either customize
10572 variable @code{org-export-docbook-default-image-attributes} or use the
10573 @code{#+ATTR_DOCBOOK:} line.  Attributes specified in variable
10574 @code{org-export-docbook-default-image-attributes} are applied to all inline
10575 images in the Org file to be exported (unless they are overridden by image
10576 attributes specified in @code{#+ATTR_DOCBOOK:} lines).
10578 The @code{#+ATTR_DOCBOOK:} line can be used to specify additional image
10579 attributes or override default image attributes for individual images.  If
10580 the same attribute appears in both the @code{#+ATTR_DOCBOOK:} line and
10581 variable @code{org-export-docbook-default-image-attributes}, the former
10582 takes precedence.  Here is an example about how image attributes can be
10583 set:
10585 @cindex #+CAPTION
10586 @cindex #+LABEL
10587 @cindex #+ATTR_DOCBOOK
10588 @example
10589 #+CAPTION:    The logo of Org-mode
10590 #+LABEL:      unicorn-svg
10591 #+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
10592 [[./img/org-mode-unicorn.svg]]
10593 @end example
10595 @vindex org-export-docbook-inline-image-extensions
10596 By default, DocBook exporter recognizes the following image file types:
10597 @file{jpeg}, @file{jpg}, @file{png}, @file{gif}, and @file{svg}.  You can
10598 customize variable @code{org-export-docbook-inline-image-extensions} to add
10599 more types to this list as long as DocBook supports them.
10601 @node Special characters,  , Images in DocBook export, DocBook export
10602 @subsection Special characters in DocBook export
10603 @cindex Special characters in DocBook export
10605 @vindex org-export-docbook-doctype
10606 @vindex org-entities
10607 Special characters that are written in @TeX{}-like syntax, such as @code{\alpha},
10608 @code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter.  These
10609 characters are rewritten to XML entities, like @code{&alpha;},
10610 @code{&Gamma;}, and @code{&Zeta;}, based on the list saved in variable
10611 @code{org-entities}.  As long as the generated DocBook file includes the
10612 corresponding entities, these special characters are recognized.
10614 You can customize variable @code{org-export-docbook-doctype} to include the
10615 entities you need.  For example, you can set variable
10616 @code{org-export-docbook-doctype} to the following value to recognize all
10617 special characters included in XHTML entities:
10619 @example
10620 "<!DOCTYPE article [
10621 <!ENTITY % xhtml1-symbol PUBLIC
10622 \"-//W3C//ENTITIES Symbol for HTML//EN//XML\"
10623 \"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\"
10625 %xhtml1-symbol;
10628 @end example
10630 @c begin opendocument
10632 @node OpenDocumentText export, TaskJuggler export, DocBook export, Exporting
10633 @section OpenDocumentText export
10634 @cindex OpenDocumentText export
10635 @cindex K, Jambunathan
10637 Org-mode 7.6 supports export to OpenDocumentText format using
10638 @file{org-odt.el} module contributed by Jambunathan K.  This module can be
10639 enabled in one of the following ways based on your mode of installation.
10641 @enumerate
10642 @item
10643 If you have downloaded the Org from the Web, either as a distribution
10644 @file{.zip} or @file{.tar} file, or as a Git archive, enable the @code{odt}
10645 option in variable @code{org-modules}.
10646 @item
10647 If you are using Org that comes bundled with Emacs, then you can install the
10648 OpenDocumentText exporter using the package manager.  To do this, customize
10649 the variable @code{package-archives} to include
10650 @uref{http://orgmode.org/pkg/releases/} as one of the package archives.
10651 @end enumerate
10653 @menu
10654 * OpenDocumentText export commands::How to invoke OpenDocumentText export
10655 * Applying Custom Styles::      How to apply custom styles to the output
10656 * Converting to Other formats:: How to convert to formats like doc, docx etc
10657 * Links in OpenDocumentText export::  How links will be interpreted and formatted
10658 * Tables in OpenDocumentText export::    Tables are exported as HTML tables
10659 * Images in OpenDocumentText export::    How to insert figures into DocBook output
10660 * Additional Documentation::    Where to find more information
10661 @end menu
10663 @node OpenDocumentText export commands, Applying Custom Styles, OpenDocumentText export, OpenDocumentText export
10664 @subsection OpenDocumentText export commands
10666 @cindex region, active
10667 @cindex active region
10668 @cindex transient-mark-mode
10669 @table @kbd
10670 @orgcmd{C-c C-e o,org-export-as-odt}
10671 @cindex property EXPORT_FILE_NAME
10672 Export as OpenDocumentText file.  For an Org file, @file{myfile.org}, the
10673 OpenDocumentText file will be @file{myfile.odt}.  The file will be
10674 overwritten without warning.  If there is an active region@footnote{This
10675 requires @code{transient-mark-mode} to be turned on}, only the region will be
10676 exported.  If the selected region is a single tree@footnote{To select the
10677 current subtree, use @kbd{C-c @@}.}, the tree head will become the document
10678 title.  If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}
10679 property, that name will be used for the export.
10680 @orgcmd{C-c C-e O,org-export-as-odt-and-open}
10681 Export as OpenDocumentText file and open the resulting file.
10682 @end table
10684 @node Applying Custom Styles, Converting to Other formats, OpenDocumentText export commands, OpenDocumentText export
10685 @subsection Applying Custom Styles
10686 @cindex styles, custom
10687 @cindex template, custom
10689 @vindex org-export-odt-styles-file
10691 OpenDocumentExporter ships with a custom @file{styles.xml} for formatting of
10692 the exported file.  To customize the output to suit your needs you can use
10693 one of the following methods:
10695 @enumerate
10696 @item
10697 Customize the variable @code{org-export-odt-styles-file} to point to either a
10698 @file{styles.xml} file, a OpenDocument Text Template file @code{.ott} or a
10699 combination of Text or Template Document together with a set of member files.
10700 Use the first two options if the styles.xml has no references to additional
10701 set of files and use the last option if the @file{styles.xml} references
10702 additional files like header and footer images.
10703 @item
10704 Use an external tool like unoconv to apply custom templates.
10705 @end enumerate
10707 For best results, it is necessary that the style names used by
10708 OpenDocumentText exporter match that used in the @file{styles.xml}.
10710 @node Converting to Other formats, Links in OpenDocumentText export, Applying Custom Styles, OpenDocumentText export
10711 @subsection Converting to Other formats
10713 @cindex convert
10714 @cindex doc, docx
10716 @vindex org-export-odt-styles-file
10718 Often times there is a need to convert OpenDocumentText files to other
10719 formats like doc, docx or pdf.  You can accomplish this by one of the
10720 following methods:
10722 @table @kbd
10723 @item M-x org-lparse
10724 Export the outline first to one of the native formats (like OpenDocumentText)
10725 and immediately post-process it to other formats using an external converter.
10727 @item M-x org-lparse-convert
10728 Export an existing document to other formats using an external converter.
10729 @end table
10731 You can choose the converter used for conversion by customizing the variable
10732 @code{org-lparse-convert-process}.
10734 @node Links in OpenDocumentText export, Tables in OpenDocumentText export, Converting to Other formats, OpenDocumentText export
10735 @subsection Links in OpenDocumentText export
10736 @cindex tables, in DocBook export
10738 OpenDocumentExporter creates cross-references (aka bookmarks) for links that
10739 are destined locally.  It creates internet style links for all other links.
10741 @node Tables in OpenDocumentText export, Images in OpenDocumentText export, Links in OpenDocumentText export, OpenDocumentText export
10742 @subsection Tables in OpenDocumentText export
10743 @cindex tables, in DocBook export
10745 Export of @file{table.el} tables with row or column spanning is not
10746 supported.  Such tables are stripped from the exported document.
10748 @node Images in OpenDocumentText export, Additional Documentation, Tables in OpenDocumentText export, OpenDocumentText export
10749 @subsection Images in OpenDocumentText export
10750 @cindex images, embedding in OpenDocumentText
10751 @cindex embedding images in OpenDocumentText
10753 OpenDocumentText exporter can embed images within the exported document.  To
10754 embed images, provide a link to the desired image file with no link
10755 description.  For example, the following links @samp{[[file:img.jpg]]} or
10756 @samp{[[./img.jpg]]}, will result in embedding of @samp{img.jpg} in the
10757 exported file.
10759 The exporter can also embed scaled and explicitly sized images within the
10760 exported document.  The markup of the scale and size specifications has not
10761 been standardized yet and is hence conveniently skipped in this document.
10763 The exporter can also make an image the clickable part of a link.  To create
10764 clickable images, provide a link whose description is a link to an image
10765 file.  For example, the following link
10766 @samp{[[http://Orgmode.org][./img.jpg]]}, will result in a clickable image
10767 that links to @uref{http://Orgmode.org} website.
10769 @node Additional Documentation, , Images in OpenDocumentText export, OpenDocumentText export
10770 @subsection Additional documentation
10772 The OpenDocumentText exporter is still in development.  For up to date
10773 information, please follow Org mailing list @email{emacs-orgmode@@gnu.org}
10774 closely.
10776 @c end opendocument
10778 @node  TaskJuggler export, Freemind export, OpenDocumentText export, Exporting
10779 @section TaskJuggler export
10780 @cindex TaskJuggler export
10781 @cindex Project management
10783 @uref{http://www.taskjuggler.org/, TaskJuggler} is a project management tool.
10784 It provides an optimizing scheduler that computes your project time lines and
10785 resource assignments based on the project outline and the constraints that
10786 you have provided.
10788 The TaskJuggler exporter is a bit different from other exporters, such as the
10789 HTML and LaTeX exporters for example, in that it does not export all the
10790 nodes of a document or strictly follow the order of the nodes in the
10791 document.
10793 Instead the TaskJuggler exporter looks for a tree that defines the tasks and
10794 a optionally tree that defines the resources for this project.  It then
10795 creates a TaskJuggler file based on these trees and the attributes defined in
10796 all the nodes.
10798 @subsection TaskJuggler export commands
10800 @table @kbd
10801 @orgcmd{C-c C-e j,org-export-as-taskjuggler}
10802 Export as TaskJuggler file.
10804 @orgcmd{C-c C-e J,org-export-as-taskjuggler-and-open}
10805 Export as TaskJuggler file and then open the file with TaskJugglerUI.
10806 @end table
10808 @subsection Tasks
10810 @vindex org-export-taskjuggler-project-tag
10811 Create your tasks as you usually do with Org-mode.  Assign efforts to each
10812 task using properties (it is easiest to do this in the column view).  You
10813 should end up with something similar to the example by Peter Jones in
10814 @url{http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org}.
10815 Now mark the top node of your tasks with a tag named
10816 @code{:taskjuggler_project:} (or whatever you customized
10817 @code{org-export-taskjuggler-project-tag} to).  You are now ready to export
10818 the project plan with @kbd{C-c C-e J} which will export the project plan and
10819 open a gantt chart in TaskJugglerUI.
10821 @subsection Resources
10823 @vindex org-export-taskjuggler-resource-tag
10824 Next you can define resources and assign those to work on specific tasks.  You
10825 can group your resources hierarchically.  Tag the top node of the resources
10826 with @code{:taskjuggler_resource:} (or whatever you customized
10827 @code{org-export-taskjuggler-resource-tag} to).  You can optionally assign an
10828 identifier (named @samp{resource_id}) to the resources (using the standard
10829 Org properties commands, @pxref{Property syntax}) or you can let the exporter
10830 generate identifiers automatically (the exporter picks the first word of the
10831 headline as the identifier as long as it is unique---see the documentation of
10832 @code{org-taskjuggler-get-unique-id}).  Using that identifier you can then
10833 allocate resources to tasks.  This is again done with the @samp{allocate}
10834 property on the tasks.  Do this in column view or when on the task type
10835 @kbd{C-c C-x p allocate @key{RET} <resource_id> @key{RET}}.
10837 Once the allocations are done you can again export to TaskJuggler and check
10838 in the Resource Allocation Graph which person is working on what task at what
10839 time.
10841 @subsection Export of properties
10843 The exporter also takes TODO state information into consideration, i.e.@: if a
10844 task is marked as done it will have the corresponding attribute in
10845 TaskJuggler (@samp{complete 100}).  Also it will export any property on a task
10846 resource or resource node which is known to TaskJuggler, such as
10847 @samp{limits}, @samp{vacation}, @samp{shift}, @samp{booking},
10848 @samp{efficiency}, @samp{journalentry}, @samp{rate} for resources or
10849 @samp{account}, @samp{start}, @samp{note}, @samp{duration}, @samp{end},
10850 @samp{journalentry}, @samp{milestone}, @samp{reference}, @samp{responsible},
10851 @samp{scheduling}, etc for tasks.
10853 @subsection Dependencies
10855 The exporter will handle dependencies that are defined in the tasks either
10856 with the @samp{ORDERED} attribute (@pxref{TODO dependencies}), with the
10857 @samp{BLOCKER} attribute (see @file{org-depend.el}) or alternatively with a
10858 @samp{depends} attribute.  Both the @samp{BLOCKER} and the @samp{depends}
10859 attribute can be either @samp{previous-sibling} or a reference to an
10860 identifier (named @samp{task_id}) which is defined for another task in the
10861 project.  @samp{BLOCKER} and the @samp{depends} attribute can define multiple
10862 dependencies separated by either space or comma.  You can also specify
10863 optional attributes on the dependency by simply appending it.  The following
10864 examples should illustrate this:
10866 @example
10867 * Preparation
10868   :PROPERTIES:
10869   :task_id:  preparation
10870   :ORDERED:  t
10871   :END:
10872 * Training material
10873   :PROPERTIES:
10874   :task_id:  training_material
10875   :ORDERED:  t
10876   :END:
10877 ** Markup Guidelines
10878    :PROPERTIES:
10879    :Effort:   2d
10880    :END:
10881 ** Workflow Guidelines
10882    :PROPERTIES:
10883    :Effort:   2d
10884    :END:
10885 * Presentation
10886   :PROPERTIES:
10887   :Effort:   2d
10888   :BLOCKER:  training_material @{ gapduration 1d @} preparation
10889   :END:
10890 @end example
10892 @subsection Reports
10894 @vindex org-export-taskjuggler-default-reports
10895 TaskJuggler can produce many kinds of reports (e.g.@: gantt chart, resource
10896 allocation, etc).  The user defines what kind of reports should be generated
10897 for a project in the TaskJuggler file.  The exporter will automatically insert
10898 some default reports in the file.  These defaults are defined in
10899 @code{org-export-taskjuggler-default-reports}.  They can be modified using
10900 customize along with a number of other options.  For a more complete list, see
10901 @kbd{M-x customize-group @key{RET} org-export-taskjuggler @key{RET}}.
10903 For more information and examples see the Org-taskjuggler tutorial at
10904 @uref{http://orgmode.org/worg/org-tutorials/org-taskjuggler.html}.
10906 @node Freemind export, XOXO export, TaskJuggler export, Exporting
10907 @section Freemind export
10908 @cindex Freemind export
10909 @cindex mind map
10911 The Freemind exporter was written by Lennart Borgman.
10913 @table @kbd
10914 @orgcmd{C-c C-e m,org-export-as-freemind}
10915 Export as Freemind mind map.  For an Org file @file{myfile.org}, the Freemind 
10916 file will be @file{myfile.mm}.
10917 @end table
10919 @node XOXO export, iCalendar export, Freemind export, Exporting
10920 @section XOXO export
10921 @cindex XOXO export
10923 Org-mode contains an exporter that produces XOXO-style output.
10924 Currently, this exporter only handles the general outline structure and
10925 does not interpret any additional Org-mode features.
10927 @table @kbd
10928 @orgcmd{C-c C-e x,org-export-as-xoxo}
10929 Export as XOXO file.  For an Org file @file{myfile.org}, the XOXO file will be 
10930 @file{myfile.html}.
10931 @orgkey{C-c C-e v x}
10932 Export only the visible part of the document.
10933 @end table
10935 @node iCalendar export,  , XOXO export, Exporting
10936 @section iCalendar export
10937 @cindex iCalendar export
10939 @vindex org-icalendar-include-todo
10940 @vindex org-icalendar-use-deadline
10941 @vindex org-icalendar-use-scheduled
10942 @vindex org-icalendar-categories
10943 @vindex org-icalendar-alarm-time
10944 Some people use Org-mode for keeping track of projects, but still prefer a
10945 standard calendar application for anniversaries and appointments.  In this
10946 case it can be useful to show deadlines and other time-stamped items in Org
10947 files in the calendar application.  Org-mode can export calendar information
10948 in the standard iCalendar format.  If you also want to have TODO entries
10949 included in the export, configure the variable
10950 @code{org-icalendar-include-todo}.  Plain timestamps are exported as VEVENT,
10951 and TODO items as VTODO.  It will also create events from deadlines that are
10952 in non-TODO items.  Deadlines and scheduling dates in TODO items will be used
10953 to set the start and due dates for the TODO entry@footnote{See the variables
10954 @code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}.
10955 As categories, it will use the tags locally defined in the heading, and the
10956 file/tree category@footnote{To add inherited tags or the TODO state,
10957 configure the variable @code{org-icalendar-categories}.}.  See the variable
10958 @code{org-icalendar-alarm-time} for a way to assign alarms to entries with a
10959 time.
10961 @vindex org-icalendar-store-UID
10962 @cindex property, ID
10963 The iCalendar standard requires each entry to have a globally unique
10964 identifier (UID).  Org creates these identifiers during export.  If you set
10965 the variable @code{org-icalendar-store-UID}, the UID will be stored in the
10966 @code{:ID:} property of the entry and re-used next time you report this
10967 entry.  Since a single entry can give rise to multiple iCalendar entries (as
10968 a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds
10969 prefixes to the UID, depending on what triggered the inclusion of the entry.
10970 In this way the UID remains unique, but a synchronization program can still
10971 figure out from which entry all the different instances originate.
10973 @table @kbd
10974 @orgcmd{C-c C-e i,org-export-icalendar-this-file}
10975 Create iCalendar entries for the current file and store them in the same
10976 directory, using a file extension @file{.ics}.
10977 @orgcmd{C-c C-e I, org-export-icalendar-all-agenda-files}
10978 @vindex org-agenda-files
10979 Like @kbd{C-c C-e i}, but do this for all files in
10980 @code{org-agenda-files}.  For each of these files, a separate iCalendar
10981 file will be written.
10982 @orgcmd{C-c C-e c,org-export-icalendar-combine-agenda-files}
10983 @vindex org-combined-agenda-icalendar-file
10984 Create a single large iCalendar file from all files in
10985 @code{org-agenda-files} and write it to the file given by
10986 @code{org-combined-agenda-icalendar-file}.
10987 @end table
10989 @vindex org-use-property-inheritance
10990 @vindex org-icalendar-include-body
10991 @cindex property, SUMMARY
10992 @cindex property, DESCRIPTION
10993 @cindex property, LOCATION
10994 The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION
10995 property can be inherited from higher in the hierarchy if you configure
10996 @code{org-use-property-inheritance} accordingly.} properties if the selected
10997 entries have them.  If not, the summary will be derived from the headline,
10998 and the description from the body (limited to
10999 @code{org-icalendar-include-body} characters).
11001 How this calendar is best read and updated, depends on the application
11002 you are using.  The FAQ covers this issue.
11004 @node Publishing, Working With Source Code, Exporting, Top
11005 @chapter Publishing
11006 @cindex publishing
11008 Org includes a publishing management system that allows you to configure
11009 automatic HTML conversion of @emph{projects} composed of interlinked org
11010 files.  You can also configure Org to automatically upload your exported HTML
11011 pages and related attachments, such as images and source code files, to a web
11012 server.
11014 You can also use Org to convert files into PDF, or even combine HTML and PDF
11015 conversion so that files are available in both formats on the server.
11017 Publishing has been contributed to Org by David O'Toole.
11019 @menu
11020 * Configuration::               Defining projects
11021 * Uploading files::             How to get files up on the server
11022 * Sample configuration::        Example projects
11023 * Triggering publication::      Publication commands
11024 @end menu
11026 @node Configuration, Uploading files, Publishing, Publishing
11027 @section Configuration
11029 Publishing needs significant configuration to specify files, destination
11030 and many other properties of a project.
11032 @menu
11033 * Project alist::               The central configuration variable
11034 * Sources and destinations::    From here to there
11035 * Selecting files::             What files are part of the project?
11036 * Publishing action::           Setting the function doing the publishing
11037 * Publishing options::          Tweaking HTML/@LaTeX{} export
11038 * Publishing links::            Which links keep working after publishing?
11039 * Sitemap::                     Generating a list of all pages
11040 * Generating an index::         An index that reaches across pages
11041 @end menu
11043 @node Project alist, Sources and destinations, Configuration, Configuration
11044 @subsection The variable @code{org-publish-project-alist}
11045 @cindex org-publish-project-alist
11046 @cindex projects, for publishing
11048 @vindex org-publish-project-alist
11049 Publishing is configured almost entirely through setting the value of one
11050 variable, called @code{org-publish-project-alist}.  Each element of the list
11051 configures one project, and may be in one of the two following forms:
11053 @lisp
11054    ("project-name" :property value :property value ...) 
11055      @r{i.e.@: a well-formed property list with alternating keys and values}
11056 @r{or}
11057    ("project-name" :components ("project-name" "project-name" ...))
11059 @end lisp
11061 In both cases, projects are configured by specifying property values.  A
11062 project defines the set of files that will be published, as well as the
11063 publishing configuration to use when publishing those files.  When a project
11064 takes the second form listed above, the individual members of the
11065 @code{:components} property are taken to be sub-projects, which group
11066 together files requiring different publishing options.  When you publish such
11067 a ``meta-project'', all the components will also be published, in the
11068 sequence given.
11070 @node Sources and destinations, Selecting files, Project alist, Configuration
11071 @subsection Sources and destinations for files
11072 @cindex directories, for publishing
11074 Most properties are optional, but some should always be set.  In
11075 particular, Org needs to know where to look for source files,
11076 and where to put published files.
11078 @multitable @columnfractions 0.3 0.7
11079 @item @code{:base-directory}
11080 @tab Directory containing publishing source files
11081 @item @code{:publishing-directory}
11082 @tab Directory where output files will be published.  You can directly
11083 publish to a webserver using a file name syntax appropriate for
11084 the Emacs @file{tramp} package.  Or you can publish to a local directory and
11085 use external tools to upload your website (@pxref{Uploading files}).
11086 @item @code{:preparation-function}
11087 @tab Function or list of functions to be called before starting the
11088 publishing process, for example, to run @code{make} for updating files to be
11089 published.  The project property list is scoped into this call as the
11090 variable @code{project-plist}.
11091 @item @code{:completion-function}
11092 @tab Function or list of functions called after finishing the publishing
11093 process, for example, to change permissions of the resulting files.  The
11094 project property list is scoped into this call as the variable
11095 @code{project-plist}.
11096 @end multitable
11097 @noindent
11099 @node Selecting files, Publishing action, Sources and destinations, Configuration
11100 @subsection Selecting files
11101 @cindex files, selecting for publishing
11103 By default, all files with extension @file{.org} in the base directory
11104 are considered part of the project.  This can be modified by setting the
11105 properties
11106 @multitable @columnfractions 0.25 0.75
11107 @item @code{:base-extension}
11108 @tab Extension (without the dot!) of source files.  This actually is a
11109 regular expression.  Set this to the symbol @code{any} if you want to get all
11110 files in @code{:base-directory}, even without extension.
11112 @item @code{:exclude}
11113 @tab Regular expression to match file names that should not be
11114 published, even though they have been selected on the basis of their
11115 extension.
11117 @item @code{:include}
11118 @tab List of files to be included regardless of @code{:base-extension}
11119 and @code{:exclude}.
11121 @item @code{:recursive}
11122 @tab Non-nil means, check base-directory recursively for files to publish.
11123 @end multitable
11125 @node Publishing action, Publishing options, Selecting files, Configuration
11126 @subsection Publishing action
11127 @cindex action, for publishing
11129 Publishing means that a file is copied to the destination directory and
11130 possibly transformed in the process.  The default transformation is to export
11131 Org files as HTML files, and this is done by the function
11132 @code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTML
11133 export}).  But you also can publish your content as PDF files using
11134 @code{org-publish-org-to-pdf}, or as @code{ascii}, @code{latin1} or
11135 @code{utf8} encoded files using the corresponding functions.  If you want to
11136 publish the Org file itself, but with @i{archived}, @i{commented}, and
11137 @i{tag-excluded} trees removed, use @code{org-publish-org-to-org} and set the
11138 parameters @code{:plain-source} and/or @code{:htmlized-source}.  This will
11139 produce @file{file.org} and @file{file.org.html} in the publishing
11140 directory@footnote{@file{file-source.org} and @file{file-source.org.html} if
11141 source and publishing directories are equal.  Note that with this kind of
11142 setup, you need to add @code{:exclude "-source\\.org"} to the project
11143 definition in @code{org-publish-project-alist} to prevent the published
11144 source files from being considered as new org files the next time the project
11145 is published.}.  Other files like images only need to be copied to the
11146 publishing destination; for this you may use @code{org-publish-attachment}.
11147 For non-Org files, you always need to specify the publishing function:
11149 @multitable @columnfractions 0.3 0.7
11150 @item @code{:publishing-function}
11151 @tab Function executing the publication of a file.  This may also be a
11152 list of functions, which will all be called in turn.
11153 @item @code{:plain-source}
11154 @tab Non-nil means, publish plain source.
11155 @item @code{:htmlized-source}
11156 @tab Non-nil means, publish htmlized source.
11157 @end multitable
11159 The function must accept three arguments: a property list containing at least
11160 a @code{:publishing-directory} property, the name of the file to be
11161 published, and the path to the publishing directory of the output file.  It
11162 should take the specified file, make the necessary transformation (if any)
11163 and place the result into the destination folder.
11165 @node Publishing options, Publishing links, Publishing action, Configuration
11166 @subsection Options for the HTML/@LaTeX{} exporters
11167 @cindex options, for publishing
11169 The property list can be used to set many export options for the HTML
11170 and @LaTeX{} exporters.  In most cases, these properties correspond to user
11171 variables in Org.  The table below lists these properties along
11172 with the variable they belong to.  See the documentation string for the
11173 respective variable for details.
11175 @vindex org-export-html-link-up
11176 @vindex org-export-html-link-home
11177 @vindex org-export-default-language
11178 @vindex org-display-custom-times
11179 @vindex org-export-headline-levels
11180 @vindex org-export-with-section-numbers
11181 @vindex org-export-section-number-format
11182 @vindex org-export-with-toc
11183 @vindex org-export-preserve-breaks
11184 @vindex org-export-with-archived-trees
11185 @vindex org-export-with-emphasize
11186 @vindex org-export-with-sub-superscripts
11187 @vindex org-export-with-special-strings
11188 @vindex org-export-with-footnotes
11189 @vindex org-export-with-drawers
11190 @vindex org-export-with-tags
11191 @vindex org-export-with-todo-keywords
11192 @vindex org-export-with-tasks
11193 @vindex org-export-with-done-tasks
11194 @vindex org-export-with-priority
11195 @vindex org-export-with-TeX-macros
11196 @vindex org-export-with-LaTeX-fragments
11197 @vindex org-export-skip-text-before-1st-heading
11198 @vindex org-export-with-fixed-width
11199 @vindex org-export-with-timestamps
11200 @vindex org-export-author-info
11201 @vindex org-export-email-info
11202 @vindex org-export-creator-info
11203 @vindex org-export-time-stamp-file
11204 @vindex org-export-with-tables
11205 @vindex org-export-highlight-first-table-line
11206 @vindex org-export-html-style-include-default
11207 @vindex org-export-html-style-include-scripts
11208 @vindex org-export-html-style
11209 @vindex org-export-html-style-extra
11210 @vindex org-export-html-link-org-files-as-html
11211 @vindex org-export-html-inline-images
11212 @vindex org-export-html-extension
11213 @vindex org-export-html-table-tag
11214 @vindex org-export-html-expand
11215 @vindex org-export-html-with-timestamp
11216 @vindex org-export-publishing-directory
11217 @vindex org-export-html-preamble
11218 @vindex org-export-html-postamble
11219 @vindex user-full-name
11220 @vindex user-mail-address
11221 @vindex org-export-select-tags
11222 @vindex org-export-exclude-tags
11224 @multitable @columnfractions 0.32 0.68
11225 @item @code{:link-up}               @tab @code{org-export-html-link-up}
11226 @item @code{:link-home}             @tab @code{org-export-html-link-home}
11227 @item @code{:language}              @tab @code{org-export-default-language}
11228 @item @code{:customtime}            @tab @code{org-display-custom-times}
11229 @item @code{:headline-levels}       @tab @code{org-export-headline-levels}
11230 @item @code{:section-numbers}       @tab @code{org-export-with-section-numbers}
11231 @item @code{:section-number-format} @tab @code{org-export-section-number-format}
11232 @item @code{:table-of-contents}     @tab @code{org-export-with-toc}
11233 @item @code{:preserve-breaks}       @tab @code{org-export-preserve-breaks}
11234 @item @code{:archived-trees}        @tab @code{org-export-with-archived-trees}
11235 @item @code{:emphasize}             @tab @code{org-export-with-emphasize}
11236 @item @code{:sub-superscript}       @tab @code{org-export-with-sub-superscripts}
11237 @item @code{:special-strings}       @tab @code{org-export-with-special-strings}
11238 @item @code{:footnotes}             @tab @code{org-export-with-footnotes}
11239 @item @code{:drawers}               @tab @code{org-export-with-drawers}
11240 @item @code{:tags}                  @tab @code{org-export-with-tags}
11241 @item @code{:todo-keywords}         @tab @code{org-export-with-todo-keywords}
11242 @item @code{:tasks}                 @tab @code{org-export-with-tasks}
11243 @item @code{:priority}              @tab @code{org-export-with-priority}
11244 @item @code{:TeX-macros}            @tab @code{org-export-with-TeX-macros}
11245 @item @code{:LaTeX-fragments}       @tab @code{org-export-with-LaTeX-fragments}
11246 @item @code{:latex-listings}        @tab @code{org-export-latex-listings}
11247 @item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading}
11248 @item @code{:fixed-width}           @tab @code{org-export-with-fixed-width}
11249 @item @code{:timestamps}            @tab @code{org-export-with-timestamps}
11250 @item @code{:author}                @tab @code{user-full-name}
11251 @item @code{:email}                 @tab @code{user-mail-address} : @code{addr;addr;..}
11252 @item @code{:author-info}           @tab @code{org-export-author-info}
11253 @item @code{:email-info}            @tab @code{org-export-email-info}
11254 @item @code{:creator-info}          @tab @code{org-export-creator-info}
11255 @item @code{:tables}                @tab @code{org-export-with-tables}
11256 @item @code{:table-auto-headline}   @tab @code{org-export-highlight-first-table-line}
11257 @item @code{:style-include-default} @tab @code{org-export-html-style-include-default}
11258 @item @code{:style-include-scripts} @tab @code{org-export-html-style-include-scripts}
11259 @item @code{:style}                 @tab @code{org-export-html-style}
11260 @item @code{:style-extra}           @tab @code{org-export-html-style-extra}
11261 @item @code{:convert-org-links}     @tab @code{org-export-html-link-org-files-as-html}
11262 @item @code{:inline-images}         @tab @code{org-export-html-inline-images}
11263 @item @code{:html-extension}        @tab @code{org-export-html-extension}
11264 @item @code{:html-preamble}         @tab @code{org-export-html-preamble}
11265 @item @code{:html-postamble}        @tab @code{org-export-html-postamble}
11266 @item @code{:xml-declaration}       @tab @code{org-export-html-xml-declaration}
11267 @item @code{:html-table-tag}        @tab @code{org-export-html-table-tag}
11268 @item @code{:expand-quoted-html}    @tab @code{org-export-html-expand}
11269 @item @code{:timestamp}             @tab @code{org-export-html-with-timestamp}
11270 @item @code{:publishing-directory}  @tab @code{org-export-publishing-directory}
11271 @item @code{:select-tags}           @tab @code{org-export-select-tags}
11272 @item @code{:exclude-tags}          @tab @code{org-export-exclude-tags}
11273 @item @code{:latex-image-options}   @tab @code{org-export-latex-image-default-option}
11274 @end multitable
11276 Most of the @code{org-export-with-*} variables have the same effect in
11277 both HTML and @LaTeX{} exporters, except for @code{:TeX-macros} and
11278 @code{:LaTeX-fragments} options, respectively @code{nil} and @code{t} in the
11279 @LaTeX{} export.  See @code{org-export-plist-vars} to check this list of
11280 options.
11284 @vindex org-publish-project-alist
11285 When a property is given a value in @code{org-publish-project-alist},
11286 its setting overrides the value of the corresponding user variable (if
11287 any) during publishing.  Options set within a file (@pxref{Export
11288 options}), however, override everything.
11290 @node Publishing links, Sitemap, Publishing options, Configuration
11291 @subsection Links between published files
11292 @cindex links, publishing
11294 To create a link from one Org file to another, you would use
11295 something like @samp{[[file:foo.org][The foo]]} or simply
11296 @samp{file:foo.org.} (@pxref{Hyperlinks}).  When published, this link
11297 becomes a link to @file{foo.html}.  In this way, you can interlink the
11298 pages of your "org web" project and the links will work as expected when
11299 you publish them to HTML.  If you also publish the Org source file and want
11300 to link to that, use an @code{http:} link instead of a @code{file:} link,
11301 because @code{file:} links are converted to link to the corresponding
11302 @file{html} file.
11304 You may also link to related files, such as images.  Provided you are careful
11305 with relative file names, and provided you have also configured Org to upload
11306 the related files, these links will work too.  See @ref{Complex example}, for
11307 an example of this usage.
11309 Sometimes an Org file to be published may contain links that are
11310 only valid in your production environment, but not in the publishing
11311 location.  In this case, use the property
11313 @multitable @columnfractions 0.4 0.6
11314 @item @code{:link-validation-function}
11315 @tab Function to validate links
11316 @end multitable
11318 @noindent
11319 to define a function for checking link validity.  This function must
11320 accept two arguments, the file name and a directory relative to which
11321 the file name is interpreted in the production environment.  If this
11322 function returns @code{nil}, then the HTML generator will only insert a
11323 description into the HTML file, but no link.  One option for this
11324 function is @code{org-publish-validate-link} which checks if the given
11325 file is part of any project in @code{org-publish-project-alist}.
11327 @node Sitemap, Generating an index, Publishing links, Configuration
11328 @subsection Generating a sitemap
11329 @cindex sitemap, of published pages
11331 The following properties may be used to control publishing of
11332 a map of files for a given project.
11334 @multitable @columnfractions 0.35 0.65
11335 @item @code{:auto-sitemap}
11336 @tab When non-nil, publish a sitemap during @code{org-publish-current-project}
11337 or @code{org-publish-all}.
11339 @item @code{:sitemap-filename}
11340 @tab Filename for output of sitemap.  Defaults to @file{sitemap.org} (which
11341 becomes @file{sitemap.html}).
11343 @item @code{:sitemap-title}
11344 @tab Title of sitemap page.  Defaults to name of file.
11346 @item @code{:sitemap-function}
11347 @tab Plug-in function to use for generation of the sitemap.
11348 Defaults to @code{org-publish-org-sitemap}, which generates a plain list
11349 of links to all files in the project.
11351 @item @code{:sitemap-sort-folders}
11352 @tab Where folders should appear in the sitemap.  Set this to @code{first}
11353 (default) or @code{last} to display folders first or last,
11354 respectively.  Any other value will mix files and folders.
11356 @item @code{:sitemap-sort-files}
11357 @tab How the files are sorted in the site map.  Set this to
11358 @code{alphabetically} (default), @code{chronologically} or
11359 @code{anti-chronologically}.  @code{chronologically} sorts the files with
11360 older date first while @code{anti-chronologically} sorts the files with newer
11361 date first.  @code{alphabetically} sorts the files alphabetically.  The date of
11362 a file is retrieved with @code{org-publish-find-date}.
11364 @item @code{:sitemap-ignore-case}
11365 @tab Should sorting be case-sensitive?  Default @code{nil}.
11367 @item @code{:sitemap-file-entry-format}
11368 @tab With this option one can tell how a sitemap's entry is formated in the
11369 sitemap.  This is a format string with some escape sequences: @code{%t} stands
11370 for the title of the file, @code{%a} stands for the author of the file and
11371 @code{%d} stands for the date of the file.  The date is retrieved with the
11372 @code{org-publish-find-date} function and formated with
11373 @code{org-publish-sitemap-date-format}.  Default @code{%t}.
11375 @item @code{:sitemap-date-format}
11376 @tab Format string for the @code{format-time-string} function that tells how
11377 a sitemap entry's date is to be formated.  This property bypasses
11378 @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
11380 @item @code{:sitemap-sans-extension}
11381 @tab When non-nil, remove filenames' extensions from the generated sitemap. 
11382 Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}).
11383 Defaults to @code{nil}.
11385 @end multitable
11387 @node Generating an index,  , Sitemap, Configuration
11388 @subsection Generating an index
11389 @cindex index, in a publishing project
11391 Org-mode can generate an index across the files of a publishing project.
11393 @multitable @columnfractions 0.25 0.75
11394 @item @code{:makeindex}
11395 @tab When non-nil, generate in index in the file @file{theindex.org} and
11396 publish it as @file{theindex.html}.
11397 @end multitable
11399 The file will be created when first publishing a project with the
11400 @code{:makeindex} set.  The file only contains a statement @code{#+include:
11401 "theindex.inc"}.  You can then build around this include statement by adding
11402 a title, style information, etc.
11404 @node Uploading files, Sample configuration, Configuration, Publishing
11405 @section Uploading files
11406 @cindex rsync
11407 @cindex unison
11409 For those people already utilizing third party sync tools such as
11410 @command{rsync} or @command{unison}, it might be preferable not to use the built in
11411 @i{remote} publishing facilities of Org-mode which rely heavily on
11412 Tramp.  Tramp, while very useful and powerful, tends not to be
11413 so efficient for multiple file transfer and has been known to cause problems
11414 under heavy usage.
11416 Specialized synchronization utilities offer several advantages.  In addition
11417 to timestamp comparison, they also do content and permissions/attribute
11418 checks.  For this reason you might prefer to publish your web to a local
11419 directory (possibly even @i{in place} with your Org files) and then use
11420 @file{unison} or @file{rsync} to do the synchronization with the remote host.
11422 Since Unison (for example) can be configured as to which files to transfer to
11423 a certain remote destination, it can greatly simplify the project publishing
11424 definition.  Simply keep all files in the correct location, process your Org
11425 files with @code{org-publish} and let the synchronization tool do the rest.
11426 You do not need, in this scenario, to include attachments such as @file{jpg},
11427 @file{css} or @file{gif} files in the project definition since the 3rd party
11428 tool syncs them.
11430 Publishing to a local directory is also much faster than to a remote one, so
11431 that you can afford more easily to republish entire projects.  If you set
11432 @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
11433 benefit of re-including any changed external files such as source example
11434 files you might include with @code{#+INCLUDE}.  The timestamp mechanism in
11435 Org is not smart enough to detect if included files have been modified.
11437 @node Sample configuration, Triggering publication, Uploading files, Publishing
11438 @section Sample configuration
11440 Below we provide two example configurations.  The first one is a simple
11441 project publishing only a set of Org files.  The second example is
11442 more complex, with a multi-component project.
11444 @menu
11445 * Simple example::              One-component publishing
11446 * Complex example::             A multi-component publishing example
11447 @end menu
11449 @node Simple example, Complex example, Sample configuration, Sample configuration
11450 @subsection Example: simple publishing configuration
11452 This example publishes a set of Org files to the @file{public_html}
11453 directory on the local machine.
11455 @lisp
11456 (setq org-publish-project-alist
11457       '(("org"
11458          :base-directory "~/org/"
11459          :publishing-directory "~/public_html"
11460          :section-numbers nil
11461          :table-of-contents nil
11462          :style "<link rel=\"stylesheet\"
11463                 href=\"../other/mystyle.css\"
11464                 type=\"text/css\"/>")))
11465 @end lisp
11467 @node Complex example,  , Simple example, Sample configuration
11468 @subsection Example: complex publishing configuration
11470 This more complicated example publishes an entire website, including
11471 Org files converted to HTML, image files, Emacs Lisp source code, and
11472 style sheets.  The publishing directory is remote and private files are
11473 excluded.
11475 To ensure that links are preserved, care should be taken to replicate
11476 your directory structure on the web server, and to use relative file
11477 paths.  For example, if your Org files are kept in @file{~/org} and your
11478 publishable images in @file{~/images}, you would link to an image with
11480 @example
11481 file:../images/myimage.png
11482 @end example
11484 On the web server, the relative path to the image should be the
11485 same.  You can accomplish this by setting up an "images" folder in the
11486 right place on the web server, and publishing images to it.
11488 @lisp
11489 (setq org-publish-project-alist
11490       '(("orgfiles"
11491           :base-directory "~/org/"
11492           :base-extension "org"
11493           :publishing-directory "/ssh:user@@host:~/html/notebook/"
11494           :publishing-function org-publish-org-to-html
11495           :exclude "PrivatePage.org"   ;; regexp
11496           :headline-levels 3
11497           :section-numbers nil
11498           :table-of-contents nil
11499           :style "<link rel=\"stylesheet\"
11500                   href=\"../other/mystyle.css\" type=\"text/css\"/>"
11501           :html-preamble t)
11503          ("images"
11504           :base-directory "~/images/"
11505           :base-extension "jpg\\|gif\\|png"
11506           :publishing-directory "/ssh:user@@host:~/html/images/"
11507           :publishing-function org-publish-attachment)
11509          ("other"
11510           :base-directory "~/other/"
11511           :base-extension "css\\|el"
11512           :publishing-directory "/ssh:user@@host:~/html/other/"
11513           :publishing-function org-publish-attachment)
11514          ("website" :components ("orgfiles" "images" "other"))))
11515 @end lisp
11517 @node Triggering publication,  , Sample configuration, Publishing
11518 @section Triggering publication
11520 Once properly configured, Org can publish with the following commands:
11522 @table @kbd
11523 @orgcmd{C-c C-e X,org-publish}
11524 Prompt for a specific project and publish all files that belong to it.
11525 @orgcmd{C-c C-e P,org-publish-current-project}
11526 Publish the project containing the current file.
11527 @orgcmd{C-c C-e F,org-publish-current-file}
11528 Publish only the current file.
11529 @orgcmd{C-c C-e E,org-publish-all}
11530 Publish every project.
11531 @end table
11533 @vindex org-publish-use-timestamps-flag
11534 Org uses timestamps to track when a file has changed.  The above functions
11535 normally only publish changed files.  You can override this and force
11536 publishing of all files by giving a prefix argument to any of the commands
11537 above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
11538 This may be necessary in particular if files include other files via
11539 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
11541 @comment  node-name,  next,  previous,  up
11542 @comment Working With Source Code, Miscellaneous, Publishing, Top
11544 @node Working With Source Code, Miscellaneous, Publishing, Top
11545 @chapter Working with source code
11546 @cindex Schulte, Eric
11547 @cindex Davison, Dan
11548 @cindex source code, working with
11550 Source code can be included in Org-mode documents using a @samp{src} block,
11551 e.g.@:
11553 @example
11554 #+BEGIN_SRC emacs-lisp
11555   (defun org-xor (a b)
11556      "Exclusive or."
11557      (if a (not b) b))
11558 #+END_SRC
11559 @end example
11561 Org-mode provides a number of features for working with live source code,
11562 including editing of code blocks in their native major-mode, evaluation of
11563 code blocks, converting code blocks into source files (known as @dfn{tangling} 
11564 in literate programming), and exporting code blocks and their
11565 results in several formats.  This functionality was contributed by Eric
11566 Schulte and Dan Davison, and was originally named Org-babel.
11568 The following sections describe Org-mode's code block handling facilities.
11570 @menu
11571 * Structure of code blocks::    Code block syntax described
11572 * Editing source code::         Language major-mode editing
11573 * Exporting code blocks::       Export contents and/or results
11574 * Extracting source code::      Create pure source code files
11575 * Evaluating code blocks::      Place results of evaluation in the Org-mode buffer
11576 * Library of Babel::            Use and contribute to a library of useful code blocks
11577 * Languages::                   List of supported code block languages
11578 * Header arguments::            Configure code block functionality
11579 * Results of evaluation::       How evaluation results are handled
11580 * Noweb reference syntax::      Literate programming in Org-mode
11581 * Key bindings and useful functions::  Work quickly with code blocks
11582 * Batch execution::             Call functions from the command line
11583 @end menu
11585 @comment  node-name,  next,  previous,  up
11586 @comment  Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code
11588 @node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code
11589 @section Structure of code blocks
11590 @cindex code block, structure
11591 @cindex source code, block structure
11593 The structure of code blocks is as follows:
11595 @example
11596 #+srcname: <name>
11597 #+begin_src <language> <switches> <header arguments>
11598   <body>
11599 #+end_src
11600 @end example
11602 Switches and header arguments are optional.  Code can also be embedded in text
11603 inline using
11605 @example
11606 src_<language>@{<body>@}
11607 @end example
11611 @example
11612 src_<language>[<header arguments>]@{<body>@}
11613 @end example
11615 @table @code
11616 @item <name>
11617 This name is associated with the code block.  This is similar to the
11618 @samp{#+tblname} lines that can be used to name tables in Org-mode files.
11619 Referencing the name of a code block makes it possible to evaluate the
11620 block from other places in the file, other files, or from Org-mode table
11621 formulas (see @ref{The spreadsheet}).  Names are assumed to be unique by
11622 evaluation functions and the behavior of multiple blocks of the same name is
11623 undefined.
11624 @item <language>
11625 The language of the code in the block.
11626 @item <switches>
11627 Optional switches controlling exportation of the code block (see switches discussion in
11628 @ref{Literal examples})
11629 @item <header arguments>
11630 Optional header arguments control many aspects of evaluation, export and
11631 tangling of code blocks.  See the @ref{Header arguments}. 
11632 Header arguments can also be set on a per-buffer or per-subtree
11633 basis using properties.
11634 @item <body>
11635 The source code.
11636 @end table
11638 @comment  node-name,  next,  previous,  up
11639 @comment  Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code
11641 @node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code
11642 @section Editing source code
11643 @cindex code block, editing
11644 @cindex source code, editing
11646 @kindex C-c '
11647 Use @kbd{C-c '} to edit the current code block.  This brings up
11648 a language major-mode edit buffer containing the body of the code
11649 block.  Saving this buffer will write the new contents back to the Org
11650 buffer.  Use @kbd{C-c '} again to exit.
11652 The @code{org-src-mode} minor mode will be active in the edit buffer.  The
11653 following variables can be used to configure the behavior of the edit
11654 buffer.  See also the customization group @code{org-edit-structure} for
11655 further configuration options.
11657 @table @code
11658 @item org-src-lang-modes
11659 If an Emacs major-mode named @code{<lang>-mode} exists, where
11660 @code{<lang>} is the language named in the header line of the code block,
11661 then the edit buffer will be placed in that major-mode.  This variable
11662 can be used to map arbitrary language names to existing major modes.
11663 @item org-src-window-setup
11664 Controls the way Emacs windows are rearranged when the edit buffer is created.
11665 @item org-src-preserve-indentation
11666 This variable is especially useful for tangling languages such as
11667 Python, in which whitespace indentation in the output is critical.
11668 @item org-src-ask-before-returning-to-edit-buffer
11669 By default, Org will ask before returning to an open edit buffer.  Set this
11670 variable to nil to switch without asking.
11671 @end table
11673 To turn on native code fontification in the @emph{Org} buffer, configure the
11674 variable @code{org-src-fontify-natively}.
11676 @comment  node-name,  next,  previous,  up
11677 @comment  Exporting code blocks, Extracting source code, Editing source code, Working With Source Code
11679 @node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code
11680 @section Exporting code blocks
11681 @cindex code block, exporting
11682 @cindex source code, exporting
11684 It is possible to export the @emph{contents} of code blocks, the
11685 @emph{results} of code block evaluation, @emph{neither}, or @emph{both}.  For
11686 most languages, the default exports the contents of code blocks.  However, for
11687 some languages (e.g.@: @code{ditaa}) the default exports the results of code
11688 block evaluation.  For information on exporting code block bodies, see
11689 @ref{Literal examples}.
11691 The @code{:exports} header argument can be used to specify export
11692 behavior:
11694 @subsubheading Header arguments:
11695 @table @code
11696 @item :exports code
11697 The default in most languages.  The body of the code block is exported, as
11698 described in @ref{Literal examples}.
11699 @item :exports results
11700 The code block will be evaluated and the results will be placed in the
11701 Org-mode buffer for export, either updating previous results of the code
11702 block located anywhere in the buffer or, if no previous results exist,
11703 placing the results immediately after the code block.  The body of the code
11704 block will not be exported.
11705 @item :exports both
11706 Both the code block and its results will be exported.
11707 @item :exports none
11708 Neither the code block nor its results will be exported.
11709 @end table
11711 It is possible to inhibit the evaluation of code blocks during export. 
11712 Setting the @code{org-export-babel-evaluate} variable to @code{nil} will
11713 ensure that no code blocks are evaluated as part of the export process.  This
11714 can be useful in situations where potentially untrusted Org-mode files are
11715 exported in an automated fashion, for example when Org-mode is used as the
11716 markup language for a wiki.
11718 @comment  node-name,  next,  previous,  up
11719 @comment  Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
11720 @node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
11721 @section Extracting source code
11722 @cindex tangling
11723 @cindex source code, extracting
11724 @cindex code block, extracting source code
11726 Creating pure source code files by extracting code from source blocks is
11727 referred to as ``tangling''---a term adopted from the literate programming
11728 community.  During ``tangling'' of code blocks their bodies are expanded
11729 using @code{org-babel-expand-src-block} which can expand both variable and
11730 ``noweb'' style references  (see @ref{Noweb reference syntax}).
11732 @subsubheading Header arguments
11733 @table @code
11734 @item :tangle no
11735 The default.  The code block is not included in the tangled output.
11736 @item :tangle yes
11737 Include the code block in the tangled output.  The output file name is the
11738 name of the org file with the extension @samp{.org} replaced by the extension
11739 for the block language.
11740 @item :tangle filename
11741 Include the code block in the tangled output to file @samp{filename}.
11742 @end table
11744 @kindex  C-c C-v t
11745 @subsubheading Functions
11746 @table @code
11747 @item org-babel-tangle 
11748 Tangle the current file.  Bound to @kbd{C-c C-v t}.
11749 @item org-babel-tangle-file
11750 Choose a file to tangle.  Bound to @kbd{C-c C-v f}.
11751 @end table
11753 @subsubheading Hooks
11754 @table @code
11755 @item org-babel-post-tangle-hook
11756 This hook is run from within code files tangled by @code{org-babel-tangle}. 
11757 Example applications could include post-processing, compilation or evaluation
11758 of tangled code files.
11759 @end table
11761 @node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code
11762 @section Evaluating code blocks
11763 @cindex code block, evaluating
11764 @cindex source code, evaluating
11766 Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
11767 potential for that code to do harm.  Org-mode provides a number of safeguards
11768 to ensure that it only evaluates code with explicit confirmation from the
11769 user.  For information on these safeguards (and on how to disable them) see
11770 @ref{Code evaluation security}.} and the results placed in the Org-mode
11771 buffer.  By default, evaluation is only turned on for @code{emacs-lisp} code
11772 blocks, however support exists for evaluating blocks in many languages.  See
11773 @ref{Languages} for a list of supported languages.  See @ref{Structure of
11774 code blocks} for information on the syntax used to define a code block.
11776 @kindex C-c C-c
11777 There are a number of ways to evaluate code blocks.  The simplest is to press
11778 @kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The
11779 @code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code
11780 evaluation from the @kbd{C-c C-c} key binding.}.  This will call the
11781 @code{org-babel-execute-src-block} function to evaluate the block and insert
11782 its results into the Org-mode buffer.
11784 It is also possible to evaluate named code blocks from anywhere in an
11785 Org-mode buffer or an Org-mode table.  @code{#+call} (or synonymously
11786 @code{#+function} or @code{#+lob}) lines can be used to remotely execute code
11787 blocks located in the current Org-mode buffer or in the ``Library of Babel''
11788 (see @ref{Library of Babel}).  These lines use the following syntax to place
11789 a call on a line by itself.
11791 @example
11792 #+call: <name>(<arguments>)
11793 #+call: <name>[<header args>](<arguments>) <header args>
11794 @end example
11796 The following syntax can be used to place these calls within a block of
11797 prose.
11799 @example
11800 ...prose... call_<name>(<arguments>) ...prose...
11801 ...prose... call_<name>[<header args>](<arguments>)[<header args>] ...prose...
11802 @end example
11804 @table @code
11805 @item <name>
11806 The name of the code block to be evaluated.
11807 @item <arguments>
11808 Arguments specified in this section will be passed to the code block.  These
11809 arguments should relate to @code{:var} header arguments in the called code
11810 block expressed using standard function call syntax.  For example if the
11811 original code block named @code{double} has the header argument @code{:var
11812 n=2}, then the call line passing the number four to that block would be
11813 written as @code{#+call: double(n=2)}.
11814 @item <header args>
11815 Header arguments can be placed either inside the call to the code block or at
11816 the end of the line as shown below.
11818 @example
11819 #+call: code_bloc_name[XXXX](arguments) YYYY
11820 @end example
11822 Header arguments located in these two locations are treated differently.
11824 @table @code
11825 @item XXXX
11826 Those placed in the @code{XXXX} location are passed through and applied to
11827 the code block being called.  These header arguments affect how the code
11828 block is evaluated, for example @code{[:results output]} will collect the
11829 results from @code{STDOUT} of the called code block.
11830 @item YYYY
11831 Those placed in the @code{YYYY} location are applied to the call line and do
11832 not affect the code block being called.  These header arguments affect how
11833 the results are incorporated into the Org-mode buffer when the call line is
11834 evaluated, and how the call line is exported.  For example @code{:results
11835 org} at the end of the call line will insert the results of the call line
11836 inside of an Org-mode block.
11837 @end table
11839 For more examples of passing header arguments to @code{#+call:} lines see
11840 @ref{Header arguments in function calls}.
11841 @end table
11843 @node Library of Babel, Languages, Evaluating code blocks, Working With Source Code
11844 @section Library of Babel
11845 @cindex babel, library of
11846 @cindex source code, library
11847 @cindex code block, library
11849 The ``Library of Babel'' is a library of code blocks
11850 that can be called from any Org-mode file.  The library is housed in an
11851 Org-mode file located in the @samp{contrib} directory of Org-mode. 
11852 Org-mode users can deposit functions they believe to be generally
11853 useful in the library.
11855 Code blocks defined in the ``Library of Babel'' can be called remotely as if
11856 they were in the current Org-mode buffer (see @ref{Evaluating code blocks}
11857 for information on the syntax of remote code block evaluation).
11859 @kindex C-c C-v i
11860 Code blocks located in any Org-mode file can be loaded into the ``Library of
11861 Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v
11864 @node Languages, Header arguments, Library of Babel, Working With Source Code
11865 @section Languages
11866 @cindex babel, languages
11867 @cindex source code, languages
11868 @cindex code block, languages
11870 Code blocks in the following languages are supported.
11872 @multitable @columnfractions 0.28 0.3 0.22 0.2
11873 @item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}
11874 @item Asymptote @tab asymptote @tab Awk @tab awk
11875 @item Emacs Calc @tab calc @tab C @tab C
11876 @item C++ @tab C++ @tab Clojure @tab clojure
11877 @item CSS @tab css @tab ditaa @tab ditaa
11878 @item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp
11879 @item gnuplot @tab gnuplot @tab Haskell @tab haskell
11880 @item Javascript @tab js @tab LaTeX @tab latex 
11881 @item Ledger @tab ledger @tab Lisp @tab lisp 
11882 @item Lilypond @tab lilypond @tab MATLAB @tab matlab
11883 @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
11884 @item Octave @tab octave @tab Org-mode @tab org
11885 @item Oz @tab oz @tab Perl @tab perl
11886 @item Plantuml @tab plantuml @tab Python @tab python
11887 @item R @tab R @tab Ruby @tab ruby
11888 @item Sass @tab sass @tab Scheme @tab scheme
11889 @item GNU Screen @tab screen @tab shell @tab sh
11890 @item SQL @tab sql @tab SQLite @tab sqlite
11891 @end multitable
11893 Language-specific documentation is available for some languages.  If
11894 available, it can be found at
11895 @uref{http://orgmode.org/worg/org-contrib/babel/languages}.
11897 The @code{org-babel-load-languages} controls which languages are enabled for
11898 evaluation (by default only @code{emacs-lisp} is enabled).  This variable can
11899 be set using the customization interface or by adding code like the following
11900 to your emacs configuration.
11902 @quotation
11903 The following disables @code{emacs-lisp} evaluation and enables evaluation of
11904 @code{R} code blocks.
11905 @end quotation
11907 @lisp
11908 (org-babel-do-load-languages
11909  'org-babel-load-languages
11910  '((emacs-lisp . nil)
11911    (R . t)))
11912 @end lisp
11914 It is also possible to enable support for a language by loading the related
11915 elisp file with @code{require}.
11917 @quotation
11918 The following adds support for evaluating @code{clojure} code blocks.
11919 @end quotation
11921 @lisp
11922 (require 'ob-clojure)
11923 @end lisp
11925 @node Header arguments, Results of evaluation, Languages, Working With Source Code
11926 @section Header arguments
11927 @cindex code block, header arguments
11928 @cindex source code, block header arguments
11930 Code block functionality can be configured with header arguments.  This
11931 section provides an overview of the use of header arguments, and then
11932 describes each header argument in detail.
11934 @menu
11935 * Using header arguments::      Different ways to set header arguments
11936 * Specific header arguments::   List of header arguments
11937 @end menu
11939 @node Using header arguments, Specific header arguments, Header arguments, Header arguments
11940 @subsection Using header arguments
11942 The values of header arguments can be set in six different ways, each more
11943 specific (and having higher priority) than the last.
11944 @menu
11945 * System-wide header arguments::  Set global default values
11946 * Language-specific header arguments::  Set default values by language
11947 * Buffer-wide header arguments::  Set default values for a specific buffer
11948 * Header arguments in Org-mode properties::  Set default values for a buffer or heading
11949 * Code block specific header arguments::  The most common way to set values
11950 * Header arguments in function calls::  The most specific level
11951 @end menu
11954 @node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments
11955 @subsubheading System-wide header arguments
11956 @vindex org-babel-default-header-args
11957 System-wide values of header arguments can be specified by customizing the
11958 @code{org-babel-default-header-args} variable:
11960 @example
11961 :session    => "none"
11962 :results    => "replace"
11963 :exports    => "code"
11964 :cache      => "no"
11965 :noweb      => "no"
11966 @end example
11968 @c @example
11969 @c   org-babel-default-header-args is a variable defined in `org-babel.el'.
11970 @c   Its value is
11971 @c   ((:session . "none")
11972 @c    (:results . "replace")
11973 @c    (:exports . "code")
11974 @c    (:cache . "no")
11975 @c    (:noweb . "no"))
11978 @c   Documentation:
11979 @c   Default arguments to use when evaluating a code block.
11980 @c @end example
11982 For example, the following example could be used to set the default value of
11983 @code{:noweb} header arguments to @code{yes}.  This would have the effect of
11984 expanding @code{:noweb} references by default when evaluating source code
11985 blocks.
11987 @lisp
11988 (setq org-babel-default-header-args
11989 (cons '(:noweb . "yes")
11990 (assq-delete-all :noweb org-babel-default-header-args)))
11991 @end lisp
11993 @node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments
11994 @subsubheading Language-specific header arguments
11995 Each language can define its own set of default header arguments.  See the
11996 language-specific documentation available online at
11997 @uref{http://orgmode.org/worg/org-contrib/babel}.
11999 @node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments
12000 @subsubheading Buffer-wide header arguments
12001 Buffer-wide header arguments may be specified through the use of a special
12002 line placed anywhere in an Org-mode file.  The line consists of the
12003 @code{#+BABEL:} keyword followed by a series of header arguments which may be
12004 specified using the standard header argument syntax.
12006 For example the following would set @code{session} to @code{*R*}, and
12007 @code{results} to @code{silent} for every code block in the buffer, ensuring
12008 that all execution took place in the same session, and no results would be
12009 inserted into the buffer.
12011 @example
12012 #+BABEL: :session *R* :results silent
12013 @end example
12015 @node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments
12016 @subsubheading Header arguments in Org-mode properties
12018 Header arguments are also read from Org-mode properties (see @ref{Property
12019 syntax}), which can be set on a buffer-wide or per-heading basis.  An example
12020 of setting a header argument for all code blocks in a buffer is
12022 @example
12023 #+property: tangle yes
12024 @end example
12026 When properties are used to set default header arguments, they are looked up
12027 with inheritance, so the value of the @code{:cache} header argument will default
12028 to @code{yes} in all code blocks in the subtree rooted at the following
12029 heading:
12031 @example
12032 * outline header
12033 :PROPERTIES:
12034 :cache:    yes
12035 :END:
12036 @end example
12038 @kindex C-c C-x p
12039 @vindex org-babel-default-header-args
12040 Properties defined in this way override the properties set in
12041 @code{org-babel-default-header-args}.  It is convenient to use the
12042 @code{org-set-property} function bound to @kbd{C-c C-x p} to set properties
12043 in Org-mode documents.
12045 @node Code block specific header arguments, Header arguments in function calls, Header arguments in Org-mode properties, Using header arguments
12046 @subsubheading Code block specific header arguments
12048 The most common way to assign values to header arguments is at the
12049 code block level.  This can be done by listing a sequence of header
12050 arguments and their values as part of the @code{#+begin_src} line. 
12051 Properties set in this way override both the values of
12052 @code{org-babel-default-header-args} and header arguments specified as
12053 properties.  In the following example, the @code{:results} header argument
12054 is set to @code{silent}, meaning the results of execution will not be
12055 inserted in the buffer, and the @code{:exports} header argument is set to
12056 @code{code}, meaning only the body of the code block will be
12057 preserved on export to HTML or LaTeX.
12059 @example
12060 #+source: factorial
12061 #+begin_src haskell :results silent :exports code :var n=0
12062 fac 0 = 1
12063 fac n = n * fac (n-1)
12064 #+end_src
12065 @end example
12066 Similarly, it is possible to set header arguments for inline code blocks:
12068 @example
12069 src_haskell[:exports both]@{fac 5@}
12070 @end example
12072 Code block header arguments can span multiple lines using =#+header:= or
12073 =#+headers:= lines preceding a code block or nested in between the name and
12074 body of a named code block.
12076 Multi-line header arguments on an un-named code block:
12077 @example
12078  #+headers: :var data1=1
12079  #+begin_src emacs-lisp :var data2=2
12080    (message "data1:%S, data2:%S" data1 data2)
12081  #+end_src
12083  #+results:
12084  : data1:1, data2:2
12085 @end example
12087 Multi-line header arguments on a named code block:
12088 @example
12089    #+source: named-block
12090    #+header: :var data=2
12091    #+begin_src emacs-lisp
12092      (message "data:%S" data)
12093    #+end_src
12095    #+results: named-block
12096    : data:2
12097 @end example
12099 @node Header arguments in function calls,  , Code block specific header arguments, Using header arguments
12100 @comment  node-name,  next,  previous,  up
12101 @subsubheading Header arguments in function calls
12103 At the most specific level, header arguments for ``Library of Babel'' or
12104 function call lines can be set as shown in the two examples below.  For more
12105 information on the structure of @code{#+call:} lines see @ref{Evaluating code
12106 blocks}.
12108 The following will apply the @code{:exports results} header argument to the
12109 evaluation of the @code{#+call:} line.
12110 @example
12111 #+call: factorial(n=5) :exports results
12112 @end example
12114 The following will apply the @code{:session special} header argument to the
12115 evaluation of the @code{factorial} code block.
12116 @example
12117 #+call: factorial[:session special](n=5)
12118 @end example
12120 @node Specific header arguments,  , Using header arguments, Header arguments
12121 @subsection Specific header arguments
12122 The following header arguments are defined:
12124 @menu
12125 * var::                         Pass arguments to code blocks
12126 * results::                     Specify the type of results and how they will
12127                                 be collected and handled
12128 * file::                        Specify a path for file output
12129 * dir::                         Specify the default (possibly remote)
12130                                 directory for code block execution
12131 * exports::                     Export code and/or results
12132 * tangle::                      Toggle tangling and specify file name
12133 * mkdirp::                      Toggle creation of parent directories of target
12134                                 files during tangling
12135 * comments::                    Toggle insertion of comments in tangled
12136                                 code files
12137 * padline::                     Control insertion of padding lines in tangled
12138                                 code files
12139 * no-expand::                   Turn off variable assignment and noweb
12140                                 expansion during tangling
12141 * session::                     Preserve the state of code evaluation
12142 * noweb::                       Toggle expansion of noweb references
12143 * noweb-ref::                   Specify block's noweb reference resolution target
12144 * cache::                       Avoid re-evaluating unchanged code blocks
12145 * sep::                         Delimiter for writing tabular results outside Org
12146 * hlines::                      Handle horizontal lines in tables
12147 * colnames::                    Handle column names in tables
12148 * rownames::                    Handle row names in tables
12149 * shebang::                     Make tangled files executable
12150 * eval::                        Limit evaluation of specific code blocks
12151 @end menu
12153 Additional header arguments are defined on a language-specific basis, see
12154 @ref{Languages}.
12156 @node var, results, Specific header arguments, Specific header arguments
12157 @subsubsection @code{:var}
12158 The @code{:var} header argument is used to pass arguments to code blocks. 
12159 The specifics of how arguments are included in a code block vary by language;
12160 these are addressed in the language-specific documentation.  However, the
12161 syntax used to specify arguments is the same across all languages.  The
12162 values passed to arguments can be literal values, values from org-mode tables
12163 and literal example blocks, the results of other code blocks, or Emacs Lisp
12164 code---see the ``Emacs Lisp evaluation of variables'' heading below.
12166 These values can be indexed in a manner similar to arrays---see the
12167 ``indexable variable values'' heading below.
12169 The following syntax is used to pass arguments to code blocks using the
12170 @code{:var} header argument.
12172 @example
12173 :var name=assign
12174 @end example
12176 where @code{assign} can take one of the following forms
12178 @itemize @bullet
12179 @item literal value
12180 either a string @code{"string"} or a number @code{9}.
12181 @item reference
12182 a table name:
12184 @example
12185 #+tblname: example-table
12186 | 1 |
12187 | 2 |
12188 | 3 |
12189 | 4 |
12191 #+source: table-length
12192 #+begin_src emacs-lisp :var table=example-table
12193 (length table)
12194 #+end_src
12196 #+results: table-length
12197 : 4
12198 @end example
12200 a code block name, as assigned by @code{#+srcname:}, followed by
12201 parentheses:
12203 @example
12204 #+begin_src emacs-lisp :var length=table-length()
12205 (* 2 length)
12206 #+end_src
12208 #+results:
12209 : 8
12210 @end example
12212 In addition, an argument can be passed to the code block referenced
12213 by @code{:var}.  The argument is passed within the parentheses following the
12214 code block name:
12216 @example
12217 #+source: double
12218 #+begin_src emacs-lisp :var input=8
12219 (* 2 input)
12220 #+end_src
12222 #+results: double
12223 : 16
12225 #+source: squared
12226 #+begin_src emacs-lisp :var input=double(input=1)
12227 (* input input)
12228 #+end_src
12230 #+results: squared
12231 : 4
12232 @end example
12233 @end itemize
12235 @subsubheading Alternate argument syntax
12236 It is also possible to specify arguments in a potentially more natural way
12237 using the @code{#+source:} line of a code block.  As in the following
12238 example arguments can be packed inside of parenthesis, separated by commas,
12239 following the source name.
12241 @example
12242 #+source: double(input=0, x=2)
12243 #+begin_src emacs-lisp
12244 (* 2 (+ input x))
12245 #+end_src
12246 @end example
12248 @subsubheading Indexable variable values
12249 It is possible to reference portions of variable values by ``indexing'' into
12250 the variables.  Indexes are 0 based with negative values counting back from
12251 the end.  If an index is separated by @code{,}s then each subsequent section
12252 will index into the next deepest nesting or dimension of the value.  Note
12253 that this indexing occurs @emph{before} other table related header arguments
12254 like @code{:hlines}, @code{:colnames} and @code{:rownames} are applied.  The
12255 following example assigns the last cell of the first row the table
12256 @code{example-table} to the variable @code{data}:
12258 @example
12259 #+results: example-table
12260 | 1 | a |
12261 | 2 | b |
12262 | 3 | c |
12263 | 4 | d |
12265 #+begin_src emacs-lisp :var data=example-table[0,-1]
12266   data
12267 #+end_src
12269 #+results:
12270 : a
12271 @end example
12273 Ranges of variable values can be referenced using two integers separated by a
12274 @code{:}, in which case the entire inclusive range is referenced.  For
12275 example the following assigns the middle three rows of @code{example-table}
12276 to @code{data}.
12278 @example
12279 #+results: example-table
12280 | 1 | a |
12281 | 2 | b |
12282 | 3 | c |
12283 | 4 | d |
12284 | 5 | 3 |
12286 #+begin_src emacs-lisp :var data=example-table[1:3]
12287   data
12288 #+end_src
12290 #+results:
12291 | 2 | b |
12292 | 3 | c |
12293 | 4 | d |
12294 @end example
12296 Additionally, an empty index, or the single character @code{*}, are both
12297 interpreted to mean the entire range and as such are equivalent to
12298 @code{0:-1}, as shown in the following example in which the entire first
12299 column is referenced.
12301 @example
12302 #+results: example-table
12303 | 1 | a |
12304 | 2 | b |
12305 | 3 | c |
12306 | 4 | d |
12308 #+begin_src emacs-lisp :var data=example-table[,0]
12309   data
12310 #+end_src
12312 #+results:
12313 | 1 | 2 | 3 | 4 |
12314 @end example
12316 It is possible to index into the results of code blocks as well as tables. 
12317 Any number of dimensions can be indexed.  Dimensions are separated from one
12318 another by commas, as shown in the following example.
12320 @example
12321 #+source: 3D
12322 #+begin_src emacs-lisp
12323   '(((1  2  3)  (4  5  6)  (7  8  9))
12324     ((10 11 12) (13 14 15) (16 17 18))
12325     ((19 20 21) (22 23 24) (25 26 27)))
12326 #+end_src
12328 #+begin_src emacs-lisp :var data=3D[1,,1]
12329   data
12330 #+end_src
12332 #+results:
12333 | 11 | 14 | 17 |
12334 @end example
12336 @subsubheading Emacs Lisp evaluation of variables
12338 Emacs lisp code can be used to initialize variable values.  When a variable
12339 value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be evaluated as
12340 Emacs Lisp and the result of the evaluation will be assigned as the variable
12341 value.  The following example demonstrates use of this evaluation to reliably
12342 pass the file-name of the org-mode buffer to a code block---note that
12343 evaluation of header arguments is guaranteed to take place in the original
12344 org-mode file, while there is no such guarantee for evaluation of the code
12345 block body.
12347 @example
12348 #+begin_src sh :var filename=(buffer-file-name) :exports both
12349   wc -w $filename
12350 #+end_src
12351 @end example
12353 Note that values read from tables and lists will not be evaluated as
12354 Emacs Lisp, as shown in the following example.
12356 @example
12357 #+results: table
12358 | (a b c) |
12360 #+headers: :var data=table[0,0]
12361 #+begin_src perl
12362   $data
12363 #+end_src
12365 #+results:
12366 : (a b c)
12367 @end example
12369 @node results, file, var, Specific header arguments
12370 @subsubsection @code{:results}
12372 There are three classes of @code{:results} header argument.  Only one option
12373 per class may be supplied per code block.
12375 @itemize @bullet
12376 @item
12377 @b{collection} header arguments specify how the results should be collected
12378 from the code block
12379 @item
12380 @b{type} header arguments specify what type of result the code block will
12381 return---which has implications for how they will be inserted into the
12382 Org-mode buffer
12383 @item
12384 @b{handling} header arguments specify how the results of evaluating the code
12385 block should be handled.
12386 @end itemize
12388 @subsubheading Collection
12389 The following options are mutually exclusive, and specify how the results
12390 should be collected from the code block.
12392 @itemize @bullet
12393 @item @code{value}
12394 This is the default.  The result is the value of the last statement in the
12395 code block.  This header argument places the evaluation in functional
12396 mode.  Note that in some languages, e.g., Python, use of this result type
12397 requires that a @code{return} statement be included in the body of the source
12398 code block.  E.g., @code{:results value}.
12399 @item @code{output}
12400 The result is the collection of everything printed to STDOUT during the
12401 execution of the code block.  This header argument places the
12402 evaluation in scripting mode.  E.g., @code{:results output}.
12403 @end itemize
12405 @subsubheading Type
12407 The following options are mutually exclusive and specify what type of results
12408 the code block will return.  By default, results are inserted as either a
12409 table or scalar depending on their value.
12411 @itemize @bullet
12412 @item @code{table}, @code{vector}
12413 The results should be interpreted as an Org-mode table.  If a single value is
12414 returned, it will be converted into a table with one row and one column. 
12415 E.g., @code{:results value table}.
12416 @item @code{list}
12417 The results should be interpreted as an Org-mode list.  If a single scalar
12418 value is returned it will be converted into a list with only one element.
12419 @item @code{scalar}, @code{verbatim}
12420 The results should be interpreted literally---they will not be
12421 converted into a table.  The results will be inserted into the Org-mode
12422 buffer as quoted text.  E.g., @code{:results value verbatim}.
12423 @item @code{file}
12424 The results will be interpreted as the path to a file, and will be inserted
12425 into the Org-mode buffer as a file link.  E.g., @code{:results value file}.
12426 @item @code{raw}, @code{org}
12427 The results are interpreted as raw Org-mode code and are inserted directly
12428 into the buffer.  If the results look like a table they will be aligned as
12429 such by Org-mode.  E.g., @code{:results value raw}.
12430 @item @code{html}
12431 Results are assumed to be HTML and will be enclosed in a @code{begin_html}
12432 block.  E.g., @code{:results value html}.
12433 @item @code{latex}
12434 Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block. 
12435 E.g., @code{:results value latex}.
12436 @item @code{code}
12437 Result are assumed to be parseable code and are enclosed in a code block. 
12438 E.g., @code{:results value code}.
12439 @item @code{pp}
12440 The result is converted to pretty-printed code and is enclosed in a code
12441 block.  This option currently supports Emacs Lisp, Python, and Ruby.  E.g.,
12442 @code{:results value pp}.
12443 @item @code{wrap}
12444 The result is wrapped in a @code{begin_result} block.  This can be useful for
12445 inserting @code{raw} or @code{org} syntax results in such a way that their
12446 extend is known and they can be automatically removed or replaced.
12447 @end itemize
12449 @subsubheading Handling
12450 The following results options indicate what happens with the
12451 results once they are collected.
12453 @itemize @bullet
12454 @item @code{silent}
12455 The results will be echoed in the minibuffer but will not be inserted into
12456 the Org-mode buffer.  E.g., @code{:results output silent}.
12457 @item @code{replace}
12458 The default value.  Any existing results will be removed, and the new results
12459 will be inserted into the Org-mode buffer in their place.  E.g.,
12460 @code{:results output replace}.
12461 @item @code{append}
12462 If there are pre-existing results of the code block then the new results will
12463 be appended to the existing results.  Otherwise the new results will be
12464 inserted as with @code{replace}.
12465 @item @code{prepend}
12466 If there are pre-existing results of the code block then the new results will
12467 be prepended to the existing results.  Otherwise the new results will be
12468 inserted as with @code{replace}.
12469 @end itemize
12471 @node file, dir, results, Specific header arguments
12472 @subsubsection @code{:file}
12474 The header argument @code{:file} is used to specify an external file in which
12475 to save code block results.  After code block evaluation an Org-mode style
12476 @code{[[file:]]} link (see @ref{Link format}) to the file will be inserted
12477 into the Org-mode buffer.  Some languages including R, gnuplot, dot, and
12478 ditaa provide special handling of the @code{:file} header argument
12479 automatically wrapping the code block body in the boilerplate code required
12480 to save output to the specified file.  This is often useful for saving
12481 graphical output of a code block to the specified file.
12483 The argument to @code{:file} should be either a string specifying the path to
12484 a file, or a list of two strings in which case the first element of the list
12485 should be the path to a file and the second a description for the link.
12487 @node dir, exports, file, Specific header arguments
12488 @subsubsection @code{:dir} and remote execution
12490 While the @code{:file} header argument can be used to specify the path to the
12491 output file, @code{:dir} specifies the default directory during code block
12492 execution.  If it is absent, then the directory associated with the current
12493 buffer is used.  In other words, supplying @code{:dir path} temporarily has
12494 the same effect as changing the current directory with @kbd{M-x cd path}, and
12495 then not supplying @code{:dir}.  Under the surface, @code{:dir} simply sets
12496 the value of the Emacs variable @code{default-directory}.
12498 When using @code{:dir}, you should supply a relative path for file output
12499 (e.g.@: @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
12500 case that path will be interpreted relative to the default directory.
12502 In other words, if you want your plot to go into a folder called @file{Work}
12503 in your home directory, you could use
12505 @example
12506 #+begin_src R :file myplot.png :dir ~/Work
12507 matplot(matrix(rnorm(100), 10), type="l")
12508 #+end_src
12509 @end example
12511 @subsubheading Remote execution
12512 A directory on a remote machine can be specified using tramp file syntax, in
12513 which case the code will be evaluated on the remote machine.  An example is
12515 @example
12516 #+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu:
12517 plot(1:10, main=system("hostname", intern=TRUE))
12518 #+end_src
12519 @end example
12521 Text results will be returned to the local Org-mode buffer as usual, and file
12522 output will be created on the remote machine with relative paths interpreted
12523 relative to the remote directory.  An Org-mode link to the remote file will be
12524 created.
12526 So, in the above example a plot will be created on the remote machine,
12527 and a link of the following form will be inserted in the org buffer:
12529 @example
12530 [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
12531 @end example
12533 Most of this functionality follows immediately from the fact that @code{:dir}
12534 sets the value of the Emacs variable @code{default-directory}, thanks to
12535 tramp.  Those using XEmacs, or GNU Emacs prior to version 23 may need to
12536 install tramp separately in order for these features to work correctly.
12538 @subsubheading Further points
12540 @itemize @bullet
12541 @item
12542 If @code{:dir} is used in conjunction with @code{:session}, although it will
12543 determine the starting directory for a new session as expected, no attempt is
12544 currently made to alter the directory associated with an existing session.
12545 @item
12546 @code{:dir} should typically not be used to create files during export with
12547 @code{:exports results} or @code{:exports both}.  The reason is that, in order
12548 to retain portability of exported material between machines, during export
12549 links inserted into the buffer will *not* be expanded against @code{default
12550 directory}.  Therefore, if @code{default-directory} is altered using
12551 @code{:dir}, it is probable that the file will be created in a location to
12552 which the link does not point.
12553 @end itemize
12555 @node exports, tangle, dir, Specific header arguments
12556 @subsubsection @code{:exports}
12558 The @code{:exports} header argument specifies what should be included in HTML
12559 or LaTeX exports of the Org-mode file.
12561 @itemize @bullet
12562 @item @code{code}
12563 The default.  The body of code is included into the exported file.  E.g.,
12564 @code{:exports code}.
12565 @item @code{results}
12566 The result of evaluating the code is included in the exported file.  E.g.,
12567 @code{:exports results}.
12568 @item @code{both}
12569 Both the code and results are included in the exported file.  E.g.,
12570 @code{:exports both}.
12571 @item @code{none}
12572 Nothing is included in the exported file.  E.g., @code{:exports none}.
12573 @end itemize
12575 @node tangle, mkdirp, exports, Specific header arguments
12576 @subsubsection @code{:tangle}
12578 The @code{:tangle} header argument specifies whether or not the code
12579 block should be included in tangled extraction of source code files.
12581 @itemize @bullet
12582 @item @code{tangle}
12583 The code block is exported to a source code file named after the full path
12584 (including the directory) and file name (w/o extension) of the Org-mode file.
12585 E.g., @code{:tangle yes}.
12586 @item @code{no}
12587 The default.  The code block is not exported to a source code file. 
12588 E.g., @code{:tangle no}.
12589 @item other
12590 Any other string passed to the @code{:tangle} header argument is interpreted
12591 as a path (directory and file name relative to the directory of the Org-mode
12592 file) to which the block will be exported.  E.g., @code{:tangle path}.
12593 @end itemize
12595 @node mkdirp, comments, tangle, Specific header arguments
12596 @subsubsection @code{:mkdirp}
12598 The @code{:mkdirp} header argument can be used to create parent directories
12599 of tangled files when missing.  This can be set to @code{yes} to enable
12600 directory creation or to @code{no} to inhibit directory creation.
12602 @node comments, padline, mkdirp, Specific header arguments
12603 @subsubsection @code{:comments}
12604 By default code blocks are tangled to source-code files without any insertion
12605 of comments beyond those which may already exist in the body of the code
12606 block.  The @code{:comments} header argument can be set as follows to control
12607 the insertion of extra comments into the tangled code file.
12609 @itemize @bullet
12610 @item @code{no}
12611 The default.  No extra comments are inserted during tangling.
12612 @item @code{link}
12613 The code block is wrapped in comments which contain pointers back to the
12614 original Org file from which the code was tangled.
12615 @item @code{yes}
12616 A synonym for ``link'' to maintain backwards compatibility.
12617 @item @code{org}
12618 Include text from the org-mode file as a comment.
12620 The text is picked from the leading context of the tangled code and is
12621 limited by the nearest headline or source block as the case may be.
12622 @item @code{both}
12623 Turns on both the ``link'' and ``org'' comment options.
12624 @item @code{noweb}
12625 Turns on the ``link'' comment option, and additionally wraps expanded noweb
12626 references in the code block body in link comments.
12627 @end itemize
12629 @node padline, no-expand, comments, Specific header arguments
12630 @subsubsection @code{:padline}
12631 Control in insertion of padding lines around code block bodies in tangled
12632 code files.  The default value is @code{yes} which results in insertion of
12633 newlines before and after each tangled code block.  The following arguments
12634 are accepted.
12636 @itemize @bullet
12637 @item @code{yes}
12638 Insert newlines before and after each code block body in tangled code files.
12639 @item @code{no}
12640 Do not insert any newline padding in tangled output.
12641 @end itemize
12643 @node no-expand, session, padline, Specific header arguments
12644 @subsubsection @code{:no-expand}
12646 By default, code blocks are expanded with @code{org-babel-expand-src-block}
12647 during tangling.  This has the effect of assigning values to variables
12648 specified with @code{:var} (see @ref{var}), and of replacing ``noweb''
12649 references (see @ref{Noweb reference syntax}) with their targets.  The
12650 @code{:no-expand} header argument can be used to turn off this behavior.
12652 @node session, noweb, no-expand, Specific header arguments
12653 @subsubsection @code{:session}
12655 The @code{:session} header argument starts a session for an interpreted
12656 language where state is preserved.
12658 By default, a session is not started.
12660 A string passed to the @code{:session} header argument will give the session
12661 a name.  This makes it possible to run concurrent sessions for each
12662 interpreted language.
12664 @node noweb, noweb-ref, session, Specific header arguments
12665 @subsubsection @code{:noweb}
12667 The @code{:noweb} header argument controls expansion of ``noweb'' style (see
12668 @ref{Noweb reference syntax}) references in a code block.  This header
12669 argument can have one of three values: @code{yes}, @code{no}, or @code{tangle}.
12671 @itemize @bullet
12672 @item @code{yes}
12673 All ``noweb'' syntax references in the body of the code block will be
12674 expanded before the block is evaluated, tangled or exported.
12675 @item @code{no}
12676 The default.  No ``noweb'' syntax specific action is taken on evaluating
12677 code blocks, However, noweb references will still be expanded during
12678 tangling.
12679 @item @code{tangle}
12680 All ``noweb'' syntax references in the body of the code block will be
12681 expanded before the block is tangled, however ``noweb'' references will not
12682 be expanded when the block is evaluated or exported.
12683 @end itemize
12685 @subsubheading Noweb prefix lines
12686 Noweb insertions are now placed behind the line prefix of the
12687 @code{<<reference>>}.
12688 This behavior is illustrated in the following example.  Because the
12689 @code{<<example>>} noweb reference appears behind the SQL comment syntax,
12690 each line of the expanded noweb reference will be commented.
12692 This code block:
12694 @example
12695 -- <<example>>
12696 @end example
12699 expands to:
12701 @example
12702 -- this is the
12703 -- multi-line body of example
12704 @end example
12706 Note that noweb replacement text that does not contain any newlines will not
12707 be affected by this change, so it is still possible to use inline noweb
12708 references.
12710 @node noweb-ref, cache, noweb, Specific header arguments
12711 @subsubsection @code{:noweb-ref}
12712 When expanding ``noweb'' style references the bodies of all code block with
12713 @emph{either} a block name matching the reference name @emph{or} a
12714 @code{:noweb-ref} header argument matching the reference name will be
12715 concatenated together to form the replacement text.
12717 By setting this header argument at the sub-tree or file level, simple code
12718 block concatenation may be achieved.  For example, when tangling the
12719 following Org-mode file, the bodies of code blocks will be concatenated into
12720 the resulting pure code file.
12722 @example
12723  #+begin_src sh :tangle yes :noweb yes :shebang #!/bin/sh
12724    <<fullest-disk>>
12725  #+end_src
12726  * the mount point of the fullest disk
12727    :PROPERTIES:
12728    :noweb-ref: fullest-disk
12729    :END:
12731  ** query all mounted disks
12732  #+begin_src sh
12733    df \
12734  #+end_src
12736  ** strip the header row
12737  #+begin_src sh
12738    |sed '1d' \
12739  #+end_src
12741  ** sort by the percent full
12742  #+begin_src sh
12743    |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
12744  #+end_src
12746  ** extract the mount point
12747  #+begin_src sh
12748    |awk '@{print $2@}'
12749  #+end_src
12750 @end example
12752 @node cache, sep, noweb-ref, Specific header arguments
12753 @subsubsection @code{:cache}
12755 The @code{:cache} header argument controls the use of in-buffer caching of
12756 the results of evaluating code blocks.  It can be used to avoid re-evaluating
12757 unchanged code blocks.  This header argument can have one of two
12758 values: @code{yes} or @code{no}.
12760 @itemize @bullet
12761 @item @code{no}
12762 The default.  No caching takes place, and the code block will be evaluated
12763 every time it is called.
12764 @item @code{yes}
12765 Every time the code block is run a SHA1 hash of the code and arguments
12766 passed to the block will be generated.  This hash is packed into the
12767 @code{#+results:} line and will be checked on subsequent
12768 executions of the code block.  If the code block has not
12769 changed since the last time it was evaluated, it will not be re-evaluated.
12770 @end itemize
12772 Code block caches notice if the value of a variable argument
12773 to the code block has changed.  If this is the case, the cache is
12774 invalidated and the code block is re-run.  In the following example,
12775 @code{caller} will not be re-run unless the results of @code{random} have
12776 changed since it was last run.
12778 @example
12779  #+srcname: random
12780  #+begin_src R :cache yes
12781  runif(1)
12782  #+end_src
12784  #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
12785  0.4659510825295
12787  #+srcname: caller
12788  #+begin_src emacs-lisp :var x=random :cache yes
12790  #+end_src
12792  #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
12793  0.254227238707244
12794 @end example
12796 @node sep, hlines, cache, Specific header arguments
12797 @subsubsection @code{:sep}
12799 The @code{:sep} header argument can be used to control the delimiter used
12800 when writing tabular results out to files external to Org-mode.  This is used
12801 either when opening tabular results of a code block by calling the
12802 @code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block,
12803 or when writing code block results to an external file (see @ref{file})
12804 header argument.
12806 By default, when @code{:sep} is not specified output tables are tab
12807 delimited.
12809 @node hlines, colnames, sep, Specific header arguments
12810 @subsubsection @code{:hlines}
12812 Tables are frequently represented with one or more horizontal lines, or
12813 hlines.  The @code{:hlines} argument to a code block accepts the
12814 values @code{yes} or @code{no}, with a default value of @code{no}.
12816 @itemize @bullet
12817 @item @code{no}
12818 Strips horizontal lines from the input table.  In most languages this is the
12819 desired effect because an @code{hline} symbol is interpreted as an unbound
12820 variable and raises an error.  Setting @code{:hlines no} or relying on the
12821 default value yields the following results.
12823 @example
12824 #+tblname: many-cols
12825 | a | b | c |
12826 |---+---+---|
12827 | d | e | f |
12828 |---+---+---|
12829 | g | h | i |
12831 #+source: echo-table
12832 #+begin_src python :var tab=many-cols
12833   return tab
12834 #+end_src
12836 #+results: echo-table
12837 | a | b | c |
12838 | d | e | f |
12839 | g | h | i |
12840 @end example
12842 @item @code{yes}
12843 Leaves hlines in the table.  Setting @code{:hlines yes} has this effect.
12845 @example
12846 #+tblname: many-cols
12847 | a | b | c |
12848 |---+---+---|
12849 | d | e | f |
12850 |---+---+---|
12851 | g | h | i |
12853 #+source: echo-table
12854 #+begin_src python :var tab=many-cols :hlines yes
12855   return tab
12856 #+end_src
12858 #+results: echo-table
12859 | a | b | c |
12860 |---+---+---|
12861 | d | e | f |
12862 |---+---+---|
12863 | g | h | i |
12864 @end example
12865 @end itemize
12867 @node colnames, rownames, hlines, Specific header arguments
12868 @subsubsection @code{:colnames}
12870 The @code{:colnames} header argument accepts the values @code{yes},
12871 @code{no}, or @code{nil} for unassigned.  The default value is @code{nil}.
12873 @itemize @bullet
12874 @item @code{nil}
12875 If an input table looks like it has column names
12876 (because its second row is an hline), then the column
12877 names will be removed from the table before
12878 processing, then reapplied to the results.
12880 @example
12881 #+tblname: less-cols
12882 | a |
12883 |---|
12884 | b |
12885 | c |
12887 #+srcname: echo-table-again
12888 #+begin_src python :var tab=less-cols
12889   return [[val + '*' for val in row] for row in tab]
12890 #+end_src
12892 #+results: echo-table-again
12893 | a  |
12894 |----|
12895 | b* |
12896 | c* |
12897 @end example
12899 Please note that column names are not removed before the table is indexed
12900 using variable indexing @xref{var, Indexable variable values}.
12902 @item @code{no}
12903 No column name pre-processing takes place
12905 @item @code{yes}
12906 Column names are removed and reapplied as with @code{nil} even if the table
12907 does not ``look like'' it has column names (i.e.@: the second row is not an
12908 hline)
12909 @end itemize
12911 @node rownames, shebang, colnames, Specific header arguments
12912 @subsubsection @code{:rownames}
12914 The @code{:rownames} header argument can take on the values @code{yes}
12915 or @code{no}, with a default value of @code{no}.
12917 @itemize @bullet
12918 @item @code{no}
12919 No row name pre-processing will take place.
12921 @item @code{yes}
12922 The first column of the table is removed from the table before processing,
12923 and is then reapplied to the results.
12925 @example
12926 #+tblname: with-rownames
12927 | one | 1 | 2 | 3 | 4 |  5 |
12928 | two | 6 | 7 | 8 | 9 | 10 |
12930 #+srcname: echo-table-once-again
12931 #+begin_src python :var tab=with-rownames :rownames yes
12932   return [[val + 10 for val in row] for row in tab]
12933 #+end_src
12935 #+results: echo-table-once-again
12936 | one | 11 | 12 | 13 | 14 | 15 |
12937 | two | 16 | 17 | 18 | 19 | 20 |
12938 @end example
12940 Please note that row names are not removed before the table is indexed using
12941 variable indexing @xref{var, Indexable variable values}.
12943 @end itemize
12945 @node shebang, eval, rownames, Specific header arguments
12946 @subsubsection @code{:shebang}
12948 Setting the @code{:shebang} header argument to a string value
12949 (e.g.@: @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the
12950 first line of any tangled file holding the code block, and the file
12951 permissions of the tangled file are set to make it executable.
12953 @node eval,  , shebang, Specific header arguments
12954 @subsubsection @code{:eval}
12955 The @code{:eval} header argument can be used to limit the evaluation of
12956 specific code blocks.  @code{:eval} accepts two arguments ``never'' and
12957 ``query''.  @code{:eval never} will ensure that a code block is never
12958 evaluated, this can be useful for protecting against the evaluation of
12959 dangerous code blocks.  @code{:eval query} will require a query for every
12960 execution of a code block regardless of the value of the
12961 @code{org-confirm-babel-evaluate} variable.
12963 @node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code
12964 @section Results of evaluation
12965 @cindex code block, results of evaluation
12966 @cindex source code, results of evaluation
12968 The way in which results are handled depends on whether a session is invoked,
12969 as well as on whether @code{:results value} or @code{:results output} is
12970 used.  The following table shows the table possibilities.  For a full listing
12971 of the possible results header arguments see @ref{results}.
12973 @multitable @columnfractions 0.26 0.33 0.41
12974 @item @tab @b{Non-session} @tab @b{Session}
12975 @item @code{:results value} @tab value of last expression @tab value of last expression
12976 @item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output
12977 @end multitable
12979 Note: With @code{:results value}, the result in both @code{:session} and
12980 non-session is returned to Org-mode as a table (a one- or two-dimensional
12981 vector of strings or numbers) when appropriate.
12983 @subsection Non-session
12984 @subsubsection @code{:results value}
12985 This is the default.  Internally, the value is obtained by wrapping the code
12986 in a function definition in the external language, and evaluating that
12987 function.  Therefore, code should be written as if it were the body of such a
12988 function.  In particular, note that Python does not automatically return a
12989 value from a function unless a @code{return} statement is present, and so a
12990 @samp{return} statement will usually be required in Python.
12992 This is the only one of the four evaluation contexts in which the code is
12993 automatically wrapped in a function definition.
12995 @subsubsection @code{:results output}
12996 The code is passed to the interpreter as an external process, and the
12997 contents of the standard output stream are returned as text.  (In certain
12998 languages this also contains the error output stream; this is an area for
12999 future work.)
13001 @subsection Session
13002 @subsubsection @code{:results value}
13003 The code is passed to an interpreter running as an interactive Emacs inferior
13004 process.  Only languages which provide tools for interactive evaluation of
13005 code have session support, so some language (e.g., C and ditaa) do not
13006 support the @code{:session} header argument, and in other languages (e.g.,
13007 Python and Haskell) which have limitations on the code which may be entered
13008 into interactive sessions, those limitations apply to the code in code blocks
13009 using the @code{:session} header argument as well.
13011 Unless the @code{:results output} option is supplied (see below) the result
13012 returned is the result of the last evaluation performed by the
13013 interpreter.  (This is obtained in a language-specific manner: the value of
13014 the variable @code{_} in Python and Ruby, and the value of @code{.Last.value}
13015 in R).
13017 @subsubsection @code{:results output}
13018 The code is passed to the interpreter running as an interactive Emacs
13019 inferior process.  The result returned is the concatenation of the sequence of
13020 (text) output from the interactive interpreter.  Notice that this is not
13021 necessarily the same as what would be sent to @code{STDOUT} if the same code
13022 were passed to a non-interactive interpreter running as an external
13023 process.  For example, compare the following two blocks:
13025 @example
13026 #+begin_src python :results output
13027  print "hello"
13029  print "bye"
13030 #+end_src
13032 #+resname:
13033 : hello
13034 : bye
13035 @end example
13037 In non-session mode, the `2' is not printed and does not appear.
13038 @example
13039 #+begin_src python :results output :session
13040  print "hello"
13042  print "bye"
13043 #+end_src
13045 #+resname:
13046 : hello
13047 : 2
13048 : bye
13049 @end example
13051 But in @code{:session} mode, the interactive interpreter receives input `2'
13052 and prints out its value, `2'.  (Indeed, the other print statements are
13053 unnecessary here).
13055 @node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code
13056 @section Noweb reference syntax
13057 @cindex code block, noweb reference
13058 @cindex syntax, noweb
13059 @cindex source code, noweb reference
13061 The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate
13062 Programming system allows named blocks of code to be referenced by using the
13063 familiar Noweb syntax:
13065 @example
13066 <<code-block-name>>
13067 @end example
13069 When a code block is tangled or evaluated, whether or not ``noweb''
13070 references are expanded depends upon the value of the @code{:noweb} header
13071 argument.  If @code{:noweb yes}, then a Noweb reference is expanded before
13072 evaluation.  If @code{:noweb no}, the default, then the reference is not
13073 expanded before evaluation.
13075 Note: the default value, @code{:noweb no}, was chosen to ensure that
13076 correct code is not broken in a language, such as Ruby, where
13077 @code{<<arg>>} is a syntactically valid construct.  If @code{<<arg>>} is not
13078 syntactically valid in languages that you use, then please consider setting
13079 the default value.
13081 @node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code
13082 @section Key bindings and useful functions
13083 @cindex code block, key bindings
13085 Many common Org-mode key sequences are re-bound depending on
13086 the context.
13088 Within a code block, the following key bindings
13089 are active:
13091 @multitable @columnfractions 0.25 0.75
13092 @kindex C-c C-c
13093 @item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block}
13094 @kindex C-c C-o
13095 @item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result}
13096 @kindex C-up
13097 @item @kbd{C-@key{up}}    @tab @code{org-babel-load-in-session}
13098 @kindex M-down
13099 @item @kbd{M-@key{down}}  @tab @code{org-babel-pop-to-session}
13100 @end multitable
13102 In an Org-mode buffer, the following key bindings are active:
13104 @multitable @columnfractions 0.45 0.55
13105 @kindex C-c C-v a
13106 @kindex C-c C-v C-a
13107 @item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
13108 @kindex C-c C-v b
13109 @kindex C-c C-v C-b
13110 @item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
13111 @kindex C-c C-v f
13112 @kindex C-c C-v C-f
13113 @item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
13114 @kindex C-c C-v g
13115 @item @kbd{C-c C-v g} @tab @code{org-babel-goto-named-source-block}
13116 @kindex C-c C-v h
13117 @item @kbd{C-c C-v h} @tab @code{org-babel-describe-bindings}
13118 @kindex C-c C-v l
13119 @kindex C-c C-v C-l
13120 @item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
13121 @kindex C-c C-v p
13122 @kindex C-c C-v C-p
13123 @item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
13124 @kindex C-c C-v s
13125 @kindex C-c C-v C-s
13126 @item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
13127 @kindex C-c C-v t
13128 @kindex C-c C-v C-t
13129 @item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
13130 @kindex C-c C-v z
13131 @kindex C-c C-v C-z
13132 @item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
13133 @end multitable
13135 @c When possible these keybindings were extended to work when the control key is
13136 @c kept pressed, resulting in the following additional keybindings.
13138 @c @multitable @columnfractions 0.25 0.75
13139 @c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
13140 @c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
13141 @c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
13142 @c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
13143 @c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
13144 @c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
13145 @c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
13146 @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
13147 @c @end multitable
13149 @node Batch execution,  , Key bindings and useful functions, Working With Source Code
13150 @section Batch execution
13151 @cindex code block, batch execution
13152 @cindex source code, batch execution
13154 It is possible to call functions from the command line.  This shell
13155 script calls @code{org-babel-tangle} on every one of its arguments.
13157 Be sure to adjust the paths to fit your system.
13159 @example
13160 #!/bin/sh
13161 # -*- mode: shell-script -*-
13163 # tangle files with org-mode
13165 DIR=`pwd`
13166 FILES=""
13167 ORGINSTALL="~/src/org/lisp/org-install.el"
13169 # wrap each argument in the code required to call tangle on it
13170 for i in $@@; do
13171     FILES="$FILES \"$i\""
13172 done
13174 emacs -Q --batch -l $ORGINSTALL \
13175 --eval "(progn
13176 (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
13177 (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\"))
13178 (require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
13179 (mapc (lambda (file)
13180        (find-file (expand-file-name file \"$DIR\"))
13181        (org-babel-tangle)
13182        (kill-buffer)) '($FILES)))" 2>&1 |grep tangled
13183 @end example
13185 @node Miscellaneous, Hacking, Working With Source Code, Top
13186 @chapter Miscellaneous
13188 @menu
13189 * Completion::                  M-TAB knows what you need
13190 * Easy Templates::              Quick insertion of structural elements
13191 * Speed keys::                  Electric commands at the beginning of a headline
13192 * Code evaluation security::    Org mode files evaluate inline code
13193 * Customization::               Adapting Org to your taste
13194 * In-buffer settings::          Overview of the #+KEYWORDS
13195 * The very busy C-c C-c key::   When in doubt, press C-c C-c
13196 * Clean view::                  Getting rid of leading stars in the outline
13197 * TTY keys::                    Using Org on a tty
13198 * Interaction::                 Other Emacs packages
13199 * org-crypt.el::                Encrypting Org files
13200 @end menu
13203 @node Completion, Easy Templates, Miscellaneous, Miscellaneous
13204 @section Completion
13205 @cindex completion, of @TeX{} symbols
13206 @cindex completion, of TODO keywords
13207 @cindex completion, of dictionary words
13208 @cindex completion, of option keywords
13209 @cindex completion, of tags
13210 @cindex completion, of property keys
13211 @cindex completion, of link abbreviations
13212 @cindex @TeX{} symbol completion
13213 @cindex TODO keywords completion
13214 @cindex dictionary word completion
13215 @cindex option keyword completion
13216 @cindex tag completion
13217 @cindex link abbreviations, completion of
13219 Emacs would not be Emacs without completion, and Org-mode uses it whenever it
13220 makes sense.  If you prefer an @i{iswitchb}- or @i{ido}-like interface for
13221 some of the completion prompts, you can specify your preference by setting at
13222 most one of the variables @code{org-completion-use-iswitchb}
13223 @code{org-completion-use-ido}.
13225 Org supports in-buffer completion.  This type of completion does
13226 not make use of the minibuffer.  You simply type a few letters into
13227 the buffer and use the key to complete text right there.
13229 @table @kbd
13230 @kindex M-@key{TAB}
13231 @item M-@key{TAB}
13232 Complete word at point
13233 @itemize @bullet
13234 @item
13235 At the beginning of a headline, complete TODO keywords.
13236 @item
13237 After @samp{\}, complete @TeX{} symbols supported by the exporter.
13238 @item
13239 After @samp{*}, complete headlines in the current buffer so that they
13240 can be used in search links like @samp{[[*find this headline]]}.
13241 @item
13242 After @samp{:} in a headline, complete tags.  The list of tags is taken
13243 from the variable @code{org-tag-alist} (possibly set through the
13244 @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
13245 dynamically from all tags used in the current buffer.
13246 @item
13247 After @samp{:} and not in a headline, complete property keys.  The list
13248 of keys is constructed dynamically from all keys used in the current
13249 buffer.
13250 @item
13251 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
13252 @item
13253 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
13254 @samp{OPTIONS} which set file-specific options for Org-mode.  When the
13255 option keyword is already complete, pressing @kbd{M-@key{TAB}} again
13256 will insert example settings for this keyword.
13257 @item
13258 In the line after @samp{#+STARTUP: }, complete startup keywords,
13259 i.e.@: valid keys for this line.
13260 @item
13261 Elsewhere, complete dictionary words using Ispell.
13262 @end itemize
13263 @end table
13265 @node Easy Templates, Speed keys, Completion, Miscellaneous
13266 @section Easy Templates
13267 @cindex template insertion
13268 @cindex insertion, of templates
13270 Org-mode supports insertion of empty structural elements (like
13271 @code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key
13272 strokes.  This is achieved through a native template expansion mechanism.
13273 Note that Emacs has several other template mechanisms which could be used in
13274 a similar way, for example @file{yasnippet}.
13276 To insert a structural element, type a @samp{<}, followed by a template
13277 selector and @kbd{@key{TAB}}.  Completion takes effect only when the above
13278 keystrokes are typed on a line by itself.
13280 The following template selectors are currently supported.
13282 @multitable @columnfractions 0.1 0.9
13283 @item @kbd{s} @tab @code{#+begin_src     ... #+end_src}
13284 @item @kbd{e} @tab @code{#+begin_example ... #+end_example}
13285 @item @kbd{q} @tab @code{#+begin_quote   ... #+end_quote}
13286 @item @kbd{v} @tab @code{#+begin_verse   ... #+end_verse}
13287 @item @kbd{c} @tab @code{#+begin_center  ... #+end_center}
13288 @item @kbd{l} @tab @code{#+begin_latex   ... #+end_latex}
13289 @item @kbd{L} @tab @code{#+latex:}
13290 @item @kbd{h} @tab @code{#+begin_html    ... #+end_html}
13291 @item @kbd{H} @tab @code{#+html:}
13292 @item @kbd{a} @tab @code{#+begin_ascii   ... #+end_ascii}
13293 @item @kbd{A} @tab @code{#+ascii:}
13294 @item @kbd{i} @tab @code{#+index:} line
13295 @item @kbd{I} @tab @code{#+include:} line
13296 @end multitable
13298 For example, on an empty line, typing "<e" and then pressing TAB, will expand
13299 into a complete EXAMPLE template.
13301 You can install additional templates by customizing the variable
13302 @code{org-structure-template-alist}.  See the docstring of the variable for
13303 additional details.
13305 @node Speed keys, Code evaluation security, Easy Templates, Miscellaneous
13306 @section Speed keys
13307 @cindex speed keys
13308 @vindex org-use-speed-commands
13309 @vindex org-speed-commands-user
13311 Single keys can be made to execute commands when the cursor is at the
13312 beginning of a headline, i.e.@: before the first star.  Configure the variable
13313 @code{org-use-speed-commands} to activate this feature.  There is a
13314 pre-defined list of commands, and you can add more such commands using the
13315 variable @code{org-speed-commands-user}.  Speed keys do not only speed up
13316 navigation and other commands, but they also provide an alternative way to
13317 execute commands bound to keys that are not or not easily available on a TTY,
13318 or on a small mobile device with a limited keyboard.
13320 To see which commands are available, activate the feature and press @kbd{?}
13321 with the cursor at the beginning of a headline.
13323 @node Code evaluation security, Customization, Speed keys, Miscellaneous
13324 @section Code evaluation and security issues
13326 Org provides tools to work with the code snippets, including evaluating them.
13328 Running code on your machine always comes with a security risk.  Badly
13329 written or malicious code can be executed on purpose or by accident.  Org has
13330 default settings which will only evaluate such code if you give explicit
13331 permission to do so, and as a casual user of these features you should leave
13332 these precautions intact.
13334 For people who regularly work with such code, the confirmation prompts can
13335 become annoying, and you might want to turn them off.  This can be done, but
13336 you must be aware of the risks that are involved.
13338 Code evaluation can happen under the following circumstances:
13340 @table @i
13341 @item Source code blocks
13342 Source code blocks can be evaluated during export, or when pressing @kbd{C-c
13343 C-c} in the block.  The most important thing to realize here is that Org mode
13344 files which contain code snippets are, in a certain sense, like executable
13345 files.  So you should accept them and load them into Emacs only from trusted
13346 sources---just like you would do with a program you install on your computer.
13348 Make sure you know what you are doing before customizing the variables
13349 which take off the default security brakes.
13351 @defopt org-confirm-babel-evaluate
13352 When t (the default), the user is asked before every code block evaluation.
13353 When nil, the user is not asked.  When set to a function, it is called with
13354 two arguments (language and body of the code block) and should return t to
13355 ask and nil not to ask.
13356 @end defopt
13358 For example, here is how to execute "ditaa" code (which is considered safe)
13359 without asking:
13360 @example
13361 (defun my-org-confirm-babel-evaluate (lang body)
13362   (not (string= lang "ditaa")))  ; don't ask for ditaa
13363 (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
13364 @end example
13366 @item Following @code{shell} and @code{elisp} links
13367 Org has two link types that can directly evaluate code (@pxref{External
13368 links}).  These links can be problematic because the code to be evaluated is
13369 not visible.
13371 @defopt org-confirm-shell-link-function
13372 Function to queries user about shell link execution.
13373 @end defopt
13374 @defopt org-confirm-elisp-link-function
13375 Functions to query user for Emacs Lisp link execution.
13376 @end defopt
13378 @item Formulas in tables
13379 Formulas in tables (@pxref{The spreadsheet}) are code that is evaluated
13380 either by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter.
13381 @end table
13383 @node Customization, In-buffer settings, Code evaluation security, Miscellaneous
13384 @section Customization
13385 @cindex customization
13386 @cindex options, for customization
13387 @cindex variables, for customization
13389 There are more than 180 variables that can be used to customize
13390 Org.  For the sake of compactness of the manual, I am not
13391 describing the variables here.  A structured overview of customization
13392 variables is available with @kbd{M-x org-customize}.  Or select
13393 @code{Browse Org Group} from the @code{Org->Customization} menu.  Many
13394 settings can also be activated on a per-file basis, by putting special
13395 lines into the buffer (@pxref{In-buffer settings}).
13397 @node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
13398 @section Summary of in-buffer settings
13399 @cindex in-buffer settings
13400 @cindex special keywords
13402 Org-mode uses special lines in the buffer to define settings on a
13403 per-file basis.  These lines start with a @samp{#+} followed by a
13404 keyword, a colon, and then individual words defining a setting.  Several
13405 setting words can be in the same line, but you can also have multiple
13406 lines for the keyword.  While these settings are described throughout
13407 the manual, here is a summary.  After changing any of those lines in the
13408 buffer, press @kbd{C-c C-c} with the cursor still in the line to
13409 activate the changes immediately.  Otherwise they become effective only
13410 when the file is visited again in a new Emacs session.
13412 @vindex org-archive-location
13413 @table @kbd
13414 @item #+ARCHIVE: %s_done::
13415 This line sets the archive location for the agenda file.  It applies for
13416 all subsequent lines until the next @samp{#+ARCHIVE} line, or the end
13417 of the file.  The first such line also applies to any entries before it.
13418 The corresponding variable is @code{org-archive-location}.
13419 @item #+CATEGORY:
13420 This line sets the category for the agenda file.  The category applies
13421 for all subsequent lines until the next @samp{#+CATEGORY} line, or the
13422 end of the file.  The first such line also applies to any entries before it.
13423 @item #+COLUMNS: %25ITEM .....
13424 @cindex property, COLUMNS
13425 Set the default format for columns view.  This format applies when
13426 columns view is invoked in locations where no @code{COLUMNS} property
13427 applies.
13428 @item #+CONSTANTS: name1=value1 ...
13429 @vindex org-table-formula-constants
13430 @vindex org-table-formula
13431 Set file-local values for constants to be used in table formulas.  This
13432 line sets the local variable @code{org-table-formula-constants-local}.
13433 The global version of this variable is
13434 @code{org-table-formula-constants}.
13435 @item #+FILETAGS: :tag1:tag2:tag3:
13436 Set tags that can be inherited by any entry in the file, including the
13437 top-level entries.
13438 @item #+DRAWERS: NAME1 .....
13439 @vindex org-drawers
13440 Set the file-local set of drawers.  The corresponding global variable is
13441 @code{org-drawers}.
13442 @item #+LINK:  linkword replace
13443 @vindex org-link-abbrev-alist
13444 These lines (several are allowed) specify link abbreviations.
13445 @xref{Link abbreviations}.  The corresponding variable is
13446 @code{org-link-abbrev-alist}.
13447 @item #+PRIORITIES: highest lowest default
13448 @vindex org-highest-priority
13449 @vindex org-lowest-priority
13450 @vindex org-default-priority
13451 This line sets the limits and the default for the priorities.  All three
13452 must be either letters A-Z or numbers 0-9.  The highest priority must
13453 have a lower ASCII number than the lowest priority.
13454 @item #+PROPERTY: Property_Name Value
13455 This line sets a default inheritance value for entries in the current
13456 buffer, most useful for specifying the allowed values of a property.
13457 @cindex #+SETUPFILE
13458 @item #+SETUPFILE: file
13459 This line defines a file that holds more in-buffer setup.  Normally this is
13460 entirely ignored.  Only when the buffer is parsed for option-setting lines
13461 (i.e.@: when starting Org-mode for a file, when pressing @kbd{C-c C-c} in a
13462 settings line, or when exporting), then the contents of this file are parsed
13463 as if they had been included in the buffer.  In particular, the file can be
13464 any other Org-mode file with internal setup.  You can visit the file the
13465 cursor is in the line with @kbd{C-c '}.
13466 @item #+STARTUP:
13467 @cindex #+STARTUP:
13468 This line sets options to be used at startup of Org-mode, when an
13469 Org file is being visited.
13471 The first set of options deals with the initial visibility of the outline
13472 tree.  The corresponding variable for global default settings is
13473 @code{org-startup-folded}, with a default value @code{t}, which means
13474 @code{overview}.
13475 @vindex org-startup-folded
13476 @cindex @code{overview}, STARTUP keyword
13477 @cindex @code{content}, STARTUP keyword
13478 @cindex @code{showall}, STARTUP keyword
13479 @cindex @code{showeverything}, STARTUP keyword
13480 @example
13481 overview         @r{top-level headlines only}
13482 content          @r{all headlines}
13483 showall          @r{no folding of any entries}
13484 showeverything   @r{show even drawer contents}
13485 @end example
13487 @vindex org-startup-indented
13488 @cindex @code{indent}, STARTUP keyword
13489 @cindex @code{noindent}, STARTUP keyword
13490 Dynamic virtual indentation is controlled by the variable
13491 @code{org-startup-indented}@footnote{Emacs 23 and Org-mode 6.29 are required}
13492 @example
13493 indent     @r{start with @code{org-indent-mode} turned on}
13494 noindent   @r{start with @code{org-indent-mode} turned off}
13495 @end example
13497 @vindex org-startup-align-all-tables
13498 Then there are options for aligning tables upon visiting a file.  This
13499 is useful in files containing narrowed table columns.  The corresponding
13500 variable is @code{org-startup-align-all-tables}, with a default value
13501 @code{nil}.
13502 @cindex @code{align}, STARTUP keyword
13503 @cindex @code{noalign}, STARTUP keyword
13504 @example
13505 align      @r{align all tables}
13506 noalign    @r{don't align tables on startup}
13507 @end example
13509 @vindex org-startup-with-inline-images
13510 When visiting a file, inline images can be automatically displayed.  The
13511 corresponding variable is @code{org-startup-with-inline-images}, with a
13512 default value @code{nil} to avoid delays when visiting a file.
13513 @cindex @code{inlineimages}, STARTUP keyword
13514 @cindex @code{noinlineimages}, STARTUP keyword
13515 @example
13516 inlineimages   @r{show inline images}
13517 noinlineimages @r{don't show inline images on startup}
13518 @end example
13520 @vindex org-log-done
13521 @vindex org-log-note-clock-out
13522 @vindex org-log-repeat
13523 Logging the closing and reopening of TODO items and clock intervals can be
13524 configured using these options (see variables @code{org-log-done},
13525 @code{org-log-note-clock-out} and @code{org-log-repeat})
13526 @cindex @code{logdone}, STARTUP keyword
13527 @cindex @code{lognotedone}, STARTUP keyword
13528 @cindex @code{nologdone}, STARTUP keyword
13529 @cindex @code{lognoteclock-out}, STARTUP keyword
13530 @cindex @code{nolognoteclock-out}, STARTUP keyword
13531 @cindex @code{logrepeat}, STARTUP keyword
13532 @cindex @code{lognoterepeat}, STARTUP keyword
13533 @cindex @code{nologrepeat}, STARTUP keyword
13534 @cindex @code{logreschedule}, STARTUP keyword
13535 @cindex @code{lognotereschedule}, STARTUP keyword
13536 @cindex @code{nologreschedule}, STARTUP keyword
13537 @cindex @code{logredeadline}, STARTUP keyword
13538 @cindex @code{lognoteredeadline}, STARTUP keyword
13539 @cindex @code{nologredeadline}, STARTUP keyword
13540 @cindex @code{logrefile}, STARTUP keyword
13541 @cindex @code{lognoterefile}, STARTUP keyword
13542 @cindex @code{nologrefile}, STARTUP keyword
13543 @example
13544 logdone            @r{record a timestamp when an item is marked DONE}
13545 lognotedone        @r{record timestamp and a note when DONE}
13546 nologdone          @r{don't record when items are marked DONE}
13547 logrepeat          @r{record a time when reinstating a repeating item}
13548 lognoterepeat      @r{record a note when reinstating a repeating item}
13549 nologrepeat        @r{do not record when reinstating repeating item}
13550 lognoteclock-out   @r{record a note when clocking out}
13551 nolognoteclock-out @r{don't record a note when clocking out}
13552 logreschedule      @r{record a timestamp when scheduling time changes}
13553 lognotereschedule  @r{record a note when scheduling time changes}
13554 nologreschedule    @r{do not record when a scheduling date changes}
13555 logredeadline      @r{record a timestamp when deadline changes}
13556 lognoteredeadline  @r{record a note when deadline changes}
13557 nologredeadline    @r{do not record when a deadline date changes}
13558 logrefile          @r{record a timestamp when refiling}
13559 lognoterefile      @r{record a note when refiling}
13560 nologrefile        @r{do not record when refiling}
13561 @end example
13562 @vindex org-hide-leading-stars
13563 @vindex org-odd-levels-only
13564 Here are the options for hiding leading stars in outline headings, and for
13565 indenting outlines.  The corresponding variables are
13566 @code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a
13567 default setting @code{nil} (meaning @code{showstars} and @code{oddeven}).
13568 @cindex @code{hidestars}, STARTUP keyword
13569 @cindex @code{showstars}, STARTUP keyword
13570 @cindex @code{odd}, STARTUP keyword
13571 @cindex @code{even}, STARTUP keyword
13572 @example
13573 hidestars  @r{make all but one of the stars starting a headline invisible.}
13574 showstars  @r{show all stars starting a headline}
13575 indent     @r{virtual indentation according to outline level}
13576 noindent   @r{no virtual indentation according to outline level}
13577 odd        @r{allow only odd outline levels (1,3,...)}
13578 oddeven    @r{allow all outline levels}
13579 @end example
13580 @vindex org-put-time-stamp-overlays
13581 @vindex org-time-stamp-overlay-formats
13582 To turn on custom format overlays over timestamps (variables
13583 @code{org-put-time-stamp-overlays} and
13584 @code{org-time-stamp-overlay-formats}), use
13585 @cindex @code{customtime}, STARTUP keyword
13586 @example
13587 customtime @r{overlay custom time format}
13588 @end example
13589 @vindex constants-unit-system
13590 The following options influence the table spreadsheet (variable
13591 @code{constants-unit-system}).
13592 @cindex @code{constcgs}, STARTUP keyword
13593 @cindex @code{constSI}, STARTUP keyword
13594 @example
13595 constcgs   @r{@file{constants.el} should use the c-g-s unit system}
13596 constSI    @r{@file{constants.el} should use the SI unit system}
13597 @end example
13598 @vindex org-footnote-define-inline
13599 @vindex org-footnote-auto-label
13600 @vindex org-footnote-auto-adjust
13601 To influence footnote settings, use the following keywords.  The
13602 corresponding variables are @code{org-footnote-define-inline},
13603 @code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.
13604 @cindex @code{fninline}, STARTUP keyword
13605 @cindex @code{nofninline}, STARTUP keyword
13606 @cindex @code{fnlocal}, STARTUP keyword
13607 @cindex @code{fnprompt}, STARTUP keyword
13608 @cindex @code{fnauto}, STARTUP keyword
13609 @cindex @code{fnconfirm}, STARTUP keyword
13610 @cindex @code{fnplain}, STARTUP keyword
13611 @cindex @code{fnadjust}, STARTUP keyword
13612 @cindex @code{nofnadjust}, STARTUP keyword
13613 @example
13614 fninline    @r{define footnotes inline}
13615 fnnoinline  @r{define footnotes in separate section}
13616 fnlocal     @r{define footnotes near first reference, but not inline}
13617 fnprompt    @r{prompt for footnote labels}
13618 fnauto      @r{create @code{[fn:1]}-like labels automatically (default)}
13619 fnconfirm   @r{offer automatic label for editing or confirmation}
13620 fnplain     @r{create @code{[1]}-like labels automatically}
13621 fnadjust    @r{automatically renumber and sort footnotes}
13622 nofnadjust  @r{do not renumber and sort automatically}
13623 @end example
13624 @cindex org-hide-block-startup
13625 To hide blocks on startup, use these keywords.  The corresponding variable is
13626 @code{org-hide-block-startup}.
13627 @cindex @code{hideblocks}, STARTUP keyword
13628 @cindex @code{nohideblocks}, STARTUP keyword
13629 @example
13630 hideblocks   @r{Hide all begin/end blocks on startup}
13631 nohideblocks @r{Do not hide blocks on startup}
13632 @end example
13633 @cindex org-pretty-entities
13634 The display of entities as UTF-8 characters is governed by the variable
13635 @code{org-pretty-entities} and the keywords
13636 @cindex @code{entitiespretty}, STARTUP keyword
13637 @cindex @code{entitiesplain}, STARTUP keyword
13638 @example
13639 entitiespretty  @r{Show entities as UTF-8 characters where possible}
13640 entitiesplain   @r{Leave entities plain}
13641 @end example
13642 @item #+TAGS:  TAG1(c1) TAG2(c2)
13643 @vindex org-tag-alist
13644 These lines (several such lines are allowed) specify the valid tags in
13645 this file, and (potentially) the corresponding @emph{fast tag selection}
13646 keys.  The corresponding variable is @code{org-tag-alist}.
13647 @item #+TBLFM:
13648 This line contains the formulas for the table directly above the line.
13649 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,
13650 @itemx #+OPTIONS:, #+BIND:, #+XSLT:,
13651 @itemx #+DESCRIPTION:, #+KEYWORDS:,
13652 @itemx #+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,
13653 @itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:
13654 These lines provide settings for exporting files.  For more details see
13655 @ref{Export options}.
13656 @item #+TODO:    #+SEQ_TODO:   #+TYP_TODO:
13657 @vindex org-todo-keywords
13658 These lines set the TODO keywords and their interpretation in the
13659 current file.  The corresponding variable is @code{org-todo-keywords}.
13660 @end table
13662 @node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
13663 @section The very busy C-c C-c key
13664 @kindex C-c C-c
13665 @cindex C-c C-c, overview
13667 The key @kbd{C-c C-c} has many purposes in Org, which are all
13668 mentioned scattered throughout this manual.  One specific function of
13669 this key is to add @emph{tags} to a headline (@pxref{Tags}).  In many
13670 other circumstances it means something like @emph{``Hey Org, look
13671 here and update according to what you see here''}.  Here is a summary of
13672 what this means in different contexts.
13674 @itemize @minus
13675 @item
13676 If there are highlights in the buffer from the creation of a sparse
13677 tree, or from clock display, remove these highlights.
13678 @item
13679 If the cursor is in one of the special @code{#+KEYWORD} lines, this
13680 triggers scanning the buffer for these lines and updating the
13681 information.
13682 @item
13683 If the cursor is inside a table, realign the table.  This command
13684 works even if the automatic table editor has been turned off.
13685 @item
13686 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
13687 the entire table.
13688 @item
13689 If the current buffer is a capture buffer, close the note and file it.
13690 With a prefix argument, file it, without further interaction, to the
13691 default location.
13692 @item
13693 If the cursor is on a @code{<<<target>>>}, update radio targets and
13694 corresponding links in this buffer.
13695 @item
13696 If the cursor is in a property line or at the start or end of a property
13697 drawer, offer property commands.
13698 @item
13699 If the cursor is at a footnote reference, go to the corresponding
13700 definition, and vice versa.
13701 @item
13702 If the cursor is on a statistics cookie, update it.
13703 @item
13704 If the cursor is in a plain list item with a checkbox, toggle the status
13705 of the checkbox.
13706 @item
13707 If the cursor is on a numbered item in a plain list, renumber the
13708 ordered list.
13709 @item
13710 If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
13711 block is updated.
13712 @end itemize
13714 @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
13715 @section A cleaner outline view
13716 @cindex hiding leading stars
13717 @cindex dynamic indentation
13718 @cindex odd-levels-only outlines
13719 @cindex clean outline view
13721 Some people find it noisy and distracting that the Org headlines start with a
13722 potentially large number of stars, and that text below the headlines is not
13723 indented.  While this is no problem when writing a @emph{book-like} document
13724 where the outline headings are really section headings, in a more
13725 @emph{list-oriented} outline, indented structure is a lot cleaner:
13727 @example
13728 @group
13729 * Top level headline             |    * Top level headline
13730 ** Second level                  |      * Second level
13731 *** 3rd level                    |        * 3rd level
13732 some text                        |          some text
13733 *** 3rd level                    |        * 3rd level
13734 more text                        |          more text
13735 * Another top level headline     |    * Another top level headline
13736 @end group
13737 @end example
13739 @noindent
13741 If you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crash
13742 with @code{org-indent-mode}} and version 6.29 of Org, this kind of view can
13743 be achieved dynamically at display time using @code{org-indent-mode}.  In
13744 this minor mode, all lines are prefixed for display with the necessary amount
13745 of space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix}
13746 property, such that @code{visual-line-mode} (or purely setting
13747 @code{word-wrap}) wraps long lines (including headlines) correctly indented.
13748 }.  Also headlines are prefixed with additional stars, so that the amount of
13749 indentation shifts by two@footnote{See the variable
13750 @code{org-indent-indentation-per-level}.}  spaces per level.  All headline
13751 stars but the last one are made invisible using the @code{org-hide}
13752 face@footnote{Turning on @code{org-indent-mode} sets
13753 @code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
13754 @code{nil}.} - see below under @samp{2.} for more information on how this
13755 works.  You can turn on @code{org-indent-mode} for all files by customizing
13756 the variable @code{org-startup-indented}, or you can turn it on for
13757 individual files using
13759 @example
13760 #+STARTUP: indent
13761 @end example
13763 If you want a similar effect in an earlier version of Emacs and/or Org, or if
13764 you want the indentation to be hard space characters so that the plain text
13765 file looks as similar as possible to the Emacs display, Org supports you in
13766 the following way:
13768 @enumerate
13769 @item
13770 @emph{Indentation of text below headlines}@*
13771 You may indent text below each headline to make the left boundary line up
13772 with the headline, like
13774 @example
13775 *** 3rd level
13776     more text, now indented
13777 @end example
13779 @vindex org-adapt-indentation
13780 Org supports this with paragraph filling, line wrapping, and structure
13781 editing@footnote{See also the variable @code{org-adapt-indentation}.},
13782 preserving or adapting the indentation as appropriate.
13784 @item
13785 @vindex org-hide-leading-stars
13786 @emph{Hiding leading stars}@* You can modify the display in such a way that
13787 all leading stars become invisible.  To do this in a global way, configure
13788 the variable @code{org-hide-leading-stars} or change this on a per-file basis
13789 with
13791 @example
13792 #+STARTUP: hidestars
13793 #+STARTUP: showstars
13794 @end example
13796 With hidden stars, the tree becomes:
13798 @example
13799 @group
13800 * Top level headline
13801  * Second level
13802   * 3rd level
13803   ...
13804 @end group
13805 @end example
13807 @noindent
13808 @vindex org-hide @r{(face)}
13809 The leading stars are not truly replaced by whitespace, they are only
13810 fontified with the face @code{org-hide} that uses the background color as
13811 font color.  If you are not using either white or black background, you may
13812 have to customize this face to get the wanted effect.  Another possibility is
13813 to set this font such that the extra stars are @i{almost} invisible, for
13814 example using the color @code{grey90} on a white background.
13816 @item
13817 @vindex org-odd-levels-only
13818 Things become cleaner still if you skip all the even levels and use only odd
13819 levels 1, 3, 5..., effectively adding two stars to go from one outline level
13820 to the next@footnote{When you need to specify a level for a property search
13821 or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc@.}.  In this
13822 way we get the outline view shown at the beginning of this section.  In order
13823 to make the structure editing and export commands handle this convention
13824 correctly, configure the variable @code{org-odd-levels-only}, or set this on
13825 a per-file basis with one of the following lines:
13827 @example
13828 #+STARTUP: odd
13829 #+STARTUP: oddeven
13830 @end example
13832 You can convert an Org file from single-star-per-level to the
13833 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
13834 RET} in that file.  The reverse operation is @kbd{M-x
13835 org-convert-to-oddeven-levels}.
13836 @end enumerate
13838 @node TTY keys, Interaction, Clean view, Miscellaneous
13839 @section Using Org on a tty
13840 @cindex tty key bindings
13842 Because Org contains a large number of commands, by default many of
13843 Org's core commands are bound to keys that are generally not
13844 accessible on a tty, such as the cursor keys (@key{left}, @key{right},
13845 @key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used
13846 together with modifiers like @key{Meta} and/or @key{Shift}.  To access
13847 these commands on a tty when special keys are unavailable, the following
13848 alternative bindings can be used.  The tty bindings below will likely be
13849 more cumbersome; you may find for some of the bindings below that a
13850 customized workaround suits you better.  For example, changing a timestamp
13851 is really only fun with @kbd{S-@key{cursor}} keys, whereas on a
13852 tty you would rather use @kbd{C-c .} to re-insert the timestamp.
13854 @multitable @columnfractions 0.15 0.2 0.1 0.2
13855 @item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
13856 @item @kbd{S-@key{TAB}}     @tab @kbd{C-u @key{TAB}}       @tab @kbd{C} @tab
13857 @item @kbd{M-@key{left}}    @tab @kbd{C-c C-x l}           @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
13858 @item @kbd{M-S-@key{left}}  @tab @kbd{C-c C-x L}           @tab @kbd{L} @tab
13859 @item @kbd{M-@key{right}}   @tab @kbd{C-c C-x r}           @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
13860 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R}           @tab @kbd{R} @tab
13861 @item @kbd{M-@key{up}}      @tab @kbd{C-c C-x u}           @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
13862 @item @kbd{M-S-@key{up}}    @tab @kbd{C-c C-x U}           @tab @kbd{U} @tab
13863 @item @kbd{M-@key{down}}    @tab @kbd{C-c C-x d}           @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
13864 @item @kbd{M-S-@key{down}}  @tab @kbd{C-c C-x D}           @tab @kbd{D} @tab
13865 @item @kbd{S-@key{RET}}     @tab @kbd{C-c C-x c}           @tab @kbd{ } @tab
13866 @item @kbd{M-@key{RET}}     @tab @kbd{C-c C-x m}           @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
13867 @item @kbd{M-S-@key{RET}}   @tab @kbd{C-c C-x M}           @tab @kbd{ } @tab
13868 @item @kbd{S-@key{left}}    @tab @kbd{C-c @key{left}}      @tab @kbd{ } @tab
13869 @item @kbd{S-@key{right}}   @tab @kbd{C-c @key{right}}     @tab @kbd{ } @tab
13870 @item @kbd{S-@key{up}}      @tab @kbd{C-c @key{up}}        @tab @kbd{ } @tab
13871 @item @kbd{S-@key{down}}    @tab @kbd{C-c @key{down}}      @tab @kbd{ } @tab
13872 @item @kbd{C-S-@key{left}}  @tab @kbd{C-c C-x @key{left}}  @tab @kbd{ } @tab
13873 @item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab
13874 @end multitable
13877 @node Interaction, org-crypt.el, TTY keys, Miscellaneous
13878 @section Interaction with other packages
13879 @cindex packages, interaction with other
13880 Org lives in the world of GNU Emacs and interacts in various ways
13881 with other code out there.
13883 @menu
13884 * Cooperation::                 Packages Org cooperates with
13885 * Conflicts::                   Packages that lead to conflicts
13886 @end menu
13888 @node Cooperation, Conflicts, Interaction, Interaction
13889 @subsection Packages that Org cooperates with
13891 @table @asis
13892 @cindex @file{calc.el}
13893 @cindex Gillespie, Dave
13894 @item @file{calc.el} by Dave Gillespie
13895 Org uses the Calc package for implementing spreadsheet
13896 functionality in its tables (@pxref{The spreadsheet}).  Org
13897 checks for the availability of Calc by looking for the function
13898 @code{calc-eval} which will have been autoloaded during setup if Calc has
13899 been installed properly.  As of Emacs 22, Calc is part of the Emacs
13900 distribution.  Another possibility for interaction between the two
13901 packages is using Calc for embedded calculations.  @xref{Embedded Mode,
13902 , Embedded Mode, Calc, GNU Emacs Calc Manual}.
13903 @item @file{constants.el} by Carsten Dominik
13904 @cindex @file{constants.el}
13905 @cindex Dominik, Carsten
13906 @vindex org-table-formula-constants
13907 In a table formula (@pxref{The spreadsheet}), it is possible to use
13908 names for natural constants or units.  Instead of defining your own
13909 constants in the variable @code{org-table-formula-constants}, install
13910 the @file{constants} package which defines a large number of constants
13911 and units, and lets you use unit prefixes like @samp{M} for
13912 @samp{Mega}, etc@.  You will need version 2.0 of this package, available
13913 at @url{http://www.astro.uva.nl/~dominik/Tools}.  Org checks for
13914 the function @code{constants-get}, which has to be autoloaded in your
13915 setup.  See the installation instructions in the file
13916 @file{constants.el}.
13917 @item @file{cdlatex.el} by Carsten Dominik
13918 @cindex @file{cdlatex.el}
13919 @cindex Dominik, Carsten
13920 Org-mode can make use of the CDLa@TeX{} package to efficiently enter
13921 @LaTeX{} fragments into Org files.  See @ref{CDLaTeX mode}.
13922 @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
13923 @cindex @file{imenu.el}
13924 Imenu allows menu access to an index of items in a file.  Org-mode
13925 supports Imenu---all you need to do to get the index is the following:
13926 @lisp
13927 (add-hook 'org-mode-hook
13928           (lambda () (imenu-add-to-menubar "Imenu")))
13929 @end lisp
13930 @vindex org-imenu-depth
13931 By default the index is two levels deep---you can modify the depth using
13932 the option @code{org-imenu-depth}.
13933 @item @file{remember.el} by John Wiegley
13934 @cindex @file{remember.el}
13935 @cindex Wiegley, John
13936 Org used to use this package for capture, but no longer does.
13937 @item @file{speedbar.el} by Eric M. Ludlam
13938 @cindex @file{speedbar.el}
13939 @cindex Ludlam, Eric M.
13940 Speedbar is a package that creates a special frame displaying files and
13941 index items in files.  Org-mode supports Speedbar and allows you to
13942 drill into Org files directly from the Speedbar.  It also allows you to
13943 restrict the scope of agenda commands to a file or a subtree by using
13944 the command @kbd{<} in the Speedbar frame.
13945 @cindex @file{table.el}
13946 @item @file{table.el} by Takaaki Ota
13947 @kindex C-c C-c
13948 @cindex table editor, @file{table.el}
13949 @cindex @file{table.el}
13950 @cindex Ota, Takaaki
13952 Complex ASCII tables with automatic line wrapping, column- and row-spanning,
13953 and alignment can be created using the Emacs table package by Takaaki Ota
13954 (@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22).
13955 Org-mode will recognize these tables and export them properly.  Because of
13956 interference with other Org-mode functionality, you unfortunately cannot edit
13957 these tables directly in the buffer.  Instead, you need to use the command
13958 @kbd{C-c '} to edit them, similar to source code snippets.
13960 @table @kbd
13961 @orgcmd{C-c ',org-edit-special}
13962 Edit a @file{table.el} table.  Works when the cursor is in a table.el table.
13964 @orgcmd{C-c ~,org-table-create-with-table.el}
13965 Insert a @file{table.el} table.  If there is already a table at point, this
13966 command converts it between the @file{table.el} format and the Org-mode
13967 format.  See the documentation string of the command
13968 @code{org-convert-table} for the restrictions under which this is
13969 possible.
13970 @end table
13971 @file{table.el} is part of Emacs since Emacs 22.
13972 @item @file{footnote.el} by Steven L. Baur
13973 @cindex @file{footnote.el}
13974 @cindex Baur, Steven L.
13975 Org-mode recognizes numerical footnotes as provided by this package.
13976 However, Org-mode also has its own footnote support (@pxref{Footnotes}),
13977 which makes using @file{footnote.el} unnecessary.
13978 @end table
13980 @node Conflicts,  , Cooperation, Interaction
13981 @subsection Packages that lead to conflicts with Org-mode
13983 @table @asis
13985 @cindex @code{shift-selection-mode}
13986 @vindex org-support-shift-select
13987 In Emacs 23, @code{shift-selection-mode} is on by default, meaning that
13988 cursor motions combined with the shift key should start or enlarge regions.
13989 This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change
13990 timestamps, TODO keywords, priorities, and item bullet types if the cursor is
13991 at such a location.  By default, @kbd{S-@key{cursor}} commands outside
13992 special contexts don't do anything, but you can customize the variable
13993 @code{org-support-shift-select}.  Org-mode then tries to accommodate shift
13994 selection by (i) using it outside of the special contexts where special
13995 commands apply, and by (ii) extending an existing active region even if the
13996 cursor moves across a special context.
13998 @item @file{CUA.el} by Kim. F. Storm
13999 @cindex @file{CUA.el}
14000 @cindex Storm, Kim. F.
14001 @vindex org-replace-disputed-keys
14002 Key bindings in Org conflict with the @kbd{S-<cursor>} keys used by CUA mode
14003 (as well as @code{pc-select-mode} and @code{s-region-mode}) to select and extend the
14004 region.  In fact, Emacs 23 has this built-in in the form of
14005 @code{shift-selection-mode}, see previous paragraph.  If you are using Emacs
14006 23, you probably don't want to use another package for this purpose.  However,
14007 if you prefer to leave these keys to a different package while working in
14008 Org-mode, configure the variable @code{org-replace-disputed-keys}.  When set,
14009 Org will move the following key bindings in Org files, and in the agenda
14010 buffer (but not during date selection).
14012 @example
14013 S-UP      @result{}  M-p             S-DOWN     @result{}  M-n
14014 S-LEFT    @result{}  M--             S-RIGHT    @result{}  M-+
14015 C-S-LEFT  @result{}  M-S--           C-S-RIGHT  @result{}  M-S-+
14016 @end example
14018 @vindex org-disputed-keys
14019 Yes, these are unfortunately more difficult to remember.  If you want
14020 to have other replacement keys, look at the variable
14021 @code{org-disputed-keys}.
14023 @item @file{yasnippet.el}
14024 @cindex @file{yasnippet.el}
14025 The way Org mode binds the TAB key (binding to @code{[tab]} instead of
14026 @code{"\t"}) overrules YASnippet's access to this key.  The following code
14027 fixed this problem:
14029 @lisp
14030 (add-hook 'org-mode-hook
14031           (lambda ()
14032             (org-set-local 'yas/trigger-key [tab])
14033             (define-key yas/keymap [tab] 'yas/next-field-group)))
14034 @end lisp
14036 The latest version of yasnippet doesn't play well with Org mode.  If the
14037 above code does not fix the conflict, start by defining the following
14038 function:
14040 @lisp
14041 (defun yas/org-very-safe-expand ()
14042        (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
14043 @end lisp
14045 Then, tell Org mode what to do with the new function:
14047 @lisp
14048 (add-hook 'org-mode-hook
14049           (lambda ()
14050               (make-variable-buffer-local 'yas/trigger-key)
14051               (setq yas/trigger-key [tab])
14052               (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
14053               (define-key yas/keymap [tab] 'yas/next-field)))
14054 @end lisp
14056 @item @file{windmove.el} by Hovav Shacham
14057 @cindex @file{windmove.el}
14058 This package also uses the @kbd{S-<cursor>} keys, so everything written
14059 in the paragraph above about CUA mode also applies here.  If you want make
14060 the windmove function active in locations where Org-mode does not have
14061 special functionality on @kbd{S-@key{cursor}}, add this to your
14062 configuration:
14064 @lisp
14065 ;; Make windmove work in org-mode:
14066 (add-hook 'org-shiftup-final-hook 'windmove-up)
14067 (add-hook 'org-shiftleft-final-hook 'windmove-left)
14068 (add-hook 'org-shiftdown-final-hook 'windmove-down)
14069 (add-hook 'org-shiftright-final-hook 'windmove-right)
14070 @end lisp
14072 @item @file{viper.el} by Michael Kifer
14073 @cindex @file{viper.el}
14074 @kindex C-c /
14075 Viper uses @kbd{C-c /} and therefore makes this key not access the
14076 corresponding Org-mode command @code{org-sparse-tree}.  You need to find
14077 another key for this command, or override the key in
14078 @code{viper-vi-global-user-map} with
14080 @lisp
14081 (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
14082 @end lisp
14084 @end table
14086 @node org-crypt.el,  , Interaction, Miscellaneous
14087 @section org-crypt.el
14088 @cindex @file{org-crypt.el}
14089 @cindex @code{org-decrypt-entry}
14091 Org-crypt will encrypt the text of an entry, but not the headline, or
14092 properties.  Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
14093 files.
14095 Any text below a headline that has a @samp{:crypt:} tag will be automatically
14096 be encrypted when the file is saved.  If you want to use a different tag just
14097 customize the @code{org-crypt-tag-matcher} setting.
14099 To use org-crypt it is suggested that you have the following in your
14100 @file{.emacs}:
14102 @example
14103 (require 'org-crypt)
14104 (org-crypt-use-before-save-magic)
14105 (setq org-tags-exclude-from-inheritance (quote ("crypt")))
14107 (setq org-crypt-key nil)
14108   ;; GPG key to use for encryption
14109   ;; Either the Key ID or set to nil to use symmetric encryption.
14111 (setq auto-save-default nil)
14112   ;; Auto-saving does not cooperate with org-crypt.el: so you need
14113   ;; to turn it off if you plan to use org-crypt.el quite often.
14114   ;; Otherwise, you'll get an (annoying) message each time you 
14115   ;; start Org.
14117   ;; To turn it off only locally, you can insert this:
14118   ;;
14119   ;; # -*- buffer-auto-save-file-name: nil; -*-
14120 @end example
14122 Excluding the crypt tag from inheritance prevents already encrypted text
14123 being encrypted again.
14125 @node Hacking, MobileOrg, Miscellaneous, Top
14126 @appendix Hacking
14127 @cindex hacking
14129 This appendix covers some aspects where users can extend the functionality of
14130 Org.
14132 @menu
14133 * Hooks::                       Who to reach into Org's internals
14134 * Add-on packages::             Available extensions
14135 * Adding hyperlink types::      New custom link types
14136 * Context-sensitive commands::  How to add functionality to such commands
14137 * Tables in arbitrary syntax::  Orgtbl for @LaTeX{} and other programs
14138 * Dynamic blocks::              Automatically filled blocks
14139 * Special agenda views::        Customized views
14140 * Extracting agenda information::  Postprocessing of agenda information
14141 * Using the property API::      Writing programs that use entry properties
14142 * Using the mapping API::       Mapping over all or selected entries
14143 @end menu
14145 @node Hooks, Add-on packages, Hacking, Hacking
14146 @section Hooks
14147 @cindex hooks
14149 Org has a large number of hook variables that can be used to add
14150 functionality.  This appendix about hacking is going to illustrate the
14151 use of some of them.  A complete list of all hooks with documentation is
14152 maintained by the Worg project and can be found at
14153 @uref{http://orgmode.org/worg/org-configs/org-hooks.php}.
14155 @node Add-on packages, Adding hyperlink types, Hooks, Hacking
14156 @section Add-on packages
14157 @cindex add-on packages
14159 A large number of add-on packages have been written by various authors.
14160 These packages are not part of Emacs, but they are distributed as contributed
14161 packages with the separate release available at the Org-mode home page at
14162 @uref{http://orgmode.org}.  The list of contributed packages, along with
14163 documentation about each package, is maintained by the Worg project at
14164 @uref{http://orgmode.org/worg/org-contrib/}.
14168 @node Adding hyperlink types, Context-sensitive commands, Add-on packages, Hacking
14169 @section Adding hyperlink types
14170 @cindex hyperlinks, adding new types
14172 Org has a large number of hyperlink types built-in
14173 (@pxref{Hyperlinks}).  If you would like to add new link types, Org
14174 provides an interface for doing so.  Let's look at an example file,
14175 @file{org-man.el}, that will add support for creating links like
14176 @samp{[[man:printf][The printf manpage]]} to show Unix manual pages inside
14177 Emacs:
14179 @lisp
14180 ;;; org-man.el - Support for links to manpages in Org
14182 (require 'org)
14184 (org-add-link-type "man" 'org-man-open)
14185 (add-hook 'org-store-link-functions 'org-man-store-link)
14187 (defcustom org-man-command 'man
14188   "The Emacs command to be used to display a man page."
14189   :group 'org-link
14190   :type '(choice (const man) (const woman)))
14192 (defun org-man-open (path)
14193   "Visit the manpage on PATH.
14194 PATH should be a topic that can be thrown at the man command."
14195   (funcall org-man-command path))
14197 (defun org-man-store-link ()
14198   "Store a link to a manpage."
14199   (when (memq major-mode '(Man-mode woman-mode))
14200     ;; This is a man page, we do make this link
14201     (let* ((page (org-man-get-page-name))
14202            (link (concat "man:" page))
14203            (description (format "Manpage for %s" page)))
14204       (org-store-link-props
14205        :type "man"
14206        :link link
14207        :description description))))
14209 (defun org-man-get-page-name ()
14210   "Extract the page name from the buffer name."
14211   ;; This works for both `Man-mode' and `woman-mode'.
14212   (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
14213       (match-string 1 (buffer-name))
14214     (error "Cannot create link to this man page")))
14216 (provide 'org-man)
14218 ;;; org-man.el ends here
14219 @end lisp
14221 @noindent
14222 You would activate this new link type in @file{.emacs} with
14224 @lisp
14225 (require 'org-man)
14226 @end lisp
14228 @noindent
14229 Let's go through the file and see what it does.
14230 @enumerate
14231 @item
14232 It does @code{(require 'org)} to make sure that @file{org.el} has been
14233 loaded.
14234 @item
14235 The next line calls @code{org-add-link-type} to define a new link type
14236 with prefix @samp{man}.  The call also contains the name of a function
14237 that will be called to follow such a link.
14238 @item
14239 @vindex org-store-link-functions
14240 The next line adds a function to @code{org-store-link-functions}, in
14241 order to allow the command @kbd{C-c l} to record a useful link in a
14242 buffer displaying a man page.
14243 @end enumerate
14245 The rest of the file defines the necessary variables and functions.
14246 First there is a customization variable that determines which Emacs
14247 command should be used to display man pages.  There are two options,
14248 @code{man} and @code{woman}.  Then the function to follow a link is
14249 defined.  It gets the link path as an argument---in this case the link
14250 path is just a topic for the manual command.  The function calls the
14251 value of @code{org-man-command} to display the man page.
14253 Finally the function @code{org-man-store-link} is defined.  When you try
14254 to store a link with @kbd{C-c l}, this function will be called to
14255 try to make a link.  The function must first decide if it is supposed to
14256 create the link for this buffer type; we do this by checking the value
14257 of the variable @code{major-mode}.  If not, the function must exit and
14258 return the value @code{nil}.  If yes, the link is created by getting the
14259 manual topic from the buffer name and prefixing it with the string
14260 @samp{man:}.  Then it must call the command @code{org-store-link-props}
14261 and set the @code{:type} and @code{:link} properties.  Optionally you
14262 can also set the @code{:description} property to provide a default for
14263 the link description when the link is later inserted into an Org
14264 buffer with @kbd{C-c C-l}.
14266 When it makes sense for your new link type, you may also define a function
14267 @code{org-PREFIX-complete-link} that implements special (e.g.@: completion)
14268 support for inserting such a link with @kbd{C-c C-l}.  Such a function should
14269 not accept any arguments, and return the full link with prefix.
14271 @node Context-sensitive commands, Tables in arbitrary syntax, Adding hyperlink types, Hacking
14272 @section Context-sensitive commands
14273 @cindex context-sensitive commands, hooks
14274 @cindex add-ons, context-sensitive commands
14275 @vindex org-ctrl-c-ctrl-c-hook
14277 Org has several commands that act differently depending on context.  The most
14278 important example it the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).
14279 Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property.
14281 Add-ons can tap into this functionality by providing a function that detects
14282 special context for that add-on and executes functionality appropriate for
14283 the context.  Here is an example from Dan Davison's @file{org-R.el} which
14284 allows you to evaluate commands based on the @file{R} programming language
14285 @footnote{@file{org-R.el} has been replaced by the org-mode functionality
14286 described in @ref{Working With Source Code} and is now obsolete.}.  For this
14287 package, special contexts are lines that start with @code{#+R:} or
14288 @code{#+RR:}.
14290 @lisp
14291 (defun org-R-apply-maybe ()
14292   "Detect if this is context for org-R and execute R commands."
14293   (if (save-excursion
14294         (beginning-of-line 1)
14295         (looking-at "#\\+RR?:"))
14296       (progn (call-interactively 'org-R-apply)
14297              t) ;; to signal that we took action
14298     nil)) ;; to signal that we did not
14300 (add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe)
14301 @end lisp
14303 The function first checks if the cursor is in such a line.  If that is the
14304 case, @code{org-R-apply} is called and the function returns @code{t} to
14305 signal that action was taken, and @kbd{C-c C-c} will stop looking for other
14306 contexts.  If the function finds it should do nothing locally, it returns
14307 @code{nil} so that other, similar functions can have a try.
14310 @node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking
14311 @section Tables and lists in arbitrary syntax
14312 @cindex tables, in other modes
14313 @cindex lists, in other modes
14314 @cindex Orgtbl mode
14316 Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a
14317 frequent feature request has been to make it work with native tables in
14318 specific languages, for example @LaTeX{}.  However, this is extremely
14319 hard to do in a general way, would lead to a customization nightmare,
14320 and would take away much of the simplicity of the Orgtbl mode table
14321 editor.
14323 This appendix describes a different approach.  We keep the Orgtbl mode
14324 table in its native format (the @i{source table}), and use a custom
14325 function to @i{translate} the table to the correct syntax, and to
14326 @i{install} it in the right location (the @i{target table}).  This puts
14327 the burden of writing conversion functions on the user, but it allows
14328 for a very flexible system.
14330 Bastien added the ability to do the same with lists, in Orgstruct mode.  You
14331 can use Org's facilities to edit and structure lists by turning
14332 @code{orgstruct-mode} on, then locally exporting such lists in another format
14333 (HTML, @LaTeX{} or Texinfo.)
14336 @menu
14337 * Radio tables::                Sending and receiving radio tables
14338 * A LaTeX example::             Step by step, almost a tutorial
14339 * Translator functions::        Copy and modify
14340 * Radio lists::                 Doing the same for lists
14341 @end menu
14343 @node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax
14344 @subsection Radio tables
14345 @cindex radio tables
14347 To define the location of the target table, you first need to create two
14348 lines that are comments in the current mode, but contain magic words for
14349 Orgtbl mode to find.  Orgtbl mode will insert the translated table
14350 between these lines, replacing whatever was there before.  For example:
14352 @example
14353 /* BEGIN RECEIVE ORGTBL table_name */
14354 /* END RECEIVE ORGTBL table_name */
14355 @end example
14357 @noindent
14358 Just above the source table, we put a special line that tells
14359 Orgtbl mode how to translate this table and where to install it.  For
14360 example:
14361 @cindex #+ORGTBL
14362 @example
14363 #+ORGTBL: SEND table_name translation_function arguments....
14364 @end example
14366 @noindent
14367 @code{table_name} is the reference name for the table that is also used
14368 in the receiver lines.  @code{translation_function} is the Lisp function
14369 that does the translation.  Furthermore, the line can contain a list of
14370 arguments (alternating key and value) at the end.  The arguments will be
14371 passed as a property list to the translation function for
14372 interpretation.  A few standard parameters are already recognized and
14373 acted upon before the translation function is called:
14375 @table @code
14376 @item :skip N
14377 Skip the first N lines of the table.  Hlines do count as separate lines for
14378 this parameter!
14380 @item :skipcols (n1 n2 ...)
14381 List of columns that should be skipped.  If the table has a column with
14382 calculation marks, that column is automatically discarded as well.
14383 Please note that the translator function sees the table @emph{after} the
14384 removal of these columns, the function never knows that there have been
14385 additional columns.
14386 @end table
14388 @noindent
14389 The one problem remaining is how to keep the source table in the buffer
14390 without disturbing the normal workings of the file, for example during
14391 compilation of a C file or processing of a @LaTeX{} file.  There are a
14392 number of different solutions:
14394 @itemize @bullet
14395 @item
14396 The table could be placed in a block comment if that is supported by the
14397 language.  For example, in C mode you could wrap the table between
14398 @samp{/*} and @samp{*/} lines.
14399 @item
14400 Sometimes it is possible to put the table after some kind of @i{END}
14401 statement, for example @samp{\bye} in @TeX{} and @samp{\end@{document@}}
14402 in @LaTeX{}.
14403 @item
14404 You can just comment the table line-by-line whenever you want to process
14405 the file, and uncomment it whenever you need to edit the table.  This
14406 only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment}
14407 makes this comment-toggling very easy, in particular if you bind it to a
14408 key.
14409 @end itemize
14411 @node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax
14412 @subsection A @LaTeX{} example of radio tables
14413 @cindex @LaTeX{}, and Orgtbl mode
14415 The best way to wrap the source table in @LaTeX{} is to use the
14416 @code{comment} environment provided by @file{comment.sty}.  It has to be
14417 activated by placing @code{\usepackage@{comment@}} into the document
14418 header.  Orgtbl mode can insert a radio table skeleton@footnote{By
14419 default this works only for @LaTeX{}, HTML, and Texinfo.  Configure the
14420 variable @code{orgtbl-radio-tables} to install templates for other
14421 modes.}  with the command @kbd{M-x orgtbl-insert-radio-table}.  You will
14422 be prompted for a table name, let's say we use @samp{salesfigures}.  You
14423 will then get the following template:
14425 @cindex #+ORGTBL, SEND
14426 @example
14427 % BEGIN RECEIVE ORGTBL salesfigures
14428 % END RECEIVE ORGTBL salesfigures
14429 \begin@{comment@}
14430 #+ORGTBL: SEND salesfigures orgtbl-to-latex
14431 | | |
14432 \end@{comment@}
14433 @end example
14435 @noindent
14436 @vindex @LaTeX{}-verbatim-environments
14437 The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function
14438 @code{orgtbl-to-latex} to convert the table into @LaTeX{} and to put it
14439 into the receiver location with name @code{salesfigures}.  You may now
14440 fill in the table---feel free to use the spreadsheet features@footnote{If
14441 the @samp{#+TBLFM} line contains an odd number of dollar characters,
14442 this may cause problems with font-lock in @LaTeX{} mode.  As shown in the
14443 example you can fix this by adding an extra line inside the
14444 @code{comment} environment that is used to balance the dollar
14445 expressions.  If you are using AUC@TeX{} with the font-latex library, a
14446 much better solution is to add the @code{comment} environment to the
14447 variable @code{LaTeX-verbatim-environments}.}:
14449 @example
14450 % BEGIN RECEIVE ORGTBL salesfigures
14451 % END RECEIVE ORGTBL salesfigures
14452 \begin@{comment@}
14453 #+ORGTBL: SEND salesfigures orgtbl-to-latex
14454 | Month | Days | Nr sold | per day |
14455 |-------+------+---------+---------|
14456 | Jan   |   23 |      55 |     2.4 |
14457 | Feb   |   21 |      16 |     0.8 |
14458 | March |   22 |     278 |    12.6 |
14459 #+TBLFM: $4=$3/$2;%.1f
14460 % $ (optional extra dollar to keep font-lock happy, see footnote)
14461 \end@{comment@}
14462 @end example
14464 @noindent
14465 When you are done, press @kbd{C-c C-c} in the table to get the converted
14466 table inserted between the two marker lines.
14468 Now let's assume you want to make the table header by hand, because you
14469 want to control how columns are aligned, etc@.  In this case we make sure
14470 that the table translator skips the first 2 lines of the source
14471 table, and tell the command to work as a @i{splice}, i.e.@: to not produce
14472 header and footer commands of the target table:
14474 @example
14475 \begin@{tabular@}@{lrrr@}
14476 Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
14477 % BEGIN RECEIVE ORGTBL salesfigures
14478 % END RECEIVE ORGTBL salesfigures
14479 \end@{tabular@}
14481 \begin@{comment@}
14482 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
14483 | Month | Days | Nr sold | per day |
14484 |-------+------+---------+---------|
14485 | Jan   |   23 |      55 |     2.4 |
14486 | Feb   |   21 |      16 |     0.8 |
14487 | March |   22 |     278 |    12.6 |
14488 #+TBLFM: $4=$3/$2;%.1f
14489 \end@{comment@}
14490 @end example
14492 The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
14493 Orgtbl mode.  It uses a @code{tabular} environment to typeset the table
14494 and marks horizontal lines with @code{\hline}.  Furthermore, it
14495 interprets the following parameters (see also @pxref{Translator functions}):
14497 @table @code
14498 @item :splice nil/t
14499 When set to t, return only table body lines, don't wrap them into a
14500 tabular environment.  Default is nil.
14502 @item :fmt fmt
14503 A format to be used to wrap each field, it should contain @code{%s} for the
14504 original field value.  For example, to wrap each field value in dollars,
14505 you could use @code{:fmt "$%s$"}.  This may also be a property list with
14506 column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
14507 A function of one argument can be used in place of the strings; the
14508 function must return a formatted string.
14510 @item :efmt efmt
14511 Use this format to print numbers with exponentials.  The format should
14512 have @code{%s} twice for inserting mantissa and exponent, for example
14513 @code{"%s\\times10^@{%s@}"}.  The default is @code{"%s\\,(%s)"}.  This
14514 may also be a property list with column numbers and formats, for example
14515 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}.  After
14516 @code{efmt} has been applied to a value, @code{fmt} will also be
14517 applied.  Similar to @code{fmt}, functions of two arguments can be
14518 supplied instead of strings.
14519 @end table
14521 @node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax
14522 @subsection Translator functions
14523 @cindex HTML, and Orgtbl mode
14524 @cindex translator function
14526 Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv}
14527 (comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values)
14528 @code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}.
14529 Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the same
14530 code that produces tables during HTML export.}, these all use a generic
14531 translator, @code{orgtbl-to-generic}.  For example, @code{orgtbl-to-latex}
14532 itself is a very short function that computes the column definitions for the
14533 @code{tabular} environment, defines a few field and line separators and then
14534 hands processing over to the generic translator.  Here is the entire code:
14536 @lisp
14537 @group
14538 (defun orgtbl-to-latex (table params)
14539   "Convert the Orgtbl mode TABLE to LaTeX."
14540   (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
14541                                org-table-last-alignment ""))
14542          (params2
14543           (list
14544            :tstart (concat "\\begin@{tabular@}@{" alignment "@}")
14545            :tend "\\end@{tabular@}"
14546            :lstart "" :lend " \\\\" :sep " & "
14547            :efmt "%s\\,(%s)" :hline "\\hline")))
14548     (orgtbl-to-generic table (org-combine-plists params2 params))))
14549 @end group
14550 @end lisp
14552 As you can see, the properties passed into the function (variable
14553 @var{PARAMS}) are combined with the ones newly defined in the function
14554 (variable @var{PARAMS2}).  The ones passed into the function (i.e.@: the
14555 ones set by the @samp{ORGTBL SEND} line) take precedence.  So if you
14556 would like to use the @LaTeX{} translator, but wanted the line endings to
14557 be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
14558 overrule the default with
14560 @example
14561 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
14562 @end example
14564 For a new language, you can either write your own converter function in
14565 analogy with the @LaTeX{} translator, or you can use the generic function
14566 directly.  For example, if you have a language where a table is started
14567 with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are
14568 started with @samp{!BL!}, ended with @samp{!EL!}, and where the field
14569 separator is a TAB, you could call the generic translator like this (on
14570 a single line!):
14572 @example
14573 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
14574                               :lstart "!BL! " :lend " !EL!" :sep "\t"
14575 @end example
14577 @noindent
14578 Please check the documentation string of the function
14579 @code{orgtbl-to-generic} for a full list of parameters understood by
14580 that function, and remember that you can pass each of them into
14581 @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
14582 using the generic function.
14584 Of course you can also write a completely new function doing complicated
14585 things the generic translator cannot do.  A translator function takes
14586 two arguments.  The first argument is the table, a list of lines, each
14587 line either the symbol @code{hline} or a list of fields.  The second
14588 argument is the property list containing all parameters specified in the
14589 @samp{#+ORGTBL: SEND} line.  The function must return a single string
14590 containing the formatted table.  If you write a generally useful
14591 translator, please post it on @email{emacs-orgmode@@gnu.org} so that
14592 others can benefit from your work.
14594 @node Radio lists,  , Translator functions, Tables in arbitrary syntax
14595 @subsection Radio lists
14596 @cindex radio lists
14597 @cindex org-list-insert-radio-list
14599 Sending and receiving radio lists works exactly the same way as sending and
14600 receiving radio tables (@pxref{Radio tables}).  As for radio tables, you can
14601 insert radio list templates in HTML, @LaTeX{} and Texinfo modes by calling
14602 @code{org-list-insert-radio-list}.
14604 Here are the differences with radio tables:
14606 @itemize @minus
14607 @item
14608 Orgstruct mode must be active.
14609 @item
14610 Use the @code{ORGLST} keyword instead of @code{ORGTBL}.
14611 @item
14612 The available translation functions for radio lists don't take
14613 parameters.
14614 @item
14615 @kbd{C-c C-c} will work when pressed on the first item of the list.
14616 @end itemize
14618 Here is a @LaTeX{} example.  Let's say that you have this in your
14619 @LaTeX{} file:
14621 @cindex #+ORGLST
14622 @example
14623 % BEGIN RECEIVE ORGLST to-buy
14624 % END RECEIVE ORGLST to-buy
14625 \begin@{comment@}
14626 #+ORGLST: SEND to-buy org-list-to-latex
14627 - a new house
14628 - a new computer
14629   + a new keyboard
14630   + a new mouse
14631 - a new life
14632 \end@{comment@}
14633 @end example
14635 Pressing `C-c C-c' on @code{a new house} and will insert the converted
14636 @LaTeX{} list between the two marker lines.
14638 @node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking
14639 @section Dynamic blocks
14640 @cindex dynamic blocks
14642 Org documents can contain @emph{dynamic blocks}.  These are
14643 specially marked regions that are updated by some user-written function.
14644 A good example for such a block is the clock table inserted by the
14645 command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
14647 Dynamic blocks are enclosed by a BEGIN-END structure that assigns a name
14648 to the block and can also specify parameters for the function producing
14649 the content of the block.
14651 @cindex #+BEGIN:dynamic block
14652 @example
14653 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
14655 #+END:
14656 @end example
14658 Dynamic blocks are updated with the following commands
14660 @table @kbd
14661 @orgcmd{C-c C-x C-u,org-dblock-update}
14662 Update dynamic block at point.
14663 @orgkey{C-u C-c C-x C-u}
14664 Update all dynamic blocks in the current file.
14665 @end table
14667 Updating a dynamic block means to remove all the text between BEGIN and
14668 END, parse the BEGIN line for parameters and then call the specific
14669 writer function for this block to insert the new content.  If you want
14670 to use the original content in the writer function, you can use the
14671 extra parameter @code{:content}.
14673 For a block with name @code{myblock}, the writer function is
14674 @code{org-dblock-write:myblock} with as only parameter a property list
14675 with the parameters given in the begin line.  Here is a trivial example
14676 of a block that keeps track of when the block update function was last
14677 run:
14679 @example
14680 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
14682 #+END:
14683 @end example
14685 @noindent
14686 The corresponding block writer function could look like this:
14688 @lisp
14689 (defun org-dblock-write:block-update-time (params)
14690    (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
14691      (insert "Last block update at: "
14692              (format-time-string fmt (current-time)))))
14693 @end lisp
14695 If you want to make sure that all dynamic blocks are always up-to-date,
14696 you could add the function @code{org-update-all-dblocks} to a hook, for
14697 example @code{before-save-hook}.  @code{org-update-all-dblocks} is
14698 written in a way such that it does nothing in buffers that are not in
14699 @code{org-mode}.
14701 You can narrow the current buffer to the current dynamic block (like any
14702 other block) with @code{org-narrow-to-block}.
14704 @node Special agenda views, Extracting agenda information, Dynamic blocks, Hacking
14705 @section Special agenda views
14706 @cindex agenda views, user-defined
14708 @vindex org-agenda-skip-function
14709 @vindex org-agenda-skip-function-global
14710 Org provides a special hook that can be used to narrow down the selection
14711 made by these agenda views: @code{agenda}, @code{todo}, @code{alltodo},
14712 @code{tags}, @code{tags-todo}, @code{tags-tree}.  You may specify a function
14713 that is used at each match to verify if the match should indeed be part of
14714 the agenda view, and if not, how much should be skipped.  You can specify a
14715 global condition that will be applied to all agenda views, this condition
14716 would be stored in the variable @code{org-agenda-skip-function-global}.  More
14717 commonly, such a definition is applied only to specific custom searches,
14718 using @code{org-agenda-skip-function}.
14720 Let's say you want to produce a list of projects that contain a WAITING
14721 tag anywhere in the project tree.  Let's further assume that you have
14722 marked all tree headings that define a project with the TODO keyword
14723 PROJECT.  In this case you would run a TODO search for the keyword
14724 PROJECT, but skip the match unless there is a WAITING tag anywhere in
14725 the subtree belonging to the project line.
14727 To achieve this, you must write a function that searches the subtree for
14728 the tag.  If the tag is found, the function must return @code{nil} to
14729 indicate that this match should not be skipped.  If there is no such
14730 tag, return the location of the end of the subtree, to indicate that
14731 search should continue from there.
14733 @lisp
14734 (defun my-skip-unless-waiting ()
14735   "Skip trees that are not waiting"
14736   (let ((subtree-end (save-excursion (org-end-of-subtree t))))
14737     (if (re-search-forward ":waiting:" subtree-end t)
14738         nil          ; tag found, do not skip
14739       subtree-end))) ; tag not found, continue after end of subtree
14740 @end lisp
14742 Now you may use this function in an agenda custom command, for example
14743 like this:
14745 @lisp
14746 (org-add-agenda-custom-command
14747  '("b" todo "PROJECT"
14748    ((org-agenda-skip-function 'my-skip-unless-waiting)
14749     (org-agenda-overriding-header "Projects waiting for something: "))))
14750 @end lisp
14752 @vindex org-agenda-overriding-header
14753 Note that this also binds @code{org-agenda-overriding-header} to get a
14754 meaningful header in the agenda view.
14756 @vindex org-odd-levels-only
14757 @vindex org-agenda-skip-function
14758 A general way to create custom searches is to base them on a search for
14759 entries with a certain level limit.  If you want to study all entries with
14760 your custom search function, simply do a search for
14761 @samp{LEVEL>0}@footnote{Note that, when using @code{org-odd-levels-only}, a
14762 level number corresponds to order in the hierarchy, not to the number of
14763 stars.}, and then use @code{org-agenda-skip-function} to select the entries
14764 you really want to have.
14766 You may also put a Lisp form into @code{org-agenda-skip-function}.  In
14767 particular, you may use the functions @code{org-agenda-skip-entry-if}
14768 and @code{org-agenda-skip-subtree-if} in this form, for example:
14770 @table @code
14771 @item '(org-agenda-skip-entry-if 'scheduled)
14772 Skip current entry if it has been scheduled.
14773 @item '(org-agenda-skip-entry-if 'notscheduled)
14774 Skip current entry if it has not been scheduled.
14775 @item '(org-agenda-skip-entry-if 'deadline)
14776 Skip current entry if it has a deadline.
14777 @item '(org-agenda-skip-entry-if 'scheduled 'deadline)
14778 Skip current entry if it has a deadline, or if it is scheduled.
14779 @item '(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
14780 Skip current entry if the TODO keyword is TODO or WAITING.
14781 @item '(org-agenda-skip-entry-if 'todo 'done)
14782 Skip current entry if the TODO keyword marks a DONE state.
14783 @item '(org-agenda-skip-entry-if 'timestamp)
14784 Skip current entry if it has any timestamp, may also be deadline or scheduled.
14785 @item '(org-agenda-skip-entry 'regexp "regular expression")
14786 Skip current entry if the regular expression matches in the entry.
14787 @item '(org-agenda-skip-entry 'notregexp "regular expression")
14788 Skip current entry unless the regular expression matches.
14789 @item '(org-agenda-skip-subtree-if 'regexp "regular expression")
14790 Same as above, but check and skip the entire subtree.
14791 @end table
14793 Therefore we could also have written the search for WAITING projects
14794 like this, even without defining a special function:
14796 @lisp
14797 (org-add-agenda-custom-command
14798  '("b" todo "PROJECT"
14799    ((org-agenda-skip-function '(org-agenda-skip-subtree-if
14800                                 'regexp ":waiting:"))
14801     (org-agenda-overriding-header "Projects waiting for something: "))))
14802 @end lisp
14804 @node Extracting agenda information, Using the property API, Special agenda views, Hacking
14805 @section Extracting agenda information
14806 @cindex agenda, pipe
14807 @cindex Scripts, for agenda processing
14809 @vindex org-agenda-custom-commands
14810 Org provides commands to access agenda information for the command
14811 line in Emacs batch mode.  This extracted information can be sent
14812 directly to a printer, or it can be read by a program that does further
14813 processing of the data.  The first of these commands is the function
14814 @code{org-batch-agenda}, that produces an agenda view and sends it as
14815 ASCII text to STDOUT.  The command takes a single string as parameter.
14816 If the string has length 1, it is used as a key to one of the commands
14817 you have configured in @code{org-agenda-custom-commands}, basically any
14818 key you can use after @kbd{C-c a}.  For example, to directly print the
14819 current TODO list, you could use
14821 @example
14822 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
14823 @end example
14825 If the parameter is a string with 2 or more characters, it is used as a
14826 tags/TODO match string.  For example, to print your local shopping list
14827 (all items with the tag @samp{shop}, but excluding the tag
14828 @samp{NewYork}), you could use
14830 @example
14831 emacs -batch -l ~/.emacs                                      \
14832       -eval '(org-batch-agenda "+shop-NewYork")' | lpr
14833 @end example
14835 @noindent
14836 You may also modify parameters on the fly like this:
14838 @example
14839 emacs -batch -l ~/.emacs                                      \
14840    -eval '(org-batch-agenda "a"                               \
14841             org-agenda-span month                             \
14842             org-agenda-include-diary nil                      \
14843             org-agenda-files (quote ("~/org/project.org")))'  \
14844    | lpr
14845 @end example
14847 @noindent
14848 which will produce a 30-day agenda, fully restricted to the Org file
14849 @file{~/org/projects.org}, not even including the diary.
14851 If you want to process the agenda data in more sophisticated ways, you
14852 can use the command @code{org-batch-agenda-csv} to get a comma-separated
14853 list of values for each agenda item.  Each line in the output will
14854 contain a number of fields separated by commas.  The fields in a line
14855 are:
14857 @example
14858 category     @r{The category of the item}
14859 head         @r{The headline, without TODO keyword, TAGS and PRIORITY}
14860 type         @r{The type of the agenda entry, can be}
14861                 todo               @r{selected in TODO match}
14862                 tagsmatch          @r{selected in tags match}
14863                 diary              @r{imported from diary}
14864                 deadline           @r{a deadline}
14865                 scheduled          @r{scheduled}
14866                 timestamp          @r{appointment, selected by timestamp}
14867                 closed             @r{entry was closed on date}
14868                 upcoming-deadline  @r{warning about nearing deadline}
14869                 past-scheduled     @r{forwarded scheduled item}
14870                 block              @r{entry has date block including date}
14871 todo         @r{The TODO keyword, if any}
14872 tags         @r{All tags including inherited ones, separated by colons}
14873 date         @r{The relevant date, like 2007-2-14}
14874 time         @r{The time, like 15:00-16:50}
14875 extra        @r{String with extra planning info}
14876 priority-l   @r{The priority letter if any was given}
14877 priority-n   @r{The computed numerical priority}
14878 @end example
14880 @noindent
14881 Time and date will only be given if a timestamp (or deadline/scheduled)
14882 led to the selection of the item.
14884 A CSV list like this is very easy to use in a post-processing script.
14885 For example, here is a Perl program that gets the TODO list from
14886 Emacs/Org and prints all the items, preceded by a checkbox:
14888 @example
14889 #!/usr/bin/perl
14891 # define the Emacs command to run
14892 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
14894 # run it and capture the output
14895 $agenda = qx@{$cmd 2>/dev/null@};
14897 # loop over all lines
14898 foreach $line (split(/\n/,$agenda)) @{
14899   # get the individual values
14900   ($category,$head,$type,$todo,$tags,$date,$time,$extra,
14901    $priority_l,$priority_n) = split(/,/,$line);
14902   # process and print
14903   print "[ ] $head\n";
14905 @end example
14907 @node Using the property API, Using the mapping API, Extracting agenda information, Hacking
14908 @section Using the property API
14909 @cindex API, for properties
14910 @cindex properties, API
14912 Here is a description of the functions that can be used to work with
14913 properties.
14915 @defun org-entry-properties &optional pom which
14916 Get all properties of the entry at point-or-marker POM.@*
14917 This includes the TODO keyword, the tags, time strings for deadline,
14918 scheduled, and clocking, and any additional properties defined in the
14919 entry.  The return value is an alist.  Keys may occur multiple times
14920 if the property key was used several times.@*
14921 POM may also be nil, in which case the current entry is used.
14922 If WHICH is nil or `all', get all properties.  If WHICH is
14923 `special' or `standard', only get that subclass.
14924 @end defun
14925 @vindex org-use-property-inheritance
14926 @defun org-entry-get pom property &optional inherit
14927 Get value of PROPERTY for entry at point-or-marker POM.  By default,
14928 this only looks at properties defined locally in the entry.  If INHERIT
14929 is non-nil and the entry does not have the property, then also check
14930 higher levels of the hierarchy.  If INHERIT is the symbol
14931 @code{selective}, use inheritance if and only if the setting of
14932 @code{org-use-property-inheritance} selects PROPERTY for inheritance.
14933 @end defun
14935 @defun org-entry-delete pom property
14936 Delete the property PROPERTY from entry at point-or-marker POM.
14937 @end defun
14939 @defun org-entry-put pom property value
14940 Set PROPERTY to VALUE for entry at point-or-marker POM.
14941 @end defun
14943 @defun org-buffer-property-keys &optional include-specials
14944 Get all property keys in the current buffer.
14945 @end defun
14947 @defun org-insert-property-drawer
14948 Insert a property drawer at point.
14949 @end defun
14951 @defun org-entry-put-multivalued-property pom property &rest values
14952 Set PROPERTY at point-or-marker POM to VALUES.  VALUES should be a list of
14953 strings.  They will be concatenated, with spaces as separators.
14954 @end defun
14956 @defun org-entry-get-multivalued-property pom property
14957 Treat the value of the property PROPERTY as a whitespace-separated list of
14958 values and return the values as a list of strings.
14959 @end defun
14961 @defun org-entry-add-to-multivalued-property pom property value
14962 Treat the value of the property PROPERTY as a whitespace-separated list of
14963 values and make sure that VALUE is in this list.
14964 @end defun
14966 @defun org-entry-remove-from-multivalued-property pom property value
14967 Treat the value of the property PROPERTY as a whitespace-separated list of
14968 values and make sure that VALUE is @emph{not} in this list.
14969 @end defun
14971 @defun org-entry-member-in-multivalued-property pom property value
14972 Treat the value of the property PROPERTY as a whitespace-separated list of
14973 values and check if VALUE is in this list.
14974 @end defun
14976 @defopt org-property-allowed-value-functions
14977 Hook for functions supplying allowed values for a specific property.
14978 The functions must take a single argument, the name of the property, and
14979 return a flat list of allowed values.  If @samp{:ETC} is one of
14980 the values, use the values as completion help, but allow also other values
14981 to be entered.  The functions must return @code{nil} if they are not
14982 responsible for this property.
14983 @end defopt
14985 @node Using the mapping API,  , Using the property API, Hacking
14986 @section Using the mapping API
14987 @cindex API, for mapping
14988 @cindex mapping entries, API
14990 Org has sophisticated mapping capabilities to find all entries satisfying
14991 certain criteria.  Internally, this functionality is used to produce agenda
14992 views, but there is also an API that can be used to execute arbitrary
14993 functions for each or selected entries.  The main entry point for this API
14996 @defun org-map-entries func &optional match scope &rest skip
14997 Call FUNC at each headline selected by MATCH in SCOPE.
14999 FUNC is a function or a Lisp form.  The function will be called without
15000 arguments, with the cursor positioned at the beginning of the headline.
15001 The return values of all calls to the function will be collected and
15002 returned as a list.
15004 The call to FUNC will be wrapped into a save-excursion form, so FUNC
15005 does not need to preserve point.  After evaluation, the cursor will be
15006 moved to the end of the line (presumably of the headline of the
15007 processed entry) and search continues from there.  Under some
15008 circumstances, this may not produce the wanted results.  For example,
15009 if you have removed (e.g.@: archived) the current (sub)tree it could
15010 mean that the next entry will be skipped entirely.  In such cases, you
15011 can specify the position from where search should continue by making
15012 FUNC set the variable `org-map-continue-from' to the desired buffer
15013 position.
15015 MATCH is a tags/property/todo match as it is used in the agenda match view.
15016 Only headlines that are matched by this query will be considered during
15017 the iteration.  When MATCH is nil or t, all headlines will be
15018 visited by the iteration.
15020 SCOPE determines the scope of this command.  It can be any of:
15022 @example
15023 nil     @r{the current buffer, respecting the restriction if any}
15024 tree    @r{the subtree started with the entry at point}
15025 file    @r{the current buffer, without restriction}
15026 file-with-archives
15027         @r{the current buffer, and any archives associated with it}
15028 agenda  @r{all agenda files}
15029 agenda-with-archives
15030         @r{all agenda files with any archive files associated with them}
15031 (file1 file2 ...)
15032         @r{if this is a list, all files in the list will be scanned}
15033 @end example
15034 @noindent
15035 The remaining args are treated as settings for the skipping facilities of
15036 the scanner.  The following items can be given here:
15038 @vindex org-agenda-skip-function
15039 @example
15040 archive   @r{skip trees with the archive tag}
15041 comment   @r{skip trees with the COMMENT keyword}
15042 function or Lisp form
15043           @r{will be used as value for @code{org-agenda-skip-function},}
15044           @r{so whenever the function returns t, FUNC}
15045           @r{will not be called for that entry and search will}
15046           @r{continue from the point where the function leaves it}
15047 @end example
15048 @end defun
15050 The function given to that mapping routine can really do anything you like.
15051 It can use the property API (@pxref{Using the property API}) to gather more
15052 information about the entry, or in order to change metadata in the entry.
15053 Here are a couple of functions that might be handy:
15055 @defun org-todo &optional arg
15056 Change the TODO state of the entry.  See the docstring of the functions for
15057 the many possible values for the argument ARG.
15058 @end defun
15060 @defun org-priority &optional action
15061 Change the priority of the entry.  See the docstring of this function for the
15062 possible values for ACTION.
15063 @end defun
15065 @defun org-toggle-tag tag &optional onoff
15066 Toggle the tag TAG in the current entry.  Setting ONOFF to either @code{on}
15067 or @code{off} will not toggle tag, but ensure that it is either on or off.
15068 @end defun
15070 @defun org-promote
15071 Promote the current entry.
15072 @end defun
15074 @defun org-demote
15075 Demote the current entry.
15076 @end defun
15078 Here is a simple example that will turn all entries in the current file with
15079 a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}.
15080 Entries in comment trees and in archive trees will be ignored.
15082 @lisp
15083 (org-map-entries
15084    '(org-todo "UPCOMING")
15085    "+TOMORROW" 'file 'archive 'comment)
15086 @end lisp
15088 The following example counts the number of entries with TODO keyword
15089 @code{WAITING}, in all agenda files.
15091 @lisp
15092 (length (org-map-entries t "/+WAITING" 'agenda))
15093 @end lisp
15095 @node MobileOrg, History and Acknowledgments, Hacking, Top
15096 @appendix MobileOrg
15097 @cindex iPhone
15098 @cindex MobileOrg
15100 @uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the
15101 @i{iPhone/iPod Touch} series of devices, developed by Richard Moreland.
15102 @i{MobileOrg} offers offline viewing and capture support for an Org-mode
15103 system rooted on a ``real'' computer.  It does also allow you to record
15104 changes to existing entries.  Android users should check out
15105 @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}
15106 by Matt Jones.
15108 This appendix describes the support Org has for creating agenda views in a
15109 format that can be displayed by @i{MobileOrg}, and for integrating notes
15110 captured and changes made by @i{MobileOrg} into the main system.
15112 For changing tags and TODO states in MobileOrg, you should have set up the
15113 customization variables @code{org-todo-keywords} and @code{org-tags-alist} to
15114 cover all important tags and TODO keywords, even if individual files use only
15115 part of these.  MobileOrg will also offer you states and tags set up with
15116 in-buffer settings, but it will understand the logistics of TODO state
15117 @i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags
15118 (@pxref{Setting tags}) only for those set in these variables.
15120 @menu
15121 * Setting up the staging area::  Where to interact with the mobile device
15122 * Pushing to MobileOrg::        Uploading Org files and agendas
15123 * Pulling from MobileOrg::      Integrating captured and flagged items
15124 @end menu
15126 @node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg
15127 @section Setting up the staging area
15129 MobileOrg needs to interact with Emacs through a directory on a server.  If you
15130 are using a public server, you should consider to encrypt the files that are
15131 uploaded to the server.  This can be done with Org-mode 7.02 and with
15132 @i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl}
15133 installation on your system.  To turn on encryption, set a password in
15134 @i{MobileOrg} and, on the Emacs side, configure the variable
15135 @code{org-mobile-use-encryption}@footnote{If you can safely store the
15136 password in your Emacs setup, you might also want to configure
15137 @code{org-mobile-encryption-password}.  Please read the docstring of that
15138 variable.  Note that encryption will apply only to the contents of the
15139 @file{.org} files.  The file names themselves will remain visible.}.
15141 The easiest way to create that directory is to use a free
15142 @uref{http://dropbox.com,Dropbox.com} account@footnote{If you cannot use
15143 Dropbox, or if your version of MobileOrg does not support it, you can use a
15144 webdav server.  For more information, check out the documentation of MobileOrg and also this
15145 @uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
15146 When MobileOrg first connects to your Dropbox, it will create a directory
15147 @i{MobileOrg} inside the Dropbox.  After the directory has been created, tell
15148 Emacs about it:
15150 @lisp
15151 (setq org-mobile-directory "~/Dropbox/MobileOrg")
15152 @end lisp
15154 Org-mode has commands to put files for @i{MobileOrg} into that directory,
15155 and to read captured notes from there.
15157 @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
15158 @section Pushing to MobileOrg
15160 This operation copies all files currently listed in @code{org-mobile-files}
15161 to the directory @code{org-mobile-directory}.  By default this list contains
15162 all agenda files (as listed in @code{org-agenda-files}), but additional files
15163 can be included by customizing @code{org-mobile-files}.  File names will be
15164 staged with paths relative to @code{org-directory}, so all files should be
15165 inside this directory.  The push operation also creates a special Org file
15166 @file{agendas.org} with all custom agenda view defined by the
15167 user@footnote{While creating the agendas, Org-mode will force ID properties
15168 on all referenced entries, so that these entries can be uniquely identified
15169 if @i{MobileOrg} flags them for further action.  If you do not want to get
15170 these properties in so many entries, you can set the variable
15171 @code{org-mobile-force-id-on-agenda-items} to @code{nil}.  Org mode will then
15172 rely on outline paths, in the hope that these will be unique enough.}.
15173 Finally, Org writes the file @file{index.org}, containing links to all other
15174 files.  @i{MobileOrg} first reads this file from the server, and then
15175 downloads all agendas and Org files listed in it.  To speed up the download,
15176 MobileOrg will only read files whose checksums@footnote{stored automatically
15177 in the file @file{checksums.dat}} have changed.
15179 @node Pulling from MobileOrg,  , Pushing to MobileOrg, MobileOrg
15180 @section Pulling from MobileOrg
15182 When @i{MobileOrg} synchronizes with the server, it not only pulls the Org
15183 files for viewing.  It also appends captured entries and pointers to flagged
15184 and changed entries to the file @file{mobileorg.org} on the server.  Org has
15185 a @emph{pull} operation that integrates this information into an inbox file
15186 and operates on the pointers to flagged entries.  Here is how it works:
15188 @enumerate
15189 @item
15190 Org moves all entries found in
15191 @file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this
15192 operation.} and appends them to the file pointed to by the variable
15193 @code{org-mobile-inbox-for-pull}.  Each captured entry and each editing event
15194 will be a top-level entry in the inbox file.
15195 @item
15196 After moving the entries, Org will attempt to implement the changes made in
15197 @i{MobileOrg}.  Some changes are applied directly and without user
15198 interaction.  Examples are all changes to tags, TODO state, headline and body
15199 text that can be cleanly applied.  Entries that have been flagged for further
15200 action will receive a tag @code{:FLAGGED:}, so that they can be easily found
15201 again.  When there is a problem finding an entry or applying the change, the
15202 pointer entry will remain in the inbox and will be marked with an error
15203 message.  You need to later resolve these issues by hand.
15204 @item
15205 Org will then generate an agenda view with all flagged entries.  The user
15206 should then go through these entries and do whatever actions are necessary.
15207 If a note has been stored while flagging an entry in @i{MobileOrg}, that note
15208 will be displayed in the echo area when the cursor is on the corresponding
15209 agenda line.
15210 @table @kbd
15211 @kindex ?
15212 @item ?
15213 Pressing @kbd{?} in that special agenda will display the full flagging note in
15214 another window and also push it onto the kill ring.  So you could use @kbd{?
15215 z C-y C-c C-c} to store that flagging note as a normal note in the entry.
15216 Pressing @kbd{?} twice in succession will offer to remove the
15217 @code{:FLAGGED:} tag along with the recorded flagging note (which is stored
15218 in a property).  In this way you indicate that the intended processing for
15219 this flagged entry is finished.
15220 @end table
15221 @end enumerate
15223 @kindex C-c a ?
15224 If you are not able to process all flagged entries directly, you can always
15225 return to this agenda view@footnote{Note, however, that there is a subtle
15226 difference.  The view created automatically by @kbd{M-x org-mobile-pull
15227 @key{RET}} is guaranteed to search all files that have been addressed by the
15228 last pull.  This might include a file that is not currently in your list of
15229 agenda files.  If you later use @kbd{C-c a ?} to regenerate the view, only
15230 the current agenda files will be searched.} using @kbd{C-c a ?}.
15232 @node History and Acknowledgments, Main Index, MobileOrg, Top
15233 @appendix History and acknowledgments
15234 @cindex acknowledgments
15235 @cindex history
15236 @cindex thanks
15238 Org was born in 2003, out of frustration over the user interface of the Emacs
15239 Outline mode.  I was trying to organize my notes and projects, and using
15240 Emacs seemed to be the natural way to go.  However, having to remember eleven
15241 different commands with two or three keys per command, only to hide and show
15242 parts of the outline tree, that seemed entirely unacceptable to me.  Also,
15243 when using outlines to take notes, I constantly wanted to restructure the
15244 tree, organizing it parallel to my thoughts and plans.  @emph{Visibility
15245 cycling} and @emph{structure editing} were originally implemented in the
15246 package @file{outline-magic.el}, but quickly moved to the more general
15247 @file{org.el}.  As this environment became comfortable for project planning,
15248 the next step was adding @emph{TODO entries}, basic @emph{timestamps}, and
15249 @emph{table support}.  These areas highlighted the two main goals that Org
15250 still has today: to be a new, outline-based, plain text mode with innovative
15251 and intuitive editing features, and to incorporate project planning
15252 functionality directly into a notes file.
15254 Since the first release, literally thousands of emails to me or to
15255 @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug
15256 reports, feedback, new ideas, and sometimes patches and add-on code.
15257 Many thanks to everyone who has helped to improve this package.  I am
15258 trying to keep here a list of the people who had significant influence
15259 in shaping one or more aspects of Org.  The list may not be
15260 complete, if I have forgotten someone, please accept my apologies and
15261 let me know.
15263 Before I get to this list, a few special mentions are in order:
15265 @table @i
15266 @item Bastien Guerry
15267 Bastien has written a large number of extensions to Org (most of them
15268 integrated into the core by now), including the LaTeX exporter and the plain
15269 list parser.  His support during the early days, when he basically acted as
15270 co-maintainer, was central to the success of this project.  Bastien also
15271 invented Worg, helped establishing the Web presence of Org, and sponsors
15272 hosting costs for the orgmode.org website.
15273 @item Eric Schulte and Dan Davison
15274 Eric and Dan are jointly responsible for the Org-babel system, which turns
15275 Org into a multi-language environment for evaluating code and doing literate
15276 programming and reproducible research.
15277 @item John Wiegley
15278 John has contributed a number of great ideas and patches directly to Org,
15279 including the attachment system (@file{org-attach.el}), integration with
15280 Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO
15281 items, habit tracking (@file{org-habits.el}), and encryption
15282 (@file{org-crypt.el}).  Also, the capture system is really an extended copy
15283 of his great @file{remember.el}.
15284 @item Sebastian Rose
15285 Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
15286 of an ignorant amateur.  Sebastian has pushed this part of Org onto a much
15287 higher level.  He also wrote @file{org-info.js}, a Java script for displaying
15288 webpages derived from Org using an Info-like or a folding interface with
15289 single-key navigation.
15290 @end table
15292 @noindent OK, now to the full list of contributions!  Again, please let me
15293 know what I am missing here!
15295 @itemize @bullet
15297 @item
15298 @i{Russel Adams} came up with the idea for drawers.
15299 @item
15300 @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
15301 @item
15302 @i{Christophe Bataillon} created the great unicorn logo that we use on the
15303 Org-mode website.
15304 @item
15305 @i{Alex Bochannek} provided a patch for rounding timestamps.
15306 @item
15307 @i{Jan Böcker} wrote @file{org-docview.el}.
15308 @item
15309 @i{Brad Bozarth} showed how to pull RSS feed data into Org-mode files.
15310 @item
15311 @i{Tom Breton} wrote @file{org-choose.el}.
15312 @item
15313 @i{Charles Cave}'s suggestion sparked the implementation of templates
15314 for Remember, which are now templates for capture.
15315 @item
15316 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
15317 specified time.
15318 @item
15319 @i{Gregory Chernov} patched support for Lisp forms into table
15320 calculations and improved XEmacs compatibility, in particular by porting
15321 @file{nouline.el} to XEmacs.
15322 @item
15323 @i{Sacha Chua} suggested copying some linking code from Planner.
15324 @item
15325 @i{Baoqiu Cui} contributed the DocBook exporter.
15326 @item
15327 @i{Eddward DeVilla} proposed and tested checkbox statistics.  He also
15328 came up with the idea of properties, and that there should be an API for
15329 them.
15330 @item
15331 @i{Nick Dokos} tracked down several nasty bugs.
15332 @item
15333 @i{Kees Dullemond} used to edit projects lists directly in HTML and so
15334 inspired some of the early development, including HTML export.  He also
15335 asked for a way to narrow wide table columns.
15336 @item
15337 @i{Thomas S. Dye} contributed documentation on Worg and helped integrating
15338 the Org-Babel documentation into the manual.
15339 @item
15340 @i{Christian Egli} converted the documentation into Texinfo format, inspired
15341 the agenda, patched CSS formatting into the HTML exporter, and wrote
15342 @file{org-taskjuggler.el}.
15343 @item
15344 @i{David Emery} provided a patch for custom CSS support in exported
15345 HTML agendas.
15346 @item
15347 @i{Nic Ferrier} contributed mailcap and XOXO support.
15348 @item
15349 @i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
15350 @item
15351 @i{John Foerch} figured out how to make incremental search show context
15352 around a match in a hidden outline tree.
15353 @item
15354 @i{Raimar Finken} wrote @file{org-git-line.el}.
15355 @item
15356 @i{Mikael Fornius} works as a mailing list moderator.
15357 @item
15358 @i{Austin Frank} works as a mailing list moderator.
15359 @item
15360 @i{Eric Fraga} drove the development of BEAMER export with ideas and
15361 testing.
15362 @item
15363 @i{Barry Gidden} did proofreading the manual in preparation for the book
15364 publication through Network Theory Ltd.
15365 @item
15366 @i{Niels Giesen} had the idea to automatically archive DONE trees.
15367 @item
15368 @i{Nicolas Goaziou} rewrote much of the plain list code.
15369 @item
15370 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
15371 @item
15372 @i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a
15373 book.
15374 @item
15375 @i{Bernt Hansen} has driven much of the support for auto-repeating tasks,
15376 task state change logging, and the clocktable.  His clear explanations have
15377 been critical when we started to adopt the Git version control system.
15378 @item
15379 @i{Manuel Hermenegildo} has contributed various ideas, small fixes and
15380 patches.
15381 @item
15382 @i{Phil Jackson} wrote @file{org-irc.el}.
15383 @item
15384 @i{Scott Jaderholm} proposed footnotes, control over whitespace between
15385 folded entries, and column view for properties.
15386 @item
15387 @i{Matt Jones} wrote @i{MobileOrg Android}.
15388 @item
15389 @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
15390 @item
15391 @i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it.  He also
15392 provided frequent feedback and some patches.
15393 @item
15394 @i{Matt Lundin} has proposed last-row references for table formulas and named
15395 invisible anchors.  He has also worked a lot on the FAQ.
15396 @item
15397 @i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,
15398 and is a prolific contributor on the mailing list with competent replies,
15399 small fixes and patches.
15400 @item
15401 @i{Jason F. McBrayer} suggested agenda export to CSV format.
15402 @item
15403 @i{Max Mikhanosha} came up with the idea of refiling.
15404 @item
15405 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file
15406 basis.
15407 @item
15408 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
15409 happy.
15410 @item
15411 @i{Richard Moreland} wrote @i{MobileOrg} for the iPhone.
15412 @item
15413 @i{Rick Moynihan} proposed allowing multiple TODO sequences in a file
15414 and being able to quickly restrict the agenda to a subtree.
15415 @item
15416 @i{Todd Neal} provided patches for links to Info files and Elisp forms.
15417 @item
15418 @i{Greg Newman} refreshed the unicorn logo into its current form.
15419 @item
15420 @i{Tim O'Callaghan} suggested in-file links, search options for general
15421 file links, and TAGS.
15422 @item
15423 @i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text
15424 version of the reference card.
15425 @item
15426 @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
15427 into Japanese.
15428 @item
15429 @i{Oliver Oppitz} suggested multi-state TODO items.
15430 @item
15431 @i{Scott Otterson} sparked the introduction of descriptive text for
15432 links, among other things.
15433 @item
15434 @i{Pete Phillips} helped during the development of the TAGS feature, and
15435 provided frequent feedback.
15436 @item
15437 @i{Martin Pohlack} provided the code snippet to bundle character insertion
15438 into bundles of 20 for undo.
15439 @item
15440 @i{T.V. Raman} reported bugs and suggested improvements.
15441 @item
15442 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
15443 control.
15444 @item
15445 @i{Paul Rivier} provided the basic implementation of named footnotes.  He
15446 also acted as mailing list moderator for some time.
15447 @item
15448 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
15449 @item
15450 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
15451 conflict with @file{allout.el}.
15452 @item
15453 @i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with
15454 extensive patches.
15455 @item
15456 @i{Philip Rooke} created the Org reference card, provided lots
15457 of feedback, developed and applied standards to the Org documentation.
15458 @item
15459 @i{Christian Schlauer} proposed angular brackets around links, among
15460 other things.
15461 @item
15462 @i{Paul Sexton} wrote @file{org-ctags.el}.
15463 @item
15464 Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
15465 @file{organizer-mode.el}.
15466 @item
15467 @i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal
15468 examples, and remote highlighting for referenced code lines.
15469 @item
15470 @i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is
15471 now packaged into Org's @file{contrib} directory.
15472 @item
15473 @i{Daniel Sinder} came up with the idea of internal archiving by locking
15474 subtrees.
15475 @item
15476 @i{Dale Smith} proposed link abbreviations.
15477 @item
15478 @i{James TD Smith} has contributed a large number of patches for useful
15479 tweaks and features.
15480 @item
15481 @i{Adam Spiers} asked for global linking commands, inspired the link
15482 extension system, added support for mairix, and proposed the mapping API.
15483 @item
15484 @i{Ulf Stegemann} created the table to translate special symbols to HTML,
15485 LaTeX, UTF-8, Latin-1 and ASCII.
15486 @item
15487 @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
15488 with links transformation to Org syntax.
15489 @item
15490 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
15491 chapter about publishing.
15492 @item
15493 @i{Jambunathan K} contributed the OpenDocumentText exporter.
15494 @item
15495 @i{Sebastien Vauban} reported many issues with LaTeX and BEAMER export and
15496 enabled source code highlighling in Gnus.
15497 @item
15498 @i{Stefan Vollmar} organized a video-recorded talk at the
15499 Max-Planck-Institute for Neurology.  He also inspired the creation of a
15500 concept index for HTML export.
15501 @item
15502 @i{J@"urgen Vollmer} contributed code generating the table of contents
15503 in HTML output.
15504 @item
15505 @i{Samuel Wales} has provided important feedback and bug reports.
15506 @item
15507 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
15508 keyword.
15509 @item
15510 @i{David Wainberg} suggested archiving, and improvements to the linking
15511 system.
15512 @item
15513 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
15514 linking to Gnus.
15515 @item
15516 @i{Roland Winkler} requested additional key bindings to make Org
15517 work on a tty.
15518 @item
15519 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
15520 and contributed various ideas and code snippets.
15521 @item
15522 @end itemize
15525 @node Main Index, Key Index, History and Acknowledgments, Top
15526 @unnumbered Concept index
15528 @printindex cp
15530 @node Key Index, Command and Function Index, Main Index, Top
15531 @unnumbered Key index
15533 @printindex ky
15535 @node Command and Function Index, Variable Index, Key Index, Top
15536 @unnumbered Command and function index
15538 @printindex fn
15540 @node Variable Index,  , Command and Function Index, Top
15541 @unnumbered Variable index
15543 This is not a complete index of variables and faces, only the ones that are
15544 mentioned in the manual.  For a more complete list, use @kbd{M-x
15545 org-customize @key{RET}} and then click yourself through the tree.
15547 @printindex vr
15549 @bye
15551 @ignore
15552         arch-tag: 7893d1Fe-cc57-4d13-b5e5-f494a1CBC7ac
15553 @end ignore
15555 @c Local variables:
15556 @c fill-column: 77
15557 @c indent-tabs-mode: nil
15558 @c paragraph-start:    "\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[  ]*$"
15559 @c paragraph-separate: "\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[       \f]*$"
15560 @c End:
15563 @c  LocalWords:  webdavhost pre