3 @setfilename ../info/org
4 @settitle Org Mode Manual
7 @set DATE December 2006
11 * Org Mode: (org). outline-based notes management and organizer
14 @c Version and Contact Info
15 @set MAINTAINERSITE @uref{http://www.astro.uva.nl/~dominik/Tools/org/,maintainers webpage}
16 @set AUTHOR Carsten Dominik
17 @set MAINTAINER Carsten Dominik
18 @set MAINTAINEREMAIL @email{dominik at science dot uva dot nl}
19 @set MAINTAINERCONTACT @uref{mailto:dominik at science dot uva dot nl,contact the maintainer}
25 @c Subheadings inside a table.
26 @macro tsubheading{text}
36 This manual is for Org-mode (version @value{VERSION}).
38 Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation
41 Permission is granted to copy, distribute and/or modify this document
42 under the terms of the GNU Free Documentation License, Version 1.1 or
43 any later version published by the Free Software Foundation; with no
44 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
45 and with the Back-Cover Texts as in (a) below. A copy of the
46 license is included in the section entitled ``GNU Free Documentation
49 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
50 this GNU Manual, like GNU software. Copies published by the Free
51 Software Foundation raise funds for GNU development.''
56 @title Org Mode Manual
58 @subtitle Release @value{VERSION}
59 @author by Carsten Dominik
61 @c The following two commands start the copyright page.
63 @vskip 0pt plus 1filll
67 @c Output the table of contents at the beginning.
71 @node Top, Introduction, (dir), (dir)
78 * Introduction:: Getting started
79 * Document structure:: A tree works like your brain
80 * Tables:: Pure magic for quick formatting
81 * Hyperlinks:: Notes in context
82 * TODO items:: Every tree branch can be a TODO item
83 * Timestamps:: Assign date and time to items
84 * Tags:: Tagging headlines and matching sets of tags
85 * Agenda views:: Collecting information into views
86 * Embedded LaTeX:: LaTeX fragments and formulas
87 * Exporting:: Sharing and publishing of notes
88 * Publishing:: Create a web site of linked Org-mode files
89 * Miscellaneous:: All the rest which did not fit elsewhere
90 * Extensions and Hacking:: It is possible to write add-on code
91 * History and Acknowledgments:: How Org-mode came into being
92 * Index:: The fast road to specific information
93 * Key Index:: Key bindings and where they are described
96 --- The Detailed Node Listing ---
100 * Summary:: Brief summary of what Org-mode does
101 * Installation:: How to install a downloaded version of Org-mode
102 * Activation:: How to activate Org-mode for certain buffers.
103 * Feedback:: Bug reports, ideas, patches etc.
107 * Outlines:: Org-mode is based on outline-mode
108 * Headlines:: How to typeset org-tree headlines
109 * Visibility cycling:: Show and hide, much simplified
110 * Motion:: Jumping to other headlines
111 * Structure editing:: Changing sequence and level of headlines
112 * Archiving:: Move done task trees to a different place
113 * Sparse trees:: Matches embedded in context
114 * Plain lists:: Additional structure within an entry
118 * ARCHIVE tag:: Marking a tree as inactive
119 * Moving subtrees:: Moving a tree to an archive file
123 * Built-in table editor:: Simple tables
124 * Narrow columns:: Stop wasting space in tables
125 * Table calculations:: Compute a field from other fields
126 * orgtbl-mode:: The table editor as minor mode
127 * table.el:: Complex tables
129 Calculations in tables
131 * Formula syntax:: How to write a formula
132 * Lisp formulas:: An alternative way to write formulas
133 * Column formulas:: Formulas valid for all fields in a column
134 * Advanced features:: Field names, parameters and automatic recalc
135 * Named-field formulas:: Formulas valid in single fields
136 * Editing/debugging formulas:: Changing a stored formula
137 * Appetizer:: Taste the power of calc
141 * Link format:: How links in Org-mode are formatted
142 * Internal links:: Links to other places in the current file
143 * External links:: URL-like links to the world
144 * Handling links:: Creating, inserting and following
145 * Link abbreviations:: Shortcuts for writing complex links
146 * Search options:: Linking to a specific location
147 * Custom searches:: When the default search is not enough
148 * Remember:: Org-trees store quick notes
152 * Radio targets:: Make targets trigger links in plain text.
153 * CamelCase links:: Activating CamelCase words as links
157 * TODO basics:: Marking and displaying TODO entries
158 * TODO extensions:: Workflow and assignments
159 * Priorities:: Some things are more important than others
160 * Breaking down tasks:: Splitting a task into managable pieces
161 * Checkboxes:: Tick-off lists
163 Extended use of TODO keywords
165 * Workflow states:: From TODO to DONE in steps
166 * TODO types:: I do this, Fred the rest
167 * Per file keywords:: Different files, different requirements
171 * Time stamps:: Assigning a time to a tree entry
172 * Creating timestamps:: Commands which insert timestamps
173 * Custom time format:: If you cannot work with the ISO format
174 * Progress logging:: Documenting when what work was done.
178 * The date/time prompt:: How org-mode helps you entering date and time
182 * Closing items:: When was this entry marked DONE?
183 * Tracking TODO state changes:: When did the status change?
184 * Clocking work time:: When exactly did you work on this item?
188 * Tag inheritance:: Tags use the tree structure of the outline
189 * Setting tags:: How to assign tags to a headline
190 * Tag searches:: Searching for combinations of tags
194 * Agenda files:: Files being searched for agenda information
195 * Agenda dispatcher:: Keyboard access to agenda views
196 * Built-in agenda views:: What is available out of the box?
197 * Presentation and sorting:: How agenda items are prepared for display
198 * Agenda commands:: Remote editing of org trees
199 * Custom agenda views:: Defining special searches and views
201 The built-in agenda views
203 * Weekly/Daily agenda:: The calendar page with current tasks
204 * Global TODO list:: All unfinished action items
205 * Matching headline tags:: Structured information with fine-tuned search
206 * Timeline:: Time-sorted view for single file
207 * Stuck projects:: Find projects you need to review
209 Presentation and sorting
211 * Categories:: Not all tasks are equal
212 * Time-of-day specifications:: How the agenda knows the time
213 * Sorting of agenda items:: The order of things
217 * Storing searches:: Type once, use often
218 * Block agenda:: All the stuff you need in a single buffer
219 * Setting Options:: Changing the rules
220 * Batch processing:: Agenda views from the command line
224 * Math symbols:: TeX macros for symbols and Greek letters
225 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
226 * LaTeX fragments:: Complex formulas made easy
227 * Processing LaTeX fragments:: Previewing LaTeX processing
228 * CDLaTeX mode:: Speed up entering of formulas
232 * ASCII export:: Exporting to plain ASCII
233 * HTML export:: Exporting to HTML
234 * XOXO export:: Exporting to XOXO
235 * iCalendar export:: Exporting in iCalendar format
236 * Text interpretation:: How the exporter looks at the file
240 * Export commands:: How to invode HTML export
241 * Quoting HTML tags:: Using direct HTML in Org-mode
242 * Links:: How hyperlinks get transferred to HTML
243 * Images:: To inline or not to inline?
244 * CSS support:: Style specifications
246 Text interpretation by the exporter
248 * Comment lines:: Some lines will not be exported
249 * Enhancing text:: Subscripts, symbols and more
250 * Export options:: How to influence the export settings
254 * Configuration:: Defining projects
255 * Sample configuration:: Example projects
256 * Triggering publication:: Publication commands
260 * Project alist:: The central configuration variable
261 * Sources and destinations:: From here to there
262 * Selecting files:: What files are part of the project?
263 * Publishing action:: Setting the function doing the publishing
264 * Publishing options:: Tweaking HTML export
265 * Publishing links:: Which links keep working after publishing?
266 * Project page index:: Publishing a list of project files
270 * Simple example:: One-component publishing
271 * Complex example:: A multi-component publishing example
275 * Completion:: M-TAB knows what you need
276 * Customization:: Adapting Org-mode to your taste
277 * In-buffer settings:: Overview of the #+KEYWORDS
278 * The very busy C-c C-c key:: When in doubt, press C-c C-c
279 * Clean view:: Getting rid of leading stars in the outline
280 * TTY keys:: Using Org-mode on a tty
281 * Interaction:: Other Emacs packages
282 * Bugs:: Things which do not work perfectly
284 Interaction with other packages
286 * Cooperation:: Packages Org-mode cooperates with
287 * Conflicts:: Packages that lead to conflicts
289 Extensions, Hooks and Hacking
291 * Extensions:: Existing 3rd-part extensions
292 * Dynamic blocks:: Automatically filled blocks
293 * Special agenda views::
298 @node Introduction, Document structure, Top, Top
299 @chapter Introduction
303 * Summary:: Brief summary of what Org-mode does
304 * Installation:: How to install a downloaded version of Org-mode
305 * Activation:: How to activate Org-mode for certain buffers.
306 * Feedback:: Bug reports, ideas, patches etc.
309 @node Summary, Installation, Introduction, Introduction
313 Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
314 project planning with a fast and effective plain-text system.
316 Org-mode develops organizational tasks around NOTES files that contain
317 lists or information about projects as plain text. Org-mode is
318 implemented on top of outline-mode, which makes it possible to keep the
319 content of large files well structured. Visibility cycling and
320 structure editing help to work with the tree. Tables are easily created
321 with a built-in table editor. Org-mode supports ToDo items, deadlines,
322 time stamps, and scheduling. It dynamically compiles entries into an
323 agenda that utilizes and smoothly integrates much of the Emacs calendar
324 and diary. Plain text URL-like links connect to websites, emails,
325 Usenet messages, BBDB entries, and any files related to the projects.
326 For printing and sharing of notes, an Org-mode file can be exported as a
327 structured ASCII file, as HTML, or (todo and agenda items only) as an
328 iCalendar file. It can also serve as a publishing tool for a set of
331 An important design aspect that distinguishes Org-mode from for example
332 Planner/Muse is that it encougages to store every piece of information
333 only once. In Planner, you have project pages, day pages and possibly
334 other files, duplicating some information such as tasks. In Org-mode,
335 you only have notes files. In your notes you mark entries as tasks,
336 label them with tags and timestamps. All necessary lists like a
337 schedule for the day, the agenda for a meeting, tasks lists selected by
338 tags etc are created dynamically when you need them.
340 Org-mode keeps simple things simple. When first fired up, it should
341 feel like a straightforward, easy to use outliner. Complexity is not
342 imposed, but a large amount of functionality is available when you need
343 it. Org-mode can be used on different levels and in different ways, for
347 @r{@bullet{} as an outline extension with visibility cycling and structure editing}
348 @r{@bullet{} as an ASCII system and table editor for taking structured notes}
349 @r{@bullet{} as an ASCII table editor with spreadsheet-like capabilities}
350 @r{@bullet{} as a TODO list editor}
351 @r{@bullet{} as a full agenda and planner with deadlines and work scheduling}
352 @r{@bullet{} as an environment to implement David Allen's GTD system}
353 @r{@bullet{} as a simple hypertext system, with HTML export}
354 @r{@bullet{} as a publishing tool to create a set of interlinked webpages}
357 Org-mode's automatic, context sensitive table editor can be integrated
358 into any major mode by activating the minor Orgtbl-mode.
361 There is a website for Org-mode which provides links to the newest
362 version of Org-mode, as well as additional information, frequently asked
363 questions (FAQ), links to tutorials etc. This page is located at
364 @uref{http://www.astro.uva.nl/~dominik/Tools/org/}.
368 @node Installation, Activation, Summary, Introduction
369 @section Installation
373 @b{Important:} If Org-mode is part of the Emacs distribution or an
374 XEmacs package, please skip this section and go directly to
377 If you have downloaded Org-mode from the Web, you must take the
378 following steps to install it: Go into the Org-mode distribution
379 directory and edit the top section of the file @file{Makefile}. You
380 must set the name of the Emacs binary (likely either @file{emacs} or
381 @file{xemacs}), and the paths to the directories where local Lisp and
382 Info files are kept. If you don't have access to the system-wide
383 directories, create your own two directories for these files, enter them
384 into the Makefile, and make sure Emacs finds the Lisp files by adding
385 the following line to @file{.emacs}:
388 (setq load-path (cons "~/path/to/lispdir" load-path))
391 @b{XEmacs users now need to install the file @file{noutline.el} from
392 the @file{xemacs} subdirectory of the Org-mode distribution. Use the
396 @b{make install-noutline}
399 @noindent Now byte-compile and install the Lisp files with the shell
407 @noindent If you want to install the info documentation, use this command:
413 @noindent Then add to @file{.emacs}:
416 ;; This line only if org-mode is not part of the X/Emacs distribution.
417 (require 'org-install)
420 @node Activation, Feedback, Installation, Introduction
424 @cindex global keybindings
425 @cindex keybindings, global
427 Add the following lines to your @file{.emacs} file. The last two lines
428 define @emph{global} keys for the commands @command{org-store-link} and
429 @command{org-agenda} - please choose suitable keys yourself.
432 ;; The following lines are always needed. Choose your own keys.
433 (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
434 (define-key global-map "\C-cl" 'org-store-link)
435 (define-key global-map "\C-ca" 'org-agenda)
438 Furthermore, you must activate @code{font-lock-mode} in org-mode
439 buffers, because significant functionality depends on font-locking being
440 active. You can do this with either one of the following two lines
441 (XEmacs user must use the second option):
443 (global-font-lock-mode 1) ; for all buffers
444 (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
447 @cindex org-mode, turning on
448 With this setup, all files with extension @samp{.org} will be put
449 into Org-mode. As an alternative, make the first line of a file look
453 MY PROJECTS -*- mode: org; -*-
456 @noindent which will select Org-mode for this buffer no matter what
457 the file's name is. See also the variable
458 @code{org-insert-mode-line-in-empty-file}.
460 @node Feedback, , Activation, Introduction
467 If you find problems with Org-mode, or if you have questions, remarks,
468 or ideas about it, please contact the maintainer @value{MAINTAINER} at
469 @value{MAINTAINEREMAIL}.
471 For bug reports, please provide as much information as possible,
472 including the version information of Emacs (@kbd{C-h v emacs-version
473 @key{RET}}) and Org-mode (@kbd{C-h v org-version @key{RET}}), as well as
474 the Org-mode related setup in @file{.emacs}. If an error occurs, a
475 backtrace can be very useful (see below on how to create one). Often a
476 small example file helps, along with clear information about:
479 @item What exactly did you do?
480 @item What did you expect to happen?
481 @item What happened instead?
483 @noindent Thank you for helping to improve this mode.
485 @subsubheading How to create a useful backtrace
487 @cindex backtrace of an error
488 If working with Org-mode produces an error with a message you don't
489 understand, you may have hit a bug. The best way to report this is by
490 providing, in addition to what was mentioned above, a @emph{Backtrace}.
491 This is information from the built-in debugger about where and how the
492 error occurred. Here is how to produce a useful backtrace:
496 Start a fresh Emacs or XEmacs, and make sure that it will load the
497 original Lisp code in @file{org.el} instead of the compiled version in
498 @file{org.elc}. The backtrace contains much more information if it is
499 produced with uncompiled code. To do this, either rename @file{org.elc}
500 to something else before starting Emacs, or ask Emacs explicitly to load
501 @file{org.el} by using the command line
503 emacs -l /path/to/org.el
506 Go to the @code{Options} menu and select @code{Enter Debugger on Error}
507 (XEmacs has this option in the @code{Troubleshooting} sub-menu).
509 Do whatever you have to do to hit the error. Don't forget to
510 document the steps you take.
512 When you hit the error, a @file{*Backtrace*} buffer will appear on the
513 screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
514 attach it to your bug report.
517 @node Document structure, Tables, Introduction, Top
518 @chapter Document Structure
519 @cindex document structure
520 @cindex structure of document
522 Org-mode is based on outline mode and provides flexible commands to
523 edit the structure of the document.
526 * Outlines:: Org-mode is based on outline-mode
527 * Headlines:: How to typeset org-tree headlines
528 * Visibility cycling:: Show and hide, much simplified
529 * Motion:: Jumping to other headlines
530 * Structure editing:: Changing sequence and level of headlines
531 * Archiving:: Move done task trees to a different place
532 * Sparse trees:: Matches embedded in context
533 * Plain lists:: Additional structure within an entry
536 @node Outlines, Headlines, Document structure, Document structure
541 Org-mode is implemented on top of outline-mode. Outlines allow to
542 organize a document in a hierarchical structure, which (at least for
543 me) is the best representation of notes and thoughts. Overview over
544 this structure is achieved by folding (hiding) large parts of the
545 document to show only the general document structure and the parts
546 currently being worked on. Org-mode greatly simplifies the use of
547 outlines by compressing the entire show/hide functionality into a
548 single command @command{org-cycle}, which is bound to the @key{TAB}
551 @node Headlines, Visibility cycling, Outlines, Document structure
556 Headlines define the structure of an outline tree. The headlines in
557 Org-mode start with one or more stars, on the left margin. For
567 * Another top level headline
570 @noindent Some people find the many stars too noisy and would prefer an
571 outline that has whitespace followed by a single star as headline
572 starters. @ref{Clean view} describes a setup to realize this.
574 @node Visibility cycling, Motion, Headlines, Document structure
575 @section Visibility cycling
576 @cindex cycling, visibility
577 @cindex visibility cycling
578 @cindex trees, visibility
579 @cindex show hidden text
582 Outlines make it possible to hide parts of the text in the buffer.
583 Org-mode uses just two commands, bound to @key{TAB} and
584 @kbd{S-@key{TAB}} to change the visibility in the buffer.
586 @cindex subtree visibility states
587 @cindex subtree cycling
588 @cindex folded, subtree visibility state
589 @cindex children, subtree visibility state
590 @cindex subtree, subtree visibility state
594 @emph{Subtree cycling}: Rotate current subtree between the states
597 ,-> FOLDED -> CHILDREN -> SUBTREE --.
598 '-----------------------------------'
601 The cursor must be on a headline for this to work@footnote{see, however,
602 the option @code{org-cycle-emulate-tab}.}. When the cursor is at the
603 beginning of the buffer and the first line is not a headline, then
604 @key{TAB} actually runs global cycling (see below)@footnote{see the
605 option @code{org-cycle-global-at-bob}.}. Also when called with a prefix
606 argument (@kbd{C-u @key{TAB}}), global cycling is invoked.
608 @cindex global visibility states
609 @cindex global cycling
610 @cindex overview, global visibility state
611 @cindex contents, global visibility state
612 @cindex show all, global visibility state
616 @emph{Global cycling}: Rotate the entire buffer between the states
619 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
620 '--------------------------------------'
623 Note that inside tables, @kbd{S-@key{TAB}} jumps to the previous field.
625 @cindex show all, command
631 Reveal context around point, showing the current entry, the following
632 heading and the hierarchy above. Useful for working near a location
633 exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda
634 command (@pxref{Agenda commands}). With prefix arg show, on each
635 level, all sibling headings.
638 Show the current subtree in an indirect buffer@footnote{The indirect
639 buffer (@pxref{Indirect Buffers,Indirect Buffers,Indirect
640 Buffers,emacs,GNU Emacs Manual}) will contain the entire buffer, but
641 will be narrowed to the current tree. Editing the indirect buffer will
642 also change the original buffer, but without affecting visibility in
643 that buffer.}. With numerical prefix ARG, go up to this level and then
644 take that tree. If ARG is negative, go up that many levels. With
645 @kbd{C-u} prefix, do not remove the previously used indirect buffer.
648 When Emacs first visits an Org-mode file, the global state is set to
649 OVERVIEW, i.e. only the top level headlines are visible. This can be
650 configured through the variable @code{org-startup-folded}, or on a
651 per-file basis by adding one of the following lines anywhere in the
660 @node Motion, Structure editing, Visibility cycling, Document structure
662 @cindex motion, between headlines
663 @cindex jumping, to headlines
664 @cindex headline navigation
665 The following commands jump to other headlines in the buffer.
676 Next heading same level.
679 Previous heading same level.
682 Backward to higher level heading.
685 Jump to a different place without changing the current outline
686 visibility. Shows the document structure in a temporary buffer, where
687 you can use visibility cycling (@key{TAB}) to find your destination.
688 After pressing @key{RET}, the cursor moves to the selected location in
689 the original buffer, and the headings hierarchy above it is made
693 @node Structure editing, Archiving, Motion, Document structure
694 @section Structure editing
695 @cindex structure editing
696 @cindex headline, promotion and demotion
697 @cindex promotion, of subtrees
698 @cindex demotion, of subtrees
699 @cindex subtree, cut and paste
700 @cindex pasting, of subtrees
701 @cindex cutting, of subtrees
702 @cindex copying, of subtrees
703 @cindex subtrees, cut and paste
708 Insert new heading with same level as current. If the cursor is in a
709 plain list item, a new item is created (@pxref{Plain lists}). To force
710 creation of a new headline, use a prefix arg, or first press @key{RET}
711 to get to the beginning of the next line. When this command is used in
712 the middle of a line, the line is split and the rest of the line becomes
713 the new headline. If the command is used at the beginning of a
714 headline, the new headline is created before the current line. If at
715 the beginning of any other line, the content of that line is made the
716 new heading. If the command is used at the end of a folded subtree
717 (i.e. behind the ellipses at the end of a headline), then a headline
718 like the current one will be inserted after the end of the subtree.
719 @kindex M-S-@key{RET}
721 Insert new TODO entry with same level as current heading.
724 Promote current heading by one level.
725 @kindex M-@key{right}
727 Demote current heading by one level.
728 @kindex M-S-@key{left}
730 Promote the current subtree by one level.
731 @kindex M-S-@key{right}
732 @item M-S-@key{right}
733 Demote the current subtree by one level.
736 Move subtree up (swap with previous subtree of same
738 @kindex M-S-@key{down}
740 Move subtree down (swap with next subtree of same level).
745 Kill subtree, i.e. remove it from buffer but save in kill ring.
748 Copy subtree to kill ring.
751 Yank subtree from kill ring. This does modify the level of the subtree to
752 make sure the tree fits in nicely at the yank position. The yank
753 level can also be specified with a prefix arg, or by yanking after a
754 headline marker like @samp{****}.
757 Sort same-level entries. When there is an active region, all entries in
758 the region will be sorted. Otherwise the children of the current
759 headline are sorted. The command prompts for the sorting method, which
760 can be alphabetically, numerically, by time (using the first time stamp
761 in each entry), and each of these in reverse order. With a @kbd{C-u}
762 prefix, sorting will be case-sensitive. With two @kbd{C-u C-u}
763 prefixes, duplicate entries will also be removed.
766 @cindex region, active
767 @cindex active region
768 @cindex transient-mark-mode
769 When there is an active region (transient-mark-mode), promotion and
770 demotion work on all headlines in the region. To select a region of
771 headlines, it is best to place both point and mark at the beginning of a
772 line, mark at the beginning of the first headline, and point at the line
773 just after the last headline to change. Note that when the cursor is
774 inside a table (@pxref{Tables}), the Meta-Cursor keys have different
777 @node Archiving, Sparse trees, Structure editing, Document structure
781 When a project represented by a (sub)tree is finished, you may want
782 to move the tree out of the way and to stop it from contributing to the
783 agenda. Org-mode knows two ways of archiving. You can mark a tree with
784 the ARCHIVE tag, or you can move an entire (sub)tree to a different
788 * ARCHIVE tag:: Marking a tree as inactive
789 * Moving subtrees:: Moving a tree to an archive file
792 @node ARCHIVE tag, Moving subtrees, Archiving, Archiving
793 @subsection The ARCHIVE tag
794 @cindex internal archiving
796 A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at
797 its location in the outline tree, but behaves in the following way:
800 It does not open when you attempt to do so with a visibility cycling
801 command (@pxref{Visibility cycling}). You can force cycling archived
802 subtrees with @kbd{C-@key{TAB}}, or by setting the option
803 @code{org-cycle-open-archived-trees}. Also normal outline commands like
804 @code{show-all} will open archived subtrees.
806 During sparse tree construction (@pxref{Sparse trees}), matches in
807 archived subtrees are not exposed, unless you configure the option
808 @code{org-sparse-tree-open-archived-trees}.
810 During agenda view construction (@pxref{Agenda views}), the content of
811 archived trees is ignored unless you configure the option
812 @code{org-agenda-skip-archived-trees}.
814 Archived trees are not exported (@pxref{Exporting}), only the headline
815 is. Configure the details using the variable
816 @code{org-export-with-archived-trees}.
819 The following commands help managing the ARCHIVE tag:
824 Toggle the ARCHIVE tag for the current headline. When the tag is set,
825 the headline changes to a shadowish face, and the subtree below it is
827 @kindex C-u C-c C-x C-a
828 @item C-u C-c C-x C-a
829 Check if any direct children of the current headline should be archived.
830 To do this, each subtree is checked for open TODO entries. If none are
831 found, the command offers to set the ARCHIVE tag for the child. If the
832 cursor is @emph{not} on a headline when this command is invoked, the
833 level 1 trees will be checked.
836 Cycle a tree even if it is tagged with ARCHIVE.
839 @node Moving subtrees, , ARCHIVE tag, Archiving
840 @subsection Moving subtrees
841 @cindex external archiving
843 Once an entire project is finished, you may want to move it to a
844 different location, either in the current file, or even in a different
845 file, the archive file.
850 Archive the subtree starting at the cursor position to the location
851 given by @code{org-archive-location}.
854 Check if any direct children of the current headline could be moved to
855 the archive. To do this, each subtree is checked for open TODO entries.
856 If none are found, the command offers to move it to the archive
857 location. If the cursor is @emph{not} on a headline when this command
858 is invoked, the level 1 trees will be checked.
861 @cindex archive locations
862 The default archive location is a file in the same directory as the
863 current file, with the name derived by appending @file{_archive} to the
864 current file name. For information and examples on how to change this,
865 see the documentation string of the variable
866 @code{org-archive-location}.
868 @node Sparse trees, Plain lists, Archiving, Document structure
869 @section Sparse trees
871 @cindex trees, sparse
872 @cindex folding, sparse trees
873 @cindex occur, command
875 An important feature of Org-mode is the ability to construct
876 @emph{sparse trees} for selected information in an outline tree. A
877 sparse tree means that the entire document is folded as much as
878 possible, but the selected information is made visible along with the
879 headline structure above it@footnote{See also the variables
880 @code{org-show-hierarchy-above}, @code{org-show-following-heading}, and
881 @code{org-show-siblings} for detailed control on how much context is
882 shown around each match.}. Just try it out and you will see immediately
885 Org-mode contains several commands creating such trees. The most
886 basic one is @command{org-occur}:
891 Occur. Prompts for a regexp and shows a sparse tree with all matches.
892 If the match is in a headline, the headline is made visible. If the
893 match is in the body of an entry, headline and body are made visible.
894 In order to provide minimal context, also the full hierarchy of
895 headlines above the match is shown, as well as the headline following
896 the match. Each match is also highlighted; the highlights disappear
897 when the bufer is changes an editing command, or by pressing @kbd{C-c
898 C-c}. When called with a @kbd{C-u} prefix argument, previous highlights
899 are kept, so several calls to this command can be stacked.
902 For frequently used sparse trees of specific search strings, you can
903 use the variable @code{org-agenda-custom-commands} to define fast
904 keyboard access to specific sparse trees. These commands will then be
905 accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
909 (setq org-agenda-custom-commands
910 '(("f" occur-tree "FIXME")))
913 @noindent will define the key @kbd{C-c a f} as a shortcut for creating
914 a sparse tree matching the string @samp{FIXME}.
916 Other commands use sparse trees as well. For example @kbd{C-c
917 C-v} creates a sparse TODO tree (@pxref{TODO basics}).
920 @cindex printing sparse trees
921 @cindex visible text, printing
922 To print a sparse tree, you can use the Emacs command
923 @code{ps-print-buffer-with-faces} which does not print invisible parts
924 of the document @footnote{This does not work under XEmacs, because
925 XEmacs uses selective display for outlining, not text properties.}.
926 Or you can use the command @kbd{C-c C-e v} to export only the visible
927 part of the document and print the resulting file.
929 @node Plain lists, , Sparse trees, Document structure
933 @cindex lists, ordered
934 @cindex ordered lists
936 Within an entry of the outline tree, hand-formatted lists can provide
937 additional structure. They also provide a way to create lists of
938 checkboxes (@pxref{Checkboxes}). Org-mode supports editing such lists,
939 and the HTML exporter (@pxref{Exporting}) does parse and format them.
941 Org-mode knows ordered and unordered lists. Unordered list items start
942 with @samp{-}, @samp{+}, or @samp{*}@footnote{When using @samp{*} as a
943 bullet, lines must be indented or they will be seen as top-level
944 headlines. Also, when you are hiding leading stars to get a clean
945 outline view, plain list items starting with a star are visually
946 indistinguishable from true headlines. In short: even though @samp{*}
947 is supported, it may be better not to use it for plain list items} as
948 bullets. Ordered list items start with @samp{1.} or @samp{1)}. Items
949 belonging to the same list must have the same indentation on the first
950 line. In particular, if an ordered list reaches number @samp{10.}, then
951 the 2--digit numbers must be written left-aligned with the other numbers
952 in the list. Indentation also determines the end of a list item. It
953 ends before the next line that is indented like the bullet/number, or
959 My favorite scenes are (in this order)
960 1. The attack of the Rohirrim
961 2. Eowyns fight with the witch king
962 + this was already my favorite scene in the book
963 + I really like Miranda Otto.
964 3. Peter Jackson being shot by Legolas
966 He makes a really funny face when it happens.
967 But in the end, not individual scenes matter but the film as a whole.
971 Org-mode supports these lists by tuning filling and wrapping commands to
972 deal with them correctly@footnote{Org-mode only changes the filling
973 settings for Emacs. For XEmacs, you should use Kyle E. Jones'
974 @file{filladapt.el}. To turn this on, put into @file{.emacs}:
980 The following commands act on items when the cursor is in the first line
981 of an item (the line with the bullet or number).
986 Items can be folded just like headline levels if you set the variable
987 @code{org-cycle-include-plain-lists}. The level of an item is then
988 given by the indentation of the bullet/number. Items are always
989 subordinate to real headlines, however; the hierarchies remain
990 completely separated.
993 Insert new item at current level. With prefix arg, force a new heading
994 (@pxref{Structure editing}). If this command is used in the middle of a
995 line, the line is @emph{split} and the rest of the line becomes the new
996 item. If this command is executed in the @emph{whitespace before a bullet or
997 number}, the new item is created @emph{before} the current item. If the
998 command is executed in the white space before the text that is part of
999 an item but does not contain the bullet, a bullet is added to the
1001 @kindex M-S-@key{RET}
1003 Insert a new item with a checkbox (@pxref{Checkboxes}).
1005 @kindex S-@key{down}
1008 Jump to the previous/next item in the current list.
1009 @kindex M-S-@key{up}
1010 @kindex M-S-@key{down}
1012 @itemx M-S-@key{down}
1013 Move the item including subitems up/down (swap with previous/next item
1014 of same indentation). If the list is ordered, renumbering is
1016 @kindex M-S-@key{left}
1017 @kindex M-S-@key{right}
1018 @item M-S-@key{left}
1019 @itemx M-S-@key{right}
1020 Decrease/increase the indentation of the item, including subitems.
1021 Initially, the item tree is selected based on current indentation.
1022 When these commands are executed several times in direct succession,
1023 the initially selected region is used, even if the new indentation
1024 would imply a different hierarchy. To use the new hierarchy, break
1025 the command chain with a cursor motion or so.
1028 If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
1029 state of the checkbox. Otherwise, if this is an ordered list, renumber
1030 the ordered list at the cursor.
1033 @node Tables, Hyperlinks, Document structure, Top
1036 @cindex editing tables
1038 Org-mode has a very fast and intuitive table editor built-in.
1039 Spreadsheet-like calculations are supported in connection with the
1040 Emacs @file{calc} package.
1043 * Built-in table editor:: Simple tables
1044 * Narrow columns:: Stop wasting space in tables
1045 * Table calculations:: Compute a field from other fields
1046 * orgtbl-mode:: The table editor as minor mode
1047 * table.el:: Complex tables
1050 @node Built-in table editor, Narrow columns, Tables, Tables
1051 @section The built-in table editor
1052 @cindex table editor, builtin
1054 Org-mode makes it easy to format tables in plain ASCII. Any line with
1055 @samp{|} as the first non-white character is considered part of a
1056 table. @samp{|} is also the column separator. A table might look
1060 | Name | Phone | Age |
1061 |-------+-------+-----|
1062 | Peter | 1234 | 17 |
1063 | Anna | 4321 | 25 |
1066 A table is re-aligned automatically each time you press @key{TAB} or
1067 @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
1068 the next field (@key{RET} to the next row) and creates new table rows
1069 at the end of the table or before horizontal lines. The indentation
1070 of the table is set by the first line. Any line starting with
1071 @samp{|-} is considered as a horizontal separator line and will be
1072 expanded on the next re-align to span the whole table width. So, to
1073 create the above table, you would only type
1080 @noindent and then press @key{TAB} to align the table and start filling in
1083 When typing text into a field, Org-mode treats @key{DEL},
1084 @key{Backspace}, and all character keys in a special way, so that
1085 inserting and deleting avoids shifting other fields. Also, when
1086 typing @emph{immediately after the cursor was moved into a new field
1087 with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the
1088 field is automatically made blank. If this behavior is too
1089 unpredictable for you, configure the variables
1090 @code{org-enable-table-editor} and @code{org-table-auto-blank-field}.
1093 @tsubheading{Creation and conversion}
1096 Convert the active region to table. If every line contains at least one
1097 TAB character, the function assumes that the material is tab separated.
1098 If not, lines are split at whitespace into fields. You can use a prefix
1099 argument to indicate the minimum number of consecutive spaces required
1100 to identify a field separator (default: just one).@*
1101 If there is no active region, this command creates an empty Org-mode
1102 table. But it's easier just to start typing, like
1103 @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
1105 @tsubheading{Re-aligning and field motion}
1108 Re-align the table without moving the cursor.
1112 Re-align the table, move to the next field. Creates a new row if
1117 Re-align, move to previous field.
1121 Re-align the table and move down to next row. Creates a new row if
1122 necessary. At the beginning or end of a line, @key{RET} still does
1123 NEWLINE, so it can be used to split a table.
1125 @tsubheading{Column and row editing}
1126 @kindex M-@key{left}
1127 @kindex M-@key{right}
1129 @itemx M-@key{right}
1130 Move the current column left/right.
1132 @kindex M-S-@key{left}
1133 @item M-S-@key{left}
1134 Kill the current column.
1136 @kindex M-S-@key{right}
1137 @item M-S-@key{right}
1138 Insert a new column to the left of the cursor position.
1141 @kindex M-@key{down}
1144 Move the current row up/down.
1146 @kindex M-S-@key{up}
1148 Kill the current row or horizontal line.
1150 @kindex M-S-@key{down}
1151 @item M-S-@key{down}
1152 Insert a new row above (with arg: below) the current row.
1156 Insert a horizontal line below current row. With prefix arg, the line
1157 is created above the current line.
1161 Sort the table lines in the region. The position of point indicates the
1162 column to be used for sorting, and the range of lines is the range
1163 between the nearest horizontal separator lines, or the entire table. If
1164 point is before the first column, you will be prompted for the sorting
1165 column. If there is an active region, the mark specifies the first line
1166 and the sorting column, while point should be in the last line to be
1167 included into the sorting. The command prompts for the sorting type
1168 (alphabetically, numerically, or by time). When called with a prefix
1169 argument, alphabetic sorting will be case-sensitive.
1171 @tsubheading{Regions}
1174 Copy a rectangular region from a table to a special clipboard. Point
1175 and mark determine edge fields of the rectangle. The process ignores
1176 horizontal separator lines.
1179 Copy a rectangular region from a table to a special clipboard, and
1180 blank all fields in the rectangle. So this is the ``cut'' operation.
1183 Paste a rectangular region into a table.
1184 The upper right corner ends up in the current field. All involved fields
1185 will be overwritten. If the rectangle does not fit into the present table,
1186 the table is enlarged as needed. The process ignores horizontal separator
1190 Wrap several fields in a column like a paragraph. If there is an active
1191 region, and both point and mark are in the same column, the text in the
1192 column is wrapped to minimum width for the given number of lines. A
1193 prefix ARG may be used to change the number of desired lines. If there
1194 is no region, the current field is split at the cursor position and the
1195 text fragment to the right of the cursor is prepended to the field one
1196 line down. If there is no region, but you specify a prefix ARG, the
1197 current field is made blank, and the content is appended to the field
1200 @tsubheading{Calculations}
1201 @cindex formula, in tables
1202 @cindex calculations, in tables
1205 Install a new formula for the current column and replace current field
1206 with the result of the formula.
1210 Install a new formula for the current field, which must be a named
1211 field. Evaluate the formula and replace the field content with the
1216 Edit all formulas associated with the current table in a separate
1221 Recalculate the current row by applying the stored formulas from left
1222 to right. When called with a @kbd{C-u} prefix, recalculate the
1223 entire table, starting with the first non-header line (i.e. below the
1224 first horizontal separator line). For details, see @ref{Table calculations}.
1228 Rotate the calculation mark in first column through the states
1229 @samp{}, @samp{#}, @samp{*}, @samp{!}, @samp{$}. For the meaning of
1230 these marks see @ref{Advanced features}. When there is an active
1231 region, change all marks in the region.
1235 Which table column is the cursor in? Displays number >0 in echo
1238 @cindex region, active
1239 @cindex active region
1240 @cindex transient-mark-mode
1243 Sum the numbers in the current column, or in the rectangle defined by
1244 the active region. The result is shown in the echo area and can
1245 be inserted with @kbd{C-y}.
1249 When current field is empty, copy from first non-empty field above.
1250 When not empty, copy current field down to next row and move cursor
1251 along with it. Depending on the variable
1252 @code{org-table-copy-increment}, integer field values will be
1253 incremented during copy. This key is also used by CUA-mode
1254 (@pxref{Cooperation}).
1256 @tsubheading{Miscellaneous}
1259 Edit the current field in a separate window. This is useful for fields
1260 that are not fully visible (@pxref{Narrow columns}). When called with a
1261 @kbd{C-u} prefix, just make the full field visible, so that it can be
1264 @kindex C-c @key{TAB}
1266 This is an alias for @kbd{C-u C-c `} to make the current field fully
1269 @item M-x org-table-import
1270 Import a file as a table. The table should be TAB- or whitespace
1271 separated. Useful, for example, to import an Excel table or data from a
1272 database, because these programs generally can write TAB-separated text
1273 files. This command works by inserting the file into the buffer and
1274 then converting the region to a table. Any prefix argument is passed on
1275 to the converter, which uses it to determine the separator.
1277 @item M-x org-table-export
1278 Export the table as a TAB-separated file. Useful for data exchange with,
1279 for example, Excel or database programs.
1283 If you don't like the automatic table editor because it gets in your
1284 way on lines which you would like to start with @samp{|}, you can turn
1288 (setq org-enable-table-editor nil)
1291 @noindent Then the only table command that still works is
1292 @kbd{C-c C-c} to do a manual re-align.
1294 @node Narrow columns, Table calculations, Built-in table editor, Tables
1295 @section Narrow columns
1296 @cindex narrow columns in tables
1298 The width of columns is automatically determined by the table editor.
1299 Sometimes a single field or a few fields need to carry more text,
1300 leading to inconveniently wide columns. To limit@footnote{This feature
1301 does not work on XEmacs.} the width of a column, one field anywhere in
1302 the column may contain just the string @samp{<N>} where @samp{N} is an
1303 integer specifying the width of the column in characters. The next
1304 re-align will then set the width of this column to no more than this
1308 |---+------------------------------| |---+--------|
1310 | 1 | one | | 1 | one |
1311 | 2 | two | ----\ | 2 | two |
1312 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1313 | 4 | four | | 4 | four |
1314 |---+------------------------------| |---+--------|
1318 Fields that are wider become clipped and end in the string @samp{=>}.
1319 Note that the full text is still in the buffer, it is only invisible.
1320 To see the full text, hold the mouse over the field - a tooltip window
1321 will show the full content. To edit such a field, use the command
1322 @kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will
1323 open a new window with the full field. Edit it and finish with @kbd{C-c
1326 When visiting a file containing a table with narrowed columns, the
1327 necessary character hiding has not yet happened, and the table needs to
1328 be aligned before it looks nice. Setting the option
1329 @code{org-startup-align-all-tables} will realign all tables in a file
1330 upon visiting, but also slow down startup. You can also set this option
1331 on a per-file basis with:
1338 @node Table calculations, orgtbl-mode, Narrow columns, Tables
1339 @section Calculations in tables
1340 @cindex calculations, in tables
1341 @cindex spreadsheet capabilities
1342 @cindex @file{calc} package
1344 The table editor makes use of the Emacs @file{calc} package to implement
1345 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1346 derive fields from other fields. Org-mode has two levels of complexity
1347 for table calculations. On the basic level, tables do only horizontal
1348 computations, so a field can be computed from other fields @emph{in the
1349 same row}, and Org-mode assumes that there is only one formula for each
1350 column. This is very efficient to work with and enough for many tasks.
1351 On the complex level, columns and individual fields can be named for
1352 easier referencing in formulas, individual named fields can have their
1353 own formula associated with them, and recalculation can be automated.
1356 * Formula syntax:: How to write a formula
1357 * Lisp formulas:: An alternative way to write formulas
1358 * Column formulas:: Formulas valid for all fields in a column
1359 * Advanced features:: Field names, parameters and automatic recalc
1360 * Named-field formulas:: Formulas valid in single fields
1361 * Editing/debugging formulas:: Changing a stored formula
1362 * Appetizer:: Taste the power of calc
1365 @node Formula syntax, Lisp formulas, Table calculations, Table calculations
1366 @subsection Formula syntax
1367 @cindex formula syntax
1368 @cindex syntax, of formulas
1370 A formula can be any algebraic expression understood by the Emacs
1371 @file{calc} package. Note that @file{calc} has the slightly
1372 non-standard convention that @samp{/} has lower precedence than
1373 @samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}. Before
1374 evaluation by @code{calc-eval} (@pxref{Calling Calc from
1375 Your Programs,calc-eval,Calling calc from Your Lisp Programs,calc,GNU
1376 Emacs Calc Manual}),
1377 variable substitution takes place:
1380 $ @r{refers to the current field}
1381 $3 @r{refers to the field in column 3 of the current row}
1382 $3..$7 @r{a vector of the fields in columns 3-7 of current row}
1383 $P1..$P3 @r{vector of column range, using column names}
1384 &2 @r{second data field above the current, in same column}
1385 &5-2 @r{vector from fifth to second field above current}
1386 &III-II @r{vector of fields between 2nd and 3rd hline above}
1387 &III @r{vector of fields between third hline above and current field}
1388 $name @r{a named field, parameter or constant}
1391 @cindex vectors, in table calculations
1392 The range vectors can be directly fed into the calc vector functions
1393 like @samp{vmean} and @samp{vsum}.
1395 @cindex name, of column or field
1396 @cindex constants, in calculations
1397 @samp{$name} is interpreted as the name of a column, parameter or
1398 constant. Constants are defined globally through the variable
1399 @code{org-table-formula-constants}. If you have the
1400 @file{constants.el} package, it will also be used to resolve
1401 constants, including natural constants like @samp{$h} for Planck's
1402 constant, and units like @samp{$km} for kilometers. Column names and
1403 parameters can be specified in special table lines. These are
1404 described below, see @ref{Advanced features}.
1406 @cindex format specifier
1407 @cindex mode, for @file{calc}
1408 A formula can contain an optional mode string after a semicolon. This
1409 string consists of flags to influence calc's modes@footnote{By
1410 default, Org-mode uses the standard calc modes (precision 12, angular
1411 units degrees, fraction and symbolic modes off). The display format,
1412 however, has been changed to @code{(float 5)} to keep tables compact.
1413 The default settings can be configured using the variable
1414 @code{org-calc-default-modes}.} during execution, e.g. @samp{p20} to
1415 switch the internal precision to 20 digits, @samp{n3}, @samp{s3},
1416 @samp{e2} or @samp{f4} to switch to normal, scientific, engineering,
1417 or fixed display format, respectively, and @samp{D}, @samp{R}, @samp{F},
1418 and @samp{S} to turn on degrees, radians, fraction and symbolic modes,
1419 respectively. In addition, you may provide a @code{printf} format
1420 specifier to reformat the final result. A few examples:
1423 $1+$2 @r{Sum of first and second field}
1424 $1+$2;%.2f @r{Same, format result to two decimals}
1425 exp($2)+exp($1) @r{Math functions can be used}
1426 $;%.1f @r{Reformat current cell to 1 decimal}
1427 ($3-32)*5/9 @r{Degrees F -> C conversion}
1428 $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
1429 tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
1430 sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
1431 vmean($2..$7) @r{Compute column range mean, using vector function}
1432 vsum(&III) @r{Sum numbers from 3rd hline above, up to here}
1433 taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree}
1436 @node Lisp formulas, Column formulas, Formula syntax, Table calculations
1437 @subsection Emacs Lisp forms as formulas
1438 @cindex Lisp forms, as table formulas
1440 It is also possible to write a formula in Emacs lisp; this can be useful
1441 for string manipulation and control structures. If a formula starts
1442 with a single quote followed by an opening parenthesis, then it is
1443 evaluated as a lisp form. The evaluation should return either a string
1444 or a number. Just as with @file{calc} formulas, you can provide a
1445 format specifier after a semicolon. A few examples:
1448 @r{swap the first two characters of the content of column 1}
1449 '(concat (substring "$1" 1 2) (substring "$1" 0 1) (substring "$1" 2))
1450 @r{Add columns 1 and 2, equivalent to the calc's @code{$1+$2}}
1454 @node Column formulas, Advanced features, Lisp formulas, Table calculations
1455 @subsection Column formulas
1456 @cindex column formula
1457 @cindex formula, for table column
1459 To apply a formula to a field, type it directly into the field,
1460 preceded by an equal sign, like @samp{=$1+$2}. When you press
1461 @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the
1462 field, the formula will be stored as the formula for the current
1463 column, evaluated and the current field replaced with the result. If
1464 the field contains only @samp{=}, the previously stored formula for
1465 this column is used.
1467 For each column, Org-mode will remember the most recently used
1468 formula. The information is stored in a special line starting with
1469 @samp{#+TBLFM} directly below the table. When adding/deleting/moving
1470 columns with the appropriate commands, the stored equations will be
1471 modified accordingly. When a column used in a calculation is removed,
1472 references to this column become invalid and will cause an error upon
1473 applying the equation.
1475 Instead of typing an equation into the field, you may also use the
1476 command @kbd{C-c =}. It prompts for a formula (with default taken
1477 from the @samp{#+TBLFM:} line) and applies it to the current field. A
1478 numerical prefix (e.g. @kbd{C-5 C-c =}) will apply it to that many
1479 consecutive fields in the current column.
1481 @cindex recomputing table fields
1482 To recompute all the fields in a line, use the command @kbd{C-c *}.
1483 It re-applies all stored equations to the current row, from left to
1484 right. With a @kbd{C-u} prefix, this will be done to every line in
1485 the table, so use this command it you want to make sure the entire
1486 table is up-to-date. @kbd{C-u C-c C-c} is another way to update the
1487 entire table. Global updating does not touch the line(s) above the
1488 first horizontal separator line, assuming that this is the table
1491 @node Advanced features, Named-field formulas, Column formulas, Table calculations
1492 @subsection Advanced features
1494 If you want the recalculation of fields to happen automatically,
1495 or if you want to be able to assign a formula to an individual field
1496 (instead of an entire column) you need to reserve the first column of
1497 the table for special marking characters. Here is an example of a
1498 table that collects exam results of students and makes use of these
1503 |---+---------+--------+--------+--------+-------+------|
1504 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1505 |---+---------+--------+--------+--------+-------+------|
1506 | ! | | P1 | P2 | P3 | Tot | |
1507 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
1508 | ^ | | m1 | m2 | m3 | mt | |
1509 |---+---------+--------+--------+--------+-------+------|
1510 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
1511 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
1512 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
1513 |---+---------+--------+--------+--------+-------+------|
1514 | | Average | | | | 29.7 | |
1515 | ^ | | | | | at | |
1516 | $ | max=50 | | | | | |
1517 |---+---------+--------+--------+--------+-------+------|
1518 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(&II);%.1f
1522 @noindent @b{Important}: Please note that for these special tables,
1523 recalculating the table with @kbd{C-u C-c *} will only affect rows
1524 that are marked @samp{#} or @samp{*}, and named fields. The column
1525 formulas are not applied in rows with empty first field.
1527 @cindex marking characters, tables
1528 The marking characters have the following meaning:
1531 The fields in this line define names for the columns, so that you may
1532 refer to a column as @samp{$Tot} instead of @samp{$6}.
1534 This row defines names for the fields @emph{above} the row. With such
1535 a definition, any formula in the table may use @samp{$m1} to refer to
1536 the value @samp{10}. Also, named fields can have their own formula
1537 associated with them.
1539 Similar to @samp{^}, but defines names for the fields in the row
1542 Fields in this row can define @emph{parameters} for formulas. For
1543 example, if a field in a @samp{$} row contains @samp{max=50}, then
1544 formulas in this table can refer to the value 50 using @samp{$max}.
1545 Parameters work exactly like constants, only that they can be defined on
1546 a per-table basis. Changing a parameter and then recalculating the
1547 table can be useful.
1549 Fields in this row are automatically recalculated when pressing
1550 @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
1551 is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
1552 lines will be left alone by this command.
1554 Selects this line for global recalculation with @kbd{C-u C-c *}, but
1555 not for automatic recalculation. Use this when automatic
1556 recalculation slows down editing too much.
1558 Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
1559 All lines that should be recalculated should be marked with @samp{#}
1563 @node Named-field formulas, Editing/debugging formulas, Advanced features, Table calculations
1564 @subsection Named-field formulas
1565 @cindex named field formula
1566 @cindex formula, for named table field
1568 A named field can have its own formula associated with it. In the
1569 example above, this is used for the @samp{at} field that contains
1570 the average result of the students. To enter a formula for a named
1571 field, just type it into the buffer, preceded by @samp{:=}. Or use
1572 @kbd{C-u C-c =}. This equation will be stored below the table like
1573 @samp{$name=...}. Any recalculation in the table (even if only
1574 requested for the current line) will also update all named field
1577 @node Editing/debugging formulas, Appetizer, Named-field formulas, Table calculations
1578 @subsection Editing and debugging formulas
1579 @cindex formula editing
1580 @cindex editing, of table formulas
1582 To edit a column or field formula, use the commands @kbd{C-c
1583 =} and @kbd{C-u C-c =}, respectively. The currently active expression
1584 is then presented as default in the minibuffer, where it may be edited.
1586 Note that making a table field blank does not remove the formula
1587 associated with the field - during the next recalculation the field
1588 will be filled again. To remove a formula from a field, you have to
1589 give an empty reply when prompted for the formula, or to edit the
1590 @samp{#+TBLFM} line.
1593 You may edit the @samp{#+TBLFM} directly and re-apply
1594 the changed equations with @kbd{C-c C-c} in that line, or with the
1595 normal recalculation commands in the table.
1601 In particular for large tables with many formulas, it is convenient to
1602 use the command @kbd{C-c '} to edit the formulas of the current table
1603 in a separate buffer. That buffer will show the formulas one per
1604 line, and you are free to edit, add and remove formulas. Press
1605 @kbd{C-c ?} on a @samp{$...} expression to get information about its
1606 interpretation. Exiting the buffer with @kbd{C-c C-c} only stores the
1607 modified formulas below the table. Exiting with @kbd{C-u C-c C-c}
1608 also applies them to the entire table. @kbd{C-c C-q} exits without
1609 installing the changes.
1611 When the evaluation of a formula leads to an error, the field content
1612 becomes the string @samp{#ERROR}. If you would like see what is going
1613 on during variable substitution and calculation in order to find a
1614 bug, turn on formula debugging in the menu and repeat the calculation,
1615 for example by pressing @kbd{C-c = @key{RET}} in a field.
1616 Detailed information will be displayed.
1618 @node Appetizer, , Editing/debugging formulas, Table calculations
1619 @subsection Appetizer
1621 Finally, just to whet your appetite on what can be done with the fantastic
1622 @file{calc} package, here is a table that computes the Taylor series
1623 for a couple of functions (homework: try that with Excel :-)
1627 |---+-------------+---+-----+--------------------------------------|
1628 | | Func | n | x | Result |
1629 |---+-------------+---+-----+--------------------------------------|
1630 | # | exp(x) | 1 | x | 1 + x |
1631 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
1632 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
1633 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1634 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
1635 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
1636 |---+-------------+---+-----+--------------------------------------|
1637 #+TBLFM: $5=taylor($2,$4,$3);n3
1641 @node orgtbl-mode, table.el, Table calculations, Tables
1642 @section The Orgtbl minor mode
1644 @cindex minor mode for tables
1646 If you like the intuitive way the Org-mode table editor works, you
1647 might also want to use it in other modes like text-mode or mail-mode.
1648 The minor mode Orgtbl-mode makes this possible. You can always toggle
1649 the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for
1650 example in mail mode, use
1653 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1656 @node table.el, , orgtbl-mode, Tables
1657 @section The @file{table.el} package
1659 @cindex table editor, @file{table.el}
1660 @cindex @file{table.el}
1662 Complex ASCII tables with automatic line wrapping, column- and
1663 row-spanning, and alignment can be created using the Emacs table
1664 package by Takaaki Ota (@uref{http://sourceforge.net/projects/table},
1665 and also part of Emacs 22).
1666 When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org-mode
1667 will call @command{table-recognize-table} and move the cursor into the
1668 table. Inside a table, the keymap of Org-mode is inactive. In order
1669 to execute Org-mode-related commands, leave the table.
1674 Recognize @file{table.el} table. Works when the cursor is in a
1679 Insert a table.el table. If there is already a table at point, this
1680 command converts it between the table.el format and the Org-mode
1681 format. See the documentation string of the command
1682 @code{org-convert-table} for the restrictions under which this is
1686 @node Hyperlinks, TODO items, Tables, Top
1690 Just like HTML, Org-mode provides links inside a file, and external
1691 links to other files, Usenet articles, emails, and much more.
1694 * Link format:: How links in Org-mode are formatted
1695 * Internal links:: Links to other places in the current file
1696 * External links:: URL-like links to the world
1697 * Handling links:: Creating, inserting and following
1698 * Link abbreviations:: Shortcuts for writing complex links
1699 * Search options:: Linking to a specific location
1700 * Custom searches:: When the default search is not enough
1701 * Remember:: Org-trees store quick notes
1704 @node Link format, Internal links, Hyperlinks, Hyperlinks
1705 @section Link format
1707 @cindex format, of links
1709 Org-mode will recognize plain URL-like links and activate them as
1710 clickable links. The general link format, however, looks like this:
1713 [[link][description]] @r{or alternatively} [[link]]
1716 Once a link in the buffer is complete (all brackets present), Org-mode
1717 will change the display so that @samp{description} is displayed instead
1718 of @samp{[[link][description]]} and @samp{link} is displayed instead of
1719 @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
1720 which by default is an underlined face. You can directly edit the
1721 visible part of a link. Note that this can be either the @samp{link}
1722 part (if there is no description) or the @samp{description} part. To
1723 edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
1726 If you place the cursor at the beginning or just behind the end of the
1727 displayed text and press @key{BACKSPACE}, you will remove the
1728 (invisible) bracket at that location. This makes the link incomplete
1729 and the internals are again displayed as plain text. Inserting the
1730 missing bracket hides the link internals again. To show the
1731 internal structure of all links, use the menu entry
1732 @code{Org->Hyperlinks->Literal links}.
1734 @node Internal links, External links, Link format, Hyperlinks
1735 @section Internal links
1736 @cindex internal links
1737 @cindex links, internal
1738 @cindex CamelCase links
1739 @cindex targets, for links
1741 If the link does not look like a URL, it is considered to be internal in
1742 the current file. Links such as @samp{[[My Target]]} or @samp{[[My
1743 Target][Find my target]]} lead to a text search in the current file.
1744 The link can be followed with @kbd{C-c C-o} when the cursor is on the
1745 link, or with a mouse click (@pxref{Handling links}). The preferred
1746 match for such a link is a dedicated target: the same string in double
1747 angular brackets. Targets may be located anywhere; often it is
1748 convenient to put them into a comment line. For example
1754 @noindent In HTML export (@pxref{HTML export}), such targets will become
1755 named anchors for direct access through @samp{http} links@footnote{Note
1756 that text before the first headline will never be exported, so the first
1757 such target must be after the first headline.}.
1759 If no dedicated target exists, Org-mode will search for the words in the
1760 link. In the above example the search would be for @samp{my target}.
1761 Links starting with a star like @samp{*My Target} restrict the search to
1762 headlines. When searching, Org-mode will first try an exact match, but
1763 then move on to more and more lenient searches. For example, the link
1764 @samp{[[*My Targets]]} will find any of the following:
1768 ** TODO my targets are bright
1769 ** my 20 targets are
1772 To insert a link targeting a headline, in-buffer completion can be used.
1773 Just type a star followed by a few optional letters into the buffer and
1774 press @kbd{M-@key{TAB}}. All headlines in the current buffer will be
1775 offered as completions. @xref{Handling links}, for more commands
1778 Following a link pushes a mark onto Org-mode's own mark ring. You can
1779 return to the previous position with @kbd{C-c &}. Using this command
1780 several times in direct succession goes back to positions recorded
1784 * Radio targets:: Make targets trigger links in plain text.
1785 * CamelCase links:: Activating CamelCase words as links
1788 @node Radio targets, CamelCase links, Internal links, Internal links
1789 @subsection Radio targets
1790 @cindex radio targets
1791 @cindex targets, radio
1792 @cindex links, radio targets
1794 You can configure Org-mode to link any occurrences of certain target
1795 names in normal text. So without explicitly creating a link, the text
1796 connects to the target radioing its position. Radio targets are
1797 enclosed by triple angular brackets. For example, a target
1798 @samp{<<<My Target>>>} causes each occurrence of @samp{my target} in
1799 normal text to become activated as a link. The Org-mode file is
1800 scanned automatically for radio targets only when the file is first
1801 loaded into Emacs. To update the target list during editing, press
1802 @kbd{C-c C-c} with the cursor on or at a target.
1804 @node CamelCase links, , Radio targets, Internal links
1805 @subsection CamelCase words as links
1806 @cindex completion, of CamelCase links
1807 @cindex CamelCase links, completion of
1809 Org-mode also supports CamelCase words as links. This feature is not
1810 turned on by default because of the inconsistencies this system suffers
1811 from. It is also possible that this feature will disappear entirely in
1812 a future version of Org-mode. To activate CamelCase words as links, you
1813 need to customize the option @code{org-activate-links}. A CamelCase
1814 word then leads to a text search such that @samp{CamelCaseLink} is
1815 equivalent to @samp{[[camel case link]]}.
1817 @node External links, Handling links, Internal links, Hyperlinks
1818 @section External links
1819 @cindex links, external
1820 @cindex external links
1821 @cindex links, external
1828 @cindex WANDERLUST links
1830 @cindex USENET links
1835 Org-mode supports links to files, websites, Usenet and email messages,
1836 and BBDB database entries. External links are URL-like locators. They
1837 start with a short identifying string followed by a colon. There can be
1838 no space after the colon. The following list shows examples for each
1842 http://www.astro.uva.nl/~dominik @r{on the web}
1843 file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
1844 file:papers/last.pdf @r{file, relative path}
1845 news:comp.emacs @r{Usenet link}
1846 mailto:adent@@galaxy.net @r{Mail link}
1847 vm:folder @r{VM folder link}
1848 vm:folder#id @r{VM message link}
1849 vm://myself@@some.where.org/folder#id @r{VM on remote machine}
1850 wl:folder @r{WANDERLUST folder link}
1851 wl:folder#id @r{WANDERLUST message link}
1852 mhe:folder @r{MH-E folder link}
1853 mhe:folder#id @r{MH-E message link}
1854 rmail:folder @r{RMAIL folder link}
1855 rmail:folder#id @r{RMAIL message link}
1856 gnus:group @r{GNUS group link}
1857 gnus:group#id @r{GNUS article link}
1858 bbdb:Richard Stallman @r{BBDB link}
1859 shell:ls *.org @r{A shell command}
1860 elisp:(find-file-other-frame "Elisp.org") @r{An elisp form to evaluate}
1863 A link should be enclosed in double brackets and may contain a
1864 descriptive text to be displayed instead of the url (@pxref{Link
1865 format}), for example:
1868 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
1872 If the description is a file name or URL that points to an image, HTML
1873 export (@pxref{HTML export}) will inline the image as a clickable
1874 button. If there is no description at all and the link points to an
1876 that image will be inlined into the exported HTML file.
1878 @cindex angular brackets, around links
1879 @cindex plain text external links
1880 Org-mode also finds external links in the normal text and activates them
1881 as links. If spaces must be part of the link (for example in
1882 @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
1883 about the end of the link, enclose them in angular brackets.
1885 @node Handling links, Link abbreviations, External links, Hyperlinks
1886 @section Handling links
1887 @cindex links, handling
1889 Org-mode provides methods to create a link in the correct syntax, to
1890 insert it into an org-mode file, and to follow the link.
1894 @cindex storing links
1896 Store a link to the current location. This is a @emph{global} command
1897 which can be used in any buffer to create a link. The link will be
1898 stored for later insertion into an Org-mode buffer (see below). For
1899 Org-mode files, if there is a @samp{<<target>>} at the cursor, the link
1900 points to the target. Otherwise it points to the current headline. For
1901 VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers, the link will
1902 indicate the current article/entry. For W3 and W3M buffers, the link
1903 goes to the current URL. For any other files, the link will point to
1904 the file, with a search string (@pxref{Search options}) pointing to the
1905 contents of the current line. If there is an active region, the
1906 selected words will form the basis of the search string. If the
1907 automatically created link is not working correctly or accurately
1908 enough, you can write custom functions to select the search string and
1909 to do the search for particular file types - see @ref{Custom searches}.
1910 The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}.
1913 @cindex link completion
1914 @cindex completion, of links
1915 @cindex inserting links
1917 Insert a link. This prompts for a link to be inserted into the buffer.
1918 You can just type a link, using text for an internal link, or one of the
1919 link type prefixes mentioned in the examples above. Through completion,
1920 all links stored during the current session can be
1921 accessed@footnote{After insertion of a stored link, the link will be
1922 removed from the list of stored links. To keep it in the list later
1923 use, use a triple @kbd{C-u} prefix to @kbd{C-c C-l}, or configure the
1924 option @code{org-keep-stored-link-after-insertion}.}. The link
1925 will be inserted into the buffer, along with a descriptive text. Note
1926 that you don't have to use this command to insert a link. Links in
1927 Org-mode are plain text, and you can type or paste them straight into
1928 the buffer. By using this command, the links are automatically enclosed
1929 in double brackets, and you will be asked for the optional descriptive
1930 text. If the link is a @samp{file:} link and the linked file is located
1931 in the same directory as the current file or a subdirectory of it, the
1932 path of the file will be inserted relative to the current directory.
1935 @cindex file name completion
1936 @cindex completion, of file names
1938 When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
1939 a file will be inserted and you may use file name completion to select
1940 the name of the file. The path to the file is inserted relative to the
1941 directory of the current org file, if the linked file is in the current
1942 directory or in a subdirectory of it, or if the path is written relative
1943 to the current directory using @samp{../}. Otherwise an absolute path
1944 is used, if possible with @samp{~/} for your home directory. You can
1945 force an absolute path with two @kbd{C-u} prefixes.
1947 @item C-c C-l @r{with cursor on existing link}
1948 When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
1949 link and description parts of the link.
1951 @cindex following links
1954 Open link at point. This will launch a web browser for URLs (using
1955 @command{browse-url-at-point}), run vm/mh-e/wanderlust/rmail/gnus/bbdb
1956 for the corresponding links, and execute the command in a shell link.
1957 When the cursor is on an internal link, this commands runs the
1958 corresponding search. When the cursor is on a TAG list in a headline,
1959 it creates the corresponding TAGS view. If the cursor is on a time
1960 stamp, it compiles the agenda for that date. Furthermore, it will visit
1961 text and remote files in @samp{file:} links with Emacs and select a
1962 suitable application for local non-text files. Classification of files
1963 is based on file extension only. See option @code{org-file-apps}. If
1964 you want to override the default application and visit the file with
1965 Emacs, use a @kbd{C-u} prefix.
1971 On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o}
1972 would. Under Emacs 22, also @kbd{mouse-1} will follow a link.
1976 Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
1977 internal links to be displayed in another window@footnote{See the
1978 variable @code{org-display-internal-link-with-indirect-buffer}}.
1983 Push the current position onto the mark ring, to be able to return
1984 easily. Commands following an internal link do this automatically.
1986 @cindex links, returning to
1989 Jump back to a recorded position. A position is recorded by the
1990 commands following internal links, and by @kbd{C-c %}. Using this
1991 command several times in direct succession moves through a ring of
1992 previously recorded positions.
1995 @node Link abbreviations, Search options, Handling links, Hyperlinks
1996 @section Link abbreviatons
1997 @cindex link abbreviations
1998 @cindex abbreviation, links
2000 Long URLs can be cumbersome to type, and often many similar links are
2001 needed in a document. For this you can use link abbreviations. An
2002 abbreviated link looks like this
2005 [[linkword::tag][description]]
2009 where the tag is optional. Such abbreviations are resolved according to
2010 the information in the variable @code{org-link-abbrev-alist} that
2011 relates the linkwords to replacement text. Here is an example:
2015 (setq org-link-abbrev-alist
2016 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
2017 ("google" . "http://www.google.com/search?q=")
2018 ("ads" . "http://adsabs.harvard.edu/cgi-bin/
2019 nph-abs_connect?author=%s&db_key=AST")))
2023 If the replacement text contains the string @samp{%s}, it will be
2024 replaced with the tag. Otherwise the tag will be appended to the string
2025 in order to create the link. You may also specify a function that will
2026 be called with the tag as the only argument to create the link.
2028 With the above setting, you could link to a specific bug with
2029 @code{[[bugzilla::129]]}, search the web for OrgMode with
2030 @code{[[google::OrgMode]]} and find out what the Org-mode author is
2031 doing besides Emacs hacking with @code{[[ads::Dominik,C]]}.
2033 If you need special abbreviations just for a single Org-mode buffer, you
2034 can define them in the file with
2037 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
2038 #+LINK: google http://www.google.com/search?q=%s
2042 In-buffer completion @pxref{Completion} can be used after @samp{[} to
2043 complete link abbreviations.
2045 @node Search options, Custom searches, Link abbreviations, Hyperlinks
2046 @section Search options in file links
2047 @cindex search option in file links
2048 @cindex file links, searching
2050 File links can contain additional information to make Emacs jump to a
2051 particular location in the file when following a link. This can be a
2052 line number or a search option after a double@footnote{For backward
2053 compatibility, line numbers can also follow a single colon.} colon. For
2054 example, when the command @kbd{C-c l} creates a link (@pxref{Handling
2055 links}) to a file, it encodes the words in the current line as a search
2056 string that can be used to find this line back later when following the
2057 link with @kbd{C-c C-o}.
2059 Here is the syntax of the different ways to attach a search to a file
2060 link, together with an explanation:
2063 [[file:~/code/main.c::255]]
2064 [[file:~/xx.org::My Target]]
2065 [[file:~/xx.org::*My Target]]
2066 [[file:~/xx.org::/regexp/]]
2073 Search for a link target @samp{<<My Target>>}, or do a text search for
2074 @samp{my target}, similar to the search in internal links, see
2075 @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
2076 link will become an HTML reference to the corresponding named anchor in
2079 In an Org-mode file, restrict search to headlines.
2081 Do a regular expression search for @code{regexp}. This uses the Emacs
2082 command @code{occur} to list all matches in a separate window. If the
2083 target file is in Org-mode, @code{org-occur} is used to create a
2084 sparse tree with the matches.
2085 @c If the target file is a directory,
2086 @c @code{grep} will be used to search all files in the directory.
2089 As a degenerate case, a file link with an empty file name can be used
2090 to search the current file. For example, @code{[[file:::find me]]} does
2091 a search for @samp{find me} in the current file, just as
2092 @samp{[[find me]]} would.
2094 @node Custom searches, Remember, Search options, Hyperlinks
2095 @section Custom Searches
2096 @cindex custom search strings
2097 @cindex search strings, custom
2099 The default mechanism for creating search strings and for doing the
2100 actual search related to a file link may not work correctly in all
2101 cases. For example, BibTeX database files have many entries like
2102 @samp{year="1993"} which would not result in good search strings,
2103 because the only unique identification for a BibTeX entry is the
2106 If you come across such a problem, you can write custom functions to set
2107 the right search string for a particular file type, and to do the search
2108 for the string in the file. Using @code{add-hook}, these functions need
2109 to be added to the hook variables
2110 @code{org-create-file-search-functions} and
2111 @code{org-execute-file-search-functions}. See the docstring for these
2112 variables for more information. Org-mode actually uses this mechanism
2113 for Bib@TeX{} database files, and you can use the corresponding code as
2114 an implementation example. Search for @samp{BibTeX links} in the source
2118 @node Remember, , Custom searches, Hyperlinks
2120 @cindex @file{remember.el}
2122 Another way to create org entries with links to other files is through
2123 the @emph{Remember} package by John Wiegley. @emph{Remember} lets you
2124 store quick notes with little interruption of your work flow. See
2125 @uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more
2126 information. The notes produced by @emph{Remember} can be stored in
2127 different ways, and Org-mode files are a good target. Org-mode allows
2128 you to file away notes either to a default file, or directly to the correct
2129 location in your Org-mode outline tree. The following customization
2130 will tell @emph{Remember} to use org files as target, and to create
2131 annotations compatible with Org-mode links.
2134 (setq org-directory "~/path/to/my/orgfiles/")
2135 (setq org-default-notes-file "~/.notes")
2136 (setq remember-annotation-functions '(org-remember-annotation))
2137 (setq remember-handler-functions '(org-remember-handler))
2138 (add-hook 'remember-mode-hook 'org-remember-apply-template)
2141 @cindex templates, for remember
2142 In combination with Org-mode, you can use templates to generate
2143 different types of remember notes. For example, if you would like to
2144 use one template to create general TODO entries, and another one for
2145 journal entries, you could use:
2148 (setq org-remember-templates
2149 '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org")
2150 (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")))
2153 @noindent In these entries, the character specifies how to select the
2154 template, the first string specifies the template, and the (optional)
2155 second string specifies a default file (overruling
2156 @code{org-default-notes-file}) as a target for this note.
2158 When you call @kbd{M-x remember} to remember something, org will prompt
2159 for a key to select the template and then prepare the buffer like
2162 [[file:link to where you called remember]]
2168 * [2006-03-21 Tue 15:37]
2170 [[file:link to where you called remember]]
2173 @noindent See the variable @code{org-remember-templates} for more details.
2175 When you are finished composing a note with remember, you have to press
2176 @kbd{C-c C-c} to file the note away. The handler first prompts for a
2177 target file - if you press @key{RET}, the value of
2178 @code{org-default-notes-file} is used. Then the command offers the
2179 headings tree of the selected file. You can either immediately press
2180 @key{RET} to get the note appended to the file. Or you can use vertical
2181 cursor motion (@key{up} and @key{down}) and visibility cycling
2182 (@key{TAB}) to find a better place. Pressing @key{RET} or @key{left} or
2183 @key{right} leads to the following result.
2185 @multitable @columnfractions 0.2 0.1 0.7
2186 @item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted}
2187 @item buffer-start @tab @key{RET} @tab as level 2 heading at end of file
2188 @item on headline @tab @key{RET} @tab as sublevel of the heading at cursor
2189 @item @tab @key{left} @tab as same level, before current heading
2190 @item @tab @key{right} @tab as same level, after current heading
2191 @item not on headline @tab @key{RET}
2192 @tab at cursor position, level taken from context.
2193 Or use prefix arg to specify level manually.
2196 So a fast way to store the note is to press @kbd{C-c C-c @key{RET}
2197 @key{RET}} to append it to the default file. Even shorter would be
2198 @kbd{C-u C-c C-c}, which does the same without even showing the tree.
2199 But with little extra effort, you can push it directly to the correct
2202 Before inserting the text into a tree, the function ensures that the
2203 text has a headline, i.e. a first line that starts with a @samp{*}.
2204 If not, a headline is constructed from the current date and some
2205 additional data. If the variable @code{org-adapt-indentation} is
2206 non-nil, the entire text is also indented so that it starts in the
2207 same column as the headline (after the asterisks).
2210 @node TODO items, Timestamps, Hyperlinks, Top
2214 Org-mode does not maintain TODO lists as a separate document. TODO
2215 items are an integral part of the notes file, because TODO items
2216 usually come up while taking notes! With Org-mode, you simply mark
2217 any entry in a tree as being a TODO item. In this way, the
2218 information is not duplicated, and the entire context from which the
2219 item emerged is always present when you check.
2221 Of course, this technique causes TODO items to be scattered throughout
2222 your file. Org-mode provides methods to give you an overview over all
2223 things you have to do.
2226 * TODO basics:: Marking and displaying TODO entries
2227 * TODO extensions:: Workflow and assignments
2228 * Priorities:: Some things are more important than others
2229 * Breaking down tasks:: Splitting a task into managable pieces
2230 * Checkboxes:: Tick-off lists
2233 @node TODO basics, TODO extensions, TODO items, TODO items
2234 @section Basic TODO functionality
2236 Any headline can become a TODO item by starting it with the word TODO,
2240 *** TODO Write letter to Sam Fortune
2244 The most important commands to work with TODO entries are:
2248 @cindex cycling, of TODO states
2250 Rotate the TODO state of the current item between
2253 ,-> (unmarked) -> TODO -> DONE --.
2254 '--------------------------------'
2257 The same rotation can also be done ``remotely'' from the timeline and
2258 agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}).
2259 @kindex S-@key{right}
2260 @kindex S-@key{left}
2263 Select the following/preceding TODO state, similar to cycling. Mostly
2264 useful if more than two TODO states are possible (@pxref{TODO extensions}).
2266 @cindex sparse tree, for TODO
2268 View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds
2269 the entire buffer, but shows all TODO items and the headings hierarchy
2270 above them. With prefix arg, show also the DONE entries. With
2271 numerical prefix N, show the tree for the Nth keyword in the variable
2272 @code{org-todo-keywords}.
2275 Show the global TODO list. This collects the TODO items from all
2276 agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in
2277 @code{agenda-mode}, so there are commands to examine and manipulate
2278 the TODO entries directly from that buffer (@pxref{Agenda commands}).
2279 @xref{Global TODO list}, for more information.
2280 @c @item @code{org-agenda-include-all-todo}
2281 @c If you would like to have all your TODO items listed as part of your
2282 @c agenda, customize the variable @code{org-agenda-include-all-todo}.
2286 @node TODO extensions, Priorities, TODO basics, TODO items
2287 @section Extended use of TODO keywords
2288 @cindex extended TODO keywords
2290 The default implementation of TODO entries is just two states: TODO and
2291 DONE. You can, however, use the TODO feature for more complicated
2292 things by configuring the variables @code{org-todo-keywords} and
2293 @code{org-todo-interpretation}. Using special setup, you can even use
2294 TODO keywords in different ways in different org files.
2296 Note that @i{tags} are another way to classify headlines in general and
2297 TODO items in particular (@pxref{Tags}).
2300 * Workflow states:: From TODO to DONE in steps
2301 * TODO types:: I do this, Fred the rest
2302 * Per file keywords:: Different files, different requirements
2305 @node Workflow states, TODO types, TODO extensions, TODO extensions
2306 @subsection TODO keywords as workflow states
2307 @cindex TODO workflow
2308 @cindex workflow states as TODO keywords
2310 You can use TODO keywords to indicate different states in the process
2311 of working on an item, for example:
2314 (setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE")
2315 org-todo-interpretation 'sequence)
2318 @cindex completion, of TODO keywords
2319 Changing these variables only becomes effective in a new Emacs session.
2320 With this setup, the command @kbd{C-c C-t} will cycle an entry from
2321 TODO to FEEDBACK, then to VERIFY, and finally to DONE. You may also
2322 use a prefix argument to quickly select a specific state. For example
2323 @kbd{C-3 C-c C-t} will change the state immediately to VERIFY.
2324 If you define many keywords, you can use in-buffer completion (see
2325 @ref{Completion}) to insert these words into the buffer. Changing a todo
2326 state can be logged with a timestamp, see @ref{Tracking TODO state
2327 changes} for more information.
2329 @node TODO types, Per file keywords, Workflow states, TODO extensions
2330 @subsection TODO keywords as types
2332 @cindex names as TODO keywords
2333 @cindex types as TODO keywords
2335 The second possibility is to use TODO keywords to indicate different
2336 types of action items. For example, you might want to indicate that
2337 items are for ``work'' or ``home''. If you are into David Allen's
2338 @emph{Getting Things DONE}, you might want to use todo types
2339 @samp{NEXTACTION}, @samp{WAITING}, @samp{MAYBE}. Or, when you work
2340 with several people on a single project, you might want to assign
2341 action items directly to persons, by using their names as TODO
2342 keywords. This would be set up like this:
2345 (setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE")
2346 org-todo-interpretation 'type)
2349 In this case, different keywords do not indicate a sequence, but
2350 rather different types. So it is normally not useful to change from
2351 one type to another. Therefore, in this case the behavior of the
2352 command @kbd{C-c C-t} is changed slightly@footnote{This is also true
2353 for the @kbd{t} command in the timeline and agenda buffers.}. When
2354 used several times in succession, it will still cycle through all
2355 names. But when you return to the item after some time and execute
2356 @kbd{C-c C-t} again, it will switch from each name directly to DONE.
2357 Use prefix arguments or completion to quickly select a specific name.
2358 You can also review the items of a specific TODO type in a sparse tree
2359 by using a numeric prefix to @kbd{C-c C-v}. For example, to see all
2360 things Lucy has to do, you would use @kbd{C-3 C-c C-v}. To collect
2361 Lucy's items from all agenda files into a single buffer, you
2362 would use the prefix arg as well when creating the global todo list:
2365 @node Per file keywords, , TODO types, TODO extensions
2366 @subsection Setting up TODO keywords for individual files
2367 @cindex keyword options
2368 @cindex per file keywords
2370 It can be very useful to use different aspects of the TODO mechanism
2371 in different files, which is not possible with the global settings
2372 described above. For file-local settings, you need to add special
2373 lines to the file which set the keywords and interpretation for that
2374 file only. For example, to set one of the two examples discussed
2375 above, you need one of the following lines, starting in column zero
2376 anywhere in the file:
2379 #+SEQ_TODO: TODO FEEDBACK VERIFY DONE
2380 #+TYP_TODO: Fred Sara Lucy Mike DONE
2383 @cindex Completion, of option keywords
2385 @noindent To make sure you are using the correct keyword, type
2386 @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
2388 @cindex DONE, final TODO keyword
2389 Remember that the last keyword must always mean that the item is DONE
2390 (although you may use a different word). Also note that in each file,
2391 only one of the two aspects of TODO keywords can be used. After
2392 changing one of these lines, use @kbd{C-c C-c} with the cursor still
2393 in the line to make the changes known to Org-mode@footnote{Org-mode
2394 parses these lines only when Org-mode is activated after visiting a
2395 file. @kbd{C-c C-c} with the cursor in a line starting with @samp{#+}
2396 is simply restarting Org-mode for the current buffer.}.
2398 If you want to use very many keywords, for example when working with a
2399 large group of people, you may split the names over several lines:
2402 #+TYP_TODO: Fred Sara Lucy Mike
2403 #+TYP_TODO: Luis George Jules Jessica
2404 #+TYP_TODO: Kim Arnold Peter
2408 @node Priorities, Breaking down tasks, TODO extensions, TODO items
2412 If you use Org-mode extensively to organize your work, you may end up
2413 with a number of TODO entries so large that you'd like to prioritize
2414 them. This can be done by placing a @emph{priority cookie} into the
2418 *** TODO [#A] Write letter to Sam Fortune
2422 With its standard setup, Org-mode supports priorities @samp{A},
2423 @samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry
2424 without a cookie is treated as priority @samp{B}. Priorities make a
2425 difference only in the agenda (@pxref{Weekly/Daily agenda}).
2430 Set the priority of the current headline. The command prompts for a
2431 priority character @samp{A}, @samp{B} or @samp{C}. When you press
2432 @key{SPC} instead, the priority cookie is removed from the headline.
2433 The priorities can also be changed ``remotely'' from the timeline and
2434 agenda buffer with the @kbd{,} command (@pxref{Agenda commands}).
2437 @kindex S-@key{down}
2440 Increase/decrease priority of current headline. Note that these keys
2441 are also used to modify time stamps (@pxref{Creating timestamps}).
2442 Furthermore, these keys are also used by CUA-mode (@pxref{Conflicts}).
2445 @node Breaking down tasks, Checkboxes, Priorities, TODO items
2446 @section Breaking tasks down into subtasks
2447 @cindex tasks, breaking down
2449 It is often advisable to break down large tasks into smaller, managable
2450 subtasks. You can do this by creating an outline tree below a TODO
2451 item, with detailed subtasks on the tree@footnote{To keep subtasks out
2452 of the global TODO list, see the
2453 @code{org-agenda-todo-list-sublevels}.}. Another possibility is the use
2454 of checkboxes to identify (a hierarchy of) a large number of subtasks
2455 (@pxref{Checkboxes}).
2458 @node Checkboxes, , Breaking down tasks, TODO items
2462 Every item in a plain list (@pxref{Plain lists}) can be made a checkbox
2463 by starting it with the string @samp{[ ]}. This feature is similar to
2464 TODO items (@pxref{TODO items}), but more lightweight. Checkboxes are
2465 not included into the global TODO list, so they are often great to split
2466 a task into a number of simple steps. Or you can use them in a shopping
2467 list. To toggle a checkbox, use @kbd{C-c C-c}, or try Piotr Zielinski's
2468 @file{org-mouse.el}. Here is an example of a checkbox list.
2471 * TODO Organize party [3/6]
2477 - [ ] think about what music to play
2478 - [X] talk to the neighbors
2481 @cindex statistics, for checkboxes
2482 @cindex checkbox statistics
2483 The @samp{[3/6]} and @samp{[1/3]} in the first and second line are
2484 cookies indicating how many checkboxes are present in this entry, and
2485 how many of them have been checked off. This can give you an idea on
2486 how many checkboxes remain, even without opening a folded entry. The
2487 cookies can be placed into a headline or into (the first line of) a
2488 plain list item. Each cookie covers all checkboxes structurally below
2489 that headline/item. You have to insert the cookie yourself by typing
2490 either @samp{[/]} or @samp{[%]}. In the first case you get an @samp{n
2491 out of m} result, in the second case you get information about the
2492 percentage of checkboxes checked (in the above example, this would be
2493 @samp{[50%]} and @samp{[33%], respectively}).
2495 @noindent The following commands work with checkboxes:
2500 Toggle checkbox at point.
2503 Toggle checkbox at point.
2506 If there is an active region, toggle the first checkbox in the region
2507 and set all remaining boxes to the same status as the first. If you
2508 want to toggle all boxes in the region independently, use a prefix
2511 If the cursor is in a headline, toggle checkboxes in the region between
2512 this headline and the next (so @emph{not} the entire subtree).
2514 If there is no active region, just toggle the checkbox at point.
2516 @kindex M-S-@key{RET}
2518 Insert a new item with a checkbox.
2519 This works only if the cursor is already in a plain list item
2520 (@pxref{Plain lists}).
2523 Update the checkbox statistics in the current outline entry. When
2524 called with a @kbd{C-u} prefix, update the entire file. Checkbox
2525 statistic cookies are updated automatically if you toggle checkboxes
2526 with @kbd{C-c C-c} and make new ones with @kbd{M-S-@key{RET}}. If you
2527 delete boxes or add/change them by hand, use this command to get things
2528 back into synch. Or simply toggle any checkbox twice with @kbd{C-c C-c}.
2531 @node Timestamps, Tags, TODO items, Top
2536 Items can be labeled with timestamps to make them useful for project
2540 * Time stamps:: Assigning a time to a tree entry
2541 * Creating timestamps:: Commands which insert timestamps
2542 * Custom time format:: If you cannot work with the ISO format
2543 * Progress logging:: Documenting when what work was done.
2547 @node Time stamps, Creating timestamps, Timestamps, Timestamps
2548 @section Time stamps, deadlines and scheduling
2550 @cindex ranges, time
2555 A time stamp is a specification of a date (possibly with time) in a
2556 special format, either @samp{<2003-09-16 Tue>} or @samp{<2003-09-16 Tue
2557 09:39>}@footnote{This is the standard ISO date/time format. If you
2558 cannot get used to these, see @ref{Custom time format}}. A time stamp
2559 can appear anywhere in the headline or body of an org-tree entry. Its
2560 presence allows entries to be shown on specific dates in the agenda
2561 (@pxref{Weekly/Daily agenda}). We distinguish:
2564 @item Plain time stamp
2566 A simple time stamp just assigns a date/time to an item. This is just
2567 like writing down an appointment in a paper agenda, or like writing down
2568 an event in a diary, when you want to take note of when something
2569 happened. In the timeline and agenda displays, the headline of an entry
2570 associated with a plain time stamp will be shown exactly on that date.
2573 * Meet Peter at the movies <2006-11-01 Wed 19:15>
2576 @item Inactive time stamp
2577 @cindex timestamp, inactive
2578 @cindex inactive timestamp
2579 Just like a plain time stamp, but with square brackets instead of
2580 angular ones. These time stamps are inactive in the sense that they do
2581 @emph{not} trigger an entry to show up in the agenda.
2584 * Gillian comes late for the fifth time [2006-11-01 Wed]
2587 @item Time stamp range
2589 Two time stamps connected by @samp{--} denote a time range. The
2590 headline will be shown on the first and last day of the range, and on
2591 any dates that are displayed and fall in the range. Here is an
2595 ** Meeting in Amsterdam
2596 <2004-08-23 Mon>--<2004-08-26 Thu>
2599 @item Time stamp with SCHEDULED keyword
2600 @cindex SCHEDULED keyword
2601 If a time stamp is preceded by the word @samp{SCHEDULED:}, it means you
2602 are planning to start working on that task on the given date. So this is
2603 not about recording an event, but about planning your work. The
2604 headline will be listed under the given date@footnote{It will still be
2605 listed on that date after it has been marked DONE. If you don't like
2606 this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
2607 addition, a reminder that the scheduled date has passed will be present
2608 in the compilation for @emph{today}, until the entry is marked DONE.
2609 I.e., the task will automatically be forwarded until completed.
2612 *** TODO Call Trillian for a date on New Years Eve.
2613 SCHEDULED: <2004-12-25 Sat>
2616 @item Time stamp with DEADLINE keyword
2617 @cindex DEADLINE keyword
2618 If a time stamp is preceded by the word @samp{DEADLINE:}, the task
2619 (most likely a TODO item) is supposed to be finished on that date, and
2620 it will be listed then. In addition, the compilation for @emph{today}
2621 will carry a warning about the approaching or missed deadline,
2622 starting @code{org-deadline-warning-days} before the due date, and
2623 continuing until the entry is marked DONE. An example:
2626 *** TODO write article about the Earth for the Guide
2627 The editor in charge is [[bbdb:Ford Prefect]]
2628 DEADLINE: <2004-02-29 Sun>
2630 @item Time stamp with CLOSED keyword
2631 @cindex CLOSED keyword
2632 When @code{org-log-done} is non-nil, Org-mode will automatically insert
2633 a special time stamp each time a TODO entry is marked done
2634 (@pxref{Progress logging}). This time stamp is enclosed in square
2635 brackets instead of angular brackets.
2637 @item Time range with CLOCK keyword
2638 @cindex CLOCK keyword
2639 When using the clock to time the work that is being done on specific
2640 items, time ranges preceded by the CLOCK keyword are inserted
2641 automatically into the file. The time stamps are enclosed in square
2642 brackets instead of angular brackets. @xref{Clocking work time}.
2645 @node Creating timestamps, Custom time format, Time stamps, Timestamps
2646 @section Creating timestamps
2647 @cindex creating timestamps
2648 @cindex timestamps, creating
2650 For Org-mode to recognize time stamps, they need to be in the specific
2651 format. All commands listed below produce time stamps in the correct
2657 Prompt for a date and insert a corresponding time stamp. When the
2658 cursor is at a previously used time stamp, it is updated to NOW. When
2659 this command is used twice in succession, a time range is inserted.
2663 Like @kbd{C-c .}, but use the alternative format which contains date
2664 and time. The default time can be rounded to multiples of 5 minutes,
2665 see the option @code{org-time-stamp-rounding-minutes}.
2669 Like @kbd{C-c .}, but insert an inactive time stamp not triggering the
2674 Insert a time stamp corresponding to the cursor date in the Calendar.
2678 Access the Emacs calendar for the current date. If there is a
2679 timestamp in the current line, goto the corresponding date
2684 Access the agenda for the date given by the time stamp or -range at
2685 point (@pxref{Weekly/Daily agenda}).
2689 Insert @samp{DEADLINE} keyword along with a stamp. The insertion will
2690 happen in the line directly following the headline.
2691 @c FIXME Any CLOSED timestamp will be removed.????????
2694 @cindex sparse tree, for deadlines
2696 Create a sparse tree with all deadlines that are either past-due, or
2697 which will become due within @code{org-deadline-warning-days}.
2698 With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
2699 prefix, check that many days. For example, @kbd{C-1 C-c C-w} shows
2700 all deadlines due tomorrow.
2704 Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will
2705 happen in the line directly following the headline. Any CLOSED
2706 timestamp will be removed.
2708 @kindex S-@key{left}
2709 @kindex S-@key{right}
2711 @itemx S-@key{right}
2712 Change date at cursor by one day. These key bindings conflict with
2713 CUA-mode (@pxref{Conflicts}).
2716 @kindex S-@key{down}
2719 Change the item under the cursor in a timestamp. The cursor can be on a
2720 year, month, day, hour or minute. Note that if the cursor is in a
2721 headline and not at a time stamp, these same keys modify the priority of
2722 an item. (@pxref{Priorities}). The key bindings also conflict with
2723 CUA-mode (@pxref{Conflicts}).
2727 @cindex evaluate time range
2729 Evaluate a time range by computing the difference between start and
2730 end. With prefix arg, insert result after the time range (in a table:
2731 into the following column).
2736 * The date/time prompt:: How org-mode helps you entering date and time
2739 @node The date/time prompt, , Creating timestamps, Creating timestamps
2740 @subsection The date/time prompt
2741 @cindex date, reading in minibuffer
2742 @cindex time, reading in minibuffer
2744 When Org-mode prompts for a date/time, the prompt suggests to enter an
2745 ISO date. But it will in fact accept any string containing some date
2746 and/or time information. You can, for example, use @kbd{C-y} to paste a
2747 (possibly multi-line) string copied from an email message. Org-mode
2748 will find whatever information is in there and will replace anything not
2749 specified with the current date and time. For example:
2752 3-2-5 --> 2003-02-05
2753 feb 15 --> currentyear-02-15
2754 sep 12 9 --> 2009-09-12
2755 12:45 --> today 12:45
2756 22 sept 0:34 --> currentyear-09-22 0:34
2757 12 --> currentyear-currentmonth-12
2758 Fri --> nearest Friday (today or later)
2759 +4 --> 4 days from now (if +N is the only thing given)
2762 The function understands English month and weekday abbreviations. If
2763 you want to use unabbreviated names and/or other languages, configure
2764 the variables @code{parse-time-months} and @code{parse-time-weekdays}.
2766 @cindex calendar, for selecting date
2767 Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
2768 you don't need/want the calendar, configure the variable
2769 @code{org-popup-calendar-for-date-prompt}.}. You can control the
2770 calendar fully from the minibuffer:
2775 Scroll calendar backwards by one month.
2778 Scroll calendar forwards by one month.
2781 Select date by clicking on it.
2782 @kindex S-@key{right}
2785 @kindex S-@key{left}
2788 @kindex S-@key{down}
2794 @kindex M-S-@key{right}
2795 @item M-S-@key{right}
2797 @kindex M-S-@key{left}
2798 @item M-S-@key{left}
2802 Choose date in calendar (only if nothing was typed into minibuffer).
2805 @node Custom time format, Progress logging, Creating timestamps, Timestamps
2806 @section Custom time format
2807 @cindex custom date/time format
2808 @cindex time format, custom
2809 @cindex date format, custom
2811 Org-mode uses the standard ISO notation for dates and times as it is
2812 defined in ISO 8601. If you cannot get used to this and require another
2813 representation of date and time to keep you happy, you can get it by
2814 customizing the variables @code{org-display-custom-times} and
2815 @code{org-time-stamp-custom-formats}.
2820 Toggle the display of custom formats for dates and times.
2824 Org-mode needs the default format for scanning, so the custom date/time
2825 format does not @emph{replace} the default format - instead it is put
2826 @emph{over} the default format using text properties. This has the
2827 following consequences:
2830 You cannot place the cursor onto a time stamp anymore, only before or
2833 The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
2834 each component of a time stamp. If the cursor is at the beginning of
2835 the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
2836 just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the
2837 time will be changed by one minute.
2839 When you delete a time stamp character-by-character, it will only
2840 disappear from the buffer after @emph{all} (invisible) characters
2841 belonging to the ISO timestamp have been removed.
2843 If the custom time stamp format is longer than the default and you are
2844 using dates in tables, table alignment will be messed up. If the custom
2845 format is shorter, things do work as expected.
2848 @node Progress logging, , Custom time format, Timestamps
2849 @section Progress Logging
2850 @cindex progress logging
2851 @cindex logging, of progress
2853 Org-mode can automatically record a time stamp when you mark a TODO item
2854 as DONE, or even each time when you change the state of a TODO item.
2855 You can also measure precisely the time you spent on specific items in a
2856 project by starting and stopping a clock when you start and stop working
2857 on an aspect of a project.
2860 * Closing items:: When was this entry marked DONE?
2861 * Tracking TODO state changes:: When did the status change?
2862 * Clocking work time:: When exactly did you work on this item?
2865 @node Closing items, Tracking TODO state changes, Progress logging, Progress logging
2866 @subsection Closing items
2868 If you want to keep track of @emph{when} a certain TODO item was
2869 finished, turn on logging with@footnote{The corresponding in-buffer
2870 setting is: @code{#+STARTUP: logdone}}
2873 (setq org-log-done t)
2877 Then each time you turn a TODO entry into DONE using either @kbd{C-c
2878 C-t} in the Org-mode buffer or @kbd{t} in the agenda buffer, a line
2879 @samp{CLOSED: [timestamp]} will be inserted just after the headline. If
2880 you turn the entry back into a TODO item through further state cycling,
2881 that line will be removed again. In the timeline (@pxref{Timeline}) and
2882 in the agenda (@pxref{Weekly/Daily agenda}), you can then use the
2883 @kbd{l} key to display the TODO items closed on each day, giving you an
2884 overview of what has been done on a day. If you want to record a note
2885 along with the timestamp, use@footnote{The corresponding in-buffer
2886 setting is: @code{#+STARTUP: lognotedone}}
2889 (setq org-log-done '(done))
2892 @node Tracking TODO state changes, Clocking work time, Closing items, Progress logging
2893 @subsection Tracking TODO state changes
2895 When TODO keywords are used as workflow states (@pxref{Workflow
2896 states}), you might want to keep track of when a state change occurred,
2897 and you may even want to attach notes to that state change. With the
2901 (setq org-log-done '(state))
2905 each state change will prompt you for a note that will be attached to
2906 the current headline. Very likely you do not want this verbose tracking
2907 all the time, so it is probably better to configure this behavior with
2908 in-buffer options. For example, if you are tracking purchases, put
2909 these into a separate file that starts with:
2912 #+SEQ_TODO: TODO ORDERED INVOICE PAYED RECEIVED SENT
2913 #+STARTUP: lognotestate
2916 @node Clocking work time, , Tracking TODO state changes, Progress logging
2917 @subsection Clocking work time
2919 Org-mode allows you to clock the time you spent on specific tasks in a
2920 project. When you start working on an item, you can start the clock.
2921 When you stop working on that task, or when you mark the task done, the
2922 clock is stopped and the corresponding time interval is recorded. It
2923 also computes the total time spent on each subtree of a project.
2928 Start the clock on the current item (clock-in). This inserts the CLOCK
2929 keyword together with a timestamp.
2932 Stop the clock (clock-out). The inserts another timestamp at the same
2933 location where the clock was last started. It also directly computes
2934 the resulting time in inserts it after the time range as @samp{=>
2935 HH:MM}. See the variable @code{org-log-done} for the possibility to
2936 record an additional note together with the clock-out time
2937 stamp@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
2941 Recompute the time interval after changing one of the time stamps. This
2942 is only necessary if you edit the time stamps directly. If you change
2943 them with @kbd{S-@key{cursor}} keys, the update is automatic.
2946 Changing the TODO state of an item to DONE automatically stops the clock
2947 if it is running in this same item.
2950 Cancel the current clock. This is useful if a clock was started by
2951 mistake, or if you ended up working on something else.
2954 Display time summaries for each subtree in the current buffer. This
2955 puts overlays at the end of each headline, showing the total time
2956 recorded under that heading, including the time of any subheadings. You
2957 can use visibility cycling to study the tree, but the overlays disappear
2958 when you change the buffer (see variable
2959 @code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}.
2962 Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
2963 report as an org-mode table into the current file.
2965 #+BEGIN: clocktable :maxlevel 2 :emphasize nil
2970 If such a block already exists, its content is replaced by the new
2971 table. The @samp{BEGIN} line can specify options:
2973 :maxlevels @r{Maximum level depth to which times are listed in the table.}
2974 :emphasize @r{When @code{t}, emphasize level one and level two items}
2975 :block @r{The time block to consider. This block is specified relative}
2976 @r{to the current time and may be any of these keywords:}
2977 @r{@code{today}, @code{yesterday}, @code{thisweek}, @code{lastweek},}
2978 @r{@code{thismonth}, @code{lastmonth}, @code{thisyear}, or @code{lastyear}}.
2979 :tstart @r{A time string specifying when to start considering times}
2980 :tend @r{A time string specifying when to stop considering times}
2982 So to get a clock summary for the current day, you could write
2984 #+BEGIN: clocktable :maxlevel 2 :block today
2988 and to use a specific time range you could write@footnote{Note that all
2989 parameters must be specified in a single line - the line is broken here
2990 only to fit it onto the manual.}
2992 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
2993 :tend "<2006-08-10 Thu 12:00>"
2997 @kindex C-u C-c C-x C-u
2998 @item C-u C-c C-x C-u
2999 Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
3000 you have several clocktable blocks in a buffer.
3003 The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in
3004 the agenda (@pxref{Weekly/Daily agenda}) to show which tasks have been
3005 worked on or closed during a day.
3007 @c @node Self-repeating deadlines
3008 @c @section Self-repeating deadlines
3010 @c Org-mode integrates with the Emacs calendar and diary to display cyclic
3011 @c appointments and anniversaries in the agenda (@pxref{The weekly/daily
3012 @c agenda}). However, it can be useful to have certain deadlines and
3013 @c scheduling items to auto-repeat. The advantage of a deadline or
3014 @c scheduled item is that the they produce warnings ahead of time and
3015 @c automatically forward themselves in the agenda until they are done. The
3016 @c abstract difference is therefore between cyclic @i{appointments} and
3017 @c cyclic @i{action items}. For appointments you should use the diary, for
3018 @c actions you can uses an org-mode deadline or scheduling time stamp
3019 @c together with a REPEAT cookie. For example:
3022 @c * TODO Income tax to IRS REPEAT(+1y)
3023 @c DEADLINE: <2006-12-19 Tue>
3026 @c Each time you try to mark this entry DONE using @kbd{C-c C-t}, it will
3027 @c automatically switch back to the state TODO, and the deadline will be
3028 @c shifted by 1 year.
3030 @node Tags, Agenda views, Timestamps, Top
3033 @cindex headline tagging
3034 @cindex matching, tags
3035 @cindex sparse tree, tag based
3037 If you wish to implement a system of labels and contexts for
3038 cross-correlating information, an excellent way is to assign @i{tags} to
3039 headlines. Org-mode has extensive support for using tags.
3041 Every headline can contain a list of tags, at the end of the headline.
3042 Tags are normal words containing letters, numbers, @samp{_}, and
3043 @samp{@@}. Tags must be preceded and followed by a single colon; like
3044 @samp{:WORK:}. Several tags can be specified like @samp{:WORK:URGENT:}.
3047 * Tag inheritance:: Tags use the tree structure of the outline
3048 * Setting tags:: How to assign tags to a headline
3049 * Tag searches:: Searching for combinations of tags
3052 @node Tag inheritance, Setting tags, Tags, Tags
3053 @section Tag inheritance
3054 @cindex inheritance, of tags
3055 @cindex sublevels, inclusion into tags match
3057 @i{Tags} make use of the hierarchical structure of outline trees. If a
3058 heading has a certain tag, all subheadings will inherit the tag as
3059 well. For example, in the list
3062 * Meeting with the French group :WORK:
3063 ** Summary by Frank :BOSS:NOTES:
3064 *** TODO Prepare slides for him :ACTION:
3068 the final heading will have the tags @samp{:WORK:}, @samp{:BOSS:},
3069 @samp{:NOTES:}, and @samp{:ACTION:}. When executing tag searches and
3070 Org-mode finds that a certain headline matches the search criterion, it
3071 will not check any sublevel headline, assuming that these likely also
3072 match, and that the list of matches can become very long. This may
3073 not be what you want, however, and you can influence inheritance and
3074 searching using the variables @code{org-use-tag-inheritance} and
3075 @code{org-tags-match-list-sublevels}.
3077 @node Setting tags, Tag searches, Tag inheritance, Tags
3078 @section Setting tags
3079 @cindex setting tags
3080 @cindex tags, setting
3083 Tags can simply be typed into the buffer at the end of a headline.
3084 After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
3085 also a special command for inserting tags:
3090 @cindex completion, of tags
3091 Enter new tags for the current headline. Org-mode will either offer
3092 completion or a special single-key interface for setting tags, see
3093 below. After pressing @key{RET}, the tags will be inserted and aligned
3094 to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
3095 tags in the current buffer will be aligned to that column, just to make
3096 things look nice. TAGS are automatically realigned after promotion,
3097 demotion, and TODO state changes (@pxref{TODO basics}).
3100 Org will support tag insertion based on a @emph{list of tags}. By
3101 default this list is constructed dynamically, containing all tags
3102 currently used in the buffer. You may also globally specify a hard list
3103 of tags with the variable @code{org-tag-alist}. Finally you can set
3104 the default tags for a given file with lines like
3107 #+TAGS: @@WORK @@HOME @@TENNISCLUB
3108 #+TAGS: Laptop Car PC Sailboat
3111 If you have globally defined your preferred set of tags using the
3112 variable @code{org-tag-alist}, but would like to use a dynamic tag list
3113 in a specific file: Just add an empty TAGS option line to that file:
3119 The default support method for entering tags is minibuffer completion.
3120 However, Org-mode also implements a much better method: @emph{fast tag
3121 selection}. This method allows to select and deselect tags with a
3122 single key per tag. To function efficiently, you should assign unique
3123 keys to most tags. This can be done globally with
3126 (setq org-tag-alist '(("@@WORK" . ?w) ("@@HOME" . ?h) ("Laptop" . ?l)))
3129 @noindent or on a per-file basis with
3132 #+TAGS: @@WORK(w) @@HOME(h) @@TENNISCLUB(t) Laptop(l) PC(p)
3136 You can also group together tags that are mutually exclusive. With
3137 curly braces@footnote{In @code{org-mode-alist} use
3138 @code{'(:startgroup)} and @code{'(:endgroup)}, respectively. Several
3139 groups are allowed.}
3142 #+TAGS: @{ @@WORK(w) @@HOME(h) @@TENNISCLUB(t) @} Laptop(l) PC(p)
3145 @noindent you indicate that at most one of @samp{@@WORK}, @samp{@@HOME},
3146 and @samp{@@TENNISCLUB} should be selected.
3148 @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
3149 these lines to activate any changes.
3151 If at least one tag has a selection key, pressing @kbd{C-c C-c} will
3152 automatically present you with a special interface, listing inherited
3153 tags, the tags of the current headline, and a list of all legal tags
3154 with corresponding keys@footnote{Keys will automatically be assigned to
3155 tags which have no configured keys.}. In this interface, you can use
3160 Pressing keys assigned to tags will add or remove them from the list of
3161 tags in the current line. Selecting a tag in a group of mutually
3162 exclusive tags will turn off any other tags from that group.
3165 Enter a tag in the minibuffer, even if the tag is not in the predefined
3166 list. You will be able to complete on all tags present in the buffer.
3169 Clear all tags for this line.
3172 Accept the modified set.
3174 Abort without installing changes.
3176 If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
3178 Turn off groups of mutually exclusive tags. Use this to (as an
3179 exception) assign several tags from such a group.
3181 Toggle auto-exit after the next change (see below).
3185 This method lets you assign tags to a headline with very few keys. With
3186 the above setup, you could clear the current tags and set @samp{@@HOME},
3187 @samp{Laptop} and @samp{PC} tags with just the following keys: @kbd{C-c
3188 C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@HOME} to
3189 @samp{@@WORK} would be done with @kbd{C-c C-c w @key{RET}} or
3190 alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
3191 @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
3192 @key{RET} @key{RET}}.
3194 If you find that most of the time, you need only a single keypress to
3195 modify your list of tags, set the variable
3196 @code{org-fast-tag-selection-single-key}. Then you no longer have to
3197 press @key{RET} to exit fast tag selection - it will immediately exit
3198 after the first change. If you then occasionally need more keys, press
3199 @kbd{C-c} to turn off auto-exit for the current tag selection process.
3201 @node Tag searches, , Setting tags, Tags
3202 @section Tag searches
3203 @cindex tag searches
3204 @cindex searching for tags
3206 Once a tags system has been set up, it can be used to collect related
3207 information into special lists.
3212 Create a sparse tree with all headlines matching a tags search. With a
3213 @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
3216 Create a global list of tag matches from all agenda files.
3217 @xref{Matching headline tags}.
3220 Create a global list of tag matches from all agenda files, but check
3221 only TODO items and force checking subitems (see variable
3222 @code{org-tags-match-list-sublevels}).
3225 @cindex Boolean logic, for tag searches
3226 A @i{tags} search string can use Boolean operators @samp{&} for AND and
3227 @samp{|} for OR. @samp{&} binds more strongly than @samp{|}.
3228 Parenthesis are currently not implemented. A tag may also be preceded
3229 by @samp{-}, to select against it, and @samp{+} is syntactic sugar for
3230 positive selection. The AND operator @samp{&} is optional when @samp{+}
3231 or @samp{-} is present. Examples:
3235 Select headlines tagged @samp{:WORK:}, but discard those also tagged
3238 Selects lines tagged @samp{:WORK:} or @samp{:LAPTOP:}.
3239 @item WORK|LAPTOP&NIGHT
3240 Like before, but require the @samp{:LAPTOP:} lines to be tagged also
3244 @cindex TODO keyword matching, with tags search
3245 If you are using multi-state TODO keywords (@pxref{TODO extensions}), it
3246 can be useful to also match on the TODO keyword. This can be done by
3247 adding a condition after a slash to a tags match. The syntax is similar
3248 to the tag matches, but should be applied with consideration: For
3249 example, a positive selection on several TODO keywords can not
3250 meaningfully be combined with boolean AND. However, @emph{negative
3251 selection} combined with AND can be meaningful. To make sure that only
3252 lines are checked that actually have any TODO keyword, use @kbd{C-c a
3253 M}, or equivalently start the todo part after the slash with @samp{!}.
3258 Select @samp{:WORK:}-tagged TODO lines with the specific TODO
3259 keyword @samp{WAITING}.
3260 @item WORK/!-WAITING-NEXT
3261 Select @samp{:WORK:}-tagged TODO lines that are neither @samp{WAITING}
3263 @item WORK/+WAITING|+NEXT
3264 Select @samp{:WORK:}-tagged TODO lines that are either @samp{WAITING} or
3268 @cindex regular expressions, with tags search
3269 Any element of the tag/todo match can be a regular expression - in this
3270 case it must be enclosed in curly braces. For example,
3271 @samp{WORK+@{^BOSS.*@}} matches headlines that contain the tag
3272 @samp{WORK} and any tag @i{starting} with @samp{BOSS}.
3274 @cindex level, require for tags match
3275 You can also require a headline to be of a certain level, by writing
3276 instead of any TAG an expression like @samp{LEVEL=3}. For example, a
3277 search @samp{+LEVEL=3+BOSS/-DONE} lists all level three headlines that
3278 have the tag BOSS and are @emph{not} marked witht the todo keyword DONE.
3280 @node Agenda views, Embedded LaTeX, Tags, Top
3281 @chapter Agenda Views
3282 @cindex agenda views
3284 Due to the way Org-mode works, TODO items, time-stamped items, and
3285 tagged headlines can be scattered throughout a file or even a number of
3286 files. To get an overview over open action items, or over events that
3287 are important for a particular date, this information must be collected,
3288 sorted and displayed in an organized way.
3290 Org-mode can select items based on various criteria, and display them
3291 in a separate buffer. Six different view types are provided:
3295 an @emph{agenda} that is like a calendar and shows information
3298 a @emph{TODO list} that covers all unfinished
3301 a @emph{tags view}, showings headlines based on
3302 the tags associated them,
3304 a @emph{timeline view} that shows all events in a single Org-mode file,
3305 in time-sorted view,
3307 a @emph{stuck projects view} showing projects that currently don't move
3310 @emph{custom views} that are special tag/keyword searches and
3311 combinations of different views.
3315 The extracted information is displayed in a special @emph{agenda
3316 buffer}. This buffer is read-only, but provides commands to visit the
3317 corresponding locations in the original Org-mode files, and even to
3318 edit these files remotely.
3320 Two variables control how the agenda buffer is displayed and whether the
3321 window configuration is restored when the agenda exits:
3322 @code{org-agenda-window-setup} and
3323 @code{org-agenda-restore-windows-after-quit}.
3326 * Agenda files:: Files being searched for agenda information
3327 * Agenda dispatcher:: Keyboard access to agenda views
3328 * Built-in agenda views:: What is available out of the box?
3329 * Presentation and sorting:: How agenda items are prepared for display
3330 * Agenda commands:: Remote editing of org trees
3331 * Custom agenda views:: Defining special searches and views
3334 @node Agenda files, Agenda dispatcher, Agenda views, Agenda views
3335 @section Agenda files
3336 @cindex agenda files
3337 @cindex files for agenda
3339 The information to be shown is collected from all @emph{agenda files},
3340 the files listed in the variable @code{org-agenda-files}@footnote{If the
3341 value of that variable is not a list, but a single file name, then the
3342 list of agenda files will be maintained in that external file.}. Thus even
3343 if you only work with a single Org-mode file, this file should be put
3344 into that list@footnote{When using the dispatcher, pressing @kbd{1}
3345 before selecting a command will actually limit the command to the
3346 current file, and ignore @code{org-agenda-files} until the next
3347 dispatcher command.}. You can customize @code{org-agenda-files}, but
3348 the easiest way to maintain it is through the following commands
3350 @cindex files, adding to agenda list
3354 Add current file to the list of agenda files. The file is added to
3355 the front of the list. If it was already in the list, it is moved to
3356 the front. With prefix arg, file is added/moved to the end.
3359 Remove current file from the list of agenda files.
3362 Cycle through agenda file list, visiting one file after the other.
3366 The Org menu contains the current list of files and can be used
3367 to visit any of them.
3369 @node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda views
3370 @section The agenda dispatcher
3371 @cindex agenda dispatcher
3372 @cindex dispatching agenda commands
3373 The views are created through a dispatcher that should be bound to a
3374 global key, for example @kbd{C-c a} (@pxref{Installation}). In the
3375 following we will assume that @kbd{C-c a} is indeed how the dispatcher
3376 is accessed and list keyboard access to commands accordingly. After
3377 pressing @kbd{C-c a}, an additional letter is required to execute a
3378 command. The dispatcher offers the following default commands:
3381 Create the calendar-like agenda (@pxref{Weekly/Daily agenda}).
3383 Create a list of all TODO items (@pxref{Global TODO list}).
3385 Create a list of headlines matching a TAGS expression (@pxref{Matching
3388 Create the timeline view for the current buffer (@pxref{Timeline}).
3390 Create a list of stuck projects (@pxref{Stuck projects}).
3392 Restrict an agenda command to the current buffer. After pressing
3393 @kbd{1}, you still need to press the character selecting the command.
3395 If there is an active region, restrict the following agenda command to
3396 the region. Otherwise, restrict it to the current subtree. After
3397 pressing @kbd{0}, you still need to press the character selecting the
3401 You can also define custom commands that will be accessible through the
3402 dispatcher, just like the default commands. This includes the
3403 possibility to create extended agenda buffers that contain several
3404 blocks together, for example the weekly agenda, the global TODO list and
3405 a number of special tags matches. @xref{Custom agenda views}.
3407 @node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda views
3408 @section The built-in agenda views
3410 In this section we describe the built-in views.
3413 * Weekly/Daily agenda:: The calendar page with current tasks
3414 * Global TODO list:: All unfinished action items
3415 * Matching headline tags:: Structured information with fine-tuned search
3416 * Timeline:: Time-sorted view for single file
3417 * Stuck projects:: Find projects you need to review
3420 @node Weekly/Daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views
3421 @subsection The weekly/daily agenda
3423 @cindex weekly agenda
3424 @cindex daily agenda
3426 The purpose of the weekly/daily @emph{agenda} is to act like a page of a
3427 paper agenda, showing all the tasks for the current week or day.
3430 @cindex org-agenda, command
3433 Compile an agenda for the current week from a list of org files. The
3434 agenda shows the entries for each day. With a @kbd{C-u} prefix (or
3435 when the variable @code{org-agenda-include-all-todo} is @code{t}), all
3436 unfinished TODO items (including those without a date) are also listed at
3437 the beginning of the buffer, before the first date.@*
3440 Remote editing from the agenda buffer means, for example, that you can
3441 change the dates of deadlines and appointments from the agenda buffer.
3442 The commands available in the Agenda buffer are listed in @ref{Agenda
3445 @subsubheading Calendar/Diary integration
3446 @cindex calendar integration
3447 @cindex diary integration
3449 Emacs contains the calendar and diary by Edward M. Reingold. The
3450 calendar displays a three-month calendar with holidays from different
3451 countries and cultures. The diary allows you to keep track of
3452 anniversaries, lunar phases, sunrise/set, recurrent appointments
3453 (weekly, monthly) and more. In this way, it is quite complementary to
3454 Org-mode. It can be very useful to combine output from Org-mode with
3457 In order to include entries from the Emacs diary into Org-mode's
3458 agenda, you only need to customize the variable
3461 (setq org-agenda-include-diary t)
3464 @noindent After that, everything will happen automatically. All diary
3465 entries including holidays, anniversaries etc will be included in the
3466 agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and
3467 @key{RET} can be used from the agenda buffer to jump to the diary
3468 file in order to edit existing diary entries. The @kbd{i} command to
3469 insert new entries for the current date works in the agenda buffer, as
3470 well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
3471 Sunrise/Sunset times, show lunar phases and to convert to other
3472 calendars, respectively. @kbd{c} can be used to switch back and forth
3473 between calendar and agenda.
3476 @node Global TODO list, Matching headline tags, Weekly/Daily agenda, Built-in agenda views
3477 @subsection The global TODO list
3478 @cindex global TODO list
3479 @cindex TODO list, global
3481 The global TODO list contains all unfinished TODO items, formatted and
3482 collected into a single place.
3487 Show the global TODO list. This collects the TODO items from all
3488 agenda files (@pxref{Agenda views}) into a single buffer. The buffer is in
3489 @code{agenda-mode}, so there are commands to examine and manipulate
3490 the TODO entries directly from that buffer (@pxref{Agenda commands}).
3493 @cindex TODO keyword matching
3494 Like the above, but allows selection of a specific TODO keyword. You can
3495 also do this by specifying a prefix argument to @kbd{C-c a t}. With a
3496 @kbd{C-u} prefix you are prompted for a keyword. With a numeric
3497 prefix, the Nth keyword in @code{org-todo-keywords} is selected.
3499 The @kbd{r} key in the agenda buffer regenerates it, and you can give
3500 a prefix argument to this command to change the selected TODO keyword,
3501 for example @kbd{3 r}. If you often need a search for a specific
3502 keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
3503 Matching specific TODO keywords can also be done as part of a tags
3504 search (@pxref{Tag searches}).
3507 Remote editing of TODO items means that you can change the state of a
3508 TODO entry with a single key press. The commands available in the
3509 TODO list are described in @ref{Agenda commands}.
3511 @cindex sublevels, inclusion into todo list
3512 Normally the global todo list simply shows all headlines with TODO
3513 keywords. This list can become very long. There are two ways to keep
3517 Some people view a TODO item that has been @emph{scheduled} for
3518 execution (@pxref{Time stamps}) as no longer @emph{open}. Configure the
3519 variable @code{org-agenda-todo-ignore-scheduled} to exclude scheduled
3520 items from the global TODO list.
3522 TODO items may have sublevels to break up the task into subtasks. In
3523 such cases it may be enough to list only the highest level TODO headline
3524 and omit the sublevels from the global list. Configure the variable
3525 @code{org-agenda-todo-list-sublevels} to get this behavior.
3528 @node Matching headline tags, Timeline, Global TODO list, Built-in agenda views
3529 @subsection Matching headline tags
3530 @cindex matching, of tags
3533 If headlines in the agenda files are marked with @emph{tags}
3534 (@pxref{Tags}), you can select headlines based on the tags that apply
3535 to them and collect them into an agenda buffer.
3540 Produce a list of all headlines that match a given set of tags. The
3541 command prompts for a selection criterion, which is a boolean logic
3542 expression with tags, like @samp{+WORK+URGENT-WITHBOSS} or
3543 @samp{WORK|HOME} (@pxref{Tags}). If you often need a specific search,
3544 define a custom command for it (@pxref{Agenda dispatcher}).
3547 Like @kbd{C-c a m}, but only select headlines that are also TODO items
3548 and force checking subitems (see variable
3549 @code{org-tags-match-list-sublevels}). Matching specific todo keywords
3550 together with a tags match is also possible, see @ref{Tag searches}.
3553 The commands available in the tags list are described in @ref{Agenda
3556 @node Timeline, Stuck projects, Matching headline tags, Built-in agenda views
3557 @subsection Timeline for a single file
3558 @cindex timeline, single file
3559 @cindex time-sorted view
3561 The timeline summarizes all time-stamped items from a single Org-mode
3562 file in a @emph{time-sorted view}. The main purpose of this command is
3563 to give an overview over events in a project.
3568 Show a time-sorted view of the org file, with all time-stamped items.
3569 When called with a @kbd{C-u} prefix, all unfinished TODO entries
3570 (scheduled or not) are also listed under the current date.
3574 The commands available in the timeline buffer are listed in
3575 @ref{Agenda commands}.
3578 @node Stuck projects, , Timeline, Built-in agenda views
3579 @subsection Stuck projects
3581 If you are following a system like David Allen's GTD to organize your
3582 work, one of the ``duties'' you have is a regular review to make sure
3583 that all projects move along. A @emph{stuck} project is a project that
3584 has no defined next actions, so it will never show up in the TODO lists
3585 Org-mode produces. During the review, you need to identify such
3586 projects and define next actions for them.
3591 List projects that are stuck.
3594 Customize the variable @code{org-stuck-projects} to define what a stuck
3595 project is and how to find it.
3598 You almost certainly will have to configure this view before it will
3599 work for you. The built-in default assumes that all your projects are
3600 level-2 headlines, and that a project is not stuck if it has at least
3601 one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
3603 Lets assume that you, in your own way of using Org-mode, identify
3604 projects with a tag PROJECT, and that you use a todo keyword MAYBE to
3605 indicate a project that should not be considered yet. Lets further
3606 assume that the todo keyword DONE marks finished projects, and that NEXT
3607 and TODO indicate next actions. Finally, the tag @@SHOP indicates
3608 shopping and is a next action even without the NEXT tag. In this case
3609 you would start by identifying elegible projects with a tags/todo match
3610 @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT and @@SHOP in
3611 the subtree to identify projects that are not stuck. The correct
3612 customization for this is
3615 (setq org-stuck-projects
3616 ("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")))
3620 @node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda views
3621 @section Presentation and sorting
3622 @cindex presentation, of agenda items
3624 Before displaying items in an agenda view, Org-mode visually prepares
3625 the items and sorts them. Each item occupies a single line. The line
3626 starts with a @emph{prefix} that contains the @emph{category}
3627 (@pxref{Categories}) of the item and other important information. You can
3628 customize the prefix using the option @code{org-agenda-prefix-format}.
3629 The prefix is followed by a cleaned-up version of the outline headline
3630 associated with the item.
3633 * Categories:: Not all tasks are equal
3634 * Time-of-day specifications:: How the agenda knows the time
3635 * Sorting of agenda items:: The order of things
3638 @node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
3639 @subsection Categories
3642 The category is a broad label assigned to each agenda item. By default,
3643 the category is simply derived from the file name, but you can also
3644 specify it with a special line in the buffer, like this:
3650 If there are several such lines in a file, each specifies the category
3651 for the text below it (but the first category also applies to any text
3652 before the first CATEGORY line). The display in the agenda buffer looks
3653 best if the category is not longer than 10 characters.
3655 @node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting
3656 @subsection Time-of-Day Specifications
3657 @cindex time-of-day specification
3659 Org-mode checks each agenda item for a time-of-day specification. The
3660 time can be part of the time stamp that triggered inclusion into the
3661 agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
3662 ranges can be specified with two time stamps, like
3664 @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
3666 In the headline of the entry itself, a time(range) may also appear as
3667 plain text (like @samp{12:45} or a @samp{8:30-1pm}. If the agenda
3668 integrates the Emacs diary (@pxref{Weekly/Daily agenda}), time
3669 specifications in diary entries are recognized as well.
3671 For agenda display, Org-mode extracts the time and displays it in a
3672 standard 24 hour format as part of the prefix. The example times in
3673 the previous paragraphs would end up in the agenda like this:
3676 8:30-13:00 Arthur Dent lies in front of the bulldozer
3677 12:45...... Ford Prefect arrives and takes Arthur to the pub
3678 19:00...... The Vogon reads his poem
3679 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
3683 If the agenda is in single-day mode, or for the display of today, the
3684 timed entries are embedded in a time grid, like
3687 8:00...... ------------------
3688 8:30-13:00 Arthur Dent lies in front of the bulldozer
3689 10:00...... ------------------
3690 12:00...... ------------------
3691 12:45...... Ford Prefect arrives and takes Arthur to the pub
3692 14:00...... ------------------
3693 16:00...... ------------------
3694 18:00...... ------------------
3695 19:00...... The Vogon reads his poem
3696 20:00...... ------------------
3697 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
3700 The time grid can be turned on and off with the variable
3701 @code{org-agenda-use-time-grid}, and can be configured with
3702 @code{org-agenda-time-grid}.
3704 @node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting
3705 @subsection Sorting of agenda items
3706 @cindex sorting, of agenda items
3707 @cindex priorities, of agenda items
3708 Before being inserted into a view, the items are sorted. How this is
3709 done depends on the type of view.
3712 For the daily/weekly agenda, the items for each day are sorted. The
3713 default order is to first collect all items containing an explicit
3714 time-of-day specification. These entries will be shown at the beginning
3715 of the list, as a @emph{schedule} for the day. After that, items remain
3716 grouped in categories, in the sequence given by @code{org-agenda-files}.
3717 Within each category, items are sorted by priority (@pxref{Priorities}),
3718 which is composed of the base priority (2000 for priority @samp{A}, 1000
3719 for @samp{B}, and 0 for @samp{C}), plus additional increments for
3720 overdue scheduled or deadline items.
3722 For the TODO list, items remain in the order of categories, but within
3723 each category, sorting takes place according to priority
3724 (@pxref{Priorities}).
3726 For tags matches, items are not sorted at all, but just appear in the
3727 sequence in which they are found in the agenda files.
3730 Sorting can be customized using the variable
3731 @code{org-agenda-sorting-strategy}.
3734 @node Agenda commands, Custom agenda views, Presentation and sorting, Agenda views
3735 @section Commands in the agenda buffer
3736 @cindex commands, in agenda buffer
3738 Entries in the agenda buffer are linked back to the org file or diary
3739 file where they originate. You are not allowed to edit the agenda
3740 buffer itself, but commands are provided to show and jump to the
3741 original entry location, and to edit the org-files ``remotely'' from
3742 the agenda buffer. In this way, all information is stored only once,
3743 removing the risk that your agenda and note files may diverge.
3745 Some commands can be executed with mouse clicks on agenda lines. For
3746 the other commands, the cursor needs to be in the desired line.
3749 @tsubheading{Motion}
3750 @cindex motion commands in agenda
3753 Next line (same as @key{up}).
3756 Previous line (same as @key{down}).
3757 @tsubheading{View/GoTo org file}
3762 Display the original location of the item in another window.
3766 Display original location and recenter that window.
3774 Go to the original location of the item in another window. Under Emacs
3775 22, @kbd{mouse-1} will also works for this.
3779 Go to the original location of the item and delete other windows.
3783 Toggle Follow mode. In Follow mode, as you move the cursor through
3784 the agenda buffer, the other window always shows the corresponding
3785 location in the org file. The initial setting for this mode in new
3786 agenda buffers can be set with the variable
3787 @code{org-agenda-start-with-follow-mode}.
3791 Display the entire subtree of the current item in an indirect buffer.
3792 With numerical prefix ARG, go up to this level and then take that tree.
3793 If ARG is negative, go up that many levels. With @kbd{C-u} prefix, do
3794 not remove the previously used indirect buffer.
3798 Toggle Logbook mode. In Logbook mode, entries that where marked DONE while
3799 logging was on (variable @code{org-log-done}) are shown in the agenda,
3800 as are entries that have been clocked on that day.
3802 @tsubheading{Change display}
3803 @cindex display changing, in agenda
3806 Delete other windows.
3810 Switch to weekly view (7 days displayed together).
3814 Switch to daily view (just one day displayed).
3818 Toggle the inclusion of diary entries. See @ref{Weekly/Daily agenda}.
3822 Toggle the time grid on and off. See also the variables
3823 @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
3827 Recreate the agenda buffer, for example to reflect the changes
3828 after modification of the time stamps of items with S-@key{left} and
3829 S-@key{right}. When the buffer is the global todo list, a prefix
3830 argument is interpreted to create a selective list for a specific TODO
3835 Save all Org-mode buffers in the current Emacs session.
3839 Display the following @code{org-agenda-ndays} days. For example, if
3840 the display covers a week, switch to the following week. With prefix
3841 arg, go forward that many times @code{org-agenda-ndays} days.
3845 Display the previous dates.
3851 @tsubheading{Remote editing}
3852 @cindex remote editing, from agenda
3857 @cindex undoing remote-editing events
3858 @cindex remote editing, undo
3861 Undo a change due to a remote editing command. The change is undone
3862 both in the agenda buffer and in the remote buffer.
3866 Change the TODO state of the item, both in the agenda and in the
3871 Delete the current agenda item along with the entire subtree belonging
3872 to it in the original Org-mode file. If the text to be deleted remotely
3873 is longer than one line, the kill needs to be confirmed by the user. See
3874 variable @code{org-agenda-confirm-kill}.
3878 Archive the subtree corresponding to the current headline.
3882 Show all tags associated with the current item. Because of
3883 inheritance, this may be more than the tags listed in the line itself.
3887 Set tags for the current headline.
3891 Toggle the ARCHIVE tag for the current headline.
3895 Set the priority for the current item. Org-mode prompts for the
3896 priority character. If you reply with @key{SPC}, the priority cookie
3897 is removed from the entry.
3901 Display weighted priority of current item.
3907 Increase the priority of the current item. The priority is changed in
3908 the original buffer, but the agenda is not resorted. Use the @kbd{r}
3912 @kindex S-@key{down}
3915 Decrease the priority of the current item.
3923 Set a deadline for this item.
3925 @kindex S-@key{right}
3927 Change the time stamp associated with the current line by one day into
3928 the future. With prefix argument, change it by that many days. For
3929 example, @kbd{3 6 5 S-@key{right}} will change it by a year. The
3930 stamp is changed in the original org file, but the change is not
3931 directly reflected in the agenda buffer. Use the
3932 @kbd{r} key to update the buffer.
3934 @kindex S-@key{left}
3936 Change the time stamp associated with the current line by one day
3941 Change the time stamp associated with the current line to today.
3942 The key @kbd{>} has been chosen, because it is the same as @kbd{S-.}
3947 Start the clock on the current item. If a clock is running already, it
3951 Stop the previously started clock.
3954 Cancel the currently running clock.
3956 @tsubheading{Calendar commands}
3957 @cindex calendar commands, from agenda
3960 Open the Emacs calendar and move to the date at the agenda cursor.
3963 When in the calendar, compute and show the Org-mode agenda for the
3966 @cindex diary entries, creating from agenda
3969 Insert a new entry into the diary. Prompts for the type of entry
3970 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a new
3971 entry in the diary, just as @kbd{i d} etc. would do in the calendar.
3972 The date is taken from the cursor position.
3976 Show the phases of the moon for the three months around current date.
3980 Show sunrise and sunset times. The geographical location must be set
3981 with calendar variables, see documentation of the Emacs calendar.
3985 Convert the date at cursor into many other cultural and historic
3990 Show holidays for three month around the cursor date.
3992 @c FIXME: This should be a different key.
3995 Export a single iCalendar file containing entries from all agenda files.
3997 @tsubheading{Quit and Exit}
4000 Quit agenda, remove the agenda buffer.
4003 @cindex agenda files, removing buffers
4005 Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
4006 for the compilation of the agenda. Buffers created by the user to
4007 visit org files will not be removed.
4012 @node Custom agenda views, , Agenda commands, Agenda views
4013 @section Custom agenda views
4014 @cindex custom agenda views
4015 @cindex agenda views, custom
4017 Custom agenda commands serve two purposes: to store and quickly access
4018 frequently used TODO and tags searches, and to create special composite
4019 agenda buffers. Custom agenda commands will be accessible through the
4020 dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
4023 * Storing searches:: Type once, use often
4024 * Block agenda:: All the stuff you need in a single buffer
4025 * Setting Options:: Changing the rules
4026 * Batch processing:: Agenda views from the command line
4029 @node Storing searches, Block agenda, Custom agenda views, Custom agenda views
4030 @subsection Storing searches
4032 The first application of custom searches is the definition of keyboard
4033 shortcuts for frequently used searches, either creating an agenda
4034 buffer, or a sparse tree (the latter covering of course only the current
4037 Custom commands are configured in the variable
4038 @code{org-agenda-custom-commands}. You can customize this variable, for
4039 example by pressing @kbd{C-c a C}. You can also directly set it with
4040 Emacs Lisp in @file{.emacs}. The following example contains all valid
4045 (setq org-agenda-custom-commands
4046 '(("w" todo "WAITING")
4047 ("W" todo-tree "WAITING")
4048 ("u" tags "+BOSS-URGENT")
4049 ("v" tags-todo "+BOSS-URGENT")
4050 ("U" tags-tree "+BOSS-URGENT")
4051 ("f" occur-tree "\\<FIXME\\>")))
4056 The initial single-character string in each entry defines the character
4057 you have to press after the dispatcher command @kbd{C-c a} in order to
4058 access the command. The second parameter is the search type, followed
4059 by the string or regular expression to be used for the matching. The
4060 example above will therefore define:
4064 as a global search for TODO entries with @samp{WAITING} as the TODO
4067 as the same search, but only in the current buffer and displaying the
4068 results as a sparse tree
4070 as a global tags search for headlines marked @samp{:BOSS:} but not
4073 as the same search as @kbd{C-c a u}, but limiting the search to
4074 headlines that are also TODO items
4076 as the same search as @kbd{C-c a u}, but only in the current buffer and
4077 displaying the result as a sparse tree
4079 to create a sparse tree (again: current buffer only) with all entries
4080 containing the word @samp{FIXME}.
4083 @node Block agenda, Setting Options, Storing searches, Custom agenda views
4084 @subsection Block agenda
4085 @cindex block agenda
4086 @cindex agenda, with block views
4088 Another possibility is the construction of agenda views that comprise
4089 the results of @emph{several} commands, each of which creates a block in
4090 the agenda buffer. The available commands include @code{agenda} for the
4091 daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
4092 for the global todo list (as constructed with @kbd{C-c a t}), and the
4093 matching commands discussed above: @code{todo}, @code{tags}, and
4094 @code{tags-todo}. Here are two examples:
4098 (setq org-agenda-custom-commands
4099 '(("h" "Agenda and Home-related tasks"
4103 ("o" "Agenda and Office-related tasks"
4111 This will define @kbd{C-c a h} to create a multi-block view for stuff
4112 you need to attend to at home. The resulting agenda buffer will contain
4113 your agenda for the current week, all TODO items that carry the tag
4114 @samp{HOME}, and also all lines tagged with @samp{GARDEN}. Finally the
4115 command @kbd{C-c a o} provides a similar view for office tasks.
4118 @node Setting Options, Batch processing, Block agenda, Custom agenda views
4119 @subsection Setting Options for custom commands
4120 @cindex options, for custom agenda views
4122 Org-mode contains a number of variables regulating agenda construction
4123 and display. The global variables define the behavior for all agenda
4124 commands, including the custom commands. However, if you want to change
4125 some settings just for a single custom view, you can do so. Setting
4126 options requires inserting a list of variable names and values at the
4127 right spot in @code{org-agenda-custom-commands}. For example:
4131 (setq org-agenda-custom-commands
4132 '(("w" todo "WAITING"
4133 ((org-agenda-sorting-strategy '(priority-down))
4134 (org-agenda-prefix-format " Mixed: ")))
4135 ("U" tags-tree "+BOSS-URGENT"
4136 ((org-show-following-heading nil)
4137 (org-show-hierarchy-above nil)))))
4142 Now the @kbd{C-c a w} command will sort the collected entries only by
4143 priority, and the prefix format is modified to just say @samp{ Mixed:}
4144 instead of giving the category of the entry. The sparse tags tree of
4145 @kbd{C-c a U} will now turn out ultra-compact, because neither the
4146 headline hierarchy above the match, nor the headline following the match
4149 For command sets creating a block agenda,
4150 @code{org-agenda-custom-commands} has two separate spots for setting
4151 options. You can add options that should be valid for just a single
4152 command in the set, and options that should be valid for all commands in
4153 the set. The former are just added to the command entry, the latter
4154 must come after the list of command entries. Going back to the block
4155 agenda example (@pxref{Block agenda}), let's change the sorting strategy
4156 for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
4157 the results for GARDEN tags query in the opposite order,
4158 @code{priority-up}. This would look like this:
4162 (setq org-agenda-custom-commands
4163 '(("h" "Agenda and Home-related tasks"
4166 (tags "GARDEN" ((org-agenda-sorting-strategy '(priority-up)))))
4167 ((org-agenda-sorting-strategy '(priority-down))))
4168 ("o" "Agenda and Office-related tasks"
4175 As you see, the values and parenthesis setting is a little complex.
4176 When in doubt, use the customize interface to set this variable - it
4177 fully supports its structure. Just one caveat: When setting options in
4178 this interface, the @emph{values} are just lisp expressions. So if the
4179 value is a string, you need to add the double quotes around the value
4182 @node Batch processing, , Setting Options, Custom agenda views
4183 @subsection Creating agenda views in batch processing
4184 @cindex agenda, batch production
4186 If you want to print or otherwise reprocess agenda views, it can be
4187 useful to create an agenda from the command line. This is the purpose
4188 of the function @code{org-batch-agenda}. It takes as a parameter one of
4189 the strings that are the keys in @code{org-agenda-custom-commands}. For
4190 example, to directly print the current TODO list, you could use
4193 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
4197 You may also modify parameters on the fly like this:
4200 emacs -batch -l ~/.emacs \
4201 -eval '(org-batch-agenda "a" \
4202 org-agenda-ndays 300 \
4203 org-agenda-include-diary nil \
4204 org-agenda-files (quote ("~/org/project.org")))' \
4209 which will produce a 300 day agenda, fully restricted to the Org file
4210 @file{~/org/projects.org}, not even including the diary.
4212 @node Embedded LaTeX, Exporting, Agenda views, Top
4213 @chapter Embedded LaTeX
4214 @cindex @TeX{} interpretation
4215 @cindex La@TeX{} interpretation
4217 Plain ASCII is normally sufficient for almost all note taking. One
4218 exception, however, are scientific notes which need to be able to
4219 contain mathematical symbols and the occasional formula.
4220 La@TeX{}@footnote{La@TeX{} is a macro system based on Donald E. Knuth's
4221 @TeX{} system. Many of the features described here as ``La@TeX{}'' are
4222 really from @TeX{}, but for simplicity I am blurring this distinction.}
4223 is widely used to typeset scientific documents. Org-mode supports
4224 embedding La@TeX{} code into its files, because many academics are used
4225 to read La@TeX{} source code, and because it can be readily processed
4226 into images for HTML production.
4228 It is not necessary to mark La@TeX{} macros and code in any special way.
4229 If you observe a few conventions, Org-mode knows how to find it and what
4233 * Math symbols:: TeX macros for symbols and Greek letters
4234 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
4235 * LaTeX fragments:: Complex formulas made easy
4236 * Processing LaTeX fragments:: Previewing LaTeX processing
4237 * CDLaTeX mode:: Speed up entering of formulas
4240 @node Math symbols, Subscripts and Superscripts, Embedded LaTeX, Embedded LaTeX
4241 @section Math symbols
4242 @cindex math symbols
4245 You can use La@TeX{} macros to insert special symbols like @samp{\alpha}
4246 to indicate the Greek letter, or @samp{\to} to indicate an arrow.
4247 Completion for these macros is available, just type @samp{\} and maybe a
4248 few letters, and press @kbd{M-@key{TAB}} to see possible completions.
4249 Unlike La@TeX{} code, Org-mode allows these macros to be present
4250 without surrounding math delimiters, for example:
4253 Angles are written as Greek letters \alpha, \beta and \gamma.
4256 During HTML export (@pxref{HTML export}), these symbols are translated
4257 into the proper syntax for HTML, for the above examples this is
4258 @samp{α} and @samp{→}, respectively.
4260 @node Subscripts and Superscripts, LaTeX fragments, Math symbols, Embedded LaTeX
4261 @section Subscripts and Superscripts
4265 Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super-
4266 and subscripts. Again, these can be used without embedding them in
4267 math-mode delimiters. To increase the readability of ASCII text, it is
4268 not necessary (but OK) to surround multi-character sub- and superscripts
4269 with curly braces. For example
4272 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
4273 the sun is R_@{sun@} = 6.96 x 10^8 m.
4276 To avoid interpretation as raised or lowered text, you can quote
4277 @samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}.
4279 During HTML export (@pxref{HTML export}), subscript and superscripts
4280 are surrounded with @code{<sub>} and @code{<sup>} tags, respectively.
4282 @node LaTeX fragments, Processing LaTeX fragments, Subscripts and Superscripts, Embedded LaTeX
4283 @section LaTeX fragments
4284 @cindex LaTeX fragments
4286 With symbols, sub- and superscripts, HTML is pretty much at its end when
4287 it comes to representing mathematical formulas@footnote{Yes, there is
4288 MathML, but that is not yet fully supported by many browsers, and there
4289 is no decent converter for turning LaTeX of ASCII representations of
4290 formulas into MathML. So for the time being, converting formulas into
4291 images seems the way to go.}. More complex
4292 expressions need a dedicated formula processor. To this end, Org-mode
4293 can contain arbitrary La@TeX{} fragments. It provides commands to
4294 preview the typeset result of these fragments, and upon export to HTML,
4295 all fragments will be converted to images and inlined into the HTML
4296 document. For this to work you need to be on a system with a working
4297 La@TeX{} installation. You also need the @file{dvipng} program,
4298 available at @url{http://sourceforge.net/projects/dvipng/}.
4300 La@TeX{} fragments don't need any special marking at all. The following
4301 snippets will be identified as LaTeX source code:
4304 Environments of any kind. The only requirement is that the
4305 @code{\begin} statement appears on a new line, preceded by only
4308 Text within the usual La@TeX{} math delimiters. To avoid conflicts with
4309 currency specifications, single @samp{$} characters are only recognized
4310 as math delimiters if the enclosed text contains at most two line breaks,
4311 is directly attached to the @samp{$} characters with no whitespace in
4312 between, and if the closing @samp{$} is followed by whitespace or
4313 punctuation. For the other delimiters, there is no such restriction, so
4314 when in doubt, use @samp{\(...\)} as inline math delimiters.
4317 @noindent For example:
4320 \begin@{equation@} % arbitrary environments,
4321 x=\sqrt@{b@} % even tables, figures
4322 \end@{equation@} % etc
4324 If $a^2=b$ and \( b=2 \), then the solution must be
4325 either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
4329 If you need any of the delimiter ASCII sequences for other purposes, you
4330 can configure the option @code{org-format-latex-options} to deselect the
4331 ones you do not wish to have interpreted by the La@TeX{} converter.
4333 @node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX
4334 @section Processing LaTeX fragments
4335 @cindex LaTeX fragments, preview
4337 La@TeX{} fragments can be processed to produce a preview images of the
4338 typeset expressions:
4343 Produce a preview image of the La@TeX{} fragment at point and overlay it
4344 over the source code. If there is no fragment at point, process all
4345 fragments in the current entry (between two headlines). When called
4346 with a prefix argument, process the entire subtree. When called with
4347 two prefix arguments, or when the cursor is before the first headline,
4348 process the entire buffer.
4351 Remove the overlay preview images.
4354 During HTML export (@pxref{HTML export}), all La@TeX{} fragments are
4355 converted into images and inlined into the document if the following
4359 (setq org-export-with-LaTeX-fragments t)
4362 @node CDLaTeX mode, , Processing LaTeX fragments, Embedded LaTeX
4363 @section Using CDLaTeX to enter math
4366 CDLaTeX-mode is a minor mode that is normally used in combination with a
4367 major LaTeX mode like AUCTeX in order to speed-up insertion of
4368 environments and math templates. Inside Org-mode, you can make use of
4369 some of the features of cdlatex-mode. You need to install
4370 @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
4371 AUCTeX) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}.
4372 Don't turn cdlatex-mode itself under Org-mode, but use the light
4373 version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it
4374 on for the current buffer with @code{M-x org-cdlatex-mode}, or for all
4378 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
4381 When this mode is enabled, the following features are present (for more
4382 details see the documentation of cdlatex-mode):
4386 Environment templates can be inserted with @kbd{C-c @{}.
4389 The @key{TAB} key will do template expansion if the cursor is inside a
4390 LaTeX fragment@footnote{Org-mode has a method to test if the cursor is
4391 inside such a fragment, see the documentation of the function
4392 @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
4393 expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
4394 correctly inside the first brace. Another @key{TAB} will get you into
4395 the second brace. Even outside fragments, @key{TAB} will expand
4396 environment abbreviations at the beginning of a line. For example, if
4397 you write @samp{equ} at the beginning of a line and press @key{TAB},
4398 this abbreviation will be expanded to an @code{equation} environment.
4399 To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}.
4403 Pressing @kbd{_} and @kbd{^} inside a LaTeX fragment will insert these
4404 characters together with a pair of braces. If you use @key{TAB} to move
4405 out of the braces, and if the braces surround only a single character or
4406 macro, they are removed again (depending on the variable
4407 @code{cdlatex-simplify-sub-super-scripts}).
4410 Pressing the backquote @kbd{`} followed by a character inserts math
4411 macros, also outside LaTeX fragments. If you wait more than 1.5 seconds
4412 after the backquote, a help window will pop up.
4415 Pressing the normal quote @kbd{'} followed by another character modifies
4416 the symbol before point with an accent or a font. If you wait more than
4417 1.5 seconds after the backquote, a help window will pop up. Character
4418 modification will work only inside La@TeX{} fragments, outside the quote
4422 @node Exporting, Publishing, Embedded LaTeX, Top
4426 Org-mode documents can be exported into a variety of other formats. For
4427 printing and sharing of notes, ASCII export produces a readable and
4428 simple version of an Org-mode file. HTML export allows you to publish a
4429 notes file on the web, while the XOXO format provides a solid base for
4430 exchange with a broad range of other applications. To incorporate
4431 entries with associated times like deadlines or appointments into a
4432 desktop calendar program like iCal, Org-mode can also produce extracts
4433 in the iCalendar format. Currently Org-mode only supports export, not
4434 import of these different formats.
4436 When exporting, Org-mode uses special conventions to enrich the output
4437 produced. @xref{Text interpretation}, for more details.
4442 Dispatcher for export and publishing commands. Displays a help-window
4443 listing the additional key(s) needed to launch an export or publishing
4448 * ASCII export:: Exporting to plain ASCII
4449 * HTML export:: Exporting to HTML
4450 * XOXO export:: Exporting to XOXO
4451 * iCalendar export:: Exporting in iCalendar format
4452 * Text interpretation:: How the exporter looks at the file
4455 @node ASCII export, HTML export, Exporting, Exporting
4456 @section ASCII export
4457 @cindex ASCII export
4459 ASCII export produces a simple and very readable version of an Org-mode
4462 @cindex region, active
4463 @cindex active region
4464 @cindex transient-mark-mode
4468 Export as ASCII file. If there is an active region, only the region
4469 will be exported. For an org file @file{myfile.org}, the ASCII file
4470 will be @file{myfile.txt}. The file will be overwritten without
4474 Export only the visible part of the document.
4477 @cindex headline levels, for exporting
4478 In the exported version, the first 3 outline levels will become
4479 headlines, defining a general document structure. Additional levels
4480 will be exported as itemized lists. If you want that transition to occur
4481 at a different level, specify it with a prefix argument. For example,
4488 creates only top level headlines and does the rest as items. When
4489 headlines are converted to items, the indentation of the text following
4490 the headline is changed to fit nicely under the item. This is done with
4491 the assumption that the first bodyline indicates the base indentation of
4492 the body text. Any indentation larger than this is adjusted to preserve
4493 the layout relative to the first line. Should there be lines with less
4494 indentation than the first, these are left alone.
4496 @node HTML export, XOXO export, ASCII export, Exporting
4497 @section HTML export
4500 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
4501 HTML formatting, in ways similar to John Grubers @emph{markdown}
4502 language, but with additional support for tables.
4505 * Export commands:: How to invode HTML export
4506 * Quoting HTML tags:: Using direct HTML in Org-mode
4507 * Links:: How hyperlinks get transferred to HTML
4508 * Images:: To inline or not to inline?
4509 * CSS support:: Style specifications
4512 @node Export commands, Quoting HTML tags, HTML export, HTML export
4513 @subsection HTML export commands
4515 @cindex region, active
4516 @cindex active region
4517 @cindex transient-mark-mode
4521 Export as HTML file @file{myfile.html}.
4524 Export as HTML file and open it with a browser.
4529 Export only the visible part of the document.
4532 @cindex headline levels, for exporting
4533 In the exported version, the first 3 outline levels will become
4534 headlines, defining a general document structure. Additional levels
4535 will be exported as itemized lists. If you want that transition to occur
4536 at a different level, specify it with a prefix argument. For example,
4543 creates two levels of headings and does the rest as items.
4545 @node Quoting HTML tags, Links, Export commands, HTML export
4546 @subsection Quoting HTML tags
4548 If you want to include HTML tags which should be interpreted as such,
4549 mark them with @samp{@@} as in @samp{@@<b>bold text@@</b>}.
4550 Plain @samp{<} and @samp{>} are always transformed to @samp{<} and
4551 @samp{>} in HTML export.
4553 @node Links, Images, Quoting HTML tags, HTML export
4556 @cindex links, in HTML export
4557 @cindex internal links, in HTML export
4558 @cindex external links, in HTML export
4559 Internal links (@pxref{Internal links}) will continue to work in HTML
4560 files only if they match a dedicated @samp{<<target>>}. Automatic links
4561 created by radio targets (@pxref{Radio targets}) will also work in the
4562 HTML file. Links to external files will still work if the HTML file is
4563 in the same directory as the Org-mode file. Links to other @file{.org}
4564 files will be translated into HTML links under the assumption that an
4565 HTML version also exists of the linked file. For information related to
4566 linking files while publishing them to a publishing directory see
4567 @ref{Publishing links}.
4569 @node Images, CSS support, Links, HTML export
4572 @cindex images, inline in HTML
4573 @cindex inlining images in HTML
4574 HTML export can inline images given as links in the Org-mode file, and
4575 it can make an image the clickable part of a link. By
4576 default@footnote{but see the variable
4577 @code{org-export-html-inline-images}}, images are inlined if a link does
4578 not have a description. So @samp{[[file:myimg.jpg]]} will be inlined,
4579 while @samp{[[file:myimg.jpg][the image]]} will just produce a link
4580 @samp{the image} that points to the image. If the description part
4581 itself is a @code{file:} link or a @code{http:} URL pointing to an
4582 image, this image will be inlined and activated so that clicking on the
4583 image will activate the link. For example, to include a thumbnail that
4584 will link to a high resolution version of the image, you could use:
4587 [[file:highres.jpg][file:thumb.jpg]]
4591 and you could use @code{http} addresses just as well.
4593 @node CSS support, , Images, HTML export
4594 @subsection CSS support
4596 You can also give style information for the exported file. The HTML
4597 exporter assigns the following CSS classes to appropriate parts of the
4598 document - your style specifications may change these:
4600 .todo @r{TODO keywords}
4601 .done @r{the DONE keyword}
4602 .timestamp @r{time stamp}
4603 .timestamp-kwd @r{keyword associated with a time stamp, like SCHEDULED}
4604 .tag @r{tag in a headline}
4605 .target @r{target for links}
4608 The default style specification can be configured through the option
4609 @code{org-export-html-style}. If you want to use a file-local style,
4610 you may use file variables, best wrapped into a COMMENT section at the
4611 end of the outline tree. For example@footnote{Under Emacs 21, the
4612 continuation lines for a variable value should have no @samp{#} at the
4613 start of the line.}:
4616 * COMMENT html style specifications
4619 # org-export-html-style: " <style type=\"text/css\">
4620 # p @{font-weight: normal; color: gray; @}
4621 # h1 @{color: black; @}
4626 Remember to execute @kbd{M-x normal-mode} after changing this to make
4627 the new style visible to Emacs. This command restarts org-mode for the
4628 current buffer and forces Emacs to re-evaluate the local variables
4629 section in the buffer.
4631 @c FIXME: More about header and footer styles
4632 @c FIXME: Talk about links and targets.
4634 @node XOXO export, iCalendar export, HTML export, Exporting
4635 @section XOXO export
4638 Org-mode contains an exporter that produces XOXO-style output.
4639 Currently, this exporter only handles the general outline structure and
4640 does not interpret any additional Org-mode features.
4645 Export as XOXO file @file{myfile.html}.
4648 Export only the visible part of the document.
4651 @node iCalendar export, Text interpretation, XOXO export, Exporting
4652 @section iCalendar export
4653 @cindex iCalendar export
4655 Some people like to use Org-mode for keeping track of projects, but
4656 still prefer a standard calendar application for anniversaries and
4657 appointments. In this case it can be useful to have deadlines and
4658 other time-stamped items in Org-mode files show up in the calendar
4659 application. Org-mode can export calendar information in the standard
4665 Create iCalendar entries for the current file and store them in the same
4666 directory, using a file extension @file{.ics}.
4669 Like @kbd{C-c C-e i}, but do this for all files in
4670 @code{org-agenda-files}. For each of these files, a separate iCalendar
4671 file will be written.
4674 Create a single large iCalendar file from all files in
4675 @code{org-agenda-files} and write it to the file given by
4676 @code{org-combined-agenda-icalendar-file}.
4679 How this calendar is best read and updated, depends on the application
4680 you are using. For example, when using iCal under Apple MacOS X, you
4681 could create a new calendar @samp{OrgMode} (the default name for the
4682 calendar created by @kbd{C-c C-e c}, see the variables
4683 @code{org-icalendar-combined-name} and
4684 @code{org-combined-agenda-icalendar-file}). Then set Org-mode to
4685 overwrite the corresponding file
4686 @file{~/Library/Calendars/OrgMode.ics}. You may even use AppleScript
4687 to make iCal re-read the calendar files each time a new version of
4688 @file{OrgMode.ics} is produced. Here is the setup needed for this:
4690 @cindex applescript, for calendar update
4692 (setq org-combined-agenda-icalendar-file
4693 "~/Library/Calendars/OrgMode.ics")
4694 (add-hook 'org-after-save-iCalendar-file-hook
4697 "osascript -e 'tell application \"iCal\" to reload calendars'")))
4700 @node Text interpretation, , iCalendar export, Exporting
4701 @section Text interpretation by the exporter
4703 The exporter backends interpret additional structure in the Org-mode file
4704 in order to produce better output.
4707 * Comment lines:: Some lines will not be exported
4708 * Enhancing text:: Subscripts, symbols and more
4709 * Export options:: How to influence the export settings
4712 @node Comment lines, Enhancing text, Text interpretation, Text interpretation
4713 @subsection Comment lines
4714 @cindex comment lines
4715 @cindex exporting, not
4717 Lines starting with @samp{#} in column zero are treated as comments
4718 and will never be exported. Also entire subtrees starting with the
4719 word @samp{COMMENT} will never be exported. Finally, any text before
4720 the first headline will not be exported either.
4725 Toggle the COMMENT keyword at the beginning of an entry.
4728 @node Enhancing text, Export options, Comment lines, Text interpretation
4729 @subsection Enhancing text for export
4730 @cindex enhancing text
4733 Some of the export backends of Org-mode allow for sophisticated text
4734 formatting, this is true in particular for the HTML backend. Org-mode
4735 has a number of typing conventions that allow to produce a richly
4740 @cindex hand-formatted lists
4741 @cindex lists, hand-formatted
4743 Plain lists @samp{-}, @samp{*} or @samp{+} as bullet, or with @samp{1.}
4744 or @samp{2)} as enumerator will be recognized and transformed if the
4745 backend supports lists. See @xref{Plain lists}.
4747 @cindex underlined text
4751 You can make words @b{*bold*}, @i{/italic/}, _underlined_,
4752 @code{=code=}, and @samp{+strikethrough+}.
4754 @cindex LaTeX fragments, export
4755 @cindex TeX macros, export
4757 Many @TeX{} macros and entire La@TeX{} fragments are converted into HTML
4758 entities or images (@pxref{Embedded LaTeX}).
4760 @cindex tables, export
4762 Tables are transformed into native tables under the exporter, if the
4763 export backend supports this. Data fields before the first horizontal
4764 separator line will be formatted as table header fields.
4768 If a headline starts with the word @samp{QUOTE}, the text below the
4769 headline will be typeset as fixed-width, to allow quoting of computer
4770 codes etc. Lines starting with @samp{:} are also typeset in
4775 Toggle fixed-width for entry (QUOTE) or region, see below.
4778 @cindex linebreak, forced
4780 A double backslash @emph{at the end of a line} enforces a line break at
4784 If these conversions conflict with your habits of typing ASCII text,
4785 they can all be turned off with corresponding variables (see the
4786 customization group @code{org-export-general}, and the following section
4787 which explains how to set export options with special lines in a
4791 @node Export options, , Enhancing text, Text interpretation
4792 @subsection Export options
4793 @cindex options, for export
4795 @cindex completion, of option keywords
4796 The exporter recognizes special lines in the buffer which provide
4797 additional information. These lines may be put anywhere in the file.
4798 The whole set of lines can be inserted into the buffer with @kbd{C-c
4799 C-e t}. For individual lines, a good way to make sure the keyword is
4800 correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion
4801 (@pxref{Completion}).
4806 Insert template with export options, see example below.
4810 #+TITLE: the title to be shown (default is the buffer name)
4811 #+AUTHOR: the author (default taken from @code{user-full-name})
4812 #+EMAIL: his/her email address (default from @code{user-mail-address})
4813 #+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language})
4814 #+TEXT: Some descriptive text to be inserted at the beginning.
4815 #+TEXT: Several lines may be given.
4816 #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t *:nil TeX:t LaTeX:t
4820 The OPTIONS line is a compact form to specify export settings. Here
4822 @cindex headline levels
4823 @cindex section-numbers
4824 @cindex table of contents
4825 @cindex linebreak preservation
4826 @cindex quoted HTML tags
4827 @cindex fixed-width sections
4829 @cindex @TeX{}-like syntax for sub- and superscripts
4830 @cindex emphasized text
4831 @cindex @TeX{} macros
4832 @cindex La@TeX{} fragments
4834 H: @r{set the number of headline levels for export}
4835 num: @r{turn on/off section-numbers}
4836 toc: @r{turn on/off table of contents}
4837 \n: @r{turn on/off linebreak-preservation}
4838 @@: @r{turn on/off quoted HTML tags}
4839 :: @r{turn on/off fixed-width sections}
4840 |: @r{turn on/off tables}
4841 ^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts.}
4842 *: @r{turn on/off emphasized text (bold, italic, underlined)}
4843 TeX: @r{turn on/off simple @TeX{} macros in plain text}
4844 LaTeX: @r{turn on/off La@TeX{} fragments}
4847 @node Publishing, Miscellaneous, Exporting, Top
4851 Org-mode includes@footnote{@file{org-publish.el} is not yet part of
4852 Emacs, so if you are using @file{org.el} as it comes with Emacs, you
4853 need to download this file separately. Also make sure org.el is at
4854 least version 4.27.} a publishing management system
4855 that allows you to configure automatic HTML conversion of
4856 @emph{projects} composed of interlinked org files. This system is
4857 called @emph{org-publish}. You can also configure org-publish to
4858 automatically upload your exported HTML pages and related attachments,
4859 such as images and source code files, to a web server. Org-publish turns
4860 org-mode into a web-site authoring tool.
4862 Org-publish has been contributed to Org-mode by David O'Toole.
4865 * Configuration:: Defining projects
4866 * Sample configuration:: Example projects
4867 * Triggering publication:: Publication commands
4870 @node Configuration, Sample configuration, Publishing, Publishing
4871 @section Configuration
4873 Publishing needs significant configuration to specify files, destination
4874 and many other properties of a project.
4877 * Project alist:: The central configuration variable
4878 * Sources and destinations:: From here to there
4879 * Selecting files:: What files are part of the project?
4880 * Publishing action:: Setting the function doing the publishing
4881 * Publishing options:: Tweaking HTML export
4882 * Publishing links:: Which links keep working after publishing?
4883 * Project page index:: Publishing a list of project files
4886 @node Project alist, Sources and destinations, Configuration, Configuration
4887 @subsection The variable @code{org-publish-project-alist}
4888 @cindex org-publish-project-alist
4889 @cindex projects, for publishing
4891 Org-publish is configured almost entirely through setting the value of
4892 one variable, called @code{org-publish-project-alist}.
4893 Each element of the list configures one project, and may be in one of
4894 the two following forms:
4897 ("project-name" :property value :property value ...)
4901 ("project-name" :components ("project-name" "project-name" ...))
4905 In both cases, projects are configured by specifying property values.
4906 A project defines the set of files that will be published, as well as
4907 the publishing configuration to use when publishing those files. When
4908 a project takes the second form listed above, the individual members
4909 of the ``components'' property are taken to be components of the
4910 project, which group together files requiring different publishing
4911 options. When you publish such a ``meta-project'' all the components
4914 @node Sources and destinations, Selecting files, Project alist, Configuration
4915 @subsection Sources and destinations for files
4916 @cindex directories, for publishing
4918 Most properties are optional, but some should always be set. In
4919 particular, org-publish needs to know where to look for source files,
4920 and where to put published files.
4922 @multitable @columnfractions 0.3 0.7
4923 @item @code{:base-directory}
4924 @tab Directory containing publishing source files
4925 @item @code{:publishing-directory}
4926 @tab Directory (possibly remote) where output files will be published.
4927 @item @code{:preparation-function}
4928 @tab Function called before starting publishing process, for example to
4929 run @code{make} for updating files to be published.
4933 @node Selecting files, Publishing action, Sources and destinations, Configuration
4934 @subsection Selecting files
4935 @cindex files, selecting for publishing
4937 By default, all files with extension @file{.org} in the base directory
4938 are considered part of the project. This can be modified by setting the
4940 @multitable @columnfractions 0.25 0.75
4941 @item @code{:base-extension}
4942 @tab Extension (without the dot!) of source files. This actually is a
4945 @item @code{:exclude}
4946 @tab Regular expression to match file names that should not be
4947 published, even though they have been selected on the basis of their
4950 @item @code{:include}
4951 @tab List of files to be included regardless of @code{:base-extension}
4952 and @code{:exclude}.
4955 @node Publishing action, Publishing options, Selecting files, Configuration
4956 @subsection Publishing Action
4957 @cindex action, for publishing
4959 Publishing means that a file is copied to the destination directory and
4960 possibly transformed in the process. The default transformation is to
4961 export Org-mode files as HTML files, and this is done by the function
4962 @code{org-publish-org-to-html} which calls the HTML exporter
4963 (@pxref{HTML export}). Other files like images only need to be copied
4964 to the publishing destination. For non-Org-mode files, you need to
4965 specify the publishing function.
4967 @multitable @columnfractions 0.3 0.7
4968 @item @code{:publishing-function}
4969 @tab Function executing the publication of a file. This may also be a
4970 list of functions, which will all be called in turn.
4973 The function must accept two arguments: a property list containing at
4974 least a @code{:publishing-directory} property, and the name of the file
4975 to be published. It should take the specified file, make the necessary
4976 transformation (if any) and place the result into the destination folder.
4977 You can write your own publishing function, but @code{org-publish}
4978 provides one for attachments (files that only need to be copied):
4979 @code{org-publish-attachment}.
4981 @node Publishing options, Publishing links, Publishing action, Configuration
4982 @subsection Options for the HTML exporter
4983 @cindex options, for publishing
4985 The property list can be used to set many export options for the HTML
4986 exporter. In most cases, these properties correspond to user variables
4987 in Org-mode. The table below lists these properties along with the
4988 variable they belong to. See the documentation string for the
4989 respective variable for details.
4991 @multitable @columnfractions 0.3 0.7
4992 @item @code{:language} @tab @code{org-export-default-language}
4993 @item @code{:headline-levels} @tab @code{org-export-headline-levels}
4994 @item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
4995 @item @code{:table-of-contents} @tab @code{org-export-with-toc}
4996 @item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
4997 @item @code{:emphasize} @tab @code{org-export-with-emphasize}
4998 @item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts}
4999 @item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros}
5000 @item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments}
5001 @item @code{:fixed-width} @tab @code{org-export-with-fixed-width}
5002 @item @code{:timestamps} .@tab @code{org-export-with-timestamps}
5003 @item @code{:tags} .@tab @code{org-export-with-tags}
5004 @item @code{:tables} @tab @code{org-export-with-tables}
5005 @item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line}
5006 @item @code{:style} @tab @code{org-export-html-style}
5007 @item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html}
5008 @item @code{:inline-images} @tab @code{org-export-html-inline-images}
5009 @item @code{:expand-quoted-html} @tab @code{org-export-html-expand}
5010 @item @code{:timestamp} @tab @code{org-export-html-with-timestamp}
5011 @item @code{:publishing-directory} @tab @code{org-export-publishing-directory}
5012 @item @code{:preamble} @tab @code{org-export-html-preamble}
5013 @item @code{:postamble} @tab @code{org-export-html-postamble}
5014 @item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble}
5015 @item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble}
5016 @item @code{:author} @tab @code{user-full-name}
5017 @item @code{:email} @tab @code{user-mail-address}
5020 When a property is given a value in org-publish-project-alist, its
5021 setting overrides the value of the corresponding user variable (if any)
5022 during publishing. options set within a file (@pxref{Export
5023 options}), however, override everything.
5025 @node Publishing links, Project page index, Publishing options, Configuration
5026 @subsection Links between published files
5027 @cindex links, publishing
5029 To create a link from one Org-mode file to another, you would use
5030 something like @samp{[[file:foo.org][The foo]]} or simply
5031 @samp{file:foo.org.} (@pxref{Hyperlinks}). Upon publishing this link
5032 becomes a link to @file{foo.html}. In this way, you can interlink the
5033 pages of your "org web" project and the links will work as expected when
5034 you publish them to HTML.
5036 You may also link to related files, such as images. Provided you are
5037 careful with relative pathnames, and provided you have also configured
5038 org-publish to upload the related files, these links will work
5039 too. @ref{Complex example} for an example of this usage.
5041 Sometime an Org-mode file to be published may contain links that are
5042 only valid in your production environment, but not in the publishing
5043 location. In this case, use the property
5045 @multitable @columnfractions 0.4 0.6
5046 @item @code{:link-validation-function}
5047 @tab Function to validate links
5051 to define a function for checking link validity. This function must
5052 accept two arguments, the file name and a directory relative to which
5053 the file name is interpreted in the production environment. If this
5054 function returns @code{nil}, then the HTML generator will only insert a
5055 description into the HTML file, but no link. One option for this
5056 function is @code{org-publish-validate-link} which checks if the given
5057 file is part of any project in @code{org-publish-project-alist}.
5059 @node Project page index, , Publishing links, Configuration
5060 @subsection Project page index
5061 @cindex index, of published pages
5063 The following properties may be used to control publishing of an
5064 index of files or summary page for a given project.
5066 @multitable @columnfractions 0.25 0.75
5067 @item @code{:auto-index}
5068 @tab When non-nil, publish an index during org-publish-current-project or
5071 @item @code{:index-filename}
5072 @tab Filename for output of index. Defaults to @file{index.org} (which
5073 becomes @file{index.html}).
5075 @item @code{:index-title}
5076 @tab Title of index page. Defaults to name of file.
5078 @item @code{:index-function}
5079 @tab Plugin function to use for generation of index.
5080 Defaults to @code{org-publish-org-index}, which generates a plain list
5081 of links to all files in the project.
5084 @node Sample configuration, Triggering publication, Configuration, Publishing
5085 @section Sample configuration
5087 Below we provide two example configurations. The first one is a simple
5088 project publishing only a set of Org-mode files. The second example is
5089 more complex, with a multi-component project.
5092 * Simple example:: One-component publishing
5093 * Complex example:: A multi-component publishing example
5096 @node Simple example, Complex example, Sample configuration, Sample configuration
5097 @subsection Example: simple publishing configuration
5099 This example publishes a set of Org-mode files to the @file{public_html}
5100 directory on the local machine.
5103 (setq org-publish-project-alist
5105 :base-directory "~/org/"
5106 :publishing-directory "~/public_html"
5107 :section-numbers nil
5108 :table-of-contents nil
5109 :style "<link rel=stylesheet
5110 href=\"../other/mystyle.css\"
5111 type=\"text/css\">")))
5114 @node Complex example, , Simple example, Sample configuration
5115 @subsection Example: complex publishing configuration
5117 This more complicated example publishes an entire website, including
5118 org files converted to HTML, image files, emacs lisp source code, and
5119 stylesheets. The publishing-directory is remote and private files are
5122 To ensure that links are preserved, care should be taken to replicate
5123 your directory structure on the web server, and to use relative file
5124 paths. For example, if your org files are kept in @file{~/org} and your
5125 publishable images in @file{~/images}, you'd link to an image with
5128 file:../images/myimage.png
5131 On the web server, the relative path to the image should be the
5132 same. You can accomplish this by setting up an "images" folder in the
5133 right place on the webserver, and publishing images to it.
5136 (setq org-publish-project-alist
5138 :base-directory "~/org/"
5139 :base-extension "org"
5140 :publishing-directory "/ssh:user@@host:~/html/notebook/"
5141 :publishing-function org-publish-org-to-html
5142 :exclude "PrivatePage.org" ;; regexp
5144 :section-numbers nil
5145 :table-of-contents nil
5146 :style "<link rel=stylesheet
5147 href=\"../other/mystyle.css\" type=\"text/css\">"
5149 :auto-postamble nil)
5152 :base-directory "~/images/"
5153 :base-extension "jpg\\|gif\\|png"
5154 :publishing-directory "/ssh:user@@host:~/html/images/"
5155 :publishing-function org-publish-attachment)
5158 :base-directory "~/other/"
5159 :base-extension "css\\|el"
5160 :publishing-directory "/ssh:user@@host:~/html/other/"
5161 :publishing-function org-publish-attachment)
5162 ("website" :components ("orgfiles" "images" "other"))))
5165 @node Triggering publication, , Sample configuration, Publishing
5166 @section Triggering publication
5168 Once org-publish is properly configured, you can publish with the
5169 following functions:
5173 Prompt for a specific project and publish all files that belong to it.
5175 Publish the project containing the current file.
5177 Publish only the current file.
5179 Publish all projects.
5182 Org uses timestamps to track when a file has changed. The above
5183 functions normally only publish changed files. You can override this and
5184 force publishing of all files by giving a prefix argument.
5186 @node Miscellaneous, Extensions and Hacking, Publishing, Top
5187 @chapter Miscellaneous
5190 * Completion:: M-TAB knows what you need
5191 * Customization:: Adapting Org-mode to your taste
5192 * In-buffer settings:: Overview of the #+KEYWORDS
5193 * The very busy C-c C-c key:: When in doubt, press C-c C-c
5194 * Clean view:: Getting rid of leading stars in the outline
5195 * TTY keys:: Using Org-mode on a tty
5196 * Interaction:: Other Emacs packages
5197 * Bugs:: Things which do not work perfectly
5200 @node Completion, Customization, Miscellaneous, Miscellaneous
5202 @cindex completion, of @TeX{} symbols
5203 @cindex completion, of TODO keywords
5204 @cindex completion, of dictionary words
5205 @cindex completion, of option keywords
5206 @cindex completion, of CamelCase links
5207 @cindex completion, of tags
5208 @cindex @TeX{} symbol completion
5209 @cindex TODO keywords completion
5210 @cindex dictionary word completion
5211 @cindex option keyword completion
5212 @cindex CamelCase link completion
5213 @cindex tag completion
5215 Org-mode supports in-buffer completion. This type of completion does
5216 not make use of the minibuffer. You simply type a few letters into
5217 the buffer and use the key to complete text right there.
5222 Complete word at point
5225 At the beginning of a headline, complete TODO keywords.
5227 After @samp{\}, complete @TeX{} symbols supported by the exporter.
5229 After @samp{*}, complete headlines in the current buffer so that they
5230 can be used in search links like @samp{[[*find this headline]]}.
5232 After @samp{:}, complete tags. The list of tags is taken from the
5233 variable @code{org-tag-alist} (possibly set through the @samp{#+TAGS}
5234 in-buffer option, @pxref{Setting tags}), or it is created dynamically
5235 from all tags used in the current buffer.
5237 After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
5239 After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
5240 @samp{OPTIONS} which set file-specific options for Org-mode. When the
5241 option keyword is already complete, pressing @kbd{M-@key{TAB}} again
5242 will insert example settings for this keyword.
5244 In the line after @samp{#+STARTUP: }, complete startup keywords,
5245 i.e. valid keys for this line.
5247 Elsewhere, complete dictionary words using ispell.
5251 @node Customization, In-buffer settings, Completion, Miscellaneous
5252 @section Customization
5253 @cindex customization
5254 @cindex options, for customization
5255 @cindex variables, for customization
5257 There are more than 170 variables that can be used to customize
5258 Org-mode. For the sake of compactness of the manual, I am not
5259 describing the variables here. A structured overview of customization
5260 variables is available with @kbd{M-x org-customize}. Or select
5261 @code{Browse Org Group} from the @code{Org->Customization} menu. Many
5262 settings can also be activated on a per-file basis, by putting special
5263 lines into the buffer (@pxref{In-buffer settings}).
5265 @node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous
5266 @section Summary of in-buffer settings
5267 @cindex in-buffer settings
5268 @cindex special keywords
5270 Org-mode uses special lines in the buffer to define settings on a
5271 per-file basis. These lines start with a @samp{#+} followed by a
5272 keyword, a colon, and then individual words defining a setting. Several
5273 setting words can be in the same line, but you can also have multiple
5274 lines for the keyword. While these settings are described throughout
5275 the manual, here is a summary. After changing any of those lines in the
5276 buffer, press @kbd{C-c C-c} with the cursor still in the line to
5277 activate the changes immediately. Otherwise they become effective only
5278 when the file is visited again in a new Emacs session.
5282 This line sets options to be used at startup of org-mode, when an
5283 Org-mode file is being visited. The first set of options deals with the
5284 initial visibility of the outline tree. The corresponding variable for
5285 global default settings is @code{org-startup-folded}, with a default
5286 value @code{t}, which means @code{overview}.
5287 @cindex @code{overview}, STARTUP keyword
5288 @cindex @code{content}, STARTUP keyword
5289 @cindex @code{showall}, STARTUP keyword
5291 overview @r{top-level headlines only}
5292 content @r{all headlines}
5293 showall @r{no folding at all, show everything}
5295 Then there are options for aligning tables upon visiting a file. This
5296 is useful in files containing narrowed table columns. The corresponding
5297 variable is @code{org-startup-align-all-tables}, with a default value
5299 @cindex @code{align}, STARTUP keyword
5300 @cindex @code{noalign}, STARTUP keyword
5302 align @r{align all tables}
5303 noalign @r{don't align tables on startup}
5305 Logging TODO state changes and clock intervals (variable
5306 @code{org-log-done}) can be configured using these options.
5307 @cindex @code{logdone}, STARTUP keyword
5308 @cindex @code{nologging}, STARTUP keyword
5309 @cindex @code{lognotedone}, STARTUP keyword
5310 @cindex @code{lognoteclock-out}, STARTUP keyword
5311 @cindex @code{lognotestate}, STARTUP keyword
5313 logging @r{record a timestamp when an item is marked DONE}
5314 nologging @r{don't record when items are marked DONE}
5315 lognotedone @r{record timestamp and a note when DONE}
5316 lognotestate @r{record timestamp, note when TODO state changes}
5317 lognoteclock-out @r{record timestamp and a note when clocking out}
5319 Here are the options for hiding leading stars in outline headings. The
5320 corresponding variables are @code{org-hide-leading-stars} and
5321 @code{org-odd-levels-only}, both with a default setting @code{nil}
5322 (meaning @code{showstars} and @code{oddeven}).
5323 @cindex @code{hidestars}, STARTUP keyword
5324 @cindex @code{showstars}, STARTUP keyword
5325 @cindex @code{odd}, STARTUP keyword
5326 @cindex @code{even}, STARTUP keyword
5328 hidestars @r{make all but one of the stars starting a headline invisible.}
5329 showstars @r{show all stars starting a headline}
5330 odd @r{allow only odd outline levels (1,3,...)}
5331 oddeven @r{allow all outline levels}
5333 To turn on custom format overlays over time stamps (variables
5334 @code{org-put-time-stamp-overlays} and
5335 @code{org-time-stamp-overlay-formats}), use
5336 @cindex @code{customtime}, STARTUP keyword
5338 customtime @r{overlay custom time format}
5340 @item #+SEQ_TODO: #+TYP_TODO:
5341 These lines set the TODO keywords and their interpretation in the
5342 current file. The corresponding variables are @code{org-todo-keywords}
5343 and @code{org-todo-interpretation}.
5344 @item #+TAGS: TAG1(c1) TAG2(c2)
5345 These lines (several such lines are allowed) specify the legal tags in
5346 this file, and (potentially) the corresponding @emph{fast tag selection}
5347 keys. The corresponding variable is @code{org-tag-alist}.
5348 @item #+LINK: linkword replace
5349 These lines (several are allowed) specify link abbreviations.
5350 @xref{Link abbreviations}. The corresponding variable is
5351 @code{org-link-abbrev-alist}.
5353 This line sets the category for the agenda file. The category applies
5354 for all subsequent lines until the next @samp{#+CATEGORY} line, or the
5357 This line contains the formulas for the table directly above the line.
5358 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:
5359 These lines provide settings for exporting files. For more details see
5360 @ref{Export options}.
5363 @node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous
5364 @section The very busy C-c C-c key
5366 @cindex C-c C-c, overview
5368 The key @kbd{C-c C-c} has many purposes in org-mode, which are all
5369 mentioned scattered throughout this manual. One specific function of
5370 this key is to add @emph{tags} to a headline (@pxref{Tags}). In many
5371 other circumstances it means something like @emph{Hey Org-mode, look
5372 here and update according to what you see here}. Here is a summary of
5373 what this means in different contexts.
5377 If there are highlights in the buffer from the creation of a sparse
5378 tree, or from clock display, remove these highlights.
5380 If the cursor is in one of the special @code{#+KEYWORD} lines, this
5381 triggers scanning the buffer for these lines and updating the
5384 If the cursor is inside a table, realign the table. This command
5385 works even if the automatic table editor has been turned off.
5387 If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
5390 If the cursor is inside a table created by the @file{table.el} package,
5391 activate that table.
5393 If the current buffer is a remember buffer, close the note and file it.
5394 With a prefix argument, file it, without further interaction, to the
5397 If the cursor is on a @code{<<<target>>>}, update radio targets and
5398 corresponding links in this buffer.
5400 If the cursor is in a plain list item with a checkbox, toggle the status
5403 If the cursor is on a numbered item in a plain list, renumber the
5407 @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous
5408 @section A cleaner outline view
5409 @cindex hiding leading stars
5410 @cindex clean outline view
5412 Some people find it noisy and distracting that the Org-mode headlines
5413 are starting with a potentially large number of stars. For example
5414 the tree from @ref{Headlines}:
5417 * Top level headline
5423 * Another top level headline
5427 Unfortunately this is deeply ingrained into the code of Org-mode and
5428 cannot be easily changed. You can, however, modify the display in such
5429 a way that all leading stars become invisible and the outline more easy
5430 to read. To do this, customize the variable
5431 @code{org-hide-leading-stars} like this:
5434 (setq org-hide-leading-stars t)
5438 or change this on a per-file basis with one of the lines (anywhere in
5442 #+STARTUP: showstars
5443 #+STARTUP: hidestars
5447 Press @kbd{C-c C-c} with the cursor in a @samp{STARTUP} line to activate
5450 With stars hidden, the tree becomes:
5453 * Top level headline
5459 * Another top level headline
5463 Note that the leading stars are not truly replaced by whitespace, they
5464 are only fontified with the face @code{org-hide} that uses the
5465 background color as font color. If you are not using either white or
5466 black background, you may have to customize this face to get the wanted
5467 effect. Another possibility is to set this font such that the extra
5468 stars are @i{almost} invisible, for example using the color
5469 @code{grey90} on a white background.
5471 Things become cleaner still if you skip all the even levels and use only
5472 odd levels 1, 3, 5..., effectively adding two stars to go from one
5473 outline level to the next:
5476 * Top level headline
5482 * Another top level headline
5486 In order to make the structure editing and export commands handle this
5487 convention correctly, use
5490 (setq org-odd-levels-only t)
5494 or set this on a per-file basis with one of the following lines (don't
5495 forget to press @kbd{C-c C-c} with the cursor in the startup line to
5496 activate changes immediately).
5503 You can convert an Org-mode file from single-star-per-level to the
5504 double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels
5505 RET} in that file. The reverse operation is @kbd{M-x
5506 org-convert-to-oddeven-levels}.
5508 @node TTY keys, Interaction, Clean view, Miscellaneous
5509 @section Using org-mode on a tty
5510 @cindex tty keybindings
5512 Org-mode uses a number of keys that are not accessible on a tty. This
5513 applies to most special keys like cursor keys, @key{TAB} and
5514 @key{RET}, when these are combined with modifier keys like @key{Meta}
5515 and/or @key{Shift}. Org-mode uses these bindings because it needs to
5516 provide keys for a large number of commands, and because these keys
5517 appeared particularly easy to remember. In order to still be able to
5518 access the core functionality of Org-mode on a tty, alternative
5519 bindings are provided. Here is a complete list of these bindings,
5520 which are obviously more cumbersome to use. Note that sometimes a
5521 work-around can be better. For example changing a time stamp is
5522 really only fun with @kbd{S-@key{cursor}} keys. On a tty you would
5523 rather use @kbd{C-c .} to re-insert the timestamp.
5525 @multitable @columnfractions 0.15 0.2 0.2
5526 @item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2}
5527 @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab
5528 @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}}
5529 @item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab
5530 @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{@key{Esc} @key{right}}
5531 @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab
5532 @item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{@key{Esc} @key{up}}
5533 @item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab
5534 @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{@key{Esc} @key{down}}
5535 @item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab
5536 @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab
5537 @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{@key{Esc} @key{RET}}
5538 @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab
5539 @item @kbd{S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab
5540 @item @kbd{S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab
5541 @item @kbd{S-@key{up}} @tab @kbd{C-c C-x @key{up}} @tab
5542 @item @kbd{S-@key{down}} @tab @kbd{C-c C-x @key{down}} @tab
5545 @node Interaction, Bugs, TTY keys, Miscellaneous
5546 @section Interaction with other packages
5547 @cindex packages, interaction with other
5548 Org-mode lives in the world of GNU Emacs and interacts in various ways
5549 with other code out there.
5552 * Cooperation:: Packages Org-mode cooperates with
5553 * Conflicts:: Packages that lead to conflicts
5556 @node Cooperation, Conflicts, Interaction, Interaction
5557 @subsection Packages that Org-mode cooperates with
5560 @cindex @file{calc.el}
5561 @item @file{calc.el} by Dave Gillespie
5562 Org-mode uses the calc package for implementing spreadsheet
5563 functionality in its tables (@pxref{Table calculations}). Org-modes
5564 checks for the availability of calc by looking for the function
5565 @code{calc-eval} which should be autoloaded in your setup if calc has
5566 been installed properly. As of Emacs 22, calc is part of the Emacs
5567 distribution. Another possibility for interaction between the two
5568 packages is using calc for embedded calculations. @xref{Embedded Mode,
5569 , Embedded Mode, calc, GNU Emacs Calc Manual}.
5570 @cindex @file{constants.el}
5571 @item @file{constants.el} by Carsten Dominik
5572 In a table formula (@pxref{Table calculations}), it is possible to use
5573 names for natural constants or units. Instead of defining your own
5574 constants in the variable @code{org-table-formula-constants}, install
5575 the @file{constants} package which defines a large number of constants
5576 and units, and lets you use unit prefixes like @samp{M} for
5577 @samp{Mega} etc. You will need version 2.0 of this package, available
5578 at @url{http://www.astro.uva.nl/~dominik/Tools}. Org-mode checks for
5579 the function @code{constants-get}, which has to be autoloaded in your
5580 setup. See the installation instructions in the file
5581 @file{constants.el}.
5582 @item @file{cdlatex.el} by Carsten Dominik
5583 @cindex @file{cdlatex.el}
5584 Org-mode can make use of the cdlatex package to efficiently enter
5585 La@TeX{} fragments into Org-mode files. See @ref{CDLaTeX mode}.
5586 @item @file{remember.el} by John Wiegley
5587 @cindex @file{remember.el}
5588 Org mode cooperates with remember, see @ref{Remember}.
5589 @file{Remember.el} is not part of Emacs, find it on the web.
5590 @cindex @file{table.el}
5591 @item @file{table.el} by Takaaki Ota
5592 Org mode cooperates with table.el, see @ref{table.el}. @file{table.el}
5593 is part of Emacs 22.
5596 @node Conflicts, , Cooperation, Interaction
5597 @subsection Packages that lead to conflicts with Org-mode
5601 @cindex @file{allout.el}
5602 @item @file{allout.el} by Ken Manheimer
5603 Startup of Org-mode may fail with the error message
5604 @code{(wrong-type-argument keymapp nil)} when there is an outdated
5605 version @file{allout.el} on the load path, for example the version
5606 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem will
5607 disappear. If for some reason you cannot do this, make sure that org.el
5608 is loaded @emph{before} @file{allout.el}, for example by putting
5609 @code{(require 'org)} early enough into your @file{.emacs} file.
5611 @cindex @file{CUA.el}
5612 @item @file{CUA.el} by Kim. F. Storm
5613 Keybindings in Org-mode conflict with the @kbd{S-<cursor>} keys
5614 used by CUA-mode (as well as pc-select-mode and s-region-mode) to
5615 select and extend the region. If you want to use one of these
5616 packages along with Org-mode, configure the variable
5617 @code{org-CUA-compatible}. When set, Org-mode will move the following
5618 keybindings in org-mode files, and in the agenda buffer (but not
5619 during date selection).
5622 S-UP -> M-p S-DOWN -> M-n
5623 S-LEFT -> M-- S-RIGHT -> M-+
5627 Yes, these are unfortunately more difficult to remember. If you want
5628 to have other replacement keys, look at the variable
5629 @code{org-disputed-keys}.
5630 @item @file{windmove.el} by Hovav Shacham
5631 @cindex @file{windmove.el}
5632 Also this package uses the @kbd{S-<cursor>} keys, so everything written
5633 in the paragraph above about CUA mode also applies here.
5637 @node Bugs, , Interaction, Miscellaneous
5641 Here is a list of things that should work differently, but which I
5642 have found too hard to fix.
5646 If a table field starts with a link, and if the corresponding table
5647 column is narrowed (@pxref{Narrow columns}) to a width too small to
5648 display the link, the field would look entirely empty even though it is
5649 not. To prevent this, Org-mode throws an error. The work-around is to
5650 make the column wide enough to fit the link, or to add some text (at
5651 least 2 characters) before the link in the same field.
5653 Narrowing table columns does not work on XEmacs, because the
5654 @code{format} function does not transport text properties.
5656 Text in an entry protected with the @samp{QUOTE} keyword should not
5659 When the application called by @kbd{C-c C-o} to open a file link fails
5660 (for example because the application does not exist or refuses to open
5661 the file), it does so silently. No error message is displayed.
5663 Recalculating a table line applies the formulas from left to right.
5664 If a formula uses @emph{calculated} fields further down the row,
5665 multiple recalculation may be needed to get all fields consistent.
5667 A single letter cannot be made bold, for example @samp{*a*}.
5669 The exporters work well, but could be made more efficient.
5673 @node Extensions and Hacking, History and Acknowledgments, Miscellaneous, Top
5674 @appendix Extensions, Hooks and Hacking
5676 This appendix lists extensions for Org-mode written by other authors.
5677 It also covers some aspects where users can extend the functionality of
5681 * Extensions:: Existing 3rd-part extensions
5682 * Dynamic blocks:: Automatically filled blocks
5683 * Special agenda views::
5686 @node Extensions, Dynamic blocks, Extensions and Hacking, Extensions and Hacking
5687 @section Third-party extensions for Org-mode
5689 The following extensions for Org-mode have been written by other people:
5692 @cindex @file{org-publish.el}
5693 @item @file{org-publish.el} by David O'Toole
5694 This package provides facilities for publishing related sets of Org-mode
5695 files together with linked files like images as a webpages. It is
5696 highly configurable and can be used for other publishing purposes as
5697 well. As of Org-mode version 4.30, @file{org-publish.el} is part of the
5698 Org-mode distribution. It is not yet part of Emacs, however, a delay
5699 caused by the preparations for the 22.1 release. In the mean time,
5700 @file{org-publish.el} can be downloaded from David's site:
5701 @url{http://dto.freeshell.org/e/org-publish.el}.
5702 @cindex @file{org-mouse.el}
5703 @item @file{org-mouse.el} by Piotr Zielinski
5704 This package implements extended mouse functionality for Org-mode. It
5705 allows you to cycle visibility and to edit the document structure with
5706 the mouse. Best of all, it provides a context-sensitive menu on
5707 @key{mouse-3} that changes depending on the context of a mouse-click.
5708 As of Org-mode version 4.53, @file{org-mouse.el} is part of the
5709 Org-mode distribution. It is not yet part of Emacs, however, a delay
5710 caused by the preparations for the 22.1 release. In the mean time,
5711 @file{org-mouse.el} can be downloaded from Piotr's site:
5712 @url{http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el}.
5713 @cindex @file{org-blog.el}
5714 @item @file{org-blog.el} by David O'Toole
5715 A blogging plug-in for @file{org-publish.el}.@*
5716 @url{http://dto.freeshell.org/notebook/OrgMode.html}.
5717 @cindex @file{blorg.el}
5718 @item @file{blorg.el} by Bastien Guerry
5719 Publish Org-mode files as
5720 blogs. @url{http://www.cognition.ens.fr/~guerry/blorg.html}.
5723 @node Dynamic blocks, Special agenda views, Extensions, Extensions and Hacking
5724 @section Dynamic blocks
5726 Org-mode documents can contain @emph{dynamic blocks}. These are
5727 specially marked regions that are updated by some user-written
5728 function. A good example for such a block is the clock table inserted
5729 by the command @kbd{C-c C-x C-r} (@pxref{Clocking work time}).
5731 Dynamic block are enclosed by a BEGIN-END structure that assigns a name
5732 to the block and can also specify parameters for the function producing
5733 the content of the block.
5736 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
5741 Dynamic blocks are updated with the following commands
5746 Update dynamic block at point.
5747 @kindex C-u C-c C-x C-u
5748 @item C-u C-c C-x C-u
5749 Update all dynamic blocks in the current file.
5752 Updating a dynamic block means to remove all the text between BEGIN and
5753 END, parse the BEGIN line for parameters and then call the specific
5754 writer function for this block to insert the new content. For a block
5755 with name @code{myblock}, the writer function is
5756 @code{org-dblock-write:myblock} with as only parameter a property list
5757 with the parameters given in the begin line. Here is a trivial example
5758 of a block that keeps track of when the block update function was last
5762 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
5768 The corresponding block writer function could look like this:
5771 (defun org-dblock-write:block-update-time (params)
5772 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
5773 (insert "Last block update at: "
5774 (format-time-string fmt (current-time)))))
5777 If you want to make sure that all dynamic blocks are always up-to-date,
5778 you could add the function @code{org-update-all-dblocks} to a hook, for
5779 example @code{before-save-hook}. @code{org-update-all-dblocks} is
5780 written in a way that is does nothing in buffers that are not in Org-mode.
5782 @node Special agenda views, , Dynamic blocks, Extensions and Hacking
5783 @section Special Agenda Views
5785 Org-mode provides a special hook that can be used to narrow down the
5786 selection made by any of the agenda views. You may specify a function
5787 that is used at each match to verify if the match should indeed be part
5788 of the agenda view, and if not, how much should be skipped.
5790 Let's say you want to produce a list of projects that contain a WAITING
5791 tag anywhere in the project tree. Let's further assume that you have
5792 marked all tree headings that define a project with the todo keyword
5793 PROJECT. In this case you would run a todo search for the keyword
5794 PROJECT, but skip the match unless there is a WAITING tag anywhere in
5795 the subtree belonging to the project line..
5797 To achieve this, you must write a function that searches the subtree for
5798 the tag. If the tag is found, the function must return @code{nil} to
5799 indicate that this match should not be skipped. If there is no such
5800 tag, return the location of the end of the subtree, to indicate that
5801 search should continue from there.
5804 (defun my-skip-unless-waiting ()
5805 "Skip trees that are not waiting"
5806 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
5807 (if (re-search-forward ":WAITING:" subtree-end t)
5808 nil ; tag found, do not skip
5809 subtree-end))) ; tag not found, continue after end of subtree
5812 Furthermore you must write a command that uses @code{let} to temporarily
5813 puts this function into the variable @code{org-agenda-skip-function},
5814 sets the header string for the agenda buffer, and calls the todo-list
5815 generator while asking for the specific TODO keyword PROJECT. The
5816 function must also accept one argument MATCH, but it can choose to
5817 ignore it@footnote{MATCH must be present in case you want to define a
5818 custom command for producing this special list. Custom commands always
5819 supply the MATCH argument, but it can be empty if you do not specify it
5820 while defining the command(@pxref{Custom agenda
5821 views}).} (as we do in the example below). Here is the example:
5824 (defun my-org-waiting-projects (&optional match)
5825 "Produce a list of projects that contain a WAITING tag.
5826 MATCH is being ignored."
5828 (let ((org-agenda-skip-function 'my-skip-unless-waiting)
5829 (org-agenda-overriding-header "Projects waiting for something: "))
5831 (org-todo-list "PROJECT")))
5835 @node History and Acknowledgments, Index, Extensions and Hacking, Top
5836 @appendix History and Acknowledgments
5837 @cindex acknowledgments
5841 Org-mode was borne in 2003, out of frustration over the user interface
5842 of the Emacs outline-mode. All I wanted was to make working with an
5843 outline tree possible without having to remember more than 10 commands
5844 just for hiding and unhiding parts of the outline tree, and to allow to
5845 restructure a tree easily. Visibility cycling and structure editing
5846 were originally implemented in the package @file{outline-magic.el}, but
5847 quickly moved to the more general @file{org.el}. TODO entries, basic
5848 time stamps, and table support were added next, and highlight the two
5849 main goals that Org-mode still has today: To create a new,
5850 outline-based, plain text mode with innovative and intuitive editing
5851 features, and to incorporate project planning functionality directly
5854 Since the first release, hundreds of emails to me or on
5855 @code{emacs-orgmode@@gnu.org} have provided a constant stream of bug
5856 reports, feedback, new ideas, and sometimes even patches and add-on
5857 code. Many thanks to everyone who has helped to improve this package.
5858 I am trying to keep here a list of the people who had significant
5859 influence in shaping one or more aspects of Org-mode. The list may not
5860 be complete, if I have forgotten someone, please accept my apologies and
5866 @i{Thomas Baumann} contributed the code for links to the MH-E email
5869 @i{Alex Bochannek} provided a patch for rounding time stamps.
5871 @i{Charles Cave}'s suggestion sparked the implementation of templates
5874 @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
5877 @i{Gregory Chernov} patched support for lisp forms into table
5878 calculations and improved XEmacs compatibility, in particular by porting
5879 @file{nouline.el} to XEmacs.
5881 @i{Sacha Chua} suggested to copy some linking code from Planner.
5883 @i{Eddward DeVilla} proposed and tested checkbox statistics.
5885 @i{Kees Dullemond} inspired the use of narrowed tabled columns.
5887 @i{Christian Egli} converted the documentation into TeXInfo format,
5888 patched CSS formatting into the HTML exporter, and inspired the agenda.
5890 @i{Nic Ferrier} contributed mailcap and XOXO support.
5892 @i{John Foerch} figured out how to make incremental search show context
5893 around a match in a hidden outline tree.
5895 @i{Niels Giessen} had the idea to automatically archive DONE trees.
5897 @i{Bastien Guerry} provided extensive feedback.
5899 @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
5901 @i{Leon Liu} asked for embedded LaTeX and tested it.
5903 @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
5906 @i{Todd Neal} provided patches for links to Info files and elisp forms.
5908 @i{Tim O'Callaghan} suggested in-file links, search options for general
5909 file links, and TAGS.
5911 @i{Oliver Oppitz} suggested multi-state TODO items.
5913 @i{Scott Otterson} sparked the introduction of descriptive text for
5914 links, among other things.
5916 @i{Pete Phillips} helped during the development of the TAGS feature, and
5917 provided frequent feedback.
5919 @i{T.V. Raman} reported bugs and suggested improvements.
5921 @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
5924 @i{Kevin Rogers} contributed code to access VM files on remote hosts.
5926 @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
5927 conflict with @file{allout.el}.
5929 @i{Jason Riedy} sent a patch to fix a bug with export of TODO keywords.
5931 @i{Philip Rooke} created the Org-mode reference card and provided lots
5934 @i{Christian Schlauer} proposed angular brackets around links, among
5937 Linking to VM/BBDB/GNUS was inspired by @i{Tom Shannon}'s
5938 @file{organizer-mode.el}.
5940 @i{Daniel Sinder} came up with the idea of internal archiving by locking
5943 @i{Dale Smith} proposed link abbreviations.
5945 @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
5946 chapter about publishing.
5948 @i{J@"urgen Vollmer} contributed code generating the table of contents
5951 @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
5954 @i{David Wainberg} suggested archiving, and improvements to the linking
5957 @i{John Wiegley} wrote @file{emacs-wiki.el} and @file{planner.el}. The
5958 development of Org-mode was fully independent, and both systems are
5959 really different beasts in their basic ideas and implementation details.
5960 I later looked at John's code, however, and learned from his
5961 implementation of (i) links where the link itself is hidden and only a
5962 description is shown, and (ii) popping up a calendar to select a date.
5964 @i{Carsten Wimmer} suggested some changes and helped fix a bug in
5967 @i{Roland Winkler} requested additional keybindings to make Org-mode
5970 @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
5971 and contributed various ideas and code snippets.
5975 @node Index, Key Index, History and Acknowledgments, Top
5980 @node Key Index, , Index, Top
5981 @unnumbered Key Index
5988 arch-tag: 7893d1fe-cc57-4d13-b5e5-f494a1bcc7ac