1 This is org, produced by makeinfo version 4.8 from org.texi.
5 * Org Mode: (org). Outline-based notes management and organizer
8 This manual is for Org-mode (version 4.74).
10 Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation
12 Permission is granted to copy, distribute and/or modify this
13 document under the terms of the GNU Free Documentation License,
14 Version 1.1 or any later version published by the Free Software
15 Foundation; with no Invariant Sections, with the Front-Cover texts
16 being "A GNU Manual," and with the Back-Cover Texts as in (a)
17 below. A copy of the license is included in the section entitled
18 "GNU Free Documentation License."
20 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
21 modify this GNU Manual, like GNU software. Copies published by
22 the Free Software Foundation raise funds for GNU development."
25 File: org, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
30 This manual is for Org-mode (version 4.74).
32 Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation
34 Permission is granted to copy, distribute and/or modify this
35 document under the terms of the GNU Free Documentation License,
36 Version 1.1 or any later version published by the Free Software
37 Foundation; with no Invariant Sections, with the Front-Cover texts
38 being "A GNU Manual," and with the Back-Cover Texts as in (a)
39 below. A copy of the license is included in the section entitled
40 "GNU Free Documentation License."
42 (a) The FSF's Back-Cover Text is: "You have freedom to copy and
43 modify this GNU Manual, like GNU software. Copies published by
44 the Free Software Foundation raise funds for GNU development."
48 * Introduction:: Getting started
49 * Document structure:: A tree works like your brain
50 * Tables:: Pure magic for quick formatting
51 * Hyperlinks:: Notes in context
52 * TODO items:: Every tree branch can be a TODO item
53 * Timestamps:: Assign date and time to items
54 * Tags:: Tagging headlines and matching sets of tags
55 * Agenda views:: Collecting information into views
56 * Embedded LaTeX:: LaTeX fragments and formulas
57 * Exporting:: Sharing and publishing of notes
58 * Publishing:: Create a web site of linked Org-mode files
59 * Miscellaneous:: All the rest which did not fit elsewhere
60 * Extensions and Hacking:: It is possible to write add-on code
61 * History and Acknowledgments:: How Org-mode came into being
62 * Index:: The fast road to specific information
63 * Key Index:: Key bindings and where they are described
65 --- The Detailed Node Listing ---
69 * Summary:: Brief summary of what Org-mode does
70 * Installation:: How to install a downloaded version of Org-mode
71 * Activation:: How to activate Org-mode for certain buffers.
72 * Feedback:: Bug reports, ideas, patches etc.
76 * Outlines:: Org-mode is based on outline-mode
77 * Headlines:: How to typeset org-tree headlines
78 * Visibility cycling:: Show and hide, much simplified
79 * Motion:: Jumping to other headlines
80 * Structure editing:: Changing sequence and level of headlines
81 * Archiving:: Move done task trees to a different place
82 * Sparse trees:: Matches embedded in context
83 * Plain lists:: Additional structure within an entry
87 * ARCHIVE tag:: Marking a tree as inactive
88 * Moving subtrees:: Moving a tree to an archive file
92 * Built-in table editor:: Simple tables
93 * Narrow columns:: Stop wasting space in tables
94 * orgtbl-mode:: The table editor as minor mode
95 * The spreadsheet:: The table editor has spreadsheet capabilities.
99 * References:: How to refer to another field or range
100 * Formula syntax for Calc:: Using Calc to compute stuff
101 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
102 * Field formulas:: Formulas valid for a single field
103 * Column formulas:: Formulas valid for an entire column
104 * Editing and debugging formulas:: Fixing formulas
105 * Updating the table:: Recomputing all dependent fields
106 * Advanced features:: Field names, parameters and automatic recalc
110 * Link format:: How links in Org-mode are formatted
111 * Internal links:: Links to other places in the current file
112 * External links:: URL-like links to the world
113 * Handling links:: Creating, inserting and following
114 * Link abbreviations:: Shortcuts for writing complex links
115 * Search options:: Linking to a specific location
116 * Custom searches:: When the default search is not enough
117 * Remember:: Org-trees store quick notes
121 * Radio targets:: Make targets trigger links in plain text.
125 * Setting up remember:: Some code for .emacs to get things going
126 * Remember templates:: Define the outline of different note types
127 * Storing notes:: Directly get the note to where it belongs
131 * TODO basics:: Marking and displaying TODO entries
132 * TODO extensions:: Workflow and assignments
133 * Priorities:: Some things are more important than others
134 * Breaking down tasks:: Splitting a task into manageable pieces
135 * Checkboxes:: Tick-off lists
137 Extended use of TODO keywords
139 * Workflow states:: From TODO to DONE in steps
140 * TODO types:: I do this, Fred the rest
141 * Multiple sets in one file:: Mixing it all, and still finding your way
142 * Per file keywords:: Different files, different requirements
146 * Time stamps:: Assigning a time to a tree entry
147 * Creating timestamps:: Commands which insert timestamps
148 * Custom time format:: If you cannot work with the ISO format
149 * Repeating items:: Deadlines that come back again and again
150 * Progress logging:: Documenting when what work was done.
154 * The date/time prompt:: How org-mode helps you entering date and time
158 * Closing items:: When was this entry marked DONE?
159 * Tracking TODO state changes:: When did the status change?
160 * Clocking work time:: When exactly did you work on this item?
164 * Tag inheritance:: Tags use the tree structure of the outline
165 * Setting tags:: How to assign tags to a headline
166 * Tag searches:: Searching for combinations of tags
170 * Agenda files:: Files being searched for agenda information
171 * Agenda dispatcher:: Keyboard access to agenda views
172 * Built-in agenda views:: What is available out of the box?
173 * Presentation and sorting:: How agenda items are prepared for display
174 * Agenda commands:: Remote editing of org trees
175 * Custom agenda views:: Defining special searches and views
177 The built-in agenda views
179 * Weekly/Daily agenda:: The calendar page with current tasks
180 * Global TODO list:: All unfinished action items
181 * Matching headline tags:: Structured information with fine-tuned search
182 * Timeline:: Time-sorted view for single file
183 * Stuck projects:: Find projects you need to review
185 Presentation and sorting
187 * Categories:: Not all tasks are equal
188 * Time-of-day specifications:: How the agenda knows the time
189 * Sorting of agenda items:: The order of things
193 * Storing searches:: Type once, use often
194 * Block agenda:: All the stuff you need in a single buffer
195 * Setting Options:: Changing the rules
196 * Exporting Agenda Views:: Writing agendas to files.
197 * Extracting Agenda Information for other programs::
201 * Math symbols:: TeX macros for symbols and Greek letters
202 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
203 * LaTeX fragments:: Complex formulas made easy
204 * Processing LaTeX fragments:: Previewing LaTeX processing
205 * CDLaTeX mode:: Speed up entering of formulas
209 * ASCII export:: Exporting to plain ASCII
210 * HTML export:: Exporting to HTML
211 * XOXO export:: Exporting to XOXO
212 * iCalendar export:: Exporting in iCalendar format
213 * Text interpretation:: How the exporter looks at the file
217 * Export commands:: How to invoke HTML export
218 * Quoting HTML tags:: Using direct HTML in Org-mode
219 * Links:: How hyperlinks get transferred to HTML
220 * Images:: To inline or not to inline?
221 * CSS support:: Style specifications
223 Text interpretation by the exporter
225 * Comment lines:: Some lines will not be exported
226 * Initial text:: Text before the first headline
227 * Enhancing text:: Subscripts, symbols and more
228 * Export options:: How to influence the export settings
232 * Configuration:: Defining projects
233 * Sample configuration:: Example projects
234 * Triggering publication:: Publication commands
238 * Project alist:: The central configuration variable
239 * Sources and destinations:: From here to there
240 * Selecting files:: What files are part of the project?
241 * Publishing action:: Setting the function doing the publishing
242 * Publishing options:: Tweaking HTML export
243 * Publishing links:: Which links keep working after publishing?
244 * Project page index:: Publishing a list of project files
248 * Simple example:: One-component publishing
249 * Complex example:: A multi-component publishing example
253 * Completion:: M-TAB knows what you need
254 * Customization:: Adapting Org-mode to your taste
255 * In-buffer settings:: Overview of the #+KEYWORDS
256 * The very busy C-c C-c key:: When in doubt, press C-c C-c
257 * Clean view:: Getting rid of leading stars in the outline
258 * TTY keys:: Using Org-mode on a tty
259 * Interaction:: Other Emacs packages
260 * Bugs:: Things which do not work perfectly
262 Interaction with other packages
264 * Cooperation:: Packages Org-mode cooperates with
265 * Conflicts:: Packages that lead to conflicts
267 Extensions, Hooks and Hacking
269 * Extensions:: Existing 3rd-part extensions
270 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
271 * Dynamic blocks:: Automatically filled blocks
272 * Special agenda views:: Customized views
274 Tables in arbitrary syntax
276 * Radio tables:: Sending and receiving
277 * A LaTeX example:: Step by step, almost a tutorial
278 * Translator functions:: Copy and modify
281 File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top
288 * Summary:: Brief summary of what Org-mode does
289 * Installation:: How to install a downloaded version of Org-mode
290 * Activation:: How to activate Org-mode for certain buffers.
291 * Feedback:: Bug reports, ideas, patches etc.
294 File: org, Node: Summary, Next: Installation, Prev: Introduction, Up: Introduction
299 Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
300 project planning with a fast and effective plain-text system.
302 Org-mode develops organizational tasks around NOTES files that
303 contain lists or information about projects as plain text. Org-mode is
304 implemented on top of outline-mode, which makes it possible to keep the
305 content of large files well structured. Visibility cycling and
306 structure editing help to work with the tree. Tables are easily created
307 with a built-in table editor. Org-mode supports ToDo items, deadlines,
308 time stamps, and scheduling. It dynamically compiles entries into an
309 agenda that utilizes and smoothly integrates much of the Emacs calendar
310 and diary. Plain text URL-like links connect to websites, emails,
311 Usenet messages, BBDB entries, and any files related to the projects.
312 For printing and sharing of notes, an Org-mode file can be exported as a
313 structured ASCII file, as HTML, or (todo and agenda items only) as an
314 iCalendar file. It can also serve as a publishing tool for a set of
317 An important design aspect that distinguishes Org-mode from for
318 example Planner/Muse is that it encourages to store every piece of
319 information only once. In Planner, you have project pages, day pages
320 and possibly other files, duplicating some information such as tasks.
321 In Org-mode, you only have notes files. In your notes you mark entries
322 as tasks, label them with tags and timestamps. All necessary lists
323 like a schedule for the day, the agenda for a meeting, tasks lists
324 selected by tags etc are created dynamically when you need them.
326 Org-mode keeps simple things simple. When first fired up, it should
327 feel like a straightforward, easy to use outliner. Complexity is not
328 imposed, but a large amount of functionality is available when you need
329 it. Org-mode can be used on different levels and in different ways, for
332 * outline extension with visibility cycling and structure editing
333 * ASCII system and table editor for taking structured notes
334 * ASCII table editor with spreadsheet-like capabilities
336 * full agenda and planner with deadlines and work scheduling
337 * environment to implement David Allen's GTD system
338 * simple hypertext system, with HTML export
339 * publishing tool to create a set of interlinked webpages
341 Org-mode's automatic, context sensitive table editor with spreadsheet
342 capabilities can be integrated into any major mode by activating the
343 minor Orgtbl-mode. Using a translation step, it can be used to maintain
344 tables in arbitrary file types, for example in LaTeX.
346 There is a website for Org-mode which provides links to the newest
347 version of Org-mode, as well as additional information, frequently asked
348 questions (FAQ), links to tutorials etc. This page is located at
349 `http://www.astro.uva.nl/~dominik/Tools/org/'.
352 File: org, Node: Installation, Next: Activation, Prev: Summary, Up: Introduction
357 Important: If Org-mode is part of the Emacs distribution or an XEmacs
358 package, please skip this section and go directly to *Note Activation::.
360 If you have downloaded Org-mode from the Web, you must take the
361 following steps to install it: Go into the Org-mode distribution
362 directory and edit the top section of the file `Makefile'. You must
363 set the name of the Emacs binary (likely either `emacs' or `xemacs'),
364 and the paths to the directories where local Lisp and Info files are
365 kept. If you don't have access to the system-wide directories, create
366 your own two directories for these files, enter them into the Makefile,
367 and make sure Emacs finds the Lisp files by adding the following line
370 (setq load-path (cons "~/path/to/lispdir" load-path))
372 XEmacs users now need to install the file `noutline.el' from the
373 `xemacs' subdirectory of the Org-mode distribution. Use the command:
375 make install-noutline
377 Now byte-compile and install the Lisp files with the shell commands:
382 If you want to install the info documentation, use this command:
386 Then add to `.emacs':
388 ;; This line only if org-mode is not part of the X/Emacs distribution.
389 (require 'org-install)
392 File: org, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction
397 Add the following lines to your `.emacs' file. The last two lines
398 define _global_ keys for the commands `org-store-link' and `org-agenda'
399 - please choose suitable keys yourself.
401 ;; The following lines are always needed. Choose your own keys.
402 (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
403 (define-key global-map "\C-cl" 'org-store-link)
404 (define-key global-map "\C-ca" 'org-agenda)
406 Furthermore, you must activate `font-lock-mode' in org-mode buffers,
407 because significant functionality depends on font-locking being active.
408 You can do this with either one of the following two lines (XEmacs
409 user must use the second option):
410 (global-font-lock-mode 1) ; for all buffers
411 (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
413 With this setup, all files with extension `.org' will be put into
414 Org-mode. As an alternative, make the first line of a file look like
417 MY PROJECTS -*- mode: org; -*-
419 which will select Org-mode for this buffer no matter what the file's
420 name is. See also the variable `org-insert-mode-line-in-empty-file'.
423 File: org, Node: Feedback, Prev: Activation, Up: Introduction
428 If you find problems with Org-mode, or if you have questions, remarks,
429 or ideas about it, please contact the maintainer Carsten Dominik at
430 <dominik at science dot uva dot nl>.
432 For bug reports, please provide as much information as possible,
433 including the version information of Emacs (`C-h v emacs-version
434 <RET>') and Org-mode (`C-h v org-version <RET>'), as well as the
435 Org-mode related setup in `.emacs'. If an error occurs, a backtrace
436 can be very useful (see below on how to create one). Often a small
437 example file helps, along with clear information about:
439 1. What exactly did you do?
441 2. What did you expect to happen?
443 3. What happened instead?
444 Thank you for helping to improve this mode.
446 How to create a useful backtrace
447 ................................
449 If working with Org-mode produces an error with a message you don't
450 understand, you may have hit a bug. The best way to report this is by
451 providing, in addition to what was mentioned above, a _Backtrace_.
452 This is information from the built-in debugger about where and how the
453 error occurred. Here is how to produce a useful backtrace:
455 1. Start a fresh Emacs or XEmacs, and make sure that it will load the
456 original Lisp code in `org.el' instead of the compiled version in
457 `org.elc'. The backtrace contains much more information if it is
458 produced with uncompiled code. To do this, either rename `org.elc'
459 to something else before starting Emacs, or ask Emacs explicitly
460 to load `org.el' by using the command line
461 emacs -l /path/to/org.el
463 2. Go to the `Options' menu and select `Enter Debugger on Error'
464 (XEmacs has this option in the `Troubleshooting' sub-menu).
466 3. Do whatever you have to do to hit the error. Don't forget to
467 document the steps you take.
469 4. When you hit the error, a `*Backtrace*' buffer will appear on the
470 screen. Save this buffer to a file (for example using `C-x C-w')
471 and attach it to your bug report.
474 File: org, Node: Document structure, Next: Tables, Prev: Introduction, Up: Top
479 Org-mode is based on outline mode and provides flexible commands to
480 edit the structure of the document.
484 * Outlines:: Org-mode is based on outline-mode
485 * Headlines:: How to typeset org-tree headlines
486 * Visibility cycling:: Show and hide, much simplified
487 * Motion:: Jumping to other headlines
488 * Structure editing:: Changing sequence and level of headlines
489 * Archiving:: Move done task trees to a different place
490 * Sparse trees:: Matches embedded in context
491 * Plain lists:: Additional structure within an entry
494 File: org, Node: Outlines, Next: Headlines, Prev: Document structure, Up: Document structure
499 Org-mode is implemented on top of outline-mode. Outlines allow to
500 organize a document in a hierarchical structure, which (at least for
501 me) is the best representation of notes and thoughts. Overview over
502 this structure is achieved by folding (hiding) large parts of the
503 document to show only the general document structure and the parts
504 currently being worked on. Org-mode greatly simplifies the use of
505 outlines by compressing the entire show/hide functionality into a
506 single command `org-cycle', which is bound to the <TAB> key.
509 File: org, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document structure
514 Headlines define the structure of an outline tree. The headlines in
515 Org-mode start with one or more stars, on the left margin(1). For
525 * Another top level headline
527 Some people find the many stars too noisy and would prefer an outline
528 that has whitespace followed by a single star as headline starters.
529 *Note Clean view:: describes a setup to realize this.
531 An empty line after the end of a subtree is considered part of it and
532 will be hidden when the subtree is folded. However, if you leave at
533 least two empty lines, one empty line will remain visible after folding
534 the subtree, in order to structure the collapsed view. See the
535 variable `org-cycle-separator-lines' for modifying this behavior.
537 ---------- Footnotes ----------
539 (1) See the variable `org-special-ctrl-a' to configure special
540 behavior of `C-a' in headlines.
543 File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document structure
545 2.3 Visibility cycling
546 ======================
548 Outlines make it possible to hide parts of the text in the buffer.
549 Org-mode uses just two commands, bound to <TAB> and `S-<TAB>' to change
550 the visibility in the buffer.
553 _Subtree cycling_: Rotate current subtree among the states
555 ,-> FOLDED -> CHILDREN -> SUBTREE --.
556 '-----------------------------------'
558 The cursor must be on a headline for this to work(1). When the
559 cursor is at the beginning of the buffer and the first line is not
560 a headline, then <TAB> actually runs global cycling (see
561 below)(2). Also when called with a prefix argument (`C-u <TAB>'),
562 global cycling is invoked.
566 _Global cycling_: Rotate the entire buffer among the states
568 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
569 '--------------------------------------'
571 When `S-<TAB>' is called with a numerical prefix N, the CONTENTS
572 view up to headlines of level N will be shown. Note that inside
573 tables, `S-<TAB>' jumps to the previous field.
579 Reveal context around point, showing the current entry, the
580 following heading and the hierarchy above. Useful for working
581 near a location exposed by a sparse tree command (*note Sparse
582 trees::) or an agenda command (*note Agenda commands::). With
583 prefix arg show, on each level, all sibling headings.
586 Show the current subtree in an indirect buffer(3). With numerical
587 prefix ARG, go up to this level and then take that tree. If ARG is
588 negative, go up that many levels. With `C-u' prefix, do not remove
589 the previously used indirect buffer.
591 When Emacs first visits an Org-mode file, the global state is set to
592 OVERVIEW, i.e. only the top level headlines are visible. This can be
593 configured through the variable `org-startup-folded', or on a per-file
594 basis by adding one of the following lines anywhere in the buffer:
600 ---------- Footnotes ----------
602 (1) see, however, the option `org-cycle-emulate-tab'.
604 (2) see the option `org-cycle-global-at-bob'.
606 (3) The indirect buffer (*note Indirect Buffers: (emacs)Indirect
607 Buffers.) will contain the entire buffer, but will be narrowed to the
608 current tree. Editing the indirect buffer will also change the
609 original buffer, but without affecting visibility in that buffer.
612 File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document structure
617 The following commands jump to other headlines in the buffer.
626 Next heading same level.
629 Previous heading same level.
632 Backward to higher level heading.
635 Jump to a different place without changing the current outline
636 visibility. Shows the document structure in a temporary buffer,
637 where you can use the following keys to find your destination:
638 <TAB> Cycle visibility.
639 <down> / <up> Next/previous visible headline.
640 n / p Next/previous visible headline.
641 f / b Next/previous headline same level.
644 <RET> Select this location.
647 File: org, Node: Structure editing, Next: Archiving, Prev: Motion, Up: Document structure
649 2.5 Structure editing
650 =====================
653 Insert new heading with same level as current. If the cursor is
654 in a plain list item, a new item is created (*note Plain lists::).
655 To force creation of a new headline, use a prefix arg, or first
656 press <RET> to get to the beginning of the next line. When this
657 command is used in the middle of a line, the line is split and the
658 rest of the line becomes the new headline. If the command is used
659 at the beginning of a headline, the new headline is created before
660 the current line. If at the beginning of any other line, the
661 content of that line is made the new heading. If the command is
662 used at the end of a folded subtree (i.e. behind the ellipses at
663 the end of a headline), then a headline like the current one will
664 be inserted after the end of the subtree.
667 Insert new TODO entry with same level as current heading.
670 Promote current heading by one level.
673 Demote current heading by one level.
676 Promote the current subtree by one level.
679 Demote the current subtree by one level.
682 Move subtree up (swap with previous subtree of same level).
685 Move subtree down (swap with next subtree of same level).
689 Kill subtree, i.e. remove it from buffer but save in kill ring.
692 Copy subtree to kill ring.
695 Yank subtree from kill ring. This does modify the level of the
696 subtree to make sure the tree fits in nicely at the yank position.
697 The yank level can also be specified with a prefix arg, or by
698 yanking after a headline marker like `****'.
701 Sort same-level entries. When there is an active region, all
702 entries in the region will be sorted. Otherwise the children of
703 the current headline are sorted. The command prompts for the
704 sorting method, which can be alphabetically, numerically, by time
705 (using the first time stamp in each entry), and each of these in
706 reverse order. With a `C-u' prefix, sorting will be
707 case-sensitive. With two `C-u C-u' prefixes, duplicate entries
708 will also be removed.
710 When there is an active region (transient-mark-mode), promotion and
711 demotion work on all headlines in the region. To select a region of
712 headlines, it is best to place both point and mark at the beginning of a
713 line, mark at the beginning of the first headline, and point at the line
714 just after the last headline to change. Note that when the cursor is
715 inside a table (*note Tables::), the Meta-Cursor keys have different
719 File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: Document structure
724 When a project represented by a (sub)tree is finished, you may want to
725 move the tree out of the way and to stop it from contributing to the
726 agenda. Org-mode knows two ways of archiving. You can mark a tree with
727 the ARCHIVE tag, or you can move an entire (sub)tree to a different
732 * ARCHIVE tag:: Marking a tree as inactive
733 * Moving subtrees:: Moving a tree to an archive file
736 File: org, Node: ARCHIVE tag, Next: Moving subtrees, Prev: Archiving, Up: Archiving
738 2.6.1 The ARCHIVE tag
739 ---------------------
741 A headline that is marked with the ARCHIVE tag (*note Tags::) stays at
742 its location in the outline tree, but behaves in the following way:
743 - It does not open when you attempt to do so with a visibility
744 cycling command (*note Visibility cycling::). You can force
745 cycling archived subtrees with `C-<TAB>', or by setting the option
746 `org-cycle-open-archived-trees'. Also normal outline commands like
747 `show-all' will open archived subtrees.
749 - During sparse tree construction (*note Sparse trees::), matches in
750 archived subtrees are not exposed, unless you configure the option
751 `org-sparse-tree-open-archived-trees'.
753 - During agenda view construction (*note Agenda views::), the
754 content of archived trees is ignored unless you configure the
755 option `org-agenda-skip-archived-trees'.
757 - Archived trees are not exported (*note Exporting::), only the
758 headline is. Configure the details using the variable
759 `org-export-with-archived-trees'.
761 The following commands help managing the ARCHIVE tag:
764 Toggle the ARCHIVE tag for the current headline. When the tag is
765 set, the headline changes to a shadowish face, and the subtree
769 Check if any direct children of the current headline should be
770 archived. To do this, each subtree is checked for open TODO
771 entries. If none are found, the command offers to set the ARCHIVE
772 tag for the child. If the cursor is _not_ on a headline when this
773 command is invoked, the level 1 trees will be checked.
776 Cycle a tree even if it is tagged with ARCHIVE.
779 File: org, Node: Moving subtrees, Prev: ARCHIVE tag, Up: Archiving
781 2.6.2 Moving subtrees
782 ---------------------
784 Once an entire project is finished, you may want to move it to a
785 different location, either in the current file, or even in a different
786 file, the archive file.
789 Archive the subtree starting at the cursor position to the location
790 given by `org-archive-location'.
793 Check if any direct children of the current headline could be
794 moved to the archive. To do this, each subtree is checked for
795 open TODO entries. If none are found, the command offers to move
796 it to the archive location. If the cursor is _not_ on a headline
797 when this command is invoked, the level 1 trees will be checked.
799 The default archive location is a file in the same directory as the
800 current file, with the name derived by appending `_archive' to the
801 current file name. For information and examples on how to change this,
802 see the documentation string of the variable `org-archive-location'.
803 There is also an in-buffer option for setting this variable, for example
807 You may have several such lines in the buffer, they will then be valid
808 for the entries following the line (the first will also apply to any
812 File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure
817 An important feature of Org-mode is the ability to construct _sparse
818 trees_ for selected information in an outline tree. A sparse tree
819 means that the entire document is folded as much as possible, but the
820 selected information is made visible along with the headline structure
821 above it(1). Just try it out and you will see immediately how it works.
823 Org-mode contains several commands creating such trees. The most
824 basic one is `org-occur':
827 Occur. Prompts for a regexp and shows a sparse tree with all
828 matches. If the match is in a headline, the headline is made
829 visible. If the match is in the body of an entry, headline and
830 body are made visible. In order to provide minimal context, also
831 the full hierarchy of headlines above the match is shown, as well
832 as the headline following the match. Each match is also
833 highlighted; the highlights disappear when the buffer is changes
834 an editing command, or by pressing `C-c C-c'. When called with a
835 `C-u' prefix argument, previous highlights are kept, so several
836 calls to this command can be stacked.
837 For frequently used sparse trees of specific search strings, you can
838 use the variable `org-agenda-custom-commands' to define fast keyboard
839 access to specific sparse trees. These commands will then be
840 accessible through the agenda dispatcher (*note Agenda dispatcher::).
843 (setq org-agenda-custom-commands
844 '(("f" occur-tree "FIXME")))
846 will define the key `C-c a f' as a shortcut for creating a sparse tree
847 matching the string `FIXME'.
849 Other commands use sparse trees as well. For example `C-c C-v'
850 creates a sparse TODO tree (*note TODO basics::).
852 To print a sparse tree, you can use the Emacs command
853 `ps-print-buffer-with-faces' which does not print invisible parts of
854 the document (2). Or you can use the command `C-c C-e v' to export
855 only the visible part of the document and print the resulting file.
857 ---------- Footnotes ----------
859 (1) See also the variables `org-show-hierarchy-above',
860 `org-show-following-heading', and `org-show-siblings' for detailed
861 control on how much context is shown around each match.
863 (2) This does not work under XEmacs, because XEmacs uses selective
864 display for outlining, not text properties.
867 File: org, Node: Plain lists, Prev: Sparse trees, Up: Document structure
872 Within an entry of the outline tree, hand-formatted lists can provide
873 additional structure. They also provide a way to create lists of
874 checkboxes (*note Checkboxes::). Org-mode supports editing such lists,
875 and the HTML exporter (*note Exporting::) does parse and format them.
877 Org-mode knows ordered and unordered lists. Unordered list items
878 start with `-', `+', or `*'(1) as bullets. Ordered list items start
879 with `1.' or `1)'. Items belonging to the same list must have the same
880 indentation on the first line. In particular, if an ordered list
881 reaches number `10.', then the 2-digit numbers must be written
882 left-aligned with the other numbers in the list. Indentation also
883 determines the end of a list item. It ends before the next line that
884 is indented like the bullet/number, or less. Empty lines are part of
885 the previous item, so you can have several paragraphs in one item. If
886 you would like an emtpy line to terminate all currently open plain
887 lists, configure the variable `org-empty-line-terminates-plain-lists'.
888 Here is an for example:
891 My favorite scenes are (in this order)
892 1. The attack of the Rohirrim
893 2. Eowyns fight with the witch king
894 + this was already my favorite scene in the book
895 + I really like Miranda Otto.
896 3. Peter Jackson being shot by Legolas
898 He makes a really funny face when it happens.
899 But in the end, not individual scenes matter but the film as a whole.
901 Org-mode supports these lists by tuning filling and wrapping
902 commands to deal with them correctly(2).
904 The following commands act on items when the cursor is in the first
905 line of an item (the line with the bullet or number).
908 Items can be folded just like headline levels if you set the
909 variable `org-cycle-include-plain-lists'. The level of an item is
910 then given by the indentation of the bullet/number. Items are
911 always subordinate to real headlines, however; the hierarchies
912 remain completely separated.
915 Insert new item at current level. With prefix arg, force a new
916 heading (*note Structure editing::). If this command is used in
917 the middle of a line, the line is _split_ and the rest of the line
918 becomes the new item. If this command is executed in the
919 _whitespace before a bullet or number_, the new item is created
920 _before_ the current item. If the command is executed in the
921 white space before the text that is part of an item but does not
922 contain the bullet, a bullet is added to the current line.
925 Insert a new item with a checkbox (*note Checkboxes::).
929 Jump to the previous/next item in the current list.
933 Move the item including subitems up/down (swap with previous/next
934 item of same indentation). If the list is ordered, renumbering is
939 Decrease/increase the indentation of the item, including subitems.
940 Initially, the item tree is selected based on current indentation.
941 When these commands are executed several times in direct
942 succession, the initially selected region is used, even if the new
943 indentation would imply a different hierarchy. To use the new
944 hierarchy, break the command chain with a cursor motion or so.
947 If there is a checkbox (*note Checkboxes::) in the item line,
948 toggle the state of the checkbox. Otherwise, if this is an
949 ordered list, renumber the ordered list at the cursor.
951 ---------- Footnotes ----------
953 (1) When using `*' as a bullet, lines must be indented or they will
954 be seen as top-level headlines. Also, when you are hiding leading
955 stars to get a clean outline view, plain list items starting with a
956 star are visually indistinguishable from true headlines. In short:
957 even though `*' is supported, it may be better not to use it for plain
960 (2) Org-mode only changes the filling settings for Emacs. For
961 XEmacs, you should use Kyle E. Jones' `filladapt.el'. To turn this on,
966 File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top
971 Org-mode has a very fast and intuitive table editor built-in.
972 Spreadsheet-like calculations are supported in connection with the
973 Emacs `calc' package.
977 * Built-in table editor:: Simple tables
978 * Narrow columns:: Stop wasting space in tables
979 * orgtbl-mode:: The table editor as minor mode
980 * The spreadsheet:: The table editor has spreadsheet capabilities.
983 File: org, Node: Built-in table editor, Next: Narrow columns, Prev: Tables, Up: Tables
985 3.1 The built-in table editor
986 =============================
988 Org-mode makes it easy to format tables in plain ASCII. Any line with
989 `|' as the first non-white character is considered part of a table.
990 `|' is also the column separator. A table might look like this:
992 | Name | Phone | Age |
993 |-------+-------+-----|
994 | Peter | 1234 | 17 |
997 A table is re-aligned automatically each time you press <TAB> or
998 <RET> or `C-c C-c' inside the table. <TAB> also moves to the next
999 field (<RET> to the next row) and creates new table rows at the end of
1000 the table or before horizontal lines. The indentation of the table is
1001 set by the first line. Any line starting with `|-' is considered as a
1002 horizontal separator line and will be expanded on the next re-align to
1003 span the whole table width. So, to create the above table, you would
1009 and then press <TAB> to align the table and start filling in fields.
1011 When typing text into a field, Org-mode treats <DEL>, <Backspace>,
1012 and all character keys in a special way, so that inserting and deleting
1013 avoids shifting other fields. Also, when typing _immediately after the
1014 cursor was moved into a new field with `<TAB>', `S-<TAB>' or `<RET>'_,
1015 the field is automatically made blank. If this behavior is too
1016 unpredictable for you, configure the variables
1017 `org-enable-table-editor' and `org-table-auto-blank-field'.
1019 Creation and conversion
1020 .......................
1023 Convert the active region to table. If every line contains at
1024 least one TAB character, the function assumes that the material is
1025 tab separated. If not, lines are split at whitespace into fields.
1026 You can use a prefix argument to indicate the minimum number of
1027 consecutive spaces required to identify a field separator
1028 (default: just one).
1029 If there is no active region, this command creates an empty
1030 Org-mode table. But it's easier just to start typing, like
1031 `|Name|Phone|Age <RET> |- <TAB>'.
1033 Re-aligning and field motion
1034 ............................
1037 Re-align the table without moving the cursor.
1040 Re-align the table, move to the next field. Creates a new row if
1044 Re-align, move to previous field.
1047 Re-align the table and move down to next row. Creates a new row if
1048 necessary. At the beginning or end of a line, <RET> still does
1049 NEWLINE, so it can be used to split a table.
1051 Column and row editing
1052 ......................
1056 Move the current column left/right.
1059 Kill the current column.
1062 Insert a new column to the left of the cursor position.
1066 Move the current row up/down.
1069 Kill the current row or horizontal line.
1072 Insert a new row above (with arg: below) the current row.
1075 Insert a horizontal line below current row. With prefix arg, the
1076 line is created above the current line.
1079 Sort the table lines in the region. The position of point
1080 indicates the column to be used for sorting, and the range of
1081 lines is the range between the nearest horizontal separator lines,
1082 or the entire table. If point is before the first column, you
1083 will be prompted for the sorting column. If there is an active
1084 region, the mark specifies the first line and the sorting column,
1085 while point should be in the last line to be included into the
1086 sorting. The command prompts for the sorting type
1087 (alphabetically, numerically, or by time). When called with a
1088 prefix argument, alphabetic sorting will be case-sensitive.
1094 Copy a rectangular region from a table to a special clipboard.
1095 Point and mark determine edge fields of the rectangle. The
1096 process ignores horizontal separator lines.
1099 Copy a rectangular region from a table to a special clipboard, and
1100 blank all fields in the rectangle. So this is the "cut" operation.
1103 Paste a rectangular region into a table. The upper right corner
1104 ends up in the current field. All involved fields will be
1105 overwritten. If the rectangle does not fit into the present table,
1106 the table is enlarged as needed. The process ignores horizontal
1110 Wrap several fields in a column like a paragraph. If there is an
1111 active region, and both point and mark are in the same column, the
1112 text in the column is wrapped to minimum width for the given
1113 number of lines. A prefix ARG may be used to change the number of
1114 desired lines. If there is no region, the current field is split
1115 at the cursor position and the text fragment to the right of the
1116 cursor is prepended to the field one line down. If there is no
1117 region, but you specify a prefix ARG, the current field is made
1118 blank, and the content is appended to the field above.
1124 Sum the numbers in the current column, or in the rectangle defined
1125 by the active region. The result is shown in the echo area and can
1126 be inserted with `C-y'.
1129 When current field is empty, copy from first non-empty field above.
1130 When not empty, copy current field down to next row and move cursor
1131 along with it. Depending on the variable
1132 `org-table-copy-increment', integer field values will be
1133 incremented during copy. This key is also used by CUA-mode (*note
1140 Edit the current field in a separate window. This is useful for
1141 fields that are not fully visible (*note Narrow columns::). When
1142 called with a `C-u' prefix, just make the full field visible, so
1143 that it can be edited in place.
1146 This is an alias for `C-u C-c `' to make the current field fully
1149 `M-x org-table-import'
1150 Import a file as a table. The table should be TAB- or whitespace
1151 separated. Useful, for example, to import an Excel table or data
1152 from a database, because these programs generally can write
1153 TAB-separated text files. This command works by inserting the
1154 file into the buffer and then converting the region to a table.
1155 Any prefix argument is passed on to the converter, which uses it
1156 to determine the separator.
1159 Tables can also be imported by pasting tabular text into the
1160 org-mode buffer, selecting the pasted text with `C-x C-x' and then
1161 using the `C-c |' command (see above under Creation and conversion.
1163 `M-x org-table-export'
1164 Export the table as a TAB-separated file. Useful for data
1165 exchange with, for example, Excel or database programs.
1167 If you don't like the automatic table editor because it gets in your
1168 way on lines which you would like to start with `|', you can turn it
1171 (setq org-enable-table-editor nil)
1173 Then the only table command that still works is `C-c C-c' to do a
1177 File: org, Node: Narrow columns, Next: orgtbl-mode, Prev: Built-in table editor, Up: Tables
1182 The width of columns is automatically determined by the table editor.
1183 Sometimes a single field or a few fields need to carry more text,
1184 leading to inconveniently wide columns. To limit(1) the width of a
1185 column, one field anywhere in the column may contain just the string
1186 `<N>' where `N' is an integer specifying the width of the column in
1187 characters. The next re-align will then set the width of this column
1188 to no more than this value.
1190 |---+------------------------------| |---+--------|
1192 | 1 | one | | 1 | one |
1193 | 2 | two | ----\ | 2 | two |
1194 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1195 | 4 | four | | 4 | four |
1196 |---+------------------------------| |---+--------|
1198 Fields that are wider become clipped and end in the string `=>'. Note
1199 that the full text is still in the buffer, it is only invisible. To
1200 see the full text, hold the mouse over the field - a tool-tip window
1201 will show the full content. To edit such a field, use the command `C-c
1202 `' (that is `C-c' followed by the backquote). This will open a new
1203 window with the full field. Edit it and finish with `C-c C-c'.
1205 When visiting a file containing a table with narrowed columns, the
1206 necessary character hiding has not yet happened, and the table needs to
1207 be aligned before it looks nice. Setting the option
1208 `org-startup-align-all-tables' will realign all tables in a file upon
1209 visiting, but also slow down startup. You can also set this option on
1210 a per-file basis with:
1215 ---------- Footnotes ----------
1217 (1) This feature does not work on XEmacs.
1220 File: org, Node: orgtbl-mode, Next: The spreadsheet, Prev: Narrow columns, Up: Tables
1222 3.3 The Orgtbl minor mode
1223 =========================
1225 If you like the intuitive way the Org-mode table editor works, you
1226 might also want to use it in other modes like text-mode or mail-mode.
1227 The minor mode Orgtbl-mode makes this possible. You can always toggle
1228 the mode with `M-x orgtbl-mode'. To turn it on by default, for example
1231 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1233 Furthermore, with some special setup, it is possible to maintain
1234 tables in arbitrary syntax with Orgtbl-mode. For example, it is
1235 possible to construct LaTeX tables with the underlying ease and power of
1236 Orgtbl-mode, including spreadsheet capabilities. For details, see
1237 *Note Tables in arbitrary syntax::.
1240 File: org, Node: The spreadsheet, Prev: orgtbl-mode, Up: Tables
1245 The table editor makes use of the Emacs `calc' package to implement
1246 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1247 derive fields from other fields. While fully featured, Org-mode's
1248 implementation is not identical to other spreadsheets. For example,
1249 Org-mode knows the concept of a _column formula_ that will be applied
1250 to all non-header fields in a column without having to copy the formula
1251 to each relevant field.
1255 * References:: How to refer to another field or range
1256 * Formula syntax for Calc:: Using Calc to compute stuff
1257 * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
1258 * Field formulas:: Formulas valid for a single field
1259 * Column formulas:: Formulas valid for an entire column
1260 * Editing and debugging formulas:: Fixing formulas
1261 * Updating the table:: Recomputing all dependent fields
1262 * Advanced features:: Field names, parameters and automatic recalc
1265 File: org, Node: References, Next: Formula syntax for Calc, Prev: The spreadsheet, Up: The spreadsheet
1270 To compute fields in the table from other fields, formulas must
1271 reference other fields or ranges. In Org-mode, fields can be referenced
1272 by name, by absolute coordinates, and by relative coordinates. To find
1273 out what the coordinates of a field are, press `C-c ?' in that field,
1274 or press `C-c }' to toggle the display of a grid.
1279 Formulas can reference the value of another field in two ways. Like in
1280 any other spreadsheet, you may reference fields with a letter/number
1281 combination like `B3', meaning the 2nd field in the 3rd row.
1283 Org-mode also uses another, more general operator that looks like this:
1286 Column references can be absolute like `1', `2',...`N', or relative to
1287 the current column like `+1' or `-2'.
1289 The row specification only counts data lines and ignores horizontal
1290 separator lines (hlines). You can use absolute row numbers `1'...`N',
1291 and row numbers relative to the current row like `+3' or `-1'. Or
1292 specify the row relative to one of the hlines: `I' refers to the first
1293 hline, `II' to the second etc. `-I' refers to the first such line
1294 above the current line, `+I' to the first such line below the current
1295 line. You can also write `III+2' which is the second data line after
1296 the third hline in the table. Relative row numbers like `-3' will not
1297 cross hlines if the current line is too close to the hline. Instead,
1298 the value directly at the hline is used.
1300 `0' refers to the current row and column. Also, if you omit either
1301 the column or the row part of the reference, the current row/column is
1304 Org-mode's references with _unsigned_ numbers are fixed references
1305 in the sense that if you use the same reference in the formula for two
1306 different fields, the same field will be referenced each time.
1307 Org-mode's references with _signed_ numbers are floating references
1308 because the same reference operator can reference different fields
1309 depending on the field being calculated by the formula.
1311 Here are a few examples:
1313 @2$3 2nd row, 3rd column
1315 $5 column 5 in the current row
1317 @2 current column, row 2
1318 @-1$-3 the field one row up, three columns to the left
1319 @-I$2 field just under hline above current row, column 2
1324 You may reference a rectangular range of fields by specifying two field
1325 references connected by two dots `..'. If both fields are in the
1326 current row, you may simply use `$2..$7', but if at least one field is
1327 in a different row, you need to use the general `@row$column' format at
1328 least for the first field (i.e the reference must start with `@' in
1329 order to be interpreted correctly). Examples:
1331 $1..$3 First three fields in the current row.
1332 $P..$Q Range, using column names (see under Advanced)
1333 @2$1..@4$3 6 fields between these two fields.
1334 A2..C4 Same as above.
1335 @-1$-2..@-1 3 numbers from the column to the left, 2 up to current row
1337 Range references return a vector of values that can be fed into Calc
1338 vector functions. Empty fields in ranges are normally suppressed, so
1339 that the vector contains only the non-empty fields (but see the `E'
1340 mode switch below). If there are no non-empty fields, `[0]' is
1341 returned to avoid syntax errors in formulas.
1346 `$name' is interpreted as the name of a column, parameter or constant.
1347 Constants are defined globally through the variable
1348 `org-table-formula-constants'. If you have the `constants.el' package,
1349 it will also be used to resolve constants, including natural constants
1350 like `$h' for Planck's constant, and units like `$km' for
1351 kilometers(1). Column names and parameters can be specified in special
1352 table lines. These are described below, see *Note Advanced features::.
1353 All names must start with a letter, and further consist of letters and
1356 ---------- Footnotes ----------
1358 (1) `Constant.el' can supply the values of constants in two
1359 different unit systems, `SI' and `cgs'. Which one is used depends on
1360 the value of the variable `constants-unit-system'. You can use the
1361 `#+STARTUP' options `constSI' and `constcgs' to set this value for the
1365 File: org, Node: Formula syntax for Calc, Next: Formula syntax for Lisp, Prev: References, Up: The spreadsheet
1367 3.4.2 Formula syntax for Calc
1368 -----------------------------
1370 A formula can be any algebraic expression understood by the Emacs
1371 `Calc' package. Note that `calc' has the non-standard convention that
1372 `/' has lower precedence than `*', so that `a/b*c' is interpreted as
1373 `a/(b*c)'. Before evaluation by `calc-eval' (*note calc-eval:
1374 (calc)Calling Calc from Your Programs.), variable substitution takes
1375 place according to the rules described above. The range vectors can be
1376 directly fed into the calc vector functions like `vmean' and `vsum'.
1378 A formula can contain an optional mode string after a semicolon.
1379 This string consists of flags to influence Calc and other modes during
1380 execution. By default, Org-mode uses the standard calc modes (precision
1381 12, angular units degrees, fraction and symbolic modes off. The display
1382 format, however, has been changed to `(float 5)' to keep tables
1383 compact. The default settings can be configured using the variable
1384 `org-calc-default-modes'.
1386 p20 switch the internal precision to 20 digits
1387 n3 s3 e2 f4 normal, scientific, engineering, or fixed display format
1388 D R angle modes: degrees, radians
1389 F S fraction and symbolic modes
1390 N interpret all fields as numbers, use 0 for non-numbers
1391 T force text interpretation
1392 E keep empty fields in ranges
1394 In addition, you may provide a `printf' format specifier to reformat
1395 the final result. A few examples:
1397 $1+$2 Sum of first and second field
1398 $1+$2;%.2f Same, format result to two decimals
1399 exp($2)+exp($1) Math functions can be used
1400 $0;%.1f Reformat current cell to 1 decimal
1401 ($3-32)*5/9 Degrees F -> C conversion
1402 $c/$1/$cm Hz -> cm conversion, using `constants.el'
1403 tan($1);Dp3s1 Compute in degrees, precision 3, display SCI 1
1404 sin($1);Dp3%.1e Same, but use printf specifier for display
1405 vmean($2..$7) Compute column range mean, using vector function
1406 vmean($2..$7);EN Same, but treat empty fields as 0
1407 taylor($3,x=7,2) taylor series of $3, at x=7, second degree
1409 Calc also contains a complete set of logical operations. For example
1411 if($1<20,teen,string("")) "teen" if age $1 less than 20, else empty
1414 File: org, Node: Formula syntax for Lisp, Next: Field formulas, Prev: Formula syntax for Calc, Up: The spreadsheet
1416 3.4.3 Emacs Lisp forms as formulas
1417 ----------------------------------
1419 It is also possible to write a formula in Emacs Lisp; this can be useful
1420 for string manipulation and control structures, if the Calc's
1421 functionality is not enough. If a formula starts with a single quote
1422 followed by an opening parenthesis, then it is evaluated as a lisp form.
1423 The evaluation should return either a string or a number. Just as with
1424 `calc' formulas, you can specify modes and a printf format after a
1425 semicolon. A reference will be replaced with a string (in double
1426 quotes) containing the field. If you provide the `N' mode switch, all
1427 referenced elements will be numbers. Ranges are inserted as
1428 space-separated fields, so you can embed them in list or vector syntax.
1429 A few examples, note how the `N' mode is used when we do computations
1432 Swap the first two characters of the content of column 1
1433 '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
1434 Add columns 1 and 2, equivalent to the Calc's `$1+$2'
1436 Compute the sum of columns 1-4, like Calc's `vsum($1..$4)'
1437 '(apply '+ '($1..$4));N
1440 File: org, Node: Field formulas, Next: Column formulas, Prev: Formula syntax for Lisp, Up: The spreadsheet
1442 3.4.4 Field formulas
1443 --------------------
1445 To assign a formula to a particular field, type it directly into the
1446 field, preceded by `:=', for example `:=$1+$2'. When you press <TAB>
1447 or <RET> or `C-c C-c' with the cursor still in the field, the formula
1448 will be stored as the formula for this field, evaluated, and the
1449 current field replaced with the result.
1451 Formulas are stored in a special line starting with `#+TBLFM:'
1452 directly below the table. If you typed the equation in the 4th field of
1453 the 3rd data line in the table, the formula will look like
1454 `@3$4=$1+$2'. When inserting/deleting/swapping column and rows with
1455 the appropriate commands, absolute references (but not relative ones)
1456 in stored formulas are modified in order to still reference the same
1457 field. Of cause this is not true if you edit the table structure with
1458 normal editing commands - then you must fix the equations yourself.
1460 Instead of typing an equation into the field, you may also use the
1464 Install a new formula for the current field. The command prompts
1465 for a formula, with default taken from the `#+TBLFM:' line, applies
1466 it to the current field and stores it.
1469 File: org, Node: Column formulas, Next: Editing and debugging formulas, Prev: Field formulas, Up: The spreadsheet
1471 3.4.5 Column formulas
1472 ---------------------
1474 Often in a table, the same formula should be used for all fields in a
1475 particular column. Instead of having to copy the formula to all fields
1476 in that column, org-mode allows to assign a single formula to an entire
1477 column. If the table contains horizontal separator hlines, everything
1478 before the first such line is considered part of the table _header_ and
1479 will not be modified by column formulas.
1481 To assign a formula to a column, type it directly into any field in
1482 the column, preceded by an equal sign, like `=$1+$2'. When you press
1483 <TAB> or <RET> or `C-c C-c' with the cursor still in the field, the
1484 formula will be stored as the formula for the current column, evaluated
1485 and the current field replaced with the result. If the field contains
1486 only `=', the previously stored formula for this column is used. For
1487 each column, Org-mode will only remember the most recently used
1488 formula. In the `TBLFM:' line, column formulas will look like
1491 Instead of typing an equation into the field, you may also use the
1495 Install a new formula for the current column and replace current
1496 field with the result of the formula. The command prompts for a
1497 formula, with default taken from the `#+TBLFM' line, applies it to
1498 the current field and stores it. With a numerical prefix (e.g.
1499 `C-5 C-c =') will apply it to that many consecutive fields in the
1503 File: org, Node: Editing and debugging formulas, Next: Updating the table, Prev: Column formulas, Up: The spreadsheet
1505 3.4.6 Editing and Debugging formulas
1506 ------------------------------------
1508 You can edit individual formulas in the minibuffer or directly in the
1509 field. Org-mode can also prepare a special buffer with all active
1510 formulas of a table. When offering a formula for editing, Org-mode
1511 converts references to the standard format (like `B3' or `D&') if
1512 possible. If you prefer to only work with the internal format (like
1513 `@3$2' or `$4'), configure the variable
1514 `org-table-use-standard-references'.
1518 Edit the formula associated with the current column/field in the
1519 minibuffer. See *Note Column formulas:: and *Note Field
1523 Re-insert the active formula (either a field formula, or a column
1524 formula) into the current field, so that you can edit it directly
1525 in the field. The advantage over editing in the minibuffer is
1526 that you can use the command `C-c ?'.
1529 While editing a formula in a table field, highlight the field(s)
1530 referenced by the reference at the cursor position in the formula.
1533 Toggle the display of row and column numbers for a table, using
1534 overlays. These are updated each time the table is aligned, you
1535 can force it with `C-c C-c'.
1538 Toggle the formula debugger on and off. See below.
1541 Edit all formulas for the current table in a special buffer, where
1542 the formulas will be displayed one per line. If the current field
1543 has an active formula, the cursor in the formula editor will mark
1544 it. While inside the special buffer, Org-mode will automatically
1545 highlight any field or range reference at the cursor position.
1546 You may edit, remove and add formulas, and use the following
1550 Exit the formula editor and store the modified formulas.
1551 With `C-u' prefix, also apply the new formulas to the entire
1555 Exit the formula editor without installing changes.
1558 Toggle all references in the formula editor between standard
1559 (like `B3') and internal (like `@3$2').
1562 Pretty-print or indent lisp formula at point. When in a line
1563 containing a lisp formula, format the formula according to
1564 Emacs Lisp rules. Another <TAB> collapses the formula back
1565 again. In the open formula, <TAB> re-indents just like in
1569 Complete Lisp symbols, just like in Emacs-lisp-mode.
1571 `S-<up>/<down>/<left>/<right>'
1572 Shift the reference at point. For example, if the reference
1573 is `B3' and you press `S-<right>', it will become `C3'. This
1574 also works for relative references, and for hline references.
1577 Move the test line for column formulas in the Org-mode buffer
1581 Scroll the window displaying the table.
1584 Turn the coordinate grid in the table on and off.
1586 Making a table field blank does not remove the formula associated
1587 with the field, because that is stored in a different line (the `TBLFM'
1588 line) - during the next recalculation the field will be filled again.
1589 To remove a formula from a field, you have to give an empty reply when
1590 prompted for the formula, or to edit the `#+TBLFM' line.
1592 You may edit the `#+TBLFM' directly and re-apply the changed
1593 equations with `C-c C-c' in that line, or with the normal recalculation
1594 commands in the table.
1599 When the evaluation of a formula leads to an error, the field content
1600 becomes the string `#ERROR'. If you would like see what is going on
1601 during variable substitution and calculation in order to find a bug,
1602 turn on formula debugging in the `Tbl' menu and repeat the calculation,
1603 for example by pressing `C-u C-u C-c = <RET>' in a field. Detailed
1604 information will be displayed.
1607 File: org, Node: Updating the table, Next: Advanced features, Prev: Editing and debugging formulas, Up: The spreadsheet
1609 3.4.7 Updating the Table
1610 ------------------------
1612 Recalculation of a table is normally not automatic, but needs to be
1613 triggered by a command. See *Note Advanced features:: for a way to make
1614 recalculation at least semi-automatically.
1616 In order to recalculate a line of a table or the entire table, use
1617 the following commands:
1620 Recalculate the current row by first applying the stored column
1621 formulas from left to right, and all field formulas in the current
1626 Recompute the entire table, line by line. Any lines before the
1627 first hline are left alone, assuming that these are part of the
1631 Iterate the table by recomputing it until no further changes occur.
1632 This may be necessary if some computed fields use the value of
1633 other fields that are computed later in the calculation sequence.
1636 File: org, Node: Advanced features, Prev: Updating the table, Up: The spreadsheet
1638 3.4.8 Advanced features
1639 -----------------------
1641 If you want the recalculation of fields to happen automatically, or if
1642 you want to be able to assign names to fields and columns, you need to
1643 reserve the first column of the table for special marking characters.
1645 Rotate the calculation mark in first column through the states `',
1646 `#', `*', `!', `$'. The meaning of these characters is discussed
1647 below. When there is an active region, change all marks in the
1650 Here is an example of a table that collects exam results of students
1651 and makes use of these features:
1653 |---+---------+--------+--------+--------+-------+------|
1654 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1655 |---+---------+--------+--------+--------+-------+------|
1656 | ! | | P1 | P2 | P3 | Tot | |
1657 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
1658 | ^ | | m1 | m2 | m3 | mt | |
1659 |---+---------+--------+--------+--------+-------+------|
1660 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
1661 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
1662 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
1663 |---+---------+--------+--------+--------+-------+------|
1664 | | Average | | | | 29.7 | |
1665 | ^ | | | | | at | |
1666 | $ | max=50 | | | | | |
1667 |---+---------+--------+--------+--------+-------+------|
1668 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f
1670 Important: Please note that for these special tables, recalculating the
1671 table with `C-u C-c *' will only affect rows that are marked `#' or
1672 `*', and fields that have a formula assigned to the field itself. The
1673 column formulas are not applied in rows with empty first field.
1675 The marking characters have the following meaning:
1677 The fields in this line define names for the columns, so that you
1678 may refer to a column as `$Tot' instead of `$6'.
1681 This row defines names for the fields _above_ the row. With such
1682 a definition, any formula in the table may use `$m1' to refer to
1683 the value `10'. Also, if you assign a formula to a names field, it
1684 will be stored as `$name=...'.
1687 Similar to `^', but defines names for the fields in the row
1691 Fields in this row can define _parameters_ for formulas. For
1692 example, if a field in a `$' row contains `max=50', then formulas
1693 in this table can refer to the value 50 using `$max'. Parameters
1694 work exactly like constants, only that they can be defined on a
1698 Fields in this row are automatically recalculated when pressing
1699 <TAB> or <RET> or `S-<TAB>' in this row. Also, this row is
1700 selected for a global recalculation with `C-u C-c *'. Unmarked
1701 lines will be left alone by this command.
1704 Selects this line for global recalculation with `C-u C-c *', but
1705 not for automatic recalculation. Use this when automatic
1706 recalculation slows down editing too much.
1709 Unmarked lines are exempt from recalculation with `C-u C-c *'.
1710 All lines that should be recalculated should be marked with `#' or
1714 Do not export this line. Useful for lines that contain the
1715 narrowing `<N>' markers.
1717 Finally, just to whet your appetite on what can be done with the
1718 fantastic `calc' package, here is a table that computes the Taylor
1719 series of degree `n' at location `x' for a couple of functions
1720 (homework: try that with Excel :-)
1722 |---+-------------+---+-----+--------------------------------------|
1723 | | Func | n | x | Result |
1724 |---+-------------+---+-----+--------------------------------------|
1725 | # | exp(x) | 1 | x | 1 + x |
1726 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
1727 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
1728 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1729 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
1730 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
1731 |---+-------------+---+-----+--------------------------------------|
1732 #+TBLFM: $5=taylor($2,$4,$3);n3
1735 File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top
1740 Just like HTML, Org-mode provides links inside a file, and external
1741 links to other files, Usenet articles, emails, and much more.
1745 * Link format:: How links in Org-mode are formatted
1746 * Internal links:: Links to other places in the current file
1747 * External links:: URL-like links to the world
1748 * Handling links:: Creating, inserting and following
1749 * Link abbreviations:: Shortcuts for writing complex links
1750 * Search options:: Linking to a specific location
1751 * Custom searches:: When the default search is not enough
1752 * Remember:: Org-trees store quick notes
1755 File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks
1760 Org-mode will recognize plain URL-like links and activate them as
1761 clickable links. The general link format, however, looks like this:
1763 [[link][description]] or alternatively [[link]]
1765 Once a link in the buffer is complete (all brackets present),
1766 Org-mode will change the display so that `description' is displayed
1767 instead of `[[link][description]]' and `link' is displayed instead of
1768 `[[link]]'. Links will be highlighted in the face `org-link', which by
1769 default is an underlined face. You can directly edit the visible part
1770 of a link. Note that this can be either the `link' part (if there is
1771 no description) or the `description' part. To edit also the invisible
1772 `link' part, use `C-c C-l' with the cursor on the link.
1774 If you place the cursor at the beginning or just behind the end of
1775 the displayed text and press <BACKSPACE>, you will remove the
1776 (invisible) bracket at that location. This makes the link incomplete
1777 and the internals are again displayed as plain text. Inserting the
1778 missing bracket hides the link internals again. To show the internal
1779 structure of all links, use the menu entry `Org->Hyperlinks->Literal
1783 File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks
1788 If the link does not look like a URL, it is considered to be internal in
1789 the current file. Links such as `[[My Target]]' or `[[My Target][Find
1790 my target]]' lead to a text search in the current file. The link can
1791 be followed with `C-c C-o' when the cursor is on the link, or with a
1792 mouse click (*note Handling links::). The preferred match for such a
1793 link is a dedicated target: the same string in double angular brackets.
1794 Targets may be located anywhere; sometimes it is convenient to put
1795 them into a comment line. For example
1799 In HTML export (*note HTML export::), such targets will become named
1800 anchors for direct access through `http' links(1).
1802 If no dedicated target exists, Org-mode will search for the words in
1803 the link. In the above example the search would be for `my target'.
1804 Links starting with a star like `*My Target' restrict the search to
1805 headlines. When searching, Org-mode will first try an exact match, but
1806 then move on to more and more lenient searches. For example, the link
1807 `[[*My Targets]]' will find any of the following:
1810 ** TODO my targets are bright
1811 ** my 20 targets are
1813 To insert a link targeting a headline, in-buffer completion can be
1814 used. Just type a star followed by a few optional letters into the
1815 buffer and press `M-<TAB>'. All headlines in the current buffer will be
1816 offered as completions. *Note Handling links::, for more commands
1819 Following a link pushes a mark onto Org-mode's own mark ring. You
1820 can return to the previous position with `C-c &'. Using this command
1821 several times in direct succession goes back to positions recorded
1826 * Radio targets:: Make targets trigger links in plain text.
1828 ---------- Footnotes ----------
1830 (1) Note that text before the first headline will never be exported,
1831 so the first such target must be after the first headline.
1834 File: org, Node: Radio targets, Prev: Internal links, Up: Internal links
1839 You can configure Org-mode to link any occurrences of certain target
1840 names in normal text. So without explicitly creating a link, the text
1841 connects to the target radioing its position. Radio targets are
1842 enclosed by triple angular brackets. For example, a target `<<<My
1843 Target>>>' causes each occurrence of `my target' in normal text to
1844 become activated as a link. The Org-mode file is scanned automatically
1845 for radio targets only when the file is first loaded into Emacs. To
1846 update the target list during editing, press `C-c C-c' with the cursor
1850 File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks
1855 Org-mode supports links to files, websites, Usenet and email messages,
1856 and BBDB database entries. External links are URL-like locators. They
1857 start with a short identifying string followed by a colon. There can be
1858 no space after the colon. The following list shows examples for each
1861 http://www.astro.uva.nl/~dominik on the web
1862 file:/home/dominik/images/jupiter.jpg file, absolute path
1863 file:papers/last.pdf file, relative path
1864 news:comp.emacs Usenet link
1865 mailto:adent@galaxy.net Mail link
1866 vm:folder VM folder link
1867 vm:folder#id VM message link
1868 vm://myself@some.where.org/folder#id VM on remote machine
1869 wl:folder WANDERLUST folder link
1870 wl:folder#id WANDERLUST message link
1871 mhe:folder MH-E folder link
1872 mhe:folder#id MH-E message link
1873 rmail:folder RMAIL folder link
1874 rmail:folder#id RMAIL message link
1875 gnus:group GNUS group link
1876 gnus:group#id GNUS article link
1877 bbdb:Richard Stallman BBDB link
1878 shell:ls *.org A shell command
1879 elisp:(find-file-other-frame "Elisp.org") An elisp form to evaluate
1881 A link should be enclosed in double brackets and may contain a
1882 descriptive text to be displayed instead of the url (*note Link
1883 format::), for example:
1885 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
1887 If the description is a file name or URL that points to an image, HTML
1888 export (*note HTML export::) will inline the image as a clickable
1889 button. If there is no description at all and the link points to an
1890 image, that image will be inlined into the exported HTML file.
1892 Org-mode also finds external links in the normal text and activates
1893 them as links. If spaces must be part of the link (for example in
1894 `bbdb:Richard Stallman'), or if you need to remove ambiguities about
1895 the end of the link, enclose them in angular brackets.
1898 File: org, Node: Handling links, Next: Link abbreviations, Prev: External links, Up: Hyperlinks
1903 Org-mode provides methods to create a link in the correct syntax, to
1904 insert it into an org-mode file, and to follow the link.
1907 Store a link to the current location. This is a _global_ command
1908 which can be used in any buffer to create a link. The link will be
1909 stored for later insertion into an Org-mode buffer (see below).
1910 For Org-mode files, if there is a `<<target>>' at the cursor, the
1911 link points to the target. Otherwise it points to the current
1912 headline. For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers,
1913 the link will indicate the current article/entry. For W3 and W3M
1914 buffers, the link goes to the current URL. For any other files,
1915 the link will point to the file, with a search string (*note
1916 Search options::) pointing to the contents of the current line.
1917 If there is an active region, the selected words will form the
1918 basis of the search string. If the automatically created link is
1919 not working correctly or accurately enough, you can write custom
1920 functions to select the search string and to do the search for
1921 particular file types - see *Note Custom searches::. The key
1922 binding `C-c l' is only a suggestion - see *Note Installation::.
1925 Insert a link. This prompts for a link to be inserted into the
1926 buffer. You can just type a link, using text for an internal
1927 link, or one of the link type prefixes mentioned in the examples
1928 above. All links stored during the current session are part of
1929 the history for this prompt, so you can access them with <up> and
1930 <down>, or with completion(1). The link will be inserted into the
1931 buffer, along with a descriptive text. If some text was selected
1932 when this command is called, the selected text becomes the default
1934 Note that you don't have to use this command to insert a link.
1935 Links in Org-mode are plain text, and you can type or paste them
1936 straight into the buffer. By using this command, the links are
1937 automatically enclosed in double brackets, and you will be asked
1938 for the optional descriptive text.
1941 When `C-c C-l' is called with a `C-u' prefix argument, a link to a
1942 file will be inserted and you may use file name completion to
1943 select the name of the file. The path to the file is inserted
1944 relative to the directory of the current org file, if the linked
1945 file is in the current directory or in a subdirectory of it, or if
1946 the path is written relative to the current directory using `../'.
1947 Otherwise an absolute path is used, if possible with `~/' for
1948 your home directory. You can force an absolute path with two
1951 `C-c C-l (with cursor on existing link)'
1952 When the cursor is on an existing link, `C-c C-l' allows you to
1953 edit the link and description parts of the link.
1956 Open link at point. This will launch a web browser for URLs (using
1957 `browse-url-at-point'), run vm/mh-e/wanderlust/rmail/gnus/bbdb for
1958 the corresponding links, and execute the command in a shell link.
1959 When the cursor is on an internal link, this commands runs the
1960 corresponding search. When the cursor is on a TAG list in a
1961 headline, it creates the corresponding TAGS view. If the cursor
1962 is on a time stamp, it compiles the agenda for that date.
1963 Furthermore, it will visit text and remote files in `file:' links
1964 with Emacs and select a suitable application for local non-text
1965 files. Classification of files is based on file extension only.
1966 See option `org-file-apps'. If you want to override the default
1967 application and visit the file with Emacs, use a `C-u' prefix.
1971 On links, `mouse-2' will open the link just as `C-c C-o' would.
1972 Under Emacs 22, also `mouse-1' will follow a link.
1975 Like `mouse-2', but force file links to be opened with Emacs, and
1976 internal links to be displayed in another window(2).
1979 Push the current position onto the mark ring, to be able to return
1980 easily. Commands following an internal link do this automatically.
1983 Jump back to a recorded position. A position is recorded by the
1984 commands following internal links, and by `C-c %'. Using this
1985 command several times in direct succession moves through a ring of
1986 previously recorded positions.
1990 Move forward/backward to the next link in the buffer. At the
1991 limit of the buffer, the search fails once, and then wraps around.
1992 The key bindings for this are really too long, you might want to
1993 bind this also to `C-n' and `C-p'
1994 (add-hook 'org-load-hook
1996 (define-key 'org-mode-map "\C-n" 'org-next-link)
1997 (define-key 'org-mode-map "\C-p" 'org-previous-link)))
1999 ---------- Footnotes ----------
2001 (1) After insertion of a stored link, the link will be removed from
2002 the list of stored links. To keep it in the list later use, use a
2003 triple `C-u' prefix to `C-c C-l', or configure the option
2004 `org-keep-stored-link-after-insertion'.
2006 (2) See the variable `org-display-internal-link-with-indirect-buffer'
2009 File: org, Node: Link abbreviations, Next: Search options, Prev: Handling links, Up: Hyperlinks
2011 4.5 Link abbreviations
2012 ======================
2014 Long URLs can be cumbersome to type, and often many similar links are
2015 needed in a document. For this you can use link abbreviations. An
2016 abbreviated link looks like this
2018 [[linkword:tag][description]]
2020 where the tag is optional. Such abbreviations are resolved according to
2021 the information in the variable `org-link-abbrev-alist' that relates
2022 the linkwords to replacement text. Here is an example:
2024 (setq org-link-abbrev-alist
2025 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
2026 ("google" . "http://www.google.com/search?q=")
2027 ("ads" . "http://adsabs.harvard.edu/cgi-bin/
2028 nph-abs_connect?author=%s&db_key=AST")))
2030 If the replacement text contains the string `%s', it will be
2031 replaced with the tag. Otherwise the tag will be appended to the string
2032 in order to create the link. You may also specify a function that will
2033 be called with the tag as the only argument to create the link.
2035 With the above setting, you could link to a specific bug with
2036 `[[bugzilla:129]]', search the web for `OrgMode' with
2037 `[[google:OrgMode]]' and find out what the Org-mode author is doing
2038 besides Emacs hacking with `[[ads:Dominik,C]]'.
2040 If you need special abbreviations just for a single Org-mode buffer,
2041 you can define them in the file with
2043 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
2044 #+LINK: google http://www.google.com/search?q=%s
2046 In-buffer completion *note Completion:: can be used after `[' to
2047 complete link abbreviations.
2050 File: org, Node: Search options, Next: Custom searches, Prev: Link abbreviations, Up: Hyperlinks
2052 4.6 Search options in file links
2053 ================================
2055 File links can contain additional information to make Emacs jump to a
2056 particular location in the file when following a link. This can be a
2057 line number or a search option after a double(1) colon. For example,
2058 when the command `C-c l' creates a link (*note Handling links::) to a
2059 file, it encodes the words in the current line as a search string that
2060 can be used to find this line back later when following the link with
2063 Here is the syntax of the different ways to attach a search to a file
2064 link, together with an explanation:
2066 [[file:~/code/main.c::255]]
2067 [[file:~/xx.org::My Target]]
2068 [[file:~/xx.org::*My Target]]
2069 [[file:~/xx.org::/regexp/]]
2075 Search for a link target `<<My Target>>', or do a text search for
2076 `my target', similar to the search in internal links, see *Note
2077 Internal links::. In HTML export (*note HTML export::), such a
2078 file link will become an HTML reference to the corresponding named
2079 anchor in the linked file.
2082 In an Org-mode file, restrict search to headlines.
2085 Do a regular expression search for `regexp'. This uses the Emacs
2086 command `occur' to list all matches in a separate window. If the
2087 target file is in Org-mode, `org-occur' is used to create a sparse
2088 tree with the matches.
2090 As a degenerate case, a file link with an empty file name can be used
2091 to search the current file. For example, `[[file:::find me]]' does a
2092 search for `find me' in the current file, just as `[[find me]]' would.
2094 ---------- Footnotes ----------
2096 (1) For backward compatibility, line numbers can also follow a
2100 File: org, Node: Custom searches, Next: Remember, Prev: Search options, Up: Hyperlinks
2105 The default mechanism for creating search strings and for doing the
2106 actual search related to a file link may not work correctly in all
2107 cases. For example, BibTeX database files have many entries like
2108 `year="1993"' which would not result in good search strings, because
2109 the only unique identification for a BibTeX entry is the citation key.
2111 If you come across such a problem, you can write custom functions to
2112 set the right search string for a particular file type, and to do the
2113 search for the string in the file. Using `add-hook', these functions
2114 need to be added to the hook variables
2115 `org-create-file-search-functions' and
2116 `org-execute-file-search-functions'. See the docstring for these
2117 variables for more information. Org-mode actually uses this mechanism
2118 for BibTeX database files, and you can use the corresponding code as an
2119 implementation example. Search for `BibTeX links' in the source file.
2122 File: org, Node: Remember, Prev: Custom searches, Up: Hyperlinks
2127 Another way to create org entries with links to other files is through
2128 the remember package by John Wiegley. Remember lets you store quick
2129 notes with little interruption of your work flow. See
2130 `http://www.emacswiki.org/cgi-bin/wiki/RememberMode' for more
2131 information. The notes produced by Remember can be stored in different
2132 ways, and Org-mode files are a good target. Org-mode significantly
2133 expands the possibilities of remember: You may define templates for
2134 different note types, and to associate target files and headlines with
2135 specific templates. It also allows you to select the location where a
2136 note should be stored interactively, on the fly.
2140 * Setting up remember:: Some code for .emacs to get things going
2141 * Remember templates:: Define the outline of different note types
2142 * Storing notes:: Directly get the note to where it belongs
2145 File: org, Node: Setting up remember, Next: Remember templates, Prev: Remember, Up: Remember
2147 4.8.1 Setting up remember
2148 -------------------------
2150 The following customization will tell remember to use org files as
2151 target, and to create annotations compatible with Org-mode links.
2153 (setq org-directory "~/path/to/my/orgfiles/")
2154 (setq org-default-notes-file "~/.notes")
2155 (setq remember-annotation-functions '(org-remember-annotation))
2156 (setq remember-handler-functions '(org-remember-handler))
2157 (add-hook 'remember-mode-hook 'org-remember-apply-template)
2160 File: org, Node: Remember templates, Next: Storing notes, Prev: Setting up remember, Up: Remember
2162 4.8.2 Remember templates
2163 ------------------------
2165 In combination with Org-mode, you can use templates to generate
2166 different types of remember notes. For example, if you would like to
2167 use one template to create general TODO entries, another one for
2168 journal entries, and a third one for collecting random ideas, you could
2171 (setq org-remember-templates
2172 '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org")
2173 (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")
2174 (?i "* %^{Title}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas")))
2176 In these entries, the character specifies how to select the template.
2177 The first string specifies the template. Two more (optional) strings
2178 give the file in which, and the headline under which the new note
2179 should be stored. The file defaults (if not present or `nil') to
2180 `org-default-notes-file', the heading to
2181 `org-remember-default-headline'. Both defaults help to get to the
2182 storing location quickly, but you can change the location interactively
2183 while storing the note.
2185 When you call `M-x remember' (or `M-x org-remember') to remember
2186 something, org will prompt for a key to select the template (if you have
2187 more than one template) and then prepare the buffer like
2189 [[file:link to where you called remember]]
2193 * [2006-03-21 Tue 15:37]
2195 [[file:link to where you called remember]]
2197 During expansion of the template, special `%'-escapes allow dynamic
2198 insertion of content:
2199 %^{prompt} prompt the user for a string and replace this sequence with it.
2200 %t time stamp, date only
2201 %T time stamp with date and time
2202 %u, %U like the above, but inactive time stamps
2203 %^t like `%t', but prompt for date. Similarly `%^T', `%^u', `%^U'
2204 You may define a prompt like `%^{Birthday}t'
2205 %n user name (taken from `user-full-name')
2206 %a annotation, normally the link created with `org-store-link'
2207 %i initial content, the region when remember is called with C-u.
2208 The entire text will be indented like `%i' itself.
2209 %:keyword specific information for certain link types, see below
2211 For specific link types, the following keywords will be defined:
2213 Link type | Available keywords
2214 -------------------+----------------------------------------------
2215 bbdb | %:name %:company
2216 vm, wl, mh, rmail | %:type %:subject %:message-id
2217 | %:from %:fromname %:fromaddress
2218 | %:to %:toname %:toaddress
2219 | %:fromto (either "to NAME" or "from NAME")(1)
2220 gnus | %:group, for messages also all email fields
2222 info | %:file %:node
2225 To place the cursor after template expansion use:
2227 %? After completing the template, position cursor here.
2229 If you change you mind about which template to use, call `org-remember'
2230 in the remember buffer. You may then select a new template that will
2231 be filled with the previous context information.
2233 ---------- Footnotes ----------
2235 (1) This will always be the other, not the user. See the variable
2236 `org-from-is-user-regexp'.
2239 File: org, Node: Storing notes, Prev: Remember templates, Up: Remember
2244 When you are finished preparing a note with remember, you have to press
2245 `C-c C-c' to file the note away. The handler first prompts for a
2246 target file - if you press <RET>, the value specified for the template
2247 is used. Then the command offers the headings tree of the selected
2248 file, with the cursor position at the default headline (if you had
2249 specified one in the template). You can either immediately press <RET>
2250 to get the note placed there. Or you can use the following keys to
2251 find a better location:
2252 <TAB> Cycle visibility.
2253 <down> / <up> Next/previous visible headline.
2254 n / p Next/previous visible headline.
2255 f / b Next/previous headline same level.
2257 Pressing <RET> or <left> or <right> then leads to the following
2260 Cursor Key Note gets inserted
2262 buffer-start <RET> as level 2 heading at end of file
2263 on headline <RET> as sublevel of the heading at cursor
2264 <left>/<right>as same level, before/after current heading
2265 not on <RET> at cursor position, level taken from context.
2268 So a fast way to store the note to its default location is to press
2269 `C-c C-c <RET> <RET>'. Even shorter would be `C-u C-c C-c', which does
2270 the same without even asking for a file or showing the tree.
2272 Before inserting the text into a tree, the function ensures that the
2273 text has a headline, i.e. a first line that starts with a `*'. If not,
2274 a headline is constructed from the current date and some additional
2275 data. If the variable `org-adapt-indentation' is non-nil, the entire
2276 text is also indented so that it starts in the same column as the
2277 headline (after the asterisks).
2280 File: org, Node: TODO items, Next: Timestamps, Prev: Hyperlinks, Up: Top
2285 Org-mode does not maintain TODO lists as a separate document. TODO
2286 items are an integral part of the notes file, because TODO items
2287 usually come up while taking notes! With Org-mode, you simply mark any
2288 entry in a tree as being a TODO item. In this way, the information is
2289 not duplicated, and the entire context from which the item emerged is
2290 always present when you check.
2292 Of course, this technique causes TODO items to be scattered
2293 throughout your file. Org-mode provides methods to give you an
2294 overview over all things you have to do.
2298 * TODO basics:: Marking and displaying TODO entries
2299 * TODO extensions:: Workflow and assignments
2300 * Priorities:: Some things are more important than others
2301 * Breaking down tasks:: Splitting a task into manageable pieces
2302 * Checkboxes:: Tick-off lists
2305 File: org, Node: TODO basics, Next: TODO extensions, Prev: TODO items, Up: TODO items
2307 5.1 Basic TODO functionality
2308 ============================
2310 Any headline can become a TODO item by starting it with the word TODO,
2313 *** TODO Write letter to Sam Fortune
2315 The most important commands to work with TODO entries are:
2318 Rotate the TODO state of the current item among
2320 ,-> (unmarked) -> TODO -> DONE --.
2321 '--------------------------------'
2323 The same rotation can also be done "remotely" from the timeline and
2324 agenda buffers with the `t' command key (*note Agenda commands::).
2328 Select the following/preceding TODO state, similar to cycling.
2329 Mostly useful if more than two TODO states are possible (*note
2333 View TODO items in a _sparse tree_ (*note Sparse trees::). Folds
2334 the entire buffer, but shows all TODO items and the headings
2335 hierarchy above them. With prefix arg, search for a specific
2336 TODO. You will be prompted for the keyword, and you can also give
2337 a list of keywords like `kwd1|kwd2|...'. With numerical prefix N,
2338 show the tree for the Nth keyword in the variable
2339 `org-todo-keywords'. With two prefix args, find all TODO and DONE
2343 Show the global TODO list. This collects the TODO items from all
2344 agenda files (*note Agenda views::) into a single buffer. The
2345 buffer is in `agenda-mode', so there are commands to examine and
2346 manipulate the TODO entries directly from that buffer (*note
2347 Agenda commands::). *Note Global TODO list::, for more
2351 File: org, Node: TODO extensions, Next: Priorities, Prev: TODO basics, Up: TODO items
2353 5.2 Extended use of TODO keywords
2354 =================================
2356 The default implementation of TODO entries is just two states: TODO and
2357 DONE. You can use the TODO feature for more complicated things by
2358 configuring the variable `org-todo-keywords'. With special setup, the
2359 TODO keyword system can work differently in different files.
2361 Note that tags are another way to classify headlines in general and
2362 TODO items in particular (*note Tags::).
2366 * Workflow states:: From TODO to DONE in steps
2367 * TODO types:: I do this, Fred the rest
2368 * Multiple sets in one file:: Mixing it all, and still finding your way
2369 * Per file keywords:: Different files, different requirements
2372 File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, Up: TODO extensions
2374 5.2.1 TODO keywords as workflow states
2375 --------------------------------------
2377 You can use TODO keywords to indicate different _sequential_ states in
2378 the process of working on an item, for example(1):
2380 (setq org-todo-keywords
2381 '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
2383 The vertical bar separates the TODO keywords (states that _need
2384 action_) from the DONE states (which need _no further action_. If you
2385 don't provide the separator bar, the last state is used as the DONE
2386 state. With this setup, the command `C-c C-t' will cycle an entry from
2387 TODO to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED.
2388 You may also use a prefix argument to quickly select a specific state.
2389 For example `C-3 C-c C-t' will change the state immediately to VERIFY.
2390 If you define many keywords, you can use in-buffer completion (see
2391 *Note Completion::) to insert these words into the buffer. Changing a
2392 todo state can be logged with a timestamp, see *Note Tracking TODO
2393 state changes:: for more information.
2395 ---------- Footnotes ----------
2397 (1) Changing this variable only becomes effective after restarting
2398 Org-mode in a buffer.
2401 File: org, Node: TODO types, Next: Multiple sets in one file, Prev: Workflow states, Up: TODO extensions
2403 5.2.2 TODO keywords as types
2404 ----------------------------
2406 The second possibility is to use TODO keywords to indicate different
2407 _types_ of action items. For example, you might want to indicate that
2408 items are for "work" or "home". Or, when you work with several people
2409 on a single project, you might want to assign action items directly to
2410 persons, by using their names as TODO keywords. This would be set up
2413 (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
2415 In this case, different keywords do not indicate a sequence, but
2416 rather different types. So the normal work flow would be to assign a
2417 task to a person, and later to mark it DONE. Org-mode supports this
2418 style by adapting the workings of the command `C-c C-t'(1). When used
2419 several times in succession, it will still cycle through all names, in
2420 order to first select the right type for a task. But when you return
2421 to the item after some time and execute `C-c C-t' again, it will switch
2422 from any name directly to DONE. Use prefix arguments or completion to
2423 quickly select a specific name. You can also review the items of a
2424 specific TODO type in a sparse tree by using a numeric prefix to `C-c
2425 C-v'. For example, to see all things Lucy has to do, you would use
2426 `C-3 C-c C-v'. To collect Lucy's items from all agenda files into a
2427 single buffer, you would use the prefix arg as well when creating the
2428 global todo list: `C-3 C-c t'.
2430 ---------- Footnotes ----------
2432 (1) This is also true for the `t' command in the timeline and agenda
2436 File: org, Node: Multiple sets in one file, Next: Per file keywords, Prev: TODO types, Up: TODO extensions
2438 5.2.3 Multiple keyword sets in one file
2439 ---------------------------------------
2441 Sometimes you may want to use different sets of TODO keywords in
2442 parallel. For example, you may want to have the basic `TODO'/`DONE',
2443 but also a workflow for bug fixing, and a separate state indicating
2444 that an item has been canceled (so it is not DONE, but also does not
2445 require action). Your setup would then look like this:
2447 (setq org-todo-keywords
2448 '((sequence "TODO" "|" "DONE")
2449 (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
2450 (sequence "|" "CANCELED")))
2452 The keywords should all be different, this helps Org-mode to keep
2453 track of which subsequence should be used for a given entry. In this
2454 setup, `C-c C-t' only operates within a subsequence, so it switches from
2455 `DONE' to (nothing) to `TODO', and from `FIXED' to (nothing) to
2456 `REPORT'. Therefore you need a mechanism to initially select the
2457 correct sequence. Besides the obvious ways like typing a keyword or
2458 using completion, you may also apply the following commands:
2462 These keys jump from one TODO subset to the next. In the above
2463 example, `C-S-<right>' would jump from `TODO' or `DONE' to
2464 `REPORT', and any of the words in the second row to `CANCELED'.
2468 `S-<<left>>' and `S-<<right>>' and walk through _all_ keywords
2469 from all sets, so for example `S-<<right>>' would switch from
2470 `DONE' to `REPORT' in the example above.
2473 File: org, Node: Per file keywords, Prev: Multiple sets in one file, Up: TODO extensions
2475 5.2.4 Setting up keywords for individual files
2476 ----------------------------------------------
2478 It can be very useful to use different aspects of the TODO mechanism in
2479 different files. For file-local settings, you need to add special lines
2480 to the file which set the keywords and interpretation for that file
2481 only. For example, to set one of the two examples discussed above, you
2482 need one of the following lines, starting in column zero anywhere in the
2485 #+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED
2487 #+TYP_TODO: Fred Sara Lucy Mike | DONE
2489 A setup for using several sets in parallel would be:
2491 #+SEQ_TODO: "TODO" "|" "DONE"
2492 #+SEQ_TODO: "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED"
2493 #+SEQ_TODO: "|" "CANCELED"
2495 To make sure you are using the correct keyword, type `#+' into the
2496 buffer and then use `M-<TAB>' completion.
2498 Remember that the keywords after the vertical bar (or the last
2499 keyword if no bar is there) must always mean that the item is DONE
2500 (although you may use a different word). After changing one of these
2501 lines, use `C-c C-c' with the cursor still in the line to make the
2502 changes known to Org-mode(1).
2504 ---------- Footnotes ----------
2506 (1) Org-mode parses these lines only when Org-mode is activated
2507 after visiting a file. `C-c C-c' with the cursor in a line starting
2508 with `#+' is simply restarting Org-mode for the current buffer.
2511 File: org, Node: Priorities, Next: Breaking down tasks, Prev: TODO extensions, Up: TODO items
2516 If you use Org-mode extensively to organize your work, you may end up
2517 with a number of TODO entries so large that you'd like to prioritize
2518 them. This can be done by placing a _priority cookie_ into the
2521 *** TODO [#A] Write letter to Sam Fortune
2523 With its standard setup, Org-mode supports priorities `A', `B', and
2524 `C'. `A' is the highest priority. An entry without a cookie is
2525 treated as priority `B'. Priorities make a difference only in the
2526 agenda (*note Weekly/Daily agenda::).
2529 Set the priority of the current headline. The command prompts for
2530 a priority character `A', `B' or `C'. When you press <SPC>
2531 instead, the priority cookie is removed from the headline. The
2532 priorities can also be changed "remotely" from the timeline and
2533 agenda buffer with the `,' command (*note Agenda commands::).
2537 Increase/decrease priority of current headline. Note that these
2538 keys are also used to modify time stamps (*note Creating
2539 timestamps::). Furthermore, these keys are also used by CUA-mode
2540 (*note Conflicts::).
2543 File: org, Node: Breaking down tasks, Next: Checkboxes, Prev: Priorities, Up: TODO items
2545 5.4 Breaking tasks down into subtasks
2546 =====================================
2548 It is often advisable to break down large tasks into smaller, manageable
2549 subtasks. You can do this by creating an outline tree below a TODO
2550 item, with detailed subtasks on the tree(1). Another possibility is
2551 the use of checkboxes to identify (a hierarchy of) a large number of
2552 subtasks (*note Checkboxes::).
2554 ---------- Footnotes ----------
2556 (1) To keep subtasks out of the global TODO list, see the
2557 `org-agenda-todo-list-sublevels'.
2560 File: org, Node: Checkboxes, Prev: Breaking down tasks, Up: TODO items
2565 Every item in a plain list (*note Plain lists::) can be made a checkbox
2566 by starting it with the string `[ ]'. This feature is similar to TODO
2567 items (*note TODO items::), but more lightweight. Checkboxes are not
2568 included into the global TODO list, so they are often great to split a
2569 task into a number of simple steps. Or you can use them in a shopping
2570 list. To toggle a checkbox, use `C-c C-c', or try Piotr Zielinski's
2571 `org-mouse.el'. Here is an example of a checkbox list.
2573 * TODO Organize party [3/6]
2579 - [ ] think about what music to play
2580 - [X] talk to the neighbors
2582 The `[3/6]' and `[1/3]' in the first and second line are cookies
2583 indicating how many checkboxes are present in this entry, and how many
2584 of them have been checked off. This can give you an idea on how many
2585 checkboxes remain, even without opening a folded entry. The cookies
2586 can be placed into a headline or into (the first line of) a plain list
2587 item. Each cookie covers all checkboxes structurally below that
2588 headline/item. You have to insert the cookie yourself by typing either
2589 `[/]' or `[%]'. In the first case you get an `n out of m' result, in
2590 the second case you get information about the percentage of checkboxes
2591 checked (in the above example, this would be `[50%]' and `[33%],
2594 The following commands work with checkboxes:
2597 Toggle checkbox at point.
2600 Toggle checkbox at point.
2601 - If there is an active region, toggle the first checkbox in
2602 the region and set all remaining boxes to the same status as
2603 the first. If you want to toggle all boxes in the region
2604 independently, use a prefix argument.
2606 - If the cursor is in a headline, toggle checkboxes in the
2607 region between this headline and the next (so _not_ the
2610 - If there is no active region, just toggle the checkbox at
2614 Insert a new item with a checkbox. This works only if the cursor
2615 is already in a plain list item (*note Plain lists::).
2618 Update the checkbox statistics in the current outline entry. When
2619 called with a `C-u' prefix, update the entire file. Checkbox
2620 statistic cookies are updated automatically if you toggle
2621 checkboxes with `C-c C-c' and make new ones with `M-S-<RET>'. If
2622 you delete boxes or add/change them by hand, use this command to
2623 get things back into synch. Or simply toggle any checkbox twice
2627 File: org, Node: Timestamps, Next: Tags, Prev: TODO items, Up: Top
2632 Items can be labeled with timestamps to make them useful for project
2637 * Time stamps:: Assigning a time to a tree entry
2638 * Creating timestamps:: Commands which insert timestamps
2639 * Custom time format:: If you cannot work with the ISO format
2640 * Repeating items:: Deadlines that come back again and again
2641 * Progress logging:: Documenting when what work was done.
2644 File: org, Node: Time stamps, Next: Creating timestamps, Prev: Timestamps, Up: Timestamps
2646 6.1 Time stamps, deadlines and scheduling
2647 =========================================
2649 A time stamp is a specification of a date (possibly with time) in a
2650 special format, either `<2003-09-16 Tue>' or `<2003-09-16 Tue
2651 09:39>'(1). A time stamp can appear anywhere in the headline or body
2652 of an org-tree entry. Its presence allows entries to be shown on
2653 specific dates in the agenda (*note Weekly/Daily agenda::). We
2657 A simple time stamp just assigns a date/time to an item. This is
2658 just like writing down an appointment in a paper agenda, or like
2659 writing down an event in a diary, when you want to take note of
2660 when something happened. In the timeline and agenda displays, the
2661 headline of an entry associated with a plain time stamp will be
2662 shown exactly on that date.
2664 * Meet Peter at the movies <2006-11-01 Wed 19:15>
2667 Just like a plain time stamp, but with square brackets instead of
2668 angular ones. These time stamps are inactive in the sense that
2669 they do _not_ trigger an entry to show up in the agenda.
2671 * Gillian comes late for the fifth time [2006-11-01 Wed]
2674 Two time stamps connected by `--' denote a time range. The
2675 headline will be shown on the first and last day of the range, and
2676 on any dates that are displayed and fall in the range. Here is an
2679 ** Meeting in Amsterdam
2680 <2004-08-23 Mon>--<2004-08-26 Thu>
2682 TIME STAMP WITH SCHEDULED KEYWORD
2683 If a time stamp is preceded by the word `SCHEDULED:', it means you
2684 are planning to start working on that task on the given date. So
2685 this is not about recording an event, but about planning your
2686 work. The headline will be listed under the given date(2). In
2687 addition, a reminder that the scheduled date has passed will be
2688 present in the compilation for _today_, until the entry is marked
2689 DONE. I.e., the task will automatically be forwarded until
2692 *** TODO Call Trillian for a date on New Years Eve.
2693 SCHEDULED: <2004-12-25 Sat>
2695 TIME STAMP WITH DEADLINE KEYWORD
2696 If a time stamp is preceded by the word `DEADLINE:', the task
2697 (most likely a TODO item) is supposed to be finished on that date,
2698 and it will be listed then. In addition, the compilation for
2699 _today_ will carry a warning about the approaching or missed
2700 deadline, starting `org-deadline-warning-days' before the due
2701 date, and continuing until the entry is marked DONE. An example:
2703 *** TODO write article about the Earth for the Guide
2704 The editor in charge is [[bbdb:Ford Prefect]]
2705 DEADLINE: <2004-02-29 Sun>
2707 TIME STAMP WITH CLOSED KEYWORD
2708 When `org-log-done' is non-nil, Org-mode will automatically insert
2709 a special time stamp each time a TODO entry is marked done (*note
2710 Progress logging::). This time stamp is enclosed in square
2711 brackets instead of angular brackets.
2713 TIME RANGE WITH CLOCK KEYWORD
2714 When using the clock to time the work that is being done on
2715 specific items, time ranges preceded by the CLOCK keyword are
2716 inserted automatically into the file. The time stamps are
2717 enclosed in square brackets instead of angular brackets. *Note
2718 Clocking work time::.
2720 ---------- Footnotes ----------
2722 (1) This is the standard ISO date/time format. If you cannot get
2723 used to these, see *Note Custom time format::
2725 (2) It will still be listed on that date after it has been marked
2726 DONE. If you don't like this, set the variable
2727 `org-agenda-skip-scheduled-if-done'.
2730 File: org, Node: Creating timestamps, Next: Custom time format, Prev: Time stamps, Up: Timestamps
2732 6.2 Creating timestamps
2733 =======================
2735 For Org-mode to recognize time stamps, they need to be in the specific
2736 format. All commands listed below produce time stamps in the correct
2740 Prompt for a date and insert a corresponding time stamp. When the
2741 cursor is at a previously used time stamp, it is updated to NOW.
2742 When this command is used twice in succession, a time range is
2746 Like `C-c .', but use the alternative format which contains date
2747 and time. The default time can be rounded to multiples of 5
2748 minutes, see the option `org-time-stamp-rounding-minutes'.
2751 Like `C-c .', but insert an inactive time stamp that will not cause
2755 Insert a time stamp corresponding to the cursor date in the
2759 Access the Emacs calendar for the current date. If there is a
2760 timestamp in the current line, goto the corresponding date instead.
2763 Access the agenda for the date given by the time stamp or -range at
2764 point (*note Weekly/Daily agenda::).
2767 Insert `DEADLINE' keyword along with a stamp. The insertion will
2768 happen in the line directly following the headline.
2771 Create a sparse tree with all deadlines that are either past-due,
2772 or which will become due within `org-deadline-warning-days'. With
2773 `C-u' prefix, show all deadlines in the file. With a numeric
2774 prefix, check that many days. For example, `C-1 C-c C-w' shows
2775 all deadlines due tomorrow.
2778 Insert `SCHEDULED' keyword along with a stamp. The insertion will
2779 happen in the line directly following the headline. Any CLOSED
2780 timestamp will be removed.
2784 Change date at cursor by one day. These key bindings conflict with
2785 CUA-mode (*note Conflicts::).
2789 Change the item under the cursor in a timestamp. The cursor can
2790 be on a year, month, day, hour or minute. Note that if the cursor
2791 is in a headline and not at a time stamp, these same keys modify
2792 the priority of an item. (*note Priorities::). The key bindings
2793 also conflict with CUA-mode (*note Conflicts::).
2796 Evaluate a time range by computing the difference between start and
2797 end. With prefix arg, insert result after the time range (in a
2798 table: into the following column).
2802 * The date/time prompt:: How org-mode helps you entering date and time
2805 File: org, Node: The date/time prompt, Prev: Creating timestamps, Up: Creating timestamps
2807 6.2.1 The date/time prompt
2808 --------------------------
2810 When Org-mode prompts for a date/time, the prompt suggests to enter an
2811 ISO date. But it will in fact accept any string containing some date
2812 and/or time information. You can, for example, use `C-y' to paste a
2813 (possibly multi-line) string copied from an email message. Org-mode
2814 will find whatever information is in there and will replace anything not
2815 specified with the current date and time. For example:
2817 3-2-5 --> 2003-02-05
2818 feb 15 --> currentyear-02-15
2819 sep 12 9 --> 2009-09-12
2820 12:45 --> today 12:45
2821 22 sept 0:34 --> currentyear-09-22 0:34
2822 12 --> currentyear-currentmonth-12
2823 Fri --> nearest Friday (today or later)
2824 +4 --> 4 days from now (if +N is the only thing given)
2826 The function understands English month and weekday abbreviations. If
2827 you want to use unabbreviated names and/or other languages, configure
2828 the variables `parse-time-months' and `parse-time-weekdays'.
2830 Parallel to the minibuffer prompt, a calendar is popped up(1). When
2831 you exit the date prompt, either by clicking on a date in the calendar,
2832 or by pressing <RET>, the date selected in the calendar will be
2833 combined with the information entered at the prompt. You can control
2834 the calendar fully from the minibuffer:
2837 Scroll calendar backwards by one month.
2840 Scroll calendar forwards by one month.
2843 Select date by clicking on it.
2864 Choose date in calendar (only if nothing was typed into
2867 ---------- Footnotes ----------
2869 (1) If you don't need/want the calendar, configure the variable
2870 `org-popup-calendar-for-date-prompt'.
2873 File: org, Node: Custom time format, Next: Repeating items, Prev: Creating timestamps, Up: Timestamps
2875 6.3 Custom time format
2876 ======================
2878 Org-mode uses the standard ISO notation for dates and times as it is
2879 defined in ISO 8601. If you cannot get used to this and require another
2880 representation of date and time to keep you happy, you can get it by
2881 customizing the variables `org-display-custom-times' and
2882 `org-time-stamp-custom-formats'.
2885 Toggle the display of custom formats for dates and times.
2887 Org-mode needs the default format for scanning, so the custom date/time
2888 format does not _replace_ the default format - instead it is put _over_
2889 the default format using text properties. This has the following
2891 * You cannot place the cursor onto a time stamp anymore, only before
2894 * The `S-<up>/<down>' keys can no longer be used to adjust each
2895 component of a time stamp. If the cursor is at the beginning of
2896 the stamp, `S-<up>/<down>' will change the stamp by one day, just
2897 like `S-<left>/<right>'. At the end of the stamp, the time will
2898 be changed by one minute.
2900 * When you delete a time stamp character-by-character, it will only
2901 disappear from the buffer after _all_ (invisible) characters
2902 belonging to the ISO timestamp have been removed.
2904 * If the custom time stamp format is longer than the default and you
2905 are using dates in tables, table alignment will be messed up. If
2906 the custom format is shorter, things do work as expected.
2909 File: org, Node: Repeating items, Next: Progress logging, Prev: Custom time format, Up: Timestamps
2914 Org-mode integrates with the Emacs calendar and diary to display cyclic
2915 appointments, anniversaries and other special entries in the agenda
2916 (*note Weekly/Daily agenda::). However, it can be useful to have
2917 certain deadlines and scheduling items to auto-repeat. The advantage of
2918 a deadline or scheduled item is that the they produce warnings ahead of
2919 time and automatically forward themselves in the agenda until they are
2920 done. The abstract difference is therefore between cyclic appointments
2921 and cyclic action items. For appointments you should use the diary,
2922 for actions you can uses an org-mode deadline or scheduling time stamp
2923 together with a REPEAT cookie. For example:
2925 * TODO Replace batteries in smoke detector REPEAT(+18m)
2926 SCHEDULED: <2007-01-01 Mon>
2928 * TODO Get dentist appointment REPEAT(+6m)
2929 SCHEDULED: <2006-12-19 Tue>
2931 * TODO Tax report to IRS REPEAT(+1y)
2932 DEADLINE: <2007-04-01 Sun>
2934 Each time you try to mark one of these entries DONE using `C-c C-t',
2935 they will automatically switch back to the state TODO, and the
2936 deadline/scheduling will be shifted accordingly. The time units
2937 recognized by org-mode are year (y), month (m), week (w), and day (d).
2938 Org-mode will also prompt you for a note and record the fact that you
2939 have closed this item in a note under the headline.
2941 One unusual property of these repeating items is that only one
2942 instance of each exist at any given time. So if you look back or ahead
2943 in the agenda, you will not find past and future instances, only the
2944 current one will show up. Use a cyclic diary entry if you need all
2945 past and future instances to be visible in the agenda.
2948 File: org, Node: Progress logging, Prev: Repeating items, Up: Timestamps
2950 6.5 Progress Logging
2951 ====================
2953 Org-mode can automatically record a time stamp when you mark a TODO item
2954 as DONE, or even each time when you change the state of a TODO item.
2955 You can also measure precisely the time you spent on specific items in a
2956 project by starting and stopping a clock when you start and stop working
2957 on an aspect of a project.
2961 * Closing items:: When was this entry marked DONE?
2962 * Tracking TODO state changes:: When did the status change?
2963 * Clocking work time:: When exactly did you work on this item?
2966 File: org, Node: Closing items, Next: Tracking TODO state changes, Prev: Progress logging, Up: Progress logging
2971 If you want to keep track of _when_ a certain TODO item was finished,
2972 turn on logging with(1)
2974 (setq org-log-done t)
2976 Then each time you turn a TODO entry into DONE using either `C-c C-t'
2977 in the Org-mode buffer or `t' in the agenda buffer, a line `CLOSED:
2978 [timestamp]' will be inserted just after the headline. If you turn the
2979 entry back into a TODO item through further state cycling, that line
2980 will be removed again. In the timeline (*note Timeline::) and in the
2981 agenda (*note Weekly/Daily agenda::), you can then use the `l' key to
2982 display the TODO items closed on each day, giving you an overview of
2983 what has been done on a day. If you want to record a note along with
2984 the timestamp, use(2)
2986 (setq org-log-done '(done))
2988 ---------- Footnotes ----------
2990 (1) The corresponding in-buffer setting is: `#+STARTUP: logdone'
2992 (2) The corresponding in-buffer setting is: `#+STARTUP: lognotedone'
2995 File: org, Node: Tracking TODO state changes, Next: Clocking work time, Prev: Closing items, Up: Progress logging
2997 6.5.2 Tracking TODO state changes
2998 ---------------------------------
3000 When TODO keywords are used as workflow states (*note Workflow
3001 states::), you might want to keep track of when a state change occurred,
3002 and you may even want to attach notes to that state change. With the
3005 (setq org-log-done '(state))
3007 each state change will prompt you for a note that will be attached to
3008 the current headline. Very likely you do not want this verbose tracking
3009 all the time, so it is probably better to configure this behavior with
3010 in-buffer options. For example, if you are tracking purchases, put
3011 these into a separate file that starts with:
3013 #+SEQ_TODO: TODO ORDERED INVOICE PAYED RECEIVED SENT
3014 #+STARTUP: lognotestate
3017 File: org, Node: Clocking work time, Prev: Tracking TODO state changes, Up: Progress logging
3019 6.5.3 Clocking work time
3020 ------------------------
3022 Org-mode allows you to clock the time you spent on specific tasks in a
3023 project. When you start working on an item, you can start the clock.
3024 When you stop working on that task, or when you mark the task done, the
3025 clock is stopped and the corresponding time interval is recorded. It
3026 also computes the total time spent on each subtree of a project.
3029 Start the clock on the current item (clock-in). This inserts the
3030 CLOCK keyword together with a timestamp.
3033 Stop the clock (clock-out). The inserts another timestamp at the
3034 same location where the clock was last started. It also directly
3035 computes the resulting time in inserts it after the time range as
3036 `=> HH:MM'. See the variable `org-log-done' for the possibility to
3037 record an additional note together with the clock-out time
3041 Recompute the time interval after changing one of the time stamps.
3042 This is only necessary if you edit the time stamps directly. If
3043 you change them with `S-<cursor>' keys, the update is automatic.
3046 Changing the TODO state of an item to DONE automatically stops the
3047 clock if it is running in this same item.
3050 Cancel the current clock. This is useful if a clock was started by
3051 mistake, or if you ended up working on something else.
3054 Display time summaries for each subtree in the current buffer.
3055 This puts overlays at the end of each headline, showing the total
3056 time recorded under that heading, including the time of any
3057 subheadings. You can use visibility cycling to study the tree, but
3058 the overlays disappear when you change the buffer (see variable
3059 `org-remove-highlights-with-change') or press `C-c C-c'.
3062 Insert a dynamic block (*note Dynamic blocks::) containing a clock
3063 report as an org-mode table into the current file.
3064 #+BEGIN: clocktable :maxlevel 2 :emphasize nil
3067 If such a block already exists, its content is replaced by the new
3068 table. The `BEGIN' line can specify options:
3069 :maxlevels Maximum level depth to which times are listed in the table.
3070 :emphasize When `t', emphasize level one and level two items
3071 :block The time block to consider. This block is specified relative
3072 to the current time and may be any of these keywords:
3073 `today', `yesterday', `thisweek', `lastweek',
3074 `thismonth', `lastmonth', `thisyear', or `lastyear'.
3075 :tstart A time string specifying when to start considering times
3076 :tend A time string specifying when to stop considering times
3077 So to get a clock summary for the current day, you could write
3078 #+BEGIN: clocktable :maxlevel 2 :block today
3081 and to use a specific time range you could write(2)
3082 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
3083 :tend "<2006-08-10 Thu 12:00>"
3088 Update all dynamic blocks (*note Dynamic blocks::). This is
3089 useful if you have several clocktable blocks in a buffer.
3091 The `l' key may be used in the timeline (*note Timeline::) and in
3092 the agenda (*note Weekly/Daily agenda::) to show which tasks have been
3093 worked on or closed during a day.
3095 ---------- Footnotes ----------
3097 (1) The corresponding in-buffer setting is: `#+STARTUP:
3100 (2) Note that all parameters must be specified in a single line -
3101 the line is broken here only to fit it onto the manual.
3104 File: org, Node: Tags, Next: Agenda views, Prev: Timestamps, Up: Top
3109 If you wish to implement a system of labels and contexts for
3110 cross-correlating information, an excellent way is to assign tags to
3111 headlines. Org-mode has extensive support for using tags.
3113 Every headline can contain a list of tags, at the end of the
3114 headline. Tags are normal words containing letters, numbers, `_', and
3115 `@'. Tags must be preceded and followed by a single colon; like
3116 `:WORK:'. Several tags can be specified like `:WORK:URGENT:'.
3120 * Tag inheritance:: Tags use the tree structure of the outline
3121 * Setting tags:: How to assign tags to a headline
3122 * Tag searches:: Searching for combinations of tags
3125 File: org, Node: Tag inheritance, Next: Setting tags, Prev: Tags, Up: Tags
3130 Tags make use of the hierarchical structure of outline trees. If a
3131 heading has a certain tag, all subheadings will inherit the tag as
3132 well. For example, in the list
3134 * Meeting with the French group :WORK:
3135 ** Summary by Frank :BOSS:NOTES:
3136 *** TODO Prepare slides for him :ACTION:
3138 the final heading will have the tags `:WORK:', `:BOSS:', `:NOTES:', and
3139 `:ACTION:'. When executing tag searches and Org-mode finds that a
3140 certain headline matches the search criterion, it will not check any
3141 sublevel headline, assuming that these likely also match, and that the
3142 list of matches can become very long. This may not be what you want,
3143 however, and you can influence inheritance and searching using the
3144 variables `org-use-tag-inheritance' and `org-tags-match-list-sublevels'.
3147 File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags
3152 Tags can simply be typed into the buffer at the end of a headline.
3153 After a colon, `M-<TAB>' offers completion on tags. There is also a
3154 special command for inserting tags:
3157 Enter new tags for the current headline. Org-mode will either
3158 offer completion or a special single-key interface for setting
3159 tags, see below. After pressing <RET>, the tags will be inserted
3160 and aligned to `org-tags-column'. When called with a `C-u'
3161 prefix, all tags in the current buffer will be aligned to that
3162 column, just to make things look nice. TAGS are automatically
3163 realigned after promotion, demotion, and TODO state changes (*note
3166 Org will support tag insertion based on a _list of tags_. By
3167 default this list is constructed dynamically, containing all tags
3168 currently used in the buffer. You may also globally specify a hard list
3169 of tags with the variable `org-tag-alist'. Finally you can set the
3170 default tags for a given file with lines like
3172 #+TAGS: @WORK @HOME @TENNISCLUB
3173 #+TAGS: Laptop Car PC Sailboat
3175 If you have globally defined your preferred set of tags using the
3176 variable `org-tag-alist', but would like to use a dynamic tag list in a
3177 specific file: Just add an empty TAGS option line to that file:
3181 The default support method for entering tags is minibuffer
3182 completion. However, Org-mode also implements a much better method:
3183 _fast tag selection_. This method allows to select and deselect tags
3184 with a single key per tag. To function efficiently, you should assign
3185 unique keys to most tags. This can be done globally with
3187 (setq org-tag-alist '(("@WORK" . ?w) ("@HOME" . ?h) ("Laptop" . ?l)))
3189 or on a per-file basis with
3191 #+TAGS: @WORK(w) @HOME(h) @TENNISCLUB(t) Laptop(l) PC(p)
3193 You can also group together tags that are mutually exclusive. With
3196 #+TAGS: { @WORK(w) @HOME(h) @TENNISCLUB(t) } Laptop(l) PC(p)
3198 you indicate that at most one of `@WORK', `@HOME', and `@TENNISCLUB'
3201 Don't forget to press `C-c C-c' with the cursor in one of these lines
3202 to activate any changes.
3204 If at least one tag has a selection key, pressing `C-c C-c' will
3205 automatically present you with a special interface, listing inherited
3206 tags, the tags of the current headline, and a list of all legal tags
3207 with corresponding keys(2). In this interface, you can use the
3211 Pressing keys assigned to tags will add or remove them from the
3212 list of tags in the current line. Selecting a tag in a group of
3213 mutually exclusive tags will turn off any other tags from that
3217 Enter a tag in the minibuffer, even if the tag is not in the
3218 predefined list. You will be able to complete on all tags present
3222 Clear all tags for this line.
3225 Accept the modified set.
3228 Abort without installing changes.
3231 If `q' is not assigned to a tag, it aborts like `C-g'.
3234 Turn off groups of mutually exclusive tags. Use this to (as an
3235 exception) assign several tags from such a group.
3238 Toggle auto-exit after the next change (see below). If you are
3239 using expert mode, the first `C-c' will display the selection
3242 This method lets you assign tags to a headline with very few keys. With
3243 the above setup, you could clear the current tags and set `@HOME',
3244 `Laptop' and `PC' tags with just the following keys: `C-c C-c <SPC> h l
3245 p <RET>'. Switching from `@HOME' to `@WORK' would be done with `C-c
3246 C-c w <RET>' or alternatively with `C-c C-c C-c w'. Adding the
3247 non-predefined tag `Sarah' could be done with `C-c C-c <TAB> S a r a h
3250 If you find that most of the time, you need only a single keypress to
3251 modify your list of tags, set the variable
3252 `org-fast-tag-selection-single-key'. Then you no longer have to press
3253 <RET> to exit fast tag selection - it will immediately exit after the
3254 first change. If you then occasionally need more keys, press `C-c' to
3255 turn off auto-exit for the current tag selection process (in effect:
3256 start selection with `C-c C-c C-c' instead of `C-c C-c'). If you set
3257 the variable to the value `expert', the special window is not even
3258 shown for single-key tag selection, it comes up only when you press an
3261 ---------- Footnotes ----------
3263 (1) In `org-mode-alist' use `'(:startgroup)' and `'(:endgroup)',
3264 respectively. Several groups are allowed.
3266 (2) Keys will automatically be assigned to tags which have no
3270 File: org, Node: Tag searches, Prev: Setting tags, Up: Tags
3275 Once a tags system has been set up, it can be used to collect related
3276 information into special lists.
3279 Create a sparse tree with all headlines matching a tags search.
3280 With a `C-u' prefix argument, ignore headlines that are not a TODO
3284 Create a global list of tag matches from all agenda files. *Note
3285 Matching headline tags::.
3288 Create a global list of tag matches from all agenda files, but
3289 check only TODO items and force checking subitems (see variable
3290 `org-tags-match-list-sublevels').
3292 A tags search string can use Boolean operators `&' for AND and `|'
3293 for OR. `&' binds more strongly than `|'. Parenthesis are currently
3294 not implemented. A tag may also be preceded by `-', to select against
3295 it, and `+' is syntactic sugar for positive selection. The AND
3296 operator `&' is optional when `+' or `-' is present. Examples:
3299 Select headlines tagged `:WORK:', but discard those also tagged
3303 Selects lines tagged `:WORK:' or `:LAPTOP:'.
3306 Like before, but require the `:LAPTOP:' lines to be tagged also
3309 If you are using multi-state TODO keywords (*note TODO
3310 extensions::), it can be useful to also match on the TODO keyword.
3311 This can be done by adding a condition after a slash to a tags match.
3312 The syntax is similar to the tag matches, but should be applied with
3313 consideration: For example, a positive selection on several TODO
3314 keywords can not meaningfully be combined with boolean AND. However,
3315 _negative selection_ combined with AND can be meaningful. To make sure
3316 that only lines are checked that actually have any TODO keyword, use
3317 `C-c a M', or equivalently start the todo part after the slash with `!'.
3321 Select `:WORK:'-tagged TODO lines with the specific TODO keyword
3324 `WORK/!-WAITING-NEXT'
3325 Select `:WORK:'-tagged TODO lines that are neither `WAITING' nor
3328 `WORK/+WAITING|+NEXT'
3329 Select `:WORK:'-tagged TODO lines that are either `WAITING' or
3332 Any element of the tag/todo match can be a regular expression - in
3333 this case it must be enclosed in curly braces. For example,
3334 `WORK+{^BOSS.*}' matches headlines that contain the tag `WORK' and any
3335 tag starting with `BOSS'.
3337 You can also require a headline to be of a certain level, by writing
3338 instead of any TAG an expression like `LEVEL=3'. For example, a search
3339 `+LEVEL=3+BOSS/-DONE' lists all level three headlines that have the tag
3340 BOSS and are _not_ marked with the todo keyword DONE.
3343 File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Tags, Up: Top
3348 Due to the way Org-mode works, TODO items, time-stamped items, and
3349 tagged headlines can be scattered throughout a file or even a number of
3350 files. To get an overview over open action items, or over events that
3351 are important for a particular date, this information must be collected,
3352 sorted and displayed in an organized way.
3354 Org-mode can select items based on various criteria, and display them
3355 in a separate buffer. Six different view types are provided:
3357 * an _agenda_ that is like a calendar and shows information for
3360 * a _TODO list_ that covers all unfinished action items,
3362 * a _tags view_, showings headlines based on the tags associated
3365 * a _timeline view_ that shows all events in a single Org-mode file,
3366 in time-sorted view,
3368 * a _stuck projects view_ showing projects that currently don't move
3371 * _custom views_ that are special tag/keyword searches and
3372 combinations of different views.
3374 The extracted information is displayed in a special _agenda buffer_.
3375 This buffer is read-only, but provides commands to visit the
3376 corresponding locations in the original Org-mode files, and even to
3377 edit these files remotely.
3379 Two variables control how the agenda buffer is displayed and whether
3380 the window configuration is restored when the agenda exits:
3381 `org-agenda-window-setup' and `org-agenda-restore-windows-after-quit'.
3385 * Agenda files:: Files being searched for agenda information
3386 * Agenda dispatcher:: Keyboard access to agenda views
3387 * Built-in agenda views:: What is available out of the box?
3388 * Presentation and sorting:: How agenda items are prepared for display
3389 * Agenda commands:: Remote editing of org trees
3390 * Custom agenda views:: Defining special searches and views
3393 File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views
3398 The information to be shown is collected from all _agenda files_, the
3399 files listed in the variable `org-agenda-files'(1). Thus even if you
3400 only work with a single Org-mode file, this file should be put into
3401 that list(2). You can customize `org-agenda-files', but the easiest
3402 way to maintain it is through the following commands
3405 Add current file to the list of agenda files. The file is added to
3406 the front of the list. If it was already in the list, it is moved
3407 to the front. With prefix arg, file is added/moved to the end.
3410 Remove current file from the list of agenda files.
3414 Cycle through agenda file list, visiting one file after the other.
3416 The Org menu contains the current list of files and can be used to
3419 ---------- Footnotes ----------
3421 (1) If the value of that variable is not a list, but a single file
3422 name, then the list of agenda files will be maintained in that external
3425 (2) When using the dispatcher, pressing `1' before selecting a
3426 command will actually limit the command to the current file, and ignore
3427 `org-agenda-files' until the next dispatcher command.
3430 File: org, Node: Agenda dispatcher, Next: Built-in agenda views, Prev: Agenda files, Up: Agenda views
3432 8.2 The agenda dispatcher
3433 =========================
3435 The views are created through a dispatcher that should be bound to a
3436 global key, for example `C-c a' (*note Installation::). In the
3437 following we will assume that `C-c a' is indeed how the dispatcher is
3438 accessed and list keyboard access to commands accordingly. After
3439 pressing `C-c a', an additional letter is required to execute a
3440 command. The dispatcher offers the following default commands:
3442 Create the calendar-like agenda (*note Weekly/Daily agenda::).
3445 Create a list of all TODO items (*note Global TODO list::).
3448 Create a list of headlines matching a TAGS expression (*note
3449 Matching headline tags::).
3452 Create the timeline view for the current buffer (*note Timeline::).
3455 Create a list of stuck projects (*note Stuck projects::).
3458 Restrict an agenda command to the current buffer. After pressing
3459 `1', you still need to press the character selecting the command.
3462 If there is an active region, restrict the following agenda
3463 command to the region. Otherwise, restrict it to the current
3464 subtree. After pressing `0', you still need to press the
3465 character selecting the command.
3467 You can also define custom commands that will be accessible through
3468 the dispatcher, just like the default commands. This includes the
3469 possibility to create extended agenda buffers that contain several
3470 blocks together, for example the weekly agenda, the global TODO list and
3471 a number of special tags matches. *Note Custom agenda views::.
3474 File: org, Node: Built-in agenda views, Next: Presentation and sorting, Prev: Agenda dispatcher, Up: Agenda views
3476 8.3 The built-in agenda views
3477 =============================
3479 In this section we describe the built-in views.
3483 * Weekly/Daily agenda:: The calendar page with current tasks
3484 * Global TODO list:: All unfinished action items
3485 * Matching headline tags:: Structured information with fine-tuned search
3486 * Timeline:: Time-sorted view for single file
3487 * Stuck projects:: Find projects you need to review
3490 File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Built-in agenda views, Up: Built-in agenda views
3492 8.3.1 The weekly/daily agenda
3493 -----------------------------
3495 The purpose of the weekly/daily _agenda_ is to act like a page of a
3496 paper agenda, showing all the tasks for the current week or day.
3499 Compile an agenda for the current week from a list of org files.
3500 The agenda shows the entries for each day. With a `C-u' prefix (or
3501 when the variable `org-agenda-include-all-todo' is `t'), all
3502 unfinished TODO items (including those without a date) are also
3503 listed at the beginning of the buffer, before the first date.
3505 Remote editing from the agenda buffer means, for example, that you
3506 can change the dates of deadlines and appointments from the agenda
3507 buffer. The commands available in the Agenda buffer are listed in
3508 *Note Agenda commands::.
3510 Calendar/Diary integration
3511 ..........................
3513 Emacs contains the calendar and diary by Edward M. Reingold. The
3514 calendar displays a three-month calendar with holidays from different
3515 countries and cultures. The diary allows you to keep track of
3516 anniversaries, lunar phases, sunrise/set, recurrent appointments
3517 (weekly, monthly) and more. In this way, it is quite complementary to
3518 Org-mode. It can be very useful to combine output from Org-mode with
3521 In order to include entries from the Emacs diary into Org-mode's
3522 agenda, you only need to customize the variable
3524 (setq org-agenda-include-diary t)
3526 After that, everything will happen automatically. All diary entries
3527 including holidays, anniversaries etc will be included in the agenda
3528 buffer created by Org-mode. <SPC>, <TAB>, and <RET> can be used from
3529 the agenda buffer to jump to the diary file in order to edit existing
3530 diary entries. The `i' command to insert new entries for the current
3531 date works in the agenda buffer, as well as the commands `S', `M', and
3532 `C' to display Sunrise/Sunset times, show lunar phases and to convert
3533 to other calendars, respectively. `c' can be used to switch back and
3534 forth between calendar and agenda.
3537 File: org, Node: Global TODO list, Next: Matching headline tags, Prev: Weekly/Daily agenda, Up: Built-in agenda views
3539 8.3.2 The global TODO list
3540 --------------------------
3542 The global TODO list contains all unfinished TODO items, formatted and
3543 collected into a single place.
3546 Show the global TODO list. This collects the TODO items from all
3547 agenda files (*note Agenda views::) into a single buffer. The
3548 buffer is in `agenda-mode', so there are commands to examine and
3549 manipulate the TODO entries directly from that buffer (*note
3553 Like the above, but allows selection of a specific TODO keyword.
3554 You can also do this by specifying a prefix argument to `C-c a t'.
3555 With a `C-u' prefix you are prompted for a keyword, and you may
3556 also specify several keywords by separating them with `|' as
3557 boolean OR operator. With a numeric prefix, the Nth keyword in
3558 `org-todo-keywords' is selected. The `r' key in the agenda buffer
3559 regenerates it, and you can give a prefix argument to this command
3560 to change the selected TODO keyword, for example `3 r'. If you
3561 often need a search for a specific keyword, define a custom
3562 command for it (*note Agenda dispatcher::).
3563 Matching specific TODO keywords can also be done as part of a tags
3564 search (*note Tag searches::).
3566 Remote editing of TODO items means that you can change the state of a
3567 TODO entry with a single key press. The commands available in the TODO
3568 list are described in *Note Agenda commands::.
3570 Normally the global todo list simply shows all headlines with TODO
3571 keywords. This list can become very long. There are two ways to keep
3573 - Some people view a TODO item that has been _scheduled_ for
3574 execution (*note Time stamps::) as no longer _open_. Configure the
3575 variable `org-agenda-todo-ignore-scheduled' to exclude scheduled
3576 items from the global TODO list.
3578 - TODO items may have sublevels to break up the task into subtasks.
3579 In such cases it may be enough to list only the highest level TODO
3580 headline and omit the sublevels from the global list. Configure
3581 the variable `org-agenda-todo-list-sublevels' to get this behavior.
3584 File: org, Node: Matching headline tags, Next: Timeline, Prev: Global TODO list, Up: Built-in agenda views
3586 8.3.3 Matching headline tags
3587 ----------------------------
3589 If headlines in the agenda files are marked with _tags_ (*note Tags::),
3590 you can select headlines based on the tags that apply to them and
3591 collect them into an agenda buffer.
3594 Produce a list of all headlines that match a given set of tags.
3595 The command prompts for a selection criterion, which is a boolean
3596 logic expression with tags, like `+WORK+URGENT-WITHBOSS' or
3597 `WORK|HOME' (*note Tags::). If you often need a specific search,
3598 define a custom command for it (*note Agenda dispatcher::).
3601 Like `C-c a m', but only select headlines that are also TODO items
3602 and force checking subitems (see variable
3603 `org-tags-match-list-sublevels'). Matching specific todo keywords
3604 together with a tags match is also possible, see *Note Tag
3607 The commands available in the tags list are described in *Note
3611 File: org, Node: Timeline, Next: Stuck projects, Prev: Matching headline tags, Up: Built-in agenda views
3613 8.3.4 Timeline for a single file
3614 --------------------------------
3616 The timeline summarizes all time-stamped items from a single Org-mode
3617 file in a _time-sorted view_. The main purpose of this command is to
3618 give an overview over events in a project.
3621 Show a time-sorted view of the org file, with all time-stamped
3622 items. When called with a `C-u' prefix, all unfinished TODO
3623 entries (scheduled or not) are also listed under the current date.
3625 The commands available in the timeline buffer are listed in *Note
3629 File: org, Node: Stuck projects, Prev: Timeline, Up: Built-in agenda views
3631 8.3.5 Stuck projects
3632 --------------------
3634 If you are following a system like David Allen's GTD to organize your
3635 work, one of the "duties" you have is a regular review to make sure
3636 that all projects move along. A _stuck_ project is a project that has
3637 no defined next actions, so it will never show up in the TODO lists
3638 Org-mode produces. During the review, you need to identify such
3639 projects and define next actions for them.
3642 List projects that are stuck.
3645 Customize the variable `org-stuck-projects' to define what a stuck
3646 project is and how to find it.
3648 You almost certainly will have to configure this view before it will
3649 work for you. The built-in default assumes that all your projects are
3650 level-2 headlines, and that a project is not stuck if it has at least
3651 one entry marked with a todo keyword TODO or NEXT or NEXTACTION.
3653 Lets assume that you, in your own way of using Org-mode, identify
3654 projects with a tag PROJECT, and that you use a todo keyword MAYBE to
3655 indicate a project that should not be considered yet. Lets further
3656 assume that the todo keyword DONE marks finished projects, and that NEXT
3657 and TODO indicate next actions. The tag @SHOP indicates shopping and
3658 is a next action even without the NEXT tag. Finally, if the project
3659 contains the special word IGNORE anywhere, it should not be listed
3660 either. In this case you would start by identifying eligible projects
3661 with a tags/todo match `+PROJECT/-MAYBE-DONE', and then check for TODO,
3662 NEXT, @SHOP, and IGNORE in the subtree to identify projects that are
3663 not stuck. The correct customization for this is
3665 (setq org-stuck-projects
3666 '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@SHOP")
3670 File: org, Node: Presentation and sorting, Next: Agenda commands, Prev: Built-in agenda views, Up: Agenda views
3672 8.4 Presentation and sorting
3673 ============================
3675 Before displaying items in an agenda view, Org-mode visually prepares
3676 the items and sorts them. Each item occupies a single line. The line
3677 starts with a _prefix_ that contains the _category_ (*note
3678 Categories::) of the item and other important information. You can
3679 customize the prefix using the option `org-agenda-prefix-format'. The
3680 prefix is followed by a cleaned-up version of the outline headline
3681 associated with the item.
3685 * Categories:: Not all tasks are equal
3686 * Time-of-day specifications:: How the agenda knows the time
3687 * Sorting of agenda items:: The order of things
3690 File: org, Node: Categories, Next: Time-of-day specifications, Prev: Presentation and sorting, Up: Presentation and sorting
3695 The category is a broad label assigned to each agenda item. By default,
3696 the category is simply derived from the file name, but you can also
3697 specify it with a special line in the buffer, like this:
3701 If there are several such lines in a file, each specifies the
3702 category for the text below it (but the first category also applies to
3703 any text before the first CATEGORY line). The display in the agenda
3704 buffer looks best if the category is not longer than 10 characters.
3707 File: org, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and sorting
3709 8.4.2 Time-of-Day Specifications
3710 --------------------------------
3712 Org-mode checks each agenda item for a time-of-day specification. The
3713 time can be part of the time stamp that triggered inclusion into the
3714 agenda, for example as in `<2005-05-10 Tue 19:00>'. Time ranges can be
3715 specified with two time stamps, like
3716 `<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>'.
3718 In the headline of the entry itself, a time(range) may also appear as
3719 plain text (like `12:45' or a `8:30-1pm'. If the agenda integrates the
3720 Emacs diary (*note Weekly/Daily agenda::), time specifications in diary
3721 entries are recognized as well.
3723 For agenda display, Org-mode extracts the time and displays it in a
3724 standard 24 hour format as part of the prefix. The example times in
3725 the previous paragraphs would end up in the agenda like this:
3727 8:30-13:00 Arthur Dent lies in front of the bulldozer
3728 12:45...... Ford Prefect arrives and takes Arthur to the pub
3729 19:00...... The Vogon reads his poem
3730 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
3732 If the agenda is in single-day mode, or for the display of today, the
3733 timed entries are embedded in a time grid, like
3735 8:00...... ------------------
3736 8:30-13:00 Arthur Dent lies in front of the bulldozer
3737 10:00...... ------------------
3738 12:00...... ------------------
3739 12:45...... Ford Prefect arrives and takes Arthur to the pub
3740 14:00...... ------------------
3741 16:00...... ------------------
3742 18:00...... ------------------
3743 19:00...... The Vogon reads his poem
3744 20:00...... ------------------
3745 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
3747 The time grid can be turned on and off with the variable
3748 `org-agenda-use-time-grid', and can be configured with
3749 `org-agenda-time-grid'.
3752 File: org, Node: Sorting of agenda items, Prev: Time-of-day specifications, Up: Presentation and sorting
3754 8.4.3 Sorting of agenda items
3755 -----------------------------
3757 Before being inserted into a view, the items are sorted. How this is
3758 done depends on the type of view.
3759 * For the daily/weekly agenda, the items for each day are sorted.
3760 The default order is to first collect all items containing an
3761 explicit time-of-day specification. These entries will be shown
3762 at the beginning of the list, as a _schedule_ for the day. After
3763 that, items remain grouped in categories, in the sequence given by
3764 `org-agenda-files'. Within each category, items are sorted by
3765 priority (*note Priorities::), which is composed of the base
3766 priority (2000 for priority `A', 1000 for `B', and 0 for `C'),
3767 plus additional increments for overdue scheduled or deadline items.
3769 * For the TODO list, items remain in the order of categories, but
3770 within each category, sorting takes place according to priority
3771 (*note Priorities::).
3773 * For tags matches, items are not sorted at all, but just appear in
3774 the sequence in which they are found in the agenda files.
3776 Sorting can be customized using the variable
3777 `org-agenda-sorting-strategy'.
3780 File: org, Node: Agenda commands, Next: Custom agenda views, Prev: Presentation and sorting, Up: Agenda views
3782 8.5 Commands in the agenda buffer
3783 =================================
3785 Entries in the agenda buffer are linked back to the org file or diary
3786 file where they originate. You are not allowed to edit the agenda
3787 buffer itself, but commands are provided to show and jump to the
3788 original entry location, and to edit the org-files "remotely" from the
3789 agenda buffer. In this way, all information is stored only once,
3790 removing the risk that your agenda and note files may diverge.
3792 Some commands can be executed with mouse clicks on agenda lines. For
3793 the other commands, the cursor needs to be in the desired line.
3799 Next line (same as <up>).
3802 Previous line (same as <down>).
3809 Display the original location of the item in another window.
3812 Display original location and recenter that window.
3817 Go to the original location of the item in another window. Under
3818 Emacs 22, `mouse-1' will also works for this.
3821 Go to the original location of the item and delete other windows.
3824 Toggle Follow mode. In Follow mode, as you move the cursor through
3825 the agenda buffer, the other window always shows the corresponding
3826 location in the org file. The initial setting for this mode in new
3827 agenda buffers can be set with the variable
3828 `org-agenda-start-with-follow-mode'.
3831 Display the entire subtree of the current item in an indirect
3832 buffer. With numerical prefix ARG, go up to this level and then
3833 take that tree. If ARG is negative, go up that many levels. With
3834 `C-u' prefix, do not remove the previously used indirect buffer.
3837 Toggle Logbook mode. In Logbook mode, entries that where marked
3838 DONE while logging was on (variable `org-log-done') are shown in
3839 the agenda, as are entries that have been clocked on that day.
3845 Delete other windows.
3848 Switch to weekly view (7 days displayed together).
3851 Switch to daily view (just one day displayed).
3854 Toggle the inclusion of diary entries. See *Note Weekly/Daily
3858 Toggle the time grid on and off. See also the variables
3859 `org-agenda-use-time-grid' and `org-agenda-time-grid'.
3862 Recreate the agenda buffer, for example to reflect the changes
3863 after modification of the time stamps of items with S-<left> and
3864 S-<right>. When the buffer is the global todo list, a prefix
3865 argument is interpreted to create a selective list for a specific
3869 Save all Org-mode buffers in the current Emacs session.
3872 Display the following `org-agenda-ndays' days. For example, if
3873 the display covers a week, switch to the following week. With
3874 prefix arg, go forward that many times `org-agenda-ndays' days.
3877 Display the previous dates.
3889 Undo a change due to a remote editing command. The change is
3890 undone both in the agenda buffer and in the remote buffer.
3893 Change the TODO state of the item, both in the agenda and in the
3897 Delete the current agenda item along with the entire subtree
3898 belonging to it in the original Org-mode file. If the text to be
3899 deleted remotely is longer than one line, the kill needs to be
3900 confirmed by the user. See variable `org-agenda-confirm-kill'.
3903 Archive the subtree corresponding to the current headline.
3906 Show all tags associated with the current item. Because of
3907 inheritance, this may be more than the tags listed in the line
3911 Set tags for the current headline.
3914 Toggle the ARCHIVE tag for the current headline.
3917 Set the priority for the current item. Org-mode prompts for the
3918 priority character. If you reply with <SPC>, the priority cookie
3919 is removed from the entry.
3922 Display weighted priority of current item.
3926 Increase the priority of the current item. The priority is
3927 changed in the original buffer, but the agenda is not resorted.
3928 Use the `r' key for this.
3932 Decrease the priority of the current item.
3938 Set a deadline for this item.
3941 Change the time stamp associated with the current line by one day
3942 into the future. With prefix argument, change it by that many
3943 days. For example, `3 6 5 S-<right>' will change it by a year.
3944 The stamp is changed in the original org file, but the change is
3945 not directly reflected in the agenda buffer. Use the `r' key to
3949 Change the time stamp associated with the current line by one day
3953 Change the time stamp associated with the current line to today.
3954 The key `>' has been chosen, because it is the same as `S-.' on my
3958 Start the clock on the current item. If a clock is running
3959 already, it is stopped first.
3962 Stop the previously started clock.
3965 Cancel the currently running clock.
3971 Open the Emacs calendar and move to the date at the agenda cursor.
3974 When in the calendar, compute and show the Org-mode agenda for the
3978 Insert a new entry into the diary. Prompts for the type of entry
3979 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a
3980 new entry in the diary, just as `i d' etc. would do in the
3981 calendar. The date is taken from the cursor position.
3984 Show the phases of the moon for the three months around current
3988 Show sunrise and sunset times. The geographical location must be
3989 set with calendar variables, see documentation of the Emacs
3993 Convert the date at cursor into many other cultural and historic
3997 Show holidays for three month around the cursor date.
4000 Export a single iCalendar file containing entries from all agenda
4007 Write the agenda view to a file. Depending on the extension of the
4008 selected file name, the view will be exported as HTML (extension
4009 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4010 (any other extension). Use the variable
4011 `org-agenda-exporter-settings' to set options for `ps-print' and
4012 for `htmlize' to be used during export.
4018 Quit agenda, remove the agenda buffer.
4021 Exit agenda, remove the agenda buffer and all buffers loaded by
4022 Emacs for the compilation of the agenda. Buffers created by the
4023 user to visit org files will not be removed.
4026 File: org, Node: Custom agenda views, Prev: Agenda commands, Up: Agenda views
4028 8.6 Custom agenda views
4029 =======================
4031 Custom agenda commands serve two purposes: to store and quickly access
4032 frequently used TODO and tags searches, and to create special composite
4033 agenda buffers. Custom agenda commands will be accessible through the
4034 dispatcher (*note Agenda dispatcher::), just like the default commands.
4038 * Storing searches:: Type once, use often
4039 * Block agenda:: All the stuff you need in a single buffer
4040 * Setting Options:: Changing the rules
4041 * Exporting Agenda Views:: Writing agendas to files.
4042 * Extracting Agenda Information for other programs::
4045 File: org, Node: Storing searches, Next: Block agenda, Prev: Custom agenda views, Up: Custom agenda views
4047 8.6.1 Storing searches
4048 ----------------------
4050 The first application of custom searches is the definition of keyboard
4051 shortcuts for frequently used searches, either creating an agenda
4052 buffer, or a sparse tree (the latter covering of course only the current
4053 buffer). Custom commands are configured in the variable
4054 `org-agenda-custom-commands'. You can customize this variable, for
4055 example by pressing `C-c a C'. You can also directly set it with Emacs
4056 Lisp in `.emacs'. The following example contains all valid search
4059 (setq org-agenda-custom-commands
4060 '(("w" todo "WAITING")
4061 ("W" todo-tree "WAITING")
4062 ("u" tags "+BOSS-URGENT")
4063 ("v" tags-todo "+BOSS-URGENT")
4064 ("U" tags-tree "+BOSS-URGENT")
4065 ("f" occur-tree "\\<FIXME\\>")))
4067 The initial single-character string in each entry defines the character
4068 you have to press after the dispatcher command `C-c a' in order to
4069 access the command. The second parameter is the search type, followed
4070 by the string or regular expression to be used for the matching. The
4071 example above will therefore define:
4074 as a global search for TODO entries with `WAITING' as the TODO
4078 as the same search, but only in the current buffer and displaying
4079 the results as a sparse tree
4082 as a global tags search for headlines marked `:BOSS:' but not
4086 as the same search as `C-c a u', but limiting the search to
4087 headlines that are also TODO items
4090 as the same search as `C-c a u', but only in the current buffer and
4091 displaying the result as a sparse tree
4094 to create a sparse tree (again: current buffer only) with all
4095 entries containing the word `FIXME'.
4098 File: org, Node: Block agenda, Next: Setting Options, Prev: Storing searches, Up: Custom agenda views
4103 Another possibility is the construction of agenda views that comprise
4104 the results of _several_ commands, each of which creates a block in the
4105 agenda buffer. The available commands include `agenda' for the daily
4106 or weekly agenda (as created with `C-c a a'), `alltodo' for the global
4107 todo list (as constructed with `C-c a t'), and the matching commands
4108 discussed above: `todo', `tags', and `tags-todo'. Here are two
4111 (setq org-agenda-custom-commands
4112 '(("h" "Agenda and Home-related tasks"
4116 ("o" "Agenda and Office-related tasks"
4121 This will define `C-c a h' to create a multi-block view for stuff you
4122 need to attend to at home. The resulting agenda buffer will contain
4123 your agenda for the current week, all TODO items that carry the tag
4124 `HOME', and also all lines tagged with `GARDEN'. Finally the command
4125 `C-c a o' provides a similar view for office tasks.
4128 File: org, Node: Setting Options, Next: Exporting Agenda Views, Prev: Block agenda, Up: Custom agenda views
4130 8.6.3 Setting Options for custom commands
4131 -----------------------------------------
4133 Org-mode contains a number of variables regulating agenda construction
4134 and display. The global variables define the behavior for all agenda
4135 commands, including the custom commands. However, if you want to change
4136 some settings just for a single custom view, you can do so. Setting
4137 options requires inserting a list of variable names and values at the
4138 right spot in `org-agenda-custom-commands'. For example:
4140 (setq org-agenda-custom-commands
4141 '(("w" todo "WAITING"
4142 ((org-agenda-sorting-strategy '(priority-down))
4143 (org-agenda-prefix-format " Mixed: ")))
4144 ("U" tags-tree "+BOSS-URGENT"
4145 ((org-show-following-heading nil)
4146 (org-show-hierarchy-above nil)))))
4148 Now the `C-c a w' command will sort the collected entries only by
4149 priority, and the prefix format is modified to just say ` Mixed:'
4150 instead of giving the category of the entry. The sparse tags tree of
4151 `C-c a U' will now turn out ultra-compact, because neither the headline
4152 hierarchy above the match, nor the headline following the match will be
4155 For command sets creating a block agenda,
4156 `org-agenda-custom-commands' has two separate spots for setting
4157 options. You can add options that should be valid for just a single
4158 command in the set, and options that should be valid for all commands in
4159 the set. The former are just added to the command entry, the latter
4160 must come after the list of command entries. Going back to the block
4161 agenda example (*note Block agenda::), let's change the sorting strategy
4162 for the `C-c a h' commands to `priority-down', but let's sort the
4163 results for GARDEN tags query in the opposite order, `priority-up'.
4164 This would look like this:
4166 (setq org-agenda-custom-commands
4167 '(("h" "Agenda and Home-related tasks"
4171 ((org-agenda-sorting-strategy '(priority-up)))))
4172 ((org-agenda-sorting-strategy '(priority-down))))
4173 ("o" "Agenda and Office-related tasks"
4178 As you see, the values and parenthesis setting is a little complex.
4179 When in doubt, use the customize interface to set this variable - it
4180 fully supports its structure. Just one caveat: When setting options in
4181 this interface, the _values_ are just lisp expressions. So if the
4182 value is a string, you need to add the double quotes around the value
4186 File: org, Node: Exporting Agenda Views, Next: Extracting Agenda Information for other programs, Prev: Setting Options, Up: Custom agenda views
4188 8.6.4 Exporting Agenda Views
4189 ----------------------------
4191 If you are away from your computer, it can be very useful to have a
4192 printed version of some agenda views to carry around. Org-mode can
4193 export custom agenda views as plain text, HTML(1) and postscript. If
4194 you want to do this only occasionally, use the commend
4197 Write the agenda view to a file. Depending on the extension of the
4198 selected file name, the view will be exported as HTML (extension
4199 `.html' or `.htm'), Postscript (extension `.ps'), or plain text
4200 (any other extension). Use the variable
4201 `org-agenda-exporter-settings' to set options for `ps-print' and
4202 for `htmlize' to be used during export, for example
4203 (setq org-agenda-exporter-settings
4204 '((ps-number-of-columns 2)
4205 (ps-landscape-mode t)
4206 (htmlize-output-type 'inline-css)))
4208 If you need to export certain agenda views frequently, you can
4209 associate any custom agenda command with a list of output file names
4210 (2). Here is an example that first does define custom commands for the
4211 agenda and the global todo list, together with a number of files to
4212 which to export them. Then we define two block agenda commands and
4213 specify filenames for them as well. File names can be relative to the
4214 current working directory, or absolute.
4216 (setq org-agenda-custom-commands
4217 '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
4218 ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
4219 ("h" "Agenda and Home-related tasks"
4224 ("~/views/home.html"))
4225 ("o" "Agenda and Office-related tasks"
4230 ("~/views/office.ps"))))
4232 The extension of the file name determines the type of export. If it
4233 is `.html', Org-mode will use the `htmlize.el' package to convert the
4234 buffer to HTML and save it to this file name. If the extension is
4235 `.ps', `ps-print-buffer-with-faces' is used to produce postscript
4236 output. Any other extension produces a plain ASCII file.
4238 The export files are _not_ created when you use one of those
4239 commands interactively. Instead, there is a special command to produce
4240 _all_ specified files in one step:
4243 Export all agenda views that have export filenames associated with
4246 You can use the options section of the custom agenda commands to also
4247 set options for the export commands. For example:
4249 (setq org-agenda-custom-commands
4251 ((ps-number-of-columns 2)
4252 (ps-landscape-mode t)
4253 (org-agenda-prefix-format " [ ] ")
4254 (org-agenda-with-colors nil)
4255 (org-agenda-remove-tags t))
4258 This command sets two options for the postscript exporter, to make it
4259 print in two columns in landscape format - the resulting page can be cut
4260 in two and then used in a paper agenda. The remaining settings modify
4261 the agenda prefix to omit category and scheduling information, and
4262 instead include a checkbox to check off items. We also remove the tags
4263 to make the lines compact, and we don't want to use colors for the
4264 black-and-white printer. Settings specified in
4265 `org-agenda-exporter-settings' will also apply, but the settings in
4266 `org-agenda-custom-commands' take precedence.
4268 From the command line you may also use
4269 emacs -f org-batch-store-agenda-views -kill
4270 or, if you need to modify some parameters
4271 emacs -eval '(org-batch-store-agenda-views \
4272 org-agenda-ndays 30 \
4273 org-agenda-include-diary nil \
4274 org-agenda-files (quote ("~/org/project.org")))' \
4276 which will create the agenda views restricted to the file
4277 `~/org/project.org', without diary entries and with 30 days extent.
4279 ---------- Footnotes ----------
4281 (1) You need to install Hrvoje Niksic' `htmlize.el'.
4283 (2) If you want to store standard views like the weekly agenda or
4284 the global TODO list as well, you need to define custom commands for
4285 them in order to be able to specify filenames.
4288 File: org, Node: Extracting Agenda Information for other programs, Prev: Exporting Agenda Views, Up: Custom agenda views
4290 8.6.5 Extracting Agenda Information for other programs
4291 ------------------------------------------------------
4293 Org-mode provides commands to access agenda information for the command
4294 line in emacs batch mode. This extracted information can be sent
4295 directly to a printer, or it can be read by a program that does further
4296 processing of the data. The first of these commands is the function
4297 `org-batch-agenda', that produces an agenda view and sends it as ASCII
4298 text to STDOUT. The command takes a single string as parameter. If
4299 the string has length 1, it is used as a key to one of the commands you
4300 have configured in `org-agenda-custom-commands', basically any key you
4301 can use after `C-c a'. For example, to directly print the current TODO
4304 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
4306 If the parameter is a string with 2 or more characters, it is used
4307 as a tags/todo match string. For example, to print your local shopping
4308 list (all items with the tag `shop', but excluding the tag `NewYork'),
4311 emacs -batch -l ~/.emacs \
4312 -eval '(org-batch-agenda "+shop-NewYork")' | lpr
4314 You may also modify parameters on the fly like this:
4316 emacs -batch -l ~/.emacs \
4317 -eval '(org-batch-agenda "a" \
4318 org-agenda-ndays 30 \
4319 org-agenda-include-diary nil \
4320 org-agenda-files (quote ("~/org/project.org")))' \
4323 which will produce a 30 day agenda, fully restricted to the Org file
4324 `~/org/projects.org', not even including the diary.
4326 If you want to process the agenda data in more sophisticated ways,
4327 you can use the command `org-batch-agenda-csv' to get a comma-separated
4328 list of values for each agenda item. Each line in the output will
4329 contain a number of fields separated by commas. The fields in a line
4332 category The category of the item
4333 head The headline, without TODO kwd, TAGS and PRIORITY
4334 type The type of the agenda entry, can be
4335 todo selected in TODO match
4336 tagsmatch selected in tags match
4337 diary imported from diary
4340 timestamp appointment, selected by timestamp
4341 closed entry was closed on date
4342 upcoming-deadline warning about nearing deadline
4343 past-scheduled forwarded scheduled item
4344 block entry has date block including date
4345 todo The todo keyword, if any
4346 tags All tags including inherited ones, separated by colons
4347 date The relevant date, like 2007-2-14
4348 time The time, like 15:00-16:50
4349 extra String with extra planning info
4350 priority-l The priority letter if any was given
4351 priority-n The computed numerical priority
4353 Time and date will only be given if a timestamp (or deadline/scheduled)
4354 lead to the selection of the item.
4356 A CSV list like this is very easy to use in a post processing script.
4357 For example, here is a Perl program that gets the TODO list from
4358 Emacs/org-mode and prints all the items, preceded by a checkbox:
4362 # define the Emacs command to run
4363 $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
4365 # run it and capture the output
4366 $agenda = qx{$cmd 2>/dev/null};
4368 # loop over all lines
4369 foreach $line (split(/\n/,$agenda)) {
4371 # get the individual values
4372 ($category,$head,$type,$todo,$tags,$date,$time,$extra,
4373 $priority_l,$priority_n) = split(/,/,$line);
4375 # proccess and print
4376 print "[ ] $head\n";
4380 File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top
4385 Plain ASCII is normally sufficient for almost all note taking. One
4386 exception, however, are scientific notes which need to be able to
4387 contain mathematical symbols and the occasional formula. LaTeX(1) is
4388 widely used to typeset scientific documents. Org-mode supports
4389 embedding LaTeX code into its files, because many academics are used to
4390 read LaTeX source code, and because it can be readily processed into
4391 images for HTML production.
4393 It is not necessary to mark LaTeX macros and code in any special way.
4394 If you observe a few conventions, Org-mode knows how to find it and what
4399 * Math symbols:: TeX macros for symbols and Greek letters
4400 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
4401 * LaTeX fragments:: Complex formulas made easy
4402 * Processing LaTeX fragments:: Previewing LaTeX processing
4403 * CDLaTeX mode:: Speed up entering of formulas
4405 ---------- Footnotes ----------
4407 (1) LaTeX is a macro system based on Donald E. Knuth's TeX system.
4408 Many of the features described here as "LaTeX" are really from TeX, but
4409 for simplicity I am blurring this distinction.
4412 File: org, Node: Math symbols, Next: Subscripts and Superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX
4417 You can use LaTeX macros to insert special symbols like `\alpha' to
4418 indicate the Greek letter, or `\to' to indicate an arrow. Completion
4419 for these macros is available, just type `\' and maybe a few letters,
4420 and press `M-<TAB>' to see possible completions. Unlike LaTeX code,
4421 Org-mode allows these macros to be present without surrounding math
4422 delimiters, for example:
4424 Angles are written as Greek letters \alpha, \beta and \gamma.
4426 During HTML export (*note HTML export::), these symbols are
4427 translated into the proper syntax for HTML, for the above examples this
4428 is `α' and `→', respectively.
4431 File: org, Node: Subscripts and Superscripts, Next: LaTeX fragments, Prev: Math symbols, Up: Embedded LaTeX
4433 9.2 Subscripts and Superscripts
4434 ===============================
4436 Just like in LaTeX, `^' and `_' are used to indicate super- and
4437 subscripts. Again, these can be used without embedding them in
4438 math-mode delimiters. To increase the readability of ASCII text, it is
4439 not necessary (but OK) to surround multi-character sub- and superscripts
4440 with curly braces. For example
4442 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
4443 the sun is R_{sun} = 6.96 x 10^8 m.
4445 To avoid interpretation as raised or lowered text, you can quote `^'
4446 and `_' with a backslash: `\_' and `\^'.
4448 During HTML export (*note HTML export::), subscript and superscripts
4449 are surrounded with `<sub>' and `<sup>' tags, respectively.
4452 File: org, Node: LaTeX fragments, Next: Processing LaTeX fragments, Prev: Subscripts and Superscripts, Up: Embedded LaTeX
4457 With symbols, sub- and superscripts, HTML is pretty much at its end when
4458 it comes to representing mathematical formulas(1). More complex
4459 expressions need a dedicated formula processor. To this end, Org-mode
4460 can contain arbitrary LaTeX fragments. It provides commands to preview
4461 the typeset result of these fragments, and upon export to HTML, all
4462 fragments will be converted to images and inlined into the HTML
4463 document. For this to work you need to be on a system with a working
4464 LaTeX installation. You also need the `dvipng' program, available at
4465 `http://sourceforge.net/projects/dvipng/'. The LaTeX header that will
4466 be used when processing a fragment can be configured with the variable
4467 `org-format-latex-header'.
4469 LaTeX fragments don't need any special marking at all. The following
4470 snippets will be identified as LaTeX source code:
4471 * Environments of any kind. The only requirement is that the
4472 `\begin' statement appears on a new line, preceded by only
4475 * Text within the usual LaTeX math delimiters. To avoid conflicts
4476 with currency specifications, single `$' characters are only
4477 recognized as math delimiters if the enclosed text contains at
4478 most two line breaks, is directly attached to the `$' characters
4479 with no whitespace in between, and if the closing `$' is followed
4480 by whitespace or punctuation. For the other delimiters, there is
4481 no such restriction, so when in doubt, use `\(...\)' as inline
4486 \begin{equation} % arbitrary environments,
4487 x=\sqrt{b} % even tables, figures
4488 \end{equation} % etc
4490 If $a^2=b$ and \( b=2 \), then the solution must be
4491 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
4493 If you need any of the delimiter ASCII sequences for other purposes, you
4494 can configure the option `org-format-latex-options' to deselect the
4495 ones you do not wish to have interpreted by the LaTeX converter.
4497 ---------- Footnotes ----------
4499 (1) Yes, there is MathML, but that is not yet fully supported by
4500 many browsers, and there is no decent converter for turning LaTeX of
4501 ASCII representations of formulas into MathML. So for the time being,
4502 converting formulas into images seems the way to go.
4505 File: org, Node: Processing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX
4507 9.4 Processing LaTeX fragments
4508 ==============================
4510 LaTeX fragments can be processed to produce a preview images of the
4511 typeset expressions:
4514 Produce a preview image of the LaTeX fragment at point and overlay
4515 it over the source code. If there is no fragment at point,
4516 process all fragments in the current entry (between two
4517 headlines). When called with a prefix argument, process the
4518 entire subtree. When called with two prefix arguments, or when
4519 the cursor is before the first headline, process the entire buffer.
4522 Remove the overlay preview images.
4524 During HTML export (*note HTML export::), all LaTeX fragments are
4525 converted into images and inlined into the document if the following
4528 (setq org-export-with-LaTeX-fragments t)
4531 File: org, Node: CDLaTeX mode, Prev: Processing LaTeX fragments, Up: Embedded LaTeX
4533 9.5 Using CDLaTeX to enter math
4534 ===============================
4536 CDLaTeX-mode is a minor mode that is normally used in combination with a
4537 major LaTeX mode like AUCTeX in order to speed-up insertion of
4538 environments and math templates. Inside Org-mode, you can make use of
4539 some of the features of cdlatex-mode. You need to install `cdlatex.el'
4540 and `texmathp.el' (the latter comes also with AUCTeX) from
4541 `http://www.astro.uva.nl/~dominik/Tools/cdlatex'. Don't turn
4542 cdlatex-mode itself under Org-mode, but use the light version
4543 `org-cdlatex-mode' that comes as part of Org-mode. Turn it on for the
4544 current buffer with `M-x org-cdlatex-mode', or for all Org-mode files
4547 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
4549 When this mode is enabled, the following features are present (for
4550 more details see the documentation of cdlatex-mode):
4551 * Environment templates can be inserted with `C-c {'.
4553 * The <TAB> key will do template expansion if the cursor is inside a
4554 LaTeX fragment(1). For example, <TAB> will expand `fr' to
4555 `\frac{}{}' and position the cursor correctly inside the first
4556 brace. Another <TAB> will get you into the second brace. Even
4557 outside fragments, <TAB> will expand environment abbreviations at
4558 the beginning of a line. For example, if you write `equ' at the
4559 beginning of a line and press <TAB>, this abbreviation will be
4560 expanded to an `equation' environment. To get a list of all
4561 abbreviations, type `M-x cdlatex-command-help'.
4563 * Pressing `_' and `^' inside a LaTeX fragment will insert these
4564 characters together with a pair of braces. If you use <TAB> to
4565 move out of the braces, and if the braces surround only a single
4566 character or macro, they are removed again (depending on the
4567 variable `cdlatex-simplify-sub-super-scripts').
4569 * Pressing the backquote ``' followed by a character inserts math
4570 macros, also outside LaTeX fragments. If you wait more than 1.5
4571 seconds after the backquote, a help window will pop up.
4573 * Pressing the normal quote `'' followed by another character
4574 modifies the symbol before point with an accent or a font. If you
4575 wait more than 1.5 seconds after the backquote, a help window will
4576 pop up. Character modification will work only inside LaTeX
4577 fragments, outside the quote is normal.
4579 ---------- Footnotes ----------
4581 (1) Org-mode has a method to test if the cursor is inside such a
4582 fragment, see the documentation of the function
4583 `org-inside-LaTeX-fragment-p'.
4586 File: org, Node: Exporting, Next: Publishing, Prev: Embedded LaTeX, Up: Top
4591 Org-mode documents can be exported into a variety of other formats. For
4592 printing and sharing of notes, ASCII export produces a readable and
4593 simple version of an Org-mode file. HTML export allows you to publish a
4594 notes file on the web, while the XOXO format provides a solid base for
4595 exchange with a broad range of other applications. To incorporate
4596 entries with associated times like deadlines or appointments into a
4597 desktop calendar program like iCal, Org-mode can also produce extracts
4598 in the iCalendar format. Currently Org-mode only supports export, not
4599 import of these different formats.
4601 When exporting, Org-mode uses special conventions to enrich the
4602 output produced. *Note Text interpretation::, for more details.
4605 Dispatcher for export and publishing commands. Displays a
4606 help-window listing the additional key(s) needed to launch an
4607 export or publishing command.
4611 * ASCII export:: Exporting to plain ASCII
4612 * HTML export:: Exporting to HTML
4613 * XOXO export:: Exporting to XOXO
4614 * iCalendar export:: Exporting in iCalendar format
4615 * Text interpretation:: How the exporter looks at the file
4618 File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting
4623 ASCII export produces a simple and very readable version of an Org-mode
4627 Export as ASCII file. If there is an active region, only the
4628 region will be exported. For an org file `myfile.org', the ASCII
4629 file will be `myfile.txt'. The file will be overwritten without
4633 Export only the visible part of the document.
4635 In the exported version, the first 3 outline levels will become
4636 headlines, defining a general document structure. Additional levels
4637 will be exported as itemized lists. If you want that transition to
4638 occur at a different level, specify it with a prefix argument. For
4643 creates only top level headlines and does the rest as items. When
4644 headlines are converted to items, the indentation of the text following
4645 the headline is changed to fit nicely under the item. This is done with
4646 the assumption that the first bodyline indicates the base indentation of
4647 the body text. Any indentation larger than this is adjusted to preserve
4648 the layout relative to the first line. Should there be lines with less
4649 indentation than the first, these are left alone.
4652 File: org, Node: HTML export, Next: XOXO export, Prev: ASCII export, Up: Exporting
4657 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
4658 HTML formatting, in ways similar to John Grubers _markdown_ language,
4659 but with additional support for tables.
4663 * Export commands:: How to invoke HTML export
4664 * Quoting HTML tags:: Using direct HTML in Org-mode
4665 * Links:: How hyperlinks get transferred to HTML
4666 * Images:: To inline or not to inline?
4667 * CSS support:: Style specifications
4670 File: org, Node: Export commands, Next: Quoting HTML tags, Prev: HTML export, Up: HTML export
4672 10.2.1 HTML export commands
4673 ---------------------------
4676 Export as HTML file `myfile.html'.
4679 Export as HTML file and open it with a browser.
4682 Export to a temporary buffer, do not create a file.
4689 Export only the visible part of the document.
4691 In the exported version, the first 3 outline levels will become
4692 headlines, defining a general document structure. Additional levels
4693 will be exported as itemized lists. If you want that transition to
4694 occur at a different level, specify it with a prefix argument. For
4699 creates two levels of headings and does the rest as items.
4702 File: org, Node: Quoting HTML tags, Next: Links, Prev: Export commands, Up: HTML export
4704 10.2.2 Quoting HTML tags
4705 ------------------------
4707 Plain `<' and `>' are always transformed to `<' and `>' in HTML
4708 export. If you want to include simple HTML tags which should be
4709 interpreted as such, mark them with `@' as in `@<b>bold text@</b>'.
4710 Note that this really works only for simple tags. For more extensive
4711 HTML that should be copied verbatim to the exported file use either
4713 #+HTML: Literal HTML code for export
4718 All lines between these markers are exported literally
4722 File: org, Node: Links, Next: Images, Prev: Quoting HTML tags, Up: HTML export
4727 Internal links (*note Internal links::) will continue to work in HTML
4728 files only if they match a dedicated `<<target>>'. Automatic links
4729 created by radio targets (*note Radio targets::) will also work in the
4730 HTML file. Links to external files will still work if the HTML file is
4731 in the same directory as the Org-mode file. Links to other `.org'
4732 files will be translated into HTML links under the assumption that an
4733 HTML version also exists of the linked file. For information related to
4734 linking files while publishing them to a publishing directory see *Note
4738 File: org, Node: Images, Next: CSS support, Prev: Links, Up: HTML export
4743 HTML export can inline images given as links in the Org-mode file, and
4744 it can make an image the clickable part of a link. By default(1),
4745 images are inlined if a link does not have a description. So
4746 `[[file:myimg.jpg]]' will be inlined, while `[[file:myimg.jpg][the
4747 image]]' will just produce a link `the image' that points to the image.
4748 If the description part itself is a `file:' link or a `http:' URL
4749 pointing to an image, this image will be inlined and activated so that
4750 clicking on the image will activate the link. For example, to include
4751 a thumbnail that will link to a high resolution version of the image,
4754 [[file:highres.jpg][file:thumb.jpg]]
4756 and you could use `http' addresses just as well.
4758 ---------- Footnotes ----------
4760 (1) but see the variable `org-export-html-inline-images'
4763 File: org, Node: CSS support, Prev: Images, Up: HTML export
4768 You can also give style information for the exported file. The HTML
4769 exporter assigns the following CSS classes to appropriate parts of the
4770 document - your style specifications may change these:
4772 .done the DONE keyword
4773 .timestamp time stamp
4774 .timestamp-kwd keyword associated with a time stamp, like SCHEDULED
4775 .tag tag in a headline
4776 .target target for links
4778 The default style specification can be configured through the option
4779 `org-export-html-style'. If you want to use a file-local style, you
4780 may use file variables, best wrapped into a COMMENT section at the end
4781 of the outline tree. For example(1):
4783 * COMMENT html style specifications
4786 # org-export-html-style: " <style type=\"text/css\">
4787 # p {font-weight: normal; color: gray; }
4788 # h1 {color: black; }
4792 Remember to execute `M-x normal-mode' after changing this to make
4793 the new style visible to Emacs. This command restarts org-mode for the
4794 current buffer and forces Emacs to re-evaluate the local variables
4795 section in the buffer.
4797 ---------- Footnotes ----------
4799 (1) Under Emacs 21, the continuation lines for a variable value
4800 should have no `#' at the start of the line.
4803 File: org, Node: XOXO export, Next: iCalendar export, Prev: HTML export, Up: Exporting
4808 Org-mode contains an exporter that produces XOXO-style output.
4809 Currently, this exporter only handles the general outline structure and
4810 does not interpret any additional Org-mode features.
4813 Export as XOXO file `myfile.html'.
4816 Export only the visible part of the document.
4819 File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting
4821 10.4 iCalendar export
4822 =====================
4824 Some people like to use Org-mode for keeping track of projects, but
4825 still prefer a standard calendar application for anniversaries and
4826 appointments. In this case it can be useful to have deadlines and
4827 other time-stamped items in Org-mode files show up in the calendar
4828 application. Org-mode can export calendar information in the standard
4829 iCalendar format. If you also want to have TODO entries included in the
4830 export, configure the variable `org-icalendar-include-todo'.
4833 Create iCalendar entries for the current file and store them in
4834 the same directory, using a file extension `.ics'.
4837 Like `C-c C-e i', but do this for all files in `org-agenda-files'.
4838 For each of these files, a separate iCalendar file will be
4842 Create a single large iCalendar file from all files in
4843 `org-agenda-files' and write it to the file given by
4844 `org-combined-agenda-icalendar-file'.
4846 How this calendar is best read and updated, depends on the
4847 application you are using. The FAQ covers this issue.
4850 File: org, Node: Text interpretation, Prev: iCalendar export, Up: Exporting
4852 10.5 Text interpretation by the exporter
4853 ========================================
4855 The exporter backends interpret additional structure in the Org-mode
4856 file in order to produce better output.
4860 * Comment lines:: Some lines will not be exported
4861 * Initial text:: Text before the first headline
4862 * Enhancing text:: Subscripts, symbols and more
4863 * Export options:: How to influence the export settings
4866 File: org, Node: Comment lines, Next: Initial text, Prev: Text interpretation, Up: Text interpretation
4868 10.5.1 Comment lines
4869 --------------------
4871 Lines starting with `#' in column zero are treated as comments and will
4872 never be exported. Also entire subtrees starting with the word
4873 `COMMENT' will never be exported.
4876 Toggle the COMMENT keyword at the beginning of an entry.
4879 File: org, Node: Initial text, Next: Enhancing text, Prev: Comment lines, Up: Text interpretation
4881 10.5.2 Text before the first headline
4882 -------------------------------------
4884 Org-mode normally ignores any text before the first headline when
4885 exporting, leaving this region for internal links to speed up navigation
4886 etc. However, in publishing-oriented files, you might want to have some
4887 text before the first headline, like a small introduction, special HTML
4888 code with a navigation bar, etc. You can ask to have this part of the
4889 file exported as well by setting the variable
4890 `org-export-skip-text-before-1st-heading' to `nil'. On a per-file
4891 basis, you can get the same effect with
4895 The text before the first headline will be fully processed (*note
4896 Enhancing text::), and the first non-comment line becomes the title of
4897 the exported document. If you need to include literal HTML, use the
4898 special constructs described in *Note Quoting HTML tags::. The table
4899 of contents is normally inserted directly before the first headline of
4900 the file. If you would like to get it to a different location, insert
4901 the string `[TABLE-OF-CONTENTS]' on a line by itself at the desired
4904 Finally, if you want to use the space before the first headline for
4905 internal purposes, but _still_ want to place something before the first
4906 headline when exporting the file, you can use the `#+TEXT' construct:
4909 #+TEXT: This text will go before the *first* headline.
4910 #+TEXT: We place the table of contents here:
4911 #+TEXT: [TABLE-OF-CONTENTS]
4912 #+TEXT: This goes between the table of contents and the first headline
4915 File: org, Node: Enhancing text, Next: Export options, Prev: Initial text, Up: Text interpretation
4917 10.5.3 Enhancing text for export
4918 --------------------------------
4920 Some of the export backends of Org-mode allow for sophisticated text
4921 formatting, this is true in particular for the HTML backend. Org-mode
4922 has a number of typing conventions that allow to produce a richly
4925 * Plain lists `-', `*' or `+' as bullet, or with `1.' or `2)' as
4926 enumerator will be recognized and transformed if the backend
4927 supports lists. See *Note Plain lists::.
4929 * You can make words *bold*, /italic/, _underlined_, `=code=', and
4930 even `+strikethrough+'(1).
4932 * A line consisting of only dashes, and at least 5 of them, will be
4933 exported as a horizontal line (`<hr/>' in HTML).
4935 * Many TeX macros and entire LaTeX fragments are converted into HTML
4936 entities or images (*note Embedded LaTeX::).
4938 * Tables are transformed into native tables under the exporter, if
4939 the export backend supports this. Data fields before the first
4940 horizontal separator line will be formatted as table header fields.
4942 * If a headline starts with the word `QUOTE', the text below the
4943 headline will be typeset as fixed-width, to allow quoting of
4944 computer codes etc. Lines starting with `:' are also typeset in
4947 Toggle fixed-width for entry (QUOTE) or region, see below.
4949 * A double backslash _at the end of a line_ enforces a line break at
4952 If these conversions conflict with your habits of typing ASCII text,
4953 they can all be turned off with corresponding variables. See the
4954 customization group `org-export-general', and the following section
4955 which explains how to set export options with special lines in a buffer.
4957 ---------- Footnotes ----------
4959 (1) but remember that strikethrough is typographically evil and
4960 should never be used.
4963 File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation
4965 10.5.4 Export options
4966 ---------------------
4968 The exporter recognizes special lines in the buffer which provide
4969 additional information. These lines may be put anywhere in the file.
4970 The whole set of lines can be inserted into the buffer with `C-c C-e
4971 t'. For individual lines, a good way to make sure the keyword is
4972 correct is to type `#+' and then use `M-<TAB>' completion (*note
4976 Insert template with export options, see example below.
4978 #+TITLE: the title to be shown (default is the buffer name)
4979 #+AUTHOR: the author (default taken from `user-full-name')
4980 #+EMAIL: his/her email address (default from `user-mail-address')
4981 #+LANGUAGE: language for HTML, e.g. `en' (`org-export-default-language')
4982 #+TEXT: Some descriptive text to be inserted at the beginning.
4983 #+TEXT: Several lines may be given.
4984 #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t *:nil TeX:t LaTeX:t skip:t
4986 The OPTIONS line is a compact form to specify export settings. Here
4988 H: set the number of headline levels for export
4989 num: turn on/off section-numbers
4990 toc: turn on/off table of contents, or set level limit (integer)
4991 \n: turn on/off linebreak-preservation
4992 @: turn on/off quoted HTML tags
4993 :: turn on/off fixed-width sections
4994 |: turn on/off tables
4995 ^: turn on/off TeX-like syntax for sub- and superscripts. If
4996 you write "^:{}", `a_{b}' will be interpreted, but
4997 the simple `a_b' will be left as it is.
4998 *: turn on/off emphasized text (bold, italic, underlined)
4999 TeX: turn on/off simple TeX macros in plain text
5000 LaTeX: turn on/off LaTeX fragments
5001 skip: turn on/off skipping the text before the first heading
5004 File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top
5009 Org-mode includes(1) a publishing management system that allows you to
5010 configure automatic HTML conversion of _projects_ composed of
5011 interlinked org files. This system is called _org-publish_. You can
5012 also configure org-publish to automatically upload your exported HTML
5013 pages and related attachments, such as images and source code files, to
5014 a web server. Org-publish turns org-mode into a web-site authoring
5017 Org-publish has been contributed to Org-mode by David O'Toole.
5021 * Configuration:: Defining projects
5022 * Sample configuration:: Example projects
5023 * Triggering publication:: Publication commands
5025 ---------- Footnotes ----------
5027 (1) `org-publish.el' is not yet part of Emacs, so if you are using
5028 `org.el' as it comes with Emacs, you need to download this file
5029 separately. Also make sure org.el is at least version 4.27.
5032 File: org, Node: Configuration, Next: Sample configuration, Prev: Publishing, Up: Publishing
5037 Publishing needs significant configuration to specify files, destination
5038 and many other properties of a project.
5042 * Project alist:: The central configuration variable
5043 * Sources and destinations:: From here to there
5044 * Selecting files:: What files are part of the project?
5045 * Publishing action:: Setting the function doing the publishing
5046 * Publishing options:: Tweaking HTML export
5047 * Publishing links:: Which links keep working after publishing?
5048 * Project page index:: Publishing a list of project files
5051 File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration
5053 11.1.1 The variable `org-publish-project-alist'
5054 -----------------------------------------------
5056 Org-publish is configured almost entirely through setting the value of
5057 one variable, called `org-publish-project-alist'. Each element of the
5058 list configures one project, and may be in one of the two following
5061 ("project-name" :property value :property value ...)
5065 ("project-name" :components ("project-name" "project-name" ...))
5067 In both cases, projects are configured by specifying property values.
5068 A project defines the set of files that will be published, as well as
5069 the publishing configuration to use when publishing those files. When
5070 a project takes the second form listed above, the individual members of
5071 the "components" property are taken to be components of the project,
5072 which group together files requiring different publishing options. When
5073 you publish such a "meta-project" all the components will also publish.
5076 File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration
5078 11.1.2 Sources and destinations for files
5079 -----------------------------------------
5081 Most properties are optional, but some should always be set. In
5082 particular, org-publish needs to know where to look for source files,
5083 and where to put published files.
5085 `:base-directory' Directory containing publishing source files
5086 `:publishing-directory'Directory (possibly remote) where output files
5088 `:preparation-function'Function called before starting publishing
5089 process, for example to run `make' for updating
5090 files to be published.
5093 File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration
5095 11.1.3 Selecting files
5096 ----------------------
5098 By default, all files with extension `.org' in the base directory are
5099 considered part of the project. This can be modified by setting the
5101 `:base-extension' Extension (without the dot!) of source files. This
5102 actually is a regular expression.
5103 `:exclude' Regular expression to match file names that should
5104 not be published, even though they have been selected
5105 on the basis of their extension.
5106 `:include' List of files to be included regardless of
5107 `:base-extension' and `:exclude'.
5110 File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration
5112 11.1.4 Publishing Action
5113 ------------------------
5115 Publishing means that a file is copied to the destination directory and
5116 possibly transformed in the process. The default transformation is to
5117 export Org-mode files as HTML files, and this is done by the function
5118 `org-publish-org-to-html' which calls the HTML exporter (*note HTML
5119 export::). Other files like images only need to be copied to the
5120 publishing destination. For non-Org-mode files, you need to specify
5121 the publishing function.
5123 `:publishing-function' Function executing the publication of a file.
5124 This may also be a list of functions, which will
5125 all be called in turn.
5127 The function must accept two arguments: a property list containing at
5128 least a `:publishing-directory' property, and the name of the file to
5129 be published. It should take the specified file, make the necessary
5130 transformation (if any) and place the result into the destination
5131 folder. You can write your own publishing function, but `org-publish'
5132 provides one for attachments (files that only need to be copied):
5133 `org-publish-attachment'.
5136 File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration
5138 11.1.5 Options for the HTML exporter
5139 ------------------------------------
5141 The property list can be used to set many export options for the HTML
5142 exporter. In most cases, these properties correspond to user variables
5143 in Org-mode. The table below lists these properties along with the
5144 variable they belong to. See the documentation string for the
5145 respective variable for details.
5147 `:language' `org-export-default-language'
5148 `:headline-levels' `org-export-headline-levels'
5149 `:section-numbers' `org-export-with-section-numbers'
5150 `:table-of-contents' `org-export-with-toc'
5151 `:archived-trees' `org-export-with-archived-trees'
5152 `:emphasize' `org-export-with-emphasize'
5153 `:sub-superscript' `org-export-with-sub-superscripts'
5154 `:TeX-macros' `org-export-with-TeX-macros'
5155 `:LaTeX-fragments' `org-export-with-LaTeX-fragments'
5156 `:fixed-width' `org-export-with-fixed-width'
5157 `:timestamps' `org-export-with-timestamps'
5159 `:tags' `org-export-with-tags'
5161 `:tables' `org-export-with-tables'
5162 `:table-auto-headline' `org-export-highlight-first-table-line'
5163 `:style' `org-export-html-style'
5164 `:convert-org-links' `org-export-html-link-org-files-as-html'
5165 `:inline-images' `org-export-html-inline-images'
5166 `:expand-quoted-html' `org-export-html-expand'
5167 `:timestamp' `org-export-html-with-timestamp'
5168 `:publishing-directory'`org-export-publishing-directory'
5169 `:preamble' `org-export-html-preamble'
5170 `:postamble' `org-export-html-postamble'
5171 `:auto-preamble' `org-export-html-auto-preamble'
5172 `:auto-postamble' `org-export-html-auto-postamble'
5173 `:author' `user-full-name'
5174 `:email' `user-mail-address'
5176 When a property is given a value in org-publish-project-alist, its
5177 setting overrides the value of the corresponding user variable (if any)
5178 during publishing. options set within a file (*note Export options::),
5179 however, override everything.
5182 File: org, Node: Publishing links, Next: Project page index, Prev: Publishing options, Up: Configuration
5184 11.1.6 Links between published files
5185 ------------------------------------
5187 To create a link from one Org-mode file to another, you would use
5188 something like `[[file:foo.org][The foo]]' or simply `file:foo.org.'
5189 (*note Hyperlinks::). Upon publishing this link becomes a link to
5190 `foo.html'. In this way, you can interlink the pages of your "org web"
5191 project and the links will work as expected when you publish them to
5194 You may also link to related files, such as images. Provided you are
5195 careful with relative pathnames, and provided you have also configured
5196 org-publish to upload the related files, these links will work too.
5197 *Note Complex example:: for an example of this usage.
5199 Sometime an Org-mode file to be published may contain links that are
5200 only valid in your production environment, but not in the publishing
5201 location. In this case, use the property
5203 `:link-validation-function' Function to validate links
5205 to define a function for checking link validity. This function must
5206 accept two arguments, the file name and a directory relative to which
5207 the file name is interpreted in the production environment. If this
5208 function returns `nil', then the HTML generator will only insert a
5209 description into the HTML file, but no link. One option for this
5210 function is `org-publish-validate-link' which checks if the given file
5211 is part of any project in `org-publish-project-alist'.
5214 File: org, Node: Project page index, Prev: Publishing links, Up: Configuration
5216 11.1.7 Project page index
5217 -------------------------
5219 The following properties may be used to control publishing of an index
5220 of files or summary page for a given project.
5222 `:auto-index' When non-nil, publish an index during
5223 org-publish-current-project or org-publish-all.
5224 `:index-filename' Filename for output of index. Defaults to `index.org'
5225 (which becomes `index.html').
5226 `:index-title' Title of index page. Defaults to name of file.
5227 `:index-function' Plugin function to use for generation of index.
5228 Defaults to `org-publish-org-index', which generates
5229 a plain list of links to all files in the project.
5232 File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing
5234 11.2 Sample configuration
5235 =========================
5237 Below we provide two example configurations. The first one is a simple
5238 project publishing only a set of Org-mode files. The second example is
5239 more complex, with a multi-component project.
5243 * Simple example:: One-component publishing
5244 * Complex example:: A multi-component publishing example
5247 File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration
5249 11.2.1 Example: simple publishing configuration
5250 -----------------------------------------------
5252 This example publishes a set of Org-mode files to the `public_html'
5253 directory on the local machine.
5255 (setq org-publish-project-alist
5257 :base-directory "~/org/"
5258 :publishing-directory "~/public_html"
5259 :section-numbers nil
5260 :table-of-contents nil
5261 :style "<link rel=stylesheet
5262 href=\"../other/mystyle.css\"
5263 type=\"text/css\">")))
5266 File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration
5268 11.2.2 Example: complex publishing configuration
5269 ------------------------------------------------
5271 This more complicated example publishes an entire website, including
5272 org files converted to HTML, image files, emacs lisp source code, and
5273 stylesheets. The publishing-directory is remote and private files are
5276 To ensure that links are preserved, care should be taken to replicate
5277 your directory structure on the web server, and to use relative file
5278 paths. For example, if your org files are kept in `~/org' and your
5279 publishable images in `~/images', you'd link to an image with
5280 file:../images/myimage.png
5281 On the web server, the relative path to the image should be the
5282 same. You can accomplish this by setting up an "images" folder in the
5283 right place on the webserver, and publishing images to it.
5285 (setq org-publish-project-alist
5287 :base-directory "~/org/"
5288 :base-extension "org"
5289 :publishing-directory "/ssh:user@host:~/html/notebook/"
5290 :publishing-function org-publish-org-to-html
5291 :exclude "PrivatePage.org" ;; regexp
5293 :section-numbers nil
5294 :table-of-contents nil
5295 :style "<link rel=stylesheet
5296 href=\"../other/mystyle.css\" type=\"text/css\">"
5298 :auto-postamble nil)
5301 :base-directory "~/images/"
5302 :base-extension "jpg\\|gif\\|png"
5303 :publishing-directory "/ssh:user@host:~/html/images/"
5304 :publishing-function org-publish-attachment)
5307 :base-directory "~/other/"
5308 :base-extension "css\\|el"
5309 :publishing-directory "/ssh:user@host:~/html/other/"
5310 :publishing-function org-publish-attachment)
5311 ("website" :components ("orgfiles" "images" "other"))))
5314 File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing
5316 11.3 Triggering publication
5317 ===========================
5319 Once org-publish is properly configured, you can publish with the
5320 following functions:
5323 Prompt for a specific project and publish all files that belong to
5327 Publish the project containing the current file.
5330 Publish only the current file.
5333 Publish all projects.
5335 Org uses timestamps to track when a file has changed. The above
5336 functions normally only publish changed files. You can override this and
5337 force publishing of all files by giving a prefix argument.
5340 File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishing, Up: Top
5347 * Completion:: M-TAB knows what you need
5348 * Customization:: Adapting Org-mode to your taste
5349 * In-buffer settings:: Overview of the #+KEYWORDS
5350 * The very busy C-c C-c key:: When in doubt, press C-c C-c
5351 * Clean view:: Getting rid of leading stars in the outline
5352 * TTY keys:: Using Org-mode on a tty
5353 * Interaction:: Other Emacs packages
5354 * Bugs:: Things which do not work perfectly
5357 File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous
5362 Org-mode supports in-buffer completion. This type of completion does
5363 not make use of the minibuffer. You simply type a few letters into the
5364 buffer and use the key to complete text right there.
5367 Complete word at point
5368 * At the beginning of a headline, complete TODO keywords.
5370 * After `\', complete TeX symbols supported by the exporter.
5372 * After `*', complete headlines in the current buffer so that
5373 they can be used in search links like `[[*find this
5376 * After `:', complete tags. The list of tags is taken from the
5377 variable `org-tag-alist' (possibly set through the `#+TAGS'
5378 in-buffer option, *note Setting tags::), or it is created
5379 dynamically from all tags used in the current buffer.
5381 * After `[', complete link abbreviations (*note Link
5384 * After `#+', complete the special keywords like `TYP_TODO' or
5385 `OPTIONS' which set file-specific options for Org-mode. When
5386 the option keyword is already complete, pressing `M-<TAB>'
5387 again will insert example settings for this keyword.
5389 * In the line after `#+STARTUP: ', complete startup keywords,
5390 i.e. valid keys for this line.
5392 * Elsewhere, complete dictionary words using ispell.
5395 File: org, Node: Customization, Next: In-buffer settings, Prev: Completion, Up: Miscellaneous
5400 There are more than 180 variables that can be used to customize
5401 Org-mode. For the sake of compactness of the manual, I am not
5402 describing the variables here. A structured overview of customization
5403 variables is available with `M-x org-customize'. Or select `Browse Org
5404 Group' from the `Org->Customization' menu. Many settings can also be
5405 activated on a per-file basis, by putting special lines into the buffer
5406 (*note In-buffer settings::).
5409 File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous
5411 12.3 Summary of in-buffer settings
5412 ==================================
5414 Org-mode uses special lines in the buffer to define settings on a
5415 per-file basis. These lines start with a `#+' followed by a keyword, a
5416 colon, and then individual words defining a setting. Several setting
5417 words can be in the same line, but you can also have multiple lines for
5418 the keyword. While these settings are described throughout the manual,
5419 here is a summary. After changing any of those lines in the buffer,
5420 press `C-c C-c' with the cursor still in the line to activate the
5421 changes immediately. Otherwise they become effective only when the
5422 file is visited again in a new Emacs session.
5425 This line sets options to be used at startup of org-mode, when an
5426 Org-mode file is being visited. The first set of options deals
5427 with the initial visibility of the outline tree. The
5428 corresponding variable for global default settings is
5429 `org-startup-folded', with a default value `t', which means
5431 overview top-level headlines only
5432 content all headlines
5433 showall no folding at all, show everything
5434 Then there are options for aligning tables upon visiting a file.
5435 This is useful in files containing narrowed table columns. The
5436 corresponding variable is `org-startup-align-all-tables', with a
5437 default value `nil'.
5438 align align all tables
5439 noalign don't align tables on startup
5440 Logging TODO state changes and clock intervals (variable
5441 `org-log-done') can be configured using these options.
5442 logging record a timestamp when an item is marked DONE
5443 nologging don't record when items are marked DONE
5444 lognotedone record timestamp and a note when DONE
5445 lognotestate record timestamp, note when TODO state changes
5446 logrepeat record a not when re-instating a repeating item
5447 nologrepeat do not record when re-instating repeating item
5448 lognoteclock-out record timestamp and a note when clocking out
5449 Here are the options for hiding leading stars in outline headings.
5450 The corresponding variables are `org-hide-leading-stars' and
5451 `org-odd-levels-only', both with a default setting `nil' (meaning
5452 `showstars' and `oddeven').
5453 hidestars make all but one of the stars starting a headline invisible.
5454 showstars show all stars starting a headline
5455 odd allow only odd outline levels (1,3,...)
5456 oddeven allow all outline levels
5457 To turn on custom format overlays over time stamps (variables
5458 `org-put-time-stamp-overlays' and
5459 `org-time-stamp-overlay-formats'), use
5460 customtime overlay custom time format
5461 The following options influence the table spreadsheet (variable
5462 `constants-unit-system').
5463 constcgs `constants.el' should use the c-g-s unit system
5464 constSI `constants.el' should use the SI unit system
5466 `#+SEQ_TODO: #+TYP_TODO:'
5467 These lines set the TODO keywords and their interpretation in the
5468 current file. The corresponding variables are `org-todo-keywords'
5469 and `org-todo-interpretation'.
5471 `#+TAGS: TAG1(c1) TAG2(c2)'
5472 These lines (several such lines are allowed) specify the legal
5473 tags in this file, and (potentially) the corresponding _fast tag
5474 selection_ keys. The corresponding variable is `org-tag-alist'.
5476 `#+LINK: linkword replace'
5477 These lines (several are allowed) specify link abbreviations.
5478 *Note Link abbreviations::. The corresponding variable is
5479 `org-link-abbrev-alist'.
5482 This line sets the category for the agenda file. The category
5483 applies for all subsequent lines until the next `#+CATEGORY' line,
5484 or the end of the file. The first such line also applies to any
5487 `#+ARCHIVE: %s_done::'
5488 This line sets the archive location for the agenda file. It
5489 applies for all subsequent lines until the next `#+CATEGORY' line,
5490 or the end of the file. The first such line also applies to any
5491 entries before it. The corresponding variable is
5492 `org-archive-location'.
5495 This line contains the formulas for the table directly above the
5498 `#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:'
5499 These lines provide settings for exporting files. For more
5500 details see *Note Export options::.
5503 File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous
5505 12.4 The very busy C-c C-c key
5506 ==============================
5508 The key `C-c C-c' has many purposes in org-mode, which are all
5509 mentioned scattered throughout this manual. One specific function of
5510 this key is to add _tags_ to a headline (*note Tags::). In many other
5511 circumstances it means something like _Hey Org-mode, look here and
5512 update according to what you see here_. Here is a summary of what this
5513 means in different contexts.
5515 - If there are highlights in the buffer from the creation of a sparse
5516 tree, or from clock display, remove these highlights.
5518 - If the cursor is in one of the special `#+KEYWORD' lines, this
5519 triggers scanning the buffer for these lines and updating the
5522 - If the cursor is inside a table, realign the table. This command
5523 works even if the automatic table editor has been turned off.
5525 - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the
5528 - If the cursor is inside a table created by the `table.el' package,
5529 activate that table.
5531 - If the current buffer is a remember buffer, close the note and
5532 file it. With a prefix argument, file it, without further
5533 interaction, to the default location.
5535 - If the cursor is on a `<<<target>>>', update radio targets and
5536 corresponding links in this buffer.
5538 - If the cursor is in a plain list item with a checkbox, toggle the
5539 status of the checkbox.
5541 - If the cursor is on a numbered item in a plain list, renumber the
5545 File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous
5547 12.5 A cleaner outline view
5548 ===========================
5550 Some people find it noisy and distracting that the Org-mode headlines
5551 are starting with a potentially large number of stars. For example the
5552 tree from *Note Headlines:::
5554 * Top level headline
5560 * Another top level headline
5562 Unfortunately this is deeply ingrained into the code of Org-mode and
5563 cannot be easily changed. You can, however, modify the display in such
5564 a way that all leading stars become invisible and the outline more easy
5565 to read. To do this, customize the variable `org-hide-leading-stars'
5568 (setq org-hide-leading-stars t)
5570 or change this on a per-file basis with one of the lines (anywhere in
5573 #+STARTUP: showstars
5574 #+STARTUP: hidestars
5576 Press `C-c C-c' with the cursor in a `STARTUP' line to activate the
5579 With stars hidden, the tree becomes:
5581 * Top level headline
5587 * Another top level headline
5589 Note that the leading stars are not truly replaced by whitespace, they
5590 are only fontified with the face `org-hide' that uses the background
5591 color as font color. If you are not using either white or black
5592 background, you may have to customize this face to get the wanted
5593 effect. Another possibility is to set this font such that the extra
5594 stars are almost invisible, for example using the color `grey90' on a
5597 Things become cleaner still if you skip all the even levels and use
5598 only odd levels 1, 3, 5..., effectively adding two stars to go from one
5599 outline level to the next:
5601 * Top level headline
5607 * Another top level headline
5609 In order to make the structure editing and export commands handle this
5610 convention correctly, use
5612 (setq org-odd-levels-only t)
5614 or set this on a per-file basis with one of the following lines (don't
5615 forget to press `C-c C-c' with the cursor in the startup line to
5616 activate changes immediately).
5621 You can convert an Org-mode file from single-star-per-level to the
5622 double-star-per-level convention with `M-x org-convert-to-odd-levels
5623 RET' in that file. The reverse operation is `M-x
5624 org-convert-to-oddeven-levels'.
5627 File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous
5629 12.6 Using org-mode on a tty
5630 ============================
5632 Org-mode uses a number of keys that are not accessible on a tty. This
5633 applies to most special keys like cursor keys, <TAB> and <RET>, when
5634 these are combined with modifier keys like <Meta> and/or <Shift>.
5635 Org-mode uses these bindings because it needs to provide keys for a
5636 large number of commands, and because these keys appeared particularly
5637 easy to remember. In order to still be able to access the core
5638 functionality of Org-mode on a tty, alternative bindings are provided.
5639 Here is a complete list of these bindings, which are obviously more
5640 cumbersome to use. Note that sometimes a work-around can be better.
5641 For example changing a time stamp is really only fun with `S-<cursor>'
5642 keys. On a tty you would rather use `C-c .' to re-insert the
5645 Default Alternative 1 Alternative 2
5646 `S-<TAB>' `C-u <TAB>'
5647 `M-<left>' `C-c C-x l' `<Esc> <left>'
5648 `M-S-<left>'`C-c C-x L'
5649 `M-<right>' `C-c C-x r' `<Esc>
5651 `M-S-<right>'`C-c C-x R'
5652 `M-<up>' `C-c C-x u' `<Esc> <up>'
5653 `M-S-<up>' `C-c C-x U'
5654 `M-<down>' `C-c C-x d' `<Esc> <down>'
5655 `M-S-<down>'`C-c C-x D'
5656 `S-<RET>' `C-c C-x c'
5657 `M-<RET>' `C-c C-x m' `<Esc> <RET>'
5658 `M-S-<RET>' `C-c C-x M'
5659 `S-<left>' `C-c <left>'
5660 `S-<right>' `C-c <right>'
5662 `S-<down>' `C-c <down>'
5663 `C-S-<left>'`C-c C-x
5665 `C-S-<right>'`C-c C-x
5669 File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous
5671 12.7 Interaction with other packages
5672 ====================================
5674 Org-mode lives in the world of GNU Emacs and interacts in various ways
5675 with other code out there.
5679 * Cooperation:: Packages Org-mode cooperates with
5680 * Conflicts:: Packages that lead to conflicts
5683 File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction
5685 12.7.1 Packages that Org-mode cooperates with
5686 ---------------------------------------------
5688 `calc.el' by Dave Gillespie
5689 Org-mode uses the calc package for implementing spreadsheet
5690 functionality in its tables (*note The spreadsheet::). Org-mode
5691 checks for the availability of calc by looking for the function
5692 `calc-eval' which should be autoloaded in your setup if calc has
5693 been installed properly. As of Emacs 22, calc is part of the Emacs
5694 distribution. Another possibility for interaction between the two
5695 packages is using calc for embedded calculations. *Note Embedded
5696 Mode: (calc)Embedded Mode.
5698 `constants.el' by Carsten Dominik
5699 In a table formula (*note The spreadsheet::), it is possible to use
5700 names for natural constants or units. Instead of defining your own
5701 constants in the variable `org-table-formula-constants', install
5702 the `constants' package which defines a large number of constants
5703 and units, and lets you use unit prefixes like `M' for `Mega' etc.
5704 You will need version 2.0 of this package, available at
5705 `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for the
5706 function `constants-get', which has to be autoloaded in your
5707 setup. See the installation instructions in the file
5710 `cdlatex.el' by Carsten Dominik
5711 Org-mode can make use of the cdlatex package to efficiently enter
5712 LaTeX fragments into Org-mode files. See *Note CDLaTeX mode::.
5714 `remember.el' by John Wiegley
5715 Org mode cooperates with remember, see *Note Remember::.
5716 `Remember.el' is not part of Emacs, find it on the web.
5718 `table.el' by Takaaki Ota
5719 Complex ASCII tables with automatic line wrapping, column- and
5720 row-spanning, and alignment can be created using the Emacs table
5721 package by Takaaki Ota (`http://sourceforge.net/projects/table',
5722 and also part of Emacs 22). When <TAB> or `C-c C-c' is pressed in
5723 such a table, Org-mode will call `table-recognize-table' and move
5724 the cursor into the table. Inside a table, the keymap of Org-mode
5725 is inactive. In order to execute Org-mode-related commands, leave
5729 Recognize `table.el' table. Works when the cursor is in a
5733 Insert a table.el table. If there is already a table at
5734 point, this command converts it between the table.el format
5735 and the Org-mode format. See the documentation string of the
5736 command `org-convert-table' for the restrictions under which
5738 `table.el' is part of Emacs 22.
5741 File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction
5743 12.7.2 Packages that lead to conflicts with Org-mode
5744 ----------------------------------------------------
5746 `allout.el' by Ken Manheimer
5747 Startup of Org-mode may fail with the error message
5748 `(wrong-type-argument keymapp nil)' when there is an outdated
5749 version `allout.el' on the load path, for example the version
5750 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem
5751 will disappear. If for some reason you cannot do this, make sure
5752 that org.el is loaded _before_ `allout.el', for example by putting
5753 `(require 'org)' early enough into your `.emacs' file.
5755 `CUA.el' by Kim. F. Storm
5756 Keybindings in Org-mode conflict with the `S-<cursor>' keys used
5757 by CUA-mode (as well as pc-select-mode and s-region-mode) to
5758 select and extend the region. If you want to use one of these
5759 packages along with Org-mode, configure the variable
5760 `org-CUA-compatible'. When set, Org-mode will move the following
5761 keybindings in org-mode files, and in the agenda buffer (but not
5762 during date selection).
5764 S-UP -> M-p S-DOWN -> M-n
5765 S-LEFT -> M-- S-RIGHT -> M-+
5767 Yes, these are unfortunately more difficult to remember. If you
5768 want to have other replacement keys, look at the variable
5769 `org-disputed-keys'.
5771 `windmove.el' by Hovav Shacham
5772 Also this package uses the `S-<cursor>' keys, so everything written
5773 in the paragraph above about CUA mode also applies here.
5776 File: org, Node: Bugs, Prev: Interaction, Up: Miscellaneous
5781 Here is a list of things that should work differently, but which I have
5782 found too hard to fix.
5784 * If a table field starts with a link, and if the corresponding table
5785 column is narrowed (*note Narrow columns::) to a width too small to
5786 display the link, the field would look entirely empty even though
5787 it is not. To prevent this, Org-mode throws an error. The
5788 work-around is to make the column wide enough to fit the link, or
5789 to add some text (at least 2 characters) before the link in the
5792 * Narrowing table columns does not work on XEmacs, because the
5793 `format' function does not transport text properties.
5795 * Text in an entry protected with the `QUOTE' keyword should not
5798 * When the application called by `C-c C-o' to open a file link fails
5799 (for example because the application does not exist or refuses to
5800 open the file), it does so silently. No error message is
5803 * Recalculating a table line applies the formulas from left to right.
5804 If a formula uses _calculated_ fields further down the row,
5805 multiple recalculation may be needed to get all fields consistent.
5806 You may use the command `org-table-iterate' (`C-u C-c *') to
5807 recalculate until convergence.
5809 * A single letter cannot be made bold, for example `*a*'.
5811 * The exporters work well, but could be made more efficient.
5814 File: org, Node: Extensions and Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top
5816 Appendix A Extensions, Hooks and Hacking
5817 ****************************************
5819 This appendix lists extensions for Org-mode written by other authors.
5820 It also covers some aspects where users can extend the functionality of
5825 * Extensions:: Existing 3rd-part extensions
5826 * Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
5827 * Dynamic blocks:: Automatically filled blocks
5828 * Special agenda views:: Customized views
5831 File: org, Node: Extensions, Next: Tables in arbitrary syntax, Prev: Extensions and Hacking, Up: Extensions and Hacking
5833 A.1 Third-party extensions for Org-mode
5834 =======================================
5836 The following extensions for Org-mode have been written by other people:
5838 `org-publish.el' by David O'Toole
5839 This package provides facilities for publishing related sets of
5840 Org-mode files together with linked files like images as webpages.
5841 It is highly configurable and can be used for other publishing
5842 purposes as well. As of Org-mode version 4.30, `org-publish.el'
5843 is part of the Org-mode distribution. It is not yet part of
5844 Emacs, however, a delay caused by the preparations for the 22.1
5845 release. In the mean time, `org-publish.el' can be downloaded
5846 from David's site: `http://dto.freeshell.org/e/org-publish.el'.
5848 `org-mouse.el' by Piotr Zielinski
5849 This package implements extended mouse functionality for Org-mode.
5850 It allows you to cycle visibility and to edit the document
5851 structure with the mouse. Best of all, it provides a
5852 context-sensitive menu on <mouse-3> that changes depending on the
5853 context of a mouse-click. As of Org-mode version 4.53,
5854 `org-mouse.el' is part of the Org-mode distribution. It is not
5855 yet part of Emacs, however, a delay caused by the preparations for
5856 the 22.1 release. In the mean time, `org-mouse.el' can be
5857 downloaded from Piotr's site:
5858 `http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el'.
5860 `org-blog.el' by David O'Toole
5861 A blogging plug-in for `org-publish.el'.
5862 `http://dto.freeshell.org/notebook/OrgMode.html'.
5864 `blorg.el' by Bastien Guerry
5865 Publish Org-mode files as blogs.
5866 `http://www.cognition.ens.fr/~guerry/blorg.html'.
5868 `org2rem.el' by Bastien Guerry
5869 Translates Org-mode files into something readable by Remind.
5870 `http://www.cognition.ens.fr/~guerry/u/org2rem.el'.
5873 File: org, Node: Tables in arbitrary syntax, Next: Dynamic blocks, Prev: Extensions, Up: Extensions and Hacking
5875 A.2 Tables in arbitrary syntax
5876 ==============================
5878 Since Orgtbl-mode can be used as a minor mode in arbitrary buffers, a
5879 frequent feature request has been to make it work with native tables in
5880 specific languages, for example LaTeX. However, this is extremely hard
5881 to do in a general way, would lead to a customization nightmare, and
5882 would take away much of the simplicity of the Orgtbl-mode table editor.
5884 This appendix describes a different approach. We keep the
5885 Orgtbl-mode table in its native format (the source table), and use a
5886 custom function to translate the table to the correct syntax, and to
5887 install it in the right location (the target table). This puts the
5888 burden of writing conversion functions on the user, but it allows for a
5889 very flexible system.
5893 * Radio tables:: Sending and receiving
5894 * A LaTeX example:: Step by step, almost a tutorial
5895 * Translator functions:: Copy and modify
5898 File: org, Node: Radio tables, Next: A LaTeX example, Prev: Tables in arbitrary syntax, Up: Tables in arbitrary syntax
5903 To define the location of the target table, you first need to create two
5904 lines that are comments in the current mode, but contain magic words for
5905 Orgtbl-mode to find. Orgtbl-mode will insert the translated table
5906 between these lines, replacing whatever was there before. For example:
5908 /* BEGIN RECEIVE ORGTBL table_name */
5909 /* END RECEIVE ORGTBL table_name */
5911 Just above the source table, we put a special line that tells
5912 Orgtbl-mode how to translate this table and where to install it. For
5914 #+ORGTBL: SEND table_name translation_function arguments....
5916 `table_name' is the reference name for the table that is also used in
5917 the receiver lines. `translation_function' is the Lisp function that
5918 does the translation. Furthermore, the line can contain a list of
5919 arguments (alternating key and value) at the end. The arguments will be
5920 passed as a property list to the translation function for
5921 interpretation. A few standard parameters are already recognized and
5922 acted upon before the translation function is called:
5925 Skip the first N lines of the table. Hlines do count!
5927 `:skipcols (n1 n2 ...)'
5928 List of columns that should be skipped. If the table has a column
5929 with calculation marks, that column is automatically discarded as
5930 well. Please note that the translator function sees the table
5931 _after_ the removal of these columns, the function never knows
5932 that there have been additional columns.
5934 The one problem remaining is how to keep the source table in the buffer
5935 without disturbing the normal workings of the file, for example during
5936 compilation of a C file or processing of a LaTeX file. There are a
5937 number of different solutions:
5939 * The table could be placed in a block comment if that is supported
5940 by the language. For example, in C-mode you could wrap the table
5941 between `/*' and `*/' lines.
5943 * Sometimes it is possible to put the table after some kind of END
5944 statement, for example `\bye' in TeX and `\end{document}' in LaTeX.
5946 * You can just comment the table line by line whenever you want to
5947 process the file, and uncomment it whenever you need to edit the
5948 table. This only sounds tedious - the command `M-x
5949 orgtbl-toggle-comment' does make this comment-toggling very easy,
5950 in particular if you bind it to a key.
5953 File: org, Node: A LaTeX example, Next: Translator functions, Prev: Radio tables, Up: Tables in arbitrary syntax
5955 A.2.2 A LaTeX example
5956 ---------------------
5958 The best way to wrap the source table in LaTeX is to use the `comment'
5959 environment provided by `comment.sty'. It has to be activated by
5960 placing `\usepackage{comment}' into the document header. Orgtbl-mode
5961 can insert a radio table skeleton(1) with the command `M-x
5962 orgtbl-insert-radio-table'. You will be prompted for a table name,
5963 lets say we use `salesfigures'. You will then get the following
5966 % BEGIN RECEIVE ORGTBL salesfigures
5967 % END RECEIVE ORGTBL salesfigures
5969 #+ORGTBL: SEND salesfigures orgtbl-to-latex
5973 The `#+ORGTBL: SEND' line tells orgtbl-mode to use the function
5974 `orgtbl-to-latex' to convert the table into LaTeX and to put it into
5975 the receiver location with name `salesfigures'. You may now fill in
5976 the table, feel free to use the spreadsheet features(2):
5978 % BEGIN RECEIVE ORGTBL salesfigures
5979 % END RECEIVE ORGTBL salesfigures
5981 #+ORGTBL: SEND salesfigures orgtbl-to-latex
5982 | Month | Days | Nr sold | per day |
5983 |-------+------+---------+---------|
5984 | Jan | 23 | 55 | 2.4 |
5985 | Feb | 21 | 16 | 0.8 |
5986 | March | 22 | 278 | 12.6 |
5987 #+TBLFM: $4=$3/$2;%.1f
5988 % $ (optional extra dollar to keep font-lock happy, see footnote)
5991 When you are done, press `C-c C-c' in the table to get the converted
5992 table inserted between the two marker lines.
5994 Now lets assume you want to make the table header by hand, because
5995 you want to control how columns are aligned etc. In this case we make
5996 sure that the table translator does skip the first 2 lines of the source
5997 table, and tell the command to work as a splice, i.e. to not produce
5998 header and footer commands of the target table:
6000 \begin{tabular}{lrrr}
6001 Month & \multicolumn{1}{c}{Days} & Nr.\ sold & per day\\
6002 % BEGIN RECEIVE ORGTBL salesfigures
6003 % END RECEIVE ORGTBL salesfigures
6007 #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
6008 | Month | Days | Nr sold | per day |
6009 |-------+------+---------+---------|
6010 | Jan | 23 | 55 | 2.4 |
6011 | Feb | 21 | 16 | 0.8 |
6012 | March | 22 | 278 | 12.6 |
6013 #+TBLFM: $4=$3/$2;%.1f
6016 The LaTeX translator function `orgtbl-to-latex' is already part of
6017 Orgtbl-mode. It uses a `tabular' environment to typeset the table and
6018 marks horizontal lines with `\hline'. Furthermore, it interprets the
6019 following parameters:
6022 When set to t, return only table body lines, don't wrap them into a
6023 tabular environment. Default is nil.
6026 A format to be used to wrap each field, should contain `%s' for the
6027 original field value. For example, to wrap each field value in
6028 dollars, you could use `:fmt "$%s$"'. This may also be a property
6029 list with column numbers and formats. for example `:fmt (2 "$%s$"
6033 Use this format to print numbers with exponentials. The format
6034 should have `%s' twice for inserting mantissa and exponent, for
6035 example `"%s\\times10^{%s}"'. The default is `"%s\\,(%s)"'. This
6036 may also be a property list with column numbers and formats, for
6037 example `:efmt (2 "$%s\\times10^{%s}$" 4 "$%s\\cdot10^{%s}$")'.
6038 After `efmt' has been applied to a value, `fmt' will also be
6041 ---------- Footnotes ----------
6043 (1) By default this works only for LaTeX, HTML, and TeXInfo.
6044 Configure the variable `orgtbl-radio-tables' to install templates for
6047 (2) If the `#+TBLFM' line contains an odd number of dollar
6048 characters, this may cause problems with font-lock in latex-mode. As
6049 shown in the example you can fix this by adding an extra line inside the
6050 `comment' environment that is used to balance the dollar expressions.
6051 If you are using AUCTeX with the font-latex library, a much better
6052 solution is to add the `comment' environment to the variable
6053 `LaTeX-verbatim-environments'.
6056 File: org, Node: Translator functions, Prev: A LaTeX example, Up: Tables in arbitrary syntax
6058 A.2.3 Translator functions
6059 --------------------------
6061 Orgtbl-mode has several translator functions built-in:
6062 `orgtbl-to-latex', `orgtbl-to-html', and `orgtbl-to-texinfo'. Except
6063 for `orgtbl-to-html'(1), these all use a generic translator,
6064 `orgtbl-to-generic'. For example, `orgtbl-to-latex' itself is a very
6065 short function that computes the column definitions for the `tabular'
6066 environment, defines a few field and line separators and then hands
6067 over to the generic translator. Here is the entire code:
6069 (defun orgtbl-to-latex (table params)
6070 "Convert the orgtbl-mode TABLE to LaTeX."
6071 (let* ((alignment (mapconcat (lambda (x) (if x "r" "l"))
6072 org-table-last-alignment ""))
6075 :tstart (concat "\\begin{tabular}{" alignment "}")
6076 :tend "\\end{tabular}"
6077 :lstart "" :lend " \\\\" :sep " & "
6078 :efmt "%s\\,(%s)" :hline "\\hline")))
6079 (orgtbl-to-generic table (org-combine-plists params2 params))))
6081 As you can see, the properties passed into the function (variable
6082 PARAMS) are combined with the ones newly defined in the function
6083 (variable PARAMS2). The ones passed into the function (i.e. the ones
6084 set by the `ORGTBL SEND' line) take precedence. So if you would like
6085 to use the LaTeX translator, but wanted the line endings to be
6086 `\\[2mm]' instead of the default `\\', you could just overrule the
6089 #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
6091 For a new language, you can either write your own converter function
6092 in analogy with the LaTeX translator, or you can use the generic
6093 function directly. For example, if you have a language where a table
6094 is started with `!BTBL!', ended with `!ETBL!', and where table lines are
6095 started with `!BL!', ended with `!EL!' and where the field separator is
6096 a TAB, you could call the generic translator like this (on a single
6099 #+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!"
6100 :lstart "!BL! " :lend " !EL!" :sep "\t"
6102 Please check the documentation string of the function
6103 `orgtbl-to-generic' for a full list of parameters understood by that
6104 function and remember that you can pass each of them into
6105 `orgtbl-to-latex', `orgtbl-to-texinfo', and any other function using
6106 the generic function.
6108 Of course you can also write a completely new function doing
6109 complicated things the generic translator cannot do. A translator
6110 function takes two arguments. The first argument is the table, a list
6111 of lines, each line either the symbol `hline' or a list of fields. The
6112 second argument is the property list containing all parameters
6113 specified in the `#+ORGTBL: SEND' line. The function must return a
6114 single string containing the formatted table. If you write a generally
6115 useful translator, please post it on `emacs-orgmode@gnu.org' so that
6116 others can benefit from your work.
6118 ---------- Footnotes ----------
6120 (1) The HTML translator uses the same code that produces tables
6124 File: org, Node: Dynamic blocks, Next: Special agenda views, Prev: Tables in arbitrary syntax, Up: Extensions and Hacking
6129 Org-mode documents can contain _dynamic blocks_. These are specially
6130 marked regions that are updated by some user-written function. A good
6131 example for such a block is the clock table inserted by the command
6132 `C-c C-x C-r' (*note Clocking work time::).
6134 Dynamic block are enclosed by a BEGIN-END structure that assigns a
6135 name to the block and can also specify parameters for the function
6136 producing the content of the block.
6138 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
6142 Dynamic blocks are updated with the following commands
6145 Update dynamic block at point.
6148 Update all dynamic blocks in the current file.
6150 Updating a dynamic block means to remove all the text between BEGIN
6151 and END, parse the BEGIN line for parameters and then call the specific
6152 writer function for this block to insert the new content. For a block
6153 with name `myblock', the writer function is `org-dblock-write:myblock'
6154 with as only parameter a property list with the parameters given in the
6155 begin line. Here is a trivial example of a block that keeps track of
6156 when the block update function was last run:
6158 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
6162 The corresponding block writer function could look like this:
6164 (defun org-dblock-write:block-update-time (params)
6165 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
6166 (insert "Last block update at: "
6167 (format-time-string fmt (current-time)))))
6169 If you want to make sure that all dynamic blocks are always
6170 up-to-date, you could add the function `org-update-all-dblocks' to a
6171 hook, for example `before-save-hook'. `org-update-all-dblocks' is
6172 written in a way that is does nothing in buffers that are not in
6176 File: org, Node: Special agenda views, Prev: Dynamic blocks, Up: Extensions and Hacking
6178 A.4 Special Agenda Views
6179 ========================
6181 Org-mode provides a special hook that can be used to narrow down the
6182 selection made by any of the agenda views. You may specify a function
6183 that is used at each match to verify if the match should indeed be part
6184 of the agenda view, and if not, how much should be skipped.
6186 Let's say you want to produce a list of projects that contain a
6187 WAITING tag anywhere in the project tree. Let's further assume that
6188 you have marked all tree headings that define a project with the todo
6189 keyword PROJECT. In this case you would run a todo search for the
6190 keyword PROJECT, but skip the match unless there is a WAITING tag
6191 anywhere in the subtree belonging to the project line.
6193 To achieve this, you must write a function that searches the subtree
6194 for the tag. If the tag is found, the function must return `nil' to
6195 indicate that this match should not be skipped. If there is no such
6196 tag, return the location of the end of the subtree, to indicate that
6197 search should continue from there.
6199 (defun my-skip-unless-waiting ()
6200 "Skip trees that are not waiting"
6201 (let ((subtree-end (save-excursion (org-end-of-subtree t))))
6202 (if (re-search-forward ":WAITING:" subtree-end t)
6203 nil ; tag found, do not skip
6204 subtree-end))) ; tag not found, continue after end of subtree
6206 Furthermore you must write a command that uses `let' to temporarily
6207 put this function into the variable `org-agenda-skip-function', sets
6208 the header string for the agenda buffer, and calls the todo-list
6209 generator while asking for the specific TODO keyword PROJECT. The
6210 function must also accept one argument MATCH, but it can choose to
6211 ignore it(1) (as we do in the example below). Here is the example:
6213 (defun my-org-waiting-projects (&optional match)
6214 "Produce a list of projects that contain a WAITING tag.
6215 MATCH is being ignored."
6217 (let ((org-agenda-skip-function 'my-skip-unless-waiting)
6218 (org-agenda-overriding-header "Projects waiting for something: "))
6220 (org-todo-list "PROJECT")))
6222 ---------- Footnotes ----------
6224 (1) MATCH must be present in case you want to define a custom
6225 command for producing this special list. Custom commands always supply
6226 the MATCH argument, but it can be empty if you do not specify it while
6227 defining the command(*note Custom agenda views::).
6230 File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top
6232 Appendix B History and Acknowledgments
6233 **************************************
6235 Org-mode was borne in 2003, out of frustration over the user interface
6236 of the Emacs outline-mode. I was trying to organize my notes and
6237 projects, and using Emacs seemed to be the natural way to go. However,
6238 having to remember eleven different commands with two or three keys per
6239 command, only to hide and unhide parts of the outline tree, that seemed
6240 entirely unacceptable to me. Also, when using outlines to take notes, I
6241 constantly want to restructure the tree, organizing it parallel to my
6242 thoughts and plans. _Visibility cycling_ and _structure editing_ were
6243 originally implemented in the package `outline-magic.el', but quickly
6244 moved to the more general `org.el'. As this environment became
6245 comfortable for project planning, the next step was adding _TODO
6246 entries_, basic _time stamps_, and _table support_. These areas
6247 highlight the two main goals that Org-mode still has today: To create a
6248 new, outline-based, plain text mode with innovative and intuitive
6249 editing features, and to incorporate project planning functionality
6250 directly into a notes file.
6252 Since the first release, hundreds of emails to me or on
6253 `emacs-orgmode@gnu.org' have provided a constant stream of bug reports,
6254 feedback, new ideas, and sometimes patches and add-on code. Many
6255 thanks to everyone who has helped to improve this package. I am trying
6256 to keep here a list of the people who had significant influence in
6257 shaping one or more aspects of Org-mode. The list may not be complete,
6258 if I have forgotten someone, please accept my apologies and let me know.
6260 * Thomas Baumann contributed the code for links to the MH-E email
6263 * Alex Bochannek provided a patch for rounding time stamps.
6265 * Charles Cave's suggestion sparked the implementation of templates
6268 * Pavel Chalmoviansky influenced the agenda treatment of items with
6271 * Gregory Chernov patched support for lisp forms into table
6272 calculations and improved XEmacs compatibility, in particular by
6273 porting `nouline.el' to XEmacs.
6275 * Sacha Chua suggested to copy some linking code from Planner.
6277 * Eddward DeVilla proposed and tested checkbox statistics.
6279 * Kees Dullemond used to edit projects lists directly in HTML and so
6280 inspired some of the early development, including HTML export. He
6281 also asked for a way to narrow wide table columns.
6283 * Christian Egli converted the documentation into TeXInfo format,
6284 patched CSS formatting into the HTML exporter, and inspired the
6287 * Nic Ferrier contributed mailcap and XOXO support.
6289 * John Foerch figured out how to make incremental search show context
6290 around a match in a hidden outline tree.
6292 * Niels Giessen had the idea to automatically archive DONE trees.
6294 * Bastien Guerry provided extensive feedback and some patches, and
6295 translated David O'Toole's tutorial into French.
6297 * Kai Grossjohann pointed out key-binding conflicts with other
6300 * Shidai Liu ("Leo") asked for embedded LaTeX and tested it. He also
6301 provided frequent feedback and some patches.
6303 * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler
6306 * Rick Moynihan proposed to allow multiple TODO sequences in a file.
6308 * Todd Neal provided patches for links to Info files and elisp forms.
6310 * Tim O'Callaghan suggested in-file links, search options for general
6311 file links, and TAGS.
6313 * Takeshi Okano translated the manual and David O'Toole's tutorial
6316 * Oliver Oppitz suggested multi-state TODO items.
6318 * Scott Otterson sparked the introduction of descriptive text for
6319 links, among other things.
6321 * Pete Phillips helped during the development of the TAGS feature,
6322 and provided frequent feedback.
6324 * T.V. Raman reported bugs and suggested improvements.
6326 * Matthias Rempe (Oelde) provided ideas, Windows support, and quality
6329 * Kevin Rogers contributed code to access VM files on remote hosts.
6331 * Frank Ruell solved the mystery of the `keymapp nil' bug, a
6332 conflict with `allout.el'.
6334 * Jason Riedy sent a patch to fix a bug with export of TODO keywords.
6336 * Philip Rooke created the Org-mode reference card and provided lots
6339 * Christian Schlauer proposed angular brackets around links, among
6342 * Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
6343 `organizer-mode.el'.
6345 * Daniel Sinder came up with the idea of internal archiving by
6348 * Dale Smith proposed link abbreviations.
6350 * David O'Toole wrote `org-publish.el' and drafted the manual
6351 chapter about publishing.
6353 * Ju"rgen Vollmer contributed code generating the table of contents
6356 * Chris Wallace provided a patch implementing the `QUOTE' keyword.
6358 * David Wainberg suggested archiving, and improvements to the linking
6361 * John Wiegley wrote `emacs-wiki.el' and `planner.el'. The
6362 development of Org-mode was fully independent, and both systems are
6363 really different beasts in their basic ideas and implementation
6364 details. I later looked at John's code, however, and learned from
6365 his implementation of (i) links where the link itself is hidden
6366 and only a description is shown, and (ii) popping up a calendar to
6369 * Carsten Wimmer suggested some changes and helped fix a bug in
6372 * Roland Winkler requested additional keybindings to make Org-mode
6375 * Piotr Zielinski wrote `org-mouse.el', proposed agenda blocks and
6376 contributed various ideas and code snippets.
6379 File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top
6387 * abbreviation, links: Link abbreviations. (line 6)
6388 * acknowledgments: History and Acknowledgments.
6390 * action, for publishing: Publishing action. (line 6)
6391 * activation: Activation. (line 6)
6392 * active region <1>: Export commands. (line 6)
6393 * active region <2>: ASCII export. (line 9)
6394 * active region <3>: Built-in table editor.
6396 * active region: Structure editing. (line 64)
6397 * agenda: Weekly/Daily agenda. (line 6)
6398 * agenda dispatcher: Agenda dispatcher. (line 6)
6399 * agenda files: Agenda files. (line 6)
6400 * agenda files, removing buffers: Agenda commands. (line 239)
6401 * agenda views: Agenda views. (line 6)
6402 * agenda views, custom: Custom agenda views. (line 6)
6403 * agenda views, exporting <1>: Exporting Agenda Views.
6405 * agenda views, exporting: Agenda commands. (line 228)
6406 * agenda views, user-defined: Special agenda views.
6408 * agenda, pipe: Extracting Agenda Information for other programs.
6410 * agenda, with block views: Block agenda. (line 6)
6411 * align, STARTUP keyword: In-buffer settings. (line 29)
6412 * allout.el: Conflicts. (line 6)
6413 * angular brackets, around links: External links. (line 43)
6414 * archive locations: Moving subtrees. (line 21)
6415 * archiving: Archiving. (line 6)
6416 * ASCII export: ASCII export. (line 6)
6417 * author: Feedback. (line 6)
6418 * autoload: Activation. (line 6)
6419 * backtrace of an error: Feedback. (line 27)
6420 * BBDB links: External links. (line 6)
6421 * block agenda: Block agenda. (line 6)
6422 * blorg.el: Extensions. (line 32)
6423 * bold text: Enhancing text. (line 15)
6424 * Boolean logic, for tag searches: Tag searches. (line 23)
6425 * bug reports: Feedback. (line 6)
6426 * bugs: Bugs. (line 6)
6427 * C-c C-c, overview: The very busy C-c C-c key.
6429 * calc package: The spreadsheet. (line 6)
6430 * calc.el: Cooperation. (line 6)
6431 * calculations, in tables <1>: The spreadsheet. (line 6)
6432 * calculations, in tables: Built-in table editor.
6434 * calendar commands, from agenda: Agenda commands. (line 191)
6435 * calendar integration: Weekly/Daily agenda. (line 24)
6436 * calendar, for selecting date: The date/time prompt.
6438 * category: Categories. (line 6)
6439 * CDLaTeX: CDLaTeX mode. (line 6)
6440 * cdlatex.el: Cooperation. (line 29)
6441 * checkbox statistics: Checkboxes. (line 23)
6442 * checkboxes: Checkboxes. (line 6)
6443 * children, subtree visibility state: Visibility cycling. (line 10)
6444 * clean outline view: Clean view. (line 6)
6445 * CLOCK keyword: Time stamps. (line 71)
6446 * CLOSED keyword: Time stamps. (line 65)
6447 * column formula: Column formulas. (line 6)
6448 * commands, in agenda buffer: Agenda commands. (line 6)
6449 * comment lines: Comment lines. (line 6)
6450 * completion, of dictionary words: Completion. (line 6)
6451 * completion, of file names: Handling links. (line 41)
6452 * completion, of link abbreviations: Completion. (line 6)
6453 * completion, of links: Handling links. (line 25)
6454 * completion, of option keywords <1>: Completion. (line 6)
6455 * completion, of option keywords <2>: Export options. (line 6)
6456 * completion, of option keywords: Per file keywords. (line 23)
6457 * completion, of tags <1>: Completion. (line 6)
6458 * completion, of tags: Setting tags. (line 11)
6459 * completion, of TeX symbols: Completion. (line 6)
6460 * completion, of TODO keywords <1>: Completion. (line 6)
6461 * completion, of TODO keywords: Workflow states. (line 15)
6462 * constants, in calculations: References. (line 82)
6463 * constants.el: Cooperation. (line 14)
6464 * constcgs, STARTUP keyword: In-buffer settings. (line 54)
6465 * constSI, STARTUP keyword: In-buffer settings. (line 54)
6466 * content, STARTUP keyword: In-buffer settings. (line 22)
6467 * contents, global visibility state: Visibility cycling. (line 22)
6468 * copying, of subtrees: Structure editing. (line 6)
6469 * creating timestamps: Creating timestamps. (line 6)
6470 * CUA.el: Conflicts. (line 15)
6471 * custom agenda views: Custom agenda views. (line 6)
6472 * custom date/time format: Custom time format. (line 6)
6473 * custom search strings: Custom searches. (line 6)
6474 * customization: Customization. (line 6)
6475 * customtime, STARTUP keyword: In-buffer settings. (line 51)
6476 * cutting, of subtrees: Structure editing. (line 6)
6477 * cycling, of TODO states: TODO basics. (line 13)
6478 * cycling, visibility: Visibility cycling. (line 6)
6479 * daily agenda: Weekly/Daily agenda. (line 6)
6480 * date format, custom: Custom time format. (line 6)
6481 * date stamps <1>: Time stamps. (line 6)
6482 * date stamps: Timestamps. (line 6)
6483 * date, reading in minibuffer: The date/time prompt.
6485 * DEADLINE keyword: Time stamps. (line 53)
6486 * deadlines: Time stamps. (line 6)
6487 * deadlines, repeating: Repeating items. (line 6)
6488 * debugging, of table formulas: Editing and debugging formulas.
6490 * demotion, of subtrees: Structure editing. (line 6)
6491 * diary entries, creating from agenda: Agenda commands. (line 196)
6492 * diary integration: Weekly/Daily agenda. (line 24)
6493 * dictionary word completion: Completion. (line 6)
6494 * directories, for publishing: Sources and destinations.
6496 * dispatching agenda commands: Agenda dispatcher. (line 6)
6497 * display changing, in agenda: Agenda commands. (line 65)
6498 * document structure: Document structure. (line 6)
6499 * DONE, final TODO keyword: Per file keywords. (line 26)
6500 * dynamic blocks: Dynamic blocks. (line 6)
6501 * editing tables: Tables. (line 6)
6502 * editing, of table formulas: Editing and debugging formulas.
6504 * elisp links: External links. (line 6)
6505 * emphasized text: Export options. (line 25)
6506 * enhancing text: Enhancing text. (line 6)
6507 * evaluate time range: Creating timestamps. (line 64)
6508 * even, STARTUP keyword: In-buffer settings. (line 44)
6509 * exporting: Exporting. (line 6)
6510 * exporting agenda views <1>: Exporting Agenda Views.
6512 * exporting agenda views: Agenda commands. (line 228)
6513 * exporting, not: Comment lines. (line 6)
6514 * extended TODO keywords: TODO extensions. (line 6)
6515 * extension, third-party: Extensions. (line 6)
6516 * external archiving: Moving subtrees. (line 6)
6517 * external links: External links. (line 6)
6518 * external links, in HTML export: Links. (line 6)
6519 * FAQ: Summary. (line 53)
6520 * feedback: Feedback. (line 6)
6521 * field formula: Field formulas. (line 6)
6522 * field references: References. (line 15)
6523 * file links: External links. (line 6)
6524 * file links, searching: Search options. (line 6)
6525 * file name completion: Handling links. (line 41)
6526 * files for agenda: Agenda files. (line 6)
6527 * files, adding to agenda list: Agenda files. (line 12)
6528 * files, selecting for publishing: Selecting files. (line 6)
6529 * fixed width: Enhancing text. (line 28)
6530 * fixed-width sections: Export options. (line 25)
6531 * folded, subtree visibility state: Visibility cycling. (line 10)
6532 * folding, sparse trees: Sparse trees. (line 6)
6533 * following links: Handling links. (line 56)
6534 * format specifier: Formula syntax for Calc.
6536 * format, of links: Link format. (line 6)
6537 * formula debugging: Editing and debugging formulas.
6539 * formula editing: Editing and debugging formulas.
6541 * formula syntax, Calc: Formula syntax for Calc.
6543 * formula, for individual table field: Field formulas. (line 6)
6544 * formula, for table column: Column formulas. (line 6)
6545 * formula, in tables: Built-in table editor.
6547 * global cycling: Visibility cycling. (line 22)
6548 * global keybindings: Activation. (line 6)
6549 * global TODO list: Global TODO list. (line 6)
6550 * global visibility states: Visibility cycling. (line 22)
6551 * GNUS links: External links. (line 6)
6552 * hand-formatted lists: Enhancing text. (line 11)
6553 * headline levels: Export options. (line 25)
6554 * headline levels, for exporting <1>: Export commands. (line 22)
6555 * headline levels, for exporting: ASCII export. (line 18)
6556 * headline navigation: Motion. (line 6)
6557 * headline tagging: Tags. (line 6)
6558 * headline, promotion and demotion: Structure editing. (line 6)
6559 * headlines: Headlines. (line 6)
6560 * hide text: Visibility cycling. (line 6)
6561 * hidestars, STARTUP keyword: In-buffer settings. (line 44)
6562 * hiding leading stars: Clean view. (line 6)
6563 * history: History and Acknowledgments.
6565 * horizontal rules, in exported files: Enhancing text. (line 18)
6566 * HTML export: HTML export. (line 6)
6567 * HTML, and orgtbl-mode: Translator functions.
6569 * hyperlinks: Hyperlinks. (line 6)
6570 * iCalendar export: iCalendar export. (line 6)
6571 * images, inline in HTML: Images. (line 6)
6572 * in-buffer settings: In-buffer settings. (line 6)
6573 * inactive timestamp: Time stamps. (line 24)
6574 * index, of published pages: Project page index. (line 6)
6575 * Info links: External links. (line 6)
6576 * inheritance, of tags: Tag inheritance. (line 6)
6577 * inlining images in HTML: Images. (line 6)
6578 * inserting links: Handling links. (line 25)
6579 * installation: Installation. (line 6)
6580 * internal archiving: ARCHIVE tag. (line 6)
6581 * internal links: Internal links. (line 6)
6582 * internal links, in HTML export: Links. (line 6)
6583 * introduction: Introduction. (line 6)
6584 * italic text: Enhancing text. (line 15)
6585 * jumping, to headlines: Motion. (line 6)
6586 * keybindings, global: Activation. (line 6)
6587 * keyword options: Per file keywords. (line 6)
6588 * LaTeX fragments <1>: Export options. (line 25)
6589 * LaTeX fragments: LaTeX fragments. (line 6)
6590 * LaTeX fragments, export: Enhancing text. (line 21)
6591 * LaTeX fragments, preview: Processing LaTeX fragments.
6593 * LaTeX interpretation: Embedded LaTeX. (line 6)
6594 * LaTeX, and orgtbl-mode: A LaTeX example. (line 6)
6595 * level, require for tags match: Tag searches. (line 68)
6596 * linebreak preservation: Export options. (line 25)
6597 * linebreak, forced: Enhancing text. (line 35)
6598 * link abbreviations: Link abbreviations. (line 6)
6599 * link abbreviations, completion of: Completion. (line 6)
6600 * link completion: Handling links. (line 25)
6601 * link format: Link format. (line 6)
6602 * links, external: External links. (line 6)
6603 * links, finding next/previous: Handling links. (line 89)
6604 * links, handling: Handling links. (line 6)
6605 * links, in HTML export: Links. (line 6)
6606 * links, internal: Internal links. (line 6)
6607 * links, publishing: Publishing links. (line 6)
6608 * links, radio targets: Radio targets. (line 6)
6609 * links, returning to: Handling links. (line 83)
6610 * Lisp forms, as table formulas: Formula syntax for Lisp.
6612 * lists, hand-formatted: Enhancing text. (line 11)
6613 * lists, ordered: Plain lists. (line 6)
6614 * lists, plain: Plain lists. (line 6)
6615 * logdone, STARTUP keyword: In-buffer settings. (line 33)
6616 * logging, of progress: Progress logging. (line 6)
6617 * lognoteclock-out, STARTUP keyword: In-buffer settings. (line 33)
6618 * lognotedone, STARTUP keyword: In-buffer settings. (line 33)
6619 * lognotestate, STARTUP keyword: In-buffer settings. (line 33)
6620 * logrepeat, STARTUP keyword: In-buffer settings. (line 33)
6621 * maintainer: Feedback. (line 6)
6622 * mark ring: Handling links. (line 79)
6623 * marking characters, tables: Advanced features. (line 40)
6624 * matching, of tags: Matching headline tags.
6626 * matching, tags: Tags. (line 6)
6627 * math symbols: Math symbols. (line 6)
6628 * MH-E links: External links. (line 6)
6629 * minor mode for tables: orgtbl-mode. (line 6)
6630 * mode, for calc: Formula syntax for Calc.
6632 * motion commands in agenda: Agenda commands. (line 19)
6633 * motion, between headlines: Motion. (line 6)
6634 * name, of column or field: References. (line 82)
6635 * named references: References. (line 82)
6636 * names as TODO keywords: TODO types. (line 6)
6637 * narrow columns in tables: Narrow columns. (line 6)
6638 * noalign, STARTUP keyword: In-buffer settings. (line 29)
6639 * nologging, STARTUP keyword: In-buffer settings. (line 33)
6640 * nologrepeat, STARTUP keyword: In-buffer settings. (line 33)
6641 * occur, command: Sparse trees. (line 6)
6642 * odd, STARTUP keyword: In-buffer settings. (line 44)
6643 * option keyword completion: Completion. (line 6)
6644 * options, for custom agenda views: Setting Options. (line 6)
6645 * options, for customization: Customization. (line 6)
6646 * options, for export: Export options. (line 6)
6647 * options, for publishing: Publishing options. (line 6)
6648 * ordered lists: Plain lists. (line 6)
6649 * org-agenda, command: Weekly/Daily agenda. (line 9)
6650 * org-blog.el: Extensions. (line 28)
6651 * org-mode, turning on: Activation. (line 22)
6652 * org-mouse.el: Extensions. (line 16)
6653 * org-publish-project-alist: Project alist. (line 6)
6654 * org-publish.el: Extensions. (line 8)
6655 * org2rem.el: Extensions. (line 36)
6656 * orgtbl-mode <1>: Tables in arbitrary syntax.
6658 * orgtbl-mode: orgtbl-mode. (line 6)
6659 * outline tree: Headlines. (line 6)
6660 * outline-mode: Outlines. (line 6)
6661 * outlines: Outlines. (line 6)
6662 * overview, global visibility state: Visibility cycling. (line 22)
6663 * overview, STARTUP keyword: In-buffer settings. (line 22)
6664 * packages, interaction with other: Interaction. (line 6)
6665 * pasting, of subtrees: Structure editing. (line 6)
6666 * per file keywords: Per file keywords. (line 6)
6667 * plain lists: Plain lists. (line 6)
6668 * plain text external links: External links. (line 43)
6669 * presentation, of agenda items: Presentation and sorting.
6671 * printing sparse trees: Sparse trees. (line 41)
6672 * priorities: Priorities. (line 6)
6673 * priorities, of agenda items: Sorting of agenda items.
6675 * progress logging: Progress logging. (line 6)
6676 * projects, for publishing: Project alist. (line 6)
6677 * promotion, of subtrees: Structure editing. (line 6)
6678 * publishing: Publishing. (line 6)
6679 * quoted HTML tags: Export options. (line 25)
6680 * radio tables: Radio tables. (line 6)
6681 * radio targets: Radio targets. (line 6)
6682 * range references: References. (line 60)
6683 * ranges, time: Time stamps. (line 6)
6684 * recomputing table fields: Updating the table. (line 6)
6685 * references: References. (line 6)
6686 * references, named: References. (line 82)
6687 * references, to fields: References. (line 15)
6688 * references, to ranges: References. (line 60)
6689 * region, active <1>: Export commands. (line 6)
6690 * region, active <2>: ASCII export. (line 9)
6691 * region, active <3>: Built-in table editor.
6693 * region, active: Structure editing. (line 64)
6694 * regular expressions, with tags search: Tag searches. (line 63)
6695 * remember.el <1>: Cooperation. (line 33)
6696 * remember.el: Remember. (line 6)
6697 * remote editing, from agenda: Agenda commands. (line 106)
6698 * remote editing, undo: Agenda commands. (line 107)
6699 * richer text: Enhancing text. (line 6)
6700 * RMAIL links: External links. (line 6)
6701 * SCHEDULED keyword: Time stamps. (line 40)
6702 * scheduling: Time stamps. (line 6)
6703 * scheduling, repeating: Repeating items. (line 6)
6704 * Scripts, for agenda processing: Extracting Agenda Information for other programs.
6706 * search option in file links: Search options. (line 6)
6707 * search strings, custom: Custom searches. (line 6)
6708 * searching for tags: Tag searches. (line 6)
6709 * section-numbers: Export options. (line 25)
6710 * setting tags: Setting tags. (line 6)
6711 * SHELL links: External links. (line 6)
6712 * show all, command: Visibility cycling. (line 33)
6713 * show all, global visibility state: Visibility cycling. (line 22)
6714 * show hidden text: Visibility cycling. (line 6)
6715 * showall, STARTUP keyword: In-buffer settings. (line 22)
6716 * showstars, STARTUP keyword: In-buffer settings. (line 44)
6717 * sorting, of agenda items: Sorting of agenda items.
6719 * sparse tree, for deadlines: Creating timestamps. (line 39)
6720 * sparse tree, for TODO: TODO basics. (line 26)
6721 * sparse tree, tag based: Tags. (line 6)
6722 * sparse trees: Sparse trees. (line 6)
6723 * special keywords: In-buffer settings. (line 6)
6724 * spreadsheet capabilities: The spreadsheet. (line 6)
6725 * statistics, for checkboxes: Checkboxes. (line 23)
6726 * storing links: Handling links. (line 9)
6727 * structure editing: Structure editing. (line 6)
6728 * structure of document: Document structure. (line 6)
6729 * sublevels, inclusion into tags match: Tag inheritance. (line 6)
6730 * sublevels, inclusion into todo list: Global TODO list. (line 34)
6731 * subscript: Subscripts and Superscripts.
6733 * subtree cycling: Visibility cycling. (line 10)
6734 * subtree visibility states: Visibility cycling. (line 10)
6735 * subtree, cut and paste: Structure editing. (line 6)
6736 * subtree, subtree visibility state: Visibility cycling. (line 10)
6737 * subtrees, cut and paste: Structure editing. (line 6)
6738 * summary: Summary. (line 6)
6739 * superscript: Subscripts and Superscripts.
6741 * syntax, of formulas: Formula syntax for Calc.
6743 * table editor, built-in: Built-in table editor.
6745 * table editor, table.el: Cooperation. (line 37)
6746 * table of contents: Export options. (line 25)
6747 * table.el: Cooperation. (line 34)
6748 * tables <1>: Export options. (line 25)
6749 * tables: Tables. (line 6)
6750 * tables, export: Enhancing text. (line 24)
6751 * tables, in other modes: Tables in arbitrary syntax.
6753 * tag completion: Completion. (line 6)
6754 * tag searches: Tag searches. (line 6)
6755 * tags: Tags. (line 6)
6756 * tags view: Matching headline tags.
6758 * tags, setting: Setting tags. (line 6)
6759 * targets, for links: Internal links. (line 6)
6760 * targets, radio: Radio targets. (line 6)
6761 * tasks, breaking down: Breaking down tasks. (line 6)
6762 * templates, for remember: Remember templates. (line 6)
6763 * TeX interpretation: Embedded LaTeX. (line 6)
6764 * TeX macros <1>: Export options. (line 25)
6765 * TeX macros: Math symbols. (line 6)
6766 * TeX macros, export: Enhancing text. (line 21)
6767 * TeX symbol completion: Completion. (line 6)
6768 * TeX-like syntax for sub- and superscripts: Export options. (line 25)
6769 * thanks: History and Acknowledgments.
6771 * time format, custom: Custom time format. (line 6)
6772 * time grid: Time-of-day specifications.
6774 * time stamps <1>: Time stamps. (line 6)
6775 * time stamps: Timestamps. (line 6)
6776 * time, reading in minibuffer: The date/time prompt.
6778 * time-of-day specification: Time-of-day specifications.
6780 * time-sorted view: Timeline. (line 6)
6781 * timeline, single file: Timeline. (line 6)
6782 * timerange: Time stamps. (line 31)
6783 * timestamp: Time stamps. (line 14)
6784 * timestamp, inactive: Time stamps. (line 24)
6785 * timestamps, creating: Creating timestamps. (line 6)
6786 * TODO items: TODO items. (line 6)
6787 * TODO items, repeating: Repeating items. (line 6)
6788 * TODO keyword matching: Global TODO list. (line 17)
6789 * TODO keyword matching, with tags search: Tag searches. (line 40)
6790 * todo keyword sets: Multiple sets in one file.
6792 * TODO keywords completion: Completion. (line 6)
6793 * TODO list, global: Global TODO list. (line 6)
6794 * TODO types: TODO types. (line 6)
6795 * TODO workflow: Workflow states. (line 6)
6796 * transient-mark-mode <1>: Export commands. (line 6)
6797 * transient-mark-mode <2>: ASCII export. (line 9)
6798 * transient-mark-mode <3>: Built-in table editor.
6800 * transient-mark-mode: Structure editing. (line 64)
6801 * translator function: Translator functions.
6803 * trees, sparse: Sparse trees. (line 6)
6804 * trees, visibility: Visibility cycling. (line 6)
6805 * tty keybindings: TTY keys. (line 6)
6806 * types as TODO keywords: TODO types. (line 6)
6807 * underlined text: Enhancing text. (line 15)
6808 * undoing remote-editing events: Agenda commands. (line 107)
6809 * updating, table: Updating the table. (line 6)
6810 * URL links: External links. (line 6)
6811 * USENET links: External links. (line 6)
6812 * variables, for customization: Customization. (line 6)
6813 * vectors, in table calculations: Formula syntax for Calc.
6815 * visibility cycling: Visibility cycling. (line 6)
6816 * visible text, printing: Sparse trees. (line 41)
6817 * VM links: External links. (line 6)
6818 * WANDERLUST links: External links. (line 6)
6819 * weekly agenda: Weekly/Daily agenda. (line 6)
6820 * windmove.el: Conflicts. (line 32)
6821 * workflow states as TODO keywords: Workflow states. (line 6)
6822 * XEmacs: Installation. (line 6)
6823 * XOXO export: XOXO export. (line 6)
6826 File: org, Node: Key Index, Prev: Index, Up: Top
6834 * $: Agenda commands. (line 121)
6835 * ': CDLaTeX mode. (line 43)
6836 * +: Agenda commands. (line 143)
6837 * ,: Agenda commands. (line 135)
6838 * -: Agenda commands. (line 149)
6839 * .: Agenda commands. (line 98)
6840 * :: Agenda commands. (line 129)
6841 * <: The date/time prompt.
6843 * <left>: Agenda commands. (line 95)
6844 * <RET> <1>: Agenda commands. (line 39)
6845 * <RET> <2>: Setting tags. (line 76)
6846 * <RET> <3>: The date/time prompt.
6848 * <RET>: Built-in table editor.
6850 * <right>: Agenda commands. (line 90)
6851 * <SPC> <1>: Agenda commands. (line 28)
6852 * <SPC>: Setting tags. (line 73)
6853 * <TAB> <1>: CDLaTeX mode. (line 23)
6854 * <TAB> <2>: Agenda commands. (line 33)
6855 * <TAB> <3>: Setting tags. (line 68)
6856 * <TAB> <4>: Editing and debugging formulas.
6858 * <TAB> <5>: Built-in table editor.
6860 * <TAB> <6>: Plain lists. (line 41)
6861 * <TAB>: Visibility cycling. (line 10)
6862 * > <1>: Agenda commands. (line 171)
6863 * >: The date/time prompt.
6865 * ^: CDLaTeX mode. (line 33)
6866 * _: CDLaTeX mode. (line 33)
6867 * `: CDLaTeX mode. (line 39)
6868 * a: Agenda commands. (line 132)
6869 * b: Agenda commands. (line 49)
6870 * C: Agenda commands. (line 211)
6871 * c: Agenda commands. (line 191)
6872 * C-#: Advanced features. (line 9)
6873 * C-': Agenda files. (line 18)
6874 * C-,: Agenda files. (line 18)
6875 * C-_: Agenda commands. (line 107)
6876 * C-a a L: Timeline. (line 10)
6877 * C-c !: Creating timestamps. (line 19)
6878 * C-c #: Checkboxes. (line 56)
6879 * C-c %: Handling links. (line 79)
6880 * C-c &: Handling links. (line 83)
6881 * C-c ': Editing and debugging formulas.
6883 * C-c *: Updating the table. (line 13)
6884 * C-c +: Built-in table editor.
6886 * C-c ,: Priorities. (line 18)
6887 * C-c -: Built-in table editor.
6889 * C-c .: Creating timestamps. (line 10)
6890 * C-c /: Sparse trees. (line 15)
6891 * C-c :: Enhancing text. (line 32)
6892 * C-c ;: Comment lines. (line 10)
6893 * C-c <: Creating timestamps. (line 23)
6894 * C-c <TAB>: Built-in table editor.
6896 * C-c = <1>: Editing and debugging formulas.
6898 * C-c =: Column formulas. (line 26)
6899 * C-c >: Creating timestamps. (line 27)
6900 * C-c ?: Editing and debugging formulas.
6902 * C-c [: Agenda files. (line 12)
6903 * C-c \: Tag searches. (line 9)
6904 * C-c ]: Agenda files. (line 15)
6905 * C-c ^ <1>: Built-in table editor.
6907 * C-c ^: Structure editing. (line 52)
6908 * C-c `: Built-in table editor.
6910 * C-c a !: Stuck projects. (line 14)
6911 * C-c a #: Stuck projects. (line 13)
6912 * C-c a a: Weekly/Daily agenda. (line 9)
6913 * C-c a C: Storing searches. (line 9)
6914 * C-c a e: Exporting Agenda Views.
6916 * C-c a M: Matching headline tags.
6918 * C-c a m: Matching headline tags.
6920 * C-c a M: Tag searches. (line 16)
6921 * C-c a m: Tag searches. (line 12)
6922 * C-c a T: Global TODO list. (line 14)
6923 * C-c a t <1>: Global TODO list. (line 9)
6924 * C-c a t: TODO basics. (line 36)
6925 * C-c C-a: Visibility cycling. (line 33)
6926 * C-c C-b: Motion. (line 15)
6927 * C-c C-c <1>: Cooperation. (line 37)
6928 * C-c C-c <2>: The very busy C-c C-c key.
6930 * C-c C-c <3>: Processing LaTeX fragments.
6932 * C-c C-c <4>: Setting tags. (line 10)
6933 * C-c C-c <5>: Checkboxes. (line 37)
6934 * C-c C-c <6>: Editing and debugging formulas.
6936 * C-c C-c <7>: Built-in table editor.
6938 * C-c C-c: Plain lists. (line 78)
6939 * C-c C-d <1>: Agenda commands. (line 156)
6940 * C-c C-d: Creating timestamps. (line 35)
6941 * C-c C-e: Exporting. (line 19)
6942 * C-c C-e a: ASCII export. (line 9)
6943 * C-c C-e b: Export commands. (line 7)
6944 * C-c C-e c: iCalendar export. (line 21)
6945 * C-c C-e H: Export commands. (line 10)
6946 * C-c C-e h: Export commands. (line 6)
6947 * C-c C-e I: iCalendar export. (line 16)
6948 * C-c C-e i: iCalendar export. (line 14)
6949 * C-c C-e t: Export options. (line 13)
6950 * C-c C-e v <1>: XOXO export. (line 11)
6951 * C-c C-e v: Sparse trees. (line 41)
6952 * C-c C-e v a: ASCII export. (line 13)
6953 * C-c C-e v b: Export commands. (line 13)
6954 * C-c C-e v H: Export commands. (line 13)
6955 * C-c C-e v h: Export commands. (line 13)
6956 * C-c C-e x: XOXO export. (line 10)
6957 * C-c C-f: Motion. (line 12)
6958 * C-c C-j: Motion. (line 21)
6959 * C-c C-l: Handling links. (line 25)
6960 * C-c C-n: Motion. (line 8)
6961 * C-c C-o <1>: Creating timestamps. (line 31)
6962 * C-c C-o: Handling links. (line 56)
6963 * C-c C-p: Motion. (line 9)
6964 * C-c C-q <1>: Editing and debugging formulas.
6966 * C-c C-q: Built-in table editor.
6968 * C-c C-r <1>: Editing and debugging formulas.
6970 * C-c C-r: Visibility cycling. (line 34)
6971 * C-c C-s <1>: Agenda commands. (line 153)
6972 * C-c C-s: Creating timestamps. (line 46)
6973 * C-c C-t <1>: Clocking work time. (line 27)
6974 * C-c C-t: TODO basics. (line 13)
6975 * C-c C-u: Motion. (line 18)
6976 * C-c C-v: TODO basics. (line 26)
6977 * C-c C-w: Creating timestamps. (line 39)
6978 * C-c C-x b: Visibility cycling. (line 41)
6979 * C-c C-x C-a: ARCHIVE tag. (line 28)
6980 * C-c C-x C-b: Checkboxes. (line 38)
6981 * C-c C-x C-c: Agenda commands. (line 218)
6982 * C-c C-x C-d: Clocking work time. (line 35)
6983 * C-c C-x C-i: Clocking work time. (line 12)
6984 * C-c C-x C-k: Structure editing. (line 39)
6985 * C-c C-x C-l: Processing LaTeX fragments.
6987 * C-c C-x C-n: Handling links. (line 89)
6988 * C-c C-x C-o: Clocking work time. (line 14)
6989 * C-c C-x C-p: Handling links. (line 89)
6990 * C-c C-x C-r: Clocking work time. (line 43)
6991 * C-c C-x C-s: Moving subtrees. (line 10)
6992 * C-c C-x C-t: Custom time format. (line 12)
6993 * C-c C-x C-u: Dynamic blocks. (line 21)
6994 * C-c C-x C-w <1>: Built-in table editor.
6996 * C-c C-x C-w: Structure editing. (line 39)
6997 * C-c C-x C-x: Clocking work time. (line 31)
6998 * C-c C-x C-y <1>: Built-in table editor.
7000 * C-c C-x C-y: Structure editing. (line 46)
7001 * C-c C-x M-w <1>: Built-in table editor.
7003 * C-c C-x M-w: Structure editing. (line 43)
7004 * C-c C-y <1>: Clocking work time. (line 22)
7005 * C-c C-y: Creating timestamps. (line 64)
7006 * C-c l: Handling links. (line 9)
7007 * C-c { <1>: CDLaTeX mode. (line 21)
7008 * C-c {: Editing and debugging formulas.
7010 * C-c |: Built-in table editor.
7012 * C-c }: Editing and debugging formulas.
7014 * C-c ~: Cooperation. (line 48)
7015 * C-k: Agenda commands. (line 115)
7016 * C-S-<left>: Multiple sets in one file.
7018 * C-S-<right>: Multiple sets in one file.
7020 * C-TAB: ARCHIVE tag. (line 38)
7021 * C-u C-c *: Updating the table. (line 16)
7022 * C-u C-c .: Creating timestamps. (line 14)
7023 * C-u C-c = <1>: Editing and debugging formulas.
7025 * C-u C-c =: Field formulas. (line 24)
7026 * C-u C-c C-c: Updating the table. (line 19)
7027 * C-u C-c C-l: Handling links. (line 41)
7028 * C-u C-c C-x C-a: ARCHIVE tag. (line 31)
7029 * C-u C-c C-x C-s: Moving subtrees. (line 12)
7030 * C-u C-c C-x C-u <1>: Dynamic blocks. (line 22)
7031 * C-u C-c C-x C-u: Clocking work time. (line 70)
7032 * C-u C-u C-c *: Updating the table. (line 22)
7033 * C-u C-u C-c =: Editing and debugging formulas.
7035 * C-x C-s: Editing and debugging formulas.
7037 * C-x C-w <1>: Exporting Agenda Views.
7039 * C-x C-w: Agenda commands. (line 227)
7040 * D: Agenda commands. (line 72)
7041 * d: Agenda commands. (line 69)
7042 * f: Agenda commands. (line 42)
7043 * g: Agenda commands. (line 76)
7044 * H: Agenda commands. (line 215)
7045 * i: Agenda commands. (line 196)
7046 * I: Agenda commands. (line 176)
7047 * l: Agenda commands. (line 55)
7048 * L: Agenda commands. (line 30)
7049 * M: Agenda commands. (line 202)
7050 * M-<down> <1>: Editing and debugging formulas.
7052 * M-<down>: Built-in table editor.
7054 * M-<left> <1>: Built-in table editor.
7056 * M-<left>: Structure editing. (line 21)
7057 * M-<RET> <1>: Plain lists. (line 46)
7058 * M-<RET>: Structure editing. (line 6)
7059 * M-<right> <1>: Built-in table editor.
7061 * M-<right>: Structure editing. (line 24)
7062 * M-<TAB> <1>: Completion. (line 10)
7063 * M-<TAB> <2>: Setting tags. (line 6)
7064 * M-<TAB> <3>: Per file keywords. (line 23)
7065 * M-<TAB>: Editing and debugging formulas.
7067 * M-<up> <1>: Editing and debugging formulas.
7069 * M-<up>: Built-in table editor.
7071 * M-S-<down> <1>: Editing and debugging formulas.
7073 * M-S-<down> <2>: Built-in table editor.
7075 * M-S-<down> <3>: Plain lists. (line 63)
7076 * M-S-<down>: Structure editing. (line 36)
7077 * M-S-<left> <1>: The date/time prompt.
7079 * M-S-<left> <2>: Built-in table editor.
7081 * M-S-<left> <3>: Plain lists. (line 69)
7082 * M-S-<left>: Structure editing. (line 27)
7083 * M-S-<RET> <1>: Checkboxes. (line 53)
7084 * M-S-<RET> <2>: Plain lists. (line 56)
7085 * M-S-<RET>: Structure editing. (line 18)
7086 * M-S-<right> <1>: The date/time prompt.
7088 * M-S-<right> <2>: Built-in table editor.
7090 * M-S-<right> <3>: Plain lists. (line 69)
7091 * M-S-<right>: Structure editing. (line 30)
7092 * M-S-<up> <1>: Editing and debugging formulas.
7094 * M-S-<up> <2>: Built-in table editor.
7096 * M-S-<up> <3>: Plain lists. (line 63)
7097 * M-S-<up>: Structure editing. (line 33)
7098 * mouse-1 <1>: Agenda commands. (line 33)
7099 * mouse-1 <2>: The date/time prompt.
7101 * mouse-1: Handling links. (line 70)
7102 * mouse-2 <1>: Agenda commands. (line 33)
7103 * mouse-2: Handling links. (line 70)
7104 * mouse-3 <1>: Agenda commands. (line 28)
7105 * mouse-3: Handling links. (line 75)
7106 * n: Agenda commands. (line 19)
7107 * O: Agenda commands. (line 180)
7108 * o: Agenda commands. (line 65)
7109 * P: Agenda commands. (line 140)
7110 * p: Agenda commands. (line 20)
7111 * q: Agenda commands. (line 238)
7112 * r <1>: Agenda commands. (line 80)
7113 * r: Global TODO list. (line 22)
7114 * S: Agenda commands. (line 206)
7115 * s: Agenda commands. (line 87)
7116 * S-<down> <1>: Agenda commands. (line 149)
7117 * S-<down> <2>: The date/time prompt.
7119 * S-<down> <3>: Creating timestamps. (line 56)
7120 * S-<down> <4>: Priorities. (line 23)
7121 * S-<down> <5>: Editing and debugging formulas.
7123 * S-<down>: Plain lists. (line 59)
7124 * S-<left> <1>: Agenda commands. (line 167)
7125 * S-<left> <2>: The date/time prompt.
7127 * S-<left> <3>: Creating timestamps. (line 51)
7128 * S-<left> <4>: Multiple sets in one file.
7130 * S-<left> <5>: TODO basics. (line 20)
7131 * S-<left>: Editing and debugging formulas.
7133 * S-<RET>: Built-in table editor.
7135 * S-<right> <1>: Agenda commands. (line 159)
7136 * S-<right> <2>: The date/time prompt.
7138 * S-<right> <3>: Creating timestamps. (line 51)
7139 * S-<right> <4>: Multiple sets in one file.
7141 * S-<right> <5>: TODO basics. (line 20)
7142 * S-<right>: Editing and debugging formulas.
7144 * S-<TAB> <1>: Built-in table editor.
7146 * S-<TAB>: Visibility cycling. (line 22)
7147 * S-<up> <1>: Agenda commands. (line 143)
7148 * S-<up> <2>: The date/time prompt.
7150 * S-<up> <3>: Creating timestamps. (line 56)
7151 * S-<up> <4>: Priorities. (line 23)
7152 * S-<up> <5>: Editing and debugging formulas.
7154 * S-<up>: Plain lists. (line 59)
7155 * T: Agenda commands. (line 124)
7156 * t: Agenda commands. (line 111)
7157 * w: Agenda commands. (line 66)
7158 * x: Agenda commands. (line 239)
7159 * X: Agenda commands. (line 183)
7165 Node: Introduction
\x7f11580
7166 Node: Summary
\x7f11995
7167 Node: Installation
\x7f15004
7168 Node: Activation
\x7f16382
7169 Node: Feedback
\x7f17631
7170 Node: Document structure
\x7f19707
7171 Node: Outlines
\x7f20481
7172 Node: Headlines
\x7f21141
7173 Ref: Headlines-Footnote-1
\x7f22149
7174 Node: Visibility cycling
\x7f22248
7175 Ref: Visibility cycling-Footnote-1
\x7f24458
7176 Ref: Visibility cycling-Footnote-2
\x7f24516
7177 Ref: Visibility cycling-Footnote-3
\x7f24566
7178 Node: Motion
\x7f24836
7179 Node: Structure editing
\x7f25790
7180 Node: Archiving
\x7f28616
7181 Node: ARCHIVE tag
\x7f29174
7182 Node: Moving subtrees
\x7f30967
7183 Node: Sparse trees
\x7f32278
7184 Ref: Sparse trees-Footnote-1
\x7f34410
7185 Ref: Sparse trees-Footnote-2
\x7f34592
7186 Node: Plain lists
\x7f34707
7187 Ref: Plain lists-Footnote-1
\x7f38476
7188 Ref: Plain lists-Footnote-2
\x7f38834
7189 Node: Tables
\x7f39018
7190 Node: Built-in table editor
\x7f39532
7191 Node: Narrow columns
\x7f46771
7192 Ref: Narrow columns-Footnote-1
\x7f48704
7193 Node: orgtbl-mode
\x7f48750
7194 Node: The spreadsheet
\x7f49554
7195 Node: References
\x7f50641
7196 Ref: References-Footnote-1
\x7f54770
7197 Node: Formula syntax for Calc
\x7f55059
7198 Node: Formula syntax for Lisp
\x7f57516
7199 Node: Field formulas
\x7f58785
7200 Node: Column formulas
\x7f60093
7201 Node: Editing and debugging formulas
\x7f61692
7202 Node: Updating the table
\x7f65845
7203 Node: Advanced features
\x7f66880
7204 Node: Hyperlinks
\x7f71405
7205 Node: Link format
\x7f72178
7206 Node: Internal links
\x7f73471
7207 Ref: Internal links-Footnote-1
\x7f75396
7208 Node: Radio targets
\x7f75528
7209 Node: External links
\x7f76219
7210 Node: Handling links
\x7f78623
7211 Ref: Handling links-Footnote-1
\x7f83733
7212 Ref: Handling links-Footnote-2
\x7f83970
7213 Node: Link abbreviations
\x7f84044
7214 Node: Search options
\x7f85723
7215 Ref: Search options-Footnote-1
\x7f87503
7216 Node: Custom searches
\x7f87584
7217 Node: Remember
\x7f88632
7218 Node: Setting up remember
\x7f89619
7219 Node: Remember templates
\x7f90201
7220 Ref: Remember templates-Footnote-1
\x7f93493
7221 Node: Storing notes
\x7f93591
7222 Node: TODO items
\x7f95478
7223 Node: TODO basics
\x7f96461
7224 Node: TODO extensions
\x7f98158
7225 Node: Workflow states
\x7f98977
7226 Ref: Workflow states-Footnote-1
\x7f100152
7227 Node: TODO types
\x7f100245
7228 Ref: TODO types-Footnote-1
\x7f101828
7229 Node: Multiple sets in one file
\x7f101910
7230 Node: Per file keywords
\x7f103521
7231 Ref: Per file keywords-Footnote-1
\x7f104810
7232 Node: Priorities
\x7f105011
7233 Node: Breaking down tasks
\x7f106257
7234 Ref: Breaking down tasks-Footnote-1
\x7f106777
7235 Node: Checkboxes
\x7f106873
7236 Node: Timestamps
\x7f109628
7237 Node: Time stamps
\x7f110162
7238 Ref: Time stamps-Footnote-1
\x7f113656
7239 Ref: Time stamps-Footnote-2
\x7f113772
7240 Node: Creating timestamps
\x7f113927
7241 Node: The date/time prompt
\x7f116585
7242 Ref: The date/time prompt-Footnote-1
\x7f118546
7243 Node: Custom time format
\x7f118652
7244 Node: Repeating items
\x7f120210
7245 Node: Progress logging
\x7f122020
7246 Node: Closing items
\x7f122666
7247 Ref: Closing items-Footnote-1
\x7f123600
7248 Ref: Closing items-Footnote-2
\x7f123669
7249 Node: Tracking TODO state changes
\x7f123742
7250 Node: Clocking work time
\x7f124598
7251 Ref: Clocking work time-Footnote-1
\x7f128244
7252 Ref: Clocking work time-Footnote-2
\x7f128322
7253 Node: Tags
\x7f128448
7254 Node: Tag inheritance
\x7f129210
7255 Node: Setting tags
\x7f130147
7256 Ref: Setting tags-Footnote-1
\x7f134670
7257 Ref: Setting tags-Footnote-2
\x7f134782
7258 Node: Tag searches
\x7f134865
7259 Node: Agenda views
\x7f137576
7260 Node: Agenda files
\x7f139521
7261 Ref: Agenda files-Footnote-1
\x7f140487
7262 Ref: Agenda files-Footnote-2
\x7f140636
7263 Node: Agenda dispatcher
\x7f140829
7264 Node: Built-in agenda views
\x7f142520
7265 Node: Weekly/Daily agenda
\x7f143098
7266 Node: Global TODO list
\x7f145227
7267 Node: Matching headline tags
\x7f147499
7268 Node: Timeline
\x7f148570
7269 Node: Stuck projects
\x7f149236
7270 Node: Presentation and sorting
\x7f151087
7271 Node: Categories
\x7f151878
7272 Node: Time-of-day specifications
\x7f152542
7273 Node: Sorting of agenda items
\x7f154513
7274 Node: Agenda commands
\x7f155795
7275 Node: Custom agenda views
\x7f162949
7276 Node: Storing searches
\x7f163668
7277 Node: Block agenda
\x7f165580
7278 Node: Setting Options
\x7f166810
7279 Node: Exporting Agenda Views
\x7f169549
7280 Ref: Exporting Agenda Views-Footnote-1
\x7f173840
7281 Ref: Exporting Agenda Views-Footnote-2
\x7f173897
7282 Node: Extracting Agenda Information for other programs
\x7f174083
7283 Node: Embedded LaTeX
\x7f178209
7284 Ref: Embedded LaTeX-Footnote-1
\x7f179301
7285 Node: Math symbols
\x7f179491
7286 Node: Subscripts and Superscripts
\x7f180256
7287 Node: LaTeX fragments
\x7f181100
7288 Ref: LaTeX fragments-Footnote-1
\x7f183334
7289 Node: Processing LaTeX fragments
\x7f183596
7290 Node: CDLaTeX mode
\x7f184542
7291 Ref: CDLaTeX mode-Footnote-1
\x7f187026
7292 Node: Exporting
\x7f187174
7293 Node: ASCII export
\x7f188488
7294 Node: HTML export
\x7f189778
7295 Node: Export commands
\x7f190397
7296 Node: Quoting HTML tags
\x7f191208
7297 Node: Links
\x7f191838
7298 Node: Images
\x7f192535
7299 Ref: Images-Footnote-1
\x7f193406
7300 Node: CSS support
\x7f193467
7301 Ref: CSS support-Footnote-1
\x7f194786
7302 Node: XOXO export
\x7f194899
7303 Node: iCalendar export
\x7f195338
7304 Node: Text interpretation
\x7f196557
7305 Node: Comment lines
\x7f197099
7306 Node: Initial text
\x7f197494
7307 Node: Enhancing text
\x7f199168
7308 Ref: Enhancing text-Footnote-1
\x7f201030
7309 Node: Export options
\x7f201120
7310 Node: Publishing
\x7f203013
7311 Ref: Publishing-Footnote-1
\x7f203809
7312 Node: Configuration
\x7f204005
7313 Node: Project alist
\x7f204723
7314 Node: Sources and destinations
\x7f205789
7315 Node: Selecting files
\x7f206519
7316 Node: Publishing action
\x7f207267
7317 Node: Publishing options
\x7f208500
7318 Node: Publishing links
\x7f210652
7319 Node: Project page index
\x7f212165
7320 Node: Sample configuration
\x7f212943
7321 Node: Simple example
\x7f213435
7322 Node: Complex example
\x7f214108
7323 Node: Triggering publication
\x7f216184
7324 Node: Miscellaneous
\x7f216869
7325 Node: Completion
\x7f217503
7326 Node: Customization
\x7f218974
7327 Node: In-buffer settings
\x7f219557
7328 Node: The very busy C-c C-c key
\x7f224183
7329 Node: Clean view
\x7f225827
7330 Node: TTY keys
\x7f228404
7331 Node: Interaction
\x7f230014
7332 Node: Cooperation
\x7f230411
7333 Node: Conflicts
\x7f233153
7334 Node: Bugs
\x7f234716
7335 Node: Extensions and Hacking
\x7f236212
7336 Node: Extensions
\x7f236808
7337 Node: Tables in arbitrary syntax
\x7f238755
7338 Node: Radio tables
\x7f239832
7339 Node: A LaTeX example
\x7f242335
7340 Ref: A LaTeX example-Footnote-1
\x7f245981
7341 Ref: A LaTeX example-Footnote-2
\x7f246129
7342 Node: Translator functions
\x7f246564
7343 Ref: Translator functions-Footnote-1
\x7f249673
7344 Node: Dynamic blocks
\x7f249761
7345 Node: Special agenda views
\x7f251733
7346 Ref: Special agenda views-Footnote-1
\x7f254012
7347 Node: History and Acknowledgments
\x7f254272
7348 Node: Index
\x7f260132
7349 Node: Key Index
\x7f291936