Fix Org ChangeLog entries and remove arch-tag.
[bpt/emacs.git] / doc / misc / org.texi
1
2 \input texinfo
3 @c %**start of header
4 @setfilename ../../info/org
5 @settitle The Org Manual
6
7 @set VERSION 7.7
8 @set DATE July 2011
9
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
14
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
23
24
25 @c -----------------------------------------------------------------------------
26
27 @c Macro definitions for commands and keys
28 @c =======================================
29
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.
32
33 @set cmdnames
34
35 @c Below we define the following macros for Org key tables:
36
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
48
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
55
56 @macro xorgkey{key}
57 @kindex \key\
58 @itemx @kbd{\key\}
59 @end macro
60
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
79
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
98
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
115
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
134
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
155
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
181
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
202
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
223
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 -----------------------------------------------------------------------------
250
251 @iftex
252 @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
253 @end iftex
254
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
264
265 @copying
266 This manual is for Org version @value{VERSION}.
267
268 Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
269 Free Software Foundation, Inc.
270
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.''
278
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.''
282
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
289
290 @dircategory Emacs
291 @direntry
292 * Org Mode: (org). Outline-based notes management and organizer
293 @end direntry
294
295 @titlepage
296 @title The Org Manual
297
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
301
302 @c The following two commands start the copyright page.
303 @page
304 @vskip 0pt plus 1filll
305 @insertcopying
306 @end titlepage
307
308 @c Output the table of contents at the beginning.
309 @contents
310
311 @ifnottex
312 @node Top, Introduction, (dir), (dir)
313 @top Org Mode Manual
314
315 @insertcopying
316 @end ifnottex
317
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
341
342 @detailmenu
343 --- The Detailed Node Listing ---
344
345 Introduction
346
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
352
353 Document structure
354
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
366
367 Tables
368
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
375
376 The spreadsheet
377
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
387
388 Hyperlinks
389
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
398
399 Internal links
400
401 * Radio targets:: Make targets trigger links in plain text
402
403 TODO items
404
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
411
412 Extended use of TODO keywords
413
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
421
422 Progress logging
423
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?
427
428 Tags
429
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
433
434 Properties and columns
435
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
442
443 Column view
444
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
448
449 Defining columns
450
451 * Scope of column definitions:: Where defined, where valid?
452 * Column attributes:: Appearance and content of a column
453
454 Dates and times
455
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
463
464 Creating timestamps
465
466 * The date/time prompt:: How Org-mode helps you entering date and time
467 * Custom time format:: Making dates look different
468
469 Deadlines and scheduling
470
471 * Inserting deadline/schedule:: Planning items
472 * Repeated tasks:: Items that show up again and again
473
474 Clocking work time
475
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
479
480 Capture - Refile - Archive
481
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
488
489 Capture
490
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
494
495 Capture templates
496
497 * Template elements:: What is needed for a complete template entry
498 * Template expansion:: Filling in information about time and context
499
500 Archiving
501
502 * Moving subtrees:: Moving a tree to an archive file
503 * Internal archiving:: Switch off a tree but keep it in the file
504
505 Agenda views
506
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
515
516 The built-in agenda views
517
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
524
525 Presentation and sorting
526
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
530
531 Custom agenda views
532
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
536
537 Markup for rich export
538
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
546
547 Structural markup elements
548
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
559
560 Embedded @LaTeX{}
561
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
567
568 Exporting
569
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
582
583 HTML export
584
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
595
596 @LaTeX{} and PDF export
597
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
604
605 DocBook export
606
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
613
614 OpenDocument export
615
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
623
624 Publishing
625
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
630
631 Configuration
632
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
641
642 Sample configuration
643
644 * Simple example:: One-component publishing
645 * Complex example:: A multi-component publishing example
646
647 Working with source code
648
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
661
662 Header arguments
663
664 * Using header arguments:: Different ways to set header arguments
665 * Specific header arguments:: List of header arguments
666
667 Using header arguments
668
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
675
676 Specific header arguments
677
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
704
705 Miscellaneous
706
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
718
719 Interaction with other packages
720
721 * Cooperation:: Packages Org cooperates with
722 * Conflicts:: Packages that lead to conflicts
723
724 Hacking
725
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
736
737 Tables and lists in arbitrary syntax
738
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
743
744 MobileOrg
745
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
749
750 @end detailmenu
751 @end menu
752
753 @node Introduction, Document Structure, Top, Top
754 @chapter Introduction
755 @cindex introduction
756
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
764
765 @node Summary, Installation, Introduction, Introduction
766 @section Summary
767 @cindex summary
768
769 Org is a mode for keeping notes, maintaining TODO lists, and doing
770 project planning with a fast and effective plain-text system.
771
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.
786
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}.
790
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.
794
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.
801
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:
807
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
819
820
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}.
826
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.}
831
832 @page
833
834
835 @node Installation, Activation, Summary, Introduction
836 @section Installation
837 @cindex installation
838 @cindex XEmacs
839
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}.}
845
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}:
855
856 @example
857 (setq load-path (cons "~/path/to/orgdir/lisp" load-path))
858 @end example
859
860 @noindent
861 If you plan to use code from the @file{contrib} subdirectory, do a similar
862 step for this directory:
863
864 @example
865 (setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path))
866 @end example
867
868 @noindent Now byte-compile the Lisp files with the shell command:
869
870 @example
871 make
872 @end example
873
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)
877
878 @example
879 make install
880 @end example
881
882 Installing Info files is system dependent, because of differences in the
883 @file{install-info} program. The following should correctly install the Info
884 files on most systems, please send a bug report if not@footnote{The output
885 from install-info (if any) is also system dependent. In particular Debian
886 and its derivatives use two different versions of install-info and you may
887 see the message:
888
889 @example
890 This is not dpkg install-info anymore, but GNU install-info
891 See the man page for ginstall-info for command line arguments
892 @end example
893
894 @noindent which can be safely ignored.}.
895
896 @example
897 make install-info
898 @end example
899
900 Then add the following line to @file{.emacs}. It is needed so that
901 Emacs can autoload functions that are located in files not immediately loaded
902 when Org-mode starts.
903 @lisp
904 (require 'org-install)
905 @end lisp
906
907 Do not forget to activate Org as described in the following section.
908 @page
909
910 @node Activation, Feedback, Installation, Introduction
911 @section Activation
912 @cindex activation
913 @cindex autoload
914 @cindex global key bindings
915 @cindex key bindings, global
916
917 To make sure files with extension @file{.org} use Org mode, add the following
918 line to your @file{.emacs} file.
919 @lisp
920 (add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
921 @end lisp
922 @noindent Org mode buffers need font-lock to be turned on - this is the
923 default in Emacs@footnote{If you don't use font-lock globally, turn it on in
924 Org buffer with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
925
926 The four Org commands @command{org-store-link}, @command{org-capture},
927 @command{org-agenda}, and @command{org-iswitchb} should be accessible through
928 global keys (i.e.@: anywhere in Emacs, not just in Org buffers). Here are
929 suggested bindings for these keys, please modify the keys to your own
930 liking.
931 @lisp
932 (global-set-key "\C-cl" 'org-store-link)
933 (global-set-key "\C-cc" 'org-capture)
934 (global-set-key "\C-ca" 'org-agenda)
935 (global-set-key "\C-cb" 'org-iswitchb)
936 @end lisp
937
938 @cindex Org-mode, turning on
939 With this setup, all files with extension @samp{.org} will be put
940 into Org-mode. As an alternative, make the first line of a file look
941 like this:
942
943 @example
944 MY PROJECTS -*- mode: org; -*-
945 @end example
946
947 @vindex org-insert-mode-line-in-empty-file
948 @noindent which will select Org-mode for this buffer no matter what
949 the file's name is. See also the variable
950 @code{org-insert-mode-line-in-empty-file}.
951
952 Many commands in Org work on the region if the region is @i{active}. To make
953 use of this, you need to have @code{transient-mark-mode}
954 (@code{zmacs-regions} in XEmacs) turned on. In Emacs 23 this is the default,
955 in Emacs 22 you need to do this yourself with
956 @lisp
957 (transient-mark-mode 1)
958 @end lisp
959 @noindent If you do not like @code{transient-mark-mode}, you can create an
960 active region by using the mouse to select a region, or pressing
961 @kbd{C-@key{SPC}} twice before moving the cursor.
962
963 @node Feedback, Conventions, Activation, Introduction
964 @section Feedback
965 @cindex feedback
966 @cindex bug reports
967 @cindex maintainer
968 @cindex author
969
970 If you find problems with Org, or if you have questions, remarks, or ideas
971 about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
972 If you are not a member of the mailing list, your mail will be passed to the
973 list after a moderator has approved it@footnote{Please consider subscribing
974 to the mailing list, in order to minimize the work the mailing list
975 moderators have to do.}.
976
977 For bug reports, please first try to reproduce the bug with the latest
978 version of Org available---if you are running an outdated version, it is
979 quite possible that the bug has been fixed already. If the bug persists,
980 prepare a report and provide as much information as possible, including the
981 version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
982 (@kbd{M-x org-version @key{RET}}), as well as the Org related setup in
983 @file{.emacs}. The easiest way to do this is to use the command
984 @example
985 @kbd{M-x org-submit-bug-report}
986 @end example
987 @noindent which will put all this information into an Emacs mail buffer so
988 that you only need to add your description. If you re not sending the Email
989 from within Emacs, please copy and paste the content into your Email program.
990
991 If an error occurs, a backtrace can be very useful (see below on how to
992 create one). Often a small example file helps, along with clear information
993 about:
994
995 @enumerate
996 @item What exactly did you do?
997 @item What did you expect to happen?
998 @item What happened instead?
999 @end enumerate
1000 @noindent Thank you for helping to improve this program.
1001
1002 @subsubheading How to create a useful backtrace
1003
1004 @cindex backtrace of an error
1005 If working with Org produces an error with a message you don't
1006 understand, you may have hit a bug. The best way to report this is by
1007 providing, in addition to what was mentioned above, a @emph{backtrace}.
1008 This is information from the built-in debugger about where and how the
1009 error occurred. Here is how to produce a useful backtrace:
1010
1011 @enumerate
1012 @item
1013 Reload uncompiled versions of all Org-mode Lisp files. The backtrace
1014 contains much more information if it is produced with uncompiled code.
1015 To do this, use
1016 @example
1017 C-u M-x org-reload RET
1018 @end example
1019 @noindent
1020 or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
1021 menu.
1022 @item
1023 Go to the @code{Options} menu and select @code{Enter Debugger on Error}
1024 (XEmacs has this option in the @code{Troubleshooting} sub-menu).
1025 @item
1026 Do whatever you have to do to hit the error. Don't forget to
1027 document the steps you take.
1028 @item
1029 When you hit the error, a @file{*Backtrace*} buffer will appear on the
1030 screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
1031 attach it to your bug report.
1032 @end enumerate
1033
1034 @node Conventions, , Feedback, Introduction
1035 @section Typesetting conventions used in this manual
1036
1037 Org uses three types of keywords: TODO keywords, tags, and property
1038 names. In this manual we use the following conventions:
1039
1040 @table @code
1041 @item TODO
1042 @itemx WAITING
1043 TODO keywords are written with all capitals, even if they are
1044 user-defined.
1045 @item boss
1046 @itemx ARCHIVE
1047 User-defined tags are written in lowercase; built-in tags with special
1048 meaning are written with all capitals.
1049 @item Release
1050 @itemx PRIORITY
1051 User-defined properties are capitalized; built-in properties with
1052 special meaning are written with all capitals.
1053 @end table
1054
1055 The manual lists both the keys and the corresponding commands for accessing
1056 functionality. Org mode often uses the same key for different functions,
1057 depending on context. The command that is bound to such keys has a generic
1058 name, like @code{org-metaright}. In the manual we will, wherever possible,
1059 give the function that is internally called by the generic command. For
1060 example, in the chapter on document structure, @kbd{M-@key{right}} will be
1061 listed to call @code{org-do-demote}, while in the chapter on tables, it will
1062 be listed to call org-table-move-column-right.
1063
1064 If you prefer, you can compile the manual without the command names by
1065 unsetting the flag @code{cmdnames} in @file{org.texi}.
1066
1067 @node Document Structure, Tables, Introduction, Top
1068 @chapter Document structure
1069 @cindex document structure
1070 @cindex structure of document
1071
1072 Org is based on Outline mode and provides flexible commands to
1073 edit the structure of the document.
1074
1075 @menu
1076 * Outlines:: Org is based on Outline mode
1077 * Headlines:: How to typeset Org tree headlines
1078 * Visibility cycling:: Show and hide, much simplified
1079 * Motion:: Jumping to other headlines
1080 * Structure editing:: Changing sequence and level of headlines
1081 * Sparse trees:: Matches embedded in context
1082 * Plain lists:: Additional structure within an entry
1083 * Drawers:: Tucking stuff away
1084 * Blocks:: Folding blocks
1085 * Footnotes:: How footnotes are defined in Org's syntax
1086 * Orgstruct mode:: Structure editing outside Org
1087 @end menu
1088
1089 @node Outlines, Headlines, Document Structure, Document Structure
1090 @section Outlines
1091 @cindex outlines
1092 @cindex Outline mode
1093
1094 Org is implemented on top of Outline mode. Outlines allow a
1095 document to be organized in a hierarchical structure, which (at least
1096 for me) is the best representation of notes and thoughts. An overview
1097 of this structure is achieved by folding (hiding) large parts of the
1098 document to show only the general document structure and the parts
1099 currently being worked on. Org greatly simplifies the use of
1100 outlines by compressing the entire show/hide functionality into a single
1101 command, @command{org-cycle}, which is bound to the @key{TAB} key.
1102
1103 @node Headlines, Visibility cycling, Outlines, Document Structure
1104 @section Headlines
1105 @cindex headlines
1106 @cindex outline tree
1107 @vindex org-special-ctrl-a/e
1108 @vindex org-special-ctrl-k
1109 @vindex org-ctrl-k-protect-subtree
1110
1111 Headlines define the structure of an outline tree. The headlines in Org
1112 start with one or more stars, on the left margin@footnote{See the variables
1113 @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
1114 @code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
1115 @kbd{C-e}, and @kbd{C-k} in headlines.}. For example:
1116
1117 @example
1118 * Top level headline
1119 ** Second level
1120 *** 3rd level
1121 some text
1122 *** 3rd level
1123 more text
1124
1125 * Another top level headline
1126 @end example
1127
1128 @noindent Some people find the many stars too noisy and would prefer an
1129 outline that has whitespace followed by a single star as headline
1130 starters. @ref{Clean view}, describes a setup to realize this.
1131
1132 @vindex org-cycle-separator-lines
1133 An empty line after the end of a subtree is considered part of it and
1134 will be hidden when the subtree is folded. However, if you leave at
1135 least two empty lines, one empty line will remain visible after folding
1136 the subtree, in order to structure the collapsed view. See the
1137 variable @code{org-cycle-separator-lines} to modify this behavior.
1138
1139 @node Visibility cycling, Motion, Headlines, Document Structure
1140 @section Visibility cycling
1141 @cindex cycling, visibility
1142 @cindex visibility cycling
1143 @cindex trees, visibility
1144 @cindex show hidden text
1145 @cindex hide text
1146
1147 Outlines make it possible to hide parts of the text in the buffer.
1148 Org uses just two commands, bound to @key{TAB} and
1149 @kbd{S-@key{TAB}} to change the visibility in the buffer.
1150
1151 @cindex subtree visibility states
1152 @cindex subtree cycling
1153 @cindex folded, subtree visibility state
1154 @cindex children, subtree visibility state
1155 @cindex subtree, subtree visibility state
1156 @table @asis
1157 @orgcmd{@key{TAB},org-cycle}
1158 @emph{Subtree cycling}: Rotate current subtree among the states
1159
1160 @example
1161 ,-> FOLDED -> CHILDREN -> SUBTREE --.
1162 '-----------------------------------'
1163 @end example
1164
1165 @vindex org-cycle-emulate-tab
1166 @vindex org-cycle-global-at-bob
1167 The cursor must be on a headline for this to work@footnote{see, however,
1168 the option @code{org-cycle-emulate-tab}.}. When the cursor is at the
1169 beginning of the buffer and the first line is not a headline, then
1170 @key{TAB} actually runs global cycling (see below)@footnote{see the
1171 option @code{org-cycle-global-at-bob}.}. Also when called with a prefix
1172 argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
1173
1174 @cindex global visibility states
1175 @cindex global cycling
1176 @cindex overview, global visibility state
1177 @cindex contents, global visibility state
1178 @cindex show all, global visibility state
1179 @orgcmd{S-@key{TAB},org-global-cycle}
1180 @itemx C-u @key{TAB}
1181 @emph{Global cycling}: Rotate the entire buffer among the states
1182
1183 @example
1184 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
1185 '--------------------------------------'
1186 @end example
1187
1188 When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the
1189 CONTENTS view up to headlines of level N will be shown. Note that inside
1190 tables, @kbd{S-@key{TAB}} jumps to the previous field.
1191
1192 @cindex show all, command
1193 @orgcmd{C-u C-u C-u @key{TAB},show-all}
1194 Show all, including drawers.
1195 @orgcmd{C-c C-r,org-reveal}
1196 Reveal context around point, showing the current entry, the following heading
1197 and the hierarchy above. Useful for working near a location that has been
1198 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
1199 (@pxref{Agenda commands}). With a prefix argument show, on each
1200 level, all sibling headings. With double prefix arg, also show the entire
1201 subtree of the parent.
1202 @orgcmd{C-c C-k,show-branches}
1203 Expose all the headings of the subtree, CONTENT view for just one subtree.
1204 @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
1205 Show the current subtree in an indirect buffer@footnote{The indirect
1206 buffer
1207 @ifinfo
1208 (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual})
1209 @end ifinfo
1210 @ifnotinfo
1211 (see the Emacs manual for more information about indirect buffers)
1212 @end ifnotinfo
1213 will contain the entire buffer, but will be narrowed to the current
1214 tree. Editing the indirect buffer will also change the original buffer,
1215 but without affecting visibility in that buffer.}. With a numeric
1216 prefix argument N, go up to level N and then take that tree. If N is
1217 negative then go up that many levels. With a @kbd{C-u} prefix, do not remove
1218 the previously used indirect buffer.
1219 @orgcmd{C-c C-x v,org-copy-visible}
1220 Copy the @i{visible} text in the region into the kill ring.
1221 @end table
1222
1223 @vindex org-startup-folded
1224 @cindex @code{overview}, STARTUP keyword
1225 @cindex @code{content}, STARTUP keyword
1226 @cindex @code{showall}, STARTUP keyword
1227 @cindex @code{showeverything}, STARTUP keyword
1228
1229 When Emacs first visits an Org file, the global state is set to
1230 OVERVIEW, i.e.@: only the top level headlines are visible. This can be
1231 configured through the variable @code{org-startup-folded}, or on a
1232 per-file basis by adding one of the following lines anywhere in the
1233 buffer:
1234
1235 @example
1236 #+STARTUP: overview
1237 #+STARTUP: content
1238 #+STARTUP: showall
1239 #+STARTUP: showeverything
1240 @end example
1241
1242 @cindex property, VISIBILITY
1243 @noindent
1244 Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
1245 and Columns}) will get their visibility adapted accordingly. Allowed values
1246 for this property are @code{folded}, @code{children}, @code{content}, and
1247 @code{all}.
1248 @table @asis
1249 @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
1250 Switch back to the startup visibility of the buffer, i.e.@: whatever is
1251 requested by startup options and @samp{VISIBILITY} properties in individual
1252 entries.
1253 @end table
1254
1255 @node Motion, Structure editing, Visibility cycling, Document Structure
1256 @section Motion
1257 @cindex motion, between headlines
1258 @cindex jumping, to headlines
1259 @cindex headline navigation
1260 The following commands jump to other headlines in the buffer.
1261
1262 @table @asis
1263 @orgcmd{C-c C-n,outline-next-visible-heading}
1264 Next heading.
1265 @orgcmd{C-c C-p,outline-previous-visible-heading}
1266 Previous heading.
1267 @orgcmd{C-c C-f,org-forward-same-level}
1268 Next heading same level.
1269 @orgcmd{C-c C-b,org-backward-same-level}
1270 Previous heading same level.
1271 @orgcmd{C-c C-u,outline-up-heading}
1272 Backward to higher level heading.
1273 @orgcmd{C-c C-j,org-goto}
1274 Jump to a different place without changing the current outline
1275 visibility. Shows the document structure in a temporary buffer, where
1276 you can use the following keys to find your destination:
1277 @vindex org-goto-auto-isearch
1278 @example
1279 @key{TAB} @r{Cycle visibility.}
1280 @key{down} / @key{up} @r{Next/previous visible headline.}
1281 @key{RET} @r{Select this location.}
1282 @kbd{/} @r{Do a Sparse-tree search}
1283 @r{The following keys work if you turn off @code{org-goto-auto-isearch}}
1284 n / p @r{Next/previous visible headline.}
1285 f / b @r{Next/previous headline same level.}
1286 u @r{One level up.}
1287 0-9 @r{Digit argument.}
1288 q @r{Quit}
1289 @end example
1290 @vindex org-goto-interface
1291 @noindent
1292 See also the variable @code{org-goto-interface}.
1293 @end table
1294
1295 @node Structure editing, Sparse trees, Motion, Document Structure
1296 @section Structure editing
1297 @cindex structure editing
1298 @cindex headline, promotion and demotion
1299 @cindex promotion, of subtrees
1300 @cindex demotion, of subtrees
1301 @cindex subtree, cut and paste
1302 @cindex pasting, of subtrees
1303 @cindex cutting, of subtrees
1304 @cindex copying, of subtrees
1305 @cindex sorting, of subtrees
1306 @cindex subtrees, cut and paste
1307
1308 @table @asis
1309 @orgcmd{M-@key{RET},org-insert-heading}
1310 @vindex org-M-RET-may-split-line
1311 Insert new heading with same level as current. If the cursor is in a plain
1312 list item, a new item is created (@pxref{Plain lists}). To force creation of
1313 a new headline, use a prefix argument. When this command is used in the
1314 middle of a line, the line is split and the rest of the line becomes the new
1315 headline@footnote{If you do not want the line to be split, customize the
1316 variable @code{org-M-RET-may-split-line}.}. If the command is used at the
1317 beginning of a headline, the new headline is created before the current line.
1318 If at the beginning of any other line, the content of that line is made the
1319 new heading. If the command is used at the end of a folded subtree (i.e.@:
1320 behind the ellipses at the end of a headline), then a headline like the
1321 current one will be inserted after the end of the subtree.
1322 @orgcmd{C-@key{RET},org-insert-heading-respect-content}
1323 Just like @kbd{M-@key{RET}}, except when adding a new heading below the
1324 current heading, the new heading is placed after the body instead of before
1325 it. This command works from anywhere in the entry.
1326 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
1327 @vindex org-treat-insert-todo-heading-as-state-change
1328 Insert new TODO entry with same level as current heading. See also the
1329 variable @code{org-treat-insert-todo-heading-as-state-change}.
1330 @orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
1331 Insert new TODO entry with same level as current heading. Like
1332 @kbd{C-@key{RET}}, the new headline will be inserted after the current
1333 subtree.
1334 @orgcmd{@key{TAB},org-cycle}
1335 In a new entry with no text yet, the first @key{TAB} demotes the entry to
1336 become a child of the previous one. The next @key{TAB} makes it a parent,
1337 and so on, all the way to top level. Yet another @key{TAB}, and you are back
1338 to the initial level.
1339 @orgcmd{M-@key{left},org-do-promote}
1340 Promote current heading by one level.
1341 @orgcmd{M-@key{right},org-do-demote}
1342 Demote current heading by one level.
1343 @orgcmd{M-S-@key{left},org-promote-subtree}
1344 Promote the current subtree by one level.
1345 @orgcmd{M-S-@key{right},org-demote-subtree}
1346 Demote the current subtree by one level.
1347 @orgcmd{M-S-@key{up},org-move-subtree-up}
1348 Move subtree up (swap with previous subtree of same
1349 level).
1350 @orgcmd{M-S-@key{down},org-move-subtree-down}
1351 Move subtree down (swap with next subtree of same level).
1352 @orgcmd{C-c C-x C-w,org-cut-subtree}
1353 Kill subtree, i.e.@: remove it from buffer but save in kill ring.
1354 With a numeric prefix argument N, kill N sequential subtrees.
1355 @orgcmd{C-c C-x M-w,org-copy-subtree}
1356 Copy subtree to kill ring. With a numeric prefix argument N, copy the N
1357 sequential subtrees.
1358 @orgcmd{C-c C-x C-y,org-paste-subtree}
1359 Yank subtree from kill ring. This does modify the level of the subtree to
1360 make sure the tree fits in nicely at the yank position. The yank level can
1361 also be specified with a numeric prefix argument, or by yanking after a
1362 headline marker like @samp{****}.
1363 @orgcmd{C-y,org-yank}
1364 @vindex org-yank-adjusted-subtrees
1365 @vindex org-yank-folded-subtrees
1366 Depending on the variables @code{org-yank-adjusted-subtrees} and
1367 @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
1368 paste subtrees folded and in a clever way, using the same command as @kbd{C-c
1369 C-x C-y}. With the default settings, no level adjustment will take place,
1370 but the yanked tree will be folded unless doing so would swallow text
1371 previously visible. Any prefix argument to this command will force a normal
1372 @code{yank} to be executed, with the prefix passed along. A good way to
1373 force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a
1374 yank, it will yank previous kill items plainly, without adjustment and
1375 folding.
1376 @orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
1377 Clone a subtree by making a number of sibling copies of it. You will be
1378 prompted for the number of copies to make, and you can also specify if any
1379 timestamps in the entry should be shifted. This can be useful, for example,
1380 to create a number of tasks related to a series of lectures to prepare. For
1381 more details, see the docstring of the command
1382 @code{org-clone-subtree-with-time-shift}.
1383 @orgcmd{C-c C-w,org-refile}
1384 Refile entry or region to a different location. @xref{Refiling notes}.
1385 @orgcmd{C-c ^,org-sort-entries-or-items}
1386 Sort same-level entries. When there is an active region, all entries in the
1387 region will be sorted. Otherwise the children of the current headline are
1388 sorted. The command prompts for the sorting method, which can be
1389 alphabetically, numerically, by time (first timestamp with active preferred,
1390 creation time, scheduled time, deadline time), by priority, by TODO keyword
1391 (in the sequence the keywords have been defined in the setup) or by the value
1392 of a property. Reverse sorting is possible as well. You can also supply
1393 your own function to extract the sorting key. With a @kbd{C-u} prefix,
1394 sorting will be case-sensitive. With two @kbd{C-u C-u} prefixes, duplicate
1395 entries will also be removed.
1396 @orgcmd{C-x n s,org-narrow-to-subtree}
1397 Narrow buffer to current subtree.
1398 @orgcmd{C-x n b,org-narrow-to-block}
1399 Narrow buffer to current block.
1400 @orgcmd{C-x n w,widen}
1401 Widen buffer to remove narrowing.
1402 @orgcmd{C-c *,org-toggle-heading}
1403 Turn a normal line or plain list item into a headline (so that it becomes a
1404 subheading at its location). Also turn a headline into a normal line by
1405 removing the stars. If there is an active region, turn all lines in the
1406 region into headlines. If the first line in the region was an item, turn
1407 only the item lines into headlines. Finally, if the first line is a
1408 headline, remove the stars from all headlines in the region.
1409 @end table
1410
1411 @cindex region, active
1412 @cindex active region
1413 @cindex transient mark mode
1414 When there is an active region (Transient Mark mode), promotion and
1415 demotion work on all headlines in the region. To select a region of
1416 headlines, it is best to place both point and mark at the beginning of a
1417 line, mark at the beginning of the first headline, and point at the line
1418 just after the last headline to change. Note that when the cursor is
1419 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
1420 functionality.
1421
1422
1423 @node Sparse trees, Plain lists, Structure editing, Document Structure
1424 @section Sparse trees
1425 @cindex sparse trees
1426 @cindex trees, sparse
1427 @cindex folding, sparse trees
1428 @cindex occur, command
1429
1430 @vindex org-show-hierarchy-above
1431 @vindex org-show-following-heading
1432 @vindex org-show-siblings
1433 @vindex org-show-entry-below
1434 An important feature of Org-mode is the ability to construct @emph{sparse
1435 trees} for selected information in an outline tree, so that the entire
1436 document is folded as much as possible, but the selected information is made
1437 visible along with the headline structure above it@footnote{See also the
1438 variables @code{org-show-hierarchy-above}, @code{org-show-following-heading},
1439 @code{org-show-siblings}, and @code{org-show-entry-below} for detailed
1440 control on how much context is shown around each match.}. Just try it out
1441 and you will see immediately how it works.
1442
1443 Org-mode contains several commands creating such trees, all these
1444 commands can be accessed through a dispatcher:
1445
1446 @table @asis
1447 @orgcmd{C-c /,org-sparse-tree}
1448 This prompts for an extra key to select a sparse-tree creating command.
1449 @orgcmd{C-c / r,org-occur}
1450 @vindex org-remove-highlights-with-change
1451 Prompts for a regexp and shows a sparse tree with all matches. If
1452 the match is in a headline, the headline is made visible. If the match is in
1453 the body of an entry, headline and body are made visible. In order to
1454 provide minimal context, also the full hierarchy of headlines above the match
1455 is shown, as well as the headline following the match. Each match is also
1456 highlighted; the highlights disappear when the buffer is changed by an
1457 editing command@footnote{This depends on the option
1458 @code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
1459 When called with a @kbd{C-u} prefix argument, previous highlights are kept,
1460 so several calls to this command can be stacked.
1461 @orgcmdkkc{M-g n,M-g M-n,next-error}
1462 Jump to the next sparse tree match in this buffer.
1463 @orgcmdkkc{M-g p,M-g M-p,previous-error}
1464 Jump to the previous sparse tree match in this buffer.
1465 @end table
1466
1467
1468 @noindent
1469 @vindex org-agenda-custom-commands
1470 For frequently used sparse trees of specific search strings, you can
1471 use the variable @code{org-agenda-custom-commands} to define fast
1472 keyboard access to specific sparse trees. These commands will then be
1473 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
1474 For example:
1475
1476 @lisp
1477 (setq org-agenda-custom-commands
1478 '(("f" occur-tree "FIXME")))
1479 @end lisp
1480
1481 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
1482 a sparse tree matching the string @samp{FIXME}.
1483
1484 The other sparse tree commands select headings based on TODO keywords,
1485 tags, or properties and will be discussed later in this manual.
1486
1487 @kindex C-c C-e v
1488 @cindex printing sparse trees
1489 @cindex visible text, printing
1490 To print a sparse tree, you can use the Emacs command
1491 @code{ps-print-buffer-with-faces} which does not print invisible parts
1492 of the document @footnote{This does not work under XEmacs, because
1493 XEmacs uses selective display for outlining, not text properties.}.
1494 Or you can use the command @kbd{C-c C-e v} to export only the visible
1495 part of the document and print the resulting file.
1496
1497 @node Plain lists, Drawers, Sparse trees, Document Structure
1498 @section Plain lists
1499 @cindex plain lists
1500 @cindex lists, plain
1501 @cindex lists, ordered
1502 @cindex ordered lists
1503
1504 Within an entry of the outline tree, hand-formatted lists can provide
1505 additional structure. They also provide a way to create lists of checkboxes
1506 (@pxref{Checkboxes}). Org supports editing such lists, and every exporter
1507 (@pxref{Exporting}) can parse and format them.
1508
1509 Org knows ordered lists, unordered lists, and description lists.
1510 @itemize @bullet
1511 @item
1512 @emph{Unordered} list items start with @samp{-}, @samp{+}, or
1513 @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
1514 they will be seen as top-level headlines. Also, when you are hiding leading
1515 stars to get a clean outline view, plain list items starting with a star may
1516 be hard to distinguish from true headlines. In short: even though @samp{*}
1517 is supported, it may be better to not use it for plain list items.} as
1518 bullets.
1519 @item
1520 @vindex org-plain-list-ordered-item-terminator
1521 @vindex org-alphabetical-lists
1522 @emph{Ordered} list items start with a numeral followed by either a period or
1523 a right parenthesis@footnote{You can filter out any of them by configuring
1524 @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
1525 @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
1526 @samp{A)} by configuring @code{org-alphabetical-lists}. To minimize
1527 confusion with normal text, those are limited to one character only. Beyond
1528 that limit, bullets will automatically fallback to numbers.}. If you want a
1529 list to start with a different value (e.g.@: 20), start the text of the item
1530 with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
1531 must be put @emph{before} the checkbox. If you have activated alphabetical
1532 lists, you can also use counters like @code{[@@b]}.}. Those constructs can
1533 be used in any item of the list in order to enforce a particular numbering.
1534 @item
1535 @emph{Description} list items are unordered list items, and contain the
1536 separator @samp{ :: } to distinguish the description @emph{term} from the
1537 description.
1538 @end itemize
1539
1540 Items belonging to the same list must have the same indentation on the first
1541 line. In particular, if an ordered list reaches number @samp{10.}, then the
1542 2--digit numbers must be written left-aligned with the other numbers in the
1543 list. An item ends before the next line that is less or equally indented
1544 than its bullet/number.
1545
1546 @vindex org-list-ending-method
1547 @vindex org-list-end-regexp
1548 @vindex org-empty-line-terminates-plain-lists
1549 Two methods@footnote{To disable either of them, configure
1550 @code{org-list-ending-method}.} are provided to terminate lists. A list ends
1551 whenever every item has ended, which means before any line less or equally
1552 indented than items at top level. It also ends before two blank
1553 lines@footnote{See also @code{org-empty-line-terminates-plain-lists}.}. In
1554 that case, all items are closed. For finer control, you can end lists with
1555 any pattern set in @code{org-list-end-regexp}. Here is an example:
1556
1557 @example
1558 @group
1559 ** Lord of the Rings
1560 My favorite scenes are (in this order)
1561 1. The attack of the Rohirrim
1562 2. Eowyn's fight with the witch king
1563 + this was already my favorite scene in the book
1564 + I really like Miranda Otto.
1565 3. Peter Jackson being shot by Legolas
1566 - on DVD only
1567 He makes a really funny face when it happens.
1568 But in the end, no individual scenes matter but the film as a whole.
1569 Important actors in this film are:
1570 - @b{Elijah Wood} :: He plays Frodo
1571 - @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember
1572 him very well from his role as Mikey Walsh in @i{The Goonies}.
1573 @end group
1574 @end example
1575
1576 Org supports these lists by tuning filling and wrapping commands to deal with
1577 them correctly@footnote{Org only changes the filling settings for Emacs. For
1578 XEmacs, you should use Kyle E. Jones' @file{filladapt.el}. To turn this on,
1579 put into @file{.emacs}: @code{(require 'filladapt)}}, and by exporting them
1580 properly (@pxref{Exporting}). Since indentation is what governs the
1581 structure of these lists, many structural constructs like @code{#+BEGIN_...}
1582 blocks can be indented to signal that they belong to a particular item.
1583
1584 @vindex org-list-demote-modify-bullet
1585 @vindex org-list-indent-offset
1586 If you find that using a different bullet for a sub-list (than that used for
1587 the current list-level) improves readability, customize the variable
1588 @code{org-list-demote-modify-bullet}. To get a greater difference of
1589 indentation between items and theirs sub-items, customize
1590 @code{org-list-indent-offset}.
1591
1592 @vindex org-list-automatic-rules
1593 The following commands act on items when the cursor is in the first line of
1594 an item (the line with the bullet or number). Some of them imply the
1595 application of automatic rules to keep list structure intact. If some of
1596 these actions get in your way, configure @code{org-list-automatic-rules}
1597 to disable them individually.
1598
1599 @table @asis
1600 @orgcmd{@key{TAB},org-cycle}
1601 @vindex org-cycle-include-plain-lists
1602 Items can be folded just like headline levels. Normally this works only if
1603 the cursor is on a plain list item. For more details, see the variable
1604 @code{org-cycle-include-plain-lists}. If this variable is set to
1605 @code{integrate}, plain list items will be treated like low-level
1606 headlines. The level of an item is then given by the
1607 indentation of the bullet/number. Items are always subordinate to real
1608 headlines, however; the hierarchies remain completely separated.
1609 @orgcmd{M-@key{RET},org-insert-heading}
1610 @vindex org-M-RET-may-split-line
1611 @vindex org-list-automatic-rules
1612 Insert new item at current level. With a prefix argument, force a new
1613 heading (@pxref{Structure editing}). If this command is used in the middle
1614 of an item, that item is @emph{split} in two, and the second part becomes the
1615 new item@footnote{If you do not want the item to be split, customize the
1616 variable @code{org-M-RET-may-split-line}.}. If this command is executed
1617 @emph{before item's body}, the new item is created @emph{before} the current
1618 one.
1619 @kindex M-S-@key{RET}
1620 @item M-S-@key{RET}
1621 Insert a new item with a checkbox (@pxref{Checkboxes}).
1622 @orgcmd{@key{TAB},org-cycle}
1623 In a new item with no text yet, the first @key{TAB} demotes the item to
1624 become a child of the previous one. Subsequent @key{TAB}s move the item to
1625 meaningful levels in the list and eventually get it back to its initial
1626 position.
1627 @kindex S-@key{down}
1628 @item S-@key{up}
1629 @itemx S-@key{down}
1630 @cindex shift-selection-mode
1631 @vindex org-support-shift-select
1632 @vindex org-list-use-circular-motion
1633 Jump to the previous/next item in the current list@footnote{If you want to
1634 cycle around items that way, you may customize
1635 @code{org-list-use-circular-motion}.}, but only if
1636 @code{org-support-shift-select} is off. If not, you can still use paragraph
1637 jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
1638 similar effect.
1639 @kindex M-@key{up}
1640 @kindex M-@key{down}
1641 @item M-@key{up}
1642 @itemx M-@key{down}
1643 Move the item including subitems up/down@footnote{See
1644 @code{org-liste-use-circular-motion} for a cyclic behavior.} (swap with
1645 previous/next item of same indentation). If the list is ordered, renumbering
1646 is automatic.
1647 @kindex M-@key{left}
1648 @kindex M-@key{right}
1649 @item M-@key{left}
1650 @itemx M-@key{right}
1651 Decrease/increase the indentation of an item, leaving children alone.
1652 @kindex M-S-@key{left}
1653 @kindex M-S-@key{right}
1654 @item M-S-@key{left}
1655 @itemx M-S-@key{right}
1656 Decrease/increase the indentation of the item, including subitems.
1657 Initially, the item tree is selected based on current indentation. When
1658 these commands are executed several times in direct succession, the initially
1659 selected region is used, even if the new indentation would imply a different
1660 hierarchy. To use the new hierarchy, break the command chain with a cursor
1661 motion or so.
1662
1663 As a special case, using this command on the very first item of a list will
1664 move the whole list. This behavior can be disabled by configuring
1665 @code{org-list-automatic-rules}. The global indentation of a list has no
1666 influence on the text @emph{after} the list.
1667 @kindex C-c C-c
1668 @item C-c C-c
1669 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1670 state of the checkbox. In any case, verify bullets and indentation
1671 consistency in the whole list.
1672 @kindex C-c -
1673 @vindex org-plain-list-ordered-item-terminator
1674 @vindex org-list-automatic-rules
1675 @item C-c -
1676 Cycle the entire list level through the different itemize/enumerate bullets
1677 (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
1678 depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
1679 and its position@footnote{See @code{bullet} rule in
1680 @code{org-list-automatic-rules} for more information.}. With a numeric
1681 prefix argument N, select the Nth bullet from this list. If there is an
1682 active region when calling this, selected text will be changed into an item.
1683 With a prefix argument, all lines will be converted to list items. If the
1684 first line already was a list item, any item marker will be removed from the
1685 list. Finally, even without an active region, a normal line will be
1686 converted into a list item.
1687 @kindex C-c *
1688 @item C-c *
1689 Turn a plain list item into a headline (so that it becomes a subheading at
1690 its location). @xref{Structure editing}, for a detailed explanation.
1691 @kindex C-c C-*
1692 @item C-c C-*
1693 Turn the whole plain list into a subtree of the current heading. Checkboxes
1694 (@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
1695 (resp. checked).
1696 @kindex S-@key{left}
1697 @kindex S-@key{right}
1698 @item S-@key{left}/@key{right}
1699 @vindex org-support-shift-select
1700 This command also cycles bullet styles when the cursor in on the bullet or
1701 anywhere in an item line, details depending on
1702 @code{org-support-shift-select}.
1703 @kindex C-c ^
1704 @item C-c ^
1705 Sort the plain list. You will be prompted for the sorting method:
1706 numerically, alphabetically, by time, or by custom function.
1707 @end table
1708
1709 @node Drawers, Blocks, Plain lists, Document Structure
1710 @section Drawers
1711 @cindex drawers
1712 @cindex #+DRAWERS
1713 @cindex visibility cycling, drawers
1714
1715 @vindex org-drawers
1716 Sometimes you want to keep information associated with an entry, but you
1717 normally don't want to see it. For this, Org-mode has @emph{drawers}.
1718 Drawers need to be configured with the variable
1719 @code{org-drawers}@footnote{You can define drawers on a per-file basis
1720 with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers
1721 look like this:
1722
1723 @example
1724 ** This is a headline
1725 Still outside the drawer
1726 :DRAWERNAME:
1727 This is inside the drawer.
1728 :END:
1729 After the drawer.
1730 @end example
1731
1732 Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
1733 show the entry, but keep the drawer collapsed to a single line. In order to
1734 look inside the drawer, you need to move the cursor to the drawer line and
1735 press @key{TAB} there. Org-mode uses the @code{PROPERTIES} drawer for
1736 storing properties (@pxref{Properties and Columns}), and you can also arrange
1737 for state change notes (@pxref{Tracking TODO state changes}) and clock times
1738 (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
1739 want to store a quick note in the LOGBOOK drawer, in a similar way to state changes, use
1740
1741 @table @kbd
1742 @kindex C-c C-z
1743 @item C-c C-z
1744 Add a time-stamped note to the LOGBOOK drawer.
1745 @end table
1746
1747 @node Blocks, Footnotes, Drawers, Document Structure
1748 @section Blocks
1749
1750 @vindex org-hide-block-startup
1751 @cindex blocks, folding
1752 Org-mode uses begin...end blocks for various purposes from including source
1753 code examples (@pxref{Literal examples}) to capturing time logging
1754 information (@pxref{Clocking work time}). These blocks can be folded and
1755 unfolded by pressing TAB in the begin line. You can also get all blocks
1756 folded at startup by configuring the variable @code{org-hide-block-startup}
1757 or on a per-file basis by using
1758
1759 @cindex @code{hideblocks}, STARTUP keyword
1760 @cindex @code{nohideblocks}, STARTUP keyword
1761 @example
1762 #+STARTUP: hideblocks
1763 #+STARTUP: nohideblocks
1764 @end example
1765
1766 @node Footnotes, Orgstruct mode, Blocks, Document Structure
1767 @section Footnotes
1768 @cindex footnotes
1769
1770 Org-mode supports the creation of footnotes. In contrast to the
1771 @file{footnote.el} package, Org-mode's footnotes are designed for work on a
1772 larger document, not only for one-off documents like emails. The basic
1773 syntax is similar to the one used by @file{footnote.el}, i.e.@: a footnote is
1774 defined in a paragraph that is started by a footnote marker in square
1775 brackets in column 0, no indentation allowed. If you need a paragraph break
1776 inside a footnote, use the @LaTeX{} idiom @samp{\par}. The footnote reference
1777 is simply the marker in square brackets, inside text. For example:
1778
1779 @example
1780 The Org homepage[fn:1] now looks a lot better than it used to.
1781 ...
1782 [fn:1] The link is: http://orgmode.org
1783 @end example
1784
1785 Org-mode extends the number-based syntax to @emph{named} footnotes and
1786 optional inline definition. Using plain numbers as markers (as
1787 @file{footnote.el} does) is supported for backward compatibility, but not
1788 encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded
1789 LaTeX}). Here are the valid references:
1790
1791 @table @code
1792 @item [1]
1793 A plain numeric footnote marker. Compatible with @file{footnote.el}, but not
1794 recommended because something like @samp{[1]} could easily be part of a code
1795 snippet.
1796 @item [fn:name]
1797 A named footnote reference, where @code{name} is a unique label word, or, for
1798 simplicity of automatic creation, a number.
1799 @item [fn:: This is the inline definition of this footnote]
1800 A @LaTeX{}-like anonymous footnote where the definition is given directly at the
1801 reference point.
1802 @item [fn:name: a definition]
1803 An inline definition of a footnote, which also specifies a name for the note.
1804 Since Org allows multiple references to the same note, you can then use
1805 @code{[fn:name]} to create additional references.
1806 @end table
1807
1808 @vindex org-footnote-auto-label
1809 Footnote labels can be created automatically, or you can create names yourself.
1810 This is handled by the variable @code{org-footnote-auto-label} and its
1811 corresponding @code{#+STARTUP} keywords. See the docstring of that variable
1812 for details.
1813
1814 @noindent The following command handles footnotes:
1815
1816 @table @kbd
1817 @kindex C-c C-x f
1818 @item C-c C-x f
1819 The footnote action command.
1820
1821 When the cursor is on a footnote reference, jump to the definition. When it
1822 is at a definition, jump to the (first) reference.
1823
1824 @vindex org-footnote-define-inline
1825 @vindex org-footnote-section
1826 @vindex org-footnote-auto-adjust
1827 Otherwise, create a new footnote. Depending on the variable
1828 @code{org-footnote-define-inline}@footnote{The corresponding in-buffer
1829 setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
1830 definition will be placed right into the text as part of the reference, or
1831 separately into the location determined by the variable
1832 @code{org-footnote-section}.
1833
1834 When this command is called with a prefix argument, a menu of additional
1835 options is offered:
1836 @example
1837 s @r{Sort the footnote definitions by reference sequence. During editing,}
1838 @r{Org makes no effort to sort footnote definitions into a particular}
1839 @r{sequence. If you want them sorted, use this command, which will}
1840 @r{also move entries according to @code{org-footnote-section}. Automatic}
1841 @r{sorting after each insertion/deletion can be configured using the}
1842 @r{variable @code{org-footnote-auto-adjust}.}
1843 r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering}
1844 @r{after each insertion/deletion can be configured using the variable}
1845 @r{@code{org-footnote-auto-adjust}.}
1846 S @r{Short for first @code{r}, then @code{s} action.}
1847 n @r{Normalize the footnotes by collecting all definitions (including}
1848 @r{inline definitions) into a special section, and then numbering them}
1849 @r{in sequence. The references will then also be numbers. This is}
1850 @r{meant to be the final step before finishing a document (e.g.@: sending}
1851 @r{off an email). The exporters do this automatically, and so could}
1852 @r{something like @code{message-send-hook}.}
1853 d @r{Delete the footnote at point, and all definitions of and references}
1854 @r{to it.}
1855 @end example
1856 Depending on the variable @code{org-footnote-auto-adjust}@footnote{the
1857 corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},
1858 renumbering and sorting footnotes can be automatic after each insertion or
1859 deletion.
1860
1861 @kindex C-c C-c
1862 @item C-c C-c
1863 If the cursor is on a footnote reference, jump to the definition. If it is a
1864 the definition, jump back to the reference. When called at a footnote
1865 location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
1866 @kindex C-c C-o
1867 @kindex mouse-1
1868 @kindex mouse-2
1869 @item C-c C-o @r{or} mouse-1/2
1870 Footnote labels are also links to the corresponding definition/reference, and
1871 you can use the usual commands to follow these links.
1872 @end table
1873
1874 @node Orgstruct mode, , Footnotes, Document Structure
1875 @section The Orgstruct minor mode
1876 @cindex Orgstruct mode
1877 @cindex minor mode for structure editing
1878
1879 If you like the intuitive way the Org-mode structure editing and list
1880 formatting works, you might want to use these commands in other modes like
1881 Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes
1882 this possible. Toggle the mode with @kbd{M-x orgstruct-mode}, or
1883 turn it on by default, for example in Message mode, with one of:
1884
1885 @lisp
1886 (add-hook 'message-mode-hook 'turn-on-orgstruct)
1887 (add-hook 'message-mode-hook 'turn-on-orgstruct++)
1888 @end lisp
1889
1890 When this mode is active and the cursor is on a line that looks to Org like a
1891 headline or the first line of a list item, most structure editing commands
1892 will work, even if the same keys normally have different functionality in the
1893 major mode you are using. If the cursor is not in one of those special
1894 lines, Orgstruct mode lurks silently in the shadows. When you use
1895 @code{orgstruct++-mode}, Org will also export indentation and autofill
1896 settings into that mode, and detect item context after the first line of an
1897 item.
1898
1899 @node Tables, Hyperlinks, Document Structure, Top
1900 @chapter Tables
1901 @cindex tables
1902 @cindex editing tables
1903
1904 Org comes with a fast and intuitive table editor. Spreadsheet-like
1905 calculations are supported using the Emacs @file{calc} package
1906 @ifinfo
1907 (@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}).
1908 @end ifinfo
1909 @ifnotinfo
1910 (see the Emacs Calculator manual for more information about the Emacs
1911 calculator).
1912 @end ifnotinfo
1913
1914 @menu
1915 * Built-in table editor:: Simple tables
1916 * Column width and alignment:: Overrule the automatic settings
1917 * Column groups:: Grouping to trigger vertical lines
1918 * Orgtbl mode:: The table editor as minor mode
1919 * The spreadsheet:: The table editor has spreadsheet capabilities
1920 * Org-Plot:: Plotting from org tables
1921 @end menu
1922
1923 @node Built-in table editor, Column width and alignment, Tables, Tables
1924 @section The built-in table editor
1925 @cindex table editor, built-in
1926
1927 Org makes it easy to format tables in plain ASCII. Any line with @samp{|} as
1928 the first non-whitespace character is considered part of a table. @samp{|}
1929 is also the column separator@footnote{To insert a vertical bar into a table
1930 field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table
1931 might look like this:
1932
1933 @example
1934 | Name | Phone | Age |
1935 |-------+-------+-----|
1936 | Peter | 1234 | 17 |
1937 | Anna | 4321 | 25 |
1938 @end example
1939
1940 A table is re-aligned automatically each time you press @key{TAB} or
1941 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
1942 the next field (@key{RET} to the next row) and creates new table rows
1943 at the end of the table or before horizontal lines. The indentation
1944 of the table is set by the first line. Any line starting with
1945 @samp{|-} is considered as a horizontal separator line and will be
1946 expanded on the next re-align to span the whole table width. So, to
1947 create the above table, you would only type
1948
1949 @example
1950 |Name|Phone|Age|
1951 |-
1952 @end example
1953
1954 @noindent and then press @key{TAB} to align the table and start filling in
1955 fields. Even faster would be to type @code{|Name|Phone|Age} followed by
1956 @kbd{C-c @key{RET}}.
1957
1958 @vindex org-enable-table-editor
1959 @vindex org-table-auto-blank-field
1960 When typing text into a field, Org treats @key{DEL},
1961 @key{Backspace}, and all character keys in a special way, so that
1962 inserting and deleting avoids shifting other fields. Also, when
1963 typing @emph{immediately after the cursor was moved into a new field
1964 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
1965 field is automatically made blank. If this behavior is too
1966 unpredictable for you, configure the variables
1967 @code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
1968
1969 @table @kbd
1970 @tsubheading{Creation and conversion}
1971 @orgcmd{C-c |,org-table-create-or-convert-from-region}
1972 Convert the active region to table. If every line contains at least one
1973 TAB character, the function assumes that the material is tab separated.
1974 If every line contains a comma, comma-separated values (CSV) are assumed.
1975 If not, lines are split at whitespace into fields. You can use a prefix
1976 argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
1977 C-u} forces TAB, and a numeric argument N indicates that at least N
1978 consecutive spaces, or alternatively a TAB will be the separator.
1979 @*
1980 If there is no active region, this command creates an empty Org
1981 table. But it is easier just to start typing, like
1982 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
1983
1984 @tsubheading{Re-aligning and field motion}
1985 @orgcmd{C-c C-c,org-table-align}
1986 Re-align the table without moving the cursor.
1987 @c
1988 @orgcmd{<TAB>,org-table-next-field}
1989 Re-align the table, move to the next field. Creates a new row if
1990 necessary.
1991 @c
1992 @orgcmd{S-@key{TAB},org-table-previous-field}
1993 Re-align, move to previous field.
1994 @c
1995 @orgcmd{@key{RET},org-table-next-row}
1996 Re-align the table and move down to next row. Creates a new row if
1997 necessary. At the beginning or end of a line, @key{RET} still does
1998 NEWLINE, so it can be used to split a table.
1999 @c
2000 @orgcmd{M-a,org-table-beginning-of-field}
2001 Move to beginning of the current table field, or on to the previous field.
2002 @orgcmd{M-e,org-table-end-of-field}
2003 Move to end of the current table field, or on to the next field.
2004
2005 @tsubheading{Column and row editing}
2006 @orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
2007 Move the current column left/right.
2008 @c
2009 @orgcmd{M-S-@key{left},org-table-delete-column}
2010 Kill the current column.
2011 @c
2012 @orgcmd{M-S-@key{right},org-table-insert-column}
2013 Insert a new column to the left of the cursor position.
2014 @c
2015 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
2016 Move the current row up/down.
2017 @c
2018 @orgcmd{M-S-@key{up},org-table-kill-row}
2019 Kill the current row or horizontal line.
2020 @c
2021 @orgcmd{M-S-@key{down},org-table-insert-row}
2022 Insert a new row above the current row. With a prefix argument, the line is
2023 created below the current one.
2024 @c
2025 @orgcmd{C-c -,org-table-insert-hline}
2026 Insert a horizontal line below current row. With a prefix argument, the line
2027 is created above the current line.
2028 @c
2029 @orgcmd{C-c @key{RET},org-table-hline-and-move}
2030 Insert a horizontal line below current row, and move the cursor into the row
2031 below that line.
2032 @c
2033 @orgcmd{C-c ^,org-table-sort-lines}
2034 Sort the table lines in the region. The position of point indicates the
2035 column to be used for sorting, and the range of lines is the range
2036 between the nearest horizontal separator lines, or the entire table. If
2037 point is before the first column, you will be prompted for the sorting
2038 column. If there is an active region, the mark specifies the first line
2039 and the sorting column, while point should be in the last line to be
2040 included into the sorting. The command prompts for the sorting type
2041 (alphabetically, numerically, or by time). When called with a prefix
2042 argument, alphabetic sorting will be case-sensitive.
2043
2044 @tsubheading{Regions}
2045 @orgcmd{C-c C-x M-w,org-table-copy-region}
2046 Copy a rectangular region from a table to a special clipboard. Point and
2047 mark determine edge fields of the rectangle. If there is no active region,
2048 copy just the current field. The process ignores horizontal separator lines.
2049 @c
2050 @orgcmd{C-c C-x C-w,org-table-cut-region}
2051 Copy a rectangular region from a table to a special clipboard, and
2052 blank all fields in the rectangle. So this is the ``cut'' operation.
2053 @c
2054 @orgcmd{C-c C-x C-y,org-table-paste-rectangle}
2055 Paste a rectangular region into a table.
2056 The upper left corner ends up in the current field. All involved fields
2057 will be overwritten. If the rectangle does not fit into the present table,
2058 the table is enlarged as needed. The process ignores horizontal separator
2059 lines.
2060 @c
2061 @orgcmd{M-@key{RET},org-table-wrap-region}
2062 Split the current field at the cursor position and move the rest to the line
2063 below. If there is an active region, and both point and mark are in the same
2064 column, the text in the column is wrapped to minimum width for the given
2065 number of lines. A numeric prefix argument may be used to change the number
2066 of desired lines. If there is no region, but you specify a prefix argument,
2067 the current field is made blank, and the content is appended to the field
2068 above.
2069
2070 @tsubheading{Calculations}
2071 @cindex formula, in tables
2072 @cindex calculations, in tables
2073 @cindex region, active
2074 @cindex active region
2075 @cindex transient mark mode
2076 @orgcmd{C-c +,org-table-sum}
2077 Sum the numbers in the current column, or in the rectangle defined by
2078 the active region. The result is shown in the echo area and can
2079 be inserted with @kbd{C-y}.
2080 @c
2081 @orgcmd{S-@key{RET},org-table-copy-down}
2082 @vindex org-table-copy-increment
2083 When current field is empty, copy from first non-empty field above. When not
2084 empty, copy current field down to next row and move cursor along with it.
2085 Depending on the variable @code{org-table-copy-increment}, integer field
2086 values will be incremented during copy. Integers that are too large will not
2087 be incremented. Also, a @code{0} prefix argument temporarily disables the
2088 increment. This key is also used by shift-selection and related modes
2089 (@pxref{Conflicts}).
2090
2091 @tsubheading{Miscellaneous}
2092 @orgcmd{C-c `,org-table-edit-field}
2093 Edit the current field in a separate window. This is useful for fields that
2094 are not fully visible (@pxref{Column width and alignment}). When called with
2095 a @kbd{C-u} prefix, just make the full field visible, so that it can be
2096 edited in place. When called with two @kbd{C-u} prefixes, make the editor
2097 window follow the cursor through the table and always show the current
2098 field. The follow mode exits automatically when the cursor leaves the table,
2099 or when you repeat this command with @kbd{C-u C-u C-c `}.
2100 @c
2101 @item M-x org-table-import
2102 Import a file as a table. The table should be TAB or whitespace
2103 separated. Use, for example, to import a spreadsheet table or data
2104 from a database, because these programs generally can write
2105 TAB-separated text files. This command works by inserting the file into
2106 the buffer and then converting the region to a table. Any prefix
2107 argument is passed on to the converter, which uses it to determine the
2108 separator.
2109 @orgcmd{C-c |,org-table-create-or-convert-from-region}
2110 Tables can also be imported by pasting tabular text into the Org
2111 buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
2112 @kbd{C-c |} command (see above under @i{Creation and conversion}).
2113 @c
2114 @item M-x org-table-export
2115 @findex org-table-export
2116 @vindex org-table-export-default-format
2117 Export the table, by default as a TAB-separated file. Use for data
2118 exchange with, for example, spreadsheet or database programs. The format
2119 used to export the file can be configured in the variable
2120 @code{org-table-export-default-format}. You may also use properties
2121 @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
2122 name and the format for table export in a subtree. Org supports quite
2123 general formats for exported tables. The exporter format is the same as the
2124 format used by Orgtbl radio tables, see @ref{Translator functions}, for a
2125 detailed description.
2126 @end table
2127
2128 If you don't like the automatic table editor because it gets in your
2129 way on lines which you would like to start with @samp{|}, you can turn
2130 it off with
2131
2132 @lisp
2133 (setq org-enable-table-editor nil)
2134 @end lisp
2135
2136 @noindent Then the only table command that still works is
2137 @kbd{C-c C-c} to do a manual re-align.
2138
2139 @node Column width and alignment, Column groups, Built-in table editor, Tables
2140 @section Column width and alignment
2141 @cindex narrow columns in tables
2142 @cindex alignment in tables
2143
2144 The width of columns is automatically determined by the table editor. And
2145 also the alignment of a column is determined automatically from the fraction
2146 of number-like versus non-number fields in the column.
2147
2148 Sometimes a single field or a few fields need to carry more text, leading to
2149 inconveniently wide columns. Or maybe you want to make a table with several
2150 columns having a fixed width, regardless of content. To set@footnote{This
2151 feature does not work on XEmacs.} the width of a column, one field anywhere
2152 in the column may contain just the string @samp{<N>} where @samp{N} is an
2153 integer specifying the width of the column in characters. The next re-align
2154 will then set the width of this column to this value.
2155
2156 @example
2157 @group
2158 |---+------------------------------| |---+--------|
2159 | | | | | <6> |
2160 | 1 | one | | 1 | one |
2161 | 2 | two | ----\ | 2 | two |
2162 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
2163 | 4 | four | | 4 | four |
2164 |---+------------------------------| |---+--------|
2165 @end group
2166 @end example
2167
2168 @noindent
2169 Fields that are wider become clipped and end in the string @samp{=>}.
2170 Note that the full text is still in the buffer but is hidden.
2171 To see the full text, hold the mouse over the field---a tool-tip window
2172 will show the full content. To edit such a field, use the command
2173 @kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will
2174 open a new window with the full field. Edit it and finish with @kbd{C-c
2175 C-c}.
2176
2177 @vindex org-startup-align-all-tables
2178 When visiting a file containing a table with narrowed columns, the
2179 necessary character hiding has not yet happened, and the table needs to
2180 be aligned before it looks nice. Setting the option
2181 @code{org-startup-align-all-tables} will realign all tables in a file
2182 upon visiting, but also slow down startup. You can also set this option
2183 on a per-file basis with:
2184
2185 @example
2186 #+STARTUP: align
2187 #+STARTUP: noalign
2188 @end example
2189
2190 If you would like to overrule the automatic alignment of number-rich columns
2191 to the right and of string-rich column to the left, you can use @samp{<r>},
2192 @samp{c}@footnote{Centering does not work inside Emacs, but it does have an
2193 effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may
2194 also combine alignment and field width like this: @samp{<l10>}.
2195
2196 Lines which only contain these formatting cookies will be removed
2197 automatically when exporting the document.
2198
2199 @node Column groups, Orgtbl mode, Column width and alignment, Tables
2200 @section Column groups
2201 @cindex grouping columns in tables
2202
2203 When Org exports tables, it does so by default without vertical
2204 lines because that is visually more satisfying in general. Occasionally
2205 however, vertical lines can be useful to structure a table into groups
2206 of columns, much like horizontal lines can do for groups of rows. In
2207 order to specify column groups, you can use a special row where the
2208 first field contains only @samp{/}. The further fields can either
2209 contain @samp{<} to indicate that this column should start a group,
2210 @samp{>} to indicate the end of a column, or @samp{<>} to make a column
2211 a group of its own. Boundaries between column groups will upon export be
2212 marked with vertical lines. Here is an example:
2213
2214 @example
2215 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2216 |---+-----+-----+-----+---------+------------|
2217 | / | < | | > | < | > |
2218 | 1 | 1 | 1 | 1 | 1 | 1 |
2219 | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
2220 | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
2221 |---+-----+-----+-----+---------+------------|
2222 #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
2223 @end example
2224
2225 It is also sufficient to just insert the column group starters after
2226 every vertical line you would like to have:
2227
2228 @example
2229 | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
2230 |----+-----+-----+-----+---------+------------|
2231 | / | < | | | < | |
2232 @end example
2233
2234 @node Orgtbl mode, The spreadsheet, Column groups, Tables
2235 @section The Orgtbl minor mode
2236 @cindex Orgtbl mode
2237 @cindex minor mode for tables
2238
2239 If you like the intuitive way the Org table editor works, you
2240 might also want to use it in other modes like Text mode or Mail mode.
2241 The minor mode Orgtbl mode makes this possible. You can always toggle
2242 the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for
2243 example in Message mode, use
2244
2245 @lisp
2246 (add-hook 'message-mode-hook 'turn-on-orgtbl)
2247 @end lisp
2248
2249 Furthermore, with some special setup, it is possible to maintain tables
2250 in arbitrary syntax with Orgtbl mode. For example, it is possible to
2251 construct @LaTeX{} tables with the underlying ease and power of
2252 Orgtbl mode, including spreadsheet capabilities. For details, see
2253 @ref{Tables in arbitrary syntax}.
2254
2255 @node The spreadsheet, Org-Plot, Orgtbl mode, Tables
2256 @section The spreadsheet
2257 @cindex calculations, in tables
2258 @cindex spreadsheet capabilities
2259 @cindex @file{calc} package
2260
2261 The table editor makes use of the Emacs @file{calc} package to implement
2262 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
2263 derive fields from other fields. While fully featured, Org's implementation
2264 is not identical to other spreadsheets. For example, Org knows the concept
2265 of a @emph{column formula} that will be applied to all non-header fields in a
2266 column without having to copy the formula to each relevant field. There is
2267 also a formula debugger, and a formula editor with features for highlighting
2268 fields in the table corresponding to the references at the point in the
2269 formula, moving these references by arrow keys
2270
2271 @menu
2272 * References:: How to refer to another field or range
2273 * Formula syntax for Calc:: Using Calc to compute stuff
2274 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
2275 * Durations and time values:: How to compute durations and time values
2276 * Field and range formulas:: Formula for specific (ranges of) fields
2277 * Column formulas:: Formulas valid for an entire column
2278 * Editing and debugging formulas:: Fixing formulas
2279 * Updating the table:: Recomputing all dependent fields
2280 * Advanced features:: Field names, parameters and automatic recalc
2281 @end menu
2282
2283 @node References, Formula syntax for Calc, The spreadsheet, The spreadsheet
2284 @subsection References
2285 @cindex references
2286
2287 To compute fields in the table from other fields, formulas must
2288 reference other fields or ranges. In Org, fields can be referenced
2289 by name, by absolute coordinates, and by relative coordinates. To find
2290 out what the coordinates of a field are, press @kbd{C-c ?} in that
2291 field, or press @kbd{C-c @}} to toggle the display of a grid.
2292
2293 @subsubheading Field references
2294 @cindex field references
2295 @cindex references, to fields
2296
2297 Formulas can reference the value of another field in two ways. Like in
2298 any other spreadsheet, you may reference fields with a letter/number
2299 combination like @code{B3}, meaning the 2nd field in the 3rd row.
2300 @vindex org-table-use-standard-references
2301 However, Org prefers@footnote{Org will understand references typed by the
2302 user as @samp{B4}, but it will not use this syntax when offering a formula
2303 for editing. You can customize this behavior using the variable
2304 @code{org-table-use-standard-references}.} to use another, more general
2305 representation that looks like this:
2306 @example
2307 @@@var{row}$@var{column}
2308 @end example
2309
2310 Column specifications can be absolute like @code{$1},
2311 @code{$2},...@code{$@var{N}}, or relative to the current column (i.e.@: the
2312 column of the field which is being computed) like @code{$+1} or @code{$-2}.
2313 @code{$<} and @code{$>} are immutable references to the first and last
2314 column, respectively, and you can use @code{$>>>} to indicate the third
2315 column from the right.
2316
2317 The row specification only counts data lines and ignores horizontal separator
2318 lines (hlines). Like with columns, you can use absolute row numbers
2319 @code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
2320 current row like @code{@@+3} or @code{@@-1}. @code{@@<} and @code{@@>} are
2321 immutable references the first and last@footnote{For backward compatibility
2322 you can also use special names like @code{$LR5} and @code{$LR12} to refer in
2323 a stable way to the 5th and 12th field in the last row of the table.
2324 However, this syntax is deprecated, it should not be used for new documents.
2325 Use @code{@@>$} instead.} row in the table, respectively. You may also
2326 specify the row relative to one of the hlines: @code{@@I} refers to the first
2327 hline, @code{@@II} to the second, etc@. @code{@@-I} refers to the first such
2328 line above the current line, @code{@@+I} to the first such line below the
2329 current line. You can also write @code{@@III+2} which is the second data line
2330 after the third hline in the table.
2331
2332 @code{@@0} and @code{$0} refer to the current row and column, respectively,
2333 i.e. to the row/column for the field being computed. Also, if you omit
2334 either the column or the row part of the reference, the current row/column is
2335 implied.
2336
2337 Org's references with @emph{unsigned} numbers are fixed references
2338 in the sense that if you use the same reference in the formula for two
2339 different fields, the same field will be referenced each time.
2340 Org's references with @emph{signed} numbers are floating
2341 references because the same reference operator can reference different
2342 fields depending on the field being calculated by the formula.
2343
2344 Here are a few examples:
2345
2346 @example
2347 @@2$3 @r{2nd row, 3rd column (same as @code{C2})}
2348 $5 @r{column 5 in the current row (same as @code{E&})}
2349 @@2 @r{current column, row 2}
2350 @@-1$-3 @r{the field one row up, three columns to the left}
2351 @@-I$2 @r{field just under hline above current row, column 2}
2352 @@>$5 @r{field in the last row, in column 5}
2353 @end example
2354
2355 @subsubheading Range references
2356 @cindex range references
2357 @cindex references, to ranges
2358
2359 You may reference a rectangular range of fields by specifying two field
2360 references connected by two dots @samp{..}. If both fields are in the
2361 current row, you may simply use @samp{$2..$7}, but if at least one field
2362 is in a different row, you need to use the general @code{@@row$column}
2363 format at least for the first field (i.e the reference must start with
2364 @samp{@@} in order to be interpreted correctly). Examples:
2365
2366 @example
2367 $1..$3 @r{first three fields in the current row}
2368 $P..$Q @r{range, using column names (see under Advanced)}
2369 $<<<..$>> @r{start in third column, continue to the one but last}
2370 @@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
2371 @@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row}
2372 @@I..II @r{between first and second hline, short for @code{@@I..@@II}}
2373 @end example
2374
2375 @noindent Range references return a vector of values that can be fed
2376 into Calc vector functions. Empty fields in ranges are normally
2377 suppressed, so that the vector contains only the non-empty fields (but
2378 see the @samp{E} mode switch below). If there are no non-empty fields,
2379 @samp{[0]} is returned to avoid syntax errors in formulas.
2380
2381 @subsubheading Field coordinates in formulas
2382 @cindex field coordinates
2383 @cindex coordinates, of field
2384 @cindex row, of field coordinates
2385 @cindex column, of field coordinates
2386
2387 For Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used to
2388 get the row or column number of the field where the formula result goes.
2389 The traditional Lisp formula equivalents are @code{org-table-current-dline}
2390 and @code{org-table-current-column}. Examples:
2391
2392 @example
2393 if(@@# % 2, $#, string("")) @r{column number on odd lines only}
2394 $3 = remote(FOO, @@@@#$2) @r{copy column 2 from table FOO into}
2395 @r{column 3 of the current table}
2396 @end example
2397
2398 @noindent For the second example, table FOO must have at least as many rows
2399 as the current table. Note that this is inefficient@footnote{The computation time scales as
2400 O(N^2) because table FOO is parsed for each field to be copied.} for large
2401 number of rows.
2402
2403 @subsubheading Named references
2404 @cindex named references
2405 @cindex references, named
2406 @cindex name, of column or field
2407 @cindex constants, in calculations
2408 @cindex #+CONSTANTS
2409
2410 @vindex org-table-formula-constants
2411 @samp{$name} is interpreted as the name of a column, parameter or
2412 constant. Constants are defined globally through the variable
2413 @code{org-table-formula-constants}, and locally (for the file) through a
2414 line like
2415
2416 @example
2417 #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
2418 @end example
2419
2420 @noindent
2421 @vindex constants-unit-system
2422 @pindex constants.el
2423 Also properties (@pxref{Properties and Columns}) can be used as
2424 constants in table formulas: for a property @samp{:Xyz:} use the name
2425 @samp{$PROP_Xyz}, and the property will be searched in the current
2426 outline entry and in the hierarchy above it. If you have the
2427 @file{constants.el} package, it will also be used to resolve constants,
2428 including natural constants like @samp{$h} for Planck's constant, and
2429 units like @samp{$km} for kilometers@footnote{@file{constants.el} can
2430 supply the values of constants in two different unit systems, @code{SI}
2431 and @code{cgs}. Which one is used depends on the value of the variable
2432 @code{constants-unit-system}. You can use the @code{#+STARTUP} options
2433 @code{constSI} and @code{constcgs} to set this value for the current
2434 buffer.}. Column names and parameters can be specified in special table
2435 lines. These are described below, see @ref{Advanced features}. All
2436 names must start with a letter, and further consist of letters and
2437 numbers.
2438
2439 @subsubheading Remote references
2440 @cindex remote references
2441 @cindex references, remote
2442 @cindex references, to a different table
2443 @cindex name, of column or field
2444 @cindex constants, in calculations
2445 @cindex #+TBLNAME
2446
2447 You may also reference constants, fields and ranges from a different table,
2448 either in the current file or even in a different file. The syntax is
2449
2450 @example
2451 remote(NAME-OR-ID,REF)
2452 @end example
2453
2454 @noindent
2455 where NAME can be the name of a table in the current file as set by a
2456 @code{#+TBLNAME: NAME} line before the table. It can also be the ID of an
2457 entry, even in a different file, and the reference then refers to the first
2458 table in that entry. REF is an absolute field or range reference as
2459 described above for example @code{@@3$3} or @code{$somename}, valid in the
2460 referenced table.
2461
2462 @node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet
2463 @subsection Formula syntax for Calc
2464 @cindex formula syntax, Calc
2465 @cindex syntax, of formulas
2466
2467 A formula can be any algebraic expression understood by the Emacs
2468 @file{Calc} package. @b{Note that @file{calc} has the
2469 non-standard convention that @samp{/} has lower precedence than
2470 @samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before
2471 evaluation by @code{calc-eval} (@pxref{Calling Calc from
2472 Your Programs,calc-eval,Calling Calc from Your Lisp Programs,Calc,GNU
2473 Emacs Calc Manual}),
2474 @c FIXME: The link to the Calc manual in HTML does not work.
2475 variable substitution takes place according to the rules described above.
2476 @cindex vectors, in table calculations
2477 The range vectors can be directly fed into the Calc vector functions
2478 like @samp{vmean} and @samp{vsum}.
2479
2480 @cindex format specifier
2481 @cindex mode, for @file{calc}
2482 @vindex org-calc-default-modes
2483 A formula can contain an optional mode string after a semicolon. This
2484 string consists of flags to influence Calc and other modes during
2485 execution. By default, Org uses the standard Calc modes (precision
2486 12, angular units degrees, fraction and symbolic modes off). The display
2487 format, however, has been changed to @code{(float 8)} to keep tables
2488 compact. The default settings can be configured using the variable
2489 @code{org-calc-default-modes}.
2490
2491 @example
2492 p20 @r{set the internal Calc calculation precision to 20 digits}
2493 n3 s3 e2 f4 @r{Normal, scientific, engineering, or fixed}
2494 @r{format of the result of Calc passed back to Org.}
2495 @r{Calc formatting is unlimited in precision as}
2496 @r{long as the Calc calculation precision is greater.}
2497 D R @r{angle modes: degrees, radians}
2498 F S @r{fraction and symbolic modes}
2499 N @r{interpret all fields as numbers, use 0 for non-numbers}
2500 E @r{keep empty fields in ranges}
2501 L @r{literal}
2502 @end example
2503
2504 @noindent
2505 Unless you use large integer numbers or high-precision-calculation
2506 and -display for floating point numbers you may alternatively provide a
2507 @code{printf} format specifier to reformat the Calc result after it has been
2508 passed back to Org instead of letting Calc already do the
2509 formatting@footnote{The @code{printf} reformatting is limited in precision
2510 because the value passed to it is converted into an @code{integer} or
2511 @code{double}. The @code{integer} is limited in size by truncating the
2512 signed value to 32 bits. The @code{double} is limited in precision to 64
2513 bits overall which leaves approximately 16 significant decimal digits.}.
2514 A few examples:
2515
2516 @example
2517 $1+$2 @r{Sum of first and second field}
2518 $1+$2;%.2f @r{Same, format result to two decimals}
2519 exp($2)+exp($1) @r{Math functions can be used}
2520 $0;%.1f @r{Reformat current cell to 1 decimal}
2521 ($3-32)*5/9 @r{Degrees F -> C conversion}
2522 $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
2523 tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
2524 sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
2525 vmean($2..$7) @r{Compute column range mean, using vector function}
2526 vmean($2..$7);EN @r{Same, but treat empty fields as 0}
2527 taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree}
2528 @end example
2529
2530 Calc also contains a complete set of logical operations. For example
2531
2532 @example
2533 if($1<20,teen,string("")) @r{"teen" if age $1 less than 20, else empty}
2534 @end example
2535
2536 Note that you can also use two org-specific flags @code{T} and @code{t} for
2537 durations computations @ref{Durations and time values}.
2538
2539 @node Formula syntax for Lisp, Durations and time values, Formula syntax for Calc, The spreadsheet
2540 @subsection Emacs Lisp forms as formulas
2541 @cindex Lisp forms, as table formulas
2542
2543 It is also possible to write a formula in Emacs Lisp; this can be useful for
2544 string manipulation and control structures, if Calc's functionality is not
2545 enough. If a formula starts with a single-quote followed by an opening
2546 parenthesis, then it is evaluated as a Lisp form. The evaluation should
2547 return either a string or a number. Just as with @file{calc} formulas, you
2548 can specify modes and a printf format after a semicolon. With Emacs Lisp
2549 forms, you need to be conscious about the way field references are
2550 interpolated into the form. By default, a reference will be interpolated as
2551 a Lisp string (in double-quotes) containing the field. If you provide the
2552 @samp{N} mode switch, all referenced elements will be numbers (non-number
2553 fields will be zero) and interpolated as Lisp numbers, without quotes. If
2554 you provide the @samp{L} flag, all fields will be interpolated literally,
2555 without quotes. I.e., if you want a reference to be interpreted as a string
2556 by the Lisp form, enclose the reference operator itself in double-quotes,
2557 like @code{"$3"}. Ranges are inserted as space-separated fields, so you can
2558 embed them in list or vector syntax. Here are a few examples---note how the
2559 @samp{N} mode is used when we do computations in Lisp:
2560
2561 @example
2562 @r{Swap the first two characters of the content of column 1}
2563 '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
2564 @r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}}
2565 '(+ $1 $2);N
2566 @r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}}
2567 '(apply '+ '($1..$4));N
2568 @end example
2569
2570 @node Durations and time values, Field and range formulas, Formula syntax for Lisp, The spreadsheet
2571 @subsection Durations and time values
2572 @cindex Duration, computing
2573 @cindex Time, computing
2574 @vindex org-table-duration-custom-format
2575
2576 If you want to compute time values use the @code{T} flag, either in Calc
2577 formulas or Elisp formulas:
2578
2579 @example
2580 @group
2581 | Task 1 | Task 2 | Total |
2582 |---------+----------+----------|
2583 | 2:12 | 1:47 | 03:59:00 |
2584 | 3:02:20 | -2:07:00 | 0.92 |
2585 #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;t
2586 @end group
2587 @end example
2588
2589 Input duration values must be of the form @code{[HH:MM[:SS]}, where seconds
2590 are optional. With the @code{T} flag, computed durations will be displayed
2591 as @code{[HH:MM:SS} (see the first formula above). With the @code{t} flag,
2592 computed durations will be displayed according to the value of the variable
2593 @code{org-table-duration-custom-format}, which defaults to @code{'hours} and
2594 will display the result as a fraction of hours (see the second formula in the
2595 example above).
2596
2597 Negative duration values can be manipulated as well, and integers will be
2598 considered as seconds in addition and subtraction.
2599
2600 @node Field and range formulas, Column formulas, Durations and time values, The spreadsheet
2601 @subsection Field and range formulas
2602 @cindex field formula
2603 @cindex range formula
2604 @cindex formula, for individual table field
2605 @cindex formula, for range of fields
2606
2607 To assign a formula to a particular field, type it directly into the field,
2608 preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press
2609 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2610 the formula will be stored as the formula for this field, evaluated, and the
2611 current field will be replaced with the result.
2612
2613 @cindex #+TBLFM
2614 Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
2615 below the table. If you type the equation in the 4th field of the 3rd data
2616 line in the table, the formula will look like @samp{@@3$4=$1+$2}. When
2617 inserting/deleting/swapping column and rows with the appropriate commands,
2618 @i{absolute references} (but not relative ones) in stored formulas are
2619 modified in order to still reference the same field. To avoid this from
2620 happening, in particular in range references, anchor ranges at the table
2621 borders (using @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines
2622 using the @code{@@I} notation. Automatic adaptation of field references does
2623 of cause not happen if you edit the table structure with normal editing
2624 commands---then you must fix the equations yourself.
2625
2626 Instead of typing an equation into the field, you may also use the following
2627 command
2628
2629 @table @kbd
2630 @orgcmd{C-u C-c =,org-table-eval-formula}
2631 Install a new formula for the current field. The command prompts for a
2632 formula with default taken from the @samp{#+TBLFM:} line, applies
2633 it to the current field, and stores it.
2634 @end table
2635
2636 The left-hand side of a formula can also be a special expression in order to
2637 assign the formula to a number of different fields. There is no keyboard
2638 shortcut to enter such range formulas. To add them, use the formula editor
2639 (@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
2640 directly.
2641
2642 @table @code
2643 @item $2=
2644 Column formula, valid for the entire column. This is so common that Org
2645 treats these formulas in a special way, see @ref{Column formulas}.
2646 @item @@3=
2647 Row formula, applies to all fields in the specified row. @code{@@>=} means
2648 the last row.
2649 @item @@1$2..@@4$3=
2650 Range formula, applies to all fields in the given rectangular range. This
2651 can also be used to assign a formula to some but not all fields in a row.
2652 @item $name=
2653 Named field, see @ref{Advanced features}.
2654 @end table
2655
2656 @node Column formulas, Editing and debugging formulas, Field and range formulas, The spreadsheet
2657 @subsection Column formulas
2658 @cindex column formula
2659 @cindex formula, for table column
2660
2661 When you assign a formula to a simple column reference like @code{$3=}, the
2662 same formula will be used in all fields of that column, with the following
2663 very convenient exceptions: (i) If the table contains horizontal separator
2664 hlines, everything before the first such line is considered part of the table
2665 @emph{header} and will not be modified by column formulas. (ii) Fields that
2666 already get a value from a field/range formula will be left alone by column
2667 formulas. These conditions make column formulas very easy to use.
2668
2669 To assign a formula to a column, type it directly into any field in the
2670 column, preceded by an equal sign, like @samp{=$1+$2}. When you press
2671 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
2672 the formula will be stored as the formula for the current column, evaluated
2673 and the current field replaced with the result. If the field contains only
2674 @samp{=}, the previously stored formula for this column is used. For each
2675 column, Org will only remember the most recently used formula. In the
2676 @samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The
2677 left-hand side of a column formula can not be the name of column, it must be
2678 the numeric column reference or @code{$>}.
2679
2680 Instead of typing an equation into the field, you may also use the
2681 following command:
2682
2683 @table @kbd
2684 @orgcmd{C-c =,org-table-eval-formula}
2685 Install a new formula for the current column and replace current field with
2686 the result of the formula. The command prompts for a formula, with default
2687 taken from the @samp{#+TBLFM} line, applies it to the current field and
2688 stores it. With a numeric prefix argument(e.g.@: @kbd{C-5 C-c =}) the command
2689 will apply it to that many consecutive fields in the current column.
2690 @end table
2691
2692 @node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet
2693 @subsection Editing and debugging formulas
2694 @cindex formula editing
2695 @cindex editing, of table formulas
2696
2697 @vindex org-table-use-standard-references
2698 You can edit individual formulas in the minibuffer or directly in the
2699 field. Org can also prepare a special buffer with all active
2700 formulas of a table. When offering a formula for editing, Org
2701 converts references to the standard format (like @code{B3} or @code{D&})
2702 if possible. If you prefer to only work with the internal format (like
2703 @code{@@3$2} or @code{$4}), configure the variable
2704 @code{org-table-use-standard-references}.
2705
2706 @table @kbd
2707 @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
2708 Edit the formula associated with the current column/field in the
2709 minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}.
2710 @orgcmd{C-u C-u C-c =,org-table-eval-formula}
2711 Re-insert the active formula (either a
2712 field formula, or a column formula) into the current field, so that you
2713 can edit it directly in the field. The advantage over editing in the
2714 minibuffer is that you can use the command @kbd{C-c ?}.
2715 @orgcmd{C-c ?,org-table-field-info}
2716 While editing a formula in a table field, highlight the field(s)
2717 referenced by the reference at the cursor position in the formula.
2718 @kindex C-c @}
2719 @findex org-table-toggle-coordinate-overlays
2720 @item C-c @}
2721 Toggle the display of row and column numbers for a table, using overlays
2722 (@command{org-table-toggle-coordinate-overlays}). These are updated each
2723 time the table is aligned; you can force it with @kbd{C-c C-c}.
2724 @kindex C-c @{
2725 @findex org-table-toggle-formula-debugger
2726 @item C-c @{
2727 Toggle the formula debugger on and off
2728 (@command{org-table-toggle-formula-debugger}). See below.
2729 @orgcmd{C-c ',org-table-edit-formulas}
2730 Edit all formulas for the current table in a special buffer, where the
2731 formulas will be displayed one per line. If the current field has an
2732 active formula, the cursor in the formula editor will mark it.
2733 While inside the special buffer, Org will automatically highlight
2734 any field or range reference at the cursor position. You may edit,
2735 remove and add formulas, and use the following commands:
2736 @table @kbd
2737 @orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
2738 Exit the formula editor and store the modified formulas. With @kbd{C-u}
2739 prefix, also apply the new formulas to the entire table.
2740 @orgcmd{C-c C-q,org-table-fedit-abort}
2741 Exit the formula editor without installing changes.
2742 @orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
2743 Toggle all references in the formula editor between standard (like
2744 @code{B3}) and internal (like @code{@@3$2}).
2745 @orgcmd{@key{TAB},org-table-fedit-lisp-indent}
2746 Pretty-print or indent Lisp formula at point. When in a line containing
2747 a Lisp formula, format the formula according to Emacs Lisp rules.
2748 Another @key{TAB} collapses the formula back again. In the open
2749 formula, @key{TAB} re-indents just like in Emacs Lisp mode.
2750 @orgcmd{M-@key{TAB},lisp-complete-symbol}
2751 Complete Lisp symbols, just like in Emacs Lisp mode.
2752 @kindex S-@key{up}
2753 @kindex S-@key{down}
2754 @kindex S-@key{left}
2755 @kindex S-@key{right}
2756 @findex org-table-fedit-ref-up
2757 @findex org-table-fedit-ref-down
2758 @findex org-table-fedit-ref-left
2759 @findex org-table-fedit-ref-right
2760 @item S-@key{up}/@key{down}/@key{left}/@key{right}
2761 Shift the reference at point. For example, if the reference is
2762 @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
2763 This also works for relative references and for hline references.
2764 @orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
2765 Move the test line for column formulas in the Org buffer up and
2766 down.
2767 @orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
2768 Scroll the window displaying the table.
2769 @kindex C-c @}
2770 @findex org-table-toggle-coordinate-overlays
2771 @item C-c @}
2772 Turn the coordinate grid in the table on and off.
2773 @end table
2774 @end table
2775
2776 Making a table field blank does not remove the formula associated with
2777 the field, because that is stored in a different line (the @samp{#+TBLFM}
2778 line)---during the next recalculation the field will be filled again.
2779 To remove a formula from a field, you have to give an empty reply when
2780 prompted for the formula, or to edit the @samp{#+TBLFM} line.
2781
2782 @kindex C-c C-c
2783 You may edit the @samp{#+TBLFM} directly and re-apply the changed
2784 equations with @kbd{C-c C-c} in that line or with the normal
2785 recalculation commands in the table.
2786
2787 @subsubheading Debugging formulas
2788 @cindex formula debugging
2789 @cindex debugging, of table formulas
2790 When the evaluation of a formula leads to an error, the field content
2791 becomes the string @samp{#ERROR}. If you would like see what is going
2792 on during variable substitution and calculation in order to find a bug,
2793 turn on formula debugging in the @code{Tbl} menu and repeat the
2794 calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
2795 field. Detailed information will be displayed.
2796
2797 @node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet
2798 @subsection Updating the table
2799 @cindex recomputing table fields
2800 @cindex updating, table
2801
2802 Recalculation of a table is normally not automatic, but needs to be
2803 triggered by a command. See @ref{Advanced features}, for a way to make
2804 recalculation at least semi-automatic.
2805
2806 In order to recalculate a line of a table or the entire table, use the
2807 following commands:
2808
2809 @table @kbd
2810 @orgcmd{C-c *,org-table-recalculate}
2811 Recalculate the current row by first applying the stored column formulas
2812 from left to right, and all field/range formulas in the current row.
2813 @c
2814 @kindex C-u C-c *
2815 @item C-u C-c *
2816 @kindex C-u C-c C-c
2817 @itemx C-u C-c C-c
2818 Recompute the entire table, line by line. Any lines before the first
2819 hline are left alone, assuming that these are part of the table header.
2820 @c
2821 @orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
2822 Iterate the table by recomputing it until no further changes occur.
2823 This may be necessary if some computed fields use the value of other
2824 fields that are computed @i{later} in the calculation sequence.
2825 @item M-x org-table-recalculate-buffer-tables
2826 @findex org-table-recalculate-buffer-tables
2827 Recompute all tables in the current buffer.
2828 @item M-x org-table-iterate-buffer-tables
2829 @findex org-table-iterate-buffer-tables
2830 Iterate all tables in the current buffer, in order to converge table-to-table
2831 dependencies.
2832 @end table
2833
2834 @node Advanced features, , Updating the table, The spreadsheet
2835 @subsection Advanced features
2836
2837 If you want the recalculation of fields to happen automatically, or if
2838 you want to be able to assign @i{names} to fields and columns, you need
2839 to reserve the first column of the table for special marking characters.
2840
2841 @table @kbd
2842 @orgcmd{C-#,org-table-rotate-recalc-marks}
2843 Rotate the calculation mark in first column through the states @samp{ },
2844 @samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,
2845 change all marks in the region.
2846 @end table
2847
2848 Here is an example of a table that collects exam results of students and
2849 makes use of these features:
2850
2851 @example
2852 @group
2853 |---+---------+--------+--------+--------+-------+------|
2854 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
2855 |---+---------+--------+--------+--------+-------+------|
2856 | ! | | P1 | P2 | P3 | Tot | |
2857 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
2858 | ^ | | m1 | m2 | m3 | mt | |
2859 |---+---------+--------+--------+--------+-------+------|
2860 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
2861 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
2862 |---+---------+--------+--------+--------+-------+------|
2863 | | Average | | | | 29.7 | |
2864 | ^ | | | | | at | |
2865 | $ | max=50 | | | | | |
2866 |---+---------+--------+--------+--------+-------+------|
2867 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
2868 @end group
2869 @end example
2870
2871 @noindent @b{Important}: please note that for these special tables,
2872 recalculating the table with @kbd{C-u C-c *} will only affect rows that
2873 are marked @samp{#} or @samp{*}, and fields that have a formula assigned
2874 to the field itself. The column formulas are not applied in rows with
2875 empty first field.
2876
2877 @cindex marking characters, tables
2878 The marking characters have the following meaning:
2879 @table @samp
2880 @item !
2881 The fields in this line define names for the columns, so that you may
2882 refer to a column as @samp{$Tot} instead of @samp{$6}.
2883 @item ^
2884 This row defines names for the fields @emph{above} the row. With such
2885 a definition, any formula in the table may use @samp{$m1} to refer to
2886 the value @samp{10}. Also, if you assign a formula to a names field, it
2887 will be stored as @samp{$name=...}.
2888 @item _
2889 Similar to @samp{^}, but defines names for the fields in the row
2890 @emph{below}.
2891 @item $
2892 Fields in this row can define @emph{parameters} for formulas. For
2893 example, if a field in a @samp{$} row contains @samp{max=50}, then
2894 formulas in this table can refer to the value 50 using @samp{$max}.
2895 Parameters work exactly like constants, only that they can be defined on
2896 a per-table basis.
2897 @item #
2898 Fields in this row are automatically recalculated when pressing
2899 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
2900 is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
2901 lines will be left alone by this command.
2902 @item *
2903 Selects this line for global recalculation with @kbd{C-u C-c *}, but
2904 not for automatic recalculation. Use this when automatic
2905 recalculation slows down editing too much.
2906 @item
2907 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
2908 All lines that should be recalculated should be marked with @samp{#}
2909 or @samp{*}.
2910 @item /
2911 Do not export this line. Useful for lines that contain the narrowing
2912 @samp{<N>} markers or column group markers.
2913 @end table
2914
2915 Finally, just to whet your appetite for what can be done with the
2916 fantastic @file{calc.el} package, here is a table that computes the Taylor
2917 series of degree @code{n} at location @code{x} for a couple of
2918 functions.
2919
2920 @example
2921 @group
2922 |---+-------------+---+-----+--------------------------------------|
2923 | | Func | n | x | Result |
2924 |---+-------------+---+-----+--------------------------------------|
2925 | # | exp(x) | 1 | x | 1 + x |
2926 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
2927 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
2928 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
2929 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
2930 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
2931 |---+-------------+---+-----+--------------------------------------|
2932 #+TBLFM: $5=taylor($2,$4,$3);n3
2933 @end group
2934 @end example
2935
2936 @node Org-Plot, , The spreadsheet, Tables
2937 @section Org-Plot
2938 @cindex graph, in tables
2939 @cindex plot tables using Gnuplot
2940 @cindex #+PLOT
2941
2942 Org-Plot can produce 2D and 3D graphs of information stored in org tables
2943 using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
2944 @uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}. To see
2945 this in action, ensure that you have both Gnuplot and Gnuplot mode installed
2946 on your system, then call @code{org-plot/gnuplot} on the following table.
2947
2948 @example
2949 @group
2950 #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
2951 | Sede | Max cites | H-index |
2952 |-----------+-----------+---------|
2953 | Chile | 257.72 | 21.39 |
2954 | Leeds | 165.77 | 19.68 |
2955 | Sao Paolo | 71.00 | 11.50 |
2956 | Stockholm | 134.19 | 14.33 |
2957 | Morelia | 257.56 | 17.67 |
2958 @end group
2959 @end example
2960
2961 Notice that Org Plot is smart enough to apply the table's headers as labels.
2962 Further control over the labels, type, content, and appearance of plots can
2963 be exercised through the @code{#+PLOT:} lines preceding a table. See below
2964 for a complete list of Org-plot options. For more information and examples
2965 see the Org-plot tutorial at
2966 @uref{http://orgmode.org/worg/org-tutorials/org-plot.html}.
2967
2968 @subsubheading Plot Options
2969
2970 @table @code
2971 @item set
2972 Specify any @command{gnuplot} option to be set when graphing.
2973
2974 @item title
2975 Specify the title of the plot.
2976
2977 @item ind
2978 Specify which column of the table to use as the @code{x} axis.
2979
2980 @item deps
2981 Specify the columns to graph as a Lisp style list, surrounded by parentheses
2982 and separated by spaces for example @code{dep:(3 4)} to graph the third and
2983 fourth columns (defaults to graphing all other columns aside from the @code{ind}
2984 column).
2985
2986 @item type
2987 Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
2988
2989 @item with
2990 Specify a @code{with} option to be inserted for every col being plotted
2991 (e.g.@: @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
2992 Defaults to @code{lines}.
2993
2994 @item file
2995 If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
2996
2997 @item labels
2998 List of labels to be used for the @code{deps} (defaults to the column headers
2999 if they exist).
3000
3001 @item line
3002 Specify an entire line to be inserted in the Gnuplot script.
3003
3004 @item map
3005 When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
3006 flat mapping rather than a @code{3d} slope.
3007
3008 @item timefmt
3009 Specify format of Org-mode timestamps as they will be parsed by Gnuplot.
3010 Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
3011
3012 @item script
3013 If you want total control, you can specify a script file (place the file name
3014 between double-quotes) which will be used to plot. Before plotting, every
3015 instance of @code{$datafile} in the specified script will be replaced with
3016 the path to the generated data file. Note: even if you set this option, you
3017 may still want to specify the plot type, as that can impact the content of
3018 the data file.
3019 @end table
3020
3021 @node Hyperlinks, TODO Items, Tables, Top
3022 @chapter Hyperlinks
3023 @cindex hyperlinks
3024
3025 Like HTML, Org provides links inside a file, external links to
3026 other files, Usenet articles, emails, and much more.
3027
3028 @menu
3029 * Link format:: How links in Org are formatted
3030 * Internal links:: Links to other places in the current file
3031 * External links:: URL-like links to the world
3032 * Handling links:: Creating, inserting and following
3033 * Using links outside Org:: Linking from my C source code?
3034 * Link abbreviations:: Shortcuts for writing complex links
3035 * Search options:: Linking to a specific location
3036 * Custom searches:: When the default search is not enough
3037 @end menu
3038
3039 @node Link format, Internal links, Hyperlinks, Hyperlinks
3040 @section Link format
3041 @cindex link format
3042 @cindex format, of links
3043
3044 Org will recognize plain URL-like links and activate them as
3045 clickable links. The general link format, however, looks like this:
3046
3047 @example
3048 [[link][description]] @r{or alternatively} [[link]]
3049 @end example
3050
3051 @noindent
3052 Once a link in the buffer is complete (all brackets present), Org
3053 will change the display so that @samp{description} is displayed instead
3054 of @samp{[[link][description]]} and @samp{link} is displayed instead of
3055 @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
3056 which by default is an underlined face. You can directly edit the
3057 visible part of a link. Note that this can be either the @samp{link}
3058 part (if there is no description) or the @samp{description} part. To
3059 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
3060 cursor on the link.
3061
3062 If you place the cursor at the beginning or just behind the end of the
3063 displayed text and press @key{BACKSPACE}, you will remove the
3064 (invisible) bracket at that location. This makes the link incomplete
3065 and the internals are again displayed as plain text. Inserting the
3066 missing bracket hides the link internals again. To show the
3067 internal structure of all links, use the menu entry
3068 @code{Org->Hyperlinks->Literal links}.
3069
3070 @node Internal links, External links, Link format, Hyperlinks
3071 @section Internal links
3072 @cindex internal links
3073 @cindex links, internal
3074 @cindex targets, for links
3075
3076 @cindex property, CUSTOM_ID
3077 If the link does not look like a URL, it is considered to be internal in the
3078 current file. The most important case is a link like
3079 @samp{[[#my-custom-id]]} which will link to the entry with the
3080 @code{CUSTOM_ID} property @samp{my-custom-id}. Such custom IDs are very good
3081 for HTML export (@pxref{HTML export}) where they produce pretty section
3082 links. You are responsible yourself to make sure these custom IDs are unique
3083 in a file.
3084
3085 Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
3086 lead to a text search in the current file.
3087
3088 The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
3089 or with a mouse click (@pxref{Handling links}). Links to custom IDs will
3090 point to the corresponding headline. The preferred match for a text link is
3091 a @i{dedicated target}: the same string in double angular brackets. Targets
3092 may be located anywhere; sometimes it is convenient to put them into a
3093 comment line. For example
3094
3095 @example
3096 # <<My Target>>
3097 @end example
3098
3099 @noindent In HTML export (@pxref{HTML export}), such targets will become
3100 named anchors for direct access through @samp{http} links@footnote{Note that
3101 text before the first headline is usually not exported, so the first such
3102 target should be after the first headline, or in the line directly before the
3103 first headline.}.
3104
3105 If no dedicated target exists, Org will search for a headline that is exactly
3106 the link text but may also include a TODO keyword and tags@footnote{To insert
3107 a link targeting a headline, in-buffer completion can be used. Just type a
3108 star followed by a few optional letters into the buffer and press
3109 @kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as
3110 completions.}. In non-Org files, the search will look for the words in the
3111 link text. In the above example the search would be for @samp{my target}.
3112
3113 Following a link pushes a mark onto Org's own mark ring. You can
3114 return to the previous position with @kbd{C-c &}. Using this command
3115 several times in direct succession goes back to positions recorded
3116 earlier.
3117
3118 @menu
3119 * Radio targets:: Make targets trigger links in plain text
3120 @end menu
3121
3122 @node Radio targets, , Internal links, Internal links
3123 @subsection Radio targets
3124 @cindex radio targets
3125 @cindex targets, radio
3126 @cindex links, radio targets
3127
3128 Org can automatically turn any occurrences of certain target names
3129 in normal text into a link. So without explicitly creating a link, the
3130 text connects to the target radioing its position. Radio targets are
3131 enclosed by triple angular brackets. For example, a target @samp{<<<My
3132 Target>>>} causes each occurrence of @samp{my target} in normal text to
3133 become activated as a link. The Org file is scanned automatically
3134 for radio targets only when the file is first loaded into Emacs. To
3135 update the target list during editing, press @kbd{C-c C-c} with the
3136 cursor on or at a target.
3137
3138 @node External links, Handling links, Internal links, Hyperlinks
3139 @section External links
3140 @cindex links, external
3141 @cindex external links
3142 @cindex links, external
3143 @cindex Gnus links
3144 @cindex BBDB links
3145 @cindex IRC links
3146 @cindex URL links
3147 @cindex file links
3148 @cindex VM links
3149 @cindex RMAIL links
3150 @cindex WANDERLUST links
3151 @cindex MH-E links
3152 @cindex USENET links
3153 @cindex SHELL links
3154 @cindex Info links
3155 @cindex Elisp links
3156
3157 Org supports links to files, websites, Usenet and email messages,
3158 BBDB database entries and links to both IRC conversations and their
3159 logs. External links are URL-like locators. They start with a short
3160 identifying string followed by a colon. There can be no space after
3161 the colon. The following list shows examples for each link type.
3162
3163 @example
3164 http://www.astro.uva.nl/~dominik @r{on the web}
3165 doi:10.1000/182 @r{DOI for an electronic resource}
3166 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
3167 /home/dominik/images/jupiter.jpg @r{same as above}
3168 file:papers/last.pdf @r{file, relative path}
3169 ./papers/last.pdf @r{same as above}
3170 file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine}
3171 /myself@@some.where:papers/last.pdf @r{same as above}
3172 file:sometextfile::NNN @r{file with line number to jump to}
3173 file:projects.org @r{another Org file}
3174 file:projects.org::some words @r{text search in Org file}
3175 file:projects.org::*task title @r{heading search in Org file}
3176 docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN}
3177 id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
3178 news:comp.emacs @r{Usenet link}
3179 mailto:adent@@galaxy.net @r{Mail link}
3180 vm:folder @r{VM folder link}
3181 vm:folder#id @r{VM message link}
3182 vm://myself@@some.where.org/folder#id @r{VM on remote machine}
3183 wl:folder @r{WANDERLUST folder link}
3184 wl:folder#id @r{WANDERLUST message link}
3185 mhe:folder @r{MH-E folder link}
3186 mhe:folder#id @r{MH-E message link}
3187 rmail:folder @r{RMAIL folder link}
3188 rmail:folder#id @r{RMAIL message link}
3189 gnus:group @r{Gnus group link}
3190 gnus:group#id @r{Gnus article link}
3191 bbdb:R.*Stallman @r{BBDB link (with regexp)}
3192 irc:/irc.com/#emacs/bob @r{IRC link}
3193 info:org#External%20links @r{Info node link (with encoded space)}
3194 shell:ls *.org @r{A shell command}
3195 elisp:org-agenda @r{Interactive Elisp command}
3196 elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
3197 @end example
3198
3199 For customizing Org to add new link types @ref{Adding hyperlink types}.
3200
3201 A link should be enclosed in double brackets and may contain a
3202 descriptive text to be displayed instead of the URL (@pxref{Link
3203 format}), for example:
3204
3205 @example
3206 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
3207 @end example
3208
3209 @noindent
3210 If the description is a file name or URL that points to an image, HTML
3211 export (@pxref{HTML export}) will inline the image as a clickable
3212 button. If there is no description at all and the link points to an
3213 image,
3214 that image will be inlined into the exported HTML file.
3215
3216 @cindex square brackets, around links
3217 @cindex plain text external links
3218 Org also finds external links in the normal text and activates them
3219 as links. If spaces must be part of the link (for example in
3220 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
3221 about the end of the link, enclose them in square brackets.
3222
3223 @node Handling links, Using links outside Org, External links, Hyperlinks
3224 @section Handling links
3225 @cindex links, handling
3226
3227 Org provides methods to create a link in the correct syntax, to
3228 insert it into an Org file, and to follow the link.
3229
3230 @table @kbd
3231 @orgcmd{C-c l,org-store-link}
3232 @cindex storing links
3233 Store a link to the current location. This is a @emph{global} command (you
3234 must create the key binding yourself) which can be used in any buffer to
3235 create a link. The link will be stored for later insertion into an Org
3236 buffer (see below). What kind of link will be created depends on the current
3237 buffer:
3238
3239 @b{Org-mode buffers}@*
3240 For Org files, if there is a @samp{<<target>>} at the cursor, the link points
3241 to the target. Otherwise it points to the current headline, which will also
3242 be the description@footnote{If the headline contains a timestamp, it will be
3243 removed from the link and result in a wrong link -- you should avoid putting
3244 timestamp in the headline.}.
3245
3246 @vindex org-link-to-org-use-id
3247 @cindex property, CUSTOM_ID
3248 @cindex property, ID
3249 If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
3250 will be stored. In addition or alternatively (depending on the value of
3251 @code{org-link-to-org-use-id}), a globally unique @code{ID} property will be
3252 created and/or used to construct a link. So using this command in Org
3253 buffers will potentially create two links: a human-readable from the custom
3254 ID, and one that is globally unique and works even if the entry is moved from
3255 file to file. Later, when inserting the link, you need to decide which one
3256 to use.
3257
3258 @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
3259 Pretty much all Emacs mail clients are supported. The link will point to the
3260 current article, or, in some GNUS buffers, to the group. The description is
3261 constructed from the author and the subject.
3262
3263 @b{Web browsers: W3 and W3M}@*
3264 Here the link will be the current URL, with the page title as description.
3265
3266 @b{Contacts: BBDB}@*
3267 Links created in a BBDB buffer will point to the current entry.
3268
3269 @b{Chat: IRC}@*
3270 @vindex org-irc-link-to-logs
3271 For IRC links, if you set the variable @code{org-irc-link-to-logs} to
3272 @code{t}, a @samp{file:/} style link to the relevant point in the logs for
3273 the current conversation is created. Otherwise an @samp{irc:/} style link to
3274 the user/channel/server under the point will be stored.
3275
3276 @b{Other files}@*
3277 For any other files, the link will point to the file, with a search string
3278 (@pxref{Search options}) pointing to the contents of the current line. If
3279 there is an active region, the selected words will form the basis of the
3280 search string. If the automatically created link is not working correctly or
3281 accurately enough, you can write custom functions to select the search string
3282 and to do the search for particular file types---see @ref{Custom searches}.
3283 The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
3284
3285 @b{Agenda view}@*
3286 When the cursor is in an agenda view, the created link points to the
3287 entry referenced by the current line.
3288
3289 @c
3290 @orgcmd{C-c C-l,org-insert-link}
3291 @cindex link completion
3292 @cindex completion, of links
3293 @cindex inserting links
3294 @vindex org-keep-stored-link-after-insertion
3295 Insert a link@footnote{ Note that you don't have to use this command to
3296 insert a link. Links in Org are plain text, and you can type or paste them
3297 straight into the buffer. By using this command, the links are automatically
3298 enclosed in double brackets, and you will be asked for the optional
3299 descriptive text.}. This prompts for a link to be inserted into the buffer.
3300 You can just type a link, using text for an internal link, or one of the link
3301 type prefixes mentioned in the examples above. The link will be inserted
3302 into the buffer@footnote{After insertion of a stored link, the link will be
3303 removed from the list of stored links. To keep it in the list later use, use
3304 a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
3305 @code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
3306 If some text was selected when this command is called, the selected text
3307 becomes the default description.
3308
3309 @b{Inserting stored links}@*
3310 All links stored during the
3311 current session are part of the history for this prompt, so you can access
3312 them with @key{up} and @key{down} (or @kbd{M-p/n}).
3313
3314 @b{Completion support}@* Completion with @key{TAB} will help you to insert
3315 valid link prefixes like @samp{http:} or @samp{ftp:}, including the prefixes
3316 defined through link abbreviations (@pxref{Link abbreviations}). If you
3317 press @key{RET} after inserting only the @var{prefix}, Org will offer
3318 specific completion support for some link types@footnote{This works by
3319 calling a special function @code{org-PREFIX-complete-link}.} For
3320 example, if you type @kbd{file @key{RET}}, file name completion (alternative
3321 access: @kbd{C-u C-c C-l}, see below) will be offered, and after @kbd{bbdb
3322 @key{RET}} you can complete contact names.
3323 @orgkey C-u C-c C-l
3324 @cindex file name completion
3325 @cindex completion, of file names
3326 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
3327 a file will be inserted and you may use file name completion to select
3328 the name of the file. The path to the file is inserted relative to the
3329 directory of the current Org file, if the linked file is in the current
3330 directory or in a sub-directory of it, or if the path is written relative
3331 to the current directory using @samp{../}. Otherwise an absolute path
3332 is used, if possible with @samp{~/} for your home directory. You can
3333 force an absolute path with two @kbd{C-u} prefixes.
3334 @c
3335 @item C-c C-l @ @r{(with cursor on existing link)}
3336 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
3337 link and description parts of the link.
3338 @c
3339 @cindex following links
3340 @orgcmd{C-c C-o,org-open-at-point}
3341 @vindex org-file-apps
3342 Open link at point. This will launch a web browser for URLs (using
3343 @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
3344 the corresponding links, and execute the command in a shell link. When the
3345 cursor is on an internal link, this command runs the corresponding search.
3346 When the cursor is on a TAG list in a headline, it creates the corresponding
3347 TAGS view. If the cursor is on a timestamp, it compiles the agenda for that
3348 date. Furthermore, it will visit text and remote files in @samp{file:} links
3349 with Emacs and select a suitable application for local non-text files.
3350 Classification of files is based on file extension only. See option
3351 @code{org-file-apps}. If you want to override the default application and
3352 visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
3353 opening in Emacs, use a @kbd{C-u C-u} prefix.@*
3354 If the cursor is on a headline, but not on a link, offer all links in the
3355 headline and entry text.
3356 @orgkey @key{RET}
3357 @vindex org-return-follows-link
3358 When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
3359 the link at point.
3360 @c
3361 @kindex mouse-2
3362 @kindex mouse-1
3363 @item mouse-2
3364 @itemx mouse-1
3365 On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
3366 would. Under Emacs 22 and later, @kbd{mouse-1} will also follow a link.
3367 @c
3368 @kindex mouse-3
3369 @item mouse-3
3370 @vindex org-display-internal-link-with-indirect-buffer
3371 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
3372 internal links to be displayed in another window@footnote{See the
3373 variable @code{org-display-internal-link-with-indirect-buffer}}.
3374 @c
3375 @orgcmd{C-c C-x C-v,org-toggle-inline-images}
3376 @cindex inlining images
3377 @cindex images, inlining
3378 @vindex org-startup-with-inline-images
3379 @cindex @code{inlineimages}, STARTUP keyword
3380 @cindex @code{noinlineimages}, STARTUP keyword
3381 Toggle the inline display of linked images. Normally this will only inline
3382 images that have no description part in the link, i.e.@: images that will also
3383 be inlined during export. When called with a prefix argument, also display
3384 images that do have a link description. You can ask for inline images to be
3385 displayed at startup by configuring the variable
3386 @code{org-startup-with-inline-images}@footnote{with corresponding
3387 @code{#+STARTUP} keywords @code{inlineimages} and @code{inlineimages}}.
3388 @orgcmd{C-c %,org-mark-ring-push}
3389 @cindex mark ring
3390 Push the current position onto the mark ring, to be able to return
3391 easily. Commands following an internal link do this automatically.
3392 @c
3393 @orgcmd{C-c &,org-mark-ring-goto}
3394 @cindex links, returning to
3395 Jump back to a recorded position. A position is recorded by the
3396 commands following internal links, and by @kbd{C-c %}. Using this
3397 command several times in direct succession moves through a ring of
3398 previously recorded positions.
3399 @c
3400 @orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
3401 @cindex links, finding next/previous
3402 Move forward/backward to the next link in the buffer. At the limit of
3403 the buffer, the search fails once, and then wraps around. The key
3404 bindings for this are really too long; you might want to bind this also
3405 to @kbd{C-n} and @kbd{C-p}
3406 @lisp
3407 (add-hook 'org-load-hook
3408 (lambda ()
3409 (define-key org-mode-map "\C-n" 'org-next-link)
3410 (define-key org-mode-map "\C-p" 'org-previous-link)))
3411 @end lisp
3412 @end table
3413
3414 @node Using links outside Org, Link abbreviations, Handling links, Hyperlinks
3415 @section Using links outside Org
3416
3417 You can insert and follow links that have Org syntax not only in
3418 Org, but in any Emacs buffer. For this, you should create two
3419 global commands, like this (please select suitable global keys
3420 yourself):
3421
3422 @lisp
3423 (global-set-key "\C-c L" 'org-insert-link-global)
3424 (global-set-key "\C-c o" 'org-open-at-point-global)
3425 @end lisp
3426
3427 @node Link abbreviations, Search options, Using links outside Org, Hyperlinks
3428 @section Link abbreviations
3429 @cindex link abbreviations
3430 @cindex abbreviation, links
3431
3432 Long URLs can be cumbersome to type, and often many similar links are
3433 needed in a document. For this you can use link abbreviations. An
3434 abbreviated link looks like this
3435
3436 @example
3437 [[linkword:tag][description]]
3438 @end example
3439
3440 @noindent
3441 @vindex org-link-abbrev-alist
3442 where the tag is optional.
3443 The @i{linkword} must be a word, starting with a letter, followed by
3444 letters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolved
3445 according to the information in the variable @code{org-link-abbrev-alist}
3446 that relates the linkwords to replacement text. Here is an example:
3447
3448 @smalllisp
3449 @group
3450 (setq org-link-abbrev-alist
3451 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
3452 ("google" . "http://www.google.com/search?q=")
3453 ("gmap" . "http://maps.google.com/maps?q=%s")
3454 ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
3455 ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
3456 @end group
3457 @end smalllisp
3458
3459 If the replacement text contains the string @samp{%s}, it will be
3460 replaced with the tag. Otherwise the tag will be appended to the string
3461 in order to create the link. You may also specify a function that will
3462 be called with the tag as the only argument to create the link.
3463
3464 With the above setting, you could link to a specific bug with
3465 @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
3466 @code{[[google:OrgMode]]}, show the map location of the Free Software
3467 Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
3468 @code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
3469 what the Org author is doing besides Emacs hacking with
3470 @code{[[ads:Dominik,C]]}.
3471
3472 If you need special abbreviations just for a single Org buffer, you
3473 can define them in the file with
3474
3475 @cindex #+LINK
3476 @example
3477 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
3478 #+LINK: google http://www.google.com/search?q=%s
3479 @end example
3480
3481 @noindent
3482 In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
3483 complete link abbreviations. You may also define a function
3484 @code{org-PREFIX-complete-link} that implements special (e.g.@: completion)
3485 support for inserting such a link with @kbd{C-c C-l}. Such a function should
3486 not accept any arguments, and return the full link with prefix.
3487
3488 @node Search options, Custom searches, Link abbreviations, Hyperlinks
3489 @section Search options in file links
3490 @cindex search option in file links
3491 @cindex file links, searching
3492
3493 File links can contain additional information to make Emacs jump to a
3494 particular location in the file when following a link. This can be a
3495 line number or a search option after a double@footnote{For backward
3496 compatibility, line numbers can also follow a single colon.} colon. For
3497 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
3498 links}) to a file, it encodes the words in the current line as a search
3499 string that can be used to find this line back later when following the
3500 link with @kbd{C-c C-o}.
3501
3502 Here is the syntax of the different ways to attach a search to a file
3503 link, together with an explanation:
3504
3505 @example
3506 [[file:~/code/main.c::255]]
3507 [[file:~/xx.org::My Target]]
3508 [[file:~/xx.org::*My Target]]
3509 [[file:~/xx.org::#my-custom-id]]
3510 [[file:~/xx.org::/regexp/]]
3511 @end example
3512
3513 @table @code
3514 @item 255
3515 Jump to line 255.
3516 @item My Target
3517 Search for a link target @samp{<<My Target>>}, or do a text search for
3518 @samp{my target}, similar to the search in internal links, see
3519 @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
3520 link will become an HTML reference to the corresponding named anchor in
3521 the linked file.
3522 @item *My Target
3523 In an Org file, restrict search to headlines.
3524 @item #my-custom-id
3525 Link to a heading with a @code{CUSTOM_ID} property
3526 @item /regexp/
3527 Do a regular expression search for @code{regexp}. This uses the Emacs
3528 command @code{occur} to list all matches in a separate window. If the
3529 target file is in Org-mode, @code{org-occur} is used to create a
3530 sparse tree with the matches.
3531 @c If the target file is a directory,
3532 @c @code{grep} will be used to search all files in the directory.
3533 @end table
3534
3535 As a degenerate case, a file link with an empty file name can be used
3536 to search the current file. For example, @code{[[file:::find me]]} does
3537 a search for @samp{find me} in the current file, just as
3538 @samp{[[find me]]} would.
3539
3540 @node Custom searches, , Search options, Hyperlinks
3541 @section Custom Searches
3542 @cindex custom search strings
3543 @cindex search strings, custom
3544
3545 The default mechanism for creating search strings and for doing the
3546 actual search related to a file link may not work correctly in all
3547 cases. For example, Bib@TeX{} database files have many entries like
3548 @samp{year="1993"} which would not result in good search strings,
3549 because the only unique identification for a Bib@TeX{} entry is the
3550 citation key.
3551
3552 @vindex org-create-file-search-functions
3553 @vindex org-execute-file-search-functions
3554 If you come across such a problem, you can write custom functions to set
3555 the right search string for a particular file type, and to do the search
3556 for the string in the file. Using @code{add-hook}, these functions need
3557 to be added to the hook variables
3558 @code{org-create-file-search-functions} and
3559 @code{org-execute-file-search-functions}. See the docstring for these
3560 variables for more information. Org actually uses this mechanism
3561 for Bib@TeX{} database files, and you can use the corresponding code as
3562 an implementation example. See the file @file{org-bibtex.el}.
3563
3564 @node TODO Items, Tags, Hyperlinks, Top
3565 @chapter TODO items
3566 @cindex TODO items
3567
3568 Org-mode does not maintain TODO lists as separate documents@footnote{Of
3569 course, you can make a document that contains only long lists of TODO items,
3570 but this is not required.}. Instead, TODO items are an integral part of the
3571 notes file, because TODO items usually come up while taking notes! With Org
3572 mode, simply mark any entry in a tree as being a TODO item. In this way,
3573 information is not duplicated, and the entire context from which the TODO
3574 item emerged is always present.
3575
3576 Of course, this technique for managing TODO items scatters them
3577 throughout your notes file. Org-mode compensates for this by providing
3578 methods to give you an overview of all the things that you have to do.
3579
3580 @menu
3581 * TODO basics:: Marking and displaying TODO entries
3582 * TODO extensions:: Workflow and assignments
3583 * Progress logging:: Dates and notes for progress
3584 * Priorities:: Some things are more important than others
3585 * Breaking down tasks:: Splitting a task into manageable pieces
3586 * Checkboxes:: Tick-off lists
3587 @end menu
3588
3589 @node TODO basics, TODO extensions, TODO Items, TODO Items
3590 @section Basic TODO functionality
3591
3592 Any headline becomes a TODO item when it starts with the word
3593 @samp{TODO}, for example:
3594
3595 @example
3596 *** TODO Write letter to Sam Fortune
3597 @end example
3598
3599 @noindent
3600 The most important commands to work with TODO entries are:
3601
3602 @table @kbd
3603 @orgcmd{C-c C-t,org-todo}
3604 @cindex cycling, of TODO states
3605 Rotate the TODO state of the current item among
3606
3607 @example
3608 ,-> (unmarked) -> TODO -> DONE --.
3609 '--------------------------------'
3610 @end example
3611
3612 The same rotation can also be done ``remotely'' from the timeline and
3613 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
3614
3615 @orgkey{C-u C-c C-t}
3616 Select a specific keyword using completion or (if it has been set up)
3617 the fast selection interface. For the latter, you need to assign keys
3618 to TODO states, see @ref{Per-file keywords}, and @ref{Setting tags}, for
3619 more information.
3620
3621 @kindex S-@key{right}
3622 @kindex S-@key{left}
3623 @item S-@key{right} @ @r{/} @ S-@key{left}
3624 @vindex org-treat-S-cursor-todo-selection-as-state-change
3625 Select the following/preceding TODO state, similar to cycling. Useful
3626 mostly if more than two TODO states are possible (@pxref{TODO
3627 extensions}). See also @ref{Conflicts}, for a discussion of the interaction
3628 with @code{shift-selection-mode}. See also the variable
3629 @code{org-treat-S-cursor-todo-selection-as-state-change}.
3630 @orgcmd{C-c / t,org-show-todo-key}
3631 @cindex sparse tree, for TODO
3632 @vindex org-todo-keywords
3633 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
3634 entire buffer, but shows all TODO items (with not-DONE state) and the
3635 headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
3636 / T}), search for a specific TODO. You will be prompted for the keyword, and
3637 you can also give a list of keywords like @code{KWD1|KWD2|...} to list
3638 entries that match any one of these keywords. With a numeric prefix argument
3639 N, show the tree for the Nth keyword in the variable
3640 @code{org-todo-keywords}. With two prefix arguments, find all TODO states,
3641 both un-done and done.
3642 @orgcmd{C-c a t,org-todo-list}
3643 Show the global TODO list. Collects the TODO items (with not-DONE states)
3644 from all agenda files (@pxref{Agenda Views}) into a single buffer. The new
3645 buffer will be in @code{agenda-mode}, which provides commands to examine and
3646 manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
3647 @xref{Global TODO list}, for more information.
3648 @orgcmd{S-M-@key{RET},org-insert-todo-heading}
3649 Insert a new TODO entry below the current one.
3650 @end table
3651
3652 @noindent
3653 @vindex org-todo-state-tags-triggers
3654 Changing a TODO state can also trigger tag changes. See the docstring of the
3655 option @code{org-todo-state-tags-triggers} for details.
3656
3657 @node TODO extensions, Progress logging, TODO basics, TODO Items
3658 @section Extended use of TODO keywords
3659 @cindex extended TODO keywords
3660
3661 @vindex org-todo-keywords
3662 By default, marked TODO entries have one of only two states: TODO and
3663 DONE. Org-mode allows you to classify TODO items in more complex ways
3664 with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
3665 special setup, the TODO keyword system can work differently in different
3666 files.
3667
3668 Note that @i{tags} are another way to classify headlines in general and
3669 TODO items in particular (@pxref{Tags}).
3670
3671 @menu
3672 * Workflow states:: From TODO to DONE in steps
3673 * TODO types:: I do this, Fred does the rest
3674 * Multiple sets in one file:: Mixing it all, and still finding your way
3675 * Fast access to TODO states:: Single letter selection of a state
3676 * Per-file keywords:: Different files, different requirements
3677 * Faces for TODO keywords:: Highlighting states
3678 * TODO dependencies:: When one task needs to wait for others
3679 @end menu
3680
3681 @node Workflow states, TODO types, TODO extensions, TODO extensions
3682 @subsection TODO keywords as workflow states
3683 @cindex TODO workflow
3684 @cindex workflow states as TODO keywords
3685
3686 You can use TODO keywords to indicate different @emph{sequential} states
3687 in the process of working on an item, for example@footnote{Changing
3688 this variable only becomes effective after restarting Org-mode in a
3689 buffer.}:
3690
3691 @lisp
3692 (setq org-todo-keywords
3693 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
3694 @end lisp
3695
3696 The vertical bar separates the TODO keywords (states that @emph{need
3697 action}) from the DONE states (which need @emph{no further action}). If
3698 you don't provide the separator bar, the last state is used as the DONE
3699 state.
3700 @cindex completion, of TODO keywords
3701 With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
3702 to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may
3703 also use a numeric prefix argument to quickly select a specific state. For
3704 example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
3705 Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
3706 define many keywords, you can use in-buffer completion
3707 (@pxref{Completion}) or even a special one-key selection scheme
3708 (@pxref{Fast access to TODO states}) to insert these words into the
3709 buffer. Changing a TODO state can be logged with a timestamp, see
3710 @ref{Tracking TODO state changes}, for more information.
3711
3712 @node TODO types, Multiple sets in one file, Workflow states, TODO extensions
3713 @subsection TODO keywords as types
3714 @cindex TODO types
3715 @cindex names as TODO keywords
3716 @cindex types as TODO keywords
3717
3718 The second possibility is to use TODO keywords to indicate different
3719 @emph{types} of action items. For example, you might want to indicate
3720 that items are for ``work'' or ``home''. Or, when you work with several
3721 people on a single project, you might want to assign action items
3722 directly to persons, by using their names as TODO keywords. This would
3723 be set up like this:
3724
3725 @lisp
3726 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
3727 @end lisp
3728
3729 In this case, different keywords do not indicate a sequence, but rather
3730 different types. So the normal work flow would be to assign a task to a
3731 person, and later to mark it DONE. Org-mode supports this style by adapting
3732 the workings of the command @kbd{C-c C-t}@footnote{This is also true for the
3733 @kbd{t} command in the timeline and agenda buffers.}. When used several
3734 times in succession, it will still cycle through all names, in order to first
3735 select the right type for a task. But when you return to the item after some
3736 time and execute @kbd{C-c C-t} again, it will switch from any name directly
3737 to DONE. Use prefix arguments or completion to quickly select a specific
3738 name. You can also review the items of a specific TODO type in a sparse tree
3739 by using a numeric prefix to @kbd{C-c / t}. For example, to see all things
3740 Lucy has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items
3741 from all agenda files into a single buffer, you would use the numeric prefix
3742 argument as well when creating the global TODO list: @kbd{C-3 C-c a t}.
3743
3744 @node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions
3745 @subsection Multiple keyword sets in one file
3746 @cindex TODO keyword sets
3747
3748 Sometimes you may want to use different sets of TODO keywords in
3749 parallel. For example, you may want to have the basic
3750 @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
3751 separate state indicating that an item has been canceled (so it is not
3752 DONE, but also does not require action). Your setup would then look
3753 like this:
3754
3755 @lisp
3756 (setq org-todo-keywords
3757 '((sequence "TODO" "|" "DONE")
3758 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
3759 (sequence "|" "CANCELED")))
3760 @end lisp
3761
3762 The keywords should all be different, this helps Org-mode to keep track
3763 of which subsequence should be used for a given entry. In this setup,
3764 @kbd{C-c C-t} only operates within a subsequence, so it switches from
3765 @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
3766 (nothing) to @code{REPORT}. Therefore you need a mechanism to initially
3767 select the correct sequence. Besides the obvious ways like typing a
3768 keyword or using completion, you may also apply the following commands:
3769
3770 @table @kbd
3771 @kindex C-S-@key{right}
3772 @kindex C-S-@key{left}
3773 @kindex C-u C-u C-c C-t
3774 @item C-u C-u C-c C-t
3775 @itemx C-S-@key{right}
3776 @itemx C-S-@key{left}
3777 These keys jump from one TODO subset to the next. In the above example,
3778 @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or
3779 @code{DONE} to @code{REPORT}, and any of the words in the second row to
3780 @code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with
3781 @code{shift-selection-mode} (@pxref{Conflicts}).
3782 @kindex S-@key{right}
3783 @kindex S-@key{left}
3784 @item S-@key{right}
3785 @itemx S-@key{left}
3786 @kbd{S-@key{<left>}} and @kbd{S-@key{<right>}} and walk through @emph{all}
3787 keywords from all sets, so for example @kbd{S-@key{<right>}} would switch
3788 from @code{DONE} to @code{REPORT} in the example above. See also
3789 @ref{Conflicts}, for a discussion of the interaction with
3790 @code{shift-selection-mode}.
3791 @end table
3792
3793 @node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions
3794 @subsection Fast access to TODO states
3795
3796 If you would like to quickly change an entry to an arbitrary TODO state
3797 instead of cycling through the states, you can set up keys for
3798 single-letter access to the states. This is done by adding the section
3799 key after each keyword, in parentheses. For example:
3800
3801 @lisp
3802 (setq org-todo-keywords
3803 '((sequence "TODO(t)" "|" "DONE(d)")
3804 (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
3805 (sequence "|" "CANCELED(c)")))
3806 @end lisp
3807
3808 @vindex org-fast-tag-selection-include-todo
3809 If you then press @kbd{C-c C-t} followed by the selection key, the entry
3810 will be switched to this state. @kbd{SPC} can be used to remove any TODO
3811 keyword from an entry.@footnote{Check also the variable
3812 @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
3813 state through the tags interface (@pxref{Setting tags}), in case you like to
3814 mingle the two concepts. Note that this means you need to come up with
3815 unique keys across both sets of keywords.}
3816
3817 @node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions
3818 @subsection Setting up keywords for individual files
3819 @cindex keyword options
3820 @cindex per-file keywords
3821 @cindex #+TODO
3822 @cindex #+TYP_TODO
3823 @cindex #+SEQ_TODO
3824
3825 It can be very useful to use different aspects of the TODO mechanism in
3826 different files. For file-local settings, you need to add special lines
3827 to the file which set the keywords and interpretation for that file
3828 only. For example, to set one of the two examples discussed above, you
3829 need one of the following lines, starting in column zero anywhere in the
3830 file:
3831
3832 @example
3833 #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
3834 @end example
3835 @noindent (you may also write @code{#+SEQ_TODO} to be explicit about the
3836 interpretation, but it means the same as @code{#+TODO}), or
3837 @example
3838 #+TYP_TODO: Fred Sara Lucy Mike | DONE
3839 @end example
3840
3841 A setup for using several sets in parallel would be:
3842
3843 @example
3844 #+TODO: TODO | DONE
3845 #+TODO: REPORT BUG KNOWNCAUSE | FIXED
3846 #+TODO: | CANCELED
3847 @end example
3848
3849 @cindex completion, of option keywords
3850 @kindex M-@key{TAB}
3851 @noindent To make sure you are using the correct keyword, type
3852 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
3853
3854 @cindex DONE, final TODO keyword
3855 Remember that the keywords after the vertical bar (or the last keyword
3856 if no bar is there) must always mean that the item is DONE (although you
3857 may use a different word). After changing one of these lines, use
3858 @kbd{C-c C-c} with the cursor still in the line to make the changes
3859 known to Org-mode@footnote{Org-mode parses these lines only when
3860 Org-mode is activated after visiting a file. @kbd{C-c C-c} with the
3861 cursor in a line starting with @samp{#+} is simply restarting Org-mode
3862 for the current buffer.}.
3863
3864 @node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions
3865 @subsection Faces for TODO keywords
3866 @cindex faces, for TODO keywords
3867
3868 @vindex org-todo @r{(face)}
3869 @vindex org-done @r{(face)}
3870 @vindex org-todo-keyword-faces
3871 Org-mode highlights TODO keywords with special faces: @code{org-todo}
3872 for keywords indicating that an item still has to be acted upon, and
3873 @code{org-done} for keywords indicating that an item is finished. If
3874 you are using more than 2 different states, you might want to use
3875 special faces for some of them. This can be done using the variable
3876 @code{org-todo-keyword-faces}. For example:
3877
3878 @lisp
3879 @group
3880 (setq org-todo-keyword-faces
3881 '(("TODO" . org-warning) ("STARTED" . "yellow")
3882 ("CANCELED" . (:foreground "blue" :weight bold))))
3883 @end group
3884 @end lisp
3885
3886 While using a list with face properties as shown for CANCELED @emph{should}
3887 work, this does not aways seem to be the case. If necessary, define a
3888 special face and use that. A string is interpreted as a color. The variable
3889 @code{org-faces-easy-properties} determines if that color is interpreted as a
3890 foreground or a background color.
3891
3892 @node TODO dependencies, , Faces for TODO keywords, TODO extensions
3893 @subsection TODO dependencies
3894 @cindex TODO dependencies
3895 @cindex dependencies, of TODO states
3896
3897 @vindex org-enforce-todo-dependencies
3898 @cindex property, ORDERED
3899 The structure of Org files (hierarchy and lists) makes it easy to define TODO
3900 dependencies. Usually, a parent TODO task should not be marked DONE until
3901 all subtasks (defined as children tasks) are marked as DONE. And sometimes
3902 there is a logical sequence to a number of (sub)tasks, so that one task
3903 cannot be acted upon before all siblings above it are done. If you customize
3904 the variable @code{org-enforce-todo-dependencies}, Org will block entries
3905 from changing state to DONE while they have children that are not DONE.
3906 Furthermore, if an entry has a property @code{ORDERED}, each of its children
3907 will be blocked until all earlier siblings are marked DONE. Here is an
3908 example:
3909
3910 @example
3911 * TODO Blocked until (two) is done
3912 ** DONE one
3913 ** TODO two
3914
3915 * Parent
3916 :PROPERTIES:
3917 :ORDERED: t
3918 :END:
3919 ** TODO a
3920 ** TODO b, needs to wait for (a)
3921 ** TODO c, needs to wait for (a) and (b)
3922 @end example
3923
3924 @table @kbd
3925 @orgcmd{C-c C-x o,org-toggle-ordered-property}
3926 @vindex org-track-ordered-property-with-tag
3927 @cindex property, ORDERED
3928 Toggle the @code{ORDERED} property of the current entry. A property is used
3929 for this behavior because this should be local to the current entry, not
3930 inherited like a tag. However, if you would like to @i{track} the value of
3931 this property with a tag for better visibility, customize the variable
3932 @code{org-track-ordered-property-with-tag}.
3933 @orgkey{C-u C-u C-u C-c C-t}
3934 Change TODO state, circumventing any state blocking.
3935 @end table
3936
3937 @vindex org-agenda-dim-blocked-tasks
3938 If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries
3939 that cannot be closed because of such dependencies will be shown in a dimmed
3940 font or even made invisible in agenda views (@pxref{Agenda Views}).
3941
3942 @cindex checkboxes and TODO dependencies
3943 @vindex org-enforce-todo-dependencies
3944 You can also block changes of TODO states by looking at checkboxes
3945 (@pxref{Checkboxes}). If you set the variable
3946 @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
3947 checkboxes will be blocked from switching to DONE.
3948
3949 If you need more complex dependency structures, for example dependencies
3950 between entries in different trees or files, check out the contributed
3951 module @file{org-depend.el}.
3952
3953 @page
3954 @node Progress logging, Priorities, TODO extensions, TODO Items
3955 @section Progress logging
3956 @cindex progress logging
3957 @cindex logging, of progress
3958
3959 Org-mode can automatically record a timestamp and possibly a note when
3960 you mark a TODO item as DONE, or even each time you change the state of
3961 a TODO item. This system is highly configurable, settings can be on a
3962 per-keyword basis and can be localized to a file or even a subtree. For
3963 information on how to clock working time for a task, see @ref{Clocking
3964 work time}.
3965
3966 @menu
3967 * Closing items:: When was this entry marked DONE?
3968 * Tracking TODO state changes:: When did the status change?
3969 * Tracking your habits:: How consistent have you been?
3970 @end menu
3971
3972 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging
3973 @subsection Closing items
3974
3975 The most basic logging is to keep track of @emph{when} a certain TODO
3976 item was finished. This is achieved with@footnote{The corresponding
3977 in-buffer setting is: @code{#+STARTUP: logdone}}
3978
3979 @lisp
3980 (setq org-log-done 'time)
3981 @end lisp
3982
3983 @noindent
3984 Then each time you turn an entry from a TODO (not-done) state into any
3985 of the DONE states, a line @samp{CLOSED: [timestamp]} will be inserted
3986 just after the headline. If you turn the entry back into a TODO item
3987 through further state cycling, that line will be removed again. If you
3988 want to record a note along with the timestamp, use@footnote{The
3989 corresponding in-buffer setting is: @code{#+STARTUP: lognotedone}}
3990
3991 @lisp
3992 (setq org-log-done 'note)
3993 @end lisp
3994
3995 @noindent
3996 You will then be prompted for a note, and that note will be stored below
3997 the entry with a @samp{Closing Note} heading.
3998
3999 In the timeline (@pxref{Timeline}) and in the agenda
4000 (@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key to
4001 display the TODO items with a @samp{CLOSED} timestamp on each day,
4002 giving you an overview of what has been done.
4003
4004 @node Tracking TODO state changes, Tracking your habits, Closing items, Progress logging
4005 @subsection Tracking TODO state changes
4006 @cindex drawer, for state change recording
4007
4008 @vindex org-log-states-order-reversed
4009 @vindex org-log-into-drawer
4010 @cindex property, LOG_INTO_DRAWER
4011 When TODO keywords are used as workflow states (@pxref{Workflow states}), you
4012 might want to keep track of when a state change occurred and maybe take a
4013 note about this change. You can either record just a timestamp, or a
4014 time-stamped note for a change. These records will be inserted after the
4015 headline as an itemized list, newest first@footnote{See the variable
4016 @code{org-log-states-order-reversed}}. When taking a lot of notes, you might
4017 want to get the notes out of the way into a drawer (@pxref{Drawers}).
4018 Customize the variable @code{org-log-into-drawer} to get this
4019 behavior---the recommended drawer for this is called @code{LOGBOOK}. You can
4020 also overrule the setting of this variable for a subtree by setting a
4021 @code{LOG_INTO_DRAWER} property.
4022
4023 Since it is normally too much to record a note for every state, Org-mode
4024 expects configuration on a per-keyword basis for this. This is achieved by
4025 adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note)
4026 in parentheses after each keyword. For example, with the setting
4027
4028 @lisp
4029 (setq org-todo-keywords
4030 '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
4031 @end lisp
4032
4033 @noindent
4034 @vindex org-log-done
4035 you not only define global TODO keywords and fast access keys, but also
4036 request that a time is recorded when the entry is set to
4037 DONE@footnote{It is possible that Org-mode will record two timestamps
4038 when you are using both @code{org-log-done} and state change logging.
4039 However, it will never prompt for two notes---if you have configured
4040 both, the state change recording note will take precedence and cancel
4041 the @samp{Closing Note}.}, and that a note is recorded when switching to
4042 WAIT or CANCELED. The setting for WAIT is even more special: the
4043 @samp{!} after the slash means that in addition to the note taken when
4044 entering the state, a timestamp should be recorded when @i{leaving} the
4045 WAIT state, if and only if the @i{target} state does not configure
4046 logging for entering it. So it has no effect when switching from WAIT
4047 to DONE, because DONE is configured to record a timestamp only. But
4048 when switching from WAIT back to TODO, the @samp{/!} in the WAIT
4049 setting now triggers a timestamp even though TODO has no logging
4050 configured.
4051
4052 You can use the exact same syntax for setting logging preferences local
4053 to a buffer:
4054 @example
4055 #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
4056 @end example
4057
4058 @cindex property, LOGGING
4059 In order to define logging settings that are local to a subtree or a
4060 single item, define a LOGGING property in this entry. Any non-empty
4061 LOGGING property resets all logging settings to nil. You may then turn
4062 on logging for this specific tree using STARTUP keywords like
4063 @code{lognotedone} or @code{logrepeat}, as well as adding state specific
4064 settings like @code{TODO(!)}. For example
4065
4066 @example
4067 * TODO Log each state with only a time
4068 :PROPERTIES:
4069 :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
4070 :END:
4071 * TODO Only log when switching to WAIT, and when repeating
4072 :PROPERTIES:
4073 :LOGGING: WAIT(@@) logrepeat
4074 :END:
4075 * TODO No logging at all
4076 :PROPERTIES:
4077 :LOGGING: nil
4078 :END:
4079 @end example
4080
4081 @node Tracking your habits, , Tracking TODO state changes, Progress logging
4082 @subsection Tracking your habits
4083 @cindex habits
4084
4085 Org has the ability to track the consistency of a special category of TODOs,
4086 called ``habits''. A habit has the following properties:
4087
4088 @enumerate
4089 @item
4090 You have enabled the @code{habits} module by customizing the variable
4091 @code{org-modules}.
4092 @item
4093 The habit is a TODO item, with a TODO keyword representing an open state.
4094 @item
4095 The property @code{STYLE} is set to the value @code{habit}.
4096 @item
4097 The TODO has a scheduled date, usually with a @code{.+} style repeat
4098 interval. A @code{++} style may be appropriate for habits with time
4099 constraints, e.g., must be done on weekends, or a @code{+} style for an
4100 unusual habit that can have a backlog, e.g., weekly reports.
4101 @item
4102 The TODO may also have minimum and maximum ranges specified by using the
4103 syntax @samp{.+2d/3d}, which says that you want to do the task at least every
4104 three days, but at most every two days.
4105 @item
4106 You must also have state logging for the @code{DONE} state enabled, in order
4107 for historical data to be represented in the consistency graph. If it is not
4108 enabled it is not an error, but the consistency graphs will be largely
4109 meaningless.
4110 @end enumerate
4111
4112 To give you an idea of what the above rules look like in action, here's an
4113 actual habit with some history:
4114
4115 @example
4116 ** TODO Shave
4117 SCHEDULED: <2009-10-17 Sat .+2d/4d>
4118 - State "DONE" from "TODO" [2009-10-15 Thu]
4119 - State "DONE" from "TODO" [2009-10-12 Mon]
4120 - State "DONE" from "TODO" [2009-10-10 Sat]
4121 - State "DONE" from "TODO" [2009-10-04 Sun]
4122 - State "DONE" from "TODO" [2009-10-02 Fri]
4123 - State "DONE" from "TODO" [2009-09-29 Tue]
4124 - State "DONE" from "TODO" [2009-09-25 Fri]
4125 - State "DONE" from "TODO" [2009-09-19 Sat]
4126 - State "DONE" from "TODO" [2009-09-16 Wed]
4127 - State "DONE" from "TODO" [2009-09-12 Sat]
4128 :PROPERTIES:
4129 :STYLE: habit
4130 :LAST_REPEAT: [2009-10-19 Mon 00:36]
4131 :END:
4132 @end example
4133
4134 What this habit says is: I want to shave at most every 2 days (given by the
4135 @code{SCHEDULED} date and repeat interval) and at least every 4 days. If
4136 today is the 15th, then the habit first appears in the agenda on Oct 17,
4137 after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
4138 after four days have elapsed.
4139
4140 What's really useful about habits is that they are displayed along with a
4141 consistency graph, to show how consistent you've been at getting that task
4142 done in the past. This graph shows every day that the task was done over the
4143 past three weeks, with colors for each day. The colors used are:
4144
4145 @table @code
4146 @item Blue
4147 If the task wasn't to be done yet on that day.
4148 @item Green
4149 If the task could have been done on that day.
4150 @item Yellow
4151 If the task was going to be overdue the next day.
4152 @item Red
4153 If the task was overdue on that day.
4154 @end table
4155
4156 In addition to coloring each day, the day is also marked with an asterisk if
4157 the task was actually done that day, and an exclamation mark to show where
4158 the current day falls in the graph.
4159
4160 There are several configuration variables that can be used to change the way
4161 habits are displayed in the agenda.
4162
4163 @table @code
4164 @item org-habit-graph-column
4165 The buffer column at which the consistency graph should be drawn. This will
4166 overwrite any text in that column, so it is a good idea to keep your habits'
4167 titles brief and to the point.
4168 @item org-habit-preceding-days
4169 The amount of history, in days before today, to appear in consistency graphs.
4170 @item org-habit-following-days
4171 The number of days after today that will appear in consistency graphs.
4172 @item org-habit-show-habits-only-for-today
4173 If non-nil, only show habits in today's agenda view. This is set to true by
4174 default.
4175 @end table
4176
4177 Lastly, pressing @kbd{K} in the agenda buffer will cause habits to
4178 temporarily be disabled and they won't appear at all. Press @kbd{K} again to
4179 bring them back. They are also subject to tag filtering, if you have habits
4180 which should only be done in certain contexts, for example.
4181
4182 @node Priorities, Breaking down tasks, Progress logging, TODO Items
4183 @section Priorities
4184 @cindex priorities
4185
4186 If you use Org-mode extensively, you may end up with enough TODO items that
4187 it starts to make sense to prioritize them. Prioritizing can be done by
4188 placing a @emph{priority cookie} into the headline of a TODO item, like this
4189
4190 @example
4191 *** TODO [#A] Write letter to Sam Fortune
4192 @end example
4193
4194 @noindent
4195 @vindex org-priority-faces
4196 By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and
4197 @samp{C}. @samp{A} is the highest priority. An entry without a cookie is
4198 treated just like priority @samp{B}. Priorities make a difference only for
4199 sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
4200 have no inherent meaning to Org-mode. The cookies can be highlighted with
4201 special faces by customizing the variable @code{org-priority-faces}.
4202
4203 Priorities can be attached to any outline node; they do not need to be TODO
4204 items.
4205
4206 @table @kbd
4207 @item @kbd{C-c ,}
4208 @kindex @kbd{C-c ,}
4209 @findex org-priority
4210 Set the priority of the current headline (@command{org-priority}). The
4211 command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
4212 When you press @key{SPC} instead, the priority cookie is removed from the
4213 headline. The priorities can also be changed ``remotely'' from the timeline
4214 and agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
4215 @c
4216 @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
4217 @vindex org-priority-start-cycle-with-default
4218 Increase/decrease priority of current headline@footnote{See also the option
4219 @code{org-priority-start-cycle-with-default}.}. Note that these keys are
4220 also used to modify timestamps (@pxref{Creating timestamps}). See also
4221 @ref{Conflicts}, for a discussion of the interaction with
4222 @code{shift-selection-mode}.
4223 @end table
4224
4225 @vindex org-highest-priority
4226 @vindex org-lowest-priority
4227 @vindex org-default-priority
4228 You can change the range of allowed priorities by setting the variables
4229 @code{org-highest-priority}, @code{org-lowest-priority}, and
4230 @code{org-default-priority}. For an individual buffer, you may set
4231 these values (highest, lowest, default) like this (please make sure that
4232 the highest priority is earlier in the alphabet than the lowest
4233 priority):
4234
4235 @cindex #+PRIORITIES
4236 @example
4237 #+PRIORITIES: A C B
4238 @end example
4239
4240 @node Breaking down tasks, Checkboxes, Priorities, TODO Items
4241 @section Breaking tasks down into subtasks
4242 @cindex tasks, breaking down
4243 @cindex statistics, for TODO items
4244
4245 @vindex org-agenda-todo-list-sublevels
4246 It is often advisable to break down large tasks into smaller, manageable
4247 subtasks. You can do this by creating an outline tree below a TODO item,
4248 with detailed subtasks on the tree@footnote{To keep subtasks out of the
4249 global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep
4250 the overview over the fraction of subtasks that are already completed, insert
4251 either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will
4252 be updated each time the TODO status of a child changes, or when pressing
4253 @kbd{C-c C-c} on the cookie. For example:
4254
4255 @example
4256 * Organize Party [33%]
4257 ** TODO Call people [1/2]
4258 *** TODO Peter
4259 *** DONE Sarah
4260 ** TODO Buy food
4261 ** DONE Talk to neighbor
4262 @end example
4263
4264 @cindex property, COOKIE_DATA
4265 If a heading has both checkboxes and TODO children below it, the meaning of
4266 the statistics cookie become ambiguous. Set the property
4267 @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
4268 this issue.
4269
4270 @vindex org-hierarchical-todo-statistics
4271 If you would like to have the statistics cookie count any TODO entries in the
4272 subtree (not just direct children), configure the variable
4273 @code{org-hierarchical-todo-statistics}. To do this for a single subtree,
4274 include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
4275 property.
4276
4277 @example
4278 * Parent capturing statistics [2/20]
4279 :PROPERTIES:
4280 :COOKIE_DATA: todo recursive
4281 :END:
4282 @end example
4283
4284 If you would like a TODO entry to automatically change to DONE
4285 when all children are done, you can use the following setup:
4286
4287 @example
4288 (defun org-summary-todo (n-done n-not-done)
4289 "Switch entry to DONE when all subentries are done, to TODO otherwise."
4290 (let (org-log-done org-log-states) ; turn off logging
4291 (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
4292
4293 (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
4294 @end example
4295
4296
4297 Another possibility is the use of checkboxes to identify (a hierarchy of) a
4298 large number of subtasks (@pxref{Checkboxes}).
4299
4300
4301 @node Checkboxes, , Breaking down tasks, TODO Items
4302 @section Checkboxes
4303 @cindex checkboxes
4304
4305 @vindex org-list-automatic-rules
4306 Every item in a plain list@footnote{With the exception of description
4307 lists. But you can allow it by modifying @code{org-list-automatic-rules}
4308 accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
4309 it with the string @samp{[ ]}. This feature is similar to TODO items
4310 (@pxref{TODO Items}), but is more lightweight. Checkboxes are not included
4311 into the global TODO list, so they are often great to split a task into a
4312 number of simple steps. Or you can use them in a shopping list. To toggle a
4313 checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
4314 @file{org-mouse.el}).
4315
4316 Here is an example of a checkbox list.
4317
4318 @example
4319 * TODO Organize party [2/4]
4320 - [-] call people [1/3]
4321 - [ ] Peter
4322 - [X] Sarah
4323 - [ ] Sam
4324 - [X] order food
4325 - [ ] think about what music to play
4326 - [X] talk to the neighbors
4327 @end example
4328
4329 Checkboxes work hierarchically, so if a checkbox item has children that
4330 are checkboxes, toggling one of the children checkboxes will make the
4331 parent checkbox reflect if none, some, or all of the children are
4332 checked.
4333
4334 @cindex statistics, for checkboxes
4335 @cindex checkbox statistics
4336 @cindex property, COOKIE_DATA
4337 @vindex org-hierarchical-checkbox-statistics
4338 The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
4339 indicating how many checkboxes present in this entry have been checked off,
4340 and the total number of checkboxes present. This can give you an idea on how
4341 many checkboxes remain, even without opening a folded entry. The cookies can
4342 be placed into a headline or into (the first line of) a plain list item.
4343 Each cookie covers checkboxes of direct children structurally below the
4344 headline/item on which the cookie appears@footnote{Set the variable
4345 @code{org-hierarchical-checkbox-statistics} if you want such cookies to
4346 count all checkboxes below the cookie, not just those belonging to direct
4347 children.}. You have to insert the cookie yourself by typing either
4348 @samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}
4349 result, as in the examples above. With @samp{[%]} you get information about
4350 the percentage of checkboxes checked (in the above example, this would be
4351 @samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie can
4352 count either checkboxes below the heading or TODO states of children, and it
4353 will display whatever was changed last. Set the property @code{COOKIE_DATA}
4354 to either @samp{checkbox} or @samp{todo} to resolve this issue.
4355
4356 @cindex blocking, of checkboxes
4357 @cindex checkbox blocking
4358 @cindex property, ORDERED
4359 If the current outline node has an @code{ORDERED} property, checkboxes must
4360 be checked off in sequence, and an error will be thrown if you try to check
4361 off a box while there are unchecked boxes above it.
4362
4363 @noindent The following commands work with checkboxes:
4364
4365 @table @kbd
4366 @orgcmd{C-c C-c,org-toggle-checkbox}
4367 Toggle checkbox status or (with prefix arg) checkbox presence at point. With
4368 double prefix argument, set it to @samp{[-]}, which is considered to be an
4369 intermediate state.
4370 @orgcmd{C-c C-x C-b,org-toggle-checkbox}
4371 Toggle checkbox status or (with prefix arg) checkbox presence at point. With
4372 double prefix argument, set it to @samp{[-]}, which is considered to be an
4373 intermediate state.
4374 @itemize @minus
4375 @item
4376 If there is an active region, toggle the first checkbox in the region
4377 and set all remaining boxes to the same status as the first. With a prefix
4378 arg, add or remove the checkbox for all items in the region.
4379 @item
4380 If the cursor is in a headline, toggle checkboxes in the region between
4381 this headline and the next (so @emph{not} the entire subtree).
4382 @item
4383 If there is no active region, just toggle the checkbox at point.
4384 @end itemize
4385 @orgcmd{M-S-@key{RET},org-insert-todo-heading}
4386 Insert a new item with a checkbox. This works only if the cursor is already
4387 in a plain list item (@pxref{Plain lists}).
4388 @orgcmd{C-c C-x o,org-toggle-ordered-property}
4389 @vindex org-track-ordered-property-with-tag
4390 @cindex property, ORDERED
4391 Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
4392 be checked off in sequence. A property is used for this behavior because
4393 this should be local to the current entry, not inherited like a tag.
4394 However, if you would like to @i{track} the value of this property with a tag
4395 for better visibility, customize the variable
4396 @code{org-track-ordered-property-with-tag}.
4397 @orgcmd{C-c #,org-update-statistics-cookies}
4398 Update the statistics cookie in the current outline entry. When called with
4399 a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are
4400 updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
4401 new ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update when
4402 changing TODO states. If you delete boxes/entries or add/change them by
4403 hand, use this command to get things back into sync.
4404 @end table
4405
4406 @node Tags, Properties and Columns, TODO Items, Top
4407 @chapter Tags
4408 @cindex tags
4409 @cindex headline tagging
4410 @cindex matching, tags
4411 @cindex sparse tree, tag based
4412
4413 An excellent way to implement labels and contexts for cross-correlating
4414 information is to assign @i{tags} to headlines. Org-mode has extensive
4415 support for tags.
4416
4417 @vindex org-tag-faces
4418 Every headline can contain a list of tags; they occur at the end of the
4419 headline. Tags are normal words containing letters, numbers, @samp{_}, and
4420 @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
4421 @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
4422 Tags will by default be in bold face with the same color as the headline.
4423 You may specify special faces for specific tags using the variable
4424 @code{org-tag-faces}, in much the same way as you can for TODO keywords
4425 (@pxref{Faces for TODO keywords}).
4426
4427 @menu
4428 * Tag inheritance:: Tags use the tree structure of the outline
4429 * Setting tags:: How to assign tags to a headline
4430 * Tag searches:: Searching for combinations of tags
4431 @end menu
4432
4433 @node Tag inheritance, Setting tags, Tags, Tags
4434 @section Tag inheritance
4435 @cindex tag inheritance
4436 @cindex inheritance, of tags
4437 @cindex sublevels, inclusion into tags match
4438
4439 @i{Tags} make use of the hierarchical structure of outline trees. If a
4440 heading has a certain tag, all subheadings will inherit the tag as
4441 well. For example, in the list
4442
4443 @example
4444 * Meeting with the French group :work:
4445 ** Summary by Frank :boss:notes:
4446 *** TODO Prepare slides for him :action:
4447 @end example
4448
4449 @noindent
4450 the final heading will have the tags @samp{:work:}, @samp{:boss:},
4451 @samp{:notes:}, and @samp{:action:} even though the final heading is not
4452 explicitly marked with those tags. You can also set tags that all entries in
4453 a file should inherit just as if these tags were defined in a hypothetical
4454 level zero that surrounds the entire file. Use a line like this@footnote{As
4455 with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
4456 changes in the line.}:
4457
4458 @cindex #+FILETAGS
4459 @example
4460 #+FILETAGS: :Peter:Boss:Secret:
4461 @end example
4462
4463 @noindent
4464 @vindex org-use-tag-inheritance
4465 @vindex org-tags-exclude-from-inheritance
4466 To limit tag inheritance to specific tags, or to turn it off entirely, use
4467 the variables @code{org-use-tag-inheritance} and
4468 @code{org-tags-exclude-from-inheritance}.
4469
4470 @vindex org-tags-match-list-sublevels
4471 When a headline matches during a tags search while tag inheritance is turned
4472 on, all the sublevels in the same tree will (for a simple match form) match
4473 as well@footnote{This is only true if the search does not involve more
4474 complex tests including properties (@pxref{Property searches}).}. The list
4475 of matches may then become very long. If you only want to see the first tags
4476 match in a subtree, configure the variable
4477 @code{org-tags-match-list-sublevels} (not recommended).
4478
4479 @node Setting tags, Tag searches, Tag inheritance, Tags
4480 @section Setting tags
4481 @cindex setting tags
4482 @cindex tags, setting
4483
4484 @kindex M-@key{TAB}
4485 Tags can simply be typed into the buffer at the end of a headline.
4486 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
4487 also a special command for inserting tags:
4488
4489 @table @kbd
4490 @orgcmd{C-c C-q,org-set-tags-command}
4491 @cindex completion, of tags
4492 @vindex org-tags-column
4493 Enter new tags for the current headline. Org-mode will either offer
4494 completion or a special single-key interface for setting tags, see
4495 below. After pressing @key{RET}, the tags will be inserted and aligned
4496 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
4497 tags in the current buffer will be aligned to that column, just to make
4498 things look nice. TAGS are automatically realigned after promotion,
4499 demotion, and TODO state changes (@pxref{TODO basics}).
4500 @orgcmd{C-c C-c,org-set-tags-command}
4501 When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
4502 @end table
4503
4504 @vindex org-tag-alist
4505 Org supports tag insertion based on a @emph{list of tags}. By
4506 default this list is constructed dynamically, containing all tags
4507 currently used in the buffer. You may also globally specify a hard list
4508 of tags with the variable @code{org-tag-alist}. Finally you can set
4509 the default tags for a given file with lines like
4510
4511 @cindex #+TAGS
4512 @example
4513 #+TAGS: @@work @@home @@tennisclub
4514 #+TAGS: laptop car pc sailboat
4515 @end example
4516
4517 If you have globally defined your preferred set of tags using the
4518 variable @code{org-tag-alist}, but would like to use a dynamic tag list
4519 in a specific file, add an empty TAGS option line to that file:
4520
4521 @example
4522 #+TAGS:
4523 @end example
4524
4525 @vindex org-tag-persistent-alist
4526 If you have a preferred set of tags that you would like to use in every file,
4527 in addition to those defined on a per-file basis by TAGS option lines, then
4528 you may specify a list of tags with the variable
4529 @code{org-tag-persistent-alist}. You may turn this off on a per-file basis
4530 by adding a STARTUP option line to that file:
4531
4532 @example
4533 #+STARTUP: noptag
4534 @end example
4535
4536 By default Org-mode uses the standard minibuffer completion facilities for
4537 entering tags. However, it also implements another, quicker, tag selection
4538 method called @emph{fast tag selection}. This allows you to select and
4539 deselect tags with just a single key press. For this to work well you should
4540 assign unique letters to most of your commonly used tags. You can do this
4541 globally by configuring the variable @code{org-tag-alist} in your
4542 @file{.emacs} file. For example, you may find the need to tag many items in
4543 different files with @samp{:@@home:}. In this case you can set something
4544 like:
4545
4546 @lisp
4547 (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
4548 @end lisp
4549
4550 @noindent If the tag is only relevant to the file you are working on, then you
4551 can instead set the TAGS option line as:
4552
4553 @example
4554 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
4555 @end example
4556
4557 @noindent The tags interface will show the available tags in a splash
4558 window. If you want to start a new line after a specific tag, insert
4559 @samp{\n} into the tag list
4560
4561 @example
4562 #+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p)
4563 @end example
4564
4565 @noindent or write them in two lines:
4566
4567 @example
4568 #+TAGS: @@work(w) @@home(h) @@tennisclub(t)
4569 #+TAGS: laptop(l) pc(p)
4570 @end example
4571
4572 @noindent
4573 You can also group together tags that are mutually exclusive by using
4574 braces, as in:
4575
4576 @example
4577 #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)
4578 @end example
4579
4580 @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
4581 and @samp{@@tennisclub} should be selected. Multiple such groups are allowed.
4582
4583 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
4584 these lines to activate any changes.
4585
4586 @noindent
4587 To set these mutually exclusive groups in the variable @code{org-tags-alist},
4588 you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
4589 of the braces. Similarly, you can use @code{:newline} to indicate a line
4590 break. The previous example would be set globally by the following
4591 configuration:
4592
4593 @lisp
4594 (setq org-tag-alist '((:startgroup . nil)
4595 ("@@work" . ?w) ("@@home" . ?h)
4596 ("@@tennisclub" . ?t)
4597 (:endgroup . nil)
4598 ("laptop" . ?l) ("pc" . ?p)))
4599 @end lisp
4600
4601 If at least one tag has a selection key then pressing @kbd{C-c C-c} will
4602 automatically present you with a special interface, listing inherited tags,
4603 the tags of the current headline, and a list of all valid tags with
4604 corresponding keys@footnote{Keys will automatically be assigned to tags which
4605 have no configured keys.}. In this interface, you can use the following
4606 keys:
4607
4608 @table @kbd
4609 @item a-z...
4610 Pressing keys assigned to tags will add or remove them from the list of
4611 tags in the current line. Selecting a tag in a group of mutually
4612 exclusive tags will turn off any other tags from that group.
4613 @kindex @key{TAB}
4614 @item @key{TAB}
4615 Enter a tag in the minibuffer, even if the tag is not in the predefined
4616 list. You will be able to complete on all tags present in the buffer.
4617 You can also add several tags: just separate them with a comma.
4618
4619 @kindex @key{SPC}
4620 @item @key{SPC}
4621 Clear all tags for this line.
4622 @kindex @key{RET}
4623 @item @key{RET}
4624 Accept the modified set.
4625 @item C-g
4626 Abort without installing changes.
4627 @item q
4628 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
4629 @item !
4630 Turn off groups of mutually exclusive tags. Use this to (as an
4631 exception) assign several tags from such a group.
4632 @item C-c
4633 Toggle auto-exit after the next change (see below).
4634 If you are using expert mode, the first @kbd{C-c} will display the
4635 selection window.
4636 @end table
4637
4638 @noindent
4639 This method lets you assign tags to a headline with very few keys. With
4640 the above setup, you could clear the current tags and set @samp{@@home},
4641 @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
4642 C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to
4643 @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
4644 alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
4645 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
4646 @key{RET} @key{RET}}.
4647
4648 @vindex org-fast-tag-selection-single-key
4649 If you find that most of the time you need only a single key press to
4650 modify your list of tags, set the variable
4651 @code{org-fast-tag-selection-single-key}. Then you no longer have to
4652 press @key{RET} to exit fast tag selection---it will immediately exit
4653 after the first change. If you then occasionally need more keys, press
4654 @kbd{C-c} to turn off auto-exit for the current tag selection process
4655 (in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c
4656 C-c}). If you set the variable to the value @code{expert}, the special
4657 window is not even shown for single-key tag selection, it comes up only
4658 when you press an extra @kbd{C-c}.
4659
4660 @node Tag searches, , Setting tags, Tags
4661 @section Tag searches
4662 @cindex tag searches
4663 @cindex searching for tags
4664
4665 Once a system of tags has been set up, it can be used to collect related
4666 information into special lists.
4667
4668 @table @kbd
4669 @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
4670 Create a sparse tree with all headlines matching a tags search. With a
4671 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
4672 @orgcmd{C-c a m,org-tags-view}
4673 Create a global list of tag matches from all agenda files.
4674 @xref{Matching tags and properties}.
4675 @orgcmd{C-c a M,org-tags-view}
4676 @vindex org-tags-match-list-sublevels
4677 Create a global list of tag matches from all agenda files, but check
4678 only TODO items and force checking subitems (see variable
4679 @code{org-tags-match-list-sublevels}).
4680 @end table
4681
4682 These commands all prompt for a match string which allows basic Boolean logic
4683 like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
4684 @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
4685 which are tagged, like @samp{Kathy} or @samp{Sally}. The full syntax of the search
4686 string is rich and allows also matching against TODO keywords, entry levels
4687 and properties. For a complete description with many examples, see
4688 @ref{Matching tags and properties}.
4689
4690
4691 @node Properties and Columns, Dates and Times, Tags, Top
4692 @chapter Properties and columns
4693 @cindex properties
4694
4695 Properties are a set of key-value pairs associated with an entry. There
4696 are two main applications for properties in Org-mode. First, properties
4697 are like tags, but with a value. Second, you can use properties to
4698 implement (very basic) database capabilities in an Org buffer. For
4699 an example of the first application, imagine maintaining a file where
4700 you document bugs and plan releases for a piece of software. Instead of
4701 using tags like @code{:release_1:}, @code{:release_2:}, one can use a
4702 property, say @code{:Release:}, that in different subtrees has different
4703 values, such as @code{1.0} or @code{2.0}. For an example of the second
4704 application of properties, imagine keeping track of your music CDs,
4705 where properties could be things such as the album, artist, date of
4706 release, number of tracks, and so on.
4707
4708 Properties can be conveniently edited and viewed in column view
4709 (@pxref{Column view}).
4710
4711 @menu
4712 * Property syntax:: How properties are spelled out
4713 * Special properties:: Access to other Org-mode features
4714 * Property searches:: Matching property values
4715 * Property inheritance:: Passing values down the tree
4716 * Column view:: Tabular viewing and editing
4717 * Property API:: Properties for Lisp programmers
4718 @end menu
4719
4720 @node Property syntax, Special properties, Properties and Columns, Properties and Columns
4721 @section Property syntax
4722 @cindex property syntax
4723 @cindex drawer, for properties
4724
4725 Properties are key-value pairs. They need to be inserted into a special
4726 drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property
4727 is specified on a single line, with the key (surrounded by colons)
4728 first, and the value after it. Here is an example:
4729
4730 @example
4731 * CD collection
4732 ** Classic
4733 *** Goldberg Variations
4734 :PROPERTIES:
4735 :Title: Goldberg Variations
4736 :Composer: J.S. Bach
4737 :Artist: Glen Gould
4738 :Publisher: Deutsche Grammophon
4739 :NDisks: 1
4740 :END:
4741 @end example
4742
4743 You may define the allowed values for a particular property @samp{:Xyz:}
4744 by setting a property @samp{:Xyz_ALL:}. This special property is
4745 @emph{inherited}, so if you set it in a level 1 entry, it will apply to
4746 the entire tree. When allowed values are defined, setting the
4747 corresponding property becomes easier and is less prone to typing
4748 errors. For the example with the CD collection, we can predefine
4749 publishers and the number of disks in a box like this:
4750
4751 @example
4752 * CD collection
4753 :PROPERTIES:
4754 :NDisks_ALL: 1 2 3 4
4755 :Publisher_ALL: "Deutsche Grammophon" Philips EMI
4756 :END:
4757 @end example
4758
4759 If you want to set properties that can be inherited by any entry in a
4760 file, use a line like
4761 @cindex property, _ALL
4762 @cindex #+PROPERTY
4763 @example
4764 #+PROPERTY: NDisks_ALL 1 2 3 4
4765 @end example
4766
4767 @vindex org-global-properties
4768 Property values set with the global variable
4769 @code{org-global-properties} can be inherited by all entries in all
4770 Org files.
4771
4772 @noindent
4773 The following commands help to work with properties:
4774
4775 @table @kbd
4776 @orgcmd{M-@key{TAB},pcomplete}
4777 After an initial colon in a line, complete property keys. All keys used
4778 in the current file will be offered as possible completions.
4779 @orgcmd{C-c C-x p,org-set-property}
4780 Set a property. This prompts for a property name and a value. If
4781 necessary, the property drawer is created as well.
4782 @item M-x org-insert-property-drawer
4783 @findex org-insert-property-drawer
4784 Insert a property drawer into the current entry. The drawer will be
4785 inserted early in the entry, but after the lines with planning
4786 information like deadlines.
4787 @orgcmd{C-c C-c,org-property-action}
4788 With the cursor in a property drawer, this executes property commands.
4789 @orgcmd{C-c C-c s,org-set-property}
4790 Set a property in the current entry. Both the property and the value
4791 can be inserted using completion.
4792 @orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
4793 Switch property at point to the next/previous allowed value.
4794 @orgcmd{C-c C-c d,org-delete-property}
4795 Remove a property from the current entry.
4796 @orgcmd{C-c C-c D,org-delete-property-globally}
4797 Globally remove a property, from all entries in the current file.
4798 @orgcmd{C-c C-c c,org-compute-property-at-point}
4799 Compute the property at point, using the operator and scope from the
4800 nearest column format definition.
4801 @end table
4802
4803 @node Special properties, Property searches, Property syntax, Properties and Columns
4804 @section Special properties
4805 @cindex properties, special
4806
4807 Special properties provide an alternative access method to Org-mode features,
4808 like the TODO state or the priority of an entry, discussed in the previous
4809 chapters. This interface exists so that you can include these states in a
4810 column view (@pxref{Column view}), or to use them in queries. The following
4811 property names are special and (except for @code{:CATEGORY:}) should not be
4812 used as keys in the properties drawer:
4813
4814 @cindex property, special, TODO
4815 @cindex property, special, TAGS
4816 @cindex property, special, ALLTAGS
4817 @cindex property, special, CATEGORY
4818 @cindex property, special, PRIORITY
4819 @cindex property, special, DEADLINE
4820 @cindex property, special, SCHEDULED
4821 @cindex property, special, CLOSED
4822 @cindex property, special, TIMESTAMP
4823 @cindex property, special, TIMESTAMP_IA
4824 @cindex property, special, CLOCKSUM
4825 @cindex property, special, BLOCKED
4826 @c guessing that ITEM is needed in this area; also, should this list be sorted?
4827 @cindex property, special, ITEM
4828 @cindex property, special, FILE
4829 @example
4830 TODO @r{The TODO keyword of the entry.}
4831 TAGS @r{The tags defined directly in the headline.}
4832 ALLTAGS @r{All tags, including inherited ones.}
4833 CATEGORY @r{The category of an entry.}
4834 PRIORITY @r{The priority of the entry, a string with a single letter.}
4835 DEADLINE @r{The deadline time string, without the angular brackets.}
4836 SCHEDULED @r{The scheduling timestamp, without the angular brackets.}
4837 CLOSED @r{When was this entry closed?}
4838 TIMESTAMP @r{The first keyword-less timestamp in the entry.}
4839 TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
4840 CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}}
4841 @r{must be run first to compute the values in the current buffer.}
4842 BLOCKED @r{"t" if task is currently blocked by children or siblings}
4843 ITEM @r{The content of the entry.}
4844 FILE @r{The filename the entry is located in.}
4845 @end example
4846
4847 @node Property searches, Property inheritance, Special properties, Properties and Columns
4848 @section Property searches
4849 @cindex properties, searching
4850 @cindex searching, of properties
4851
4852 To create sparse trees and special lists with selection based on properties,
4853 the same commands are used as for tag searches (@pxref{Tag searches}).
4854 @table @kbd
4855 @orgcmdkkc{C-c / m,C-c \,org-match-sparse-tree}
4856 Create a sparse tree with all matching entries. With a
4857 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
4858 @orgcmd{C-c a m,org-tags-view}
4859 Create a global list of tag/property matches from all agenda files.
4860 @xref{Matching tags and properties}.
4861 @orgcmd{C-c a M,org-tags-view}
4862 @vindex org-tags-match-list-sublevels
4863 Create a global list of tag matches from all agenda files, but check
4864 only TODO items and force checking of subitems (see variable
4865 @code{org-tags-match-list-sublevels}).
4866 @end table
4867
4868 The syntax for the search string is described in @ref{Matching tags and
4869 properties}.
4870
4871 There is also a special command for creating sparse trees based on a
4872 single property:
4873
4874 @table @kbd
4875 @orgkey{C-c / p}
4876 Create a sparse tree based on the value of a property. This first
4877 prompts for the name of a property, and then for a value. A sparse tree
4878 is created with all entries that define this property with the given
4879 value. If you enclose the value in curly braces, it is interpreted as
4880 a regular expression and matched against the property values.
4881 @end table
4882
4883 @node Property inheritance, Column view, Property searches, Properties and Columns
4884 @section Property Inheritance
4885 @cindex properties, inheritance
4886 @cindex inheritance, of properties
4887
4888 @vindex org-use-property-inheritance
4889 The outline structure of Org-mode documents lends itself to an
4890 inheritance model of properties: if the parent in a tree has a certain
4891 property, the children can inherit this property. Org-mode does not
4892 turn this on by default, because it can slow down property searches
4893 significantly and is often not needed. However, if you find inheritance
4894 useful, you can turn it on by setting the variable
4895 @code{org-use-property-inheritance}. It may be set to @code{t} to make
4896 all properties inherited from the parent, to a list of properties
4897 that should be inherited, or to a regular expression that matches
4898 inherited properties. If a property has the value @samp{nil}, this is
4899 interpreted as an explicit undefine of the property, so that inheritance
4900 search will stop at this value and return @code{nil}.
4901
4902 Org-mode has a few properties for which inheritance is hard-coded, at
4903 least for the special applications for which they are used:
4904
4905 @cindex property, COLUMNS
4906 @table @code
4907 @item COLUMNS
4908 The @code{:COLUMNS:} property defines the format of column view
4909 (@pxref{Column view}). It is inherited in the sense that the level
4910 where a @code{:COLUMNS:} property is defined is used as the starting
4911 point for a column view table, independently of the location in the
4912 subtree from where columns view is turned on.
4913 @item CATEGORY
4914 @cindex property, CATEGORY
4915 For agenda view, a category set through a @code{:CATEGORY:} property
4916 applies to the entire subtree.
4917 @item ARCHIVE
4918 @cindex property, ARCHIVE
4919 For archiving, the @code{:ARCHIVE:} property may define the archive
4920 location for the entire subtree (@pxref{Moving subtrees}).
4921 @item LOGGING
4922 @cindex property, LOGGING
4923 The LOGGING property may define logging settings for an entry or a
4924 subtree (@pxref{Tracking TODO state changes}).
4925 @end table
4926
4927 @node Column view, Property API, Property inheritance, Properties and Columns
4928 @section Column view
4929
4930 A great way to view and edit properties in an outline tree is
4931 @emph{column view}. In column view, each outline node is turned into a
4932 table row. Columns in this table provide access to properties of the
4933 entries. Org-mode implements columns by overlaying a tabular structure
4934 over the headline of each item. While the headlines have been turned
4935 into a table row, you can still change the visibility of the outline
4936 tree. For example, you get a compact table by switching to CONTENTS
4937 view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
4938 is active), but you can still open, read, and edit the entry below each
4939 headline. Or, you can switch to column view after executing a sparse
4940 tree command and in this way get a table only for the selected items.
4941 Column view also works in agenda buffers (@pxref{Agenda Views}) where
4942 queries have collected selected items, possibly from a number of files.
4943
4944 @menu
4945 * Defining columns:: The COLUMNS format property
4946 * Using column view:: How to create and use column view
4947 * Capturing column view:: A dynamic block for column view
4948 @end menu
4949
4950 @node Defining columns, Using column view, Column view, Column view
4951 @subsection Defining columns
4952 @cindex column view, for properties
4953 @cindex properties, column view
4954
4955 Setting up a column view first requires defining the columns. This is
4956 done by defining a column format line.
4957
4958 @menu
4959 * Scope of column definitions:: Where defined, where valid?
4960 * Column attributes:: Appearance and content of a column
4961 @end menu
4962
4963 @node Scope of column definitions, Column attributes, Defining columns, Defining columns
4964 @subsubsection Scope of column definitions
4965
4966 To define a column format for an entire file, use a line like
4967
4968 @cindex #+COLUMNS
4969 @example
4970 #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
4971 @end example
4972
4973 To specify a format that only applies to a specific tree, add a
4974 @code{:COLUMNS:} property to the top node of that tree, for example:
4975
4976 @example
4977 ** Top node for columns view
4978 :PROPERTIES:
4979 :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
4980 :END:
4981 @end example
4982
4983 If a @code{:COLUMNS:} property is present in an entry, it defines columns
4984 for the entry itself, and for the entire subtree below it. Since the
4985 column definition is part of the hierarchical structure of the document,
4986 you can define columns on level 1 that are general enough for all
4987 sublevels, and more specific columns further down, when you edit a
4988 deeper part of the tree.
4989
4990 @node Column attributes, , Scope of column definitions, Defining columns
4991 @subsubsection Column attributes
4992 A column definition sets the attributes of a column. The general
4993 definition looks like this:
4994
4995 @example
4996 %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]
4997 @end example
4998
4999 @noindent
5000 Except for the percent sign and the property name, all items are
5001 optional. The individual parts have the following meaning:
5002
5003 @example
5004 @var{width} @r{An integer specifying the width of the column in characters.}
5005 @r{If omitted, the width will be determined automatically.}
5006 @var{property} @r{The property that should be edited in this column.}
5007 @r{Special properties representing meta data are allowed here}
5008 @r{as well (@pxref{Special properties})}
5009 @var{title} @r{The header text for the column. If omitted, the property}
5010 @r{name is used.}
5011 @{@var{summary-type}@} @r{The summary type. If specified, the column values for}
5012 @r{parent nodes are computed from the children.}
5013 @r{Supported summary types are:}
5014 @{+@} @r{Sum numbers in this column.}
5015 @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.}
5016 @{$@} @r{Currency, short for @samp{+;%.2f}.}
5017 @{:@} @r{Sum times, HH:MM, plain numbers are hours.}
5018 @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
5019 @{X/@} @r{Checkbox status, @samp{[n/m]}.}
5020 @{X%@} @r{Checkbox status, @samp{[n%]}.}
5021 @{min@} @r{Smallest number in column.}
5022 @{max@} @r{Largest number.}
5023 @{mean@} @r{Arithmetic mean of numbers.}
5024 @{:min@} @r{Smallest time value in column.}
5025 @{:max@} @r{Largest time value.}
5026 @{:mean@} @r{Arithmetic mean of time values.}
5027 @{@@min@} @r{Minimum age (in days/hours/mins/seconds).}
5028 @{@@max@} @r{Maximum age (in days/hours/mins/seconds).}
5029 @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
5030 @{est+@} @r{Add low-high estimates.}
5031 @end example
5032
5033 @noindent
5034 Be aware that you can only have one summary type for any property you
5035 include. Subsequent columns referencing the same property will all display the
5036 same summary information.
5037
5038 The @code{est+} summary type requires further explanation. It is used for
5039 combining estimates, expressed as low-high ranges. For example, instead
5040 of estimating a particular task will take 5 days, you might estimate it as
5041 5-6 days if you're fairly confident you know how much work is required, or
5042 1-10 days if you don't really know what needs to be done. Both ranges
5043 average at 5.5 days, but the first represents a more predictable delivery.
5044
5045 When combining a set of such estimates, simply adding the lows and highs
5046 produces an unrealistically wide result. Instead, @code{est+} adds the
5047 statistical mean and variance of the sub-tasks, generating a final estimate
5048 from the sum. For example, suppose you had ten tasks, each of which was
5049 estimated at 0.5 to 2 days of work. Straight addition produces an estimate
5050 of 5 to 20 days, representing what to expect if everything goes either
5051 extremely well or extremely poorly. In contrast, @code{est+} estimates the
5052 full job more realistically, at 10-15 days.
5053
5054 Here is an example for a complete columns definition, along with allowed
5055 values.
5056
5057 @example
5058 :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.}
5059 %10Time_Estimate@{:@} %CLOCKSUM
5060 :Owner_ALL: Tammy Mark Karl Lisa Don
5061 :Status_ALL: "In progress" "Not started yet" "Finished" ""
5062 :Approved_ALL: "[ ]" "[X]"
5063 @end example
5064
5065 @noindent
5066 The first column, @samp{%25ITEM}, means the first 25 characters of the
5067 item itself, i.e.@: of the headline. You probably always should start the
5068 column definition with the @samp{ITEM} specifier. The other specifiers
5069 create columns @samp{Owner} with a list of names as allowed values, for
5070 @samp{Status} with four different possible values, and for a checkbox
5071 field @samp{Approved}. When no width is given after the @samp{%}
5072 character, the column will be exactly as wide as it needs to be in order
5073 to fully display all values. The @samp{Approved} column does have a
5074 modified title (@samp{Approved?}, with a question mark). Summaries will
5075 be created for the @samp{Time_Estimate} column by adding time duration
5076 expressions like HH:MM, and for the @samp{Approved} column, by providing
5077 an @samp{[X]} status if all children have been checked. The
5078 @samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervals
5079 in the subtree.
5080
5081 @node Using column view, Capturing column view, Defining columns, Column view
5082 @subsection Using column view
5083
5084 @table @kbd
5085 @tsubheading{Turning column view on and off}
5086 @orgcmd{C-c C-x C-c,org-columns}
5087 @vindex org-columns-default-format
5088 Turn on column view. If the cursor is before the first headline in the file,
5089 column view is turned on for the entire file, using the @code{#+COLUMNS}
5090 definition. If the cursor is somewhere inside the outline, this command
5091 searches the hierarchy, up from point, for a @code{:COLUMNS:} property that
5092 defines a format. When one is found, the column view table is established
5093 for the tree starting at the entry that contains the @code{:COLUMNS:}
5094 property. If no such property is found, the format is taken from the
5095 @code{#+COLUMNS} line or from the variable @code{org-columns-default-format},
5096 and column view is established for the current entry and its subtree.
5097 @orgcmd{r,org-columns-redo}
5098 Recreate the column view, to include recent changes made in the buffer.
5099 @orgcmd{g,org-columns-redo}
5100 Same as @kbd{r}.
5101 @orgcmd{q,org-columns-quit}
5102 Exit column view.
5103 @tsubheading{Editing values}
5104 @item @key{left} @key{right} @key{up} @key{down}
5105 Move through the column view from field to field.
5106 @kindex S-@key{left}
5107 @kindex S-@key{right}
5108 @item S-@key{left}/@key{right}
5109 Switch to the next/previous allowed value of the field. For this, you
5110 have to have specified allowed values for a property.
5111 @item 1..9,0
5112 Directly select the Nth allowed value, @kbd{0} selects the 10th value.
5113 @orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value}
5114 Same as @kbd{S-@key{left}/@key{right}}
5115 @orgcmd{e,org-columns-edit-value}
5116 Edit the property at point. For the special properties, this will
5117 invoke the same interface that you normally use to change that
5118 property. For example, when editing a TAGS property, the tag completion
5119 or fast selection interface will pop up.
5120 @orgcmd{C-c C-c,org-columns-set-tags-or-toggle}
5121 When there is a checkbox at point, toggle it.
5122 @orgcmd{v,org-columns-show-value}
5123 View the full value of this property. This is useful if the width of
5124 the column is smaller than that of the value.
5125 @orgcmd{a,org-columns-edit-allowed}
5126 Edit the list of allowed values for this property. If the list is found
5127 in the hierarchy, the modified values is stored there. If no list is
5128 found, the new value is stored in the first entry that is part of the
5129 current column view.
5130 @tsubheading{Modifying the table structure}
5131 @orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen}
5132 Make the column narrower/wider by one character.
5133 @orgcmd{S-M-@key{right},org-columns-new}
5134 Insert a new column, to the left of the current column.
5135 @orgcmd{S-M-@key{left},org-columns-delete}
5136 Delete the current column.
5137 @end table
5138
5139 @node Capturing column view, , Using column view, Column view
5140 @subsection Capturing column view
5141
5142 Since column view is just an overlay over a buffer, it cannot be
5143 exported or printed directly. If you want to capture a column view, use
5144 a @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
5145 of this block looks like this:
5146
5147 @cindex #+BEGIN, columnview
5148 @example
5149 * The column view
5150 #+BEGIN: columnview :hlines 1 :id "label"
5151
5152 #+END:
5153 @end example
5154
5155 @noindent This dynamic block has the following parameters:
5156
5157 @table @code
5158 @item :id
5159 This is the most important parameter. Column view is a feature that is
5160 often localized to a certain (sub)tree, and the capture block might be
5161 at a different location in the file. To identify the tree whose view to
5162 capture, you can use 4 values:
5163 @cindex property, ID
5164 @example
5165 local @r{use the tree in which the capture block is located}
5166 global @r{make a global view, including all headings in the file}
5167 "file:@var{path-to-file}"
5168 @r{run column view at the top of this file}
5169 "@var{ID}" @r{call column view in the tree that has an @code{:ID:}}
5170 @r{property with the value @i{label}. You can use}
5171 @r{@kbd{M-x org-id-copy} to create a globally unique ID for}
5172 @r{the current entry and copy it to the kill-ring.}
5173 @end example
5174 @item :hlines
5175 When @code{t}, insert an hline after every line. When a number @var{N}, insert
5176 an hline before each headline with level @code{<= @var{N}}.
5177 @item :vlines
5178 When set to @code{t}, force column groups to get vertical lines.
5179 @item :maxlevel
5180 When set to a number, don't capture entries below this level.
5181 @item :skip-empty-rows
5182 When set to @code{t}, skip rows where the only non-empty specifier of the
5183 column view is @code{ITEM}.
5184
5185 @end table
5186
5187 @noindent
5188 The following commands insert or update the dynamic block:
5189
5190 @table @kbd
5191 @orgcmd{C-c C-x i,org-insert-columns-dblock}
5192 Insert a dynamic block capturing a column view. You will be prompted
5193 for the scope or ID of the view.
5194 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
5195 Update dynamic block at point. The cursor needs to be in the
5196 @code{#+BEGIN} line of the dynamic block.
5197 @orgcmd{C-u C-c C-x C-u,org-update-all-dblocks}
5198 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
5199 you have several clock table blocks, column-capturing blocks or other dynamic
5200 blocks in a buffer.
5201 @end table
5202
5203 You can add formulas to the column view table and you may add plotting
5204 instructions in front of the table---these will survive an update of the
5205 block. If there is a @code{#+TBLFM:} after the table, the table will
5206 actually be recalculated automatically after an update.
5207
5208 An alternative way to capture and process property values into a table is
5209 provided by Eric Schulte's @file{org-collector.el} which is a contributed
5210 package@footnote{Contributed packages are not part of Emacs, but are
5211 distributed with the main distribution of Org (visit
5212 @uref{http://orgmode.org}).}. It provides a general API to collect
5213 properties from entries in a certain scope, and arbitrary Lisp expressions to
5214 process these values before inserting them into a table or a dynamic block.
5215
5216 @node Property API, , Column view, Properties and Columns
5217 @section The Property API
5218 @cindex properties, API
5219 @cindex API, for properties
5220
5221 There is a full API for accessing and changing properties. This API can
5222 be used by Emacs Lisp programs to work with properties and to implement
5223 features based on them. For more information see @ref{Using the
5224 property API}.
5225
5226 @node Dates and Times, Capture - Refile - Archive, Properties and Columns, Top
5227 @chapter Dates and times
5228 @cindex dates
5229 @cindex times
5230 @cindex timestamp
5231 @cindex date stamp
5232
5233 To assist project planning, TODO items can be labeled with a date and/or
5234 a time. The specially formatted string carrying the date and time
5235 information is called a @emph{timestamp} in Org-mode. This may be a
5236 little confusing because timestamp is often used as indicating when
5237 something was created or last changed. However, in Org-mode this term
5238 is used in a much wider sense.
5239
5240 @menu
5241 * Timestamps:: Assigning a time to a tree entry
5242 * Creating timestamps:: Commands which insert timestamps
5243 * Deadlines and scheduling:: Planning your work
5244 * Clocking work time:: Tracking how long you spend on a task
5245 * Effort estimates:: Planning work effort in advance
5246 * Relative timer:: Notes with a running timer
5247 * Countdown timer:: Starting a countdown timer for a task
5248 @end menu
5249
5250
5251 @node Timestamps, Creating timestamps, Dates and Times, Dates and Times
5252 @section Timestamps, deadlines, and scheduling
5253 @cindex timestamps
5254 @cindex ranges, time
5255 @cindex date stamps
5256 @cindex deadlines
5257 @cindex scheduling
5258
5259 A timestamp is a specification of a date (possibly with a time or a range of
5260 times) in a special format, either @samp{<2003-09-16 Tue>} or
5261 @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue
5262 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 date/time
5263 format. To use an alternative format, see @ref{Custom time format}.}. A
5264 timestamp can appear anywhere in the headline or body of an Org tree entry.
5265 Its presence causes entries to be shown on specific dates in the agenda
5266 (@pxref{Weekly/daily agenda}). We distinguish:
5267
5268 @table @var
5269 @item Plain timestamp; Event; Appointment
5270 @cindex timestamp
5271 A simple timestamp just assigns a date/time to an item. This is just
5272 like writing down an appointment or event in a paper agenda. In the
5273 timeline and agenda displays, the headline of an entry associated with a
5274 plain timestamp will be shown exactly on that date.
5275
5276 @example
5277 * Meet Peter at the movies <2006-11-01 Wed 19:15>
5278 * Discussion on climate change <2006-11-02 Thu 20:00-22:00>
5279 @end example
5280
5281 @item Timestamp with repeater interval
5282 @cindex timestamp, with repeater interval
5283 A timestamp may contain a @emph{repeater interval}, indicating that it
5284 applies not only on the given date, but again and again after a certain
5285 interval of N days (d), weeks (w), months (m), or years (y). The
5286 following will show up in the agenda every Wednesday:
5287
5288 @example
5289 * Pick up Sam at school <2007-05-16 Wed 12:30 +1w>
5290 @end example
5291
5292 @item Diary-style sexp entries
5293 For more complex date specifications, Org-mode supports using the special
5294 sexp diary entries implemented in the Emacs calendar/diary
5295 package@footnote{When working with the standard diary sexp functions, you
5296 need to be very careful with the order of the arguments. That order depend
5297 evilly on the variable @code{calendar-date-style} (or, for older Emacs
5298 versions, @code{european-calendar-style}). For example, to specify a date
5299 December 12, 2005, the call might look like @code{(diary-date 12 1 2005)} or
5300 @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
5301 the settings. This has been the source of much confusion. Org-mode users
5302 can resort to special versions of these functions like @code{org-date} or
5303 @code{org-anniversary}. These work just like the corresponding @code{diary-}
5304 functions, but with stable ISO order of arguments (year, month, day) wherever
5305 applicable, independent of the value of @code{calendar-date-style}.}. For example
5306
5307 @example
5308 * The nerd meeting on every 2nd Thursday of the month
5309 <%%(org-float t 4 2)>
5310 @end example
5311
5312 @item Time/Date range
5313 @cindex timerange
5314 @cindex date range
5315 Two timestamps connected by @samp{--} denote a range. The headline
5316 will be shown on the first and last day of the range, and on any dates
5317 that are displayed and fall in the range. Here is an example:
5318
5319 @example
5320 ** Meeting in Amsterdam
5321 <2004-08-23 Mon>--<2004-08-26 Thu>
5322 @end example
5323
5324 @item Inactive timestamp
5325 @cindex timestamp, inactive
5326 @cindex inactive timestamp
5327 Just like a plain timestamp, but with square brackets instead of
5328 angular ones. These timestamps are inactive in the sense that they do
5329 @emph{not} trigger an entry to show up in the agenda.
5330
5331 @example
5332 * Gillian comes late for the fifth time [2006-11-01 Wed]
5333 @end example
5334
5335 @end table
5336
5337 @node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times
5338 @section Creating timestamps
5339 @cindex creating timestamps
5340 @cindex timestamps, creating
5341
5342 For Org-mode to recognize timestamps, they need to be in the specific
5343 format. All commands listed below produce timestamps in the correct
5344 format.
5345
5346 @table @kbd
5347 @orgcmd{C-c .,org-time-stamp}
5348 Prompt for a date and insert a corresponding timestamp. When the cursor is
5349 at an existing timestamp in the buffer, the command is used to modify this
5350 timestamp instead of inserting a new one. When this command is used twice in
5351 succession, a time range is inserted.
5352 @c
5353 @orgcmd{C-c !,org-time-stamp-inactive}
5354 Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
5355 an agenda entry.
5356 @c
5357 @kindex C-u C-c .
5358 @kindex C-u C-c !
5359 @item C-u C-c .
5360 @itemx C-u C-c !
5361 @vindex org-time-stamp-rounding-minutes
5362 Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which
5363 contains date and time. The default time can be rounded to multiples of 5
5364 minutes, see the option @code{org-time-stamp-rounding-minutes}.
5365 @c
5366 @orgcmd{C-c <,org-date-from-calendar}
5367 Insert a timestamp corresponding to the cursor date in the Calendar.
5368 @c
5369 @orgcmd{C-c >,org-goto-calendar}
5370 Access the Emacs calendar for the current date. If there is a
5371 timestamp in the current line, go to the corresponding date
5372 instead.
5373 @c
5374 @orgcmd{C-c C-o,org-open-at-point}
5375 Access the agenda for the date given by the timestamp or -range at
5376 point (@pxref{Weekly/daily agenda}).
5377 @c
5378 @orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day}
5379 Change date at cursor by one day. These key bindings conflict with
5380 shift-selection and related modes (@pxref{Conflicts}).
5381 @c
5382 @orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down}
5383 Change the item under the cursor in a timestamp. The cursor can be on a
5384 year, month, day, hour or minute. When the timestamp contains a time range
5385 like @samp{15:30-16:30}, modifying the first time will also shift the second,
5386 shifting the time block with constant length. To change the length, modify
5387 the second time. Note that if the cursor is in a headline and not at a
5388 timestamp, these same keys modify the priority of an item.
5389 (@pxref{Priorities}). The key bindings also conflict with shift-selection and
5390 related modes (@pxref{Conflicts}).
5391 @c
5392 @orgcmd{C-c C-y,org-evaluate-time-range}
5393 @cindex evaluate time range
5394 Evaluate a time range by computing the difference between start and end.
5395 With a prefix argument, insert result after the time range (in a table: into
5396 the following column).
5397 @end table
5398
5399
5400 @menu
5401 * The date/time prompt:: How Org-mode helps you entering date and time
5402 * Custom time format:: Making dates look different
5403 @end menu
5404
5405 @node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps
5406 @subsection The date/time prompt
5407 @cindex date, reading in minibuffer
5408 @cindex time, reading in minibuffer
5409
5410 @vindex org-read-date-prefer-future
5411 When Org-mode prompts for a date/time, the default is shown in default
5412 date/time format, and the prompt therefore seems to ask for a specific
5413 format. But it will in fact accept any string containing some date and/or
5414 time information, and it is really smart about interpreting your input. You
5415 can, for example, use @kbd{C-y} to paste a (possibly multi-line) string
5416 copied from an email message. Org-mode will find whatever information is in
5417 there and derive anything you have not specified from the @emph{default date
5418 and time}. The default is usually the current date and time, but when
5419 modifying an existing timestamp, or when entering the second stamp of a
5420 range, it is taken from the stamp in the buffer. When filling in
5421 information, Org-mode assumes that most of the time you will want to enter a
5422 date in the future: if you omit the month/year and the given day/month is
5423 @i{before} today, it will assume that you mean a future date@footnote{See the
5424 variable @code{org-read-date-prefer-future}. You may set that variable to
5425 the symbol @code{time} to even make a time before now shift the date to
5426 tomorrow.}. If the date has been automatically shifted into the future, the
5427 time prompt will show this with @samp{(=>F).}
5428
5429 For example, let's assume that today is @b{June 13, 2006}. Here is how
5430 various inputs will be interpreted, the items filled in by Org-mode are
5431 in @b{bold}.
5432
5433 @example
5434 3-2-5 @result{} 2003-02-05
5435 2/5/3 @result{} 2003-02-05
5436 14 @result{} @b{2006}-@b{06}-14
5437 12 @result{} @b{2006}-@b{07}-12
5438 2/5 @result{} @b{2007}-02-05
5439 Fri @result{} nearest Friday (default date or later)
5440 sep 15 @result{} @b{2006}-09-15
5441 feb 15 @result{} @b{2007}-02-15
5442 sep 12 9 @result{} 2009-09-12
5443 12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45
5444 22 sept 0:34 @result{} @b{2006}-09-22 0:34
5445 w4 @result{} ISO week for of the current year @b{2006}
5446 2012 w4 fri @result{} Friday of ISO week 4 in 2012
5447 2012-w04-5 @result{} Same as above
5448 @end example
5449
5450 Furthermore you can specify a relative date by giving, as the
5451 @emph{first} thing in the input: a plus/minus sign, a number and a
5452 letter ([dwmy]) to indicate change in days, weeks, months, or years. With a
5453 single plus or minus, the date is always relative to today. With a
5454 double plus or minus, it is relative to the default date. If instead of
5455 a single letter, you use the abbreviation of day name, the date will be
5456 the Nth such day, e.g.@:
5457
5458 @example
5459 +0 @result{} today
5460 . @result{} today
5461 +4d @result{} four days from today
5462 +4 @result{} same as above
5463 +2w @result{} two weeks from today
5464 ++5 @result{} five days from default date
5465 +2tue @result{} second Tuesday from now.
5466 @end example
5467
5468 @vindex parse-time-months
5469 @vindex parse-time-weekdays
5470 The function understands English month and weekday abbreviations. If
5471 you want to use unabbreviated names and/or other languages, configure
5472 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
5473
5474 @vindex org-read-date-force-compatible-dates
5475 Not all dates can be represented in a given Emacs implementation. By default
5476 Org mode forces dates into the compatibility range 1970--2037 which works on
5477 all Emacs implementations. If you want to use dates outside of this range,
5478 read the docstring of the variable
5479 @code{org-read-date-force-compatible-dates}.
5480
5481 You can specify a time range by giving start and end times or by giving a
5482 start time and a duration (in HH:MM format). Use one or two dash(es) as the
5483 separator in the former case and use '+' as the separator in the latter
5484 case, e.g.@:
5485
5486 @example
5487 11am-1:15pm @result{} 11:00-13:15
5488 11am--1:15pm @result{} same as above
5489 11am+2:15 @result{} same as above
5490 @end example
5491
5492 @cindex calendar, for selecting date
5493 @vindex org-popup-calendar-for-date-prompt
5494 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
5495 you don't need/want the calendar, configure the variable
5496 @code{org-popup-calendar-for-date-prompt}.}. When you exit the date
5497 prompt, either by clicking on a date in the calendar, or by pressing
5498 @key{RET}, the date selected in the calendar will be combined with the
5499 information entered at the prompt. You can control the calendar fully
5500 from the minibuffer:
5501
5502 @kindex <
5503 @kindex >
5504 @kindex M-v
5505 @kindex C-v
5506 @kindex mouse-1
5507 @kindex S-@key{right}
5508 @kindex S-@key{left}
5509 @kindex S-@key{down}
5510 @kindex S-@key{up}
5511 @kindex M-S-@key{right}
5512 @kindex M-S-@key{left}
5513 @kindex @key{RET}
5514 @example
5515 @key{RET} @r{Choose date at cursor in calendar.}
5516 mouse-1 @r{Select date by clicking on it.}
5517 S-@key{right}/@key{left} @r{One day forward/backward.}
5518 S-@key{down}/@key{up} @r{One week forward/backward.}
5519 M-S-@key{right}/@key{left} @r{One month forward/backward.}
5520 > / < @r{Scroll calendar forward/backward by one month.}
5521 M-v / C-v @r{Scroll calendar forward/backward by 3 months.}
5522 @end example
5523
5524 @vindex org-read-date-display-live
5525 The actions of the date/time prompt may seem complex, but I assure you they
5526 will grow on you, and you will start getting annoyed by pretty much any other
5527 way of entering a date/time out there. To help you understand what is going
5528 on, the current interpretation of your input will be displayed live in the
5529 minibuffer@footnote{If you find this distracting, turn the display of with
5530 @code{org-read-date-display-live}.}.
5531
5532 @node Custom time format, , The date/time prompt, Creating timestamps
5533 @subsection Custom time format
5534 @cindex custom date/time format
5535 @cindex time format, custom
5536 @cindex date format, custom
5537
5538 @vindex org-display-custom-times
5539 @vindex org-time-stamp-custom-formats
5540 Org-mode uses the standard ISO notation for dates and times as it is
5541 defined in ISO 8601. If you cannot get used to this and require another
5542 representation of date and time to keep you happy, you can get it by
5543 customizing the variables @code{org-display-custom-times} and
5544 @code{org-time-stamp-custom-formats}.
5545
5546 @table @kbd
5547 @orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays}
5548 Toggle the display of custom formats for dates and times.
5549 @end table
5550
5551 @noindent
5552 Org-mode needs the default format for scanning, so the custom date/time
5553 format does not @emph{replace} the default format---instead it is put
5554 @emph{over} the default format using text properties. This has the
5555 following consequences:
5556 @itemize @bullet
5557 @item
5558 You cannot place the cursor onto a timestamp anymore, only before or
5559 after.
5560 @item
5561 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
5562 each component of a timestamp. If the cursor is at the beginning of
5563 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
5564 just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the
5565 time will be changed by one minute.
5566 @item
5567 If the timestamp contains a range of clock times or a repeater, these
5568 will not be overlaid, but remain in the buffer as they were.
5569 @item
5570 When you delete a timestamp character-by-character, it will only
5571 disappear from the buffer after @emph{all} (invisible) characters
5572 belonging to the ISO timestamp have been removed.
5573 @item
5574 If the custom timestamp format is longer than the default and you are
5575 using dates in tables, table alignment will be messed up. If the custom
5576 format is shorter, things do work as expected.
5577 @end itemize
5578
5579
5580 @node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times
5581 @section Deadlines and scheduling
5582
5583 A timestamp may be preceded by special keywords to facilitate planning:
5584
5585 @table @var
5586 @item DEADLINE
5587 @cindex DEADLINE keyword
5588
5589 Meaning: the task (most likely a TODO item, though not necessarily) is supposed
5590 to be finished on that date.
5591
5592 @vindex org-deadline-warning-days
5593 On the deadline date, the task will be listed in the agenda. In
5594 addition, the agenda for @emph{today} will carry a warning about the
5595 approaching or missed deadline, starting
5596 @code{org-deadline-warning-days} before the due date, and continuing
5597 until the entry is marked DONE. An example:
5598
5599 @example
5600 *** TODO write article about the Earth for the Guide
5601 The editor in charge is [[bbdb:Ford Prefect]]
5602 DEADLINE: <2004-02-29 Sun>
5603 @end example
5604
5605 You can specify a different lead time for warnings for a specific
5606 deadlines using the following syntax. Here is an example with a warning
5607 period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}.
5608
5609 @item SCHEDULED
5610 @cindex SCHEDULED keyword
5611
5612 Meaning: you are planning to start working on that task on the given
5613 date.
5614
5615 @vindex org-agenda-skip-scheduled-if-done
5616 The headline will be listed under the given date@footnote{It will still
5617 be listed on that date after it has been marked DONE. If you don't like
5618 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
5619 addition, a reminder that the scheduled date has passed will be present
5620 in the compilation for @emph{today}, until the entry is marked DONE, i.e.@:
5621 the task will automatically be forwarded until completed.
5622
5623 @example
5624 *** TODO Call Trillian for a date on New Years Eve.
5625 SCHEDULED: <2004-12-25 Sat>
5626 @end example
5627
5628 @noindent
5629 @b{Important:} Scheduling an item in Org-mode should @i{not} be
5630 understood in the same way that we understand @i{scheduling a meeting}.
5631 Setting a date for a meeting is just a simple appointment, you should
5632 mark this entry with a simple plain timestamp, to get this item shown
5633 on the date where it applies. This is a frequent misunderstanding by
5634 Org users. In Org-mode, @i{scheduling} means setting a date when you
5635 want to start working on an action item.
5636 @end table
5637
5638 You may use timestamps with repeaters in scheduling and deadline
5639 entries. Org-mode will issue early and late warnings based on the
5640 assumption that the timestamp represents the @i{nearest instance} of
5641 the repeater. However, the use of diary sexp entries like
5642 @c
5643 @code{<%%(org-float t 42)>}
5644 @c
5645 in scheduling and deadline timestamps is limited. Org-mode does not
5646 know enough about the internals of each sexp function to issue early and
5647 late warnings. However, it will show the item on each day where the
5648 sexp entry matches.
5649
5650 @menu
5651 * Inserting deadline/schedule:: Planning items
5652 * Repeated tasks:: Items that show up again and again
5653 @end menu
5654
5655 @node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling
5656 @subsection Inserting deadlines or schedules
5657
5658 The following commands allow you to quickly insert@footnote{The @samp{SCHEDULED} and
5659 @samp{DEADLINE} dates are inserted on the line right below the headline. Don't put
5660 any text between this line and the headline.} a deadline or to schedule
5661 an item:
5662
5663 @table @kbd
5664 @c
5665 @orgcmd{C-c C-d,org-deadline}
5666 Insert @samp{DEADLINE} keyword along with a stamp. The insertion will happen
5667 in the line directly following the headline. Any CLOSED timestamp will be
5668 removed. When called with a prefix arg, an existing deadline will be removed
5669 from the entry. Depending on the variable @code{org-log-redeadline}@footnote{with corresponding
5670 @code{#+STARTUP} keywords @code{logredeadline}, @code{lognoteredeadline},
5671 and @code{nologredeadline}}, a note will be taken when changing an existing
5672 deadline.
5673
5674 @orgcmd{C-c C-s,org-schedule}
5675 Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will
5676 happen in the line directly following the headline. Any CLOSED timestamp
5677 will be removed. When called with a prefix argument, remove the scheduling
5678 date from the entry. Depending on the variable
5679 @code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}
5680 keywords @code{logreschedule}, @code{lognotereschedule}, and
5681 @code{nologreschedule}}, a note will be taken when changing an existing
5682 scheduling time.
5683 @c
5684 @orgcmd{C-c C-x C-k,org-mark-entry-for-agenda-action}
5685 @kindex k a
5686 @kindex k s
5687 Mark the current entry for agenda action. After you have marked the entry
5688 like this, you can open the agenda or the calendar to find an appropriate
5689 date. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to
5690 schedule the marked item.
5691 @c
5692 @orgcmd{C-c / d,org-check-deadlines}
5693 @cindex sparse tree, for deadlines
5694 @vindex org-deadline-warning-days
5695 Create a sparse tree with all deadlines that are either past-due, or
5696 which will become due within @code{org-deadline-warning-days}.
5697 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
5698 prefix, check that many days. For example, @kbd{C-1 C-c / d} shows
5699 all deadlines due tomorrow.
5700 @c
5701 @orgcmd{C-c / b,org-check-before-date}
5702 Sparse tree for deadlines and scheduled items before a given date.
5703 @c
5704 @orgcmd{C-c / a,org-check-after-date}
5705 Sparse tree for deadlines and scheduled items after a given date.
5706 @end table
5707
5708 Note that @code{org-schedule} and @code{org-deadline} supports
5709 setting the date by indicating a relative time: e.g. +1d will set
5710 the date to the next day after today, and --1w will set the date
5711 to the previous week before any current timestamp.
5712
5713 @node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling
5714 @subsection Repeated tasks
5715 @cindex tasks, repeated
5716 @cindex repeated tasks
5717
5718 Some tasks need to be repeated again and again. Org-mode helps to
5719 organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
5720 or plain timestamp. In the following example
5721 @example
5722 ** TODO Pay the rent
5723 DEADLINE: <2005-10-01 Sat +1m>
5724 @end example
5725 @noindent
5726 the @code{+1m} is a repeater; the intended interpretation is that the task
5727 has a deadline on <2005-10-01> and repeats itself every (one) month starting
5728 from that time. If you need both a repeater and a special warning period in
5729 a deadline entry, the repeater should come first and the warning period last:
5730 @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
5731
5732 @vindex org-todo-repeat-to-state
5733 Deadlines and scheduled items produce entries in the agenda when they are
5734 over-due, so it is important to be able to mark such an entry as completed
5735 once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO
5736 keyword DONE, it will no longer produce entries in the agenda. The problem
5737 with this is, however, that then also the @emph{next} instance of the
5738 repeated entry will not be active. Org-mode deals with this in the following
5739 way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
5740 shift the base date of the repeating timestamp by the repeater interval, and
5741 immediately set the entry state back to TODO@footnote{In fact, the target
5742 state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or
5743 the variable @code{org-todo-repeat-to-state}. If neither of these is
5744 specified, the target state defaults to the first state of the TODO state
5745 sequence.}. In the example above, setting the state to DONE would actually
5746 switch the date like this:
5747
5748 @example
5749 ** TODO Pay the rent
5750 DEADLINE: <2005-11-01 Tue +1m>
5751 @end example
5752
5753 @vindex org-log-repeat
5754 A timestamp@footnote{You can change this using the option
5755 @code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},
5756 @code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you
5757 will also be prompted for a note.} will be added under the deadline, to keep
5758 a record that you actually acted on the previous instance of this deadline.
5759
5760 As a consequence of shifting the base date, this entry will no longer be
5761 visible in the agenda when checking past dates, but all future instances
5762 will be visible.
5763
5764 With the @samp{+1m} cookie, the date shift will always be exactly one
5765 month. So if you have not paid the rent for three months, marking this
5766 entry DONE will still keep it as an overdue deadline. Depending on the
5767 task, this may not be the best way to handle it. For example, if you
5768 forgot to call your father for 3 weeks, it does not make sense to call
5769 him 3 times in a single day to make up for it. Finally, there are tasks
5770 like changing batteries which should always repeat a certain time
5771 @i{after} the last time you did it. For these tasks, Org-mode has
5772 special repeaters @samp{++} and @samp{.+}. For example:
5773
5774 @example
5775 ** TODO Call Father
5776 DEADLINE: <2008-02-10 Sun ++1w>
5777 Marking this DONE will shift the date by at least one week,
5778 but also by as many weeks as it takes to get this date into
5779 the future. However, it stays on a Sunday, even if you called
5780 and marked it done on Saturday.
5781 ** TODO Check the batteries in the smoke detectors
5782 DEADLINE: <2005-11-01 Tue .+1m>
5783 Marking this DONE will shift the date to one month after
5784 today.
5785 @end example
5786
5787 You may have both scheduling and deadline information for a specific
5788 task---just make sure that the repeater intervals on both are the same.
5789
5790 An alternative to using a repeater is to create a number of copies of a task
5791 subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was
5792 created for this purpose, it is described in @ref{Structure editing}.
5793
5794
5795 @node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and Times
5796 @section Clocking work time
5797 @cindex clocking time
5798 @cindex time clocking
5799
5800 Org-mode allows you to clock the time you spend on specific tasks in a
5801 project. When you start working on an item, you can start the clock.
5802 When you stop working on that task, or when you mark the task done, the
5803 clock is stopped and the corresponding time interval is recorded. It
5804 also computes the total time spent on each subtree of a project. And it
5805 remembers a history or tasks recently clocked, to that you can jump quickly
5806 between a number of tasks absorbing your time.
5807
5808 To save the clock history across Emacs sessions, use
5809 @lisp
5810 (setq org-clock-persist 'history)
5811 (org-clock-persistence-insinuate)
5812 @end lisp
5813 When you clock into a new task after resuming Emacs, the incomplete
5814 clock@footnote{To resume the clock under the assumption that you have worked
5815 on this task while outside Emacs, use @code{(setq org-clock-persist t)}.}
5816 will be found (@pxref{Resolving idle time}) and you will be prompted about
5817 what to do with it.
5818
5819 @menu
5820 * Clocking commands:: Starting and stopping a clock
5821 * The clock table:: Detailed reports
5822 * Resolving idle time:: Resolving time when you've been idle
5823 @end menu
5824
5825 @node Clocking commands, The clock table, Clocking work time, Clocking work time
5826 @subsection Clocking commands
5827
5828 @table @kbd
5829 @orgcmd{C-c C-x C-i,org-clock-in}
5830 @vindex org-clock-into-drawer
5831 @cindex property, LOG_INTO_DRAWER
5832 Start the clock on the current item (clock-in). This inserts the CLOCK
5833 keyword together with a timestamp. If this is not the first clocking of
5834 this item, the multiple CLOCK lines will be wrapped into a
5835 @code{:LOGBOOK:} drawer (see also the variable
5836 @code{org-clock-into-drawer}). You can also overrule
5837 the setting of this variable for a subtree by setting a
5838 @code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
5839 When called with a @kbd{C-u} prefix argument,
5840 select the task from a list of recently clocked tasks. With two @kbd{C-u
5841 C-u} prefixes, clock into the task at point and mark it as the default task.
5842 The default task will always be available when selecting a clocking task,
5843 with letter @kbd{d}.@*
5844 @cindex property: CLOCK_MODELINE_TOTAL
5845 @cindex property: LAST_REPEAT
5846 @vindex org-clock-modeline-total
5847 While the clock is running, the current clocking time is shown in the mode
5848 line, along with the title of the task. The clock time shown will be all
5849 time ever clocked for this task and its children. If the task has an effort
5850 estimate (@pxref{Effort estimates}), the mode line displays the current
5851 clocking time against it@footnote{To add an effort estimate ``on the fly'',
5852 hook a function doing this to @code{org-clock-in-prepare-hook}.} If the task
5853 is a repeating one (@pxref{Repeated tasks}), only the time since the last
5854 reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}
5855 will be shown. More control over what time is shown can be exercised with
5856 the @code{CLOCK_MODELINE_TOTAL} property. It may have the values
5857 @code{current} to show only the current clocking instance, @code{today} to
5858 show all time clocked on this tasks today (see also the variable
5859 @code{org-extend-today-until}), @code{all} to include all time, or
5860 @code{auto} which is the default@footnote{See also the variable
5861 @code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
5862 mode line entry will pop up a menu with clocking options.
5863 @c
5864 @orgcmd{C-c C-x C-o,org-clock-out}
5865 @vindex org-log-note-clock-out
5866 Stop the clock (clock-out). This inserts another timestamp at the same
5867 location where the clock was last started. It also directly computes
5868 the resulting time in inserts it after the time range as @samp{=>
5869 HH:MM}. See the variable @code{org-log-note-clock-out} for the
5870 possibility to record an additional note together with the clock-out
5871 timestamp@footnote{The corresponding in-buffer setting is:
5872 @code{#+STARTUP: lognoteclock-out}}.
5873 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
5874 Update the effort estimate for the current clock task.
5875 @kindex C-c C-y
5876 @kindex C-c C-c
5877 @orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range}
5878 Recompute the time interval after changing one of the timestamps. This
5879 is only necessary if you edit the timestamps directly. If you change
5880 them with @kbd{S-@key{cursor}} keys, the update is automatic.
5881 @orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
5882 On @code{CLOCK} log lines, increase/decrease both timestamps at the same
5883 time so that duration keeps the same.
5884 @orgcmd{C-c C-t,org-todo}
5885 Changing the TODO state of an item to DONE automatically stops the clock
5886 if it is running in this same item.
5887 @orgcmd{C-c C-x C-x,org-clock-cancel}
5888 Cancel the current clock. This is useful if a clock was started by
5889 mistake, or if you ended up working on something else.
5890 @orgcmd{C-c C-x C-j,org-clock-goto}
5891 Jump to the headline of the currently clocked in task. With a @kbd{C-u}
5892 prefix arg, select the target task from a list of recently clocked tasks.
5893 @orgcmd{C-c C-x C-d,org-clock-display}
5894 @vindex org-remove-highlights-with-change
5895 Display time summaries for each subtree in the current buffer. This puts
5896 overlays at the end of each headline, showing the total time recorded under
5897 that heading, including the time of any subheadings. You can use visibility
5898 cycling to study the tree, but the overlays disappear when you change the
5899 buffer (see variable @code{org-remove-highlights-with-change}) or press
5900 @kbd{C-c C-c}.
5901 @end table
5902
5903 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
5904 the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been
5905 worked on or closed during a day.
5906
5907 @node The clock table, Resolving idle time, Clocking commands, Clocking work time
5908 @subsection The clock table
5909 @cindex clocktable, dynamic block
5910 @cindex report, of clocked time
5911
5912 Org mode can produce quite complex reports based on the time clocking
5913 information. Such a report is called a @emph{clock table}, because it is
5914 formatted as one or several Org tables.
5915
5916 @table @kbd
5917 @orgcmd{C-c C-x C-r,org-clock-report}
5918 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
5919 report as an Org-mode table into the current file. When the cursor is
5920 at an existing clock table, just update it. When called with a prefix
5921 argument, jump to the first clock report in the current document and
5922 update it.
5923 @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
5924 Update dynamic block at point. The cursor needs to be in the
5925 @code{#+BEGIN} line of the dynamic block.
5926 @orgkey{C-u C-c C-x C-u}
5927 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
5928 you have several clock table blocks in a buffer.
5929 @orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift}
5930 Shift the current @code{:block} interval and update the table. The cursor
5931 needs to be in the @code{#+BEGIN: clocktable} line for this command. If
5932 @code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
5933 @end table
5934
5935
5936 Here is an example of the frame for a clock table as it is inserted into the
5937 buffer with the @kbd{C-c C-x C-r} command:
5938
5939 @cindex #+BEGIN, clocktable
5940 @example
5941 #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
5942 #+END: clocktable
5943 @end example
5944 @noindent
5945 @vindex org-clocktable-defaults
5946 The @samp{BEGIN} line and specify a number of options to define the scope,
5947 structure, and formatting of the report. Defaults for all these options can
5948 be configured in the variable @code{org-clocktable-defaults}.
5949
5950 @noindent First there are options that determine which clock entries are to
5951 be selected:
5952 @example
5953 :maxlevel @r{Maximum level depth to which times are listed in the table.}
5954 @r{Clocks at deeper levels will be summed into the upper level.}
5955 :scope @r{The scope to consider. This can be any of the following:}
5956 nil @r{the current buffer or narrowed region}
5957 file @r{the full current buffer}
5958 subtree @r{the subtree where the clocktable is located}
5959 tree@var{N} @r{the surrounding level @var{N} tree, for example @code{tree3}}
5960 tree @r{the surrounding level 1 tree}
5961 agenda @r{all agenda files}
5962 ("file"..) @r{scan these files}
5963 file-with-archives @r{current file and its archives}
5964 agenda-with-archives @r{all agenda files, including archives}
5965 :block @r{The time block to consider. This block is specified either}
5966 @r{absolute, or relative to the current time and may be any of}
5967 @r{these formats:}
5968 2007-12-31 @r{New year eve 2007}
5969 2007-12 @r{December 2007}
5970 2007-W50 @r{ISO-week 50 in 2007}
5971 2007-Q2 @r{2nd quarter in 2007}
5972 2007 @r{the year 2007}
5973 today, yesterday, today-@var{N} @r{a relative day}
5974 thisweek, lastweek, thisweek-@var{N} @r{a relative week}
5975 thismonth, lastmonth, thismonth-@var{N} @r{a relative month}
5976 thisyear, lastyear, thisyear-@var{N} @r{a relative year}
5977 @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}
5978 :tstart @r{A time string specifying when to start considering times.}
5979 :tend @r{A time string specifying when to stop considering times.}
5980 :step @r{@code{week} or @code{day}, to split the table into chunks.}
5981 @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}
5982 :stepskip0 @r{Do not show steps that have zero time.}
5983 :fileskip0 @r{Do not show table sections from files which did not contribute.}
5984 :tags @r{A tags match to select entries that should contribute. See}
5985 @r{@ref{Matching tags and properties} for the match syntax.}
5986 @end example
5987
5988 Then there are options which determine the formatting of the table. There
5989 options are interpreted by the function @code{org-clocktable-write-default},
5990 but you can specify your own function using the @code{:formatter} parameter.
5991 @example
5992 :emphasize @r{When @code{t}, emphasize level one and level two items.}
5993 :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".}
5994 :link @r{Link the item headlines in the table to their origins.}
5995 :narrow @r{An integer to limit the width of the headline column in}
5996 @r{the org table. If you write it like @samp{50!}, then the}
5997 @r{headline will also be shortened in export.}
5998 :indent @r{Indent each headline field according to its level.}
5999 :tcolumns @r{Number of columns to be used for times. If this is smaller}
6000 @r{than @code{:maxlevel}, lower levels will be lumped into one column.}
6001 :level @r{Should a level number column be included?}
6002 :compact @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}}
6003 @r{All are overwritten except if there is an explicit @code{:narrow}}
6004 :timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,}
6005 @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}
6006 :properties @r{List of properties that should be shown in the table. Each}
6007 @r{property will get its own column.}
6008 :inherit-props @r{When this flag is @code{t}, the values for @code{:properties} will be inherited.}
6009 :formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.}
6010 @r{As a special case, @samp{:formula %} adds a column with % time.}
6011 @r{If you do not specify a formula here, any existing formula}
6012 @r{below the clock table will survive updates and be evaluated.}
6013 :formatter @r{A function to format clock data and insert it into the buffer.}
6014 @end example
6015 To get a clock summary of the current level 1 tree, for the current
6016 day, you could write
6017 @example
6018 #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
6019 #+END: clocktable
6020 @end example
6021 @noindent
6022 and to use a specific time range you could write@footnote{Note that all
6023 parameters must be specified in a single line---the line is broken here
6024 only to fit it into the manual.}
6025 @example
6026 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
6027 :tend "<2006-08-10 Thu 12:00>"
6028 #+END: clocktable
6029 @end example
6030 A summary of the current subtree with % times would be
6031 @example
6032 #+BEGIN: clocktable :scope subtree :link t :formula %
6033 #+END: clocktable
6034 @end example
6035 A horizontally compact representation of everything clocked during last week
6036 would be
6037 @example
6038 #+BEGIN: clocktable :scope agenda :block lastweek :compact t
6039 #+END: clocktable
6040 @end example
6041
6042 @node Resolving idle time, , The clock table, Clocking work time
6043 @subsection Resolving idle time
6044 @cindex resolve idle time
6045
6046 @cindex idle, resolve, dangling
6047 If you clock in on a work item, and then walk away from your
6048 computer---perhaps to take a phone call---you often need to ``resolve'' the
6049 time you were away by either subtracting it from the current clock, or
6050 applying it to another one.
6051
6052 @vindex org-clock-idle-time
6053 By customizing the variable @code{org-clock-idle-time} to some integer, such
6054 as 10 or 15, Emacs can alert you when you get back to your computer after
6055 being idle for that many minutes@footnote{On computers using Mac OS X,
6056 idleness is based on actual user idleness, not just Emacs' idle time. For
6057 X11, you can install a utility program @file{x11idle.c}, available in the
6058 UTILITIES directory of the Org git distribution, to get the same general
6059 treatment of idleness. On other systems, idle time refers to Emacs idle time
6060 only.}, and ask what you want to do with the idle time. There will be a
6061 question waiting for you when you get back, indicating how much idle time has
6062 passed (constantly updated with the current amount), as well as a set of
6063 choices to correct the discrepancy:
6064
6065 @table @kbd
6066 @item k
6067 To keep some or all of the minutes and stay clocked in, press @kbd{k}. Org
6068 will ask how many of the minutes to keep. Press @key{RET} to keep them all,
6069 effectively changing nothing, or enter a number to keep that many minutes.
6070 @item K
6071 If you use the shift key and press @kbd{K}, it will keep however many minutes
6072 you request and then immediately clock out of that task. If you keep all of
6073 the minutes, this is the same as just clocking out of the current task.
6074 @item s
6075 To keep none of the minutes, use @kbd{s} to subtract all the away time from
6076 the clock, and then check back in from the moment you returned.
6077 @item S
6078 To keep none of the minutes and just clock out at the start of the away time,
6079 use the shift key and press @kbd{S}. Remember that using shift will always
6080 leave you clocked out, no matter which option you choose.
6081 @item C
6082 To cancel the clock altogether, use @kbd{C}. Note that if instead of
6083 canceling you subtract the away time, and the resulting clock amount is less
6084 than a minute, the clock will still be canceled rather than clutter up the
6085 log with an empty entry.
6086 @end table
6087
6088 What if you subtracted those away minutes from the current clock, and now
6089 want to apply them to a new clock? Simply clock in to any task immediately
6090 after the subtraction. Org will notice that you have subtracted time ``on
6091 the books'', so to speak, and will ask if you want to apply those minutes to
6092 the next task you clock in on.
6093
6094 There is one other instance when this clock resolution magic occurs. Say you
6095 were clocked in and hacking away, and suddenly your cat chased a mouse who
6096 scared a hamster that crashed into your UPS's power button! You suddenly
6097 lose all your buffers, but thanks to auto-save you still have your recent Org
6098 mode changes, including your last clock in.
6099
6100 If you restart Emacs and clock into any task, Org will notice that you have a
6101 dangling clock which was never clocked out from your last session. Using
6102 that clock's starting time as the beginning of the unaccounted-for period,
6103 Org will ask how you want to resolve that time. The logic and behavior is
6104 identical to dealing with away time due to idleness; it is just happening due
6105 to a recovery event rather than a set amount of idle time.
6106
6107 You can also check all the files visited by your Org agenda for dangling
6108 clocks at any time using @kbd{M-x org-resolve-clocks}.
6109
6110 @node Effort estimates, Relative timer, Clocking work time, Dates and Times
6111 @section Effort estimates
6112 @cindex effort estimates
6113
6114 @cindex property, Effort
6115 @vindex org-effort-property
6116 If you want to plan your work in a very detailed way, or if you need to
6117 produce offers with quotations of the estimated work effort, you may want to
6118 assign effort estimates to entries. If you are also clocking your work, you
6119 may later want to compare the planned effort with the actual working time, a
6120 great way to improve planning estimates. Effort estimates are stored in a
6121 special property @samp{Effort}@footnote{You may change the property being
6122 used with the variable @code{org-effort-property}.}. You can set the effort
6123 for an entry with the following commands:
6124
6125 @table @kbd
6126 @orgcmd{C-c C-x e,org-set-effort}
6127 Set the effort estimate for the current entry. With a numeric prefix
6128 argument, set it to the Nth allowed value (see below). This command is also
6129 accessible from the agenda with the @kbd{e} key.
6130 @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
6131 Modify the effort estimate of the item currently being clocked.
6132 @end table
6133
6134 Clearly the best way to work with effort estimates is through column view
6135 (@pxref{Column view}). You should start by setting up discrete values for
6136 effort estimates, and a @code{COLUMNS} format that displays these values
6137 together with clock sums (if you want to clock your time). For a specific
6138 buffer you can use
6139
6140 @example
6141 #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
6142 #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM
6143 @end example
6144
6145 @noindent
6146 @vindex org-global-properties
6147 @vindex org-columns-default-format
6148 or, even better, you can set up these values globally by customizing the
6149 variables @code{org-global-properties} and @code{org-columns-default-format}.
6150 In particular if you want to use this setup also in the agenda, a global
6151 setup may be advised.
6152
6153 The way to assign estimates to individual items is then to switch to column
6154 mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the
6155 value. The values you enter will immediately be summed up in the hierarchy.
6156 In the column next to it, any clocked time will be displayed.
6157
6158 @vindex org-agenda-columns-add-appointments-to-effort-sum
6159 If you switch to column view in the daily/weekly agenda, the effort column
6160 will summarize the estimated work effort for each day@footnote{Please note
6161 the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda
6162 column view}).}, and you can use this to find space in your schedule. To get
6163 an overview of the entire part of the day that is committed, you can set the
6164 option @code{org-agenda-columns-add-appointments-to-effort-sum}. The
6165 appointments on a day that take place over a specified time interval will
6166 then also be added to the load estimate of the day.
6167
6168 Effort estimates can be used in secondary agenda filtering that is triggered
6169 with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have
6170 these estimates defined consistently, two or three key presses will narrow
6171 down the list to stuff that fits into an available time slot.
6172
6173 @node Relative timer, Countdown timer, Effort estimates, Dates and Times
6174 @section Taking notes with a relative timer
6175 @cindex relative timer
6176
6177 When taking notes during, for example, a meeting or a video viewing, it can
6178 be useful to have access to times relative to a starting time. Org provides
6179 such a relative timer and make it easy to create timed notes.
6180
6181 @table @kbd
6182 @orgcmd{C-c C-x .,org-timer}
6183 Insert a relative time into the buffer. The first time you use this, the
6184 timer will be started. When called with a prefix argument, the timer is
6185 restarted.
6186 @orgcmd{C-c C-x -,org-timer-item}
6187 Insert a description list item with the current relative time. With a prefix
6188 argument, first reset the timer to 0.
6189 @orgcmd{M-@key{RET},org-insert-heading}
6190 Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert
6191 new timer items.
6192 @c for key sequences with a comma, command name macros fail :(
6193 @kindex C-c C-x ,
6194 @item C-c C-x ,
6195 Pause the timer, or continue it if it is already paused
6196 (@command{org-timer-pause-or-continue}).
6197 @c removed the sentence because it is redundant to the following item
6198 @kindex C-u C-c C-x ,
6199 @item C-u C-c C-x ,
6200 Stop the timer. After this, you can only start a new timer, not continue the
6201 old one. This command also removes the timer from the mode line.
6202 @orgcmd{C-c C-x 0,org-timer-start}
6203 Reset the timer without inserting anything into the buffer. By default, the
6204 timer is reset to 0. When called with a @kbd{C-u} prefix, reset the timer to
6205 specific starting offset. The user is prompted for the offset, with a
6206 default taken from a timer string at point, if any, So this can be used to
6207 restart taking notes after a break in the process. When called with a double
6208 prefix argument @kbd{C-u C-u}, change all timer strings in the active region
6209 by a certain amount. This can be used to fix timer strings if the timer was
6210 not started at exactly the right moment.
6211 @end table
6212
6213 @node Countdown timer, , Relative timer, Dates and Times
6214 @section Countdown timer
6215 @cindex Countdown timer
6216 @kindex C-c C-x ;
6217 @kindex ;
6218
6219 Calling @code{org-timer-set-timer} from an Org-mode buffer runs a countdown
6220 timer. Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everwhere else.
6221
6222 @code{org-timer-set-timer} prompts the user for a duration and displays a
6223 countdown timer in the modeline. @code{org-timer-default-timer} sets the
6224 default countdown value. Giving a prefix numeric argument overrides this
6225 default value.
6226
6227 @node Capture - Refile - Archive, Agenda Views, Dates and Times, Top
6228 @chapter Capture - Refile - Archive
6229 @cindex capture
6230
6231 An important part of any organization system is the ability to quickly
6232 capture new ideas and tasks, and to associate reference material with them.
6233 Org does this using a process called @i{capture}. It also can store files
6234 related to a task (@i{attachments}) in a special directory. Once in the
6235 system, tasks and projects need to be moved around. Moving completed project
6236 trees to an archive file keeps the system compact and fast.
6237
6238 @menu
6239 * Capture:: Capturing new stuff
6240 * Attachments:: Add files to tasks
6241 * RSS Feeds:: Getting input from RSS feeds
6242 * Protocols:: External (e.g.@: Browser) access to Emacs and Org
6243 * Refiling notes:: Moving a tree from one place to another
6244 * Archiving:: What to do with finished projects
6245 @end menu
6246
6247 @node Capture, Attachments, Capture - Refile - Archive, Capture - Refile - Archive
6248 @section Capture
6249 @cindex capture
6250
6251 Org's method for capturing new items is heavily inspired by John Wiegley
6252 excellent remember package. Up to version 6.36 Org used a special setup
6253 for @file{remember.el}. @file{org-remember.el} is still part of Org-mode for
6254 backward compatibility with existing setups. You can find the documentation
6255 for org-remember at @url{http://orgmode.org/org-remember.pdf}.
6256
6257 The new capturing setup described here is preferred and should be used by new
6258 users. To convert your @code{org-remember-templates}, run the command
6259 @example
6260 @kbd{M-x org-capture-import-remember-templates @key{RET}}
6261 @end example
6262 @noindent and then customize the new variable with @kbd{M-x
6263 customize-variable org-capture-templates}, check the result, and save the
6264 customization. You can then use both remember and capture until
6265 you are familiar with the new mechanism.
6266
6267 Capture lets you quickly store notes with little interruption of your work
6268 flow. The basic process of capturing is very similar to remember, but Org
6269 does enhance it with templates and more.
6270
6271 @menu
6272 * Setting up capture:: Where notes will be stored
6273 * Using capture:: Commands to invoke and terminate capture
6274 * Capture templates:: Define the outline of different note types
6275 @end menu
6276
6277 @node Setting up capture, Using capture, Capture, Capture
6278 @subsection Setting up capture
6279
6280 The following customization sets a default target file for notes, and defines
6281 a global key@footnote{Please select your own key, @kbd{C-c c} is only a
6282 suggestion.} for capturing new material.
6283
6284 @vindex org-default-notes-file
6285 @example
6286 (setq org-default-notes-file (concat org-directory "/notes.org"))
6287 (define-key global-map "\C-cc" 'org-capture)
6288 @end example
6289
6290 @node Using capture, Capture templates, Setting up capture, Capture
6291 @subsection Using capture
6292
6293 @table @kbd
6294 @orgcmd{C-c c,org-capture}
6295 Call the command @code{org-capture}. Note that this keybinding is global and
6296 not active by default - you need to install it. If you have templates
6297 @cindex date tree
6298 defined @pxref{Capture templates}, it will offer these templates for
6299 selection or use a new Org outline node as the default template. It will
6300 insert the template into the target file and switch to an indirect buffer
6301 narrowed to this new node. You may then insert the information you want.
6302
6303 @orgcmd{C-c C-c,org-capture-finalize}
6304 Once you have finished entering information into the capture buffer, @kbd{C-c
6305 C-c} will return you to the window configuration before the capture process,
6306 so that you can resume your work without further distraction. When called
6307 with a prefix arg, finalize and then jump to the captured item.
6308
6309 @orgcmd{C-c C-w,org-capture-refile}
6310 Finalize the capture process by refiling (@pxref{Refiling notes}) the note to
6311 a different place. Please realize that this is a normal refiling command
6312 that will be executed---so the cursor position at the moment you run this
6313 command is important. If you have inserted a tree with a parent and
6314 children, first move the cursor back to the parent. Any prefix argument
6315 given to this command will be passed on to the @code{org-refile} command.
6316
6317 @orgcmd{C-c C-k,org-capture-kill}
6318 Abort the capture process and return to the previous state.
6319
6320 @end table
6321
6322 You can also call @code{org-capture} in a special way from the agenda, using
6323 the @kbd{k c} key combination. With this access, any timestamps inserted by
6324 the selected capture template will default to the cursor date in the agenda,
6325 rather than to the current date.
6326
6327 To find the locations of the last stored capture, use @code{org-capture} with
6328 prefix commands:
6329
6330 @table @kbd
6331 @orgkey{C-u C-c c}
6332 Visit the target location of a capture template. You get to select the
6333 template in the usual way.
6334 @orgkey{C-u C-u C-c c}
6335 Visit the last stored capture item in its buffer.
6336 @end table
6337
6338 @node Capture templates, , Using capture, Capture
6339 @subsection Capture templates
6340 @cindex templates, for Capture
6341
6342 You can use templates for different types of capture items, and
6343 for different target locations. The easiest way to create such templates is
6344 through the customize interface.
6345
6346 @table @kbd
6347 @orgkey{C-c c C}
6348 Customize the variable @code{org-capture-templates}.
6349 @end table
6350
6351 Before we give the formal description of template definitions, let's look at
6352 an example. Say you would like to use one template to create general TODO
6353 entries, and you want to put these entries under the heading @samp{Tasks} in
6354 your file @file{~/org/gtd.org}. Also, a date tree in the file
6355 @file{journal.org} should capture journal entries. A possible configuration
6356 would look like:
6357
6358 @example
6359 (setq org-capture-templates
6360 '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
6361 "* TODO %?\n %i\n %a")
6362 ("j" "Journal" entry (file+datetree "~/org/journal.org")
6363 "* %?\nEntered on %U\n %i\n %a")))
6364 @end example
6365
6366 @noindent If you then press @kbd{C-c c t}, Org will prepare the template
6367 for you like this:
6368 @example
6369 * TODO
6370 [[file:@var{link to where you initiated capture}]]
6371 @end example
6372
6373 @noindent
6374 During expansion of the template, @code{%a} has been replaced by a link to
6375 the location from where you called the capture command. This can be
6376 extremely useful for deriving tasks from emails, for example. You fill in
6377 the task definition, press @code{C-c C-c} and Org returns you to the same
6378 place where you started the capture process.
6379
6380 To define special keys to capture to a particular template without going
6381 through the interactive template selection, you can create your key binding
6382 like this:
6383
6384 @lisp
6385 (define-key global-map "\C-cx"
6386 (lambda () (interactive) (org-capture nil "x")))
6387 @end lisp
6388
6389 @menu
6390 * Template elements:: What is needed for a complete template entry
6391 * Template expansion:: Filling in information about time and context
6392 @end menu
6393
6394 @node Template elements, Template expansion, Capture templates, Capture templates
6395 @subsubsection Template elements
6396
6397 Now lets look at the elements of a template definition. Each entry in
6398 @code{org-capture-templates} is a list with the following items:
6399
6400 @table @var
6401 @item keys
6402 The keys that will select the template, as a string, characters
6403 only, for example @code{"a"} for a template to be selected with a
6404 single key, or @code{"bt"} for selection with two keys. When using
6405 several keys, keys using the same prefix key must be sequential
6406 in the list and preceded by a 2-element entry explaining the
6407 prefix key, for example
6408 @example
6409 ("b" "Templates for marking stuff to buy")
6410 @end example
6411 @noindent If you do not define a template for the @kbd{C} key, this key will
6412 be used to open the customize buffer for this complex variable.
6413
6414 @item description
6415 A short string describing the template, which will be shown during
6416 selection.
6417
6418 @item type
6419 The type of entry, a symbol. Valid values are:
6420 @table @code
6421 @item entry
6422 An Org-mode node, with a headline. Will be filed as the child of the target
6423 entry or as a top-level entry. The target file should be an Org-mode file.
6424 @item item
6425 A plain list item, placed in the first plain list at the target
6426 location. Again the target file should be an Org file.
6427 @item checkitem
6428 A checkbox item. This only differs from the plain list item by the
6429 default template.
6430 @item table-line
6431 a new line in the first table at the target location. Where exactly the
6432 line will be inserted depends on the properties @code{:prepend} and
6433 @code{:table-line-pos} (see below).
6434 @item plain
6435 Text to be inserted as it is.
6436 @end table
6437
6438 @item target
6439 @vindex org-default-notes-file
6440 Specification of where the captured item should be placed. In Org-mode
6441 files, targets usually define a node. Entries will become children of this
6442 node. Other types will be added to the table or list in the body of this
6443 node. Most target specifications contain a file name. If that file name is
6444 the empty string, it defaults to @code{org-default-notes-file}. A file can
6445 also be given as a variable, function, or Emacs Lisp form.
6446
6447 Valid values are:
6448 @table @code
6449 @item (file "path/to/file")
6450 Text will be placed at the beginning or end of that file.
6451
6452 @item (id "id of existing org entry")
6453 Filing as child of this entry, or in the body of the entry.
6454
6455 @item (file+headline "path/to/file" "node headline")
6456 Fast configuration if the target heading is unique in the file.
6457
6458 @item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
6459 For non-unique headings, the full path is safer.
6460
6461 @item (file+regexp "path/to/file" "regexp to find location")
6462 Use a regular expression to position the cursor.
6463
6464 @item (file+datetree "path/to/file")
6465 Will create a heading in a date tree for today's date.
6466
6467 @item (file+datetree+prompt "path/to/file")
6468 Will create a heading in a date tree, but will prompt for the date.
6469
6470 @item (file+function "path/to/file" function-finding-location)
6471 A function to find the right location in the file.
6472
6473 @item (clock)
6474 File to the entry that is currently being clocked.
6475
6476 @item (function function-finding-location)
6477 Most general way, write your own function to find both
6478 file and location.
6479 @end table
6480
6481 @item template
6482 The template for creating the capture item. If you leave this empty, an
6483 appropriate default template will be used. Otherwise this is a string with
6484 escape codes, which will be replaced depending on time and context of the
6485 capture call. The string with escapes may be loaded from a template file,
6486 using the special syntax @code{(file "path/to/template")}. See below for
6487 more details.
6488
6489 @item properties
6490 The rest of the entry is a property list of additional options.
6491 Recognized properties are:
6492 @table @code
6493 @item :prepend
6494 Normally new captured information will be appended at
6495 the target location (last child, last table line, last list item...).
6496 Setting this property will change that.
6497
6498 @item :immediate-finish
6499 When set, do not offer to edit the information, just
6500 file it away immediately. This makes sense if the template only needs
6501 information that can be added automatically.
6502
6503 @item :empty-lines
6504 Set this to the number of lines to insert
6505 before and after the new item. Default 0, only common other value is 1.
6506
6507 @item :clock-in
6508 Start the clock in this item.
6509
6510 @item :clock-keep
6511 Keep the clock running when filing the captured entry.
6512
6513 @item :clock-resume
6514 If starting the capture interrupted a clock, restart that clock when finished
6515 with the capture. Note that @code{:clock-keep} has precedence over
6516 @code{:clock-resume}. When setting both to @code{t}, the current clock will
6517 run and the previous one will not be resumed.
6518
6519 @item :unnarrowed
6520 Do not narrow the target buffer, simply show the full buffer. Default is to
6521 narrow it so that you only see the new material.
6522
6523 @item :table-line-pos
6524 Specification of the location in the table where the new line should be
6525 inserted. It should be a string like @code{"II-3"} meaning that the new
6526 line should become the third line before the second horizontal separator
6527 line.
6528
6529 @item :kill-buffer
6530 If the target file was not yet visited when capture was invoked, kill the
6531 buffer again after capture is completed.
6532 @end table
6533 @end table
6534
6535 @node Template expansion, , Template elements, Capture templates
6536 @subsubsection Template expansion
6537
6538 In the template itself, special @kbd{%}-escapes@footnote{If you need one of
6539 these sequences literally, escape the @kbd{%} with a backslash.} allow
6540 dynamic insertion of content. The templates are expanded in the order given here:
6541
6542 @smallexample
6543 %[@var{file}] @r{insert the contents of the file given by @var{file}.}
6544 %(@var{sexp}) @r{evaluate Elisp @var{sexp} and replace with the result.}
6545 %<...> @r{the result of format-time-string on the ... format specification.}
6546 %t @r{timestamp, date only.}
6547 %T @r{timestamp with date and time.}
6548 %u, %U @r{like the above, but inactive timestamps.}
6549 %a @r{annotation, normally the link created with @code{org-store-link}.}
6550 %i @r{initial content, the region when capture is called while the}
6551 @r{region is active.}
6552 @r{The entire text will be indented like @code{%i} itself.}
6553 %A @r{like @code{%a}, but prompt for the description part.}
6554 %c @r{Current kill ring head.}
6555 %x @r{Content of the X clipboard.}
6556 %k @r{title of the currently clocked task.}
6557 %K @r{link to the currently clocked task.}
6558 %n @r{user name (taken from @code{user-full-name}).}
6559 %f @r{file visited by current buffer when org-capture was called.}
6560 %F @r{full path of the file or directory visited by current buffer.}
6561 %:keyword @r{specific information for certain link types, see below.}
6562 %^g @r{prompt for tags, with completion on tags in target file.}
6563 %^G @r{prompt for tags, with completion all tags in all agenda files.}
6564 %^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}.}
6565 @r{You may define a prompt like @code{%^@{Birthday@}t}.}
6566 %^C @r{Interactive selection of which kill or clip to use.}
6567 %^L @r{Like @code{%^C}, but insert as link.}
6568 %^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}.}
6569 %^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.}
6570 @r{You may specify a default value and a completion table with}
6571 @r{%^@{prompt|default|completion2|completion3...@}.}
6572 @r{The arrow keys access a prompt-specific history.}
6573 @end smallexample
6574
6575 @noindent
6576 For specific link types, the following keywords will be
6577 defined@footnote{If you define your own link types (@pxref{Adding
6578 hyperlink types}), any property you store with
6579 @code{org-store-link-props} can be accessed in capture templates in a
6580 similar way.}:
6581
6582 @vindex org-from-is-user-regexp
6583 @smallexample
6584 Link type | Available keywords
6585 ------------------------+----------------------------------------------
6586 bbdb | %:name %:company
6587 irc | %:server %:port %:nick
6588 vm, wl, mh, mew, rmail | %:type %:subject %:message-id
6589 | %:from %:fromname %:fromaddress
6590 | %:to %:toname %:toaddress
6591 | %:date @r{(message date header field)}
6592 | %:date-timestamp @r{(date as active timestamp)}
6593 | %:date-timestamp-inactive @r{(date as inactive timestamp)}
6594 | %: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}.}}
6595 gnus | %:group, @r{for messages also all email fields}
6596 w3, w3m | %:url
6597 info | %:file %:node
6598 calendar | %:date
6599 @end smallexample
6600
6601 @noindent
6602 To place the cursor after template expansion use:
6603
6604 @smallexample
6605 %? @r{After completing the template, position cursor here.}
6606 @end smallexample
6607
6608
6609 @node Attachments, RSS Feeds, Capture, Capture - Refile - Archive
6610 @section Attachments
6611 @cindex attachments
6612
6613 @vindex org-attach-directory
6614 It is often useful to associate reference material with an outline node/task.
6615 Small chunks of plain text can simply be stored in the subtree of a project.
6616 Hyperlinks (@pxref{Hyperlinks}) can establish associations with
6617 files that live elsewhere on your computer or in the cloud, like emails or
6618 source code files belonging to a project. Another method is @i{attachments},
6619 which are files located in a directory belonging to an outline node. Org
6620 uses directories named by the unique ID of each entry. These directories are
6621 located in the @file{data} directory which lives in the same directory where
6622 your Org file lives@footnote{If you move entries or Org files from one
6623 directory to another, you may want to configure @code{org-attach-directory}
6624 to contain an absolute path.}. If you initialize this directory with
6625 @code{git init}, Org will automatically commit changes when it sees them.
6626 The attachment system has been contributed to Org by John Wiegley.
6627
6628 In cases where it seems better to do so, you can also attach a directory of your
6629 choice to an entry. You can also make children inherit the attachment
6630 directory from a parent, so that an entire subtree uses the same attached
6631 directory.
6632
6633 @noindent The following commands deal with attachments:
6634
6635 @table @kbd
6636
6637 @orgcmd{C-c C-a,org-attach}
6638 The dispatcher for commands related to the attachment system. After these
6639 keys, a list of commands is displayed and you must press an additional key
6640 to select a command:
6641
6642 @table @kbd
6643 @orgcmdtkc{a,C-c C-a a,org-attach-attach}
6644 @vindex org-attach-method
6645 Select a file and move it into the task's attachment directory. The file
6646 will be copied, moved, or linked, depending on @code{org-attach-method}.
6647 Note that hard links are not supported on all systems.
6648
6649 @kindex C-c C-a c
6650 @kindex C-c C-a m
6651 @kindex C-c C-a l
6652 @item c/m/l
6653 Attach a file using the copy/move/link method.
6654 Note that hard links are not supported on all systems.
6655
6656 @orgcmdtkc{n,C-c C-a n,org-attach-new}
6657 Create a new attachment as an Emacs buffer.
6658
6659 @orgcmdtkc{z,C-c C-a z,org-attach-sync}
6660 Synchronize the current task with its attachment directory, in case you added
6661 attachments yourself.
6662
6663 @orgcmdtkc{o,C-c C-a o,org-attach-open}
6664 @vindex org-file-apps
6665 Open current task's attachment. If there is more than one, prompt for a
6666 file name first. Opening will follow the rules set by @code{org-file-apps}.
6667 For more details, see the information on following hyperlinks
6668 (@pxref{Handling links}).
6669
6670 @orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs}
6671 Also open the attachment, but force opening the file in Emacs.
6672
6673 @orgcmdtkc{f,C-c C-a f,org-attach-reveal}
6674 Open the current task's attachment directory.
6675
6676 @orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs}
6677 Also open the directory, but force using @command{dired} in Emacs.
6678
6679 @orgcmdtkc{d,C-c C-a d,org-attach-delete-one}
6680 Select and delete a single attachment.
6681
6682 @orgcmdtkc{D,C-c C-a D,org-attach-delete-all}
6683 Delete all of a task's attachments. A safer way is to open the directory in
6684 @command{dired} and delete from there.
6685
6686 @orgcmdtkc{s,C-c C-a s,org-attach-set-directory}
6687 @cindex property, ATTACH_DIR
6688 Set a specific directory as the entry's attachment directory. This works by
6689 putting the directory path into the @code{ATTACH_DIR} property.
6690
6691 @orgcmdtkc{i,C-c C-a i,org-attach-set-inherit}
6692 @cindex property, ATTACH_DIR_INHERIT
6693 Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the
6694 same directory for attachments as the parent does.
6695 @end table
6696 @end table
6697
6698 @node RSS Feeds, Protocols, Attachments, Capture - Refile - Archive
6699 @section RSS feeds
6700 @cindex RSS feeds
6701 @cindex Atom feeds
6702
6703 Org can add and change entries based on information found in RSS feeds and
6704 Atom feeds. You could use this to make a task out of each new podcast in a
6705 podcast feed. Or you could use a phone-based note-creating service on the
6706 web to import tasks into Org. To access feeds, configure the variable
6707 @code{org-feed-alist}. The docstring of this variable has detailed
6708 information. Here is just an example:
6709
6710 @example
6711 (setq org-feed-alist
6712 '(("Slashdot"
6713 "http://rss.slashdot.org/Slashdot/slashdot"
6714 "~/txt/org/feeds.org" "Slashdot Entries")))
6715 @end example
6716
6717 @noindent
6718 will configure that new items from the feed provided by
6719 @code{rss.slashdot.org} will result in new entries in the file
6720 @file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
6721 the following command is used:
6722
6723 @table @kbd
6724 @orgcmd{C-c C-x g,org-feed-update-all}
6725 @item C-c C-x g
6726 Collect items from the feeds configured in @code{org-feed-alist} and act upon
6727 them.
6728 @orgcmd{C-c C-x G,org-feed-goto-inbox}
6729 Prompt for a feed name and go to the inbox configured for this feed.
6730 @end table
6731
6732 Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which
6733 it will store information about the status of items in the feed, to avoid
6734 adding the same item several times. You should add @samp{FEEDSTATUS} to the
6735 list of drawers in that file:
6736
6737 @example
6738 #+DRAWERS: LOGBOOK PROPERTIES FEEDSTATUS
6739 @end example
6740
6741 For more information, including how to read atom feeds, see
6742 @file{org-feed.el} and the docstring of @code{org-feed-alist}.
6743
6744 @node Protocols, Refiling notes, RSS Feeds, Capture - Refile - Archive
6745 @section Protocols for external access
6746 @cindex protocols, for external access
6747 @cindex emacsserver
6748
6749 You can set up Org for handling protocol calls from outside applications that
6750 are passed to Emacs through the @file{emacsserver}. For example, you can
6751 configure bookmarks in your web browser to send a link to the current page to
6752 Org and create a note from it using capture (@pxref{Capture}). Or you
6753 could create a bookmark that will tell Emacs to open the local source file of
6754 a remote website you are looking at with the browser. See
6755 @uref{http://orgmode.org/worg/org-contrib/org-protocol.php} for detailed
6756 documentation and setup instructions.
6757
6758 @node Refiling notes, Archiving, Protocols, Capture - Refile - Archive
6759 @section Refiling notes
6760 @cindex refiling notes
6761
6762 When reviewing the captured data, you may want to refile some of the entries
6763 into a different list, for example into a project. Cutting, finding the
6764 right location, and then pasting the note is cumbersome. To simplify this
6765 process, you can use the following special command:
6766
6767 @table @kbd
6768 @orgcmd{C-c C-w,org-refile}
6769 @vindex org-reverse-note-order
6770 @vindex org-refile-targets
6771 @vindex org-refile-use-outline-path
6772 @vindex org-outline-path-complete-in-steps
6773 @vindex org-refile-allow-creating-parent-nodes
6774 @vindex org-log-refile
6775 @vindex org-refile-use-cache
6776 Refile the entry or region at point. This command offers possible locations
6777 for refiling the entry and lets you select one with completion. The item (or
6778 all items in the region) is filed below the target heading as a subitem.
6779 Depending on @code{org-reverse-note-order}, it will be either the first or
6780 last subitem.@*
6781 By default, all level 1 headlines in the current buffer are considered to be
6782 targets, but you can have more complex definitions across a number of files.
6783 See the variable @code{org-refile-targets} for details. If you would like to
6784 select a location via a file-path-like completion along the outline path, see
6785 the variables @code{org-refile-use-outline-path} and
6786 @code{org-outline-path-complete-in-steps}. If you would like to be able to
6787 create new nodes as new parents for refiling on the fly, check the
6788 variable @code{org-refile-allow-creating-parent-nodes}.
6789 When the variable @code{org-log-refile}@footnote{with corresponding
6790 @code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},
6791 and @code{nologrefile}} is set, a timestamp or a note will be
6792 recorded when an entry has been refiled.
6793 @orgkey{C-u C-c C-w}
6794 Use the refile interface to jump to a heading.
6795 @orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored}
6796 Jump to the location where @code{org-refile} last moved a tree to.
6797 @item C-2 C-c C-w
6798 Refile as the child of the item currently being clocked.
6799 @item C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w
6800
6801 @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}
6802
6803 Clear the target cache. Caching of refile targets can be turned on by
6804 setting @code{org-refile-use-cache}. To make the command see new possible
6805 targets, you have to clear the cache with this command.
6806 @end table
6807
6808 @node Archiving, , Refiling notes, Capture - Refile - Archive
6809 @section Archiving
6810 @cindex archiving
6811
6812 When a project represented by a (sub)tree is finished, you may want
6813 to move the tree out of the way and to stop it from contributing to the
6814 agenda. Archiving is important to keep your working files compact and global
6815 searches like the construction of agenda views fast.
6816
6817 @table @kbd
6818 @orgcmd{C-c C-x C-a,org-archive-subtree-default}
6819 @vindex org-archive-default-command
6820 Archive the current entry using the command specified in the variable
6821 @code{org-archive-default-command}.
6822 @end table
6823
6824 @menu
6825 * Moving subtrees:: Moving a tree to an archive file
6826 * Internal archiving:: Switch off a tree but keep it in the file
6827 @end menu
6828
6829 @node Moving subtrees, Internal archiving, Archiving, Archiving
6830 @subsection Moving a tree to the archive file
6831 @cindex external archiving
6832
6833 The most common archiving action is to move a project tree to another file,
6834 the archive file.
6835
6836 @table @kbd
6837 @orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
6838 @vindex org-archive-location
6839 Archive the subtree starting at the cursor position to the location
6840 given by @code{org-archive-location}.
6841 @orgkey{C-u C-c C-x C-s}
6842 Check if any direct children of the current headline could be moved to
6843 the archive. To do this, each subtree is checked for open TODO entries.
6844 If none are found, the command offers to move it to the archive
6845 location. If the cursor is @emph{not} on a headline when this command
6846 is invoked, the level 1 trees will be checked.
6847 @end table
6848
6849 @cindex archive locations
6850 The default archive location is a file in the same directory as the
6851 current file, with the name derived by appending @file{_archive} to the
6852 current file name. For information and examples on how to change this,
6853 see the documentation string of the variable
6854 @code{org-archive-location}. There is also an in-buffer option for
6855 setting this variable, for example@footnote{For backward compatibility,
6856 the following also works: If there are several such lines in a file,
6857 each specifies the archive location for the text below it. The first
6858 such line also applies to any text before its definition. However,
6859 using this method is @emph{strongly} deprecated as it is incompatible
6860 with the outline structure of the document. The correct method for
6861 setting multiple archive locations in a buffer is using properties.}:
6862
6863 @cindex #+ARCHIVE
6864 @example
6865 #+ARCHIVE: %s_done::
6866 @end example
6867
6868 @cindex property, ARCHIVE
6869 @noindent
6870 If you would like to have a special ARCHIVE location for a single entry
6871 or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
6872 location as the value (@pxref{Properties and Columns}).
6873
6874 @vindex org-archive-save-context-info
6875 When a subtree is moved, it receives a number of special properties that
6876 record context information like the file from where the entry came, its
6877 outline path the archiving time etc. Configure the variable
6878 @code{org-archive-save-context-info} to adjust the amount of information
6879 added.
6880
6881
6882 @node Internal archiving, , Moving subtrees, Archiving
6883 @subsection Internal archiving
6884
6885 If you want to just switch off (for agenda views) certain subtrees without
6886 moving them to a different file, you can use the @code{ARCHIVE tag}.
6887
6888 A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
6889 its location in the outline tree, but behaves in the following way:
6890 @itemize @minus
6891 @item
6892 @vindex org-cycle-open-archived-trees
6893 It does not open when you attempt to do so with a visibility cycling
6894 command (@pxref{Visibility cycling}). You can force cycling archived
6895 subtrees with @kbd{C-@key{TAB}}, or by setting the option
6896 @code{org-cycle-open-archived-trees}. Also normal outline commands like
6897 @code{show-all} will open archived subtrees.
6898 @item
6899 @vindex org-sparse-tree-open-archived-trees
6900 During sparse tree construction (@pxref{Sparse trees}), matches in
6901 archived subtrees are not exposed, unless you configure the option
6902 @code{org-sparse-tree-open-archived-trees}.
6903 @item
6904 @vindex org-agenda-skip-archived-trees
6905 During agenda view construction (@pxref{Agenda Views}), the content of
6906 archived trees is ignored unless you configure the option
6907 @code{org-agenda-skip-archived-trees}, in which case these trees will always
6908 be included. In the agenda you can press @kbd{v a} to get archives
6909 temporarily included.
6910 @item
6911 @vindex org-export-with-archived-trees
6912 Archived trees are not exported (@pxref{Exporting}), only the headline
6913 is. Configure the details using the variable
6914 @code{org-export-with-archived-trees}.
6915 @item
6916 @vindex org-columns-skip-archived-trees
6917 Archived trees are excluded from column view unless the variable
6918 @code{org-columns-skip-archived-trees} is configured to @code{nil}.
6919 @end itemize
6920
6921 The following commands help manage the ARCHIVE tag:
6922
6923 @table @kbd
6924 @orgcmd{C-c C-x a,org-toggle-archive-tag}
6925 Toggle the ARCHIVE tag for the current headline. When the tag is set,
6926 the headline changes to a shadowed face, and the subtree below it is
6927 hidden.
6928 @orgkey{C-u C-c C-x a}
6929 Check if any direct children of the current headline should be archived.
6930 To do this, each subtree is checked for open TODO entries. If none are
6931 found, the command offers to set the ARCHIVE tag for the child. If the
6932 cursor is @emph{not} on a headline when this command is invoked, the
6933 level 1 trees will be checked.
6934 @orgcmd{C-@kbd{TAB},org-force-cycle-archived}
6935 Cycle a tree even if it is tagged with ARCHIVE.
6936 @orgcmd{C-c C-x A,org-archive-to-archive-sibling}
6937 Move the current entry to the @emph{Archive Sibling}. This is a sibling of
6938 the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The
6939 entry becomes a child of that sibling and in this way retains a lot of its
6940 original context, including inherited tags and approximate position in the
6941 outline.
6942 @end table
6943
6944
6945 @node Agenda Views, Markup, Capture - Refile - Archive, Top
6946 @chapter Agenda views
6947 @cindex agenda views
6948
6949 Due to the way Org works, TODO items, time-stamped items, and
6950 tagged headlines can be scattered throughout a file or even a number of
6951 files. To get an overview of open action items, or of events that are
6952 important for a particular date, this information must be collected,
6953 sorted and displayed in an organized way.
6954
6955 Org can select items based on various criteria and display them
6956 in a separate buffer. Seven different view types are provided:
6957
6958 @itemize @bullet
6959 @item
6960 an @emph{agenda} that is like a calendar and shows information
6961 for specific dates,
6962 @item
6963 a @emph{TODO list} that covers all unfinished
6964 action items,
6965 @item
6966 a @emph{match view}, showings headlines based on the tags, properties, and
6967 TODO state associated with them,
6968 @item
6969 a @emph{timeline view} that shows all events in a single Org file,
6970 in time-sorted view,
6971 @item
6972 a @emph{text search view} that shows all entries from multiple files
6973 that contain specified keywords,
6974 @item
6975 a @emph{stuck projects view} showing projects that currently don't move
6976 along, and
6977 @item
6978 @emph{custom views} that are special searches and combinations of different
6979 views.
6980 @end itemize
6981
6982 @noindent
6983 The extracted information is displayed in a special @emph{agenda
6984 buffer}. This buffer is read-only, but provides commands to visit the
6985 corresponding locations in the original Org files, and even to
6986 edit these files remotely.
6987
6988 @vindex org-agenda-window-setup
6989 @vindex org-agenda-restore-windows-after-quit
6990 Two variables control how the agenda buffer is displayed and whether the
6991 window configuration is restored when the agenda exits:
6992 @code{org-agenda-window-setup} and
6993 @code{org-agenda-restore-windows-after-quit}.
6994
6995 @menu
6996 * Agenda files:: Files being searched for agenda information
6997 * Agenda dispatcher:: Keyboard access to agenda views
6998 * Built-in agenda views:: What is available out of the box?
6999 * Presentation and sorting:: How agenda items are prepared for display
7000 * Agenda commands:: Remote editing of Org trees
7001 * Custom agenda views:: Defining special searches and views
7002 * Exporting Agenda Views:: Writing a view to a file
7003 * Agenda column view:: Using column view for collected entries
7004 @end menu
7005
7006 @node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views
7007 @section Agenda files
7008 @cindex agenda files
7009 @cindex files for agenda
7010
7011 @vindex org-agenda-files
7012 The information to be shown is normally collected from all @emph{agenda
7013 files}, the files listed in the variable
7014 @code{org-agenda-files}@footnote{If the value of that variable is not a
7015 list, but a single file name, then the list of agenda files will be
7016 maintained in that external file.}. If a directory is part of this list,
7017 all files with the extension @file{.org} in this directory will be part
7018 of the list.
7019
7020 Thus, even if you only work with a single Org file, that file should
7021 be put into the list@footnote{When using the dispatcher, pressing
7022 @kbd{<} before selecting a command will actually limit the command to
7023 the current file, and ignore @code{org-agenda-files} until the next
7024 dispatcher command.}. You can customize @code{org-agenda-files}, but
7025 the easiest way to maintain it is through the following commands
7026
7027 @cindex files, adding to agenda list
7028 @table @kbd
7029 @orgcmd{C-c [,org-agenda-file-to-front}
7030 Add current file to the list of agenda files. The file is added to
7031 the front of the list. If it was already in the list, it is moved to
7032 the front. With a prefix argument, file is added/moved to the end.
7033 @orgcmd{C-c ],org-remove-file}
7034 Remove current file from the list of agenda files.
7035 @kindex C-,
7036 @orgcmd{C-',org-cycle-agenda-files}
7037 @itemx C-,
7038 Cycle through agenda file list, visiting one file after the other.
7039 @kindex M-x org-iswitchb
7040 @item M-x org-iswitchb
7041 Command to use an @code{iswitchb}-like interface to switch to and between Org
7042 buffers.
7043 @end table
7044
7045 @noindent
7046 The Org menu contains the current list of files and can be used
7047 to visit any of them.
7048
7049 If you would like to focus the agenda temporarily on a file not in
7050 this list, or on just one file in the list, or even on only a subtree in a
7051 file, then this can be done in different ways. For a single agenda command,
7052 you may press @kbd{<} once or several times in the dispatcher
7053 (@pxref{Agenda dispatcher}). To restrict the agenda scope for an
7054 extended period, use the following commands:
7055
7056 @table @kbd
7057 @orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
7058 Permanently restrict the agenda to the current subtree. When with a
7059 prefix argument, or with the cursor before the first headline in a file,
7060 the agenda scope is set to the entire file. This restriction remains in
7061 effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
7062 or @kbd{>} in the agenda dispatcher. If there is a window displaying an
7063 agenda view, the new restriction takes effect immediately.
7064 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
7065 Remove the permanent restriction created by @kbd{C-c C-x <}.
7066 @end table
7067
7068 @noindent
7069 When working with @file{speedbar.el}, you can use the following commands in
7070 the Speedbar frame:
7071 @table @kbd
7072 @orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
7073 Permanently restrict the agenda to the item---either an Org file or a subtree
7074 in such a file---at the cursor in the Speedbar frame.
7075 If there is a window displaying an agenda view, the new restriction takes
7076 effect immediately.
7077 @orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
7078 Lift the restriction.
7079 @end table
7080
7081 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views
7082 @section The agenda dispatcher
7083 @cindex agenda dispatcher
7084 @cindex dispatching agenda commands
7085 The views are created through a dispatcher, which should be bound to a
7086 global key---for example @kbd{C-c a} (@pxref{Activation}). In the
7087 following we will assume that @kbd{C-c a} is indeed how the dispatcher
7088 is accessed and list keyboard access to commands accordingly. After
7089 pressing @kbd{C-c a}, an additional letter is required to execute a
7090 command. The dispatcher offers the following default commands:
7091 @table @kbd
7092 @item a
7093 Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
7094 @item t @r{/} T
7095 Create a list of all TODO items (@pxref{Global TODO list}).
7096 @item m @r{/} M
7097 Create a list of headlines matching a TAGS expression (@pxref{Matching
7098 tags and properties}).
7099 @item L
7100 Create the timeline view for the current buffer (@pxref{Timeline}).
7101 @item s
7102 Create a list of entries selected by a boolean expression of keywords
7103 and/or regular expressions that must or must not occur in the entry.
7104 @item /
7105 @vindex org-agenda-text-search-extra-files
7106 Search for a regular expression in all agenda files and additionally in
7107 the files listed in @code{org-agenda-text-search-extra-files}. This
7108 uses the Emacs command @code{multi-occur}. A prefix argument can be
7109 used to specify the number of context lines for each match, default is
7110 1.
7111 @item # @r{/} !
7112 Create a list of stuck projects (@pxref{Stuck projects}).
7113 @item <
7114 Restrict an agenda command to the current buffer@footnote{For backward
7115 compatibility, you can also press @kbd{1} to restrict to the current
7116 buffer.}. After pressing @kbd{<}, you still need to press the character
7117 selecting the command.
7118 @item < <
7119 If there is an active region, restrict the following agenda command to
7120 the region. Otherwise, restrict it to the current subtree@footnote{For
7121 backward compatibility, you can also press @kbd{0} to restrict to the
7122 current region/subtree.}. After pressing @kbd{< <}, you still need to press the
7123 character selecting the command.
7124 @end table
7125
7126 You can also define custom commands that will be accessible through the
7127 dispatcher, just like the default commands. This includes the
7128 possibility to create extended agenda buffers that contain several
7129 blocks together, for example the weekly agenda, the global TODO list and
7130 a number of special tags matches. @xref{Custom agenda views}.
7131
7132 @node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda Views
7133 @section The built-in agenda views
7134
7135 In this section we describe the built-in views.
7136
7137 @menu
7138 * Weekly/daily agenda:: The calendar page with current tasks
7139 * Global TODO list:: All unfinished action items
7140 * Matching tags and properties:: Structured information with fine-tuned search
7141 * Timeline:: Time-sorted view for single file
7142 * Search view:: Find entries by searching for text
7143 * Stuck projects:: Find projects you need to review
7144 @end menu
7145
7146 @node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
7147 @subsection The weekly/daily agenda
7148 @cindex agenda
7149 @cindex weekly agenda
7150 @cindex daily agenda
7151
7152 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
7153 paper agenda, showing all the tasks for the current week or day.
7154
7155 @table @kbd
7156 @cindex org-agenda, command
7157 @orgcmd{C-c a a,org-agenda-list}
7158 Compile an agenda for the current week from a list of Org files. The agenda
7159 shows the entries for each day. With a numeric prefix@footnote{For backward
7160 compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be
7161 listed before the agenda. This feature is deprecated, use the dedicated TODO
7162 list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1
7163 C-c a a}) you may set the number of days to be displayed.
7164 @end table
7165
7166 @vindex org-agenda-span
7167 @vindex org-agenda-ndays
7168 The default number of days displayed in the agenda is set by the variable
7169 @code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This
7170 variable can be set to any number of days you want to see by default in the
7171 agenda, or to a span name, such a @code{day}, @code{week}, @code{month} or
7172 @code{year}.
7173
7174 Remote editing from the agenda buffer means, for example, that you can
7175 change the dates of deadlines and appointments from the agenda buffer.
7176 The commands available in the Agenda buffer are listed in @ref{Agenda
7177 commands}.
7178
7179 @subsubheading Calendar/Diary integration
7180 @cindex calendar integration
7181 @cindex diary integration
7182
7183 Emacs contains the calendar and diary by Edward M. Reingold. The
7184 calendar displays a three-month calendar with holidays from different
7185 countries and cultures. The diary allows you to keep track of
7186 anniversaries, lunar phases, sunrise/set, recurrent appointments
7187 (weekly, monthly) and more. In this way, it is quite complementary to
7188 Org. It can be very useful to combine output from Org with
7189 the diary.
7190
7191 In order to include entries from the Emacs diary into Org-mode's
7192 agenda, you only need to customize the variable
7193
7194 @lisp
7195 (setq org-agenda-include-diary t)
7196 @end lisp
7197
7198 @noindent After that, everything will happen automatically. All diary
7199 entries including holidays, anniversaries, etc., will be included in the
7200 agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and
7201 @key{RET} can be used from the agenda buffer to jump to the diary
7202 file in order to edit existing diary entries. The @kbd{i} command to
7203 insert new entries for the current date works in the agenda buffer, as
7204 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
7205 Sunrise/Sunset times, show lunar phases and to convert to other
7206 calendars, respectively. @kbd{c} can be used to switch back and forth
7207 between calendar and agenda.
7208
7209 If you are using the diary only for sexp entries and holidays, it is
7210 faster to not use the above setting, but instead to copy or even move
7211 the entries into an Org file. Org-mode evaluates diary-style sexp
7212 entries, and does it faster because there is no overhead for first
7213 creating the diary display. Note that the sexp entries must start at
7214 the left margin, no whitespace is allowed before them. For example,
7215 the following segment of an Org file will be processed and entries
7216 will be made in the agenda:
7217
7218 @example
7219 * Birthdays and similar stuff
7220 #+CATEGORY: Holiday
7221 %%(org-calendar-holiday) ; special function for holiday names
7222 #+CATEGORY: Ann
7223 %%(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
7224 %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
7225 @end example
7226
7227 @subsubheading Anniversaries from BBDB
7228 @cindex BBDB, anniversaries
7229 @cindex anniversaries, from BBDB
7230
7231 If you are using the Big Brothers Database to store your contacts, you will
7232 very likely prefer to store anniversaries in BBDB rather than in a
7233 separate Org or diary file. Org supports this and will show BBDB
7234 anniversaries as part of the agenda. All you need to do is to add the
7235 following to one your your agenda files:
7236
7237 @example
7238 * Anniversaries
7239 :PROPERTIES:
7240 :CATEGORY: Anniv
7241 :END:
7242 %%(org-bbdb-anniversaries)
7243 @end example
7244
7245 You can then go ahead and define anniversaries for a BBDB record. Basically,
7246 you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
7247 record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
7248 followed by a space and the class of the anniversary (@samp{birthday} or
7249 @samp{wedding}, or a format string). If you omit the class, it will default to
7250 @samp{birthday}. Here are a few examples, the header for the file
7251 @file{org-bbdb.el} contains more detailed information.
7252
7253 @example
7254 1973-06-22
7255 06-22
7256 1955-08-02 wedding
7257 2008-04-14 %s released version 6.01 of org-mode, %d years ago
7258 @end example
7259
7260 After a change to BBDB, or for the first agenda display during an Emacs
7261 session, the agenda display will suffer a short delay as Org updates its
7262 hash with anniversaries. However, from then on things will be very fast---much
7263 faster in fact than a long list of @samp{%%(diary-anniversary)} entries
7264 in an Org or Diary file.
7265
7266 @subsubheading Appointment reminders
7267 @cindex @file{appt.el}
7268 @cindex appointment reminders
7269
7270 Org can interact with Emacs appointments notification facility. To add all
7271 the appointments of your agenda files, use the command
7272 @code{org-agenda-to-appt}. This command also lets you filter through the
7273 list of your appointments and add only those belonging to a specific category
7274 or matching a regular expression. See the docstring for details.
7275
7276 @node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views
7277 @subsection The global TODO list
7278 @cindex global TODO list
7279 @cindex TODO list, global
7280
7281 The global TODO list contains all unfinished TODO items formatted and
7282 collected into a single place.
7283
7284 @table @kbd
7285 @orgcmd{C-c a t,org-todo-list}
7286 Show the global TODO list. This collects the TODO items from all agenda
7287 files (@pxref{Agenda Views}) into a single buffer. By default, this lists
7288 items with a state the is not a DONE state. The buffer is in
7289 @code{agenda-mode}, so there are commands to examine and manipulate the TODO
7290 entries directly from that buffer (@pxref{Agenda commands}).
7291 @orgcmd{C-c a T,org-todo-list}
7292 @cindex TODO keyword matching
7293 @vindex org-todo-keywords
7294 Like the above, but allows selection of a specific TODO keyword. You can
7295 also do this by specifying a prefix argument to @kbd{C-c a t}. You are
7296 prompted for a keyword, and you may also specify several keywords by
7297 separating them with @samp{|} as the boolean OR operator. With a numeric
7298 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
7299 @kindex r
7300 The @kbd{r} key in the agenda buffer regenerates it, and you can give
7301 a prefix argument to this command to change the selected TODO keyword,
7302 for example @kbd{3 r}. If you often need a search for a specific
7303 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
7304 Matching specific TODO keywords can also be done as part of a tags
7305 search (@pxref{Tag searches}).
7306 @end table
7307
7308 Remote editing of TODO items means that you can change the state of a
7309 TODO entry with a single key press. The commands available in the
7310 TODO list are described in @ref{Agenda commands}.
7311
7312 @cindex sublevels, inclusion into TODO list
7313 Normally the global TODO list simply shows all headlines with TODO
7314 keywords. This list can become very long. There are two ways to keep
7315 it more compact:
7316 @itemize @minus
7317 @item
7318 @vindex org-agenda-todo-ignore-scheduled
7319 @vindex org-agenda-todo-ignore-deadlines
7320 @vindex org-agenda-todo-ignore-timestamp
7321 @vindex org-agenda-todo-ignore-with-date
7322 Some people view a TODO item that has been @emph{scheduled} for execution or
7323 have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.
7324 Configure the variables @code{org-agenda-todo-ignore-scheduled},
7325 @code{org-agenda-todo-ignore-deadlines},
7326 @code{org-agenda-todo-ignore-timestamp} and/or
7327 @code{org-agenda-todo-ignore-with-date} to exclude such items from the global
7328 TODO list.
7329 @item
7330 @vindex org-agenda-todo-list-sublevels
7331 TODO items may have sublevels to break up the task into subtasks. In
7332 such cases it may be enough to list only the highest level TODO headline
7333 and omit the sublevels from the global list. Configure the variable
7334 @code{org-agenda-todo-list-sublevels} to get this behavior.
7335 @end itemize
7336
7337 @node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views
7338 @subsection Matching tags and properties
7339 @cindex matching, of tags
7340 @cindex matching, of properties
7341 @cindex tags view
7342 @cindex match view
7343
7344 If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
7345 or have properties (@pxref{Properties and Columns}), you can select headlines
7346 based on this metadata and collect them into an agenda buffer. The match
7347 syntax described here also applies when creating sparse trees with @kbd{C-c /
7348 m}.
7349
7350 @table @kbd
7351 @orgcmd{C-c a m,org-tags-view}
7352 Produce a list of all headlines that match a given set of tags. The
7353 command prompts for a selection criterion, which is a boolean logic
7354 expression with tags, like @samp{+work+urgent-withboss} or
7355 @samp{work|home} (@pxref{Tags}). If you often need a specific search,
7356 define a custom command for it (@pxref{Agenda dispatcher}).
7357 @orgcmd{C-c a M,org-tags-view}
7358 @vindex org-tags-match-list-sublevels
7359 @vindex org-agenda-tags-todo-honor-ignore-options
7360 Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
7361 not-DONE state and force checking subitems (see variable
7362 @code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items,
7363 see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching
7364 specific TODO keywords together with a tags match is also possible, see
7365 @ref{Tag searches}.
7366 @end table
7367
7368 The commands available in the tags list are described in @ref{Agenda
7369 commands}.
7370
7371 @subsubheading Match syntax
7372
7373 @cindex Boolean logic, for tag/property searches
7374 A search string can use Boolean operators @samp{&} for AND and @samp{|} for
7375 OR. @samp{&} binds more strongly than @samp{|}. Parentheses are currently
7376 not implemented. Each element in the search is either a tag, a regular
7377 expression matching tags, or an expression like @code{PROPERTY OPERATOR
7378 VALUE} with a comparison operator, accessing a property value. Each element
7379 may be preceded by @samp{-}, to select against it, and @samp{+} is syntactic
7380 sugar for positive selection. The AND operator @samp{&} is optional when
7381 @samp{+} or @samp{-} is present. Here are some examples, using only tags.
7382
7383 @table @samp
7384 @item +work-boss
7385 Select headlines tagged @samp{:work:}, but discard those also tagged
7386 @samp{:boss:}.
7387 @item work|laptop
7388 Selects lines tagged @samp{:work:} or @samp{:laptop:}.
7389 @item work|laptop+night
7390 Like before, but require the @samp{:laptop:} lines to be tagged also
7391 @samp{:night:}.
7392 @end table
7393
7394 @cindex regular expressions, with tags search
7395 Instead of a tag, you may also specify a regular expression enclosed in curly
7396 braces. For example,
7397 @samp{work+@{^boss.*@}} matches headlines that contain the tag
7398 @samp{:work:} and any tag @i{starting} with @samp{boss}.
7399
7400 @cindex TODO keyword matching, with tags search
7401 @cindex level, require for tags/property match
7402 @cindex category, require for tags/property match
7403 @vindex org-odd-levels-only
7404 You may also test for properties (@pxref{Properties and Columns}) at the same
7405 time as matching tags. The properties may be real properties, or special
7406 properties that represent other metadata (@pxref{Special properties}). For
7407 example, the ``property'' @code{TODO} represents the TODO keyword of the
7408 entry. Or, the ``property'' @code{LEVEL} represents the level of an entry.
7409 So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all level three headlines
7410 that have the tag @samp{boss} and are @emph{not} marked with the TODO keyword
7411 DONE. In buffers with @code{org-odd-levels-only} set, @samp{LEVEL} does not
7412 count the number of stars, but @samp{LEVEL=2} will correspond to 3 stars etc.
7413
7414 Here are more examples:
7415 @table @samp
7416 @item work+TODO="WAITING"
7417 Select @samp{:work:}-tagged TODO lines with the specific TODO
7418 keyword @samp{WAITING}.
7419 @item work+TODO="WAITING"|home+TODO="WAITING"
7420 Waiting tasks both at work and at home.
7421 @end table
7422
7423 When matching properties, a number of different operators can be used to test
7424 the value of a property. Here is a complex example:
7425
7426 @example
7427 +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \
7428 +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
7429 @end example
7430
7431 @noindent
7432 The type of comparison will depend on how the comparison value is written:
7433 @itemize @minus
7434 @item
7435 If the comparison value is a plain number, a numerical comparison is done,
7436 and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
7437 @samp{>=}, and @samp{<>}.
7438 @item
7439 If the comparison value is enclosed in double-quotes,
7440 a string comparison is done, and the same operators are allowed.
7441 @item
7442 If the comparison value is enclosed in double-quotes @emph{and} angular
7443 brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
7444 assumed to be date/time specifications in the standard Org way, and the
7445 comparison will be done accordingly. Special values that will be recognized
7446 are @code{"<now>"} for now (including time), and @code{"<today>"}, and
7447 @code{"<tomorrow>"} for these days at 0:00 hours, i.e.@: without a time
7448 specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
7449 @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
7450 respectively, can be used.
7451 @item
7452 If the comparison value is enclosed
7453 in curly braces, a regexp match is performed, with @samp{=} meaning that the
7454 regexp matches the property value, and @samp{<>} meaning that it does not
7455 match.
7456 @end itemize
7457
7458 So the search string in the example finds entries tagged @samp{:work:} but
7459 not @samp{:boss:}, which also have a priority value @samp{A}, a
7460 @samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
7461 property that is numerically smaller than 2, a @samp{:With:} property that is
7462 matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
7463 on or after October 11, 2008.
7464
7465 Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing any
7466 other properties will slow down the search. However, once you have paid the
7467 price by accessing one property, testing additional properties is cheap
7468 again.
7469
7470 You can configure Org-mode to use property inheritance during a search, but
7471 beware that this can slow down searches considerably. See @ref{Property
7472 inheritance}, for details.
7473
7474 For backward compatibility, and also for typing speed, there is also a
7475 different way to test TODO states in a search. For this, terminate the
7476 tags/property part of the search string (which may include several terms
7477 connected with @samp{|}) with a @samp{/} and then specify a Boolean
7478 expression just for TODO keywords. The syntax is then similar to that for
7479 tags, but should be applied with care: for example, a positive selection on
7480 several TODO keywords cannot meaningfully be combined with boolean AND.
7481 However, @emph{negative selection} combined with AND can be meaningful. To
7482 make sure that only lines are checked that actually have any TODO keyword
7483 (resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
7484 part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will
7485 not match TODO keywords in a DONE state. Examples:
7486
7487 @table @samp
7488 @item work/WAITING
7489 Same as @samp{work+TODO="WAITING"}
7490 @item work/!-WAITING-NEXT
7491 Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
7492 nor @samp{NEXT}
7493 @item work/!+WAITING|+NEXT
7494 Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
7495 @samp{NEXT}.
7496 @end table
7497
7498 @node Timeline, Search view, Matching tags and properties, Built-in agenda views
7499 @subsection Timeline for a single file
7500 @cindex timeline, single file
7501 @cindex time-sorted view
7502
7503 The timeline summarizes all time-stamped items from a single Org-mode
7504 file in a @emph{time-sorted view}. The main purpose of this command is
7505 to give an overview over events in a project.
7506
7507 @table @kbd
7508 @orgcmd{C-c a L,org-timeline}
7509 Show a time-sorted view of the Org file, with all time-stamped items.
7510 When called with a @kbd{C-u} prefix, all unfinished TODO entries
7511 (scheduled or not) are also listed under the current date.
7512 @end table
7513
7514 @noindent
7515 The commands available in the timeline buffer are listed in
7516 @ref{Agenda commands}.
7517
7518 @node Search view, Stuck projects, Timeline, Built-in agenda views
7519 @subsection Search view
7520 @cindex search view
7521 @cindex text search
7522 @cindex searching, for text
7523
7524 This agenda view is a general text search facility for Org-mode entries.
7525 It is particularly useful to find notes.
7526
7527 @table @kbd
7528 @orgcmd{C-c a s,org-search-view}
7529 This is a special search that lets you select entries by matching a substring
7530 or specific words using a boolean logic.
7531 @end table
7532 For example, the search string @samp{computer equipment} will find entries
7533 that contain @samp{computer equipment} as a substring. If the two words are
7534 separated by more space or a line break, the search will still match.
7535 Search view can also search for specific keywords in the entry, using Boolean
7536 logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
7537 will search for note entries that contain the keywords @code{computer}
7538 and @code{wifi}, but not the keyword @code{ethernet}, and which are also
7539 not matched by the regular expression @code{8\.11[bg]}, meaning to
7540 exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on
7541 word search, other @samp{+} characters are optional. For more details, see
7542 the docstring of the command @code{org-search-view}.
7543
7544 @vindex org-agenda-text-search-extra-files
7545 Note that in addition to the agenda files, this command will also search
7546 the files listed in @code{org-agenda-text-search-extra-files}.
7547
7548 @node Stuck projects, , Search view, Built-in agenda views
7549 @subsection Stuck projects
7550 @pindex GTD, Getting Things Done
7551
7552 If you are following a system like David Allen's GTD to organize your
7553 work, one of the ``duties'' you have is a regular review to make sure
7554 that all projects move along. A @emph{stuck} project is a project that
7555 has no defined next actions, so it will never show up in the TODO lists
7556 Org-mode produces. During the review, you need to identify such
7557 projects and define next actions for them.
7558
7559 @table @kbd
7560 @orgcmd{C-c a #,org-agenda-list-stuck-projects}
7561 List projects that are stuck.
7562 @kindex C-c a !
7563 @item C-c a !
7564 @vindex org-stuck-projects
7565 Customize the variable @code{org-stuck-projects} to define what a stuck
7566 project is and how to find it.
7567 @end table
7568
7569 You almost certainly will have to configure this view before it will
7570 work for you. The built-in default assumes that all your projects are
7571 level-2 headlines, and that a project is not stuck if it has at least
7572 one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
7573
7574 Let's assume that you, in your own way of using Org-mode, identify
7575 projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
7576 indicate a project that should not be considered yet. Let's further
7577 assume that the TODO keyword DONE marks finished projects, and that NEXT
7578 and TODO indicate next actions. The tag @@SHOP indicates shopping and
7579 is a next action even without the NEXT tag. Finally, if the project
7580 contains the special word IGNORE anywhere, it should not be listed
7581 either. In this case you would start by identifying eligible projects
7582 with a tags/todo match@footnote{@xref{Tag searches}.}
7583 @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, and
7584 IGNORE in the subtree to identify projects that are not stuck. The
7585 correct customization for this is
7586
7587 @lisp
7588 (setq org-stuck-projects
7589 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
7590 "\\<IGNORE\\>"))
7591 @end lisp
7592
7593 Note that if a project is identified as non-stuck, the subtree of this entry
7594 will still be searched for stuck projects.
7595
7596 @node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda Views
7597 @section Presentation and sorting
7598 @cindex presentation, of agenda items
7599
7600 @vindex org-agenda-prefix-format
7601 @vindex org-agenda-tags-column
7602 Before displaying items in an agenda view, Org-mode visually prepares the
7603 items and sorts them. Each item occupies a single line. The line starts
7604 with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
7605 of the item and other important information. You can customize in which
7606 column tags will be displayed through @code{org-agenda-tags-column}. You can
7607 also customize the prefix using the option @code{org-agenda-prefix-format}.
7608 This prefix is followed by a cleaned-up version of the outline headline
7609 associated with the item.
7610
7611 @menu
7612 * Categories:: Not all tasks are equal
7613 * Time-of-day specifications:: How the agenda knows the time
7614 * Sorting of agenda items:: The order of things
7615 @end menu
7616
7617 @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
7618 @subsection Categories
7619
7620 @cindex category
7621 @cindex #+CATEGORY
7622 The category is a broad label assigned to each agenda item. By default,
7623 the category is simply derived from the file name, but you can also
7624 specify it with a special line in the buffer, like this@footnote{For
7625 backward compatibility, the following also works: if there are several
7626 such lines in a file, each specifies the category for the text below it.
7627 The first category also applies to any text before the first CATEGORY
7628 line. However, using this method is @emph{strongly} deprecated as it is
7629 incompatible with the outline structure of the document. The correct
7630 method for setting multiple categories in a buffer is using a
7631 property.}:
7632
7633 @example
7634 #+CATEGORY: Thesis
7635 @end example
7636
7637 @noindent
7638 @cindex property, CATEGORY
7639 If you would like to have a special CATEGORY for a single entry or a
7640 (sub)tree, give the entry a @code{:CATEGORY:} property with the
7641 special category you want to apply as the value.
7642
7643 @noindent
7644 The display in the agenda buffer looks best if the category is not
7645 longer than 10 characters.
7646
7647 @noindent
7648 You can set up icons for category by customizing the
7649 @code{org-agenda-category-icon-alist} variable.
7650
7651 @node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
7652 @subsection Time-of-day specifications
7653 @cindex time-of-day specification
7654
7655 Org-mode checks each agenda item for a time-of-day specification. The
7656 time can be part of the timestamp that triggered inclusion into the
7657 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
7658 ranges can be specified with two timestamps, like
7659 @c
7660 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
7661
7662 In the headline of the entry itself, a time(range) may also appear as
7663 plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda
7664 integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
7665 specifications in diary entries are recognized as well.
7666
7667 For agenda display, Org-mode extracts the time and displays it in a
7668 standard 24 hour format as part of the prefix. The example times in
7669 the previous paragraphs would end up in the agenda like this:
7670
7671 @example
7672 8:30-13:00 Arthur Dent lies in front of the bulldozer
7673 12:45...... Ford Prefect arrives and takes Arthur to the pub
7674 19:00...... The Vogon reads his poem
7675 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
7676 @end example
7677
7678 @cindex time grid
7679 If the agenda is in single-day mode, or for the display of today, the
7680 timed entries are embedded in a time grid, like
7681
7682 @example
7683 8:00...... ------------------
7684 8:30-13:00 Arthur Dent lies in front of the bulldozer
7685 10:00...... ------------------
7686 12:00...... ------------------
7687 12:45...... Ford Prefect arrives and takes Arthur to the pub
7688 14:00...... ------------------
7689 16:00...... ------------------
7690 18:00...... ------------------
7691 19:00...... The Vogon reads his poem
7692 20:00...... ------------------
7693 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
7694 @end example
7695
7696 @vindex org-agenda-use-time-grid
7697 @vindex org-agenda-time-grid
7698 The time grid can be turned on and off with the variable
7699 @code{org-agenda-use-time-grid}, and can be configured with
7700 @code{org-agenda-time-grid}.
7701
7702 @node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting
7703 @subsection Sorting of agenda items
7704 @cindex sorting, of agenda items
7705 @cindex priorities, of agenda items
7706 Before being inserted into a view, the items are sorted. How this is
7707 done depends on the type of view.
7708 @itemize @bullet
7709 @item
7710 @vindex org-agenda-files
7711 For the daily/weekly agenda, the items for each day are sorted. The
7712 default order is to first collect all items containing an explicit
7713 time-of-day specification. These entries will be shown at the beginning
7714 of the list, as a @emph{schedule} for the day. After that, items remain
7715 grouped in categories, in the sequence given by @code{org-agenda-files}.
7716 Within each category, items are sorted by priority (@pxref{Priorities}),
7717 which is composed of the base priority (2000 for priority @samp{A}, 1000
7718 for @samp{B}, and 0 for @samp{C}), plus additional increments for
7719 overdue scheduled or deadline items.
7720 @item
7721 For the TODO list, items remain in the order of categories, but within
7722 each category, sorting takes place according to priority
7723 (@pxref{Priorities}). The priority used for sorting derives from the
7724 priority cookie, with additions depending on how close an item is to its due
7725 or scheduled date.
7726 @item
7727 For tags matches, items are not sorted at all, but just appear in the
7728 sequence in which they are found in the agenda files.
7729 @end itemize
7730
7731 @vindex org-agenda-sorting-strategy
7732 Sorting can be customized using the variable
7733 @code{org-agenda-sorting-strategy}, and may also include criteria based on
7734 the estimated effort of an entry (@pxref{Effort estimates}).
7735
7736 @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views
7737 @section Commands in the agenda buffer
7738 @cindex commands, in agenda buffer
7739
7740 Entries in the agenda buffer are linked back to the Org file or diary
7741 file where they originate. You are not allowed to edit the agenda
7742 buffer itself, but commands are provided to show and jump to the
7743 original entry location, and to edit the Org files ``remotely'' from
7744 the agenda buffer. In this way, all information is stored only once,
7745 removing the risk that your agenda and note files may diverge.
7746
7747 Some commands can be executed with mouse clicks on agenda lines. For
7748 the other commands, the cursor needs to be in the desired line.
7749
7750 @table @kbd
7751 @tsubheading{Motion}
7752 @cindex motion commands in agenda
7753 @orgcmd{n,org-agenda-next-line}
7754 Next line (same as @key{up} and @kbd{C-p}).
7755 @orgcmd{p,org-agenda-previous-line}
7756 Previous line (same as @key{down} and @kbd{C-n}).
7757 @tsubheading{View/Go to Org file}
7758 @orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
7759 Display the original location of the item in another window.
7760 With prefix arg, make sure that the entire entry is made visible in the
7761 outline, not only the heading.
7762 @c
7763 @orgcmd{L,org-agenda-recenter}
7764 Display original location and recenter that window.
7765 @c
7766 @orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
7767 Go to the original location of the item in another window.
7768 @c
7769 @orgcmd{@key{RET},org-agenda-switch-to}
7770 Go to the original location of the item and delete other windows.
7771 @c
7772 @orgcmd{F,org-agenda-follow-mode}
7773 @vindex org-agenda-start-with-follow-mode
7774 Toggle Follow mode. In Follow mode, as you move the cursor through
7775 the agenda buffer, the other window always shows the corresponding
7776 location in the Org file. The initial setting for this mode in new
7777 agenda buffers can be set with the variable
7778 @code{org-agenda-start-with-follow-mode}.
7779 @c
7780 @orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
7781 Display the entire subtree of the current item in an indirect buffer. With a
7782 numeric prefix argument N, go up to level N and then take that tree. If N is
7783 negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the
7784 previously used indirect buffer.
7785
7786 @orgcmd{C-c C-o,org-agenda-open-link}
7787 Follow a link in the entry. This will offer a selection of any links in the
7788 text belonging to the referenced Org node. If there is only one link, it
7789 will be followed without a selection prompt.
7790
7791 @tsubheading{Change display}
7792 @cindex display changing, in agenda
7793 @kindex A
7794 @item A
7795 Interactively select another agenda view and append it to the current view.
7796 @c
7797 @kindex o
7798 @item o
7799 Delete other windows.
7800 @c
7801 @orgcmdkskc{v d,d,org-aganda-day-view}
7802 @xorgcmdkskc{v w,w,org-aganda-day-view}
7803 @xorgcmd{v m,org-agenda-month-view}
7804 @xorgcmd{v y,org-agenda-month-year}
7805 @xorgcmd{v SPC,org-agenda-reset-view}
7806 @vindex org-agenda-span
7807 Switch to day/week/month/year view. When switching to day or week view, this
7808 setting becomes the default for subsequent agenda refreshes. Since month and
7809 year views are slow to create, they do not become the default. A numeric
7810 prefix argument may be used to jump directly to a specific day of the year,
7811 ISO week, month, or year, respectively. For example, @kbd{32 d} jumps to
7812 February 1st, @kbd{9 w} to ISO week number 9. When setting day, week, or
7813 month view, a year may be encoded in the prefix argument as well. For
7814 example, @kbd{200712 w} will jump to week 12 in 2007. If such a year
7815 specification has only one or two digits, it will be mapped to the interval
7816 1938-2037. @kbd{v @key{SPC}} will reset to what is set in
7817 @code{org-agenda-span}.
7818 @c
7819 @orgcmd{f,org-agenda-later}
7820 Go forward in time to display the following @code{org-agenda-current-span} days.
7821 For example, if the display covers a week, switch to the following week.
7822 With prefix arg, go forward that many times @code{org-agenda-current-span} days.
7823 @c
7824 @orgcmd{b,org-agenda-earlier}
7825 Go backward in time to display earlier dates.
7826 @c
7827 @orgcmd{.,org-agenda-goto-today}
7828 Go to today.
7829 @c
7830 @orgcmd{j,org-agenda-goto-date}
7831 Prompt for a date and go there.
7832 @c
7833 @orgcmd{J,org-agenda-clock-goto}
7834 Go to the currently clocked-in task @i{in the agenda buffer}.
7835 @c
7836 @orgcmd{D,org-agenda-toggle-diary}
7837 Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}.
7838 @c
7839 @orgcmdkskc{v l,l,org-agenda-log-mode}
7840 @kindex v L
7841 @vindex org-log-done
7842 @vindex org-agenda-log-mode-items
7843 Toggle Logbook mode. In Logbook mode, entries that were marked DONE while
7844 logging was on (variable @code{org-log-done}) are shown in the agenda, as are
7845 entries that have been clocked on that day. You can configure the entry
7846 types that should be included in log mode using the variable
7847 @code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show
7848 all possible logbook entries, including state changes. When called with two
7849 prefix args @kbd{C-u C-u}, show only logging information, nothing else.
7850 @kbd{v L} is equivalent to @kbd{C-u v l}.
7851 @c
7852 @orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
7853 Include inactive timestamps into the current view. Only for weekly/daily
7854 agenda and timeline views.
7855 @c
7856 @orgcmd{v a,org-agenda-archives-mode}
7857 @xorgcmd{v A,org-agenda-archives-mode 'files}
7858 Toggle Archives mode. In Archives mode, trees that are marked
7859 @code{ARCHIVED} are also scanned when producing the agenda. When you use the
7860 capital @kbd{A}, even all archive files are included. To exit archives mode,
7861 press @kbd{v a} again.
7862 @c
7863 @orgcmdkskc{v R,R,org-agenda-clockreport-mode}
7864 @vindex org-agenda-start-with-clockreport-mode
7865 Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will
7866 always show a table with the clocked times for the timespan and file scope
7867 covered by the current agenda view. The initial setting for this mode in new
7868 agenda buffers can be set with the variable
7869 @code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
7870 when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show
7871 contributions from entries that are hidden by agenda filtering@footnote{Only
7872 tags filtering will be respected here, effort filtering is ignored.}.
7873 @c
7874 @orgkey{v c}
7875 @vindex org-agenda-clock-consistency-checks
7876 Show overlapping clock entries, clocking gaps, and other clocking problems in
7877 the current agenda range. You can then visit clocking lines and fix them
7878 manually. See the variable @code{org-agenda-clock-consistency-checks} for
7879 information on how to customize the definition of what constituted a clocking
7880 problem. To return to normal agenda display, press @kbd{l} to exit Logbook
7881 mode.
7882 @c
7883 @orgcmdkskc{v E,E,org-agenda-entry-text-mode}
7884 @vindex org-agenda-start-with-entry-text-mode
7885 @vindex org-agenda-entry-text-maxlines
7886 Toggle entry text mode. In entry text mode, a number of lines from the Org
7887 outline node referenced by an agenda line will be displayed below the line.
7888 The maximum number of lines is given by the variable
7889 @code{org-agenda-entry-text-maxlines}. Calling this command with a numeric
7890 prefix argument will temporarily modify that number to the prefix value.
7891 @c
7892 @orgcmd{G,org-agenda-toggle-time-grid}
7893 @vindex org-agenda-use-time-grid
7894 @vindex org-agenda-time-grid
7895 Toggle the time grid on and off. See also the variables
7896 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
7897 @c
7898 @orgcmd{r,org-agenda-redo}
7899 Recreate the agenda buffer, for example to reflect the changes after
7900 modification of the timestamps of items with @kbd{S-@key{left}} and
7901 @kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix
7902 argument is interpreted to create a selective list for a specific TODO
7903 keyword.
7904 @orgcmd{g,org-agenda-redo}
7905 Same as @kbd{r}.
7906 @c
7907 @orgcmdkskc{C-x C-s,s,org-save-all-org-buffers}
7908 Save all Org buffers in the current Emacs session, and also the locations of
7909 IDs.
7910 @c
7911 @orgcmd{C-c C-x C-c,org-agenda-columns}
7912 @vindex org-columns-default-format
7913 Invoke column view (@pxref{Column view}) in the agenda buffer. The column
7914 view format is taken from the entry at point, or (if there is no entry at
7915 point), from the first entry in the agenda view. So whatever the format for
7916 that entry would be in the original buffer (taken from a property, from a
7917 @code{#+COLUMNS} line, or from the default variable
7918 @code{org-columns-default-format}), will be used in the agenda.
7919
7920 @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
7921 Remove the restriction lock on the agenda, if it is currently restricted to a
7922 file or subtree (@pxref{Agenda files}).
7923
7924 @tsubheading{Secondary filtering and query editing}
7925 @cindex filtering, by tag and effort, in agenda
7926 @cindex tag filtering, in agenda
7927 @cindex effort filtering, in agenda
7928 @cindex query editing, in agenda
7929
7930 @orgcmd{/,org-agenda-filter-by-tag}
7931 @vindex org-agenda-filter-preset
7932 Filter the current agenda view with respect to a tag and/or effort estimates.
7933 The difference between this and a custom agenda command is that filtering is
7934 very fast, so that you can switch quickly between different filters without
7935 having to recreate the agenda.@footnote{Custom commands can preset a filter by
7936 binding the variable @code{org-agenda-filter-preset} as an option. This
7937 filter will then be applied to the view and persist as a basic filter through
7938 refreshes and more secondary filtering. The filter is a global property of
7939 the entire agenda view---in a block agenda, you should only set this in the
7940 global options section, not in the section of an individual block.}
7941
7942 You will be prompted for a tag selection letter; @key{SPC} will mean any tag at
7943 all. Pressing @key{TAB} at that prompt will offer use completion to select a
7944 tag (including any tags that do not have a selection character). The command
7945 then hides all entries that do not contain or inherit this tag. When called
7946 with prefix arg, remove the entries that @emph{do} have the tag. A second
7947 @kbd{/} at the prompt will turn off the filter and unhide any hidden entries.
7948 If the first key you press is either @kbd{+} or @kbd{-}, the previous filter
7949 will be narrowed by requiring or forbidding the selected additional tag.
7950 Instead of pressing @kbd{+} or @kbd{-} after @kbd{/}, you can also
7951 immediately use the @kbd{\} command.
7952
7953 @vindex org-sort-agenda-noeffort-is-high
7954 In order to filter for effort estimates, you should set up allowed
7955 efforts globally, for example
7956 @lisp
7957 (setq org-global-properties
7958 '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
7959 @end lisp
7960 You can then filter for an effort by first typing an operator, one of
7961 @kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
7962 estimate in your array of allowed values, where @kbd{0} means the 10th value.
7963 The filter will then restrict to entries with effort smaller-or-equal, equal,
7964 or larger-or-equal than the selected value. If the digits 0-9 are not used
7965 as fast access keys to tags, you can also simply press the index digit
7966 directly without an operator. In this case, @kbd{<} will be assumed. For
7967 application of the operator, entries without a defined effort will be treated
7968 according to the value of @code{org-sort-agenda-noeffort-is-high}. To filter
7969 for tasks without effort definition, press @kbd{?} as the operator.
7970
7971 Org also supports automatic, context-aware tag filtering. If the variable
7972 @code{org-agenda-auto-exclude-function} is set to a user-defined function,
7973 that function can decide which tags should be excluded from the agenda
7974 automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
7975 as a sub-option key and runs the auto exclusion logic. For example, let's
7976 say you use a @code{Net} tag to identify tasks which need network access, an
7977 @code{Errand} tag for errands in town, and a @code{Call} tag for making phone
7978 calls. You could auto-exclude these tags based on the availability of the
7979 Internet, and outside of business hours, with something like this:
7980
7981 @lisp
7982 @group
7983 (defun org-my-auto-exclude-function (tag)
7984 (and (cond
7985 ((string= tag "Net")
7986 (/= 0 (call-process "/sbin/ping" nil nil nil
7987 "-c1" "-q" "-t1" "mail.gnu.org")))
7988 ((or (string= tag "Errand") (string= tag "Call"))
7989 (let ((hour (nth 2 (decode-time))))
7990 (or (< hour 8) (> hour 21)))))
7991 (concat "-" tag)))
7992
7993 (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
7994 @end group
7995 @end lisp
7996
7997 @orgcmd{\\,org-agenda-filter-by-tag-refine}
7998 Narrow the current agenda filter by an additional condition. When called with
7999 prefix arg, remove the entries that @emph{do} have the tag, or that do match
8000 the effort criterion. You can achieve the same effect by pressing @kbd{+} or
8001 @kbd{-} as the first key after the @kbd{/} command.
8002
8003 @c
8004 @kindex [
8005 @kindex ]
8006 @kindex @{
8007 @kindex @}
8008 @item [ ] @{ @}
8009 @table @i
8010 @item @r{in} search view
8011 add new search words (@kbd{[} and @kbd{]}) or new regular expressions
8012 (@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
8013 add a positive search term prefixed by @samp{+}, indicating that this search
8014 term @i{must} occur/match in the entry. The closing bracket/brace will add a
8015 negative search term which @i{must not} occur/match in the entry for it to be
8016 selected.
8017 @end table
8018
8019 @tsubheading{Remote editing}
8020 @cindex remote editing, from agenda
8021
8022 @item 0-9
8023 Digit argument.
8024 @c
8025 @cindex undoing remote-editing events
8026 @cindex remote editing, undo
8027 @orgcmd{C-_,org-agenda-undo}
8028 Undo a change due to a remote editing command. The change is undone
8029 both in the agenda buffer and in the remote buffer.
8030 @c
8031 @orgcmd{t,org-agenda-todo}
8032 Change the TODO state of the item, both in the agenda and in the
8033 original org file.
8034 @c
8035 @orgcmd{C-S-@key{right},org-agenda-todo-nextset}
8036 @orgcmd{C-S-@key{left},org-agenda-todo-previousset}
8037 Switch to the next/previous set of TODO keywords.
8038 @c
8039 @orgcmd{C-k,org-agenda-kill}
8040 @vindex org-agenda-confirm-kill
8041 Delete the current agenda item along with the entire subtree belonging
8042 to it in the original Org file. If the text to be deleted remotely
8043 is longer than one line, the kill needs to be confirmed by the user. See
8044 variable @code{org-agenda-confirm-kill}.
8045 @c
8046 @orgcmd{C-c C-w,org-agenda-refile}
8047 Refile the entry at point.
8048 @c
8049 @orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation}
8050 @vindex org-archive-default-command
8051 Archive the subtree corresponding to the entry at point using the default
8052 archiving command set in @code{org-archive-default-command}. When using the
8053 @code{a} key, confirmation will be required.
8054 @c
8055 @orgcmd{C-c C-x a,org-agenda-toggle-archive-tag}
8056 Toggle the ARCHIVE tag for the current headline.
8057 @c
8058 @orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling}
8059 Move the subtree corresponding to the current entry to its @emph{archive
8060 sibling}.
8061 @c
8062 @orgcmdkskc{C-c C-x C-s,$,org-agenda-archive}
8063 Archive the subtree corresponding to the current headline. This means the
8064 entry will be moved to the configured archive location, most likely a
8065 different file.
8066 @c
8067 @orgcmd{T,org-agenda-show-tags}
8068 @vindex org-agenda-show-inherited-tags
8069 Show all tags associated with the current item. This is useful if you have
8070 turned off @code{org-agenda-show-inherited-tags}, but still want to see all
8071 tags of a headline occasionally.
8072 @c
8073 @orgcmd{:,org-agenda-set-tags}
8074 Set tags for the current headline. If there is an active region in the
8075 agenda, change a tag for all headings in the region.
8076 @c
8077 @kindex ,
8078 @item ,
8079 Set the priority for the current item (@command{org-agenda-priority}).
8080 Org-mode prompts for the priority character. If you reply with @key{SPC},
8081 the priority cookie is removed from the entry.
8082 @c
8083 @orgcmd{P,org-agenda-show-priority}
8084 Display weighted priority of current item.
8085 @c
8086 @orgcmdkkc{+,S-@key{up},org-agenda-priority-up}
8087 Increase the priority of the current item. The priority is changed in
8088 the original buffer, but the agenda is not resorted. Use the @kbd{r}
8089 key for this.
8090 @c
8091 @orgcmdkkc{-,S-@key{down},org-agenda-priority-down}
8092 Decrease the priority of the current item.
8093 @c
8094 @orgcmdkkc{z,C-c C-z,org-agenda-add-note}
8095 @vindex org-log-into-drawer
8096 Add a note to the entry. This note will be recorded, and then filed to the
8097 same location where state change notes are put. Depending on
8098 @code{org-log-into-drawer}, this may be inside a drawer.
8099 @c
8100 @orgcmd{C-c C-a,org-attach}
8101 Dispatcher for all command related to attachments.
8102 @c
8103 @orgcmd{C-c C-s,org-agenda-schedule}
8104 Schedule this item. With prefix arg remove the scheduling timestamp
8105 @c
8106 @orgcmd{C-c C-d,org-agenda-deadline}
8107 Set a deadline for this item. With prefix arg remove the deadline.
8108 @c
8109 @orgcmd{k,org-agenda-action}
8110 Agenda actions, to set dates for selected items to the cursor date.
8111 This command also works in the calendar! The command prompts for an
8112 additional key:
8113 @example
8114 m @r{Mark the entry at point for action. You can also make entries}
8115 @r{in Org files with @kbd{C-c C-x C-k}.}
8116 d @r{Set the deadline of the marked entry to the date at point.}
8117 s @r{Schedule the marked entry at the date at point.}
8118 r @r{Call @code{org-capture} with the cursor date as default date.}
8119 @end example
8120 @noindent
8121 Press @kbd{r} afterward to refresh the agenda and see the effect of the
8122 command.
8123 @c
8124 @orgcmd{S-@key{right},org-agenda-do-date-later}
8125 Change the timestamp associated with the current line by one day into the
8126 future. With a numeric prefix argument, change it by that many days. For
8127 example, @kbd{3 6 5 S-@key{right}} will change it by a year. With a
8128 @kbd{C-u} prefix, change the time by one hour. If you immediately repeat the
8129 command, it will continue to change hours even without the prefix arg. With
8130 a double @kbd{C-u C-u} prefix, do the same for changing minutes. The stamp
8131 is changed in the original Org file, but the change is not directly reflected
8132 in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
8133 @c
8134 @orgcmd{S-@key{left},org-agenda-do-date-earlier}
8135 Change the timestamp associated with the current line by one day
8136 into the past.
8137 @c
8138 @orgcmd{>,org-agenda-date-prompt}
8139 Change the timestamp associated with the current line. The key @kbd{>} has
8140 been chosen, because it is the same as @kbd{S-.} on my keyboard.
8141 @c
8142 @orgcmd{I,org-agenda-clock-in}
8143 Start the clock on the current item. If a clock is running already, it
8144 is stopped first.
8145 @c
8146 @orgcmd{O,org-agenda-clock-out}
8147 Stop the previously started clock.
8148 @c
8149 @orgcmd{X,org-agenda-clock-cancel}
8150 Cancel the currently running clock.
8151 @c
8152 @orgcmd{J,org-agenda-clock-goto}
8153 Jump to the running clock in another window.
8154
8155 @tsubheading{Bulk remote editing selected entries}
8156 @cindex remote editing, bulk, from agenda
8157
8158 @orgcmd{m,org-agenda-bulk-mark}
8159 Mark the entry at point for bulk action. With prefix arg, mark that many
8160 successive entries.
8161 @c
8162 @orgcmd{%,org-agenda-bulk-mark-regexp}
8163 Mark entries matching a regular expression for bulk action.
8164 @c
8165 @orgcmd{u,org-agenda-bulk-unmark}
8166 Unmark entry for bulk action.
8167 @c
8168 @orgcmd{U,org-agenda-bulk-remove-all-marks}
8169 Unmark all marked entries for bulk action.
8170 @c
8171 @orgcmd{B,org-agenda-bulk-action}
8172 Bulk action: act on all marked entries in the agenda. This will prompt for
8173 another key to select the action to be applied. The prefix arg to @kbd{B}
8174 will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove
8175 these special timestamps.
8176 @example
8177 r @r{Prompt for a single refile target and move all entries. The entries}
8178 @r{will no longer be in the agenda; refresh (@kbd{g}) to bring them back.}
8179 $ @r{Archive all selected entries.}
8180 A @r{Archive entries by moving them to their respective archive siblings.}
8181 t @r{Change TODO state. This prompts for a single TODO keyword and}
8182 @r{changes the state of all selected entries, bypassing blocking and}
8183 @r{suppressing logging notes (but not timestamps).}
8184 + @r{Add a tag to all selected entries.}
8185 - @r{Remove a tag from all selected entries.}
8186 s @r{Schedule all items to a new date. To shift existing schedule dates}
8187 @r{by a fixed number of days, use something starting with double plus}
8188 @r{at the prompt, for example @samp{++8d} or @samp{++2w}.}
8189 S @r{Reschedule randomly into the coming N days. N will be prompted for.}
8190 @r{With prefix arg (@kbd{C-u B S}), scatter only across weekdays.}
8191 d @r{Set deadline to a specific date.}
8192 f @r{Apply a function to marked entries.}
8193 @r{For example, the function below sets the CATEGORY property of the}
8194 @r{entries to web.}
8195 @r{(defun set-category ()}
8196 @r{ (interactive "P")}
8197 @r{ (let* ((marker (or (org-get-at-bol 'org-hd-marker)}
8198 @r{ (org-agenda-error)))}
8199 @r{ (buffer (marker-buffer marker)))}
8200 @r{ (with-current-buffer buffer}
8201 @r{ (save-excursion}
8202 @r{ (save-restriction}
8203 @r{ (widen)}
8204 @r{ (goto-char marker)}
8205 @r{ (org-back-to-heading t)}
8206 @r{ (org-set-property "CATEGORY" "web"))))))}
8207 @end example
8208
8209
8210 @tsubheading{Calendar commands}
8211 @cindex calendar commands, from agenda
8212
8213 @orgcmd{c,org-agenda-goto-calendar}
8214 Open the Emacs calendar and move to the date at the agenda cursor.
8215 @c
8216 @orgcmd{c,org-calendar-goto-agenda}
8217 When in the calendar, compute and show the Org-mode agenda for the
8218 date at the cursor.
8219 @c
8220 @cindex diary entries, creating from agenda
8221 @orgcmd{i,org-agenda-diary-entry}
8222 @vindex org-agenda-diary-file
8223 Insert a new entry into the diary, using the date at the cursor and (for
8224 block entries) the date at the mark. This will add to the Emacs diary
8225 file@footnote{This file is parsed for the agenda when
8226 @code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
8227 command in the calendar. The diary file will pop up in another window, where
8228 you can add the entry.
8229
8230 If you configure @code{org-agenda-diary-file} to point to an Org-mode file,
8231 Org will create entries (in org-mode syntax) in that file instead. Most
8232 entries will be stored in a date-based outline tree that will later make it
8233 easy to archive appointments from previous months/years. The tree will be
8234 built under an entry with a @code{DATE_TREE} property, or else with years as
8235 top-level entries. Emacs will prompt you for the entry text---if you specify
8236 it, the entry will be created in @code{org-agenda-diary-file} without further
8237 interaction. If you directly press @key{RET} at the prompt without typing
8238 text, the target file will be shown in another window for you to finish the
8239 entry there. See also the @kbd{k r} command.
8240 @c
8241 @orgcmd{M,org-agenda-phases-of-moon}
8242 Show the phases of the moon for the three months around current date.
8243 @c
8244 @orgcmd{S,org-agenda-sunrise-sunset}
8245 Show sunrise and sunset times. The geographical location must be set
8246 with calendar variables, see the documentation for the Emacs calendar.
8247 @c
8248 @orgcmd{C,org-agenda-convert-date}
8249 Convert the date at cursor into many other cultural and historic
8250 calendars.
8251 @c
8252 @orgcmd{H,org-agenda-holidays}
8253 Show holidays for three months around the cursor date.
8254
8255 @item M-x org-export-icalendar-combine-agenda-files
8256 Export a single iCalendar file containing entries from all agenda files.
8257 This is a globally available command, and also available in the agenda menu.
8258
8259 @tsubheading{Exporting to a file}
8260 @orgcmd{C-x C-w,org-write-agenda}
8261 @cindex exporting agenda views
8262 @cindex agenda views, exporting
8263 @vindex org-agenda-exporter-settings
8264 Write the agenda view to a file. Depending on the extension of the selected
8265 file name, the view will be exported as HTML (extension @file{.html} or
8266 @file{.htm}), Postscript (extension @file{.ps}), PDF (extension @file{.pdf}),
8267 and plain text (any other extension). When called with a @kbd{C-u} prefix
8268 argument, immediately open the newly created file. Use the variable
8269 @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
8270 for @file{htmlize} to be used during export.
8271
8272 @tsubheading{Quit and Exit}
8273 @orgcmd{q,org-agenda-quit}
8274 Quit agenda, remove the agenda buffer.
8275 @c
8276 @cindex agenda files, removing buffers
8277 @orgcmd{x,org-agenda-exit}
8278 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
8279 for the compilation of the agenda. Buffers created by the user to
8280 visit Org files will not be removed.
8281 @end table
8282
8283
8284 @node Custom agenda views, Exporting Agenda Views, Agenda commands, Agenda Views
8285 @section Custom agenda views
8286 @cindex custom agenda views
8287 @cindex agenda views, custom
8288
8289 Custom agenda commands serve two purposes: to store and quickly access
8290 frequently used TODO and tags searches, and to create special composite
8291 agenda buffers. Custom agenda commands will be accessible through the
8292 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
8293
8294 @menu
8295 * Storing searches:: Type once, use often
8296 * Block agenda:: All the stuff you need in a single buffer
8297 * Setting Options:: Changing the rules
8298 @end menu
8299
8300 @node Storing searches, Block agenda, Custom agenda views, Custom agenda views
8301 @subsection Storing searches
8302
8303 The first application of custom searches is the definition of keyboard
8304 shortcuts for frequently used searches, either creating an agenda
8305 buffer, or a sparse tree (the latter covering of course only the current
8306 buffer).
8307 @kindex C-c a C
8308 @vindex org-agenda-custom-commands
8309 Custom commands are configured in the variable
8310 @code{org-agenda-custom-commands}. You can customize this variable, for
8311 example by pressing @kbd{C-c a C}. You can also directly set it with
8312 Emacs Lisp in @file{.emacs}. The following example contains all valid
8313 search types:
8314
8315 @lisp
8316 @group
8317 (setq org-agenda-custom-commands
8318 '(("w" todo "WAITING")
8319 ("W" todo-tree "WAITING")
8320 ("u" tags "+boss-urgent")
8321 ("v" tags-todo "+boss-urgent")
8322 ("U" tags-tree "+boss-urgent")
8323 ("f" occur-tree "\\<FIXME\\>")
8324 ("h" . "HOME+Name tags searches") ; description for "h" prefix
8325 ("hl" tags "+home+Lisa")
8326 ("hp" tags "+home+Peter")
8327 ("hk" tags "+home+Kim")))
8328 @end group
8329 @end lisp
8330
8331 @noindent
8332 The initial string in each entry defines the keys you have to press
8333 after the dispatcher command @kbd{C-c a} in order to access the command.
8334 Usually this will be just a single character, but if you have many
8335 similar commands, you can also define two-letter combinations where the
8336 first character is the same in several combinations and serves as a
8337 prefix key@footnote{You can provide a description for a prefix key by
8338 inserting a cons cell with the prefix and the description.}. The second
8339 parameter is the search type, followed by the string or regular
8340 expression to be used for the matching. The example above will
8341 therefore define:
8342
8343 @table @kbd
8344 @item C-c a w
8345 as a global search for TODO entries with @samp{WAITING} as the TODO
8346 keyword
8347 @item C-c a W
8348 as the same search, but only in the current buffer and displaying the
8349 results as a sparse tree
8350 @item C-c a u
8351 as a global tags search for headlines marked @samp{:boss:} but not
8352 @samp{:urgent:}
8353 @item C-c a v
8354 as the same search as @kbd{C-c a u}, but limiting the search to
8355 headlines that are also TODO items
8356 @item C-c a U
8357 as the same search as @kbd{C-c a u}, but only in the current buffer and
8358 displaying the result as a sparse tree
8359 @item C-c a f
8360 to create a sparse tree (again: current buffer only) with all entries
8361 containing the word @samp{FIXME}
8362 @item C-c a h
8363 as a prefix command for a HOME tags search where you have to press an
8364 additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,
8365 Peter, or Kim) as additional tag to match.
8366 @end table
8367
8368 @node Block agenda, Setting Options, Storing searches, Custom agenda views
8369 @subsection Block agenda
8370 @cindex block agenda
8371 @cindex agenda, with block views
8372
8373 Another possibility is the construction of agenda views that comprise
8374 the results of @emph{several} commands, each of which creates a block in
8375 the agenda buffer. The available commands include @code{agenda} for the
8376 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
8377 for the global TODO list (as constructed with @kbd{C-c a t}), and the
8378 matching commands discussed above: @code{todo}, @code{tags}, and
8379 @code{tags-todo}. Here are two examples:
8380
8381 @lisp
8382 @group
8383 (setq org-agenda-custom-commands
8384 '(("h" "Agenda and Home-related tasks"
8385 ((agenda "")
8386 (tags-todo "home")
8387 (tags "garden")))
8388 ("o" "Agenda and Office-related tasks"
8389 ((agenda "")
8390 (tags-todo "work")
8391 (tags "office")))))
8392 @end group
8393 @end lisp
8394
8395 @noindent
8396 This will define @kbd{C-c a h} to create a multi-block view for stuff
8397 you need to attend to at home. The resulting agenda buffer will contain
8398 your agenda for the current week, all TODO items that carry the tag
8399 @samp{home}, and also all lines tagged with @samp{garden}. Finally the
8400 command @kbd{C-c a o} provides a similar view for office tasks.
8401
8402 @node Setting Options, , Block agenda, Custom agenda views
8403 @subsection Setting options for custom commands
8404 @cindex options, for custom agenda views
8405
8406 @vindex org-agenda-custom-commands
8407 Org-mode contains a number of variables regulating agenda construction
8408 and display. The global variables define the behavior for all agenda
8409 commands, including the custom commands. However, if you want to change
8410 some settings just for a single custom view, you can do so. Setting
8411 options requires inserting a list of variable names and values at the
8412 right spot in @code{org-agenda-custom-commands}. For example:
8413
8414 @lisp
8415 @group
8416 (setq org-agenda-custom-commands
8417 '(("w" todo "WAITING"
8418 ((org-agenda-sorting-strategy '(priority-down))
8419 (org-agenda-prefix-format " Mixed: ")))
8420 ("U" tags-tree "+boss-urgent"
8421 ((org-show-following-heading nil)
8422 (org-show-hierarchy-above nil)))
8423 ("N" search ""
8424 ((org-agenda-files '("~org/notes.org"))
8425 (org-agenda-text-search-extra-files nil)))))
8426 @end group
8427 @end lisp
8428
8429 @noindent
8430 Now the @kbd{C-c a w} command will sort the collected entries only by
8431 priority, and the prefix format is modified to just say @samp{ Mixed: }
8432 instead of giving the category of the entry. The sparse tags tree of
8433 @kbd{C-c a U} will now turn out ultra-compact, because neither the
8434 headline hierarchy above the match, nor the headline following the match
8435 will be shown. The command @kbd{C-c a N} will do a text search limited
8436 to only a single file.
8437
8438 @vindex org-agenda-custom-commands
8439 For command sets creating a block agenda,
8440 @code{org-agenda-custom-commands} has two separate spots for setting
8441 options. You can add options that should be valid for just a single
8442 command in the set, and options that should be valid for all commands in
8443 the set. The former are just added to the command entry; the latter
8444 must come after the list of command entries. Going back to the block
8445 agenda example (@pxref{Block agenda}), let's change the sorting strategy
8446 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
8447 the results for GARDEN tags query in the opposite order,
8448 @code{priority-up}. This would look like this:
8449
8450 @lisp
8451 @group
8452 (setq org-agenda-custom-commands
8453 '(("h" "Agenda and Home-related tasks"
8454 ((agenda)
8455 (tags-todo "home")
8456 (tags "garden"
8457 ((org-agenda-sorting-strategy '(priority-up)))))
8458 ((org-agenda-sorting-strategy '(priority-down))))
8459 ("o" "Agenda and Office-related tasks"
8460 ((agenda)
8461 (tags-todo "work")
8462 (tags "office")))))
8463 @end group
8464 @end lisp
8465
8466 As you see, the values and parentheses setting is a little complex.
8467 When in doubt, use the customize interface to set this variable---it
8468 fully supports its structure. Just one caveat: when setting options in
8469 this interface, the @emph{values} are just Lisp expressions. So if the
8470 value is a string, you need to add the double-quotes around the value
8471 yourself.
8472
8473
8474 @node Exporting Agenda Views, Agenda column view, Custom agenda views, Agenda Views
8475 @section Exporting Agenda Views
8476 @cindex agenda views, exporting
8477
8478 If you are away from your computer, it can be very useful to have a printed
8479 version of some agenda views to carry around. Org-mode can export custom
8480 agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's
8481 @file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the
8482 ghostscript @file{ps2pdf} utility must be installed on the system. Selecting
8483 a PDF file will also create the postscript file.}, and iCalendar files. If
8484 you want to do this only occasionally, use the command
8485
8486 @table @kbd
8487 @orgcmd{C-x C-w,org-write-agenda}
8488 @cindex exporting agenda views
8489 @cindex agenda views, exporting
8490 @vindex org-agenda-exporter-settings
8491 Write the agenda view to a file. Depending on the extension of the selected
8492 file name, the view will be exported as HTML (extension @file{.html} or
8493 @file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension
8494 @file{.ics}), or plain text (any other extension). Use the variable
8495 @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
8496 for @file{htmlize} to be used during export, for example
8497
8498 @vindex org-agenda-add-entry-text-maxlines
8499 @vindex htmlize-output-type
8500 @vindex ps-number-of-columns
8501 @vindex ps-landscape-mode
8502 @lisp
8503 (setq org-agenda-exporter-settings
8504 '((ps-number-of-columns 2)
8505 (ps-landscape-mode t)
8506 (org-agenda-add-entry-text-maxlines 5)
8507 (htmlize-output-type 'css)))
8508 @end lisp
8509 @end table
8510
8511 If you need to export certain agenda views frequently, you can associate
8512 any custom agenda command with a list of output file names
8513 @footnote{If you want to store standard views like the weekly agenda
8514 or the global TODO list as well, you need to define custom commands for
8515 them in order to be able to specify file names.}. Here is an example
8516 that first defines custom commands for the agenda and the global
8517 TODO list, together with a number of files to which to export them.
8518 Then we define two block agenda commands and specify file names for them
8519 as well. File names can be relative to the current working directory,
8520 or absolute.
8521
8522 @lisp
8523 @group
8524 (setq org-agenda-custom-commands
8525 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
8526 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
8527 ("h" "Agenda and Home-related tasks"
8528 ((agenda "")
8529 (tags-todo "home")
8530 (tags "garden"))
8531 nil
8532 ("~/views/home.html"))
8533 ("o" "Agenda and Office-related tasks"
8534 ((agenda)
8535 (tags-todo "work")
8536 (tags "office"))
8537 nil
8538 ("~/views/office.ps" "~/calendars/office.ics"))))
8539 @end group
8540 @end lisp
8541
8542 The extension of the file name determines the type of export. If it is
8543 @file{.html}, Org-mode will use the @file{htmlize.el} package to convert
8544 the buffer to HTML and save it to this file name. If the extension is
8545 @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
8546 Postscript output. If the extension is @file{.ics}, iCalendar export is
8547 run export over all files that were used to construct the agenda, and
8548 limit the export to entries listed in the agenda. Any other
8549 extension produces a plain ASCII file.
8550
8551 The export files are @emph{not} created when you use one of those
8552 commands interactively because this might use too much overhead.
8553 Instead, there is a special command to produce @emph{all} specified
8554 files in one step:
8555
8556 @table @kbd
8557 @orgcmd{C-c a e,org-store-agenda-views}
8558 Export all agenda views that have export file names associated with
8559 them.
8560 @end table
8561
8562 You can use the options section of the custom agenda commands to also
8563 set options for the export commands. For example:
8564
8565 @lisp
8566 (setq org-agenda-custom-commands
8567 '(("X" agenda ""
8568 ((ps-number-of-columns 2)
8569 (ps-landscape-mode t)
8570 (org-agenda-prefix-format " [ ] ")
8571 (org-agenda-with-colors nil)
8572 (org-agenda-remove-tags t))
8573 ("theagenda.ps"))))
8574 @end lisp
8575
8576 @noindent
8577 This command sets two options for the Postscript exporter, to make it
8578 print in two columns in landscape format---the resulting page can be cut
8579 in two and then used in a paper agenda. The remaining settings modify
8580 the agenda prefix to omit category and scheduling information, and
8581 instead include a checkbox to check off items. We also remove the tags
8582 to make the lines compact, and we don't want to use colors for the
8583 black-and-white printer. Settings specified in
8584 @code{org-agenda-exporter-settings} will also apply, but the settings
8585 in @code{org-agenda-custom-commands} take precedence.
8586
8587 @noindent
8588 From the command line you may also use
8589 @example
8590 emacs -f org-batch-store-agenda-views -kill
8591 @end example
8592 @noindent
8593 or, if you need to modify some parameters@footnote{Quoting depends on the
8594 system you use, please check the FAQ for examples.}
8595 @example
8596 emacs -eval '(org-batch-store-agenda-views \
8597 org-agenda-span month \
8598 org-agenda-start-day "2007-11-01" \
8599 org-agenda-include-diary nil \
8600 org-agenda-files (quote ("~/org/project.org")))' \
8601 -kill
8602 @end example
8603 @noindent
8604 which will create the agenda views restricted to the file
8605 @file{~/org/project.org}, without diary entries and with a 30-day
8606 extent.
8607
8608 You can also extract agenda information in a way that allows further
8609 processing by other programs. See @ref{Extracting agenda information}, for
8610 more information.
8611
8612
8613 @node Agenda column view, , Exporting Agenda Views, Agenda Views
8614 @section Using column view in the agenda
8615 @cindex column view, in agenda
8616 @cindex agenda, column view
8617
8618 Column view (@pxref{Column view}) is normally used to view and edit
8619 properties embedded in the hierarchical structure of an Org file. It can be
8620 quite useful to use column view also from the agenda, where entries are
8621 collected by certain criteria.
8622
8623 @table @kbd
8624 @orgcmd{C-c C-x C-c,org-agenda-columns}
8625 Turn on column view in the agenda.
8626 @end table
8627
8628 To understand how to use this properly, it is important to realize that the
8629 entries in the agenda are no longer in their proper outline environment.
8630 This causes the following issues:
8631
8632 @enumerate
8633 @item
8634 @vindex org-columns-default-format
8635 @vindex org-overriding-columns-format
8636 Org needs to make a decision which @code{COLUMNS} format to use. Since the
8637 entries in the agenda are collected from different files, and different files
8638 may have different @code{COLUMNS} formats, this is a non-trivial problem.
8639 Org first checks if the variable @code{org-agenda-overriding-columns-format} is
8640 currently set, and if so, takes the format from there. Otherwise it takes
8641 the format associated with the first item in the agenda, or, if that item
8642 does not have a specific format (defined in a property, or in its file), it
8643 uses @code{org-columns-default-format}.
8644 @item
8645 @cindex property, special, CLOCKSUM
8646 If any of the columns has a summary type defined (@pxref{Column attributes}),
8647 turning on column view in the agenda will visit all relevant agenda files and
8648 make sure that the computations of this property are up to date. This is
8649 also true for the special @code{CLOCKSUM} property. Org will then sum the
8650 values displayed in the agenda. In the daily/weekly agenda, the sums will
8651 cover a single day; in all other views they cover the entire block. It is
8652 vital to realize that the agenda may show the same entry @emph{twice} (for
8653 example as scheduled and as a deadline), and it may show two entries from the
8654 same hierarchy (for example a @emph{parent} and its @emph{child}). In these
8655 cases, the summation in the agenda will lead to incorrect results because
8656 some values will count double.
8657 @item
8658 When the column view in the agenda shows the @code{CLOCKSUM}, that is always
8659 the entire clocked time for this item. So even in the daily/weekly agenda,
8660 the clocksum listed in column view may originate from times outside the
8661 current view. This has the advantage that you can compare these values with
8662 a column listing the planned total effort for a task---one of the major
8663 applications for column view in the agenda. If you want information about
8664 clocked time in the displayed period use clock table mode (press @kbd{R} in
8665 the agenda).
8666 @end enumerate
8667
8668
8669 @node Markup, Exporting, Agenda Views, Top
8670 @chapter Markup for rich export
8671
8672 When exporting Org-mode documents, the exporter tries to reflect the
8673 structure of the document as accurately as possible in the backend. Since
8674 export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting,
8675 Org-mode has rules on how to prepare text for rich export. This section
8676 summarizes the markup rules used in an Org-mode buffer.
8677
8678 @menu
8679 * Structural markup elements:: The basic structure as seen by the exporter
8680 * Images and tables:: Tables and Images will be included
8681 * Literal examples:: Source code examples with special formatting
8682 * Include files:: Include additional files into a document
8683 * Index entries:: Making an index
8684 * Macro replacement:: Use macros to create complex output
8685 * Embedded LaTeX:: LaTeX can be freely used inside Org documents
8686 @end menu
8687
8688 @node Structural markup elements, Images and tables, Markup, Markup
8689 @section Structural markup elements
8690
8691 @menu
8692 * Document title:: Where the title is taken from
8693 * Headings and sections:: The document structure as seen by the exporter
8694 * Table of contents:: The if and where of the table of contents
8695 * Initial text:: Text before the first heading?
8696 * Lists:: Lists
8697 * Paragraphs:: Paragraphs
8698 * Footnote markup:: Footnotes
8699 * Emphasis and monospace:: Bold, italic, etc.
8700 * Horizontal rules:: Make a line
8701 * Comment lines:: What will *not* be exported
8702 @end menu
8703
8704 @node Document title, Headings and sections, Structural markup elements, Structural markup elements
8705 @subheading Document title
8706 @cindex document title, markup rules
8707
8708 @noindent
8709 The title of the exported document is taken from the special line
8710
8711 @cindex #+TITLE
8712 @example
8713 #+TITLE: This is the title of the document
8714 @end example
8715
8716 @noindent
8717 If this line does not exist, the title is derived from the first non-empty,
8718 non-comment line in the buffer. If no such line exists, or if you have
8719 turned off exporting of the text before the first headline (see below), the
8720 title will be the file name without extension.
8721
8722 @cindex property, EXPORT_TITLE
8723 If you are exporting only a subtree by marking is as the region, the heading
8724 of the subtree will become the title of the document. If the subtree has a
8725 property @code{EXPORT_TITLE}, that will take precedence.
8726
8727 @node Headings and sections, Table of contents, Document title, Structural markup elements
8728 @subheading Headings and sections
8729 @cindex headings and sections, markup rules
8730
8731 @vindex org-export-headline-levels
8732 The outline structure of the document as described in @ref{Document
8733 Structure}, forms the basis for defining sections of the exported document.
8734 However, since the outline structure is also used for (for example) lists of
8735 tasks, only the first three outline levels will be used as headings. Deeper
8736 levels will become itemized lists. You can change the location of this
8737 switch globally by setting the variable @code{org-export-headline-levels}, or on a
8738 per-file basis with a line
8739
8740 @cindex #+OPTIONS
8741 @example
8742 #+OPTIONS: H:4
8743 @end example
8744
8745 @node Table of contents, Initial text, Headings and sections, Structural markup elements
8746 @subheading Table of contents
8747 @cindex table of contents, markup rules
8748
8749 @vindex org-export-with-toc
8750 The table of contents is normally inserted directly before the first headline
8751 of the file. If you would like to get it to a different location, insert the
8752 string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired
8753 location. The depth of the table of contents is by default the same as the
8754 number of headline levels, but you can choose a smaller number, or turn off
8755 the table of contents entirely, by configuring the variable
8756 @code{org-export-with-toc}, or on a per-file basis with a line like
8757
8758 @example
8759 #+OPTIONS: toc:2 (only to two levels in TOC)
8760 #+OPTIONS: toc:nil (no TOC at all)
8761 @end example
8762
8763 @node Initial text, Lists, Table of contents, Structural markup elements
8764 @subheading Text before the first headline
8765 @cindex text before first headline, markup rules
8766 @cindex #+TEXT
8767
8768 Org-mode normally exports the text before the first headline, and even uses
8769 the first line as the document title. The text will be fully marked up. If
8770 you need to include literal HTML, @LaTeX{}, or DocBook code, use the special
8771 constructs described below in the sections for the individual exporters.
8772
8773 @vindex org-export-skip-text-before-1st-heading
8774 Some people like to use the space before the first headline for setup and
8775 internal links and therefore would like to control the exported text before
8776 the first headline in a different way. You can do so by setting the variable
8777 @code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-file
8778 basis, you can get the same effect with @samp{#+OPTIONS: skip:t}.
8779
8780 @noindent
8781 If you still want to have some text before the first headline, use the
8782 @code{#+TEXT} construct:
8783
8784 @example
8785 #+OPTIONS: skip:t
8786 #+TEXT: This text will go before the *first* headline.
8787 #+TEXT: [TABLE-OF-CONTENTS]
8788 #+TEXT: This goes between the table of contents and the *first* headline
8789 @end example
8790
8791 @node Lists, Paragraphs, Initial text, Structural markup elements
8792 @subheading Lists
8793 @cindex lists, markup rules
8794
8795 Plain lists as described in @ref{Plain lists}, are translated to the backend's
8796 syntax for such lists. Most backends support unordered, ordered, and
8797 description lists.
8798
8799 @node Paragraphs, Footnote markup, Lists, Structural markup elements
8800 @subheading Paragraphs, line breaks, and quoting
8801 @cindex paragraphs, markup rules
8802
8803 Paragraphs are separated by at least one empty line. If you need to enforce
8804 a line break within a paragraph, use @samp{\\} at the end of a line.
8805
8806 To keep the line breaks in a region, but otherwise use normal formatting, you
8807 can use this construct, which can also be used to format poetry.
8808
8809 @cindex #+BEGIN_VERSE
8810 @example
8811 #+BEGIN_VERSE
8812 Great clouds overhead
8813 Tiny black birds rise and fall
8814 Snow covers Emacs
8815
8816 -- AlexSchroeder
8817 #+END_VERSE
8818 @end example
8819
8820 When quoting a passage from another document, it is customary to format this
8821 as a paragraph that is indented on both the left and the right margin. You
8822 can include quotations in Org-mode documents like this:
8823
8824 @cindex #+BEGIN_QUOTE
8825 @example
8826 #+BEGIN_QUOTE
8827 Everything should be made as simple as possible,
8828 but not any simpler -- Albert Einstein
8829 #+END_QUOTE
8830 @end example
8831
8832 If you would like to center some text, do it like this:
8833 @cindex #+BEGIN_CENTER
8834 @example
8835 #+BEGIN_CENTER
8836 Everything should be made as simple as possible, \\
8837 but not any simpler
8838 #+END_CENTER
8839 @end example
8840
8841
8842 @node Footnote markup, Emphasis and monospace, Paragraphs, Structural markup elements
8843 @subheading Footnote markup
8844 @cindex footnotes, markup rules
8845 @cindex @file{footnote.el}
8846
8847 Footnotes defined in the way described in @ref{Footnotes}, will be exported
8848 by all backends. Org allows multiple references to the same note, and
8849 multiple footnotes side by side.
8850
8851 @node Emphasis and monospace, Horizontal rules, Footnote markup, Structural markup elements
8852 @subheading Emphasis and monospace
8853
8854 @cindex underlined text, markup rules
8855 @cindex bold text, markup rules
8856 @cindex italic text, markup rules
8857 @cindex verbatim text, markup rules
8858 @cindex code text, markup rules
8859 @cindex strike-through text, markup rules
8860 You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=}
8861 and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text
8862 in the code and verbatim string is not processed for Org-mode specific
8863 syntax; it is exported verbatim.
8864
8865 @node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements
8866 @subheading Horizontal rules
8867 @cindex horizontal rules, markup rules
8868 A line consisting of only dashes, and at least 5 of them, will be exported as
8869 a horizontal line (@samp{<hr/>} in HTML and @code{\hrule} in @LaTeX{}).
8870
8871 @node Comment lines, , Horizontal rules, Structural markup elements
8872 @subheading Comment lines
8873 @cindex comment lines
8874 @cindex exporting, not
8875 @cindex #+BEGIN_COMMENT
8876
8877 Lines starting with @samp{#} in column zero are treated as comments and will
8878 never be exported. If you want an indented line to be treated as a comment,
8879 start it with @samp{#+ }. Also entire subtrees starting with the word
8880 @samp{COMMENT} will never be exported. Finally, regions surrounded by
8881 @samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported.
8882
8883 @table @kbd
8884 @kindex C-c ;
8885 @item C-c ;
8886 Toggle the COMMENT keyword at the beginning of an entry.
8887 @end table
8888
8889
8890 @node Images and tables, Literal examples, Structural markup elements, Markup
8891 @section Images and Tables
8892
8893 @cindex tables, markup rules
8894 @cindex #+CAPTION
8895 @cindex #+LABEL
8896 Both the native Org-mode tables (@pxref{Tables}) and tables formatted with
8897 the @file{table.el} package will be exported properly. For Org-mode tables,
8898 the lines before the first horizontal separator line will become table header
8899 lines. You can use the following lines somewhere before the table to assign
8900 a caption and a label for cross references, and in the text you can refer to
8901 the object with @code{\ref@{tab:basic-data@}}:
8902
8903 @example
8904 #+CAPTION: This is the caption for the next table (or link)
8905 #+LABEL: tbl:basic-data
8906 | ... | ...|
8907 |-----|----|
8908 @end example
8909
8910 Optionally, the caption can take the form:
8911 @example
8912 #+CAPTION: [Caption for list of figures]@{Caption for table (or link).@}
8913 @end example
8914
8915 @cindex inlined images, markup rules
8916 Some backends (HTML, @LaTeX{}, and DocBook) allow you to directly include
8917 images into the exported document. Org does this, if a link to an image
8918 files does not have a description part, for example @code{[[./img/a.jpg]]}.
8919 If you wish to define a caption for the image and maybe a label for internal
8920 cross references, make sure that the link is on a line by itself and precede
8921 it with @code{#+CAPTION} and @code{#+LABEL} as follows:
8922
8923 @example
8924 #+CAPTION: This is the caption for the next figure link (or table)
8925 #+LABEL: fig:SED-HR4049
8926 [[./img/a.jpg]]
8927 @end example
8928
8929 You may also define additional attributes for the figure. As this is
8930 backend-specific, see the sections about the individual backends for more
8931 information.
8932
8933 @xref{Handling links,the discussion of image links}.
8934
8935 @node Literal examples, Include files, Images and tables, Markup
8936 @section Literal examples
8937 @cindex literal examples, markup rules
8938 @cindex code line references, markup rules
8939
8940 You can include literal examples that should not be subjected to
8941 markup. Such examples will be typeset in monospace, so this is well suited
8942 for source code and similar examples.
8943 @cindex #+BEGIN_EXAMPLE
8944
8945 @example
8946 #+BEGIN_EXAMPLE
8947 Some example from a text file.
8948 #+END_EXAMPLE
8949 @end example
8950
8951 Note that such blocks may be @i{indented} in order to align nicely with
8952 indented text and in particular with plain list structure (@pxref{Plain
8953 lists}). For simplicity when using small examples, you can also start the
8954 example lines with a colon followed by a space. There may also be additional
8955 whitespace before the colon:
8956
8957 @example
8958 Here is an example
8959 : Some example from a text file.
8960 @end example
8961
8962 @cindex formatting source code, markup rules
8963 If the example is source code from a programming language, or any other text
8964 that can be marked up by font-lock in Emacs, you can ask for the example to
8965 look like the fontified Emacs buffer@footnote{This works automatically for
8966 the HTML backend (it requires version 1.34 of the @file{htmlize.el} package,
8967 which is distributed with Org). Fontified code chunks in LaTeX can be
8968 achieved using either the listings or the
8969 @url{http://code.google.com/p/minted, minted,} package. To use listings, turn
8970 on the variable @code{org-export-latex-listings} and ensure that the listings
8971 package is included by the LaTeX header (e.g.@: by configuring
8972 @code{org-export-latex-packages-alist}). See the listings documentation for
8973 configuration options, including obtaining colored output. For minted it is
8974 necessary to install the program @url{http://pygments.org, pygments}, in
8975 addition to setting @code{org-export-latex-minted}, ensuring that the minted
8976 package is included by the LaTeX header, and ensuring that the
8977 @code{-shell-escape} option is passed to @file{pdflatex} (see
8978 @code{org-latex-to-pdf-process}). See the documentation of the variables
8979 @code{org-export-latex-listings} and @code{org-export-latex-minted} for
8980 further details.}. This is done with the @samp{src} block, where you also
8981 need to specify the name of the major mode that should be used to fontify the
8982 example@footnote{Code in @samp{src} blocks may also be evaluated either
8983 interactively or on export. See @pxref{Working With Source Code} for more
8984 information on evaluating code blocks.}:
8985 @cindex #+BEGIN_SRC
8986
8987 @example
8988 #+BEGIN_SRC emacs-lisp
8989 (defun org-xor (a b)
8990 "Exclusive or."
8991 (if a (not b) b))
8992 #+END_SRC
8993 @end example
8994
8995 Both in @code{example} and in @code{src} snippets, you can add a @code{-n}
8996 switch to the end of the @code{BEGIN} line, to get the lines of the example
8997 numbered. If you use a @code{+n} switch, the numbering from the previous
8998 numbered snippet will be continued in the current one. In literal examples,
8999 Org will interpret strings like @samp{(ref:name)} as labels, and use them as
9000 targets for special hyperlinks like @code{[[(name)]]} (i.e.@: the reference name
9001 enclosed in single parenthesis). In HTML, hovering the mouse over such a
9002 link will remote-highlight the corresponding code line, which is kind of
9003 cool.
9004
9005 You can also add a @code{-r} switch which @i{removes} the labels from the
9006 source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
9007 labels in the source code while using line numbers for the links, which might
9008 be useful to explain those in an org-mode example code.}. With the @code{-n}
9009 switch, links to these references will be labeled by the line numbers from
9010 the code listing, otherwise links will use the labels with no parentheses.
9011 Here is an example:
9012
9013 @example
9014 #+BEGIN_SRC emacs-lisp -n -r
9015 (save-excursion (ref:sc)
9016 (goto-char (point-min)) (ref:jump)
9017 #+END_SRC
9018 In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
9019 jumps to point-min.
9020 @end example
9021
9022 @vindex org-coderef-label-format
9023 If the syntax for the label format conflicts with the language syntax, use a
9024 @code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
9025 -n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}.
9026
9027 HTML export also allows examples to be published as text areas (@pxref{Text
9028 areas in HTML export}).
9029
9030 Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
9031 so often, shortcuts are provided using the Easy Templates facility
9032 (@pxref{Easy Templates}).
9033
9034 @table @kbd
9035 @kindex C-c '
9036 @item C-c '
9037 Edit the source code example at point in its native mode. This works by
9038 switching to a temporary buffer with the source code. You need to exit by
9039 pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*}
9040 or @samp{#} will get a comma prepended, to keep them from being interpreted
9041 by Org as outline nodes or special comments. These commas will be stripped
9042 for editing with @kbd{C-c '}, and also for export.}. The edited version will
9043 then replace the old version in the Org buffer. Fixed-width regions
9044 (where each line starts with a colon followed by a space) will be edited
9045 using @code{artist-mode}@footnote{You may select a different-mode with the
9046 variable @code{org-edit-fixed-width-region-mode}.} to allow creating ASCII
9047 drawings easily. Using this command in an empty line will create a new
9048 fixed-width region.
9049 @kindex C-c l
9050 @item C-c l
9051 Calling @code{org-store-link} while editing a source code example in a
9052 temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure
9053 that it is unique in the current buffer, and insert it with the proper
9054 formatting like @samp{(ref:label)} at the end of the current line. Then the
9055 label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
9056 @end table
9057
9058
9059 @node Include files, Index entries, Literal examples, Markup
9060 @section Include files
9061 @cindex include files, markup rules
9062
9063 During export, you can include the content of another file. For example, to
9064 include your @file{.emacs} file, you could use:
9065 @cindex #+INCLUDE
9066
9067 @example
9068 #+INCLUDE: "~/.emacs" src emacs-lisp
9069 @end example
9070 @noindent
9071 The optional second and third parameter are the markup (e.g.@: @samp{quote},
9072 @samp{example}, or @samp{src}), and, if the markup is @samp{src}, the
9073 language for formatting the contents. The markup is optional; if it is not
9074 given, the text will be assumed to be in Org-mode format and will be
9075 processed normally. The include line will also allow additional keyword
9076 parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the
9077 first line and for each following line, @code{:minlevel} in order to get
9078 org-mode content demoted to a specified level, as well as any options
9079 accepted by the selected markup. For example, to include a file as an item,
9080 use
9081
9082 @example
9083 #+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " "
9084 @end example
9085
9086 You can also include a portion of a file by specifying a lines range using
9087 the @code{:lines} parameter. The line at the upper end of the range will not
9088 be included. The start and/or the end of the range may be omitted to use the
9089 obvious defaults.
9090
9091 @example
9092 #+INCLUDE: "~/.emacs" :lines "5-10" @r{Include lines 5 to 10, 10 excluded}
9093 #+INCLUDE: "~/.emacs" :lines "-10" @r{Include lines 1 to 10, 10 excluded}
9094 #+INCLUDE: "~/.emacs" :lines "10-" @r{Include lines from 10 to EOF}
9095 @end example
9096
9097 @table @kbd
9098 @kindex C-c '
9099 @item C-c '
9100 Visit the include file at point.
9101 @end table
9102
9103 @node Index entries, Macro replacement, Include files, Markup
9104 @section Index entries
9105 @cindex index entries, for publishing
9106
9107 You can specify entries that will be used for generating an index during
9108 publishing. This is done by lines starting with @code{#+INDEX}. An entry
9109 the contains an exclamation mark will create a sub item. See @ref{Generating
9110 an index} for more information.
9111
9112 @example
9113 * Curriculum Vitae
9114 #+INDEX: CV
9115 #+INDEX: Application!CV
9116 @end example
9117
9118
9119
9120
9121 @node Macro replacement, Embedded LaTeX, Index entries, Markup
9122 @section Macro replacement
9123 @cindex macro replacement, during export
9124 @cindex #+MACRO
9125
9126 You can define text snippets with
9127
9128 @example
9129 #+MACRO: name replacement text $1, $2 are arguments
9130 @end example
9131
9132 @noindent which can be referenced anywhere in the document (even in
9133 code examples) with @code{@{@{@{name(arg1,arg2)@}@}@}}. In addition to
9134 defined macros, @code{@{@{@{title@}@}@}}, @code{@{@{@{author@}@}@}}, etc.,
9135 will reference information set by the @code{#+TITLE:}, @code{#+AUTHOR:}, and
9136 similar lines. Also, @code{@{@{@{date(@var{FORMAT})@}@}@}} and
9137 @code{@{@{@{modification-time(@var{FORMAT})@}@}@}} refer to current date time
9138 and to the modification time of the file being exported, respectively.
9139 @var{FORMAT} should be a format string understood by
9140 @code{format-time-string}.
9141
9142 Macro expansion takes place during export, and some people use it to
9143 construct complex HTML code.
9144
9145
9146 @node Embedded LaTeX, , Macro replacement, Markup
9147 @section Embedded @LaTeX{}
9148 @cindex @TeX{} interpretation
9149 @cindex @LaTeX{} interpretation
9150
9151 Plain ASCII is normally sufficient for almost all note taking. Exceptions
9152 include scientific notes, which often require mathematical symbols and the
9153 occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on
9154 Donald E. Knuth's @TeX{} system. Many of the features described here as
9155 ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
9156 distinction.} is widely used to typeset scientific documents. Org-mode
9157 supports embedding @LaTeX{} code into its files, because many academics are
9158 used to writing and reading @LaTeX{} source code, and because it can be
9159 readily processed to produce pretty output for a number of export backends.
9160
9161 @menu
9162 * Special symbols:: Greek letters and other symbols
9163 * Subscripts and superscripts:: Simple syntax for raising/lowering text
9164 * LaTeX fragments:: Complex formulas made easy
9165 * Previewing LaTeX fragments:: What will this snippet look like?
9166 * CDLaTeX mode:: Speed up entering of formulas
9167 @end menu
9168
9169 @node Special symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX
9170 @subsection Special symbols
9171 @cindex math symbols
9172 @cindex special symbols
9173 @cindex @TeX{} macros
9174 @cindex @LaTeX{} fragments, markup rules
9175 @cindex HTML entities
9176 @cindex @LaTeX{} entities
9177
9178 You can use @LaTeX{} macros to insert special symbols like @samp{\alpha} to
9179 indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion
9180 for these macros is available, just type @samp{\} and maybe a few letters,
9181 and press @kbd{M-@key{TAB}} to see possible completions. Unlike @LaTeX{}
9182 code, Org-mode allows these macros to be present without surrounding math
9183 delimiters, for example:
9184
9185 @example
9186 Angles are written as Greek letters \alpha, \beta and \gamma.
9187 @end example
9188
9189 @vindex org-entities
9190 During export, these symbols will be transformed into the native format of
9191 the exporter backend. Strings like @code{\alpha} will be exported as
9192 @code{&alpha;} in the HTML output, and as @code{$\alpha$} in the @LaTeX{}
9193 output. Similarly, @code{\nbsp} will become @code{&nbsp;} in HTML and
9194 @code{~} in @LaTeX{}. If you need such a symbol inside a word, terminate it
9195 like this: @samp{\Aacute@{@}stor}.
9196
9197 A large number of entities is provided, with names taken from both HTML and
9198 @LaTeX{}; see the variable @code{org-entities} for the complete list.
9199 @samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and
9200 @samp{...} are all converted into special commands creating hyphens of
9201 different lengths or a compact set of dots.
9202
9203 If you would like to see entities displayed as UTF8 characters, use the
9204 following command@footnote{You can turn this on by default by setting the
9205 variable @code{org-pretty-entities}, or on a per-file base with the
9206 @code{#+STARTUP} option @code{entitiespretty}.}:
9207
9208 @table @kbd
9209 @kindex C-c C-x \
9210 @item C-c C-x \
9211 Toggle display of entities as UTF-8 characters. This does not change the
9212 buffer content which remains plain ASCII, but it overlays the UTF-8 character
9213 for display purposes only.
9214 @end table
9215
9216 @node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX
9217 @subsection Subscripts and superscripts
9218 @cindex subscript
9219 @cindex superscript
9220
9221 Just like in @LaTeX{}, @samp{^} and @samp{_} are used to indicate super-
9222 and subscripts. Again, these can be used without embedding them in
9223 math-mode delimiters. To increase the readability of ASCII text, it is
9224 not necessary (but OK) to surround multi-character sub- and superscripts
9225 with curly braces. For example
9226
9227 @example
9228 The mass of the sun is M_sun = 1.989 x 10^30 kg. The radius of
9229 the sun is R_@{sun@} = 6.96 x 10^8 m.
9230 @end example
9231
9232 @vindex org-export-with-sub-superscripts
9233 To avoid interpretation as raised or lowered text, you can quote @samp{^} and
9234 @samp{_} with a backslash: @samp{\^} and @samp{\_}. If you write a text
9235 where the underscore is often used in a different context, Org's convention
9236 to always interpret these as subscripts can get in your way. Configure the
9237 variable @code{org-export-with-sub-superscripts} to globally change this
9238 convention, or use, on a per-file basis:
9239
9240 @example
9241 #+OPTIONS: ^:@{@}
9242 @end example
9243
9244 @noindent With this setting, @samp{a_b} will not be interpreted as a
9245 subscript, but @samp{a_@{b@}} will.
9246
9247 @table @kbd
9248 @kindex C-c C-x \
9249 @item C-c C-x \
9250 In addition to showing entities as UTF-8 characters, this command will also
9251 format sub- and superscripts in a WYSIWYM way.
9252 @end table
9253
9254 @node LaTeX fragments, Previewing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX
9255 @subsection @LaTeX{} fragments
9256 @cindex @LaTeX{} fragments
9257
9258 @vindex org-format-latex-header
9259 Going beyond symbols and sub- and superscripts, a full formula language is
9260 needed. Org-mode can contain @LaTeX{} math fragments, and it supports ways
9261 to process these for several export backends. When exporting to @LaTeX{},
9262 the code is obviously left as it is. When exporting to HTML, Org invokes the
9263 @uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in
9264 HTML export}) to process and display the math@footnote{If you plan to use
9265 this regularly or on pages with significant page views, you should install
9266 @file{MathJax} on your own
9267 server in order to limit the load of our server.}. Finally, it can also
9268 process the mathematical expressions into images@footnote{For this to work
9269 you need to be on a system with a working @LaTeX{} installation. You also
9270 need the @file{dvipng} program, available at
9271 @url{http://sourceforge.net/projects/dvipng/}. The @LaTeX{} header that will
9272 be used when processing a fragment can be configured with the variable
9273 @code{org-format-latex-header}.} that can be displayed in a browser or in
9274 DocBook documents.
9275
9276 @LaTeX{} fragments don't need any special marking at all. The following
9277 snippets will be identified as @LaTeX{} source code:
9278 @itemize @bullet
9279 @item
9280 Environments of any kind@footnote{When @file{MathJax} is used, only the
9281 environment recognized by @file{MathJax} will be processed. When
9282 @file{dvipng} is used to create images, any @LaTeX{} environments will be
9283 handled.}. The only requirement is that the @code{\begin} statement appears
9284 on a new line, preceded by only whitespace.
9285 @item
9286 Text within the usual @LaTeX{} math delimiters. To avoid conflicts with
9287 currency specifications, single @samp{$} characters are only recognized as
9288 math delimiters if the enclosed text contains at most two line breaks, is
9289 directly attached to the @samp{$} characters with no whitespace in between,
9290 and if the closing @samp{$} is followed by whitespace, punctuation or a dash.
9291 For the other delimiters, there is no such restriction, so when in doubt, use
9292 @samp{\(...\)} as inline math delimiters.
9293 @end itemize
9294
9295 @noindent For example:
9296
9297 @example
9298 \begin@{equation@} % arbitrary environments,
9299 x=\sqrt@{b@} % even tables, figures
9300 \end@{equation@} % etc
9301
9302 If $a^2=b$ and \( b=2 \), then the solution must be
9303 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
9304 @end example
9305
9306 @noindent
9307 @vindex org-format-latex-options
9308 If you need any of the delimiter ASCII sequences for other purposes, you
9309 can configure the option @code{org-format-latex-options} to deselect the
9310 ones you do not wish to have interpreted by the @LaTeX{} converter.
9311
9312 @vindex org-export-with-LaTeX-fragments
9313 LaTeX processing can be configured with the variable
9314 @code{org-export-with-LaTeX-fragments}. The default setting is @code{t}
9315 which means @file{MathJax} for HTML, and no processing for DocBook, ASCII and
9316 LaTeX backends. You can also set this variable on a per-file basis using one
9317 of these lines:
9318
9319 @example
9320 #+OPTIONS: LaTeX:t @r{Do the right thing automatically (MathJax)}
9321 #+OPTIONS: LaTeX:dvipng @r{Force using dvipng images}
9322 #+OPTIONS: LaTeX:nil @r{Do not process @LaTeX{} fragments at all}
9323 #+OPTIONS: LaTeX:verbatim @r{Verbatim export, for jsMath or so}
9324 @end example
9325
9326 @node Previewing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
9327 @subsection Previewing LaTeX fragments
9328 @cindex LaTeX fragments, preview
9329
9330 If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to
9331 produce preview images of the typeset expressions:
9332
9333 @table @kbd
9334 @kindex C-c C-x C-l
9335 @item C-c C-x C-l
9336 Produce a preview image of the @LaTeX{} fragment at point and overlay it
9337 over the source code. If there is no fragment at point, process all
9338 fragments in the current entry (between two headlines). When called
9339 with a prefix argument, process the entire subtree. When called with
9340 two prefix arguments, or when the cursor is before the first headline,
9341 process the entire buffer.
9342 @kindex C-c C-c
9343 @item C-c C-c
9344 Remove the overlay preview images.
9345 @end table
9346
9347 @vindex org-format-latex-options
9348 You can customize the variable @code{org-format-latex-options} to influence
9349 some aspects of the preview. In particular, the @code{:scale} (and for HTML
9350 export, @code{:html-scale}) property can be used to adjust the size of the
9351 preview images.
9352
9353 @node CDLaTeX mode, , Previewing LaTeX fragments, Embedded LaTeX
9354 @subsection Using CDLa@TeX{} to enter math
9355 @cindex CDLa@TeX{}
9356
9357 CDLa@TeX{} mode is a minor mode that is normally used in combination with a
9358 major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
9359 environments and math templates. Inside Org-mode, you can make use of
9360 some of the features of CDLa@TeX{} mode. You need to install
9361 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
9362 AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
9363 Don't use CDLa@TeX{} mode itself under Org-mode, but use the light
9364 version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it
9365 on for the current buffer with @code{M-x org-cdlatex-mode}, or for all
9366 Org files with
9367
9368 @lisp
9369 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
9370 @end lisp
9371
9372 When this mode is enabled, the following features are present (for more
9373 details see the documentation of CDLa@TeX{} mode):
9374 @itemize @bullet
9375 @kindex C-c @{
9376 @item
9377 Environment templates can be inserted with @kbd{C-c @{}.
9378 @item
9379 @kindex @key{TAB}
9380 The @key{TAB} key will do template expansion if the cursor is inside a
9381 @LaTeX{} fragment@footnote{Org-mode has a method to test if the cursor is
9382 inside such a fragment, see the documentation of the function
9383 @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
9384 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
9385 correctly inside the first brace. Another @key{TAB} will get you into
9386 the second brace. Even outside fragments, @key{TAB} will expand
9387 environment abbreviations at the beginning of a line. For example, if
9388 you write @samp{equ} at the beginning of a line and press @key{TAB},
9389 this abbreviation will be expanded to an @code{equation} environment.
9390 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
9391 @item
9392 @kindex _
9393 @kindex ^
9394 @vindex cdlatex-simplify-sub-super-scripts
9395 Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these
9396 characters together with a pair of braces. If you use @key{TAB} to move
9397 out of the braces, and if the braces surround only a single character or
9398 macro, they are removed again (depending on the variable
9399 @code{cdlatex-simplify-sub-super-scripts}).
9400 @item
9401 @kindex `
9402 Pressing the backquote @kbd{`} followed by a character inserts math
9403 macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds
9404 after the backquote, a help window will pop up.
9405 @item
9406 @kindex '
9407 Pressing the single-quote @kbd{'} followed by another character modifies
9408 the symbol before point with an accent or a font. If you wait more than
9409 1.5 seconds after the single-quote, a help window will pop up. Character
9410 modification will work only inside @LaTeX{} fragments; outside the quote
9411 is normal.
9412 @end itemize
9413
9414 @node Exporting, Publishing, Markup, Top
9415 @chapter Exporting
9416 @cindex exporting
9417
9418 Org-mode documents can be exported into a variety of other formats. For
9419 printing and sharing of notes, ASCII export produces a readable and simple
9420 version of an Org file. HTML export allows you to publish a notes file on
9421 the web, while the XOXO format provides a solid base for exchange with a
9422 broad range of other applications. @LaTeX{} export lets you use Org-mode and
9423 its structured editing functions to easily create @LaTeX{} files. DocBook
9424 export makes it possible to convert Org files to many other formats using
9425 DocBook tools. OpenDocumentText export allows seamless colloboration across
9426 organizational boundaries. For project management you can create gantt and
9427 resource charts by using TaskJuggler export. To incorporate entries with
9428 associated times like deadlines or appointments into a desktop calendar
9429 program like iCal, Org-mode can also produce extracts in the iCalendar
9430 format. Currently Org-mode only supports export, not import of these
9431 different formats.
9432
9433 Org supports export of selected regions when @code{transient-mark-mode} is
9434 enabled (default in Emacs 23).
9435
9436 @menu
9437 * Selective export:: Using tags to select and exclude trees
9438 * Export options:: Per-file export settings
9439 * The export dispatcher:: How to access exporter commands
9440 * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
9441 * HTML export:: Exporting to HTML
9442 * LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF
9443 * DocBook export:: Exporting to DocBook
9444 * OpenDocumentText export:: Exporting to OpenDocumentText
9445 * TaskJuggler export:: Exporting to TaskJuggler
9446 * Freemind export:: Exporting to Freemind mind maps
9447 * XOXO export:: Exporting to XOXO
9448 * iCalendar export:: Exporting in iCalendar format
9449 @end menu
9450
9451 @node Selective export, Export options, Exporting, Exporting
9452 @section Selective export
9453 @cindex export, selective by tags or TODO keyword
9454
9455 @vindex org-export-select-tags
9456 @vindex org-export-exclude-tags
9457 @cindex org-export-with-tasks
9458 You may use tags to select the parts of a document that should be exported,
9459 or to exclude parts from export. This behavior is governed by two variables:
9460 @code{org-export-select-tags} and @code{org-export-exclude-tags}.
9461
9462 @enumerate
9463 @item
9464 Org first checks if any of the @emph{select} tags is present in the
9465 buffer. If yes, all trees that do not carry one of these tags will be
9466 excluded. If a selected tree is a subtree, the heading hierarchy above it
9467 will also be selected for export, but not the text below those headings.
9468
9469 @item
9470 If none of the select tags is found, the whole buffer will be selected for
9471 export.
9472
9473 @item
9474 Finally, all subtrees that are marked by any of the @emph{exclude} tags will
9475 be removed from the export buffer.
9476 @end enumerate
9477
9478 The variable @code{org-export-with-tasks} can be configured to select which
9479 kind of tasks should be included for export. See the docstring of the
9480 variable for more information.
9481
9482 @node Export options, The export dispatcher, Selective export, Exporting
9483 @section Export options
9484 @cindex options, for export
9485
9486 @cindex completion, of option keywords
9487 The exporter recognizes special lines in the buffer which provide
9488 additional information. These lines may be put anywhere in the file.
9489 The whole set of lines can be inserted into the buffer with @kbd{C-c
9490 C-e t}. For individual lines, a good way to make sure the keyword is
9491 correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
9492 (@pxref{Completion}). For a summary of other in-buffer settings not
9493 specifically related to export, see @ref{In-buffer settings}.
9494 In particular, note that you can place commonly-used (export) options in
9495 a separate file which can be included using @code{#+SETUPFILE}.
9496
9497 @table @kbd
9498 @orgcmd{C-c C-e t,org-insert-export-options-template}
9499 Insert template with export options, see example below.
9500 @end table
9501
9502 @cindex #+TITLE
9503 @cindex #+AUTHOR
9504 @cindex #+DATE
9505 @cindex #+EMAIL
9506 @cindex #+DESCRIPTION
9507 @cindex #+KEYWORDS
9508 @cindex #+LANGUAGE
9509 @cindex #+TEXT
9510 @cindex #+OPTIONS
9511 @cindex #+BIND
9512 @cindex #+LINK_UP
9513 @cindex #+LINK_HOME
9514 @cindex #+EXPORT_SELECT_TAGS
9515 @cindex #+EXPORT_EXCLUDE_TAGS
9516 @cindex #+XSLT
9517 @cindex #+LATEX_HEADER
9518 @vindex user-full-name
9519 @vindex user-mail-address
9520 @vindex org-export-default-language
9521 @example
9522 #+TITLE: the title to be shown (default is the buffer name)
9523 #+AUTHOR: the author (default taken from @code{user-full-name})
9524 #+DATE: a date, fixed, or a format string for @code{format-time-string}
9525 #+EMAIL: his/her email address (default from @code{user-mail-address})
9526 #+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag
9527 #+KEYWORDS: the page keywords, e.g.@: for the XHTML meta tag
9528 #+LANGUAGE: language for HTML, e.g.@: @samp{en} (@code{org-export-default-language})
9529 #+TEXT: Some descriptive text to be inserted at the beginning.
9530 #+TEXT: Several lines may be given.
9531 #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ...
9532 #+BIND: lisp-var lisp-val, e.g.@:: org-export-latex-low-levels itemize
9533 @r{You need to confirm using these, or configure @code{org-export-allow-BIND}}
9534 #+LINK_UP: the ``up'' link of an exported page
9535 #+LINK_HOME: the ``home'' link of an exported page
9536 #+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@}
9537 #+EXPORT_SELECT_TAGS: Tags that select a tree for export
9538 #+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export
9539 #+XSLT: the XSLT stylesheet used by DocBook exporter to generate FO file
9540 @end example
9541
9542 @noindent
9543 The OPTIONS line is a compact@footnote{If you want to configure many options
9544 this way, you can use several OPTIONS lines.} form to specify export
9545 settings. Here you can:
9546 @cindex headline levels
9547 @cindex section-numbers
9548 @cindex table of contents
9549 @cindex line-break preservation
9550 @cindex quoted HTML tags
9551 @cindex fixed-width sections
9552 @cindex tables
9553 @cindex @TeX{}-like syntax for sub- and superscripts
9554 @cindex footnotes
9555 @cindex special strings
9556 @cindex emphasized text
9557 @cindex @TeX{} macros
9558 @cindex @LaTeX{} fragments
9559 @cindex author info, in export
9560 @cindex time info, in export
9561 @vindex org-export-plist-vars
9562 @vindex org-export-author-info
9563 @vindex org-export-creator-info
9564 @vindex org-export-email-info
9565 @vindex org-export-time-stamp-file
9566 @example
9567 H: @r{set the number of headline levels for export}
9568 num: @r{turn on/off section-numbers}
9569 toc: @r{turn on/off table of contents, or set level limit (integer)}
9570 \n: @r{turn on/off line-break-preservation (DOES NOT WORK)}
9571 @@: @r{turn on/off quoted HTML tags}
9572 :: @r{turn on/off fixed-width sections}
9573 |: @r{turn on/off tables}
9574 ^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If}
9575 @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but}
9576 @r{the simple @code{a_b} will be left as it is.}
9577 -: @r{turn on/off conversion of special strings.}
9578 f: @r{turn on/off footnotes like this[1].}
9579 todo: @r{turn on/off inclusion of TODO keywords into exported text}
9580 tasks: @r{turn on/off inclusion of tasks (TODO items), can be nil to remove}
9581 @r{all tasks, @code{todo} to remove DONE tasks, or list of kwds to keep}
9582 pri: @r{turn on/off priority cookies}
9583 tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}}
9584 <: @r{turn on/off inclusion of any time/date stamps like DEADLINES}
9585 *: @r{turn on/off emphasized text (bold, italic, underlined)}
9586 TeX: @r{turn on/off simple @TeX{} macros in plain text}
9587 LaTeX: @r{configure export of @LaTeX{} fragments. Default @code{auto}}
9588 skip: @r{turn on/off skipping the text before the first heading}
9589 author: @r{turn on/off inclusion of author name/email into exported file}
9590 email: @r{turn on/off inclusion of author email into exported file}
9591 creator: @r{turn on/off inclusion of creator info into exported file}
9592 timestamp: @r{turn on/off inclusion creation time into exported file}
9593 d: @r{turn on/off inclusion of drawers}
9594 @end example
9595 @noindent
9596 These options take effect in both the HTML and @LaTeX{} export, except for
9597 @code{TeX} and @code{LaTeX} options, which are respectively @code{t} and
9598 @code{nil} for the @LaTeX{} export.
9599
9600 The default values for these and many other options are given by a set of
9601 variables. For a list of such variables, the corresponding OPTIONS keys and
9602 also the publishing keys (@pxref{Project alist}), see the constant
9603 @code{org-export-plist-vars}.
9604
9605 When exporting only a single subtree by selecting it with @kbd{C-c @@} before
9606 calling an export command, the subtree can overrule some of the file's export
9607 settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE},
9608 @code{EXPORT_TEXT}, @code{EXPORT_AUTHOR}, @code{EXPORT_DATE}, and
9609 @code{EXPORT_OPTIONS}.
9610
9611 @node The export dispatcher, ASCII/Latin-1/UTF-8 export, Export options, Exporting
9612 @section The export dispatcher
9613 @cindex dispatcher, for export commands
9614
9615 All export commands can be reached using the export dispatcher, which is a
9616 prefix key that prompts for an additional key specifying the command.
9617 Normally the entire file is exported, but if there is an active region that
9618 contains one outline tree, the first heading is used as document title and
9619 the subtrees are exported.
9620
9621 @table @kbd
9622 @orgcmd{C-c C-e,org-export}
9623 @vindex org-export-run-in-background
9624 Dispatcher for export and publishing commands. Displays a help-window
9625 listing the additional key(s) needed to launch an export or publishing
9626 command. The prefix arg is passed through to the exporter. A double prefix
9627 @kbd{C-u C-u} causes most commands to be executed in the background, in a
9628 separate Emacs process@footnote{To make this behavior the default, customize
9629 the variable @code{org-export-run-in-background}.}.
9630 @orgcmd{C-c C-e v,org-export-visible}
9631 Like @kbd{C-c C-e}, but only export the text that is currently visible
9632 (i.e.@: not hidden by outline visibility).
9633 @orgcmd{C-u C-u C-c C-e,org-export}
9634 @vindex org-export-run-in-background
9635 Call the exporter, but reverse the setting of
9636 @code{org-export-run-in-background}, i.e.@: request background processing if
9637 not set, or force processing in the current Emacs process if set.
9638 @end table
9639
9640 @node ASCII/Latin-1/UTF-8 export, HTML export, The export dispatcher, Exporting
9641 @section ASCII/Latin-1/UTF-8 export
9642 @cindex ASCII export
9643 @cindex Latin-1 export
9644 @cindex UTF-8 export
9645
9646 ASCII export produces a simple and very readable version of an Org-mode
9647 file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file
9648 with special characters and symbols available in these encodings.
9649
9650 @cindex region, active
9651 @cindex active region
9652 @cindex transient-mark-mode
9653 @table @kbd
9654 @orgcmd{C-c C-e a,org-export-as-ascii}
9655 @cindex property, EXPORT_FILE_NAME
9656 Export as ASCII file. For an Org file, @file{myfile.org}, the ASCII file
9657 will be @file{myfile.txt}. The file will be overwritten without
9658 warning. If there is an active region@footnote{This requires
9659 @code{transient-mark-mode} be turned on.}, only the region will be
9660 exported. If the selected region is a single tree@footnote{To select the
9661 current subtree, use @kbd{C-c @@}.}, the tree head will
9662 become the document title. If the tree head entry has or inherits an
9663 @code{EXPORT_FILE_NAME} property, that name will be used for the
9664 export.
9665 @orgcmd{C-c C-e A,org-export-as-ascii-to-buffer}
9666 Export to a temporary buffer. Do not create a file.
9667 @orgcmd{C-c C-e n,org-export-as-latin1}
9668 @xorgcmd{C-c C-e N,org-export-as-latin1-to-buffer}
9669 Like the above commands, but use Latin-1 encoding.
9670 @orgcmd{C-c C-e u,org-export-as-utf8}
9671 @xorgcmd{C-c C-e U,org-export-as-utf8-to-buffer}
9672 Like the above commands, but use UTF-8 encoding.
9673 @item C-c C-e v a/n/u
9674 Export only the visible part of the document.
9675 @end table
9676
9677 @cindex headline levels, for exporting
9678 In the exported version, the first 3 outline levels will become
9679 headlines, defining a general document structure. Additional levels
9680 will be exported as itemized lists. If you want that transition to occur
9681 at a different level, specify it with a prefix argument. For example,
9682
9683 @example
9684 @kbd{C-1 C-c C-e a}
9685 @end example
9686
9687 @noindent
9688 creates only top level headlines and does the rest as items. When
9689 headlines are converted to items, the indentation of the text following
9690 the headline is changed to fit nicely under the item. This is done with
9691 the assumption that the first body line indicates the base indentation of
9692 the body text. Any indentation larger than this is adjusted to preserve
9693 the layout relative to the first line. Should there be lines with less
9694 indentation than the first, these are left alone.
9695
9696 @vindex org-export-ascii-links-to-notes
9697 Links will be exported in a footnote-like style, with the descriptive part in
9698 the text and the link in a note before the next heading. See the variable
9699 @code{org-export-ascii-links-to-notes} for details and other options.
9700
9701 @node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting
9702 @section HTML export
9703 @cindex HTML export
9704
9705 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
9706 HTML formatting, in ways similar to John Gruber's @emph{markdown}
9707 language, but with additional support for tables.
9708
9709 @menu
9710 * HTML Export commands:: How to invoke HTML export
9711 * HTML preamble and postamble:: How to insert a preamble and a postamble
9712 * Quoting HTML tags:: Using direct HTML in Org-mode
9713 * Links in HTML export:: How links will be interpreted and formatted
9714 * Tables in HTML export:: How to modify the formatting of tables
9715 * Images in HTML export:: How to insert figures into HTML output
9716 * Math formatting in HTML export:: Beautiful math also on the web
9717 * Text areas in HTML export:: An alternative way to show an example
9718 * CSS support:: Changing the appearance of the output
9719 * JavaScript support:: Info and Folding in a web browser
9720 @end menu
9721
9722 @node HTML Export commands, HTML preamble and postamble, HTML export, HTML export
9723 @subsection HTML export commands
9724
9725 @cindex region, active
9726 @cindex active region
9727 @cindex transient-mark-mode
9728 @table @kbd
9729 @orgcmd{C-c C-e h,org-export-as-html}
9730 @cindex property, EXPORT_FILE_NAME
9731 Export as HTML file. For an Org file @file{myfile.org},
9732 the HTML file will be @file{myfile.html}. The file will be overwritten
9733 without warning. If there is an active region@footnote{This requires
9734 @code{transient-mark-mode} be turned on.}, only the region will be
9735 exported. If the selected region is a single tree@footnote{To select the
9736 current subtree, use @kbd{C-c @@}.}, the tree head will become the document
9737 title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}
9738 property, that name will be used for the export.
9739 @orgcmd{C-c C-e b,org-export-as-html-and-open}
9740 Export as HTML file and immediately open it with a browser.
9741 @orgcmd{C-c C-e H,org-export-as-html-to-buffer}
9742 Export to a temporary buffer. Do not create a file.
9743 @orgcmd{C-c C-e R,org-export-region-as-html}
9744 Export the active region to a temporary buffer. With a prefix argument, do
9745 not produce the file header and footer, but just the plain HTML section for
9746 the region. This is good for cut-and-paste operations.
9747 @item C-c C-e v h/b/H/R
9748 Export only the visible part of the document.
9749 @item M-x org-export-region-as-html
9750 Convert the region to HTML under the assumption that it was Org-mode
9751 syntax before. This is a global command that can be invoked in any
9752 buffer.
9753 @item M-x org-replace-region-by-HTML
9754 Replace the active region (assumed to be in Org-mode syntax) by HTML
9755 code.
9756 @end table
9757
9758 @cindex headline levels, for exporting
9759 In the exported version, the first 3 outline levels will become headlines,
9760 defining a general document structure. Additional levels will be exported as
9761 itemized lists. If you want that transition to occur at a different level,
9762 specify it with a numeric prefix argument. For example,
9763
9764 @example
9765 @kbd{C-2 C-c C-e b}
9766 @end example
9767
9768 @noindent
9769 creates two levels of headings and does the rest as items.
9770
9771
9772 @node HTML preamble and postamble, Quoting HTML tags, HTML Export commands, HTML export
9773 @subsection HTML preamble and postamble
9774 @vindex org-export-html-preamble
9775 @vindex org-export-html-postamble
9776 @vindex org-export-html-preamble-format
9777 @vindex org-export-html-postamble-format
9778 @vindex org-export-html-validation-link
9779 @vindex org-export-author-info
9780 @vindex org-export-email-info
9781 @vindex org-export-creator-info
9782 @vindex org-export-time-stamp-file
9783
9784 The HTML exporter lets you define a preamble and a postamble.
9785
9786 The default value for @code{org-export-html-preamble} is @code{t}, which
9787 means that the preamble is inserted depending on the relevant formatting
9788 string in @code{org-export-html-preamble-format}.
9789
9790 Setting @code{org-export-html-preamble} to a string will override the default
9791 formatting string. Setting it to a function, will insert the output of the
9792 function, which must be a string; such a function takes no argument but you
9793 can check against the value of @code{opt-plist}, which contains the list of
9794 publishing properties for the current file. Setting to @code{nil} will not
9795 insert any preamble.
9796
9797 The default value for @code{org-export-html-postamble} is @code{'auto}, which
9798 means that the HTML exporter will look for the value of
9799 @code{org-export-author-info}, @code{org-export-email-info},
9800 @code{org-export-creator-info} and @code{org-export-time-stamp-file},
9801 @code{org-export-html-validation-link} and build the postamble from these
9802 values. Setting @code{org-export-html-postamble} to @code{t} will insert the
9803 postamble from the relevant formatting string found in
9804 @code{org-export-html-postamble-format}. Setting it to @code{nil} will not
9805 insert any postamble.
9806
9807 @node Quoting HTML tags, Links in HTML export, HTML preamble and postamble, HTML export
9808 @subsection Quoting HTML tags
9809
9810 Plain @samp{<} and @samp{>} are always transformed to @samp{&lt;} and
9811 @samp{&gt;} in HTML export. If you want to include simple HTML tags
9812 which should be interpreted as such, mark them with @samp{@@} as in
9813 @samp{@@<b>bold text@@</b>}. Note that this really works only for
9814 simple tags. For more extensive HTML that should be copied verbatim to
9815 the exported file use either
9816
9817 @cindex #+HTML
9818 @cindex #+BEGIN_HTML
9819 @example
9820 #+HTML: Literal HTML code for export
9821 @end example
9822
9823 @noindent or
9824 @cindex #+BEGIN_HTML
9825
9826 @example
9827 #+BEGIN_HTML
9828 All lines between these markers are exported literally
9829 #+END_HTML
9830 @end example
9831
9832
9833 @node Links in HTML export, Tables in HTML export, Quoting HTML tags, HTML export
9834 @subsection Links in HTML export
9835
9836 @cindex links, in HTML export
9837 @cindex internal links, in HTML export
9838 @cindex external links, in HTML export
9839 Internal links (@pxref{Internal links}) will continue to work in HTML. This
9840 includes automatic links created by radio targets (@pxref{Radio
9841 targets}). Links to external files will still work if the target file is on
9842 the same @i{relative} path as the published Org file. Links to other
9843 @file{.org} files will be translated into HTML links under the assumption
9844 that an HTML version also exists of the linked file, at the same relative
9845 path. @samp{id:} links can then be used to jump to specific entries across
9846 files. For information related to linking files while publishing them to a
9847 publishing directory see @ref{Publishing links}.
9848
9849 If you want to specify attributes for links, you can do so using a special
9850 @code{#+ATTR_HTML} line to define attributes that will be added to the
9851 @code{<a>} or @code{<img>} tags. Here is an example that sets @code{title}
9852 and @code{style} attributes for a link:
9853
9854 @cindex #+ATTR_HTML
9855 @example
9856 #+ATTR_HTML: title="The Org-mode homepage" style="color:red;"
9857 [[http://orgmode.org]]
9858 @end example
9859
9860 @node Tables in HTML export, Images in HTML export, Links in HTML export, HTML export
9861 @subsection Tables
9862 @cindex tables, in HTML
9863 @vindex org-export-html-table-tag
9864
9865 Org-mode tables are exported to HTML using the table tag defined in
9866 @code{org-export-html-table-tag}. The default setting makes tables without
9867 cell borders and frame. If you would like to change this for individual
9868 tables, place something like the following before the table:
9869
9870 @cindex #+CAPTION
9871 @cindex #+ATTR_HTML
9872 @example
9873 #+CAPTION: This is a table with lines around and between cells
9874 #+ATTR_HTML: border="2" rules="all" frame="all"
9875 @end example
9876
9877 @node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export
9878 @subsection Images in HTML export
9879
9880 @cindex images, inline in HTML
9881 @cindex inlining images in HTML
9882 @vindex org-export-html-inline-images
9883 HTML export can inline images given as links in the Org file, and
9884 it can make an image the clickable part of a link. By
9885 default@footnote{But see the variable
9886 @code{org-export-html-inline-images}.}, images are inlined if a link does
9887 not have a description. So @samp{[[file:myimg.jpg]]} will be inlined,
9888 while @samp{[[file:myimg.jpg][the image]]} will just produce a link
9889 @samp{the image} that points to the image. If the description part
9890 itself is a @code{file:} link or a @code{http:} URL pointing to an
9891 image, this image will be inlined and activated so that clicking on the
9892 image will activate the link. For example, to include a thumbnail that
9893 will link to a high resolution version of the image, you could use:
9894
9895 @example
9896 [[file:highres.jpg][file:thumb.jpg]]
9897 @end example
9898
9899 If you need to add attributes to an inlined image, use a @code{#+ATTR_HTML}.
9900 In the example below we specify the @code{alt} and @code{title} attributes to
9901 support text viewers and accessibility, and align it to the right.
9902
9903 @cindex #+CAPTION
9904 @cindex #+ATTR_HTML
9905 @example
9906 #+CAPTION: A black cat stalking a spider
9907 #+ATTR_HTML: alt="cat/spider image" title="Action!" align="right"
9908 [[./img/a.jpg]]
9909 @end example
9910
9911 @noindent
9912 You could use @code{http} addresses just as well.
9913
9914 @node Math formatting in HTML export, Text areas in HTML export, Images in HTML export, HTML export
9915 @subsection Math formatting in HTML export
9916 @cindex MathJax
9917 @cindex dvipng
9918
9919 @LaTeX{} math snippets (@pxref{LaTeX fragments}) can be displayed in two
9920 different ways on HTML pages. The default is to use the
9921 @uref{http://www.mathjax.org, MathJax system} which should work out of the
9922 box with Org mode installation because @code{http://orgmode.org} serves
9923 @file{MathJax} for Org-mode users for small applications and for testing
9924 purposes. @b{If you plan to use this regularly or on pages with significant
9925 page views, you should install@footnote{Installation instructions can be
9926 found on the MathJax website, see
9927 @uref{http://www.mathjax.org/resources/docs/?installation.html}.} MathJax on
9928 your own server in order to limit the load of our server.} To configure
9929 @file{MathJax}, use the variable @code{org-export-html-mathjax-options} or
9930 insert something like the following into the buffer:
9931
9932 @example
9933 #+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"
9934 @end example
9935
9936 @noindent See the docstring of the variable
9937 @code{org-export-html-mathjax-options} for the meaning of the parameters in
9938 this line.
9939
9940 If you prefer, you can also request that @LaTeX{} fragments are processed
9941 into small images that will be inserted into the browser page. Before the
9942 availability of MathJax, this was the default method for Org files. This
9943 method requires that the @file{dvipng} program is available on your system.
9944 You can still get this processing with
9945
9946 @example
9947 #+OPTIONS: LaTeX:dvipng
9948 @end example
9949
9950 @node Text areas in HTML export, CSS support, Math formatting in HTML export, HTML export
9951 @subsection Text areas in HTML export
9952
9953 @cindex text areas, in HTML
9954 An alternative way to publish literal code examples in HTML is to use text
9955 areas, where the example can even be edited before pasting it into an
9956 application. It is triggered by a @code{-t} switch at an @code{example} or
9957 @code{src} block. Using this switch disables any options for syntax and
9958 label highlighting, and line numbering, which may be present. You may also
9959 use @code{-h} and @code{-w} switches to specify the height and width of the
9960 text area, which default to the number of lines in the example, and 80,
9961 respectively. For example
9962
9963 @example
9964 #+BEGIN_EXAMPLE -t -w 40
9965 (defun org-xor (a b)
9966 "Exclusive or."
9967 (if a (not b) b))
9968 #+END_EXAMPLE
9969 @end example
9970
9971
9972 @node CSS support, JavaScript support, Text areas in HTML export, HTML export
9973 @subsection CSS support
9974 @cindex CSS, for HTML export
9975 @cindex HTML export, CSS
9976
9977 @vindex org-export-html-todo-kwd-class-prefix
9978 @vindex org-export-html-tag-class-prefix
9979 You can also give style information for the exported file. The HTML exporter
9980 assigns the following special CSS classes@footnote{If the classes on TODO
9981 keywords and tags lead to conflicts, use the variables
9982 @code{org-export-html-todo-kwd-class-prefix} and
9983 @code{org-export-html-tag-class-prefix} to make them unique.} to appropriate
9984 parts of the document---your style specifications may change these, in
9985 addition to any of the standard classes like for headlines, tables, etc.
9986 @example
9987 p.author @r{author information, including email}
9988 p.date @r{publishing date}
9989 p.creator @r{creator info, about org-mode version}
9990 .title @r{document title}
9991 .todo @r{TODO keywords, all not-done states}
9992 .done @r{the DONE keywords, all states that count as done}
9993 .WAITING @r{each TODO keyword also uses a class named after itself}
9994 .timestamp @r{timestamp}
9995 .timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED}
9996 .timestamp-wrapper @r{span around keyword plus timestamp}
9997 .tag @r{tag in a headline}
9998 ._HOME @r{each tag uses itself as a class, "@@" replaced by "_"}
9999 .target @r{target for links}
10000 .linenr @r{the line number in a code example}
10001 .code-highlighted @r{for highlighting referenced code lines}
10002 div.outline-N @r{div for outline level N (headline plus text))}
10003 div.outline-text-N @r{extra div for text at outline level N}
10004 .section-number-N @r{section number in headlines, different for each level}
10005 div.figure @r{how to format an inlined image}
10006 pre.src @r{formatted source code}
10007 pre.example @r{normal example}
10008 p.verse @r{verse paragraph}
10009 div.footnotes @r{footnote section headline}
10010 p.footnote @r{footnote definition paragraph, containing a footnote}
10011 .footref @r{a footnote reference number (always a <sup>)}
10012 .footnum @r{footnote number in footnote definition (always <sup>)}
10013 @end example
10014
10015 @vindex org-export-html-style-default
10016 @vindex org-export-html-style-include-default
10017 @vindex org-export-html-style
10018 @vindex org-export-html-extra
10019 @vindex org-export-html-style-default
10020 Each exported file contains a compact default style that defines these
10021 classes in a basic way@footnote{This style is defined in the constant
10022 @code{org-export-html-style-default}, which you should not modify. To turn
10023 inclusion of these defaults off, customize
10024 @code{org-export-html-style-include-default}}. You may overwrite these
10025 settings, or add to them by using the variables @code{org-export-html-style}
10026 (for Org-wide settings) and @code{org-export-html-style-extra} (for more
10027 fine-grained settings, like file-local settings). To set the latter variable
10028 individually for each file, you can use
10029
10030 @cindex #+STYLE
10031 @example
10032 #+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />
10033 @end example
10034
10035 @noindent
10036 For longer style definitions, you can use several such lines. You could also
10037 directly write a @code{<style>} @code{</style>} section in this way, without
10038 referring to an external file.
10039
10040 In order to add styles to a subtree, use the @code{:HTML_CONTAINER_CLASS:}
10041 property to assign a class to the tree. In order to specify CSS styles for a
10042 particular headline, you can use the id specified in a @code{:CUSTOM_ID:}
10043 property.
10044
10045 @c FIXME: More about header and footer styles
10046 @c FIXME: Talk about links and targets.
10047
10048 @node JavaScript support, , CSS support, HTML export
10049 @subsection JavaScript supported display of web pages
10050
10051 @cindex Rose, Sebastian
10052 Sebastian Rose has written a JavaScript program especially designed to
10053 enhance the web viewing experience of HTML files created with Org. This
10054 program allows you to view large files in two different ways. The first one
10055 is an @emph{Info}-like mode where each section is displayed separately and
10056 navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys
10057 as well, press @kbd{?} for an overview of the available keys). The second
10058 view type is a @emph{folding} view much like Org provides inside Emacs. The
10059 script is available at @url{http://orgmode.org/org-info.js} and you can find
10060 the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}.
10061 We host the script at our site, but if you use it a lot, you might
10062 not want to be dependent on @url{orgmode.org} and prefer to install a local
10063 copy on your own web server.
10064
10065 To use the script, you need to make sure that the @file{org-jsinfo.el} module
10066 gets loaded. It should be loaded by default, but you can try @kbd{M-x
10067 customize-variable @key{RET} org-modules @key{RET}} to convince yourself that
10068 this is indeed the case. All it then takes to make use of the program is
10069 adding a single line to the Org file:
10070
10071 @cindex #+INFOJS_OPT
10072 @example
10073 #+INFOJS_OPT: view:info toc:nil
10074 @end example
10075
10076 @noindent
10077 If this line is found, the HTML header will automatically contain the code
10078 needed to invoke the script. Using the line above, you can set the following
10079 viewing options:
10080
10081 @example
10082 path: @r{The path to the script. The default is to grab the script from}
10083 @r{@url{http://orgmode.org/org-info.js}, but you might want to have}
10084 @r{a local copy and use a path like @samp{../scripts/org-info.js}.}
10085 view: @r{Initial view when website is first shown. Possible values are:}
10086 info @r{Info-like interface with one section per page.}
10087 overview @r{Folding interface, initially showing only top-level.}
10088 content @r{Folding interface, starting with all headlines visible.}
10089 showall @r{Folding interface, all headlines and text visible.}
10090 sdepth: @r{Maximum headline level that will still become an independent}
10091 @r{section for info and folding modes. The default is taken from}
10092 @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).}
10093 @r{If this is smaller than in @code{org-export-headline-levels}, each}
10094 @r{info/folding section can still contain child headlines.}
10095 toc: @r{Should the table of contents @emph{initially} be visible?}
10096 @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}
10097 tdepth: @r{The depth of the table of contents. The defaults are taken from}
10098 @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}
10099 ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?}
10100 @r{If yes, the toc will never be displayed as a section.}
10101 ltoc: @r{Should there be short contents (children) in each section?}
10102 @r{Make this @code{above} if the section should be above initial text.}
10103 mouse: @r{Headings are highlighted when the mouse is over them. Should be}
10104 @r{@samp{underline} (default) or a background color like @samp{#cccccc}.}
10105 buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the}
10106 @r{default), only one such button will be present.}
10107 @end example
10108 @noindent
10109 @vindex org-infojs-options
10110 @vindex org-export-html-use-infojs
10111 You can choose default values for these options by customizing the variable
10112 @code{org-infojs-options}. If you always want to apply the script to your
10113 pages, configure the variable @code{org-export-html-use-infojs}.
10114
10115 @node LaTeX and PDF export, DocBook export, HTML export, Exporting
10116 @section @LaTeX{} and PDF export
10117 @cindex @LaTeX{} export
10118 @cindex PDF export
10119 @cindex Guerry, Bastien
10120
10121 Org-mode contains a @LaTeX{} exporter written by Bastien Guerry. With
10122 further processing@footnote{The default LaTeX output is designed for
10123 processing with pdftex or latex. It includes packages that are not
10124 compatible with xetex and possibly luatex. See the variables
10125 @code{org-export-latex-default-packages-alist} and
10126 @code{org-export-latex-packages-alist}.}, this backend is also used to
10127 produce PDF output. Since the @LaTeX{} output uses @file{hyperref} to
10128 implement links and cross references, the PDF output file will be fully
10129 linked. Beware of the fact that your @code{org} file has to be properly
10130 structured in order to be correctly exported: respect the hierarchy of
10131 sections.
10132
10133 @menu
10134 * LaTeX/PDF export commands:: Which key invokes which commands
10135 * Header and sectioning:: Setting up the export file structure
10136 * Quoting LaTeX code:: Incorporating literal @LaTeX{} code
10137 * Tables in LaTeX export:: Options for exporting tables to @LaTeX{}
10138 * Images in LaTeX export:: How to insert figures into @LaTeX{} output
10139 * Beamer class export:: Turning the file into a presentation
10140 @end menu
10141
10142 @node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export
10143 @subsection @LaTeX{} export commands
10144
10145 @cindex region, active
10146 @cindex active region
10147 @cindex transient-mark-mode
10148 @table @kbd
10149 @orgcmd{C-c C-e l,org-export-as-latex}
10150 @cindex property EXPORT_FILE_NAME
10151 Export as @LaTeX{} file. For an Org file
10152 @file{myfile.org}, the @LaTeX{} file will be @file{myfile.tex}. The file will
10153 be overwritten without warning. If there is an active region@footnote{This
10154 requires @code{transient-mark-mode} be turned on.}, only the region will be
10155 exported. If the selected region is a single tree@footnote{To select the
10156 current subtree, use @kbd{C-c @@}.}, the tree head will become the document
10157 title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME}
10158 property, that name will be used for the export.
10159 @orgcmd{C-c C-e L,org-export-as-latex-to-buffer}
10160 Export to a temporary buffer. Do not create a file.
10161 @item C-c C-e v l/L
10162 Export only the visible part of the document.
10163 @item M-x org-export-region-as-latex
10164 Convert the region to @LaTeX{} under the assumption that it was Org-mode
10165 syntax before. This is a global command that can be invoked in any
10166 buffer.
10167 @item M-x org-replace-region-by-latex
10168 Replace the active region (assumed to be in Org-mode syntax) by @LaTeX{}
10169 code.
10170 @orgcmd{C-c C-e p,org-export-as-pdf}
10171 Export as @LaTeX{} and then process to PDF.
10172 @orgcmd{C-c C-e d,org-export-as-pdf-and-open}
10173 Export as @LaTeX{} and then process to PDF, then open the resulting PDF file.
10174 @end table
10175
10176 @cindex headline levels, for exporting
10177 @vindex org-latex-low-levels
10178 In the exported version, the first 3 outline levels will become
10179 headlines, defining a general document structure. Additional levels
10180 will be exported as description lists. The exporter can ignore them or
10181 convert them to a custom string depending on
10182 @code{org-latex-low-levels}.
10183
10184 If you want that transition to occur at a different level, specify it
10185 with a numeric prefix argument. For example,
10186
10187 @example
10188 @kbd{C-2 C-c C-e l}
10189 @end example
10190
10191 @noindent
10192 creates two levels of headings and does the rest as items.
10193
10194 @node Header and sectioning, Quoting LaTeX code, LaTeX/PDF export commands, LaTeX and PDF export
10195 @subsection Header and sectioning structure
10196 @cindex @LaTeX{} class
10197 @cindex @LaTeX{} sectioning structure
10198 @cindex @LaTeX{} header
10199 @cindex header, for LaTeX files
10200 @cindex sectioning structure, for LaTeX export
10201
10202 By default, the @LaTeX{} output uses the class @code{article}.
10203
10204 @vindex org-export-latex-default-class
10205 @vindex org-export-latex-classes
10206 @vindex org-export-latex-default-packages-alist
10207 @vindex org-export-latex-packages-alist
10208 @cindex #+LATEX_HEADER
10209 @cindex #+LATEX_CLASS
10210 @cindex #+LATEX_CLASS_OPTIONS
10211 @cindex property, LATEX_CLASS
10212 @cindex property, LATEX_CLASS_OPTIONS
10213 You can change this globally by setting a different value for
10214 @code{org-export-latex-default-class} or locally by adding an option like
10215 @code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:}
10216 property that applies when exporting a region containing only this (sub)tree.
10217 The class must be listed in @code{org-export-latex-classes}. This variable
10218 defines a header template for each class@footnote{Into which the values of
10219 @code{org-export-latex-default-packages-alist} and
10220 @code{org-export-latex-packages-alist} are spliced.}, and allows you to
10221 define the sectioning structure for each class. You can also define your own
10222 classes there. @code{#+LaTeX_CLASS_OPTIONS} or a @code{LaTeX_CLASS_OPTIONS}
10223 property can specify the options for the @code{\documentclass} macro. You
10224 can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to the
10225 header. See the docstring of @code{org-export-latex-classes} for more
10226 information.
10227
10228 @node Quoting LaTeX code, Tables in LaTeX export, Header and sectioning, LaTeX and PDF export
10229 @subsection Quoting @LaTeX{} code
10230
10231 Embedded @LaTeX{} as described in @ref{Embedded LaTeX}, will be correctly
10232 inserted into the @LaTeX{} file. This includes simple macros like
10233 @samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore,
10234 you can add special code that should only be present in @LaTeX{} export with
10235 the following constructs:
10236
10237 @cindex #+LaTeX
10238 @cindex #+BEGIN_LaTeX
10239 @example
10240 #+LaTeX: Literal LaTeX code for export
10241 @end example
10242
10243 @noindent or
10244 @cindex #+BEGIN_LaTeX
10245
10246 @example
10247 #+BEGIN_LaTeX
10248 All lines between these markers are exported literally
10249 #+END_LaTeX
10250 @end example
10251
10252
10253 @node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export
10254 @subsection Tables in @LaTeX{} export
10255 @cindex tables, in @LaTeX{} export
10256
10257 For @LaTeX{} export of a table, you can specify a label, a caption and
10258 placement options (@pxref{Images and tables}). You can also use the
10259 @code{ATTR_LaTeX} line to request a @code{longtable} environment for the
10260 table, so that it may span several pages, or to change the default table
10261 environment from @code{table} to @code{table*} or to change the default inner
10262 tabular environment to @code{tabularx} or @code{tabulary}. Finally, you can
10263 set the alignment string, and (with @code{tabularx} or @code{tabulary}) the
10264 width:
10265
10266 @cindex #+CAPTION
10267 @cindex #+LABEL
10268 @cindex #+ATTR_LaTeX
10269 @example
10270 #+CAPTION: A long table
10271 #+LABEL: tbl:long
10272 #+ATTR_LaTeX: longtable align=l|lp@{3cm@}r|l
10273 | ..... | ..... |
10274 | ..... | ..... |
10275 @end example
10276
10277 or to specify a multicolumn table with @code{tabulary}
10278
10279 @cindex #+CAPTION
10280 @cindex #+LABEL
10281 @cindex #+ATTR_LaTeX
10282 @example
10283 #+CAPTION: A wide table with tabulary
10284 #+LABEL: tbl:wide
10285 #+ATTR_LaTeX: table* tabulary width=\textwidth
10286 | ..... | ..... |
10287 | ..... | ..... |
10288 @end example
10289
10290 @node Images in LaTeX export, Beamer class export, Tables in LaTeX export, LaTeX and PDF export
10291 @subsection Images in @LaTeX{} export
10292 @cindex images, inline in @LaTeX{}
10293 @cindex inlining images in @LaTeX{}
10294
10295 Images that are linked to without a description part in the link, like
10296 @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF
10297 output file resulting from @LaTeX{} processing. Org will use an
10298 @code{\includegraphics} macro to insert the image. If you have specified a
10299 caption and/or a label as described in @ref{Images and tables}, the figure
10300 will be wrapped into a @code{figure} environment and thus become a floating
10301 element. You can use an @code{#+ATTR_LaTeX:} line to specify various other
10302 options. You can ask org to export an image as a float without specifying
10303 a label or a caption by using the keyword @code{float} in this line. Various
10304 optional arguments to the @code{\includegraphics} macro can also be specified
10305 in this fashion. To modify the placement option of the floating environment,
10306 add something like @samp{placement=[h!]} to the attributes. It is to be noted
10307 this option can be used with tables as well@footnote{One can also take
10308 advantage of this option to pass other, unrelated options into the figure or
10309 table environment. For an example see the section ``Exporting org files'' in
10310 @url{http://orgmode.org/worg/org-hacks.html}}. For example the
10311 @code{#+ATTR_LaTeX:} line below is exported as the @code{figure} environment
10312 below it.
10313
10314 If you would like to let text flow around the image, add the word @samp{wrap}
10315 to the @code{#+ATTR_LaTeX:} line, which will make the figure occupy the left
10316 half of the page. To fine-tune, the @code{placement} field will be the set
10317 of additional arguments needed by the @code{wrapfigure} environment. Note
10318 that if you change the size of the image, you need to use compatible settings
10319 for @code{\includegraphics} and @code{wrapfigure}.
10320
10321 @cindex #+CAPTION
10322 @cindex #+LABEL
10323 @cindex #+ATTR_LaTeX
10324 @example
10325 #+CAPTION: The black-body emission of the disk around HR 4049
10326 #+LABEL: fig:SED-HR4049
10327 #+ATTR_LaTeX: width=5cm,angle=90
10328 [[./img/sed-hr4049.pdf]]
10329
10330 #+ATTR_LaTeX: width=0.38\textwidth wrap placement=@{r@}@{0.4\textwidth@}
10331 [[./img/hst.png]]
10332 @end example
10333
10334 If you wish to include an image which spans multiple columns in a page, you
10335 can use the keyword @code{multicolumn} in the @code{#+ATTR_LaTeX} line. This
10336 will export the image wrapped in a @code{figure*} environment.
10337
10338 If you need references to a label created in this way, write
10339 @samp{\ref@{fig:SED-HR4049@}} just like in @LaTeX{}.
10340
10341 @node Beamer class export, , Images in LaTeX export, LaTeX and PDF export
10342 @subsection Beamer class export
10343
10344 The LaTeX class @file{beamer} allows production of high quality presentations
10345 using LaTeX and pdf processing. Org-mode has special support for turning an
10346 Org-mode file or tree into a @file{beamer} presentation.
10347
10348 When the LaTeX class for the current buffer (as set with @code{#+LaTeX_CLASS:
10349 beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is
10350 @code{beamer}, a special export mode will turn the file or tree into a beamer
10351 presentation. Any tree with not-too-deep level nesting should in principle be
10352 exportable as a beamer presentation. By default, the top-level entries (or
10353 the first level below the selected subtree heading) will be turned into
10354 frames, and the outline structure below this level will become itemize lists.
10355 You can also configure the variable @code{org-beamer-frame-level} to a
10356 different level---then the hierarchy above frames will produce the sectioning
10357 structure of the presentation.
10358
10359 A template for useful in-buffer settings or properties can be inserted into
10360 the buffer with @kbd{M-x org-insert-beamer-options-template}. Among other
10361 things, this will install a column view format which is very handy for
10362 editing special properties used by beamer.
10363
10364 You can influence the structure of the presentation using the following
10365 properties:
10366
10367 @table @code
10368 @item BEAMER_env
10369 The environment that should be used to format this entry. Valid environments
10370 are defined in the constant @code{org-beamer-environments-default}, and you
10371 can define more in @code{org-beamer-environments-extra}. If this property is
10372 set, the entry will also get a @code{:B_environment:} tag to make this
10373 visible. This tag has no semantic meaning, it is only a visual aid.
10374 @item BEAMER_envargs
10375 The beamer-special arguments that should be used for the environment, like
10376 @code{[t]} or @code{[<+->]} of @code{<2-3>}. If the @code{BEAMER_col}
10377 property is also set, something like @code{C[t]} can be added here as well to
10378 set an options argument for the implied @code{columns} environment.
10379 @code{c[t]} or @code{c<2->} will set an options for the implied @code{column}
10380 environment.
10381 @item BEAMER_col
10382 The width of a column that should start with this entry. If this property is
10383 set, the entry will also get a @code{:BMCOL:} property to make this visible.
10384 Also this tag is only a visual aid. When this is a plain number, it will be
10385 interpreted as a fraction of @code{\textwidth}. Otherwise it will be assumed
10386 that you have specified the units, like @samp{3cm}. The first such property
10387 in a frame will start a @code{columns} environment to surround the columns.
10388 This environment is closed when an entry has a @code{BEAMER_col} property
10389 with value 0 or 1, or automatically at the end of the frame.
10390 @item BEAMER_extra
10391 Additional commands that should be inserted after the environment has been
10392 opened. For example, when creating a frame, this can be used to specify
10393 transitions.
10394 @end table
10395
10396 Frames will automatically receive a @code{fragile} option if they contain
10397 source code that uses the verbatim environment. Special @file{beamer}
10398 specific code can be inserted using @code{#+BEAMER:} and
10399 @code{#+BEGIN_beamer...#+end_beamer} constructs, similar to other export
10400 backends, but with the difference that @code{#+LaTeX:} stuff will be included
10401 in the presentation as well.
10402
10403 Outline nodes with @code{BEAMER_env} property value @samp{note} or
10404 @samp{noteNH} will be formatted as beamer notes, i,e, they will be wrapped
10405 into @code{\note@{...@}}. The former will include the heading as part of the
10406 note text, the latter will ignore the heading of that node. To simplify note
10407 generation, it is actually enough to mark the note with a @emph{tag} (either
10408 @code{:B_note:} or @code{:B_noteNH:}) instead of creating the
10409 @code{BEAMER_env} property.
10410
10411 You can turn on a special minor mode @code{org-beamer-mode} for editing
10412 support with
10413
10414 @example
10415 #+STARTUP: beamer
10416 @end example
10417
10418 @table @kbd
10419 @orgcmd{C-c C-b,org-beamer-select-environment}
10420 In @code{org-beamer-mode}, this key offers fast selection of a beamer
10421 environment or the @code{BEAMER_col} property.
10422 @end table
10423
10424 Column view provides a great way to set the environment of a node and other
10425 important parameters. Make sure you are using a COLUMN format that is geared
10426 toward this special purpose. The command @kbd{M-x
10427 org-insert-beamer-options-template} defines such a format.
10428
10429 Here is a simple example Org document that is intended for beamer export.
10430
10431 @smallexample
10432 #+LaTeX_CLASS: beamer
10433 #+TITLE: Example Presentation
10434 #+AUTHOR: Carsten Dominik
10435 #+LaTeX_CLASS_OPTIONS: [presentation]
10436 #+BEAMER_FRAME_LEVEL: 2
10437 #+BEAMER_HEADER_EXTRA: \usetheme@{Madrid@}\usecolortheme@{default@}
10438 #+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex)
10439
10440 * This is the first structural section
10441
10442 ** Frame 1 \\ with a subtitle
10443 *** Thanks to Eric Fraga :BMCOL:B_block:
10444 :PROPERTIES:
10445 :BEAMER_env: block
10446 :BEAMER_envargs: C[t]
10447 :BEAMER_col: 0.5
10448 :END:
10449 for the first viable beamer setup in Org
10450 *** Thanks to everyone else :BMCOL:B_block:
10451 :PROPERTIES:
10452 :BEAMER_col: 0.5
10453 :BEAMER_env: block
10454 :BEAMER_envargs: <2->
10455 :END:
10456 for contributing to the discussion
10457 **** This will be formatted as a beamer note :B_note:
10458 ** Frame 2 \\ where we will not use columns
10459 *** Request :B_block:
10460 Please test this stuff!
10461 :PROPERTIES:
10462 :BEAMER_env: block
10463 :END:
10464 @end smallexample
10465
10466 For more information, see the documentation on Worg.
10467
10468 @node DocBook export, OpenDocumentText export, LaTeX and PDF export, Exporting
10469 @section DocBook export
10470 @cindex DocBook export
10471 @cindex PDF export
10472 @cindex Cui, Baoqiu
10473
10474 Org contains a DocBook exporter written by Baoqiu Cui. Once an Org file is
10475 exported to DocBook format, it can be further processed to produce other
10476 formats, including PDF, HTML, man pages, etc., using many available DocBook
10477 tools and stylesheets.
10478
10479 Currently DocBook exporter only supports DocBook V5.0.
10480
10481 @menu
10482 * DocBook export commands:: How to invoke DocBook export
10483 * Quoting DocBook code:: Incorporating DocBook code in Org files
10484 * Recursive sections:: Recursive sections in DocBook
10485 * Tables in DocBook export:: Tables are exported as HTML tables
10486 * Images in DocBook export:: How to insert figures into DocBook output
10487 * Special characters:: How to handle special characters
10488 @end menu
10489
10490 @node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export
10491 @subsection DocBook export commands
10492
10493 @cindex region, active
10494 @cindex active region
10495 @cindex transient-mark-mode
10496 @table @kbd
10497 @orgcmd{C-c C-e D,org-export-as-docbook}
10498 @cindex property EXPORT_FILE_NAME
10499 Export as DocBook file. For an Org file, @file{myfile.org}, the DocBook XML
10500 file will be @file{myfile.xml}. The file will be overwritten without
10501 warning. If there is an active region@footnote{This requires
10502 @code{transient-mark-mode} to be turned on}, only the region will be
10503 exported. If the selected region is a single tree@footnote{To select the
10504 current subtree, use @kbd{C-c @@}.}, the tree head will become the document
10505 title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}
10506 property, that name will be used for the export.
10507 @orgcmd{C-c C-e V,org-export-as-docbook-pdf-and-open}
10508 Export as DocBook file, process to PDF, then open the resulting PDF file.
10509
10510 @vindex org-export-docbook-xslt-proc-command
10511 @vindex org-export-docbook-xsl-fo-proc-command
10512 Note that, in order to produce PDF output based on exported DocBook file, you
10513 need to have XSLT processor and XSL-FO processor software installed on your
10514 system. Check variables @code{org-export-docbook-xslt-proc-command} and
10515 @code{org-export-docbook-xsl-fo-proc-command}.
10516
10517 @vindex org-export-docbook-xslt-stylesheet
10518 The stylesheet argument @code{%s} in variable
10519 @code{org-export-docbook-xslt-proc-command} is replaced by the value of
10520 variable @code{org-export-docbook-xslt-stylesheet}, which needs to be set by
10521 the user. You can also overrule this global setting on a per-file basis by
10522 adding an in-buffer setting @code{#+XSLT:} to the Org file.
10523
10524 @orgkey{C-c C-e v D}
10525 Export only the visible part of the document.
10526 @end table
10527
10528 @node Quoting DocBook code, Recursive sections, DocBook export commands, DocBook export
10529 @subsection Quoting DocBook code
10530
10531 You can quote DocBook code in Org files and copy it verbatim into exported
10532 DocBook file with the following constructs:
10533
10534 @cindex #+DOCBOOK
10535 @cindex #+BEGIN_DOCBOOK
10536 @example
10537 #+DOCBOOK: Literal DocBook code for export
10538 @end example
10539
10540 @noindent or
10541 @cindex #+BEGIN_DOCBOOK
10542
10543 @example
10544 #+BEGIN_DOCBOOK
10545 All lines between these markers are exported by DocBook exporter
10546 literally.
10547 #+END_DOCBOOK
10548 @end example
10549
10550 For example, you can use the following lines to include a DocBook warning
10551 admonition. As to what this warning says, you should pay attention to the
10552 document context when quoting DocBook code in Org files. You may make
10553 exported DocBook XML files invalid by not quoting DocBook code correctly.
10554
10555 @example
10556 #+BEGIN_DOCBOOK
10557 <warning>
10558 <para>You should know what you are doing when quoting DocBook XML code
10559 in your Org file. Invalid DocBook XML may be generated by
10560 DocBook exporter if you are not careful!</para>
10561 </warning>
10562 #+END_DOCBOOK
10563 @end example
10564
10565 @node Recursive sections, Tables in DocBook export, Quoting DocBook code, DocBook export
10566 @subsection Recursive sections
10567 @cindex DocBook recursive sections
10568
10569 DocBook exporter exports Org files as articles using the @code{article}
10570 element in DocBook. Recursive sections, i.e.@: @code{section} elements, are
10571 used in exported articles. Top level headlines in Org files are exported as
10572 top level sections, and lower level headlines are exported as nested
10573 sections. The entire structure of Org files will be exported completely, no
10574 matter how many nested levels of headlines there are.
10575
10576 Using recursive sections makes it easy to port and reuse exported DocBook
10577 code in other DocBook document types like @code{book} or @code{set}.
10578
10579 @node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export
10580 @subsection Tables in DocBook export
10581 @cindex tables, in DocBook export
10582
10583 Tables in Org files are exported as HTML tables, which have been supported since
10584 DocBook V4.3.
10585
10586 If a table does not have a caption, an informal table is generated using the
10587 @code{informaltable} element; otherwise, a formal table will be generated
10588 using the @code{table} element.
10589
10590 @node Images in DocBook export, Special characters, Tables in DocBook export, DocBook export
10591 @subsection Images in DocBook export
10592 @cindex images, inline in DocBook
10593 @cindex inlining images in DocBook
10594
10595 Images that are linked to without a description part in the link, like
10596 @samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, will be exported to DocBook
10597 using @code{mediaobject} elements. Each @code{mediaobject} element contains
10598 an @code{imageobject} that wraps an @code{imagedata} element. If you have
10599 specified a caption for an image as described in @ref{Images and tables}, a
10600 @code{caption} element will be added in @code{mediaobject}. If a label is
10601 also specified, it will be exported as an @code{xml:id} attribute of the
10602 @code{mediaobject} element.
10603
10604 @vindex org-export-docbook-default-image-attributes
10605 Image attributes supported by the @code{imagedata} element, like @code{align}
10606 or @code{width}, can be specified in two ways: you can either customize
10607 variable @code{org-export-docbook-default-image-attributes} or use the
10608 @code{#+ATTR_DOCBOOK:} line. Attributes specified in variable
10609 @code{org-export-docbook-default-image-attributes} are applied to all inline
10610 images in the Org file to be exported (unless they are overridden by image
10611 attributes specified in @code{#+ATTR_DOCBOOK:} lines).
10612
10613 The @code{#+ATTR_DOCBOOK:} line can be used to specify additional image
10614 attributes or override default image attributes for individual images. If
10615 the same attribute appears in both the @code{#+ATTR_DOCBOOK:} line and
10616 variable @code{org-export-docbook-default-image-attributes}, the former
10617 takes precedence. Here is an example about how image attributes can be
10618 set:
10619
10620 @cindex #+CAPTION
10621 @cindex #+LABEL
10622 @cindex #+ATTR_DOCBOOK
10623 @example
10624 #+CAPTION: The logo of Org-mode
10625 #+LABEL: unicorn-svg
10626 #+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
10627 [[./img/org-mode-unicorn.svg]]
10628 @end example
10629
10630 @vindex org-export-docbook-inline-image-extensions
10631 By default, DocBook exporter recognizes the following image file types:
10632 @file{jpeg}, @file{jpg}, @file{png}, @file{gif}, and @file{svg}. You can
10633 customize variable @code{org-export-docbook-inline-image-extensions} to add
10634 more types to this list as long as DocBook supports them.
10635
10636 @node Special characters, , Images in DocBook export, DocBook export
10637 @subsection Special characters in DocBook export
10638 @cindex Special characters in DocBook export
10639
10640 @vindex org-export-docbook-doctype
10641 @vindex org-entities
10642 Special characters that are written in @TeX{}-like syntax, such as @code{\alpha},
10643 @code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter. These
10644 characters are rewritten to XML entities, like @code{&alpha;},
10645 @code{&Gamma;}, and @code{&Zeta;}, based on the list saved in variable
10646 @code{org-entities}. As long as the generated DocBook file includes the
10647 corresponding entities, these special characters are recognized.
10648
10649 You can customize variable @code{org-export-docbook-doctype} to include the
10650 entities you need. For example, you can set variable
10651 @code{org-export-docbook-doctype} to the following value to recognize all
10652 special characters included in XHTML entities:
10653
10654 @example
10655 "<!DOCTYPE article [
10656 <!ENTITY % xhtml1-symbol PUBLIC
10657 \"-//W3C//ENTITIES Symbol for HTML//EN//XML\"
10658 \"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\"
10659 >
10660 %xhtml1-symbol;
10661 ]>
10662 "
10663 @end example
10664
10665 @c begin opendocument
10666
10667 @node OpenDocumentText export, TaskJuggler export, DocBook export, Exporting
10668 @section OpenDocumentText export
10669 @cindex OpenDocumentText export
10670 @cindex K, Jambunathan
10671
10672 Org-mode 7.6 supports export to OpenDocumentText format using
10673 @file{org-odt.el} module contributed by Jambunathan K. This module can be
10674 enabled in one of the following ways based on your mode of installation.
10675
10676 @enumerate
10677 @item
10678 If you have downloaded the Org from the Web, either as a distribution
10679 @file{.zip} or @file{.tar} file, or as a Git archive, enable the @code{odt}
10680 option in variable @code{org-modules}.
10681 @item
10682 If you are using Org that comes bundled with Emacs, then you can install the
10683 OpenDocumentText exporter using the package manager. To do this, customize
10684 the variable @code{package-archives} to include
10685 @uref{http://orgmode.org/pkg/releases/} as one of the package archives.
10686 @end enumerate
10687
10688 @menu
10689 * OpenDocumentText export commands::How to invoke OpenDocumentText export
10690 * Applying Custom Styles:: How to apply custom styles to the output
10691 * Converting to Other formats:: How to convert to formats like doc, docx etc
10692 * Links in OpenDocumentText export:: How links will be interpreted and formatted
10693 * Tables in OpenDocumentText export:: Tables are exported as HTML tables
10694 * Images in OpenDocumentText export:: How to insert figures into DocBook output
10695 * Additional Documentation:: Where to find more information
10696 @end menu
10697
10698 @node OpenDocumentText export commands, Applying Custom Styles, OpenDocumentText export, OpenDocumentText export
10699 @subsection OpenDocumentText export commands
10700
10701 @cindex region, active
10702 @cindex active region
10703 @cindex transient-mark-mode
10704 @table @kbd
10705 @orgcmd{C-c C-e o,org-export-as-odt}
10706 @cindex property EXPORT_FILE_NAME
10707 Export as OpenDocumentText file. For an Org file, @file{myfile.org}, the
10708 OpenDocumentText file will be @file{myfile.odt}. The file will be
10709 overwritten without warning. If there is an active region@footnote{This
10710 requires @code{transient-mark-mode} to be turned on}, only the region will be
10711 exported. If the selected region is a single tree@footnote{To select the
10712 current subtree, use @kbd{C-c @@}.}, the tree head will become the document
10713 title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME}
10714 property, that name will be used for the export.
10715 @orgcmd{C-c C-e O,org-export-as-odt-and-open}
10716 Export as OpenDocumentText file and open the resulting file.
10717 @end table
10718
10719 @node Applying Custom Styles, Converting to Other formats, OpenDocumentText export commands, OpenDocumentText export
10720 @subsection Applying Custom Styles
10721 @cindex styles, custom
10722 @cindex template, custom
10723
10724 @vindex org-export-odt-styles-file
10725
10726 OpenDocumentExporter ships with a custom @file{styles.xml} for formatting of
10727 the exported file. To customize the output to suit your needs you can use
10728 one of the following methods:
10729
10730 @enumerate
10731 @item
10732 Customize the variable @code{org-export-odt-styles-file} to point to either a
10733 @file{styles.xml} file, a OpenDocument Text Template file @code{.ott} or a
10734 combination of Text or Template Document together with a set of member files.
10735 Use the first two options if the styles.xml has no references to additional
10736 set of files and use the last option if the @file{styles.xml} references
10737 additional files like header and footer images.
10738 @item
10739 Use an external tool like unoconv to apply custom templates.
10740 @end enumerate
10741
10742 For best results, it is necessary that the style names used by
10743 OpenDocumentText exporter match that used in the @file{styles.xml}.
10744
10745 @node Converting to Other formats, Links in OpenDocumentText export, Applying Custom Styles, OpenDocumentText export
10746 @subsection Converting to Other formats
10747
10748 @cindex convert
10749 @cindex doc, docx
10750
10751 @vindex org-export-odt-styles-file
10752
10753 Often times there is a need to convert OpenDocumentText files to other
10754 formats like doc, docx or pdf. You can accomplish this by one of the
10755 following methods:
10756
10757 @table @kbd
10758 @item M-x org-lparse
10759 Export the outline first to one of the native formats (like OpenDocumentText)
10760 and immediately post-process it to other formats using an external converter.
10761
10762 @item M-x org-lparse-convert
10763 Export an existing document to other formats using an external converter.
10764 @end table
10765
10766 You can choose the converter used for conversion by customizing the variable
10767 @code{org-lparse-convert-process}.
10768
10769 @node Links in OpenDocumentText export, Tables in OpenDocumentText export, Converting to Other formats, OpenDocumentText export
10770 @subsection Links in OpenDocumentText export
10771 @cindex tables, in DocBook export
10772
10773 OpenDocumentExporter creates cross-references (aka bookmarks) for links that
10774 are destined locally. It creates internet style links for all other links.
10775
10776 @node Tables in OpenDocumentText export, Images in OpenDocumentText export, Links in OpenDocumentText export, OpenDocumentText export
10777 @subsection Tables in OpenDocumentText export
10778 @cindex tables, in DocBook export
10779
10780 Export of @file{table.el} tables with row or column spanning is not
10781 supported. Such tables are stripped from the exported document.
10782
10783 @node Images in OpenDocumentText export, Additional Documentation, Tables in OpenDocumentText export, OpenDocumentText export
10784 @subsection Images in OpenDocumentText export
10785 @cindex images, embedding in OpenDocumentText
10786 @cindex embedding images in OpenDocumentText
10787
10788 OpenDocumentText exporter can embed images within the exported document. To
10789 embed images, provide a link to the desired image file with no link
10790 description. For example, the following links @samp{[[file:img.jpg]]} or
10791 @samp{[[./img.jpg]]}, will result in embedding of @samp{img.jpg} in the
10792 exported file.
10793
10794 The exporter can also embed scaled and explicitly sized images within the
10795 exported document. The markup of the scale and size specifications has not
10796 been standardized yet and is hence conveniently skipped in this document.
10797
10798 The exporter can also make an image the clickable part of a link. To create
10799 clickable images, provide a link whose description is a link to an image
10800 file. For example, the following link
10801 @samp{[[http://orgmode.org][./img.jpg]]}, will result in a clickable image
10802 that links to @uref{http://Orgmode.org} website.
10803
10804 @node Additional Documentation, , Images in OpenDocumentText export, OpenDocumentText export
10805 @subsection Additional documentation
10806
10807 The OpenDocumentText exporter is still in development. For up to date
10808 information, please follow Org mailing list @email{emacs-orgmode@@gnu.org}
10809 closely.
10810
10811 @c end opendocument
10812
10813 @node TaskJuggler export, Freemind export, OpenDocumentText export, Exporting
10814 @section TaskJuggler export
10815 @cindex TaskJuggler export
10816 @cindex Project management
10817
10818 @uref{http://www.taskjuggler.org/, TaskJuggler} is a project management tool.
10819 It provides an optimizing scheduler that computes your project time lines and
10820 resource assignments based on the project outline and the constraints that
10821 you have provided.
10822
10823 The TaskJuggler exporter is a bit different from other exporters, such as the
10824 HTML and LaTeX exporters for example, in that it does not export all the
10825 nodes of a document or strictly follow the order of the nodes in the
10826 document.
10827
10828 Instead the TaskJuggler exporter looks for a tree that defines the tasks and
10829 a optionally tree that defines the resources for this project. It then
10830 creates a TaskJuggler file based on these trees and the attributes defined in
10831 all the nodes.
10832
10833 @subsection TaskJuggler export commands
10834
10835 @table @kbd
10836 @orgcmd{C-c C-e j,org-export-as-taskjuggler}
10837 Export as TaskJuggler file.
10838
10839 @orgcmd{C-c C-e J,org-export-as-taskjuggler-and-open}
10840 Export as TaskJuggler file and then open the file with TaskJugglerUI.
10841 @end table
10842
10843 @subsection Tasks
10844
10845 @vindex org-export-taskjuggler-project-tag
10846 Create your tasks as you usually do with Org-mode. Assign efforts to each
10847 task using properties (it is easiest to do this in the column view). You
10848 should end up with something similar to the example by Peter Jones in
10849 @url{http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org}.
10850 Now mark the top node of your tasks with a tag named
10851 @code{:taskjuggler_project:} (or whatever you customized
10852 @code{org-export-taskjuggler-project-tag} to). You are now ready to export
10853 the project plan with @kbd{C-c C-e J} which will export the project plan and
10854 open a gantt chart in TaskJugglerUI.
10855
10856 @subsection Resources
10857
10858 @vindex org-export-taskjuggler-resource-tag
10859 Next you can define resources and assign those to work on specific tasks. You
10860 can group your resources hierarchically. Tag the top node of the resources
10861 with @code{:taskjuggler_resource:} (or whatever you customized
10862 @code{org-export-taskjuggler-resource-tag} to). You can optionally assign an
10863 identifier (named @samp{resource_id}) to the resources (using the standard
10864 Org properties commands, @pxref{Property syntax}) or you can let the exporter
10865 generate identifiers automatically (the exporter picks the first word of the
10866 headline as the identifier as long as it is unique---see the documentation of
10867 @code{org-taskjuggler-get-unique-id}). Using that identifier you can then
10868 allocate resources to tasks. This is again done with the @samp{allocate}
10869 property on the tasks. Do this in column view or when on the task type
10870 @kbd{C-c C-x p allocate @key{RET} <resource_id> @key{RET}}.
10871
10872 Once the allocations are done you can again export to TaskJuggler and check
10873 in the Resource Allocation Graph which person is working on what task at what
10874 time.
10875
10876 @subsection Export of properties
10877
10878 The exporter also takes TODO state information into consideration, i.e.@: if a
10879 task is marked as done it will have the corresponding attribute in
10880 TaskJuggler (@samp{complete 100}). Also it will export any property on a task
10881 resource or resource node which is known to TaskJuggler, such as
10882 @samp{limits}, @samp{vacation}, @samp{shift}, @samp{booking},
10883 @samp{efficiency}, @samp{journalentry}, @samp{rate} for resources or
10884 @samp{account}, @samp{start}, @samp{note}, @samp{duration}, @samp{end},
10885 @samp{journalentry}, @samp{milestone}, @samp{reference}, @samp{responsible},
10886 @samp{scheduling}, etc for tasks.
10887
10888 @subsection Dependencies
10889
10890 The exporter will handle dependencies that are defined in the tasks either
10891 with the @samp{ORDERED} attribute (@pxref{TODO dependencies}), with the
10892 @samp{BLOCKER} attribute (see @file{org-depend.el}) or alternatively with a
10893 @samp{depends} attribute. Both the @samp{BLOCKER} and the @samp{depends}
10894 attribute can be either @samp{previous-sibling} or a reference to an
10895 identifier (named @samp{task_id}) which is defined for another task in the
10896 project. @samp{BLOCKER} and the @samp{depends} attribute can define multiple
10897 dependencies separated by either space or comma. You can also specify
10898 optional attributes on the dependency by simply appending it. The following
10899 examples should illustrate this:
10900
10901 @example
10902 * Preparation
10903 :PROPERTIES:
10904 :task_id: preparation
10905 :ORDERED: t
10906 :END:
10907 * Training material
10908 :PROPERTIES:
10909 :task_id: training_material
10910 :ORDERED: t
10911 :END:
10912 ** Markup Guidelines
10913 :PROPERTIES:
10914 :Effort: 2d
10915 :END:
10916 ** Workflow Guidelines
10917 :PROPERTIES:
10918 :Effort: 2d
10919 :END:
10920 * Presentation
10921 :PROPERTIES:
10922 :Effort: 2d
10923 :BLOCKER: training_material @{ gapduration 1d @} preparation
10924 :END:
10925 @end example
10926
10927 @subsection Reports
10928
10929 @vindex org-export-taskjuggler-default-reports
10930 TaskJuggler can produce many kinds of reports (e.g.@: gantt chart, resource
10931 allocation, etc). The user defines what kind of reports should be generated
10932 for a project in the TaskJuggler file. The exporter will automatically insert
10933 some default reports in the file. These defaults are defined in
10934 @code{org-export-taskjuggler-default-reports}. They can be modified using
10935 customize along with a number of other options. For a more complete list, see
10936 @kbd{M-x customize-group @key{RET} org-export-taskjuggler @key{RET}}.
10937
10938 For more information and examples see the Org-taskjuggler tutorial at
10939 @uref{http://orgmode.org/worg/org-tutorials/org-taskjuggler.html}.
10940
10941 @node Freemind export, XOXO export, TaskJuggler export, Exporting
10942 @section Freemind export
10943 @cindex Freemind export
10944 @cindex mind map
10945
10946 The Freemind exporter was written by Lennart Borgman.
10947
10948 @table @kbd
10949 @orgcmd{C-c C-e m,org-export-as-freemind}
10950 Export as Freemind mind map. For an Org file @file{myfile.org}, the Freemind
10951 file will be @file{myfile.mm}.
10952 @end table
10953
10954 @node XOXO export, iCalendar export, Freemind export, Exporting
10955 @section XOXO export
10956 @cindex XOXO export
10957
10958 Org-mode contains an exporter that produces XOXO-style output.
10959 Currently, this exporter only handles the general outline structure and
10960 does not interpret any additional Org-mode features.
10961
10962 @table @kbd
10963 @orgcmd{C-c C-e x,org-export-as-xoxo}
10964 Export as XOXO file. For an Org file @file{myfile.org}, the XOXO file will be
10965 @file{myfile.html}.
10966 @orgkey{C-c C-e v x}
10967 Export only the visible part of the document.
10968 @end table
10969
10970 @node iCalendar export, , XOXO export, Exporting
10971 @section iCalendar export
10972 @cindex iCalendar export
10973
10974 @vindex org-icalendar-include-todo
10975 @vindex org-icalendar-use-deadline
10976 @vindex org-icalendar-use-scheduled
10977 @vindex org-icalendar-categories
10978 @vindex org-icalendar-alarm-time
10979 Some people use Org-mode for keeping track of projects, but still prefer a
10980 standard calendar application for anniversaries and appointments. In this
10981 case it can be useful to show deadlines and other time-stamped items in Org
10982 files in the calendar application. Org-mode can export calendar information
10983 in the standard iCalendar format. If you also want to have TODO entries
10984 included in the export, configure the variable
10985 @code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT,
10986 and TODO items as VTODO. It will also create events from deadlines that are
10987 in non-TODO items. Deadlines and scheduling dates in TODO items will be used
10988 to set the start and due dates for the TODO entry@footnote{See the variables
10989 @code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}.}.
10990 As categories, it will use the tags locally defined in the heading, and the
10991 file/tree category@footnote{To add inherited tags or the TODO state,
10992 configure the variable @code{org-icalendar-categories}.}. See the variable
10993 @code{org-icalendar-alarm-time} for a way to assign alarms to entries with a
10994 time.
10995
10996 @vindex org-icalendar-store-UID
10997 @cindex property, ID
10998 The iCalendar standard requires each entry to have a globally unique
10999 identifier (UID). Org creates these identifiers during export. If you set
11000 the variable @code{org-icalendar-store-UID}, the UID will be stored in the
11001 @code{:ID:} property of the entry and re-used next time you report this
11002 entry. Since a single entry can give rise to multiple iCalendar entries (as
11003 a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds
11004 prefixes to the UID, depending on what triggered the inclusion of the entry.
11005 In this way the UID remains unique, but a synchronization program can still
11006 figure out from which entry all the different instances originate.
11007
11008 @table @kbd
11009 @orgcmd{C-c C-e i,org-export-icalendar-this-file}
11010 Create iCalendar entries for the current file and store them in the same
11011 directory, using a file extension @file{.ics}.
11012 @orgcmd{C-c C-e I, org-export-icalendar-all-agenda-files}
11013 @vindex org-agenda-files
11014 Like @kbd{C-c C-e i}, but do this for all files in
11015 @code{org-agenda-files}. For each of these files, a separate iCalendar
11016 file will be written.
11017 @orgcmd{C-c C-e c,org-export-icalendar-combine-agenda-files}
11018 @vindex org-combined-agenda-icalendar-file
11019 Create a single large iCalendar file from all files in
11020 @code{org-agenda-files} and write it to the file given by
11021 @code{org-combined-agenda-icalendar-file}.
11022 @end table
11023
11024 @vindex org-use-property-inheritance
11025 @vindex org-icalendar-include-body
11026 @cindex property, SUMMARY
11027 @cindex property, DESCRIPTION
11028 @cindex property, LOCATION
11029 The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION
11030 property can be inherited from higher in the hierarchy if you configure
11031 @code{org-use-property-inheritance} accordingly.} properties if the selected
11032 entries have them. If not, the summary will be derived from the headline,
11033 and the description from the body (limited to
11034 @code{org-icalendar-include-body} characters).
11035
11036 How this calendar is best read and updated, depends on the application
11037 you are using. The FAQ covers this issue.
11038
11039 @node Publishing, Working With Source Code, Exporting, Top
11040 @chapter Publishing
11041 @cindex publishing
11042
11043 Org includes a publishing management system that allows you to configure
11044 automatic HTML conversion of @emph{projects} composed of interlinked org
11045 files. You can also configure Org to automatically upload your exported HTML
11046 pages and related attachments, such as images and source code files, to a web
11047 server.
11048
11049 You can also use Org to convert files into PDF, or even combine HTML and PDF
11050 conversion so that files are available in both formats on the server.
11051
11052 Publishing has been contributed to Org by David O'Toole.
11053
11054 @menu
11055 * Configuration:: Defining projects
11056 * Uploading files:: How to get files up on the server
11057 * Sample configuration:: Example projects
11058 * Triggering publication:: Publication commands
11059 @end menu
11060
11061 @node Configuration, Uploading files, Publishing, Publishing
11062 @section Configuration
11063
11064 Publishing needs significant configuration to specify files, destination
11065 and many other properties of a project.
11066
11067 @menu
11068 * Project alist:: The central configuration variable
11069 * Sources and destinations:: From here to there
11070 * Selecting files:: What files are part of the project?
11071 * Publishing action:: Setting the function doing the publishing
11072 * Publishing options:: Tweaking HTML/@LaTeX{} export
11073 * Publishing links:: Which links keep working after publishing?
11074 * Sitemap:: Generating a list of all pages
11075 * Generating an index:: An index that reaches across pages
11076 @end menu
11077
11078 @node Project alist, Sources and destinations, Configuration, Configuration
11079 @subsection The variable @code{org-publish-project-alist}
11080 @cindex org-publish-project-alist
11081 @cindex projects, for publishing
11082
11083 @vindex org-publish-project-alist
11084 Publishing is configured almost entirely through setting the value of one
11085 variable, called @code{org-publish-project-alist}. Each element of the list
11086 configures one project, and may be in one of the two following forms:
11087
11088 @lisp
11089 ("project-name" :property value :property value ...)
11090 @r{i.e.@: a well-formed property list with alternating keys and values}
11091 @r{or}
11092 ("project-name" :components ("project-name" "project-name" ...))
11093
11094 @end lisp
11095
11096 In both cases, projects are configured by specifying property values. A
11097 project defines the set of files that will be published, as well as the
11098 publishing configuration to use when publishing those files. When a project
11099 takes the second form listed above, the individual members of the
11100 @code{:components} property are taken to be sub-projects, which group
11101 together files requiring different publishing options. When you publish such
11102 a ``meta-project'', all the components will also be published, in the
11103 sequence given.
11104
11105 @node Sources and destinations, Selecting files, Project alist, Configuration
11106 @subsection Sources and destinations for files
11107 @cindex directories, for publishing
11108
11109 Most properties are optional, but some should always be set. In
11110 particular, Org needs to know where to look for source files,
11111 and where to put published files.
11112
11113 @multitable @columnfractions 0.3 0.7
11114 @item @code{:base-directory}
11115 @tab Directory containing publishing source files
11116 @item @code{:publishing-directory}
11117 @tab Directory where output files will be published. You can directly
11118 publish to a webserver using a file name syntax appropriate for
11119 the Emacs @file{tramp} package. Or you can publish to a local directory and
11120 use external tools to upload your website (@pxref{Uploading files}).
11121 @item @code{:preparation-function}
11122 @tab Function or list of functions to be called before starting the
11123 publishing process, for example, to run @code{make} for updating files to be
11124 published. The project property list is scoped into this call as the
11125 variable @code{project-plist}.
11126 @item @code{:completion-function}
11127 @tab Function or list of functions called after finishing the publishing
11128 process, for example, to change permissions of the resulting files. The
11129 project property list is scoped into this call as the variable
11130 @code{project-plist}.
11131 @end multitable
11132 @noindent
11133
11134 @node Selecting files, Publishing action, Sources and destinations, Configuration
11135 @subsection Selecting files
11136 @cindex files, selecting for publishing
11137
11138 By default, all files with extension @file{.org} in the base directory
11139 are considered part of the project. This can be modified by setting the
11140 properties
11141 @multitable @columnfractions 0.25 0.75
11142 @item @code{:base-extension}
11143 @tab Extension (without the dot!) of source files. This actually is a
11144 regular expression. Set this to the symbol @code{any} if you want to get all
11145 files in @code{:base-directory}, even without extension.
11146
11147 @item @code{:exclude}
11148 @tab Regular expression to match file names that should not be
11149 published, even though they have been selected on the basis of their
11150 extension.
11151
11152 @item @code{:include}
11153 @tab List of files to be included regardless of @code{:base-extension}
11154 and @code{:exclude}.
11155
11156 @item @code{:recursive}
11157 @tab Non-nil means, check base-directory recursively for files to publish.
11158 @end multitable
11159
11160 @node Publishing action, Publishing options, Selecting files, Configuration
11161 @subsection Publishing action
11162 @cindex action, for publishing
11163
11164 Publishing means that a file is copied to the destination directory and
11165 possibly transformed in the process. The default transformation is to export
11166 Org files as HTML files, and this is done by the function
11167 @code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTML
11168 export}). But you also can publish your content as PDF files using
11169 @code{org-publish-org-to-pdf}, or as @code{ascii}, @code{latin1} or
11170 @code{utf8} encoded files using the corresponding functions. If you want to
11171 publish the Org file itself, but with @i{archived}, @i{commented}, and
11172 @i{tag-excluded} trees removed, use @code{org-publish-org-to-org} and set the
11173 parameters @code{:plain-source} and/or @code{:htmlized-source}. This will
11174 produce @file{file.org} and @file{file.org.html} in the publishing
11175 directory@footnote{@file{file-source.org} and @file{file-source.org.html} if
11176 source and publishing directories are equal. Note that with this kind of
11177 setup, you need to add @code{:exclude "-source\\.org"} to the project
11178 definition in @code{org-publish-project-alist} to prevent the published
11179 source files from being considered as new org files the next time the project
11180 is published.}. Other files like images only need to be copied to the
11181 publishing destination; for this you may use @code{org-publish-attachment}.
11182 For non-Org files, you always need to specify the publishing function:
11183
11184 @multitable @columnfractions 0.3 0.7
11185 @item @code{:publishing-function}
11186 @tab Function executing the publication of a file. This may also be a
11187 list of functions, which will all be called in turn.
11188 @item @code{:plain-source}
11189 @tab Non-nil means, publish plain source.
11190 @item @code{:htmlized-source}
11191 @tab Non-nil means, publish htmlized source.
11192 @end multitable
11193
11194 The function must accept three arguments: a property list containing at least
11195 a @code{:publishing-directory} property, the name of the file to be
11196 published, and the path to the publishing directory of the output file. It
11197 should take the specified file, make the necessary transformation (if any)
11198 and place the result into the destination folder.
11199
11200 @node Publishing options, Publishing links, Publishing action, Configuration
11201 @subsection Options for the HTML/@LaTeX{} exporters
11202 @cindex options, for publishing
11203
11204 The property list can be used to set many export options for the HTML
11205 and @LaTeX{} exporters. In most cases, these properties correspond to user
11206 variables in Org. The table below lists these properties along
11207 with the variable they belong to. See the documentation string for the
11208 respective variable for details.
11209
11210 @vindex org-export-html-link-up
11211 @vindex org-export-html-link-home
11212 @vindex org-export-default-language
11213 @vindex org-display-custom-times
11214 @vindex org-export-headline-levels
11215 @vindex org-export-with-section-numbers
11216 @vindex org-export-section-number-format
11217 @vindex org-export-with-toc
11218 @vindex org-export-preserve-breaks
11219 @vindex org-export-with-archived-trees
11220 @vindex org-export-with-emphasize
11221 @vindex org-export-with-sub-superscripts
11222 @vindex org-export-with-special-strings
11223 @vindex org-export-with-footnotes
11224 @vindex org-export-with-drawers
11225 @vindex org-export-with-tags
11226 @vindex org-export-with-todo-keywords
11227 @vindex org-export-with-tasks
11228 @vindex org-export-with-done-tasks
11229 @vindex org-export-with-priority
11230 @vindex org-export-with-TeX-macros
11231 @vindex org-export-with-LaTeX-fragments
11232 @vindex org-export-skip-text-before-1st-heading
11233 @vindex org-export-with-fixed-width
11234 @vindex org-export-with-timestamps
11235 @vindex org-export-author-info
11236 @vindex org-export-email-info
11237 @vindex org-export-creator-info
11238 @vindex org-export-time-stamp-file
11239 @vindex org-export-with-tables
11240 @vindex org-export-highlight-first-table-line
11241 @vindex org-export-html-style-include-default
11242 @vindex org-export-html-style-include-scripts
11243 @vindex org-export-html-style
11244 @vindex org-export-html-style-extra
11245 @vindex org-export-html-link-org-files-as-html
11246 @vindex org-export-html-inline-images
11247 @vindex org-export-html-extension
11248 @vindex org-export-html-table-tag
11249 @vindex org-export-html-expand
11250 @vindex org-export-html-with-timestamp
11251 @vindex org-export-publishing-directory
11252 @vindex org-export-html-preamble
11253 @vindex org-export-html-postamble
11254 @vindex user-full-name
11255 @vindex user-mail-address
11256 @vindex org-export-select-tags
11257 @vindex org-export-exclude-tags
11258
11259 @multitable @columnfractions 0.32 0.68
11260 @item @code{:link-up} @tab @code{org-export-html-link-up}
11261 @item @code{:link-home} @tab @code{org-export-html-link-home}
11262 @item @code{:language} @tab @code{org-export-default-language}
11263 @item @code{:customtime} @tab @code{org-display-custom-times}
11264 @item @code{:headline-levels} @tab @code{org-export-headline-levels}
11265 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
11266 @item @code{:section-number-format} @tab @code{org-export-section-number-format}
11267 @item @code{:table-of-contents} @tab @code{org-export-with-toc}
11268 @item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}
11269 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
11270 @item @code{:emphasize} @tab @code{org-export-with-emphasize}
11271 @item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts}
11272 @item @code{:special-strings} @tab @code{org-export-with-special-strings}
11273 @item @code{:footnotes} @tab @code{org-export-with-footnotes}
11274 @item @code{:drawers} @tab @code{org-export-with-drawers}
11275 @item @code{:tags} @tab @code{org-export-with-tags}
11276 @item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords}
11277 @item @code{:tasks} @tab @code{org-export-with-tasks}
11278 @item @code{:priority} @tab @code{org-export-with-priority}
11279 @item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}
11280 @item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}
11281 @item @code{:latex-listings} @tab @code{org-export-latex-listings}
11282 @item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading}
11283 @item @code{:fixed-width} @tab @code{org-export-with-fixed-width}
11284 @item @code{:timestamps} @tab @code{org-export-with-timestamps}
11285 @item @code{:author} @tab @code{user-full-name}
11286 @item @code{:email} @tab @code{user-mail-address} : @code{addr;addr;..}
11287 @item @code{:author-info} @tab @code{org-export-author-info}
11288 @item @code{:email-info} @tab @code{org-export-email-info}
11289 @item @code{:creator-info} @tab @code{org-export-creator-info}
11290 @item @code{:tables} @tab @code{org-export-with-tables}
11291 @item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line}
11292 @item @code{:style-include-default} @tab @code{org-export-html-style-include-default}
11293 @item @code{:style-include-scripts} @tab @code{org-export-html-style-include-scripts}
11294 @item @code{:style} @tab @code{org-export-html-style}
11295 @item @code{:style-extra} @tab @code{org-export-html-style-extra}
11296 @item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html}
11297 @item @code{:inline-images} @tab @code{org-export-html-inline-images}
11298 @item @code{:html-extension} @tab @code{org-export-html-extension}
11299 @item @code{:html-preamble} @tab @code{org-export-html-preamble}
11300 @item @code{:html-postamble} @tab @code{org-export-html-postamble}
11301 @item @code{:xml-declaration} @tab @code{org-export-html-xml-declaration}
11302 @item @code{:html-table-tag} @tab @code{org-export-html-table-tag}
11303 @item @code{:expand-quoted-html} @tab @code{org-export-html-expand}
11304 @item @code{:timestamp} @tab @code{org-export-html-with-timestamp}
11305 @item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
11306 @item @code{:select-tags} @tab @code{org-export-select-tags}
11307 @item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
11308 @item @code{:latex-image-options} @tab @code{org-export-latex-image-default-option}
11309 @end multitable
11310
11311 Most of the @code{org-export-with-*} variables have the same effect in
11312 both HTML and @LaTeX{} exporters, except for @code{:TeX-macros} and
11313 @code{:LaTeX-fragments} options, respectively @code{nil} and @code{t} in the
11314 @LaTeX{} export. See @code{org-export-plist-vars} to check this list of
11315 options.
11316
11317
11318
11319 @vindex org-publish-project-alist
11320 When a property is given a value in @code{org-publish-project-alist},
11321 its setting overrides the value of the corresponding user variable (if
11322 any) during publishing. Options set within a file (@pxref{Export
11323 options}), however, override everything.
11324
11325 @node Publishing links, Sitemap, Publishing options, Configuration
11326 @subsection Links between published files
11327 @cindex links, publishing
11328
11329 To create a link from one Org file to another, you would use
11330 something like @samp{[[file:foo.org][The foo]]} or simply
11331 @samp{file:foo.org.} (@pxref{Hyperlinks}). When published, this link
11332 becomes a link to @file{foo.html}. In this way, you can interlink the
11333 pages of your "org web" project and the links will work as expected when
11334 you publish them to HTML. If you also publish the Org source file and want
11335 to link to that, use an @code{http:} link instead of a @code{file:} link,
11336 because @code{file:} links are converted to link to the corresponding
11337 @file{html} file.
11338
11339 You may also link to related files, such as images. Provided you are careful
11340 with relative file names, and provided you have also configured Org to upload
11341 the related files, these links will work too. See @ref{Complex example}, for
11342 an example of this usage.
11343
11344 Sometimes an Org file to be published may contain links that are
11345 only valid in your production environment, but not in the publishing
11346 location. In this case, use the property
11347
11348 @multitable @columnfractions 0.4 0.6
11349 @item @code{:link-validation-function}
11350 @tab Function to validate links
11351 @end multitable
11352
11353 @noindent
11354 to define a function for checking link validity. This function must
11355 accept two arguments, the file name and a directory relative to which
11356 the file name is interpreted in the production environment. If this
11357 function returns @code{nil}, then the HTML generator will only insert a
11358 description into the HTML file, but no link. One option for this
11359 function is @code{org-publish-validate-link} which checks if the given
11360 file is part of any project in @code{org-publish-project-alist}.
11361
11362 @node Sitemap, Generating an index, Publishing links, Configuration
11363 @subsection Generating a sitemap
11364 @cindex sitemap, of published pages
11365
11366 The following properties may be used to control publishing of
11367 a map of files for a given project.
11368
11369 @multitable @columnfractions 0.35 0.65
11370 @item @code{:auto-sitemap}
11371 @tab When non-nil, publish a sitemap during @code{org-publish-current-project}
11372 or @code{org-publish-all}.
11373
11374 @item @code{:sitemap-filename}
11375 @tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which
11376 becomes @file{sitemap.html}).
11377
11378 @item @code{:sitemap-title}
11379 @tab Title of sitemap page. Defaults to name of file.
11380
11381 @item @code{:sitemap-function}
11382 @tab Plug-in function to use for generation of the sitemap.
11383 Defaults to @code{org-publish-org-sitemap}, which generates a plain list
11384 of links to all files in the project.
11385
11386 @item @code{:sitemap-sort-folders}
11387 @tab Where folders should appear in the sitemap. Set this to @code{first}
11388 (default) or @code{last} to display folders first or last,
11389 respectively. Any other value will mix files and folders.
11390
11391 @item @code{:sitemap-sort-files}
11392 @tab How the files are sorted in the site map. Set this to
11393 @code{alphabetically} (default), @code{chronologically} or
11394 @code{anti-chronologically}. @code{chronologically} sorts the files with
11395 older date first while @code{anti-chronologically} sorts the files with newer
11396 date first. @code{alphabetically} sorts the files alphabetically. The date of
11397 a file is retrieved with @code{org-publish-find-date}.
11398
11399 @item @code{:sitemap-ignore-case}
11400 @tab Should sorting be case-sensitive? Default @code{nil}.
11401
11402 @item @code{:sitemap-file-entry-format}
11403 @tab With this option one can tell how a sitemap's entry is formated in the
11404 sitemap. This is a format string with some escape sequences: @code{%t} stands
11405 for the title of the file, @code{%a} stands for the author of the file and
11406 @code{%d} stands for the date of the file. The date is retrieved with the
11407 @code{org-publish-find-date} function and formated with
11408 @code{org-publish-sitemap-date-format}. Default @code{%t}.
11409
11410 @item @code{:sitemap-date-format}
11411 @tab Format string for the @code{format-time-string} function that tells how
11412 a sitemap entry's date is to be formated. This property bypasses
11413 @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
11414
11415 @item @code{:sitemap-sans-extension}
11416 @tab When non-nil, remove filenames' extensions from the generated sitemap.
11417 Useful to have cool URIs (see @uref{http://www.w3.org/Provider/Style/URI}).
11418 Defaults to @code{nil}.
11419
11420 @end multitable
11421
11422 @node Generating an index, , Sitemap, Configuration
11423 @subsection Generating an index
11424 @cindex index, in a publishing project
11425
11426 Org-mode can generate an index across the files of a publishing project.
11427
11428 @multitable @columnfractions 0.25 0.75
11429 @item @code{:makeindex}
11430 @tab When non-nil, generate in index in the file @file{theindex.org} and
11431 publish it as @file{theindex.html}.
11432 @end multitable
11433
11434 The file will be created when first publishing a project with the
11435 @code{:makeindex} set. The file only contains a statement @code{#+include:
11436 "theindex.inc"}. You can then build around this include statement by adding
11437 a title, style information, etc.
11438
11439 @node Uploading files, Sample configuration, Configuration, Publishing
11440 @section Uploading files
11441 @cindex rsync
11442 @cindex unison
11443
11444 For those people already utilizing third party sync tools such as
11445 @command{rsync} or @command{unison}, it might be preferable not to use the built in
11446 @i{remote} publishing facilities of Org-mode which rely heavily on
11447 Tramp. Tramp, while very useful and powerful, tends not to be
11448 so efficient for multiple file transfer and has been known to cause problems
11449 under heavy usage.
11450
11451 Specialized synchronization utilities offer several advantages. In addition
11452 to timestamp comparison, they also do content and permissions/attribute
11453 checks. For this reason you might prefer to publish your web to a local
11454 directory (possibly even @i{in place} with your Org files) and then use
11455 @file{unison} or @file{rsync} to do the synchronization with the remote host.
11456
11457 Since Unison (for example) can be configured as to which files to transfer to
11458 a certain remote destination, it can greatly simplify the project publishing
11459 definition. Simply keep all files in the correct location, process your Org
11460 files with @code{org-publish} and let the synchronization tool do the rest.
11461 You do not need, in this scenario, to include attachments such as @file{jpg},
11462 @file{css} or @file{gif} files in the project definition since the 3rd party
11463 tool syncs them.
11464
11465 Publishing to a local directory is also much faster than to a remote one, so
11466 that you can afford more easily to republish entire projects. If you set
11467 @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
11468 benefit of re-including any changed external files such as source example
11469 files you might include with @code{#+INCLUDE}. The timestamp mechanism in
11470 Org is not smart enough to detect if included files have been modified.
11471
11472 @node Sample configuration, Triggering publication, Uploading files, Publishing
11473 @section Sample configuration
11474
11475 Below we provide two example configurations. The first one is a simple
11476 project publishing only a set of Org files. The second example is
11477 more complex, with a multi-component project.
11478
11479 @menu
11480 * Simple example:: One-component publishing
11481 * Complex example:: A multi-component publishing example
11482 @end menu
11483
11484 @node Simple example, Complex example, Sample configuration, Sample configuration
11485 @subsection Example: simple publishing configuration
11486
11487 This example publishes a set of Org files to the @file{public_html}
11488 directory on the local machine.
11489
11490 @lisp
11491 (setq org-publish-project-alist
11492 '(("org"
11493 :base-directory "~/org/"
11494 :publishing-directory "~/public_html"
11495 :section-numbers nil
11496 :table-of-contents nil
11497 :style "<link rel=\"stylesheet\"
11498 href=\"../other/mystyle.css\"
11499 type=\"text/css\"/>")))
11500 @end lisp
11501
11502 @node Complex example, , Simple example, Sample configuration
11503 @subsection Example: complex publishing configuration
11504
11505 This more complicated example publishes an entire website, including
11506 Org files converted to HTML, image files, Emacs Lisp source code, and
11507 style sheets. The publishing directory is remote and private files are
11508 excluded.
11509
11510 To ensure that links are preserved, care should be taken to replicate
11511 your directory structure on the web server, and to use relative file
11512 paths. For example, if your Org files are kept in @file{~/org} and your
11513 publishable images in @file{~/images}, you would link to an image with
11514 @c
11515 @example
11516 file:../images/myimage.png
11517 @end example
11518 @c
11519 On the web server, the relative path to the image should be the
11520 same. You can accomplish this by setting up an "images" folder in the
11521 right place on the web server, and publishing images to it.
11522
11523 @lisp
11524 (setq org-publish-project-alist
11525 '(("orgfiles"
11526 :base-directory "~/org/"
11527 :base-extension "org"
11528 :publishing-directory "/ssh:user@@host:~/html/notebook/"
11529 :publishing-function org-publish-org-to-html
11530 :exclude "PrivatePage.org" ;; regexp
11531 :headline-levels 3
11532 :section-numbers nil
11533 :table-of-contents nil
11534 :style "<link rel=\"stylesheet\"
11535 href=\"../other/mystyle.css\" type=\"text/css\"/>"
11536 :html-preamble t)
11537
11538 ("images"
11539 :base-directory "~/images/"
11540 :base-extension "jpg\\|gif\\|png"
11541 :publishing-directory "/ssh:user@@host:~/html/images/"
11542 :publishing-function org-publish-attachment)
11543
11544 ("other"
11545 :base-directory "~/other/"
11546 :base-extension "css\\|el"
11547 :publishing-directory "/ssh:user@@host:~/html/other/"
11548 :publishing-function org-publish-attachment)
11549 ("website" :components ("orgfiles" "images" "other"))))
11550 @end lisp
11551
11552 @node Triggering publication, , Sample configuration, Publishing
11553 @section Triggering publication
11554
11555 Once properly configured, Org can publish with the following commands:
11556
11557 @table @kbd
11558 @orgcmd{C-c C-e X,org-publish}
11559 Prompt for a specific project and publish all files that belong to it.
11560 @orgcmd{C-c C-e P,org-publish-current-project}
11561 Publish the project containing the current file.
11562 @orgcmd{C-c C-e F,org-publish-current-file}
11563 Publish only the current file.
11564 @orgcmd{C-c C-e E,org-publish-all}
11565 Publish every project.
11566 @end table
11567
11568 @vindex org-publish-use-timestamps-flag
11569 Org uses timestamps to track when a file has changed. The above functions
11570 normally only publish changed files. You can override this and force
11571 publishing of all files by giving a prefix argument to any of the commands
11572 above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
11573 This may be necessary in particular if files include other files via
11574 @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
11575
11576 @comment node-name, next, previous, up
11577 @comment Working With Source Code, Miscellaneous, Publishing, Top
11578
11579 @node Working With Source Code, Miscellaneous, Publishing, Top
11580 @chapter Working with source code
11581 @cindex Schulte, Eric
11582 @cindex Davison, Dan
11583 @cindex source code, working with
11584
11585 Source code can be included in Org-mode documents using a @samp{src} block,
11586 e.g.@:
11587
11588 @example
11589 #+BEGIN_SRC emacs-lisp
11590 (defun org-xor (a b)
11591 "Exclusive or."
11592 (if a (not b) b))
11593 #+END_SRC
11594 @end example
11595
11596 Org-mode provides a number of features for working with live source code,
11597 including editing of code blocks in their native major-mode, evaluation of
11598 code blocks, converting code blocks into source files (known as @dfn{tangling}
11599 in literate programming), and exporting code blocks and their
11600 results in several formats. This functionality was contributed by Eric
11601 Schulte and Dan Davison, and was originally named Org-babel.
11602
11603 The following sections describe Org-mode's code block handling facilities.
11604
11605 @menu
11606 * Structure of code blocks:: Code block syntax described
11607 * Editing source code:: Language major-mode editing
11608 * Exporting code blocks:: Export contents and/or results
11609 * Extracting source code:: Create pure source code files
11610 * Evaluating code blocks:: Place results of evaluation in the Org-mode buffer
11611 * Library of Babel:: Use and contribute to a library of useful code blocks
11612 * Languages:: List of supported code block languages
11613 * Header arguments:: Configure code block functionality
11614 * Results of evaluation:: How evaluation results are handled
11615 * Noweb reference syntax:: Literate programming in Org-mode
11616 * Key bindings and useful functions:: Work quickly with code blocks
11617 * Batch execution:: Call functions from the command line
11618 @end menu
11619
11620 @comment node-name, next, previous, up
11621 @comment Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code
11622
11623 @node Structure of code blocks, Editing source code, Working With Source Code, Working With Source Code
11624 @section Structure of code blocks
11625 @cindex code block, structure
11626 @cindex source code, block structure
11627
11628 The structure of code blocks is as follows:
11629
11630 @example
11631 #+srcname: <name>
11632 #+begin_src <language> <switches> <header arguments>
11633 <body>
11634 #+end_src
11635 @end example
11636
11637 Switches and header arguments are optional. Code can also be embedded in text
11638 inline using
11639
11640 @example
11641 src_<language>@{<body>@}
11642 @end example
11643
11644 or
11645
11646 @example
11647 src_<language>[<header arguments>]@{<body>@}
11648 @end example
11649
11650 @table @code
11651 @item <name>
11652 This name is associated with the code block. This is similar to the
11653 @samp{#+tblname} lines that can be used to name tables in Org-mode files.
11654 Referencing the name of a code block makes it possible to evaluate the
11655 block from other places in the file, other files, or from Org-mode table
11656 formulas (see @ref{The spreadsheet}). Names are assumed to be unique by
11657 evaluation functions and the behavior of multiple blocks of the same name is
11658 undefined.
11659 @item <language>
11660 The language of the code in the block.
11661 @item <switches>
11662 Optional switches controlling exportation of the code block (see switches discussion in
11663 @ref{Literal examples})
11664 @item <header arguments>
11665 Optional header arguments control many aspects of evaluation, export and
11666 tangling of code blocks. See the @ref{Header arguments}.
11667 Header arguments can also be set on a per-buffer or per-subtree
11668 basis using properties.
11669 @item <body>
11670 The source code.
11671 @end table
11672
11673 @comment node-name, next, previous, up
11674 @comment Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code
11675
11676 @node Editing source code, Exporting code blocks, Structure of code blocks, Working With Source Code
11677 @section Editing source code
11678 @cindex code block, editing
11679 @cindex source code, editing
11680
11681 @kindex C-c '
11682 Use @kbd{C-c '} to edit the current code block. This brings up
11683 a language major-mode edit buffer containing the body of the code
11684 block. Saving this buffer will write the new contents back to the Org
11685 buffer. Use @kbd{C-c '} again to exit.
11686
11687 The @code{org-src-mode} minor mode will be active in the edit buffer. The
11688 following variables can be used to configure the behavior of the edit
11689 buffer. See also the customization group @code{org-edit-structure} for
11690 further configuration options.
11691
11692 @table @code
11693 @item org-src-lang-modes
11694 If an Emacs major-mode named @code{<lang>-mode} exists, where
11695 @code{<lang>} is the language named in the header line of the code block,
11696 then the edit buffer will be placed in that major-mode. This variable
11697 can be used to map arbitrary language names to existing major modes.
11698 @item org-src-window-setup
11699 Controls the way Emacs windows are rearranged when the edit buffer is created.
11700 @item org-src-preserve-indentation
11701 This variable is especially useful for tangling languages such as
11702 Python, in which whitespace indentation in the output is critical.
11703 @item org-src-ask-before-returning-to-edit-buffer
11704 By default, Org will ask before returning to an open edit buffer. Set this
11705 variable to nil to switch without asking.
11706 @end table
11707
11708 To turn on native code fontification in the @emph{Org} buffer, configure the
11709 variable @code{org-src-fontify-natively}.
11710
11711 @comment node-name, next, previous, up
11712 @comment Exporting code blocks, Extracting source code, Editing source code, Working With Source Code
11713
11714 @node Exporting code blocks, Extracting source code, Editing source code, Working With Source Code
11715 @section Exporting code blocks
11716 @cindex code block, exporting
11717 @cindex source code, exporting
11718
11719 It is possible to export the @emph{contents} of code blocks, the
11720 @emph{results} of code block evaluation, @emph{neither}, or @emph{both}. For
11721 most languages, the default exports the contents of code blocks. However, for
11722 some languages (e.g.@: @code{ditaa}) the default exports the results of code
11723 block evaluation. For information on exporting code block bodies, see
11724 @ref{Literal examples}.
11725
11726 The @code{:exports} header argument can be used to specify export
11727 behavior:
11728
11729 @subsubheading Header arguments:
11730 @table @code
11731 @item :exports code
11732 The default in most languages. The body of the code block is exported, as
11733 described in @ref{Literal examples}.
11734 @item :exports results
11735 The code block will be evaluated and the results will be placed in the
11736 Org-mode buffer for export, either updating previous results of the code
11737 block located anywhere in the buffer or, if no previous results exist,
11738 placing the results immediately after the code block. The body of the code
11739 block will not be exported.
11740 @item :exports both
11741 Both the code block and its results will be exported.
11742 @item :exports none
11743 Neither the code block nor its results will be exported.
11744 @end table
11745
11746 It is possible to inhibit the evaluation of code blocks during export.
11747 Setting the @code{org-export-babel-evaluate} variable to @code{nil} will
11748 ensure that no code blocks are evaluated as part of the export process. This
11749 can be useful in situations where potentially untrusted Org-mode files are
11750 exported in an automated fashion, for example when Org-mode is used as the
11751 markup language for a wiki.
11752
11753 @comment node-name, next, previous, up
11754 @comment Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
11755 @node Extracting source code, Evaluating code blocks, Exporting code blocks, Working With Source Code
11756 @section Extracting source code
11757 @cindex tangling
11758 @cindex source code, extracting
11759 @cindex code block, extracting source code
11760
11761 Creating pure source code files by extracting code from source blocks is
11762 referred to as ``tangling''---a term adopted from the literate programming
11763 community. During ``tangling'' of code blocks their bodies are expanded
11764 using @code{org-babel-expand-src-block} which can expand both variable and
11765 ``noweb'' style references (see @ref{Noweb reference syntax}).
11766
11767 @subsubheading Header arguments
11768 @table @code
11769 @item :tangle no
11770 The default. The code block is not included in the tangled output.
11771 @item :tangle yes
11772 Include the code block in the tangled output. The output file name is the
11773 name of the org file with the extension @samp{.org} replaced by the extension
11774 for the block language.
11775 @item :tangle filename
11776 Include the code block in the tangled output to file @samp{filename}.
11777 @end table
11778
11779 @kindex C-c C-v t
11780 @subsubheading Functions
11781 @table @code
11782 @item org-babel-tangle
11783 Tangle the current file. Bound to @kbd{C-c C-v t}.
11784 @item org-babel-tangle-file
11785 Choose a file to tangle. Bound to @kbd{C-c C-v f}.
11786 @end table
11787
11788 @subsubheading Hooks
11789 @table @code
11790 @item org-babel-post-tangle-hook
11791 This hook is run from within code files tangled by @code{org-babel-tangle}.
11792 Example applications could include post-processing, compilation or evaluation
11793 of tangled code files.
11794 @end table
11795
11796 @node Evaluating code blocks, Library of Babel, Extracting source code, Working With Source Code
11797 @section Evaluating code blocks
11798 @cindex code block, evaluating
11799 @cindex source code, evaluating
11800
11801 Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
11802 potential for that code to do harm. Org-mode provides a number of safeguards
11803 to ensure that it only evaluates code with explicit confirmation from the
11804 user. For information on these safeguards (and on how to disable them) see
11805 @ref{Code evaluation security}.} and the results placed in the Org-mode
11806 buffer. By default, evaluation is only turned on for @code{emacs-lisp} code
11807 blocks, however support exists for evaluating blocks in many languages. See
11808 @ref{Languages} for a list of supported languages. See @ref{Structure of
11809 code blocks} for information on the syntax used to define a code block.
11810
11811 @kindex C-c C-c
11812 There are a number of ways to evaluate code blocks. The simplest is to press
11813 @kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The
11814 @code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code
11815 evaluation from the @kbd{C-c C-c} key binding.}. This will call the
11816 @code{org-babel-execute-src-block} function to evaluate the block and insert
11817 its results into the Org-mode buffer.
11818
11819 It is also possible to evaluate named code blocks from anywhere in an
11820 Org-mode buffer or an Org-mode table. @code{#+call} (or synonymously
11821 @code{#+function} or @code{#+lob}) lines can be used to remotely execute code
11822 blocks located in the current Org-mode buffer or in the ``Library of Babel''
11823 (see @ref{Library of Babel}). These lines use the following syntax to place
11824 a call on a line by itself.
11825
11826 @example
11827 #+call: <name>(<arguments>)
11828 #+call: <name>[<header args>](<arguments>) <header args>
11829 @end example
11830
11831 The following syntax can be used to place these calls within a block of
11832 prose.
11833
11834 @example
11835 ...prose... call_<name>(<arguments>) ...prose...
11836 ...prose... call_<name>[<header args>](<arguments>)[<header args>] ...prose...
11837 @end example
11838
11839 @table @code
11840 @item <name>
11841 The name of the code block to be evaluated.
11842 @item <arguments>
11843 Arguments specified in this section will be passed to the code block. These
11844 arguments should relate to @code{:var} header arguments in the called code
11845 block expressed using standard function call syntax. For example if the
11846 original code block named @code{double} has the header argument @code{:var
11847 n=2}, then the call line passing the number four to that block would be
11848 written as @code{#+call: double(n=2)}.
11849 @item <header args>
11850 Header arguments can be placed either inside the call to the code block or at
11851 the end of the line as shown below.
11852
11853 @example
11854 #+call: code_bloc_name[XXXX](arguments) YYYY
11855 @end example
11856
11857 Header arguments located in these two locations are treated differently.
11858
11859 @table @code
11860 @item XXXX
11861 Those placed in the @code{XXXX} location are passed through and applied to
11862 the code block being called. These header arguments affect how the code
11863 block is evaluated, for example @code{[:results output]} will collect the
11864 results from @code{STDOUT} of the called code block.
11865 @item YYYY
11866 Those placed in the @code{YYYY} location are applied to the call line and do
11867 not affect the code block being called. These header arguments affect how
11868 the results are incorporated into the Org-mode buffer when the call line is
11869 evaluated, and how the call line is exported. For example @code{:results
11870 org} at the end of the call line will insert the results of the call line
11871 inside of an Org-mode block.
11872 @end table
11873
11874 For more examples of passing header arguments to @code{#+call:} lines see
11875 @ref{Header arguments in function calls}.
11876 @end table
11877
11878 @node Library of Babel, Languages, Evaluating code blocks, Working With Source Code
11879 @section Library of Babel
11880 @cindex babel, library of
11881 @cindex source code, library
11882 @cindex code block, library
11883
11884 The ``Library of Babel'' is a library of code blocks
11885 that can be called from any Org-mode file. The library is housed in an
11886 Org-mode file located in the @samp{contrib} directory of Org-mode.
11887 Org-mode users can deposit functions they believe to be generally
11888 useful in the library.
11889
11890 Code blocks defined in the ``Library of Babel'' can be called remotely as if
11891 they were in the current Org-mode buffer (see @ref{Evaluating code blocks}
11892 for information on the syntax of remote code block evaluation).
11893
11894 @kindex C-c C-v i
11895 Code blocks located in any Org-mode file can be loaded into the ``Library of
11896 Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v
11897 i}.
11898
11899 @node Languages, Header arguments, Library of Babel, Working With Source Code
11900 @section Languages
11901 @cindex babel, languages
11902 @cindex source code, languages
11903 @cindex code block, languages
11904
11905 Code blocks in the following languages are supported.
11906
11907 @multitable @columnfractions 0.28 0.3 0.22 0.2
11908 @item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}
11909 @item Asymptote @tab asymptote @tab Awk @tab awk
11910 @item Emacs Calc @tab calc @tab C @tab C
11911 @item C++ @tab C++ @tab Clojure @tab clojure
11912 @item CSS @tab css @tab ditaa @tab ditaa
11913 @item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp
11914 @item gnuplot @tab gnuplot @tab Haskell @tab haskell
11915 @item Java @tab java @tab @tab
11916 @item Javascript @tab js @tab LaTeX @tab latex
11917 @item Ledger @tab ledger @tab Lisp @tab lisp
11918 @item Lilypond @tab lilypond @tab MATLAB @tab matlab
11919 @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
11920 @item Octave @tab octave @tab Org-mode @tab org
11921 @item Oz @tab oz @tab Perl @tab perl
11922 @item Plantuml @tab plantuml @tab Python @tab python
11923 @item R @tab R @tab Ruby @tab ruby
11924 @item Sass @tab sass @tab Scheme @tab scheme
11925 @item GNU Screen @tab screen @tab shell @tab sh
11926 @item SQL @tab sql @tab SQLite @tab sqlite
11927 @end multitable
11928
11929 Language-specific documentation is available for some languages. If
11930 available, it can be found at
11931 @uref{http://orgmode.org/worg/org-contrib/babel/languages}.
11932
11933 The @code{org-babel-load-languages} controls which languages are enabled for
11934 evaluation (by default only @code{emacs-lisp} is enabled). This variable can
11935 be set using the customization interface or by adding code like the following
11936 to your emacs configuration.
11937
11938 @quotation
11939 The following disables @code{emacs-lisp} evaluation and enables evaluation of
11940 @code{R} code blocks.
11941 @end quotation
11942
11943 @lisp
11944 (org-babel-do-load-languages
11945 'org-babel-load-languages
11946 '((emacs-lisp . nil)
11947 (R . t)))
11948 @end lisp
11949
11950 It is also possible to enable support for a language by loading the related
11951 elisp file with @code{require}.
11952
11953 @quotation
11954 The following adds support for evaluating @code{clojure} code blocks.
11955 @end quotation
11956
11957 @lisp
11958 (require 'ob-clojure)
11959 @end lisp
11960
11961 @node Header arguments, Results of evaluation, Languages, Working With Source Code
11962 @section Header arguments
11963 @cindex code block, header arguments
11964 @cindex source code, block header arguments
11965
11966 Code block functionality can be configured with header arguments. This
11967 section provides an overview of the use of header arguments, and then
11968 describes each header argument in detail.
11969
11970 @menu
11971 * Using header arguments:: Different ways to set header arguments
11972 * Specific header arguments:: List of header arguments
11973 @end menu
11974
11975 @node Using header arguments, Specific header arguments, Header arguments, Header arguments
11976 @subsection Using header arguments
11977
11978 The values of header arguments can be set in six different ways, each more
11979 specific (and having higher priority) than the last.
11980 @menu
11981 * System-wide header arguments:: Set global default values
11982 * Language-specific header arguments:: Set default values by language
11983 * Buffer-wide header arguments:: Set default values for a specific buffer
11984 * Header arguments in Org-mode properties:: Set default values for a buffer or heading
11985 * Code block specific header arguments:: The most common way to set values
11986 * Header arguments in function calls:: The most specific level
11987 @end menu
11988
11989
11990 @node System-wide header arguments, Language-specific header arguments, Using header arguments, Using header arguments
11991 @subsubheading System-wide header arguments
11992 @vindex org-babel-default-header-args
11993 System-wide values of header arguments can be specified by customizing the
11994 @code{org-babel-default-header-args} variable:
11995
11996 @example
11997 :session => "none"
11998 :results => "replace"
11999 :exports => "code"
12000 :cache => "no"
12001 :noweb => "no"
12002 @end example
12003
12004 @c @example
12005 @c org-babel-default-header-args is a variable defined in `org-babel.el'.
12006 @c Its value is
12007 @c ((:session . "none")
12008 @c (:results . "replace")
12009 @c (:exports . "code")
12010 @c (:cache . "no")
12011 @c (:noweb . "no"))
12012
12013
12014 @c Documentation:
12015 @c Default arguments to use when evaluating a code block.
12016 @c @end example
12017
12018 For example, the following example could be used to set the default value of
12019 @code{:noweb} header arguments to @code{yes}. This would have the effect of
12020 expanding @code{:noweb} references by default when evaluating source code
12021 blocks.
12022
12023 @lisp
12024 (setq org-babel-default-header-args
12025 (cons '(:noweb . "yes")
12026 (assq-delete-all :noweb org-babel-default-header-args)))
12027 @end lisp
12028
12029 @node Language-specific header arguments, Buffer-wide header arguments, System-wide header arguments, Using header arguments
12030 @subsubheading Language-specific header arguments
12031 Each language can define its own set of default header arguments. See the
12032 language-specific documentation available online at
12033 @uref{http://orgmode.org/worg/org-contrib/babel}.
12034
12035 @node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments
12036 @subsubheading Buffer-wide header arguments
12037 Buffer-wide header arguments may be specified through the use of a special
12038 line placed anywhere in an Org-mode file. The line consists of the
12039 @code{#+BABEL:} keyword followed by a series of header arguments which may be
12040 specified using the standard header argument syntax.
12041
12042 For example the following would set @code{session} to @code{*R*}, and
12043 @code{results} to @code{silent} for every code block in the buffer, ensuring
12044 that all execution took place in the same session, and no results would be
12045 inserted into the buffer.
12046
12047 @example
12048 #+BABEL: :session *R* :results silent
12049 @end example
12050
12051 @node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments
12052 @subsubheading Header arguments in Org-mode properties
12053
12054 Header arguments are also read from Org-mode properties (see @ref{Property
12055 syntax}), which can be set on a buffer-wide or per-heading basis. An example
12056 of setting a header argument for all code blocks in a buffer is
12057
12058 @example
12059 #+property: tangle yes
12060 @end example
12061
12062 When properties are used to set default header arguments, they are looked up
12063 with inheritance, so the value of the @code{:cache} header argument will default
12064 to @code{yes} in all code blocks in the subtree rooted at the following
12065 heading:
12066
12067 @example
12068 * outline header
12069 :PROPERTIES:
12070 :cache: yes
12071 :END:
12072 @end example
12073
12074 @kindex C-c C-x p
12075 @vindex org-babel-default-header-args
12076 Properties defined in this way override the properties set in
12077 @code{org-babel-default-header-args}. It is convenient to use the
12078 @code{org-set-property} function bound to @kbd{C-c C-x p} to set properties
12079 in Org-mode documents.
12080
12081 @node Code block specific header arguments, Header arguments in function calls, Header arguments in Org-mode properties, Using header arguments
12082 @subsubheading Code block specific header arguments
12083
12084 The most common way to assign values to header arguments is at the
12085 code block level. This can be done by listing a sequence of header
12086 arguments and their values as part of the @code{#+begin_src} line.
12087 Properties set in this way override both the values of
12088 @code{org-babel-default-header-args} and header arguments specified as
12089 properties. In the following example, the @code{:results} header argument
12090 is set to @code{silent}, meaning the results of execution will not be
12091 inserted in the buffer, and the @code{:exports} header argument is set to
12092 @code{code}, meaning only the body of the code block will be
12093 preserved on export to HTML or LaTeX.
12094
12095 @example
12096 #+source: factorial
12097 #+begin_src haskell :results silent :exports code :var n=0
12098 fac 0 = 1
12099 fac n = n * fac (n-1)
12100 #+end_src
12101 @end example
12102 Similarly, it is possible to set header arguments for inline code blocks:
12103
12104 @example
12105 src_haskell[:exports both]@{fac 5@}
12106 @end example
12107
12108 Code block header arguments can span multiple lines using =#+header:= or
12109 =#+headers:= lines preceding a code block or nested in between the name and
12110 body of a named code block.
12111
12112 Multi-line header arguments on an un-named code block:
12113 @example
12114 #+headers: :var data1=1
12115 #+begin_src emacs-lisp :var data2=2
12116 (message "data1:%S, data2:%S" data1 data2)
12117 #+end_src
12118
12119 #+results:
12120 : data1:1, data2:2
12121 @end example
12122
12123 Multi-line header arguments on a named code block:
12124 @example
12125 #+source: named-block
12126 #+header: :var data=2
12127 #+begin_src emacs-lisp
12128 (message "data:%S" data)
12129 #+end_src
12130
12131 #+results: named-block
12132 : data:2
12133 @end example
12134
12135 @node Header arguments in function calls, , Code block specific header arguments, Using header arguments
12136 @comment node-name, next, previous, up
12137 @subsubheading Header arguments in function calls
12138
12139 At the most specific level, header arguments for ``Library of Babel'' or
12140 function call lines can be set as shown in the two examples below. For more
12141 information on the structure of @code{#+call:} lines see @ref{Evaluating code
12142 blocks}.
12143
12144 The following will apply the @code{:exports results} header argument to the
12145 evaluation of the @code{#+call:} line.
12146 @example
12147 #+call: factorial(n=5) :exports results
12148 @end example
12149
12150 The following will apply the @code{:session special} header argument to the
12151 evaluation of the @code{factorial} code block.
12152 @example
12153 #+call: factorial[:session special](n=5)
12154 @end example
12155
12156 @node Specific header arguments, , Using header arguments, Header arguments
12157 @subsection Specific header arguments
12158 The following header arguments are defined:
12159
12160 @menu
12161 * var:: Pass arguments to code blocks
12162 * results:: Specify the type of results and how they will
12163 be collected and handled
12164 * file:: Specify a path for file output
12165 * dir:: Specify the default (possibly remote)
12166 directory for code block execution
12167 * exports:: Export code and/or results
12168 * tangle:: Toggle tangling and specify file name
12169 * mkdirp:: Toggle creation of parent directories of target
12170 files during tangling
12171 * comments:: Toggle insertion of comments in tangled
12172 code files
12173 * padline:: Control insertion of padding lines in tangled
12174 code files
12175 * no-expand:: Turn off variable assignment and noweb
12176 expansion during tangling
12177 * session:: Preserve the state of code evaluation
12178 * noweb:: Toggle expansion of noweb references
12179 * noweb-ref:: Specify block's noweb reference resolution target
12180 * cache:: Avoid re-evaluating unchanged code blocks
12181 * sep:: Delimiter for writing tabular results outside Org
12182 * hlines:: Handle horizontal lines in tables
12183 * colnames:: Handle column names in tables
12184 * rownames:: Handle row names in tables
12185 * shebang:: Make tangled files executable
12186 * eval:: Limit evaluation of specific code blocks
12187 @end menu
12188
12189 Additional header arguments are defined on a language-specific basis, see
12190 @ref{Languages}.
12191
12192 @node var, results, Specific header arguments, Specific header arguments
12193 @subsubsection @code{:var}
12194 The @code{:var} header argument is used to pass arguments to code blocks.
12195 The specifics of how arguments are included in a code block vary by language;
12196 these are addressed in the language-specific documentation. However, the
12197 syntax used to specify arguments is the same across all languages. The
12198 values passed to arguments can be literal values, values from org-mode tables
12199 and literal example blocks, the results of other code blocks, or Emacs Lisp
12200 code---see the ``Emacs Lisp evaluation of variables'' heading below.
12201
12202 These values can be indexed in a manner similar to arrays---see the
12203 ``indexable variable values'' heading below.
12204
12205 The following syntax is used to pass arguments to code blocks using the
12206 @code{:var} header argument.
12207
12208 @example
12209 :var name=assign
12210 @end example
12211
12212 where @code{assign} can take one of the following forms
12213
12214 @itemize @bullet
12215 @item literal value
12216 either a string @code{"string"} or a number @code{9}.
12217 @item reference
12218 a table name:
12219
12220 @example
12221 #+tblname: example-table
12222 | 1 |
12223 | 2 |
12224 | 3 |
12225 | 4 |
12226
12227 #+source: table-length
12228 #+begin_src emacs-lisp :var table=example-table
12229 (length table)
12230 #+end_src
12231
12232 #+results: table-length
12233 : 4
12234 @end example
12235
12236 a code block name, as assigned by @code{#+srcname:}, followed by
12237 parentheses:
12238
12239 @example
12240 #+begin_src emacs-lisp :var length=table-length()
12241 (* 2 length)
12242 #+end_src
12243
12244 #+results:
12245 : 8
12246 @end example
12247
12248 In addition, an argument can be passed to the code block referenced
12249 by @code{:var}. The argument is passed within the parentheses following the
12250 code block name:
12251
12252 @example
12253 #+source: double
12254 #+begin_src emacs-lisp :var input=8
12255 (* 2 input)
12256 #+end_src
12257
12258 #+results: double
12259 : 16
12260
12261 #+source: squared
12262 #+begin_src emacs-lisp :var input=double(input=1)
12263 (* input input)
12264 #+end_src
12265
12266 #+results: squared
12267 : 4
12268 @end example
12269 @end itemize
12270
12271 @subsubheading Alternate argument syntax
12272 It is also possible to specify arguments in a potentially more natural way
12273 using the @code{#+source:} line of a code block. As in the following
12274 example arguments can be packed inside of parenthesis, separated by commas,
12275 following the source name.
12276
12277 @example
12278 #+source: double(input=0, x=2)
12279 #+begin_src emacs-lisp
12280 (* 2 (+ input x))
12281 #+end_src
12282 @end example
12283
12284 @subsubheading Indexable variable values
12285 It is possible to reference portions of variable values by ``indexing'' into
12286 the variables. Indexes are 0 based with negative values counting back from
12287 the end. If an index is separated by @code{,}s then each subsequent section
12288 will index into the next deepest nesting or dimension of the value. Note
12289 that this indexing occurs @emph{before} other table related header arguments
12290 like @code{:hlines}, @code{:colnames} and @code{:rownames} are applied. The
12291 following example assigns the last cell of the first row the table
12292 @code{example-table} to the variable @code{data}:
12293
12294 @example
12295 #+results: example-table
12296 | 1 | a |
12297 | 2 | b |
12298 | 3 | c |
12299 | 4 | d |
12300
12301 #+begin_src emacs-lisp :var data=example-table[0,-1]
12302 data
12303 #+end_src
12304
12305 #+results:
12306 : a
12307 @end example
12308
12309 Ranges of variable values can be referenced using two integers separated by a
12310 @code{:}, in which case the entire inclusive range is referenced. For
12311 example the following assigns the middle three rows of @code{example-table}
12312 to @code{data}.
12313
12314 @example
12315 #+results: example-table
12316 | 1 | a |
12317 | 2 | b |
12318 | 3 | c |
12319 | 4 | d |
12320 | 5 | 3 |
12321
12322 #+begin_src emacs-lisp :var data=example-table[1:3]
12323 data
12324 #+end_src
12325
12326 #+results:
12327 | 2 | b |
12328 | 3 | c |
12329 | 4 | d |
12330 @end example
12331
12332 Additionally, an empty index, or the single character @code{*}, are both
12333 interpreted to mean the entire range and as such are equivalent to
12334 @code{0:-1}, as shown in the following example in which the entire first
12335 column is referenced.
12336
12337 @example
12338 #+results: example-table
12339 | 1 | a |
12340 | 2 | b |
12341 | 3 | c |
12342 | 4 | d |
12343
12344 #+begin_src emacs-lisp :var data=example-table[,0]
12345 data
12346 #+end_src
12347
12348 #+results:
12349 | 1 | 2 | 3 | 4 |
12350 @end example
12351
12352 It is possible to index into the results of code blocks as well as tables.
12353 Any number of dimensions can be indexed. Dimensions are separated from one
12354 another by commas, as shown in the following example.
12355
12356 @example
12357 #+source: 3D
12358 #+begin_src emacs-lisp
12359 '(((1 2 3) (4 5 6) (7 8 9))
12360 ((10 11 12) (13 14 15) (16 17 18))
12361 ((19 20 21) (22 23 24) (25 26 27)))
12362 #+end_src
12363
12364 #+begin_src emacs-lisp :var data=3D[1,,1]
12365 data
12366 #+end_src
12367
12368 #+results:
12369 | 11 | 14 | 17 |
12370 @end example
12371
12372 @subsubheading Emacs Lisp evaluation of variables
12373
12374 Emacs lisp code can be used to initialize variable values. When a variable
12375 value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be evaluated as
12376 Emacs Lisp and the result of the evaluation will be assigned as the variable
12377 value. The following example demonstrates use of this evaluation to reliably
12378 pass the file-name of the org-mode buffer to a code block---note that
12379 evaluation of header arguments is guaranteed to take place in the original
12380 org-mode file, while there is no such guarantee for evaluation of the code
12381 block body.
12382
12383 @example
12384 #+begin_src sh :var filename=(buffer-file-name) :exports both
12385 wc -w $filename
12386 #+end_src
12387 @end example
12388
12389 Note that values read from tables and lists will not be evaluated as
12390 Emacs Lisp, as shown in the following example.
12391
12392 @example
12393 #+results: table
12394 | (a b c) |
12395
12396 #+headers: :var data=table[0,0]
12397 #+begin_src perl
12398 $data
12399 #+end_src
12400
12401 #+results:
12402 : (a b c)
12403 @end example
12404
12405 @node results, file, var, Specific header arguments
12406 @subsubsection @code{:results}
12407
12408 There are three classes of @code{:results} header argument. Only one option
12409 per class may be supplied per code block.
12410
12411 @itemize @bullet
12412 @item
12413 @b{collection} header arguments specify how the results should be collected
12414 from the code block
12415 @item
12416 @b{type} header arguments specify what type of result the code block will
12417 return---which has implications for how they will be inserted into the
12418 Org-mode buffer
12419 @item
12420 @b{handling} header arguments specify how the results of evaluating the code
12421 block should be handled.
12422 @end itemize
12423
12424 @subsubheading Collection
12425 The following options are mutually exclusive, and specify how the results
12426 should be collected from the code block.
12427
12428 @itemize @bullet
12429 @item @code{value}
12430 This is the default. The result is the value of the last statement in the
12431 code block. This header argument places the evaluation in functional
12432 mode. Note that in some languages, e.g., Python, use of this result type
12433 requires that a @code{return} statement be included in the body of the source
12434 code block. E.g., @code{:results value}.
12435 @item @code{output}
12436 The result is the collection of everything printed to STDOUT during the
12437 execution of the code block. This header argument places the
12438 evaluation in scripting mode. E.g., @code{:results output}.
12439 @end itemize
12440
12441 @subsubheading Type
12442
12443 The following options are mutually exclusive and specify what type of results
12444 the code block will return. By default, results are inserted as either a
12445 table or scalar depending on their value.
12446
12447 @itemize @bullet
12448 @item @code{table}, @code{vector}
12449 The results should be interpreted as an Org-mode table. If a single value is
12450 returned, it will be converted into a table with one row and one column.
12451 E.g., @code{:results value table}.
12452 @item @code{list}
12453 The results should be interpreted as an Org-mode list. If a single scalar
12454 value is returned it will be converted into a list with only one element.
12455 @item @code{scalar}, @code{verbatim}
12456 The results should be interpreted literally---they will not be
12457 converted into a table. The results will be inserted into the Org-mode
12458 buffer as quoted text. E.g., @code{:results value verbatim}.
12459 @item @code{file}
12460 The results will be interpreted as the path to a file, and will be inserted
12461 into the Org-mode buffer as a file link. E.g., @code{:results value file}.
12462 @item @code{raw}, @code{org}
12463 The results are interpreted as raw Org-mode code and are inserted directly
12464 into the buffer. If the results look like a table they will be aligned as
12465 such by Org-mode. E.g., @code{:results value raw}.
12466 @item @code{html}
12467 Results are assumed to be HTML and will be enclosed in a @code{begin_html}
12468 block. E.g., @code{:results value html}.
12469 @item @code{latex}
12470 Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block.
12471 E.g., @code{:results value latex}.
12472 @item @code{code}
12473 Result are assumed to be parseable code and are enclosed in a code block.
12474 E.g., @code{:results value code}.
12475 @item @code{pp}
12476 The result is converted to pretty-printed code and is enclosed in a code
12477 block. This option currently supports Emacs Lisp, Python, and Ruby. E.g.,
12478 @code{:results value pp}.
12479 @item @code{wrap}
12480 The result is wrapped in a @code{begin_result} block. This can be useful for
12481 inserting @code{raw} or @code{org} syntax results in such a way that their
12482 extend is known and they can be automatically removed or replaced.
12483 @end itemize
12484
12485 @subsubheading Handling
12486 The following results options indicate what happens with the
12487 results once they are collected.
12488
12489 @itemize @bullet
12490 @item @code{silent}
12491 The results will be echoed in the minibuffer but will not be inserted into
12492 the Org-mode buffer. E.g., @code{:results output silent}.
12493 @item @code{replace}
12494 The default value. Any existing results will be removed, and the new results
12495 will be inserted into the Org-mode buffer in their place. E.g.,
12496 @code{:results output replace}.
12497 @item @code{append}
12498 If there are pre-existing results of the code block then the new results will
12499 be appended to the existing results. Otherwise the new results will be
12500 inserted as with @code{replace}.
12501 @item @code{prepend}
12502 If there are pre-existing results of the code block then the new results will
12503 be prepended to the existing results. Otherwise the new results will be
12504 inserted as with @code{replace}.
12505 @end itemize
12506
12507 @node file, dir, results, Specific header arguments
12508 @subsubsection @code{:file}
12509
12510 The header argument @code{:file} is used to specify an external file in which
12511 to save code block results. After code block evaluation an Org-mode style
12512 @code{[[file:]]} link (see @ref{Link format}) to the file will be inserted
12513 into the Org-mode buffer. Some languages including R, gnuplot, dot, and
12514 ditaa provide special handling of the @code{:file} header argument
12515 automatically wrapping the code block body in the boilerplate code required
12516 to save output to the specified file. This is often useful for saving
12517 graphical output of a code block to the specified file.
12518
12519 The argument to @code{:file} should be either a string specifying the path to
12520 a file, or a list of two strings in which case the first element of the list
12521 should be the path to a file and the second a description for the link.
12522
12523 @node dir, exports, file, Specific header arguments
12524 @subsubsection @code{:dir} and remote execution
12525
12526 While the @code{:file} header argument can be used to specify the path to the
12527 output file, @code{:dir} specifies the default directory during code block
12528 execution. If it is absent, then the directory associated with the current
12529 buffer is used. In other words, supplying @code{:dir path} temporarily has
12530 the same effect as changing the current directory with @kbd{M-x cd path}, and
12531 then not supplying @code{:dir}. Under the surface, @code{:dir} simply sets
12532 the value of the Emacs variable @code{default-directory}.
12533
12534 When using @code{:dir}, you should supply a relative path for file output
12535 (e.g.@: @code{:file myfile.jpg} or @code{:file results/myfile.jpg}) in which
12536 case that path will be interpreted relative to the default directory.
12537
12538 In other words, if you want your plot to go into a folder called @file{Work}
12539 in your home directory, you could use
12540
12541 @example
12542 #+begin_src R :file myplot.png :dir ~/Work
12543 matplot(matrix(rnorm(100), 10), type="l")
12544 #+end_src
12545 @end example
12546
12547 @subsubheading Remote execution
12548 A directory on a remote machine can be specified using tramp file syntax, in
12549 which case the code will be evaluated on the remote machine. An example is
12550
12551 @example
12552 #+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu:
12553 plot(1:10, main=system("hostname", intern=TRUE))
12554 #+end_src
12555 @end example
12556
12557 Text results will be returned to the local Org-mode buffer as usual, and file
12558 output will be created on the remote machine with relative paths interpreted
12559 relative to the remote directory. An Org-mode link to the remote file will be
12560 created.
12561
12562 So, in the above example a plot will be created on the remote machine,
12563 and a link of the following form will be inserted in the org buffer:
12564
12565 @example
12566 [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
12567 @end example
12568
12569 Most of this functionality follows immediately from the fact that @code{:dir}
12570 sets the value of the Emacs variable @code{default-directory}, thanks to
12571 tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to
12572 install tramp separately in order for these features to work correctly.
12573
12574 @subsubheading Further points
12575
12576 @itemize @bullet
12577 @item
12578 If @code{:dir} is used in conjunction with @code{:session}, although it will
12579 determine the starting directory for a new session as expected, no attempt is
12580 currently made to alter the directory associated with an existing session.
12581 @item
12582 @code{:dir} should typically not be used to create files during export with
12583 @code{:exports results} or @code{:exports both}. The reason is that, in order
12584 to retain portability of exported material between machines, during export
12585 links inserted into the buffer will *not* be expanded against @code{default
12586 directory}. Therefore, if @code{default-directory} is altered using
12587 @code{:dir}, it is probable that the file will be created in a location to
12588 which the link does not point.
12589 @end itemize
12590
12591 @node exports, tangle, dir, Specific header arguments
12592 @subsubsection @code{:exports}
12593
12594 The @code{:exports} header argument specifies what should be included in HTML
12595 or LaTeX exports of the Org-mode file.
12596
12597 @itemize @bullet
12598 @item @code{code}
12599 The default. The body of code is included into the exported file. E.g.,
12600 @code{:exports code}.
12601 @item @code{results}
12602 The result of evaluating the code is included in the exported file. E.g.,
12603 @code{:exports results}.
12604 @item @code{both}
12605 Both the code and results are included in the exported file. E.g.,
12606 @code{:exports both}.
12607 @item @code{none}
12608 Nothing is included in the exported file. E.g., @code{:exports none}.
12609 @end itemize
12610
12611 @node tangle, mkdirp, exports, Specific header arguments
12612 @subsubsection @code{:tangle}
12613
12614 The @code{:tangle} header argument specifies whether or not the code
12615 block should be included in tangled extraction of source code files.
12616
12617 @itemize @bullet
12618 @item @code{tangle}
12619 The code block is exported to a source code file named after the full path
12620 (including the directory) and file name (w/o extension) of the Org-mode file.
12621 E.g., @code{:tangle yes}.
12622 @item @code{no}
12623 The default. The code block is not exported to a source code file.
12624 E.g., @code{:tangle no}.
12625 @item other
12626 Any other string passed to the @code{:tangle} header argument is interpreted
12627 as a path (directory and file name relative to the directory of the Org-mode
12628 file) to which the block will be exported. E.g., @code{:tangle path}.
12629 @end itemize
12630
12631 @node mkdirp, comments, tangle, Specific header arguments
12632 @subsubsection @code{:mkdirp}
12633
12634 The @code{:mkdirp} header argument can be used to create parent directories
12635 of tangled files when missing. This can be set to @code{yes} to enable
12636 directory creation or to @code{no} to inhibit directory creation.
12637
12638 @node comments, padline, mkdirp, Specific header arguments
12639 @subsubsection @code{:comments}
12640 By default code blocks are tangled to source-code files without any insertion
12641 of comments beyond those which may already exist in the body of the code
12642 block. The @code{:comments} header argument can be set as follows to control
12643 the insertion of extra comments into the tangled code file.
12644
12645 @itemize @bullet
12646 @item @code{no}
12647 The default. No extra comments are inserted during tangling.
12648 @item @code{link}
12649 The code block is wrapped in comments which contain pointers back to the
12650 original Org file from which the code was tangled.
12651 @item @code{yes}
12652 A synonym for ``link'' to maintain backwards compatibility.
12653 @item @code{org}
12654 Include text from the org-mode file as a comment.
12655
12656 The text is picked from the leading context of the tangled code and is
12657 limited by the nearest headline or source block as the case may be.
12658 @item @code{both}
12659 Turns on both the ``link'' and ``org'' comment options.
12660 @item @code{noweb}
12661 Turns on the ``link'' comment option, and additionally wraps expanded noweb
12662 references in the code block body in link comments.
12663 @end itemize
12664
12665 @node padline, no-expand, comments, Specific header arguments
12666 @subsubsection @code{:padline}
12667 Control in insertion of padding lines around code block bodies in tangled
12668 code files. The default value is @code{yes} which results in insertion of
12669 newlines before and after each tangled code block. The following arguments
12670 are accepted.
12671
12672 @itemize @bullet
12673 @item @code{yes}
12674 Insert newlines before and after each code block body in tangled code files.
12675 @item @code{no}
12676 Do not insert any newline padding in tangled output.
12677 @end itemize
12678
12679 @node no-expand, session, padline, Specific header arguments
12680 @subsubsection @code{:no-expand}
12681
12682 By default, code blocks are expanded with @code{org-babel-expand-src-block}
12683 during tangling. This has the effect of assigning values to variables
12684 specified with @code{:var} (see @ref{var}), and of replacing ``noweb''
12685 references (see @ref{Noweb reference syntax}) with their targets. The
12686 @code{:no-expand} header argument can be used to turn off this behavior.
12687
12688 @node session, noweb, no-expand, Specific header arguments
12689 @subsubsection @code{:session}
12690
12691 The @code{:session} header argument starts a session for an interpreted
12692 language where state is preserved.
12693
12694 By default, a session is not started.
12695
12696 A string passed to the @code{:session} header argument will give the session
12697 a name. This makes it possible to run concurrent sessions for each
12698 interpreted language.
12699
12700 @node noweb, noweb-ref, session, Specific header arguments
12701 @subsubsection @code{:noweb}
12702
12703 The @code{:noweb} header argument controls expansion of ``noweb'' style (see
12704 @ref{Noweb reference syntax}) references in a code block. This header
12705 argument can have one of three values: @code{yes}, @code{no}, or @code{tangle}.
12706
12707 @itemize @bullet
12708 @item @code{yes}
12709 All ``noweb'' syntax references in the body of the code block will be
12710 expanded before the block is evaluated, tangled or exported.
12711 @item @code{no}
12712 The default. No ``noweb'' syntax specific action is taken on evaluating
12713 code blocks, However, noweb references will still be expanded during
12714 tangling.
12715 @item @code{tangle}
12716 All ``noweb'' syntax references in the body of the code block will be
12717 expanded before the block is tangled, however ``noweb'' references will not
12718 be expanded when the block is evaluated or exported.
12719 @end itemize
12720
12721 @subsubheading Noweb prefix lines
12722 Noweb insertions are now placed behind the line prefix of the
12723 @code{<<reference>>}.
12724 This behavior is illustrated in the following example. Because the
12725 @code{<<example>>} noweb reference appears behind the SQL comment syntax,
12726 each line of the expanded noweb reference will be commented.
12727
12728 This code block:
12729
12730 @example
12731 -- <<example>>
12732 @end example
12733
12734
12735 expands to:
12736
12737 @example
12738 -- this is the
12739 -- multi-line body of example
12740 @end example
12741
12742 Note that noweb replacement text that does not contain any newlines will not
12743 be affected by this change, so it is still possible to use inline noweb
12744 references.
12745
12746 @node noweb-ref, cache, noweb, Specific header arguments
12747 @subsubsection @code{:noweb-ref}
12748 When expanding ``noweb'' style references the bodies of all code block with
12749 @emph{either} a block name matching the reference name @emph{or} a
12750 @code{:noweb-ref} header argument matching the reference name will be
12751 concatenated together to form the replacement text.
12752
12753 By setting this header argument at the sub-tree or file level, simple code
12754 block concatenation may be achieved. For example, when tangling the
12755 following Org-mode file, the bodies of code blocks will be concatenated into
12756 the resulting pure code file.
12757
12758 @example
12759 #+begin_src sh :tangle yes :noweb yes :shebang #!/bin/sh
12760 <<fullest-disk>>
12761 #+end_src
12762 * the mount point of the fullest disk
12763 :PROPERTIES:
12764 :noweb-ref: fullest-disk
12765 :END:
12766
12767 ** query all mounted disks
12768 #+begin_src sh
12769 df \
12770 #+end_src
12771
12772 ** strip the header row
12773 #+begin_src sh
12774 |sed '1d' \
12775 #+end_src
12776
12777 ** sort by the percent full
12778 #+begin_src sh
12779 |awk '@{print $5 " " $6@}'|sort -n |tail -1 \
12780 #+end_src
12781
12782 ** extract the mount point
12783 #+begin_src sh
12784 |awk '@{print $2@}'
12785 #+end_src
12786 @end example
12787
12788 @node cache, sep, noweb-ref, Specific header arguments
12789 @subsubsection @code{:cache}
12790
12791 The @code{:cache} header argument controls the use of in-buffer caching of
12792 the results of evaluating code blocks. It can be used to avoid re-evaluating
12793 unchanged code blocks. This header argument can have one of two
12794 values: @code{yes} or @code{no}.
12795
12796 @itemize @bullet
12797 @item @code{no}
12798 The default. No caching takes place, and the code block will be evaluated
12799 every time it is called.
12800 @item @code{yes}
12801 Every time the code block is run a SHA1 hash of the code and arguments
12802 passed to the block will be generated. This hash is packed into the
12803 @code{#+results:} line and will be checked on subsequent
12804 executions of the code block. If the code block has not
12805 changed since the last time it was evaluated, it will not be re-evaluated.
12806 @end itemize
12807
12808 Code block caches notice if the value of a variable argument
12809 to the code block has changed. If this is the case, the cache is
12810 invalidated and the code block is re-run. In the following example,
12811 @code{caller} will not be re-run unless the results of @code{random} have
12812 changed since it was last run.
12813
12814 @example
12815 #+srcname: random
12816 #+begin_src R :cache yes
12817 runif(1)
12818 #+end_src
12819
12820 #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
12821 0.4659510825295
12822
12823 #+srcname: caller
12824 #+begin_src emacs-lisp :var x=random :cache yes
12825 x
12826 #+end_src
12827
12828 #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
12829 0.254227238707244
12830 @end example
12831
12832 @node sep, hlines, cache, Specific header arguments
12833 @subsubsection @code{:sep}
12834
12835 The @code{:sep} header argument can be used to control the delimiter used
12836 when writing tabular results out to files external to Org-mode. This is used
12837 either when opening tabular results of a code block by calling the
12838 @code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block,
12839 or when writing code block results to an external file (see @ref{file})
12840 header argument.
12841
12842 By default, when @code{:sep} is not specified output tables are tab
12843 delimited.
12844
12845 @node hlines, colnames, sep, Specific header arguments
12846 @subsubsection @code{:hlines}
12847
12848 Tables are frequently represented with one or more horizontal lines, or
12849 hlines. The @code{:hlines} argument to a code block accepts the
12850 values @code{yes} or @code{no}, with a default value of @code{no}.
12851
12852 @itemize @bullet
12853 @item @code{no}
12854 Strips horizontal lines from the input table. In most languages this is the
12855 desired effect because an @code{hline} symbol is interpreted as an unbound
12856 variable and raises an error. Setting @code{:hlines no} or relying on the
12857 default value yields the following results.
12858
12859 @example
12860 #+tblname: many-cols
12861 | a | b | c |
12862 |---+---+---|
12863 | d | e | f |
12864 |---+---+---|
12865 | g | h | i |
12866
12867 #+source: echo-table
12868 #+begin_src python :var tab=many-cols
12869 return tab
12870 #+end_src
12871
12872 #+results: echo-table
12873 | a | b | c |
12874 | d | e | f |
12875 | g | h | i |
12876 @end example
12877
12878 @item @code{yes}
12879 Leaves hlines in the table. Setting @code{:hlines yes} has this effect.
12880
12881 @example
12882 #+tblname: many-cols
12883 | a | b | c |
12884 |---+---+---|
12885 | d | e | f |
12886 |---+---+---|
12887 | g | h | i |
12888
12889 #+source: echo-table
12890 #+begin_src python :var tab=many-cols :hlines yes
12891 return tab
12892 #+end_src
12893
12894 #+results: echo-table
12895 | a | b | c |
12896 |---+---+---|
12897 | d | e | f |
12898 |---+---+---|
12899 | g | h | i |
12900 @end example
12901 @end itemize
12902
12903 @node colnames, rownames, hlines, Specific header arguments
12904 @subsubsection @code{:colnames}
12905
12906 The @code{:colnames} header argument accepts the values @code{yes},
12907 @code{no}, or @code{nil} for unassigned. The default value is @code{nil}.
12908
12909 @itemize @bullet
12910 @item @code{nil}
12911 If an input table looks like it has column names
12912 (because its second row is an hline), then the column
12913 names will be removed from the table before
12914 processing, then reapplied to the results.
12915
12916 @example
12917 #+tblname: less-cols
12918 | a |
12919 |---|
12920 | b |
12921 | c |
12922
12923 #+srcname: echo-table-again
12924 #+begin_src python :var tab=less-cols
12925 return [[val + '*' for val in row] for row in tab]
12926 #+end_src
12927
12928 #+results: echo-table-again
12929 | a |
12930 |----|
12931 | b* |
12932 | c* |
12933 @end example
12934
12935 Please note that column names are not removed before the table is indexed
12936 using variable indexing @xref{var, Indexable variable values}.
12937
12938 @item @code{no}
12939 No column name pre-processing takes place
12940
12941 @item @code{yes}
12942 Column names are removed and reapplied as with @code{nil} even if the table
12943 does not ``look like'' it has column names (i.e.@: the second row is not an
12944 hline)
12945 @end itemize
12946
12947 @node rownames, shebang, colnames, Specific header arguments
12948 @subsubsection @code{:rownames}
12949
12950 The @code{:rownames} header argument can take on the values @code{yes}
12951 or @code{no}, with a default value of @code{no}.
12952
12953 @itemize @bullet
12954 @item @code{no}
12955 No row name pre-processing will take place.
12956
12957 @item @code{yes}
12958 The first column of the table is removed from the table before processing,
12959 and is then reapplied to the results.
12960
12961 @example
12962 #+tblname: with-rownames
12963 | one | 1 | 2 | 3 | 4 | 5 |
12964 | two | 6 | 7 | 8 | 9 | 10 |
12965
12966 #+srcname: echo-table-once-again
12967 #+begin_src python :var tab=with-rownames :rownames yes
12968 return [[val + 10 for val in row] for row in tab]
12969 #+end_src
12970
12971 #+results: echo-table-once-again
12972 | one | 11 | 12 | 13 | 14 | 15 |
12973 | two | 16 | 17 | 18 | 19 | 20 |
12974 @end example
12975
12976 Please note that row names are not removed before the table is indexed using
12977 variable indexing @xref{var, Indexable variable values}.
12978
12979 @end itemize
12980
12981 @node shebang, eval, rownames, Specific header arguments
12982 @subsubsection @code{:shebang}
12983
12984 Setting the @code{:shebang} header argument to a string value
12985 (e.g.@: @code{:shebang "#!/bin/bash"}) causes the string to be inserted as the
12986 first line of any tangled file holding the code block, and the file
12987 permissions of the tangled file are set to make it executable.
12988
12989 @node eval, , shebang, Specific header arguments
12990 @subsubsection @code{:eval}
12991 The @code{:eval} header argument can be used to limit the evaluation of
12992 specific code blocks. @code{:eval} accepts two arguments ``never'' and
12993 ``query''. @code{:eval never} will ensure that a code block is never
12994 evaluated, this can be useful for protecting against the evaluation of
12995 dangerous code blocks. @code{:eval query} will require a query for every
12996 execution of a code block regardless of the value of the
12997 @code{org-confirm-babel-evaluate} variable.
12998
12999 If this header argument is not set then evaluation is determined by the value
13000 of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation
13001 security}.
13002
13003 @node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code
13004 @section Results of evaluation
13005 @cindex code block, results of evaluation
13006 @cindex source code, results of evaluation
13007
13008 The way in which results are handled depends on whether a session is invoked,
13009 as well as on whether @code{:results value} or @code{:results output} is
13010 used. The following table shows the table possibilities. For a full listing
13011 of the possible results header arguments see @ref{results}.
13012
13013 @multitable @columnfractions 0.26 0.33 0.41
13014 @item @tab @b{Non-session} @tab @b{Session}
13015 @item @code{:results value} @tab value of last expression @tab value of last expression
13016 @item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output
13017 @end multitable
13018
13019 Note: With @code{:results value}, the result in both @code{:session} and
13020 non-session is returned to Org-mode as a table (a one- or two-dimensional
13021 vector of strings or numbers) when appropriate.
13022
13023 @subsection Non-session
13024 @subsubsection @code{:results value}
13025 This is the default. Internally, the value is obtained by wrapping the code
13026 in a function definition in the external language, and evaluating that
13027 function. Therefore, code should be written as if it were the body of such a
13028 function. In particular, note that Python does not automatically return a
13029 value from a function unless a @code{return} statement is present, and so a
13030 @samp{return} statement will usually be required in Python.
13031
13032 This is the only one of the four evaluation contexts in which the code is
13033 automatically wrapped in a function definition.
13034
13035 @subsubsection @code{:results output}
13036 The code is passed to the interpreter as an external process, and the
13037 contents of the standard output stream are returned as text. (In certain
13038 languages this also contains the error output stream; this is an area for
13039 future work.)
13040
13041 @subsection Session
13042 @subsubsection @code{:results value}
13043 The code is passed to an interpreter running as an interactive Emacs inferior
13044 process. Only languages which provide tools for interactive evaluation of
13045 code have session support, so some language (e.g., C and ditaa) do not
13046 support the @code{:session} header argument, and in other languages (e.g.,
13047 Python and Haskell) which have limitations on the code which may be entered
13048 into interactive sessions, those limitations apply to the code in code blocks
13049 using the @code{:session} header argument as well.
13050
13051 Unless the @code{:results output} option is supplied (see below) the result
13052 returned is the result of the last evaluation performed by the
13053 interpreter. (This is obtained in a language-specific manner: the value of
13054 the variable @code{_} in Python and Ruby, and the value of @code{.Last.value}
13055 in R).
13056
13057 @subsubsection @code{:results output}
13058 The code is passed to the interpreter running as an interactive Emacs
13059 inferior process. The result returned is the concatenation of the sequence of
13060 (text) output from the interactive interpreter. Notice that this is not
13061 necessarily the same as what would be sent to @code{STDOUT} if the same code
13062 were passed to a non-interactive interpreter running as an external
13063 process. For example, compare the following two blocks:
13064
13065 @example
13066 #+begin_src python :results output
13067 print "hello"
13068 2
13069 print "bye"
13070 #+end_src
13071
13072 #+resname:
13073 : hello
13074 : bye
13075 @end example
13076
13077 In non-session mode, the `2' is not printed and does not appear.
13078 @example
13079 #+begin_src python :results output :session
13080 print "hello"
13081 2
13082 print "bye"
13083 #+end_src
13084
13085 #+resname:
13086 : hello
13087 : 2
13088 : bye
13089 @end example
13090
13091 But in @code{:session} mode, the interactive interpreter receives input `2'
13092 and prints out its value, `2'. (Indeed, the other print statements are
13093 unnecessary here).
13094
13095 @node Noweb reference syntax, Key bindings and useful functions, Results of evaluation, Working With Source Code
13096 @section Noweb reference syntax
13097 @cindex code block, noweb reference
13098 @cindex syntax, noweb
13099 @cindex source code, noweb reference
13100
13101 The ``noweb'' (see @uref{http://www.cs.tufts.edu/~nr/noweb/}) Literate
13102 Programming system allows named blocks of code to be referenced by using the
13103 familiar Noweb syntax:
13104
13105 @example
13106 <<code-block-name>>
13107 @end example
13108
13109 When a code block is tangled or evaluated, whether or not ``noweb''
13110 references are expanded depends upon the value of the @code{:noweb} header
13111 argument. If @code{:noweb yes}, then a Noweb reference is expanded before
13112 evaluation. If @code{:noweb no}, the default, then the reference is not
13113 expanded before evaluation.
13114
13115 Note: the default value, @code{:noweb no}, was chosen to ensure that
13116 correct code is not broken in a language, such as Ruby, where
13117 @code{<<arg>>} is a syntactically valid construct. If @code{<<arg>>} is not
13118 syntactically valid in languages that you use, then please consider setting
13119 the default value.
13120
13121 @node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code
13122 @section Key bindings and useful functions
13123 @cindex code block, key bindings
13124
13125 Many common Org-mode key sequences are re-bound depending on
13126 the context.
13127
13128 Within a code block, the following key bindings
13129 are active:
13130
13131 @multitable @columnfractions 0.25 0.75
13132 @kindex C-c C-c
13133 @item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block}
13134 @kindex C-c C-o
13135 @item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result}
13136 @kindex C-up
13137 @item @kbd{C-@key{up}} @tab @code{org-babel-load-in-session}
13138 @kindex M-down
13139 @item @kbd{M-@key{down}} @tab @code{org-babel-pop-to-session}
13140 @end multitable
13141
13142 In an Org-mode buffer, the following key bindings are active:
13143
13144 @multitable @columnfractions 0.45 0.55
13145 @kindex C-c C-v a
13146 @kindex C-c C-v C-a
13147 @item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
13148 @kindex C-c C-v b
13149 @kindex C-c C-v C-b
13150 @item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
13151 @kindex C-c C-v f
13152 @kindex C-c C-v C-f
13153 @item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
13154 @kindex C-c C-v g
13155 @item @kbd{C-c C-v g} @tab @code{org-babel-goto-named-source-block}
13156 @kindex C-c C-v h
13157 @item @kbd{C-c C-v h} @tab @code{org-babel-describe-bindings}
13158 @kindex C-c C-v l
13159 @kindex C-c C-v C-l
13160 @item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
13161 @kindex C-c C-v p
13162 @kindex C-c C-v C-p
13163 @item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
13164 @kindex C-c C-v s
13165 @kindex C-c C-v C-s
13166 @item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
13167 @kindex C-c C-v t
13168 @kindex C-c C-v C-t
13169 @item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
13170 @kindex C-c C-v z
13171 @kindex C-c C-v C-z
13172 @item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
13173 @end multitable
13174
13175 @c When possible these keybindings were extended to work when the control key is
13176 @c kept pressed, resulting in the following additional keybindings.
13177
13178 @c @multitable @columnfractions 0.25 0.75
13179 @c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
13180 @c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
13181 @c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
13182 @c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
13183 @c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
13184 @c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
13185 @c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
13186 @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
13187 @c @end multitable
13188
13189 @node Batch execution, , Key bindings and useful functions, Working With Source Code
13190 @section Batch execution
13191 @cindex code block, batch execution
13192 @cindex source code, batch execution
13193
13194 It is possible to call functions from the command line. This shell
13195 script calls @code{org-babel-tangle} on every one of its arguments.
13196
13197 Be sure to adjust the paths to fit your system.
13198
13199 @example
13200 #!/bin/sh
13201 # -*- mode: shell-script -*-
13202 #
13203 # tangle files with org-mode
13204 #
13205 DIR=`pwd`
13206 FILES=""
13207 ORGINSTALL="~/src/org/lisp/org-install.el"
13208
13209 # wrap each argument in the code required to call tangle on it
13210 for i in $@@; do
13211 FILES="$FILES \"$i\""
13212 done
13213
13214 emacs -Q --batch -l $ORGINSTALL \
13215 --eval "(progn
13216 (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
13217 (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\"))
13218 (require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
13219 (mapc (lambda (file)
13220 (find-file (expand-file-name file \"$DIR\"))
13221 (org-babel-tangle)
13222 (kill-buffer)) '($FILES)))" 2>&1 |grep tangled
13223 @end example
13224
13225 @node Miscellaneous, Hacking, Working With Source Code, Top
13226 @chapter Miscellaneous
13227
13228 @menu
13229 * Completion:: M-TAB knows what you need
13230 * Easy Templates:: Quick insertion of structural elements
13231 * Speed keys:: Electric commands at the beginning of a headline
13232 * Code evaluation security:: Org mode files evaluate inline code
13233 * Customization:: Adapting Org to your taste
13234 * In-buffer settings:: Overview of the #+KEYWORDS
13235 * The very busy C-c C-c key:: When in doubt, press C-c C-c
13236 * Clean view:: Getting rid of leading stars in the outline
13237 * TTY keys:: Using Org on a tty
13238 * Interaction:: Other Emacs packages
13239 * org-crypt.el:: Encrypting Org files
13240 @end menu
13241
13242
13243 @node Completion, Easy Templates, Miscellaneous, Miscellaneous
13244 @section Completion
13245 @cindex completion, of @TeX{} symbols
13246 @cindex completion, of TODO keywords
13247 @cindex completion, of dictionary words
13248 @cindex completion, of option keywords
13249 @cindex completion, of tags
13250 @cindex completion, of property keys
13251 @cindex completion, of link abbreviations
13252 @cindex @TeX{} symbol completion
13253 @cindex TODO keywords completion
13254 @cindex dictionary word completion
13255 @cindex option keyword completion
13256 @cindex tag completion
13257 @cindex link abbreviations, completion of
13258
13259 Emacs would not be Emacs without completion, and Org-mode uses it whenever it
13260 makes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface for
13261 some of the completion prompts, you can specify your preference by setting at
13262 most one of the variables @code{org-completion-use-iswitchb}
13263 @code{org-completion-use-ido}.
13264
13265 Org supports in-buffer completion. This type of completion does
13266 not make use of the minibuffer. You simply type a few letters into
13267 the buffer and use the key to complete text right there.
13268
13269 @table @kbd
13270 @kindex M-@key{TAB}
13271 @item M-@key{TAB}
13272 Complete word at point
13273 @itemize @bullet
13274 @item
13275 At the beginning of a headline, complete TODO keywords.
13276 @item
13277 After @samp{\}, complete @TeX{} symbols supported by the exporter.
13278 @item
13279 After @samp{*}, complete headlines in the current buffer so that they
13280 can be used in search links like @samp{[[*find this headline]]}.
13281 @item
13282 After @samp{:} in a headline, complete tags. The list of tags is taken
13283 from the variable @code{org-tag-alist} (possibly set through the
13284 @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
13285 dynamically from all tags used in the current buffer.
13286 @item
13287 After @samp{:} and not in a headline, complete property keys. The list
13288 of keys is constructed dynamically from all keys used in the current
13289 buffer.
13290 @item
13291 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
13292 @item
13293 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
13294 @samp{OPTIONS} which set file-specific options for Org-mode. When the
13295 option keyword is already complete, pressing @kbd{M-@key{TAB}} again
13296 will insert example settings for this keyword.
13297 @item
13298 In the line after @samp{#+STARTUP: }, complete startup keywords,
13299 i.e.@: valid keys for this line.
13300 @item
13301 Elsewhere, complete dictionary words using Ispell.
13302 @end itemize
13303 @end table
13304
13305 @node Easy Templates, Speed keys, Completion, Miscellaneous
13306 @section Easy Templates
13307 @cindex template insertion
13308 @cindex insertion, of templates
13309
13310 Org-mode supports insertion of empty structural elements (like
13311 @code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key
13312 strokes. This is achieved through a native template expansion mechanism.
13313 Note that Emacs has several other template mechanisms which could be used in
13314 a similar way, for example @file{yasnippet}.
13315
13316 To insert a structural element, type a @samp{<}, followed by a template
13317 selector and @kbd{@key{TAB}}. Completion takes effect only when the above
13318 keystrokes are typed on a line by itself.
13319
13320 The following template selectors are currently supported.
13321
13322 @multitable @columnfractions 0.1 0.9
13323 @item @kbd{s} @tab @code{#+begin_src ... #+end_src}
13324 @item @kbd{e} @tab @code{#+begin_example ... #+end_example}
13325 @item @kbd{q} @tab @code{#+begin_quote ... #+end_quote}
13326 @item @kbd{v} @tab @code{#+begin_verse ... #+end_verse}
13327 @item @kbd{c} @tab @code{#+begin_center ... #+end_center}
13328 @item @kbd{l} @tab @code{#+begin_latex ... #+end_latex}
13329 @item @kbd{L} @tab @code{#+latex:}
13330 @item @kbd{h} @tab @code{#+begin_html ... #+end_html}
13331 @item @kbd{H} @tab @code{#+html:}
13332 @item @kbd{a} @tab @code{#+begin_ascii ... #+end_ascii}
13333 @item @kbd{A} @tab @code{#+ascii:}
13334 @item @kbd{i} @tab @code{#+index:} line
13335 @item @kbd{I} @tab @code{#+include:} line
13336 @end multitable
13337
13338 For example, on an empty line, typing "<e" and then pressing TAB, will expand
13339 into a complete EXAMPLE template.
13340
13341 You can install additional templates by customizing the variable
13342 @code{org-structure-template-alist}. See the docstring of the variable for
13343 additional details.
13344
13345 @node Speed keys, Code evaluation security, Easy Templates, Miscellaneous
13346 @section Speed keys
13347 @cindex speed keys
13348 @vindex org-use-speed-commands
13349 @vindex org-speed-commands-user
13350
13351 Single keys can be made to execute commands when the cursor is at the
13352 beginning of a headline, i.e.@: before the first star. Configure the variable
13353 @code{org-use-speed-commands} to activate this feature. There is a
13354 pre-defined list of commands, and you can add more such commands using the
13355 variable @code{org-speed-commands-user}. Speed keys do not only speed up
13356 navigation and other commands, but they also provide an alternative way to
13357 execute commands bound to keys that are not or not easily available on a TTY,
13358 or on a small mobile device with a limited keyboard.
13359
13360 To see which commands are available, activate the feature and press @kbd{?}
13361 with the cursor at the beginning of a headline.
13362
13363 @node Code evaluation security, Customization, Speed keys, Miscellaneous
13364 @section Code evaluation and security issues
13365
13366 Org provides tools to work with the code snippets, including evaluating them.
13367
13368 Running code on your machine always comes with a security risk. Badly
13369 written or malicious code can be executed on purpose or by accident. Org has
13370 default settings which will only evaluate such code if you give explicit
13371 permission to do so, and as a casual user of these features you should leave
13372 these precautions intact.
13373
13374 For people who regularly work with such code, the confirmation prompts can
13375 become annoying, and you might want to turn them off. This can be done, but
13376 you must be aware of the risks that are involved.
13377
13378 Code evaluation can happen under the following circumstances:
13379
13380 @table @i
13381 @item Source code blocks
13382 Source code blocks can be evaluated during export, or when pressing @kbd{C-c
13383 C-c} in the block. The most important thing to realize here is that Org mode
13384 files which contain code snippets are, in a certain sense, like executable
13385 files. So you should accept them and load them into Emacs only from trusted
13386 sources---just like you would do with a program you install on your computer.
13387
13388 Make sure you know what you are doing before customizing the variables
13389 which take off the default security brakes.
13390
13391 @defopt org-confirm-babel-evaluate
13392 When t (the default), the user is asked before every code block evaluation.
13393 When nil, the user is not asked. When set to a function, it is called with
13394 two arguments (language and body of the code block) and should return t to
13395 ask and nil not to ask.
13396 @end defopt
13397
13398 For example, here is how to execute "ditaa" code (which is considered safe)
13399 without asking:
13400 @example
13401 (defun my-org-confirm-babel-evaluate (lang body)
13402 (not (string= lang "ditaa"))) ; don't ask for ditaa
13403 (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
13404 @end example
13405
13406 @item Following @code{shell} and @code{elisp} links
13407 Org has two link types that can directly evaluate code (@pxref{External
13408 links}). These links can be problematic because the code to be evaluated is
13409 not visible.
13410
13411 @defopt org-confirm-shell-link-function
13412 Function to queries user about shell link execution.
13413 @end defopt
13414 @defopt org-confirm-elisp-link-function
13415 Functions to query user for Emacs Lisp link execution.
13416 @end defopt
13417
13418 @item Formulas in tables
13419 Formulas in tables (@pxref{The spreadsheet}) are code that is evaluated
13420 either by the @i{calc} interpreter, or by the @i{Emacs Lisp} interpreter.
13421 @end table
13422
13423 @node Customization, In-buffer settings, Code evaluation security, Miscellaneous
13424 @section Customization
13425 @cindex customization
13426 @cindex options, for customization
13427 @cindex variables, for customization
13428
13429 There are more than 180 variables that can be used to customize
13430 Org. For the sake of compactness of the manual, I am not
13431 describing the variables here. A structured overview of customization
13432 variables is available with @kbd{M-x org-customize}. Or select
13433 @code{Browse Org Group} from the @code{Org->Customization} menu. Many
13434 settings can also be activated on a per-file basis, by putting special
13435 lines into the buffer (@pxref{In-buffer settings}).
13436
13437 @node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
13438 @section Summary of in-buffer settings
13439 @cindex in-buffer settings
13440 @cindex special keywords
13441
13442 Org-mode uses special lines in the buffer to define settings on a
13443 per-file basis. These lines start with a @samp{#+} followed by a
13444 keyword, a colon, and then individual words defining a setting. Several
13445 setting words can be in the same line, but you can also have multiple
13446 lines for the keyword. While these settings are described throughout
13447 the manual, here is a summary. After changing any of those lines in the
13448 buffer, press @kbd{C-c C-c} with the cursor still in the line to
13449 activate the changes immediately. Otherwise they become effective only
13450 when the file is visited again in a new Emacs session.
13451
13452 @vindex org-archive-location
13453 @table @kbd
13454 @item #+ARCHIVE: %s_done::
13455 This line sets the archive location for the agenda file. It applies for
13456 all subsequent lines until the next @samp{#+ARCHIVE} line, or the end
13457 of the file. The first such line also applies to any entries before it.
13458 The corresponding variable is @code{org-archive-location}.
13459 @item #+CATEGORY:
13460 This line sets the category for the agenda file. The category applies
13461 for all subsequent lines until the next @samp{#+CATEGORY} line, or the
13462 end of the file. The first such line also applies to any entries before it.
13463 @item #+COLUMNS: %25ITEM .....
13464 @cindex property, COLUMNS
13465 Set the default format for columns view. This format applies when
13466 columns view is invoked in locations where no @code{COLUMNS} property
13467 applies.
13468 @item #+CONSTANTS: name1=value1 ...
13469 @vindex org-table-formula-constants
13470 @vindex org-table-formula
13471 Set file-local values for constants to be used in table formulas. This
13472 line sets the local variable @code{org-table-formula-constants-local}.
13473 The global version of this variable is
13474 @code{org-table-formula-constants}.
13475 @item #+FILETAGS: :tag1:tag2:tag3:
13476 Set tags that can be inherited by any entry in the file, including the
13477 top-level entries.
13478 @item #+DRAWERS: NAME1 .....
13479 @vindex org-drawers
13480 Set the file-local set of drawers. The corresponding global variable is
13481 @code{org-drawers}.
13482 @item #+LINK: linkword replace
13483 @vindex org-link-abbrev-alist
13484 These lines (several are allowed) specify link abbreviations.
13485 @xref{Link abbreviations}. The corresponding variable is
13486 @code{org-link-abbrev-alist}.
13487 @item #+PRIORITIES: highest lowest default
13488 @vindex org-highest-priority
13489 @vindex org-lowest-priority
13490 @vindex org-default-priority
13491 This line sets the limits and the default for the priorities. All three
13492 must be either letters A-Z or numbers 0-9. The highest priority must
13493 have a lower ASCII number than the lowest priority.
13494 @item #+PROPERTY: Property_Name Value
13495 This line sets a default inheritance value for entries in the current
13496 buffer, most useful for specifying the allowed values of a property.
13497 @cindex #+SETUPFILE
13498 @item #+SETUPFILE: file
13499 This line defines a file that holds more in-buffer setup. Normally this is
13500 entirely ignored. Only when the buffer is parsed for option-setting lines
13501 (i.e.@: when starting Org-mode for a file, when pressing @kbd{C-c C-c} in a
13502 settings line, or when exporting), then the contents of this file are parsed
13503 as if they had been included in the buffer. In particular, the file can be
13504 any other Org-mode file with internal setup. You can visit the file the
13505 cursor is in the line with @kbd{C-c '}.
13506 @item #+STARTUP:
13507 @cindex #+STARTUP:
13508 This line sets options to be used at startup of Org-mode, when an
13509 Org file is being visited.
13510
13511 The first set of options deals with the initial visibility of the outline
13512 tree. The corresponding variable for global default settings is
13513 @code{org-startup-folded}, with a default value @code{t}, which means
13514 @code{overview}.
13515 @vindex org-startup-folded
13516 @cindex @code{overview}, STARTUP keyword
13517 @cindex @code{content}, STARTUP keyword
13518 @cindex @code{showall}, STARTUP keyword
13519 @cindex @code{showeverything}, STARTUP keyword
13520 @example
13521 overview @r{top-level headlines only}
13522 content @r{all headlines}
13523 showall @r{no folding of any entries}
13524 showeverything @r{show even drawer contents}
13525 @end example
13526
13527 @vindex org-startup-indented
13528 @cindex @code{indent}, STARTUP keyword
13529 @cindex @code{noindent}, STARTUP keyword
13530 Dynamic virtual indentation is controlled by the variable
13531 @code{org-startup-indented}@footnote{Emacs 23 and Org-mode 6.29 are required}
13532 @example
13533 indent @r{start with @code{org-indent-mode} turned on}
13534 noindent @r{start with @code{org-indent-mode} turned off}
13535 @end example
13536
13537 @vindex org-startup-align-all-tables
13538 Then there are options for aligning tables upon visiting a file. This
13539 is useful in files containing narrowed table columns. The corresponding
13540 variable is @code{org-startup-align-all-tables}, with a default value
13541 @code{nil}.
13542 @cindex @code{align}, STARTUP keyword
13543 @cindex @code{noalign}, STARTUP keyword
13544 @example
13545 align @r{align all tables}
13546 noalign @r{don't align tables on startup}
13547 @end example
13548
13549 @vindex org-startup-with-inline-images
13550 When visiting a file, inline images can be automatically displayed. The
13551 corresponding variable is @code{org-startup-with-inline-images}, with a
13552 default value @code{nil} to avoid delays when visiting a file.
13553 @cindex @code{inlineimages}, STARTUP keyword
13554 @cindex @code{noinlineimages}, STARTUP keyword
13555 @example
13556 inlineimages @r{show inline images}
13557 noinlineimages @r{don't show inline images on startup}
13558 @end example
13559
13560 @vindex org-log-done
13561 @vindex org-log-note-clock-out
13562 @vindex org-log-repeat
13563 Logging the closing and reopening of TODO items and clock intervals can be
13564 configured using these options (see variables @code{org-log-done},
13565 @code{org-log-note-clock-out} and @code{org-log-repeat})
13566 @cindex @code{logdone}, STARTUP keyword
13567 @cindex @code{lognotedone}, STARTUP keyword
13568 @cindex @code{nologdone}, STARTUP keyword
13569 @cindex @code{lognoteclock-out}, STARTUP keyword
13570 @cindex @code{nolognoteclock-out}, STARTUP keyword
13571 @cindex @code{logrepeat}, STARTUP keyword
13572 @cindex @code{lognoterepeat}, STARTUP keyword
13573 @cindex @code{nologrepeat}, STARTUP keyword
13574 @cindex @code{logreschedule}, STARTUP keyword
13575 @cindex @code{lognotereschedule}, STARTUP keyword
13576 @cindex @code{nologreschedule}, STARTUP keyword
13577 @cindex @code{logredeadline}, STARTUP keyword
13578 @cindex @code{lognoteredeadline}, STARTUP keyword
13579 @cindex @code{nologredeadline}, STARTUP keyword
13580 @cindex @code{logrefile}, STARTUP keyword
13581 @cindex @code{lognoterefile}, STARTUP keyword
13582 @cindex @code{nologrefile}, STARTUP keyword
13583 @example
13584 logdone @r{record a timestamp when an item is marked DONE}
13585 lognotedone @r{record timestamp and a note when DONE}
13586 nologdone @r{don't record when items are marked DONE}
13587 logrepeat @r{record a time when reinstating a repeating item}
13588 lognoterepeat @r{record a note when reinstating a repeating item}
13589 nologrepeat @r{do not record when reinstating repeating item}
13590 lognoteclock-out @r{record a note when clocking out}
13591 nolognoteclock-out @r{don't record a note when clocking out}
13592 logreschedule @r{record a timestamp when scheduling time changes}
13593 lognotereschedule @r{record a note when scheduling time changes}
13594 nologreschedule @r{do not record when a scheduling date changes}
13595 logredeadline @r{record a timestamp when deadline changes}
13596 lognoteredeadline @r{record a note when deadline changes}
13597 nologredeadline @r{do not record when a deadline date changes}
13598 logrefile @r{record a timestamp when refiling}
13599 lognoterefile @r{record a note when refiling}
13600 nologrefile @r{do not record when refiling}
13601 @end example
13602 @vindex org-hide-leading-stars
13603 @vindex org-odd-levels-only
13604 Here are the options for hiding leading stars in outline headings, and for
13605 indenting outlines. The corresponding variables are
13606 @code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a
13607 default setting @code{nil} (meaning @code{showstars} and @code{oddeven}).
13608 @cindex @code{hidestars}, STARTUP keyword
13609 @cindex @code{showstars}, STARTUP keyword
13610 @cindex @code{odd}, STARTUP keyword
13611 @cindex @code{even}, STARTUP keyword
13612 @example
13613 hidestars @r{make all but one of the stars starting a headline invisible.}
13614 showstars @r{show all stars starting a headline}
13615 indent @r{virtual indentation according to outline level}
13616 noindent @r{no virtual indentation according to outline level}
13617 odd @r{allow only odd outline levels (1,3,...)}
13618 oddeven @r{allow all outline levels}
13619 @end example
13620 @vindex org-put-time-stamp-overlays
13621 @vindex org-time-stamp-overlay-formats
13622 To turn on custom format overlays over timestamps (variables
13623 @code{org-put-time-stamp-overlays} and
13624 @code{org-time-stamp-overlay-formats}), use
13625 @cindex @code{customtime}, STARTUP keyword
13626 @example
13627 customtime @r{overlay custom time format}
13628 @end example
13629 @vindex constants-unit-system
13630 The following options influence the table spreadsheet (variable
13631 @code{constants-unit-system}).
13632 @cindex @code{constcgs}, STARTUP keyword
13633 @cindex @code{constSI}, STARTUP keyword
13634 @example
13635 constcgs @r{@file{constants.el} should use the c-g-s unit system}
13636 constSI @r{@file{constants.el} should use the SI unit system}
13637 @end example
13638 @vindex org-footnote-define-inline
13639 @vindex org-footnote-auto-label
13640 @vindex org-footnote-auto-adjust
13641 To influence footnote settings, use the following keywords. The
13642 corresponding variables are @code{org-footnote-define-inline},
13643 @code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.
13644 @cindex @code{fninline}, STARTUP keyword
13645 @cindex @code{nofninline}, STARTUP keyword
13646 @cindex @code{fnlocal}, STARTUP keyword
13647 @cindex @code{fnprompt}, STARTUP keyword
13648 @cindex @code{fnauto}, STARTUP keyword
13649 @cindex @code{fnconfirm}, STARTUP keyword
13650 @cindex @code{fnplain}, STARTUP keyword
13651 @cindex @code{fnadjust}, STARTUP keyword
13652 @cindex @code{nofnadjust}, STARTUP keyword
13653 @example
13654 fninline @r{define footnotes inline}
13655 fnnoinline @r{define footnotes in separate section}
13656 fnlocal @r{define footnotes near first reference, but not inline}
13657 fnprompt @r{prompt for footnote labels}
13658 fnauto @r{create @code{[fn:1]}-like labels automatically (default)}
13659 fnconfirm @r{offer automatic label for editing or confirmation}
13660 fnplain @r{create @code{[1]}-like labels automatically}
13661 fnadjust @r{automatically renumber and sort footnotes}
13662 nofnadjust @r{do not renumber and sort automatically}
13663 @end example
13664 @cindex org-hide-block-startup
13665 To hide blocks on startup, use these keywords. The corresponding variable is
13666 @code{org-hide-block-startup}.
13667 @cindex @code{hideblocks}, STARTUP keyword
13668 @cindex @code{nohideblocks}, STARTUP keyword
13669 @example
13670 hideblocks @r{Hide all begin/end blocks on startup}
13671 nohideblocks @r{Do not hide blocks on startup}
13672 @end example
13673 @cindex org-pretty-entities
13674 The display of entities as UTF-8 characters is governed by the variable
13675 @code{org-pretty-entities} and the keywords
13676 @cindex @code{entitiespretty}, STARTUP keyword
13677 @cindex @code{entitiesplain}, STARTUP keyword
13678 @example
13679 entitiespretty @r{Show entities as UTF-8 characters where possible}
13680 entitiesplain @r{Leave entities plain}
13681 @end example
13682 @item #+TAGS: TAG1(c1) TAG2(c2)
13683 @vindex org-tag-alist
13684 These lines (several such lines are allowed) specify the valid tags in
13685 this file, and (potentially) the corresponding @emph{fast tag selection}
13686 keys. The corresponding variable is @code{org-tag-alist}.
13687 @item #+TBLFM:
13688 This line contains the formulas for the table directly above the line.
13689 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,
13690 @itemx #+OPTIONS:, #+BIND:, #+XSLT:,
13691 @itemx #+DESCRIPTION:, #+KEYWORDS:,
13692 @itemx #+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,
13693 @itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:
13694 These lines provide settings for exporting files. For more details see
13695 @ref{Export options}.
13696 @item #+TODO: #+SEQ_TODO: #+TYP_TODO:
13697 @vindex org-todo-keywords
13698 These lines set the TODO keywords and their interpretation in the
13699 current file. The corresponding variable is @code{org-todo-keywords}.
13700 @end table
13701
13702 @node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
13703 @section The very busy C-c C-c key
13704 @kindex C-c C-c
13705 @cindex C-c C-c, overview
13706
13707 The key @kbd{C-c C-c} has many purposes in Org, which are all
13708 mentioned scattered throughout this manual. One specific function of
13709 this key is to add @emph{tags} to a headline (@pxref{Tags}). In many
13710 other circumstances it means something like @emph{``Hey Org, look
13711 here and update according to what you see here''}. Here is a summary of
13712 what this means in different contexts.
13713
13714 @itemize @minus
13715 @item
13716 If there are highlights in the buffer from the creation of a sparse
13717 tree, or from clock display, remove these highlights.
13718 @item
13719 If the cursor is in one of the special @code{#+KEYWORD} lines, this
13720 triggers scanning the buffer for these lines and updating the
13721 information.
13722 @item
13723 If the cursor is inside a table, realign the table. This command
13724 works even if the automatic table editor has been turned off.
13725 @item
13726 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
13727 the entire table.
13728 @item
13729 If the current buffer is a capture buffer, close the note and file it.
13730 With a prefix argument, file it, without further interaction, to the
13731 default location.
13732 @item
13733 If the cursor is on a @code{<<<target>>>}, update radio targets and
13734 corresponding links in this buffer.
13735 @item
13736 If the cursor is in a property line or at the start or end of a property
13737 drawer, offer property commands.
13738 @item
13739 If the cursor is at a footnote reference, go to the corresponding
13740 definition, and vice versa.
13741 @item
13742 If the cursor is on a statistics cookie, update it.
13743 @item
13744 If the cursor is in a plain list item with a checkbox, toggle the status
13745 of the checkbox.
13746 @item
13747 If the cursor is on a numbered item in a plain list, renumber the
13748 ordered list.
13749 @item
13750 If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
13751 block is updated.
13752 @end itemize
13753
13754 @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
13755 @section A cleaner outline view
13756 @cindex hiding leading stars
13757 @cindex dynamic indentation
13758 @cindex odd-levels-only outlines
13759 @cindex clean outline view
13760
13761 Some people find it noisy and distracting that the Org headlines start with a
13762 potentially large number of stars, and that text below the headlines is not
13763 indented. While this is no problem when writing a @emph{book-like} document
13764 where the outline headings are really section headings, in a more
13765 @emph{list-oriented} outline, indented structure is a lot cleaner:
13766
13767 @example
13768 @group
13769 * Top level headline | * Top level headline
13770 ** Second level | * Second level
13771 *** 3rd level | * 3rd level
13772 some text | some text
13773 *** 3rd level | * 3rd level
13774 more text | more text
13775 * Another top level headline | * Another top level headline
13776 @end group
13777 @end example
13778
13779 @noindent
13780
13781 If you are using at least Emacs 23.2@footnote{Emacs 23.1 can actually crash
13782 with @code{org-indent-mode}} and version 6.29 of Org, this kind of view can
13783 be achieved dynamically at display time using @code{org-indent-mode}. In
13784 this minor mode, all lines are prefixed for display with the necessary amount
13785 of space@footnote{@code{org-indent-mode} also sets the @code{wrap-prefix}
13786 property, such that @code{visual-line-mode} (or purely setting
13787 @code{word-wrap}) wraps long lines (including headlines) correctly indented.
13788 }. Also headlines are prefixed with additional stars, so that the amount of
13789 indentation shifts by two@footnote{See the variable
13790 @code{org-indent-indentation-per-level}.} spaces per level. All headline
13791 stars but the last one are made invisible using the @code{org-hide}
13792 face@footnote{Turning on @code{org-indent-mode} sets
13793 @code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
13794 @code{nil}.} - see below under @samp{2.} for more information on how this
13795 works. You can turn on @code{org-indent-mode} for all files by customizing
13796 the variable @code{org-startup-indented}, or you can turn it on for
13797 individual files using
13798
13799 @example
13800 #+STARTUP: indent
13801 @end example
13802
13803 If you want a similar effect in an earlier version of Emacs and/or Org, or if
13804 you want the indentation to be hard space characters so that the plain text
13805 file looks as similar as possible to the Emacs display, Org supports you in
13806 the following way:
13807
13808 @enumerate
13809 @item
13810 @emph{Indentation of text below headlines}@*
13811 You may indent text below each headline to make the left boundary line up
13812 with the headline, like
13813
13814 @example
13815 *** 3rd level
13816 more text, now indented
13817 @end example
13818
13819 @vindex org-adapt-indentation
13820 Org supports this with paragraph filling, line wrapping, and structure
13821 editing@footnote{See also the variable @code{org-adapt-indentation}.},
13822 preserving or adapting the indentation as appropriate.
13823
13824 @item
13825 @vindex org-hide-leading-stars
13826 @emph{Hiding leading stars}@* You can modify the display in such a way that
13827 all leading stars become invisible. To do this in a global way, configure
13828 the variable @code{org-hide-leading-stars} or change this on a per-file basis
13829 with
13830
13831 @example
13832 #+STARTUP: hidestars
13833 #+STARTUP: showstars
13834 @end example
13835
13836 With hidden stars, the tree becomes:
13837
13838 @example
13839 @group
13840 * Top level headline
13841 * Second level
13842 * 3rd level
13843 ...
13844 @end group
13845 @end example
13846
13847 @noindent
13848 @vindex org-hide @r{(face)}
13849 The leading stars are not truly replaced by whitespace, they are only
13850 fontified with the face @code{org-hide} that uses the background color as
13851 font color. If you are not using either white or black background, you may
13852 have to customize this face to get the wanted effect. Another possibility is
13853 to set this font such that the extra stars are @i{almost} invisible, for
13854 example using the color @code{grey90} on a white background.
13855
13856 @item
13857 @vindex org-odd-levels-only
13858 Things become cleaner still if you skip all the even levels and use only odd
13859 levels 1, 3, 5..., effectively adding two stars to go from one outline level
13860 to the next@footnote{When you need to specify a level for a property search
13861 or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc@.}. In this
13862 way we get the outline view shown at the beginning of this section. In order
13863 to make the structure editing and export commands handle this convention
13864 correctly, configure the variable @code{org-odd-levels-only}, or set this on
13865 a per-file basis with one of the following lines:
13866
13867 @example
13868 #+STARTUP: odd
13869 #+STARTUP: oddeven
13870 @end example
13871
13872 You can convert an Org file from single-star-per-level to the
13873 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
13874 RET} in that file. The reverse operation is @kbd{M-x
13875 org-convert-to-oddeven-levels}.
13876 @end enumerate
13877
13878 @node TTY keys, Interaction, Clean view, Miscellaneous
13879 @section Using Org on a tty
13880 @cindex tty key bindings
13881
13882 Because Org contains a large number of commands, by default many of
13883 Org's core commands are bound to keys that are generally not
13884 accessible on a tty, such as the cursor keys (@key{left}, @key{right},
13885 @key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used
13886 together with modifiers like @key{Meta} and/or @key{Shift}. To access
13887 these commands on a tty when special keys are unavailable, the following
13888 alternative bindings can be used. The tty bindings below will likely be
13889 more cumbersome; you may find for some of the bindings below that a
13890 customized workaround suits you better. For example, changing a timestamp
13891 is really only fun with @kbd{S-@key{cursor}} keys, whereas on a
13892 tty you would rather use @kbd{C-c .} to re-insert the timestamp.
13893
13894 @multitable @columnfractions 0.15 0.2 0.1 0.2
13895 @item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
13896 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab
13897 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
13898 @item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab
13899 @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
13900 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab
13901 @item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
13902 @item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab
13903 @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
13904 @item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab
13905 @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab
13906 @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
13907 @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab
13908 @item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab
13909 @item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab
13910 @item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab
13911 @item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab
13912 @item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab
13913 @item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab
13914 @end multitable
13915
13916
13917 @node Interaction, org-crypt.el, TTY keys, Miscellaneous
13918 @section Interaction with other packages
13919 @cindex packages, interaction with other
13920 Org lives in the world of GNU Emacs and interacts in various ways
13921 with other code out there.
13922
13923 @menu
13924 * Cooperation:: Packages Org cooperates with
13925 * Conflicts:: Packages that lead to conflicts
13926 @end menu
13927
13928 @node Cooperation, Conflicts, Interaction, Interaction
13929 @subsection Packages that Org cooperates with
13930
13931 @table @asis
13932 @cindex @file{calc.el}
13933 @cindex Gillespie, Dave
13934 @item @file{calc.el} by Dave Gillespie
13935 Org uses the Calc package for implementing spreadsheet
13936 functionality in its tables (@pxref{The spreadsheet}). Org
13937 checks for the availability of Calc by looking for the function
13938 @code{calc-eval} which will have been autoloaded during setup if Calc has
13939 been installed properly. As of Emacs 22, Calc is part of the Emacs
13940 distribution. Another possibility for interaction between the two
13941 packages is using Calc for embedded calculations. @xref{Embedded Mode,
13942 , Embedded Mode, Calc, GNU Emacs Calc Manual}.
13943 @item @file{constants.el} by Carsten Dominik
13944 @cindex @file{constants.el}
13945 @cindex Dominik, Carsten
13946 @vindex org-table-formula-constants
13947 In a table formula (@pxref{The spreadsheet}), it is possible to use
13948 names for natural constants or units. Instead of defining your own
13949 constants in the variable @code{org-table-formula-constants}, install
13950 the @file{constants} package which defines a large number of constants
13951 and units, and lets you use unit prefixes like @samp{M} for
13952 @samp{Mega}, etc@. You will need version 2.0 of this package, available
13953 at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for
13954 the function @code{constants-get}, which has to be autoloaded in your
13955 setup. See the installation instructions in the file
13956 @file{constants.el}.
13957 @item @file{cdlatex.el} by Carsten Dominik
13958 @cindex @file{cdlatex.el}
13959 @cindex Dominik, Carsten
13960 Org-mode can make use of the CDLa@TeX{} package to efficiently enter
13961 @LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}.
13962 @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
13963 @cindex @file{imenu.el}
13964 Imenu allows menu access to an index of items in a file. Org-mode
13965 supports Imenu---all you need to do to get the index is the following:
13966 @lisp
13967 (add-hook 'org-mode-hook
13968 (lambda () (imenu-add-to-menubar "Imenu")))
13969 @end lisp
13970 @vindex org-imenu-depth
13971 By default the index is two levels deep---you can modify the depth using
13972 the option @code{org-imenu-depth}.
13973 @item @file{remember.el} by John Wiegley
13974 @cindex @file{remember.el}
13975 @cindex Wiegley, John
13976 Org used to use this package for capture, but no longer does.
13977 @item @file{speedbar.el} by Eric M. Ludlam
13978 @cindex @file{speedbar.el}
13979 @cindex Ludlam, Eric M.
13980 Speedbar is a package that creates a special frame displaying files and
13981 index items in files. Org-mode supports Speedbar and allows you to
13982 drill into Org files directly from the Speedbar. It also allows you to
13983 restrict the scope of agenda commands to a file or a subtree by using
13984 the command @kbd{<} in the Speedbar frame.
13985 @cindex @file{table.el}
13986 @item @file{table.el} by Takaaki Ota
13987 @kindex C-c C-c
13988 @cindex table editor, @file{table.el}
13989 @cindex @file{table.el}
13990 @cindex Ota, Takaaki
13991
13992 Complex ASCII tables with automatic line wrapping, column- and row-spanning,
13993 and alignment can be created using the Emacs table package by Takaaki Ota
13994 (@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22).
13995 Org-mode will recognize these tables and export them properly. Because of
13996 interference with other Org-mode functionality, you unfortunately cannot edit
13997 these tables directly in the buffer. Instead, you need to use the command
13998 @kbd{C-c '} to edit them, similar to source code snippets.
13999
14000 @table @kbd
14001 @orgcmd{C-c ',org-edit-special}
14002 Edit a @file{table.el} table. Works when the cursor is in a table.el table.
14003 @c
14004 @orgcmd{C-c ~,org-table-create-with-table.el}
14005 Insert a @file{table.el} table. If there is already a table at point, this
14006 command converts it between the @file{table.el} format and the Org-mode
14007 format. See the documentation string of the command
14008 @code{org-convert-table} for the restrictions under which this is
14009 possible.
14010 @end table
14011 @file{table.el} is part of Emacs since Emacs 22.
14012 @item @file{footnote.el} by Steven L. Baur
14013 @cindex @file{footnote.el}
14014 @cindex Baur, Steven L.
14015 Org-mode recognizes numerical footnotes as provided by this package.
14016 However, Org-mode also has its own footnote support (@pxref{Footnotes}),
14017 which makes using @file{footnote.el} unnecessary.
14018 @end table
14019
14020 @node Conflicts, , Cooperation, Interaction
14021 @subsection Packages that lead to conflicts with Org-mode
14022
14023 @table @asis
14024
14025 @cindex @code{shift-selection-mode}
14026 @vindex org-support-shift-select
14027 In Emacs 23, @code{shift-selection-mode} is on by default, meaning that
14028 cursor motions combined with the shift key should start or enlarge regions.
14029 This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change
14030 timestamps, TODO keywords, priorities, and item bullet types if the cursor is
14031 at such a location. By default, @kbd{S-@key{cursor}} commands outside
14032 special contexts don't do anything, but you can customize the variable
14033 @code{org-support-shift-select}. Org-mode then tries to accommodate shift
14034 selection by (i) using it outside of the special contexts where special
14035 commands apply, and by (ii) extending an existing active region even if the
14036 cursor moves across a special context.
14037
14038 @item @file{CUA.el} by Kim. F. Storm
14039 @cindex @file{CUA.el}
14040 @cindex Storm, Kim. F.
14041 @vindex org-replace-disputed-keys
14042 Key bindings in Org conflict with the @kbd{S-<cursor>} keys used by CUA mode
14043 (as well as @code{pc-select-mode} and @code{s-region-mode}) to select and extend the
14044 region. In fact, Emacs 23 has this built-in in the form of
14045 @code{shift-selection-mode}, see previous paragraph. If you are using Emacs
14046 23, you probably don't want to use another package for this purpose. However,
14047 if you prefer to leave these keys to a different package while working in
14048 Org-mode, configure the variable @code{org-replace-disputed-keys}. When set,
14049 Org will move the following key bindings in Org files, and in the agenda
14050 buffer (but not during date selection).
14051
14052 @example
14053 S-UP @result{} M-p S-DOWN @result{} M-n
14054 S-LEFT @result{} M-- S-RIGHT @result{} M-+
14055 C-S-LEFT @result{} M-S-- C-S-RIGHT @result{} M-S-+
14056 @end example
14057
14058 @vindex org-disputed-keys
14059 Yes, these are unfortunately more difficult to remember. If you want
14060 to have other replacement keys, look at the variable
14061 @code{org-disputed-keys}.
14062
14063 @item @file{yasnippet.el}
14064 @cindex @file{yasnippet.el}
14065 The way Org mode binds the TAB key (binding to @code{[tab]} instead of
14066 @code{"\t"}) overrules YASnippet's access to this key. The following code
14067 fixed this problem:
14068
14069 @lisp
14070 (add-hook 'org-mode-hook
14071 (lambda ()
14072 (org-set-local 'yas/trigger-key [tab])
14073 (define-key yas/keymap [tab] 'yas/next-field-group)))
14074 @end lisp
14075
14076 The latest version of yasnippet doesn't play well with Org mode. If the
14077 above code does not fix the conflict, start by defining the following
14078 function:
14079
14080 @lisp
14081 (defun yas/org-very-safe-expand ()
14082 (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
14083 @end lisp
14084
14085 Then, tell Org mode what to do with the new function:
14086
14087 @lisp
14088 (add-hook 'org-mode-hook
14089 (lambda ()
14090 (make-variable-buffer-local 'yas/trigger-key)
14091 (setq yas/trigger-key [tab])
14092 (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
14093 (define-key yas/keymap [tab] 'yas/next-field)))
14094 @end lisp
14095
14096 @item @file{windmove.el} by Hovav Shacham
14097 @cindex @file{windmove.el}
14098 This package also uses the @kbd{S-<cursor>} keys, so everything written
14099 in the paragraph above about CUA mode also applies here. If you want make
14100 the windmove function active in locations where Org-mode does not have
14101 special functionality on @kbd{S-@key{cursor}}, add this to your
14102 configuration:
14103
14104 @lisp
14105 ;; Make windmove work in org-mode:
14106 (add-hook 'org-shiftup-final-hook 'windmove-up)
14107 (add-hook 'org-shiftleft-final-hook 'windmove-left)
14108 (add-hook 'org-shiftdown-final-hook 'windmove-down)
14109 (add-hook 'org-shiftright-final-hook 'windmove-right)
14110 @end lisp
14111
14112 @item @file{viper.el} by Michael Kifer
14113 @cindex @file{viper.el}
14114 @kindex C-c /
14115 Viper uses @kbd{C-c /} and therefore makes this key not access the
14116 corresponding Org-mode command @code{org-sparse-tree}. You need to find
14117 another key for this command, or override the key in
14118 @code{viper-vi-global-user-map} with
14119
14120 @lisp
14121 (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
14122 @end lisp
14123
14124 @end table
14125
14126 @node org-crypt.el, , Interaction, Miscellaneous
14127 @section org-crypt.el
14128 @cindex @file{org-crypt.el}
14129 @cindex @code{org-decrypt-entry}
14130
14131 Org-crypt will encrypt the text of an entry, but not the headline, or
14132 properties. Org-crypt uses the Emacs EasyPG library to encrypt and decrypt
14133 files.
14134
14135 Any text below a headline that has a @samp{:crypt:} tag will be automatically
14136 be encrypted when the file is saved. If you want to use a different tag just
14137 customize the @code{org-crypt-tag-matcher} setting.
14138
14139 To use org-crypt it is suggested that you have the following in your
14140 @file{.emacs}:
14141
14142 @example
14143 (require 'org-crypt)
14144 (org-crypt-use-before-save-magic)
14145 (setq org-tags-exclude-from-inheritance (quote ("crypt")))
14146
14147 (setq org-crypt-key nil)
14148 ;; GPG key to use for encryption
14149 ;; Either the Key ID or set to nil to use symmetric encryption.
14150
14151 (setq auto-save-default nil)
14152 ;; Auto-saving does not cooperate with org-crypt.el: so you need
14153 ;; to turn it off if you plan to use org-crypt.el quite often.
14154 ;; Otherwise, you'll get an (annoying) message each time you
14155 ;; start Org.
14156
14157 ;; To turn it off only locally, you can insert this:
14158 ;;
14159 ;; # -*- buffer-auto-save-file-name: nil; -*-
14160 @end example
14161
14162 Excluding the crypt tag from inheritance prevents already encrypted text
14163 being encrypted again.
14164
14165 @node Hacking, MobileOrg, Miscellaneous, Top
14166 @appendix Hacking
14167 @cindex hacking
14168
14169 This appendix covers some aspects where users can extend the functionality of
14170 Org.
14171
14172 @menu
14173 * Hooks:: Who to reach into Org's internals
14174 * Add-on packages:: Available extensions
14175 * Adding hyperlink types:: New custom link types
14176 * Context-sensitive commands:: How to add functionality to such commands
14177 * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
14178 * Dynamic blocks:: Automatically filled blocks
14179 * Special agenda views:: Customized views
14180 * Extracting agenda information:: Postprocessing of agenda information
14181 * Using the property API:: Writing programs that use entry properties
14182 * Using the mapping API:: Mapping over all or selected entries
14183 @end menu
14184
14185 @node Hooks, Add-on packages, Hacking, Hacking
14186 @section Hooks
14187 @cindex hooks
14188
14189 Org has a large number of hook variables that can be used to add
14190 functionality. This appendix about hacking is going to illustrate the
14191 use of some of them. A complete list of all hooks with documentation is
14192 maintained by the Worg project and can be found at
14193 @uref{http://orgmode.org/worg/org-configs/org-hooks.php}.
14194
14195 @node Add-on packages, Adding hyperlink types, Hooks, Hacking
14196 @section Add-on packages
14197 @cindex add-on packages
14198
14199 A large number of add-on packages have been written by various authors.
14200 These packages are not part of Emacs, but they are distributed as contributed
14201 packages with the separate release available at the Org-mode home page at
14202 @uref{http://orgmode.org}. The list of contributed packages, along with
14203 documentation about each package, is maintained by the Worg project at
14204 @uref{http://orgmode.org/worg/org-contrib/}.
14205
14206
14207
14208 @node Adding hyperlink types, Context-sensitive commands, Add-on packages, Hacking
14209 @section Adding hyperlink types
14210 @cindex hyperlinks, adding new types
14211
14212 Org has a large number of hyperlink types built-in
14213 (@pxref{Hyperlinks}). If you would like to add new link types, Org
14214 provides an interface for doing so. Let's look at an example file,
14215 @file{org-man.el}, that will add support for creating links like
14216 @samp{[[man:printf][The printf manpage]]} to show Unix manual pages inside
14217 Emacs:
14218
14219 @lisp
14220 ;;; org-man.el - Support for links to manpages in Org
14221
14222 (require 'org)
14223
14224 (org-add-link-type "man" 'org-man-open)
14225 (add-hook 'org-store-link-functions 'org-man-store-link)
14226
14227 (defcustom org-man-command 'man
14228 "The Emacs command to be used to display a man page."
14229 :group 'org-link
14230 :type '(choice (const man) (const woman)))
14231
14232 (defun org-man-open (path)
14233 "Visit the manpage on PATH.
14234 PATH should be a topic that can be thrown at the man command."
14235 (funcall org-man-command path))
14236
14237 (defun org-man-store-link ()
14238 "Store a link to a manpage."
14239 (when (memq major-mode '(Man-mode woman-mode))
14240 ;; This is a man page, we do make this link
14241 (let* ((page (org-man-get-page-name))
14242 (link (concat "man:" page))
14243 (description (format "Manpage for %s" page)))
14244 (org-store-link-props
14245 :type "man"
14246 :link link
14247 :description description))))
14248
14249 (defun org-man-get-page-name ()
14250 "Extract the page name from the buffer name."
14251 ;; This works for both `Man-mode' and `woman-mode'.
14252 (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
14253 (match-string 1 (buffer-name))
14254 (error "Cannot create link to this man page")))
14255
14256 (provide 'org-man)
14257
14258 ;;; org-man.el ends here
14259 @end lisp
14260
14261 @noindent
14262 You would activate this new link type in @file{.emacs} with
14263
14264 @lisp
14265 (require 'org-man)
14266 @end lisp
14267
14268 @noindent
14269 Let's go through the file and see what it does.
14270 @enumerate
14271 @item
14272 It does @code{(require 'org)} to make sure that @file{org.el} has been
14273 loaded.
14274 @item
14275 The next line calls @code{org-add-link-type} to define a new link type
14276 with prefix @samp{man}. The call also contains the name of a function
14277 that will be called to follow such a link.
14278 @item
14279 @vindex org-store-link-functions
14280 The next line adds a function to @code{org-store-link-functions}, in
14281 order to allow the command @kbd{C-c l} to record a useful link in a
14282 buffer displaying a man page.
14283 @end enumerate
14284
14285 The rest of the file defines the necessary variables and functions.
14286 First there is a customization variable that determines which Emacs
14287 command should be used to display man pages. There are two options,
14288 @code{man} and @code{woman}. Then the function to follow a link is
14289 defined. It gets the link path as an argument---in this case the link
14290 path is just a topic for the manual command. The function calls the
14291 value of @code{org-man-command} to display the man page.
14292
14293 Finally the function @code{org-man-store-link} is defined. When you try
14294 to store a link with @kbd{C-c l}, this function will be called to
14295 try to make a link. The function must first decide if it is supposed to
14296 create the link for this buffer type; we do this by checking the value
14297 of the variable @code{major-mode}. If not, the function must exit and
14298 return the value @code{nil}. If yes, the link is created by getting the
14299 manual topic from the buffer name and prefixing it with the string
14300 @samp{man:}. Then it must call the command @code{org-store-link-props}
14301 and set the @code{:type} and @code{:link} properties. Optionally you
14302 can also set the @code{:description} property to provide a default for
14303 the link description when the link is later inserted into an Org
14304 buffer with @kbd{C-c C-l}.
14305
14306 When it makes sense for your new link type, you may also define a function
14307 @code{org-PREFIX-complete-link} that implements special (e.g.@: completion)
14308 support for inserting such a link with @kbd{C-c C-l}. Such a function should
14309 not accept any arguments, and return the full link with prefix.
14310
14311 @node Context-sensitive commands, Tables in arbitrary syntax, Adding hyperlink types, Hacking
14312 @section Context-sensitive commands
14313 @cindex context-sensitive commands, hooks
14314 @cindex add-ons, context-sensitive commands
14315 @vindex org-ctrl-c-ctrl-c-hook
14316
14317 Org has several commands that act differently depending on context. The most
14318 important example it the @kbd{C-c C-c} (@pxref{The very busy C-c C-c key}).
14319 Also the @kbd{M-cursor} and @kbd{M-S-cursor} keys have this property.
14320
14321 Add-ons can tap into this functionality by providing a function that detects
14322 special context for that add-on and executes functionality appropriate for
14323 the context. Here is an example from Dan Davison's @file{org-R.el} which
14324 allows you to evaluate commands based on the @file{R} programming language
14325 @footnote{@file{org-R.el} has been replaced by the org-mode functionality
14326 described in @ref{Working With Source Code} and is now obsolete.}. For this
14327 package, special contexts are lines that start with @code{#+R:} or
14328 @code{#+RR:}.
14329
14330 @lisp
14331 (defun org-R-apply-maybe ()
14332 "Detect if this is context for org-R and execute R commands."
14333 (if (save-excursion
14334 (beginning-of-line 1)
14335 (looking-at "#\\+RR?:"))
14336 (progn (call-interactively 'org-R-apply)
14337 t) ;; to signal that we took action
14338 nil)) ;; to signal that we did not
14339
14340 (add-hook 'org-ctrl-c-ctrl-c-hook 'org-R-apply-maybe)
14341 @end lisp
14342
14343 The function first checks if the cursor is in such a line. If that is the
14344 case, @code{org-R-apply} is called and the function returns @code{t} to
14345 signal that action was taken, and @kbd{C-c C-c} will stop looking for other
14346 contexts. If the function finds it should do nothing locally, it returns
14347 @code{nil} so that other, similar functions can have a try.
14348
14349
14350 @node Tables in arbitrary syntax, Dynamic blocks, Context-sensitive commands, Hacking
14351 @section Tables and lists in arbitrary syntax
14352 @cindex tables, in other modes
14353 @cindex lists, in other modes
14354 @cindex Orgtbl mode
14355
14356 Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a
14357 frequent feature request has been to make it work with native tables in
14358 specific languages, for example @LaTeX{}. However, this is extremely
14359 hard to do in a general way, would lead to a customization nightmare,
14360 and would take away much of the simplicity of the Orgtbl mode table
14361 editor.
14362
14363 This appendix describes a different approach. We keep the Orgtbl mode
14364 table in its native format (the @i{source table}), and use a custom
14365 function to @i{translate} the table to the correct syntax, and to
14366 @i{install} it in the right location (the @i{target table}). This puts
14367 the burden of writing conversion functions on the user, but it allows
14368 for a very flexible system.
14369
14370 Bastien added the ability to do the same with lists, in Orgstruct mode. You
14371 can use Org's facilities to edit and structure lists by turning
14372 @code{orgstruct-mode} on, then locally exporting such lists in another format
14373 (HTML, @LaTeX{} or Texinfo.)
14374
14375
14376 @menu
14377 * Radio tables:: Sending and receiving radio tables
14378 * A LaTeX example:: Step by step, almost a tutorial
14379 * Translator functions:: Copy and modify
14380 * Radio lists:: Doing the same for lists
14381 @end menu
14382
14383 @node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax
14384 @subsection Radio tables
14385 @cindex radio tables
14386
14387 To define the location of the target table, you first need to create two
14388 lines that are comments in the current mode, but contain magic words for
14389 Orgtbl mode to find. Orgtbl mode will insert the translated table
14390 between these lines, replacing whatever was there before. For example:
14391
14392 @example
14393 /* BEGIN RECEIVE ORGTBL table_name */
14394 /* END RECEIVE ORGTBL table_name */
14395 @end example
14396
14397 @noindent
14398 Just above the source table, we put a special line that tells
14399 Orgtbl mode how to translate this table and where to install it. For
14400 example:
14401 @cindex #+ORGTBL
14402 @example
14403 #+ORGTBL: SEND table_name translation_function arguments....
14404 @end example
14405
14406 @noindent
14407 @code{table_name} is the reference name for the table that is also used
14408 in the receiver lines. @code{translation_function} is the Lisp function
14409 that does the translation. Furthermore, the line can contain a list of
14410 arguments (alternating key and value) at the end. The arguments will be
14411 passed as a property list to the translation function for
14412 interpretation. A few standard parameters are already recognized and
14413 acted upon before the translation function is called:
14414
14415 @table @code
14416 @item :skip N
14417 Skip the first N lines of the table. Hlines do count as separate lines for
14418 this parameter!
14419
14420 @item :skipcols (n1 n2 ...)
14421 List of columns that should be skipped. If the table has a column with
14422 calculation marks, that column is automatically discarded as well.
14423 Please note that the translator function sees the table @emph{after} the
14424 removal of these columns, the function never knows that there have been
14425 additional columns.
14426 @end table
14427
14428 @noindent
14429 The one problem remaining is how to keep the source table in the buffer
14430 without disturbing the normal workings of the file, for example during
14431 compilation of a C file or processing of a @LaTeX{} file. There are a
14432 number of different solutions:
14433
14434 @itemize @bullet
14435 @item
14436 The table could be placed in a block comment if that is supported by the
14437 language. For example, in C mode you could wrap the table between
14438 @samp{/*} and @samp{*/} lines.
14439 @item
14440 Sometimes it is possible to put the table after some kind of @i{END}
14441 statement, for example @samp{\bye} in @TeX{} and @samp{\end@{document@}}
14442 in @LaTeX{}.
14443 @item
14444 You can just comment the table line-by-line whenever you want to process
14445 the file, and uncomment it whenever you need to edit the table. This
14446 only sounds tedious---the command @kbd{M-x orgtbl-toggle-comment}
14447 makes this comment-toggling very easy, in particular if you bind it to a
14448 key.
14449 @end itemize
14450
14451 @node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax
14452 @subsection A @LaTeX{} example of radio tables
14453 @cindex @LaTeX{}, and Orgtbl mode
14454
14455 The best way to wrap the source table in @LaTeX{} is to use the
14456 @code{comment} environment provided by @file{comment.sty}. It has to be
14457 activated by placing @code{\usepackage@{comment@}} into the document
14458 header. Orgtbl mode can insert a radio table skeleton@footnote{By
14459 default this works only for @LaTeX{}, HTML, and Texinfo. Configure the
14460 variable @code{orgtbl-radio-tables} to install templates for other
14461 modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will
14462 be prompted for a table name, let's say we use @samp{salesfigures}. You
14463 will then get the following template:
14464
14465 @cindex #+ORGTBL, SEND
14466 @example
14467 % BEGIN RECEIVE ORGTBL salesfigures
14468 % END RECEIVE ORGTBL salesfigures
14469 \begin@{comment@}
14470 #+ORGTBL: SEND salesfigures orgtbl-to-latex
14471 | | |
14472 \end@{comment@}
14473 @end example
14474
14475 @noindent
14476 @vindex @LaTeX{}-verbatim-environments
14477 The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function
14478 @code{orgtbl-to-latex} to convert the table into @LaTeX{} and to put it
14479 into the receiver location with name @code{salesfigures}. You may now
14480 fill in the table---feel free to use the spreadsheet features@footnote{If
14481 the @samp{#+TBLFM} line contains an odd number of dollar characters,
14482 this may cause problems with font-lock in @LaTeX{} mode. As shown in the
14483 example you can fix this by adding an extra line inside the
14484 @code{comment} environment that is used to balance the dollar
14485 expressions. If you are using AUC@TeX{} with the font-latex library, a
14486 much better solution is to add the @code{comment} environment to the
14487 variable @code{LaTeX-verbatim-environments}.}:
14488
14489 @example
14490 % BEGIN RECEIVE ORGTBL salesfigures
14491 % END RECEIVE ORGTBL salesfigures
14492 \begin@{comment@}
14493 #+ORGTBL: SEND salesfigures orgtbl-to-latex
14494 | Month | Days | Nr sold | per day |
14495 |-------+------+---------+---------|
14496 | Jan | 23 | 55 | 2.4 |
14497 | Feb | 21 | 16 | 0.8 |
14498 | March | 22 | 278 | 12.6 |
14499 #+TBLFM: $4=$3/$2;%.1f
14500 % $ (optional extra dollar to keep font-lock happy, see footnote)
14501 \end@{comment@}
14502 @end example
14503
14504 @noindent
14505 When you are done, press @kbd{C-c C-c} in the table to get the converted
14506 table inserted between the two marker lines.
14507
14508 Now let's assume you want to make the table header by hand, because you
14509 want to control how columns are aligned, etc@. In this case we make sure
14510 that the table translator skips the first 2 lines of the source
14511 table, and tell the command to work as a @i{splice}, i.e.@: to not produce
14512 header and footer commands of the target table:
14513
14514 @example
14515 \begin@{tabular@}@{lrrr@}
14516 Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
14517 % BEGIN RECEIVE ORGTBL salesfigures
14518 % END RECEIVE ORGTBL salesfigures
14519 \end@{tabular@}
14520 %
14521 \begin@{comment@}
14522 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
14523 | Month | Days | Nr sold | per day |
14524 |-------+------+---------+---------|
14525 | Jan | 23 | 55 | 2.4 |
14526 | Feb | 21 | 16 | 0.8 |
14527 | March | 22 | 278 | 12.6 |
14528 #+TBLFM: $4=$3/$2;%.1f
14529 \end@{comment@}
14530 @end example
14531
14532 The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
14533 Orgtbl mode. It uses a @code{tabular} environment to typeset the table
14534 and marks horizontal lines with @code{\hline}. Furthermore, it
14535 interprets the following parameters (see also @pxref{Translator functions}):
14536
14537 @table @code
14538 @item :splice nil/t
14539 When set to t, return only table body lines, don't wrap them into a
14540 tabular environment. Default is nil.
14541
14542 @item :fmt fmt
14543 A format to be used to wrap each field, it should contain @code{%s} for the
14544 original field value. For example, to wrap each field value in dollars,
14545 you could use @code{:fmt "$%s$"}. This may also be a property list with
14546 column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
14547 A function of one argument can be used in place of the strings; the
14548 function must return a formatted string.
14549
14550 @item :efmt efmt
14551 Use this format to print numbers with exponentials. The format should
14552 have @code{%s} twice for inserting mantissa and exponent, for example
14553 @code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This
14554 may also be a property list with column numbers and formats, for example
14555 @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
14556 @code{efmt} has been applied to a value, @code{fmt} will also be
14557 applied. Similar to @code{fmt}, functions of two arguments can be
14558 supplied instead of strings.
14559 @end table
14560
14561 @node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax
14562 @subsection Translator functions
14563 @cindex HTML, and Orgtbl mode
14564 @cindex translator function
14565
14566 Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv}
14567 (comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values)
14568 @code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}.
14569 Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the same
14570 code that produces tables during HTML export.}, these all use a generic
14571 translator, @code{orgtbl-to-generic}. For example, @code{orgtbl-to-latex}
14572 itself is a very short function that computes the column definitions for the
14573 @code{tabular} environment, defines a few field and line separators and then
14574 hands processing over to the generic translator. Here is the entire code:
14575
14576 @lisp
14577 @group
14578 (defun orgtbl-to-latex (table params)
14579 "Convert the Orgtbl mode TABLE to LaTeX."
14580 (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
14581 org-table-last-alignment ""))
14582 (params2
14583 (list
14584 :tstart (concat "\\begin@{tabular@}@{" alignment "@}")
14585 :tend "\\end@{tabular@}"
14586 :lstart "" :lend " \\\\" :sep " & "
14587 :efmt "%s\\,(%s)" :hline "\\hline")))
14588 (orgtbl-to-generic table (org-combine-plists params2 params))))
14589 @end group
14590 @end lisp
14591
14592 As you can see, the properties passed into the function (variable
14593 @var{PARAMS}) are combined with the ones newly defined in the function
14594 (variable @var{PARAMS2}). The ones passed into the function (i.e.@: the
14595 ones set by the @samp{ORGTBL SEND} line) take precedence. So if you
14596 would like to use the @LaTeX{} translator, but wanted the line endings to
14597 be @samp{\\[2mm]} instead of the default @samp{\\}, you could just
14598 overrule the default with
14599
14600 @example
14601 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
14602 @end example
14603
14604 For a new language, you can either write your own converter function in
14605 analogy with the @LaTeX{} translator, or you can use the generic function
14606 directly. For example, if you have a language where a table is started
14607 with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are
14608 started with @samp{!BL!}, ended with @samp{!EL!}, and where the field
14609 separator is a TAB, you could call the generic translator like this (on
14610 a single line!):
14611
14612 @example
14613 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
14614 :lstart "!BL! " :lend " !EL!" :sep "\t"
14615 @end example
14616
14617 @noindent
14618 Please check the documentation string of the function
14619 @code{orgtbl-to-generic} for a full list of parameters understood by
14620 that function, and remember that you can pass each of them into
14621 @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
14622 using the generic function.
14623
14624 Of course you can also write a completely new function doing complicated
14625 things the generic translator cannot do. A translator function takes
14626 two arguments. The first argument is the table, a list of lines, each
14627 line either the symbol @code{hline} or a list of fields. The second
14628 argument is the property list containing all parameters specified in the
14629 @samp{#+ORGTBL: SEND} line. The function must return a single string
14630 containing the formatted table. If you write a generally useful
14631 translator, please post it on @email{emacs-orgmode@@gnu.org} so that
14632 others can benefit from your work.
14633
14634 @node Radio lists, , Translator functions, Tables in arbitrary syntax
14635 @subsection Radio lists
14636 @cindex radio lists
14637 @cindex org-list-insert-radio-list
14638
14639 Sending and receiving radio lists works exactly the same way as sending and
14640 receiving radio tables (@pxref{Radio tables}). As for radio tables, you can
14641 insert radio list templates in HTML, @LaTeX{} and Texinfo modes by calling
14642 @code{org-list-insert-radio-list}.
14643
14644 Here are the differences with radio tables:
14645
14646 @itemize @minus
14647 @item
14648 Orgstruct mode must be active.
14649 @item
14650 Use the @code{ORGLST} keyword instead of @code{ORGTBL}.
14651 @item
14652 The available translation functions for radio lists don't take
14653 parameters.
14654 @item
14655 @kbd{C-c C-c} will work when pressed on the first item of the list.
14656 @end itemize
14657
14658 Here is a @LaTeX{} example. Let's say that you have this in your
14659 @LaTeX{} file:
14660
14661 @cindex #+ORGLST
14662 @example
14663 % BEGIN RECEIVE ORGLST to-buy
14664 % END RECEIVE ORGLST to-buy
14665 \begin@{comment@}
14666 #+ORGLST: SEND to-buy org-list-to-latex
14667 - a new house
14668 - a new computer
14669 + a new keyboard
14670 + a new mouse
14671 - a new life
14672 \end@{comment@}
14673 @end example
14674
14675 Pressing `C-c C-c' on @code{a new house} and will insert the converted
14676 @LaTeX{} list between the two marker lines.
14677
14678 @node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking
14679 @section Dynamic blocks
14680 @cindex dynamic blocks
14681
14682 Org documents can contain @emph{dynamic blocks}. These are
14683 specially marked regions that are updated by some user-written function.
14684 A good example for such a block is the clock table inserted by the
14685 command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
14686
14687 Dynamic blocks are enclosed by a BEGIN-END structure that assigns a name
14688 to the block and can also specify parameters for the function producing
14689 the content of the block.
14690
14691 @cindex #+BEGIN:dynamic block
14692 @example
14693 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
14694
14695 #+END:
14696 @end example
14697
14698 Dynamic blocks are updated with the following commands
14699
14700 @table @kbd
14701 @orgcmd{C-c C-x C-u,org-dblock-update}
14702 Update dynamic block at point.
14703 @orgkey{C-u C-c C-x C-u}
14704 Update all dynamic blocks in the current file.
14705 @end table
14706
14707 Updating a dynamic block means to remove all the text between BEGIN and
14708 END, parse the BEGIN line for parameters and then call the specific
14709 writer function for this block to insert the new content. If you want
14710 to use the original content in the writer function, you can use the
14711 extra parameter @code{:content}.
14712
14713 For a block with name @code{myblock}, the writer function is
14714 @code{org-dblock-write:myblock} with as only parameter a property list
14715 with the parameters given in the begin line. Here is a trivial example
14716 of a block that keeps track of when the block update function was last
14717 run:
14718
14719 @example
14720 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
14721
14722 #+END:
14723 @end example
14724
14725 @noindent
14726 The corresponding block writer function could look like this:
14727
14728 @lisp
14729 (defun org-dblock-write:block-update-time (params)
14730 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
14731 (insert "Last block update at: "
14732 (format-time-string fmt (current-time)))))
14733 @end lisp
14734
14735 If you want to make sure that all dynamic blocks are always up-to-date,
14736 you could add the function @code{org-update-all-dblocks} to a hook, for
14737 example @code{before-save-hook}. @code{org-update-all-dblocks} is
14738 written in a way such that it does nothing in buffers that are not in
14739 @code{org-mode}.
14740
14741 You can narrow the current buffer to the current dynamic block (like any
14742 other block) with @code{org-narrow-to-block}.
14743
14744 @node Special agenda views, Extracting agenda information, Dynamic blocks, Hacking
14745 @section Special agenda views
14746 @cindex agenda views, user-defined
14747
14748 @vindex org-agenda-skip-function
14749 @vindex org-agenda-skip-function-global
14750 Org provides a special hook that can be used to narrow down the selection
14751 made by these agenda views: @code{agenda}, @code{todo}, @code{alltodo},
14752 @code{tags}, @code{tags-todo}, @code{tags-tree}. You may specify a function
14753 that is used at each match to verify if the match should indeed be part of
14754 the agenda view, and if not, how much should be skipped. You can specify a
14755 global condition that will be applied to all agenda views, this condition
14756 would be stored in the variable @code{org-agenda-skip-function-global}. More
14757 commonly, such a definition is applied only to specific custom searches,
14758 using @code{org-agenda-skip-function}.
14759
14760 Let's say you want to produce a list of projects that contain a WAITING
14761 tag anywhere in the project tree. Let's further assume that you have
14762 marked all tree headings that define a project with the TODO keyword
14763 PROJECT. In this case you would run a TODO search for the keyword
14764 PROJECT, but skip the match unless there is a WAITING tag anywhere in
14765 the subtree belonging to the project line.
14766
14767 To achieve this, you must write a function that searches the subtree for
14768 the tag. If the tag is found, the function must return @code{nil} to
14769 indicate that this match should not be skipped. If there is no such
14770 tag, return the location of the end of the subtree, to indicate that
14771 search should continue from there.
14772
14773 @lisp
14774 (defun my-skip-unless-waiting ()
14775 "Skip trees that are not waiting"
14776 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
14777 (if (re-search-forward ":waiting:" subtree-end t)
14778 nil ; tag found, do not skip
14779 subtree-end))) ; tag not found, continue after end of subtree
14780 @end lisp
14781
14782 Now you may use this function in an agenda custom command, for example
14783 like this:
14784
14785 @lisp
14786 (org-add-agenda-custom-command
14787 '("b" todo "PROJECT"
14788 ((org-agenda-skip-function 'my-skip-unless-waiting)
14789 (org-agenda-overriding-header "Projects waiting for something: "))))
14790 @end lisp
14791
14792 @vindex org-agenda-overriding-header
14793 Note that this also binds @code{org-agenda-overriding-header} to get a
14794 meaningful header in the agenda view.
14795
14796 @vindex org-odd-levels-only
14797 @vindex org-agenda-skip-function
14798 A general way to create custom searches is to base them on a search for
14799 entries with a certain level limit. If you want to study all entries with
14800 your custom search function, simply do a search for
14801 @samp{LEVEL>0}@footnote{Note that, when using @code{org-odd-levels-only}, a
14802 level number corresponds to order in the hierarchy, not to the number of
14803 stars.}, and then use @code{org-agenda-skip-function} to select the entries
14804 you really want to have.
14805
14806 You may also put a Lisp form into @code{org-agenda-skip-function}. In
14807 particular, you may use the functions @code{org-agenda-skip-entry-if}
14808 and @code{org-agenda-skip-subtree-if} in this form, for example:
14809
14810 @table @code
14811 @item (org-agenda-skip-entry-if 'scheduled)
14812 Skip current entry if it has been scheduled.
14813 @item (org-agenda-skip-entry-if 'notscheduled)
14814 Skip current entry if it has not been scheduled.
14815 @item (org-agenda-skip-entry-if 'deadline)
14816 Skip current entry if it has a deadline.
14817 @item (org-agenda-skip-entry-if 'scheduled 'deadline)
14818 Skip current entry if it has a deadline, or if it is scheduled.
14819 @item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
14820 Skip current entry if the TODO keyword is TODO or WAITING.
14821 @item (org-agenda-skip-entry-if 'todo 'done)
14822 Skip current entry if the TODO keyword marks a DONE state.
14823 @item (org-agenda-skip-entry-if 'timestamp)
14824 Skip current entry if it has any timestamp, may also be deadline or scheduled.
14825 @item (org-agenda-skip-entry 'regexp "regular expression")
14826 Skip current entry if the regular expression matches in the entry.
14827 @item (org-agenda-skip-entry 'notregexp "regular expression")
14828 Skip current entry unless the regular expression matches.
14829 @item (org-agenda-skip-subtree-if 'regexp "regular expression")
14830 Same as above, but check and skip the entire subtree.
14831 @end table
14832
14833 Therefore we could also have written the search for WAITING projects
14834 like this, even without defining a special function:
14835
14836 @lisp
14837 (org-add-agenda-custom-command
14838 '("b" todo "PROJECT"
14839 ((org-agenda-skip-function '(org-agenda-skip-subtree-if
14840 'regexp ":waiting:"))
14841 (org-agenda-overriding-header "Projects waiting for something: "))))
14842 @end lisp
14843
14844 @node Extracting agenda information, Using the property API, Special agenda views, Hacking
14845 @section Extracting agenda information
14846 @cindex agenda, pipe
14847 @cindex Scripts, for agenda processing
14848
14849 @vindex org-agenda-custom-commands
14850 Org provides commands to access agenda information for the command
14851 line in Emacs batch mode. This extracted information can be sent
14852 directly to a printer, or it can be read by a program that does further
14853 processing of the data. The first of these commands is the function
14854 @code{org-batch-agenda}, that produces an agenda view and sends it as
14855 ASCII text to STDOUT. The command takes a single string as parameter.
14856 If the string has length 1, it is used as a key to one of the commands
14857 you have configured in @code{org-agenda-custom-commands}, basically any
14858 key you can use after @kbd{C-c a}. For example, to directly print the
14859 current TODO list, you could use
14860
14861 @example
14862 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
14863 @end example
14864
14865 If the parameter is a string with 2 or more characters, it is used as a
14866 tags/TODO match string. For example, to print your local shopping list
14867 (all items with the tag @samp{shop}, but excluding the tag
14868 @samp{NewYork}), you could use
14869
14870 @example
14871 emacs -batch -l ~/.emacs \
14872 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
14873 @end example
14874
14875 @noindent
14876 You may also modify parameters on the fly like this:
14877
14878 @example
14879 emacs -batch -l ~/.emacs \
14880 -eval '(org-batch-agenda "a" \
14881 org-agenda-span month \
14882 org-agenda-include-diary nil \
14883 org-agenda-files (quote ("~/org/project.org")))' \
14884 | lpr
14885 @end example
14886
14887 @noindent
14888 which will produce a 30-day agenda, fully restricted to the Org file
14889 @file{~/org/projects.org}, not even including the diary.
14890
14891 If you want to process the agenda data in more sophisticated ways, you
14892 can use the command @code{org-batch-agenda-csv} to get a comma-separated
14893 list of values for each agenda item. Each line in the output will
14894 contain a number of fields separated by commas. The fields in a line
14895 are:
14896
14897 @example
14898 category @r{The category of the item}
14899 head @r{The headline, without TODO keyword, TAGS and PRIORITY}
14900 type @r{The type of the agenda entry, can be}
14901 todo @r{selected in TODO match}
14902 tagsmatch @r{selected in tags match}
14903 diary @r{imported from diary}
14904 deadline @r{a deadline}
14905 scheduled @r{scheduled}
14906 timestamp @r{appointment, selected by timestamp}
14907 closed @r{entry was closed on date}
14908 upcoming-deadline @r{warning about nearing deadline}
14909 past-scheduled @r{forwarded scheduled item}
14910 block @r{entry has date block including date}
14911 todo @r{The TODO keyword, if any}
14912 tags @r{All tags including inherited ones, separated by colons}
14913 date @r{The relevant date, like 2007-2-14}
14914 time @r{The time, like 15:00-16:50}
14915 extra @r{String with extra planning info}
14916 priority-l @r{The priority letter if any was given}
14917 priority-n @r{The computed numerical priority}
14918 @end example
14919
14920 @noindent
14921 Time and date will only be given if a timestamp (or deadline/scheduled)
14922 led to the selection of the item.
14923
14924 A CSV list like this is very easy to use in a post-processing script.
14925 For example, here is a Perl program that gets the TODO list from
14926 Emacs/Org and prints all the items, preceded by a checkbox:
14927
14928 @example
14929 #!/usr/bin/perl
14930
14931 # define the Emacs command to run
14932 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
14933
14934 # run it and capture the output
14935 $agenda = qx@{$cmd 2>/dev/null@};
14936
14937 # loop over all lines
14938 foreach $line (split(/\n/,$agenda)) @{
14939 # get the individual values
14940 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
14941 $priority_l,$priority_n) = split(/,/,$line);
14942 # process and print
14943 print "[ ] $head\n";
14944 @}
14945 @end example
14946
14947 @node Using the property API, Using the mapping API, Extracting agenda information, Hacking
14948 @section Using the property API
14949 @cindex API, for properties
14950 @cindex properties, API
14951
14952 Here is a description of the functions that can be used to work with
14953 properties.
14954
14955 @defun org-entry-properties &optional pom which
14956 Get all properties of the entry at point-or-marker POM.@*
14957 This includes the TODO keyword, the tags, time strings for deadline,
14958 scheduled, and clocking, and any additional properties defined in the
14959 entry. The return value is an alist. Keys may occur multiple times
14960 if the property key was used several times.@*
14961 POM may also be nil, in which case the current entry is used.
14962 If WHICH is nil or `all', get all properties. If WHICH is
14963 `special' or `standard', only get that subclass.
14964 @end defun
14965 @vindex org-use-property-inheritance
14966 @defun org-entry-get pom property &optional inherit
14967 Get value of PROPERTY for entry at point-or-marker POM. By default,
14968 this only looks at properties defined locally in the entry. If INHERIT
14969 is non-nil and the entry does not have the property, then also check
14970 higher levels of the hierarchy. If INHERIT is the symbol
14971 @code{selective}, use inheritance if and only if the setting of
14972 @code{org-use-property-inheritance} selects PROPERTY for inheritance.
14973 @end defun
14974
14975 @defun org-entry-delete pom property
14976 Delete the property PROPERTY from entry at point-or-marker POM.
14977 @end defun
14978
14979 @defun org-entry-put pom property value
14980 Set PROPERTY to VALUE for entry at point-or-marker POM.
14981 @end defun
14982
14983 @defun org-buffer-property-keys &optional include-specials
14984 Get all property keys in the current buffer.
14985 @end defun
14986
14987 @defun org-insert-property-drawer
14988 Insert a property drawer at point.
14989 @end defun
14990
14991 @defun org-entry-put-multivalued-property pom property &rest values
14992 Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a list of
14993 strings. They will be concatenated, with spaces as separators.
14994 @end defun
14995
14996 @defun org-entry-get-multivalued-property pom property
14997 Treat the value of the property PROPERTY as a whitespace-separated list of
14998 values and return the values as a list of strings.
14999 @end defun
15000
15001 @defun org-entry-add-to-multivalued-property pom property value
15002 Treat the value of the property PROPERTY as a whitespace-separated list of
15003 values and make sure that VALUE is in this list.
15004 @end defun
15005
15006 @defun org-entry-remove-from-multivalued-property pom property value
15007 Treat the value of the property PROPERTY as a whitespace-separated list of
15008 values and make sure that VALUE is @emph{not} in this list.
15009 @end defun
15010
15011 @defun org-entry-member-in-multivalued-property pom property value
15012 Treat the value of the property PROPERTY as a whitespace-separated list of
15013 values and check if VALUE is in this list.
15014 @end defun
15015
15016 @defopt org-property-allowed-value-functions
15017 Hook for functions supplying allowed values for a specific property.
15018 The functions must take a single argument, the name of the property, and
15019 return a flat list of allowed values. If @samp{:ETC} is one of
15020 the values, use the values as completion help, but allow also other values
15021 to be entered. The functions must return @code{nil} if they are not
15022 responsible for this property.
15023 @end defopt
15024
15025 @node Using the mapping API, , Using the property API, Hacking
15026 @section Using the mapping API
15027 @cindex API, for mapping
15028 @cindex mapping entries, API
15029
15030 Org has sophisticated mapping capabilities to find all entries satisfying
15031 certain criteria. Internally, this functionality is used to produce agenda
15032 views, but there is also an API that can be used to execute arbitrary
15033 functions for each or selected entries. The main entry point for this API
15034 is:
15035
15036 @defun org-map-entries func &optional match scope &rest skip
15037 Call FUNC at each headline selected by MATCH in SCOPE.
15038
15039 FUNC is a function or a Lisp form. The function will be called without
15040 arguments, with the cursor positioned at the beginning of the headline.
15041 The return values of all calls to the function will be collected and
15042 returned as a list.
15043
15044 The call to FUNC will be wrapped into a save-excursion form, so FUNC
15045 does not need to preserve point. After evaluation, the cursor will be
15046 moved to the end of the line (presumably of the headline of the
15047 processed entry) and search continues from there. Under some
15048 circumstances, this may not produce the wanted results. For example,
15049 if you have removed (e.g.@: archived) the current (sub)tree it could
15050 mean that the next entry will be skipped entirely. In such cases, you
15051 can specify the position from where search should continue by making
15052 FUNC set the variable `org-map-continue-from' to the desired buffer
15053 position.
15054
15055 MATCH is a tags/property/todo match as it is used in the agenda match view.
15056 Only headlines that are matched by this query will be considered during
15057 the iteration. When MATCH is nil or t, all headlines will be
15058 visited by the iteration.
15059
15060 SCOPE determines the scope of this command. It can be any of:
15061
15062 @example
15063 nil @r{the current buffer, respecting the restriction if any}
15064 tree @r{the subtree started with the entry at point}
15065 region @r{The entries within the active region, if any}
15066 file @r{the current buffer, without restriction}
15067 file-with-archives
15068 @r{the current buffer, and any archives associated with it}
15069 agenda @r{all agenda files}
15070 agenda-with-archives
15071 @r{all agenda files with any archive files associated with them}
15072 (file1 file2 ...)
15073 @r{if this is a list, all files in the list will be scanned}
15074 @end example
15075 @noindent
15076 The remaining args are treated as settings for the skipping facilities of
15077 the scanner. The following items can be given here:
15078
15079 @vindex org-agenda-skip-function
15080 @example
15081 archive @r{skip trees with the archive tag}
15082 comment @r{skip trees with the COMMENT keyword}
15083 function or Lisp form
15084 @r{will be used as value for @code{org-agenda-skip-function},}
15085 @r{so whenever the function returns t, FUNC}
15086 @r{will not be called for that entry and search will}
15087 @r{continue from the point where the function leaves it}
15088 @end example
15089 @end defun
15090
15091 The function given to that mapping routine can really do anything you like.
15092 It can use the property API (@pxref{Using the property API}) to gather more
15093 information about the entry, or in order to change metadata in the entry.
15094 Here are a couple of functions that might be handy:
15095
15096 @defun org-todo &optional arg
15097 Change the TODO state of the entry. See the docstring of the functions for
15098 the many possible values for the argument ARG.
15099 @end defun
15100
15101 @defun org-priority &optional action
15102 Change the priority of the entry. See the docstring of this function for the
15103 possible values for ACTION.
15104 @end defun
15105
15106 @defun org-toggle-tag tag &optional onoff
15107 Toggle the tag TAG in the current entry. Setting ONOFF to either @code{on}
15108 or @code{off} will not toggle tag, but ensure that it is either on or off.
15109 @end defun
15110
15111 @defun org-promote
15112 Promote the current entry.
15113 @end defun
15114
15115 @defun org-demote
15116 Demote the current entry.
15117 @end defun
15118
15119 Here is a simple example that will turn all entries in the current file with
15120 a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}.
15121 Entries in comment trees and in archive trees will be ignored.
15122
15123 @lisp
15124 (org-map-entries
15125 '(org-todo "UPCOMING")
15126 "+TOMORROW" 'file 'archive 'comment)
15127 @end lisp
15128
15129 The following example counts the number of entries with TODO keyword
15130 @code{WAITING}, in all agenda files.
15131
15132 @lisp
15133 (length (org-map-entries t "/+WAITING" 'agenda))
15134 @end lisp
15135
15136 @node MobileOrg, History and Acknowledgments, Hacking, Top
15137 @appendix MobileOrg
15138 @cindex iPhone
15139 @cindex MobileOrg
15140
15141 @uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the
15142 @i{iPhone/iPod Touch} series of devices, developed by Richard Moreland.
15143 @i{MobileOrg} offers offline viewing and capture support for an Org-mode
15144 system rooted on a ``real'' computer. It does also allow you to record
15145 changes to existing entries. Android users should check out
15146 @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android}
15147 by Matt Jones.
15148
15149 This appendix describes the support Org has for creating agenda views in a
15150 format that can be displayed by @i{MobileOrg}, and for integrating notes
15151 captured and changes made by @i{MobileOrg} into the main system.
15152
15153 For changing tags and TODO states in MobileOrg, you should have set up the
15154 customization variables @code{org-todo-keywords} and @code{org-tags-alist} to
15155 cover all important tags and TODO keywords, even if individual files use only
15156 part of these. MobileOrg will also offer you states and tags set up with
15157 in-buffer settings, but it will understand the logistics of TODO state
15158 @i{sets} (@pxref{Per-file keywords}) and @i{mutually exclusive} tags
15159 (@pxref{Setting tags}) only for those set in these variables.
15160
15161 @menu
15162 * Setting up the staging area:: Where to interact with the mobile device
15163 * Pushing to MobileOrg:: Uploading Org files and agendas
15164 * Pulling from MobileOrg:: Integrating captured and flagged items
15165 @end menu
15166
15167 @node Setting up the staging area, Pushing to MobileOrg, MobileOrg, MobileOrg
15168 @section Setting up the staging area
15169
15170 MobileOrg needs to interact with Emacs through a directory on a server. If you
15171 are using a public server, you should consider to encrypt the files that are
15172 uploaded to the server. This can be done with Org-mode 7.02 and with
15173 @i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl}
15174 installation on your system. To turn on encryption, set a password in
15175 @i{MobileOrg} and, on the Emacs side, configure the variable
15176 @code{org-mobile-use-encryption}@footnote{If you can safely store the
15177 password in your Emacs setup, you might also want to configure
15178 @code{org-mobile-encryption-password}. Please read the docstring of that
15179 variable. Note that encryption will apply only to the contents of the
15180 @file{.org} files. The file names themselves will remain visible.}.
15181
15182 The easiest way to create that directory is to use a free
15183 @uref{http://dropbox.com,Dropbox.com} account@footnote{If you cannot use
15184 Dropbox, or if your version of MobileOrg does not support it, you can use a
15185 webdav server. For more information, check out the documentation of MobileOrg and also this
15186 @uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
15187 When MobileOrg first connects to your Dropbox, it will create a directory
15188 @i{MobileOrg} inside the Dropbox. After the directory has been created, tell
15189 Emacs about it:
15190
15191 @lisp
15192 (setq org-mobile-directory "~/Dropbox/MobileOrg")
15193 @end lisp
15194
15195 Org-mode has commands to put files for @i{MobileOrg} into that directory,
15196 and to read captured notes from there.
15197
15198 @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg
15199 @section Pushing to MobileOrg
15200
15201 This operation copies all files currently listed in @code{org-mobile-files}
15202 to the directory @code{org-mobile-directory}. By default this list contains
15203 all agenda files (as listed in @code{org-agenda-files}), but additional files
15204 can be included by customizing @code{org-mobile-files}. File names will be
15205 staged with paths relative to @code{org-directory}, so all files should be
15206 inside this directory. The push operation also creates a special Org file
15207 @file{agendas.org} with all custom agenda view defined by the
15208 user@footnote{While creating the agendas, Org-mode will force ID properties
15209 on all referenced entries, so that these entries can be uniquely identified
15210 if @i{MobileOrg} flags them for further action. If you do not want to get
15211 these properties in so many entries, you can set the variable
15212 @code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then
15213 rely on outline paths, in the hope that these will be unique enough.}.
15214 Finally, Org writes the file @file{index.org}, containing links to all other
15215 files. @i{MobileOrg} first reads this file from the server, and then
15216 downloads all agendas and Org files listed in it. To speed up the download,
15217 MobileOrg will only read files whose checksums@footnote{stored automatically
15218 in the file @file{checksums.dat}} have changed.
15219
15220 @node Pulling from MobileOrg, , Pushing to MobileOrg, MobileOrg
15221 @section Pulling from MobileOrg
15222
15223 When @i{MobileOrg} synchronizes with the server, it not only pulls the Org
15224 files for viewing. It also appends captured entries and pointers to flagged
15225 and changed entries to the file @file{mobileorg.org} on the server. Org has
15226 a @emph{pull} operation that integrates this information into an inbox file
15227 and operates on the pointers to flagged entries. Here is how it works:
15228
15229 @enumerate
15230 @item
15231 Org moves all entries found in
15232 @file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this
15233 operation.} and appends them to the file pointed to by the variable
15234 @code{org-mobile-inbox-for-pull}. Each captured entry and each editing event
15235 will be a top-level entry in the inbox file.
15236 @item
15237 After moving the entries, Org will attempt to implement the changes made in
15238 @i{MobileOrg}. Some changes are applied directly and without user
15239 interaction. Examples are all changes to tags, TODO state, headline and body
15240 text that can be cleanly applied. Entries that have been flagged for further
15241 action will receive a tag @code{:FLAGGED:}, so that they can be easily found
15242 again. When there is a problem finding an entry or applying the change, the
15243 pointer entry will remain in the inbox and will be marked with an error
15244 message. You need to later resolve these issues by hand.
15245 @item
15246 Org will then generate an agenda view with all flagged entries. The user
15247 should then go through these entries and do whatever actions are necessary.
15248 If a note has been stored while flagging an entry in @i{MobileOrg}, that note
15249 will be displayed in the echo area when the cursor is on the corresponding
15250 agenda line.
15251 @table @kbd
15252 @kindex ?
15253 @item ?
15254 Pressing @kbd{?} in that special agenda will display the full flagging note in
15255 another window and also push it onto the kill ring. So you could use @kbd{?
15256 z C-y C-c C-c} to store that flagging note as a normal note in the entry.
15257 Pressing @kbd{?} twice in succession will offer to remove the
15258 @code{:FLAGGED:} tag along with the recorded flagging note (which is stored
15259 in a property). In this way you indicate that the intended processing for
15260 this flagged entry is finished.
15261 @end table
15262 @end enumerate
15263
15264 @kindex C-c a ?
15265 If you are not able to process all flagged entries directly, you can always
15266 return to this agenda view@footnote{Note, however, that there is a subtle
15267 difference. The view created automatically by @kbd{M-x org-mobile-pull
15268 @key{RET}} is guaranteed to search all files that have been addressed by the
15269 last pull. This might include a file that is not currently in your list of
15270 agenda files. If you later use @kbd{C-c a ?} to regenerate the view, only
15271 the current agenda files will be searched.} using @kbd{C-c a ?}.
15272
15273 @node History and Acknowledgments, Main Index, MobileOrg, Top
15274 @appendix History and acknowledgments
15275 @cindex acknowledgments
15276 @cindex history
15277 @cindex thanks
15278
15279 Org was born in 2003, out of frustration over the user interface of the Emacs
15280 Outline mode. I was trying to organize my notes and projects, and using
15281 Emacs seemed to be the natural way to go. However, having to remember eleven
15282 different commands with two or three keys per command, only to hide and show
15283 parts of the outline tree, that seemed entirely unacceptable to me. Also,
15284 when using outlines to take notes, I constantly wanted to restructure the
15285 tree, organizing it parallel to my thoughts and plans. @emph{Visibility
15286 cycling} and @emph{structure editing} were originally implemented in the
15287 package @file{outline-magic.el}, but quickly moved to the more general
15288 @file{org.el}. As this environment became comfortable for project planning,
15289 the next step was adding @emph{TODO entries}, basic @emph{timestamps}, and
15290 @emph{table support}. These areas highlighted the two main goals that Org
15291 still has today: to be a new, outline-based, plain text mode with innovative
15292 and intuitive editing features, and to incorporate project planning
15293 functionality directly into a notes file.
15294
15295 Since the first release, literally thousands of emails to me or to
15296 @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug
15297 reports, feedback, new ideas, and sometimes patches and add-on code.
15298 Many thanks to everyone who has helped to improve this package. I am
15299 trying to keep here a list of the people who had significant influence
15300 in shaping one or more aspects of Org. The list may not be
15301 complete, if I have forgotten someone, please accept my apologies and
15302 let me know.
15303
15304 Before I get to this list, a few special mentions are in order:
15305
15306 @table @i
15307 @item Bastien Guerry
15308 Bastien has written a large number of extensions to Org (most of them
15309 integrated into the core by now), including the LaTeX exporter and the plain
15310 list parser. His support during the early days, when he basically acted as
15311 co-maintainer, was central to the success of this project. Bastien also
15312 invented Worg, helped establishing the Web presence of Org, and sponsors
15313 hosting costs for the orgmode.org website.
15314 @item Eric Schulte and Dan Davison
15315 Eric and Dan are jointly responsible for the Org-babel system, which turns
15316 Org into a multi-language environment for evaluating code and doing literate
15317 programming and reproducible research.
15318 @item John Wiegley
15319 John has contributed a number of great ideas and patches directly to Org,
15320 including the attachment system (@file{org-attach.el}), integration with
15321 Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO
15322 items, habit tracking (@file{org-habits.el}), and encryption
15323 (@file{org-crypt.el}). Also, the capture system is really an extended copy
15324 of his great @file{remember.el}.
15325 @item Sebastian Rose
15326 Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
15327 of an ignorant amateur. Sebastian has pushed this part of Org onto a much
15328 higher level. He also wrote @file{org-info.js}, a Java script for displaying
15329 webpages derived from Org using an Info-like or a folding interface with
15330 single-key navigation.
15331 @end table
15332
15333 @noindent OK, now to the full list of contributions! Again, please let me
15334 know what I am missing here!
15335
15336 @itemize @bullet
15337
15338 @item
15339 @i{Russel Adams} came up with the idea for drawers.
15340 @item
15341 @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
15342 @item
15343 @i{Christophe Bataillon} created the great unicorn logo that we use on the
15344 Org-mode website.
15345 @item
15346 @i{Alex Bochannek} provided a patch for rounding timestamps.
15347 @item
15348 @i{Jan Böcker} wrote @file{org-docview.el}.
15349 @item
15350 @i{Brad Bozarth} showed how to pull RSS feed data into Org-mode files.
15351 @item
15352 @i{Tom Breton} wrote @file{org-choose.el}.
15353 @item
15354 @i{Charles Cave}'s suggestion sparked the implementation of templates
15355 for Remember, which are now templates for capture.
15356 @item
15357 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
15358 specified time.
15359 @item
15360 @i{Gregory Chernov} patched support for Lisp forms into table
15361 calculations and improved XEmacs compatibility, in particular by porting
15362 @file{nouline.el} to XEmacs.
15363 @item
15364 @i{Sacha Chua} suggested copying some linking code from Planner.
15365 @item
15366 @i{Baoqiu Cui} contributed the DocBook exporter.
15367 @item
15368 @i{Eddward DeVilla} proposed and tested checkbox statistics. He also
15369 came up with the idea of properties, and that there should be an API for
15370 them.
15371 @item
15372 @i{Nick Dokos} tracked down several nasty bugs.
15373 @item
15374 @i{Kees Dullemond} used to edit projects lists directly in HTML and so
15375 inspired some of the early development, including HTML export. He also
15376 asked for a way to narrow wide table columns.
15377 @item
15378 @i{Thomas S. Dye} contributed documentation on Worg and helped integrating
15379 the Org-Babel documentation into the manual.
15380 @item
15381 @i{Christian Egli} converted the documentation into Texinfo format, inspired
15382 the agenda, patched CSS formatting into the HTML exporter, and wrote
15383 @file{org-taskjuggler.el}.
15384 @item
15385 @i{David Emery} provided a patch for custom CSS support in exported
15386 HTML agendas.
15387 @item
15388 @i{Nic Ferrier} contributed mailcap and XOXO support.
15389 @item
15390 @i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
15391 @item
15392 @i{John Foerch} figured out how to make incremental search show context
15393 around a match in a hidden outline tree.
15394 @item
15395 @i{Raimar Finken} wrote @file{org-git-line.el}.
15396 @item
15397 @i{Mikael Fornius} works as a mailing list moderator.
15398 @item
15399 @i{Austin Frank} works as a mailing list moderator.
15400 @item
15401 @i{Eric Fraga} drove the development of BEAMER export with ideas and
15402 testing.
15403 @item
15404 @i{Barry Gidden} did proofreading the manual in preparation for the book
15405 publication through Network Theory Ltd.
15406 @item
15407 @i{Niels Giesen} had the idea to automatically archive DONE trees.
15408 @item
15409 @i{Nicolas Goaziou} rewrote much of the plain list code.
15410 @item
15411 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
15412 @item
15413 @i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a
15414 book.
15415 @item
15416 @i{Bernt Hansen} has driven much of the support for auto-repeating tasks,
15417 task state change logging, and the clocktable. His clear explanations have
15418 been critical when we started to adopt the Git version control system.
15419 @item
15420 @i{Manuel Hermenegildo} has contributed various ideas, small fixes and
15421 patches.
15422 @item
15423 @i{Phil Jackson} wrote @file{org-irc.el}.
15424 @item
15425 @i{Scott Jaderholm} proposed footnotes, control over whitespace between
15426 folded entries, and column view for properties.
15427 @item
15428 @i{Matt Jones} wrote @i{MobileOrg Android}.
15429 @item
15430 @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
15431 @item
15432 @i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also
15433 provided frequent feedback and some patches.
15434 @item
15435 @i{Matt Lundin} has proposed last-row references for table formulas and named
15436 invisible anchors. He has also worked a lot on the FAQ.
15437 @item
15438 @i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,
15439 and is a prolific contributor on the mailing list with competent replies,
15440 small fixes and patches.
15441 @item
15442 @i{Jason F. McBrayer} suggested agenda export to CSV format.
15443 @item
15444 @i{Max Mikhanosha} came up with the idea of refiling.
15445 @item
15446 @i{Dmitri Minaev} sent a patch to set priority limits on a per-file
15447 basis.
15448 @item
15449 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
15450 happy.
15451 @item
15452 @i{Richard Moreland} wrote @i{MobileOrg} for the iPhone.
15453 @item
15454 @i{Rick Moynihan} proposed allowing multiple TODO sequences in a file
15455 and being able to quickly restrict the agenda to a subtree.
15456 @item
15457 @i{Todd Neal} provided patches for links to Info files and Elisp forms.
15458 @item
15459 @i{Greg Newman} refreshed the unicorn logo into its current form.
15460 @item
15461 @i{Tim O'Callaghan} suggested in-file links, search options for general
15462 file links, and TAGS.
15463 @item
15464 @i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text
15465 version of the reference card.
15466 @item
15467 @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
15468 into Japanese.
15469 @item
15470 @i{Oliver Oppitz} suggested multi-state TODO items.
15471 @item
15472 @i{Scott Otterson} sparked the introduction of descriptive text for
15473 links, among other things.
15474 @item
15475 @i{Pete Phillips} helped during the development of the TAGS feature, and
15476 provided frequent feedback.
15477 @item
15478 @i{Martin Pohlack} provided the code snippet to bundle character insertion
15479 into bundles of 20 for undo.
15480 @item
15481 @i{T.V. Raman} reported bugs and suggested improvements.
15482 @item
15483 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
15484 control.
15485 @item
15486 @i{Paul Rivier} provided the basic implementation of named footnotes. He
15487 also acted as mailing list moderator for some time.
15488 @item
15489 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
15490 @item
15491 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
15492 conflict with @file{allout.el}.
15493 @item
15494 @i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with
15495 extensive patches.
15496 @item
15497 @i{Philip Rooke} created the Org reference card, provided lots
15498 of feedback, developed and applied standards to the Org documentation.
15499 @item
15500 @i{Christian Schlauer} proposed angular brackets around links, among
15501 other things.
15502 @item
15503 @i{Paul Sexton} wrote @file{org-ctags.el}.
15504 @item
15505 Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
15506 @file{organizer-mode.el}.
15507 @item
15508 @i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal
15509 examples, and remote highlighting for referenced code lines.
15510 @item
15511 @i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is
15512 now packaged into Org's @file{contrib} directory.
15513 @item
15514 @i{Daniel Sinder} came up with the idea of internal archiving by locking
15515 subtrees.
15516 @item
15517 @i{Dale Smith} proposed link abbreviations.
15518 @item
15519 @i{James TD Smith} has contributed a large number of patches for useful
15520 tweaks and features.
15521 @item
15522 @i{Adam Spiers} asked for global linking commands, inspired the link
15523 extension system, added support for mairix, and proposed the mapping API.
15524 @item
15525 @i{Ulf Stegemann} created the table to translate special symbols to HTML,
15526 LaTeX, UTF-8, Latin-1 and ASCII.
15527 @item
15528 @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
15529 with links transformation to Org syntax.
15530 @item
15531 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
15532 chapter about publishing.
15533 @item
15534 @i{Jambunathan K} contributed the OpenDocumentText exporter.
15535 @item
15536 @i{Sebastien Vauban} reported many issues with LaTeX and BEAMER export and
15537 enabled source code highlighling in Gnus.
15538 @item
15539 @i{Stefan Vollmar} organized a video-recorded talk at the
15540 Max-Planck-Institute for Neurology. He also inspired the creation of a
15541 concept index for HTML export.
15542 @item
15543 @i{J@"urgen Vollmer} contributed code generating the table of contents
15544 in HTML output.
15545 @item
15546 @i{Samuel Wales} has provided important feedback and bug reports.
15547 @item
15548 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
15549 keyword.
15550 @item
15551 @i{David Wainberg} suggested archiving, and improvements to the linking
15552 system.
15553 @item
15554 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
15555 linking to Gnus.
15556 @item
15557 @i{Roland Winkler} requested additional key bindings to make Org
15558 work on a tty.
15559 @item
15560 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
15561 and contributed various ideas and code snippets.
15562 @item
15563 @end itemize
15564
15565
15566 @node Main Index, Key Index, History and Acknowledgments, Top
15567 @unnumbered Concept index
15568
15569 @printindex cp
15570
15571 @node Key Index, Command and Function Index, Main Index, Top
15572 @unnumbered Key index
15573
15574 @printindex ky
15575
15576 @node Command and Function Index, Variable Index, Key Index, Top
15577 @unnumbered Command and function index
15578
15579 @printindex fn
15580
15581 @node Variable Index, , Command and Function Index, Top
15582 @unnumbered Variable index
15583
15584 This is not a complete index of variables and faces, only the ones that are
15585 mentioned in the manual. For a more complete list, use @kbd{M-x
15586 org-customize @key{RET}} and then click yourself through the tree.
15587
15588 @printindex vr
15589
15590 @bye
15591
15592 @c Local variables:
15593 @c fill-column: 77
15594 @c indent-tabs-mode: nil
15595 @c paragraph-start: "\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$"
15596 @c paragraph-separate: "\b\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$"
15597 @c End:
15598
15599
15600 @c LocalWords: webdavhost pre