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.56).
10 Copyright (C) 2004, 2005, 2006 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.56).
32 Copyright (C) 2004, 2005, 2006 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 * Table calculations:: Compute a field from other fields
95 * orgtbl-mode:: The table editor as minor mode
96 * table.el:: Complex tables
98 Calculations in tables
100 * Formula syntax:: How to write a formula
101 * Lisp formulas:: An alternative way to write formulas
102 * Column formulas:: Formulas valid for all fields in a column
103 * Advanced features:: Field names, parameters and automatic recalc
104 * Named-field formulas:: Formulas valid in single fields
105 * Editing/debugging formulas:: Changing a stored formula
106 * Appetizer:: Taste the power of calc
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.
122 * CamelCase links:: Activating CamelCase words as links
126 * TODO basics:: Marking and displaying TODO entries
127 * TODO extensions:: Workflow and assignments
128 * Priorities:: Some things are more important than others
129 * Breaking down tasks:: Splitting a task into managable pieces
130 * Checkboxes:: Tick-off lists
132 Extended use of TODO keywords
134 * Workflow states:: From TODO to DONE in steps
135 * TODO types:: I do this, Fred the rest
136 * Per file keywords:: Different files, different requirements
140 * Time stamps:: Assigning a time to a tree entry
141 * Creating timestamps:: Commands which insert timestamps
142 * Custom time format:: If you cannot work with the ISO format
143 * Progress logging:: Documenting when what work was done.
147 * The date/time prompt:: How org-mode helps you entering date and time
151 * Closing items:: When was this entry marked DONE?
152 * Clocking work time:: When exactly did you work on this item?
156 * Tag inheritance:: Tags use the tree structure of the outline
157 * Setting tags:: How to assign tags to a headline
158 * Tag searches:: Searching for combinations of tags
162 * Agenda files:: Files being searched for agenda information
163 * Agenda dispatcher:: Keyboard access to agenda views
164 * Weekly/Daily agenda:: The calendar page with current tasks
165 * Global TODO list:: All unfinished action items
166 * Matching headline tags:: Structured information with fine-tuned search
167 * Timeline:: Time-sorted view for single file
168 * Presentation and sorting:: How agenda items are prepared for display
169 * Agenda commands:: Remote editing of org trees
170 * Custom agenda views:: Defining special searches and views
172 The weekly/daily agenda
174 * Calendar/Diary integration:: Integrating Anniversaries and more
176 Presentation and sorting
178 * Categories:: Not all tasks are equal
179 * Time-of-day specifications:: How the agenda knows the time
180 * Sorting of agenda items:: The order of things
184 * Storing searches:: Type once, use often
185 * Block agenda:: All the stuff you need in a single buffer
186 * Setting Options:: Changing the rules
187 * Batch processing:: Agenda views from the command line
191 * Math symbols:: TeX macros for symbols and Greek letters
192 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
193 * LaTeX fragments:: Complex formulas made easy
194 * Processing LaTeX fragments:: Previewing LaTeX processing
195 * CDLaTeX mode:: Speed up entering of formulas
199 * ASCII export:: Exporting to plain ASCII
200 * HTML export:: Exporting to HTML
201 * XOXO export:: Exporting to XOXO
202 * iCalendar export:: Exporting in iCalendar format
203 * Text interpretation:: How the exporter looks at the file
205 Text interpretation by the exporter
207 * Comment lines:: Some lines will not be exported
208 * Enhancing text:: Subscripts, symbols and more
209 * Export options:: How to influence the export settings
213 * Configuration:: Defining projects
214 * Sample configuration:: Example projects
215 * Triggering publication:: Publication commands
219 * Project alist:: The central configuration variable
220 * Sources and destinations:: From here to there
221 * Selecting files:: What files are part of the project?
222 * Publishing action:: Setting the function doing the publishing
223 * Publishing options:: Tweaking HTML export
224 * Publishing links:: Which links keep working after publishing?
225 * Project page index:: Publishing a list of project files
229 * Simple example:: One-component publishing
230 * Complex example:: A multi-component publishing example
234 * Completion:: M-TAB knows what you need
235 * Customization:: Adapting Org-mode to your taste
236 * In-buffer settings:: Overview of the #+KEYWORDS
237 * The very busy C-c C-c key:: When in doubt, press C-c C-c
238 * Clean view:: Getting rid of leading stars in the outline
239 * TTY keys:: Using Org-mode on a tty
240 * Interaction:: Other Emacs packages
241 * Bugs:: Things which do not work perfectly
243 Interaction with other packages
245 * Cooperation:: Packages Org-mode cooperates with
246 * Conflicts:: Packages that lead to conflicts
248 Extensions, Hooks and Hacking
250 * Extensions:: Existing 3rd-part extensions
251 * Dynamic blocks:: Automatically filled blocks
254 File: org, Node: Introduction, Next: Document structure, Prev: Top, Up: Top
261 * Summary:: Brief summary of what Org-mode does
262 * Installation:: How to install a downloaded version of Org-mode
263 * Activation:: How to activate Org-mode for certain buffers.
264 * Feedback:: Bug reports, ideas, patches etc.
267 File: org, Node: Summary, Next: Installation, Prev: Introduction, Up: Introduction
272 Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing
273 project planning with a fast and effective plain-text system.
275 Org-mode develops organizational tasks around NOTES files that
276 contain lists or information about projects as plain text. Org-mode is
277 implemented on top of outline-mode, which makes it possible to keep the
278 content of large files well structured. Visibility cycling and
279 structure editing help to work with the tree. Tables are easily created
280 with a built-in table editor. Org-mode supports ToDo items, deadlines,
281 time stamps, and scheduling. It dynamically compiles entries into an
282 agenda that utilizes and smoothly integrates much of the Emacs calendar
283 and diary. Plain text URL-like links connect to websites, emails,
284 Usenet messages, BBDB entries, and any files related to the projects.
285 For printing and sharing of notes, an Org-mode file can be exported as a
286 structured ASCII file, as HTML, or (todo and agenda items only) as an
287 iCalendar file. It can also serve as a publishing tool for a set of
290 An important design aspect that distinguishes Org-mode from for
291 example Planner/Muse is that it encougages to store every piece of
292 information only once. In Planner, you have project pages, day pages
293 and possibly other files, duplicating some information such as tasks.
294 In Org-mode, you only have notes files. In your notes you mark entries
295 as tasks, label them with tags and timestamps. All necessary lists
296 like a schedule for the day, the agenda for a meeting, tasks lists
297 selected by tags etc are created dynamically when you need them.
299 Org-mode keeps simple things simple. When first fired up, it should
300 feel like a straightforward, easy to use outliner. Complexity is not
301 imposed, but a large amount of functionality is available when you need
302 it. Org-mode can be used on different levels and in different ways, for
305 * as an outline extension with visibility cycling and structure editing
306 * as an ASCII system and table editor for taking structured notes
307 * as an ASCII table editor with spreadsheet-like capabilities
308 * as a TODO list editor
309 * as a full agenda and planner with deadlines and work scheduling
310 * as an environment to implement David Allen's GTD system
311 * as a simple hypertext system, with HTML export
312 * as a publishing tool to create a set of interlinked webpages
314 Org-mode's automatic, context sensitive table editor can be
315 integrated into any major mode by activating the minor Orgtbl-mode.
317 There is a website for Org-mode which provides links to the newest
318 version of Org-mode, as well as additional information, frequently asked
319 questions (FAQ), links to tutorials etc. This page is located at
320 `http://www.astro.uva.nl/~dominik/Tools/org/'.
323 File: org, Node: Installation, Next: Activation, Prev: Summary, Up: Introduction
328 Important: If Org-mode is part of the Emacs distribution or an XEmacs
329 package, please skip this section and go directly to *Note Activation::.
331 If you have downloaded Org-mode from the Web, you must take the
332 following steps to install it: Go into the Org-mode distribution
333 directory and edit the top section of the file `Makefile'. You must
334 set the name of the Emacs binary (likely either `emacs' or `xemacs'),
335 and the paths to the directories where local Lisp and Info files are
336 kept. If you don't have access to the system-wide directories, create
337 your own two directories for these files, enter them into the Makefile,
338 and make sure Emacs finds the Lisp files by adding the following line
341 (setq load-path (cons "~/path/to/lispdir" load-path))
343 XEmacs users now need to install the file `noutline.el' from the
344 `xemacs' subdirectory of the Org-mode distribution. Use the command:
346 make install-noutline
348 Now byte-compile and install the Lisp files with the shell commands:
353 If you want to install the info documentation, use this command:
357 Then add to `.emacs':
359 ;; This line only if org-mode is not part of the X/Emacs distribution.
360 (require 'org-install)
363 File: org, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction
368 Add the following lines to your `.emacs' file. The last two lines
369 define _global_ keys for the commands `org-store-link' and `org-agenda'
370 - please choose suitable keys yourself.
372 ;; The following lines are always needed. Choose your own keys.
373 (add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
374 (define-key global-map "\C-cl" 'org-store-link)
375 (define-key global-map "\C-ca" 'org-agenda)
377 Furthermore, you must activate `font-lock-mode' in org-mode buffers,
378 because significant functionality depends on font-locking being active.
379 You can do this with either one of the following two lines (XEmacs
380 user must use the second option):
381 (global-font-lock-mode 1) ; for all buffers
382 (add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
384 With this setup, all files with extension `.org' will be put into
385 Org-mode. As an alternative, make the first line of a file look like
388 MY PROJECTS -*- mode: org; -*-
390 which will select Org-mode for this buffer no matter what the file's
391 name is. See also the variable `org-insert-mode-line-in-empty-file'.
394 File: org, Node: Feedback, Prev: Activation, Up: Introduction
399 If you find problems with Org-mode, or if you have questions, remarks,
400 or ideas about it, please contact the maintainer Carsten Dominik at
401 <dominik at science dot uva dot nl>.
403 For bug reports, please provide as much information as possible,
404 including the version information of Emacs (`C-h v emacs-version
405 <RET>') and Org-mode (`C-h v org-version <RET>'), as well as the
406 Org-mode related setup in `.emacs'. If an error occurs, a backtrace
407 can be very useful (see below on how to create one). Often a small
408 example file helps, along with clear information about:
410 1. What exactly did you do?
412 2. What did you expect to happen?
414 3. What happened instead?
415 Thank you for helping to improve this mode.
417 How to create a useful backtrace
418 ................................
420 If working with Org-mode produces an error with a message you don't
421 understand, you may have hit a bug. The best way to report this is by
422 providing, in addition to what was mentioned above, a _Backtrace_.
423 This is information from the built-in debugger about where and how the
424 error occurred. Here is how to produce a useful backtrace:
426 1. Start a fresh Emacs or XEmacs, and make sure that it will load the
427 original Lisp code in `org.el' instead of the compiled version in
428 `org.elc'. The backtrace contains much more information if it is
429 produced with uncompiled code. To do this, either rename `org.elc'
430 to something else before starting Emacs, or ask Emacs explicitly
431 to load `org.el' by using the command line
432 emacs -l /path/to/org.el
434 2. Go to the `Options' menu and select `Enter Debugger on Error'
435 (XEmacs has this option in the `Troubleshooting' sub-menu).
437 3. Do whatever you have to do to hit the error. Don't forget to
438 document the steps you take.
440 4. When you hit the error, a `*Backtrace*' buffer will appear on the
441 screen. Save this buffer to a file (for example using `C-x C-w')
442 and attach it to your bug report.
445 File: org, Node: Document structure, Next: Tables, Prev: Introduction, Up: Top
450 Org-mode is based on outline mode and provides flexible commands to
451 edit the structure of the document.
455 * Outlines:: Org-mode is based on outline-mode
456 * Headlines:: How to typeset org-tree headlines
457 * Visibility cycling:: Show and hide, much simplified
458 * Motion:: Jumping to other headlines
459 * Structure editing:: Changing sequence and level of headlines
460 * Archiving:: Move done task trees to a different place
461 * Sparse trees:: Matches embedded in context
462 * Plain lists:: Additional structure within an entry
465 File: org, Node: Outlines, Next: Headlines, Prev: Document structure, Up: Document structure
470 Org-mode is implemented on top of outline-mode. Outlines allow to
471 organize a document in a hierarchical structure, which (at least for
472 me) is the best representation of notes and thoughts. Overview over
473 this structure is achieved by folding (hiding) large parts of the
474 document to show only the general document structure and the parts
475 currently being worked on. Org-mode greatly simplifies the use of
476 outlines by compressing the entire show/hide functionality into a
477 single command `org-cycle', which is bound to the <TAB> key.
480 File: org, Node: Headlines, Next: Visibility cycling, Prev: Outlines, Up: Document structure
485 Headlines define the structure of an outline tree. The headlines in
486 Org-mode start with one or more stars, on the left margin. For example:
494 * Another top level headline
496 Some people find the many stars too noisy and would prefer an outline
497 that has whitespace followed by a single star as headline starters.
498 *Note Clean view:: describes a setup to realize this.
501 File: org, Node: Visibility cycling, Next: Motion, Prev: Headlines, Up: Document structure
503 2.3 Visibility cycling
504 ======================
506 Outlines make it possible to hide parts of the text in the buffer.
507 Org-mode uses just two commands, bound to <TAB> and `S-<TAB>' to change
508 the visibility in the buffer.
511 _Subtree cycling_: Rotate current subtree between the states
513 ,-> FOLDED -> CHILDREN -> SUBTREE --.
514 '-----------------------------------'
516 The cursor must be on a headline for this to work(1). When the
517 cursor is at the beginning of the buffer and the first line is not
518 a headline, then <TAB> actually runs global cycling (see
519 below)(2). Also when called with a prefix argument (`C-u <TAB>'),
520 global cycling is invoked.
524 _Global cycling_: Rotate the entire buffer between the states
526 ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
527 '--------------------------------------'
529 Note that inside tables, `S-<TAB>' jumps to the previous field.
535 Reveal context around point, showing the current entry, the
536 following heading and the hierarchy above. Useful for working
537 near a location exposed by a sparse tree command (*note Sparse
538 trees::) or an agenda command (*note Agenda commands::).
540 When Emacs first visits an Org-mode file, the global state is set to
541 OVERVIEW, i.e. only the top level headlines are visible. This can be
542 configured through the variable `org-startup-folded', or on a per-file
543 basis by adding one of the following lines anywhere in the buffer:
549 ---------- Footnotes ----------
551 (1) see, however, the option `org-cycle-emulate-tab'.
553 (2) see the option `org-cycle-global-at-bob'.
556 File: org, Node: Motion, Next: Structure editing, Prev: Visibility cycling, Up: Document structure
561 The following commands jump to other headlines in the buffer.
570 Next heading same level.
573 Previous heading same level.
576 Backward to higher level heading.
579 Jump to a different place without changing the current outline
580 visibility. Shows the document structure in a temporary buffer,
581 where you can use visibility cycling (<TAB>) to find your
582 destination. After pressing <RET>, the cursor moves to the
583 selected location in the original buffer, and the headings
584 hierarchy above it is made visible.
587 File: org, Node: Structure editing, Next: Archiving, Prev: Motion, Up: Document structure
589 2.5 Structure editing
590 =====================
593 Insert new heading with same level as current. If the cursor is
594 in a plain list item, a new item is created (*note Plain lists::).
595 To force creation of a new headline, use a prefix arg, or first
596 press <RET> to get to the beginning of the next line. When this
597 command is used in the middle of a line, the line is split and the
598 rest of the line becomes the new headline. If the command is used
599 at the beginning of a headline, the new headline is created before
600 the current line. If at the beginning of any other line, the
601 content of that line is made the new heading. If the command is
602 used at the end of a folded subtree (i.e. behind the ellipses at
603 the end of a headline), then a headline like the current one will
604 be inserted after the end of the subtree.
607 Insert new TODO entry with same level as current heading.
610 Promote current heading by one level.
613 Demote current heading by one level.
616 Promote the current subtree by one level.
619 Demote the current subtree by one level.
622 Move subtree up (swap with previous subtree of same level).
625 Move subtree down (swap with next subtree of same level).
629 Kill subtree, i.e. remove it from buffer but save in kill ring.
632 Copy subtree to kill ring.
635 Yank subtree from kill ring. This does modify the level of the
636 subtree to make sure the tree fits in nicely at the yank position.
637 The yank level can also be specified with a prefix arg, or by
638 yanking after a headline marker like `****'.
640 When there is an active region (transient-mark-mode), promotion and
641 demotion work on all headlines in the region. To select a region of
642 headlines, it is best to place both point and mark at the beginning of a
643 line, mark at the beginning of the first headline, and point at the line
644 just after the last headline to change. Note that when the cursor is
645 inside a table (*note Tables::), the Meta-Cursor keys have different
649 File: org, Node: Archiving, Next: Sparse trees, Prev: Structure editing, Up: Document structure
654 When a project represented by a (sub)tree is finished, you may want to
655 move the tree out of the way and to stop it from contributing to the
656 agenda. Org-mode knows two ways of archiving. You can mark a tree with
657 the ARCHIVE tag, or you can move an entire (sub)tree to a different
662 * ARCHIVE tag:: Marking a tree as inactive
663 * Moving subtrees:: Moving a tree to an archive file
666 File: org, Node: ARCHIVE tag, Next: Moving subtrees, Prev: Archiving, Up: Archiving
668 2.6.1 The ARCHIVE tag
669 ---------------------
671 A headline that is marked with the ARCHIVE tag (*note Tags::) stays at
672 its location in the outline tree, but behaves in the following way:
673 - It does not open when you attempt to do so with a visibility
674 cycling command (*note Visibility cycling::). You can force
675 cycling archived subtrees with `C-<TAB>', or by setting the option
676 `org-cycle-open-archived-trees'. Also normal outline commands like
677 `show-all' will open archived subtrees.
679 - During sparse tree construction (*note Sparse trees::), matches in
680 archived subtrees are not exposed, unless you configure the option
681 `org-sparse-tree-open-archived-trees'.
683 - During agenda view construction (*note Agenda views::), the
684 content of archived trees is ignored unless you configure the
685 option `org-agenda-skip-archived-trees'.
687 - Archived trees are not exported (*note Exporting::), only the
688 headline is. Configure the details using the variable
689 `org-export-with-archived-trees'.
691 The following commands help managing the ARCHIVE tag:
694 Toggle the ARCHIVE tag for the current headline. When the tag is
695 set, the headline changes to a shadowish face, and the subtree
699 Check if any direct children of the current headline should be
700 archived. To do this, each subtree is checked for open TODO
701 entries. If none are found, the command offers to set the ARCHIVE
702 tag for the child. If the cursor is _not_ on a headline when this
703 command is invoked, the level 1 trees will be checked.
706 Cycle a tree even if it is tagged with ARCHIVE.
709 File: org, Node: Moving subtrees, Prev: ARCHIVE tag, Up: Archiving
711 2.6.2 Moving subtrees
712 ---------------------
714 Once an entire project is finished, you may want to move it to a
715 different location, either in the current file, or even in a different
716 file, the archive file.
719 Archive the subtree starting at the cursor position to the location
720 given by `org-archive-location'.
723 Check if any direct children of the current headline could be
724 moved to the archive. To do this, each subtree is checked for
725 open TODO entries. If none are found, the command offers to move
726 it to the archive location. If the cursor is _not_ on a headline
727 when this command is invoked, the level 1 trees will be checked.
729 The default archive location is a file in the same directory as the
730 current file, with the name derived by appending `_archive' to the
731 current file name. For information and examples on how to change this,
732 see the documentation string of the variable `org-archive-location'.
735 File: org, Node: Sparse trees, Next: Plain lists, Prev: Archiving, Up: Document structure
740 An important feature of Org-mode is the ability to construct _sparse
741 trees_ for selected information in an outline tree. A sparse tree
742 means that the entire document is folded as much as possible, but the
743 selected information is made visible along with the headline structure
744 above it(1). Just try it out and you will see immediately how it works.
746 Org-mode contains several commands creating such trees. The most
747 basic one is `org-occur':
750 Occur. Prompts for a regexp and shows a sparse tree with all
751 matches. If the match is in a headline, the headline is made
752 visible. If the match is in the body of an entry, headline and
753 body are made visible. In order to provide minimal context, also
754 the full hierarchy of headlines above the match is shown, as well
755 as the headline following the match. Each match is also
756 highlighted; the highlights disappear when the bufer is changes an
757 editing command, or by pressing `C-c C-c'. When called with a
758 `C-u' prefix argument, previous highlights are kept, so several
759 calls to this command can be stacked.
760 For frequently used sparse trees of specific search strings, you can
761 use the variable `org-agenda-custom-commands' to define fast keyboard
762 access to specific sparse trees. These commands will then be
763 accessible through the agenda dispatcher (*note Agenda dispatcher::).
766 (setq org-agenda-custom-commands
767 '(("f" occur-tree "FIXME")))
769 will define the key `C-c a f' as a shortcut for creating a sparse tree
770 matching the string `FIXME'.
772 Other commands use sparse trees as well. For example `C-c C-v'
773 creates a sparse TODO tree (*note TODO basics::).
775 To print a sparse tree, you can use the Emacs command
776 `ps-print-buffer-with-faces' which does not print invisible parts of
777 the document (2). Or you can use the command `C-c C-e v' to export
778 only the visible part of the document and print the resulting file.
780 ---------- Footnotes ----------
782 (1) See also the variables `org-show-hierarchy-above' and
783 `org-show-following-heading'.
785 (2) This does not work under XEmacs, because XEmacs uses selective
786 display for outlining, not text properties.
789 File: org, Node: Plain lists, Prev: Sparse trees, Up: Document structure
794 Within an entry of the outline tree, hand-formatted lists can provide
795 additional structure. They also provide a way to create lists of
796 checkboxes (*note Checkboxes::). Org-mode supports editing such lists,
797 and the HTML exporter (*note Exporting::) does parse and format them.
799 Org-mode knows ordered and unordered lists. Unordered list items
800 start with `-', `+', or `*'(1) as bullets. Ordered list items start
801 with `1.' or `1)'. Items belonging to the same list must have the same
802 indentation on the first line. In particular, if an ordered list
803 reaches number `10.', then the 2-digit numbers must be written
804 left-aligned with the other numbers in the list. Indentation also
805 determines the end of a list item. It ends before the next line that
806 is indented like the bullet/number, or less. For example:
809 My favorite scenes are (in this order)
810 1. The attack of the Rohirrim
811 2. Eowyns fight with the witch king
812 + this was already my favorite scene in the book
813 + I really like Miranda Otto.
814 3. Peter Jackson being shot by Legolas
816 He makes a really funny face when it happens.
817 But in the end, not individual scenes matter but the film as a whole.
819 Org-mode supports these lists by tuning filling and wrapping
820 commands to deal with them correctly(2).
822 The following commands act on items when the cursor is in the first
823 line of an item (the line with the bullet or number).
826 Items can be folded just like headline levels if you set the
827 variable `org-cycle-include-plain-lists'. The level of an item is
828 then given by the indentation of the bullet/number. Items are
829 always subordinate to real headlines, however; the hierarchies
830 remain completely separated.
833 Insert new item at current level. With prefix arg, force a new
834 heading (*note Structure editing::). If this command is used in
835 the middle of a line, the line is _split_ and the rest of the line
836 becomes the new item. If this command is executed in the
837 _whitespace before a bullet or number_, the new item is created
838 _before_ the current item. If the command is executed in the
839 white space before the text that is part of an item but does not
840 contain the bullet, a bullet is added to the current line.
843 Insert a new item with a checkbox (*note Checkboxes::).
847 Jump to the previous/next item in the current list.
851 Move the item including subitems up/down (swap with previous/next
852 item of same indentation). If the list is ordered, renumbering is
857 Decrease/increase the indentation of the item, including subitems.
858 Initially, the item tree is selected based on current indentation.
859 When these commands are executed several times in direct
860 succession, the initially selected region is used, even if the new
861 indentation would imply a different hierarchy. To use the new
862 hierarchy, break the command chain with a cursor motion or so.
865 If there is a checkbox (*note Checkboxes::) in the item line,
866 toggle the state of the checkbox. Otherwise, if this is an
867 ordered list, renumber the ordered list at the cursor.
869 ---------- Footnotes ----------
871 (1) When using `*' as a bullet, lines must be indented or they will
872 be seen as top-level headlines. Also, when you are hiding leading
873 stars to get a clean outline view, plain list items starting with a
874 star are visually indistinguishable from true headlines. In short:
875 even though `*' is supported, it may be better not to use it for plain
878 (2) Org-mode only changes the filling settings for Emacs. For
879 XEmacs, you should use Kyle E. Jones' `filladapt.el'. To turn this on,
884 File: org, Node: Tables, Next: Hyperlinks, Prev: Document structure, Up: Top
889 Org-mode has a very fast and intuitive table editor built-in.
890 Spreadsheet-like calculations are supported in connection with the
891 Emacs `calc' package.
895 * Built-in table editor:: Simple tables
896 * Narrow columns:: Stop wasting space in tables
897 * Table calculations:: Compute a field from other fields
898 * orgtbl-mode:: The table editor as minor mode
899 * table.el:: Complex tables
902 File: org, Node: Built-in table editor, Next: Narrow columns, Prev: Tables, Up: Tables
904 3.1 The built-in table editor
905 =============================
907 Org-mode makes it easy to format tables in plain ASCII. Any line with
908 `|' as the first non-white character is considered part of a table.
909 `|' is also the column separator. A table might look like this:
911 | Name | Phone | Age |
912 |-------+-------+-----|
913 | Peter | 1234 | 17 |
916 A table is re-aligned automatically each time you press <TAB> or
917 <RET> or `C-c C-c' inside the table. <TAB> also moves to the next
918 field (<RET> to the next row) and creates new table rows at the end of
919 the table or before horizontal lines. The indentation of the table is
920 set by the first line. Any line starting with `|-' is considered as a
921 horizontal separator line and will be expanded on the next re-align to
922 span the whole table width. So, to create the above table, you would
928 and then press <TAB> to align the table and start filling in fields.
930 When typing text into a field, Org-mode treats <DEL>, <Backspace>,
931 and all character keys in a special way, so that inserting and deleting
932 avoids shifting other fields. Also, when typing _immediately after the
933 cursor was moved into a new field with `<TAB>', `S-<TAB>' or `<RET>'_,
934 the field is automatically made blank. If this behavior is too
935 unpredictable for you, configure the variables
936 `org-enable-table-editor' and `org-table-auto-blank-field'.
938 Creation and conversion
939 .......................
942 Convert the active region to table. If every line contains at
943 least one TAB character, the function assumes that the material is
944 tab separated. If not, lines are split at whitespace into fields.
945 You can use a prefix argument to indicate the minimum number of
946 consecutive spaces required to identify a field separator
948 If there is no active region, this command creates an empty
949 Org-mode table. But it's easier just to start typing, like
950 `|Name|Phone|Age <RET> |- <TAB>'.
952 Re-aligning and field motion
953 ............................
956 Re-align the table without moving the cursor.
959 Re-align the table, move to the next field. Creates a new row if
963 Re-align, move to previous field.
966 Re-align the table and move down to next row. Creates a new row if
967 necessary. At the beginning or end of a line, <RET> still does
968 NEWLINE, so it can be used to split a table.
970 Column and row editing
971 ......................
975 Move the current column left/right.
978 Kill the current column.
981 Insert a new column to the left of the cursor position.
985 Move the current row up/down.
988 Kill the current row or horizontal line.
991 Insert a new row above (with arg: below) the current row.
994 Insert a horizontal line below current row. With prefix arg, the
995 line is created above the current line.
998 Sort the table lines in the region. Point and mark must be in the
999 first and last line to be included, and must be in the column that
1000 should be used for sorting. The command prompts for numerical
1001 versus alphanumerical sorting.
1007 Copy a rectangular region from a table to a special clipboard.
1008 Point and mark determine edge fields of the rectangle. The
1009 process ignores horizontal separator lines.
1012 Copy a rectangular region from a table to a special clipboard, and
1013 blank all fields in the rectangle. So this is the "cut" operation.
1016 Paste a rectangular region into a table. The upper right corner
1017 ends up in the current field. All involved fields will be
1018 overwritten. If the rectangle does not fit into the present table,
1019 the table is enlarged as needed. The process ignores horizontal
1023 Wrap several fields in a column like a paragraph. If there is an
1024 active region, and both point and mark are in the same column, the
1025 text in the column is wrapped to minimum width for the given
1026 number of lines. A prefix ARG may be used to change the number of
1027 desired lines. If there is no region, the current field is split
1028 at the cursor position and the text fragment to the right of the
1029 cursor is prepended to the field one line down. If there is no
1030 region, but you specify a prefix ARG, the current field is made
1031 blank, and the content is appended to the field above.
1037 Install a new formula for the current column and replace current
1038 field with the result of the formula.
1041 Install a new formula for the current field, which must be a named
1042 field. Evaluate the formula and replace the field content with the
1046 Edit all formulas associated with the current table in a separate
1050 Recalculate the current row by applying the stored formulas from
1051 left to right. When called with a `C-u' prefix, recalculate the
1052 entire table, starting with the first non-header line (i.e. below
1053 the first horizontal separator line). For details, see *Note
1054 Table calculations::.
1057 Rotate the calculation mark in first column through the states `',
1058 `#', `*', `!', `$'. For the meaning of these marks see *Note
1059 Advanced features::. When there is an active region, change all
1060 marks in the region.
1063 Which table column is the cursor in? Displays number >0 in echo
1067 Sum the numbers in the current column, or in the rectangle defined
1068 by the active region. The result is shown in the echo area and can
1069 be inserted with `C-y'.
1072 When current field is empty, copy from first non-empty field above.
1073 When not empty, copy current field down to next row and move cursor
1074 along with it. Depending on the variable
1075 `org-table-copy-increment', integer field values will be
1076 incremented during copy. This key is also used by CUA-mode (*note
1083 Edit the current field in a separate window. This is useful for
1084 fields that are not fully visible (*note Narrow columns::). When
1085 called with a `C-u' prefix, just make the full field visible, so
1086 that it can be edited in place.
1089 This is an alias for `C-u C-c `' to make the current field fully
1092 `M-x org-table-import'
1093 Import a file as a table. The table should be TAB- or whitespace
1094 separated. Useful, for example, to import an Excel table or data
1095 from a database, because these programs generally can write
1096 TAB-separated text files. This command works by inserting the
1097 file into the buffer and then converting the region to a table.
1098 Any prefix argument is passed on to the converter, which uses it
1099 to determine the separator.
1101 `M-x org-table-export'
1102 Export the table as a TAB-separated file. Useful for data
1103 exchange with, for example, Excel or database programs.
1106 If you don't like the automatic table editor because it gets in your
1107 way on lines which you would like to start with `|', you can turn it
1110 (setq org-enable-table-editor nil)
1112 Then the only table command that still works is `C-c C-c' to do a
1116 File: org, Node: Narrow columns, Next: Table calculations, Prev: Built-in table editor, Up: Tables
1121 The width of columns is automatically determined by the table editor.
1122 Sometimes a single field or a few fields need to carry more text,
1123 leading to inconveniently wide columns. To limit(1) the width of a
1124 column, one field anywhere in the column may contain just the string
1125 `<N>' where `N' is an integer specifying the width of the column in
1126 characters. The next re-align will then set the width of this column
1127 to no more than this value.
1129 |---+------------------------------| |---+--------|
1131 | 1 | one | | 1 | one |
1132 | 2 | two | ----\ | 2 | two |
1133 | 3 | This is a long chunk of text | ----/ | 3 | This=> |
1134 | 4 | four | | 4 | four |
1135 |---+------------------------------| |---+--------|
1137 Fields that are wider become clipped and end in the string `=>'. Note
1138 that the full text is still in the buffer, it is only invisible. To
1139 see the full text, hold the mouse over the field - a tooltip window
1140 will show the full content. To edit such a field, use the command `C-c
1141 `' (that is `C-c' followed by the backquote). This will open a new
1142 window with the full field. Edit it and finish with `C-c C-c'.
1144 When visiting a file containing a table with narrowed columns, the
1145 necessary character hiding has not yet happened, and the table needs to
1146 be aligned before it looks nice. Setting the option
1147 `org-startup-align-all-tables' will realign all tables in a file upon
1148 visiting, but also slow down startup. You can also set this option on
1149 a per-file basis with:
1154 ---------- Footnotes ----------
1156 (1) This feature does not work on XEmacs.
1159 File: org, Node: Table calculations, Next: orgtbl-mode, Prev: Narrow columns, Up: Tables
1161 3.3 Calculations in tables
1162 ==========================
1164 The table editor makes use of the Emacs `calc' package to implement
1165 spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
1166 derive fields from other fields. Org-mode has two levels of complexity
1167 for table calculations. On the basic level, tables do only horizontal
1168 computations, so a field can be computed from other fields _in the same
1169 row_, and Org-mode assumes that there is only one formula for each
1170 column. This is very efficient to work with and enough for many tasks.
1171 On the complex level, columns and individual fields can be named for
1172 easier referencing in formulas, individual named fields can have their
1173 own formula associated with them, and recalculation can be automated.
1177 * Formula syntax:: How to write a formula
1178 * Lisp formulas:: An alternative way to write formulas
1179 * Column formulas:: Formulas valid for all fields in a column
1180 * Advanced features:: Field names, parameters and automatic recalc
1181 * Named-field formulas:: Formulas valid in single fields
1182 * Editing/debugging formulas:: Changing a stored formula
1183 * Appetizer:: Taste the power of calc
1186 File: org, Node: Formula syntax, Next: Lisp formulas, Prev: Table calculations, Up: Table calculations
1188 3.3.1 Formula syntax
1189 --------------------
1191 A formula can be any algebraic expression understood by the Emacs
1192 `calc' package. Note that `calc' has the slightly non-standard
1193 convention that `/' has lower precedence than `*', so that `a/b*c' is
1194 interpreted as `a/(b*c)'. Before evaluation by `calc-eval' (*note
1195 calc-eval: (calc)Calling Calc from Your Programs.), variable
1196 substitution takes place:
1198 $ refers to the current field
1199 $3 refers to the field in column 3 of the current row
1200 $3..$7 a vector of the fields in columns 3-7 of current row
1201 $P1..$P3 vector of column range, using column names
1202 &2 second data field above the current, in same column
1203 &5-2 vector from fifth to second field above current
1204 &III-II vector of fields between 2nd and 3rd hline above
1205 &III vector of fields between third hline above and current field
1206 $name a named field, parameter or constant
1208 The range vectors can be directly fed into the calc vector functions
1209 like `vmean' and `vsum'.
1211 `$name' is interpreted as the name of a column, parameter or
1212 constant. Constants are defined globally through the variable
1213 `org-table-formula-constants'. If you have the `constants.el' package,
1214 it will also be used to resolve constants, including natural constants
1215 like `$h' for Planck's constant, and units like `$km' for kilometers.
1216 Column names and parameters can be specified in special table lines.
1217 These are described below, see *Note Advanced features::.
1219 A formula can contain an optional mode string after a semicolon.
1220 This string consists of flags to influence calc's modes(1) during
1221 execution, e.g. `p20' to switch the internal precision to 20 digits,
1222 `n3', `s3', `e2' or `f4' to switch to normal, scientific, engineering,
1223 or fixed display format, respectively, and `D', `R', `F', and `S' to
1224 turn on degrees, radians, fraction and symbolic modes, respectively.
1225 In addition, you may provide a `printf' format specifier to reformat
1226 the final result. A few examples:
1228 $1+$2 Sum of first and second field
1229 $1+$2;%.2f Same, format result to two decimals
1230 exp($2)+exp($1) Math functions can be used
1231 $;%.1f Reformat current cell to 1 decimal
1232 ($3-32)*5/9 Degrees F -> C conversion
1233 $c/$1/$cm Hz -> cm conversion, using `constants.el'
1234 tan($1);Dp3s1 Compute in degrees, precision 3, display SCI 1
1235 sin($1);Dp3%.1e Same, but use printf specifier for display
1236 vmean($2..$7) Compute column range mean, using vector function
1237 vsum(&III) Sum numbers from 3rd hline above, up to here
1238 taylor($3,x=7,2) taylor series of $3, at x=7, second degree
1240 ---------- Footnotes ----------
1242 (1) By default, Org-mode uses the standard calc modes (precision 12,
1243 angular units degrees, fraction and symbolic modes off). The display
1244 format, however, has been changed to `(float 5)' to keep tables compact.
1245 The default settings can be configured using the variable
1246 `org-calc-default-modes'.
1249 File: org, Node: Lisp formulas, Next: Column formulas, Prev: Formula syntax, Up: Table calculations
1251 3.3.2 Emacs Lisp forms as formulas
1252 ----------------------------------
1254 It is also possible to write a formula in Emacs lisp; this can be useful
1255 for string manipulation and control structures. If a formula starts
1256 with a single quote followed by an opening parenthesis, then it is
1257 evaluated as a lisp form. The evaluation should return either a string
1258 or a number. Just as with `calc' formulas, you can provide a format
1259 specifier after a semicolon. A few examples:
1261 swap the first two characters of the content of column 1
1262 '(concat (substring "$1" 1 2) (substring "$1" 0 1) (substring "$1" 2))
1263 Add columns 1 and 2, equivalent to the calc's `$1+$2'
1267 File: org, Node: Column formulas, Next: Advanced features, Prev: Lisp formulas, Up: Table calculations
1269 3.3.3 Column formulas
1270 ---------------------
1272 To apply a formula to a field, type it directly into the field,
1273 preceded by an equal sign, like `=$1+$2'. When you press <TAB> or
1274 <RET> or `C-c C-c' with the cursor still in the field, the formula will
1275 be stored as the formula for the current column, evaluated and the
1276 current field replaced with the result. If the field contains only
1277 `=', the previously stored formula for this column is used.
1279 For each column, Org-mode will remember the most recently used
1280 formula. The information is stored in a special line starting with
1281 `#+TBLFM' directly below the table. When adding/deleting/moving
1282 columns with the appropriate commands, the stored equations will be
1283 modified accordingly. When a column used in a calculation is removed,
1284 references to this column become invalid and will cause an error upon
1285 applying the equation.
1287 Instead of typing an equation into the field, you may also use the
1288 command `C-c ='. It prompts for a formula (with default taken from the
1289 `#+TBLFM:' line) and applies it to the current field. A numerical
1290 prefix (e.g. `C-5 C-c =') will apply it to that many consecutive fields
1291 in the current column.
1293 To recompute all the fields in a line, use the command `C-c *'. It
1294 re-applies all stored equations to the current row, from left to right.
1295 With a `C-u' prefix, this will be done to every line in the table, so
1296 use this command it you want to make sure the entire table is
1297 up-to-date. `C-u C-c C-c' is another way to update the entire table.
1298 Global updating does not touch the line(s) above the first horizontal
1299 separator line, assuming that this is the table header.
1302 File: org, Node: Advanced features, Next: Named-field formulas, Prev: Column formulas, Up: Table calculations
1304 3.3.4 Advanced features
1305 -----------------------
1307 If you want the recalculation of fields to happen automatically, or if
1308 you want to be able to assign a formula to an individual field (instead
1309 of an entire column) you need to reserve the first column of the table
1310 for special marking characters. Here is an example of a table that
1311 collects exam results of students and makes use of these features:
1313 |---+---------+--------+--------+--------+-------+------|
1314 | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
1315 |---+---------+--------+--------+--------+-------+------|
1316 | ! | | P1 | P2 | P3 | Tot | |
1317 | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
1318 | ^ | | m1 | m2 | m3 | mt | |
1319 |---+---------+--------+--------+--------+-------+------|
1320 | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
1321 | # | Sara | 6 | 14 | 19 | 39 | 7.8 |
1322 | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
1323 |---+---------+--------+--------+--------+-------+------|
1324 | | Average | | | | 29.7 | |
1325 | ^ | | | | | at | |
1326 | $ | max=50 | | | | | |
1327 |---+---------+--------+--------+--------+-------+------|
1328 #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(&II);%.1f
1330 Important: Please note that for these special tables, recalculating the
1331 table with `C-u C-c *' will only affect rows that are marked `#' or
1332 `*', and named fields. The column formulas are not applied in rows
1333 with empty first field.
1335 The marking characters have the following meaning:
1337 The fields in this line define names for the columns, so that you
1338 may refer to a column as `$Tot' instead of `$6'.
1341 This row defines names for the fields _above_ the row. With such
1342 a definition, any formula in the table may use `$m1' to refer to
1343 the value `10'. Also, named fields can have their own formula
1344 associated with them.
1347 Similar to `^', but defines names for the fields in the row
1351 Fields in this row can define _parameters_ for formulas. For
1352 example, if a field in a `$' row contains `max=50', then formulas
1353 in this table can refer to the value 50 using `$max'. Parameters
1354 work exactly like constants, only that they can be defined on a
1355 per-table basis. Changing a parameter and then recalculating the
1356 table can be useful.
1359 Fields in this row are automatically recalculated when pressing
1360 <TAB> or <RET> or `S-<TAB>' in this row. Also, this row is
1361 selected for a global recalculation with `C-u C-c *'. Unmarked
1362 lines will be left alone by this command.
1365 Selects this line for global recalculation with `C-u C-c *', but
1366 not for automatic recalculation. Use this when automatic
1367 recalculation slows down editing too much.
1370 Unmarked lines are exempt from recalculation with `C-u C-c *'.
1371 All lines that should be recalculated should be marked with `#' or
1375 File: org, Node: Named-field formulas, Next: Editing/debugging formulas, Prev: Advanced features, Up: Table calculations
1377 3.3.5 Named-field formulas
1378 --------------------------
1380 A named field can have its own formula associated with it. In the
1381 example above, this is used for the `at' field that contains the
1382 average result of the students. To enter a formula for a named field,
1383 just type it into the buffer, preceded by `:='. Or use `C-u C-c ='.
1384 This equation will be stored below the table like `$name=...'. Any
1385 recalculation in the table (even if only requested for the current
1386 line) will also update all named field formulas.
1389 File: org, Node: Editing/debugging formulas, Next: Appetizer, Prev: Named-field formulas, Up: Table calculations
1391 3.3.6 Editing and debugging formulas
1392 ------------------------------------
1394 To edit a column or field formula, use the commands `C-c =' and `C-u
1395 C-c =', respectively. The currently active expression is then
1396 presented as default in the minibuffer, where it may be edited.
1398 Note that making a table field blank does not remove the formula
1399 associated with the field - during the next recalculation the field
1400 will be filled again. To remove a formula from a field, you have to
1401 give an empty reply when prompted for the formula, or to edit the
1404 You may edit the `#+TBLFM' directly and re-apply the changed
1405 equations with `C-c C-c' in that line, or with the normal recalculation
1406 commands in the table.
1408 In particular for large tables with many formulas, it is convenient
1409 to use the command `C-c '' to edit the formulas of the current table in
1410 a separate buffer. That buffer will show the formulas one per line,
1411 and you are free to edit, add and remove formulas. Press `C-c ?' on a
1412 `$...' expression to get information about its interpretation.
1413 Exiting the buffer with `C-c C-c' only stores the modified formulas
1414 below the table. Exiting with `C-u C-c C-c' also applies them to the
1415 entire table. `C-c C-q' exits without installing the changes.
1417 When the evaluation of a formula leads to an error, the field content
1418 becomes the string `#ERROR'. If you would like see what is going on
1419 during variable substitution and calculation in order to find a bug,
1420 turn on formula debugging in the menu and repeat the calculation, for
1421 example by pressing `C-c = <RET>' in a field. Detailed information
1425 File: org, Node: Appetizer, Prev: Editing/debugging formulas, Up: Table calculations
1430 Finally, just to whet your appetite on what can be done with the
1431 fantastic `calc' package, here is a table that computes the Taylor
1432 series for a couple of functions (homework: try that with Excel :-)
1434 |---+-------------+---+-----+--------------------------------------|
1435 | | Func | n | x | Result |
1436 |---+-------------+---+-----+--------------------------------------|
1437 | # | exp(x) | 1 | x | 1 + x |
1438 | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
1439 | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
1440 | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
1441 | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
1442 | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
1443 |---+-------------+---+-----+--------------------------------------|
1444 #+TBLFM: $5=taylor($2,$4,$3);n3
1447 File: org, Node: orgtbl-mode, Next: table.el, Prev: Table calculations, Up: Tables
1449 3.4 The Orgtbl minor mode
1450 =========================
1452 If you like the intuitive way the Org-mode table editor works, you
1453 might also want to use it in other modes like text-mode or mail-mode.
1454 The minor mode Orgtbl-mode makes this possible. You can always toggle
1455 the mode with `M-x orgtbl-mode'. To turn it on by default, for example
1458 (add-hook 'mail-mode-hook 'turn-on-orgtbl)
1461 File: org, Node: table.el, Prev: orgtbl-mode, Up: Tables
1463 3.5 The `table.el' package
1464 ==========================
1466 Complex ASCII tables with automatic line wrapping, column- and
1467 row-spanning, and alignment can be created using the Emacs table
1468 package by Takaaki Ota (`http://sourceforge.net/projects/table', and
1469 also part of Emacs 22). When <TAB> or `C-c C-c' is pressed in such a
1470 table, Org-mode will call `table-recognize-table' and move the cursor
1471 into the table. Inside a table, the keymap of Org-mode is inactive.
1472 In order to execute Org-mode-related commands, leave the table.
1475 Recognize `table.el' table. Works when the cursor is in a
1479 Insert a table.el table. If there is already a table at point,
1480 this command converts it between the table.el format and the
1481 Org-mode format. See the documentation string of the command
1482 `org-convert-table' for the restrictions under which this is
1486 File: org, Node: Hyperlinks, Next: TODO items, Prev: Tables, Up: Top
1491 Just like HTML, Org-mode provides links inside a file, and external
1492 links to other files, Usenet articles, emails, and much more.
1496 * Link format:: How links in Org-mode are formatted
1497 * Internal links:: Links to other places in the current file
1498 * External links:: URL-like links to the world
1499 * Handling links:: Creating, inserting and following
1500 * Link abbreviations:: Shortcuts for writing complex links
1501 * Search options:: Linking to a specific location
1502 * Custom searches:: When the default search is not enough
1503 * Remember:: Org-trees store quick notes
1506 File: org, Node: Link format, Next: Internal links, Prev: Hyperlinks, Up: Hyperlinks
1511 Org-mode will recognize plain URL-like links and activate them as
1512 clickable links. The general link format, however, looks like this:
1514 [[link][description]] or alternatively [[link]]
1516 Once a link in the buffer is complete (all brackets present),
1517 Org-mode will change the display so that `description' is displayed
1518 instead of `[[link][description]]' and `link' is displayed instead of
1519 `[[link]]'. Links will be highlighted in the face `org-link', which by
1520 default is an underlined face. You can directly edit the visible part
1521 of a link. Note that this can be either the `link' part (if there is
1522 no description) or the `description' part. To edit also the invisible
1523 `link' part, use `C-c C-l' with the cursor on the link.
1525 If you place the cursor at the beginning or just behind the end of
1526 the displayed text and press <BACKSPACE>, you will remove the
1527 (invisible) bracket at that location. This makes the link incomplete
1528 and the internals are again displayed as plain text. Inserting the
1529 missing bracket hides the link internals again. To show the internal
1530 structure of all links, use the menu entry `Org->Hyperlinks->Literal
1534 File: org, Node: Internal links, Next: External links, Prev: Link format, Up: Hyperlinks
1539 If the link does not look like a URL, it is considered to be internal in
1540 the current file. Links such as `[[My Target]]' or `[[My Target][Find
1541 my target]]' lead to a text search in the current file. The link can
1542 be followed with `C-c C-o' when the cursor is on the link, or with a
1543 mouse click (*note Handling links::). The preferred match for such a
1544 link is a dedicated target: the same string in double angular brackets.
1545 Targets may be located anywhere; often it is convenient to put them
1546 into a comment line. For example
1550 In HTML export (*note HTML export::), such targets will become named
1551 anchors for direct access through `http' links(1).
1553 If no dedicated target exists, Org-mode will search for the words in
1554 the link. In the above example the search would be for `my target'.
1555 Links starting with a star like `*My Target' restrict the search to
1556 headlines. When searching, Org-mode will first try an exact match, but
1557 then move on to more and more lenient searches. For example, the link
1558 `[[*My Targets]]' will find any of the following:
1561 ** TODO my targets are bright
1562 ** my 20 targets are
1564 To insert a link targeting a headline, in-buffer completion can be
1565 used. Just type a star followed by a few optional letters into the
1566 buffer and press `M-<TAB>'. All headlines in the current buffer will be
1567 offered as completions. *Note Handling links::, for more commands
1570 Following a link pushes a mark onto Org-mode's own mark ring. You
1571 can return to the previous position with `C-c &'. Using this command
1572 several times in direct succession goes back to positions recorded
1577 * Radio targets:: Make targets trigger links in plain text.
1578 * CamelCase links:: Activating CamelCase words as links
1580 ---------- Footnotes ----------
1582 (1) Note that text before the first headline will never be exported,
1583 so the first such target must be after the first headline.
1586 File: org, Node: Radio targets, Next: CamelCase links, Prev: Internal links, Up: Internal links
1591 You can configure Org-mode to link any occurrences of certain target
1592 names in normal text. So without explicitly creating a link, the text
1593 connects to the target radioing its position. Radio targets are
1594 enclosed by triple angular brackets. For example, a target `<<<My
1595 Target>>>' causes each occurrence of `my target' in normal text to
1596 become activated as a link. The Org-mode file is scanned automatically
1597 for radio targets only when the file is first loaded into Emacs. To
1598 update the target list during editing, press `C-c C-c' with the cursor
1602 File: org, Node: CamelCase links, Prev: Radio targets, Up: Internal links
1604 4.2.2 CamelCase words as links
1605 ------------------------------
1607 Org-mode also supports CamelCase words as links. This feature is not
1608 turned on by default because of the inconsistencies this system suffers
1609 from. It is also possible that this feature will disappear entirely in
1610 a future version of Org-mode. To activate CamelCase words as links, you
1611 need to customize the option `org-activate-links'. A CamelCase word
1612 then leads to a text search such that `CamelCaseLink' is equivalent to
1613 `[[camel case link]]'.
1616 File: org, Node: External links, Next: Handling links, Prev: Internal links, Up: Hyperlinks
1621 Org-mode supports links to files, websites, Usenet and email messages,
1622 and BBDB database entries. External links are URL-like locators. They
1623 start with a short identifying string followed by a colon. There can be
1624 no space after the colon. The following list shows examples for each
1627 http://www.astro.uva.nl/~dominik on the web
1628 file:/home/dominik/images/jupiter.jpg file, absolute path
1629 file:papers/last.pdf file, relative path
1630 news:comp.emacs Usenet link
1631 mailto:adent@galaxy.net Mail link
1632 vm:folder VM folder link
1633 vm:folder#id VM message link
1634 vm://myself@some.where.org/folder#id VM on remote machine
1635 wl:folder WANDERLUST folder link
1636 wl:folder#id WANDERLUST message link
1637 mhe:folder MH-E folder link
1638 mhe:folder#id MH-E message link
1639 rmail:folder RMAIL folder link
1640 rmail:folder#id RMAIL message link
1641 gnus:group GNUS group link
1642 gnus:group#id GNUS article link
1643 bbdb:Richard Stallman BBDB link
1644 shell:ls *.org A shell command
1645 elisp:(find-file-other-frame "Elisp.org") An elisp form to evaluate
1647 A link should be enclosed in double brackets and may contain a
1648 descriptive text to be displayed instead of the url (*note Link
1649 format::), for example:
1651 [[http://www.gnu.org/software/emacs/][GNU Emacs]]
1653 Org-mode also finds external links in the normal text and activates
1654 them as links. If spaces must be part of the link (for example in
1655 `bbdb:Richard Stallman'), or you need to remove ambiguities about the
1656 end of the link, enclose them in angular brackets.
1659 File: org, Node: Handling links, Next: Link abbreviations, Prev: External links, Up: Hyperlinks
1664 Org-mode provides methods to create a link in the correct syntax, to
1665 insert it into an org-mode file, and to follow the link.
1668 Store a link to the current location. This is a _global_ command
1669 which can be used in any buffer to create a link. The link will be
1670 stored for later insertion into an Org-mode buffer (see below).
1671 For Org-mode files, if there is a `<<target>>' at the cursor, the
1672 link points to the target. Otherwise it points to the current
1673 headline. For VM, RMAIL, WANDERLUST, MH-E, GNUS and BBDB buffers,
1674 the link will indicate the current article/entry. For W3 and W3M
1675 buffers, the link goes to the current URL. For any other files,
1676 the link will point to the file, with a search string (*note
1677 Search options::) pointing to the contents of the current line.
1678 If there is an active region, the selected words will form the
1679 basis of the search string. If the automatically created link is
1680 not working correctly or accurately enough, you can write custom
1681 functions to select the search string and to do the search for
1682 particular file types - see *Note Custom searches::. The key
1683 binding `C-c l' is only a suggestion - see *Note Installation::.
1686 Insert a link. This prompts for a link to be inserted into the
1687 buffer. You can just type a link, using text for an internal
1688 link, or one of the link type prefixes mentioned in the examples
1689 above. Through completion, all links stored during the current
1690 session can be accessed(1). The link will be inserted into the
1691 buffer, along with a descriptive text. Note that you don't have
1692 to use this command to insert a link. Links in Org-mode are plain
1693 text, and you can type or paste them straight into the buffer. By
1694 using this command, the links are automatically enclosed in double
1695 brackets, and you will be asked for the optional descriptive text.
1696 If the link is a `file:' link and the linked file is located in
1697 the same directory as the current file or a subdirectory of it, the
1698 path of the file will be inserted relative to the current
1702 When `C-c C-l' is called with a `C-u' prefix argument, a link to a
1703 file will be inserted and you may use file name completion to
1704 select the name of the file. The path to the file is inserted
1705 relative to the directory of the current org file, if the linked
1706 file is in the current directory or in a subdirectory of it, or if
1707 the path is written relative to the current directory using `../'.
1708 Otherwise an absolute path is used, if possible with `~/' for
1709 your home directory. You can force an absolute path with two
1712 `C-c C-l with cursor on existing link'
1713 When the cursor is on an existing link, `C-c C-l' allows you to
1714 edit the link and description parts of the link.
1717 Open link at point. This will launch a web browser for URLs (using
1718 `browse-url-at-point'), run vm/mh-e/wanderlust/rmail/gnus/bbdb for
1719 the corresponding links, and execute the command in a shell link.
1720 When the cursor is on an internal link, this commands runs the
1721 corresponding search. When the cursor is on a TAG list in a
1722 headline, it creates the corresponding TAGS view. If the cursor
1723 is on a time stamp, it compiles the agenda for that date.
1724 Furthermore, it will visit text and remote files in `file:' links
1725 with Emacs and select a suitable application for local non-text
1726 files. Classification of files is based on file extension only.
1727 See option `org-file-apps'. If you want to override the default
1728 application and visit the file with Emacs, use a `C-u' prefix.
1732 On links, `mouse-2' will open the link just as `C-c C-o' would.
1733 Under Emacs 22, also `mouse-1' will follow a link.
1736 Like `mouse-2', but force file links to be opened with Emacs, and
1737 internal links to be displayed in another window(2).
1740 Push the current position onto the mark ring, to be able to return
1741 easily. Commands following an internal link do this automatically.
1744 Jump back to a recorded position. A position is recorded by the
1745 commands following internal links, and by `C-c %'. Using this
1746 command several times in direct succession moves through a ring of
1747 previously recorded positions.
1749 ---------- Footnotes ----------
1751 (1) After insertion of a stored link, the link will be removed from
1752 the list of stored links. To keep it in the list later use, use a
1753 triple `C-u' prefix to `C-c C-l', or configure the option
1754 `org-keep-stored-link-after-insertion'.
1756 (2) See the variable `org-display-internal-link-with-indirect-buffer'
1759 File: org, Node: Link abbreviations, Next: Search options, Prev: Handling links, Up: Hyperlinks
1761 4.5 Link abbreviatons
1762 =====================
1764 Long URLs can be cumbersome to type, and often many similar links are
1765 needed in a document. For this you can use link abbreviations. An
1766 abbreviated link looks like this
1768 [[linkword::tag][description]]
1770 where the tag is optional. Such abbreviations are resolved according to
1771 the information in the variable `org-link-abbrev-alist' that relates
1772 the linkwords to replacement text. Here is an example:
1774 (setq org-link-abbrev-alist
1775 '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
1776 ("google" . "http://www.google.com/search?q=")
1777 ("ads" . "http://adsabs.harvard.edu/cgi-bin/
1778 nph-abs_connect?author=%s&db_key=AST")))
1780 If the replacement text contains the string `%s', it will be
1781 replaced with the tag. Otherwise the tag will be appended to the string
1782 in order to create the link. You may also specify a function that will
1783 be called with the tag as the only argument to create the link.
1785 With the above setting, you could link to a specific bug with
1786 `[[bugzilla::129]]', search the web for OrgMode with
1787 `[[google::OrgMode]]' and find out what the Org-mode author is doing
1788 besides Emacs hacking with `[[ads::Dominik,C]]'.
1790 If you need special abbreviations just for a single Org-mode buffer,
1791 you can define them in the file with
1793 #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
1794 #+LINK: google http://www.google.com/search?q=%s
1796 In-buffer completion *note Completion:: can be used after `[' to
1797 complete link abbreviations.
1800 File: org, Node: Search options, Next: Custom searches, Prev: Link abbreviations, Up: Hyperlinks
1802 4.6 Search options in file links
1803 ================================
1805 File links can contain additional information to make Emacs jump to a
1806 particular location in the file when following a link. This can be a
1807 line number or a search option after a double(1) colon. For example,
1808 when the command `C-c l' creates a link (*note Handling links::) to a
1809 file, it encodes the words in the current line as a search string that
1810 can be used to find this line back later when following the link with
1813 Here is the syntax of the different ways to attach a search to a file
1814 link, together with an explanation:
1816 [[file:~/code/main.c::255]]
1817 [[file:~/xx.org::My Target]]
1818 [[file:~/xx.org::*My Target]]
1819 [[file:~/xx.org::/regexp/]]
1825 Search for a link target `<<My Target>>', or do a text search for
1826 `my target', similar to the search in internal links, see *Note
1827 Internal links::. In HTML export (*note HTML export::), such a
1828 file link will become an HTML reference to the corresponding named
1829 anchor in the linked file.
1832 In an Org-mode file, restrict search to headlines.
1835 Do a regular expression search for `regexp'. This uses the Emacs
1836 command `occur' to list all matches in a separate window. If the
1837 target file is in Org-mode, `org-occur' is used to create a sparse
1838 tree with the matches.
1840 As a degenerate case, a file link with an empty file name can be used
1841 to search the current file. For example, `<file:::find me>' does a
1842 search for `find me' in the current file, just as `[[find me]]' would.
1844 ---------- Footnotes ----------
1846 (1) For backward compatibility, line numbers can also follow a
1850 File: org, Node: Custom searches, Next: Remember, Prev: Search options, Up: Hyperlinks
1855 The default mechanism for creating search strings and for doing the
1856 actual search related to a file link may not work correctly in all
1857 cases. For example, BibTeX database files have many entries like
1858 `year="1993"' which would not result in good search strings, because
1859 the only unique identification for a BibTeX entry is the citation key.
1861 If you come across such a problem, you can write custom functions to
1862 set the right search string for a particular file type, and to do the
1863 search for the string in the file. Using `add-hook', these functions
1864 need to be added to the hook variables
1865 `org-create-file-search-functions' and
1866 `org-execute-file-search-functions'. See the docstring for these
1867 variables for more information. Org-mode actually uses this mechanism
1868 for BibTeX database files, and you can use the corresponding code as an
1869 implementation example. Search for `BibTeX links' in the source file.
1872 File: org, Node: Remember, Prev: Custom searches, Up: Hyperlinks
1877 Another way to create org entries with links to other files is through
1878 the _Remember_ package by John Wiegley. _Remember_ lets you store
1879 quick notes with little interruption of your work flow. See
1880 `http://www.emacswiki.org/cgi-bin/wiki/RememberMode' for more
1881 information. The notes produced by _Remember_ can be stored in
1882 different ways, and Org-mode files are a good target. Org-mode allows
1883 you to file away notes either to a default file, or directly to the
1884 correct location in your Org-mode outline tree. The following
1885 customization will tell _Remember_ to use org files as target, and to
1886 create annotations compatible with Org-mode links.
1888 (setq org-directory "~/path/to/my/orgfiles/")
1889 (setq org-default-notes-file "~/.notes")
1890 (setq remember-annotation-functions '(org-remember-annotation))
1891 (setq remember-handler-functions '(org-remember-handler))
1892 (add-hook 'remember-mode-hook 'org-remember-apply-template)
1894 In combination with Org-mode, you can use templates to generate
1895 different types of remember notes. For example, if you would like to
1896 use one template to create general TODO entries, and another one for
1897 journal entries, you could use:
1899 (setq org-remember-templates
1900 '((?t "* TODO %?\n %i\n %a" "~/org/TODO.org")
1901 (?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org")))
1903 In these entries, the character specifies how to select the template,
1904 the first string specifies the template, and the (optional) second
1905 string specifies a default file (overruling `org-default-notes-file')
1906 as a target for this note.
1908 When you call `M-x remember' to remember something, org will prompt
1909 for a key to select the template and then prepare the buffer like
1911 <file:link to where you called remember>
1915 * [2006-03-21 Tue 15:37]
1917 <file:link to where you called remember>
1919 See the variable `org-remember-templates' for more details.
1921 When you are finished composing a note with remember, you have to
1922 press `C-c C-c' to file the note away. The handler first prompts for a
1923 target file - if you press <RET>, the value of `org-default-notes-file'
1924 is used. Then the command offers the headings tree of the selected
1925 file. You can either immediately press <RET> to get the note appended
1926 to the file. Or you can use vertical cursor motion (<up> and <down>)
1927 and visibility cycling (<TAB>) to find a better place. Pressing <RET>
1928 or <left> or <right> leads to the following result.
1930 Cursor Key Note gets inserted
1932 buffer-start <RET> as level 2 heading at end of file
1933 on headline <RET> as sublevel of the heading at cursor
1934 <left> as same level, before current heading
1935 <right> as same level, after current heading
1936 not on <RET> at cursor position, level taken from context.
1937 headline Or use prefix arg to specify level
1940 So a fast way to store the note is to press `C-c C-c <RET> <RET>' to
1941 append it to the default file. Even shorter would be `C-u C-c C-c',
1942 which does the same without even showing the tree. But with little
1943 extra effort, you can push it directly to the correct location.
1945 Before inserting the text into a tree, the function ensures that the
1946 text has a headline, i.e. a first line that starts with a `*'. If not,
1947 a headline is constructed from the current date and some additional
1948 data. If the variable `org-adapt-indentation' is non-nil, the entire
1949 text is also indented so that it starts in the same column as the
1950 headline (after the asterisks).
1953 File: org, Node: TODO items, Next: Timestamps, Prev: Hyperlinks, Up: Top
1958 Org-mode does not maintain TODO lists as a separate document. TODO
1959 items are an integral part of the notes file, because TODO items
1960 usually come up while taking notes! With Org-mode, you simply mark any
1961 entry in a tree as being a TODO item. In this way, the information is
1962 not duplicated, and the entire context from which the item emerged is
1963 always present when you check.
1965 Of course, this technique causes TODO items to be scattered
1966 throughout your file. Org-mode provides methods to give you an
1967 overview over all things you have to do.
1971 * TODO basics:: Marking and displaying TODO entries
1972 * TODO extensions:: Workflow and assignments
1973 * Priorities:: Some things are more important than others
1974 * Breaking down tasks:: Splitting a task into managable pieces
1975 * Checkboxes:: Tick-off lists
1978 File: org, Node: TODO basics, Next: TODO extensions, Prev: TODO items, Up: TODO items
1980 5.1 Basic TODO functionality
1981 ============================
1983 Any headline can become a TODO item by starting it with the word TODO,
1986 *** TODO Write letter to Sam Fortune
1988 The most important commands to work with TODO entries are:
1991 Rotate the TODO state of the current item between
1993 ,-> (unmarked) -> TODO -> DONE --.
1994 '--------------------------------'
1996 The same rotation can also be done "remotely" from the timeline and
1997 agenda buffers with the `t' command key (*note Agenda commands::).
2001 Select the following/preceding TODO state, similar to cycling.
2002 Mostly useful if more than two TODO states are possible (*note
2006 View TODO items in a _sparse tree_ (*note Sparse trees::). Folds
2007 the entire buffer, but shows all TODO items and the headings
2008 hierarchy above them. With prefix arg, show also the DONE
2009 entries. With numerical prefix N, show the tree for the Nth
2010 keyword in the variable `org-todo-keywords'.
2013 Show the global TODO list. This collects the TODO items from all
2014 agenda files (*note Agenda views::) into a single buffer. The
2015 buffer is in `agenda-mode', so there are commands to examine and
2016 manipulate the TODO entries directly from that buffer (*note
2017 Agenda commands::). *Note Global TODO list::, for more
2021 File: org, Node: TODO extensions, Next: Priorities, Prev: TODO basics, Up: TODO items
2023 5.2 Extended use of TODO keywords
2024 =================================
2026 The default implementation of TODO entries is just two states: TODO and
2027 DONE. You can, however, use the TODO feature for more complicated
2028 things by configuring the variables `org-todo-keywords' and
2029 `org-todo-interpretation'. Using special setup, you can even use TODO
2030 keywords in different ways in different org files.
2032 Note that tags are another way to classify headlines in general and
2033 TODO items in particular (*note Tags::).
2037 * Workflow states:: From TODO to DONE in steps
2038 * TODO types:: I do this, Fred the rest
2039 * Per file keywords:: Different files, different requirements
2042 File: org, Node: Workflow states, Next: TODO types, Prev: TODO extensions, Up: TODO extensions
2044 5.2.1 TODO keywords as workflow states
2045 --------------------------------------
2047 You can use TODO keywords to indicate different states in the process
2048 of working on an item, for example:
2050 (setq org-todo-keywords '("TODO" "FEEDBACK" "VERIFY" "DONE")
2051 org-todo-interpretation 'sequence)
2053 Changing these variables only becomes effective in a new Emacs
2054 session. With this setup, the command `C-c C-t' will cycle an entry
2055 from TODO to FEEDBACK, then to VERIFY, and finally to DONE. You may
2056 also use a prefix argument to quickly select a specific state. For
2057 example `C-3 C-c C-t' will change the state immediately to VERIFY. If
2058 you define many keywords, you can use in-buffer completion (see *Note
2059 Completion::) to insert these words into the buffer.
2062 File: org, Node: TODO types, Next: Per file keywords, Prev: Workflow states, Up: TODO extensions
2064 5.2.2 TODO keywords as types
2065 ----------------------------
2067 The second possibility is to use TODO keywords to indicate different
2068 types of action items. For example, you might want to indicate that
2069 items are for "work" or "home". If you are into David Allen's _Getting
2070 Things DONE_, you might want to use todo types `NEXTACTION', `WAITING',
2071 `MAYBE'. Or, when you work with several people on a single project,
2072 you might want to assign action items directly to persons, by using
2073 their names as TODO keywords. This would be set up like this:
2075 (setq org-todo-keywords '("Fred" "Sara" "Lucy" "Mike" "DONE")
2076 org-todo-interpretation 'type)
2078 In this case, different keywords do not indicate a sequence, but
2079 rather different types. So it is normally not useful to change from
2080 one type to another. Therefore, in this case the behavior of the
2081 command `C-c C-t' is changed slightly(1). When used several times in
2082 succession, it will still cycle through all names. But when you return
2083 to the item after some time and execute `C-c C-t' again, it will switch
2084 from each name directly to DONE. Use prefix arguments or completion to
2085 quickly select a specific name. You can also review the items of a
2086 specific TODO type in a sparse tree by using a numeric prefix to `C-c
2087 C-v'. For example, to see all things Lucy has to do, you would use
2088 `C-3 C-c C-v'. To collect Lucy's items from all agenda files into a
2089 single buffer, you would use the prefix arg as well when creating the
2090 global todo list: `C-3 C-c t'.
2092 ---------- Footnotes ----------
2094 (1) This is also true for the `t' command in the timeline and agenda
2098 File: org, Node: Per file keywords, Prev: TODO types, Up: TODO extensions
2100 5.2.3 Setting up TODO keywords for individual files
2101 ---------------------------------------------------
2103 It can be very useful to use different aspects of the TODO mechanism in
2104 different files, which is not possible with the global settings
2105 described above. For file-local settings, you need to add special
2106 lines to the file which set the keywords and interpretation for that
2107 file only. For example, to set one of the two examples discussed
2108 above, you need one of the following lines, starting in column zero
2109 anywhere in the file:
2111 #+SEQ_TODO: TODO FEEDBACK VERIFY DONE
2112 #+TYP_TODO: Fred Sara Lucy Mike DONE
2114 To make sure you are using the correct keyword, type `#+' into the
2115 buffer and then use `M-<TAB>' completion.
2117 Remember that the last keyword must always mean that the item is DONE
2118 (although you may use a different word). Also note that in each file,
2119 only one of the two aspects of TODO keywords can be used. After
2120 changing one of these lines, use `C-c C-c' with the cursor still in the
2121 line to make the changes known to Org-mode(1).
2123 If you want to use very many keywords, for example when working with
2124 a large group of people, you may split the names over several lines:
2126 #+TYP_TODO: Fred Sara Lucy Mike
2127 #+TYP_TODO: Luis George Jules Jessica
2128 #+TYP_TODO: Kim Arnold Peter
2131 ---------- Footnotes ----------
2133 (1) Org-mode parses these lines only when Org-mode is activated
2134 after visiting a file. `C-c C-c' with the cursor in a line starting
2135 with `#+' is simply restarting Org-mode for the current buffer.
2138 File: org, Node: Priorities, Next: Breaking down tasks, Prev: TODO extensions, Up: TODO items
2143 If you use Org-mode extensively to organize your work, you may end up
2144 with a number of TODO entries so large that you'd like to prioritize
2145 them. This can be done by placing a _priority cookie_ into the
2148 *** TODO [#A] Write letter to Sam Fortune
2150 With its standard setup, Org-mode supports priorities `A', `B', and
2151 `C'. `A' is the highest priority. An entry without a cookie is
2152 treated as priority `B'. Priorities make a difference only in the
2153 agenda (*note Weekly/Daily agenda::).
2156 Set the priority of the current headline. The command prompts for
2157 a priority character `A', `B' or `C'. When you press <SPC>
2158 instead, the priority cookie is removed from the headline. The
2159 priorities can also be changed "remotely" from the timeline and
2160 agenda buffer with the `,' command (*note Agenda commands::).
2164 Increase/decrease priority of current headline. Note that these
2165 keys are also used to modify time stamps (*note Creating
2166 timestamps::). Furthermore, these keys are also used by CUA-mode
2167 (*note Conflicts::).
2170 File: org, Node: Breaking down tasks, Next: Checkboxes, Prev: Priorities, Up: TODO items
2172 5.4 Breaking tasks down into subtasks
2173 =====================================
2175 It is often advisable to break down large tasks into smaller, managable
2176 subtasks. You can do this by creating an outline tree below a TODO
2177 item, with detailed subtasks on the tree(1). Another possibility is
2178 the use of checkboxes to identify (a hierarchy of) a large number of
2179 subtasks (*note Checkboxes::).
2181 ---------- Footnotes ----------
2183 (1) To keep subtasks out of the global TODO list, see the
2184 `org-agenda-todo-list-sublevels'.
2187 File: org, Node: Checkboxes, Prev: Breaking down tasks, Up: TODO items
2192 Every item in a plain list (*note Plain lists::) can be made a checkbox
2193 by starting it with the string `[ ]'. This feature is similar to TODO
2194 items (*note TODO items::), but more lightweight. Checkboxes are not
2195 included into the global TODO list, so they are often great to split a
2196 task into a number of simple steps. Or you can use them in a shopping
2197 list. To toggle a checkbox, use `C-c C-c', or try Piotr Zielinski's
2198 `org-mouse.el'. Here is an example of a checkbox list.
2200 * TODO Organize party [3/6]
2206 - [ ] think about what music to play
2207 - [X] talk to the neighbors
2209 The `[3/6]' and `[1/3]' in the first and second line are cookies
2210 indicating how many checkboxes are present in this entry, and how many
2211 of them have been checked off. This can give you an idea on how many
2212 checkboxes remain, even without opening a folded entry. The cookies
2213 can be placed into a headline or into (the first line of) a plain list
2214 item. Each cookie covers all checkboxes structurally below that
2215 headline/item. You have to insert the cookie yourself by typing either
2216 `[/]' or `[%]'. In the first case you get an `n out of m' result, in
2217 the second case you get information about the percentage of checkboxes
2218 checked (in the above example, this would be `[50%]' and `[33%],
2221 The following commands work with checkboxes:
2224 Toggle checkbox at point.
2227 Toggle checkbox at point.
2228 - If there is an active region, toggle the first checkbox in
2229 the region and set all remaining boxes to the same status as
2230 the first. If you want to toggle all boxes in the region
2231 independently, use a prefix argument.
2233 - If the cursor is in a headline, toggle checkboxes in the
2234 region between this headline and the next (so _not_ the
2237 - If there is no active region, just toggle the checkbox at
2241 Insert a new item with a checkbox. This works only if the cursor
2242 is already in a plain list item (*note Plain lists::).
2245 Update the checkbox statistics in the current outline entry. When
2246 called with a `C-u' prefix, update the entire file. Checkbox
2247 statistic cookies are updated automatically if you toggle
2248 checkboxes with `C-c C-c' and make new ones with `M-S-<RET>'. If
2249 you delete boxes or add/change them by hand, use this command to
2250 get things back into synch. Or simply toggle any checkbox twice
2254 File: org, Node: Timestamps, Next: Tags, Prev: TODO items, Up: Top
2259 Items can be labeled with timestamps to make them useful for project
2264 * Time stamps:: Assigning a time to a tree entry
2265 * Creating timestamps:: Commands which insert timestamps
2266 * Custom time format:: If you cannot work with the ISO format
2267 * Progress logging:: Documenting when what work was done.
2270 File: org, Node: Time stamps, Next: Creating timestamps, Prev: Timestamps, Up: Timestamps
2272 6.1 Time stamps, deadlines and scheduling
2273 =========================================
2275 A time stamp is a specification of a date (possibly with time) in a
2276 special format, either `<2003-09-16 Tue>' or `<2003-09-16 Tue
2277 09:39>'(1). A time stamp can appear anywhere in the headline or body
2278 of an org-tree entry. Its presence allows entries to be shown on
2279 specific dates in the agenda (*note Weekly/Daily agenda::). We
2283 A simple time stamp just assigns a date/time to an item. This is
2284 just like writing down an appointment in a paper agenda, or like
2285 writing down an event in a diary, when you want to take note of
2286 when something happened. In the timeline and agenda displays, the
2287 headline of an entry associated with a plain time stamp will be
2288 shown exactly on that date.
2290 * Meet Peter at the movies <2006-11-01 Wed 19:15>
2293 Just like a plain time stamp, but with square brackets instead of
2294 angular ones. These time stamps are inactive in the sense that
2295 they do _not_ trigger an entry to show up in the agenda.
2297 * Gillian comes late for the fifth time [2006-11-01 Wed]
2300 Two time stamps connected by `--' denote a time range. The
2301 headline will be shown on the first and last day of the range, and
2302 on any dates that are displayed and fall in the range. Here is an
2305 ** Meeting in Amsterdam
2306 <2004-08-23 Mon>--<2004-08-26 Thu>
2308 TIME STAMP WITH SCHEDULED KEYWORD
2309 If a time stamp is preceded by the word `SCHEDULED:', it means you
2310 are planning to start working on that task on the given date. So
2311 this is not about recording an event, but about planning your
2312 work. The headline will be listed under the given date. In
2313 addition, a reminder that the scheduled date has passed will be
2314 present in the compilation for _today_, until the entry is marked
2315 DONE. I.e., the task will automatically be forwarded until
2318 *** TODO Call Trillian for a date on New Years Eve.
2319 SCHEDULED: <2004-12-25 Sat>
2321 TIME STAMP WITH DEADLINE KEYWORD
2322 If a time stamp is preceded by the word `DEADLINE:', the task
2323 (most likely a TODO item) is supposed to be finished on that date,
2324 and it will be listed then. In addition, the compilation for
2325 _today_ will carry a warning about the approaching or missed
2326 deadline, starting `org-deadline-warning-days' before the due
2327 date, and continuing until the entry is marked DONE. An example:
2329 *** TODO write article about the Earth for the Guide
2330 The editor in charge is <bbdb:Ford Prefect>
2331 DEADLINE: <2004-02-29 Sun>
2333 TIME STAMP WITH CLOSED KEYWORD
2334 When `org-log-done' is non-nil, Org-mode will automatically insert
2335 a special time stamp each time a TODO entry is marked done (*note
2336 Progress logging::). This time stamp is enclosed in square
2337 brackets instead of angular brackets.
2339 TIME RANGE WITH CLOCK KEYWORD
2340 When using the clock to time the work that is being done on
2341 specific items, time ranges preceded by the CLOCK keyword are
2342 inserted automatically into the file. The time stamps are
2343 enclosed in square brackets instead of angular brackets. *Note
2344 Clocking work time::.
2346 ---------- Footnotes ----------
2348 (1) This is the standard ISO date/time format. If you cannot get
2349 used to these, see *Note Custom time format::
2352 File: org, Node: Creating timestamps, Next: Custom time format, Prev: Time stamps, Up: Timestamps
2354 6.2 Creating timestamps
2355 =======================
2357 For Org-mode to recognize time stamps, they need to be in the specific
2358 format. All commands listed below produce time stamps in the correct
2362 Prompt for a date and insert a corresponding time stamp. When the
2363 cursor is at a previously used time stamp, it is updated to NOW.
2364 When this command is used twice in succession, a time range is
2368 Like `C-c .', but use the alternative format which contains date
2369 and time. The default time can be rounded to multiples of 5
2370 minutes, see the option `org-time-stamp-rounding-minutes'.
2373 Like `C-c .', but insert an inactive time stamp not triggering the
2377 Insert a time stamp corresponding to the cursor date in the
2381 Access the Emacs calendar for the current date. If there is a
2382 timestamp in the current line, goto the corresponding date instead.
2385 Access the agenda for the date given by the time stamp or -range at
2386 point (*note Weekly/Daily agenda::).
2389 Insert `DEADLINE' keyword along with a stamp. The insertion will
2390 happen in the line directly following the headline.
2393 Create a sparse tree with all deadlines that are either past-due,
2394 or which will become due within `org-deadline-warning-days'. With
2395 `C-u' prefix, show all deadlines in the file. With a numeric
2396 prefix, check that many days. For example, `C-1 C-c C-w' shows
2397 all deadlines due tomorrow.
2400 Insert `SCHEDULED' keyword along with a stamp. The insertion will
2401 happen in the line directly following the headline. Any CLOSED
2402 timestamp will be removed.
2406 Change date at cursor by one day. These key bindings conflict with
2407 CUA-mode (*note Conflicts::).
2411 Change the item under the cursor in a timestamp. The cursor can
2412 be on a year, month, day, hour or minute. Note that if the cursor
2413 is in a headline and not at a time stamp, these same keys modify
2414 the priority of an item. (*note Priorities::). The key bindings
2415 also conflict with CUA-mode (*note Conflicts::).
2418 Evaluate a time range by computing the difference between start and
2419 end. With prefix arg, insert result after the time range (in a
2420 table: into the following column).
2424 * The date/time prompt:: How org-mode helps you entering date and time
2427 File: org, Node: The date/time prompt, Prev: Creating timestamps, Up: Creating timestamps
2429 6.2.1 The date/time prompt
2430 --------------------------
2432 When Org-mode prompts for a date/time, the prompt suggests to enter an
2433 ISO date. But it will in fact accept any string containing some date
2434 and/or time information. You can, for example, use `C-y' to paste a
2435 (possibly multi-line) string copied from an email message. Org-mode
2436 will find whatever information is in there and will replace anything not
2437 specified with the current date and time. For example:
2439 3-2-5 --> 2003-02-05
2440 feb 15 --> currentyear-02-15
2441 sep 12 9 --> 2009-09-12
2442 12:45 --> today 12:45
2443 22 sept 0:34 --> currentyear-09-22 0:34
2444 12 --> currentyear-currentmonth-12
2445 Fri --> nearest Friday (today or later)
2447 The function understands English month and weekday abbreviations. If
2448 you want to use unabbreviated names and/or other languages, configure
2449 the variables `parse-time-months' and `parse-time-weekdays'.
2451 Parallel to the minibuffer prompt, a calendar is popped up(1). You
2452 can control the calendar fully from the minibuffer:
2455 Scroll calendar backwards by one month.
2458 Scroll calendar forwards by one month.
2461 Select date by clicking on it.
2482 Choose date in calendar (only if nothing was typed into
2485 ---------- Footnotes ----------
2487 (1) If you don't need/want the calendar, configure the variable
2488 `org-popup-calendar-for-date-prompt'.
2491 File: org, Node: Custom time format, Next: Progress logging, Prev: Creating timestamps, Up: Timestamps
2493 6.3 Custom time format
2494 ======================
2496 Org-mode uses the standard ISO notation for dates and times as it is
2497 defined in ISO 8601. If you cannot get used to this and require another
2498 representation of date and time to keep you happy, you can get it by
2499 customizing the variables `org-display-custom-times' and
2500 `org-time-stamp-custom-formats'.
2503 Toggle the display of custom formats for dates and times.
2505 Org-mode needs the default format for scanning, so the custom date/time
2506 format does not _replace_ the default format - instead it is put _over_
2507 the default format using text properties. This has the following
2509 * You cannot place the cursor onto a time stamp anymore, only before
2512 * The `S-<up>/<down>' keys can no longer be used to adjust each
2513 component of a time stamp. If the cursor is at the beginning of
2514 the stamp, `S-<up>/<down>' will change the stamp by one day, just
2515 like `S-<left>/<right>'. At the end of the stamp, the time will
2516 be changed by one minute.
2518 * When you delete a time stamp character-by-character, it will only
2519 disappear from the buffer after _all_ (invisible) characters
2520 belonging to the ISO timestamp have been removed.
2522 * If the custom time stamp format is longer than the default and you
2523 are using dates in tables, table alignment will be messed up. If
2524 the custom format is shorter, things do work as expected.
2527 File: org, Node: Progress logging, Prev: Custom time format, Up: Timestamps
2529 6.4 Progress Logging
2530 ====================
2532 Org-mode can automatically record a time stamp when you mark a TODO item
2533 as DONE. You can also measure precisely the time you spent on specific
2534 items in a project by starting and stopping a clock when you start and
2535 stop working on an aspect of a project.
2539 * Closing items:: When was this entry marked DONE?
2540 * Clocking work time:: When exactly did you work on this item?
2543 File: org, Node: Closing items, Next: Clocking work time, Prev: Progress logging, Up: Progress logging
2548 If you want to keep track of _when_ a certain TODO item was finished,
2549 turn on logging with
2551 (setq org-log-done t)
2553 Then each time you turn a TODO entry into DONE using either `C-c C-t'
2554 in the Org-mode buffer or `t' in the agenda buffer, a line `CLOSED:
2555 [timestamp]' will be inserted just after the headline. If you turn the
2556 entry back into a TODO item again through further state cycling, that
2557 line will be removed again. In the timeline (*note Timeline::) and in
2558 the agenda (*note Weekly/Daily agenda::), you can then use the `l' key
2559 to display the TODO items closed on each day, giving you an overview of
2560 what has been done on a day. See the variable `org-log-done' for the
2561 possibility to record an additional note together with a timestamp.
2564 File: org, Node: Clocking work time, Prev: Closing items, Up: Progress logging
2566 6.4.2 Clocking work time
2567 ------------------------
2569 Org-mode allows you to clock the time you spent on specific tasks in a
2570 project. When you start working on an item, you can start the clock.
2571 When you stop working on that task, or when you mark the task done, the
2572 clock is stopped and the corresponding time interval is recorded. It
2573 also computes the total time spent on each subtree of a project.
2576 Start the clock on the current item (clock-in). This inserts the
2577 CLOCK keyword together with a timestamp.
2580 Stop the clock (clock-out). The inserts another timestamp at the
2581 same location where the clock was last started. It also directly
2582 computes the resulting time in inserts it after the time range as
2583 `=> HH:MM'. See the variable `org-log-done' for the possibility to
2584 record an additional note together with the clock-out time stamp.
2587 Recompute the time interval after changing one of the time stamps.
2588 This is only necessary if you edit the time stamps directly. If
2589 you change them with `S-<cursor>' keys, the update is automatic.
2592 Changing the TODO state of an item to DONE automatically stops the
2593 clock if it is running in this same item.
2596 Cancel the current clock. This is useful if a clock was started by
2597 mistake, or if you ended up working on something else.
2600 Display time summaries for each subtree in the current buffer.
2601 This puts overlays at the end of each headline, showing the total
2602 time recorded under that heading, including the time of any
2603 subheadings. You can use visibility cycling to study the tree, but
2604 the overlays disappear when you change the buffer (see variable
2605 `org-remove-highlights-with-change') or press `C-c C-c'.
2608 Insert a dynamic block (*note Dynamic blocks::) containing a clock
2609 report as an org-mode table into the current file.
2610 #+BEGIN: clocktable :maxlevel 2 :emphasize nil
2613 If such a block already exists, its content is replaced by the new
2614 table. The `BEGIN' line can specify options:
2615 :maxlevels Maximum level depth to which times are listed in the table.
2616 :emphasize When `t', emphasize level one and level two items
2617 :block The time block to consider. This block is specified relative
2618 to the current time and may be any of these keywords:
2619 `today', `yesterday', `thisweek', `lastweek',
2620 `thismonth', `lastmonth', `thisyear', or `lastyear'.
2621 :tstart A time string specifying when to start considering times
2622 :tend A time string specifying when to stop considering times
2623 So to get a clock summary for the current day, you could write
2624 #+BEGIN: clocktable :maxlevel 2 :block today
2627 and to use a specific time range you could write(1)
2628 #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
2629 :tend "<2006-08-10 Thu 12:00>"
2634 Update all dynamic blocks (*note Dynamic blocks::). This is
2635 useful if you have several clocktable blocks in a buffer.
2637 The `l' key may be used in the timeline (*note Timeline::) and in
2638 the agenda (*note Weekly/Daily agenda::) to show which tasks have been
2639 worked on or closed during a day.
2641 ---------- Footnotes ----------
2643 (1) Note that all parameters must be specified in a single line -
2644 the line is broken here only to fit it onto the manual.
2647 File: org, Node: Tags, Next: Agenda views, Prev: Timestamps, Up: Top
2652 If you wish to implement a system of labels and contexts for
2653 cross-correlating information, an excellent way is to assign tags to
2654 headlines. Org-mode has extensive support for using tags.
2656 Every headline can contain a list of tags, at the end of the
2657 headline. Tags are normal words containing letters, numbers, `_', and
2658 `@'. Tags must be preceded and followed by a single colon; like
2659 `:WORK:'. Several tags can be specified like `:WORK:URGENT:'.
2663 * Tag inheritance:: Tags use the tree structure of the outline
2664 * Setting tags:: How to assign tags to a headline
2665 * Tag searches:: Searching for combinations of tags
2668 File: org, Node: Tag inheritance, Next: Setting tags, Prev: Tags, Up: Tags
2673 Tags make use of the hierarchical structure of outline trees. If a
2674 heading has a certain tag, all subheadings will inherit the tag as
2675 well. For example, in the list
2677 * Meeting with the French group :WORK:
2678 ** Summary by Frank :BOSS:NOTES:
2679 *** TODO Prepare slides for him :ACTION:
2681 the final heading will have the tags `:WORK:', `:BOSS:', `:NOTES:', and
2682 `:ACTION:'. When executing tag searches and Org-mode finds that a
2683 certain headline matches the search criterion, it will not check any
2684 sublevel headline, assuming that these likely also match, and that the
2685 list of matches can become very long. This may not be what you want,
2686 however, and you can influence inheritance and searching using the
2687 variables `org-use-tag-inheritance' and `org-tags-match-list-sublevels'.
2690 File: org, Node: Setting tags, Next: Tag searches, Prev: Tag inheritance, Up: Tags
2695 Tags can simply be typed into the buffer at the end of a headline.
2696 After a colon, `M-<TAB>' offers completion on tags. There is also a
2697 special command for inserting tags:
2700 Enter new tags for the current headline. Org-mode will either
2701 offer completion or a special single-key interface for setting
2702 tags, see below. After pressing <RET>, the tags will be inserted
2703 and aligned to `org-tags-column'. When called with a `C-u'
2704 prefix, all tags in the current buffer will be aligned to that
2705 column, just to make things look nice. TAGS are automatically
2706 realigned after promotion, demotion, and TODO state changes (*note
2709 Org will support tag insertion based on a _list of tags_. By
2710 default this list is constructed dynamically, containing all tags
2711 currently used in the buffer. You may also globally specify a hard list
2712 of tags with the variable `org-tag-alist'. Finally you can set the
2713 default tags for a given file with lines like
2715 #+TAGS: @WORK @HOME @TENNISCLUB
2716 #+TAGS: Laptop Car PC Sailboat
2718 If you have globally defined your preferred set of tags using the
2719 variable `org-tag-alist', but would like to use a dynamic tag list in a
2720 specific file: Just add an empty TAGS option line to that file:
2724 The default support method for entering tags is minibuffer
2725 completion. However, Org-mode also implements a much better method:
2726 _fast tag selection_. This method allows to select and deselect tags
2727 with a single key per tag. To function efficiently, you should assign
2728 unique keys to most tags. This can be done globally with
2730 (setq org-tag-alist '(("@WORK" . ?w) ("@HOME" . ?h) ("Laptop" . ?l)))
2732 or on a per-file basis with
2734 #+TAGS: @WORK(w) @HOME(h) @TENNISCLUB(t) Laptop(l) PC(p)
2736 You can also group together tags that are mutually exclusive. With
2739 #+TAGS: { @WORK(w) @HOME(h) @TENNISCLUB(t) } Laptop(l) PC(p)
2741 you indicate that at most one of `@WORK', `@HOME', and `@TENNISCLUB'
2744 Don't forget to press `C-c C-c' with the cursor in one of these lines
2745 to activate any changes.
2747 If at least one tag has a selection key, pressing `C-c C-c' will
2748 automatically present you with a special interface, listing inherited
2749 tags, the tags of the current headline, and a list of all legal tags
2750 with corresponding keys(2). In this interface, you can use the
2754 Pressing keys assigned to tags will add or remove them from the
2755 list of tags in the current line. Selecting a tag in a group of
2756 mutually exclusive tags will turn off any other tags from that
2760 Enter a tag in the minibuffer, even if the tag is not in the
2761 predefined list. You will be able to complete on all tags present
2765 Clear all tags for this line.
2768 Accept the modified set.
2771 Abort without installing changes.
2774 If `q' is not assigned to a tag, it aborts like `C-g'.
2777 Turn off groups of mutually exclusive tags. Use this to (as an
2778 exception) assign several tags from such a group.
2781 Toggle auto-exit after the next change (see below).
2783 This method lets you assign tags to a headline with very few keys. With
2784 the above setup, you could clear the current tags and set `@HOME',
2785 `Laptop' and `PC' tags with just the following keys: `C-c C-c <SPC> h l
2786 p <RET>'. Switching from `@HOME' to `@WORK' would be done with `C-c
2787 C-c w <RET>' or alternatively with `C-c C-c C-c w'. Adding the
2788 non-predefined tag `Sarah' could be done with `C-c C-c <TAB> S a r a h
2791 If you find that most of the time, you need only a single keypress to
2792 modify your list of tags, set the variable
2793 `org-fast-tag-selection-single-key'. Then you no longer have to press
2794 <RET> to exit fast tag selection - it will immediately exit after the
2795 first change. If you then occasionally need more keys, press `C-c' to
2796 turn off auto-exit for the current tag selection process.
2798 ---------- Footnotes ----------
2800 (1) In `org-mode-alist' use `'(:startgroup)' and `'(:endgroup)',
2801 respectively. Several groups are allowed.
2803 (2) Keys will automatically be assigned to tags which have no
2807 File: org, Node: Tag searches, Prev: Setting tags, Up: Tags
2812 Once a tags system has been set up, it can be used to collect related
2813 information into special lists.
2816 Create a sparse tree with all headlines matching a tags search.
2819 Create a global list of tag matches from all agenda files. *Note
2820 Matching headline tags::.
2823 Create a global list of tag matches from all agenda files, but
2824 check only TODO items and force checking subitems (see variable
2825 `org-tags-match-list-sublevels').
2827 A tags search string can use Boolean operators `&' for AND and `|'
2828 for OR. `&' binds more strongly than `|'. Parenthesis are currently
2829 not implemented. A tag may also be preceded by `-', to select against
2830 it, and `+' is syntactic sugar for positive selection. The AND
2831 operator `&' is optional when `+' or `-' is present. Examples:
2834 Select all headlines that are tagged `:WORK:', but discard those
2835 also tagged `:BOSS:'.
2838 Selects lines tagged `:WORK:' or `:LAPTOP:'.
2841 Like the previous example, but require the `:LAPTOP:' lines to be
2842 tagged also `NIGHT'.
2844 If you are using multi-state TODO keywords (*note TODO
2845 extensions::), it can be useful to also match on the TODO keyword.
2846 This can be done by adding a condition after a slash to a tags match.
2847 The syntax is similar to the tag matches, but should be applied with
2848 consideration: For example, a positive selection on several TODO
2849 keywords can not meaningfully be combined with boolean AND. However,
2850 _negative selection_ combined with AND can be meaningful. Examples:
2853 Select `:WORK:'-tagged TODO lines with the specific TODO keyword
2856 `WORK/-WAITING-NEXT'
2857 Select `:WORK:'-tagged TODO lines that are neither `WAITING' nor
2860 `WORK/+WAITING|+NEXT'
2861 Select `:WORK:'-tagged TODO lines that are either `WAITING' or
2865 File: org, Node: Agenda views, Next: Embedded LaTeX, Prev: Tags, Up: Top
2870 Due to the way Org-mode works, TODO items, time-stamped items, and
2871 tagged headlines can be scattered throughout a file or even a number of
2872 files. To get an overview over open action items, or over events that
2873 are important for a particular date, this information must be collected,
2874 sorted and displayed in an organized way.
2876 Org-mode can select items based on various criteria, and display them
2877 in a separate buffer. Five different view types are provided:
2879 * an _agenda_ that is like a calendar and shows information for
2882 * a _TODO list_ that covers all unfinished action items,
2884 * a _tags view_ that shows information based on the tags associated
2885 with headlines in the outline tree,
2887 * a _timeline view_ that shows all events in a single Org-mode file,
2890 * _custom views_ that are special tag and keyword searches and
2891 combinations of different views.
2893 The extracted information is displayed in a special _agenda buffer_.
2894 This buffer is read-only, but provides commands to visit the
2895 corresponding locations in the original Org-mode files, and even to
2896 edit these files remotely.
2898 Two variables control how the agenda buffer is displayed and whether
2899 the window configuration is restored when the agenda exits:
2900 `org-agenda-window-setup' and `org-agenda-restore-windows-after-quit'.
2904 * Agenda files:: Files being searched for agenda information
2905 * Agenda dispatcher:: Keyboard access to agenda views
2906 * Weekly/Daily agenda:: The calendar page with current tasks
2907 * Global TODO list:: All unfinished action items
2908 * Matching headline tags:: Structured information with fine-tuned search
2909 * Timeline:: Time-sorted view for single file
2910 * Presentation and sorting:: How agenda items are prepared for display
2911 * Agenda commands:: Remote editing of org trees
2912 * Custom agenda views:: Defining special searches and views
2915 File: org, Node: Agenda files, Next: Agenda dispatcher, Prev: Agenda views, Up: Agenda views
2920 The information to be shown is collected from all _agenda files_, the
2921 files listed in the variable `org-agenda-files'(1). Thus even if you
2922 only work with a single Org-mode file, this file should be put into
2923 that list(2). You can customize `org-agenda-files', but the easiest
2924 way to maintain it is through the following commands
2927 Add current file to the list of agenda files. The file is added to
2928 the front of the list. If it was already in the list, it is moved
2929 to the front. With prefix arg, file is added/moved to the end.
2932 Remove current file from the list of agenda files.
2935 Cycle through agenda file list, visiting one file after the other.
2937 The Org menu contains the current list of files and can be used to
2940 ---------- Footnotes ----------
2942 (1) If the value of that variable is not a list, but a single file
2943 name, then the list of agenda files will be maintained in that external
2946 (2) When using the dispatcher, pressing `1' before selecting a
2947 command will actually limit the command to the current file, and ignore
2948 `org-agenda-files' until the next dispatcher command.
2951 File: org, Node: Agenda dispatcher, Next: Weekly/Daily agenda, Prev: Agenda files, Up: Agenda views
2953 8.2 The agenda dispatcher
2954 =========================
2956 The views are created through a dispatcher that should be bound to a
2957 global key, for example `C-c a' (*note Installation::). In the
2958 following we will assume that `C-c a' is indeed how the dispatcher is
2959 accessed and list keyboard access to commands accordingly. After
2960 pressing `C-c a', an additional letter is required to execute a
2961 command. The dispatcher offers the following default commands:
2963 Create the calendar-like agenda (*note Weekly/Daily agenda::).
2966 Create a list of all TODO items (*note Global TODO list::).
2969 Create a list of headlines matching a TAGS expression (*note
2970 Matching headline tags::).
2973 Create the timeline view for the current buffer (*note Timeline::).
2976 Restrict an agenda command to the current buffer. After pressing
2977 `1', you still need to press the character selecting the command.
2980 If there is an active region, restrict the following agenda
2981 command to the region. Otherwise, restrict it to the current
2982 subtree. After pressing `0', you still need to press the
2983 character selecting the command.
2985 You can also define custom commands that will be accessible through
2986 the dispatcher, just like the default commands. This includes the
2987 possibility to create extended agenda buffers that contain several
2988 blocks together, for example the weekly agenda, the global TODO list and
2989 a number of special tags matches. *Note Custom agenda views::.
2992 File: org, Node: Weekly/Daily agenda, Next: Global TODO list, Prev: Agenda dispatcher, Up: Agenda views
2994 8.3 The weekly/daily agenda
2995 ===========================
2997 The purpose of the weekly/daily _agenda_ is to act like a page of a
2998 paper agenda, showing all the tasks for the current week or day.
3001 Compile an agenda for the current week from a list of org files.
3002 The agenda shows the entries for each day. With a `C-u' prefix (or
3003 when the variable `org-agenda-include-all-todo' is `t'), all
3004 unfinished TODO items (including those without a date) are also
3005 listed at the beginning of the buffer, before the first date.
3007 Remote editing from the agenda buffer means, for example, that you
3008 can change the dates of deadlines and appointments from the agenda
3009 buffer. The commands available in the Agenda buffer are listed in
3010 *Note Agenda commands::.
3014 * Calendar/Diary integration:: Integrating Anniversaries and more
3017 File: org, Node: Calendar/Diary integration, Prev: Weekly/Daily agenda, Up: Weekly/Daily agenda
3019 8.3.1 Calendar/Diary integration
3020 --------------------------------
3022 Emacs contains the calendar and diary by Edward M. Reingold. The
3023 calendar displays a three-month calendar with holidays from different
3024 countries and cultures. The diary allows you to keep track of
3025 anniversaries, lunar phases, sunrise/set, recurrent appointments
3026 (weekly, monthly) and more. In this way, it is quite complementary to
3027 Org-mode. It can be very useful to combine output from Org-mode with
3030 In order to include entries from the Emacs diary into Org-mode's
3031 agenda, you only need to customize the variable
3033 (setq org-agenda-include-diary t)
3035 After that, everything will happen automatically. All diary entries
3036 including holidays, anniversaries etc will be included in the agenda
3037 buffer created by Org-mode. <SPC>, <TAB>, and <RET> can be used from
3038 the agenda buffer to jump to the diary file in order to edit existing
3039 diary entries. The `i' command to insert new entries for the current
3040 date works in the agenda buffer, as well as the commands `S', `M', and
3041 `C' to display Sunrise/Sunset times, show lunar phases and to convert
3042 to other calendars, respectively. `c' can be used to switch back and
3043 forth between calendar and agenda.
3046 File: org, Node: Global TODO list, Next: Matching headline tags, Prev: Weekly/Daily agenda, Up: Agenda views
3048 8.4 The global TODO list
3049 ========================
3051 The global TODO list contains all unfinished TODO items, formatted and
3052 collected into a single place.
3055 Show the global TODO list. This collects the TODO items from all
3056 agenda files (*note Agenda views::) into a single buffer. The
3057 buffer is in `agenda-mode', so there are commands to examine and
3058 manipulate the TODO entries directly from that buffer (*note
3062 Like the above, but allows selection of a specific TODO keyword.
3063 You can also do this by specifying a prefix argument to `C-c a t'.
3064 With a `C-u' prefix you are prompted for a keyword. With a
3065 numeric prefix, the Nth keyword in `org-todo-keywords' is selected. The
3066 `r' key in the agenda buffer regenerates it, and you can give a
3067 prefix argument to this command to change the selected TODO
3068 keyword, for example `3 r'. If you often need a search for a
3069 specific keyword, define a custom command for it (*note Agenda
3071 Matching specific TODO keywords can also be done as part of a tags
3072 search (*note Tag searches::).
3074 Remote editing of TODO items means that you can change the state of a
3075 TODO entry with a single key press. The commands available in the TODO
3076 list are described in *Note Agenda commands::.
3078 Normally the global todo list simply shows all headlines with TODO
3079 keywords. This list can become very long. There are two ways to keep
3081 - Some people view a TODO item that has been _scheduled_ for
3082 execution (*note Time stamps::) as no longer _open_. Configure the
3083 variable `org-agenda-todo-ignore-scheduled' to exclude scheduled
3084 items from the global TODO list.
3086 - TODO items may have sublevels to break up the task into subtasks.
3087 In such cases it may be enough to list only the highest level TODO
3088 headline and omit the sublevels from the global list. Configure
3089 the variable `org-agenda-todo-list-sublevels' to get this behavior.
3092 File: org, Node: Matching headline tags, Next: Timeline, Prev: Global TODO list, Up: Agenda views
3094 8.5 Matching headline tags
3095 ==========================
3097 If headlines in the agenda files are marked with _tags_ (*note Tags::),
3098 you can select headlines based on the tags that apply to them and
3099 collect them into an agenda buffer.
3102 Produce a list of all headlines that match a given set of tags.
3103 The command prompts for a selection criterion, which is a boolean
3104 logic expression with tags, like `+WORK+URGENT-WITHBOSS' or
3105 `WORK|HOME' (*note Tags::). If you often need a specific search,
3106 define a custom command for it (*note Agenda dispatcher::).
3109 Like `C-c a m', but only select headlines that are also TODO items
3110 and force checking subitems (see variable
3111 `org-tags-match-list-sublevels'). Matching specific todo keywords
3112 together with a tags match is also possible, see *Note Tag
3115 The commands available in the tags list are described in *Note
3119 File: org, Node: Timeline, Next: Presentation and sorting, Prev: Matching headline tags, Up: Agenda views
3121 8.6 Timeline for a single file
3122 ==============================
3124 The timeline summarizes all time-stamped items from a single Org-mode
3125 file in a _time-sorted view_. The main purpose of this command is to
3126 give an overview over events in a project.
3129 Show a time-sorted view of the org file, with all time-stamped
3130 items. When called with a `C-u' prefix, all unfinished TODO
3131 entries (scheduled or not) are also listed under the current date.
3133 The commands available in the timeline buffer are listed in *Note
3137 File: org, Node: Presentation and sorting, Next: Agenda commands, Prev: Timeline, Up: Agenda views
3139 8.7 Presentation and sorting
3140 ============================
3142 Before displaying items in an agenda view, Org-mode visually prepares
3143 the items and sorts them. Each item occupies a single line. The line
3144 starts with a _prefix_ that contains the _category_ (*note
3145 Categories::) of the item and other important information. You can
3146 customize the prefix using the option `org-agenda-prefix-format'. The
3147 prefix is followed by a cleaned-up version of the outline headline
3148 associated with the item.
3152 * Categories:: Not all tasks are equal
3153 * Time-of-day specifications:: How the agenda knows the time
3154 * Sorting of agenda items:: The order of things
3157 File: org, Node: Categories, Next: Time-of-day specifications, Prev: Presentation and sorting, Up: Presentation and sorting
3162 The category is a broad label assigned to each agenda item. By default,
3163 the category is simply derived from the file name, but you can also
3164 specify it with a special line in the buffer, like this:
3168 If there are several such lines in a file, each specifies the
3169 category for the text below it (but the first category also applies to
3170 any text before the first CATEGORY line). The display in the agenda
3171 buffer looks best if the category is not longer than 10 characters.
3174 File: org, Node: Time-of-day specifications, Next: Sorting of agenda items, Prev: Categories, Up: Presentation and sorting
3176 8.7.2 Time-of-Day Specifications
3177 --------------------------------
3179 Org-mode checks each agenda item for a time-of-day specification. The
3180 time can be part of the time stamp that triggered inclusion into the
3181 agenda, for example as in `<2005-05-10 Tue 19:00>'. Time ranges can be
3182 specified with two time stamps, like
3183 `<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>'.
3185 In the headline of the entry itself, a time(range) may also appear as
3186 plain text (like `12:45' or a `8:30-1pm'. If the agenda integrates the
3187 Emacs diary (*note Calendar/Diary integration::), time specifications
3188 in diary entries are recognized as well.
3190 For agenda display, Org-mode extracts the time and displays it in a
3191 standard 24 hour format as part of the prefix. The example times in
3192 the previous paragraphs would end up in the agenda like this:
3194 8:30-13:00 Arthur Dent lies in front of the bulldozer
3195 12:45...... Ford Prefect arrives and takes Arthur to the pub
3196 19:00...... The Vogon reads his poem
3197 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
3199 If the agenda is in single-day mode, or for the display of today, the
3200 timed entries are embedded in a time grid, like
3202 8:00...... ------------------
3203 8:30-13:00 Arthur Dent lies in front of the bulldozer
3204 10:00...... ------------------
3205 12:00...... ------------------
3206 12:45...... Ford Prefect arrives and takes Arthur to the pub
3207 14:00...... ------------------
3208 16:00...... ------------------
3209 18:00...... ------------------
3210 19:00...... The Vogon reads his poem
3211 20:00...... ------------------
3212 20:30-22:15 Marwin escorts the Hitchhikers to the bridge
3214 The time grid can be turned on and off with the variable
3215 `org-agenda-use-time-grid', and can be configured with
3216 `org-agenda-time-grid'.
3219 File: org, Node: Sorting of agenda items, Prev: Time-of-day specifications, Up: Presentation and sorting
3221 8.7.3 Sorting of agenda items
3222 -----------------------------
3224 Before being inserted into a view, the items are sorted. How this is
3225 done depends on the type of view.
3226 * For the daily/weekly agenda, the items for each day are sorted.
3227 The default order is to first collect all items containing an
3228 explicit time-of-day specification. These entries will be shown
3229 at the beginning of the list, as a _schedule_ for the day. After
3230 that, items remain grouped in categories, in the sequence given by
3231 `org-agenda-files'. Within each category, items are sorted by
3232 priority (*note Priorities::), which is composed of the base
3233 priority (2000 for priority `A', 1000 for `B', and 0 for `C'),
3234 plus additional increments for overdue scheduled or deadline items.
3236 * For the TODO list, items remain in the order of categories, but
3237 within each category, sorting takes place according to priority
3238 (*note Priorities::).
3240 * For tags matches, items are not sorted at all, but just appear in
3241 the sequence in which they are found in the agenda files.
3243 Sorting can be customized using the variable
3244 `org-agenda-sorting-strategy'.
3247 File: org, Node: Agenda commands, Next: Custom agenda views, Prev: Presentation and sorting, Up: Agenda views
3249 8.8 Commands in the agenda buffer
3250 =================================
3252 Entries in the agenda buffer are linked back to the org file or diary
3253 file where they originate. You are not allowed to edit the agenda
3254 buffer itself, but commands are provided to show and jump to the
3255 original entry location, and to edit the org-files "remotely" from the
3256 agenda buffer. In this way, all information is stored only once,
3257 removing the risk that your agenda and note files may diverge.
3259 Some commands can be executed with mouse clicks on agenda lines. For
3260 the other commands, the cursor needs to be in the desired line.
3266 Next line (same as <up>).
3269 Previous line (same as <down>).
3276 Display the original location of the item in another window.
3279 Display original location and recenter that window.
3284 Go to the original location of the item in another window. Under
3285 Emacs 22, `mouse-1' will also works for this.
3288 Go to the original location of the item and delete other windows.
3291 Toggle Follow mode. In Follow mode, as you move the cursor through
3292 the agenda buffer, the other window always shows the corresponding
3293 location in the org file. The initial setting for this mode in new
3294 agenda buffers can be set with the variable
3295 `org-agenda-start-with-follow-mode'.
3298 Toggle Logbook mode. In Logbook mode, entries that where marked
3299 DONE while logging was on (variable `org-log-done') are shown in
3300 the agenda, as are entries that have been clocked on that day.
3306 Delete other windows.
3309 Switch to weekly view (7 days displayed together).
3312 Switch to daily view (just one day displayed).
3315 Toggle the inclusion of diary entries. See *Note Calendar/Diary
3319 Toggle the time grid on and off. See also the variables
3320 `org-agenda-use-time-grid' and `org-agenda-time-grid'.
3323 Recreate the agenda buffer, for example to reflect the changes
3324 after modification of the time stamps of items with S-<left> and
3325 S-<right>. When the buffer is the global todo list, a prefix
3326 argument is interpreted to create a selective list for a specific
3330 Save all Org-mode buffers in the current Emacs session.
3333 Display the following `org-agenda-ndays' days. For example, if
3334 the display covers a week, switch to the following week. With
3335 prefix arg, go forward that many times `org-agenda-ndays' days.
3338 Display the previous dates.
3350 Change the TODO state of the item, both in the agenda and in the
3354 Delete the current agenda item along with the entire subtree
3355 belonging to it in the original Org-mode file. If the text to be
3356 deleted remotely is longer than one line, the kill needs to be
3357 confirmed by the user. See variable `org-agenda-confirm-kill'.
3360 Show all tags associated with the current item. Because of
3361 inheritance, this may be more than the tags listed in the line
3365 Set tags for the current headline.
3368 Toggle the ARCHIVE tag for the current headline.
3371 Set the priority for the current item. Org-mode prompts for the
3372 priority character. If you reply with <SPC>, the priority cookie
3373 is removed from the entry.
3376 Display weighted priority of current item.
3380 Increase the priority of the current item. The priority is
3381 changed in the original buffer, but the agenda is not resorted.
3382 Use the `r' key for this.
3386 Decrease the priority of the current item.
3392 Set a deadline for this item.
3395 Change the time stamp associated with the current line by one day
3396 into the future. With prefix argument, change it by that many
3397 days. For example, `3 6 5 S-<right>' will change it by a year.
3398 The stamp is changed in the original org file, but the change is
3399 not directly reflected in the agenda buffer. Use the `r' key to
3403 Change the time stamp associated with the current line by one day
3407 Change the time stamp associated with the current line to today.
3408 The key `>' has been chosen, because it is the same as `S-.' on my
3412 Start the clock on the current item. If a clock is running
3413 already, it is stopped first.
3416 Stop the previously started clock.
3419 Cancel the currently running clock.
3425 Open the Emacs calendar and move to the date at the agenda cursor.
3428 When in the calendar, compute and show the Org-mode agenda for the
3432 Insert a new entry into the diary. Prompts for the type of entry
3433 (day, weekly, monthly, yearly, anniversary, cyclic) and creates a
3434 new entry in the diary, just as `i d' etc. would do in the
3435 calendar. The date is taken from the cursor position.
3438 Show the phases of the moon for the three months around current
3442 Show sunrise and sunset times. The geographical location must be
3443 set with calendar variables, see documentation of the Emacs
3447 Convert the date at cursor into many other cultural and historic
3451 Show holidays for three month around the cursor date.
3454 Export a single iCalendar file containing entries from all agenda
3461 Quit agenda, remove the agenda buffer.
3464 Exit agenda, remove the agenda buffer and all buffers loaded by
3465 Emacs for the compilation of the agenda. Buffers created by the
3466 user to visit org files will not be removed.
3470 File: org, Node: Custom agenda views, Prev: Agenda commands, Up: Agenda views
3472 8.9 Custom agenda views
3473 =======================
3475 Custom agenda commands serve two purposes: to store and quickly access
3476 frequently used TODO and tags searches, and to create special composite
3477 agenda buffers. Custom agenda commands will be accessible through the
3478 dispatcher (*note Agenda dispatcher::), just like the default commands.
3482 * Storing searches:: Type once, use often
3483 * Block agenda:: All the stuff you need in a single buffer
3484 * Setting Options:: Changing the rules
3485 * Batch processing:: Agenda views from the command line
3488 File: org, Node: Storing searches, Next: Block agenda, Prev: Custom agenda views, Up: Custom agenda views
3490 8.9.1 Storing searches
3491 ----------------------
3493 The first application of custom searches is the definition of keyboard
3494 shortcuts for frequently used searches, either creating an agenda
3495 buffer, or a sparse tree (the latter covering of course only the current
3496 buffer). Custom commands are configured in the variable
3497 `org-agenda-custom-commands'. You can customize this variable, for
3498 example by pressing `C-c a C'. You can also directly set it with Emacs
3499 Lisp in `.emacs'. The following example contains all valid search
3502 (setq org-agenda-custom-commands
3503 '(("w" todo "WAITING")
3504 ("W" todo-tree "WAITING")
3505 ("u" tags "+BOSS-URGENT")
3506 ("v" tags-todo "+BOSS-URGENT")
3507 ("U" tags-tree "+BOSS-URGENT")
3508 ("f" occur-tree "\\<FIXME\\>")))
3510 The initial single-character string in each entry defines the character
3511 you have to press after the dispatcher command `C-c a' in order to
3512 access the command. The second parameter is the search type, followed
3513 by the string or regular expression to be used for the matching. The
3514 example above will therefore define:
3517 as a global search for TODO entries with `WAITING' as the TODO
3521 as the same search, but only in the current buffer and displaying
3522 the results as a sparse tree
3525 as a global tags search for headlines marked `:BOSS:' but not
3529 as the same search as `C-c a u', but limiting the search to
3530 headlines that are also TODO items
3533 as the same search as `C-c a u', but only in the current buffer and
3534 displaying the result as a sparse tree
3537 to create a sparse tree (again: current buffer only) with all
3538 entries containing the word `FIXME'.
3541 File: org, Node: Block agenda, Next: Setting Options, Prev: Storing searches, Up: Custom agenda views
3546 Another possibility is the construction of agenda views that comprise
3547 the results of _several_ commands, each of which creates a block in the
3548 agenda buffer. The available commands include `agenda' for the daily
3549 or weekly agenda (as created with `C-c a a'), `alltodo' for the global
3550 todo list (as constructed with `C-c a t'), and the matching commands
3551 discussed above: `todo', `tags', and `tags-todo'. Here are two
3554 (setq org-agenda-custom-commands
3555 '(("h" "Agenda and Home-related tasks"
3559 ("o" "Agenda and Office-related tasks"
3564 This will define `C-c a h' to create a multi-block view for stuff you
3565 need to attend to at home. The resulting agenda buffer will contain
3566 your agenda for the current week, all TODO items that carry the tag
3567 `HOME', and also all lines tagged with `GARDEN'. Finally the command
3568 `C-c a o' provides a similar view for office tasks.
3571 File: org, Node: Setting Options, Next: Batch processing, Prev: Block agenda, Up: Custom agenda views
3573 8.9.3 Setting Options for custom commands
3574 -----------------------------------------
3576 Org-mode contains a number of variables regulating agenda construction
3577 and display. The global variables define the behavior for all agenda
3578 commands, including the custom commands. However, if you want to change
3579 some settings just for a single custom view, you can do so. Setting
3580 options requires inserting a list of variable names and values at the
3581 right spot in `org-agenda-custom-commands'. For example:
3583 (setq org-agenda-custom-commands
3584 '(("w" todo "WAITING"
3585 ((org-agenda-sorting-strategy '(priority-down))
3586 (org-agenda-prefix-format " Mixed: ")))
3587 ("U" tags-tree "+BOSS-URGENT"
3588 ((org-show-following-heading nil)
3589 (org-show-hierarchy-above nil)))))
3591 Now the `C-c a w' command will sort the collected entries only by
3592 priority, and the prefix format is modified to just say ` Mixed:'
3593 instead of giving the category of the entry. The sparse tags tree of
3594 `C-c a U' will now turn out ultra-compact, because neither the headline
3595 hierarchy above the match, nor the headline following the match will be
3598 For command sets creating a block agenda,
3599 `org-agenda-custom-commands' has two separate spots for setting
3600 options. You can add options that should be valid for just a single
3601 command in the set, and options that should be valid for all commands in
3602 the set. The former are just added to the command entry, the latter
3603 must come after the list of command entries. Going back to the block
3604 agenda example (*note Block agenda::), let's change the sorting strategy
3605 for the `C-c a h' commands to `priority-down', but let's sort the
3606 results for GARDEN tags query in the opposite order, `priority-up'.
3607 This would look like this:
3609 (setq org-agenda-custom-commands
3610 '(("h" "Agenda and Home-related tasks"
3613 (tags "GARDEN" ((org-agenda-sorting-strategy '(priority-up)))))
3614 ((org-agenda-sorting-strategy '(priority-down))))
3615 ("o" "Agenda and Office-related tasks"
3620 As you see, the values and parenthesis setting is a little complex.
3621 When in doubt, use the customize interface to set this variable - it
3622 fully supports its structure. Just one caveat: When setting options in
3623 this interface, the _values_ are just lisp expressions. So if the
3624 value is a string, you need to add the double quotes around the value
3628 File: org, Node: Batch processing, Prev: Setting Options, Up: Custom agenda views
3630 8.9.4 Creating agenda views in batch processing
3631 -----------------------------------------------
3633 If you want to print or otherwise reprocess agenda views, it can be
3634 useful to create an agenda from the command line. This is the purpose
3635 of the function `org-batch-agenda'. It takes as a parameter one of the
3636 strings that are the keys in `org-agenda-custom-commands'. For
3637 example, to directly print the current TODO list, you could use
3639 emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
3641 You may also modify parameters on the fly like this:
3643 emacs -batch -l ~/.emacs \
3644 -eval '(org-batch-agenda "a" \
3645 org-agenda-ndays 300 \
3646 org-agenda-include-diary nil \
3647 org-agenda-files (quote ("~/org/project.org")))' \
3650 which will produce a 300 day agenda, fully restricted to the Org file
3651 `~/org/projects.org', not even including the diary.
3654 File: org, Node: Embedded LaTeX, Next: Exporting, Prev: Agenda views, Up: Top
3659 Plain ASCII is normally sufficient for almost all note taking. One
3660 exception, however, are scientific notes which need to be able to
3661 contain mathematical symbols and the occasional formula. LaTeX(1) is
3662 widely used to typeset scientific documents. Org-mode supports
3663 embedding LaTeX code into its files, because many academics are used to
3664 read LaTeX source code, and because it can be readily processed into
3665 images for HTML production.
3667 It is not necessary to mark LaTeX macros and code in any special way.
3668 If you observe a few conventions, Org-mode knows how to find it and what
3673 * Math symbols:: TeX macros for symbols and Greek letters
3674 * Subscripts and Superscripts:: Simple syntax for raising/lowering text
3675 * LaTeX fragments:: Complex formulas made easy
3676 * Processing LaTeX fragments:: Previewing LaTeX processing
3677 * CDLaTeX mode:: Speed up entering of formulas
3679 ---------- Footnotes ----------
3681 (1) LaTeX is a macro system based on Donald E. Knuth's TeX system.
3682 Many of the features described here as "LaTeX" are really from TeX, but
3683 for simplicity I am blurring this distinction.
3686 File: org, Node: Math symbols, Next: Subscripts and Superscripts, Prev: Embedded LaTeX, Up: Embedded LaTeX
3691 You can use LaTeX macros to insert special symbols like `\alpha' to
3692 indicate the Greek letter, or `\to' to indicate an arrow. Completion
3693 for these macros is available, just type `\' and maybe a few letters,
3694 and press `M-<TAB>' to see possible completions. Unlike LaTeX code,
3695 Org-mode allows these macros to be present without surrounding math
3696 delimiters, for example:
3698 Angles are written as Greek letters \alpha, \beta and \gamma.
3700 During HTML export (*note HTML export::), these symbols are
3701 translated into the proper syntax for HTML, for the above examples this
3702 is `α' and `→', respectively.
3705 File: org, Node: Subscripts and Superscripts, Next: LaTeX fragments, Prev: Math symbols, Up: Embedded LaTeX
3707 9.2 Subscripts and Superscripts
3708 ===============================
3710 Just like in LaTeX, `^' and `_' are used to indicate super- and
3711 subscripts. Again, these can be used without embedding them in
3712 math-mode delimiters. To increase the readability of ASCII text, it is
3713 not necessary (but OK) to surround multi-character sub- and superscripts
3714 with curly braces. For example
3716 The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of
3717 the sun is R_{sun} = 6.96 x 10^8 m.
3719 To avoid interpretation as raised or lowered text, you can quote `^'
3720 and `_' with a backslash: `\_' and `\^'.
3722 During HTML export (*note HTML export::), subscript and superscripts
3723 are surrounded with `<sub>' and `<sup>' tags, respectively.
3726 File: org, Node: LaTeX fragments, Next: Processing LaTeX fragments, Prev: Subscripts and Superscripts, Up: Embedded LaTeX
3731 With symbols, sub- and superscripts, HTML is pretty much at its end when
3732 it comes to representing mathematical formulas(1). More complex
3733 expressions need a dedicated formula processor. To this end, Org-mode
3734 can contain arbitrary LaTeX fragments. It provides commands to preview
3735 the typeset result of these fragments, and upon export to HTML, all
3736 fragments will be converted to images and inlined into the HTML
3737 document. For this to work you need to be on a system with a working
3738 LaTeX installation. You also need the `dvipng' program, available at
3739 `http://sourceforge.net/projects/dvipng/'.
3741 LaTeX fragments don't need any special marking at all. The following
3742 snippets will be identified as LaTeX source code:
3743 * Environments of any kind. The only requirement is that the
3744 `\begin' statement appears on a new line, preceded by only
3747 * Text within the usual LaTeX math delimiters. To avoid conflicts
3748 with currency specifications, single `$' characters are only
3749 recognized as math delimiters if the enclosed text contains at
3750 most two line breaks, is directly attached to the `$' characters
3751 with no whitespace in between, and if the closing `$' is followed
3752 by whitespace or punctuation. For the other delimiters, there is
3753 no such restriction, so when in doubt, use `\(...\)' as inline
3758 \begin{equation} % arbitrary environments,
3759 x=\sqrt{b} % even tables, figures
3760 \end{equation} % etc
3762 If $a^2=b$ and \( b=2 \), then the solution must be
3763 either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].
3765 If you need any of the delimiter ASCII sequences for other purposes, you
3766 can configure the option `org-format-latex-options' to deselect the
3767 ones you do not wish to have interpreted by the LaTeX converter.
3769 ---------- Footnotes ----------
3771 (1) Yes, there is MathML, but that is not yet fully supported by
3772 many browsers, and there is no decent converter for turning LaTeX of
3773 ASCII representations of formulas into MathML. So for the time being,
3774 converting formulas into images seems the way to go.
3777 File: org, Node: Processing LaTeX fragments, Next: CDLaTeX mode, Prev: LaTeX fragments, Up: Embedded LaTeX
3779 9.4 Processing LaTeX fragments
3780 ==============================
3782 LaTeX fragments can be processed to produce a preview images of the
3783 typeset expressions:
3786 Produce a preview image of the LaTeX fragment at point and overlay
3787 it over the source code. If there is no fragment at point,
3788 process all fragments in the current entry (between two
3789 headlines). When called with a prefix argument, process the
3790 entire subtree. When called with two prefix arguments, or when
3791 the cursor is before the first headline, process the entire buffer.
3794 Remove the overlay preview images.
3796 During HTML export (*note HTML export::), all LaTeX fragments are
3797 converted into images and inlined into the document if the following
3800 (setq org-export-with-LaTeX-fragments t)
3803 File: org, Node: CDLaTeX mode, Prev: Processing LaTeX fragments, Up: Embedded LaTeX
3805 9.5 Using CDLaTeX to enter math
3806 ===============================
3808 CDLaTeX-mode is a minor mode that is normally used in combination with a
3809 major LaTeX mode like AUCTeX in order to speed-up insertion of
3810 environments and math templates. Inside Org-mode, you can make use of
3811 some of the features of cdlatex-mode. You need to install `cdlatex.el'
3812 and `texmathp.el' (the latter comes also with AUCTeX) from
3813 `http://www.astro.uva.nl/~dominik/Tools/cdlatex'. Don't turn
3814 cdlatex-mode itself under Org-mode, but use the light version
3815 `org-cdlatex-mode' that comes as part of Org-mode. Turn it on for the
3816 current buffer with `M-x org-cdlatex-mode', or for all Org-mode files
3819 (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
3821 When this mode is enabled, the following features are present (for
3822 more details see the documentation of cdlatex-mode):
3823 * Environment templates can be inserted with `C-c {'.
3825 * The <TAB> key will do template expansion if the cursor is inside a
3826 LaTeX fragment(1). For example, <TAB> will expand `fr' to
3827 `\frac{}{}' and position the cursor correctly inside the first
3828 brace. Another <TAB> will get you into the second brace. Even
3829 outside fragments, <TAB> will expand environment abbreviations at
3830 the beginning of a line. For example, if you write `equ' at the
3831 beginning of a line and press <TAB>, this abbreviation will be
3832 expanded to an `equation' environment. To get a list of all
3833 abbreviations, type `M-x cdlatex-command-help'.
3835 * Pressing `_' and `^' inside a LaTeX fragment will insert these
3836 characters together with a pair of braces. If you use <TAB> to
3837 move out of the braces, and if the braces surround only a single
3838 character or macro, they are removed again (depending on the
3839 variable `cdlatex-simplify-sub-super-scripts').
3841 * Pressing the backquote ``' followed by a character inserts math
3842 macros, also outside LaTeX fragments. If you wait more than 1.5
3843 seconds after the backquote, a help window will pop up.
3845 * Pressing the normal quote `'' followed by another character
3846 modifies the symbol before point with an accent or a font. If you
3847 wait more than 1.5 seconds after the backquote, a help window will
3848 pop up. Character modification will work only inside LaTeX
3849 fragments, outside the quote is normal.
3851 ---------- Footnotes ----------
3853 (1) Org-mode has a method to test if the cursor is inside such a
3854 fragment, see the documentation of the function
3855 `org-inside-LaTeX-fragment-p'.
3858 File: org, Node: Exporting, Next: Publishing, Prev: Embedded LaTeX, Up: Top
3863 Org-mode documents can be exported into a variety of other formats. For
3864 printing and sharing of notes, ASCII export produces a readable and
3865 simple version of an Org-mode file. HTML export allows you to publish a
3866 notes file on the web, while the XOXO format provides a solid base for
3867 exchange with a broad range of other applications. To incorporate
3868 entries with associated times like deadlines or appointments into a
3869 desktop calendar program like iCal, Org-mode can also produce extracts
3870 in the iCalendar format. Currently Org-mode only supports export, not
3871 import of these different formats.
3873 When exporting, Org-mode uses special conventions to enrich the
3874 output produced. *Note Text interpretation::, for more details.
3877 Dispatcher for export and publishing commands. Displays a
3878 help-window listing the additional key(s) needed to launch an
3879 export or publishing command.
3883 * ASCII export:: Exporting to plain ASCII
3884 * HTML export:: Exporting to HTML
3885 * XOXO export:: Exporting to XOXO
3886 * iCalendar export:: Exporting in iCalendar format
3887 * Text interpretation:: How the exporter looks at the file
3890 File: org, Node: ASCII export, Next: HTML export, Prev: Exporting, Up: Exporting
3895 ASCII export produces a simple and very readable version of an Org-mode
3899 Export as ASCII file. If there is an active region, only the
3900 region will be exported. For an org file `myfile.org', the ASCII
3901 file will be `myfile.txt'. The file will be overwritten without
3905 Export only the visible part of the document.
3907 In the exported version, the first 3 outline levels will become
3908 headlines, defining a general document structure. Additional levels
3909 will be exported as itemized lists. If you want that transition to
3910 occur at a different level, specify it with a prefix argument. For
3915 creates only top level headlines and does the rest as items. When
3916 headlines are converted to items, the indentation of the text following
3917 the headline is changed to fit nicely under the item. This is done with
3918 the assumption that the first bodyline indicates the base indentation of
3919 the body text. Any indentation larger than this is adjusted to preserve
3920 the layout relative to the first line. Should there be lines with less
3921 indentation than the first, these are left alone.
3924 File: org, Node: HTML export, Next: XOXO export, Prev: ASCII export, Up: Exporting
3929 Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive
3930 HTML formatting, in ways similar to John Grubers _markdown_ language,
3931 but with additional support for tables.
3934 Export as HTML file `myfile.html'.
3937 Export as HTML file and open it with a browser.
3942 Export only the visible part of the document.
3944 In the exported version, the first 3 outline levels will become
3945 headlines, defining a general document structure. Additional levels
3946 will be exported as itemized lists. If you want that transition to
3947 occur at a different level, specify it with a prefix argument. For
3952 creates two levels of headings and does the rest as items.
3954 If you want to include HTML tags which should be interpreted as such,
3955 mark them with `@' as in `@<b>bold text@</b>'. Plain `<' and `>' are
3956 always transformed to `<' and `>' in HTML export.
3958 Internal links (*note Internal links::) will continue to work in HTML
3959 files only if they match a dedicated `<<target>>'. Automatic links
3960 created by radio targets (*note Radio targets::) will also work in the
3961 HTML file. Links to external files will still work if the HTML file is
3962 in the same directory as the Org-mode file. Links to other `.org'
3963 files will be translated into HTML links under the assumption that an
3964 HTML version also exists of the linked file. For information related to
3965 linking files while publishing them to a publishing directory see *Note
3968 You can also give style information for the exported file. The HTML
3969 exporter assigns the following CSS classes to appropriate parts of the
3970 document - your style specifications may change these:
3972 .done the DONE keyword
3973 .timestamp time stamp
3974 .timestamp-kwd keyword associated with a time stamp, like SCHEDULED
3975 .tag tag in a headline
3976 .target target for links
3978 The default style specification can be configured through the option
3979 `org-export-html-style'. If you want to use a file-local style, you
3980 may use file variables, best wrapped into a COMMENT section at the end
3981 of the outline tree. For example:
3983 * COMMENT HTML style specifications
3986 # org-export-html-style: " <style type=\"text/css\">
3987 # p {font-weight: normal; color: gray; }
3988 # h1 {color: black; }
3992 Remember to execute `M-x normal-mode' after changing this to make
3993 the new style visible to Emacs. This command restarts org-mode for the
3994 current buffer and forces Emacs to re-evaluate the local variables
3995 section in the buffer.
3998 File: org, Node: XOXO export, Next: iCalendar export, Prev: HTML export, Up: Exporting
4003 Org-mode contains an exporter that produces XOXO-style output.
4004 Currently, this exporter only handles the general outline structure and
4005 does not interpret any additional Org-mode features.
4008 Export as XOXO file `myfile.html'.
4011 Export only the visible part of the document.
4014 File: org, Node: iCalendar export, Next: Text interpretation, Prev: XOXO export, Up: Exporting
4016 10.4 iCalendar export
4017 =====================
4019 Some people like to use Org-mode for keeping track of projects, but
4020 still prefer a standard calendar application for anniversaries and
4021 appointments. In this case it can be useful to have deadlines and
4022 other time-stamped items in Org-mode files show up in the calendar
4023 application. Org-mode can export calendar information in the standard
4027 Create iCalendar entries for the current file and store them in
4028 the same directory, using a file extension `.ics'.
4031 Like `C-c C-e i', but do this for all files in `org-agenda-files'.
4032 For each of these files, a separate iCalendar file will be
4036 Create a single large iCalendar file from all files in
4037 `org-agenda-files' and write it to the file given by
4038 `org-combined-agenda-icalendar-file'.
4040 How this calendar is best read and updated, depends on the
4041 application you are using. For example, when using iCal under Apple
4042 MacOS X, you could create a new calendar `OrgMode' (the default name
4043 for the calendar created by `C-c C-e c', see the variables
4044 `org-icalendar-combined-name' and
4045 `org-combined-agenda-icalendar-file'). Then set Org-mode to overwrite
4046 the corresponding file `~/Library/Calendars/OrgMode.ics'. You may even
4047 use AppleScript to make iCal re-read the calendar files each time a new
4048 version of `OrgMode.ics' is produced. Here is the setup needed for
4051 (setq org-combined-agenda-icalendar-file
4052 "~/Library/Calendars/OrgMode.ics")
4053 (add-hook 'org-after-save-iCalendar-file-hook
4056 "osascript -e 'tell application \"iCal\" to reload calendars'")))
4059 File: org, Node: Text interpretation, Prev: iCalendar export, Up: Exporting
4061 10.5 Text interpretation by the exporter
4062 ========================================
4064 The exporter backends interpret additional structure in the Org-mode
4065 file in order to produce better output.
4069 * Comment lines:: Some lines will not be exported
4070 * Enhancing text:: Subscripts, symbols and more
4071 * Export options:: How to influence the export settings
4074 File: org, Node: Comment lines, Next: Enhancing text, Prev: Text interpretation, Up: Text interpretation
4076 10.5.1 Comment lines
4077 --------------------
4079 Lines starting with `#' in column zero are treated as comments and will
4080 never be exported. Also entire subtrees starting with the word
4081 `COMMENT' will never be exported. Finally, any text before the first
4082 headline will not be exported either.
4085 Toggle the COMMENT keyword at the beginning of an entry.
4088 File: org, Node: Enhancing text, Next: Export options, Prev: Comment lines, Up: Text interpretation
4090 10.5.2 Enhancing text for export
4091 --------------------------------
4093 Some of the export backends of Org-mode allow for sophisticated text
4094 formatting, this is true in particular for the HTML backend. Org-mode
4095 has a number of typing conventions that allow to produce a richly
4098 * Plain lists `-', `*' or `+' as bullet, or with `1.' or `2)' as
4099 enumerator will be recognized and transformed if the backend
4100 supports lists. See *Note Plain lists::.
4102 * You can make words *bold*, /italic/, _underlined_, `=code=', and
4105 * Many TeX macros and entire LaTeX fragments are converted into HTML
4106 entities or images (*note Embedded LaTeX::).
4108 * Tables are transformed into native tables under the exporter, if
4109 the export backend supports this. Data fields before the first
4110 horizontal separator line will be formatted as table header fields.
4112 * If a headline starts with the word `QUOTE', the text below the
4113 headline will be typeset as fixed-width, to allow quoting of
4114 computer codes etc. Lines starting with `:' are also typeset in
4117 Toggle fixed-width for entry (QUOTE) or region, see below.
4119 * A double backslash _at the end of a line_ enforces a line break at
4122 If these conversions conflict with your habits of typing ASCII text,
4123 they can all be turned off with corresponding variables (see the
4124 customization group `org-export-general', and the following section
4125 which explains how to set export options with special lines in a buffer.
4128 File: org, Node: Export options, Prev: Enhancing text, Up: Text interpretation
4130 10.5.3 Export options
4131 ---------------------
4133 The exporter recognizes special lines in the buffer which provide
4134 additional information. These lines may be put anywhere in the file.
4135 The whole set of lines can be inserted into the buffer with `C-c C-e
4136 t'. For individual lines, a good way to make sure the keyword is
4137 correct is to type `#+' and then use `M-<TAB>' completion (*note
4141 Insert template with export options, see example below.
4143 #+TITLE: the title to be shown (default is the buffer name)
4144 #+AUTHOR: the author (default taken from `user-full-name')
4145 #+EMAIL: his/her email address (default from `user-mail-address')
4146 #+LANGUAGE: language for HTML, e.g. `en' (`org-export-default-language')
4147 #+TEXT: Some descriptive text to be inserted at the beginning.
4148 #+TEXT: Several lines may be given.
4149 #+OPTIONS: H:2 num:t toc:t \n:nil @:t ::t |:t ^:t *:nil TeX:t LaTeX:t
4151 The OPTIONS line is a compact form to specify export settings. Here
4153 H: set the number of headline levels for export
4154 num: turn on/off section-numbers
4155 toc: turn on/off table of contents
4156 \n: turn on/off linebreak-preservation
4157 @: turn on/off quoted HTML tags
4158 :: turn on/off fixed-width sections
4159 |: turn on/off tables
4160 ^: turn on/off TeX-like syntax for sub- and superscripts.
4161 *: turn on/off emphasized text (bold, italic, underlined)
4162 TeX: turn on/off simple TeX macros in plain text
4163 LaTeX: turn on/off LaTeX fragments
4166 File: org, Node: Publishing, Next: Miscellaneous, Prev: Exporting, Up: Top
4171 Org-mode includes(1) a publishing management system that allows you to
4172 configure automatic HTML conversion of _projects_ composed of
4173 interlinked org files. This system is called _org-publish_. You can
4174 also configure org-publish to automatically upload your exported HTML
4175 pages and related attachments, such as images and source code files, to
4176 a web server. Org-publish turns org-mode into a web-site authoring
4179 Org-publish has been contributed to Org-mode by David O'Toole.
4183 * Configuration:: Defining projects
4184 * Sample configuration:: Example projects
4185 * Triggering publication:: Publication commands
4187 ---------- Footnotes ----------
4189 (1) `org-publish.el' is not yet part of Emacs, so if you are using
4190 `org.el' as it comes with Emacs, you need to download this file
4191 separately. Also make sure org.el is at least version 4.27.
4194 File: org, Node: Configuration, Next: Sample configuration, Prev: Publishing, Up: Publishing
4199 Publishing needs significant configuration to specify files, destination
4200 and many other properties of a project.
4204 * Project alist:: The central configuration variable
4205 * Sources and destinations:: From here to there
4206 * Selecting files:: What files are part of the project?
4207 * Publishing action:: Setting the function doing the publishing
4208 * Publishing options:: Tweaking HTML export
4209 * Publishing links:: Which links keep working after publishing?
4210 * Project page index:: Publishing a list of project files
4213 File: org, Node: Project alist, Next: Sources and destinations, Prev: Configuration, Up: Configuration
4215 11.1.1 The variable `org-publish-project-alist'
4216 -----------------------------------------------
4218 Org-publish is configured almost entirely through setting the value of
4219 one variable, called `org-publish-project-alist'. Each element of the
4220 list configures one project, and may be in one of the two following
4223 ("project-name" :property value :property value ...)
4227 ("project-name" :components ("project-name" "project-name" ...))
4229 In both cases, projects are configured by specifying property values.
4230 A project defines the set of files that will be published, as well as
4231 the publishing configuration to use when publishing those files. When
4232 a project takes the second form listed above, the individual members of
4233 the "components" property are taken to be components of the project,
4234 which group together files requiring different publishing options. When
4235 you publish such a "meta-project" all the components will also publish.
4238 File: org, Node: Sources and destinations, Next: Selecting files, Prev: Project alist, Up: Configuration
4240 11.1.2 Sources and destinations for files
4241 -----------------------------------------
4243 Most properties are optional, but some should always be set. In
4244 particular, org-publish needs to know where to look for source files,
4245 and where to put published files.
4247 `:base-directory' Directory containing publishing source files
4248 `:publishing-directory'Directory (possibly remote) where output files
4250 `:preparation-function'Function called before starting publishing
4251 process, for example to run `make' for updating
4252 files to be published.
4255 File: org, Node: Selecting files, Next: Publishing action, Prev: Sources and destinations, Up: Configuration
4257 11.1.3 Selecting files
4258 ----------------------
4260 By default, all files with extension `.org' in the base directory are
4261 considered part of the project. This can be modified by setting the
4263 `:base-extension' Extension (without the dot!) of source files. This
4264 actually is a regular expression.
4265 `:exclude' Regular expression to match file names that should
4266 not be published, even though they have been selected
4267 on the basis of their extension.
4268 `:include' List of files to be included regardless of
4269 `:base-extension' and `:exclude'.
4272 File: org, Node: Publishing action, Next: Publishing options, Prev: Selecting files, Up: Configuration
4274 11.1.4 Publishing Action
4275 ------------------------
4277 Publishing means that a file is copied to the destination directory and
4278 possibly transformed in the process. The default transformation is to
4279 export Org-mode files as HTML files, and this is done by the function
4280 `org-publish-org-to-html' which calls the HTML exporter (*note HTML
4281 export::). Other files like images only need to be copied to the
4282 publishing destination. For non-Org-mode files, you need to specify
4283 the publishing function.
4285 `:publishing-function' Function executing the publication of a file.
4286 This may also be a list of functions, which will
4287 all be called in turn.
4289 The function must accept two arguments: a property list containing at
4290 least a `:publishing-directory' property, and the name of the file to
4291 be published. It should take the specified file, make the necessary
4292 transformation (if any) and place the result into the destination
4293 folder. You can write your own publishing function, but `org-publish'
4294 provides one for attachments (files that only need to be copied):
4295 `org-publish-attachment'.
4298 File: org, Node: Publishing options, Next: Publishing links, Prev: Publishing action, Up: Configuration
4300 11.1.5 Options for the HTML exporter
4301 ------------------------------------
4303 The property list can be used to set many export options for the HTML
4304 exporter. In most cases, these properties correspond to user variables
4305 in Org-mode. The table below lists these properties along with the
4306 variable they belong to. See the documentation string for the
4307 respective variable for details.
4309 `:language' `org-export-default-language'
4310 `:headline-levels' `org-export-headline-levels'
4311 `:section-numbers' `org-export-with-section-numbers'
4312 `:table-of-contents' `org-export-with-toc'
4313 `:archived-trees' `org-export-with-archived-trees'
4314 `:emphasize' `org-export-with-emphasize'
4315 `:sub-superscript' `org-export-with-sub-superscripts'
4316 `:TeX-macros' `org-export-with-TeX-macros'
4317 `:LaTeX-fragments' `org-export-with-LaTeX-fragments'
4318 `:fixed-width' `org-export-with-fixed-width'
4319 `:timestamps' `org-export-with-timestamps'
4321 `:tags' `org-export-with-tags'
4323 `:tables' `org-export-with-tables'
4324 `:table-auto-headline' `org-export-highlight-first-table-line'
4325 `:style' `org-export-html-style'
4326 `:convert-org-links' `org-export-html-link-org-files-as-html'
4327 `:inline-images' `org-export-html-inline-images'
4328 `:expand-quoted-html' `org-export-html-expand'
4329 `:timestamp' `org-export-html-with-timestamp'
4330 `:publishing-directory'`org-export-publishing-directory'
4331 `:preamble' `org-export-html-preamble'
4332 `:postamble' `org-export-html-postamble'
4333 `:auto-preamble' `org-export-html-auto-preamble'
4334 `:auto-postamble' `org-export-html-auto-postamble'
4335 `:author' `user-full-name'
4336 `:email' `user-mail-address'
4338 When a property is given a value in org-publish-project-alist, its
4339 setting overrides the value of the corresponding user variable (if any)
4340 during publishing. options set within a file (*note Export options::),
4341 however, override everything.
4344 File: org, Node: Publishing links, Next: Project page index, Prev: Publishing options, Up: Configuration
4346 11.1.6 Links between published files
4347 ------------------------------------
4349 To create a link from one Org-mode file to another, you would use
4350 something like `[[file:foo.org][The foo]]' or simply `file:foo.org.'
4351 (*note Hyperlinks::). Upon publishing this link becomes a link to
4352 `foo.html'. In this way, you can interlink the pages of your "org web"
4353 project and the links will work as expected when you publish them to
4356 You may also link to related files, such as images. Provided you are
4357 careful with relative pathnames, and provided you have also configured
4358 org-publish to upload the related files, these links will work too.
4359 *Note Complex example:: for an example of this usage.
4361 Sometime an Org-mode file to be published may contain links that are
4362 only valid in your production environment, but not in the publishing
4363 location. In this case, use the property
4365 `:link-validation-function' Function to validate links
4367 to define a function for checking link validity. This function must
4368 accept two arguments, the file name and a directory relative to which
4369 the file name is interpreted in the production environment. If this
4370 function returns `nil', then the HTML generator will only insert a
4371 description into the HTML file, but no link. One option for this
4372 function is `org-publish-validate-link' which checks if the given file
4373 is part of any project in `org-publish-project-alist'.
4376 File: org, Node: Project page index, Prev: Publishing links, Up: Configuration
4378 11.1.7 Project page index
4379 -------------------------
4381 The following properties may be used to control publishing of an index
4382 of files or summary page for a given project.
4384 `:auto-index' When non-nil, publish an index during
4385 org-publish-current-project or org-publish-all.
4386 `:index-filename' Filename for output of index. Defaults to `index.org'
4387 (which becomes `index.html').
4388 `:index-title' Title of index page. Defaults to name of file.
4389 `:index-function' Plugin function to use for generation of index.
4390 Defaults to `org-publish-org-index', which generates
4391 a plain list of links to all files in the project.
4394 File: org, Node: Sample configuration, Next: Triggering publication, Prev: Configuration, Up: Publishing
4396 11.2 Sample configuration
4397 =========================
4399 Below we provide two example configurations. The first one is a simple
4400 project publishing only a set of Org-mode files. The second example is
4401 more complex, with a multi-component project.
4405 * Simple example:: One-component publishing
4406 * Complex example:: A multi-component publishing example
4409 File: org, Node: Simple example, Next: Complex example, Prev: Sample configuration, Up: Sample configuration
4411 11.2.1 Example: simple publishing configuration
4412 -----------------------------------------------
4414 This example publishes a set of Org-mode files to the `public_html'
4415 directory on the local machine.
4417 (setq org-publish-project-alist
4419 :base-directory "~/org/"
4420 :publishing-directory "~/public_html"
4421 :section-numbers nil
4422 :table-of-contents nil
4423 :style "<link rel=stylesheet
4424 href=\"../other/mystyle.css\"
4425 type=\"text/css\">")))
4428 File: org, Node: Complex example, Prev: Simple example, Up: Sample configuration
4430 11.2.2 Example: complex publishing configuration
4431 ------------------------------------------------
4433 This more complicated example publishes an entire website, including
4434 org files converted to HTML, image files, emacs lisp source code, and
4435 stylesheets. The publishing-directory is remote and private files are
4438 To ensure that links are preserved, care should be taken to replicate
4439 your directory structure on the web server, and to use relative file
4440 paths. For example, if your org files are kept in `~/org' and your
4441 publishable images in `~/images', you'd link to an image with
4442 file:../images/myimage.png
4443 On the web server, the relative path to the image should be the
4444 same. You can accomplish this by setting up an "images" folder in the
4445 right place on the webserver, and publishing images to it.
4447 (setq org-publish-project-alist
4449 :base-directory "~/org/"
4450 :base-extension "org"
4451 :publishing-directory "/ssh:user@host:~/html/notebook/"
4452 :publishing-function org-publish-org-to-html
4453 :exclude "PrivatePage.org" ;; regexp
4455 :section-numbers nil
4456 :table-of-contents nil
4457 :style "<link rel=stylesheet
4458 href=\"../other/mystyle.css\" type=\"text/css\">"
4460 :auto-postamble nil)
4463 :base-directory "~/images/"
4464 :base-extension "jpg\\|gif\\|png"
4465 :publishing-directory "/ssh:user@host:~/html/images/"
4466 :publishing-function org-publish-attachment)
4469 :base-directory "~/other/"
4470 :base-extension "css\\|el"
4471 :publishing-directory "/ssh:user@host:~/html/other/"
4472 :publishing-function org-publish-attachment)
4473 ("website" :components ("orgfiles" "images" "other"))))
4476 File: org, Node: Triggering publication, Prev: Sample configuration, Up: Publishing
4478 11.3 Triggering publication
4479 ===========================
4481 Once org-publish is properly configured, you can publish with the
4482 following functions:
4485 Prompt for a specific project and publish all files that belong to
4489 Publish the project containing the current file.
4492 Publish only the current file.
4495 Publish all projects.
4497 Org uses timestamps to track when a file has changed. The above
4498 functions normally only publish changed files. You can override this and
4499 force publishing of all files by giving a prefix argument.
4502 File: org, Node: Miscellaneous, Next: Extensions and Hacking, Prev: Publishing, Up: Top
4509 * Completion:: M-TAB knows what you need
4510 * Customization:: Adapting Org-mode to your taste
4511 * In-buffer settings:: Overview of the #+KEYWORDS
4512 * The very busy C-c C-c key:: When in doubt, press C-c C-c
4513 * Clean view:: Getting rid of leading stars in the outline
4514 * TTY keys:: Using Org-mode on a tty
4515 * Interaction:: Other Emacs packages
4516 * Bugs:: Things which do not work perfectly
4519 File: org, Node: Completion, Next: Customization, Prev: Miscellaneous, Up: Miscellaneous
4524 Org-mode supports in-buffer completion. This type of completion does
4525 not make use of the minibuffer. You simply type a few letters into the
4526 buffer and use the key to complete text right there.
4529 Complete word at point
4530 * At the beginning of a headline, complete TODO keywords.
4532 * After `\', complete TeX symbols supported by the exporter.
4534 * After `*', complete headlines in the current buffer so that
4535 they can be used in search links like `[[*find this
4538 * After `:', complete tags. The list of tags is taken from the
4539 variable `org-tag-alist' (possibly set through the `#+TAGS'
4540 in-buffer option, *note Setting tags::), or it is created
4541 dynamically from all tags used in the current buffer.
4543 * After `[', complete link abbreviations (*note Link
4546 * After `#+', complete the special keywords like `TYP_TODO' or
4547 `OPTIONS' which set file-specific options for Org-mode. When
4548 the option keyword is already complete, pressing `M-<TAB>'
4549 again will insert example settings for this keyword.
4551 * In the line after `#+STARTUP: ', complete startup keywords,
4552 i.e. valid keys for this line.
4554 * Elsewhere, complete dictionary words using ispell.
4557 File: org, Node: Customization, Next: In-buffer settings, Prev: Completion, Up: Miscellaneous
4562 There are more than 100 variables that can be used to customize
4563 Org-mode. For the sake of compactness of the manual, we are not
4564 describing the variables here. A structured overview of customization
4565 variables is available with `M-x org-customize'. Or select `Browse Org
4566 Group' from the `Org->Customization' menu. Many settings can also be
4567 activated on a per-file basis, by putting special lines into the buffer
4568 (*note In-buffer settings::).
4571 File: org, Node: In-buffer settings, Next: The very busy C-c C-c key, Prev: Customization, Up: Miscellaneous
4573 12.3 Summary of in-buffer settings
4574 ==================================
4576 Org-mode uses special lines in the buffer to define settings on a
4577 per-file basis. These lines start with a `#+' followed by a keyword, a
4578 colon, and then individual words defining a setting. Several setting
4579 words can be in the same line, but you can also have multiple lines for
4580 the keyword. While these settings are described throughout the manual,
4581 here is a summary. After changing any of those lines in the buffer,
4582 press `C-c C-c' with the cursor still in the line to activate the
4583 changes immediately. Otherwise they become effective only when the
4584 file is visited again in a new Emacs session.
4587 This line sets options to be used at startup of org-mode, when an
4588 Org-mode file is being visited. The first set of options deals
4589 with the initial visibility of the outline tree. The
4590 corresponding variable for global default settings is
4591 `org-startup-folded', with a default value `t', which means
4593 overview top-level headlines only
4594 content all headlines
4595 showall no folding at all, show everything
4596 Then there are options for aligning tables upon visiting a file.
4597 This is useful in files containing narrowed table columns. The
4598 corresponding variable is `org-startup-align-all-tables', with a
4599 default value `nil'.
4600 align align all tables
4601 noalign don't align tables on startup
4602 Logging when a TODO item is marked DONE (variable `org-log-done')
4603 can be configured using these options.
4604 logging record a timestamp when an item is marked DONE
4605 nologging don't record when items are marked DONE
4606 Here are the options for hiding leading stars in outline headings.
4607 The corresponding variables are `org-hide-leading-stars' and
4608 `org-odd-levels-only', both with a default setting `nil' (meaning
4609 `showstars' and `oddeven').
4610 hidestars make all but one of the stars starting a headline invisible.
4611 showstars show all stars starting a headline
4612 odd allow only odd outline levels (1,3,...)
4613 oddeven allow all outline levels
4614 To turn on custom format overlays over time stamps (variables
4615 `org-put-time-stamp-overlays' and
4616 `org-time-stamp-overlay-formats'), use
4617 customtime overlay custom time format
4619 `#+SEQ_TODO: #+TYP_TODO:'
4620 These lines set the TODO keywords and their interpretation in the
4621 current file. The corresponding variables are `org-todo-keywords'
4622 and `org-todo-interpretation'.
4624 `#+TAGS: TAG1(c1) TAG2(c2)'
4625 These lines (several such lines are allowed) specify the legal
4626 tags in this file, and (potentially) the corresponding _fast tag
4627 selection_ keys. The corresponding variable is `org-tag-alist'.
4629 `#+LINK: linkword replace'
4630 These lines (several are allowed) specify link abbreviations.
4631 *Note Link abbreviations::. The corresponding variable is
4632 `org-link-abbrev-alist'.
4635 This line sets the category for the agenda file. The category
4636 applies for all subsequent lines until the next `#+CATEGORY' line,
4637 or the end of the file.
4640 This line contains the formulas for the table directly above the
4643 `#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS:'
4644 These lines provide settings for exporting files. For more
4645 details see *Note Export options::.
4648 File: org, Node: The very busy C-c C-c key, Next: Clean view, Prev: In-buffer settings, Up: Miscellaneous
4650 12.4 The very busy C-c C-c key
4651 ==============================
4653 The key `C-c C-c' has many purposes in org-mode, which are all
4654 mentioned scattered throughout this manual. One specific function of
4655 this key is to add _tags_ to a headline (*note Tags::). In many other
4656 circumstances it means something like _Hey Org-mode, look here and
4657 update according to what you see here_. Here is a summary of what this
4658 means in different contexts.
4660 - If there are highlights in the buffer from the creation of a sparse
4661 tree, or from clock display, remove these highlights.
4663 - If the cursor is in one of the special `#+KEYWORD' lines, this
4664 triggers scanning the buffer for these lines and updating the
4667 - If the cursor is inside a table, realign the table. This command
4668 works even if the automatic table editor has been turned off.
4670 - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the
4673 - If the cursor is inside a table created by the `table.el' package,
4674 activate that table.
4676 - If the current buffer is a remember buffer, close the note and
4677 file it. With a prefix argument, file it, without further
4678 interaction, to the default location.
4680 - If the cursor is on a `<<<target>>>', update radio targets and
4681 corresponding links in this buffer.
4683 - If the cursor is in a plain list item with a checkbox, toggle the
4684 status of the checkbox.
4686 - If the cursor is on a numbered item in a plain list, renumber the
4690 File: org, Node: Clean view, Next: TTY keys, Prev: The very busy C-c C-c key, Up: Miscellaneous
4692 12.5 A cleaner outline view
4693 ===========================
4695 Some people find it noisy and distracting that the Org-mode headlines
4696 are starting with a potentially large number of stars. For example the
4697 tree from *Note Headlines:::
4699 * Top level headline
4705 * Another top level headline
4707 Unfortunately this is deeply ingrained into the code of Org-mode and
4708 cannot be easily changed. You can, however, modify the display in such
4709 a way that all leading stars become invisible and the outline more easy
4710 to read. To do this, customize the variable `org-hide-leading-stars'
4713 (setq org-hide-leading-stars t)
4715 or change this on a per-file basis with one of the lines (anywhere in
4718 #+STARTUP: showstars
4719 #+STARTUP: hidestars
4721 Press `C-c C-c' with the cursor in a `STARTUP' line to activate the
4724 With stars hidden, the tree becomes:
4726 * Top level headline
4732 * Another top level headline
4734 Note that the leading stars are not truly replaced by whitespace, they
4735 are only fontified with the face `org-hide' that uses the background
4736 color as font color. If you are not using either white or black
4737 background, you may have to customize this face to get the wanted
4738 effect. Another possibility is to set this font such that the extra
4739 stars are almost invisible, for example using the color `grey90' on a
4742 Things become cleaner still if you skip all the even levels and use
4743 only odd levels 1, 3, 5..., effectively adding two stars to go from one
4744 outline level to the next:
4746 * Top level headline
4752 * Another top level headline
4754 In order to make the structure editing and export commands handle this
4755 convention correctly, use
4757 (setq org-odd-levels-only t)
4759 or set this on a per-file basis with one of the following lines (don't
4760 forget to press `C-c C-c' with the cursor in the startup line to
4761 activate changes immediately).
4766 You can convert an Org-mode file from single-star-per-level to the
4767 double-star-per-level convention with `M-x org-convert-to-odd-levels
4768 RET' in that file. The reverse operation is `M-x
4769 org-convert-to-oddeven-levels'.
4772 File: org, Node: TTY keys, Next: Interaction, Prev: Clean view, Up: Miscellaneous
4774 12.6 Using org-mode on a tty
4775 ============================
4777 Org-mode uses a number of keys that are not accessible on a tty. This
4778 applies to most special keys like cursor keys, <TAB> and <RET>, when
4779 these are combined with modifier keys like <Meta> and/or <Shift>.
4780 Org-mode uses these bindings because it needs to provide keys for a
4781 large number of commands, and because these keys appeared particularly
4782 easy to remember. In order to still be able to access the core
4783 functionality of Org-mode on a tty, alternative bindings are provided.
4784 Here is a complete list of these bindings, which are obviously more
4785 cumbersome to use. Note that sometimes a work-around can be better.
4786 For example changing a time stamp is really only fun with `S-<cursor>'
4787 keys. On a tty you would rather use `C-c .' to re-insert the
4790 Default Alternative 1 Alternative 2
4791 `S-<TAB>' `C-u <TAB>'
4792 `M-<left>' `C-c C-x l' `<Esc> <left>'
4793 `M-S-<left>'`C-c C-x L'
4794 `M-<right>' `C-c C-x r' `<Esc>
4796 `M-S-<right>'`C-c C-x R'
4797 `M-<up>' `C-c C-x u' `<Esc> <up>'
4798 `M-S-<up>' `C-c C-x U'
4799 `M-<down>' `C-c C-x d' `<Esc> <down>'
4800 `M-S-<down>'`C-c C-x D'
4801 `S-<RET>' `C-c C-x c'
4802 `M-<RET>' `C-c C-x m' `<Esc> <RET>'
4803 `M-S-<RET>' `C-c C-x M'
4806 `S-<right>' `C-c C-x
4814 File: org, Node: Interaction, Next: Bugs, Prev: TTY keys, Up: Miscellaneous
4816 12.7 Interaction with other packages
4817 ====================================
4819 Org-mode lives in the world of GNU Emacs and interacts in various ways
4820 with other code out there.
4824 * Cooperation:: Packages Org-mode cooperates with
4825 * Conflicts:: Packages that lead to conflicts
4828 File: org, Node: Cooperation, Next: Conflicts, Prev: Interaction, Up: Interaction
4830 12.7.1 Packages that Org-mode cooperates with
4831 ---------------------------------------------
4833 `calc.el' by Dave Gillespie
4834 Org-mode uses the calc package for implementing spreadsheet
4835 functionality in its tables (*note Table calculations::).
4836 Org-modes checks for the availability of calc by looking for the
4837 function `calc-eval' which should be autoloaded in your setup if
4838 calc has been installed properly. As of Emacs 22, calc is part of
4839 the Emacs distribution. Another possibility for interaction
4840 between the two packages is using calc for embedded calculations.
4841 *Note Embedded Mode: (calc)Embedded Mode.
4843 `constants.el' by Carsten Dominik
4844 In a table formula (*note Table calculations::), it is possible to
4845 use names for natural constants or units. Instead of defining
4846 your own constants in the variable `org-table-formula-constants',
4847 install the `constants' package which defines a large number of
4848 constants and units, and lets you use unit prefixes like `M' for
4849 `Mega' etc. You will need version 2.0 of this package, available
4850 at `http://www.astro.uva.nl/~dominik/Tools'. Org-mode checks for
4851 the function `constants-get', which has to be autoloaded in your
4852 setup. See the installation instructions in the file
4855 `cdlatex.el' by Carsten Dominik
4856 Org-mode can make use of the cdlatex package to efficiently enter
4857 LaTeX fragments into Org-mode files. See *Note CDLaTeX mode::.
4859 `remember.el' by John Wiegley
4860 Org mode cooperates with remember, see *Note Remember::.
4861 `Remember.el' is not part of Emacs, find it on the web.
4863 `table.el' by Takaaki Ota
4864 Org mode cooperates with table.el, see *Note table.el::.
4865 `table.el' is part of Emacs 22.
4868 File: org, Node: Conflicts, Prev: Cooperation, Up: Interaction
4870 12.7.2 Packages that lead to conflicts with Org-mode
4871 ----------------------------------------------------
4873 `allout.el' by Ken Manheimer
4874 Startup of Org-mode may fail with the error message
4875 `(wrong-type-argument keymapp nil)' when there is an outdated
4876 version `allout.el' on the load path, for example the version
4877 distributed with Emacs 21.x. Upgrade to Emacs 22 and this problem
4878 will disappear. If for some reason you cannot do this, make sure
4879 that org.el is loaded _before_ `allout.el', for example by putting
4880 `(require 'org)' early enough into your `.emacs' file.
4882 `CUA.el' by Kim. F. Storm
4883 Keybindings in Org-mode conflict with the `S-<cursor>' keys used
4884 by CUA-mode (as well as pc-select-mode and s-region-mode) to
4885 select and extend the region. If you want to use one of these
4886 packages along with Org-mode, configure the variable
4887 `org-CUA-compatible'. When set, Org-mode will move the following
4888 keybindings in org-mode files, and in the agenda buffer (but not
4889 during date selection).
4891 S-UP -> M-p S-DOWN -> M-n
4892 S-LEFT -> M-- S-RIGHT -> M-+
4895 Yes, these are unfortunately more difficult to remember. If you
4896 want to have other replacement keys, look at the variable
4897 `org-disputed-keys'.
4899 `windmove.el' by Hovav Shacham
4900 Also this package uses the `S-<cursor>' keys, so everything written
4901 in the paragraph above about CUA mode also applies here.
4904 File: org, Node: Bugs, Prev: Interaction, Up: Miscellaneous
4909 Here is a list of things that should work differently, but which I have
4910 found too hard to fix.
4912 * If a table field starts with a link, and if the corresponding table
4913 column is narrowed (*note Narrow columns::) to a width too small to
4914 display the link, the field would look entirely empty even though
4915 it is not. To prevent this, Org-mode throws an error. The
4916 work-around is to make the column wide enough to fit the link, or
4917 to add some text (at least 2 characters) before the link in the
4920 * Narrowing table columns does not work on XEmacs, because the
4921 `format' function does not transport text properties.
4923 * Text in an entry protected with the `QUOTE' keyword should not
4926 * When the application called by `C-c C-o' to open a file link fails
4927 (for example because the application does not exist or refuses to
4928 open the file), it does so silently. No error message is
4931 * The remote-editing commands in the agenda buffer cannot be undone
4932 with `undo' called from within the agenda buffer. But you can go
4933 to the corresponding buffer (using <TAB> or <RET> and execute
4936 * Recalculating a table line applies the formulas from left to right.
4937 If a formula uses _calculated_ fields further down the row,
4938 multiple recalculation may be needed to get all fields consistent.
4940 * A single letter cannot be made bold, for example `*a*'.
4942 * The exporters work well, but could be made more efficient.
4945 File: org, Node: Extensions and Hacking, Next: History and Acknowledgments, Prev: Miscellaneous, Up: Top
4947 Appendix A Extensions, Hooks and Hacking
4948 ****************************************
4950 This appendix lists extensions for Org-mode written by other authors.
4951 It also covers some aspects where users can easily extend the
4952 functionality of Org-mode.
4956 * Extensions:: Existing 3rd-part extensions
4957 * Dynamic blocks:: Automatically filled blocks
4960 File: org, Node: Extensions, Next: Dynamic blocks, Prev: Extensions and Hacking, Up: Extensions and Hacking
4962 A.1 Third-party extensions for Org-mode
4963 =======================================
4965 The following extensions for Org-mode have been written by other people:
4967 `org-publish.el' by David O'Toole
4968 This package provides facilities for publishing related sets of
4969 Org-mode files together with linked files like images as a
4970 webpages. It is highly configurable and can be used for other
4971 publishing purposes as well. As of Org-mode version 4.30,
4972 `org-publish.el' is part of the Org-mode distribution. It is not
4973 yet part of Emacs, however, a delay caused by the preparations for
4974 the 22.1 release. In the mean time, `org-publish.el' can be
4975 downloaded from David's site:
4976 `http://dto.freeshell.org/e/org-publish.el'.
4978 `org-mouse.el' by Piotr Zielinski
4979 This package implements extended mouse functionality for Org-mode.
4980 It allows you to cycle visibility and to edit the document
4981 structure with the mouse. Best of all, it provides a
4982 context-sensitive menu on <mouse-3> that changes depending on the
4983 context of a mouse-click. As of Org-mode version 4.53,
4984 `org-mouse.el' is part of the Org-mode distribution. It is not
4985 yet part of Emacs, however, a delay caused by the preparations for
4986 the 22.1 release. In the mean time, `org-mouse.el' can be
4987 downloaded from Piotr's site:
4988 `http://www.cl.cam.ac.uk/~pz215/files/org-mouse.el'.
4990 `org-blog.el' by David O'Toole
4991 A blogging plug-in for `org-publish.el'.
4992 `http://dto.freeshell.org/notebook/OrgMode.html'.
4994 `org-blogging.el' by Bastien Guerry
4995 Publish Org-mode files as blogs.
4996 `http://www.cognition.ens.fr/~guerry/org-blogging.html'.
4999 File: org, Node: Dynamic blocks, Prev: Extensions, Up: Extensions and Hacking
5004 Org-mode documents can contain _dynamic blocks_. These are specially
5005 marked regions that are updated by some user-written function. A good
5006 example for such a block is the clock table inserted by the command
5007 `C-c C-x C-r' (*note Clocking work time::).
5009 Dynamic block are enclosed by a BEGIN-END structure that assigns a
5010 name to the block and can also specify parameters for the function
5011 producing the content of the block.
5013 #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
5017 Dynamic blocks are updated with the following commands
5020 Update dynamic block at point.
5023 Update all dynamic blocks in the current file.
5025 Updating a dynamic block means to remove all the text between BEGIN
5026 and END, parse the BEGIN line for parameters and then call the specific
5027 writer function for this block to insert the new content. For a block
5028 with name `myblock', the writer function is `org-dblock-write:myblock'
5029 with as only parameter a property list with the parameters given in the
5030 begin line. Here is a trivial example of a block that keeps track of
5031 when the block update function was last run:
5033 #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
5037 The corresponding block writer function could look like this:
5039 (defun org-dblock-write:block-update-time (params)
5040 (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
5041 (insert "Last block update at: "
5042 (format-time-string fmt (current-time)))))
5044 If you want to make sure that all dynamic blocks are always
5045 up-to-date, you could add the function `org-update-all-dblocks' to a
5046 hook, for example `before-save-hook'. `org-update-all-dblocks' is
5047 written in a way that is does nothing in buffers that are not in
5051 File: org, Node: History and Acknowledgments, Next: Index, Prev: Extensions and Hacking, Up: Top
5053 Appendix B History and Acknowledgments
5054 **************************************
5056 Org-mode was borne in 2003, out of frustration over the user interface
5057 of the Emacs outline-mode. All I wanted was to make working with an
5058 outline tree possible without having to remember more than 10 commands
5059 just for hiding and unhiding parts of the outline tree, and to allow to
5060 restructure a tree easily. Visibility cycling and structure editing
5061 were originally implemented in the package `outline-magic.el', but
5062 quickly moved to the more general `org.el'. TODO entries, basic time
5063 stamps, and table support were added next, and highlight the two main
5064 goals that Org-mode still has today: To create a new, outline-based,
5065 plain text mode with innovative and intuitive editing features, and to
5066 incorporate project planning functionality directly into a notes file.
5068 Since the first release, hundreds of emails to me or on
5069 `emacs-orgmode@gnu.org' have provided a constant stream of bug reports,
5070 feedback, new ideas, and sometimes even patches and add-on code. Many
5071 thanks to everyone who has helped to improve this package. I am trying
5072 to keep here a list of the people who had significant influence in
5073 shaping one or more aspects of Org-mode. The list may not be complete,
5074 if I have forgotten someone, please accept my apologies and let me know.
5076 * Thomas Baumann contributed the code for links to the MH-E email
5079 * Alex Bochannek provided a patch for rounding time stamps.
5081 * Charles Cave's suggestion sparked the implementation of templates
5084 * Pavel Chalmoviansky influenced the agenda treatment of items with
5087 * Gregory Chernov patched support for lisp forms into table
5088 calculations and improved XEmacs compatibility, in particular by
5089 porting `nouline.el' to XEmacs.
5091 * Sacha Chua suggested to copy some linking code from Planner.
5093 * Eddward DeVilla proposed and tested checkbox statistics.
5095 * Kees Dullemond inspired the use of narrowed tabled columns.
5097 * Christian Egli converted the documentation into TeXInfo format,
5098 patched CSS formatting into the HTML exporter, and inspired the
5101 * Nic Ferrier contributed mailcap and XOXO support.
5103 * Niels Giessen had the idea to automatically archive DONE trees.
5105 * Bastien Guerry provided extensive feedback.
5107 * Kai Grossjohann pointed out key-binding conflicts with other
5110 * Leon Liu asked for embedded LaTeX and tested it.
5112 * Stefan Monnier provided a patch to keep the Emacs-Lisp compiler
5115 * Todd Neal provided patches for links to Info files and elisp forms.
5117 * Tim O'Callaghan suggested in-file links, search options for general
5118 file links, and TAGS.
5120 * Oliver Oppitz suggested multi-state TODO items.
5122 * Scott Otterson sparked the introduction of descriptive text for
5123 links, among other things.
5125 * Pete Phillips helped during the development of the TAGS feature,
5126 and provided frequent feedback.
5128 * T.V. Raman reported bugs and suggested improvements.
5130 * Matthias Rempe (Oelde) provided ideas, Windows support, and quality
5133 * Kevin Rogers contributed code to access VM files on remote hosts.
5135 * Frank Ruell solved the mystery of the `keymapp nil' bug, a
5136 conflict with `allout.el'.
5138 * Jason Riedy sent a patch to fix a bug with export of TODO keywords.
5140 * Philip Rooke created the Org-mode reference card and provided lots
5143 * Christian Schlauer proposed angular brackets around links, among
5146 * Linking to VM/BBDB/GNUS was inspired by Tom Shannon's
5147 `organizer-mode.el'.
5149 * Daniel Sinder came up with the idea of internal archiving by
5152 * Dale Smith proposed link abbreviations.
5154 * David O'Toole wrote `org-publish.el' and drafted the manual
5155 chapter about publishing.
5157 * Ju"rgen Vollmer contributed code generating the table of contents
5160 * Chris Wallace provided a patch implementing the `QUOTE' keyword.
5162 * David Wainberg suggested archiving, and improvements to the linking
5165 * John Wiegley wrote `emacs-wiki.el' and `planner.el'. The
5166 development of Org-mode was fully independent, and both systems are
5167 really different beasts in their basic ideas and implementation
5168 details. I later looked at John's code, however, and learned from
5169 his implementation of (i) links where the link itself is hidden
5170 and only a description is shown, and (ii) popping up a calendar to
5173 * Carsten Wimmer suggested some changes and helped fix a bug in
5176 * Roland Winkler requested additional keybindings to make Org-mode
5179 * Piotr Zielinski wrote `org-mouse.el', proposed agenda blocks and
5180 contributed various ideas and code snippets.
5183 File: org, Node: Index, Next: Key Index, Prev: History and Acknowledgments, Up: Top
5191 * abbreviation, links: Link abbreviations. (line 6)
5192 * acknowledgments: History and Acknowledgments.
5194 * action, for publishing: Publishing action. (line 6)
5195 * activation: Activation. (line 6)
5196 * active region <1>: HTML export. (line 10)
5197 * active region <2>: ASCII export. (line 9)
5198 * active region <3>: Built-in table editor.
5200 * active region: Structure editing. (line 54)
5201 * agenda: Weekly/Daily agenda. (line 6)
5202 * agenda dispatcher: Agenda dispatcher. (line 6)
5203 * agenda files: Agenda files. (line 6)
5204 * agenda files, removing buffers: Agenda commands. (line 217)
5205 * agenda views: Agenda views. (line 6)
5206 * agenda views, custom: Custom agenda views. (line 6)
5207 * agenda, batch production: Batch processing. (line 6)
5208 * agenda, with block views: Block agenda. (line 6)
5209 * allout.el: Conflicts. (line 6)
5210 * angular brackets, around links: External links. (line 38)
5211 * applescript, for calendar update: iCalendar export. (line 38)
5212 * archive locations: Moving subtrees. (line 21)
5213 * archiving: Archiving. (line 6)
5214 * ASCII export: ASCII export. (line 6)
5215 * author: Feedback. (line 6)
5216 * autoload: Activation. (line 6)
5217 * backtrace of an error: Feedback. (line 27)
5218 * BBDB links: External links. (line 6)
5219 * block agenda: Block agenda. (line 6)
5220 * bold text: Enhancing text. (line 15)
5221 * Boolean logic, for tag searches: Tag searches. (line 21)
5222 * bug reports: Feedback. (line 6)
5223 * bugs: Bugs. (line 6)
5224 * C-c C-c, overview: The very busy C-c C-c key.
5226 * calc package: Table calculations. (line 6)
5227 * calc.el: Cooperation. (line 6)
5228 * calculations, in tables <1>: Table calculations. (line 6)
5229 * calculations, in tables: Built-in table editor.
5231 * calendar commands, from agenda: Agenda commands. (line 178)
5232 * calendar integration: Calendar/Diary integration.
5234 * calendar, for selecting date: The date/time prompt.
5236 * CamelCase link completion: Completion. (line 6)
5237 * CamelCase links: Internal links. (line 6)
5238 * CamelCase links, completion of: CamelCase links. (line 6)
5239 * category: Categories. (line 6)
5240 * CDLaTeX: CDLaTeX mode. (line 6)
5241 * cdlatex.el: Cooperation. (line 29)
5242 * checkbox statistics: Checkboxes. (line 23)
5243 * checkboxes: Checkboxes. (line 6)
5244 * children, subtree visibility state: Visibility cycling. (line 10)
5245 * clean outline view: Clean view. (line 6)
5246 * CLOCK keyword: Time stamps. (line 71)
5247 * CLOSED keyword: Time stamps. (line 65)
5248 * column formula: Column formulas. (line 6)
5249 * commands, in agenda buffer: Agenda commands. (line 6)
5250 * comment lines: Comment lines. (line 6)
5251 * completion, of CamelCase links <1>: Completion. (line 6)
5252 * completion, of CamelCase links: CamelCase links. (line 6)
5253 * completion, of dictionary words: Completion. (line 6)
5254 * completion, of file names: Handling links. (line 43)
5255 * completion, of links: Handling links. (line 27)
5256 * completion, of option keywords <1>: Completion. (line 6)
5257 * completion, of option keywords: Export options. (line 6)
5258 * Completion, of option keywords: Per file keywords. (line 17)
5259 * completion, of tags <1>: Completion. (line 6)
5260 * completion, of tags: Setting tags. (line 11)
5261 * completion, of TeX symbols: Completion. (line 6)
5262 * completion, of TODO keywords <1>: Completion. (line 6)
5263 * completion, of TODO keywords: Workflow states. (line 12)
5264 * constants, in calculations: Formula syntax. (line 26)
5265 * constants.el: Cooperation. (line 14)
5266 * contents, global visibility state: Visibility cycling. (line 22)
5267 * copying, of subtrees: Structure editing. (line 6)
5268 * creating timestamps: Creating timestamps. (line 6)
5269 * CUA.el: Conflicts. (line 15)
5270 * custom agenda views: Custom agenda views. (line 6)
5271 * custom date/time format: Custom time format. (line 6)
5272 * custom search strings: Custom searches. (line 6)
5273 * customization: Customization. (line 6)
5274 * cutting, of subtrees: Structure editing. (line 6)
5275 * cycling, of TODO states: TODO basics. (line 13)
5276 * cycling, visibility: Visibility cycling. (line 6)
5277 * daily agenda: Weekly/Daily agenda. (line 6)
5278 * date format, custom: Custom time format. (line 6)
5279 * date stamps <1>: Time stamps. (line 6)
5280 * date stamps: Timestamps. (line 6)
5281 * date, reading in minibuffer: The date/time prompt.
5283 * DEADLINE keyword: Time stamps. (line 53)
5284 * deadlines: Time stamps. (line 6)
5285 * demotion, of subtrees: Structure editing. (line 6)
5286 * diary entries, creating from agenda: Agenda commands. (line 185)
5287 * diary integration: Calendar/Diary integration.
5289 * dictionary word completion: Completion. (line 6)
5290 * directories, for publishing: Sources and destinations.
5292 * dispatching agenda commands: Agenda dispatcher. (line 6)
5293 * display changing, in agenda: Agenda commands. (line 59)
5294 * document structure: Document structure. (line 6)
5295 * DONE, final TODO keyword: Per file keywords. (line 20)
5296 * editing tables: Tables. (line 6)
5297 * editing, of table formulas: Editing/debugging formulas.
5299 * elisp links: External links. (line 6)
5300 * emphasized text: Export options. (line 25)
5301 * enhancing text: Enhancing text. (line 6)
5302 * evaluate time range: Creating timestamps. (line 66)
5303 * exporting: Exporting. (line 6)
5304 * exporting, not: Comment lines. (line 6)
5305 * extended TODO keywords: TODO extensions. (line 6)
5306 * external archiving: Moving subtrees. (line 6)
5307 * external links: External links. (line 6)
5308 * external links, in HTML export: HTML export. (line 35)
5309 * FAQ: Summary. (line 51)
5310 * feedback: Feedback. (line 6)
5311 * file links: External links. (line 6)
5312 * file links, searching: Search options. (line 6)
5313 * file name completion: Handling links. (line 43)
5314 * files for agenda: Agenda files. (line 6)
5315 * files, adding to agenda list: Agenda files. (line 12)
5316 * files, selecting for publishing: Selecting files. (line 6)
5317 * fixed width: Enhancing text. (line 25)
5318 * fixed-width sections: Export options. (line 25)
5319 * folded, subtree visibility state: Visibility cycling. (line 10)
5320 * folding, sparse trees: Sparse trees. (line 6)
5321 * following links: Handling links. (line 58)
5322 * format specifier: Formula syntax. (line 34)
5323 * format, of links: Link format. (line 6)
5324 * formula editing: Editing/debugging formulas.
5326 * formula syntax: Formula syntax. (line 6)
5327 * formula, for named table field: Named-field formulas.
5329 * formula, for table column: Column formulas. (line 6)
5330 * formula, in tables: Built-in table editor.
5332 * global cycling: Visibility cycling. (line 22)
5333 * global keybindings: Activation. (line 6)
5334 * global TODO list: Global TODO list. (line 6)
5335 * global visibility states: Visibility cycling. (line 22)
5336 * GNUS links: External links. (line 6)
5337 * hand-formatted lists: Enhancing text. (line 11)
5338 * headline levels: Export options. (line 25)
5339 * headline levels, for exporting <1>: HTML export. (line 21)
5340 * headline levels, for exporting: ASCII export. (line 18)
5341 * headline navigation: Motion. (line 6)
5342 * headline tagging: Tags. (line 6)
5343 * headline, promotion and demotion: Structure editing. (line 6)
5344 * headlines: Headlines. (line 6)
5345 * hide text: Visibility cycling. (line 6)
5346 * hiding leading stars: Clean view. (line 6)
5347 * history: History and Acknowledgments.
5349 * HTML export: HTML export. (line 6)
5350 * hyperlinks: Hyperlinks. (line 6)
5351 * iCalendar export: iCalendar export. (line 6)
5352 * in-buffer settings: In-buffer settings. (line 6)
5353 * inactive timestamp: Time stamps. (line 24)
5354 * index, of published pages: Project page index. (line 6)
5355 * Info links: External links. (line 6)
5356 * inheritance, of tags: Tag inheritance. (line 6)
5357 * inserting links: Handling links. (line 27)
5358 * installation: Installation. (line 6)
5359 * internal archiving: ARCHIVE tag. (line 6)
5360 * internal links: Internal links. (line 6)
5361 * internal links, in HTML export: HTML export. (line 35)
5362 * introduction: Introduction. (line 6)
5363 * italic text: Enhancing text. (line 15)
5364 * jumping, to headlines: Motion. (line 6)
5365 * keybindings, global: Activation. (line 6)
5366 * keyword options: Per file keywords. (line 6)
5367 * LaTeX fragments <1>: Export options. (line 25)
5368 * LaTeX fragments: LaTeX fragments. (line 6)
5369 * LaTeX fragments, export: Enhancing text. (line 18)
5370 * LaTeX fragments, preview: Processing LaTeX fragments.
5372 * LaTeX interpretation: Embedded LaTeX. (line 6)
5373 * linebreak preservation: Export options. (line 25)
5374 * linebreak, forced: Enhancing text. (line 32)
5375 * link abbreviations: Link abbreviations. (line 6)
5376 * link completion: Handling links. (line 27)
5377 * link format: Link format. (line 6)
5378 * links, external: External links. (line 6)
5379 * links, handling: Handling links. (line 6)
5380 * links, in HTML export: HTML export. (line 35)
5381 * links, internal: Internal links. (line 6)
5382 * links, publishing: Publishing links. (line 6)
5383 * links, radio targets: Radio targets. (line 6)
5384 * links, returning to: Handling links. (line 85)
5385 * Lisp forms, as table formulas: Lisp formulas. (line 6)
5386 * lists, hand-formatted: Enhancing text. (line 11)
5387 * lists, ordered: Plain lists. (line 6)
5388 * lists, plain: Plain lists. (line 6)
5389 * logging, of progress: Progress logging. (line 6)
5390 * maintainer: Feedback. (line 6)
5391 * mark ring: Handling links. (line 81)
5392 * marking characters, tables: Advanced features. (line 34)
5393 * matching, of tags: Matching headline tags.
5395 * matching, tags: Tags. (line 6)
5396 * math symbols: Math symbols. (line 6)
5397 * MH-E links: External links. (line 6)
5398 * minor mode for tables: orgtbl-mode. (line 6)
5399 * mode, for calc: Formula syntax. (line 34)
5400 * motion commands in agenda: Agenda commands. (line 19)
5401 * motion, between headlines: Motion. (line 6)
5402 * name, of column or field: Formula syntax. (line 26)
5403 * named field formula: Named-field formulas.
5405 * names as TODO keywords: TODO types. (line 6)
5406 * narrow columns in tables: Narrow columns. (line 6)
5407 * occur, command: Sparse trees. (line 6)
5408 * option keyword completion: Completion. (line 6)
5409 * options, for custom agenda views: Setting Options. (line 6)
5410 * options, for customization: Customization. (line 6)
5411 * options, for export: Export options. (line 6)
5412 * options, for publishing: Publishing options. (line 6)
5413 * ordered lists: Plain lists. (line 6)
5414 * org-agenda, command: Weekly/Daily agenda. (line 9)
5415 * org-blog.el: Extensions. (line 29)
5416 * org-blogging.el: Extensions. (line 33)
5417 * org-mode, turning on: Activation. (line 22)
5418 * org-mouse.el: Extensions. (line 17)
5419 * org-publish-project-alist: Project alist. (line 6)
5420 * org-publish.el: Extensions. (line 8)
5421 * orgtbl-mode: orgtbl-mode. (line 6)
5422 * outline tree: Headlines. (line 6)
5423 * outline-mode: Outlines. (line 6)
5424 * outlines: Outlines. (line 6)
5425 * overview, global visibility state: Visibility cycling. (line 22)
5426 * packages, interaction with other: Interaction. (line 6)
5427 * pasting, of subtrees: Structure editing. (line 6)
5428 * per file keywords: Per file keywords. (line 6)
5429 * plain lists: Plain lists. (line 6)
5430 * plain text external links: External links. (line 38)
5431 * presentation, of agenda items: Presentation and sorting.
5433 * printing sparse trees: Sparse trees. (line 41)
5434 * priorities: Priorities. (line 6)
5435 * priorities, of agenda items: Sorting of agenda items.
5437 * progress logging: Progress logging. (line 6)
5438 * projects, for publishing: Project alist. (line 6)
5439 * promotion, of subtrees: Structure editing. (line 6)
5440 * publishing: Publishing. (line 6)
5441 * quoted HTML tags: Export options. (line 25)
5442 * radio targets: Radio targets. (line 6)
5443 * ranges, time: Time stamps. (line 6)
5444 * recomputing table fields: Column formulas. (line 27)
5445 * region, active <1>: HTML export. (line 10)
5446 * region, active <2>: ASCII export. (line 9)
5447 * region, active <3>: Built-in table editor.
5449 * region, active: Structure editing. (line 54)
5450 * remember.el <1>: Cooperation. (line 33)
5451 * remember.el: Remember. (line 6)
5452 * remote editing, from agenda: Agenda commands. (line 100)
5453 * richer text: Enhancing text. (line 6)
5454 * RMAIL links: External links. (line 6)
5455 * SCHEDULED keyword: Time stamps. (line 40)
5456 * scheduling: Time stamps. (line 6)
5457 * search option in file links: Search options. (line 6)
5458 * search strings, custom: Custom searches. (line 6)
5459 * searching for tags: Tag searches. (line 6)
5460 * section-numbers: Export options. (line 25)
5461 * setting tags: Setting tags. (line 6)
5462 * SHELL links: External links. (line 6)
5463 * show all, command: Visibility cycling. (line 31)
5464 * show all, global visibility state: Visibility cycling. (line 22)
5465 * show hidden text: Visibility cycling. (line 6)
5466 * sorting, of agenda items: Sorting of agenda items.
5468 * sparse tree, for deadlines: Creating timestamps. (line 41)
5469 * sparse tree, for TODO: TODO basics. (line 26)
5470 * sparse tree, tag based: Tags. (line 6)
5471 * sparse trees: Sparse trees. (line 6)
5472 * special keywords: In-buffer settings. (line 6)
5473 * spreadsheet capabilities: Table calculations. (line 6)
5474 * statistics, for checkboxes: Checkboxes. (line 23)
5475 * storing links: Handling links. (line 9)
5476 * structure editing: Structure editing. (line 6)
5477 * structure of document: Document structure. (line 6)
5478 * sublevels, inclusion into tags match: Tag inheritance. (line 6)
5479 * sublevels, inclusion into todo list: Global TODO list. (line 33)
5480 * subscript: Subscripts and Superscripts.
5482 * subtree cycling: Visibility cycling. (line 10)
5483 * subtree visibility states: Visibility cycling. (line 10)
5484 * subtree, cut and paste: Structure editing. (line 6)
5485 * subtree, subtree visibility state: Visibility cycling. (line 10)
5486 * subtrees, cut and paste: Structure editing. (line 6)
5487 * summary: Summary. (line 6)
5488 * superscript: Subscripts and Superscripts.
5490 * syntax, of formulas: Formula syntax. (line 6)
5491 * table editor, builtin: Built-in table editor.
5493 * table editor, table.el: table.el. (line 6)
5494 * table of contents: Export options. (line 25)
5495 * table.el <1>: Cooperation. (line 34)
5496 * table.el: table.el. (line 6)
5497 * tables <1>: Export options. (line 25)
5498 * tables: Tables. (line 6)
5499 * tables, export: Enhancing text. (line 21)
5500 * tag completion: Completion. (line 6)
5501 * tag searches: Tag searches. (line 6)
5502 * tags: Tags. (line 6)
5503 * tags view: Matching headline tags.
5505 * tags, setting: Setting tags. (line 6)
5506 * targets, for links: Internal links. (line 6)
5507 * targets, radio: Radio targets. (line 6)
5508 * tasks, breaking down: Breaking down tasks. (line 6)
5509 * templates, for remember: Remember. (line 23)
5510 * TeX interpretation: Embedded LaTeX. (line 6)
5511 * TeX macros <1>: Export options. (line 25)
5512 * TeX macros: Math symbols. (line 6)
5513 * TeX macros, export: Enhancing text. (line 18)
5514 * TeX symbol completion: Completion. (line 6)
5515 * TeX-like syntax for sub- and superscripts: Export options. (line 25)
5516 * thanks: History and Acknowledgments.
5518 * time format, custom: Custom time format. (line 6)
5519 * time grid: Time-of-day specifications.
5521 * time stamps <1>: Time stamps. (line 6)
5522 * time stamps: Timestamps. (line 6)
5523 * time, reading in minibuffer: The date/time prompt.
5525 * time-of-day specification: Time-of-day specifications.
5527 * time-sorted view: Timeline. (line 6)
5528 * timeline, single file: Timeline. (line 6)
5529 * timerange: Time stamps. (line 31)
5530 * timestamp: Time stamps. (line 14)
5531 * timestamp, inactive: Time stamps. (line 24)
5532 * timestamps, creating: Creating timestamps. (line 6)
5533 * TODO items: TODO items. (line 6)
5534 * TODO keyword matching: Global TODO list. (line 17)
5535 * TODO keyword matching, with tags search: Tag searches. (line 38)
5536 * TODO keywords completion: Completion. (line 6)
5537 * TODO list, global: Global TODO list. (line 6)
5538 * TODO types: TODO types. (line 6)
5539 * TODO workflow: Workflow states. (line 6)
5540 * transient-mark-mode <1>: HTML export. (line 10)
5541 * transient-mark-mode <2>: ASCII export. (line 9)
5542 * transient-mark-mode <3>: Built-in table editor.
5544 * transient-mark-mode: Structure editing. (line 54)
5545 * trees, sparse: Sparse trees. (line 6)
5546 * trees, visibility: Visibility cycling. (line 6)
5547 * tty keybindings: TTY keys. (line 6)
5548 * types as TODO keywords: TODO types. (line 6)
5549 * underlined text: Enhancing text. (line 15)
5550 * URL links: External links. (line 6)
5551 * USENET links: External links. (line 6)
5552 * variables, for customization: Customization. (line 6)
5553 * vectors, in table calculations: Formula syntax. (line 23)
5554 * visibility cycling: Visibility cycling. (line 6)
5555 * visible text, printing: Sparse trees. (line 41)
5556 * VM links: External links. (line 6)
5557 * WANDERLUST links: External links. (line 6)
5558 * weekly agenda: Weekly/Daily agenda. (line 6)
5559 * windmove.el: Conflicts. (line 33)
5560 * workflow states as TODO keywords: Workflow states. (line 6)
5561 * XEmacs: Installation. (line 6)
5562 * XOXO export: XOXO export. (line 6)
5565 File: org, Node: Key Index, Prev: Index, Up: Top
5573 * ': CDLaTeX mode. (line 43)
5574 * +: Agenda commands. (line 132)
5575 * ,: Agenda commands. (line 124)
5576 * -: Agenda commands. (line 138)
5577 * .: Agenda commands. (line 94)
5578 * :: Agenda commands. (line 118)
5579 * <: The date/time prompt.
5581 * <left>: Agenda commands. (line 91)
5582 * <RET> <1>: Agenda commands. (line 41)
5583 * <RET> <2>: Setting tags. (line 76)
5584 * <RET> <3>: The date/time prompt.
5586 * <RET>: Built-in table editor.
5588 * <right>: Agenda commands. (line 86)
5589 * <SPC> <1>: Agenda commands. (line 28)
5590 * <SPC>: Setting tags. (line 73)
5591 * <TAB> <1>: CDLaTeX mode. (line 23)
5592 * <TAB> <2>: Agenda commands. (line 35)
5593 * <TAB> <3>: Setting tags. (line 68)
5594 * <TAB> <4>: Built-in table editor.
5596 * <TAB> <5>: Plain lists. (line 37)
5597 * <TAB>: Visibility cycling. (line 10)
5598 * > <1>: Agenda commands. (line 160)
5599 * >: The date/time prompt.
5601 * ^: CDLaTeX mode. (line 33)
5602 * _: CDLaTeX mode. (line 33)
5603 * `: CDLaTeX mode. (line 39)
5604 * a: Agenda commands. (line 121)
5605 * C: Agenda commands. (line 200)
5606 * c: Agenda commands. (line 178)
5607 * C-#: Built-in table editor.
5609 * C-,: Agenda files. (line 18)
5610 * C-a a L: Timeline. (line 10)
5611 * C-c !: Creating timestamps. (line 21)
5612 * C-c #: Checkboxes. (line 56)
5613 * C-c $: Moving subtrees. (line 10)
5614 * C-c %: Handling links. (line 81)
5615 * C-c &: Handling links. (line 85)
5616 * C-c ' <1>: Editing/debugging formulas.
5618 * C-c ': Built-in table editor.
5620 * C-c *: Built-in table editor.
5622 * C-c +: Built-in table editor.
5624 * C-c ,: Priorities. (line 18)
5625 * C-c -: Built-in table editor.
5627 * C-c .: Creating timestamps. (line 10)
5628 * C-c /: Sparse trees. (line 15)
5629 * C-c :: Enhancing text. (line 29)
5630 * C-c ;: Comment lines. (line 11)
5631 * C-c <: Creating timestamps. (line 25)
5632 * C-c <TAB>: Built-in table editor.
5634 * C-c =: Built-in table editor.
5636 * C-c >: Creating timestamps. (line 29)
5637 * C-c ? <1>: Editing/debugging formulas.
5639 * C-c ?: Built-in table editor.
5641 * C-c [: Agenda files. (line 12)
5642 * C-c \: Tag searches. (line 9)
5643 * C-c ]: Agenda files. (line 15)
5644 * C-c ^: Built-in table editor.
5646 * C-c `: Built-in table editor.
5648 * C-c a a: Weekly/Daily agenda. (line 9)
5649 * C-c a C: Storing searches. (line 9)
5650 * C-c a M: Matching headline tags.
5652 * C-c a m: Matching headline tags.
5654 * C-c a M: Tag searches. (line 14)
5655 * C-c a m: Tag searches. (line 10)
5656 * C-c a T: Global TODO list. (line 14)
5657 * C-c a t <1>: Global TODO list. (line 9)
5658 * C-c a t: TODO basics. (line 33)
5659 * C-c C-a: Visibility cycling. (line 31)
5660 * C-c C-b: Motion. (line 15)
5661 * C-c C-c <1>: The very busy C-c C-c key.
5663 * C-c C-c <2>: Processing LaTeX fragments.
5665 * C-c C-c <3>: Setting tags. (line 10)
5666 * C-c C-c <4>: Checkboxes. (line 37)
5667 * C-c C-c <5>: table.el. (line 6)
5668 * C-c C-c <6>: Editing/debugging formulas.
5670 * C-c C-c <7>: Built-in table editor.
5672 * C-c C-c: Plain lists. (line 74)
5673 * C-c C-d <1>: Agenda commands. (line 145)
5674 * C-c C-d: Creating timestamps. (line 37)
5675 * C-c C-e: Exporting. (line 19)
5676 * C-c C-e a: ASCII export. (line 9)
5677 * C-c C-e b: HTML export. (line 11)
5678 * C-c C-e c: iCalendar export. (line 20)
5679 * C-c C-e h: HTML export. (line 10)
5680 * C-c C-e I: iCalendar export. (line 15)
5681 * C-c C-e i: iCalendar export. (line 13)
5682 * C-c C-e t: Export options. (line 13)
5683 * C-c C-e v <1>: XOXO export. (line 11)
5684 * C-c C-e v: Sparse trees. (line 41)
5685 * C-c C-e v a: ASCII export. (line 13)
5686 * C-c C-e v b: HTML export. (line 14)
5687 * C-c C-e v h: HTML export. (line 14)
5688 * C-c C-e x: XOXO export. (line 10)
5689 * C-c C-f: Motion. (line 12)
5690 * C-c C-j: Motion. (line 21)
5691 * C-c C-l: Handling links. (line 27)
5692 * C-c C-n: Motion. (line 8)
5693 * C-c C-o <1>: Creating timestamps. (line 33)
5694 * C-c C-o: Handling links. (line 58)
5695 * C-c C-p: Motion. (line 9)
5696 * C-c C-q <1>: Editing/debugging formulas.
5698 * C-c C-q: Built-in table editor.
5700 * C-c C-r: Visibility cycling. (line 32)
5701 * C-c C-s <1>: Agenda commands. (line 142)
5702 * C-c C-s: Creating timestamps. (line 48)
5703 * C-c C-t <1>: Clocking work time. (line 26)
5704 * C-c C-t: TODO basics. (line 13)
5705 * C-c C-u: Motion. (line 18)
5706 * C-c C-v: TODO basics. (line 26)
5707 * C-c C-w: Creating timestamps. (line 41)
5708 * C-c C-x C-a: ARCHIVE tag. (line 28)
5709 * C-c C-x C-b: Checkboxes. (line 38)
5710 * C-c C-x C-c: Agenda commands. (line 207)
5711 * C-c C-x C-d: Clocking work time. (line 34)
5712 * C-c C-x C-i: Clocking work time. (line 12)
5713 * C-c C-x C-k: Structure editing. (line 39)
5714 * C-c C-x C-l: Processing LaTeX fragments.
5716 * C-c C-x C-o: Clocking work time. (line 14)
5717 * C-c C-x C-r: Clocking work time. (line 42)
5718 * C-c C-x C-t: Custom time format. (line 12)
5719 * C-c C-x C-u: Dynamic blocks. (line 21)
5720 * C-c C-x C-w <1>: Built-in table editor.
5722 * C-c C-x C-w: Structure editing. (line 39)
5723 * C-c C-x C-x: Clocking work time. (line 30)
5724 * C-c C-x C-y <1>: Built-in table editor.
5726 * C-c C-x C-y: Structure editing. (line 46)
5727 * C-c C-x M-w <1>: Built-in table editor.
5729 * C-c C-x M-w: Structure editing. (line 43)
5730 * C-c C-y <1>: Clocking work time. (line 21)
5731 * C-c C-y: Creating timestamps. (line 66)
5732 * C-c l: Handling links. (line 9)
5733 * C-c {: CDLaTeX mode. (line 21)
5734 * C-c |: Built-in table editor.
5736 * C-c ~: table.el. (line 18)
5737 * C-k: Agenda commands. (line 107)
5738 * C-TAB: ARCHIVE tag. (line 38)
5739 * C-u C-c $: Moving subtrees. (line 12)
5740 * C-u C-c .: Creating timestamps. (line 16)
5741 * C-u C-c =: Built-in table editor.
5743 * C-u C-c C-l: Handling links. (line 43)
5744 * C-u C-c C-x C-a: ARCHIVE tag. (line 31)
5745 * C-u C-c C-x C-u <1>: Dynamic blocks. (line 22)
5746 * C-u C-c C-x C-u: Clocking work time. (line 69)
5747 * D: Agenda commands. (line 68)
5748 * d: Agenda commands. (line 65)
5749 * f: Agenda commands. (line 44)
5750 * g: Agenda commands. (line 72)
5751 * H: Agenda commands. (line 204)
5752 * i: Agenda commands. (line 185)
5753 * I: Agenda commands. (line 165)
5754 * l: Agenda commands. (line 51)
5755 * L: Agenda commands. (line 32)
5756 * M: Agenda commands. (line 191)
5757 * M-<down>: Built-in table editor.
5759 * M-<left> <1>: Built-in table editor.
5761 * M-<left>: Structure editing. (line 21)
5762 * M-<RET> <1>: Plain lists. (line 42)
5763 * M-<RET>: Structure editing. (line 6)
5764 * M-<right> <1>: Built-in table editor.
5766 * M-<right>: Structure editing. (line 24)
5767 * M-<TAB> <1>: Completion. (line 10)
5768 * M-<TAB> <2>: Setting tags. (line 6)
5769 * M-<TAB>: Per file keywords. (line 17)
5770 * M-<up>: Built-in table editor.
5772 * M-S-<down> <1>: Built-in table editor.
5774 * M-S-<down> <2>: Plain lists. (line 59)
5775 * M-S-<down>: Structure editing. (line 36)
5776 * M-S-<left> <1>: The date/time prompt.
5778 * M-S-<left> <2>: Built-in table editor.
5780 * M-S-<left> <3>: Plain lists. (line 65)
5781 * M-S-<left>: Structure editing. (line 27)
5782 * M-S-<RET> <1>: Checkboxes. (line 53)
5783 * M-S-<RET> <2>: Plain lists. (line 52)
5784 * M-S-<RET>: Structure editing. (line 18)
5785 * M-S-<right> <1>: The date/time prompt.
5787 * M-S-<right> <2>: Built-in table editor.
5789 * M-S-<right> <3>: Plain lists. (line 65)
5790 * M-S-<right>: Structure editing. (line 30)
5791 * M-S-<up> <1>: Built-in table editor.
5793 * M-S-<up> <2>: Plain lists. (line 59)
5794 * M-S-<up>: Structure editing. (line 33)
5795 * mouse-1 <1>: Agenda commands. (line 35)
5796 * mouse-1 <2>: The date/time prompt.
5798 * mouse-1: Handling links. (line 72)
5799 * mouse-2 <1>: Agenda commands. (line 35)
5800 * mouse-2: Handling links. (line 72)
5801 * mouse-3 <1>: Agenda commands. (line 28)
5802 * mouse-3: Handling links. (line 77)
5803 * n: Agenda commands. (line 19)
5804 * O: Agenda commands. (line 167)
5805 * o: Agenda commands. (line 59)
5806 * P: Agenda commands. (line 129)
5807 * p: Agenda commands. (line 20)
5808 * q: Agenda commands. (line 214)
5809 * r <1>: Agenda commands. (line 76)
5810 * r: Global TODO list. (line 20)
5811 * S: Agenda commands. (line 195)
5812 * s: Agenda commands. (line 83)
5813 * S-<down> <1>: Agenda commands. (line 138)
5814 * S-<down> <2>: The date/time prompt.
5816 * S-<down> <3>: Creating timestamps. (line 58)
5817 * S-<down> <4>: Priorities. (line 25)
5818 * S-<down>: Plain lists. (line 55)
5819 * S-<left> <1>: Agenda commands. (line 156)
5820 * S-<left> <2>: The date/time prompt.
5822 * S-<left> <3>: Creating timestamps. (line 53)
5823 * S-<left>: TODO basics. (line 20)
5824 * S-<RET>: Built-in table editor.
5826 * S-<right> <1>: Agenda commands. (line 148)
5827 * S-<right> <2>: The date/time prompt.
5829 * S-<right> <3>: Creating timestamps. (line 53)
5830 * S-<right>: TODO basics. (line 20)
5831 * S-<TAB> <1>: Built-in table editor.
5833 * S-<TAB>: Visibility cycling. (line 22)
5834 * S-<up> <1>: Agenda commands. (line 132)
5835 * S-<up> <2>: The date/time prompt.
5837 * S-<up> <3>: Creating timestamps. (line 58)
5838 * S-<up> <4>: Priorities. (line 25)
5839 * S-<up>: Plain lists. (line 55)
5840 * T: Agenda commands. (line 113)
5841 * t: Agenda commands. (line 103)
5842 * w: Agenda commands. (line 62)
5843 * x: Agenda commands. (line 217)
5844 * X: Agenda commands. (line 170)
5850 Node: Introduction
\x7f10363
5851 Node: Summary
\x7f10778
5852 Node: Installation
\x7f13690
5853 Node: Activation
\x7f15068
5854 Node: Feedback
\x7f16317
5855 Node: Document structure
\x7f18393
5856 Node: Outlines
\x7f19167
5857 Node: Headlines
\x7f19827
5858 Node: Visibility cycling
\x7f20450
5859 Ref: Visibility cycling-Footnote-1
\x7f22201
5860 Ref: Visibility cycling-Footnote-2
\x7f22259
5861 Node: Motion
\x7f22309
5862 Node: Structure editing
\x7f23093
5863 Node: Archiving
\x7f25409
5864 Node: ARCHIVE tag
\x7f25967
5865 Node: Moving subtrees
\x7f27760
5866 Node: Sparse trees
\x7f28801
5867 Ref: Sparse trees-Footnote-1
\x7f30932
5868 Ref: Sparse trees-Footnote-2
\x7f31024
5869 Node: Plain lists
\x7f31139
5870 Ref: Plain lists-Footnote-1
\x7f34664
5871 Ref: Plain lists-Footnote-2
\x7f35021
5872 Node: Tables
\x7f35205
5873 Node: Built-in table editor
\x7f35753
5874 Node: Narrow columns
\x7f43361
5875 Ref: Narrow columns-Footnote-1
\x7f45300
5876 Node: Table calculations
\x7f45346
5877 Node: Formula syntax
\x7f46666
5878 Ref: Formula syntax-Footnote-1
\x7f49571
5879 Node: Lisp formulas
\x7f49871
5880 Node: Column formulas
\x7f50660
5881 Node: Advanced features
\x7f52422
5882 Node: Named-field formulas
\x7f55676
5883 Node: Editing/debugging formulas
\x7f56316
5884 Node: Appetizer
\x7f58074
5885 Node: orgtbl-mode
\x7f59177
5886 Node: table.el
\x7f59668
5887 Node: Hyperlinks
\x7f60645
5888 Node: Link format
\x7f61418
5889 Node: Internal links
\x7f62711
5890 Ref: Internal links-Footnote-1
\x7f64700
5891 Node: Radio targets
\x7f64832
5892 Node: CamelCase links
\x7f65547
5893 Node: External links
\x7f66141
5894 Node: Handling links
\x7f68272
5895 Ref: Handling links-Footnote-1
\x7f72924
5896 Ref: Handling links-Footnote-2
\x7f73161
5897 Node: Link abbreviations
\x7f73235
5898 Node: Search options
\x7f74914
5899 Ref: Search options-Footnote-1
\x7f76692
5900 Node: Custom searches
\x7f76773
5901 Node: Remember
\x7f77821
5902 Node: TODO items
\x7f81511
5903 Node: TODO basics
\x7f82493
5904 Node: TODO extensions
\x7f84020
5905 Node: Workflow states
\x7f84815
5906 Node: TODO types
\x7f85683
5907 Ref: TODO types-Footnote-1
\x7f87341
5908 Node: Per file keywords
\x7f87423
5909 Ref: Per file keywords-Footnote-1
\x7f88877
5910 Node: Priorities
\x7f89078
5911 Node: Breaking down tasks
\x7f90322
5912 Ref: Breaking down tasks-Footnote-1
\x7f90841
5913 Node: Checkboxes
\x7f90937
5914 Node: Timestamps
\x7f93692
5915 Node: Time stamps
\x7f94153
5916 Ref: Time stamps-Footnote-1
\x7f97642
5917 Node: Creating timestamps
\x7f97758
5918 Node: The date/time prompt
\x7f100384
5919 Ref: The date/time prompt-Footnote-1
\x7f102077
5920 Node: Custom time format
\x7f102183
5921 Node: Progress logging
\x7f103742
5922 Node: Closing items
\x7f104271
5923 Node: Clocking work time
\x7f105175
5924 Ref: Clocking work time-Footnote-1
\x7f108799
5925 Node: Tags
\x7f108925
5926 Node: Tag inheritance
\x7f109687
5927 Node: Setting tags
\x7f110624
5928 Ref: Setting tags-Footnote-1
\x7f114823
5929 Ref: Setting tags-Footnote-2
\x7f114935
5930 Node: Tag searches
\x7f115018
5931 Node: Agenda views
\x7f117018
5932 Node: Agenda files
\x7f119111
5933 Ref: Agenda files-Footnote-1
\x7f120071
5934 Ref: Agenda files-Footnote-2
\x7f120220
5935 Node: Agenda dispatcher
\x7f120413
5936 Node: Weekly/Daily agenda
\x7f122030
5937 Node: Calendar/Diary integration
\x7f122995
5938 Node: Global TODO list
\x7f124333
5939 Node: Matching headline tags
\x7f126493
5940 Node: Timeline
\x7f127551
5941 Node: Presentation and sorting
\x7f128214
5942 Node: Categories
\x7f128992
5943 Node: Time-of-day specifications
\x7f129656
5944 Node: Sorting of agenda items
\x7f131634
5945 Node: Agenda commands
\x7f132916
5946 Node: Custom agenda views
\x7f139085
5947 Node: Storing searches
\x7f139760
5948 Node: Block agenda
\x7f141672
5949 Node: Setting Options
\x7f142902
5950 Node: Batch processing
\x7f145614
5951 Node: Embedded LaTeX
\x7f146744
5952 Ref: Embedded LaTeX-Footnote-1
\x7f147836
5953 Node: Math symbols
\x7f148026
5954 Node: Subscripts and Superscripts
\x7f148791
5955 Node: LaTeX fragments
\x7f149635
5956 Ref: LaTeX fragments-Footnote-1
\x7f151743
5957 Node: Processing LaTeX fragments
\x7f152005
5958 Node: CDLaTeX mode
\x7f152951
5959 Ref: CDLaTeX mode-Footnote-1
\x7f155435
5960 Node: Exporting
\x7f155583
5961 Node: ASCII export
\x7f156897
5962 Node: HTML export
\x7f158187
5963 Node: XOXO export
\x7f161023
5964 Node: iCalendar export
\x7f161462
5965 Node: Text interpretation
\x7f163285
5966 Node: Comment lines
\x7f163764
5967 Node: Enhancing text
\x7f164235
5968 Node: Export options
\x7f165927
5969 Node: Publishing
\x7f167594
5970 Ref: Publishing-Footnote-1
\x7f168390
5971 Node: Configuration
\x7f168586
5972 Node: Project alist
\x7f169304
5973 Node: Sources and destinations
\x7f170370
5974 Node: Selecting files
\x7f171100
5975 Node: Publishing action
\x7f171848
5976 Node: Publishing options
\x7f173081
5977 Node: Publishing links
\x7f175233
5978 Node: Project page index
\x7f176746
5979 Node: Sample configuration
\x7f177524
5980 Node: Simple example
\x7f178016
5981 Node: Complex example
\x7f178689
5982 Node: Triggering publication
\x7f180765
5983 Node: Miscellaneous
\x7f181450
5984 Node: Completion
\x7f182084
5985 Node: Customization
\x7f183555
5986 Node: In-buffer settings
\x7f184140
5987 Node: The very busy C-c C-c key
\x7f187759
5988 Node: Clean view
\x7f189403
5989 Node: TTY keys
\x7f191980
5990 Node: Interaction
\x7f193589
5991 Node: Cooperation
\x7f193986
5992 Node: Conflicts
\x7f195853
5993 Node: Bugs
\x7f197445
5994 Node: Extensions and Hacking
\x7f199068
5995 Node: Extensions
\x7f199554
5996 Node: Dynamic blocks
\x7f201355
5997 Node: History and Acknowledgments
\x7f203282
5998 Node: Index
\x7f208289
5999 Node: Key Index
\x7f235377